0xray 4.1.0 → 4.1.1

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

@@ -0,0 +1,35 @@
+---
+title: Repertoire
+sidebar_label: Repertoire
+---
+
+# Repertoire
+
+The memory organ matches named laws.
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ INPUT LAYER                                                │
+│   ┌────────────────────────────────────────────────────┐   │
+│   │ a task and its signals                             │   │
+│   └──────────────────────────┬─────────────────────────┘   │
+└──────────────────────────────┼─────────────────────────────┘
+             v
+┌────────────┼───────────────────────────────────────────────┐
+│ PROCESSING LAYER                                            │
+│   ┌────────────────────────────────────────────────────┐   │
+│   │ match the worn laws                                │   │
+│   └──────────────────────────┬─────────────────────────┘   │
+└──────────────────────────────┼─────────────────────────────┘
+                               v
+┌──────────────────────────────┼─────────────────────────────┐
+│ OUTPUT LAYER                 v                             │
+│   ┌────────────────────────────────────────────────────┐   │
+│   │ one law, or none                                   │   │
+│   └────────────────────────────────────────────────────┘   │
+└────────────────────────────────────────────────────────────┘
+```
+
+The code is `src/memory-routing`. The worn package is `@0xray/repertoire` 0.2.9. Station is the wake ticket. This organ is the judgment. Do not pin 0.1.8.
+
+stamped · 0xray 4.1.0

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

@@ -0,0 +1,35 @@
+---
+title: Synthesis
+sidebar_label: Synthesis
+---
+
+# Synthesis
+
+The reflect checkpoint for this checkout.
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ INPUT LAYER                                                │
+│   ┌────────────────────────────────────────────────────┐   │
+│   │ a gate, a turn, or a finished todo                 │   │
+│   └──────────────────────────┬─────────────────────────┘   │
+└──────────────────────────────┼─────────────────────────────┘
+             v
+┌────────────┼───────────────────────────────────────────────┐
+│ PROCESSING LAYER                                            │
+│   ┌────────────────────────────────────────────────────┐   │
+│   │ the checkpoint when enabled                        │   │
+│   └──────────────────────────┬─────────────────────────┘   │
+└──────────────────────────────┼─────────────────────────────┘
+                               v
+┌──────────────────────────────┼─────────────────────────────┐
+│ OUTPUT LAYER                 v                             │
+│   ┌────────────────────────────────────────────────────┐   │
+│   │ due or not due                                     │   │
+│   └────────────────────────────────────────────────────┘   │
+└────────────────────────────────────────────────────────────┘
+```
+
+The file is `src/nucleus/synthesis.ts`. The checkpoint is `.xray/state/synthesis-checkpoint.json`. While `synthesis.enabled` is false, a slice is not written and it does not come due.
+
+stamped · 0xray 4.1.0

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

@@ -0,0 +1,35 @@
+---
+title: Temperament
+sidebar_label: Temperament
+---
+
+# Temperament
+
+Ceremony scales by host.
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ INPUT LAYER                                                │
+│   ┌────────────────────────────────────────────────────┐   │
+│   │ a host                                             │   │
+│   └──────────────────────────┬─────────────────────────┘   │
+└──────────────────────────────┼─────────────────────────────┘
+             v
+┌────────────┼───────────────────────────────────────────────┐
+│ PROCESSING LAYER                                            │
+│   ┌────────────────────────────────────────────────────┐   │
+│   │ read suit_temperament                              │   │
+│   └──────────────────────────┬─────────────────────────┘   │
+└──────────────────────────────┼─────────────────────────────┘
+                               v
+┌──────────────────────────────┼─────────────────────────────┐
+│ OUTPUT LAYER                 v                             │
+│   ┌────────────────────────────────────────────────────┐   │
+│   │ frontier warns, guided denies                      │   │
+│   └────────────────────────────────────────────────────┘   │
+└────────────────────────────────────────────────────────────┘
+```
+
+The module is `src/nucleus/suit-temperament.ts`. A missing `suit_temperament` stays guided. Frontier warns when a spawn has no plan. Guided and strict deny that spawn. Codex stays on. The guide is `docs-site/docs/guides/v3-temperament.md`.
+
+stamped · 0xray 4.1.0

package/docs-site/docs/plates/trail-state.md

@@ -30,6 +30,6 @@ The suit writes its trail under .xray.
 └────────────────────────────────────────────────────────────┘
 ```
 
