neon 8.3.1 → 8.3.2

package/README.md

@@ -839,7 +839,9 @@ The target directory must be empty unless you pass `--force` (a lone `.git` is i
 
 Recommended installs the Neon plugin for every detected agent (global config, project folders, and the host CLI). Plugin-capable agents get the plugin; the rest get skills and MCP. If none are detected, it installs the default Neon skills for Cursor and Codex in this directory (`./.agents/skills`) and does not configure MCP. It then links a project when the CLI is authenticated, and writes a default `neon.ts` (Postgres only) using the package manager already in the directory.
 
-Unauthenticated `-y` skips linking and prints the next step: sign up at https://neon.com/signup, then `neon login`, `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 login` or `--claimable`.
+Unauthenticated `-y` skips linking and prints the next step: sign up at https://neon.com/signup, then `neon login`, `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. Without credentials, `--org-id`, `--project-id`, and `--branch` together write `.neon` offline (as `neon link --no-checks` does), and init prints `neon login` as the next step; Neon checks the IDs on the first command that reaches it. With only some of those flags, init still installs agent tooling and writes `neon.ts`, then prints `neon login` and the `neon link` command with those flags.
+
+When init picks MCP auth (no `--mcp-auth`) and the CLI credential is an organization or project-scoped API key, which cannot mint the MCP server's key, init configures MCP with OAuth instead and continues. With `--mcp-auth api-key`, init skips MCP, finishes linking and `neon.ts`, then reports `Neon setup failed.` with the `neon mcp` commands to retry and exits 1.
 
 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.
 

package/dist/init/copy.js

@@ -51,7 +51,7 @@ const NO_AGENTS_FALLBACK_STATUS = "No coding agents detected. Installing the def
 const NO_AGENT_SETUP_CONFLICT = "--no-agent-setup cannot be combined with --agent, --skill, or MCP flags.";
 const INIT_NEEDS_YES = "No interactive terminal. Re-run with -y to set up this directory with Recommended defaults: `neon init -y`. To pick each step instead, run `neon init` in a terminal, or see `neon init --help` for the flag that sets each step.";
 const NON_TTY_LINK_NEEDS_AUTH = "No interactive terminal. Sign in with `neon login`, then re-run, or pass --claimable.";
-const YES_LINK_NEEDS_AUTH = "-y cannot sign in. Sign in with `neon login`, then re-run, or pass --claimable.";
+const MCP_OAUTH_FALLBACK = "This CLI credential cannot mint an API key for the Neon MCP server. Configuring it with OAuth instead.";
 const MCP_SCOPED_NEEDS_PROJECT = "--mcp-project-scoped requires a linked project. Link a project first, or omit --mcp-project-scoped.";
 const namedAgentsUnavailable = (ids) => `--agent ${ids.join(", ")} cannot install this tooling. Pass agents that support it, or omit --agent.`;
 const mcpConfigLocationUnavailable = (ids, location) => location === "project" ? `--agent ${ids.join(", ")} cannot install project-level MCP config. Use --mcp-config-location global, or choose an agent that supports project config.` : `--agent ${ids.join(", ")} cannot install global MCP config. Choose an agent that supports global config.`;
@@ -78,7 +78,8 @@ const PROGRESS = {
 	install: (pm) => `Installing Neon dependencies with ${pm}...`,
 	env: "Pulling Neon environment variables..."
 };
-const unattendedUnauthedNext = () => [
+/** `deferred` carries the account and credential flags init was given. */
+const unattendedUnauthedNext = (deferred) => deferred === void 0 ? [
 	"Link a project with a Neon account and an authenticated CLI.",
 	"Sign up: https://neon.com/signup",
 	`${getCliName()} login`,
@@ -86,6 +87,16 @@ const unattendedUnauthedNext = () => [
 	"",
 	"Or create a claimable project without an account. It expires in 72 hours unless claimed.",
 	`${getCliName()} claim create`
+] : [
+	"Link the project once the CLI is authenticated.",
+	deferred.login,
+	deferred.link
+];
+const PROJECT_PINNED_OFFLINE = "linked, not verified";
+const offlinePinNext = (input) => [
+	"The link was written without contacting Neon. Sign in to use it:",
+	input.login,
+	...input.envPull !== void 0 ? ["Then pull the branch's environment variables:", input.envPull] : []
 ];
 const skippedLinkNext = () => ["To connect this directory to a Neon project:", `${getCliName()} link`];
 const extraServicesNext = () => [
@@ -122,6 +133,17 @@ const installFailedNext = (command) => ({
 	body: "Could not install the Neon dependencies.",
 	next: ["Install the dependencies, then run neon init again:", command]
 });
+const MCP_API_KEY_NEEDS_AUTH = "API-key MCP setup needs a Neon credential to mint the key. Sign in with `neon login` or pass a personal API key.";
+/** `mcp` is the `neon mcp` invocation without an auth flag. */
+const mcpKeyFailedNext = (reason, mcp) => [
+	reason === "cannot-mint" ? "The Neon MCP server was not configured: this CLI credential cannot mint its API key." : "The Neon MCP server was not configured: minting its API key needs a signed-in CLI.",
+	"Configure it with a personal API key:",
+	`${mcp} --api-key <personal-api-key>`,
+	"",
+	"Or with OAuth:",
+	`${mcp} --oauth`
+];
+const mcpAfterLinkNext = (mcp) => ["Then configure the Neon MCP server for that project:", mcp];
 const envPullFailedNext = () => ({
 	heading: HEADING_FAILED,
 	body: "The project is linked, but its environment variables could not be pulled.",
@@ -137,4 +159,4 @@ const headingForOutcome = (outcome) => {
 	}
 };
 //#endregion
-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_NEEDS_YES, 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 };
+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_NEEDS_YES, INIT_SUBTITLE, MCP_API_KEY_NEEDS_AUTH, MCP_AUTH_API_KEY_DESCRIPTION, MCP_AUTH_API_KEY_TITLE, MCP_AUTH_MESSAGE, MCP_AUTH_OAUTH_DESCRIPTION, MCP_AUTH_OAUTH_TITLE, MCP_OAUTH_FALLBACK, 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_PINNED_OFFLINE, 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, claimableNext, claimableThenServicesNext, envPullFailedNext, existingConfigNext, extraServicesNext, headingForOutcome, installFailedNext, mcpAfterLinkNext, mcpConfigLocationSkipped, mcpConfigLocationUnavailable, mcpKeyFailedNext, namedAgentsUnavailable, offlinePinNext, skippedLinkNext, unattendedUnauthedNext };

package/dist/init/run.js

@@ -15,10 +15,12 @@ import { missingPluginsCommands, pluginsInstallableAgents } from "../plugins/tar
 import { skillsInstallableAgents } from "../skills/targets.js";
 import { FALLBACK_SKILLS_AGENTS, assertNamedAgentTooling, funnelAgentSetup, planInitToolingSteps, recommendedTooling, resolveNamedAgents, splitInitTooling } from "./plan.js";
 import { inferPackageManager, resolvePackageManager } from "../utils/package_manager.js";
-import { CANCELLED_BODY, CLAIMABLE_ACCOUNT_FLAGS, CLAIMABLE_ALREADY_LINKED, CLAIMABLE_MCP_API_KEY, CLAIMABLE_NO_LINK, MCP_SCOPED_NEEDS_PROJECT, NON_TTY_LINK_NEEDS_AUTH, NO_AGENTS_FALLBACK_STATUS, PROGRESS, YES_LINK_NEEDS_AUTH, claimableNext, claimableThenServicesNext, envPullFailedNext, existingConfigNext, extraServicesNext, installFailedNext, mcpConfigLocationSkipped, mcpConfigLocationUnavailable, namedAgentsUnavailable, skippedLinkNext, unattendedUnauthedNext } from "./copy.js";
+import { CANCELLED_BODY, CLAIMABLE_ACCOUNT_FLAGS, CLAIMABLE_ALREADY_LINKED, CLAIMABLE_MCP_API_KEY, CLAIMABLE_NO_LINK, MCP_API_KEY_NEEDS_AUTH, MCP_SCOPED_NEEDS_PROJECT, NON_TTY_LINK_NEEDS_AUTH, NO_AGENTS_FALLBACK_STATUS, PROGRESS, PROJECT_PINNED_OFFLINE, claimableNext, claimableThenServicesNext, envPullFailedNext, existingConfigNext, extraServicesNext, installFailedNext, mcpAfterLinkNext, mcpConfigLocationSkipped, mcpConfigLocationUnavailable, mcpKeyFailedNext, namedAgentsUnavailable, offlinePinNext, skippedLinkNext, unattendedUnauthedNext } from "./copy.js";
 import { agentsRowValue, configRowValue, formatInitDone, headingForKind, printInitBanner, printInitDone, printInitProgress, projectRowValue, shouldPrintInitBanner } from "./chrome.js";
 import { ConfigInstallFailed, initCmd } from "../commands/config.js";
+import { quoteFlagValue, runLink } from "../commands/link.js";
 import { runAuthenticatedLink } from "./link.js";
+import { CannotMintApiKeyError } from "../mcp/mint.js";
 import { pullInitEnv } from "./auth.js";
 import { InitCancelled, raceSigint, restoreCursor } from "./cancelled.js";
 import { pickAgentSetupInteractively, pickInitAgentsInteractively, pickInitConfigInteractively, pickInitMcpAuthInteractively, pickInitMcpConfigLocationInteractively, pickInitModeInteractively, pickInitPackageManagerInteractively, pickInitProjectSetupInteractively, pickInitServicesInteractively, pickInitSkillsInteractively } from "./wizard.js";
@@ -34,6 +36,24 @@ const isLinked = (contextFile) => {
 	const projectId = readContextFile(contextFile).projectId;
 	return typeof projectId === "string" && projectId.length > 0;
 };
+const commandLine = (command, pairs) => [`${getCliName()} ${command}`, ...pairs.flatMap(([flag, value]) => value === void 0 ? [] : [`${flag} ${quoteFlagValue(value)}`])].join(" ");
+const deferredLinkCommands = (props, inputs) => {
+	const session = [["--profile", props.profile], ["--config-dir", props.configDir === defaultDir ? void 0 : props.configDir]];
+	const context = [["--context-file", props.contextFile === ".neon" ? void 0 : props.contextFile]];
+	return {
+		login: commandLine("login", session),
+		link: commandLine("link", [
+			["--org-id", inputs.orgId],
+			["--project-id", inputs.projectId],
+			["--project-name", inputs.projectName],
+			["--region-id", inputs.regionId],
+			["--branch", inputs.branch],
+			...context,
+			...session
+		]),
+		envPull: commandLine("env pull", [...context, ...session])
+	};
+};
 const expandTelemetryServices = (services) => {
 	if (services.includes("data-api") && !services.includes("auth")) return CONFIG_INIT_SERVICES.filter((service) => service === "auth" || services.includes(service));
 	return [...services];
@@ -231,6 +251,7 @@ const runInit = async (props) => {
 		const pluginReady = (agents) => agents.filter((id) => !unavailablePluginAgents.includes(id));
 		let tooling = { setup: "skip" };
 		let mcpAuth = props.mcpAuth;
+		let mcpAuthChosen = props.mcpAuth !== void 0;
 		let mcpConfigLocation = props.mcpConfigLocation ?? "global";
 		let selectedSkills = props.skill;
 		let delayMcp = false;
@@ -293,7 +314,9 @@ const runInit = async (props) => {
 							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");
+							const chosenAuth = props.mcpAuth ?? (yes ? void 0 : await pickAuth?.({ authenticated: detection.authenticated }));
+							mcpAuthChosen = chosenAuth !== void 0;
+							mcpAuth = chosenAuth ?? (detection.authenticated && props.claimable !== true ? "api-key" : "oauth");
 						}
 						tooling = skillsMcpTooling(skillsSelection, mcpSelection, mcpConfigLocation, namedFallback);
 					}
@@ -305,16 +328,36 @@ const runInit = async (props) => {
 		if (mcpAuth === void 0 && usesMcp && (!detection.authenticated || props.claimable === true)) mcpAuth = "oauth";
 		delayMcp = usesMcp && (mcpAuth === "api-key" || props.mcpProjectScoped === true);
 		const mcpOauth = mcpAuth === "oauth";
-		const earlyTooling = delayMcp ? tooling.setup === "skills-mcp" ? {
-			setup: "skills-mcp",
-			skillsAgents: tooling.skillsAgents,
-			mcpAgents: []
-		} : tooling.setup === "mixed" ? {
-			setup: "mixed",
-			pluginAgents: tooling.pluginAgents,
-			skillsAgents: tooling.skillsAgents,
-			mcpAgents: []
-		} : tooling : tooling;
+		const earlyTooling = delayMcp ? withoutMcp(tooling) : tooling;
+		const mcpState = {};
+		const reportedTooling = () => mcpState.error === void 0 && mcpState.deferredPin === void 0 ? tooling : withoutMcp(tooling);
+		const mcpCommand = (projectIdArg) => [
+			`${getCliName()} mcp -y`,
+			...mcpConfigLocation === "project" ? ["--project"] : [],
+			...projectIdArg !== void 0 ? [`--project-id ${projectIdArg}`] : [],
+			...("mcpAgents" in tooling ? tooling.mcpAgents : []).map((agent) => `--agent ${agent}`)
+		].join(" ");
+		const mcpFailedNext = () => mcpState.error === void 0 ? [] : mcpKeyFailedNext(mcpState.reason ?? "cannot-mint", mcpCommand(mcpState.pinId !== void 0 ? quoteFlagValue(mcpState.pinId) : void 0));
+		const mcpDeferredNext = () => mcpState.deferredPin === void 0 ? [] : mcpAfterLinkNext(`${mcpCommand(mcpState.deferredPin)}${mcpOauth ? " --oauth" : ""}`);
+		const runTooling = async (steps, plan) => {
+			let ran = plan;
+			try {
+				await runToolingSteps(steps, {
+					cwd,
+					output: props.output,
+					auth,
+					operations: props.operations,
+					narrate: "human",
+					mcpOauthFallback: !mcpAuthChosen
+				});
+			} catch (error) {
+				if (!(error instanceof CannotMintApiKeyError)) throw error;
+				mcpState.error = error;
+				mcpState.reason = "cannot-mint";
+				ran = withoutMcp(plan);
+			}
+			funnel.agentsInstalled = uniqueAgents([...funnel.agentsInstalled, ...agentsFromTooling(ran)]);
+		};
 		const toolingSteps = planInitToolingSteps({
 			tooling: earlyTooling,
 			yes: true,
@@ -324,20 +367,12 @@ const runInit = async (props) => {
 			mcpProject: mcpConfigLocation === "project",
 			...selectedSkills !== void 0 ? { skills: selectedSkills } : {}
 		});
-		if (toolingSteps.length > 0) {
-			await runToolingSteps(toolingSteps, {
-				cwd,
-				output: props.output,
-				auth,
-				operations: props.operations,
-				narrate: "human"
-			});
-			funnel.agentsInstalled = agentsFromTooling(earlyTooling);
-		}
+		if (toolingSteps.length > 0) await runTooling(toolingSteps, earlyTooling);
 		let projectSetup = "skip";
 		let linkedNow = false;
 		let claimExpiresAt;
 		const noLink = props.link === false;
+		const linkByDefault = detection.authenticated || hasExplicitLinkInputs && !yes;
 		if (noLink) {
 			funnel.link = alreadyLinked ? "already_linked" : "skipped";
 			projectSetup = "skip";
@@ -346,19 +381,39 @@ const runInit = async (props) => {
 			projectSetup = "already";
 			if (claimableExisting) claimExpiresAt = readLinkedClaimableCredentials(configDir, readContextFile(contextFile))?.expiresAt;
 		} else if (recommended) {
-			if (hasExplicitLinkInputs || detection.authenticated) projectSetup = "link";
+			if (linkByDefault) projectSetup = "link";
 			else if (detection.interactive && !yes) projectSetup = "link";
 			else {
 				projectSetup = "skip";
 				funnel.link = "skipped";
 			}
 		} else if (props.claimable === true) projectSetup = "claimable";
-		else if (hasExplicitLinkInputs || detection.authenticated) projectSetup = "link";
+		else if (linkByDefault) projectSetup = "link";
 		else if (yes) {
 			projectSetup = "skip";
 			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);
+		const linkProps = {
+			apiClient: props.apiClient,
+			apiKey: props.apiKey,
+			apiHost: props.apiHost,
+			output: props.output,
+			contextFile,
+			yes,
+			clear: false,
+			checks: true,
+			envPull: true,
+			config: false,
+			cwd,
+			...linkInputs,
+			...props.configDir ? { configDir: props.configDir } : {},
+			...props.profile ? { profile: props.profile } : {},
+			...props.oauthHost ? { oauthHost: props.oauthHost } : {},
+			...props.clientId ? { clientId: props.clientId } : {},
+			...props.forceAuth !== void 0 ? { forceAuth: props.forceAuth } : {},
+			...props.allowUnsafeTls !== void 0 ? { allowUnsafeTls: props.allowUnsafeTls } : {}
+		};
 		if (usesMcp && mcpAuth === "api-key" && (projectSetup === "claimable" || props.claimable === true)) throw new Error(CLAIMABLE_MCP_API_KEY);
 		if (projectSetup === "claimable") {
 			printInitProgress(PROGRESS.claim);
@@ -374,32 +429,28 @@ const runInit = async (props) => {
 			funnel.link = "claimable";
 			claimExpiresAt = readLinkedClaimableCredentials(configDir, readContextFile(contextFile))?.expiresAt;
 		} else if (projectSetup === "link") {
-			if (yes && !detection.authenticated) throw new Error(YES_LINK_NEEDS_AUTH);
 			printInitProgress(detection.authenticated ? PROGRESS.link : PROGRESS.auth);
-			await (props.linkProject ?? runAuthenticatedLink)({
-				apiClient: props.apiClient,
-				apiKey: props.apiKey,
-				apiHost: props.apiHost,
-				output: props.output,
-				contextFile,
-				yes,
-				clear: false,
-				checks: true,
-				envPull: true,
-				config: false,
-				cwd,
-				...linkInputs,
-				...props.configDir ? { configDir: props.configDir } : {},
-				...props.profile ? { profile: props.profile } : {},
-				...props.oauthHost ? { oauthHost: props.oauthHost } : {},
-				...props.clientId ? { clientId: props.clientId } : {},
-				...props.forceAuth !== void 0 ? { forceAuth: props.forceAuth } : {},
-				...props.allowUnsafeTls !== void 0 ? { allowUnsafeTls: props.allowUnsafeTls } : {}
+			await (props.linkProject ?? runAuthenticatedLink)(linkProps);
+			linkedNow = true;
+			funnel.link = "linked";
+		}
+		const pinnedOffline = funnel.link === "skipped" && !noLink && linkInputs.orgId !== void 0 && linkInputs.projectId !== void 0 && linkInputs.branch !== void 0 && linkInputs.projectName === void 0 && linkInputs.regionId === void 0;
+		if (pinnedOffline) {
+			await runLink({
+				...linkProps,
+				checks: false,
+				envPull: false
 			});
 			linkedNow = true;
 			funnel.link = "linked";
 		}
-		if (delayMcp && tooling.setup !== "skip") {
+		if (delayMcp && tooling.setup !== "skip" && props.mcpProjectScoped === true && funnel.link === "skipped" && !noLink) mcpState.deferredPin = linkInputs.projectId !== void 0 ? quoteFlagValue(linkInputs.projectId) : "<project-id>";
+		else if (delayMcp && tooling.setup !== "skip" && mcpAuth === "api-key" && yes && !detection.authenticated) {
+			mcpState.error = new Error(MCP_API_KEY_NEEDS_AUTH);
+			mcpState.reason = "signed-out";
+			const linkedId = readContextFile(contextFile).projectId;
+			if (props.mcpProjectScoped === true && typeof linkedId === "string") mcpState.pinId = linkedId;
+		} else if (delayMcp && tooling.setup !== "skip") {
 			const linkedId = readContextFile(contextFile).projectId;
 			let pinId;
 			if (props.mcpProjectScoped === true) {
@@ -424,16 +475,8 @@ const runInit = async (props) => {
 				mcpProject: mcpConfigLocation === "project",
 				...pinId !== void 0 ? { mcpProjectId: pinId } : {}
 			});
-			if (mcpSteps.length > 0) {
-				await runToolingSteps(mcpSteps, {
-					cwd,
-					output: props.output,
-					auth,
-					operations: props.operations,
-					narrate: "human"
-				});
-				funnel.agentsInstalled = uniqueAgents([...funnel.agentsInstalled, ...agentsFromTooling(mcpOnly)]);
-			}
+			mcpState.pinId = pinId;
+			if (mcpSteps.length > 0) await runTooling(mcpSteps, mcpOnly);
 		}
 		const canAskConfig = props.pickConfig !== void 0 || detection.interactive;
 		const configResolution = resolveInitConfigChoice({
@@ -490,7 +533,7 @@ const runInit = async (props) => {
 						heading: failed.heading,
 						body: failed.body,
 						rows: [],
-						next: failed.next
+						next: joinNext(failed.next, mcpFailedNext())
 					}));
 					printed = true;
 					outcome = "error";
@@ -503,8 +546,8 @@ const runInit = async (props) => {
 		const context = readContextFile(contextFile);
 		const branch = contextBranch(context);
 		const linked = isLinked(contextFile);
-		const alreadyPulled = linkedNow && funnel.link === "linked";
-		if (shouldPullEnvAfterInitConfig({
+		const alreadyPulled = linkedNow && funnel.link === "linked" && !pinnedOffline;
+		if (funnel.link !== "skipped" && !pinnedOffline && shouldPullEnvAfterInitConfig({
 			wroteNewFile,
 			extraServices,
 			alreadyPulled,
@@ -530,7 +573,7 @@ const runInit = async (props) => {
 					{
 						label: "Agents",
 						value: agentsRowValue({
-							tooling,
+							tooling: reportedTooling(),
 							installed: funnel.agentsInstalled
 						})
 					},
@@ -543,20 +586,29 @@ const runInit = async (props) => {
 						value: configRowValue(funnel.config, existingFilename)
 					}
 				],
-				next: failed.next
+				next: joinNext(failed.next, mcpFailedNext())
 			}));
 			printed = true;
 			outcome = "error";
 			throw error;
 		}
-		const pendingUnauthed = funnel.link === "skipped" && !noLink && !alreadyLinked;
+		const pendingUnauthed = funnel.link === "skipped" && !noLink;
 		const pendingServices = extraServices && linked;
 		const pendingClaimable = funnel.link === "claimable" && claimExpiresAt !== void 0;
 		const pendingExisting = funnel.config === "existing" && linked && !wroteNewFile;
-		const pending = pendingUnauthed || pendingServices || pendingClaimable && extraServices || pendingExisting;
+		const pending = pinnedOffline || pendingUnauthed || pendingServices || pendingClaimable && extraServices || pendingExisting;
 		const next = [];
-		if (pendingUnauthed) next.push(...unattendedUnauthedNext());
-		else if (noLink && !alreadyLinked) next.push(...skippedLinkNext());
+		if (pinnedOffline) {
+			const commands = deferredLinkCommands(props, linkInputs);
+			next.push(...offlinePinNext({
+				login: commands.login,
+				...extraServices || existingConfig ? {} : { envPull: commands.envPull }
+			}));
+		} else if (pendingUnauthed) {
+			next.push(...unattendedUnauthedNext(hasExplicitLinkInputs ? deferredLinkCommands(props, linkInputs) : void 0));
+			const deferredMcp = mcpDeferredNext();
+			if (deferredMcp.length > 0) next.push("", ...deferredMcp);
+		} else if (noLink && !alreadyLinked) next.push(...skippedLinkNext());
 		if (pendingClaimable && extraServices && claimExpiresAt !== void 0) {
 			if (next.length > 0) next.push("");
 			next.push(...claimableThenServicesNext(claimExpiresAt));
@@ -573,28 +625,30 @@ const runInit = async (props) => {
 		outcome = pending && !pendingUnauthed && noLink ? "success" : pending ? "pending" : "success";
 		if (pendingUnauthed) outcome = "pending";
 		if (noLink && !pendingUnauthed && !pendingServices && !pendingExisting) outcome = "success";
+		if (mcpState.error !== void 0) outcome = "error";
 		printInitDone(formatInitDone({
 			heading: headingForKind(outcome),
 			rows: [
 				{
 					label: "Agents",
 					value: agentsRowValue({
-						tooling,
+						tooling: reportedTooling(),
 						installed: funnel.agentsInstalled
 					})
 				},
 				{
 					label: "Project",
-					value: projectRowValue(funnel.link ?? (linked ? "already_linked" : null))
+					value: pinnedOffline ? PROJECT_PINNED_OFFLINE : projectRowValue(funnel.link ?? (linked ? "already_linked" : null))
 				},
 				{
 					label: "Config",
 					value: configRowValue(funnel.config, existingFilename)
 				}
 			],
-			next
+			next: joinNext(mcpFailedNext(), next)
 		}));
 		printed = true;
+		if (mcpState.error !== void 0) throw mcpState.error;
 		takeCommandSuccessExtras();
 		recordCommandSuccessExtras({
 			init_kind: detection.emptyDirectory ? "empty-skip" : "existing",
@@ -628,6 +682,22 @@ const uniqueAgents = (ids) => {
 	}
 	return out;
 };
+const joinNext = (first, second) => first.length === 0 || second.length === 0 ? [...first, ...second] : [
+	...first,
+	"",
+	...second
+];
+const withoutMcp = (tooling) => {
+	if (tooling.setup === "mixed") return {
+		...tooling,
+		mcpAgents: []
+	};
+	if (tooling.setup === "skills-mcp") return tooling.skillsAgents.length === 0 ? { setup: "skip" } : {
+		...tooling,
+		mcpAgents: []
+	};
+	return tooling;
+};
 const agentsFromTooling = (tooling) => {
 	switch (tooling.setup) {
 		case "skip": return [];

package/dist/init/tooling.js

@@ -1,7 +1,8 @@
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
 import { assertNamedAgentTooling, chooseYesAgentTooling, collectYesAgents, initYesSupportedAgents, noDetectedAgentsMessage, planAgentSteps, planToolingSteps, planYesAgentSteps, resolveInitAgentSetup } from "./plan.js";
-import { PROGRESS } from "./copy.js";
+import { MCP_OAUTH_FALLBACK, PROGRESS } from "./copy.js";
+import { CannotMintApiKeyError } from "../mcp/mint.js";
 import { detectAgent } from "./detect_host.js";
 import { AgentSelectionSkipped, canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { mcpInstallError, reportMcpInstall } from "../commands/mcp.js";
@@ -99,10 +100,19 @@ const runToolingSteps = async (steps, options) => {
 					break;
 				}
 				case "mcp": {
-					const outcome = await raceSigint(ops.installMcp({
+					const install = (oauth) => raceSigint(ops.installMcp({
 						...step.options,
-						...sharedOptions
+						...sharedOptions,
+						oauth
 					}));
+					let outcome;
+					try {
+						outcome = await install(step.options.oauth);
+					} catch (error) {
+						if (!(error instanceof CannotMintApiKeyError) || options.mcpOauthFallback !== true || step.options.oauth === true) throw error;
+						log.warning(MCP_OAUTH_FALLBACK);
+						outcome = await install(true);
+					}
 					reportMcpInstall(reportProps, outcome);
 					const error = mcpInstallError(outcome);
 					if (error) throw error;

package/dist/mcp/mint.js

@@ -4,7 +4,12 @@ import { getCliName } from "../utils/cli_name.js";
 import { mintedKeyName } from "../profile_keys.js";
 import { orgIdForProject } from "../commands/api_keys.js";
 //#region src/mcp/mint.ts
-const cannotMintMessage = "This CLI credential cannot mint API keys. Organization and project-scoped keys cannot create other keys. Sign in with `neon login` or pass a personal API key.";
+var CannotMintApiKeyError = class extends Error {
+	constructor() {
+		super("This CLI credential cannot mint API keys. Organization and project-scoped keys cannot create other keys. Sign in with `neon login` or pass a personal API key.");
+		this.name = "CannotMintApiKeyError";
+	}
+};
 function mintedKeyRevokeCommand(key) {
 	return key.orgId ? `${getCliName()} api-keys revoke ${key.id} --org-id ${key.orgId}` : `${getCliName()} api-keys revoke ${key.id}`;
 }
@@ -44,7 +49,7 @@ const createAndAssert = async (client, create, name, scope) => {
 		const { data } = await create();
 		return assertUsable(client, data, name, scope);
 	} catch (err) {
-		if (isNeonApiError(err) && (err.status === 403 || err.status === 404)) throw new Error(cannotMintMessage);
+		if (isNeonApiError(err) && (err.status === 403 || err.status === 404)) throw new CannotMintApiKeyError();
 		throw err;
 	}
 };
@@ -67,4 +72,4 @@ async function withdrawMintedKey(apiClient, key) {
 	return withdraw(apiClient, key.id, key.orgId);
 }
 //#endregion
-export { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey };
+export { CannotMintApiKeyError, mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "8.3.1",
+  "version": "8.3.2",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -101,8 +101,8 @@
     "typescript": "^5.9.0",
     "vitest": "^3.0.9",
     "@neon-internals/cli-core": "0.0.0",
-    "@neon-internals/env-core": "0.0.29",
     "@neon/e2e-harness": "0.0.0",
+    "@neon-internals/env-core": "0.0.29",
     "@neon/functions": "0.11.0"
   },
   "publishConfig": {