neon 4.5.0 → 4.6.0

package/README.md

@@ -710,6 +710,12 @@ $ neon bootstrap my-app
 
 # Scaffold a specific template into the current directory (no prompts)
 $ neon bootstrap . --template hono
+
+# List templates
+$ neon bootstrap --list-templates
+
+# Machine-readable catalog
+$ neon bootstrap --list-templates --output json
 ```
 
 The target directory must be empty unless you pass `--force` (a lone `.git` is ignored, so a freshly `git init`ed folder is fine). Symlinks and executable bits in the template are preserved.
@@ -781,7 +787,7 @@ That message reports where parsing stopped and nothing more. `--data` carries wh
 # Interactive: global or project, then agents, then API key or OAuth, then confirm.
 $ neon mcp
 
-# Skip prompts. Global config, every globally detected agent, minted API key.
+# Skip prompts. Global config, every globally detected agent, reuse or mint an API key.
 $ neon mcp -y
 
 # OAuth: no API key minted. The agent prompts for Neon sign-in on first use.
@@ -804,7 +810,7 @@ $ neon mcp --category querying --category schema
 
 On a TTY the command asks for config location (global is the default), then agents, then API key vs OAuth, then a summary to confirm before it writes. Detected agents start selected: globally installed agents or project-folder markers such as `.cursor` when the install is project.
 
-`-y` skips those questions. `--project`, `--oauth` and `--agent` skip the question they answer and still apply with `-y`. `--read-only` and `--category` are flags only and are never prompted. A linked project-folder install asks whether to pin MCP tools to that `.neon` project (`?projectId=`). If you pin and selected API-key auth, the minted key is limited to that project too. An unlinked project folder does not ask. Global installs never add that param unless you pass `--project-id`. `-y` does not infer a project from `.neon`. Without a TTY, pass `-y` to mint into every detected agent, `--agent` to name the agents or `--oauth` to write the URL only.
+`-y` skips those questions. `neon mcp -y` writes `https://mcp.neon.tech/mcp` into global config for every globally detected agent, reuses an existing Neon MCP API key or mints an account-wide key, leaves write tools enabled, exposes every tool category, and does not pin a project (including from `.neon`). `--project`, `--oauth` and `--agent` skip the question they answer and still apply with `-y`. `--read-only` and `--category` are flags only and are never prompted. A linked project-folder install asks whether to pin MCP tools to that `.neon` project (`?projectId=`). If you pin and selected API-key auth, the minted key is limited to that project too. An unlinked project folder does not ask. Global installs never add that param unless you pass `--project-id`. Without a TTY, pass `-y` to mint into every detected agent, `--agent` to name the agents or `--oauth` to write the URL only. `neon mcp --help` lists the server URL, those `-y` defaults, the supported `--agent` names, and the `--category` values.
 
 `--agent` names: `antigravity`, `cline`, `cline-cli`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `goose`, `github-copilot-cli`, `grok-build`, `mcporter`, `opencode`, `vscode`, `windsurf`, `zed`. Project installs drop `antigravity`, `cline`, `cline-cli`, `goose` and `windsurf`. `claude-desktop` is a known name that is then skipped.
 
@@ -838,9 +844,9 @@ On a TTY the command asks which agents and which skills, then shows a summary to
 
 `-y` skips those questions and installs the default skills. `--skill` / `-s` names specific skills and skips the skill picker. `--agent` and `--global` still apply. Without a TTY, pass `-y` or `--skill`. `--agent` alone is not enough.
 
-`--skill` names: `claimable-postgres`, `neon`, `neon-ai-gateway`, `neon-functions`, `neon-object-storage`, `neon-postgres`, `neon-postgres-branches`, `neon-postgres-egress-optimizer`, `neon-postgres-agent-platforms`.
+`--skill` names by source repo: `neondatabase/agent-skills` (`claimable-postgres`, `neon`, `neon-ai-gateway`, `neon-functions`, `neon-object-storage`, `neon-postgres`, `neon-postgres-branches`, `neon-postgres-egress-optimizer`); `neondatabase/neon-for-agent-platforms` (`neon-postgres-agent-platforms`).
 
