neon 6.2.4 → 6.3.0

package/README.md

@@ -792,7 +792,7 @@ Recommended installs the Neon plugin for every detected agent (global config, pr
 
 Unauthenticated `-y` skips linking and prints the next step: sign up at https://neon.com/signup, then `neon auth`, `neon link`, or `neon claim create` (no account, expires in 72 hours unless claimed). `-y` never opens a browser. `-y` with `--project-id` or other account flags links when the CLI is already signed in; otherwise it errors and names `neon auth` or `--claimable`.
 
-Custom asks how to add Neon to coding agents (plugin, skills and MCP separately, or skip), then how to get a project (sign in and link, or a claimable project when you are not signed in), then which services `neon.ts` should declare. Postgres is listed first as always included. The package manager is inferred from the directory; Custom asks only when none is detected. `--skill` selects skills (not the plugin) and skips that picker. MCP flags (`--mcp-config-location`, `--mcp-auth`, `--mcp-project-scoped`) select skills and MCP. `--mcp-config-location` is where the config is written: `global` maps to `neon mcp`, and `project` maps to `neon mcp --project`. With `-y`, the location defaults to `global`; interactive Custom asks. If some selected agents cannot write that location, init warns and skips MCP for those agents while continuing with the supported agents. It fails when none of the selected agents support the location. `--mcp-project-scoped` limits MCP tools to the linked Neon project by passing its ID to `neon mcp --project-id`. Omitted is false, including in Custom; there is no prompt. `--no-agent-setup` skips agent setup.
+Custom asks how to add Neon to coding agents (plugin, skills and MCP separately, or skip), then how to get a project (sign in and link, or a claimable project when you are not signed in), then which services `neon.ts` should declare. Skills and MCP use separate agent pickers, and either can be skipped. Postgres is listed first as always included. The package manager is inferred from the directory; Custom asks only when none is detected. `--skill` selects skills (not the plugin) and skips that picker. MCP flags (`--mcp-config-location`, `--mcp-auth`, `--mcp-project-scoped`) select skills and MCP. `--mcp-config-location` is where the config is written: `global` maps to `neon mcp`, and `project` maps to `neon mcp --project`. With `-y`, the location defaults to `global`; interactive Custom asks. If some selected agents cannot write that location, init warns and skips MCP for those agents while continuing with the supported agents. It fails when none of the selected agents support the location. `--mcp-project-scoped` limits MCP tools to the linked Neon project by passing its ID to `neon mcp --project-id`. Omitted is false, including in Custom; there is no prompt. `--no-agent-setup` skips agent setup.
 
 Empty directories are set up in place. `neon init` does not scaffold starter files.
 

package/dist/commands/mcp.js

@@ -6,10 +6,11 @@ import { getCliName } from "../utils/cli_name.js";
 import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { writer } from "../writer.js";
 import { noPassthrough, single } from "../utils/flags.js";
+import { AGENT_MCP_SKIP_MESSAGE } from "../init/copy.js";
 import { NEON_MCP_CATEGORIES, NEON_MCP_URL, existingNeonApiKey, installNeonMcpServer, neonMcpUrl, parseMcpCategories, trackedProjectMcpConfig } from "../mcp/install.js";
 import { mcpInstallableAgents, resolveInstallTargets } from "../mcp/targets.js";
 import { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey } from "../mcp/mint.js";
-import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { canPickAgentsInteractively, skippableAgentPicker } from "../utils/agent_picker.js";
 import { resolveMcpPlan } from "../mcp/plan.js";
 //#region src/commands/mcp.ts
 var mcp_exports = /* @__PURE__ */ __exportAll({
@@ -113,7 +114,8 @@ const setupNeonMcp = async (options) => {
 		readOnly: options.readOnly === true,
 		projectId: options.projectId,
 		categories: options.category ?? [],
-		linkedProjectId
+		linkedProjectId,
+		pickAgents: skippableAgentPicker(options.allowAgentSkip, AGENT_MCP_SKIP_MESSAGE)
 	});
 	const { install, skipped } = resolveInstallTargets({
 		agents: plan.agents,

package/dist/commands/plugins.js

@@ -4,11 +4,12 @@ import { recordCommandSuccessExtras } from "../analytics.js";
 import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { writer } from "../writer.js";
 import { noPassthrough } from "../utils/flags.js";
+import { AGENT_PLUGIN_SKIP_MESSAGE } from "../init/copy.js";
 import { getAgentDisplayName } from "../mcp/agents.js";
 import { NEON_MCP_URL } from "../mcp/install.js";
 import "../init/agents.js";
 import { pluginsInstallableAgents } from "../plugins/targets.js";
-import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { canPickAgentsInteractively, skippableAgentPicker } from "../utils/agent_picker.js";
 import { resolvePluginsPlan } from "../plugins/plan.js";
 import { NEON_PLUGIN_NAME, PLUGIN_SKILLS, PLUGIN_SOURCE, neonPluginsRetryCommand, pluginsAddArgs, runPluginsCli } from "../plugins/run.js";
 //#region src/commands/plugins.ts
@@ -71,10 +72,12 @@ const installPlugins = async (options) => {
 		agents: options.agents ?? [],
 		yes,
 		cwd,
-		interactive
+		interactive,
+		pickAgents: skippableAgentPicker(options.allowAgentSkip, AGENT_PLUGIN_SKIP_MESSAGE)
 	});
 	for (const agent of plan.skipped) log.warning("Skipping %s: no plugins mapping.", getAgentDisplayName(agent));
 	for (const agent of plan.userScopeSkipped) log.warning("Skipping %s: plugins are user-level. Pass --global.", getAgentDisplayName(agent));
+	for (const { agent, command } of plan.missingCommands) log.warning("Skipping %s: the plugin installs through \"%s\", which was not found on PATH.", getAgentDisplayName(agent), command);
 	const rows = [];
 	const failed = [];
 	const scope = scopeLabel(plan.scope);
@@ -147,7 +150,8 @@ const reportPluginsInstall = (props, outcome) => {
 		title: "Plugins"
 	});
 	out.end();
-	if (outcome.failed.length === 0) log.info(outcome.scope === "project" ? "Installed the Neon plugin (project)." : "Installed the Neon plugin (user).");
+	if (outcome.rows.length === 0) log.info("No Neon plugins installed.");
+	else if (outcome.failed.length === 0) log.info(outcome.scope === "project" ? "Installed the Neon plugin (project)." : "Installed the Neon plugin (user).");
 };
 const handler = async (props) => {
 	const outcome = await installPlugins({

package/dist/commands/skills.js

@@ -4,10 +4,11 @@ import { recordCommandSuccessExtras } from "../analytics.js";
 import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { writer } from "../writer.js";
 import { noPassthrough } from "../utils/flags.js";
+import { AGENT_SKILLS_SKIP_MESSAGE } from "../init/copy.js";
 import { getAgentDisplayName } from "../mcp/agents.js";
 import "../init/agents.js";
 import { mappedSkillsAgentNames, skillsInstallableAgents } from "../skills/targets.js";
-import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { canPickAgentsInteractively, skippableAgentPicker } from "../utils/agent_picker.js";
 import { skillsHelpValues, skillsYesHelp } from "../skills/catalog.js";
 import { confirmSkillsUpdate } from "../skills/wizard.js";
 import { assertSkillsCanRun, resolveSkillsPlan } from "../skills/plan.js";
@@ -102,7 +103,8 @@ const installSkills = async (options) => {
 		skills: options.skills ?? [],
 		yes,
 		cwd,
-		interactive
+		interactive,
+		pickAgents: skippableAgentPicker(options.allowAgentSkip, AGENT_SKILLS_SKIP_MESSAGE)
 	});
 	const mapped = mappedSkillsAgentNames(plan.agents);
 	for (const agent of plan.skipped) log.warning("Skipping %s: no skills mapping.", getAgentDisplayName(agent));

package/dist/index.js

@@ -1,6 +1,6 @@
 import { log } from "./log.js";
 import pkg_default from "./pkg.js";
-import { isNeonApiError, messageFromBody } from "./api.js";
+import { codeFromBody, isNeonApiError, messageFromBody } from "./api.js";
 import { getAuthContext } from "./auth_context.js";
 import { r as defaultDir } from "./_chunks/paths-DMq0Lt7a.js";
 import { ensureConfigDir } from "./config.js";
@@ -14,6 +14,7 @@ import { recoverFrom401 } from "./auth_recovery.js";
 import { showHelp } from "./help.js";
 import { rewriteUnknownAgentArg } from "./init/plan.js";
 import commands_default from "./commands/index.js";
+import { recoverFromSSO } from "./sso_recovery.js";
 import { notifyIfUpdateAvailable } from "./update_notifier.js";
 import { fillInArgs, resolveApiKeyFromEnv } from "./utils/middlewares.js";
 import yargs from "yargs";
@@ -165,6 +166,10 @@ async function handleError(msg, err, canRetry) {
 			log.error("Request timed out");
 			sendError(err, "REQUEST_TIMEOUT");
 			return false;
+		} else if (codeFromBody(err.data) === "SSO_AUTHORIZATION_REQUIRED" || codeFromBody(err.data) === "SSO_ORG_CREDS_ONLY") {
+			if (await recoverFromSSO(err, canRetry)) return true;
+			sendError(err, "AUTH_FAILED");
+			return false;
 		} else if (err.status === 401) {
 			sendError(err, "AUTH_FAILED");
 			return await recoverFrom401(canRetry);

package/dist/init/chrome.js

@@ -49,6 +49,8 @@ const printInitDone = (text) => {
 const agentSetupLabel = (setup) => {
 	if (setup === "plugin") return "plugin";
 	if (setup === "skills-mcp") return "skills and MCP";
+	if (setup === "skills") return "skills";
+	if (setup === "mcp") return "MCP";
 	return "skipped";
 };
 const agentSetupDoneLabel = (input) => {
@@ -56,13 +58,31 @@ const agentSetupDoneLabel = (input) => {
 	return agentSetupLabel(input.setup);
 };
 const formatAgentIds = (agents) => agents.join(", ");
+const SETUP_LABELS = {
+	skip: "skipped",
+	plugin: "Neon plugin",
+	skills: "skills",
+	"skills-mcp": "skills and MCP",
+	mixed: "plugin and skills/MCP"
+};
+/** Names the agents behind each mechanism, since init picks skills and MCP agents separately. */
 const agentsRowValue = (input) => {
-	if (input.setup === null || input.setup === "skip") return "skipped";
-	if (input.setup === "skills") return "default Neon skills in this directory";
-	const ids = formatAgentIds(input.agents);
-	if (input.setup === "plugin") return ids.length > 0 ? `Neon plugin: ${ids}` : "Neon plugin";
-	if (input.setup === "skills-mcp") return ids.length > 0 ? `skills and MCP: ${ids}` : "skills and MCP";
-	return ids.length > 0 ? `plugin and skills/MCP: ${ids}` : "plugin and skills/MCP";
+	const { tooling } = input;
+	const parts = [];
+	const add = (label, ids) => {
+		const ran = ids.filter((id) => input.installed.includes(id));
+		if (ran.length > 0) parts.push(`${label}: ${formatAgentIds(ran)}`);
+	};
+	if (tooling.setup === "plugin" || tooling.setup === "skills") add(SETUP_LABELS[tooling.setup], tooling.agents);
+	else if (tooling.setup === "skills-mcp" || tooling.setup === "mixed") {
+		if (tooling.setup === "mixed") add("Neon plugin", tooling.pluginAgents);
+		if (tooling.skillsAgents.length === tooling.mcpAgents.length && tooling.skillsAgents.every((id) => tooling.mcpAgents.includes(id))) add("skills and MCP", tooling.skillsAgents);
+		else {
+			add("skills", tooling.skillsAgents);
+			add("MCP", tooling.mcpAgents);
+		}
+	}
+	return parts.length > 0 ? parts.join("; ") : SETUP_LABELS[tooling.setup];
 };
 const projectRowValue = (link) => {
 	switch (link) {

package/dist/init/copy.js

@@ -16,6 +16,12 @@ const AGENT_SETUP_SKIP_DESCRIPTION = "Continue to project setup without changing
 const AGENT_PICKER_MESSAGE = "Which coding agents should receive Neon tooling? (space to toggle, enter to confirm)";
 const AGENT_DETECTED_DESCRIPTION = "Detected on this machine or in this directory.";
 const AGENT_OTHER_DESCRIPTION = "Install for this agent.";
+const agentMissingCommandDescription = (command) => `Detected, but "${command}" was not found on PATH. Its plugin cannot install.`;
+const AGENT_PLUGIN_SKIP_MESSAGE = "No agents selected. Continue without installing the Neon plugin?";
+const AGENT_SKILLS_PICKER_MESSAGE = "Which coding agents should receive Neon skills? (space to toggle, enter to confirm)";
+const AGENT_MCP_PICKER_MESSAGE = "Which coding agents should receive the Neon MCP server? (space to toggle, enter to confirm)";
+const AGENT_SKILLS_SKIP_MESSAGE = "No agents selected. Continue without installing Neon skills?";
+const AGENT_MCP_SKIP_MESSAGE = "No agents selected. Continue without configuring the Neon MCP server?";
 const SKILLS_PICKER_MESSAGE = "Which Neon skills should be installed? (space to toggle, enter to confirm)";
 const MCP_SCOPE_MESSAGE = "Where should the Neon MCP server be configured?";
 const MCP_SCOPE_GLOBAL_TITLE = "User configuration";
@@ -130,4 +136,4 @@ const headingForOutcome = (outcome) => {
 	}
 };
 //#endregion
-export { AGENT_DETECTED_DESCRIPTION, AGENT_OTHER_DESCRIPTION, AGENT_PICKER_MESSAGE, AGENT_SETUP_MESSAGE, AGENT_SETUP_PLUGIN_DESCRIPTION, AGENT_SETUP_PLUGIN_TITLE, AGENT_SETUP_SKILLS_DESCRIPTION, AGENT_SETUP_SKILLS_TITLE, AGENT_SETUP_SKIP_DESCRIPTION, AGENT_SETUP_SKIP_TITLE, CANCELLED_BODY, CLAIMABLE_ACCOUNT_FLAGS, CLAIMABLE_ALREADY_LINKED, CLAIMABLE_MCP_API_KEY, CLAIMABLE_NO_LINK, CONFIG_CONFIRM_HINT, CONFIG_CONFIRM_MESSAGE, HEADING_CANCELLED, HEADING_COMPLETE, HEADING_FAILED, HEADING_PENDING, INIT_SUBTITLE, MCP_AUTH_API_KEY_DESCRIPTION, MCP_AUTH_API_KEY_TITLE, MCP_AUTH_MESSAGE, MCP_AUTH_OAUTH_DESCRIPTION, MCP_AUTH_OAUTH_TITLE, MCP_SCOPED_NEEDS_PROJECT, MCP_SCOPE_GLOBAL_DESCRIPTION, MCP_SCOPE_GLOBAL_TITLE, MCP_SCOPE_MESSAGE, MCP_SCOPE_PROJECT_DESCRIPTION, MCP_SCOPE_PROJECT_TITLE, MODE_CUSTOM_DESCRIPTION, MODE_CUSTOM_TITLE, MODE_MESSAGE, MODE_RECOMMENDED_DESCRIPTION, MODE_RECOMMENDED_TITLE, NON_TTY_AGENT_SETUP, NON_TTY_LINK_NEEDS_AUTH, NO_AGENTS_FALLBACK_STATUS, NO_AGENT_SETUP_CONFLICT, PACKAGE_MANAGER_MESSAGE, PROGRESS, PROJECT_SETUP_CLAIMABLE_DESCRIPTION, PROJECT_SETUP_CLAIMABLE_TITLE, PROJECT_SETUP_LINK_DESCRIPTION, PROJECT_SETUP_LINK_TITLE, PROJECT_SETUP_MESSAGE, SERVICES_HINT, SERVICES_MESSAGE, SKILLS_PICKER_MESSAGE, YES_LINK_NEEDS_AUTH, claimableNext, claimableThenServicesNext, envPullFailedNext, existingConfigNext, extraServicesNext, headingForOutcome, installFailedNext, mcpConfigLocationSkipped, mcpConfigLocationUnavailable, namedAgentsUnavailable, skippedLinkNext, unattendedUnauthedNext };
+export { AGENT_DETECTED_DESCRIPTION, AGENT_MCP_PICKER_MESSAGE, AGENT_MCP_SKIP_MESSAGE, AGENT_OTHER_DESCRIPTION, AGENT_PICKER_MESSAGE, AGENT_PLUGIN_SKIP_MESSAGE, AGENT_SETUP_MESSAGE, AGENT_SETUP_PLUGIN_DESCRIPTION, AGENT_SETUP_PLUGIN_TITLE, AGENT_SETUP_SKILLS_DESCRIPTION, AGENT_SETUP_SKILLS_TITLE, AGENT_SETUP_SKIP_DESCRIPTION, AGENT_SETUP_SKIP_TITLE, AGENT_SKILLS_PICKER_MESSAGE, AGENT_SKILLS_SKIP_MESSAGE, CANCELLED_BODY, CLAIMABLE_ACCOUNT_FLAGS, CLAIMABLE_ALREADY_LINKED, CLAIMABLE_MCP_API_KEY, CLAIMABLE_NO_LINK, CONFIG_CONFIRM_HINT, CONFIG_CONFIRM_MESSAGE, HEADING_CANCELLED, HEADING_COMPLETE, HEADING_FAILED, HEADING_PENDING, INIT_SUBTITLE, MCP_AUTH_API_KEY_DESCRIPTION, MCP_AUTH_API_KEY_TITLE, MCP_AUTH_MESSAGE, MCP_AUTH_OAUTH_DESCRIPTION, MCP_AUTH_OAUTH_TITLE, MCP_SCOPED_NEEDS_PROJECT, MCP_SCOPE_GLOBAL_DESCRIPTION, MCP_SCOPE_GLOBAL_TITLE, MCP_SCOPE_MESSAGE, MCP_SCOPE_PROJECT_DESCRIPTION, MCP_SCOPE_PROJECT_TITLE, MODE_CUSTOM_DESCRIPTION, MODE_CUSTOM_TITLE, MODE_MESSAGE, MODE_RECOMMENDED_DESCRIPTION, MODE_RECOMMENDED_TITLE, NON_TTY_AGENT_SETUP, NON_TTY_LINK_NEEDS_AUTH, NO_AGENTS_FALLBACK_STATUS, NO_AGENT_SETUP_CONFLICT, PACKAGE_MANAGER_MESSAGE, PROGRESS, PROJECT_SETUP_CLAIMABLE_DESCRIPTION, PROJECT_SETUP_CLAIMABLE_TITLE, PROJECT_SETUP_LINK_DESCRIPTION, PROJECT_SETUP_LINK_TITLE, PROJECT_SETUP_MESSAGE, SERVICES_HINT, SERVICES_MESSAGE, SKILLS_PICKER_MESSAGE, YES_LINK_NEEDS_AUTH, agentMissingCommandDescription, claimableNext, claimableThenServicesNext, envPullFailedNext, existingConfigNext, extraServicesNext, headingForOutcome, installFailedNext, mcpConfigLocationSkipped, mcpConfigLocationUnavailable, namedAgentsUnavailable, skippedLinkNext, unattendedUnauthedNext };

package/dist/init/mode.js

@@ -18,10 +18,8 @@ const assertAgentSetupFlags = (input) => {
 };
 const inferInitAgentSetup = (input) => {
 	if (input.skipAgents) return { kind: "skip" };
-	const hasSkills = hasSkillsFlag(input.skills);
-	if (hasSkills && input.hasMcpFlags) return { kind: "skills-mcp" };
-	if (hasSkills) return { kind: "skills" };
 	if (input.hasMcpFlags) return { kind: "skills-mcp" };
+	if (hasSkillsFlag(input.skills)) return { kind: "skills" };
 	if (input.namedAgents || input.yes) return { kind: "auto" };
 	if (input.canAsk) return { kind: "ask" };
 	throw new Error(NON_TTY_AGENT_SETUP);

package/dist/init/plan.js

@@ -201,8 +201,9 @@ const chooseYesAgentTooling = (agents) => {
 	};
 };
 const FALLBACK_SKILLS_AGENTS = ["cursor", "codex"];
-const splitInitTooling = (agents, pluginScope, mcpConfigLocation = pluginScope) => {
-	const pluginSet = new Set(pluginsInstallableAgents(pluginScope));
+const splitInitTooling = (agents, pluginScope, mcpConfigLocation = pluginScope, unavailablePluginAgents = []) => {
+	const unavailable = new Set(unavailablePluginAgents);
+	const pluginSet = new Set(pluginsInstallableAgents(pluginScope).filter((id) => !unavailable.has(id)));
 	const mcpSet = new Set(mcpInstallableAgents(mcpConfigLocation));
 	const pluginAgents = uniqueAgentIds(agents.filter((id) => pluginSet.has(id)));
 	const rest = uniqueAgentIds(agents.filter((id) => !pluginSet.has(id)));
@@ -226,8 +227,8 @@ const splitInitTooling = (agents, pluginScope, mcpConfigLocation = pluginScope)
 		mcpAgents
 	};
 };
-const recommendedTooling = (detected) => {
-	const split = splitInitTooling(detected, "global");
+const recommendedTooling = (detected, unavailablePluginAgents = []) => {
+	const split = splitInitTooling(detected, "global", "global", unavailablePluginAgents);
 	if (split.setup === "skip") return {
 		setup: "skills",
 		agents: FALLBACK_SKILLS_AGENTS
@@ -297,7 +298,12 @@ const planInitToolingSteps = (input) => {
 		default: return input.tooling;
 	}
 };
-const funnelAgentSetup = (tooling) => tooling.setup;
+const funnelAgentSetup = (tooling) => {
+	if (tooling.setup !== "skills-mcp") return tooling.setup;
+	if (tooling.skillsAgents.length === 0) return "mcp";
+	if (tooling.mcpAgents.length === 0) return "skills";
+	return "skills-mcp";
+};
 const planYesAgentSteps = (tooling) => planToolingSteps(tooling, {
 	yes: true,
 	named: false

package/dist/init/run.js

@@ -13,8 +13,9 @@ import { agentsRowValue, configRowValue, formatInitDone, headingForKind, printIn
 import { inferPackageManager, resolvePackageManager } from "../utils/package_manager.js";
 import { ConfigInstallFailed, hasNeonConfigFile, initCmd, neonConfigFilename } from "../commands/config.js";
 import { runAuthenticatedLink } from "./link.js";
+import { getAgentDisplayName } from "../mcp/agents.js";
 import { mcpInstallableAgents } from "../mcp/targets.js";
-import { pluginsInstallableAgents } from "../plugins/targets.js";
+import { missingPluginsCommands, pluginsInstallableAgents } from "../plugins/targets.js";
 import { skillsInstallableAgents } from "../skills/targets.js";
 import { FALLBACK_SKILLS_AGENTS, assertNamedAgentTooling, funnelAgentSetup, planInitToolingSteps, recommendedTooling, resolveNamedAgents, splitInitTooling } from "./plan.js";
 import { pullInitEnv } from "./auth.js";
@@ -56,11 +57,10 @@ const pluginScopeFor = (agents, preferred) => {
 	const project = new Set(pluginsInstallableAgents("project"));
 	return agents.some((id) => !project.has(id) && pluginsInstallableAgents("global").includes(id)) ? "global" : "project";
 };
-const availableForSetup = (setup, scope) => {
-	if (setup === "plugin") return pluginsInstallableAgents(scope);
-	if (setup === "skip") return [];
-	if (setup === "skills") return [...skillsInstallableAgents()];
-	return [.../* @__PURE__ */ new Set([...skillsInstallableAgents(), ...mcpInstallableAgents(scope === "project" ? "project" : "global")])];
+const warnMissingPluginCommands = (missing, tooling) => {
+	if (tooling.setup !== "skills-mcp" && tooling.setup !== "mixed") return;
+	const routed = /* @__PURE__ */ new Set([...tooling.skillsAgents, ...tooling.mcpAgents]);
+	for (const { agent, command } of missing) if (routed.has(agent)) log.warning("%s: \"%s\" was not found on PATH, so its plugin cannot install. Installing Neon skills and MCP instead.", getAgentDisplayName(agent), command);
 };
 const nonEmptyAgents = (ids, fallback) => {
 	const [first, ...rest] = ids;
@@ -75,14 +75,15 @@ const skillsTooling = (ids, fallback) => {
 		agents
 	};
 };
-const skillsMcpTooling = (ids, scope, fallback) => {
-	const mcpConfigLocation = scope === "project" ? "project" : "global";
-	let selected = ids;
-	if (selected.length === 0 && fallback) selected = FALLBACK_SKILLS_AGENTS;
+const skillsMcpTooling = (skillsSelection, mcpSelection, mcpConfigLocation, fallback) => {
+	const useFallback = fallback && skillsSelection?.length === 0 && mcpSelection?.length === 0;
+	const selectedSkills = (useFallback ? FALLBACK_SKILLS_AGENTS : skillsSelection ?? []).filter((id) => skillsInstallableAgents().includes(id));
+	const selectedMcp = (useFallback ? FALLBACK_SKILLS_AGENTS : mcpSelection ?? []).filter((id) => mcpInstallableAgents(mcpConfigLocation).includes(id));
+	if (selectedMcp.length === 0) return skillsTooling(selectedSkills, false);
 	return {
 		setup: "skills-mcp",
-		skillsAgents: selected.filter((id) => skillsInstallableAgents().includes(id)),
-		mcpAgents: selected.filter((id) => mcpInstallableAgents(mcpConfigLocation).includes(id))
+		skillsAgents: selectedSkills,
+		mcpAgents: selectedMcp
 	};
 };
 const validateMcpConfigLocationSupport = (ids, location) => {
@@ -103,13 +104,18 @@ const pickOrDetectAgents = async (input) => {
 		return selected;
 	}
 	const detected = input.detected.filter((id) => input.available.includes(id));
+	const preselected = (input.preselected ?? input.detected).filter((id) => input.available.includes(id));
 	if (input.pickAgents !== void 0) return input.pickAgents({
 		available: [...input.available],
-		detected
+		detected: preselected,
+		setup: input.setup
 	});
 	if (input.interactive) return pickInitAgentsInteractively({
 		available: [...input.available],
-		detected
+		detected,
+		preselected,
+		...input.missingCommands !== void 0 ? { missingCommands: input.missingCommands } : {},
+		setup: input.setup
 	});
 	return detected;
 };
@@ -229,7 +235,9 @@ const runInit = async (props) => {
 		}
 		const recommended = mode === "recommended";
 		const targets = named.length > 0 ? named : detection.detectedAgents;
-		let agentSetupChoice = "plugin";
+		const missingPluginCommands = missingPluginsCommands(targets, { cwd });
+		const unavailablePluginAgents = missingPluginCommands.map((row) => row.agent);
+		const pluginReady = (agents) => agents.filter((id) => !unavailablePluginAgents.includes(id));
 		let tooling = { setup: "skip" };
 		let mcpAuth = props.mcpAuth;
 		let mcpConfigLocation = props.mcpConfigLocation ?? "global";
@@ -238,9 +246,9 @@ const runInit = async (props) => {
 		let pluginScope = recommended ? "global" : "project";
 		if (recommended) {
 			pluginScope = "global";
-			tooling = named.length > 0 ? splitInitTooling(named, "global") : recommendedTooling(detection.detectedAgents);
+			tooling = named.length > 0 ? splitInitTooling(named, "global", "global", unavailablePluginAgents) : recommendedTooling(detection.detectedAgents, unavailablePluginAgents);
 			if (named.length === 0 && detection.detectedAgents.length === 0) printInitProgress(NO_AGENTS_FALLBACK_STATUS);
-			agentSetupChoice = funnelAgentSetup(tooling);
+			warnMissingPluginCommands(missingPluginCommands, tooling);
 			mcpAuth = !detection.authenticated && (tooling.setup === "skills-mcp" || tooling.setup === "mixed") ? "oauth" : mcpAuth;
 		} else {
 			const inferred = inferInitAgentSetup({
@@ -251,53 +259,58 @@ const runInit = async (props) => {
 				canAsk: detection.interactive || props.pickAgentSetup !== void 0,
 				...props.skill !== void 0 ? { skills: props.skill } : {}
 			});
-			if (inferred.kind === "skip") {
-				tooling = { setup: "skip" };
-				agentSetupChoice = "skip";
-			} else if (inferred.kind === "auto") {
+			if (inferred.kind === "skip") tooling = { setup: "skip" };
+			else if (inferred.kind === "auto") {
 				const autoAgents = named.length > 0 ? named : detection.detectedAgents;
-				pluginScope = pluginScopeFor(autoAgents, "project");
-				tooling = splitInitTooling(autoAgents, pluginScope, mcpConfigLocation);
+				pluginScope = pluginScopeFor(pluginReady(autoAgents), "project");
+				tooling = splitInitTooling(autoAgents, pluginScope, mcpConfigLocation, unavailablePluginAgents);
+				warnMissingPluginCommands(missingPluginCommands, tooling);
 				if (tooling.setup === "skip" && yes && named.length === 0) {
 					tooling = recommendedTooling([]);
 					printInitProgress(NO_AGENTS_FALLBACK_STATUS);
 				}
-				agentSetupChoice = funnelAgentSetup(tooling);
 			} else {
 				const setup = inferred.kind === "ask" ? await (props.pickAgentSetup ?? pickAgentSetupInteractively)() : inferred.kind;
-				agentSetupChoice = setup === "skills" ? "skills" : setup;
 				if (setup !== "skip") {
 					pluginScope = pluginScopeFor(targets, "project");
-					const available = setup === "plugin" ? uniqueAgents([...pluginsInstallableAgents("project"), ...pluginsInstallableAgents("global")]) : availableForSetup(setup, pluginScope);
-					const selected = await pickOrDetectAgents({
+					const namedFallback = named.length === 0;
+					const pickAgents = (setup, available) => pickOrDetectAgents({
 						named,
 						available,
 						detected: detection.detectedAgents,
+						...setup === "plugin" ? {
+							preselected: pluginReady(detection.detectedAgents),
+							missingCommands: missingPluginCommands
+						} : {},
 						interactive: detection.interactive,
-						...props.pickAgents !== void 0 ? { pickAgents: props.pickAgents } : {}
+						setup,
+						pickAgents: props.pickAgents
 					});
-					const namedFallback = named.length === 0;
-					if (setup === "plugin") {
-						pluginScope = pluginScopeFor(selected, pluginScope);
-						tooling = splitInitTooling(selected, pluginScope);
-						if (tooling.setup !== "plugin" && tooling.setup !== "skip") tooling = splitInitTooling(selected.filter((id) => pluginsInstallableAgents(pluginScope).includes(id)), pluginScope);
-						agentSetupChoice = funnelAgentSetup(tooling);
-					} else if (setup === "skills") {
-						tooling = skillsTooling(selected, namedFallback);
-						agentSetupChoice = funnelAgentSetup(tooling);
+					if (setup === "plugin" || setup === "skills") {
+						const selected = await pickAgents(setup, setup === "plugin" ? uniqueAgents([...pluginsInstallableAgents("project"), ...pluginsInstallableAgents("global")]) : [...skillsInstallableAgents()]);
+						if (selected === void 0) tooling = { setup: "skip" };
+						else if (setup === "plugin") {
+							pluginScope = pluginScopeFor(selected, pluginScope);
+							tooling = splitInitTooling(selected.filter((id) => pluginsInstallableAgents(pluginScope).includes(id)), pluginScope);
+						} else tooling = skillsTooling(selected, namedFallback);
 					} else {
-						if (selectedSkills === void 0 && inferred.kind === "ask") selectedSkills = props.pickSkills !== void 0 ? await props.pickSkills() : detection.interactive ? await pickInitSkillsInteractively() : void 0;
-						mcpConfigLocation = props.mcpConfigLocation ?? (yes ? "global" : props.pickMcpConfigLocation !== void 0 ? await props.pickMcpConfigLocation() : detection.interactive ? await pickInitMcpConfigLocationInteractively() : "global");
-						mcpAuth = props.mcpAuth ?? (yes ? detection.authenticated && props.claimable !== true ? "api-key" : "oauth" : props.pickMcpAuth !== void 0 ? await props.pickMcpAuth({ authenticated: detection.authenticated }) : detection.interactive ? await pickInitMcpAuthInteractively({ authenticated: detection.authenticated }) : detection.authenticated && props.claimable !== true ? "api-key" : "oauth");
-						validateMcpConfigLocationSupport(selected, mcpConfigLocation);
-						tooling = skillsMcpTooling(selected, mcpConfigLocation, namedFallback);
-						agentSetupChoice = "skills-mcp";
+						const skillsAvailable = skillsInstallableAgents();
+						const skillsSelection = named.length > 0 ? named.filter((id) => skillsAvailable.includes(id)) : await pickAgents("skills", skillsAvailable);
+						if (skillsSelection !== void 0 && selectedSkills === void 0 && inferred.kind === "ask") selectedSkills = props.pickSkills !== void 0 ? await props.pickSkills() : detection.interactive ? await pickInitSkillsInteractively() : void 0;
+						const mcpSelection = named.length > 0 ? named : await pickAgents("mcp", mcpInstallableAgents("global"));
+						if (mcpSelection !== void 0) {
+							mcpConfigLocation = props.mcpConfigLocation ?? (yes ? "global" : props.pickMcpConfigLocation !== void 0 ? await props.pickMcpConfigLocation() : detection.interactive ? await pickInitMcpConfigLocationInteractively() : "global");
+							if (mcpSelection.length > 0) validateMcpConfigLocationSupport(mcpSelection, mcpConfigLocation);
+							const pickAuth = props.pickMcpAuth ?? (detection.interactive ? pickInitMcpAuthInteractively : void 0);
+							mcpAuth = props.mcpAuth ?? (yes ? void 0 : await pickAuth?.({ authenticated: detection.authenticated })) ?? (detection.authenticated && props.claimable !== true ? "api-key" : "oauth");
+						}
+						tooling = skillsMcpTooling(skillsSelection, mcpSelection, mcpConfigLocation, namedFallback);
 					}
 				}
 			}
 		}
-		funnel.agentSetup = agentSetupChoice === "plugin" || agentSetupChoice === "skills-mcp" || agentSetupChoice === "skills" || agentSetupChoice === "mixed" || agentSetupChoice === "skip" ? agentSetupChoice : funnelAgentSetup(tooling);
-		const usesMcp = tooling.setup === "skills-mcp" || tooling.setup === "mixed";
+		funnel.agentSetup = funnelAgentSetup(tooling);
+		const usesMcp = (tooling.setup === "skills-mcp" || tooling.setup === "mixed") && tooling.mcpAgents.length > 0;
 		if (mcpAuth === void 0 && usesMcp && (!detection.authenticated || props.claimable === true)) mcpAuth = "oauth";
 		delayMcp = usesMcp && (mcpAuth === "api-key" || props.mcpProjectScoped === true);
 		const mcpOauth = mcpAuth === "oauth";
@@ -355,7 +368,7 @@ const runInit = async (props) => {
 			funnel.link = "skipped";
 		} else if (props.pickProjectSetup !== void 0 || detection.interactive) projectSetup = await (props.pickProjectSetup ?? pickInitProjectSetupInteractively)();
 		else throw new Error(NON_TTY_LINK_NEEDS_AUTH);
-		if (mcpAuth === "api-key" && (projectSetup === "claimable" || props.claimable === true)) throw new Error(CLAIMABLE_MCP_API_KEY);
+		if (usesMcp && mcpAuth === "api-key" && (projectSetup === "claimable" || props.claimable === true)) throw new Error(CLAIMABLE_MCP_API_KEY);
 		if (projectSetup === "claimable") {
 			printInitProgress(PROGRESS.claim);
 			await (props.createClaimable ?? defaultCreateClaimable)({
@@ -529,8 +542,8 @@ const runInit = async (props) => {
 					{
 						label: "Agents",
 						value: agentsRowValue({
-							setup: funnel.agentSetup,
-							agents: funnel.agentsInstalled
+							tooling,
+							installed: funnel.agentsInstalled
 						})
 					},
 					{
@@ -578,8 +591,8 @@ const runInit = async (props) => {
 				{
 					label: "Agents",
 					value: agentsRowValue({
-						setup: funnel.agentSetup,
-						agents: funnel.agentsInstalled
+						tooling,
+						installed: funnel.agentsInstalled
 					})
 				},
 				{

package/dist/init/tooling.js

@@ -3,7 +3,7 @@ import { getCliName } from "../utils/cli_name.js";
 import { PROGRESS } from "./copy.js";
 import { assertNamedAgentTooling, chooseYesAgentTooling, collectYesAgents, initYesSupportedAgents, noDetectedAgentsMessage, planAgentSteps, planToolingSteps, planYesAgentSteps, resolveInitAgentSetup } from "./plan.js";
 import { detectAgent } from "./detect_host.js";
-import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { AgentSelectionSkipped, canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { mcpInstallError, reportMcpInstall } from "../commands/mcp.js";
 import { installPlugins, pluginsInstallError, reportPluginsInstall } from "../commands/plugins.js";
 import { installSkills, reportSkillsInstall, skillsInstallError } from "../commands/skills.js";
@@ -66,45 +66,61 @@ const runToolingSteps = async (steps, options) => {
 		...options.operations
 	};
 	const reportProps = { output: options.output };
+	const sharedOptions = {
+		cwd: options.cwd,
+		allowAgentSkip: options.allowAgentSkip
+	};
+	const completed = [];
 	for (const step of steps) {
 		const label = options.narrate === "human" ? TOOLING_STEP_LABELS[step.kind] : void 0;
 		if (label !== void 0) process.stdout.write(`${label}\n`);
 		else log.info("Running `%s %s`", getCliName(), toolingStepCommandText(step));
 		log.debug("Running `%s %s`", getCliName(), toolingStepCommandText(step));
-		switch (step.kind) {
-			case "plugins": {
-				const outcome = await raceSigint(ops.installPlugins({
-					...step.options,
-					cwd: options.cwd
-				}));
-				reportPluginsInstall(reportProps, outcome);
-				const error = pluginsInstallError(outcome);
-				if (error) throw error;
-				break;
-			}
-			case "skills": {
-				const outcome = await raceSigint(ops.installSkills({
-					...step.options,
-					cwd: options.cwd
-				}));
-				reportSkillsInstall(reportProps, outcome);
-				const error = skillsInstallError(outcome);
-				if (error) throw error;
-				break;
+		try {
+			switch (step.kind) {
+				case "plugins": {
+					const outcome = await raceSigint(ops.installPlugins({
+						...step.options,
+						...sharedOptions
+					}));
+					reportPluginsInstall(reportProps, outcome);
+					const error = pluginsInstallError(outcome);
+					if (error) throw error;
+					break;
+				}
+				case "skills": {
+					const outcome = await raceSigint(ops.installSkills({
+						...step.options,
+						...sharedOptions
+					}));
+					reportSkillsInstall(reportProps, outcome);
+					const error = skillsInstallError(outcome);
+					if (error) throw error;
+					break;
+				}
+				case "mcp": {
+					const outcome = await raceSigint(ops.installMcp({
+						...step.options,
+						...sharedOptions
+					}));
+					reportMcpInstall(reportProps, outcome);
+					const error = mcpInstallError(outcome);
+					if (error) throw error;
+					break;
+				}
+				default: return step;
 			}
-			case "mcp": {
-				const outcome = await raceSigint(ops.installMcp({
-					...step.options,
-					cwd: options.cwd
-				}));
-				reportMcpInstall(reportProps, outcome);
-				const error = mcpInstallError(outcome);
-				if (error) throw error;
-				break;
-			}
-			default: return step;
+			completed.push(step.kind);
+		} catch (error) {
+			if (!(error instanceof AgentSelectionSkipped)) throw error;
 		}
 	}
+	return completed;
+};
+const agentSetupResult = (setup, completed) => {
+	if (completed.length === 0) return "skip";
+	if (setup === "skills-mcp" && completed.length === 1) return completed[0] === "skills" ? "skills" : "mcp";
+	return setup;
 };
 const yesAgentsFromOptions = async (options) => collectYesAgents({
 	detected: () => (options.detectProjectAgents ?? defaultProjectAgents)(options.cwd),
@@ -119,47 +135,44 @@ const yesMiss = () => new Error(noDetectedAgentsMessage({
 const runAgentTooling = async (options) => {
 	const yes = options.yes;
 	const named = options.agents ?? [];
+	const runSetup = async (setup, steps) => agentSetupResult(setup, await runToolingSteps(steps, {
+		...options,
+		allowAgentSkip: !yes
+	}));
 	if (named.length > 0) {
 		assertNamedAgentTooling(named, options.command ?? "init");
 		const tooling = chooseYesAgentTooling(named);
-		await runToolingSteps(planToolingSteps(tooling, {
+		return runSetup(tooling.setup, planToolingSteps(tooling, {
 			yes,
 			named: true
-		}), options);
-		return tooling.setup;
-	}
-	if (options.agentSetup !== void 0) {
-		await runToolingSteps(planAgentSteps({
-			yes,
-			agentSetup: options.agentSetup
-		}), options);
-		return options.agentSetup;
+		}));
 	}
+	if (options.agentSetup !== void 0) return runSetup(options.agentSetup, planAgentSteps({
+		yes,
+		agentSetup: options.agentSetup
+	}));
 	if (yes) {
 		if (options.hasProjectPlugins !== void 0) {
 			const agentSetup = await options.hasProjectPlugins(options.cwd) ? "plugin" : "skills-mcp";
-			await runToolingSteps(planAgentSteps({
+			return runSetup(agentSetup, planAgentSteps({
 				yes: true,
 				agentSetup
-			}), options);
-			return agentSetup;
+			}));
 		}
 		const agents = await yesAgentsFromOptions(options);
 		const tooling = chooseYesAgentTooling(agents);
 		if (tooling.setup === "skip") throw yesMiss();
-		await runToolingSteps(planYesAgentSteps(tooling), options);
-		return tooling.setup;
+		return runSetup(tooling.setup, planYesAgentSteps(tooling));
 	}
 	const interactive = options.pickAgentSetup !== void 0 || canPickAgentsInteractively();
 	const agentSetup = await resolveInitAgentSetup({
 		interactive,
 		pick: options.pickAgentSetup ?? pickAgentSetupInteractively
 	});
-	await runToolingSteps(planAgentSteps({
+	return runSetup(agentSetup, planAgentSteps({
 		yes,
 		agentSetup
-	}), options);
-	return agentSetup;
+	}));
 };
 //#endregion
 export { runAgentTooling, runToolingSteps };

package/dist/init/wizard.js

@@ -1,10 +1,10 @@
 import { CONFIG_INIT_SERVICES } from "../config_template.js";
-import { AGENT_DETECTED_DESCRIPTION, AGENT_OTHER_DESCRIPTION, AGENT_PICKER_MESSAGE, AGENT_SETUP_MESSAGE, AGENT_SETUP_PLUGIN_DESCRIPTION, AGENT_SETUP_PLUGIN_TITLE, AGENT_SETUP_SKILLS_DESCRIPTION, AGENT_SETUP_SKILLS_TITLE, AGENT_SETUP_SKIP_DESCRIPTION, AGENT_SETUP_SKIP_TITLE, CONFIG_CONFIRM_HINT, CONFIG_CONFIRM_MESSAGE, MCP_AUTH_API_KEY_DESCRIPTION, MCP_AUTH_API_KEY_TITLE, MCP_AUTH_MESSAGE, MCP_AUTH_OAUTH_DESCRIPTION, MCP_AUTH_OAUTH_TITLE, MCP_SCOPE_GLOBAL_DESCRIPTION, MCP_SCOPE_GLOBAL_TITLE, MCP_SCOPE_MESSAGE, MCP_SCOPE_PROJECT_DESCRIPTION, MCP_SCOPE_PROJECT_TITLE, MODE_CUSTOM_DESCRIPTION, MODE_CUSTOM_TITLE, MODE_MESSAGE, MODE_RECOMMENDED_DESCRIPTION, MODE_RECOMMENDED_TITLE, PACKAGE_MANAGER_MESSAGE, PROJECT_SETUP_CLAIMABLE_DESCRIPTION, PROJECT_SETUP_CLAIMABLE_TITLE, PROJECT_SETUP_LINK_DESCRIPTION, PROJECT_SETUP_LINK_TITLE, PROJECT_SETUP_MESSAGE, SERVICES_HINT, SERVICES_MESSAGE, SKILLS_PICKER_MESSAGE } from "./copy.js";
+import { AGENT_DETECTED_DESCRIPTION, AGENT_MCP_PICKER_MESSAGE, AGENT_MCP_SKIP_MESSAGE, AGENT_OTHER_DESCRIPTION, AGENT_PICKER_MESSAGE, AGENT_PLUGIN_SKIP_MESSAGE, AGENT_SETUP_MESSAGE, AGENT_SETUP_PLUGIN_DESCRIPTION, AGENT_SETUP_PLUGIN_TITLE, AGENT_SETUP_SKILLS_DESCRIPTION, AGENT_SETUP_SKILLS_TITLE, AGENT_SETUP_SKIP_DESCRIPTION, AGENT_SETUP_SKIP_TITLE, AGENT_SKILLS_PICKER_MESSAGE, AGENT_SKILLS_SKIP_MESSAGE, CONFIG_CONFIRM_HINT, CONFIG_CONFIRM_MESSAGE, MCP_AUTH_API_KEY_DESCRIPTION, MCP_AUTH_API_KEY_TITLE, MCP_AUTH_MESSAGE, MCP_AUTH_OAUTH_DESCRIPTION, MCP_AUTH_OAUTH_TITLE, MCP_SCOPE_GLOBAL_DESCRIPTION, MCP_SCOPE_GLOBAL_TITLE, MCP_SCOPE_MESSAGE, MCP_SCOPE_PROJECT_DESCRIPTION, MCP_SCOPE_PROJECT_TITLE, MODE_CUSTOM_DESCRIPTION, MODE_CUSTOM_TITLE, MODE_MESSAGE, MODE_RECOMMENDED_DESCRIPTION, MODE_RECOMMENDED_TITLE, PACKAGE_MANAGER_MESSAGE, PROJECT_SETUP_CLAIMABLE_DESCRIPTION, PROJECT_SETUP_CLAIMABLE_TITLE, PROJECT_SETUP_LINK_DESCRIPTION, PROJECT_SETUP_LINK_TITLE, PROJECT_SETUP_MESSAGE, SERVICES_HINT, SERVICES_MESSAGE, SKILLS_PICKER_MESSAGE, agentMissingCommandDescription } from "./copy.js";
 import { installedPackageManagers } from "../utils/package_manager.js";
 import { POSTGRES_SERVICE_CHOICE, keepPostgresSelected } from "../utils/service_picker.js";
 import { getAgentDisplayName, listMcpAgentIds } from "../mcp/agents.js";
 import { INIT_NEEDS_YES_OR_TERMINAL } from "./plan.js";
-import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { canPickAgentsInteractively, pickAgentsInteractively } from "../utils/agent_picker.js";
 import { NEON_SKILL_CATALOG, listSkillIds } from "../skills/catalog.js";
 import { InitCancelled, restoreCursorVisibilityOnAbort } from "./cancelled.js";
 import chalk from "chalk";
@@ -71,24 +71,23 @@ const pickAgentSetupInteractively = async () => {
 };
 const pickInitAgentsInteractively = async (input) => {
 	requireInteractive();
-	if (input.available.length === 0) throw new Error("No coding agents are available to pick.");
 	const detected = new Set(input.detected);
-	const { agents } = await prompts({
-		onState: restoreCursorOnAbort,
-		type: "multiselect",
-		name: "agents",
-		message: AGENT_PICKER_MESSAGE,
-		instructions: false,
-		min: 1,
-		choices: input.available.map((id) => ({
-			value: id,
-			title: `${getAgentDisplayName(id)} (${id})`,
-			description: detected.has(id) ? AGENT_DETECTED_DESCRIPTION : AGENT_OTHER_DESCRIPTION,
-			selected: detected.has(id)
-		}))
+	const missing = new Map((input.missingCommands ?? []).map((row) => [row.agent, row.command]));
+	const selected = await pickAgentsInteractively({
+		onCancel: aborted,
+		message: input.setup === "skills" ? AGENT_SKILLS_PICKER_MESSAGE : input.setup === "mcp" ? AGENT_MCP_PICKER_MESSAGE : AGENT_PICKER_MESSAGE,
+		skipMessage: input.setup === "plugin" ? AGENT_PLUGIN_SKIP_MESSAGE : input.setup === "skills" ? AGENT_SKILLS_SKIP_MESSAGE : AGENT_MCP_SKIP_MESSAGE,
+		selected: input.preselected ?? input.detected,
+		choices: input.available.map((id) => {
+			const command = missing.get(id);
+			return {
+				id,
+				title: `${getAgentDisplayName(id)} (${id})`,
+				description: command !== void 0 ? agentMissingCommandDescription(command) : detected.has(id) ? AGENT_DETECTED_DESCRIPTION : AGENT_OTHER_DESCRIPTION
+			};
+		})
 	});
-	if (!Array.isArray(agents)) return aborted();
-	return agents.filter((id) => typeof id === "string");
+	return selected.length > 0 ? selected : void 0;
 };
 const pickInitSkillsInteractively = async () => {
 	requireInteractive();

package/dist/plugins/plan.js

@@ -1,14 +1,19 @@
 import { getAgentDisplayName, tryResolveAddMcpAgentId } from "../mcp/agents.js";
 import "../init/agents.js";
-import { detectPluginsAgents, getPluginsTargetName, isUserScopeOnlyPluginsTarget, mappedPluginsTargets, pluginsInstallableAgents } from "./targets.js";
+import { detectPluginsAgents, getPluginsTargetName, isUserScopeOnlyPluginsTarget, mappedPluginsTargets, missingPluginsCommands, pluginsInstallableAgents } from "./targets.js";
 import { collectYesAgents, noDetectedAgentsMessage } from "../init/plan.js";
 import { detectAgent } from "../init/detect_host.js";
 import { agentChoicesFrom, pickAgentsInteractively, resolveAgentSelection } from "../utils/agent_picker.js";
 //#region src/plugins/plan.ts
+const missingPluginsCommandsError = (missing) => new Error(missing.map(({ agent, command }) => `Cannot install the Neon plugin for ${getAgentDisplayName(agent)}: "${command}" was not found on PATH. Install it or add it to PATH, then retry.`).join("\n"));
 const assertPluginsCanRun = (options) => {
 	if (options.yes || options.interactive || options.hasAgents) return;
 	throw new Error("No interactive terminal. Pass -y to install into detected agents, or --agent <name> to name them.");
 };
+const commandLookup = (options) => ({
+	cwd: options.cwd,
+	...options.commandPath !== void 0 ? { path: options.commandPath } : {}
+});
 async function resolvePluginsPlan(options) {
 	assertPluginsCanRun({
 		yes: options.yes,
@@ -29,10 +34,18 @@ async function resolvePluginsPlan(options) {
 		detectAgent: options.detectAgent ?? detectAgent,
 		acceptHost: (id) => availableSet.has(id) || getPluginsTargetName(id) !== void 0
 	}) : scoped;
+	const missingDetected = new Map((prompt ? missingPluginsCommands(detected, commandLookup(options)) : []).map((row) => [row.agent, row.command]));
+	const choices = agentChoicesFrom(available, detected).map((choice) => {
+		const command = missingDetected.get(choice.id);
+		return command === void 0 ? choice : {
+			...choice,
+			description: `detected, but "${command}" is not on PATH`
+		};
+	});
 	const selected = await resolveAgentSelection({
 		specified: options.agents,
-		choices: agentChoicesFrom(available, detected),
-		detected,
+		choices,
+		detected: detected.filter((id) => !missingDetected.has(id)),
 		message: "Which coding agents should get the Neon plugin? (space to toggle, enter to confirm)",
 		nonInteractiveMessage: noDetectedAgentsMessage({
 			scope,
@@ -64,6 +77,20 @@ async function resolvePluginsPlan(options) {
 		}
 		agents.push(id);
 	}
+	const missingCommands = missingPluginsCommands(agents, commandLookup(options));
+	if (missingCommands.length > 0) {
+		if (!(options.agents.length === 0 && !prompt)) throw missingPluginsCommandsError(missingCommands);
+		const missingAgents = new Set(missingCommands.map((row) => row.agent));
+		const installable = agents.filter((id) => !missingAgents.has(id));
+		return {
+			scope,
+			agents: installable,
+			skipped,
+			userScopeSkipped,
+			missingCommands,
+			targets: installable.length === 0 ? [] : mappedPluginsTargets(installable, scope)
+		};
+	}
 	if (agents.length === 0) {
 		if (userScopeSkipped.length > 0 && skipped.length === 0) {
 			const names = userScopeSkipped.map((id) => getAgentDisplayName(id)).join(", ");
@@ -76,8 +103,9 @@ async function resolvePluginsPlan(options) {
 		agents,
 		skipped,
 		userScopeSkipped,
+		missingCommands,
 		targets: mappedPluginsTargets(agents, scope)
 	};
 }
 //#endregion
-export { assertPluginsCanRun, resolvePluginsPlan };
+export { assertPluginsCanRun, missingPluginsCommandsError, resolvePluginsPlan };

package/dist/plugins/targets.js

@@ -1,27 +1,67 @@
 import { detectInstalledAgents, listMcpAgentIds, tryResolveAddMcpAgentId, uniqueAgentIds } from "../mcp/agents.js";
 import "../init/agents.js";
+import { delimiter, dirname, join, resolve } from "node:path";
+import which from "which";
 import { detectProjectAgents } from "add-mcp";
 //#region src/plugins/targets.ts
+const CLAUDE_CODE = { target: "claude-code" };
 const PLUGINS_TARGET_BY_TYPE = {
-	cursor: "cursor",
-	vscode: "vscode",
-	"claude-code": "claude-code",
-	"claude-desktop": "claude-code",
-	codex: "codex",
-	"github-copilot-cli": "github-copilot",
-	"grok-build": "grok"
+	cursor: { target: "cursor" },
+	vscode: { target: "vscode" },
+	"claude-code": CLAUDE_CODE,
+	"claude-desktop": CLAUDE_CODE,
+	codex: { target: "codex" },
+	"github-copilot-cli": {
+		target: "github-copilot",
+		command: "copilot"
+	},
+	"grok-build": {
+		target: "grok",
+		command: "grok"
+	}
 };
+const pluginsTargets = () => [...new Set(Object.values(PLUGINS_TARGET_BY_TYPE))];
 const USER_SCOPE_ONLY_TARGETS = /* @__PURE__ */ new Set([
 	"vscode",
 	"github-copilot",
 	"grok"
 ]);
-function getPluginsTargetName(agent) {
+/** npx runs the plugins CLI with every `node_modules/.bin` from `cwd` up to the root ahead of PATH. */
+const pluginsCommandSearchPath = (cwd, path) => {
+	const bins = [];
+	let dir = resolve(cwd);
+	for (;;) {
+		bins.push(join(dir, "node_modules", ".bin"));
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return [...bins, path].join(delimiter);
+};
+const missingPluginsCommands = (agents, options) => {
+	const searchPath = pluginsCommandSearchPath(options.cwd, options.path ?? process.env.PATH ?? "");
+	const missing = [];
+	for (const agent of uniqueAgentIds(agents)) {
+		const command = getPluginsTarget(agent)?.command;
+		if (command !== void 0 && which.sync(command, {
+			nothrow: true,
+			path: searchPath
+		}) === null) missing.push({
+			agent,
+			command
+		});
+	}
+	return missing;
+};
+function getPluginsTarget(agent) {
 	if (Object.prototype.hasOwnProperty.call(PLUGINS_TARGET_BY_TYPE, agent)) return PLUGINS_TARGET_BY_TYPE[agent];
 	const id = tryResolveAddMcpAgentId(agent);
 	if (!id) return void 0;
 	return PLUGINS_TARGET_BY_TYPE[id];
 }
+function getPluginsTargetName(agent) {
+	return getPluginsTarget(agent)?.target;
+}
 function supportsPlugins(agent) {
 	return getPluginsTargetName(agent) !== void 0;
 }
@@ -65,4 +105,4 @@ const mappedPluginsTargets = (agents, scope) => {
 	return mapped;
 };
 //#endregion
-export { detectInstallablePluginsAgents, detectPluginsAgents, getPluginsTargetName, isUserScopeOnlyPluginsTarget, mappedPluginsTargets, pluginsInstallableAgents, pluginsMappedAgents, supportsPlugins };
+export { detectInstallablePluginsAgents, detectPluginsAgents, getPluginsTargetName, isUserScopeOnlyPluginsTarget, mappedPluginsTargets, missingPluginsCommands, pluginsInstallableAgents, pluginsMappedAgents, pluginsTargets, supportsPlugins };

package/dist/sso_recovery.js

@@ -0,0 +1,92 @@
+import { isCi } from "./env.js";
+import { log } from "./log.js";
+import { codeFromBody } from "./api.js";
+import open from "open";
+import prompts from "prompts";
+//#region src/sso_recovery.ts
+/**
+* Extract the SSO step-up URL from the error message.
+*
+* The Neon public API carries the recovery URL in the human-readable `message`
+* ("...Open <url> in your browser to authorize, then retry."), not a structured field — so this
+* works against the API's standard error shape without a bespoke contract.
+*/
+function extractStepUpUrl(message) {
+	if (typeof message !== "string") return;
+	const match = message.match(/(https?:\/\/[^\s)]+)/);
+	return match ? match[1] : void 0;
+}
+/**
+* Whether the invocation opted out of prompts via --yes/-y.
+*
+* The skip-prompts flag is per-command in this CLI (link, projects update, init, …), not a global
+* option, so — exactly like the --help/-h check in the error handler — detect it from argv rather than
+* a parsed global. A run that documented itself as non-interactive (`neon link -y`) must take the
+* unattended path, never open a browser or block on a confirm.
+*/
+function promptsSkipped() {
+	return process.argv.includes("--yes") || process.argv.includes("-y");
+}
+/** Whether this process can drive an interactive open-browser-then-confirm-and-retry flow. */
+function canInteract() {
+	return !isCi() && !promptsSkipped() && Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY);
+}
+/**
+* Recover from an SSO authorization error.
+*
+* Detection is by the machine `code` in the response body, NOT the HTTP status: Neon masks org
+* access-denials as 404 (existence-hiding), so the error arrives as 403 or 404 with the code in the
+* body.
+*   - SSO_AUTHORIZATION_REQUIRED: the user must complete a one-time SSO authorization in a browser.
+*     On an interactive terminal we open the step-up URL and wait for the user to confirm they've
+*     finished before signalling a retry. Unattended (CI, no TTY, or an explicit --yes/-y that opted
+*     out of prompts) we print the URL and fail, since no browser round-trip is possible.
+*   - SSO_ORG_CREDS_ONLY: terminal — no browser step resolves it; the user must use an
+*     organization-scoped API key. Return false (no retry).
+*
+* @param error   the API error
+* @param canRetry whether the caller is willing to retry (false once we've already retried)
+* @returns true if the caller should retry the command, false otherwise
+*/
+const recoverFromSSO = async (error, canRetry) => {
+	const code = codeFromBody(error.data);
+	if (code === "SSO_ORG_CREDS_ONLY") {
+		log.error(error.message);
+		return false;
+	}
+	if (code !== "SSO_AUTHORIZATION_REQUIRED") return false;
+	if (!canRetry) {
+		log.error(error.message);
+		return false;
+	}
+	const stepUpUrl = extractStepUpUrl(error.message);
+	if (!stepUpUrl) {
+		log.error(error.message);
+		return false;
+	}
+	if (!canInteract()) {
+		log.error("This organization requires a one-time SSO authorization, which needs an interactive browser session. Open this URL in a browser to authorize, then re-run the command:\n" + stepUpUrl);
+		return false;
+	}
+	log.info(`This organization requires SSO authorization. Opening your browser to authorize; if it doesn't open, visit this URL manually:\n${stepUpUrl}`);
+	try {
+		(await open(stepUpUrl)).once("error", (err) => {
+			log.warning(`Could not launch a browser automatically: ${err.message}`);
+		});
+	} catch {
+		log.warning("Could not launch a browser automatically; open the URL above manually.");
+	}
+	const { confirmed } = await prompts({
+		type: "confirm",
+		name: "confirmed",
+		message: "Press Enter once you've completed authorization in the browser to retry (or 'n' to cancel)",
+		initial: true
+	});
+	if (confirmed !== true) {
+		log.error(`SSO authorization was not completed. Re-run the command after authorizing at:\n${stepUpUrl}`);
+		return false;
+	}
+	return true;
+};
+//#endregion
+export { recoverFromSSO };

package/dist/utils/agent_picker.js

@@ -2,40 +2,66 @@ import { isCi } from "../env.js";
 import { getAgentDisplayName, resolveAddMcpAgentId, uniqueAgentIds } from "../mcp/agents.js";
 import prompts from "prompts";
 //#region src/utils/agent_picker.ts
+var AgentSelectionSkipped = class extends Error {};
 const canPickAgentsInteractively = () => !isCi() && Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY);
+const restoreCursorOnAbort = (exit) => (state) => {
+	if (state.aborted) {
+		process.stdout.write("\x1B[?25h");
+		process.stdout.write("\n");
+		if (exit) process.exit(1);
+	}
+};
 const pickAgentsInteractively = async (options) => {
 	if (!canPickAgentsInteractively()) throw new Error("No interactive terminal. Pass -y, or run this command in a terminal to pick agents.");
 	if (options.choices.length === 0) throw new Error("No coding agents are available to pick.");
+	const cancel = options.onCancel ?? (() => {
+		throw new Error("Aborted: no agents selected.");
+	});
+	const onState = restoreCursorOnAbort(options.onCancel === void 0);
 	const selected = new Set(options.selected ?? []);
-	const { agents } = await prompts({
-		onState: (state) => {
-			if (state.aborted) {
-				process.stdout.write("\x1B[?25h");
-				process.stdout.write("\n");
-				process.exit(1);
-			}
-		},
+	const question = {
+		onState,
 		type: "multiselect",
 		name: "agents",
 		message: options.message,
 		instructions: false,
-		min: 1,
+		min: options.skipMessage ? 0 : 1,
 		choices: options.choices.map((choice) => ({
 			value: choice.id,
 			title: choice.title,
 			description: choice.description,
 			selected: selected.has(choice.id)
 		}))
-	});
-	if (!Array.isArray(agents)) throw new Error("Aborted: no agents selected.");
-	const picked = [];
-	for (const value of agents) {
-		const id = agentIdInChoices(value, options.choices);
-		if (id === void 0) throw new Error(`Unknown agent: "${String(value)}".`);
-		picked.push(id);
+	};
+	while (true) {
+		const { agents } = await prompts(question);
+		if (!Array.isArray(agents)) return cancel();
+		const picked = [];
+		for (const value of agents) {
+			const id = agentIdInChoices(value, options.choices);
+			if (id === void 0) throw new Error(`Unknown agent: "${String(value)}".`);
+			picked.push(id);
+		}
+		if (picked.length > 0 || !options.skipMessage) return uniqueAgentIds(picked);
+		const { skip } = await prompts({
+			onState,
+			type: "confirm",
+			name: "skip",
+			message: options.skipMessage,
+			initial: true
+		});
+		if (typeof skip !== "boolean") return cancel();
+		if (skip) return [];
 	}
-	return uniqueAgentIds(picked);
 };
+const skippableAgentPicker = (allowed, message) => allowed ? async (options) => {
+	const selected = await pickAgentsInteractively({
+		...options,
+		skipMessage: message
+	});
+	if (selected.length === 0) throw new AgentSelectionSkipped();
+	return selected;
+} : void 0;
 const resolveAgentSelection = async (options) => {
 	if (options.specified.length > 0) {
 		const resolve = options.resolveSpecified ?? resolveAddMcpAgentId;
@@ -67,4 +93,4 @@ const agentIdInChoices = (value, choices) => {
 	for (const choice of choices) if (choice.id === value) return choice.id;
 };
 //#endregion
-export { agentChoicesFrom, canPickAgentsInteractively, pickAgentsInteractively, resolveAgentSelection };
+export { AgentSelectionSkipped, agentChoicesFrom, canPickAgentsInteractively, pickAgentsInteractively, resolveAgentSelection, skippableAgentPicker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "6.2.4",
+  "version": "6.3.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -64,9 +64,9 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
+    "@neon/config": "1.8.2",
     "@neon/config-runtime": "1.7.2",
-    "@neon/sdk": "6.1.2",
-    "@neon/config": "1.8.2"
+    "@neon/sdk": "6.1.2"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",