@orchid-labs/pluxx 0.1.7 → 0.1.8

package/dist/cli/index.js

@@ -85,7 +85,7 @@ var require_src = __commonJS({
 });
 
 // src/cli/index.ts
-import { readFileSync as readFileSync17 } from "fs";
+import { readFileSync as readFileSync18 } from "fs";
 
 // src/config/load.ts
 import { resolve, extname, dirname } from "path";
@@ -5192,6 +5192,51 @@ async function generateClaudeFamilyOutputs(args2) {
     writeInstructions(config, rootDir, options, writeFile3)
   ]);
 }
+function shellSingleQuote(value) {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function buildClaudeHookCommandWrapperScript(command2) {
+  const serializedCommand = shellSingleQuote(command2);
+  const exportLoader = [
+    'import { readFileSync } from "node:fs"',
+    "",
+    "const filepath = process.argv[1]",
+    "if (!filepath) process.exit(0)",
+    'const payload = JSON.parse(readFileSync(filepath, "utf8"))',
+    'const env = payload && typeof payload === "object" && payload.env && typeof payload.env === "object"',
+    "  ? payload.env",
+    "  : {}",
+    "",
+    "for (const [key, value] of Object.entries(env)) {",
+    "  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue",
+    '  console.log(`export ${key}=${JSON.stringify(String(value ?? ""))}`)',
+    "}"
+  ].join("\n");
+  return [
+    "#!/usr/bin/env bash",
+    "set -euo pipefail",
+    "",
+    'PLUXX_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"',
+    'PLUXX_USER_CONFIG_PATH="$PLUXX_PLUGIN_ROOT/.pluxx-user.json"',
+    "",
+    'if [ -f "$PLUXX_USER_CONFIG_PATH" ]; then',
+    "  while IFS= read -r pluxx_export; do",
+    '    if [ -n "$pluxx_export" ]; then',
+    '      eval "$pluxx_export"',
+    '      if [ -n "${CLAUDE_ENV_FILE:-}" ]; then',
+    `        printf '%s\\n' "$pluxx_export" >> "$CLAUDE_ENV_FILE"`,
+    "      fi",
+    "    fi",
+    "  done < <(",
+    `    node --input-type=module -e ${shellSingleQuote(exportLoader)} "$PLUXX_USER_CONFIG_PATH"`,
+    "  )",
+    "fi",
+    "",
+    `PLUXX_HOOK_COMMAND=${serializedCommand}`,
+    'eval "$PLUXX_HOOK_COMMAND"',
+    ""
+  ].join("\n");
+}
 async function writeManifest(config, rootDir, options, writeJson) {
   const manifest = {
     name: config.name,
@@ -5269,7 +5314,9 @@ async function writeHooks(config, platform, options, writeJson, writeFile3) {
   const hooks = {};
   const mapEventName = options.mapEventName ?? defaultMapEventName;
   const usesPlatformManagedAuth = platform === "claude-code" && config.platforms?.["claude-code"]?.mcpAuth === "platform";
+  const shouldWrapClaudeHookCommands = platform === "claude-code";
   const permissionScript = buildGeneratedPermissionHookScript(config.permissions);
+  let generatedClaudeHookCommandCount = 0;
   if (permissionScript) {
     await writeFile3("hooks/pluxx-permissions.mjs", permissionScript);
     hooks.PreToolUse = [{
@@ -5299,12 +5346,21 @@ async function writeHooks(config, platform, options, writeJson, writeFile3) {
     if (commandEntries.length === 0) continue;
     hooks[mappedEvent] = [
       ...hooks[mappedEvent] ?? [],
-      ...commandEntries.map((entry) => ({
-        ...entry.matcher !== void 0 ? { matcher: entry.matcher } : {},
-        hooks: [{
-          type: "command",
-          command: entry.command.replace("${PLUGIN_ROOT}", `\${${options.pluginRootVar}}`)
-        }]
+      ...await Promise.all(commandEntries.map(async (entry) => {
+        const command2 = entry.command.replace("${PLUGIN_ROOT}", `\${${options.pluginRootVar}}`);
+        const finalCommand = shouldWrapClaudeHookCommands ? await (async () => {
+          generatedClaudeHookCommandCount += 1;
+          const relativePath = `hooks/pluxx-hook-command-${generatedClaudeHookCommandCount}.sh`;
+          await writeFile3(relativePath, buildClaudeHookCommandWrapperScript(command2));
+          return `bash "\${${options.pluginRootVar}}/${relativePath}"`;
+        })() : command2;
+        return {
+          ...entry.matcher !== void 0 ? { matcher: entry.matcher } : {},
+          hooks: [{
+            type: "command",
+            command: finalCommand
+          }]
+        };
       }))
     ];
   }
@@ -9317,6 +9373,16 @@ import { basename as basename5, dirname as dirname4, relative as relative7, reso
 
 // src/user-config.ts
 var ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var PLACEHOLDER_SECRET_PATTERNS = [
+  /\bdummy\b/i,
+  /\bplaceholder\b/i,
+  /\bexample\b/i,
+  /\bchangeme\b/i,
+  /\breplace[_ -]?me\b/i,
+  /\byour[_ -]?(api[_ -]?)?key\b/i,
+  /\bapi[_ -]?key[_ -]?here\b/i,
+  /\btoken[_ -]?here\b/i
+];
 function normalizeUserConfigKey(value) {
   return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").replace(/[._/\s]+/g, "-").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -9331,6 +9397,12 @@ function extractEnvReference(value) {
   const match = value.match(/^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/);
   return match?.[1];
 }
+function isPlaceholderSecretValue(value) {
+  if (typeof value !== "string") return false;
+  const normalized = value.trim();
+  if (normalized === "") return false;
+  return PLACEHOLDER_SECRET_PATTERNS.some((pattern) => pattern.test(normalized));
+}
 function isRuntimePlatformManaged(config, target, server) {
   if (server.transport === "stdio") return false;
   if (server.auth?.type === "platform") {
@@ -9507,6 +9579,42 @@ var WORKFLOW_SKILL_DEFINITIONS = [
     title: "General Research",
     description: "Handle broad search and query workflows when there is not a more specific product surface match.",
     match: ["search", "query", "lookup", "look up", "discover", "find"]
+  },
+  {
+    key: "web-research",
+    title: "Web Research",
+    description: "Search the web, fetch pages, and synthesize public source-backed research.",
+    match: ["web", "website", "url", "page", "fetch", "crawl", "scrape", "search", "result", "source"]
+  },
+  {
+    key: "source-review",
+    title: "Source Review",
+    description: "Audit sources, citations, evidence quality, and duplicate or weak research results.",
+    match: ["source", "citation", "evidence", "audit", "review", "quality", "rank", "dedupe", "duplicate"]
+  },
+  {
+    key: "content-extraction",
+    title: "Content Extraction",
+    description: "Extract structured content, entities, and summaries from pages, documents, or search results.",
+    match: ["extract", "parse", "content", "summary", "summarize", "document", "html", "markdown"]
+  },
+  {
+    key: "knowledge-search",
+    title: "Knowledge Search",
+    description: "Search docs, knowledge bases, papers, repositories, and internal reference material.",
+    match: ["docs", "documentation", "knowledge", "paper", "papers", "repo", "repository", "api", "reference"]
+  },
+  {
+    key: "news-monitoring",
+    title: "News Monitoring",
+    description: "Find recent news, launches, announcements, and time-bounded developments.",
+    match: ["news", "recent", "latest", "launch", "announcement", "announced", "date", "published"]
+  },
+  {
+    key: "code-research",
+    title: "Code Research",
+    description: "Find implementation docs, code examples, API usage, migration notes, and troubleshooting context.",
+    match: ["code", "sdk", "api", "github", "example", "migration", "error", "troubleshoot", "implementation"]
   }
 ];
 var WORKFLOW_MATCH_MIN_SCORE = 2;
@@ -9589,6 +9697,8 @@ async function planMcpScaffold(options) {
     options.persistedSkills,
     options.toolRenames
   );
+  const skillGrouping = options.skillGrouping ?? "workflow";
+  const plannedCommands = planCommandScaffolds(plannedSkills, skillGrouping);
   const description = options.description ?? deriveScaffoldDescription({
     displayName,
     introspection: options.introspection,
@@ -9641,7 +9751,7 @@ async function planMcpScaffold(options) {
       passthroughPaths,
       runtimeAuthMode,
       permissions,
-      commandsPath: "./commands/"
+      commandsPath: plannedCommands.length > 0 ? "./commands/" : void 0
     })
   );
   await addPlannedFile(
@@ -9671,8 +9781,6 @@ async function planMcpScaffold(options) {
   for (const skill of plannedSkills) {
     const relativeSkillPath = `skills/${skill.dirName}`;
     const skillPath = resolve10(skillRoot, skill.dirName, "SKILL.md");
-    const relativeCommandPath = `commands/${skill.dirName}.md`;
-    const commandPath = resolve10(commandsRoot, `${skill.dirName}.md`);
     await addPlannedFile(
       `${relativeSkillPath}/SKILL.md`,
       wrapManagedMarkdown(
@@ -9686,6 +9794,10 @@ async function planMcpScaffold(options) {
     );
     skillDirectories.push(relativeSkillPath);
     generatedFiles.push(`${relativeSkillPath}/SKILL.md`);
+  }
+  for (const skill of plannedCommands) {
+    const relativeCommandPath = `commands/${skill.dirName}.md`;
+    const commandPath = resolve10(commandsRoot, `${skill.dirName}.md`);
     await addPlannedFile(
       relativeCommandPath,
       buildCommandContent(
@@ -9705,7 +9817,7 @@ async function planMcpScaffold(options) {
     introspection: options.introspection,
     pluginName,
     displayName,
-    skillGrouping: options.skillGrouping ?? "workflow",
+    skillGrouping,
     requestedHookMode: options.hookMode ?? "none",
     generatedHookMode: generatedHooks.mode,
     generatedHookEvents: Object.keys(generatedHooks.hookEntries ?? {}),
@@ -9932,6 +10044,19 @@ function buildCommandContent(skill, existingContent) {
     }
   );
 }
+function hasStrongCommandShape(skill, grouping) {
+  if (grouping === "tool") return true;
+  if (skill.tools.length > 1) return true;
+  if (skill.prompts.length > 0) return true;
+  if (skill.resources.length > 0 || skill.resourceTemplates.length > 0) return true;
+  const requiredFields = skill.tools.flatMap((tool) => getTopLevelSchemaFields(tool.inputSchema).filter((field) => field.required));
+  return requiredFields.length >= 2;
+}
+function planCommandScaffolds(plannedSkills, grouping) {
+  const commands = plannedSkills.filter((skill) => hasStrongCommandShape(skill, grouping));
+  if (commands.length > 0) return commands;
+  return plannedSkills.slice(0, 1);
+}
 function formatArgumentHintFrontmatter(value) {
   const trimmed = value.trim();
   if (!trimmed) return '""';
@@ -11272,6 +11397,11 @@ function evaluateSkills(rootDir, metadata, checks) {
 function hasManagedCommands(metadata) {
   return metadata.managedFiles.some((file) => file.startsWith("commands/"));
 }
+function managedCommandSkillNames(metadata) {
+  return new Set(
+    metadata.managedFiles.filter((file) => file.startsWith("commands/") && file.endsWith(".md")).map((file) => file.replace(/^commands\//, "").replace(/\.md$/, ""))
+  );
+}
 function evaluateCommands(rootDir, metadata, checks) {
   if (!hasManagedCommands(metadata)) {
     addCheck(checks, {
@@ -11284,7 +11414,8 @@ function evaluateCommands(rootDir, metadata, checks) {
     return;
   }
   const failures = [];
-  for (const skill of metadata.skills) {
+  const commandSkillNames = managedCommandSkillNames(metadata);
+  for (const skill of metadata.skills.filter((entry) => commandSkillNames.has(entry.dirName))) {
     const relativePath = `commands/${skill.dirName}.md`;
     const filePath = resolve11(rootDir, relativePath);
     if (!existsSync19(filePath)) {
@@ -11332,10 +11463,36 @@ function evaluateCommands(rootDir, metadata, checks) {
     level: "success",
     code: "command-quality-contract",
     title: "Command scaffolds expose expected routing guidance and related surfaces",
-    detail: `Checked ${metadata.skills.length} generated command file(s) for argument hints, tool routing, and related discovery surfaces.`,
+    detail: `Checked ${commandSkillNames.size} generated command file(s) for argument hints, tool routing, and related discovery surfaces.`,
     fix: "No action needed."
   });
 }
+function evaluateScaffoldArchitecture(metadata, checks) {
+  const commandSkillNames = managedCommandSkillNames(metadata);
+  if (metadata.tools.length === 0 || commandSkillNames.size === 0) return;
+  const singletonSkills = metadata.skills.filter((skill) => (skill.toolNames?.length ?? 0) === 1);
+  const commandBackedSingletons = singletonSkills.filter((skill) => commandSkillNames.has(skill.dirName));
+  const commandPerTool = commandSkillNames.size >= metadata.tools.length && commandBackedSingletons.length >= Math.ceil(commandSkillNames.size * 0.8);
+  if (commandPerTool) {
+    addCheck(checks, {
+      level: "warning",
+      code: "scaffold-command-per-tool-shape",
+      title: "Scaffold looks like command-per-tool output",
+      detail: `This scaffold exposes ${commandSkillNames.size} command(s) for ${metadata.tools.length} MCP tool(s), with most commands wrapping a single tool.`,
+      fix: "Prefer workflow-level commands and keep singleton raw tool wrappers as skills only unless the tool has a strong user-facing workflow or required arguments."
+    });
+  }
+  const singletonRatio = singletonSkills.length / Math.max(metadata.skills.length, 1);
+  if (metadata.skills.length >= 6 && singletonRatio >= 0.75) {
+    addCheck(checks, {
+      level: "warning",
+      code: "scaffold-singleton-heavy-taxonomy",
+      title: "Scaffold taxonomy is singleton-heavy",
+      detail: `${singletonSkills.length} of ${metadata.skills.length} skill(s) wrap a single MCP tool, which usually means the plugin is still shaped like an API surface rather than user workflows.`,
+      fix: "Run `pluxx agent run taxonomy` or `pluxx autopilot --mode standard` to merge raw tools into product workflows before shipping."
+    });
+  }
+}
 function evaluateAgentContext(contextContent, metadata, checks) {
   const missing = [];
   if (((metadata.resources?.length ?? 0) > 0 || (metadata.resourceTemplates?.length ?? 0) > 0 || (metadata.prompts?.length ?? 0) > 0) && !contextContent.includes("## MCP Discovery Surfaces")) {
@@ -11475,6 +11632,7 @@ async function runEvalSuite(options = {}) {
       evaluateInstructions(rootDir, metadata, checks);
       evaluateSkills(rootDir, metadata, checks);
       evaluateCommands(rootDir, metadata, checks);
+      evaluateScaffoldArchitecture(metadata, checks);
     }
     evaluateAgentContext(contextContent, metadata, checks);
     for (const kind of AGENT_PROMPT_KINDS) {
@@ -15249,6 +15407,10 @@ async function resolveInstallUserConfig(config, platforms = config.targets, opti
   const isTTY = options.isTTY ?? process.stdin.isTTY === true;
   for (const entry of planned) {
     if (entry.value !== void 0) {
+      if (entry.field.type === "secret" && isPlaceholderSecretValue(entry.value)) {
+        const hint = entry.envVar ? ` Export a real value first: export ${entry.envVar}='your_real_key'. Then rerun pluxx install.` : " Provide a real secret value before installing.";
+        throw new Error(`Refusing to install placeholder secret for userConfig "${entry.field.key}". Placeholder values like "dummy" are not usable by installed MCP servers.${hint}`);
+      }
       resolved.push({
         field: entry.field,
         value: entry.value,
@@ -15260,8 +15422,8 @@ async function resolveInstallUserConfig(config, platforms = config.targets, opti
       continue;
     }
     if (!isTTY) {
-      const hint = entry.envVar ? ` Export ${entry.envVar} or install interactively.` : " Re-run interactively to provide it.";
-      throw new Error(`Missing required userConfig "${entry.field.key}".${hint}`);
+      const hint = entry.envVar ? ` Export it before installing: export ${entry.envVar}='your_real_key'. Then rerun pluxx install.` : " Re-run interactively to provide it.";
+      throw new Error(`Missing required userConfig "${entry.field.key}". Installed plugins cannot prompt for this value later in every host UI.${hint}`);
     }
     const promptLabel = entry.field.title || entry.field.key;
     const envHint = entry.envVar ? ` [env: ${entry.envVar}]` : "";
@@ -15336,7 +15498,7 @@ async function ensureHookTrust(options) {
   const isTTY = options.isTTY ?? process.stdin.isTTY === true;
   if (!isTTY) {
     throw new Error(
-      `Refusing to install plugin with hooks in non-interactive mode. Re-run with --trust to continue.`
+      `Refusing to install plugin with hooks in non-interactive mode. Review the hook commands above. Re-run with --trust if you trust this plugin author.`
     );
   }
   const confirm = options.confirmPrompt ?? promptTrustConfirmation;
@@ -15535,7 +15697,7 @@ function getInstallFollowupNotes(platforms) {
     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.");
+    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. Plugin-bundled MCP servers may appear on the plugin detail page without appearing in the global MCP servers settings page.");
   }
   if (platforms.includes("opencode")) {
     notes.push("OpenCode note: if OpenCode is already open, restart or reload it so the plugin is picked up.");
@@ -15755,11 +15917,159 @@ function getClaudeMarketplaceRoot(pluginName) {
   return resolve15(home, ".claude/plugins/data", getClaudeMarketplaceName(pluginName));
 }
 function resolveInstalledConsumerPath(target, pluginName) {
-  if (target.platform === "claude-code") {
-    return resolve15(getClaudeMarketplaceRoot(pluginName), "plugins", pluginName);
+  if (target.platform === "claude-code" && pluginName !== "") {
+    return target.pluginDir;
   }
   return target.pluginDir;
 }
+function manifestPathForPlatform(platform) {
+  switch (platform) {
+    case "claude-code":
+      return ".claude-plugin/plugin.json";
+    case "cursor":
+      return ".cursor-plugin/plugin.json";
+    case "codex":
+      return ".codex-plugin/plugin.json";
+    case "opencode":
+      return "package.json";
+    default:
+      return void 0;
+  }
+}
+function isRelativeBundlePath(value) {
+  return value.startsWith("./") || value.startsWith("../") || value.startsWith(".\\") || value.startsWith("..\\");
+}
+function resolveBundleReference(rootDir, value) {
+  if (isRelativeBundlePath(value)) {
+    return resolve15(rootDir, value);
+  }
+  const pluginRootMatch = value.match(/^\$\{(?:CLAUDE_PLUGIN_ROOT|CURSOR_PLUGIN_ROOT|PLUGIN_ROOT)\}[\\/](.+)$/);
+  if (pluginRootMatch) {
+    return resolve15(rootDir, pluginRootMatch[1]);
+  }
+  return void 0;
+}
+function readBundleManifestReferences(manifest) {
+  const references = [];
+  for (const key of ["commands", "skills", "hooks", "mcpServers"]) {
+    const value = manifest[key];
+    if (typeof value === "string") {
+      references.push(value);
+    }
+  }
+  const agents = manifest.agents;
+  if (typeof agents === "string") {
+    references.push(agents);
+  } else if (Array.isArray(agents)) {
+    for (const entry of agents) {
+      if (typeof entry === "string") {
+        references.push(entry);
+      }
+    }
+  }
+  return references;
+}
+function collectHookCommandStrings(value, commands) {
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      collectHookCommandStrings(entry, commands);
+    }
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "command" && typeof child === "string") {
+      commands.push(child);
+      continue;
+    }
+    collectHookCommandStrings(child, commands);
+  }
+}
+function extractBundleCommandTargets(command2) {
+  const matches = command2.match(/\$\{(?:CLAUDE_PLUGIN_ROOT|CURSOR_PLUGIN_ROOT|PLUGIN_ROOT)\}[\\/][^\s"'`;$|&<>]+|\.\.?[\\/][^\s"'`;$|&<>]+/g);
+  return matches ?? [];
+}
+function findInstalledBundleIntegrityIssues(rootDir, platform) {
+  const manifestPath = manifestPathForPlatform(platform);
+  if (!manifestPath) {
+    return {
+      missingManifestPaths: [],
+      missingHookTargets: []
+    };
+  }
+  const manifestFile = resolve15(rootDir, manifestPath);
+  if (!existsSync23(manifestFile)) {
+    return {
+      manifestIssue: `missing plugin manifest at ${manifestPath}`,
+      missingManifestPaths: [],
+      missingHookTargets: []
+    };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync10(manifestFile, "utf-8"));
+  } catch (error) {
+    return {
+      manifestIssue: `plugin manifest at ${manifestPath} is not parseable: ${error instanceof Error ? error.message : String(error)}`,
+      missingManifestPaths: [],
+      missingHookTargets: []
+    };
+  }
+  const missingManifestPaths = readBundleManifestReferences(manifest).filter((value) => {
+    const resolved = resolveBundleReference(rootDir, value);
+    return resolved !== void 0 && !existsSync23(resolved);
+  }).sort();
+  const hooksReference = typeof manifest.hooks === "string" ? manifest.hooks : void 0;
+  if (!hooksReference) {
+    return {
+      missingManifestPaths,
+      missingHookTargets: []
+    };
+  }
+  const hooksPath = resolveBundleReference(rootDir, hooksReference);
+  if (!hooksPath || !existsSync23(hooksPath)) {
+    return {
+      missingManifestPaths,
+      missingHookTargets: []
+    };
+  }
+  try {
+    const hooks = JSON.parse(readFileSync10(hooksPath, "utf-8"));
+    const commands = [];
+    collectHookCommandStrings(hooks, commands);
+    const missingHookTargets = [...new Set(
+      commands.flatMap(extractBundleCommandTargets).filter((value) => {
+        const resolved = resolveBundleReference(rootDir, value);
+        return resolved !== void 0 && !existsSync23(resolved);
+      })
+    )].sort();
+    return {
+      missingManifestPaths,
+      missingHookTargets
+    };
+  } catch {
+    return {
+      missingManifestPaths,
+      missingHookTargets: []
+    };
+  }
+}
+function assertInstalledBundleIntegrity(rootDir, platform, label) {
+  const issues = findInstalledBundleIntegrityIssues(rootDir, platform);
+  const details = [];
+  if (issues.manifestIssue) {
+    details.push(issues.manifestIssue);
+  }
+  if (issues.missingManifestPaths.length > 0) {
+    details.push(`manifest paths missing: ${issues.missingManifestPaths.join(", ")}`);
+  }
+  if (issues.missingHookTargets.length > 0) {
+    details.push(`hook targets missing: ${issues.missingHookTargets.join(", ")}`);
+  }
+  if (details.length > 0) {
+    throw new Error(`${label} is incomplete: ${details.join("; ")}`);
+  }
+}
 function ensureClaudeMarketplace(pluginName, sourceDir, materialized) {
   const marketplaceName = getClaudeMarketplaceName(pluginName);
   const marketplaceRoot = getClaudeMarketplaceRoot(pluginName);
@@ -15770,12 +16080,11 @@ function ensureClaudeMarketplace(pluginName, sourceDir, materialized) {
   rmSync3(marketplaceRoot, { recursive: true, force: true });
   mkdirSync4(marketplaceManifestDir, { recursive: true });
   mkdirSync4(resolve15(marketplaceRoot, "plugins"), { recursive: true });
+  cpSync3(sourceDir, marketplacePluginDir, { 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);
   }
+  assertInstalledBundleIntegrity(marketplacePluginDir, "claude-code", "Claude marketplace bundle");
   writeFileSync4(
     resolve15(marketplaceManifestDir, "marketplace.json"),
     JSON.stringify({
@@ -15825,6 +16134,7 @@ function installClaudePlugin(target, pluginName, runCommand, materialized) {
   if (install.status !== 0) {
     throw new Error(`Failed to install Claude plugin: ${install.stderr || install.stdout}`);
   }
+  assertInstalledBundleIntegrity(target.pluginDir, "claude-code", "Installed Claude plugin bundle");
 }
 function uninstallClaudePlugin(target, pluginName, runCommand, options = {}) {
   const marketplaceName = getClaudeMarketplaceName(pluginName);
@@ -15906,7 +16216,11 @@ async function installPlugin(distDir, pluginName, platforms, options = {}) {
     console.log("Nothing to install. Run `pluxx build` first.");
   } else if (!options.quiet) {
     console.log(`
-Installed ${installed} plugin(s). Reload or restart your tools to pick them up.`);
+Installed ${installed} plugin(s).`);
+    console.log("Next checks:");
+    console.log(`  1. Run: pluxx verify-install --target ${filtered.map((target) => target.platform).join(",")}`);
+    console.log("  2. Open the host plugin screen and confirm the plugin appears there.");
+    console.log("  3. Reload or restart the host if it was already open.");
     for (const note of getInstallFollowupNotes(filtered.map((target) => target.platform))) {
       console.log(note);
     }
@@ -16596,6 +16910,10 @@ function checkInstalledUserConfig(checks, rootDir) {
     const payload = JSON.parse(readFileSync11(resolvedPath, "utf-8"));
     const valueCount = Object.keys(payload.values ?? {}).length;
     const envCount = Object.keys(payload.env ?? {}).length;
+    const placeholderKeys = [
+      ...Object.entries(payload.values ?? {}).filter(([, value]) => isPlaceholderSecretValue(value)).map(([key]) => key),
+      ...Object.entries(payload.env ?? {}).filter(([, value]) => isPlaceholderSecretValue(value)).map(([key]) => key)
+    ];
     addCheck2(checks, {
       level: "success",
       code: "consumer-user-config-valid",
@@ -16604,6 +16922,16 @@ function checkInstalledUserConfig(checks, rootDir) {
       fix: "No action needed.",
       path: userConfigPath
     });
+    if (placeholderKeys.length > 0) {
+      addCheck2(checks, {
+        level: "warning",
+        code: "consumer-user-config-placeholder-secret",
+        title: "Local install config contains placeholder-looking secret values",
+        detail: `.pluxx-user.json contains placeholder-looking value${placeholderKeys.length === 1 ? "" : "s"} for ${placeholderKeys.join(", ")}.`,
+        fix: "Reinstall the plugin with real secret values, or edit .pluxx-user.json and refresh/restart the host.",
+        path: userConfigPath
+      });
+    }
   } catch (error) {
     addCheck2(checks, {
       level: "error",
@@ -16688,6 +17016,16 @@ function checkInstalledMcpConfig(checks, rootDir, layout) {
     if (servers.length === 0) {
       return;
     }
+    if (layout.platform === "codex") {
+      addCheck2(checks, {
+        level: "info",
+        code: "consumer-codex-mcp-bundled-visibility",
+        title: "Codex plugin-bundled MCP visibility clarified",
+        detail: `This Codex plugin bundle includes ${servers.length} MCP server${servers.length === 1 ? "" : "s"} through ${layout.mcpConfigPath}. Codex may show this on the plugin detail page without listing it on the global MCP servers settings page.`,
+        fix: "Use the plugin detail page, tool availability in chat, and `pluxx verify-install --target codex` as the source of truth for plugin-bundled MCP wiring. If the MCP remains unavailable after install, use Plugins > Refresh if present or restart Codex.",
+        path: layout.mcpConfigPath
+      });
+    }
     const remoteEntries = servers.filter((server) => "url" in server);
     const stdioEntries = servers.filter((server) => "command" in server);
     const inlineHeaderEntries = servers.filter((server) => {
@@ -16749,6 +17087,38 @@ function checkInstalledMcpConfig(checks, rootDir, layout) {
     });
   }
 }
+function checkInstalledBundleIntegrity(checks, rootDir, layout) {
+  const issues = findInstalledBundleIntegrityIssues(rootDir, layout.platform);
+  const details = [];
+  if (issues.manifestIssue) {
+    details.push(issues.manifestIssue);
+  }
+  if (issues.missingManifestPaths.length > 0) {
+    details.push(`manifest references missing path${issues.missingManifestPaths.length === 1 ? "" : "s"}: ${issues.missingManifestPaths.join(", ")}`);
+  }
+  if (issues.missingHookTargets.length > 0) {
+    details.push(`hook commands reference missing bundle target${issues.missingHookTargets.length === 1 ? "" : "s"}: ${issues.missingHookTargets.join(", ")}`);
+  }
+  if (details.length === 0) {
+    addCheck2(checks, {
+      level: "success",
+      code: "consumer-bundle-integrity-valid",
+      title: "Installed bundle references resolve inside the plugin",
+      detail: "Every manifest-declared path and bundle-relative hook target exists in this installed bundle.",
+      fix: "No action needed.",
+      path: layout.manifestPath
+    });
+    return;
+  }
+  addCheck2(checks, {
+    level: "error",
+    code: "consumer-bundle-integrity-invalid",
+    title: "Installed bundle is missing referenced files",
+    detail: details.join("; "),
+    fix: "Reinstall the plugin or rebuild the bundle so every manifest path and hook target exists in the installed plugin.",
+    path: layout.manifestPath
+  });
+}
 function findMissingInstalledStdioRuntimePaths(rootDir, stdioEntries) {
   const missing = /* @__PURE__ */ new Set();
   for (const server of stdioEntries) {
@@ -16934,6 +17304,7 @@ async function doctorConsumer(rootDir = process.cwd()) {
     path: layout.manifestPath
   });
   checkConsumerManifest(checks, rootDir, layout);
+  checkInstalledBundleIntegrity(checks, rootDir, layout);
   checkInstalledUserConfig(checks, rootDir);
   checkInstalledEnvValidation(checks, rootDir);
   checkInstalledMcpConfig(checks, rootDir, layout);
@@ -19725,6 +20096,175 @@ echo
 echo "Installed __DISPLAY_NAME__ across ${installerTargets.join(", ")}."
 `.replaceAll("__REPO__", "REPO_PLACEHOLDER").replaceAll("__DISPLAY_NAME__", "DISPLAY_PLACEHOLDER");
 }
+function renderInstallerUserConfigSnippet(config, platform, installDirVariable) {
+  const entries = collectUserConfigEntries(config, [platform]).map((entry) => ({
+    key: entry.key,
+    title: entry.title,
+    type: entry.type ?? "string",
+    required: entry.required !== false,
+    envVar: entry.envVar ?? defaultUserConfigEnvVar(entry.key)
+  }));
+  if (entries.length === 0) return "";
+  const promptLines = entries.map((entry) => {
+    const functionName = entry.type === "secret" ? "pluxx_prompt_secret_config" : "pluxx_prompt_text_config";
+    return `${functionName} ${JSON.stringify(entry.envVar)} ${JSON.stringify(entry.title)} ${entry.required ? "1" : "0"}`;
+  });
+  return `
+PLUXX_USER_CONFIG_SPEC="$(cat <<'PLUXX_USER_CONFIG_JSON'
+${JSON.stringify(entries)}
+PLUXX_USER_CONFIG_JSON
+)"
+
+pluxx_is_placeholder_secret() {
+  case "$1" in
+    *dummy*|*Dummy*|*DUMMY*|*placeholder*|*Placeholder*|*PLACEHOLDER*|*changeme*|*CHANGE_ME*|*replace*me*|*Replace*Me*|*your*key*|*YOUR*KEY*|*api*key*here*|*API*KEY*HERE*|*token*here*|*TOKEN*HERE*)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+pluxx_prompt_secret_config() {
+  local env_var="$1"
+  local label="$2"
+  local required="$3"
+  local current_value="\${!env_var:-}"
+
+  if [[ -z "$current_value" && "$required" == "1" ]]; then
+    if [[ -t 0 || -r /dev/tty ]]; then
+      read -r -s -p "$label [$env_var]: " current_value </dev/tty
+      echo >/dev/tty
+    else
+      echo "Missing required config: export $env_var before running this installer." >&2
+      exit 1
+    fi
+  fi
+
+  if [[ -n "$current_value" ]] && pluxx_is_placeholder_secret "$current_value"; then
+    echo "Refusing placeholder-looking secret for $env_var. Set a real value and rerun the installer." >&2
+    exit 1
+  fi
+
+  export "$env_var=$current_value"
+}
+
+pluxx_prompt_text_config() {
+  local env_var="$1"
+  local label="$2"
+  local required="$3"
+  local current_value="\${!env_var:-}"
+
+  if [[ -z "$current_value" && "$required" == "1" ]]; then
+    if [[ -t 0 || -r /dev/tty ]]; then
+      read -r -p "$label [$env_var]: " current_value </dev/tty
+    else
+      echo "Missing required config: export $env_var before running this installer." >&2
+      exit 1
+    fi
+  fi
+
+  export "$env_var=$current_value"
+}
+
+${promptLines.join("\n")}
+
+export PLUXX_USER_CONFIG_SPEC
+export PLUXX_INSTALL_DIR="${installDirVariable}"
+
+node <<'NODE'
+const fs = require('fs')
+const path = require('path')
+
+const installDir = process.env.PLUXX_INSTALL_DIR
+const spec = JSON.parse(process.env.PLUXX_USER_CONFIG_SPEC || '[]')
+
+if (installDir && spec.length > 0) {
+  const env = {}
+  const values = {}
+
+  for (const entry of spec) {
+    const value = process.env[entry.envVar]
+    if (value === undefined || value === '') continue
+    values[entry.key] = value
+    env[entry.envVar] = value
+  }
+
+  fs.writeFileSync(
+    path.join(installDir, '.pluxx-user.json'),
+    JSON.stringify({ values, env }, null, 2) + '\\n',
+  )
+
+  const envScriptPath = path.join(installDir, 'scripts/check-env.sh')
+  if (fs.existsSync(envScriptPath)) {
+    fs.writeFileSync(
+      envScriptPath,
+      '#!/usr/bin/env bash\\nset -euo pipefail\\n# pluxx install materialized required config for this local plugin install.\\nexit 0\\n',
+    )
+  }
+
+  const materialize = (value) =>
+    typeof value === 'string'
+      ? value.replace(/\\$\\{([A-Za-z_][A-Za-z0-9_]*)\\}/g, (_match, name) => env[name] || '${" + name + "}')
+      : value
+
+  const materializeRecord = (record) => {
+    if (!record || typeof record !== 'object') return record
+    const next = {}
+    for (const [key, value] of Object.entries(record)) {
+      next[key] = materialize(value)
+    }
+    return next
+  }
+
+  for (const relativePath of ['.mcp.json', 'mcp.json']) {
+    const filepath = path.join(installDir, relativePath)
+    if (!fs.existsSync(filepath)) continue
+
+    const payload = JSON.parse(fs.readFileSync(filepath, 'utf8'))
+    for (const server of Object.values(payload.mcpServers || {})) {
+      if (!server || typeof server !== 'object') continue
+
+      if (server.env) {
+        server.env = materializeRecord(server.env)
+      }
+
+      if (server.bearer_token_env_var && env[server.bearer_token_env_var]) {
+        server.http_headers = {
+          ...(server.http_headers || {}),
+          Authorization: 'Bearer ' + env[server.bearer_token_env_var],
+        }
+        delete server.bearer_token_env_var
+      }
+
+      if (server.env_http_headers && typeof server.env_http_headers === 'object') {
+        server.http_headers = {
+          ...(server.http_headers || {}),
+        }
+        for (const [headerName, envVar] of Object.entries(server.env_http_headers)) {
+          if (env[envVar]) server.http_headers[headerName] = env[envVar]
+        }
+        delete server.env_http_headers
+      }
+
+      if (server.headers) {
+        server.headers = materializeRecord(server.headers)
+      }
+      if (server.http_headers) {
+        server.http_headers = materializeRecord(server.http_headers)
+      }
+    }
+
+    fs.writeFileSync(filepath, JSON.stringify(payload, null, 2) + '\\n')
+  }
+}
+NODE
+`;
+}
+function hasInstallerUserConfig(config, platform) {
+  return collectUserConfigEntries(config, [platform]).length > 0;
+}
 function renderInstallClaudeCodeScript(config) {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -19751,6 +20291,7 @@ need_cmd tar
 need_cmd mktemp
 need_cmd grep
 need_cmd sed
+${hasInstallerUserConfig(config, "claude-code") ? "need_cmd node" : ""}
 
 if [[ "$SKIP_INSTALL" != "1" ]]; then
   need_cmd curl
@@ -19787,6 +20328,7 @@ DESCRIPTION="$(grep -E '"description"' "$PLUGIN_MANIFEST" | head -n1 | sed -E 's
 mkdir -p "$INSTALL_ROOT/.claude-plugin" "$INSTALL_ROOT/plugins"
 rm -rf "$INSTALL_ROOT/plugins/$PLUGIN_NAME"
 cp -R "$BUNDLE_DIR" "$INSTALL_ROOT/plugins/$PLUGIN_NAME"
+${renderInstallerUserConfigSnippet(config, "claude-code", "$INSTALL_ROOT/plugins/$PLUGIN_NAME")}
 
 cat > "$INSTALL_ROOT/.claude-plugin/marketplace.json" <<JSON
 {
@@ -19850,6 +20392,7 @@ need_cmd() {
 need_cmd tar
 need_cmd mktemp
 need_cmd curl
+${hasInstallerUserConfig(config, "cursor") ? "need_cmd node" : ""}
 
 TMP_DIR="$(mktemp -d)"
 cleanup() {
@@ -19878,6 +20421,7 @@ fi
 mkdir -p "$(dirname "$INSTALL_DIR")"
 rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
+${renderInstallerUserConfigSnippet(config, "cursor", "$INSTALL_DIR")}
 
 echo "Installed $PLUGIN_NAME to $INSTALL_DIR"
 echo "If Cursor is already open, use Developer: Reload Window or restart Cursor so the plugin is picked up."
@@ -19935,6 +20479,7 @@ fi
 mkdir -p "$(dirname "$INSTALL_DIR")"
 rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
+${renderInstallerUserConfigSnippet(config, "codex", "$INSTALL_DIR")}
 
 mkdir -p "$(dirname "$MARKETPLACE_PATH")"
 
@@ -20049,6 +20594,7 @@ fi
 mkdir -p "$(dirname "$INSTALL_DIR")" "$SKILLS_ROOT"
 rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
+${renderInstallerUserConfigSnippet(config, "opencode", "$INSTALL_DIR")}
 
 export ENTRY_PATH
 export PLUGIN_NAME
@@ -20376,22 +20922,107 @@ function printJson(value) {
 }
 
 // src/cli/verify-install.ts
-import { existsSync as existsSync27 } from "fs";
+import { existsSync as existsSync27, lstatSync as lstatSync4, readdirSync as readdirSync11, readFileSync as readFileSync15, readlinkSync, realpathSync, statSync as statSync5 } from "fs";
 import { resolve as resolve21 } from "path";
 function buildCheckFromReport(target, pluginName, report) {
   const consumerPath = resolveInstalledConsumerPath(target, pluginName);
+  const staleReason = target.built && existsSync27(consumerPath) ? detectStaleInstall(target, pluginName, consumerPath) : void 0;
+  const stale = staleReason !== void 0;
   return {
     platform: target.platform,
     installPath: target.pluginDir,
     consumerPath,
     built: target.built,
     installed: existsSync27(consumerPath),
-    ok: report.errors === 0,
-    errors: report.errors,
+    stale,
+    ...staleReason ? { staleReason } : {},
+    ok: report.errors === 0 && !stale,
+    errors: report.errors + (stale ? 1 : 0),
     warnings: report.warnings,
     infos: report.infos
   };
 }
+function manifestPathForPlatform2(platform) {
+  switch (platform) {
+    case "claude-code":
+      return ".claude-plugin/plugin.json";
+    case "cursor":
+      return ".cursor-plugin/plugin.json";
+    case "codex":
+      return ".codex-plugin/plugin.json";
+    case "opencode":
+      return "package.json";
+    default:
+      return void 0;
+  }
+}
+function readInstalledManifestVersion(rootDir, platform) {
+  const manifestPath = manifestPathForPlatform2(platform);
+  if (!manifestPath) return void 0;
+  const filepath = resolve21(rootDir, manifestPath);
+  if (!existsSync27(filepath)) return void 0;
+  try {
+    const manifest = JSON.parse(readFileSync15(filepath, "utf-8"));
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function findCodexCacheCandidates(pluginName) {
+  const home = process.env.HOME ?? "~";
+  const cacheRoot = resolve21(home, ".codex/plugins/cache");
+  if (!existsSync27(cacheRoot)) return [];
+  const candidates = [];
+  for (const marketplace of readdirSync11(cacheRoot)) {
+    const pluginRoot = resolve21(cacheRoot, marketplace, pluginName);
+    if (!existsSync27(pluginRoot)) continue;
+    for (const versionDir of readdirSync11(pluginRoot)) {
+      const candidatePath = resolve21(pluginRoot, versionDir);
+      try {
+        const stats = statSync5(candidatePath);
+        if (!stats.isDirectory()) continue;
+        candidates.push({
+          path: candidatePath,
+          version: readInstalledManifestVersion(candidatePath, "codex") ?? versionDir,
+          mtimeMs: stats.mtimeMs
+        });
+      } catch {
+      }
+    }
+  }
+  return candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+function detectCodexCacheStaleness(pluginName, builtVersion) {
+  if (!builtVersion) return void 0;
+  const candidates = findCodexCacheCandidates(pluginName);
+  if (candidates.length === 0) return void 0;
+  if (candidates.some((candidate) => candidate.version === builtVersion)) return void 0;
+  const newest = candidates[0];
+  return `Codex active cache appears stale at ${newest.path}; cached version ${newest.version ?? "unknown"} does not match built version ${builtVersion}. Use Plugins > Refresh if available, or restart/reinstall Codex to load the current plugin bundle.`;
+}
+function detectStaleInstall(target, pluginName, consumerPath) {
+  try {
+    const details = lstatSync4(consumerPath);
+    if (details.isSymbolicLink()) {
+      const installedRealPath = realpathSync(consumerPath);
+      const builtRealPath = realpathSync(target.sourceDir);
+      if (installedRealPath !== builtRealPath) {
+        return `installed symlink points to ${readlinkSync(consumerPath)}, not the current build at ${target.sourceDir}`;
+      }
+    }
+  } catch {
+    return void 0;
+  }
+  const builtVersion = readInstalledManifestVersion(target.sourceDir, target.platform);
+  const installedVersion = readInstalledManifestVersion(consumerPath, target.platform);
+  if (builtVersion && installedVersion && builtVersion !== installedVersion) {
+    return `installed version ${installedVersion} does not match built version ${builtVersion}`;
+  }
+  if (target.platform === "codex") {
+    return detectCodexCacheStaleness(pluginName, builtVersion);
+  }
+  return void 0;
+}
 async function verifyInstall(config, options = {}) {
   const rootDir = options.rootDir ?? process.cwd();
   const distDir = resolve21(rootDir, config.outDir);
@@ -20419,12 +21050,39 @@ function printVerifyInstallResult(result) {
     console.log(`${prefix} ${check.platform}: ${check.consumerPath}`);
     console.log(`  install path: ${check.installPath}`);
     console.log(`  built: ${check.built ? "yes" : "no"}; installed: ${check.installed ? "yes" : "no"}; errors: ${check.errors}; warnings: ${check.warnings}; infos: ${check.infos}`);
+    if (check.stale) {
+      console.log(`  stale install: ${check.staleReason}`);
+    }
+    if (!check.ok) {
+      for (const action of getVerifyInstallRecoveryActions(check)) {
+        console.log(`  fix: ${action}`);
+      }
+    }
   }
   console.log(result.ok ? "pluxx verify-install passed." : "pluxx verify-install failed.");
 }
+function getVerifyInstallRecoveryActions(check) {
+  const actions = [];
+  if (!check.built) {
+    actions.push(`run pluxx build --target ${check.platform}`);
+  }
+  if (check.built && !check.installed) {
+    actions.push(`run pluxx install --target ${check.platform}${check.platform === "claude-code" ? " and accept/trust any hook prompt if expected" : ""}`);
+  }
+  if (check.stale) {
+    actions.push(`rerun pluxx install --target ${check.platform} to replace the stale local install`);
+    if (check.platform === "codex") {
+      actions.push("in Codex, use Plugins > Refresh if available, or restart Codex so the plugin cache reloads");
+    }
+  }
+  if (check.errors > 0 && actions.length === 0) {
+    actions.push(`run pluxx doctor --consumer "${check.consumerPath}" for the detailed host-specific failure`);
+  }
+  return actions;
+}
 
 // src/cli/behavioral.ts
-import { existsSync as existsSync28, readFileSync as readFileSync15 } from "fs";
+import { existsSync as existsSync28, readFileSync as readFileSync16 } from "fs";
 import { mkdtemp as mkdtemp2, rm as rm3 } from "fs/promises";
 import { tmpdir as tmpdir4 } from "os";
 import { resolve as resolve22 } from "path";
@@ -20466,7 +21124,7 @@ function loadBehavioralCases(rootDir, targets, promptOverride) {
       `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"));
+  const parsed = JSON.parse(readFileSync16(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.`);
   }
@@ -20576,7 +21234,7 @@ async function executeBehavioralCommand(platform, command2, cwd) {
       child.on("close", (code) => {
         const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
         const stderr = Buffer.concat(stderrChunks).toString("utf-8");
-        const codexMessage = codexLastMessagePath && existsSync28(codexLastMessagePath) ? readFileSync15(codexLastMessagePath, "utf-8") : "";
+        const codexMessage = codexLastMessagePath && existsSync28(codexLastMessagePath) ? readFileSync16(codexLastMessagePath, "utf-8") : "";
         resolvePromise({
           exitCode: code ?? 1,
           response: codexMessage.trim() || stdout.trim() || stderr.trim()
@@ -20639,7 +21297,7 @@ function shellQuote2(value) {
 }
 
 // src/cli/discover-installed-mcp.ts
-import { existsSync as existsSync29, readFileSync as readFileSync16 } from "fs";
+import { existsSync as existsSync29, readFileSync as readFileSync17 } from "fs";
 import { homedir as homedir2 } from "os";
 import { resolve as resolve23 } from "path";
 var INSTALLED_MCP_HOSTS = ["claude-code", "cursor", "codex", "opencode"];
@@ -20733,7 +21391,7 @@ function installedMcpFileCandidates(rootDir, homeDir) {
 }
 function parseJsonMcpFile(path, host) {
   try {
-    const raw = JSON.parse(readFileSync16(path, "utf-8"));
+    const raw = JSON.parse(readFileSync17(path, "utf-8"));
     const servers = extractJsonMcpServers(raw, path, host);
     return Object.entries(servers).flatMap(([serverName, config]) => {
       const normalized = normalizeCommonMcpServer(config, host);
@@ -20768,7 +21426,7 @@ function extractJsonMcpServers(raw, path, host) {
   return {};
 }
 function parseCodexTomlMcpFile(path) {
-  const text = readFileSync16(path, "utf-8");
+  const text = readFileSync17(path, "utf-8");
   const servers = {};
   let currentServer;
   let currentSubtable;
@@ -21141,7 +21799,7 @@ function isHelpRequested(input) {
 }
 function getCliPackageVersion() {
   const packageJsonPath = new URL("../../package.json", import.meta.url);
-  const raw = JSON.parse(readFileSync17(packageJsonPath, "utf-8"));
+  const raw = JSON.parse(readFileSync18(packageJsonPath, "utf-8"));
   if (typeof raw.version !== "string" || raw.version.trim() === "") {
     throw new Error("Unable to determine the installed pluxx version from package.json.");
   }
@@ -21253,20 +21911,21 @@ function planAutopilotPasses(input) {
   };
 }
 function countAutopilotSteps(input) {
-  return 2 + Number(input.taxonomy.enabled) + Number(input.instructions.enabled) + Number(input.review.enabled) + Number(input.verify);
+  return 2 + Number(input.taxonomy.enabled) + Number(input.instructions.enabled) + Number(input.review.enabled) + Number(input.verify) + Number(input.install) + Number(input.behavioral);
 }
 function formatAutopilotPassLine(label, decision) {
   return `${label}: ${decision.enabled ? "run" : "skip"} (${decision.reason})`;
 }
 function summarizeAutopilotWorkload(input) {
   const agentPassCount = Number(input.taxonomy.enabled) + Number(input.instructions.enabled) + Number(input.review.enabled);
+  const suffix = `${input.verify ? " + verification" : ""}${input.install ? " + install" : ""}${input.behavioral ? " + behavioral smoke" : ""}`;
   if (agentPassCount === 0 && !input.verify) {
-    return "deterministic scaffold only";
+    return `deterministic scaffold${input.install ? " + install" : ""}${input.behavioral ? " + behavioral smoke" : ""}`;
   }
   if (agentPassCount === 0) {
-    return "deterministic scaffold + verification";
+    return `deterministic scaffold${suffix}`;
   }
-  return `${agentPassCount} agent pass${agentPassCount === 1 ? "" : "es"}${input.verify ? " + verification" : ""}`;
+  return `${agentPassCount} agent pass${agentPassCount === 1 ? "" : "es"}${suffix}`;
 }
 function formatDuration(durationMs) {
   if (durationMs === void 0) {
@@ -21509,6 +22168,16 @@ function parseTargetFlagValues(rawArgs2) {
   if (!values) return void 0;
   return parseTargetPlatforms(values.join(","));
 }
+function parseInstallTargetFlag(rawArgs2, targets) {
+  const raw = readOption2(rawArgs2, "--install-target");
+  if (!raw) return [targets[0]];
+  const installTargets = parseTargetPlatforms(raw);
+  const unsupported = installTargets.filter((target) => !targets.includes(target));
+  if (unsupported.length > 0) {
+    throw new Error(`--install-target must be one of the configured autopilot targets: ${targets.join(", ")}`);
+  }
+  return installTargets;
+}
 function defaultHookMode(source) {
   if (source.auth?.type && source.auth.type !== "none" && source.auth.envVar) {
     return "safe";
@@ -22607,6 +23276,9 @@ async function runAutopilot() {
   const attach = readOption2(args, "--attach");
   const reviewRequested = args.includes("--review");
   const verify = !args.includes("--no-verify");
+  const installRequested = args.includes("--install");
+  const behavioralRequested = args.includes("--behavioral");
+  const behavioralPrompt = readOption2(args, "--behavioral-prompt");
   const verboseRunner = args.includes("--verbose-runner");
   const interactive = !runtime.jsonOutput && runtime.isInteractive && !initOptions.assumeDefaults;
   let authEnv = initOptions.authEnv;
@@ -22615,17 +23287,23 @@ async function runAutopilot() {
   let authTemplate = initOptions.authTemplate;
   let runtimeAuthMode = resolveRuntimeAuthMode(initOptions.runtimeAuth);
   if (!initOptions.source && !interactive) {
-    console.error(`Usage: pluxx autopilot --from-mcp <source> --runner <${AGENT_RUNNERS.join("|")}> [--mode <${AUTOPILOT_MODES.join("|")}>] [--name NAME] [--display-name NAME] [--author NAME] [--targets <platforms>] [--grouping workflow|tool] [--hooks none|safe] [--approve-mcp-tools] [--auth-env ENV] [--auth-type bearer|header|platform] [--auth-header NAME] [--auth-template TEMPLATE] [--runtime-auth inline|platform] [--oauth-wrapper] [--website URL] [--docs URL] [--ingest-provider <${AGENT_INGEST_PROVIDERS.join("|")}>] [--context <files...>] [--review] [--no-verify] [--verbose-runner] [--json] [--dry-run] [--quiet]`);
+    console.error(`Usage: pluxx autopilot --from-mcp <source> --runner <${AGENT_RUNNERS.join("|")}> [--mode <${AUTOPILOT_MODES.join("|")}>] [--name NAME] [--display-name NAME] [--author NAME] [--targets <platforms>] [--grouping workflow|tool] [--hooks none|safe] [--approve-mcp-tools] [--auth-env ENV] [--auth-type bearer|header|platform] [--auth-header NAME] [--auth-template TEMPLATE] [--runtime-auth inline|platform] [--oauth-wrapper] [--website URL] [--docs URL] [--ingest-provider <${AGENT_INGEST_PROVIDERS.join("|")}>] [--context <files...>] [--review] [--install] [--install-target <platform>] [--trust] [--behavioral] [--behavioral-prompt TEXT] [--no-verify] [--verbose-runner] [--json] [--dry-run] [--quiet]`);
     process.exit(1);
   }
   if ((!runnerRaw || !AGENT_RUNNERS.includes(runnerRaw)) && !interactive) {
-    console.error(`Usage: pluxx autopilot --from-mcp <source> --runner <${AGENT_RUNNERS.join("|")}> [--mode <${AUTOPILOT_MODES.join("|")}>] [--name NAME] [--display-name NAME] [--author NAME] [--targets <platforms>] [--grouping workflow|tool] [--hooks none|safe] [--approve-mcp-tools] [--auth-env ENV] [--auth-type bearer|header|platform] [--auth-header NAME] [--auth-template TEMPLATE] [--runtime-auth inline|platform] [--oauth-wrapper] [--website URL] [--docs URL] [--ingest-provider <${AGENT_INGEST_PROVIDERS.join("|")}>] [--context <files...>] [--review] [--no-verify] [--verbose-runner] [--json] [--dry-run] [--quiet]`);
+    console.error(`Usage: pluxx autopilot --from-mcp <source> --runner <${AGENT_RUNNERS.join("|")}> [--mode <${AUTOPILOT_MODES.join("|")}>] [--name NAME] [--display-name NAME] [--author NAME] [--targets <platforms>] [--grouping workflow|tool] [--hooks none|safe] [--approve-mcp-tools] [--auth-env ENV] [--auth-type bearer|header|platform] [--auth-header NAME] [--auth-template TEMPLATE] [--runtime-auth inline|platform] [--oauth-wrapper] [--website URL] [--docs URL] [--ingest-provider <${AGENT_INGEST_PROVIDERS.join("|")}>] [--context <files...>] [--review] [--install] [--install-target <platform>] [--trust] [--behavioral] [--behavioral-prompt TEXT] [--no-verify] [--verbose-runner] [--json] [--dry-run] [--quiet]`);
     process.exit(1);
   }
   if (modeRaw && !AUTOPILOT_MODES.includes(modeRaw)) {
     console.error(`Autopilot mode must be one of: ${AUTOPILOT_MODES.join(", ")}`);
     process.exit(1);
   }
+  if (installRequested && !verify) {
+    throw new Error("--install requires verification so autopilot can build outputs before installing. Remove --no-verify or omit --install.");
+  }
+  if (behavioralRequested && !installRequested) {
+    throw new Error("--behavioral requires --install so the selected host CLI can see the installed plugin bundle.");
+  }
   let tempDir;
   try {
     if (!runtime.jsonOutput && !runtime.quiet && interactive) {
@@ -22793,6 +23471,7 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
     const authorName = initOptions.author ?? (interactive ? await clackText("Author name", defaultAuthorName) : defaultAuthorName);
     const targetsRaw = initOptions.targets ?? (interactive ? await clackText("Platforms (comma-separated)", DEFAULT_INIT_TARGETS.join(",")) : DEFAULT_INIT_TARGETS.join(","));
     const targets = parseTargetPlatforms(targetsRaw);
+    const installTargets = installRequested ? parseInstallTargetFlag(args, targets) : [];
     const grouping = initOptions.grouping ? parseChoiceOption(initOptions.grouping, MCP_SKILL_GROUPINGS, "Skill grouping") : interactive ? await clackSelect("Skill grouping", [
       { value: "workflow", label: "workflow", hint: "Group related tools into workflow skills" },
       { value: "tool", label: "tool", hint: "One skill per tool" }
@@ -22822,7 +23501,9 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
       taxonomy: passDecisions.taxonomy,
       instructions: passDecisions.instructions,
       review: passDecisions.review,
-      verify
+      verify,
+      install: installRequested,
+      behavioral: behavioralRequested
     });
     const workspaceRoot = runtime.dryRun ? await mkdtemp3(`${tmpdir5()}/pluxx-autopilot-`) : process.cwd();
     tempDir = runtime.dryRun ? workspaceRoot : void 0;
@@ -22908,6 +23589,12 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
         quality,
         review: passDecisions.review.enabled,
         verify,
+        install: installRequested ? {
+          enabled: true,
+          platforms: installTargets,
+          notes: getInstallFollowupNotes(installTargets),
+          installTargets: []
+        } : void 0,
         steps: totalSteps,
         init: {
           createdFiles: initCreatedFiles,
@@ -22955,7 +23642,9 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
           taxonomy: passDecisions.taxonomy,
           instructions: passDecisions.instructions,
           review: passDecisions.review,
-          verify
+          verify,
+          install: installRequested,
+          behavioral: behavioralRequested
         })}`);
         console.log(`  Quality: ${quality.warnings} warning(s), ${quality.infos} info message(s)`);
         console.log(`  Scaffold create/update: ${[...initCreatedFiles, ...initUpdatedFiles].join(", ") || "none"}`);
@@ -22976,6 +23665,9 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
         } else {
           console.log("  Verification: skipped (--no-verify)");
         }
+        if (installRequested) {
+          console.log(`  Install: ${installTargets.join(", ")} after verification`);
+        }
       }
       return;
     }
@@ -23055,9 +23747,13 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
       });
       return result;
     })() : void 0;
-    const ok = (taxonomyResult?.ok ?? true) && (instructionsResult?.ok ?? true) && (reviewResult?.ok ?? true) && (verification?.ok ?? true);
-    const failureStage = taxonomyResult && taxonomyResult.runnerExitCode !== 0 ? "runner" : instructionsResult && instructionsResult.runnerExitCode !== 0 ? "runner" : reviewResult && reviewResult.runnerExitCode !== 0 ? "runner" : verification && !verification.ok ? "verification" : void 0;
-    const failureMessage = failureStage === "runner" ? "A headless runner command failed. Re-run with --verbose-runner to stream full runner output." : failureStage === "verification" ? "Verification failed after scaffold/refinement. Run `pluxx test` for details." : void 0;
+    const preInstallOk = (taxonomyResult?.ok ?? true) && (instructionsResult?.ok ?? true) && (reviewResult?.ok ?? true) && (verification?.ok ?? true);
+    const installedConfig = installRequested && preInstallOk ? await loadConfig() : void 0;
+    const install = installedConfig ? await maybeInstallBuiltOutputs(installedConfig, installTargets, { verifyConsumers: true }) : void 0;
+    const behavioralResult = install && install.verification?.ok && behavioralRequested ? await runBehavioralSuite(process.cwd(), installedConfig, installTargets, { promptOverride: behavioralPrompt }) : void 0;
+    const ok = preInstallOk && (install?.verification?.ok ?? true) && (behavioralResult?.ok ?? true);
+    const failureStage = taxonomyResult && taxonomyResult.runnerExitCode !== 0 ? "runner" : instructionsResult && instructionsResult.runnerExitCode !== 0 ? "runner" : reviewResult && reviewResult.runnerExitCode !== 0 ? "runner" : verification && !verification.ok ? "verification" : install?.verification && !install.verification.ok ? "verification" : behavioralResult && !behavioralResult.ok ? "verification" : void 0;
+    const failureMessage = failureStage === "runner" ? "A headless runner command failed. Re-run with --verbose-runner to stream full runner output." : failureStage === "verification" ? "Verification, install, or behavioral smoke failed after scaffold/refinement. Run `pluxx test --install` for details." : void 0;
     const summary = {
       ok,
       pluginName,
@@ -23119,6 +23815,8 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
       },
       verification,
       verificationDurationMs,
+      install,
+      behavioral: behavioralResult,
       failureStage,
       failureMessage
     };
@@ -23134,7 +23832,9 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
         taxonomy: passDecisions.taxonomy,
         instructions: passDecisions.instructions,
         review: passDecisions.review,
-        verify
+        verify,
+        install: installRequested,
+        behavioral: behavioralRequested
       })}`);
       console.log(`  Quality: ${quality.warnings} warning(s), ${quality.infos} info message(s)`);
       if (!verboseRunner) {
@@ -23157,6 +23857,23 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
       } else {
         console.log("  Verification: skipped (--no-verify)");
       }
+      if (install) {
+        console.log(`  Install: ${install.verification?.ok === false ? "failed" : "passed"} for ${install.platforms.join(", ")}`);
+        for (const target of install.installTargets) {
+          console.log(`    ${target.platform}: ${target.consumerPath}`);
+        }
+        if (install.verification) {
+          console.log(`  Verify-install: ${install.verification.ok ? "passed" : "failed"}`);
+        }
+        for (const note of install.notes) {
+          console.log(`  ${note}`);
+        }
+      } else if (installRequested) {
+        console.log(`  Install: skipped because verification did not produce a passing build`);
+      }
+      if (behavioralResult) {
+        console.log(`  Behavioral: ${behavioralResult.ok ? "passed" : "failed"}`);
+      }
       if (failureStage && failureMessage) {
         console.log(`  Failure stage: ${failureStage}`);
         console.log(`  Failure detail: ${failureMessage}`);
@@ -23165,6 +23882,9 @@ ${formatAuthRequiredMessage("autopilot", retryError, source)}`);
       console.log("  1. Review INSTRUCTIONS.md and skills/");
       console.log(`  2. Run: pluxx build${mode === "quick" && !passDecisions.taxonomy.enabled && !passDecisions.instructions.enabled && !passDecisions.review.enabled ? " (agent refinement was skipped; only do this if the deterministic scaffold already looks good)" : ""}`);
       console.log(`  3. Run: pluxx install${scaffoldPlan.generatedHookMode === "safe" ? " --trust" : ""} --target ${targets[0]}`);
+      if (!installRequested) {
+        console.log(`  Or rerun onboarding: pluxx autopilot --from-mcp "${rawSource}" --runner ${runner} --mode ${mode} --install --install-target ${targets[0]}${scaffoldPlan.generatedHookMode === "safe" ? " --trust" : ""}`);
+      }
     }
     if (!ok) {
       process.exit(1);
@@ -23489,6 +24209,10 @@ Common flags:
   --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
+  --install                               Install autopilot's verified build into one selected host
+  --install-target <platform>             Host to install after autopilot verification; defaults to the first target
+  --trust                                 Trust local hook commands during install/test flows
+  --behavioral                            Run installed headless example-query smoke checks
 
 Targets:
   claude-code, cursor, codex, opencode, github-copilot, openhands,
@@ -23531,6 +24255,8 @@ Examples:
   --attach is only supported for the opencode runner
   pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode quick --yes
   pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode standard --yes --name acme --display-name "Acme"
+  pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode standard --install --install-target codex --trust
+  pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode standard --auth-env API_KEY --auth-type bearer --install --install-target codex --trust
   pluxx autopilot --from-mcp https://example.com/mcp --runner codex --yes --approve-mcp-tools
   pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode thorough --yes --verbose-runner
   pluxx autopilot --from-mcp https://mcp.linear.app/mcp --runner codex --yes --oauth-wrapper