@orchid-labs/pluxx 0.1.4 → 0.1.6

package/dist/cli/index.js

@@ -84,6 +84,9 @@ var require_src = __commonJS({
   }
 });
 
+// src/cli/index.ts
+import { readFileSync as readFileSync16 } from "fs";
+
 // src/config/load.ts
 import { resolve, extname, dirname } from "path";
 import { existsSync } from "fs";
@@ -4176,27 +4179,67 @@ function mergeAction(current, next) {
   return ACTION_PRIORITY[next] > ACTION_PRIORITY[current] ? next : current;
 }
 function permissionRulesNeedToolLevelDowngrade(permissions) {
-  return collectPermissionRules(permissions).some((rule) => rule.pattern !== "*");
+  return collectPermissionRules(permissions).some((rule) => rule.kind === "MCP");
 }
 function buildOpenCodePermissionMap(permissions) {
   const rules = collectPermissionRules(permissions);
   const output = {};
-  const toolAliases = {
-    Bash: ["bash", "shell"],
-    Edit: ["edit", "write"],
-    Read: ["read"],
-    MCP: ["mcp"],
-    // OpenCode's native permission surface is tool-level and does not expose
-    // a dedicated skill permission key.
-    Skill: []
-  };
   for (const rule of rules) {
-    for (const tool of toolAliases[rule.kind]) {
-      output[tool] = mergeAction(output[tool], rule.action);
+    if (rule.kind === "MCP") {
+      const toolName = translateCanonicalMcpPermission(rule.pattern);
+      if (!toolName) continue;
+      output[toolName] = mergeScalarPermission(output[toolName], rule.action);
+      continue;
     }
+    const tool = toOpenCodePermissionTool(rule.kind);
+    if (!tool) continue;
+    output[tool] = mergePatternPermission(output[tool], rule.pattern, rule.action);
   }
   return output;
 }
+function toOpenCodePermissionTool(kind) {
+  switch (kind) {
+    case "Bash":
+      return "bash";
+    case "Edit":
+      return "edit";
+    case "Read":
+      return "read";
+    case "Skill":
+      return "skill";
+    case "MCP":
+      return null;
+  }
+}
+function mergeScalarPermission(current, next) {
+  if (!current) return next;
+  if (typeof current === "string") {
+    return mergeAction(current, next);
+  }
+  const merged = { ...current };
+  merged["*"] = mergeAction(merged["*"], next);
+  return merged;
+}
+function mergePatternPermission(current, pattern, next) {
+  if (pattern === "*") {
+    return mergeScalarPermission(current, next);
+  }
+  const merged = typeof current === "string" ? { "*": current } : { ...current ?? {} };
+  merged[pattern] = mergeAction(merged[pattern], next);
+  return merged;
+}
+function translateCanonicalMcpPermission(pattern) {
+  const trimmed = pattern.trim();
+  if (!trimmed || trimmed === "*") return null;
+  const dot = trimmed.indexOf(".");
+  if (dot === -1) {
+    return `${trimmed}_*`;
+  }
+  const server = trimmed.slice(0, dot).trim();
+  const tool = trimmed.slice(dot + 1).trim();
+  if (!server || !tool) return null;
+  return `${server}_${tool.replace(/\./g, "_")}`;
+}
 function buildGeneratedPermissionHookScript(permissions) {
   const rules = collectPermissionRules(permissions);
   if (rules.length === 0) return null;
@@ -4334,6 +4377,7 @@ function claudeResponse(match) {
   if (!match) return {};
   return {
     hookSpecificOutput: {
+      hookEventName: "PreToolUse",
       permissionDecision: match.action,
       permissionDecisionReason: "Pluxx permissions matched " + match.rule.raw,
     },
@@ -4726,7 +4770,7 @@ async function loadConfig(dir = process.cwd()) {
 }
 
 // src/generators/index.ts
-import { rmSync, mkdirSync as mkdirSync2 } from "fs";
+import { rmSync, mkdirSync as mkdirSync3 } from "fs";
 import { resolve as resolve8, relative as relative5 } from "path";
 
 // src/generators/base.ts
@@ -4866,9 +4910,9 @@ var Generator = class {
     for (const configPath of this.config.passthrough ?? []) {
       const src = this.resolveConfigPath(configPath, "passthrough");
       if (!existsSync4(src)) continue;
-      const basename8 = src.split("/").filter(Boolean).pop();
-      if (!basename8) continue;
-      this.copyDir(configPath, `${basename8}/`, "passthrough");
+      const basename9 = src.split("/").filter(Boolean).pop();
+      if (!basename9) continue;
+      this.copyDir(configPath, `${basename9}/`, "passthrough");
     }
   }
   /** Build canonical MCP server configs for target-specific output shaping. */
@@ -4945,8 +4989,8 @@ var Generator = class {
 };
 
 // src/generators/shared/claude-family.ts
-import { existsSync as existsSync5 } from "fs";
-import { resolve as resolve4 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { resolve as resolve5 } from "path";
 
 // src/generators/hooks-warning.ts
 var MATCHER_PASSTHROUGH_PLATFORMS = /* @__PURE__ */ new Set([
@@ -5019,6 +5063,118 @@ function mapHookEventToPascalCase(event) {
   return PASCAL_CASE_HOOK_ALIASES[event] ?? event.charAt(0).toUpperCase() + event.slice(1);
 }
 
+// src/agents.ts
+import { existsSync as existsSync5, readdirSync, readFileSync as readFileSync2, statSync } from "fs";
+import { basename, resolve as resolve4 } from "path";
+function firstHeading(content) {
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const match = line.match(/^#\s+(.*)$/);
+    if (match?.[1]?.trim()) return match[1].trim();
+  }
+  return void 0;
+}
+function splitMarkdownFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") {
+    return {
+      frontmatterLines: [],
+      body: content
+    };
+  }
+  let endIndex = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === "---") {
+      endIndex = i;
+      break;
+    }
+  }
+  if (endIndex === -1) {
+    return {
+      frontmatterLines: [],
+      body: content
+    };
+  }
+  return {
+    frontmatterLines: lines.slice(1, endIndex),
+    body: lines.slice(endIndex + 1).join("\n")
+  };
+}
+function parseScalarValue(raw) {
+  const trimmed = raw.trim();
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+  if (trimmed.length >= 2) {
+    if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+}
+function parseAgentFrontmatter(frontmatterLines) {
+  const root = {};
+  const stack = [
+    { indent: -1, target: root }
+  ];
+  for (const line of frontmatterLines) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const match = line.match(/^(\s*)(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_.-]+))\s*:\s*(.*)$/);
+    if (!match) continue;
+    const indent = match[1].length;
+    const key = match[2] ?? match[3] ?? match[4];
+    const rawValue = match[5].trim();
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+    const parent = stack[stack.length - 1].target;
+    if (!rawValue) {
+      const nested = {};
+      parent[key] = nested;
+      stack.push({ indent, target: nested });
+      continue;
+    }
+    parent[key] = parseScalarValue(rawValue);
+  }
+  return root;
+}
+function walkMarkdownFiles(dir) {
+  const entries = readdirSync(dir);
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = resolve4(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      files.push(...walkMarkdownFiles(fullPath));
+      continue;
+    }
+    if (stat.isFile() && entry.endsWith(".md")) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+function parseCanonicalAgentFile(agentPath) {
+  const content = readFileSync2(agentPath, "utf-8");
+  const { frontmatterLines, body } = splitMarkdownFrontmatter(content);
+  const frontmatter = parseAgentFrontmatter(frontmatterLines);
+  const fileStem = basename(agentPath, ".md");
+  const name = typeof frontmatter.name === "string" && frontmatter.name ? frontmatter.name : fileStem;
+  const description = typeof frontmatter.description === "string" && frontmatter.description ? frontmatter.description : firstHeading(body);
+  return {
+    filePath: agentPath,
+    fileStem,
+    name,
+    description,
+    body: body.trim(),
+    frontmatter
+  };
+}
+function readCanonicalAgentFiles(agentsDir) {
+  if (!agentsDir || !existsSync5(agentsDir)) return [];
+  return walkMarkdownFiles(agentsDir).sort((a, b) => a.localeCompare(b)).map(parseCanonicalAgentFile);
+}
+
 // src/generators/shared/claude-family.ts
 async function generateClaudeFamilyOutputs(args2) {
   const {
@@ -5030,13 +5186,13 @@ async function generateClaudeFamilyOutputs(args2) {
     writeFile: writeFile3
   } = args2;
   await Promise.all([
-    writeManifest(config, options, writeJson),
+    writeManifest(config, rootDir, options, writeJson),
     writeMcpConfig(config, platform, writeJson),
     writeHooks(config, platform, options, writeJson, writeFile3),
     writeInstructions(config, rootDir, options, writeFile3)
   ]);
 }
-async function writeManifest(config, options, writeJson) {
+async function writeManifest(config, rootDir, options, writeJson) {
   const manifest = {
     name: config.name,
     version: config.version,
@@ -5053,8 +5209,15 @@ async function writeManifest(config, options, writeJson) {
   if (config.commands) {
     manifest.commands = "./commands/";
   }
-  if (config.agents) {
+  const agentsManifestMode = options.agentsManifestMode ?? "directory";
+  if (config.agents && agentsManifestMode === "directory") {
     manifest.agents = "./agents/";
+  } else if (config.agents && agentsManifestMode === "files") {
+    const agentsDir = resolve5(rootDir, config.agents);
+    const agents = readCanonicalAgentFiles(agentsDir);
+    if (agents.length > 0) {
+      manifest.agents = agents.map((agent) => `./agents/${agent.fileStem}.md`);
+    }
   }
   manifest.skills = "./skills/";
   if ((config.hooks || config.permissions) && options.includeStandardHooksManifest !== false) {
@@ -5149,8 +5312,8 @@ async function writeHooks(config, platform, options, writeJson, writeFile3) {
 }
 async function writeInstructions(config, rootDir, options, writeFile3) {
   if (!config.instructions) return;
-  const srcPath = resolve4(rootDir, config.instructions);
-  if (!existsSync5(srcPath)) return;
+  const srcPath = resolve5(rootDir, config.instructions);
+  if (!existsSync6(srcPath)) return;
   const content = await readTextFile(srcPath);
   const titleSuffix = options.titleSuffix ?? "Plugin";
   const instructions = [
@@ -5167,8 +5330,49 @@ function defaultMapEventName(event) {
 }
 
 // src/generators/claude-code/index.ts
-import { existsSync as existsSync6, readFileSync as readFileSync2, readdirSync, writeFileSync } from "fs";
-import { basename, join as join2 } from "path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync3, readdirSync as readdirSync2, writeFileSync } from "fs";
+import { basename as basename2, join as join2 } from "path";
+
+// src/delegation.ts
+function getPortableDelegationProfile(frontmatter) {
+  const permission = asMap(frontmatter.permission);
+  const bash = asMap(permission?.bash);
+  const task = asMap(permission?.task);
+  return {
+    mode: typeof frontmatter.mode === "string" ? frontmatter.mode : void 0,
+    hidden: frontmatter.hidden === true,
+    editPolicy: typeof permission?.edit === "string" ? permission.edit : void 0,
+    bashPolicy: typeof bash?.["*"] === "string" ? bash["*"] : void 0,
+    taskPolicy: typeof task?.["*"] === "string" ? task["*"] : void 0
+  };
+}
+function buildDelegationBehaviorNotes(frontmatter) {
+  const profile = getPortableDelegationProfile(frontmatter);
+  const notes = [];
+  if (profile.mode === "subagent" || profile.hidden) {
+    notes.push("This specialist is intended primarily for delegated use rather than as the default top-level worker.");
+  }
+  if (profile.editPolicy === "deny") {
+    notes.push("Stay read-only unless the parent task explicitly asks for file edits.");
+  }
+  if (profile.bashPolicy === "deny") {
+    notes.push("Avoid shell commands unless the parent task explicitly requires them.");
+  } else if (profile.bashPolicy === "ask") {
+    notes.push("Use shell commands sparingly and only when they are clearly necessary to complete the task.");
+  }
+  if (profile.taskPolicy === "deny") {
+    notes.push("Do not delegate further subtasks unless the parent task explicitly asks for additional specialist work.");
+  } else if (profile.taskPolicy === "ask") {
+    notes.push("Only delegate further subtasks when the work clearly benefits from another specialist.");
+  }
+  return notes;
+}
+function asMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  return value;
+}
+
+// src/generators/claude-code/index.ts
 var ClaudeCodeGenerator = class extends Generator {
   platform = "claude-code";
   async generate() {
@@ -5180,7 +5384,8 @@ var ClaudeCodeGenerator = class extends Generator {
         manifestPath: ".claude-plugin/plugin.json",
         instructionsFile: "CLAUDE.md",
         pluginRootVar: "CLAUDE_PLUGIN_ROOT",
-        includeStandardHooksManifest: false
+        includeStandardHooksManifest: false,
+        agentsManifestMode: "files"
       },
       writeJson: (relativePath, data) => this.writeJson(relativePath, data),
       writeFile: (relativePath, content) => this.writeFile(relativePath, content)
@@ -5195,29 +5400,108 @@ var ClaudeCodeGenerator = class extends Generator {
   copySkills() {
     super.copySkills();
     const collidingSkills = this.collectCollidingSkills();
+    const wrappedSkills = this.collectCommandWrappedSkills();
     for (const skill of collidingSkills) {
       const outputPath = join2(this.outDir, "skills", skill.dirName, "SKILL.md");
-      if (!existsSync6(outputPath)) continue;
-      const current = readFileSync2(outputPath, "utf-8");
+      if (!existsSync7(outputPath)) continue;
+      const current = readFileSync3(outputPath, "utf-8");
       const hiddenName = buildHiddenSkillName(skill.effectiveName);
-      const rewritten = rewriteClaudeCollidingSkill(current, hiddenName);
+      const rewritten = rewriteClaudeSkillVisibility(current, {
+        nameOverride: hiddenName,
+        userInvocable: false
+      });
+      if (rewritten !== current) {
+        writeFileSync(outputPath, rewritten, "utf-8");
+      }
+    }
+    for (const skill of wrappedSkills) {
+      if (collidingSkills.some((entry) => entry.dirName === skill.dirName)) continue;
+      const outputPath = join2(this.outDir, "skills", skill.dirName, "SKILL.md");
+      if (!existsSync7(outputPath)) continue;
+      const current = readFileSync3(outputPath, "utf-8");
+      const rewritten = rewriteClaudeSkillVisibility(current, {
+        userInvocable: false
+      });
       if (rewritten !== current) {
         writeFileSync(outputPath, rewritten, "utf-8");
       }
     }
   }
+  copyAgents() {
+    if (!this.config.agents) return;
+    const agentsDir = this.resolveConfigPath(this.config.agents, "agents");
+    const agents = readCanonicalAgentFiles(agentsDir);
+    if (agents.length === 0) return;
+    mkdirSync2(join2(this.outDir, "agents"), { recursive: true });
+    for (const agent of agents) {
+      const frontmatter = [
+        "---",
+        `name: ${JSON.stringify(agent.name)}`,
+        `description: ${JSON.stringify(agent.description ?? `${agent.name} specialist.`)}`
+      ];
+      if (typeof agent.frontmatter.model === "string" && agent.frontmatter.model) {
+        frontmatter.push(`model: ${JSON.stringify(agent.frontmatter.model)}`);
+      }
+      const effort = typeof agent.frontmatter.model_reasoning_effort === "string" && agent.frontmatter.model_reasoning_effort ? agent.frontmatter.model_reasoning_effort : typeof agent.frontmatter.effort === "string" && agent.frontmatter.effort ? agent.frontmatter.effort : void 0;
+      if (effort) {
+        frontmatter.push(`effort: ${JSON.stringify(effort)}`);
+      }
+      const maxTurns = typeof agent.frontmatter.maxTurns === "number" ? agent.frontmatter.maxTurns : typeof agent.frontmatter.steps === "number" ? agent.frontmatter.steps : typeof agent.frontmatter.maxSteps === "number" ? agent.frontmatter.maxSteps : void 0;
+      if (typeof maxTurns === "number") {
+        frontmatter.push(`maxTurns: ${maxTurns}`);
+      }
+      const claudeTools = selectClaudeToolsField(agent.frontmatter);
+      if (claudeTools) {
+        frontmatter.push(`tools: ${claudeTools}`);
+      }
+      const disallowedTools = buildClaudeDisallowedTools(agent.frontmatter);
+      if (disallowedTools.length > 0) {
+        frontmatter.push(`disallowedTools: ${disallowedTools.join(", ")}`);
+      }
+      if (typeof agent.frontmatter.skills === "string" && agent.frontmatter.skills.trim()) {
+        frontmatter.push(`skills: ${agent.frontmatter.skills}`);
+      }
+      if (typeof agent.frontmatter.memory === "string" && agent.frontmatter.memory.trim()) {
+        frontmatter.push(`memory: ${JSON.stringify(agent.frontmatter.memory)}`);
+      }
+      if (typeof agent.frontmatter.background === "boolean") {
+        frontmatter.push(`background: ${agent.frontmatter.background}`);
+      }
+      if (typeof agent.frontmatter.isolation === "string" && agent.frontmatter.isolation.trim()) {
+        frontmatter.push(`isolation: ${JSON.stringify(agent.frontmatter.isolation)}`);
+      }
+      if (typeof agent.frontmatter.color === "string" && agent.frontmatter.color.trim()) {
+        frontmatter.push(`color: ${JSON.stringify(agent.frontmatter.color)}`);
+      }
+      frontmatter.push("---");
+      const delegationNotes = buildDelegationBehaviorNotes(agent.frontmatter);
+      const bodyParts = [
+        ...delegationNotes.length > 0 ? [
+          "Delegation contract:",
+          ...delegationNotes.map((note) => `- ${note}`),
+          ""
+        ] : [],
+        agent.body
+      ].filter(Boolean);
+      const outputPath = join2(this.outDir, "agents", `${agent.fileStem}.md`);
+      writeFileSync(outputPath, `${frontmatter.join("\n")}
+
+${bodyParts.join("\n").trim()}
+`, "utf-8");
+    }
+  }
   collectCollidingSkills() {
     if (!this.config.commands) return [];
     const commandsSrc = this.resolveConfigPath(this.config.commands, "commands");
     const skillsSrc = this.resolveConfigPath(this.config.skills, "skills");
-    if (!existsSync6(commandsSrc) || !existsSync6(skillsSrc)) return [];
+    if (!existsSync7(commandsSrc) || !existsSync7(skillsSrc)) return [];
     const commandNames = collectTopLevelCommandNames(commandsSrc);
     const collidingSkills = [];
-    for (const entry of readdirSync(skillsSrc, { withFileTypes: true })) {
+    for (const entry of readdirSync2(skillsSrc, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
       const skillFile = join2(skillsSrc, entry.name, "SKILL.md");
-      if (!existsSync6(skillFile)) continue;
-      const content = readFileSync2(skillFile, "utf-8");
+      if (!existsSync7(skillFile)) continue;
+      const content = readFileSync3(skillFile, "utf-8");
       const effectiveName = getEffectiveSkillName(content, entry.name);
       if (commandNames.has(effectiveName)) {
         collidingSkills.push({ dirName: entry.name, effectiveName });
@@ -5225,16 +5509,48 @@ var ClaudeCodeGenerator = class extends Generator {
     }
     return collidingSkills;
   }
+  collectCommandWrappedSkills() {
+    if (!this.config.commands) return [];
+    const commandsSrc = this.resolveConfigPath(this.config.commands, "commands");
+    const skillsSrc = this.resolveConfigPath(this.config.skills, "skills");
+    if (!existsSync7(commandsSrc) || !existsSync7(skillsSrc)) return [];
+    const referencedSkills = collectWrappedSkillNames(commandsSrc);
+    if (referencedSkills.size === 0) return [];
+    const wrappedSkills = [];
+    for (const entry of readdirSync2(skillsSrc, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const skillFile = join2(skillsSrc, entry.name, "SKILL.md");
+      if (!existsSync7(skillFile)) continue;
+      const content = readFileSync3(skillFile, "utf-8");
+      const effectiveName = getEffectiveSkillName(content, entry.name);
+      if (referencedSkills.has(effectiveName)) {
+        wrappedSkills.push({ dirName: entry.name, effectiveName });
+      }
+    }
+    return wrappedSkills;
+  }
 };
 function collectTopLevelCommandNames(commandsRoot) {
   const commandNames = /* @__PURE__ */ new Set();
-  for (const entry of readdirSync(commandsRoot, { withFileTypes: true })) {
+  for (const entry of readdirSync2(commandsRoot, { withFileTypes: true })) {
     if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
-      commandNames.add(basename(entry.name, ".md"));
+      commandNames.add(basename2(entry.name, ".md"));
     }
   }
   return commandNames;
 }
+function collectWrappedSkillNames(commandsRoot) {
+  const wrappedSkills = /* @__PURE__ */ new Set();
+  for (const entry of readdirSync2(commandsRoot, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) continue;
+    const content = readFileSync3(join2(commandsRoot, entry.name), "utf-8");
+    for (const match of content.matchAll(/Use the `([^`]+)` skill\./g)) {
+      const skillName = match[1]?.trim();
+      if (skillName) wrappedSkills.add(skillName);
+    }
+  }
+  return wrappedSkills;
+}
 function getEffectiveSkillName(content, fallback) {
   const frontmatter = extractFrontmatterLines(content);
   if (!frontmatter) return fallback;
@@ -5251,13 +5567,14 @@ function buildHiddenSkillName(name) {
   const trimmed = name.length > maxBaseLength ? name.slice(0, maxBaseLength) : name;
   return `${trimmed}-skill`;
 }
-function rewriteClaudeCollidingSkill(content, hiddenName) {
+function rewriteClaudeSkillVisibility(content, options) {
   const frontmatter = extractFrontmatterLines(content);
   if (!frontmatter) {
+    const generatedFrontmatter = ["---"];
+    if (options.nameOverride) generatedFrontmatter.push(`name: ${options.nameOverride}`);
+    if (options.userInvocable === false) generatedFrontmatter.push("user-invocable: false");
     return [
-      "---",
-      `name: ${hiddenName}`,
-      "user-invocable: false",
+      ...generatedFrontmatter,
       "---",
       "",
       content.trimStart()
@@ -5268,18 +5585,18 @@ function rewriteClaudeCollidingSkill(content, hiddenName) {
   let sawUserInvocable = false;
   for (let index = 0; index < rewritten.length; index += 1) {
     const trimmed = rewritten[index].trim();
-    if (/^name:\s*/i.test(trimmed)) {
-      rewritten[index] = `name: ${hiddenName}`;
+    if (options.nameOverride && /^name:\s*/i.test(trimmed)) {
+      rewritten[index] = `name: ${options.nameOverride}`;
       sawName = true;
       continue;
     }
-    if (/^user-invocable:\s*/i.test(trimmed)) {
+    if (options.userInvocable === false && /^user-invocable:\s*/i.test(trimmed)) {
       rewritten[index] = "user-invocable: false";
       sawUserInvocable = true;
     }
   }
-  if (!sawName) rewritten.push(`name: ${hiddenName}`);
-  if (!sawUserInvocable) rewritten.push("user-invocable: false");
+  if (options.nameOverride && !sawName) rewritten.push(`name: ${options.nameOverride}`);
+  if (options.userInvocable === false && !sawUserInvocable) rewritten.push("user-invocable: false");
   const lines = content.split("\n");
   const endIndex = findFrontmatterEndIndex(lines);
   const body = endIndex === -1 ? content : lines.slice(endIndex + 1).join("\n");
@@ -5308,162 +5625,51 @@ function stripYamlScalar(value) {
   }
   return trimmed;
 }
-
-// src/generators/cursor/index.ts
-import { existsSync as existsSync8 } from "fs";
-
-// src/agents.ts
-import { existsSync as existsSync7, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync } from "fs";
-import { basename as basename2, resolve as resolve5 } from "path";
-function firstHeading(content) {
-  const lines = content.split(/\r?\n/);
-  for (const line of lines) {
-    const match = line.match(/^#\s+(.*)$/);
-    if (match?.[1]?.trim()) return match[1].trim();
+function buildClaudeDisallowedTools(frontmatter) {
+  const tools = /* @__PURE__ */ new Set();
+  const permission = asMap2(frontmatter.permission);
+  const bash = asMap2(permission?.bash);
+  const legacyTools = asMap2(frontmatter.tools);
+  if (permission?.edit === "deny") {
+    tools.add("Write");
+    tools.add("Edit");
+    tools.add("MultiEdit");
   }
-  return void 0;
-}
-function splitMarkdownFrontmatter(content) {
-  const lines = content.split(/\r?\n/);
-  if (lines[0]?.trim() !== "---") {
-    return {
-      frontmatterLines: [],
-      body: content
-    };
+  if (permission?.bash === "deny" || bash?.["*"] === "deny") {
+    tools.add("Bash");
   }
-  let endIndex = -1;
-  for (let i = 1; i < lines.length; i += 1) {
-    if (lines[i].trim() === "---") {
-      endIndex = i;
-      break;
+  if (legacyTools?.write === false || legacyTools?.edit === false || legacyTools?.patch === false || legacyTools?.multiedit === false) {
+    tools.add("Write");
+    tools.add("Edit");
+    tools.add("MultiEdit");
+  }
+  if (legacyTools?.bash === false || legacyTools?.shell === false) {
+    tools.add("Bash");
+  }
+  if (typeof frontmatter.disallowedTools === "string") {
+    for (const token of frontmatter.disallowedTools.split(",")) {
+      const trimmed = token.trim();
+      if (trimmed) tools.add(trimmed);
     }
   }
-  if (endIndex === -1) {
-    return {
-      frontmatterLines: [],
-      body: content
-    };
+  return Array.from(tools);
+}
+function selectClaudeToolsField(frontmatter) {
+  if (typeof frontmatter.tools !== "string") return null;
+  const tools = frontmatter.tools.split(",").map((token) => token.trim()).filter(Boolean);
+  if (tools.length === 0) return null;
+  if (tools.some((token) => token.startsWith("mcp__"))) {
+    return null;
   }
-  return {
-    frontmatterLines: lines.slice(1, endIndex),
-    body: lines.slice(endIndex + 1).join("\n")
-  };
+  return tools.join(", ");
 }
-function parseScalarValue(raw) {
-  const trimmed = raw.trim();
-  if (trimmed === "true") return true;
-  if (trimmed === "false") return false;
-  if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
-  if (trimmed.length >= 2) {
-    if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
-      return trimmed.slice(1, -1);
-    }
-  }
-  return trimmed;
-}
-function parseAgentFrontmatter(frontmatterLines) {
-  const root = {};
-  const stack = [
-    { indent: -1, target: root }
-  ];
-  for (const line of frontmatterLines) {
-    if (!line.trim() || line.trim().startsWith("#")) continue;
-    const match = line.match(/^(\s*)(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_.-]+))\s*:\s*(.*)$/);
-    if (!match) continue;
-    const indent = match[1].length;
-    const key = match[2] ?? match[3] ?? match[4];
-    const rawValue = match[5].trim();
-    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
-      stack.pop();
-    }
-    const parent = stack[stack.length - 1].target;
-    if (!rawValue) {
-      const nested = {};
-      parent[key] = nested;
-      stack.push({ indent, target: nested });
-      continue;
-    }
-    parent[key] = parseScalarValue(rawValue);
-  }
-  return root;
-}
-function walkMarkdownFiles(dir) {
-  const entries = readdirSync2(dir);
-  const files = [];
-  for (const entry of entries) {
-    const fullPath = resolve5(dir, entry);
-    const stat = statSync(fullPath);
-    if (stat.isDirectory()) {
-      files.push(...walkMarkdownFiles(fullPath));
-      continue;
-    }
-    if (stat.isFile() && entry.endsWith(".md")) {
-      files.push(fullPath);
-    }
-  }
-  return files;
-}
-function parseCanonicalAgentFile(agentPath) {
-  const content = readFileSync3(agentPath, "utf-8");
-  const { frontmatterLines, body } = splitMarkdownFrontmatter(content);
-  const frontmatter = parseAgentFrontmatter(frontmatterLines);
-  const fileStem = basename2(agentPath, ".md");
-  const name = typeof frontmatter.name === "string" && frontmatter.name ? frontmatter.name : fileStem;
-  const description = typeof frontmatter.description === "string" && frontmatter.description ? frontmatter.description : firstHeading(body);
-  return {
-    filePath: agentPath,
-    fileStem,
-    name,
-    description,
-    body: body.trim(),
-    frontmatter
-  };
-}
-function readCanonicalAgentFiles(agentsDir) {
-  if (!agentsDir || !existsSync7(agentsDir)) return [];
-  return walkMarkdownFiles(agentsDir).sort((a, b) => a.localeCompare(b)).map(parseCanonicalAgentFile);
-}
-
-// src/delegation.ts
-function getPortableDelegationProfile(frontmatter) {
-  const permission = asMap(frontmatter.permission);
-  const bash = asMap(permission?.bash);
-  const task = asMap(permission?.task);
-  return {
-    mode: typeof frontmatter.mode === "string" ? frontmatter.mode : void 0,
-    hidden: frontmatter.hidden === true,
-    editPolicy: typeof permission?.edit === "string" ? permission.edit : void 0,
-    bashPolicy: typeof bash?.["*"] === "string" ? bash["*"] : void 0,
-    taskPolicy: typeof task?.["*"] === "string" ? task["*"] : void 0
-  };
-}
-function buildDelegationBehaviorNotes(frontmatter) {
-  const profile = getPortableDelegationProfile(frontmatter);
-  const notes = [];
-  if (profile.mode === "subagent" || profile.hidden) {
-    notes.push("This specialist is intended primarily for delegated use rather than as the default top-level worker.");
-  }
-  if (profile.editPolicy === "deny") {
-    notes.push("Stay read-only unless the parent task explicitly asks for file edits.");
-  }
-  if (profile.bashPolicy === "deny") {
-    notes.push("Avoid shell commands unless the parent task explicitly requires them.");
-  } else if (profile.bashPolicy === "ask") {
-    notes.push("Use shell commands sparingly and only when they are clearly necessary to complete the task.");
-  }
-  if (profile.taskPolicy === "deny") {
-    notes.push("Do not delegate further subtasks unless the parent task explicitly asks for additional specialist work.");
-  } else if (profile.taskPolicy === "ask") {
-    notes.push("Only delegate further subtasks when the work clearly benefits from another specialist.");
-  }
-  return notes;
-}
-function asMap(value) {
+function asMap2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
   return value;
 }
 
 // src/generators/cursor/index.ts
+import { existsSync as existsSync8 } from "fs";
 var CursorGenerator = class extends Generator {
   platform = "cursor";
   async generate() {
@@ -5548,7 +5754,9 @@ var CursorGenerator = class extends Generator {
           if (entry.timeout) hookDef.timeout = entry.timeout;
           if (entry.matcher) hookDef.matcher = entry.matcher;
           if (entry.failClosed) hookDef.failClosed = entry.failClosed;
-          if (entry.loop_limit !== void 0) hookDef.loop_limit = entry.loop_limit;
+          if (entry.loop_limit !== void 0 && CURSOR_LOOP_LIMIT_HOOK_EVENTS.includes(event)) {
+            hookDef.loop_limit = entry.loop_limit;
+          }
           return hookDef;
         })
       ];
@@ -5682,6 +5890,23 @@ function parseCommandFrontmatterDescription(frontmatterLines) {
   }
   return void 0;
 }
+function parseCommandFrontmatterString(frontmatterLines, key) {
+  const pattern = new RegExp(`^${key}:\\s*(.+)\\s*$`, "i");
+  for (const line of frontmatterLines) {
+    const match = pattern.exec(line.trim());
+    if (match?.[1]) {
+      return stripYamlScalar2(match[1]);
+    }
+  }
+  return void 0;
+}
+function parseCommandFrontmatterBoolean(frontmatterLines, key) {
+  const value = parseCommandFrontmatterString(frontmatterLines, key);
+  if (!value) return void 0;
+  if (/^true$/i.test(value)) return true;
+  if (/^false$/i.test(value)) return false;
+  return void 0;
+}
 function walkMarkdownFiles2(dir) {
   const entries = readdirSync3(dir);
   const files = [];
@@ -5712,6 +5937,9 @@ function readCanonicalCommandFiles(commandsDir) {
       commandId,
       title,
       description: parseCommandFrontmatterDescription(frontmatterLines),
+      agent: parseCommandFrontmatterString(frontmatterLines, "agent"),
+      subtask: parseCommandFrontmatterBoolean(frontmatterLines, "subtask"),
+      model: parseCommandFrontmatterString(frontmatterLines, "model"),
       body: body.trim()
     };
   });
@@ -5730,6 +5958,7 @@ var CodexGenerator = class extends Generator {
   async generate() {
     await Promise.all([
       this.generateManifest(),
+      this.generateAppConfig(),
       this.generateMcpConfig(".mcp.json", {
         includeDefaultAuthHeaders: false,
         transformRemoteEntry: ({ name, server }) => {
@@ -5824,6 +6053,11 @@ var CodexGenerator = class extends Generator {
     }
     await this.writeJson(".codex-plugin/plugin.json", manifest);
   }
+  async generateAppConfig() {
+    const appConfig = this.config.platforms?.codex?.app;
+    if (!appConfig || typeof appConfig !== "object" || Array.isArray(appConfig)) return;
+    await this.writeJson(".app.json", appConfig);
+  }
   async generatePermissionsCompanion() {
     const compilerIntent = this.getCompilerIntent();
     const rules = collectPermissionRules(this.config.permissions);
@@ -5961,8 +6195,8 @@ var CodexGenerator = class extends Generator {
 };
 
 // src/generators/opencode/index.ts
-import { existsSync as existsSync11, readdirSync as readdirSync4, readFileSync as readFileSync5, statSync as statSync3 } from "fs";
-import { resolve as resolve7 } from "path";
+import { existsSync as existsSync11, readdirSync as readdirSync4, readFileSync as readFileSync5, statSync as statSync3, writeFileSync as writeFileSync2 } from "fs";
+import { basename as basename3, resolve as resolve7 } from "path";
 var OpenCodeGenerator = class extends Generator {
   platform = "opencode";
   async generate() {
@@ -5972,9 +6206,11 @@ var OpenCodeGenerator = class extends Generator {
     ]);
     this.copySkills();
     this.copyCommands();
+    this.copyAgents();
     this.copyScripts();
     this.copyAssets();
     this.copyPassthrough();
+    this.rewriteOpenCodeSkillAgentMentions();
   }
   async generatePackageJson() {
     const npmName = this.config.platforms?.opencode?.npmPackage ?? `opencode-${this.config.name}`;
@@ -6286,7 +6522,10 @@ var OpenCodeGenerator = class extends Generator {
     for (const command2 of commands) {
       output[command2.commandId] = {
         template: command2.body,
-        ...command2.description ? { description: command2.description } : {}
+        ...command2.description ? { description: command2.description } : {},
+        ...command2.agent ? { agent: command2.agent } : {},
+        ...typeof command2.subtask === "boolean" ? { subtask: command2.subtask } : {},
+        ...command2.model ? { model: command2.model } : {}
       };
     }
     return output;
@@ -6312,14 +6551,36 @@ var OpenCodeGenerator = class extends Generator {
       if (typeof agent.frontmatter.temperature === "number") {
         definition.temperature = agent.frontmatter.temperature;
       }
+      if (typeof agent.frontmatter.steps === "number") {
+        definition.steps = agent.frontmatter.steps;
+      }
+      if (typeof agent.frontmatter.maxSteps === "number" && definition.steps === void 0) {
+        definition.steps = agent.frontmatter.maxSteps;
+      }
+      if (typeof agent.frontmatter.disable === "boolean") {
+        definition.disable = agent.frontmatter.disable;
+      }
       if (typeof agent.frontmatter.hidden === "boolean") {
         definition.hidden = agent.frontmatter.hidden;
       }
-      const permission = asOpenCodeMap(agent.frontmatter.permission);
+      if (typeof agent.frontmatter.color === "string" && agent.frontmatter.color) {
+        definition.color = agent.frontmatter.color;
+      }
+      if (typeof agent.frontmatter.topP === "number") {
+        definition.topP = agent.frontmatter.topP;
+      }
+      if (typeof agent.frontmatter.top_p === "number" && definition.topP === void 0) {
+        definition.topP = agent.frontmatter.top_p;
+      }
+      const legacyToolTranslation = translateLegacyOpenCodeTools(agent.frontmatter.tools);
+      const permission = mergeOpenCodeMaps(
+        legacyToolTranslation.permission,
+        asOpenCodeMap(agent.frontmatter.permission)
+      );
       if (permission) {
         definition.permission = permission;
       }
-      const tools = asOpenCodeMap(agent.frontmatter.tools);
+      const tools = legacyToolTranslation.untranslated;
       if (tools) {
         definition.tools = tools;
       }
@@ -6401,11 +6662,99 @@ var OpenCodeGenerator = class extends Generator {
     }
     return files;
   }
+  rewriteOpenCodeSkillAgentMentions() {
+    if (!this.config.agents || !this.config.skills) return;
+    const skillsDir = resolve7(this.outDir, "skills");
+    if (!existsSync11(skillsDir)) return;
+    const agentsDir = this.resolveConfigPath(this.config.agents, "agents");
+    const agentNames = readCanonicalAgentFiles(agentsDir).map((agent) => agent.name).filter(Boolean);
+    if (agentNames.length === 0) return;
+    for (const filePath of this.walkFiles(skillsDir)) {
+      if (basename3(filePath) !== "SKILL.md") continue;
+      const source = readFileSync5(filePath, "utf-8");
+      let rewritten = source;
+      for (const agentName of agentNames) {
+        const escaped = escapeRegExp(agentName);
+        rewritten = rewritten.replace(new RegExp(`\`(${escaped})\``, "g"), "`@$1`");
+      }
+      if (rewritten !== source) {
+        writeFileSync2(filePath, rewritten);
+      }
+    }
+  }
 };
 function asOpenCodeMap(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
   return value;
 }
+function mergeOpenCodeMaps(base, override) {
+  if (!base) return override;
+  if (!override) return base;
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (isOpenCodeMap(merged[key]) && isOpenCodeMap(value)) {
+      merged[key] = {
+        ...merged[key],
+        ...value
+      };
+      continue;
+    }
+    merged[key] = value;
+  }
+  return merged;
+}
+function translateLegacyOpenCodeTools(value) {
+  const tools = asOpenCodeMap(value);
+  if (!tools) return {};
+  const permission = {};
+  const untranslated = {};
+  for (const [rawKey, rawValue] of Object.entries(tools)) {
+    const key = normalizeLegacyOpenCodeToolKey(rawKey);
+    const translated = translateLegacyOpenCodeToolValue(rawValue);
+    if (translated === void 0) {
+      untranslated[rawKey] = rawValue;
+      continue;
+    }
+    permission[key] = translated;
+  }
+  return {
+    ...Object.keys(permission).length > 0 ? { permission } : {},
+    ...Object.keys(untranslated).length > 0 ? { untranslated } : {}
+  };
+}
+function normalizeLegacyOpenCodeToolKey(key) {
+  switch (key) {
+    case "write":
+    case "patch":
+    case "multiedit":
+      return "edit";
+    case "shell":
+      return "bash";
+    default:
+      return key;
+  }
+}
+function translateLegacyOpenCodeToolValue(value) {
+  if (typeof value === "boolean") {
+    return value ? "allow" : "deny";
+  }
+  if (typeof value === "string" && ["allow", "ask", "deny"].includes(value)) {
+    return value;
+  }
+  if (!isOpenCodeMap(value)) return void 0;
+  const nested = {};
+  for (const [key, rawNested] of Object.entries(value)) {
+    const translated = translateLegacyOpenCodeToolValue(rawNested);
+    if (translated === void 0 || typeof translated === "object") {
+      return void 0;
+    }
+    nested[key] = translated;
+  }
+  return nested;
+}
+function isOpenCodeMap(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
 function mapHookEventName(event) {
   const map = {
     sessionStart: "session.created",
@@ -6426,6 +6775,9 @@ function mapHookEventName(event) {
 function toPascalCase(str) {
   return str.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 
 // src/generators/github-copilot/index.ts
 var GitHubCopilotGenerator = class extends Generator {
@@ -6673,6 +7025,40 @@ var GENERATORS = {
   cline: ClineGenerator,
   amp: AmpGenerator
 };
+function assertPathWithinRoot(rootDir, configPath, configKey) {
+  const resolvedPath = resolve8(rootDir, configPath);
+  const rel = relative5(rootDir, resolvedPath);
+  if (rel.startsWith("..")) {
+    throw new Error(`${configKey} path "${configPath}" resolves outside the project root.`);
+  }
+}
+function validateConfiguredPaths(config, rootDir) {
+  assertPathWithinRoot(rootDir, config.skills, "skills");
+  if (config.commands) {
+    assertPathWithinRoot(rootDir, config.commands, "commands");
+  }
+  if (config.agents) {
+    assertPathWithinRoot(rootDir, config.agents, "agents");
+  }
+  if (config.scripts) {
+    assertPathWithinRoot(rootDir, config.scripts, "scripts");
+  }
+  if (config.assets) {
+    assertPathWithinRoot(rootDir, config.assets, "assets");
+  }
+  if (config.instructions) {
+    assertPathWithinRoot(rootDir, config.instructions, "instructions");
+  }
+  for (const passthroughPath of config.passthrough ?? []) {
+    assertPathWithinRoot(rootDir, passthroughPath, "passthrough");
+  }
+  if (config.brand?.icon) {
+    assertPathWithinRoot(rootDir, config.brand.icon, "brand.icon");
+  }
+  for (const screenshot of config.brand?.screenshots ?? []) {
+    assertPathWithinRoot(rootDir, screenshot, "brand.screenshots");
+  }
+}
 async function build(config, rootDir, options = {}) {
   const targets = options.targets ?? config.targets;
   const outDir = resolve8(rootDir, config.outDir);
@@ -6682,10 +7068,11 @@ async function build(config, rootDir, options = {}) {
       `outDir "${config.outDir}" resolves outside the project root. Refusing to delete.`
     );
   }
+  validateConfiguredPaths(config, rootDir);
   if (options.clean !== false) {
     rmSync(outDir, { recursive: true, force: true });
   }
-  mkdirSync2(outDir, { recursive: true });
+  mkdirSync3(outDir, { recursive: true });
   const generators = targets.map((target) => {
     const GeneratorClass = GENERATORS[target];
     if (!GeneratorClass) {
@@ -6705,7 +7092,7 @@ import { spawn as spawn2 } from "child_process";
 
 // src/cli/lint.ts
 import { existsSync as existsSync17, readdirSync as readdirSync5, readFileSync as readFileSync6 } from "fs";
-import { resolve as resolve9, relative as relative6, basename as basename3, dirname as dirname3 } from "path";
+import { resolve as resolve9, relative as relative6, basename as basename4, dirname as dirname3 } from "path";
 
 // src/validation/platform-rules.ts
 var STANDARD_SKILL_FRONTMATTER = [
@@ -6813,10 +7200,22 @@ var PLATFORM_LIMIT_POLICIES = {
   },
   "codex": {
     ...NULL_LIMIT_POLICIES,
-    skillDescriptionMax: { kind: "hard" },
-    skillNameMustMatchDir: { kind: "hard" },
-    manifestPromptMax: { kind: "hard" },
-    manifestPromptCountMax: { kind: "hard" },
+    skillDescriptionMax: {
+      kind: "advisory",
+      notes: "Pluxx keeps Codex descriptions concise at 1,024 characters as a conservative compatibility heuristic; the current docs do not state this as an official hard cap."
+    },
+    skillNameMustMatchDir: {
+      kind: "advisory",
+      notes: "Pluxx keeps Codex skill directory names aligned with skill names for portability and predictability, but the current docs do not state this as a formal hard requirement."
+    },
+    manifestPromptMax: {
+      kind: "advisory",
+      notes: "Pluxx keeps Codex default prompts short at 128 characters as a conservative listing heuristic; the current docs do not publish this as a hard limit."
+    },
+    manifestPromptCountMax: {
+      kind: "advisory",
+      notes: "Pluxx keeps Codex default prompt count to three as a conservative listing heuristic; the current docs do not publish this as a hard limit."
+    },
     manifestPathPrefix: { kind: "hard" },
     instructionsMaxBytes: {
       kind: "hard",
@@ -6869,7 +7268,7 @@ var PLATFORM_LIMIT_POLICIES = {
 var PLATFORM_VALIDATION_RULES = {
   "claude-code": {
     platform: "claude-code",
-    summary: "Claude Code plugins use an optional manifest at .claude-plugin/plugin.json with auto-discovery for skills, commands, agents, hooks, MCP, and output styles.",
+    summary: "Claude Code plugins use an optional manifest at .claude-plugin/plugin.json with auto-discovery for skills, commands, agents, hooks, MCP, marketplaces, and output styles.",
     limits: PLATFORM_LIMITS["claude-code"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["claude-code"],
     skillDiscoveryDirs: [
@@ -6877,7 +7276,21 @@ var PLATFORM_VALIDATION_RULES = {
     ],
     frontmatter: {
       standard: [...STANDARD_SKILL_FRONTMATTER],
-      additional: []
+      additional: [
+        "when_to_use",
+        "argument-hint",
+        "arguments",
+        "user-invocable",
+        "allowed-tools",
+        "model",
+        "effort",
+        "context",
+        "agent",
+        "hooks",
+        "paths",
+        "shell"
+      ],
+      notes: "Claude exposes the richest documented skill frontmatter of the core four."
     },
     manifest: {
       files: [".claude-plugin/plugin.json"],
@@ -6885,43 +7298,58 @@ var PLATFORM_VALIDATION_RULES = {
       notes: "The manifest is optional; if present, name is the only required field."
     },
     mcp: {
-      files: [".mcp.json"],
+      files: [".mcp.json", ".claude-plugin/plugin.json"],
       rootKey: "mcpServers",
       transports: ["stdio", "http", "sse"],
-      auth: ["headers", "env interpolation"],
-      notes: "Claude Code supports either inline MCP config in plugin.json or a separate .mcp.json file."
+      auth: ["headers", "env interpolation", "OAuth 2.0", "bearer tokens", "dynamic headers"],
+      notes: "Claude Code supports either inline MCP config in plugin.json or a separate .mcp.json file, with marketplace and dependency-aware install flows."
     },
     hooks: {
       supported: true,
-      files: ["hooks/hooks.json"],
-      eventNames: [],
-      notes: "Hook configs can be stored in hooks/hooks.json or inlined in plugin.json."
+      files: ["hooks/hooks.json", ".claude-plugin/plugin.json", "~/.claude/settings.json", ".claude/settings.json", ".claude/settings.local.json"],
+      eventNames: ["SessionStart", "PreToolUse", "PostToolUse", "PermissionRequest", "TaskCreated", "TaskCompleted", "Stop", "Notification", "ConfigChange"],
+      notes: "Hook configs can be stored in hooks/hooks.json, inlined in plugin.json, added in settings files, or scoped through skill and agent frontmatter."
     },
     instructions: {
       files: ["CLAUDE.md"],
-      format: "markdown"
+      format: "markdown",
+      notes: "Claude keeps persistent instructions in CLAUDE.md and pushes longer procedures into skills."
     },
     sources: [
-      { label: "Claude Code headless docs", url: "https://code.claude.com/docs/en/headless" },
+      { label: "Claude Code MCP docs", url: "https://code.claude.com/docs/en/mcp" },
+      { label: "Claude Code plugin marketplaces docs", url: "https://code.claude.com/docs/en/plugin-marketplaces" },
+      { label: "Claude Code plugin dependencies docs", url: "https://code.claude.com/docs/en/plugin-dependencies" },
+      { label: "Claude Code features overview", url: "https://code.claude.com/docs/en/features-overview" },
+      { label: "Claude Code best practices", url: "https://code.claude.com/docs/en/best-practices" },
       { label: "Claude Code CLI reference", url: "https://code.claude.com/docs/en/cli-reference" },
       { label: "Claude Code discover plugins docs", url: "https://code.claude.com/docs/en/discover-plugins" },
+      { label: "Claude Code plugins docs", url: "https://code.claude.com/docs/en/plugins" },
       { label: "Claude Code plugins reference", url: "https://code.claude.com/docs/en/plugins-reference" },
+      { label: "Claude Code hooks guide", url: "https://code.claude.com/docs/en/hooks-guide" },
       { label: "Claude Code hooks docs", url: "https://code.claude.com/docs/en/hooks" },
-      { label: "Claude Code skills docs", url: "https://code.claude.com/docs/en/skills" }
+      { label: "Claude Code skills docs", url: "https://code.claude.com/docs/en/skills" },
+      { label: "Claude Code sub-agents docs", url: "https://code.claude.com/docs/en/sub-agents" },
+      { label: "Claude Code env vars docs", url: "https://code.claude.com/docs/en/env-vars" }
     ]
   },
   "cursor": {
     platform: "cursor",
-    summary: "Cursor plugins use .cursor-plugin/plugin.json plus auto-discovered rules, skills, agents, commands, hooks, and mcp.json at the plugin root; Cursor subagents are a related but separate surface under .cursor/agents and ~/.cursor/agents.",
+    summary: "Cursor plugins use .cursor-plugin/plugin.json plus native rules, skills, hooks, MCP, marketplace metadata, and subagent surfaces, with additional project and user config outside the plugin bundle.",
     limits: PLATFORM_LIMITS["cursor"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["cursor"],
     skillDiscoveryDirs: [
       { path: "skills/", level: "supported" },
-      { path: "SKILL.md", level: "fallback", notes: "Used when no skills directory or manifest skill path is present." }
+      { path: ".cursor/skills/", level: "supported" },
+      { path: "~/.cursor/skills/", level: "supported" },
+      { path: ".agents/skills/", level: "supported" },
+      { path: "~/.agents/skills/", level: "supported" },
+      { path: ".claude/skills/", level: "supported", notes: "Compatibility directory" },
+      { path: ".codex/skills/", level: "supported", notes: "Compatibility directory" }
     ],
     frontmatter: {
       standard: [...STANDARD_SKILL_FRONTMATTER],
-      additional: []
+      additional: [],
+      notes: "Cursor skills document the shared frontmatter set plus compatibility metadata and supporting-file patterns."
     },
     manifest: {
       files: [".cursor-plugin/plugin.json"],
@@ -6929,16 +7357,16 @@ var PLATFORM_VALIDATION_RULES = {
       notes: "Cursor documents plugin.json as the required plugin manifest."
     },
     mcp: {
-      files: ["mcp.json"],
+      files: ["mcp.json", ".cursor/mcp.json", "~/.cursor/mcp.json"],
       rootKey: "mcpServers",
-      transports: ["stdio", "http", "sse"],
-      auth: ["headers", "env interpolation"]
+      transports: ["stdio", "sse", "streamable-http"],
+      auth: ["headers", "env interpolation", "OAuth", "static OAuth credentials"]
     },
     hooks: {
       supported: true,
-      files: ["hooks/hooks.json"],
-      eventNames: [],
-      notes: "Cursor plugin hooks live under hooks/hooks.json; project hooks also exist separately in .cursor/hooks.json."
+      files: ["hooks/hooks.json", ".cursor/hooks.json", "~/.cursor/hooks.json"],
+      eventNames: ["sessionStart", "preToolUse", "postToolUse", "subagentStart", "subagentStop", "beforeShellExecution", "afterShellExecution"],
+      notes: "Cursor plugin hooks live under hooks/hooks.json; project and user hooks also exist separately and reload on save."
     },
     instructions: {
       files: ["rules/", "AGENTS.md"],
@@ -6946,25 +7374,32 @@ var PLATFORM_VALIDATION_RULES = {
       notes: "rules/ is the plugin-native instruction surface. AGENTS.md remains useful as shared repo guidance. Cursor subagents use markdown files under .cursor/agents or ~/.cursor/agents (with .claude/.codex compatibility paths)."
     },
     sources: [
-      { label: "Cursor plugins reference", url: "https://cursor.com/docs/reference/plugins" },
       { label: "Cursor plugins overview", url: "https://cursor.com/docs/plugins" },
       { label: "Cursor hooks docs", url: "https://cursor.com/docs/hooks" },
       { label: "Cursor skills docs", url: "https://cursor.com/docs/skills" },
       { label: "Cursor rules docs", url: "https://cursor.com/docs/rules" },
       { label: "Cursor MCP docs", url: "https://cursor.com/docs/mcp" },
       { label: "Cursor CLI headless docs", url: "https://cursor.com/docs/cli/headless" },
+      { label: "Cursor CLI slash commands", url: "https://cursor.com/docs/cli/reference/slash-commands" },
       { label: "Cursor CLI parameters", url: "https://cursor.com/docs/cli/reference/parameters" },
       { label: "Cursor CLI authentication", url: "https://cursor.com/docs/cli/reference/authentication" },
+      { label: "Cursor CLI permissions", url: "https://cursor.com/docs/cli/reference/permissions" },
+      { label: "Cursor CLI configuration", url: "https://cursor.com/docs/cli/reference/configuration" },
+      { label: "Cursor ACP docs", url: "https://cursor.com/docs/cli/acp" },
       { label: "Cursor subagents docs", url: "https://cursor.com/docs/subagents" }
     ]
   },
   "codex": {
     platform: "codex",
-    summary: "Codex plugins use .codex-plugin/plugin.json with skills, .mcp.json, optional app mappings, and AGENTS.md; current docs separate plugin packaging from hooks configuration and do not document plugin-provided slash commands.",
+    summary: "Codex plugins use .codex-plugin/plugin.json with skills, optional .mcp.json and .app.json, marketplace catalogs, cache installs, AGENTS.md instructions, and separate hook configuration.",
     limits: PLATFORM_LIMITS["codex"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["codex"],
     skillDiscoveryDirs: [
-      { path: "skills/", level: "supported" }
+      { path: "skills/", level: "supported" },
+      { path: "$CWD/.agents/skills/", level: "supported" },
+      { path: "ancestor .agents/skills/", level: "supported", notes: "Walks upward until repo root" },
+      { path: "$HOME/.agents/skills/", level: "supported" },
+      { path: "/etc/codex/skills/", level: "supported" }
     ],
     frontmatter: {
       standard: [...STANDARD_SKILL_FRONTMATTER],
@@ -6976,68 +7411,95 @@ var PLATFORM_VALIDATION_RULES = {
       notes: "The build plugins guide documents plugin.json, skills/, .mcp.json, .app.json, and assets/ as the standard plugin structure."
     },
     mcp: {
-      files: [".mcp.json"],
+      files: [".mcp.json", ".codex/config.toml"],
       rootKey: "mcpServers",
-      transports: ["stdio", "http", "sse"],
-      auth: ["bearer_token_env_var", "env_http_headers", "http_headers", "platform-managed auth"],
-      notes: "The current build guide documents mcpServers as a path to .mcp.json in the plugin bundle."
+      transports: ["stdio", "streamable-http"],
+      auth: ["bearer token", "OAuth", "header env vars"],
+      notes: "The current build guide documents mcpServers as a path to .mcp.json in the plugin bundle, while active MCP state also lives in config.toml."
     },
     hooks: {
       supported: true,
       files: [".codex/hooks.json", "~/.codex/hooks.json"],
-      eventNames: [],
-      notes: "Codex documents hooks in project/user config, but the current plugin build guide does not document plugin-packaged hooks."
+      eventNames: ["SessionStart", "PreToolUse", "PermissionRequest", "PostToolUse", "UserPromptSubmit", "Stop"],
+      notes: "Codex documents hooks in project/user config, guarded by the codex_hooks feature flag; the current plugin build guide does not document plugin-packaged hooks."
     },
     instructions: {
-      files: ["AGENTS.md"],
-      format: "markdown"
+      files: ["AGENTS.md", "AGENTS.override.md"],
+      format: "markdown",
+      notes: "Codex also supports model instruction overrides plus configurable fallback filenames for project docs."
     },
     sources: [
+      { label: "Codex plugins docs", url: "https://developers.openai.com/codex/plugins" },
       { label: "Codex build plugins docs", url: "https://developers.openai.com/codex/plugins/build" },
+      { label: "Codex CLI features docs", url: "https://developers.openai.com/codex/cli/features" },
+      { label: "Codex CLI reference docs", url: "https://developers.openai.com/codex/cli/reference" },
+      { label: "Codex slash commands docs", url: "https://developers.openai.com/codex/cli/slash-commands" },
+      { label: "Codex advanced config docs", url: "https://developers.openai.com/codex/config-advanced" },
+      { label: "Codex rules docs", url: "https://developers.openai.com/codex/rules" },
       { label: "Codex hooks docs", url: "https://developers.openai.com/codex/hooks" },
       { label: "Codex skills docs", url: "https://developers.openai.com/codex/skills" },
       { label: "Codex MCP docs", url: "https://developers.openai.com/codex/mcp" },
-      { label: "Codex AGENTS.md guide", url: "https://developers.openai.com/codex/guides/agents-md" }
+      { label: "Codex AGENTS.md guide", url: "https://developers.openai.com/codex/guides/agents-md" },
+      { label: "Codex subagents docs", url: "https://developers.openai.com/codex/subagents" },
+      { label: "Codex subagents concept docs", url: "https://developers.openai.com/codex/concepts/subagents" },
+      { label: "Codex noninteractive docs", url: "https://developers.openai.com/codex/noninteractive" },
+      { label: "Codex SDK docs", url: "https://developers.openai.com/codex/sdk" },
+      { label: "Codex agents SDK guide", url: "https://developers.openai.com/codex/guides/agents-sdk" }
     ]
   },
   "opencode": {
     platform: "opencode",
-    summary: "OpenCode plugins are code-first TypeScript or JavaScript modules that register skills, commands, MCP servers, and hook handlers programmatically.",
+    summary: "OpenCode plugins are code-first JS or TS modules loaded from local plugin dirs or npm references in config, with native skills, commands, agents, MCP, and permission surfaces.",
     limits: PLATFORM_LIMITS["opencode"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["opencode"],
     skillDiscoveryDirs: [
-      { path: "skills/", level: "supported" }
+      { path: "skills/", level: "supported" },
+      { path: ".opencode/skills/", level: "supported" },
+      { path: "~/.config/opencode/skills/", level: "supported" },
+      { path: ".claude/skills/", level: "supported", notes: "Compatibility directory" },
+      { path: ".agents/skills/", level: "supported", notes: "Compatibility directory" }
     ],
     frontmatter: {
       standard: [...STANDARD_SKILL_FRONTMATTER],
-      additional: []
+      additional: [],
+      notes: "OpenCode supports Agent Skills semantics, but plugin runtime behavior is code-first rather than manifest-first."
     },
     manifest: {
-      files: ["package.json", "index.ts"],
-      required: true,
-      notes: "OpenCode plugins are loaded as local modules or npm packages rather than a JSON manifest-only bundle."
+      files: ["opencode.json", ".opencode/plugins/", "~/.config/opencode/plugins/"],
+      required: false,
+      notes: "OpenCode plugins are loaded as local modules or npm packages through config rather than a dedicated manifest-only bundle."
     },
     mcp: {
-      files: ["index.ts"],
+      files: ["opencode.json"],
+      rootKey: "mcp",
       transports: ["local", "remote"],
-      auth: ["headers", "programmatic env interpolation", "OAuth"],
-      notes: 'OpenCode plugin code mutates Config["mcp"] programmatically; the underlying platform config supports local and remote servers.'
+      auth: ["headers", "env interpolation", "OAuth"],
+      notes: "OpenCode config owns MCP; plugins can also extend runtime behavior programmatically."
     },
     hooks: {
       supported: true,
-      files: ["index.ts"],
+      files: ["plugin module (index.ts/index.js)"],
       eventNames: [],
       notes: "OpenCode hooks are plugin event handlers implemented in code, not a separate hooks.json file."
     },
     instructions: {
-      files: ["index.ts"],
-      format: "typescript",
-      notes: "Plugins inject instructions into the runtime system prompt from code."
+      files: ["AGENTS.md", "CLAUDE.md", "opencode.json"],
+      format: "markdown + json + code",
+      notes: "OpenCode supports AGENTS.md, CLAUDE.md fallback, config instructions, and plugin runtime instruction injection."
     },
     sources: [
+      { label: "OpenCode SDK docs", url: "https://opencode.ai/docs/sdk/" },
+      { label: "OpenCode server docs", url: "https://opencode.ai/docs/server/" },
+      { label: "OpenCode config docs", url: "https://opencode.ai/docs/config/" },
       { label: "OpenCode plugins docs", url: "https://opencode.ai/docs/plugins/" },
       { label: "OpenCode skills docs", url: "https://opencode.ai/docs/skills/" },
-      { label: "OpenCode MCP servers docs", url: "https://opencode.ai/docs/mcp-servers/" }
+      { label: "OpenCode commands docs", url: "https://opencode.ai/docs/commands/" },
+      { label: "OpenCode agents docs", url: "https://opencode.ai/docs/agents/" },
+      { label: "OpenCode MCP servers docs", url: "https://opencode.ai/docs/mcp-servers/" },
+      { label: "OpenCode custom tools docs", url: "https://opencode.ai/docs/custom-tools/" },
+      { label: "OpenCode permissions docs", url: "https://opencode.ai/docs/permissions/" },
+      { label: "OpenCode rules docs", url: "https://opencode.ai/docs/rules/" },
+      { label: "OpenCode ACP docs", url: "https://opencode.ai/docs/acp/" }
     ]
   },
   "openhands": {
@@ -7301,7 +7763,8 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       commands: {
         mode: "preserve",
-        nativeSurfaces: ["commands/*.md"]
+        nativeSurfaces: ["commands/*.md", "skills/<skill>/SKILL.md"],
+        notes: "Claude still supports command files, but the product is increasingly converging command workflows into skills."
       },
       agents: {
         mode: "preserve",
@@ -7310,7 +7773,7 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       hooks: {
         mode: "preserve",
-        nativeSurfaces: ["hooks/hooks.json", ".claude-plugin/plugin.json"]
+        nativeSurfaces: ["hooks/hooks.json", ".claude-plugin/plugin.json", "settings hooks", "skill/agent frontmatter hooks"]
       },
       permissions: {
         mode: "translate",
@@ -7323,8 +7786,8 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       distribution: {
         mode: "translate",
-        nativeSurfaces: [".claude-plugin/plugin.json", "install scopes", "user configuration"],
-        notes: "Distribution surfaces are native, but shared brand metadata is narrower than Codex."
+        nativeSurfaces: [".claude-plugin/plugin.json", "marketplaces", "install scopes", "user configuration", "/reload-plugins"],
+        notes: "Distribution surfaces are native, including plugin marketplaces and explicit reload behavior."
       }
     },
     sources: PLATFORM_VALIDATION_RULES["claude-code"].sources
@@ -7343,7 +7806,7 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       commands: {
         mode: "preserve",
-        nativeSurfaces: ["commands/*"]
+        nativeSurfaces: ["commands/*", "slash commands"]
       },
       agents: {
         mode: "translate",
@@ -7361,11 +7824,11 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       runtime: {
         mode: "preserve",
-        nativeSurfaces: ["mcp.json", ".cursor-plugin/plugin.json", "scripts/", "assets/"]
+        nativeSurfaces: ["mcp.json", ".cursor/mcp.json", "~/.cursor/mcp.json", ".cursor-plugin/plugin.json", "scripts/", "assets/"]
       },
       distribution: {
         mode: "preserve",
-        nativeSurfaces: [".cursor-plugin/plugin.json", ".cursor-plugin/marketplace.json", "local marketplace install path"]
+        nativeSurfaces: [".cursor-plugin/plugin.json", ".cursor-plugin/marketplace.json", "local marketplace install path", "reload window / restart"]
       }
     },
     sources: PLATFORM_VALIDATION_RULES["cursor"].sources
@@ -7408,7 +7871,7 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       distribution: {
         mode: "preserve",
-        nativeSurfaces: [".codex-plugin/plugin.json", "~/.agents/plugins/marketplace.json", "$REPO_ROOT/.agents/plugins/marketplace.json"]
+        nativeSurfaces: [".codex-plugin/plugin.json", "~/.agents/plugins/marketplace.json", "$REPO_ROOT/.agents/plugins/marketplace.json", "cache install path", "restart after update"]
       }
     },
     sources: PLATFORM_VALIDATION_RULES["codex"].sources
@@ -7418,7 +7881,7 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
     buckets: {
       instructions: {
         mode: "translate",
-        nativeSurfaces: ["config instructions", "plugin code"],
+        nativeSurfaces: ["AGENTS.md", "CLAUDE.md", "config instructions", "plugin code"],
         notes: "OpenCode instructions are native, but the surface is config- and code-driven rather than manifest markdown only."
       },
       skills: {
@@ -7431,7 +7894,8 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       agents: {
         mode: "preserve",
-        nativeSurfaces: ["agents/*.md", "config agent definitions"]
+        nativeSurfaces: ["agents/*.md", "config agent definitions"],
+        notes: "OpenCode agents are first-class native surfaces. Prefer permission-first agent config for new builds; legacy tools remains compatibility input, not the preferred emitted shape."
       },
       hooks: {
         mode: "translate",
@@ -7440,21 +7904,25 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       permissions: {
         mode: "preserve",
-        nativeSurfaces: ["config permission", "per-agent overrides"]
+        nativeSurfaces: ["config permission", "per-agent overrides"],
+        notes: "OpenCode permission is keyed by tool name and patterns, including native skill and task controls. Legacy tools booleans are deprecated in favor of permission."
       },
       runtime: {
         mode: "preserve",
-        nativeSurfaces: ["config mcp", "plugin JS/TS runtime", "scripts/", "assets/"]
+        nativeSurfaces: ["opencode.json", "config mcp", "plugin JS/TS runtime", "scripts/", "assets/"]
       },
       distribution: {
         mode: "translate",
-        nativeSurfaces: ["local plugin dir", "npm package", "plugin JS/TS entrypoint"],
+        nativeSurfaces: [".opencode/plugins/", "~/.config/opencode/plugins/", "opencode.json", "npm package", "plugin JS/TS entrypoint"],
         notes: "Distribution is native, but there is no single shared manifest analog to Claude, Cursor, or Codex."
       }
     },
     sources: PLATFORM_VALIDATION_RULES["opencode"].sources
   }
 };
+function getPlatformRules(platform) {
+  return PLATFORM_VALIDATION_RULES[platform];
+}
 function getCoreFourPrimitiveCapabilities(platform) {
   return CORE_FOUR_PRIMITIVE_CAPABILITIES[platform];
 }
@@ -7520,6 +7988,21 @@ function renderPrimitiveTranslationSummary(summary) {
     lines.push(`  ${row.bucket.padEnd(bucketWidth, " ")}  ${cells.join("  ")}`);
   }
   lines.push("  legend: keep=preserve xlat=translate weak=degrade drop=drop");
+  const detailLines = [];
+  for (const row of summary.rows) {
+    for (const target of summary.targets) {
+      const mode = row.modes[target];
+      if (!mode || mode === "preserve") continue;
+      const capability = getCoreFourPrimitiveCapabilities(target).buckets[row.bucket];
+      const verb = mode === "translate" ? "re-expressed via" : mode === "degrade" ? "weakened to" : "omitted; nearest surface would be";
+      const suffix = capability.notes ? ` ${capability.notes}` : "";
+      detailLines.push(`  - ${row.bucket} on ${TARGET_LABELS[target]}: ${verb} ${capability.nativeSurfaces.join(", ")}.${suffix}`);
+    }
+  }
+  if (detailLines.length > 0) {
+    lines.push("  details:");
+    lines.push(...detailLines);
+  }
   return lines;
 }
 
@@ -7710,16 +8193,27 @@ function lintSkillFile(skillFile, targets, issues, frontmatterCache) {
         platform: "Agent Skills"
       });
     }
-    const expectedDirName = basename3(dirname3(skillFile));
+    const expectedDirName = basename4(dirname3(skillFile));
     const platformsRequiringDirMatch = targets.filter((t2) => PLATFORM_LIMITS[t2].skillNameMustMatchDir);
-    if (platformsRequiringDirMatch.length > 0 && nameField.value !== expectedDirName) {
-      const platformNames = platformsRequiringDirMatch.join(", ");
+    const hardDirMatchPlatforms = platformsRequiringDirMatch.filter((target) => PLATFORM_LIMIT_POLICIES[target].skillNameMustMatchDir.kind === "hard");
+    const advisoryDirMatchPlatforms = platformsRequiringDirMatch.filter((target) => PLATFORM_LIMIT_POLICIES[target].skillNameMustMatchDir.kind !== "hard");
+    if (hardDirMatchPlatforms.length > 0 && nameField.value !== expectedDirName) {
+      const platformNames = hardDirMatchPlatforms.join(", ");
       pushIssue(issues, {
         level: "error",
         code: "skill-name-dir-mismatch",
         message: `Skill name "${nameField.value}" must match directory name "${expectedDirName}" (required by ${platformNames}).`,
         file: skillFile,
-        platform: platformsRequiringDirMatch[0]
+        platform: hardDirMatchPlatforms[0]
+      });
+    } else if (advisoryDirMatchPlatforms.length > 0 && nameField.value !== expectedDirName) {
+      const platformNames = advisoryDirMatchPlatforms.join(", ");
+      pushIssue(issues, {
+        level: "warning",
+        code: "skill-name-dir-guideline",
+        message: `Skill name "${nameField.value}" should match directory name "${expectedDirName}" for ${platformNames} compatibility.`,
+        file: skillFile,
+        platform: advisoryDirMatchPlatforms[0]
       });
     }
     if (!nameField.quoted && needsQuotes(nameField.rawValue)) {
@@ -7744,10 +8238,11 @@ function lintSkillFile(skillFile, targets, issues, frontmatterCache) {
     for (const target of targets) {
       const limits = PLATFORM_LIMITS[target];
       if (limits.skillDescriptionMax !== null && descriptionField.value.length > limits.skillDescriptionMax) {
+        const policy = PLATFORM_LIMIT_POLICIES[target].skillDescriptionMax;
         pushIssue(issues, {
-          level: "error",
-          code: "skill-description-length",
-          message: `Description exceeds ${target} max of ${limits.skillDescriptionMax} characters.`,
+          level: policy?.kind === "hard" ? "error" : "warning",
+          code: policy?.kind === "hard" ? "skill-description-length" : "skill-description-guideline",
+          message: policy?.kind === "hard" ? `Description exceeds ${target} max of ${limits.skillDescriptionMax} characters.` : `Description exceeds the Pluxx ${target} compatibility guideline of ${limits.skillDescriptionMax} characters.`,
           file: skillFile,
           platform: target
         });
@@ -7957,6 +8452,42 @@ function lintMcpUrls(config, issues) {
     }
   }
 }
+function lintMcpRuntimeState(config, issues) {
+  if (!config.mcp) return;
+  const claudeUsesPlatformAuth = config.targets.includes("claude-code") && config.platforms?.["claude-code"]?.mcpAuth === "platform";
+  const cursorUsesPlatformAuth = config.targets.includes("cursor") && config.platforms?.cursor?.mcpAuth === "platform";
+  for (const [serverName, server] of Object.entries(config.mcp)) {
+    if (server.transport === "stdio") {
+      pushIssue(issues, {
+        level: "warning",
+        code: "mcp-stdio-runtime-dependency",
+        message: `MCP server "${serverName}" runs through a local stdio command. End users still need that command and its runtime dependencies available after install.`,
+        file: "pluxx.config.ts",
+        platform: "MCP"
+      });
+    }
+    const runtimeAuthTargets = [];
+    if (server.auth?.type === "platform") {
+      for (const target of config.targets) {
+        if (target === "claude-code" || target === "cursor" || target === "codex" || target === "opencode") {
+          runtimeAuthTargets.push(target);
+        }
+      }
+    } else {
+      if (claudeUsesPlatformAuth) runtimeAuthTargets.push("claude-code");
+      if (cursorUsesPlatformAuth) runtimeAuthTargets.push("cursor");
+    }
+    if (runtimeAuthTargets.length > 0) {
+      pushIssue(issues, {
+        level: "warning",
+        code: "mcp-runtime-auth-external",
+        message: `MCP server "${serverName}" depends on host-managed auth or runtime config on ${runtimeAuthTargets.join(", ")}. Verify the installed bundle in the real host instead of assuming the bundle alone materializes auth.`,
+        file: "pluxx.config.ts",
+        platform: "MCP"
+      });
+    }
+  }
+}
 function lintCodexHookCompatibility(config, issues) {
   if (!isCodexTargetEnabled(config) || !config.hooks) return;
   for (const hookEvent of Object.keys(config.hooks)) {
@@ -7979,10 +8510,11 @@ function lintManifestPromptLimits(config, issues) {
     const prompts = config.brand?.defaultPrompts;
     if (!prompts) continue;
     if (limits.manifestPromptCountMax !== null && prompts.length > limits.manifestPromptCountMax) {
+      const policy = PLATFORM_LIMIT_POLICIES[target].manifestPromptCountMax;
       pushIssue(issues, {
-        level: "error",
-        code: "platform-prompt-count",
-        message: `${target} supports at most ${limits.manifestPromptCountMax} default prompts (found ${prompts.length}).`,
+        level: policy?.kind === "hard" ? "error" : "warning",
+        code: policy?.kind === "hard" ? "platform-prompt-count" : "platform-prompt-count-guideline",
+        message: policy?.kind === "hard" ? `${target} supports at most ${limits.manifestPromptCountMax} default prompts (found ${prompts.length}).` : `Pluxx recommends keeping ${target} default prompts to ${limits.manifestPromptCountMax} or fewer (found ${prompts.length}).`,
         file: "pluxx.config.ts",
         platform: target
       });
@@ -7990,10 +8522,11 @@ function lintManifestPromptLimits(config, issues) {
     if (limits.manifestPromptMax !== null) {
       for (const prompt of prompts) {
         if (prompt.length > limits.manifestPromptMax) {
+          const policy = PLATFORM_LIMIT_POLICIES[target].manifestPromptMax;
           pushIssue(issues, {
-            level: "error",
-            code: "platform-prompt-length",
-            message: `A default prompt exceeds ${target} max of ${limits.manifestPromptMax} characters.`,
+            level: policy?.kind === "hard" ? "error" : "warning",
+            code: policy?.kind === "hard" ? "platform-prompt-length" : "platform-prompt-length-guideline",
+            message: policy?.kind === "hard" ? `A default prompt exceeds ${target} max of ${limits.manifestPromptMax} characters.` : `A default prompt exceeds the Pluxx ${target} compatibility guideline of ${limits.manifestPromptMax} characters.`,
             file: "pluxx.config.ts",
             platform: target
           });
@@ -8183,6 +8716,20 @@ function lintAgentIsolation(agentFiles, issues, frontmatterCache) {
     }
   }
 }
+function lintOpenCodeAgentFrontmatter(dir, config, issues) {
+  if (!config.targets.includes("opencode") || !config.agents) return;
+  const agents = readCanonicalAgentFiles(resolve9(dir, config.agents));
+  for (const agent of agents) {
+    if (!("tools" in agent.frontmatter)) continue;
+    pushIssue(issues, {
+      level: "warning",
+      code: "opencode-agent-tools-deprecated",
+      message: "OpenCode agent `tools` is deprecated. Pluxx will translate legacy agent tools into permission-first OpenCode output where possible, but canonical agents should prefer `permission`.",
+      file: relative6(dir, agent.filePath).replace(/\\/g, "/"),
+      platform: "OpenCode"
+    });
+  }
+}
 function lintAbsolutePaths(config, issues) {
   const absolutePathPattern = /^\/[a-zA-Z]|^[A-Z]:\\/;
   if (config.hooks) {
@@ -8301,46 +8848,152 @@ function lintCursorHooks(config, issues) {
     if (!CURSOR_SUPPORTED_HOOK_EVENTS.includes(hookEvent)) {
       pushIssue(issues, {
         level: "warning",
-        code: "cursor-hook-event-unknown",
-        message: `Cursor does not support hook event "${hookEvent}". Supported: ${CURSOR_SUPPORTED_HOOK_EVENTS.join(", ")}`,
+        code: "cursor-hook-event-unknown",
+        message: `Cursor does not support hook event "${hookEvent}". Supported: ${CURSOR_SUPPORTED_HOOK_EVENTS.join(", ")}`,
+        file: "pluxx.config.ts",
+        platform: "Cursor"
+      });
+    }
+    if (!Array.isArray(hookEntries)) continue;
+    for (const entry of hookEntries) {
+      if (!entry || typeof entry !== "object") continue;
+      const rec = entry;
+      if (rec.loop_limit !== void 0 && !CURSOR_LOOP_LIMIT_HOOK_EVENTS.includes(hookEvent)) {
+        pushIssue(issues, {
+          level: "warning",
+          code: "cursor-hook-loop-limit-unsupported-event",
+          message: `Hook "${hookEvent}" has loop_limit but Cursor only supports loop_limit on ${CURSOR_LOOP_LIMIT_HOOK_EVENTS.join(", ")}.`,
+          file: "pluxx.config.ts",
+          platform: "Cursor"
+        });
+      }
+    }
+  }
+}
+function lintCursorSkillFrontmatter(config, skillFiles, issues, frontmatterCache) {
+  const supportedByTarget = new Map(
+    ["cursor", "codex", "opencode"].filter((target) => config.targets.includes(target)).map((target) => {
+      const rules = getPlatformRules(target);
+      return [target, /* @__PURE__ */ new Set([...rules.frontmatter.standard, ...rules.frontmatter.additional])];
+    })
+  );
+  if (supportedByTarget.size === 0) return;
+  for (const skillFile of skillFiles) {
+    const { parsed } = getParsedFrontmatterFile(skillFile, frontmatterCache);
+    if (!parsed.valid) continue;
+    for (const [key] of parsed.fields) {
+      for (const [target, supported] of supportedByTarget.entries()) {
+        if (supported.has(key)) continue;
+        const issue = target === "cursor" ? {
+          code: "cursor-skill-frontmatter-unsupported",
+          message: `Skill frontmatter field "${key}" is not supported by Cursor. Supported: ${[...supported].join(", ")}`,
+          platform: "Cursor"
+        } : target === "codex" ? {
+          code: "codex-skill-frontmatter-translation",
+          message: `Skill frontmatter field "${key}" is not part of documented Codex skill frontmatter. Pluxx may need to translate that intent through AGENTS.md, .codex/agents/*.toml, permissions companions, or runtime config instead of preserving it on SKILL.md.`,
+          platform: "Codex"
+        } : {
+          code: "opencode-skill-frontmatter-translation",
+          message: `Skill frontmatter field "${key}" is not part of documented OpenCode skill frontmatter. Pluxx may need to translate that intent through commands, agents, opencode.json, or plugin runtime code instead of preserving it on SKILL.md.`,
+          platform: "OpenCode"
+        };
+        pushIssue(issues, {
+          level: "warning",
+          file: skillFile,
+          ...issue
+        });
+      }
+    }
+  }
+}
+function lintHookFieldTranslations(config, issues) {
+  if (!config.hooks) return;
+  const hasPromptHooks = Object.values(config.hooks).some(
+    (entries) => (entries ?? []).some((entry) => entry.type === "prompt")
+  );
+  const hasFailClosed = Object.values(config.hooks).some(
+    (entries) => (entries ?? []).some((entry) => entry.failClosed !== void 0)
+  );
+  const hasLoopLimit = Object.values(config.hooks).some(
+    (entries) => (entries ?? []).some((entry) => entry.loop_limit !== void 0)
+  );
+  if (hasPromptHooks) {
+    if (config.targets.includes("claude-code")) {
+      pushIssue(issues, {
+        level: "warning",
+        code: "claude-prompt-hook-degrade",
+        message: "Prompt hooks are documented in Claude-native hook surfaces, but the current Claude-family generator still drops prompt hooks. Expect a degraded result unless you remodel them as command hooks or host-specific manual work.",
+        file: "pluxx.config.ts",
+        platform: "claude-code"
+      });
+    }
+    if (config.targets.includes("codex")) {
+      pushIssue(issues, {
+        level: "warning",
+        code: "codex-prompt-hook-drop",
+        message: "Codex currently receives only command-hook companions from Pluxx. Prompt hooks will be dropped from the generated Codex bundle.",
+        file: "pluxx.config.ts",
+        platform: "codex"
+      });
+    }
+    if (config.targets.includes("opencode")) {
+      pushIssue(issues, {
+        level: "warning",
+        code: "opencode-prompt-hook-drop",
+        message: "The current OpenCode runtime wrapper only emits command hooks. Prompt hooks will be dropped from the generated OpenCode plugin.",
+        file: "pluxx.config.ts",
+        platform: "opencode"
+      });
+    }
+  }
+  if (hasFailClosed && config.targets.includes("claude-code")) {
+    pushIssue(issues, {
+      level: "warning",
+      code: "claude-hook-failclosed-degrade",
+      message: "Claude hook entries currently drop `failClosed` in generated output. Keep this behavior host-specific or verify the generated hook bundle carefully.",
+      file: "pluxx.config.ts",
+      platform: "claude-code"
+    });
+  }
+  if (hasLoopLimit) {
+    if (config.targets.includes("claude-code")) {
+      pushIssue(issues, {
+        level: "warning",
+        code: "claude-hook-loop-limit-degrade",
+        message: "Claude outputs currently drop `loop_limit`. Recursive hook protection is not preserved there today.",
+        file: "pluxx.config.ts",
+        platform: "claude-code"
+      });
+    }
+    if (config.targets.includes("codex")) {
+      pushIssue(issues, {
+        level: "warning",
+        code: "codex-hook-loop-limit-drop",
+        message: "Codex hook companions currently drop `loop_limit`. Only command, matcher, timeout, and failClosed survive there today.",
         file: "pluxx.config.ts",
-        platform: "Cursor"
+        platform: "codex"
       });
     }
-    if (!Array.isArray(hookEntries)) continue;
-    for (const entry of hookEntries) {
-      if (!entry || typeof entry !== "object") continue;
-      const rec = entry;
-      if (rec.loop_limit !== void 0 && !CURSOR_LOOP_LIMIT_HOOK_EVENTS.includes(hookEvent)) {
-        pushIssue(issues, {
-          level: "warning",
-          code: "cursor-hook-loop-limit-unsupported-event",
-          message: `Hook "${hookEvent}" has loop_limit but Cursor only supports loop_limit on ${CURSOR_LOOP_LIMIT_HOOK_EVENTS.join(", ")}.`,
-          file: "pluxx.config.ts",
-          platform: "Cursor"
-        });
-      }
+    if (config.targets.includes("opencode")) {
+      pushIssue(issues, {
+        level: "warning",
+        code: "opencode-hook-loop-limit-drop",
+        message: "OpenCode runtime hooks currently drop `loop_limit`. Recursive hook protection is still Cursor-first in Pluxx.",
+        file: "pluxx.config.ts",
+        platform: "opencode"
+      });
     }
   }
 }
-function lintCursorSkillFrontmatter(config, skillFiles, issues, frontmatterCache) {
-  if (!config.targets.includes("cursor")) return;
-  const cursorSupportedFrontmatter = ["name", "description", "license", "compatibility", "metadata", "disable-model-invocation"];
-  for (const skillFile of skillFiles) {
-    const { parsed } = getParsedFrontmatterFile(skillFile, frontmatterCache);
-    if (!parsed.valid) continue;
-    for (const [key] of parsed.fields) {
-      if (!cursorSupportedFrontmatter.includes(key)) {
-        pushIssue(issues, {
-          level: "warning",
-          code: "cursor-skill-frontmatter-unsupported",
-          message: `Skill frontmatter field "${key}" is not supported by Cursor. Supported: ${cursorSupportedFrontmatter.join(", ")}`,
-          file: skillFile,
-          platform: "Cursor"
-        });
-      }
-    }
-  }
+function lintCodexCommandGuidance(config, issues) {
+  if (!config.targets.includes("codex") || !config.commands) return;
+  pushIssue(issues, {
+    level: "warning",
+    code: "codex-commands-routing-guidance",
+    message: "Codex does not currently document plugin-packaged slash-command parity. Pluxx will degrade commands into skills plus AGENTS.md and `.codex/commands.generated.json` routing guidance.",
+    file: "pluxx.config.ts",
+    platform: "codex"
+  });
 }
 function lintSkillListingBudgets(skillFiles, targets, issues, frontmatterCache) {
   for (const target of targets) {
@@ -8428,12 +9081,12 @@ function lintPermissions(config, issues) {
     });
   }
   if (rules.some((rule) => rule.kind === "Skill")) {
-    const nonClaudeTargets = config.targets.filter((target) => target !== "claude-code");
-    if (nonClaudeTargets.length > 0) {
+    const limitedTargets = config.targets.filter((target) => !["claude-code", "codex", "opencode"].includes(target));
+    if (limitedTargets.length > 0) {
       pushIssue(issues, {
         level: "warning",
         code: "permissions-skill-selector-limited",
-        message: `Skill(...) permission rules are Claude-style and will require downgrade or docs-only handling on ${nonClaudeTargets.join(", ")}.`,
+        message: `Skill(...) permission rules do not have the same native support on ${limitedTargets.join(", ")} and will require downgrade or translation there.`,
         file: "pluxx.config.ts",
         platform: "Permissions"
       });
@@ -8443,7 +9096,7 @@ function lintPermissions(config, issues) {
     pushIssue(issues, {
       level: "warning",
       code: "permissions-opencode-downgrade",
-      message: "OpenCode permission output is currently tool-level. Selector patterns like file globs and specific MCP tool names are downgraded to coarse tool permissions there.",
+      message: "OpenCode now preserves most canonical permission selectors natively, but MCP(...) rules still translate through OpenCode tool-name patterns and should be verified against the configured MCP server names.",
       file: "pluxx.config.ts",
       platform: "OpenCode"
     });
@@ -8513,11 +9166,13 @@ async function lintProject(dir = process.cwd(), options = {}) {
   lintSettingsJson(dir, issues);
   lintLegacyCommandsDir(dir, lintConfig, issues);
   lintHookEvents(lintConfig, issues);
-  const agentsDir = resolve9(dir, "agents");
+  const agentsDir = resolve9(dir, lintConfig.agents ?? "agents");
   const agentFiles = existsSync17(agentsDir) ? collectMarkdownFiles(agentsDir) : [];
   lintAgentFrontmatter(agentFiles, issues, frontmatterCache);
   lintAgentIsolation(agentFiles, issues, frontmatterCache);
+  lintOpenCodeAgentFrontmatter(dir, { ...lintConfig, agents: lintConfig.agents ?? "./agents/" }, issues);
   lintMcpUrls(lintConfig, issues);
+  lintMcpRuntimeState(lintConfig, issues);
   lintBrandMetadata(lintConfig, issues);
   lintCodexOverrides(lintConfig, issues);
   lintCodexHookCompatibility(lintConfig, issues);
@@ -8525,6 +9180,8 @@ async function lintProject(dir = process.cwd(), options = {}) {
   lintCodexHooksExternalConfig(lintConfig, issues);
   lintPermissions(lintConfig, issues);
   lintPrimitiveTranslations(lintConfig, issues);
+  lintHookFieldTranslations(lintConfig, issues);
+  lintCodexCommandGuidance(lintConfig, issues);
   lintCursorHooks(lintConfig, issues);
   lintCursorRuleContentLimits(lintConfig, issues);
   const skillsDir = resolve9(dir, lintConfig.skills);
@@ -8608,7 +9265,7 @@ import { resolve as resolve11 } from "path";
 
 // src/cli/init-from-mcp.ts
 import { mkdir as mkdir2 } from "fs/promises";
-import { basename as basename4, resolve as resolve10 } from "path";
+import { basename as basename5, resolve as resolve10 } from "path";
 
 // src/user-config.ts
 var ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -9188,7 +9845,7 @@ function buildCommandContent(skill, existingContent) {
   const generatedContent = [
     "---",
     `description: ${JSON.stringify(description)}`,
-    `argument-hint: ${JSON.stringify(argumentHint)}`,
+    `argument-hint: ${formatArgumentHintFrontmatter(argumentHint)}`,
     "---",
     "",
     entryBlurb,
@@ -9225,6 +9882,14 @@ function buildCommandContent(skill, existingContent) {
     }
   );
 }
+function formatArgumentHintFrontmatter(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return '""';
+  if (trimmed.includes("\n") || /(^#)|(\s#)/.test(trimmed)) {
+    return JSON.stringify(trimmed);
+  }
+  return trimmed;
+}
 function buildInstructionsContent(input) {
   const accessLine = describePluginAccess(input.displayName, input.source, input.runtimeAuthMode ?? "inline");
   const lines = [
@@ -10334,7 +10999,7 @@ function derivePluginName(introspection, source) {
   const candidates = [
     introspection.serverInfo.name,
     introspection.serverInfo.title,
-    source.transport === "stdio" ? basename4(source.command) : new URL(source.url).hostname.split(".")[0]
+    source.transport === "stdio" ? basename5(source.command) : new URL(source.url).hostname.split(".")[0]
   ].filter((value) => Boolean(value));
   for (const candidate of candidates) {
     const normalized = toKebabCase(candidate);
@@ -10855,7 +11520,7 @@ function printTestResult(result) {
 }
 
 // src/cli/sync-from-mcp.ts
-import { cpSync as cpSync2, existsSync as existsSync20, mkdtempSync, readFileSync as readFileSync8, rmSync as rmSync2, readdirSync as readdirSync6, rmdirSync, writeFileSync as writeFileSync2 } from "fs";
+import { cpSync as cpSync2, existsSync as existsSync20, mkdtempSync, readFileSync as readFileSync8, rmSync as rmSync2, readdirSync as readdirSync6, rmdirSync, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname4, isAbsolute, relative as relative7, resolve as resolve13 } from "path";
 import { tmpdir } from "os";
 
@@ -11138,10 +11803,10 @@ async function createSseClient(server) {
   let resolveEndpoint;
   let rejectEndpoint;
   let endpointSettled = false;
-  const endpointReady = new Promise((resolve23, reject) => {
+  const endpointReady = new Promise((resolve24, reject) => {
     resolveEndpoint = (value) => {
       endpointSettled = true;
-      resolve23(value);
+      resolve24(value);
     };
     rejectEndpoint = (error) => {
       endpointSettled = true;
@@ -11278,7 +11943,7 @@ async function createSseClient(server) {
     async request(method, params) {
       const requestId = nextRequestId();
       const endpoint = endpointUrl ?? await endpointReady;
-      const resultPromise = new Promise((resolve23, reject) => {
+      const resultPromise = new Promise((resolve24, reject) => {
         const timeout = setTimeout(() => {
           pending.delete(requestId);
           reject(new McpIntrospectionError(`Timed out waiting for MCP SSE response to ${method}.`));
@@ -11286,7 +11951,7 @@ async function createSseClient(server) {
         pending.set(requestId, {
           resolve: (value) => {
             clearTimeout(timeout);
-            resolve23(value);
+            resolve24(value);
           },
           reject: (error) => {
             clearTimeout(timeout);
@@ -11439,7 +12104,7 @@ async function createStdioClient(server) {
         method,
         ...params ? { params } : {}
       });
-      return new Promise((resolve23, reject) => {
+      return new Promise((resolve24, reject) => {
         const timeout = setTimeout(() => {
           pending.delete(id);
           reject(new McpIntrospectionError(`Timed out waiting for MCP stdio response to ${method}.`));
@@ -11447,7 +12112,7 @@ async function createStdioClient(server) {
         pending.set(id, {
           resolve: (value) => {
             clearTimeout(timeout);
-            resolve23(value);
+            resolve24(value);
           },
           reject: (error) => {
             clearTimeout(timeout);
@@ -11670,7 +12335,7 @@ async function syncFromMcp(options) {
     if (!existsSync20(newSkillPath)) continue;
     const currentContent = readFileSync8(newSkillPath, "utf-8");
     const updatedContent = injectCustomContent(currentContent, extracted.customContent);
-    writeFileSync2(newSkillPath, updatedContent, "utf-8");
+    writeFileSync3(newSkillPath, updatedContent, "utf-8");
   }
   const renamedFiles = [];
   const renamedOldDirs = /* @__PURE__ */ new Set();
@@ -11754,7 +12419,7 @@ async function applyPersistedTaxonomy(rootDir) {
   const instructionsPath = "./INSTRUCTIONS.md";
   const previousInstructions = beforeContents.get(instructionsPath);
   if (previousInstructions !== void 0) {
-    writeFileSync2(resolveWithinRoot(rootDir, instructionsPath), previousInstructions, "utf-8");
+    writeFileSync3(resolveWithinRoot(rootDir, instructionsPath), previousInstructions, "utf-8");
   }
   const newMetadataPath = resolveWithinRoot(rootDir, MCP_SCAFFOLD_METADATA_PATH);
   const newMetadata = JSON.parse(readFileSync8(newMetadataPath, "utf-8"));
@@ -11779,7 +12444,7 @@ async function applyPersistedTaxonomy(rootDir) {
   }
   for (const file of afterManaged) {
     if (file === instructionsPath && previousInstructions !== void 0) {
-      writeFileSync2(resolveWithinRoot(rootDir, file), previousInstructions, "utf-8");
+      writeFileSync3(resolveWithinRoot(rootDir, file), previousInstructions, "utf-8");
     }
   }
   invalidateSavedAgentPack(rootDir);
@@ -11820,7 +12485,7 @@ function preserveCustomContentForRenames(rootDir, renames, pathForName) {
     if (!existsSync20(newPath)) continue;
     const currentContent = readFileSync8(newPath, "utf-8");
     const updatedContent = injectCustomContent(currentContent, extracted.customContent);
-    writeFileSync2(newPath, updatedContent, "utf-8");
+    writeFileSync3(newPath, updatedContent, "utf-8");
   }
 }
 function snapshotManagedFiles(rootDir, files) {
@@ -13073,6 +13738,9 @@ function scoreFirecrawlMappedLink(link, kind) {
   const url = link.url.toLowerCase();
   const text = [link.title, link.description, link.url].filter(Boolean).join(" ").toLowerCase();
   let score = 0;
+  if (url.endsWith(".xml") || text.includes("sitemap")) {
+    return -100;
+  }
   if (kind === "docs") {
     if (url.includes("/mcp")) score += 50;
     if (url.includes("quickstart") || url.includes("get-started")) score += 35;
@@ -13221,9 +13889,9 @@ function buildDocsContextArtifact(sources) {
   const remoteSources = sources.filter((source) => source.status === "ok" && (source.kind === "website" || source.kind === "docs"));
   if (remoteSources.length === 0) return void 0;
   const productName = inferProductName(remoteSources);
-  const shortDescription = remoteSources.map((source) => source.description ?? source.paragraphs?.[0]).find((value) => Boolean(value && value.trim()));
-  const setupHints = collectHintSentences(remoteSources, ["setup", "install", "get started", "quickstart", "configuration", "configuring", "running", "restart", "onlymaincontent", "main content"]);
-  const authHints = collectHintSentences(remoteSources, ["auth", "authentication", "api key", "bearer", "header", "token", "credential"]);
+  const shortDescription = dedupeRepeatedSentences(remoteSources.map((source) => source.description ?? source.paragraphs?.[0]).find((value) => Boolean(value && value.trim())));
+  const setupHints = collectHintSentences(remoteSources, ["setup", "install", "get started", "quickstart", "configuration", "configuring", "running", "restart", "onlymaincontent", "main content", "npx", "npm", "curl", "remote hosted url"]);
+  const authHints = collectHintSentences(remoteSources, ["auth", "authentication", "api key", "api_key", "firecrawl_api_key", "bearer", "header", "token", "credential"]);
   const warnings = collectHintSentences(remoteSources, ["warning", "note", "requires", "must", "if you", "unavailable", "couldn"]);
   const workflowHints = collectWorkflowHints(remoteSources);
   const importantTerms = collectImportantTerms(remoteSources);
@@ -13297,8 +13965,19 @@ function truncateForNote(value, maxLength) {
 }
 function summarizeMarkdownArtifact(content, metadata = {}) {
   const cleaned = content.replace(/\r\n/g, "\n");
-  const headings = cleaned.split("\n").map((line) => line.match(/^#{1,3}\s+(.+)$/)?.[1]?.trim()).filter((value) => Boolean(value)).map(stripMarkdownFormatting).filter(Boolean).slice(0, 5);
-  const paragraphs = cleaned.split(/\n{2,}/).map((chunk) => stripMarkdownFormatting(chunk)).map((chunk) => chunk.replace(/\s+/g, " ").trim()).filter((chunk) => Boolean(chunk) && !chunk.startsWith("#")).slice(0, 3);
+  const headings = cleaned.split("\n").map((line) => line.match(/^#{1,4}\s+(.+)$/)?.[1]?.trim()).filter((value) => Boolean(value)).map(stripMarkdownFormatting).filter((value) => Boolean(value) && !isLikelyChromeHeading(value)).slice(0, 12);
+  const textChunks = cleaned.split(/\n{2,}/).map((chunk) => stripMarkdownFormatting(chunk)).map((chunk) => chunk.replace(/\s+/g, " ").trim()).filter((chunk) => Boolean(chunk) && !chunk.startsWith("#"));
+  const filteredTextChunks = filterLikelyContentText(textChunks);
+  const codeHints = extractMarkdownCodeHints(cleaned);
+  const paragraphCandidates = uniqueStrings([
+    ...filteredTextChunks,
+    ...codeHints
+  ]);
+  const paragraphs = paragraphCandidates.map((chunk, index) => ({
+    chunk,
+    score: scoreMarkdownTextChunk(chunk),
+    index
+  })).sort((left, right) => right.score - left.score || left.index - right.index).map(({ chunk }) => chunk).slice(0, 5);
   const title = metadata.title?.trim() || headings[0] || paragraphs[0];
   const description = metadata.description?.trim() || paragraphs[0];
   const lines = [];
@@ -13325,6 +14004,42 @@ function summarizeMarkdownArtifact(content, metadata = {}) {
 function stripMarkdownFormatting(value) {
   return value.replace(/```[\s\S]*?```/g, " ").replace(/`([^`]+)`/g, "$1").replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/^>\s*/gm, "").replace(/^\s*[-*+]\s+/gm, "").replace(/^\s*\d+\.\s+/gm, "").replace(/[_*~#]+/g, " ").replace(/\|/g, " ").replace(/\s+/g, " ").trim();
 }
+function extractMarkdownCodeHints(content) {
+  const hints = [];
+  for (const match of content.matchAll(/```[^\n]*\n([\s\S]*?)```/g)) {
+    const block = match[1] ?? "";
+    for (const rawLine of block.split("\n")) {
+      const line = rawLine.replace(/\r/g, "").trim();
+      if (!line) continue;
+      if (!/(api[_-]?key|token|header|auth|install|npx|npm|curl|onlymaincontent|main content|map|scrape|crawl|extract|search|agent|command|url|mcp)/i.test(line)) {
+        continue;
+      }
+      const normalized = line.replace(/^[`"'[{(]+|[`"'[\]}):,;]+$/g, "").replace(/\s+/g, " ").trim();
+      if (normalized) {
+        hints.push(normalized);
+      }
+    }
+  }
+  return uniqueStrings(hints).slice(0, 10);
+}
+function scoreMarkdownTextChunk(value) {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (!normalized) return Number.NEGATIVE_INFINITY;
+  if (isLikelyChromeText(normalized)) return -200;
+  const lower = normalized.toLowerCase();
+  let score = 0;
+  if (/[.!?:]/.test(normalized)) score += 20;
+  if (/`|https?:\/\/|(^| )npx( |$)|(^| )npm( |$)|(^| )curl( |$)|=/.test(normalized)) score += 20;
+  if (lower.includes("search") || lower.includes("scrape") || lower.includes("map") || lower.includes("crawl") || lower.includes("extract") || lower.includes("agent") || lower.includes("browser") || lower.includes("workflow") || lower.includes("knowledge")) {
+    score += 25;
+  }
+  if (lower.includes("api key") || lower.includes("firecrawl_api_key") || lower.includes("token") || lower.includes("auth") || lower.includes("header") || lower.includes("install") || lower.includes("quickstart") || lower.includes("configuration") || lower.includes("onlymaincontent") || lower.includes("main content") || lower.includes("remote hosted url")) {
+    score += 25;
+  }
+  if (normalized.length >= 24 && normalized.length <= 240) score += 10;
+  if (normalized.split(/\s+/).length > 40) score -= 10;
+  return score;
+}
 function summarizeHtml(html) {
   const cleanedHtml = stripNonContentHtml(html);
   const primaryHtml = selectPrimaryHtmlFragment(cleanedHtml);
@@ -13394,14 +14109,38 @@ function filterLikelyContentText(values) {
   }
   return uniqueStrings(values).map((value) => value.replace(/\s+/g, " ").trim()).filter((value) => value.length > 0);
 }
+function dedupeRepeatedSentences(value) {
+  if (!value) return void 0;
+  const normalized = value.replace(/\s+/g, " ").replace(/([.!?])\s*,\s*/g, "$1 ").trim();
+  if (!normalized) return void 0;
+  const sentenceMatches = normalized.match(/[^.!?]+[.!?]?/g);
+  if (!sentenceMatches) return normalized;
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueSentences = [];
+  for (const rawSentence of sentenceMatches) {
+    const sentence = rawSentence.trim().replace(/^,+\s*/, "");
+    if (!sentence) continue;
+    const key = sentence.replace(/[.!?]+$/, "").replace(/\s+/g, " ").trim().toLowerCase();
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    uniqueSentences.push(sentence);
+  }
+  if (uniqueSentences.length === 0) {
+    return normalized;
+  }
+  return uniqueSentences.join(" ");
+}
 function isLikelyChromeHeading(value) {
   const normalized = value.replace(/\s+/g, " ").trim();
   if (!normalized) return true;
   const lower = normalized.toLowerCase();
   const chromePatterns = [
     "search docs",
+    "skip to main content",
     "table of contents",
     "on this page",
+    "navigation",
+    "ctrl k",
     "previous",
     "next",
     "privacy",
@@ -13411,6 +14150,8 @@ function isLikelyChromeHeading(value) {
     "blog",
     "pricing",
     "careers",
+    "playground",
+    "community",
     "discord",
     "github",
     "twitter",
@@ -13426,8 +14167,11 @@ function isLikelyChromeText(value) {
   const wordCount = normalized.split(/\s+/).length;
   const chromePatterns = [
     "search docs",
+    "skip to main content",
     "table of contents",
     "on this page",
+    "navigation",
+    "ctrl k",
     "previous",
     "next",
     "privacy",
@@ -13437,6 +14181,8 @@ function isLikelyChromeText(value) {
     "blog",
     "pricing",
     "careers",
+    "playground",
+    "community",
     "discord",
     "github",
     "twitter",
@@ -13563,11 +14309,11 @@ function normalizeProductNameCandidate(value) {
 function collectHintSentences(sources, keywords) {
   const sentences = uniqueStrings(
     sources.flatMap((source) => {
-      const text = [
-        source.description,
-        ...source.paragraphs ?? []
-      ].filter(Boolean).join(" ");
-      return splitIntoSentences(text).filter((sentence) => keywords.some((keyword) => sentence.toLowerCase().includes(keyword))).slice(0, 4);
+      const segments = [
+        ...source.description ? splitIntoHintSegments(source.description) : [],
+        ...(source.paragraphs ?? []).flatMap(splitIntoHintSegments)
+      ];
+      return segments.filter((sentence) => keywords.some((keyword) => sentence.toLowerCase().includes(keyword))).slice(0, 6);
     })
   );
   return sentences.slice(0, 6);
@@ -13579,16 +14325,50 @@ function collectWorkflowHints(sources) {
     "manual installation",
     "configuration",
     "environment variables",
+    "remote hosted url",
+    "available tools",
     "features",
     "get started",
     "overview",
     "developer guides",
     "quickstarts",
-    "mcp server"
+    "mcp server",
+    "ready to build?",
+    "ready to build",
+    "use well-known tools",
+    "code you can trust",
+    "frequently asked questions"
   ]);
-  return uniqueStrings(
+  const workflowKeywords = ["search", "scrape", "map", "crawl", "extract", "agent", "browser", "workflow", "knowledge"];
+  const workflowStopKeywords = ["install", "auth", "token", "header", "configuration", "quickstart"];
+  const sourceTitles = new Set(
+    sources.flatMap((source) => source.title ? [source.title.toLowerCase()] : []).filter(Boolean)
+  );
+  const headingHints = uniqueStrings(
     sources.flatMap((source) => source.headings ?? [])
-  ).map((heading) => heading.replace(/\s+/g, " ").trim()).filter((heading) => heading.length > 0 && heading.split(/\s+/).length <= 4 && !genericHeadings.has(heading.toLowerCase())).slice(0, 8);
+  ).map(normalizeHintText).filter(
+    (heading) => heading.length > 0 && heading.split(/\s+/).length <= 4 && !genericHeadings.has(heading.toLowerCase()) && (!sourceTitles.has(heading.toLowerCase()) || workflowKeywords.some((keyword) => containsWholeWordKeyword(heading, keyword))) && !heading.includes("://")
+  ).map((heading, index) => ({
+    value: heading,
+    index,
+    score: scoreWorkflowHint(heading, workflowKeywords)
+  })).filter((entry) => entry.score > 0).sort((left, right) => right.score - left.score || left.index - right.index).map((entry) => entry.value);
+  const paragraphHints = uniqueStrings(
+    sources.flatMap(
+      (source) => (source.paragraphs ?? []).flatMap(splitIntoHintSegments).filter((segment) => {
+        const lower = segment.toLowerCase();
+        return workflowKeywords.some((keyword) => containsWholeWordKeyword(lower, keyword)) && !workflowStopKeywords.some((keyword) => lower.includes(keyword)) && !segment.includes("://") && !segment.includes("=");
+      })
+    )
+  ).map(normalizeHintText).map((segment, index) => ({
+    value: segment,
+    index,
+    score: scoreWorkflowHint(segment, workflowKeywords)
+  })).filter((entry) => entry.score > 0).sort((left, right) => right.score - left.score || left.index - right.index).map((entry) => entry.value);
+  return uniqueStrings([
+    ...headingHints,
+    ...paragraphHints
+  ]).slice(0, 8);
 }
 function collectImportantTerms(sources) {
   return uniqueStrings(
@@ -13598,8 +14378,34 @@ function collectImportantTerms(sources) {
     ])
   ).map((term) => term.replace(/\s+/g, " ").trim()).filter((term) => term.length > 0 && term.split(/\s+/).length <= 4).slice(0, 8);
 }
-function splitIntoSentences(value) {
-  return value.split(/(?<=[.!?])\s+/).map((sentence) => sentence.replace(/\s+/g, " ").trim()).filter(Boolean);
+function splitIntoHintSegments(value) {
+  return value.split(/(?<=[.!?])\s+|\n+/).map(normalizeHintText).filter(Boolean);
+}
+function normalizeHintText(value) {
+  return value.replace(/[\u200B-\u200D\uFEFF]/g, " ").replace(/^(?:hashtag\s+)+/gi, "").replace(/^(?:[#>*-]+\s*)+/, "").replace(/[\\]+/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[`*_]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function scoreWorkflowHint(value, workflowKeywords) {
+  const normalized = normalizeHintText(value);
+  const lower = normalized.toLowerCase();
+  let score = 0;
+  for (const keyword of workflowKeywords) {
+    if (containsWholeWordKeyword(lower, keyword)) {
+      score += 30;
+    } else if (lower.includes(keyword)) {
+      score += 10;
+    }
+  }
+  if (lower.includes("feature") || lower.includes("ready to build") || lower.includes("faq") || lower.includes("question")) {
+    score -= 20;
+  }
+  if (normalized.split(/\s+/).length <= 3) {
+    score += 5;
+  }
+  return score;
+}
+function containsWholeWordKeyword(value, keyword) {
+  const pattern = new RegExp(`\\b${keyword.replace(/\s+/g, "\\s+")}\\b`, "i");
+  return pattern.test(value);
 }
 function uniqueStrings(values) {
   return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
@@ -13656,17 +14462,22 @@ function buildAgentPrompt(kind, input) {
 2. Infer the MCP's real product surfaces and workflows from tools, resources, resource templates, and prompt templates.
 3. Merge, split, or rename generated skills so labels are product-facing, not lexical buckets.
 4. Update the taxonomy file first; Pluxx will re-render generated skills and commands from that taxonomy after the pass.
-5. Keep setup/onboarding, account-admin, and runtime workflows intentionally separated when appropriate.
-6. Eliminate misleading labels such as contact or people discovery when the tools do not actually perform direct lookup.
-7. Use per-skill related resources and prompt templates as strong evidence for workflow shape, but correct them when broader discovery evidence shows a mismatch.
-8. Reject stale scaffold assumptions; if current files conflict with discovery context, prefer the discovery evidence and flag the mismatch.
+5. Promote clear, repeated user entrypoints into explicit commands when host-native command UX would be clearer than asking users to infer the right skill.
+6. Promote specialist, delegated, reviewer, or bounded-execution workflows into agents/subagents when isolation is a better native fit than another inline skill.
+7. Keep setup/onboarding, account-admin, and runtime workflows intentionally separated when appropriate.
+8. Eliminate misleading labels such as contact or people discovery when the tools do not actually perform direct lookup.
+9. Use per-skill related resources and prompt templates as strong evidence for workflow shape, but correct them when broader discovery evidence shows a mismatch.
+10. When prompt templates or tool schemas imply a parameterized workflow, preserve that intent through realistic arguments, argument-bearing commands, and runnable entrypoints instead of flattening everything into generic skills.
+11. Reject stale scaffold assumptions; if current files conflict with discovery context, prefer the discovery evidence and flag the mismatch.
+12. Do not settle for a least-common-denominator skill-only scaffold if the product would be more native with commands, agents, or richer argument shapes.
 ${buildPromptOverrideBlock(kind, input.overrides)}
 Success criteria:
 - each skill represents a real user workflow or product surface
 - skill names are product-shaped and avoid raw MCP tool/server identifiers when possible
 - setup/onboarding, account-admin, and runtime workflows are grouped intentionally
 - singleton skills are avoided unless they represent a real standalone user workflow
-- commands stay aligned with the chosen taxonomy and avoid weak command UX
+- commands stay aligned with the chosen taxonomy, avoid weak command UX, and use realistic arguments when workflows are parameterized
+- specialist or delegated workflows are promoted into agents/subagents when that native shape is stronger than another flat skill
 - per-skill resource and prompt-template associations remain coherent with the chosen taxonomy
 - taxonomy decisions are grounded in current discovery context, not stale scaffold assumptions
 `;
@@ -13679,7 +14490,9 @@ Success criteria:
 4. Keep wording aligned to the MCP's product narrative and branded language; avoid raw MCP server/tool identifiers except when technically required.
 5. Prefer the branded product name in user-facing copy; do not lead with internal MCP server identifiers.
 6. Replace stale scaffold claims with current discovery-backed language and keep command examples operational, concrete, and copy-paste runnable.
-7. When a workflow already has related resources or prompt templates in the context, keep the wording and examples aligned to that surfaced workflow evidence.
+7. When discovery implies a parameterized workflow, make the examples show realistic arguments instead of bare placeholder commands.
+8. Call out when a request should route to a specialist agent/subagent instead of the generic skill path.
+9. When a workflow already has related resources or prompt templates in the context, keep the wording and examples aligned to that surfaced workflow evidence.
 ${buildPromptOverrideBlock(kind, input.overrides)}
 Success criteria:
 - instructions are concise, actionable, and product-shaped
@@ -13688,20 +14501,21 @@ Success criteria:
 - raw MCP server identifiers are omitted unless operationally necessary
 - the generated section reads like routing guidance, not pasted vendor docs
 - command examples use strong command UX (clear intent, realistic args, and runnable shapes)
+- specialist routing is explicit when certain work should go to an agent/subagent instead of a generic skill
 - workflow guidance stays coherent with related resource and prompt-template evidence in the context
 - the file remains safe for future \`pluxx sync --from-mcp\`
 `;
   }
   return `${sharedIntro.join("\n")}Your job:
 1. Review the current scaffold critically.
-2. Call out weak skill groupings, missing setup guidance, vague examples, product/category mismatches, raw documentation dumps, lexical skill names, stale scaffold assumptions, weak command UX${input.sourceKind === "mcp-derived" ? ", incoherent per-skill resource/prompt associations, or weak MCP metadata signals" : ", weak marketplace/listing copy, awkward installation guidance, or unclear operator boundaries"}.
+2. Call out weak skill groupings, missing setup guidance, vague examples, product/category mismatches, raw documentation dumps, lexical skill names, stale scaffold assumptions, weak command UX, missing argument-bearing command entrypoints, missing specialist agent/subagent boundaries, lowest-common-denominator skill-only scaffolds, and misplaced Claude-only skill-frontmatter intent${input.sourceKind === "mcp-derived" ? ", incoherent per-skill resource/prompt associations, or weak MCP metadata signals" : ", weak marketplace/listing copy, awkward installation guidance, or unclear operator boundaries"}.
 3. Separate scaffold quality findings from runtime-correctness findings.
 4. Propose only the highest-value changes needed to make the scaffold useful.
 ${buildPromptOverrideBlock(kind, input.overrides)}
 Success criteria:
 - findings are concrete and tied to files
 - scaffold quality gaps are distinguished from runtime correctness
-- stale assumptions${input.sourceKind === "mcp-derived" ? ", incoherent per-skill discovery associations," : ","} and command-UX weaknesses are identified explicitly when present
+- stale assumptions${input.sourceKind === "mcp-derived" ? ", incoherent per-skill discovery associations," : ","} command-UX weaknesses, and missing agent/subagent shaping are identified explicitly when present
 - suggested changes improve user-facing plugin quality
 - recommendations stay inside Pluxx-managed boundaries
 `;
@@ -14306,11 +15120,11 @@ ${additions.map((block) => `- ${block.replace(/\n/g, "\n  ")}`).join("\n")}
 
 // src/cli/doctor.ts
 import { accessSync, constants, existsSync as existsSync23, lstatSync, readFileSync as readFileSync11, readdirSync as readdirSync9 } from "fs";
-import { basename as basename5, dirname as dirname6, resolve as resolve16 } from "path";
+import { basename as basename6, dirname as dirname6, resolve as resolve16 } from "path";
 
 // src/cli/install.ts
 import { resolve as resolve15, dirname as dirname5 } from "path";
-import { existsSync as existsSync22, symlinkSync, mkdirSync as mkdirSync3, rmSync as rmSync3, readFileSync as readFileSync10, writeFileSync as writeFileSync3, cpSync as cpSync3, readdirSync as readdirSync8 } from "fs";
+import { existsSync as existsSync22, symlinkSync, mkdirSync as mkdirSync4, rmSync as rmSync3, readFileSync as readFileSync10, writeFileSync as writeFileSync4, cpSync as cpSync3, readdirSync as readdirSync8 } from "fs";
 import { spawnSync } from "child_process";
 import * as readline2 from "readline";
 function listHookCommands(hooks) {
@@ -14476,7 +15290,7 @@ function getInstallTargets(pluginName) {
     {
       platform: "opencode",
       pluginDir: resolve15(home, ".config/opencode/plugins", pluginName),
-      description: `~/.config/opencode/plugins/${pluginName}.ts`
+      description: `~/.config/opencode/plugins/${pluginName}.ts + ~/.config/opencode/plugins/${pluginName}/`
     },
     {
       platform: "github-copilot",
@@ -14524,7 +15338,7 @@ function toPascalCase2(value) {
 function writeOpenCodeEntryFile(pluginDir, pluginName) {
   const entryPath = getOpenCodeEntryPath(pluginDir);
   const exportName = toPascalCase2(pluginName);
-  writeFileSync3(
+  writeFileSync4(
     entryPath,
     [
       'import type { Plugin } from "@opencode-ai/plugin"',
@@ -14580,7 +15394,7 @@ ${content.slice(frontmatterMatch[0].length)}`;
 function syncOpenCodeSkills(pluginDir, pluginName) {
   const sourceSkillsDir = resolve15(pluginDir, "skills");
   if (!existsSync22(sourceSkillsDir)) return;
-  mkdirSync3(getOpenCodeSkillRoot(), { recursive: true });
+  mkdirSync4(getOpenCodeSkillRoot(), { recursive: true });
   for (const entry of readdirSync8(sourceSkillsDir, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
     const skillSourceDir = resolve15(sourceSkillsDir, entry.name);
@@ -14589,7 +15403,7 @@ function syncOpenCodeSkills(pluginDir, pluginName) {
     rmSync3(installedSkillDir, { recursive: true, force: true });
     cpSync3(skillSourceDir, installedSkillDir, { recursive: true });
     const skillPath = resolve15(installedSkillDir, "SKILL.md");
-    writeFileSync3(
+    writeFileSync4(
       skillPath,
       namespaceOpenCodeSkill(readFileSync10(skillPath, "utf-8"), pluginName, entry.name)
     );
@@ -14641,6 +15455,15 @@ function getInstallFollowupNotes(platforms) {
   if (platforms.includes("claude-code")) {
     notes.push("Claude Code note: if Claude is already open, run /reload-plugins in the session to pick up the new install.");
   }
+  if (platforms.includes("cursor")) {
+    notes.push("Cursor note: if Cursor is already open, use Developer: Reload Window or restart Cursor to pick up the new install.");
+  }
+  if (platforms.includes("codex")) {
+    notes.push("Codex note: if Codex is already open, use Plugins > Refresh if that action is available in your current UI, or restart Codex to pick up the new install.");
+  }
+  if (platforms.includes("opencode")) {
+    notes.push("OpenCode note: if OpenCode is already open, restart or reload it so the plugin is picked up.");
+  }
   return notes;
 }
 function runCommandDefault(command2, args2) {
@@ -14653,7 +15476,7 @@ function runCommandDefault(command2, args2) {
 }
 function createSymlinkInstall(target) {
   const parentDir = resolve15(target.pluginDir, "..");
-  mkdirSync3(parentDir, { recursive: true });
+  mkdirSync4(parentDir, { recursive: true });
   if (existsSync22(target.pluginDir)) {
     rmSync3(target.pluginDir, { recursive: true, force: true });
   }
@@ -14691,7 +15514,7 @@ function readCodexMarketplace(filepath) {
 }
 function ensureCodexMarketplace(pluginName) {
   const filepath = getCodexMarketplacePath();
-  mkdirSync3(dirname5(filepath), { recursive: true });
+  mkdirSync4(dirname5(filepath), { recursive: true });
   const marketplace = readCodexMarketplace(filepath);
   const nextPlugins = (marketplace.plugins ?? []).filter((plugin) => plugin.name !== pluginName);
   nextPlugins.push({
@@ -14706,7 +15529,7 @@ function ensureCodexMarketplace(pluginName) {
     },
     category: "Productivity"
   });
-  writeFileSync3(
+  writeFileSync4(
     filepath,
     JSON.stringify({
       name: marketplace.name ?? "pluxx-local",
@@ -14727,7 +15550,7 @@ function removeCodexMarketplacePlugin(pluginName) {
     rmSync3(filepath, { force: true });
     return;
   }
-  writeFileSync3(
+  writeFileSync4(
     filepath,
     JSON.stringify({
       name: marketplace.name ?? "pluxx-local",
@@ -14738,7 +15561,7 @@ function removeCodexMarketplacePlugin(pluginName) {
 }
 function createCopiedInstall(target) {
   const parentDir = resolve15(target.pluginDir, "..");
-  mkdirSync3(parentDir, { recursive: true });
+  mkdirSync4(parentDir, { recursive: true });
   if (existsSync22(target.pluginDir)) {
     rmSync3(target.pluginDir, { recursive: true, force: true });
   }
@@ -14791,7 +15614,7 @@ function patchInstalledMcpConfig(pluginDir, platform, config, entries) {
       }
       mcpServers[name] = entry;
     }
-    writeFileSync3(filepath, JSON.stringify({ mcpServers }, null, 2) + "\n");
+    writeFileSync4(filepath, JSON.stringify({ mcpServers }, null, 2) + "\n");
     return;
   }
   if (platform === "codex") {
@@ -14821,7 +15644,7 @@ function patchInstalledMcpConfig(pluginDir, platform, config, entries) {
       }
       mcpServers[name] = entry;
     }
-    writeFileSync3(filepath, JSON.stringify({ mcpServers }, null, 2) + "\n");
+    writeFileSync4(filepath, JSON.stringify({ mcpServers }, null, 2) + "\n");
   }
 }
 function writeInstalledUserConfig(pluginDir, entries) {
@@ -14831,13 +15654,13 @@ function writeInstalledUserConfig(pluginDir, entries) {
     values: buildUserConfigValueMap(entries),
     env: buildUserConfigEnvMap(entries)
   };
-  writeFileSync3(filepath, JSON.stringify(payload, null, 2) + "\n");
+  writeFileSync4(filepath, JSON.stringify(payload, null, 2) + "\n");
 }
 function disableInstalledEnvValidation(pluginDir, entries) {
   if (entries.length === 0) return;
   const filepath = resolve15(pluginDir, "scripts/check-env.sh");
   if (!existsSync22(filepath)) return;
-  writeFileSync3(
+  writeFileSync4(
     filepath,
     "#!/usr/bin/env bash\nset -euo pipefail\n# pluxx install materialized required config for this local plugin install.\nexit 0\n"
   );
@@ -14869,15 +15692,15 @@ function ensureClaudeMarketplace(pluginName, sourceDir, materialized) {
   const pluginManifestPath = resolve15(sourceDir, ".claude-plugin/plugin.json");
   const pluginManifest = JSON.parse(readFileSync10(pluginManifestPath, "utf-8"));
   rmSync3(marketplaceRoot, { recursive: true, force: true });
-  mkdirSync3(marketplaceManifestDir, { recursive: true });
-  mkdirSync3(resolve15(marketplaceRoot, "plugins"), { recursive: true });
+  mkdirSync4(marketplaceManifestDir, { recursive: true });
+  mkdirSync4(resolve15(marketplaceRoot, "plugins"), { recursive: true });
   if (materialized && materialized.entries.length > 0) {
     cpSync3(sourceDir, marketplacePluginDir, { recursive: true });
     materializeInstalledPlugin(marketplacePluginDir, "claude-code", materialized.config, materialized.entries);
   } else {
     symlinkSync(sourceDir, marketplacePluginDir);
   }
-  writeFileSync3(
+  writeFileSync4(
     resolve15(marketplaceManifestDir, "marketplace.json"),
     JSON.stringify({
       name: marketplaceName,
@@ -15473,6 +16296,43 @@ function checkMcpMetadataQuality(checks, metadata) {
     path: MCP_SCAFFOLD_METADATA_PATH
   });
 }
+function checkCompilerIntent(checks, rootDir) {
+  try {
+    const compilerIntent = readCompilerIntent(rootDir);
+    if (!compilerIntent) return;
+    if ((compilerIntent.skillPolicies?.length ?? 0) === 0) {
+      addCheck2(checks, {
+        level: "info",
+        code: "compiler-intent-empty",
+        title: "Compiler intent file present",
+        detail: `${PLUXX_COMPILER_INTENT_PATH} exists but does not currently carry migrated source-host policy rows.`,
+        fix: "No action needed unless you expected migrated source-host policy to survive into generated outputs.",
+        path: PLUXX_COMPILER_INTENT_PATH
+      });
+      return;
+    }
+    const sourceLabels = [...new Set(
+      compilerIntent.skillPolicies.map((policy) => `${policy.source.platform}:${policy.source.kind}`)
+    )];
+    addCheck2(checks, {
+      level: "info",
+      code: "compiler-intent-source-host",
+      title: "Imported source-host intent still influences compilation",
+      detail: `${PLUXX_COMPILER_INTENT_PATH} preserves ${compilerIntent.skillPolicies.length} migrated skill polic${compilerIntent.skillPolicies.length === 1 ? "y" : "ies"} from ${sourceLabels.join(", ")} so Pluxx can translate that source-host intent into native target surfaces.`,
+      fix: "Review the generated permissions, agents, and host companions to confirm the migrated source-host assumptions still match the plugin you want to ship.",
+      path: PLUXX_COMPILER_INTENT_PATH
+    });
+  } catch (error) {
+    addCheck2(checks, {
+      level: "warning",
+      code: "compiler-intent-invalid",
+      title: "Compiler intent file could not be parsed",
+      detail: error instanceof Error ? error.message : String(error),
+      fix: `Repair or remove ${PLUXX_COMPILER_INTENT_PATH} and rerun pluxx doctor.`,
+      path: PLUXX_COMPILER_INTENT_PATH
+    });
+  }
+}
 function checkScaffoldMetadata(checks, rootDir, config) {
   const metadataPath = resolve16(rootDir, MCP_SCAFFOLD_METADATA_PATH);
   if (!existsSync23(metadataPath)) {
@@ -15805,7 +16665,7 @@ function checkInstalledMcpConfig(checks, rootDir, layout) {
 function isLikelyOpenCodeInstallPath(rootDir) {
   const parent = dirname6(rootDir);
   const grandparent = dirname6(parent);
-  return basename5(parent) === "plugins" && basename5(grandparent) === "opencode";
+  return basename6(parent) === "plugins" && basename6(grandparent) === "opencode";
 }
 function checkInstalledOpenCodeHostBridge(checks, rootDir) {
   if (!isLikelyOpenCodeInstallPath(rootDir)) {
@@ -15819,7 +16679,7 @@ function checkInstalledOpenCodeHostBridge(checks, rootDir) {
     });
     return;
   }
-  const pluginName = basename5(rootDir);
+  const pluginName = basename6(rootDir);
   const entryPath = `${rootDir}.ts`;
   const entryRelativePath = `${pluginName}.ts`;
   if (!existsSync23(entryPath)) {
@@ -15860,7 +16720,7 @@ function checkInstalledOpenCodeSkills(checks, rootDir) {
   if (!isLikelyOpenCodeInstallPath(rootDir)) {
     return;
   }
-  const pluginName = basename5(rootDir);
+  const pluginName = basename6(rootDir);
   const sourceSkillsDir = resolve16(rootDir, "skills");
   if (!existsSync23(sourceSkillsDir)) {
     addCheck2(checks, {
@@ -16033,6 +16893,7 @@ async function doctorProject(rootDir = process.cwd()) {
   checkMcpConfig(checks, config);
   checkUserConfig(checks, config);
   checkScaffoldMetadata(checks, rootDir, config);
+  checkCompilerIntent(checks, rootDir);
   checkHookTrust(checks, config);
   for (const target of config.targets) {
     const limits = PLATFORM_LIMITS[target];
@@ -16159,8 +17020,8 @@ async function runBuild(rootDir, targets) {
 }
 
 // src/cli/migrate.ts
-import { basename as basename6, relative as relative10, resolve as resolve18 } from "path";
-import { existsSync as existsSync24, readdirSync as readdirSync10, mkdirSync as mkdirSync4, cpSync as cpSync4, readFileSync as readFileSync12, writeFileSync as writeFileSync4 } from "fs";
+import { basename as basename7, relative as relative10, resolve as resolve18 } from "path";
+import { existsSync as existsSync24, readdirSync as readdirSync10, mkdirSync as mkdirSync5, cpSync as cpSync4, readFileSync as readFileSync12, writeFileSync as writeFileSync5 } from "fs";
 function detectPlatform(pluginDir) {
   const checks = [
     { dir: ".claude-plugin", platform: "claude-code" },
@@ -16622,7 +17483,7 @@ function sanitizeMigratedSkillFrontmatter(outputDir) {
       "---",
       ...lines.slice(endIndex + 1)
     ].join("\n");
-    writeFileSync4(skillPath, rewritten, "utf-8");
+    writeFileSync5(skillPath, rewritten, "utf-8");
   }
 }
 function readTomlScalarValue(content, key) {
@@ -16646,16 +17507,6 @@ function renderMigratedAgentMarkdown(fileStem, parsed) {
   const agentName = toKebabCase2(parsed.name ?? fileStem) || "agent";
   const title = parsed.name ?? titleCaseFromDirName(agentName);
   const bodyLines = [];
-  if (parsed.model || parsed.effort) {
-    bodyLines.push("Source metadata:");
-    if (parsed.model) {
-      bodyLines.push(`- Preferred model: \`${parsed.model}\``);
-    }
-    if (parsed.effort) {
-      bodyLines.push(`- Preferred reasoning effort: \`${parsed.effort}\``);
-    }
-    bodyLines.push("");
-  }
   if (parsed.developerInstructions) {
     bodyLines.push(parsed.developerInstructions.trim());
   } else {
@@ -16665,6 +17516,8 @@ function renderMigratedAgentMarkdown(fileStem, parsed) {
     "---",
     `name: ${JSON.stringify(agentName)}`,
     ...parsed.description ? [`description: ${JSON.stringify(parsed.description)}`] : [],
+    ...parsed.model ? [`model: ${JSON.stringify(parsed.model)}`] : [],
+    ...parsed.effort ? [`model_reasoning_effort: ${JSON.stringify(parsed.effort)}`] : [],
     "---",
     "",
     `# ${title}`,
@@ -16716,7 +17569,7 @@ function hasTopLevelFrontmatterKey(frontmatterLines, key) {
 function normalizeMigratedOpenCodeAgentFile(agentPath) {
   const original = readFileSync12(agentPath, "utf-8");
   const parsed = splitMarkdownFrontmatter4(original);
-  const fileStem = toKebabCase2(basename6(agentPath, ".md")) || "agent";
+  const fileStem = toKebabCase2(basename7(agentPath, ".md")) || "agent";
   const fallbackDescription = buildFallbackAgentDescription(fileStem);
   if (!parsed.hasFrontmatter) {
     const rewritten2 = [
@@ -16728,7 +17581,7 @@ function normalizeMigratedOpenCodeAgentFile(agentPath) {
       original.trimEnd(),
       ""
     ].join("\n");
-    writeFileSync4(agentPath, rewritten2, "utf-8");
+    writeFileSync5(agentPath, rewritten2, "utf-8");
     return true;
   }
   const additions = [];
@@ -16749,7 +17602,7 @@ function normalizeMigratedOpenCodeAgentFile(agentPath) {
     "---",
     parsed.body
   ].join("\n");
-  writeFileSync4(agentPath, rewritten, "utf-8");
+  writeFileSync5(agentPath, rewritten, "utf-8");
   return true;
 }
 function walkMarkdownFiles3(dir) {
@@ -16781,13 +17634,13 @@ function copyCodexAgents(sourceDir, destDir) {
   const entries = readdirSync10(sourceDir, { withFileTypes: true });
   const tomlEntries = entries.filter((entry) => entry.isFile() && entry.name.endsWith(".toml"));
   if (tomlEntries.length === 0) return false;
-  mkdirSync4(destDir, { recursive: true });
+  mkdirSync5(destDir, { recursive: true });
   for (const entry of tomlEntries) {
     const sourcePath = resolve18(sourceDir, entry.name);
     const parsed = parseCodexAgentToml(readFileSync12(sourcePath, "utf-8"));
     const fallbackName = entry.name.replace(/\.toml$/, "");
     const fileName = `${toKebabCase2(parsed.name ?? fallbackName) || "agent"}.md`;
-    writeFileSync4(resolve18(destDir, fileName), renderMigratedAgentMarkdown(fallbackName, parsed), "utf-8");
+    writeFileSync5(resolve18(destDir, fileName), renderMigratedAgentMarkdown(fallbackName, parsed), "utf-8");
   }
   return true;
 }
@@ -17179,7 +18032,7 @@ Generated pluxx.config.ts`);
   }
   const taxonomyPath = resolve18(outputDir, MCP_TAXONOMY_PATH);
   const metadataPath = resolve18(outputDir, MCP_SCAFFOLD_METADATA_PATH);
-  mkdirSync4(resolve18(outputDir, ".pluxx"), { recursive: true });
+  mkdirSync5(resolve18(outputDir, ".pluxx"), { recursive: true });
   await writeTextFile(taxonomyPath, `${JSON.stringify(result.persistedSkills, null, 2)}
 `);
   if (result.compilerIntent) {
@@ -17206,7 +18059,7 @@ Generated pluxx.config.ts`);
 }
 
 // src/cli/mcp-proxy.ts
-import { mkdirSync as mkdirSync5, readFileSync as readFileSync13 } from "fs";
+import { mkdirSync as mkdirSync6, readFileSync as readFileSync13 } from "fs";
 import { dirname as dirname7, resolve as resolve19 } from "path";
 import * as readline3 from "readline";
 function usage() {
@@ -17219,19 +18072,19 @@ function usage() {
     "- --replay serves a deterministic stdio MCP session from a recorded tape."
   ].join("\n");
 }
-function readOption(rawArgs, flag) {
-  const index = rawArgs.indexOf(flag);
+function readOption(rawArgs2, flag) {
+  const index = rawArgs2.indexOf(flag);
   if (index === -1) return void 0;
-  const value = rawArgs[index + 1];
+  const value = rawArgs2[index + 1];
   if (!value || value.startsWith("-")) {
     return void 0;
   }
   return value;
 }
-function parseOptions(rawArgs) {
-  const source = readOption(rawArgs, "--from-mcp");
-  const recordPath = readOption(rawArgs, "--record");
-  const replayPath = readOption(rawArgs, "--replay");
+function parseOptions(rawArgs2) {
+  const source = readOption(rawArgs2, "--from-mcp");
+  const recordPath = readOption(rawArgs2, "--record");
+  const replayPath = readOption(rawArgs2, "--replay");
   if (recordPath && replayPath) {
     throw new Error("Choose either --record or --replay, not both.");
   }
@@ -17284,7 +18137,7 @@ async function loadReplayTape(filepath) {
 }
 async function writeTape(filepath, tape) {
   const absolutePath = resolve19(process.cwd(), filepath);
-  mkdirSync5(dirname7(absolutePath), { recursive: true });
+  mkdirSync6(dirname7(absolutePath), { recursive: true });
   await writeTextFile(absolutePath, `${JSON.stringify(tape, null, 2)}
 `);
 }
@@ -17419,17 +18272,17 @@ async function replaySession(filepath, io) {
     rl.close();
   }
 }
-async function runMcpProxy(rawArgs) {
-  return await runMcpProxyWithIo(rawArgs, {
+async function runMcpProxy(rawArgs2) {
+  return await runMcpProxyWithIo(rawArgs2, {
     input: process.stdin,
     output: process.stdout,
     error: process.stderr
   });
 }
-async function runMcpProxyWithIo(rawArgs, io) {
+async function runMcpProxyWithIo(rawArgs2, io) {
   let options;
   try {
-    options = parseOptions(rawArgs);
+    options = parseOptions(rawArgs2);
   } catch (error) {
     io.error.write(`${error instanceof Error ? error.message : String(error)}
 
@@ -17455,7 +18308,7 @@ var PromptCancelledError = class extends Error {
   }
 };
 function ask(question) {
-  return new Promise((resolve23, reject) => {
+  return new Promise((resolve24, reject) => {
     const rl = readline4.createInterface({
       input: process.stdin,
       output: process.stdout
@@ -17483,7 +18336,7 @@ function ask(question) {
     rl.once("close", onClose);
     rl.question(question, (answer) => {
       settle(() => {
-        resolve23(answer);
+        resolve24(answer);
         rl.close();
       });
     });
@@ -18458,13 +19311,13 @@ ${c2}
 } }).prompt();
 
 // src/cli/index.ts
-import { basename as basename7, resolve as resolve22 } from "path";
-import { mkdir as mkdir4, mkdtemp as mkdtemp2, rm as rm3 } from "fs/promises";
-import { tmpdir as tmpdir4 } from "os";
-import { spawn as spawn3 } from "child_process";
+import { basename as basename8, resolve as resolve23 } from "path";
+import { mkdir as mkdir4, mkdtemp as mkdtemp3, rm as rm4 } from "fs/promises";
+import { tmpdir as tmpdir5 } from "os";
+import { spawn as spawn4, spawnSync as spawnSync3 } from "child_process";
 
 // src/cli/publish.ts
-import { chmodSync, existsSync as existsSync25, mkdtempSync as mkdtempSync2, readFileSync as readFileSync14, rmSync as rmSync4, writeFileSync as writeFileSync5 } from "fs";
+import { chmodSync, existsSync as existsSync25, mkdtempSync as mkdtempSync2, readFileSync as readFileSync14, rmSync as rmSync4, writeFileSync as writeFileSync6 } from "fs";
 import { createHash } from "crypto";
 import { resolve as resolve20 } from "path";
 import { spawnSync as spawnSync2 } from "child_process";
@@ -18604,9 +19457,9 @@ function collectChecks(args2) {
   const gitStatus = args2.runCommand("git", ["status", "--porcelain"], { cwd: args2.rootDir });
   checks.push({
     name: "git-clean",
-    ok: gitStatus.status === 0 && gitStatus.stdout.trim() === "",
+    ok: args2.allowDirty || gitStatus.status === 0 && gitStatus.stdout.trim() === "",
     code: "git-clean",
-    detail: gitStatus.status !== 0 ? gitStatus.stderr || gitStatus.stdout || "Unable to read git status" : gitStatus.stdout.trim() === "" ? "Working tree is clean." : "Working tree has uncommitted changes."
+    detail: args2.allowDirty ? "Working tree cleanliness check skipped via --allow-dirty." : gitStatus.status !== 0 ? gitStatus.stderr || gitStatus.stdout || "Unable to read git status" : gitStatus.stdout.trim() === "" ? "Working tree is clean." : "Working tree has uncommitted changes."
   });
   if (args2.npmEnabled) {
     checks.push({
@@ -18658,6 +19511,7 @@ function planPublish(config, options = {}) {
     config,
     npmEnabled,
     githubReleaseEnabled,
+    allowDirty: options.allowDirty ?? false,
     packageDir,
     packageName,
     githubRepo,
@@ -18921,7 +19775,7 @@ rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
 
 echo "Installed $PLUGIN_NAME to $INSTALL_DIR"
-echo "If Cursor is already open, restart or reload it so the plugin is picked up."
+echo "If Cursor is already open, use Developer: Reload Window or restart Cursor so the plugin is picked up."
 `;
 }
 function renderInstallCodexScript(config) {
@@ -19035,7 +19889,7 @@ NODE
 
 echo "Installed $PLUGIN_NAME to $INSTALL_DIR"
 echo "Updated Codex marketplace catalog at $MARKETPLACE_PATH"
-echo "If Codex is already open, restart it so the plugin is picked up."
+echo "If Codex is already open, use Plugins > Refresh if that action is available in your current UI, or restart Codex so the plugin is picked up."
 `;
 }
 function renderInstallOpenCodeScript(config) {
@@ -19210,7 +20064,7 @@ function writeChecksumFile(tempRoot, files) {
     const name = filePath.split("/").pop();
     return `${digest}  ${name}`;
   }).join("\n");
-  writeFileSync5(checksumPath, `${lines}
+  writeFileSync6(checksumPath, `${lines}
 `);
   return checksumPath;
 }
@@ -19249,14 +20103,14 @@ function createReleaseArtifacts(rootDir, config, plan, runCommand) {
     for (const asset of githubRelease.assets) {
       if (asset.kind !== "installer") continue;
       const installerPath = resolve20(tempRoot, asset.name);
-      writeFileSync5(installerPath, renderInstallerScript(asset, config, context));
+      writeFileSync6(installerPath, renderInstallerScript(asset, config, context));
       chmodSync(installerPath, 493);
       created.push(installerPath);
     }
     const manifestAsset = githubRelease.assets.find((asset) => asset.kind === "manifest");
     if (manifestAsset) {
       const manifestPath = resolve20(tempRoot, manifestAsset.name);
-      writeFileSync5(manifestPath, buildReleaseManifest(config, context));
+      writeFileSync6(manifestPath, buildReleaseManifest(config, context));
       created.push(manifestPath);
     }
     const checksumAsset = githubRelease.assets.find((asset) => asset.kind === "checksum");
@@ -19371,36 +20225,36 @@ function runPublish(config, options = {}) {
 }
 
 // src/cli/runtime.ts
-function createCliRuntime(rawArgs) {
+function createCliRuntime(rawArgs2) {
   const isCI = process.env.CI === "1" || process.env.CI === "true";
   const isTTY = process.stdin.isTTY === true && process.stdout.isTTY === true;
   return {
-    dryRun: rawArgs.includes("--dry-run"),
-    jsonOutput: rawArgs.includes("--json"),
-    quiet: rawArgs.includes("--quiet"),
+    dryRun: rawArgs2.includes("--dry-run"),
+    jsonOutput: rawArgs2.includes("--json"),
+    quiet: rawArgs2.includes("--quiet"),
     isCI,
     isTTY,
     isInteractive: isTTY && !isCI
   };
 }
-function readFlag(rawArgs, flag) {
-  return rawArgs.includes(flag);
+function readFlag(rawArgs2, flag) {
+  return rawArgs2.includes(flag);
 }
-function readOption2(rawArgs, flag) {
-  const index = rawArgs.indexOf(flag);
+function readOption2(rawArgs2, flag) {
+  const index = rawArgs2.indexOf(flag);
   if (index === -1) return void 0;
-  const value = rawArgs[index + 1];
+  const value = rawArgs2[index + 1];
   if (!value || value.startsWith("-")) {
     return void 0;
   }
   return value;
 }
-function readMultiValueOption(rawArgs, flag) {
-  const index = rawArgs.indexOf(flag);
+function readMultiValueOption(rawArgs2, flag) {
+  const index = rawArgs2.indexOf(flag);
   if (index === -1) return void 0;
   const values = [];
-  for (let i = index + 1; i < rawArgs.length; i += 1) {
-    const value = rawArgs[i];
+  for (let i = index + 1; i < rawArgs2.length; i += 1) {
+    const value = rawArgs2[i];
     if (value.startsWith("-")) break;
     values.push(value);
   }
@@ -19464,8 +20318,225 @@ function printVerifyInstallResult(result) {
   console.log(result.ok ? "pluxx verify-install passed." : "pluxx verify-install failed.");
 }
 
+// src/cli/behavioral.ts
+import { existsSync as existsSync27, readFileSync as readFileSync15 } from "fs";
+import { mkdtemp as mkdtemp2, rm as rm3 } from "fs/promises";
+import { tmpdir as tmpdir4 } from "os";
+import { resolve as resolve22 } from "path";
+import { spawn as spawn3 } from "child_process";
+var BEHAVIORAL_CONFIG_PATH = ".pluxx/behavioral-smoke.json";
+var CURSOR_RUNNER_BINARIES2 = ["agent", "cursor-agent"];
+var SUPPORTED_PLATFORMS = ["claude-code", "cursor", "codex", "opencode"];
+async function runBehavioralSuite(rootDir, config, targets, options = {}) {
+  const selectedPlatforms = targets.filter(
+    (target) => SUPPORTED_PLATFORMS.includes(target)
+  );
+  const cases = loadBehavioralCases(rootDir, selectedPlatforms, options.promptOverride);
+  const checks = [];
+  for (const behavioralCase of cases) {
+    for (const platform of selectedPlatforms) {
+      const targetConfig = behavioralCase.targets[platform];
+      if (!targetConfig) continue;
+      checks.push(await runBehavioralCheck(rootDir, config, behavioralCase.name, platform, targetConfig));
+    }
+  }
+  return {
+    ok: checks.every((check) => check.ok),
+    source: options.promptOverride ? "--behavioral-prompt" : BEHAVIORAL_CONFIG_PATH,
+    checks
+  };
+}
+function loadBehavioralCases(rootDir, targets, promptOverride) {
+  if (promptOverride) {
+    return [{
+      name: "inline-prompt",
+      targets: Object.fromEntries(
+        targets.map((target) => [target, { prompt: promptOverride }])
+      )
+    }];
+  }
+  const filePath = resolve22(rootDir, BEHAVIORAL_CONFIG_PATH);
+  if (!existsSync27(filePath)) {
+    throw new Error(
+      `No behavioral smoke config found at ${BEHAVIORAL_CONFIG_PATH}. Add that file or pass --behavioral-prompt to define a real example query.`
+    );
+  }
+  const parsed = JSON.parse(readFileSync15(filePath, "utf-8"));
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.cases) || parsed.cases.length === 0) {
+    throw new Error(`${BEHAVIORAL_CONFIG_PATH} must contain a non-empty "cases" array.`);
+  }
+  return parsed.cases;
+}
+async function runBehavioralCheck(rootDir, config, caseName, platform, targetConfig) {
+  const prompt = targetConfig.prompt.trim();
+  if (!prompt) {
+    throw new Error(`Behavioral smoke case "${caseName}" for ${platform} is missing a prompt.`);
+  }
+  const command2 = await buildBehavioralCommand(platform, prompt, rootDir);
+  const execution = await executeBehavioralCommand(platform, command2, rootDir);
+  const responseText = execution.response.trim();
+  const failures = [];
+  if (execution.exitCode !== 0) {
+    failures.push(`runner exited with code ${execution.exitCode}`);
+  }
+  if (!responseText) {
+    failures.push("runner returned no response text");
+  }
+  for (const required of targetConfig.require ?? []) {
+    if (!includesNeedle(responseText, required)) {
+      failures.push(`missing required text: ${required}`);
+    }
+  }
+  for (const forbidden of targetConfig.forbid ?? []) {
+    if (includesNeedle(responseText, forbidden)) {
+      failures.push(`matched forbidden text: ${forbidden}`);
+    }
+  }
+  return {
+    caseName,
+    platform,
+    prompt,
+    command: command2,
+    ok: failures.length === 0,
+    exitCode: execution.exitCode,
+    responseBytes: responseText.length,
+    responsePreview: truncate2(responseText, 220),
+    require: targetConfig.require,
+    forbid: targetConfig.forbid,
+    failures
+  };
+}
+async function buildBehavioralCommand(platform, prompt, workspace) {
+  if (platform === "claude-code") {
+    return [
+      "claude",
+      "--no-session-persistence",
+      "--output-format",
+      "text",
+      "--permission-mode",
+      "acceptEdits",
+      "-p",
+      prompt
+    ];
+  }
+  if (platform === "cursor") {
+    const binary = await resolveCursorBinary2();
+    if (!binary) {
+      throw new Error("Cursor CLI `agent` or `cursor-agent` is not available on PATH.");
+    }
+    await ensureCursorAuthenticated(binary);
+    return [
+      binary,
+      "-p",
+      "--trust",
+      "--workspace",
+      workspace,
+      "--force",
+      prompt
+    ];
+  }
+  if (platform === "codex") {
+    return [
+      "codex",
+      "exec",
+      "--ephemeral",
+      "--skip-git-repo-check",
+      "--full-auto",
+      prompt
+    ];
+  }
+  return ["opencode", "run", prompt];
+}
+async function executeBehavioralCommand(platform, command2, cwd) {
+  let codexOutputDir = null;
+  let codexLastMessagePath = null;
+  const runtimeCommand = [...command2];
+  if (platform === "codex") {
+    codexOutputDir = await mkdtemp2(resolve22(tmpdir4(), "pluxx-codex-behavioral-"));
+    codexLastMessagePath = resolve22(codexOutputDir, "last-message.txt");
+    runtimeCommand.splice(2, 0, "--output-last-message", codexLastMessagePath);
+  }
+  try {
+    return await new Promise((resolvePromise, reject) => {
+      const child = spawn3(runtimeCommand[0], runtimeCommand.slice(1), {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: process.env
+      });
+      const stdoutChunks = [];
+      const stderrChunks = [];
+      child.stdout?.on("data", (chunk) => stdoutChunks.push(Buffer.from(chunk)));
+      child.stderr?.on("data", (chunk) => stderrChunks.push(Buffer.from(chunk)));
+      child.on("error", reject);
+      child.on("close", (code) => {
+        const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
+        const stderr = Buffer.concat(stderrChunks).toString("utf-8");
+        const codexMessage = codexLastMessagePath && existsSync27(codexLastMessagePath) ? readFileSync15(codexLastMessagePath, "utf-8") : "";
+        resolvePromise({
+          exitCode: code ?? 1,
+          response: codexMessage.trim() || stdout.trim() || stderr.trim()
+        });
+      });
+    });
+  } finally {
+    if (codexOutputDir) {
+      await rm3(codexOutputDir, { recursive: true, force: true });
+    }
+  }
+}
+async function resolveCursorBinary2() {
+  for (const candidate of CURSOR_RUNNER_BINARIES2) {
+    if (await commandExists2(candidate)) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+async function ensureCursorAuthenticated(binary) {
+  if (process.env.CURSOR_API_KEY && process.env.CURSOR_API_KEY.trim()) {
+    return;
+  }
+  const ok = await commandSucceeds2([binary, "status"]);
+  if (!ok) {
+    throw new Error("Cursor CLI authentication is required. Run `agent login` (or `cursor-agent login`) or export `CURSOR_API_KEY` before behavioral smoke runs.");
+  }
+}
+async function commandExists2(binary) {
+  return await new Promise((resolvePromise) => {
+    const child = spawn3("sh", ["-c", `command -v ${shellQuote2(binary)} >/dev/null 2>&1`], {
+      stdio: "ignore",
+      env: process.env
+    });
+    child.on("close", (code) => resolvePromise(code === 0));
+    child.on("error", () => resolvePromise(false));
+  });
+}
+async function commandSucceeds2(command2) {
+  return await new Promise((resolvePromise) => {
+    const child = spawn3(command2[0], command2.slice(1), {
+      stdio: "ignore",
+      env: process.env
+    });
+    child.on("close", (code) => resolvePromise(code === 0));
+    child.on("error", () => resolvePromise(false));
+  });
+}
+function truncate2(value, length) {
+  if (value.length <= length) return value;
+  return `${value.slice(0, Math.max(0, length - 3))}...`;
+}
+function includesNeedle(haystack, needle) {
+  return haystack.toLowerCase().includes(needle.trim().toLowerCase());
+}
+function shellQuote2(value) {
+  if (/^[A-Za-z0-9_./:-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
 // src/cli/index.ts
-var args = process.argv.slice(2);
+var CLI_PACKAGE_NAME = "@orchid-labs/pluxx";
+var rawArgs = process.argv.slice(2);
+var args = normalizeTopLevelArgs(rawArgs);
 var command = args[0];
 var runtime = createCliRuntime(args);
 var DEFAULT_INIT_TARGETS = ["claude-code", "cursor", "codex", "opencode"];
@@ -19485,6 +20556,12 @@ var ALL_TARGET_PLATFORMS = [
 ];
 async function main() {
   switch (command) {
+    case "version":
+      await runVersionCommand();
+      break;
+    case "upgrade":
+      await runUpgradeCommand();
+      break;
     case "build":
       await runBuild2();
       break;
@@ -19548,6 +20625,95 @@ async function main() {
       process.exit(1);
   }
 }
+function normalizeTopLevelArgs(input) {
+  if (input[0] === "--version" || input[0] === "-v") {
+    return ["version", ...input.slice(1)];
+  }
+  if (input[0] === "--upgrade") {
+    return ["upgrade", ...input.slice(1)];
+  }
+  return input;
+}
+function getCliPackageVersion() {
+  const packageJsonPath = new URL("../../package.json", import.meta.url);
+  const raw = JSON.parse(readFileSync16(packageJsonPath, "utf-8"));
+  if (typeof raw.version !== "string" || raw.version.trim() === "") {
+    throw new Error("Unable to determine the installed pluxx version from package.json.");
+  }
+  return raw.version.trim();
+}
+function resolveNpmExecutable() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+function buildUpgradeSummary() {
+  const requestedVersion = readOption2(args, "--version") ?? "latest";
+  const specifier = `${CLI_PACKAGE_NAME}@${requestedVersion}`;
+  return {
+    dryRun: runtime.dryRun,
+    packageName: CLI_PACKAGE_NAME,
+    currentVersion: getCliPackageVersion(),
+    requestedVersion,
+    specifier,
+    command: [resolveNpmExecutable(), "install", "-g", specifier],
+    note: "This updates the global npm install used by `pluxx` on your PATH. Repo-local and `npx` invocations are separate entrypoints."
+  };
+}
+async function runVersionCommand() {
+  const version = getCliPackageVersion();
+  if (runtime.jsonOutput) {
+    printJson({ version });
+    return;
+  }
+  console.log(version);
+}
+async function runUpgradeCommand() {
+  const summary = buildUpgradeSummary();
+  if (runtime.dryRun) {
+    if (runtime.jsonOutput) {
+      printJson(summary);
+      return;
+    }
+    if (!runtime.quiet) {
+      console.log(`Dry run: would run \`${summary.command.join(" ")}\``);
+      console.log(summary.note);
+      console.log(`Current version: ${summary.currentVersion}`);
+    }
+    return;
+  }
+  const install = spawnSync3(summary.command[0], summary.command.slice(1), runtime.jsonOutput ? {
+    env: process.env,
+    encoding: "utf-8",
+    stdio: "pipe"
+  } : {
+    env: process.env,
+    stdio: "inherit"
+  });
+  if (install.status !== 0) {
+    if (runtime.jsonOutput) {
+      printJson({
+        ...summary,
+        ok: false,
+        stdout: typeof install.stdout === "string" ? install.stdout : "",
+        stderr: typeof install.stderr === "string" ? install.stderr : "",
+        exitCode: install.status ?? 1
+      });
+    }
+    throw new Error(`Failed to upgrade ${CLI_PACKAGE_NAME}.`);
+  }
+  const result = {
+    ...summary,
+    ok: true
+  };
+  if (runtime.jsonOutput) {
+    printJson(result);
+    return;
+  }
+  if (!runtime.quiet) {
+    console.log(`Upgraded ${summary.packageName} with \`${summary.command.join(" ")}\`.`);
+    console.log("Run `pluxx --version` to verify the active version on your PATH.");
+    console.log(summary.note);
+  }
+}
 function hasAgentContextHints(input) {
   return Boolean(input.docsUrl || input.websiteUrl || (input.contextPaths?.length ?? 0) > 0);
 }
@@ -19833,8 +20999,8 @@ function parseTargetPlatforms(raw) {
   }
   return targets;
 }
-function parseTargetFlagValues(rawArgs) {
-  const values = readMultiValueOption(rawArgs, "--target");
+function parseTargetFlagValues(rawArgs2) {
+  const values = readMultiValueOption(rawArgs2, "--target");
   if (!values) return void 0;
   return parseTargetPlatforms(values.join(","));
 }
@@ -19912,7 +21078,7 @@ function defaultAuthEnvVar(provider, discoveredAuth) {
 function tryOpenBrowser(url) {
   const launcher = process.platform === "darwin" ? { command: "open", args: [url] } : process.platform === "win32" ? { command: "cmd", args: ["/c", "start", "", url] } : { command: "xdg-open", args: [url] };
   try {
-    const child = spawn3(launcher.command, launcher.args, {
+    const child = spawn4(launcher.command, launcher.args, {
       detached: true,
       stdio: "ignore"
     });
@@ -20130,7 +21296,7 @@ async function planInitContextArtifactFiles(rootDir, contextPack) {
   return plannedFiles;
 }
 async function planAuxiliaryFile(rootDir, relativePath, content) {
-  const filePath = resolve22(rootDir, relativePath);
+  const filePath = resolve23(rootDir, relativePath);
   const action = await planTextFileAction(filePath, content);
   return {
     relativePath,
@@ -20157,29 +21323,29 @@ function formatMcpDiscoverySummary(introspection) {
   }
   return `${parts.join(", ")} discovered`;
 }
-function parseInitFromMcpOptions(rawArgs, initialName, initialSource) {
+function parseInitFromMcpOptions(rawArgs2, initialName, initialSource) {
   return {
-    source: initialSource ?? readOption2(rawArgs, "--from-mcp"),
-    assumeDefaults: rawArgs.includes("--yes"),
-    name: readOption2(rawArgs, "--name") ?? initialName,
-    author: readOption2(rawArgs, "--author"),
-    displayName: readOption2(rawArgs, "--display-name"),
-    targets: readOption2(rawArgs, "--targets"),
-    docsUrl: readOption2(rawArgs, "--docs"),
-    websiteUrl: readOption2(rawArgs, "--website"),
-    contextPaths: readMultiValueOption(rawArgs, "--context"),
-    ingestProvider: readOption2(rawArgs, "--ingest-provider"),
-    authEnv: readOption2(rawArgs, "--auth-env"),
-    authType: readOption2(rawArgs, "--auth-type"),
-    authHeader: readOption2(rawArgs, "--auth-header"),
-    authTemplate: readOption2(rawArgs, "--auth-template"),
-    runtimeAuth: readOption2(rawArgs, "--runtime-auth"),
-    oauthWrapper: rawArgs.includes("--oauth-wrapper"),
-    approveMcpTools: rawArgs.includes("--approve-mcp-tools"),
-    grouping: readOption2(rawArgs, "--grouping"),
-    hooks: readOption2(rawArgs, "--hooks"),
-    transport: readOption2(rawArgs, "--transport"),
-    jsonOutput: rawArgs.includes("--json")
+    source: initialSource ?? readOption2(rawArgs2, "--from-mcp"),
+    assumeDefaults: rawArgs2.includes("--yes"),
+    name: readOption2(rawArgs2, "--name") ?? initialName,
+    author: readOption2(rawArgs2, "--author"),
+    displayName: readOption2(rawArgs2, "--display-name"),
+    targets: readOption2(rawArgs2, "--targets"),
+    docsUrl: readOption2(rawArgs2, "--docs"),
+    websiteUrl: readOption2(rawArgs2, "--website"),
+    contextPaths: readMultiValueOption(rawArgs2, "--context"),
+    ingestProvider: readOption2(rawArgs2, "--ingest-provider"),
+    authEnv: readOption2(rawArgs2, "--auth-env"),
+    authType: readOption2(rawArgs2, "--auth-type"),
+    authHeader: readOption2(rawArgs2, "--auth-header"),
+    authTemplate: readOption2(rawArgs2, "--auth-template"),
+    runtimeAuth: readOption2(rawArgs2, "--runtime-auth"),
+    oauthWrapper: rawArgs2.includes("--oauth-wrapper"),
+    approveMcpTools: rawArgs2.includes("--approve-mcp-tools"),
+    grouping: readOption2(rawArgs2, "--grouping"),
+    hooks: readOption2(rawArgs2, "--hooks"),
+    transport: readOption2(rawArgs2, "--transport"),
+    jsonOutput: rawArgs2.includes("--json")
   };
 }
 function toKebabCase3(value) {
@@ -20199,7 +21365,7 @@ async function runInit() {
   if (!runtime.isInteractive) {
     throw new Error("pluxx init requires an interactive terminal unless you use `pluxx init --from-mcp ... --yes`.");
   }
-  const dirName = positionalName ? toKebabCase3(positionalName) : basename7(process.cwd()).toLowerCase().replace(/[^a-z0-9-]/g, "-");
+  const dirName = positionalName ? toKebabCase3(positionalName) : basename8(process.cwd()).toLowerCase().replace(/[^a-z0-9-]/g, "-");
   console.log("");
   console.log("  pluxx init \u2014 Create a new plugin");
   console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
@@ -20276,7 +21442,7 @@ ${mcpBlock}${brandBlock}
   targets: [${targetsList}],
 })
 `;
-    await writeTextFile(resolve22(process.cwd(), "pluxx.config.ts"), template);
+    await writeTextFile(resolve23(process.cwd(), "pluxx.config.ts"), template);
     const skillDir = `skills/${skillName}`;
     await mkdir4(skillDir, { recursive: true });
     const skillContent = `---
@@ -20298,7 +21464,7 @@ Describe how agents should use this skill.
 Example prompt or command here
 \`\`\`
 `;
-    await writeTextFile(resolve22(process.cwd(), `${skillDir}/SKILL.md`), skillContent);
+    await writeTextFile(resolve23(process.cwd(), `${skillDir}/SKILL.md`), skillContent);
     console.log("");
     console.log("  Created:");
     console.log("    pluxx.config.ts");
@@ -20542,7 +21708,7 @@ ${formatAuthRequiredMessage("init", retryError, source)}`);
     if (!runtime.dryRun) {
       await applyMcpScaffoldPlan(process.cwd(), plan);
       for (const file of contextArtifactFiles) {
-        await writeTextFile(resolve22(process.cwd(), file.relativePath), file.content);
+        await writeTextFile(resolve23(process.cwd(), file.relativePath), file.content);
       }
     }
     const lintResult = runtime.dryRun ? { errors: 0, warnings: 0, issues: [] } : await lintProject(process.cwd());
@@ -20705,7 +21871,7 @@ async function runSync() {
 async function runDoctor() {
   const consumerMode = readFlag(args, "--consumer");
   const doctorPath = args.slice(1).find((value) => !value.startsWith("-"));
-  const rootDir = doctorPath ? resolve22(process.cwd(), doctorPath) : process.cwd();
+  const rootDir = doctorPath ? resolve23(process.cwd(), doctorPath) : process.cwd();
   const report = consumerMode ? await doctorConsumer(rootDir) : await doctorProject(rootDir);
   if (runtime.jsonOutput) {
     printJson(report);
@@ -21107,7 +22273,7 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
       review: passDecisions.review,
       verify
     });
-    const workspaceRoot = runtime.dryRun ? await mkdtemp2(`${tmpdir4()}/pluxx-autopilot-`) : process.cwd();
+    const workspaceRoot = runtime.dryRun ? await mkdtemp3(`${tmpdir5()}/pluxx-autopilot-`) : process.cwd();
     tempDir = runtime.dryRun ? workspaceRoot : void 0;
     const scaffoldSpinner = createSpinner(runtime);
     scaffoldSpinner?.start(`Autopilot 2/${totalSteps} \xB7 Planning scaffold...`);
@@ -21454,11 +22620,13 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
     }
   } finally {
     if (tempDir) {
-      await rm3(tempDir, { recursive: true, force: true });
+      await rm4(tempDir, { recursive: true, force: true });
     }
   }
 }
 async function runTestCommand() {
+  const behavioral = readFlag(args, "--behavioral");
+  const behavioralPrompt = readOption2(args, "--behavioral-prompt");
   const targets = parseTargetFlagValues(args);
   const result = await runTestSuite({
     rootDir: process.cwd(),
@@ -21466,15 +22634,20 @@ async function runTestCommand() {
   });
   const config = result.config.ok ? await loadConfig() : null;
   const platforms = targets ?? config?.targets ?? [];
+  if (behavioral && !args.includes("--install")) {
+    throw new Error("--behavioral requires --install so the selected host CLIs can see the installed plugin bundle.");
+  }
   const install = result.ok && config ? await maybeInstallBuiltOutputs(config, platforms, { verifyConsumers: true }) : void 0;
-  const finalResult = install?.verification ? {
+  const behavioralResult = result.ok && config && install && behavioral ? await runBehavioralSuite(process.cwd(), config, platforms, { promptOverride: behavioralPrompt }) : void 0;
+  const finalResult = install?.verification || behavioralResult ? {
     ...result,
-    ok: result.ok && install.verification.ok
+    ok: result.ok && (install?.verification?.ok ?? true) && (behavioralResult?.ok ?? true)
   } : result;
   if (runtime.jsonOutput) {
     printJson({
       ...finalResult,
-      install
+      install,
+      behavioral: behavioralResult
     });
     return;
   }
@@ -21492,6 +22665,18 @@ async function runTestCommand() {
           console.log(`${prefix} ${check.platform}: ${check.consumerPath}`);
         }
       }
+      if (behavioralResult) {
+        console.log("Behavioral headless smoke:");
+        for (const check of behavioralResult.checks) {
+          const prefix = check.ok ? "  PASS" : "  FAIL";
+          console.log(`${prefix} ${check.platform}/${check.caseName}: ${check.responsePreview || "(no response preview)"}`);
+          if (!check.ok) {
+            for (const failure of check.failures) {
+              console.log(`    - ${failure}`);
+            }
+          }
+        }
+      }
       for (const note of install.notes) {
         console.log(note);
       }
@@ -21598,7 +22783,8 @@ async function runPublishCommand() {
     requestedChannels,
     version: readOption2(args, "--version"),
     tag: readOption2(args, "--tag"),
-    dryRun: runtime.dryRun
+    dryRun: runtime.dryRun,
+    allowDirty: args.includes("--allow-dirty")
   });
   if (runtime.dryRun) {
     if (runtime.jsonOutput) {
@@ -21618,7 +22804,8 @@ async function runPublishCommand() {
     requestedChannels,
     version: readOption2(args, "--version"),
     tag: readOption2(args, "--tag"),
-    dryRun: false
+    dryRun: false,
+    allowDirty: args.includes("--allow-dirty")
   });
   if (runtime.jsonOutput) {
     printJson(result);
@@ -21641,7 +22828,7 @@ async function runVerifyInstall() {
   const targets = parseTargetFlagValues(args);
   const config = await loadConfig();
   if (runtime.dryRun) {
-    const distDir = resolve22(process.cwd(), config.outDir);
+    const distDir = resolve23(process.cwd(), config.outDir);
     const plan = planInstallPlugin(distDir, config.name, targets ?? config.targets);
     const summary = {
       dryRun: true,
@@ -21718,6 +22905,8 @@ function printHelp() {
 pluxx \u2014 Cross-platform AI agent plugin SDK
 
 Usage:
+  pluxx --version | -v                    Print the installed Pluxx CLI version
+  pluxx upgrade [--version x.y.z]         Upgrade the global npm install of Pluxx
   pluxx build [--target <platforms...>] [--install]   Generate platform-specific plugin files
   pluxx dev [--target <platforms...>]     Watch for changes and auto-rebuild
   pluxx validate                          Validate your config
@@ -21731,11 +22920,11 @@ Usage:
   pluxx init [name] [--from-mcp <source>] Create a new pluxx.config.ts
   pluxx sync [--from-mcp <source>]        Refresh MCP-derived scaffold files
   pluxx migrate <path>                    Import an existing plugin into pluxx
-  pluxx test [--target <platforms...>] [--install]    Run config, lint, eval, build, and smoke checks
+  pluxx test [--target <platforms...>] [--install] [--behavioral]    Run config, lint, eval, build, and smoke checks
   pluxx eval                              Evaluate scaffold and prompt-pack quality
   pluxx install [--target <platforms>] [--trust]  Install built plugins for local testing
   pluxx verify-install [--target <platforms>]    Inspect installed host-visible plugin state
-  pluxx publish [--npm] [--github-release] [--dry-run] [--json] [--tag latest] [--version x.y.z]
+  pluxx publish [--npm] [--github-release] [--allow-dirty] [--dry-run] [--json] [--tag latest] [--version x.y.z]
   pluxx uninstall [--target <platforms>]  Remove symlinked plugins
   pluxx help                              Show this help
 
@@ -21744,6 +22933,7 @@ Common flags:
   --quiet                                 Suppress non-error chatter
   --verbose-runner                        Stream runner stdout/stderr for agent run/autopilot
   --dry-run                               Show planned work without writing files or installing anything
+  --allow-dirty                           Skip the clean-working-tree check for publish planning or CI release flows
   --mode quick|standard|thorough          Control how much agent refinement autopilot performs
   --approve-mcp-tools                     Preapprove all tools from the imported MCP in canonical permissions
   --ingest-provider auto|local|firecrawl  Choose the docs/website ingestion backend for agent prepare/autopilot
@@ -21753,6 +22943,9 @@ Targets:
   warp, gemini-cli, roo-code, cline, amp
 
 Examples:
+  pluxx --version                         Print the installed CLI version
+  pluxx upgrade                           Upgrade the global npm install to latest
+  pluxx upgrade --version x.y.z           Upgrade the global npm install to a specific version
   pluxx build                             Build for all configured targets
   pluxx build --install                   Build and install all configured targets locally
   pluxx build --target claude-code cursor  Build for specific platforms
@@ -21792,6 +22985,8 @@ Examples:
   pluxx eval --json                       Inspect scaffold/prompt-pack quality as JSON
   pluxx test --target claude-code codex  Verify selected target outputs
   pluxx test --install                    Verify and install all configured targets locally
+  pluxx test --install --trust --behavioral  Run installed headless example-query smoke checks
+  pluxx test --install --trust --behavioral --behavioral-prompt "Use My Plugin to summarize this repo"
   pluxx install                           Install to all configured targets
   pluxx install --target claude-code      Install to Claude Code only
   pluxx verify-install --target codex     Verify the installed Codex bundle in its native local path
@@ -21801,7 +22996,7 @@ Examples:
 }
 if (import.meta.main) {
   main().catch((err) => {
-    console.error(err);
+    console.error(err instanceof Error ? err.message : err);
     process.exit(1);
   });
 }