-`--agent` names match `neon mcp`, minus agents that cannot install skills: `antigravity`, `cline`, `cline-cli`, `claude-code`, `claude-desktop`, `codex`, `cursor`, `gemini-cli`, `goose`, `github-copilot-cli`, `grok-build`, `opencode`, `vscode`, `windsurf`, `zed`. `mcporter` is a known MCP name that is then skipped.
+`--agent` names match `neon mcp`, minus agents that cannot install skills: `antigravity`, `cline`, `cline-cli`, `claude-code`, `claude-desktop`, `codex`, `cursor`, `gemini-cli`, `goose`, `github-copilot-cli`, `grok-build`, `opencode`, `vscode`, `windsurf`, `zed`. `mcporter` is a known MCP name that is then skipped. `neon skills --help` lists the same skill and agent values, and that `-y` leaves out `neon-postgres-agent-platforms`.
 
 ## Install the Neon plugin (`plugins`)
 
@@ -868,7 +874,9 @@ Default scope is `project`. `--global` is `user`. On macOS and Linux, Cursor and
 
 `--agent` names with a plugins mapping: `claude-code`, `claude-desktop`, `codex`, `cursor`, `github-copilot-cli`, `grok-build`, `vscode`. `claude-desktop` installs as Claude Code; naming both produces one install and lists both names in the table. `mcporter` is a known MCP name that is then skipped.
 
-The plugins CLI installs every plugin it finds in the Neon plugin package. Today that is `neon-postgres`.
+The plugins CLI installs every plugin it finds in the Neon plugin package. Today that is `neon-postgres` from `neondatabase/agent-skills`. It includes the Neon MCP server (`https://mcp.neon.tech/mcp`) and these skills: `neon`, `neon-ai-gateway`, `neon-functions`, `neon-object-storage`, `neon-postgres`, `neon-postgres-branches`, `neon-postgres-egress-optimizer`. It does not include `claimable-postgres` or `neon-postgres-agent-platforms`.
+
+`neon plugins --help` lists the plugin, those contents, and the supported `--agent` names.
 
 ## Snapshots (`snapshots`)
 

package/dist/commands/bootstrap.js

@@ -3,8 +3,9 @@ import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
 import { t as credentialInputs } from "../_chunks/auth_selection-ktL6uoEe.js";
-import { BootstrapInputError, FALLBACK_TEMPLATES, ensureTargetUsable, fetchTemplates, findTemplate, scaffoldTemplate, templateIds } from "../init/bootstrap.js";
-import { DO_NOT_SUBSTITUTE_HINT, formatInstallCommand, inferPackageManager, installArgs, installedPackageManagers, resolvePackageManager, runCommand } from "../utils/package_manager.js";
+import { writer } from "../writer.js";
+import { FALLBACK_TEMPLATES, ensureTargetUsable, fetchTemplates, findTemplate, scaffoldTemplate, templateIds } from "../init/bootstrap.js";
+import { formatInstallCommand, inferPackageManager, installArgs, installedPackageManagers, resolvePackageManager, runCommand } from "../utils/package_manager.js";
 import { existsSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import chalk from "chalk";
@@ -16,6 +17,7 @@ var bootstrap_exports = /* @__PURE__ */ __exportAll({
 	describe: () => describe,
 	handler: () => handler
 });
+const removedAgent = () => `\`${getCliName()} bootstrap --agent\` was removed. List templates with \`${getCliName()} bootstrap --list-templates --output json\`. Scaffold with \`${getCliName()} bootstrap <directory> --template <id>\` or \`${getCliName()} bootstrap <directory> --default\`.`;
 const command = "bootstrap [directory]";
 const describe = "Scaffold a new project from a Neon starter template";
 const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").positional("directory", {
@@ -28,7 +30,7 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 	},
 	"list-templates": {
 		alias: ["list", "ls"],
-		describe: "List available templates and exit.",
+		describe: "List available templates and exit. --output json and --output yaml print a machine-readable catalog.",
 		type: "boolean",
 		default: false
 	},