-Session boot, the lens match line, and the station card are state. The agent reads them. Do not commit `.xray/state`.
+Session boot and the station card are state. `.xray/state/LENS.md` is the plane cards. A named plane whose Entry and Exit are missing is written there, and later passes read that card. Commit `.xray/state/LENS.md`. Do not commit the rest of `.xray/state`.
 
 stamped · 0xray 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "Three-subsystem autonomous engine. The suit powers the agent you already run: memory, judgement, payments, and the wake.",
   "readme": "README.md",
   "license": "MIT",

package/scripts/foundry/README.md

@@ -37,6 +37,8 @@ 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.
 
+On the 0xray repo, `reconcile --apply` and `stamp` refuse unless `release.mjs` called them. `npm run version:sync` refuses here too. Run `npx @0xray/foundry release [patch|minor|major] --i-mean-it`. That command publishes. A docs fix does not.
+
 `FOUNDRY_ROOT` overrides cwd (the repo being milled).
 
 `gate` is build + test + docs-check. `--skip-docs` fails the gate. `--prove-published` is Gate D and does not publish: npm lists the version, the annotated tag points at HEAD, and the GitHub Release page exists. A local gate pass is not Gate D. `docs-build` runs Docusaurus on the 0xray exo (`docs-site/`); stranger mills skip. `inspect` runs the six mill checks (diff, plant vs worn, receipt, CI, live tarball GET, isolated HOME) plus observational harness (Cursor/Grok hooks bound, Repertoire fastened, Station present). `--go` emits a shop-style forge GO receipt; `--require-harness=bare|suited|partial` turns that observation into a gate. Mint fails on a costume dump. Isolated HOME skips machine `~/.grok`. Shared HOME last-mile dest is project `.grok/plugins/0xray` (no last-wins machine plugin). `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.
@@ -60,7 +62,7 @@ After mill plant is fastened, overlay their plant (defaults; remap in `foundry.j
 
 **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 dirs on every TUI floor (OpenCode, Grok, Hermes, OpenClaw). YML agents stay OpenCode. CLI re-wear calls mint **once** after mill copies. Isolated HOME is passwd home, not `os.homedir()`. CI report is `.xray/foundry-ci-report.json` (`.opencode/logs` shim).
 
-**Default mill plant:** `mill` + `inspect` (inspect AI work). Fasten is **foundry-plant/0**: builtin plant is mill+inspect only (files from this package `plant/`). Fastens a suit, not an empty one. Not 45/42 costume. `foundry.json` `"costume": true` copies that dump. **Repertoire is preferred** (vendored, dest = laws). PPE stays worn.
+**Default mill plant:** `mill` + `inspect` (inspect AI work). Fasten is **foundry-plant/0**: builtin plant is mill+inspect only (files from this package `plant/`). Fastens a suit, not an empty one. The mill suit also wears every catalog skill and every role file. A blip or sound seat fastens that plant only. A name outside the fastened set still fails inspect. **Repertoire is preferred** (vendored, dest = laws). PPE stays worn.
 
 **foundry-plant/0:** `foundry.json` `"plant": "@0xray/blip"` (aliases `"plant": "blip"` / `"plant": "sound"`) fastens whatever that mill package declares and ships in its own `plant/`. Organs (looker, vibe, mixer) live in the mill. Adding an organ is a mill publish, not a foundry catalog PR. CLI shims `foundry blip|sound` still exist on foundry 0.1.11+; fasten is the new cut. Foundry **0.1.12**.
 

package/scripts/foundry/mint-suit.cjs

@@ -114,12 +114,91 @@ function loadFoundryParams(targetDir) {
   return params;
 }
 
-/** 45/42 costume dump. Default false on consumers. Exo mill keeps the costume. */
+/** Exo repo, or foundry.json costume true. This flag does not gate catalog skills. */
 function wantsCostume(targetDir) {
   if (isExoRepo(targetDir)) return true;
   return loadFoundryExtra(targetDir).costume === true;
 }
 
+function suitPackageRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 4 && dir; i += 1) {
+    if (
+      fs.existsSync(path.join(dir, "src", "skills"))
+      || fs.existsSync(path.join(dir, "dist", "skills"))
+      || fs.existsSync(path.join(dir, "src", "opencode", "agents"))
+    ) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return start || "";
+}
+
+function catalogSkillDir(packageRoot) {
+  const base = suitPackageRoot(packageRoot);
+  const dirs = [path.join(base, "dist", "skills"), path.join(base, "src", "skills")];
+  return dirs.find((dir) => listSkillNamesAt(dir).length > 0) || "";
+}
+
+function catalogSkillNames(packageRoot) {
+  const dir = catalogSkillDir(packageRoot);
+  return dir ? listSkillNamesAt(dir) : [];
+}
+
+function catalogAgentDirs(packageRoot) {
+  const base = suitPackageRoot(packageRoot);
+  return [
+    path.join(base, "src", "opencode", "agents"),
+    path.join(base, ".opencode", "agents"),
+  ].filter((p) => fs.existsSync(p));
+}
+
+function catalogAgentFiles(packageRoot) {
+  const names = new Set();
+  for (const dir of catalogAgentDirs(packageRoot)) {
+    for (const file of listAgentFilesAt(dir)) names.add(file);
+  }
+  return [...names];
+}
+
+/**
+ * The mill suit wears the catalog. A blip-only or sound-only seat does not.
+ * Costume stays a separate flag and does not decide this.
+ */
+function suitCatalogApplies(targetDir, millPlant, packageRoot) {
+  const fromPlant = Array.isArray(millPlant?.kinds) ? millPlant.kinds : [];
+  const kinds = fromPlant.length > 0
+    ? fromPlant
+    : loadFactoryPlantKinds(targetDir, packageRoot || "");
+  return kinds.includes("mill");
+}
+
+/** Every catalog skill and role file. An existing file stays. */
+function wearCatalog(packageRoot, targetDir) {
+  const source = catalogSkillDir(packageRoot);
+  if (source) {
+    for (const dir of listProjectSkillDirs(targetDir)) {
+      for (const name of catalogSkillNames(packageRoot)) {
+        const src = path.join(source, name, "SKILL.md");
+        const dest = path.join(dir, name, "SKILL.md");
+        if (!fs.existsSync(src) || fs.existsSync(dest)) continue;
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+      }
+    }
+  }
+  const agentsDest = path.join(targetDir, ".opencode", "agents");
+  for (const dir of catalogAgentDirs(packageRoot)) {
+    for (const file of listAgentFilesAt(dir)) {
+      const dest = path.join(agentsDest, file);
+      if (fs.existsSync(dest)) continue;
+      fs.mkdirSync(agentsDest, { recursive: true });
+      fs.copyFileSync(path.join(dir, file), dest);
+    }
+  }
+}
+
 function millPlantDir(millPackageRoot) {
   return millPlantProtocol.foundryPlantDir(millPackageRoot);
 }
@@ -208,11 +287,21 @@ function inventoryPlantKinds(inventory) {
   return millPlantProtocol.plantKindsFromInventory(inventory);
 }
 