@@ -38,9 +40,8 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 		default: false
 	},
 	agent: {
-		describe: "Emit a JSON state-machine response designed for AI agents instead of prompting. The output is a single JSON object with a discriminated `status` field describing the next step.",
-		type: "boolean",
-		default: false
+		hidden: true,
+		type: "boolean"
 	},
 	default: {
 		alias: "y",
@@ -63,20 +64,33 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 		type: "boolean",
 		default: true
 	}
-}).example("$0 bootstrap my-app", "Create ./my-app from an interactively chosen template").example("$0 bootstrap . --template hono", "Scaffold the Hono template into the current directory").example("$0 bootstrap my-app --default", "Quick start: scaffold the default template and run setup without prompting").example("$0 bootstrap my-app --template hono --agent", "Scaffold without prompting and emit the JSON state machine for AI agents").strict();
+}).example("$0 bootstrap my-app", "Create ./my-app from an interactively chosen template").example("$0 bootstrap . --template hono", "Scaffold the Hono template into the current directory").example("$0 bootstrap my-app --default", "Quick start: scaffold the default template and run setup without prompting").example("$0 bootstrap --list-templates --output json", "Print the template catalog as JSON").check((argv) => {
+	if (argv.agent === true) throw new Error(removedAgent());
+	return true;
+}).strict();
 const handler = async (props) => {
 	if (props.listTemplates) {
 		const templates = await fetchTemplates();
+		if (props.output === "json" || props.output === "yaml") {
+			writer(props).end(templates.map((t) => ({
+				id: t.id,
+				title: t.title,
+				description: t.description,
+				services: t.services ?? []
+			})), { fields: [
+				"id",
+				"title",
+				"description",
+				"services"
+			] });
+			return;
+		}
 		for (const t of templates) {
 			const services = t.services && t.services.length > 0 ? ` [${t.services.join(" · ")}]` : "";
 			process.stdout.write(`${t.id} — ${t.description}${services}\n`);
 		}
 		return;
 	}
-	if (props.agent) {
-		await runAgentSafely(props);
-		return;
-	}
 	const templates = await resolveTemplateList(props);
 	const interactive = !props.default && Boolean(process.stdout.isTTY) && !isCi();
 	const template = await resolveSelectedTemplate(props, interactive, templates);
@@ -163,15 +177,6 @@ const scaffold = async (template, targetDir) => {
 	log.info("Scaffolded %d files into %s.", filesWritten, targetDir);
 	return filesWritten;
 };
-/**
-* After a human scaffold, offer the things you almost always do next: install
-* dependencies, initialize a git repo, and link the directory to a Neon
-* project. In an interactive terminal each is a y/n prompt (skippable up front
-* with --no-install / --no-git / --no-link); `--default` runs install + git
-* without asking; otherwise we just print the manual steps so nothing runs
-* behind the user's back. Agent mode never reaches here — it returns these as
-* structured `next_steps` instead (see {@link runAgent}).
-*/
 const runPostScaffoldSteps = async (props, targetDir, interactive) => {
 	const inferred = inferPackageManager(targetDir);
 	const defaultPm = resolvePackageManager(targetDir);
@@ -307,103 +312,6 @@ const printNextSteps = (targetDir, pm, opts) => {
 	log.info("  See the README to run it.");
 	log.info("");
 };
-const runAgentSafely = async (props) => {
-	try {
-		await runAgent(props);
-	} catch (err) {
-		emitAgent(toAgentError(err));
-		process.exit(1);
-	}
-};
-/**
-* The `--agent` flow: resolve what the flags determine and emit one JSON object
-* describing either the next input needed (`needs_template` / `needs_directory`)
-* or the terminal result (`scaffolded`). Unlike interactive mode it never
-* prompts and never runs install/git/link itself — those come back as structured
-* `next_steps` so the agent can confirm with the user and run them (the link
-* step chains into `neon link --agent`).
-*/
-const runAgent = async (props) => {
-	if (!props.template) {
-		const templates = await fetchTemplates();
-		emitAgent({
-			status: "needs_template",
-			instruction: `Ask the user which template to scaffold, then re-run the next_command_template with the chosen --template value${props.directory ? "" : " and a target directory"}.`,
-			options: templates.map((template) => ({
-				id: template.id,
-				title: template.title,
-				description: template.description,
-				...template.services ? { services: template.services } : {}
-			})),
-			next_command_template: `${getCliName()} bootstrap --agent ${props.directory ? shellArg(props.directory) : "<directory>"} --template <template_id>`
-		});
-		return;
-	}
-	const templates = await resolveTemplateList(props);
-	const template = findTemplate(templates, props.template);
-	if (!template) throw new BootstrapInputError(`Unknown template "${props.template}". Available templates: ${templateIds(templates)}.`, "UNKNOWN_TEMPLATE");
-	if (props.directory === void 0) {
-		emitAgent({
-			status: "needs_directory",
-			instruction: "Ask the user which directory to scaffold into (use \".\" for the current directory), then re-run the next_command_template with it.",
-			next_command_template: `${getCliName()} bootstrap --agent <directory> --template ${shellArg(template.id)}`
-		});
-		return;
-	}
-	const targetDir = resolve(process.cwd(), props.directory === "." ? "" : props.directory);
-	ensureTargetUsable(targetDir, props.force);
-	const filesWritten = await scaffold(template, targetDir);
-	const dir = displayDir(targetDir);
-	const runIn = isCurrentDir(targetDir) ? "" : `cd ${shellArg(dir)} && `;
-	const installPm = resolvePackageManager(targetDir);
-	emitAgent({
-		status: "scaffolded",
-		directory: targetDir,
-		template: {
-			id: template.id,
-			title: template.title
-		},
-		files_written: filesWritten,
-		next_steps: [
-			{
-				action: "install_dependencies",
-				instruction: `Ask the user whether to install dependencies, then run this in the project directory. ${DO_NOT_SUBSTITUTE_HINT}`,
-				command: `${runIn}${formatInstallCommand(installPm)}`
-			},
-			{
-				action: "initialize_git",
-				instruction: "Ask the user whether to initialize a git repository in the project directory.",
-				command: `${runIn}git init`
-			},
-			{
-				action: "link_neon_project",
-				instruction: "Ask the user whether to link the project to a Neon project now. This runs the link state machine — follow its JSON output for the next step.",
-				command: `${runIn}${getCliName()} link --agent`
-			}
-		],
-		message: `Scaffolded "${template.title}" (${filesWritten} files) into ${dir}. Offer the next_steps to the user: install dependencies, initialize git, then link a Neon project.`
-	});
-};
-const emitAgent = (response) => {
-	process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-};
-const toAgentError = (err) => {
-	if (err instanceof BootstrapInputError) return {
-		status: "error",
-		code: err.agentCode,
-		message: err.message
-	};
-	if (err instanceof Error) return {
-		status: "error",
-		code: "INTERNAL_ERROR",
-		message: err.message
-	};
-	return {
-		status: "error",
-		code: "INTERNAL_ERROR",
-		message: String(err)
-	};
-};
 const isCurrentDir = (targetDir) => relative(process.cwd(), targetDir) === "";
 /**
 * The path to show the user: the bare relative path for the common
@@ -415,10 +323,6 @@ const displayDir = (targetDir) => {
 	if (rel === "") return ".";
 	return rel.startsWith("..") ? targetDir : rel;
 };
-const shellArg = (value) => {
-	if (/^[A-Za-z0-9._:/-]+$/.test(value)) return value;
-	return `'${value.replace(/'/g, `'\\''`)}'`;
-};
 const onPromptState = (state) => {
 	if (state.aborted) {
 		process.stdout.write("\x1B[?25h");

package/dist/commands/mcp.js

@@ -4,12 +4,13 @@ import { readContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
 import { writer } from "../writer.js";
 import { noPassthrough, single } from "../utils/flags.js";
-import { existingNeonApiKey, installNeonMcpServer, neonMcpUrl, parseMcpCategories, trackedProjectMcpConfig } from "../mcp/install.js";
+import { NEON_MCP_CATEGORIES, NEON_MCP_URL, existingNeonApiKey, installNeonMcpServer, neonMcpUrl, parseMcpCategories, trackedProjectMcpConfig } from "../mcp/install.js";
 import { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey } from "../mcp/mint.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
-import { resolveInstallTargets } from "../mcp/targets.js";
+import { mcpInstallableAgents, resolveInstallTargets } from "../mcp/targets.js";
 import { confirmMcpInstall } from "../mcp/wizard.js";
 import { resolveMcpPlan } from "../mcp/plan.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 //#region src/commands/mcp.ts
 var mcp_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,
@@ -19,6 +20,9 @@ var mcp_exports = /* @__PURE__ */ __exportAll({
 });
 const command = "mcp";
 const describe = "Install the Neon MCP server into coding agents";
+const mcpGlobalAgents = mcpInstallableAgents("global");
+const mcpProjectAgents = mcpInstallableAgents("project");
+const mcpProjectDroppedAgents = mcpGlobalAgents.filter((id) => !mcpProjectAgents.includes(id));
 const builder = (argv) => argv.usage("$0 mcp [options]").options({
 	oauth: {
 		type: "boolean",
@@ -34,13 +38,13 @@ const builder = (argv) => argv.usage("$0 mcp [options]").options({
 		alias: "y",
 		type: "boolean",
 		default: false,
-		describe: "Skip prompts. Defaults to global config, every detected agent and a minted account-wide API key. --project, --oauth, --agent, --read-only, --project-id and --category still apply"
+		describe: "Skip prompts. Defaults listed below. --project, --oauth, --agent, --read-only, --project-id and --category still apply"
 	},
 	agent: {
 		alias: "a",
 		type: "array",
 		string: true,
-		describe: "Coding agent to install into (repeatable). Skips the agent picker",
+		describe: "Coding agent to install into (repeatable). Skips the agent picker. Values listed below",
 		coerce: (value) => {
 			if (value === void 0) return [];
 			const list = Array.isArray(value) ? value : [value];
@@ -65,7 +69,7 @@ const builder = (argv) => argv.usage("$0 mcp [options]").options({
 	category: {
 		type: "array",
 		string: true,
-		describe: "MCP tool category (repeatable or comma-separated). Default: all",
+		describe: "MCP tool category (repeatable or comma-separated). Default: all. Values listed below",
 		coerce: (value) => {
 			if (value === void 0) return [];
 			const list = Array.isArray(value) ? value : [value];
@@ -82,7 +86,7 @@ const builder = (argv) => argv.usage("$0 mcp [options]").options({
 			return parseMcpCategories(parts);
 		}
 	}
-}).example("$0 mcp", "Interactive: config location, agents, auth, then confirm").example("$0 mcp -y", "Global config, detected agents, minted API key").example("$0 mcp --oauth", "Install with OAuth; the agent signs in on first use").example("$0 mcp --project", "Write project-level config").example("$0 mcp --agent cursor --agent claude-code", "Install into specific agents").example("$0 mcp --read-only", "Hide write tools via ?readonly=true").example("$0 mcp --project-id <id>", "Pin tools to one project via ?projectId=").example("$0 mcp --category querying --category schema", "Limit tools to those categories").strict().check(noPassthrough("mcp"));
+}).example("$0 mcp", "Interactive: config location, agents, auth, then confirm").example("$0 mcp -y", "Global config, detected agents, reuse or mint an API key").example("$0 mcp --oauth", "Install with OAuth; the agent signs in on first use").example("$0 mcp --project", "Write project-level config").example("$0 mcp --agent cursor --agent claude-code", "Install into specific agents").example("$0 mcp --read-only", "Hide write tools via ?readonly=true").example("$0 mcp --project-id <id>", "Pin tools to one project via ?projectId=").example("$0 mcp --category querying --category schema", "Limit tools to those categories").epilogue(helpEpilogue(`Installs ${NEON_MCP_URL}`, helpCsv("Supported agents at global scope", mcpGlobalAgents), helpCsv("--project does not support", mcpProjectDroppedAgents), helpCsv("Supported categories", NEON_MCP_CATEGORIES), "neon mcp -y:", "  global config", "  every globally detected agent", "  reuse an existing Neon MCP API key, else mint an account-wide key", "  write tools on, all categories", "  no project pin (including from .neon)")).strict().check(noPassthrough("mcp"));
 const handler = async (props) => {
 	const cwd = process.cwd();
 	const interactive = canPickAgentsInteractively() && props.yes !== true;

package/dist/commands/plugins.js

@@ -2,11 +2,14 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { writer } from "../writer.js";
 import { noPassthrough } from "../utils/flags.js";
+import { NEON_MCP_URL } from "../mcp/install.js";
 import { getAgentDisplayName } from "../mcp/agents.js";
 import "../init/agents.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
+import { pluginsInstallableAgents } from "../plugins/targets.js";
 import { resolvePluginsPlan } from "../plugins/plan.js";
-import { NEON_PLUGIN_NAME, neonPluginsRetryCommand, pluginsAddArgs, runPluginsCli } from "../plugins/run.js";
+import { NEON_PLUGIN_NAME, PLUGIN_SKILLS, PLUGIN_SOURCE, neonPluginsRetryCommand, pluginsAddArgs, runPluginsCli } from "../plugins/run.js";
 import { confirmPluginsInstall } from "../plugins/wizard.js";
 //#region src/commands/plugins.ts
 var plugins_exports = /* @__PURE__ */ __exportAll({
@@ -27,6 +30,8 @@ const coerceAgents = (value) => {
 };
 const command = "plugins";
 const describe = "Install the Neon plugin into coding agents";
+const pluginProjectAgents = pluginsInstallableAgents("project");
+const pluginGlobalOnlyAgents = pluginsInstallableAgents("global").filter((id) => !pluginProjectAgents.includes(id));
 const builder = (argv) => argv.usage("$0 plugins [options]").options({
 	yes: {
 		alias: "y",
@@ -43,10 +48,10 @@ const builder = (argv) => argv.usage("$0 plugins [options]").options({
 		alias: "a",
 		type: "array",
 		string: true,
-		describe: "Coding agent to install into (repeatable). Skips the agent picker",
+		describe: "Coding agent to install into (repeatable). Skips the agent picker. Values listed below",
 		coerce: coerceAgents
 	}
-}).example("$0 plugins", "Interactive: agents, then confirm").example("$0 plugins -y", "Detected agents, skip prompts").example("$0 plugins --agent cursor --agent claude-code", "Install into specific agents").example("$0 plugins --global", "Install user-level").strict().check(noPassthrough("plugins"));
+}).example("$0 plugins", "Interactive: agents, then confirm").example("$0 plugins -y", "Detected agents, skip prompts").example("$0 plugins --agent cursor --agent claude-code", "Install into specific agents").example("$0 plugins --global", "Install user-level").epilogue(helpEpilogue(helpCsv("Supported agents at project scope", pluginProjectAgents), helpCsv("Also with --global", pluginGlobalOnlyAgents), `Currently one plugin: ${NEON_PLUGIN_NAME} from ${PLUGIN_SOURCE}.`, `It includes the Neon MCP server (${NEON_MCP_URL})`, helpCsv("and these skills", PLUGIN_SKILLS))).strict().check(noPassthrough("plugins"));
 const handler = async (props) => {
 	const cwd = process.cwd();
 	const yes = props.yes === true;

package/dist/commands/skills.js

@@ -5,7 +5,9 @@ import { noPassthrough } from "../utils/flags.js";
 import { getAgentDisplayName } from "../mcp/agents.js";
 import "../init/agents.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
-import { mappedSkillsAgentNames } from "../skills/targets.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
+import { skillsHelpValues, skillsYesHelp } from "../skills/catalog.js";
+import { mappedSkillsAgentNames, skillsInstallableAgents } from "../skills/targets.js";
 import { confirmSkillsInstall, confirmSkillsUpdate } from "../skills/wizard.js";
 import { assertSkillsCanRun, resolveSkillsPlan } from "../skills/plan.js";
 import { assertSkillsNode, neonSkillsRetryCommand, neonSkillsUpdateRetryCommand, runSkillsCli, skillsAddArgs, skillsMetadata, skillsUpdateArgs, skillsUpdateDetail, skillsUpdateHadNothing } from "../skills/run.js";
@@ -64,17 +66,17 @@ const builder = (argv) => argv.usage("$0 skills [command] [options]").command("u
 		alias: "a",
 		type: "array",
 		string: true,
-		describe: "Coding agent to install into (repeatable). Skips the agent picker",
+		describe: "Coding agent to install into (repeatable). Skips the agent picker. Values listed below",
 		coerce: coerceAgents
 	},
 	skill: {
 		alias: "s",
 		type: "array",
 		string: true,
-		describe: "Skill to install (repeatable). Skips the skill picker",
+		describe: "Skill to install (repeatable). Skips the skill picker. Values listed below",
 		coerce: coerceSkills
 	}
-}).example("$0 skills", "Interactive: this directory, agents, skills, then confirm").example("$0 skills -y", "This directory, detected agents, the default skills").example("$0 skills -s neon -s neon-ai-gateway --agent cursor", "Install named skills into specific agents").example("$0 skills --global", "Install user-level skills").strict().check(noPassthrough("skills"));
+}).example("$0 skills", "Interactive: this directory, agents, skills, then confirm").example("$0 skills -y", "This directory, detected agents, the default skills").example("$0 skills -s neon -s neon-ai-gateway --agent cursor", "Install named skills into specific agents").example("$0 skills --global", "Install user-level skills").epilogue(helpEpilogue(helpCsv("Supported agents", skillsInstallableAgents()), "Supported skills, by source repo:", skillsHelpValues(), skillsYesHelp())).strict().check(noPassthrough("skills"));
 const handler = async (props) => {
 	assertSkillsNode();
 	const cwd = process.cwd();

package/dist/init/bootstrap.js

@@ -305,12 +305,7 @@ const downloadTemplate = async (template) => {
 	if (files.length === 0) throw new Error(`Template subdirectory "${subdir}" was not found in ${owner}/${repo}@${ref}.`);
 	return files;
 };
-/**
-* A bad caller-supplied input that an agent (or human) can correct: an unknown
-* template id or a non-empty target directory. Carries an `agentCode` so an
-* agent surface can report a precise error code instead of a generic
-* INTERNAL_ERROR, while a human path just surfaces the clear `message`.
-*/
+/** `agentCode` lets programmatic callers branch without parsing human-readable messages. */
 var BootstrapInputError = class extends Error {
 	constructor(message, agentCode) {
 		super(message);

package/dist/plugins/run.js

@@ -4,6 +4,15 @@ import { execa } from "execa";
 const TELEMETRY_BLOCKERS = ["DISABLE_TELEMETRY", "DO_NOT_TRACK"];
 const PLUGIN_SOURCE = "neondatabase/agent-skills";
 const NEON_PLUGIN_NAME = "neon-postgres";
+const PLUGIN_SKILLS = [
+	"neon",
+	"neon-ai-gateway",
+	"neon-functions",
+	"neon-object-storage",
+	"neon-postgres",
+	"neon-postgres-branches",
+	"neon-postgres-egress-optimizer"
+];
 const PLUGINS_CLI_TIMEOUT_MS = 12e4;
 const pluginsChildEnv = (base = process.env) => {
 	const env = { ...base };
@@ -120,4 +129,4 @@ const killProcessTree = (pid) => {
 const isCommandMissing = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 const isExecaFailure = (error) => typeof error === "object" && error !== null && "shortMessage" in error && typeof error.shortMessage === "string";
 //#endregion
-export { NEON_PLUGIN_NAME, PLUGINS_CLI_TIMEOUT_MS, PLUGIN_SOURCE, neonPluginsRetryCommand, pluginsAddArgs, pluginsChildEnv, pluginsCliFailureMessage, pluginsScopeFlag, quoteNpxArg, runPluginsCli };
+export { NEON_PLUGIN_NAME, PLUGINS_CLI_TIMEOUT_MS, PLUGIN_SKILLS, PLUGIN_SOURCE, neonPluginsRetryCommand, pluginsAddArgs, pluginsChildEnv, pluginsCliFailureMessage, pluginsScopeFlag, quoteNpxArg, runPluginsCli };

package/dist/skills/catalog.js

@@ -1,3 +1,4 @@
+import { helpCsv } from "../utils/help_text.js";
 //#region src/skills/catalog.ts
 const AGENT_SKILLS_SOURCE = "neondatabase/agent-skills";
 const PLATFORMS_SKILLS_SOURCE = "neondatabase/neon-for-agent-platforms";
@@ -97,5 +98,11 @@ const invocationsForSelection = (selected) => {
 	});
 };
 const yesInstallInvocations = () => invocationsForSelection(defaultSkillEntries());
+const skillsHelpValues = () => invocationsForSelection(NEON_SKILL_CATALOG).map((group) => helpCsv(`  ${group.source}`, group.skills)).join("\n");
+const skillsYesHelp = () => {
+	const omitted = NEON_SKILL_CATALOG.filter((entry) => !entry.defaultSelected).map((entry) => entry.skill);
+	if (omitted.length === 0) return "neon skills -y installs every listed skill";
+	return `neon skills -y installs every listed skill except ${omitted.join(", ")}`;
+};
 //#endregion
-export { AGENT_SKILLS_SOURCE, NEON_SKILL_CATALOG, PLATFORMS_SKILLS_SOURCE, defaultSkillEntries, invocationsForSelection, listSkillIds, resolveSkillId, uniqueSkillEntries, yesInstallInvocations };
+export { AGENT_SKILLS_SOURCE, NEON_SKILL_CATALOG, PLATFORMS_SKILLS_SOURCE, defaultSkillEntries, invocationsForSelection, listSkillIds, resolveSkillId, skillsHelpValues, skillsYesHelp, uniqueSkillEntries, yesInstallInvocations };

package/dist/utils/help_text.js

@@ -0,0 +1,29 @@
+//#region src/utils/help_text.ts
+const HELP_WRAP = 78;
+const WRAP_INDENT = "    ";
+const helpWidth = () => {
+	const columns = process.stderr.columns ?? process.stdout.columns;
+	if (typeof columns !== "number" || !Number.isFinite(columns) || columns < 1) return 78;
+	return Math.max(24, columns - 1);
+};
+const helpCsv = (label, items, width = helpWidth()) => {
+	if (items.length === 0) return "";
+	const prefix = `${label}:`;
+	const lines = [];
+	let line = prefix;
+	for (const item of items) {
+		const addition = line === prefix ? ` ${item}` : `, ${item}`;
+		if (line.length + addition.length <= width) {
+			line += addition;
+			continue;
+		}
+		if (line === prefix) lines.push(prefix);
+		else lines.push(`${line},`);
+		line = `${WRAP_INDENT}${item}`;
+	}
+	lines.push(line);
+	return lines.join("\n");
+};
+const helpEpilogue = (...blocks) => ["", ...blocks.filter((block) => block !== "")].join("\n");
+//#endregion
+export { HELP_WRAP, helpCsv, helpEpilogue, helpWidth };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -63,9 +63,9 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/config-runtime": "1.0.3",
-    "@neon/sdk": "2.2.0",
-    "@neon/config": "1.0.3"
+    "@neon/config": "1.0.4",
+    "@neon/config-runtime": "1.0.4",
+    "@neon/sdk": "2.3.0"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",
@@ -97,8 +97,8 @@
     "typescript": "^5.9.0",
     "vitest": "^3.0.9",
     "@neon-internals/cli-core": "0.0.0",
-    "@neon/e2e-harness": "0.0.0",
-    "@neon-internals/env-core": "0.0.3"
+    "@neon-internals/env-core": "0.0.4",
+    "@neon/e2e-harness": "0.0.0"
   },
   "publishConfig": {
     "access": "public",