+function skillDirEntry(parent, entry) {
+  if (entry.isDirectory()) return true;
+  if (!entry.isSymbolicLink()) return false;
+  try {
+    return fs.statSync(path.join(parent, entry.name)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 function listSkillNamesAt(skillsSrc) {
   if (!isDirectory(skillsSrc)) return [];
   const names = [];
   for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
-    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    if (entry.name.startsWith(".") || !skillDirEntry(skillsSrc, entry)) continue;
     const skillMd = path.join(skillsSrc, entry.name, "SKILL.md");
     if (!fs.existsSync(skillMd)) continue;
     names.push(entry.name);
@@ -615,7 +704,10 @@ function costumeDumpExtras(targetDir, millPlant, tree) {
       if (Array.isArray(spec?.agents)) plantMapAgents.push(...spec.agents);
     }
   }
+  const packageRoot = tree?.millPackageRoot || "";
+  const catalogOn = suitCatalogApplies(targetDir, millPlant, packageRoot);
   const allowedSkills = new Set([
+    ...(catalogOn ? catalogSkillNames(packageRoot) : []),
     ...(Array.isArray(millPlant?.skills) ? millPlant.skills : []),
     ...(Array.isArray(millPlant?.sound?.skills) ? millPlant.sound.skills : []),
     ...(Array.isArray(millPlant?.blip?.skills) ? millPlant.blip.skills : []),
@@ -627,6 +719,7 @@ function costumeDumpExtras(targetDir, millPlant, tree) {
     ...shopPlant,
   ]);
   const allowedAgents = new Set([
+    ...(catalogOn ? catalogAgentFiles(packageRoot) : []),
     ...(Array.isArray(millPlant?.agents) ? millPlant.agents : []),
     ...(Array.isArray(millPlant?.sound?.agents) ? millPlant.sound.agents : []),
     ...(Array.isArray(millPlant?.blip?.agents) ? millPlant.blip.agents : []),
@@ -795,12 +888,34 @@ function mintConsumerFromSsot(packageRoot, targetDir, log, tree) {
   return withDna;
 }
 
+
+function gogglesDisabled(targetDir) {
+  const file = path.join(targetDir, ".xray", "features.json");
+  if (!fs.existsSync(file)) return false;
+  try {
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    return Boolean(data && data.goggles && data.goggles.enabled === false);
+  } catch {
+    return false;
+  }
+}
+
+function assertGogglesOn(targetDir) {
+  if (gogglesDisabled(targetDir)) {
+    throw new Error("goggles off — the suit keeps goggles on");
+  }
+}
+
 function mintConsumerSuit(millPackageRoot, targetDir, log) {
+  assertGogglesOn(targetDir);
   if (isDogfood(millPackageRoot, targetDir)) {
     return { suit: "dogfood", skipped: true };
   }
   const params = loadFoundryParams(targetDir);
   const millPlant = fastenMillPlant(millPackageRoot, targetDir, log);
+  if (suitCatalogApplies(targetDir, millPlant, millPackageRoot)) {
+    wearCatalog(millPackageRoot, targetDir);
+  }
   const tree = overlayConsumerTree(targetDir, log, params);
   tree.plantKinds = millPlant.kinds || loadFactoryPlantKinds(targetDir);
   tree.millPlantSkills = millPlant.skills;
@@ -825,6 +940,7 @@ function mintConsumerSuit(millPackageRoot, targetDir, log) {
     resolveInside(targetDir, params.features),
     path.join(targetDir, ".xray", "features.json"),
   );
+  assertGogglesOn(targetDir);
   tree.config = overlayJsonFacet(
     resolveInside(targetDir, params.config),
     path.join(targetDir, ".xray", "config.json"),
@@ -866,6 +982,7 @@ module.exports = {
   loadShopPlant,
   declaredShopPlant,
   wantsCostume,
+  suitCatalogApplies,
   millPlantDir,
   loadFactoryPlantKinds,
   factoryPlantAllowlist,
@@ -884,6 +1001,7 @@ module.exports = {
   listProjectSkillDirs,
   mintConsumerFromSsot,
   mintConsumerSuit,
+  assertGogglesOn,
   attachInventoryDna,
   inventoryDna,
   isDogfood,

package/scripts/foundry/plant/skills/mill/SKILL.md

@@ -13,7 +13,7 @@ The mill **fastens** a suit. Default mill plant is **inspect** (inspecting AI wo
 
 **Factory:** **Repertoire is preferred** (vendored 0.2.9 ships on; dest = named laws). Seven generated MCP. Constitution (PPE) stays worn. Not a fifth MCP. Not 5.0.
 
-**Costume:** `foundry.json` `"costume": true` copies the 45/42 mill costume.
+**Skills:** the mill suit wears every catalog skill and every role file. The mill plant stays `mill` and `inspect`. A blip or sound seat fastens that plant only.
 
 ```bash
 npx @0xray/foundry mint

package/scripts/foundry/reconcile-version.mjs

@@ -20,7 +20,7 @@ import { execSync } from "child_process";
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
-import { readRootPackage, resolveMillRoot } from "./mill-root.mjs";
+import { isXrayExoRepo, readRootPackage, resolveMillRoot } from "./mill-root.mjs";
 import { packageLockVersions, syncPackageLockVersion } from "./version-manager.mjs";
 
 const rootDir = resolveMillRoot();
@@ -103,7 +103,7 @@ function fail(msg) {
  */
 export function publishedVersionCheckError(local, npmVersion) {
   if (compare(local, npmVersion) < 0) {
-    return `package.json (${local}) must be >= npm (${npmVersion}). Run: npx @0xray/foundry reconcile patch --apply`;
+    return `package.json (${local}) must be >= npm (${npmVersion}). The bump is npx @0xray/foundry release patch --i-mean-it. That command publishes. A docs fix does not. Stop.`;
   }
   return null;
 }
@@ -134,6 +134,13 @@ function main() {
   }
 
   if (applyMode && bumpType) {
+    if (isXrayExoRepo(rootDir) && process.env.FOUNDRY_VIA_RELEASE !== "1") {
+      fail(
+        "This repo bumps only through scripts/foundry/release.mjs.\n" +
+          "Ship: node scripts/foundry/release.mjs patch --i-mean-it\n" +
+          "That command publishes. A docs fix does not. Stop.",
+      );
+    }
     const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
     pkg.version = target;
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
@@ -167,7 +174,7 @@ function main() {
   const lockNow = packageLockVersions(rootDir);
   if (lockNow && (lockNow.root !== pkgVersion || lockNow.pkg !== pkgVersion)) {
     fail(
-      `package-lock.json (${lockNow.root} / ${lockNow.pkg}) must match package.json (${pkgVersion}). The bumper writes both: npx @0xray/foundry reconcile patch --apply`,
+      `package-lock.json (${lockNow.root} / ${lockNow.pkg}) must match package.json (${pkgVersion}). The bumper is npx @0xray/foundry release patch --i-mean-it. That command publishes. A docs fix does not. Stop.`,
     );
   }
 

package/scripts/foundry/release.mjs

@@ -57,7 +57,7 @@ function run(cmd, label) {
     cwd: rootDir,
     stdio: "inherit",
     encoding: "utf-8",
-    env: { ...process.env, FOUNDRY_ROOT: rootDir },
+    env: { ...process.env, FOUNDRY_ROOT: rootDir, FOUNDRY_VIA_RELEASE: "1" },
   });
 }
 

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

@@ -410,8 +410,8 @@ function main() {
     } else {
       console.error('❌ Release docs validation FAILED:\n');
       for (const e of result.errors) console.error(`   • ${e}`);
-      console.error('\nFix docs then run: npm run version:sync');
-      console.error('Or: npx @0xray/foundry docs-check\n');
+      console.error('\nFix the docs in the branch. On this repo the stamper runs only from scripts/foundry/release.mjs, and that command publishes. A docs fix does not publish. Stop.');
+      console.error('Re-check with: npx @0xray/foundry docs-check\n');
     }
     process.exit(1);
   }

package/scripts/foundry/version-manager.mjs

@@ -574,9 +574,16 @@ function runReleaseDocsValidation() {
 
 function refuseBump(reason) {
   process.stderr.write(`${reason}\n`);
-  process.stderr.write('One bumper: npx @0xray/foundry reconcile [patch|minor|major] --apply\n');
-  process.stderr.write('Then stamp:  npx @0xray/foundry stamp\n');
-  process.stderr.write('Ship:        npx @0xray/foundry release [patch|minor|major]\n');
+  process.stderr.write('Ship: npx @0xray/foundry release [patch|minor|major] --i-mean-it\n');
+  process.exit(1);
+}
+
+function refuseOutsideRelease() {
+  if (!isXrayExoRepo(rootDir)) return;
+  if (process.env.FOUNDRY_VIA_RELEASE === '1') return;
+  process.stderr.write('This repo stamps only through scripts/foundry/release.mjs.\n');
+  process.stderr.write('Ship: node scripts/foundry/release.mjs patch --i-mean-it\n');
+  process.stderr.write('That command publishes. A docs fix does not. Stop.\n');
   process.exit(1);
 }
 
@@ -586,13 +593,14 @@ function main() {
   if (args.includes('--help') || args.includes('-h')) {
     process.stdout.write(`Current version: ${getCurrentVersion()}\n`);
     process.stdout.write('Usage: npx @0xray/foundry stamp\n');
-    process.stdout.write('Bump is refused. Reconcile advances the next cut, then this stamper runs.\n');
+    process.stdout.write('Bump is refused. On this repo the stamper runs only from scripts/foundry/release.mjs.\n');
     process.stdout.write('The stamper strips every present-tense patch pin from shipped guides and shipped OP-PROC.\n');
     process.stdout.write('It does not edit Station, NOTES, dest, or node_modules. It does not publish.\n');
     process.exit(0);
   }
 
   if (args.includes('--artifacts-only')) {
+    refuseOutsideRelease();
     updateReleaseArtifactsOnly('');
     return;
   }

package/scripts/node/install-bridges.cjs

@@ -216,7 +216,15 @@ function syncBuiltinSkills(targetSkillsDir, packageRoot) {
   try {
     if (!fs.existsSync(targetSkillsDir)) fs.mkdirSync(targetSkillsDir, { recursive: true });
     for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
+      let linkedDir = false;
+      if (entry.isSymbolicLink()) {
+        try {
+          linkedDir = fs.statSync(path.join(sourceDir, entry.name)).isDirectory();
+        } catch {
+          linkedDir = false;
+        }
+      }
+      if (!entry.isDirectory() && !linkedDir) continue;
       const skillMd = path.join(sourceDir, entry.name, "SKILL.md");
       if (!fs.existsSync(skillMd)) continue;
       const destMd = path.join(targetSkillsDir, entry.name, "SKILL.md");
@@ -234,8 +242,45 @@ function syncBuiltinSkills(targetSkillsDir, packageRoot) {
   return copied;
 }
 
+function plantIncludesMill(targetDir, packageRoot) {
+  const { loadFactoryPlantKinds } = require("../foundry/mint-suit.cjs");
+  return loadFactoryPlantKinds(targetDir, packageRoot).includes("mill");
+}
+
+function copyRoleAgentFiles(packageRoot, opencodeDest) {
+  const dirs = [
+    path.join(packageRoot, "src", "opencode", "agents"),
+    path.join(packageRoot, ".opencode", "agents"),
+  ].filter((dir) => fs.existsSync(dir));
+  const destDir = path.join(opencodeDest, "agents");
+  for (const dir of dirs) {
+    let names;
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (!name.endsWith(".yml") && !name.endsWith(".yaml")) continue;
+      const src = path.join(dir, name);
+      let st;
+      try {
+        st = fs.statSync(src);
+      } catch {
+        continue;
+      }
+      if (!st.isFile()) continue;
+      const dest = path.join(destDir, name);
+      if (fs.existsSync(dest)) continue;
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.copyFileSync(src, dest);
+    }
+  }
+}
+
 function syncCostumeSkills(targetSkillsDir, packageRoot, targetDir) {
-  if (targetDir && !wantsCostume(targetDir)) return 0;
+  // Catalog skills belong on the mill suit. A blip or sound seat keeps its plant.
+  if (targetDir && !plantIncludesMill(targetDir, packageRoot)) return 0;
   return syncBuiltinSkills(targetSkillsDir, packageRoot);
 }
 
@@ -448,7 +493,7 @@ function installOpencodeBridge(targetDir, packageRoot, log) {
   const opencodeSource = path.join(packageRoot, ".opencode");
   const opencodeDest = path.join(targetDir, ".opencode");
   const costume = wantsCostume(targetDir);
-
+  const millSuit = plantIncludesMill(targetDir, packageRoot);
   if (costume) {
     if (!fs.existsSync(opencodeSource)) {
       log("opencode-bridge", "skipped", "warn", { reason: ".opencode source missing" });
@@ -460,14 +505,18 @@ function installOpencodeBridge(targetDir, packageRoot, log) {
     } else {
       log("opencode-bridge", ".opencode exists — merging skills/plugin only", "info");
     }
-    copyOpencodePlugin(packageRoot, opencodeDest, log);
-    const copied = syncCostumeSkills(path.join(opencodeDest, "skills"), packageRoot, targetDir);
-    if (copied > 0) log("opencode-bridge", `skills synced (${copied})`, "info", { path: ".opencode/skills/" });
   } else {
-    log("opencode-bridge", "mill plant — plugin only, not costume dump", "info");
     fs.mkdirSync(opencodeDest, { recursive: true });
-    copyOpencodePlugin(packageRoot, opencodeDest, log);
+    if (millSuit) {
+      copyRoleAgentFiles(packageRoot, opencodeDest);
+      log("opencode-bridge", "mill suit — role files, not the costume tree", "info");
+    } else {
+      log("opencode-bridge", "plant seat — plugin only", "info");
+    }
   }
+  copyOpencodePlugin(packageRoot, opencodeDest, log);
+  const copied = syncCostumeSkills(path.join(opencodeDest, "skills"), packageRoot, targetDir);
+  if (copied > 0) log("opencode-bridge", `skills synced (${copied})`, "info", { path: ".opencode/skills/" });
 
   try {
     const count = wireOpencodeBridge(targetDir);
@@ -1947,9 +1996,11 @@ function syncSetupSkillsAndRootLinks(packageRoot, targetDir) {
 
 /** A byte-identical package skill is the old mirror. A different body still throws. */
 function wornSkillMatchesPackage(packageRoot, targetDir, name) {
-  const source = fs.existsSync(path.join(packageRoot, "src", "skills"))
-    ? path.join(packageRoot, "src", "skills")
-    : path.join(packageRoot, "dist", "skills");
+  const distSkills = path.join(packageRoot, "dist", "skills");
+  const srcSkills = path.join(packageRoot, "src", "skills");
+  const source = fs.existsSync(path.join(distSkills, name, "SKILL.md"))
+    ? distSkills
+    : srcSkills;
   const packaged = path.join(source, name, "SKILL.md");
   if (!fs.existsSync(packaged)) return false;
   const packagedBytes = fs.readFileSync(packaged);
@@ -1977,12 +2028,11 @@ function packageShipsConsumerSuit(packageRoot) {
 /**
  * Consumer wear files: AGENTS.md, .gitignore, repertoire link, .xray config,
  * bridges, mill plant (mill + inspect), and the scripts and dist links.
- * The role-skill mirror stays in the package.
+ * Catalog skills and role files stay worn. Costume does not strip them.
  * Does not install Cursor hooks or git hooks.
  * Existing user files follow the 4.0.28 guards inside those functions.
  */
 
-const ROLE_SKILL_KEEP = new Set(["mill", "inspect"]);
 const ROLE_SKILL_DIRS = [
   [".opencode", "skills"],
   [".grok", "plugins", "0xray", "skills"],
@@ -1990,26 +2040,6 @@ const ROLE_SKILL_DIRS = [
   [".openclaw", "skills"],
 ];
 
-function removeCopiedRoleSkills(packageRoot, targetDir) {
-  const source = fs.existsSync(path.join(packageRoot, "src", "skills"))
-    ? path.join(packageRoot, "src", "skills")
-    : path.join(packageRoot, "dist", "skills");
-  if (!fs.existsSync(source)) return;
-  for (const parts of ROLE_SKILL_DIRS) {
-    const dir = path.join(targetDir, ...parts);
-    if (!fs.existsSync(dir)) continue;
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      if (!entry.isDirectory() || ROLE_SKILL_KEEP.has(entry.name)) continue;
-      const packaged = path.join(source, entry.name, "SKILL.md");
-      const worn = path.join(dir, entry.name, "SKILL.md");
-      if (!fs.existsSync(packaged) || !fs.existsSync(worn)) continue;
-      const same = fs.readFileSync(packaged).equals(fs.readFileSync(worn));
-      if (!same) continue;
-      fs.rmSync(path.join(dir, entry.name), { recursive: true, force: true });
-    }
-  }
-}
-
 function installConsumerProjectFiles(packageRoot, targetDir, log) {
   const write = typeof log === "function" ? log : () => {};
   if (!isConsumerInstall(packageRoot, targetDir) || !packageShipsConsumerSuit(packageRoot)) {
@@ -2028,7 +2058,6 @@ function installConsumerProjectFiles(packageRoot, targetDir, log) {
   installGrokBridge(targetDir, packageRoot, write);
   installHermesBridge(targetDir, packageRoot, write);
   installOpenclawBridge(targetDir, packageRoot, write);
-  removeCopiedRoleSkills(packageRoot, targetDir);
   try {
     mintConsumerSuit(packageRoot, targetDir, write);
   } catch (err) {