neon 8.5.0 → 8.6.0

package/README.md

@@ -623,7 +623,16 @@ Console), or drop auth from --service.
 
 If you'd rather not keep env vars on disk, inject them at runtime instead with `neon-env run -- <your dev command>` (from `@neon/env`) or `neon dev`, and pass `--no-env-pull` to `link` / `checkout`.
 
-**`neon dev` resolves the same set, by the same rules** — including the AI Gateway on a branch with no `neon.ts`. A function running locally gets the same Postgres / Auth / Data API / storage / AI Gateway vars a deploy would inject. Each `NEON_FUNCTION_<SLUG>_BASE_URL` this process is serving is rewritten to `http://localhost:<port>`: every neon.ts function, or the matching slug when `--source` names one. `neon env pull` and `neon-env run` write the production URL (`https://<branchId>-<slug>.compute.…`). `dev` writes nothing, but it does *read* your `.env` / `.env.local` to reuse the branch credential behind the AI Gateway and object storage. Without a file to read from it issues one on every start and leaves the last one live — it has nowhere to keep it, and so cannot name it to revoke it. It says so when it happens; run `env pull` (or just `link` / `checkout`) once and restarts reuse the credential instead.
+**`neon dev` resolves the same set, by the same rules** — including the AI Gateway on a branch with no `neon.ts`. A function running locally gets the same Postgres / Auth / Data API / storage / AI Gateway vars a deploy would inject. Each `NEON_FUNCTION_<SLUG>_BASE_URL` this process is serving is rewritten to `http://localhost:<port>`: every neon.ts function, or the matching slug when `--source` names one. `neon env pull` and `neon-env run` write the production URL (`https://<branchId>-<slug>.compute.…`).
+
+Before `neon.ts` is evaluated, `dev` loads the project directory's `.env`, then `.env.local`, which overrides it, into the environment, so Function env values written as `process.env.X!` resolve the same way they do for `neon deploy --env`. A variable already set in the shell wins over both. Local Functions inherit every loaded variable, including keys `neon.ts` doesn't declare; the deployed runtime gets only declared and Neon-injected env. `--env <file>` loads only that file, resolved from the current directory, matching `neon deploy --env`:
+
+```bash
+neon dev                       # loads .env, then .env.local (overrides .env)
+neon dev --env .env.staging    # loads only .env.staging
+```
+
+`dev` writes nothing. To reuse the branch credential behind the AI Gateway and object storage, it reads only the file `env pull` writes (`.env` when it exists, otherwise `.env.local`), so an override in the other file cannot pair one credential's key ID with another's secret. Without a file to read from it issues one on every start and leaves the last one live — it has nowhere to keep it, and so cannot name it to revoke it. It says so when it happens; run `env pull` (or just `link` / `checkout`) once and restarts reuse the credential instead.
 
 **Where `.neon` lives**: `link` writes `.neon` into the **current working directory** by default. If an existing `.neon` is found in any parent directory, that file is reused — so commands run from a sub-directory of a linked project still pick up the project's context. To pin the location explicitly, pass `--context-file <path>`. `neon init` always writes `.neon` into the current directory.
 
@@ -890,7 +899,7 @@ Without a TTY, pass `-y` or enough flags to answer every question. `-y` alone is
 
 `--project-id`, `--org-id`, `--project-name`, `--region-id`, and `--branch` are forwarded to `link`. They select linking. A linked directory is not relinked unless you pass one of those flags.
 
-After a new default `neon.ts` on a pinned branch, init runs `env pull` unless link already pulled env or the file declares extra services (those still need `neon config plan` / `neon deploy`).
+Init pulls the branch's env vars once, after the `neon.ts` step, so the pull includes what `neon.ts` declares. The AI Gateway and Functions need no deploy and are pulled immediately. When `neon.ts` declares Auth, the Data API, Object Storage, or Realtime, init pulls Postgres, plus the AI Gateway and the scaffolded function's URL when declared. `neon deploy` provisions the rest and pulls their env vars. An existing `neon.ts` is pulled by `link` as usual.
 
 A failed step stops the rest. `--profile` and `--config-dir` are forwarded to each child. `--output json` and `--output yaml` are refused; the commands init runs print their own output.
 

package/dist/commands/dev.js

@@ -2,13 +2,14 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { isClaimableEnvTarget } from "../claimable/state.js";
 import { getCliName } from "../utils/cli_name.js";
-import { readEnvFile, resolveEnvFilePath } from "../env_file.js";
+import { defaultDevEnvFiles, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { l as functionBaseUrlKey } from "../_chunks/env-BpP3Dqpe.js";
-import { branchIdResolve } from "../utils/enrichers.js";
-import { bundleEntry } from "../utils/esbuild.js";
 import { a as resolveDevEnv } from "../_chunks/env-BNm69Qh8.js";
 import { findConfigFunctionBySource, resolveFunctionsFromConfig } from "../dev/functions.js";
 import { resolveWatchInputs } from "../dev/inputs.js";
+import { branchIdResolve } from "../utils/enrichers.js";
+import { bundleEntry } from "../utils/esbuild.js";
+import { envFlag } from "./config.js";
 import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -20,13 +21,16 @@ import { createServer } from "node:net";
 //#region src/commands/dev.ts
 var dev_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,
+	captureShellEnv: () => captureShellEnv,
 	command: () => "dev",
 	describe: () => describe,
 	devBundleDir: () => devBundleDir,
 	devEnvContext: () => devEnvContext,
 	diffUnits: () => diffUnits,
+	formatEnvFiles: () => formatEnvFiles,
 	formatEnvSummary: () => formatEnvSummary,
 	handler: () => handler,
+	loadDevEnvFiles: () => loadDevEnvFiles,
 	localFunctionUrlEnv: () => localFunctionUrlEnv,
 	planFunctionsToUnits: () => planFunctionsToUnits,
 	reportDevCredential: () => reportDevCredential,
@@ -42,7 +46,8 @@ const builder = (argv) => argv.usage("$0 dev [--source <path>] [options]").examp
 	port: {
 		describe: "Port to listen on (single-function mode only, with --source). Fails if taken. Without it (and without a PORT env var) a free port is chosen automatically.",
 		type: "number"
-	}
+	},
+	...envFlag
 }).epilogue([
 	"",
 	"Functions run with the linked branch's Neon env injected, the same set the",
@@ -55,9 +60,14 @@ const builder = (argv) => argv.usage("$0 dev [--source <path>] [options]").examp
 	"this process is serving (every neon.ts function, or the matching slug when",
 	"`--source` names one).",
 	"",
-	"`dev` reads your .env / .env.local to reuse the branch credential behind the",
-	"AI Gateway and object storage, and never writes to them. With no such file it",
-	"issues a credential on every start, so run `env pull` once if you restart often."
+	"Before neon.ts is evaluated, `dev` loads the project's .env, then .env.local,",
+	"which overrides it, into the environment, so Function env values that read",
+	"process.env resolve. A variable already set in the shell wins. `--env <file>`",
+	"loads only that file instead. Functions inherit every loaded variable.",
+	"",
+	"`dev` reuses the branch credential behind the AI Gateway and object storage from",
+	"the file `env pull` writes, and never writes to it. With no such file it issues a",
+	"credential on every start, so run `env pull` once if you restart often."
 ].join("\n")).strict();
 /**
 * The resolver context for a `neon dev` run.
@@ -74,7 +84,7 @@ const builder = (argv) => argv.usage("$0 dev [--source <path>] [options]").examp
 *   last one live — one orphan per restart. `neon-env run` already reads the file for this
 *   reason; `dev` was the one that didn't.
 */
-const devEnvContext = (props, branchId, cwd) => {
+const devEnvContext = (props, branchId, cwd, baseEnv = process.env) => {
 	const location = {
 		cwd,
 		...props.contextFile ? { contextFile: props.contextFile } : {}
@@ -84,7 +94,7 @@ const devEnvContext = (props, branchId, cwd) => {
 		...location,
 		implyAiGateway: true,
 		env: {
-			...process.env,
+			...baseEnv,
 			...existsSync(envFile) ? readEnvFile(envFile) : {}
 		},
 		...props.projectId ? { projectId: props.projectId } : {},
@@ -114,22 +124,70 @@ const reportDevCredential = (credential) => {
 	log.warning(`Resolved credential secrets for this run (%s) without writing them to a file. Run \`${getCliName()} env pull\` once so restarts reuse them instead of revealing or minting again.`, credential.keys.join(", "));
 };
 const handler = async (props) => {
+	const shellEnv = captureShellEnv();
+	const envFiles = formatEnvFiles(loadDevEnvFiles(props, process.cwd()), process.cwd());
 	if (props.source !== void 0) {
-		await runSingleSource(props);
+		await runSingleSource(props, shellEnv, envFiles);
 		return;
 	}
 	if (props.port !== void 0) throw new Error("--port can only be used with --source. To set ports for the functions in neon.ts, give each one a `dev.port` in its config.");
-	await runFromConfig(props);
+	await runFromConfig(props, shellEnv, envFiles);
+};
+/**
+* Copy of the shell env before any dotenv file loads. PORT is read through `process.env`,
+* which is case-insensitive on Windows, so a shell `Port` still sets the port. Exported for
+* unit testing.
+*/
+const captureShellEnv = () => ({
+	...process.env,
+	PORT: process.env.PORT
+});
+/**
+* Load dotenv files into process.env before neon.ts is evaluated: `--env <file>` alone
+* (relative to cwd), else the project's {@link defaultDevEnvFiles}. A later file overrides
+* an earlier one; a key set before loading (the shell) is never overridden.
+*/
+const loadDevEnvFiles = (props, cwd) => {
+	const files = props.env ? [resolve(cwd, props.env)] : defaultDevEnvFiles({
+		cwd,
+		...props.contextFile ? { contextFile: props.contextFile } : {}
+	});
+	const name = (key) => process.platform === "win32" ? key.toUpperCase() : key;
+	const preset = new Set(Object.keys(process.env).filter((key) => process.env[key] !== void 0).map(name));
+	return files.map((path) => {
+		const applied = [];
+		for (const [key, value] of Object.entries(readEnvFile(path))) {
+			if (preset.has(name(key))) continue;
+			process.env[key] = value;
+			applied.push(key);
+		}
+		return {
+			path,
+			applied
+		};
+	});
+};
+/**
+* The banner's account of the dotenv files, in load order, e.g.
+* `.env.local (4 vars) → .env (2 vars)`. Counts are the keys each file set. Exported for
+* unit testing.
+*/
+const formatEnvFiles = (files, cwd) => {
+	if (files.length === 0) return "none (no .env.local or .env)";
+	return files.map(({ path, applied }) => {
+		const count = `${applied.length} var${applied.length === 1 ? "" : "s"}`;
+		return `${relative(cwd, path) || path} (${count})`;
+	}).join(" → ");
 };
 /** Single-function mode: serve exactly the `--source` path (legacy behavior). */
-const runSingleSource = async (props) => {
+const runSingleSource = async (props, shellEnv, envFiles) => {
 	const source = resolve(process.cwd(), props.source);
 	if (!existsSync(source)) throw new Error(`Source file not found: ${source}`);
 	const branchId = await resolveBranchId(props);
-	const { vars: neonEnv, skipped, credential } = await resolveDevEnv(devEnvContext(props, branchId, process.cwd()));
+	const { vars: neonEnv, skipped, credential } = await resolveDevEnv(devEnvContext(props, branchId, process.cwd(), shellEnv));
 	reportDevCredential(credential);
 	const match = await findConfigFunctionBySource(process.cwd(), source, props.contextFile);
-	const { overlay, port } = await sourceFunctionUrlOverlay(match, props.port);
+	const { overlay, port } = await sourceFunctionUrlOverlay(match, props.port, shellEnv);
 	const unit = {
 		slug: null,
 		source,
@@ -144,19 +202,22 @@ const runSingleSource = async (props) => {
 			fn: []
 		}
 	};
-	await runSupervisor([unit], { ...skipped ? { envNote: skipped.reason } : {} });
+	await runSupervisor([unit], {
+		envFiles,
+		...skipped ? { envNote: skipped.reason } : {}
+	});
 };
 /**
 * Multi-function mode: serve every function declared in neon.ts. Requires a neon.ts
 * (there is no single source to fall back on), one dev server per function.
 */
-const runFromConfig = async (props) => {
+const runFromConfig = async (props, shellEnv, envFiles) => {
 	const branchId = await resolveBranchId(props);
 	const resolved = await resolveFunctionsFromConfig(process.cwd(), void 0, props.contextFile);
 	if (resolved === null) throw new Error("No --source given and no neon.ts found. Pass --source <path> to run a single function, or add a neon.ts that declares functions under `functions`.");
 	const { configPath, functions } = resolved;
 	if (functions.length === 0) throw new Error("neon.ts has no functions to serve. Add at least one under `functions`, or pass --source <path>.");
-	const { vars: neonEnv, skipped, credential } = await resolveDevEnv(devEnvContext(props, branchId, process.cwd()));
+	const { vars: neonEnv, skipped, credential } = await resolveDevEnv(devEnvContext(props, branchId, process.cwd(), shellEnv));
 	reportDevCredential(credential);
 	const units = await planFunctionsToUnits(functions, neonEnv, DEFAULT_PORT_BASE);
 	const replan = async (searchBase, keepPorts) => {
@@ -169,6 +230,7 @@ const runFromConfig = async (props) => {
 			configPath,
 			replan
 		},
+		envFiles,
 		...skipped ? { envNote: skipped.reason } : {}
 	});
 };
@@ -231,8 +293,8 @@ const localFunctionUrlEnv = (functions) => {
 * `--source` serves one file. If that file is a neon.ts function, rewrite only that
 * slug to localhost — this process is not listening for the others.
 */
-const sourceFunctionUrlOverlay = async (match, cliPort) => {
-	const portSpec = portFromProps(cliPort);
+const sourceFunctionUrlOverlay = async (match, cliPort, shellEnv = process.env) => {
+	const portSpec = portFromProps(cliPort, shellEnv);
 	if (match === void 0) return {
 		overlay: {},
 		port: portSpec
@@ -298,14 +360,14 @@ const resolveBranchId = async (props) => {
 	}
 };
 const DEFAULT_PORT_BASE = 8787;
-const portFromProps = (port) => {
+const portFromProps = (port, shellEnv) => {
 	if (port !== void 0) return {
 		mode: "explicit",
 		port
 	};
-	if (process.env.PORT !== void 0 && process.env.PORT !== "") return {
+	if (shellEnv.PORT !== void 0 && shellEnv.PORT !== "") return {
 		mode: "explicit",
-		port: Number(process.env.PORT)
+		port: Number(shellEnv.PORT)
 	};
 	return {
 		mode: "search",
@@ -387,7 +449,7 @@ const READY_PATTERN = /neon-dev:ready (\d+)/;
 * in place; siblings are untouched.
 */
 const runSupervisor = async (units, options = {}) => {
-	const { reload, envNote } = options;
+	const { reload, envNote, envFiles } = options;
 	const runtimePath = resolveRuntimePath();
 	let shuttingDown = false;
 	const running = units.map(makeRunningUnit);
@@ -456,7 +518,7 @@ const runSupervisor = async (units, options = {}) => {
 		await Promise.all(running.map((r) => stopUnit(r)));
 		throw new Error("No function started. See the output above for details.");
 	}
-	printBanner(running, envNote);
+	printBanner(running, envNote, envFiles);
 	let configWatcher = null;
 	if (reload) {
 		const ops = {
@@ -709,10 +771,14 @@ const pipeChildOutput = (child, label) => {
 	forward("stdout");
 	forward("stderr");
 };
-const printBanner = (running, envNote) => {
+const printBanner = (running, envNote, envFiles) => {
 	log.info("");
 	log.info(chalk.green.bold("  Neon Functions dev server"));
 	log.info("");
+	if (envFiles) {
+		log.info(`  ${chalk.dim("env files".padEnd(20))} ${chalk.dim(envFiles)}`);
+		log.info("");
+	}
 	for (const r of running) {
 		const name = r.unit.label ?? "function";
 		const url = urlFor(r.boundPort);
@@ -876,4 +942,4 @@ const resolveRuntimePath = () => {
 	return candidate;
 };
 //#endregion
-export { builder, command, describe, devBundleDir, devEnvContext, diffUnits, formatEnvSummary, handler, localFunctionUrlEnv, planFunctionsToUnits, reportDevCredential, sourceFunctionUrlOverlay, dev_exports as t };
+export { builder, captureShellEnv, command, describe, devBundleDir, devEnvContext, diffUnits, formatEnvFiles, formatEnvSummary, handler, loadDevEnvFiles, localFunctionUrlEnv, planFunctionsToUnits, reportDevCredential, sourceFunctionUrlOverlay, dev_exports as t };

package/dist/commands/env.js

@@ -7,9 +7,9 @@ import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOpt
 import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { t as NEON_ENV_VAR_KEYS, u as isFunctionBaseUrlKey } from "../_chunks/env-BpP3Dqpe.js";
 import { ENV_PULL_KEY_HELP, ENV_PULL_SERVICES, envKeysForSelection, envPullFlagValue, ownedEnvServiceKeys, parseEnvPullKeys } from "../env_services.js";
+import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-BNm69Qh8.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { warnAiGateway } from "../utils/ai_gateway_notice.js";
-import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-BNm69Qh8.js";
 import { formatPulledEnv, pulledBranch } from "./env_output.js";
 import { existsSync } from "node:fs";
 import chalk from "chalk";

package/dist/commands/link.js

@@ -864,7 +864,7 @@ const printSummary = (props, summary) => {
 */
 const finalizeLink = async (props, summary) => {
 	printSummary(props, summary);
-	if (!summary.branch || !summary.projectId || summary.noChecks) return;
+	if (!summary.branch || !summary.projectId || summary.noChecks || props.deferEnvPull === true) return;
 	const { config: _offerConfig, ...rest } = props;
 	await autoPullEnvAfterPin({
 		...rest,

package/dist/commands/subscribe.js

@@ -1,6 +1,6 @@
 import { writer } from "../writer.js";
-import { branchIdFromProps } from "../utils/enrichers.js";
 import { o as resolveNeonEnvVars } from "../_chunks/env-BNm69Qh8.js";
+import { branchIdFromProps } from "../utils/enrichers.js";
 import YAML from "yaml";
 //#region src/commands/subscribe.ts
 const builder = (argv) => argv.usage("$0 realtime subscribe \"<query>\" [options]").positional("query", {

package/dist/dev/runtime.js

@@ -121,6 +121,14 @@ const portSelectionFromEnv = (env) => {
 		mode: "explicit",
 		port: parsePort(explicit, "NEON_DEV_PORT")
 	};
+	const searchBase = env.NEON_DEV_PORT_BASE;
+	if (searchBase !== void 0 && searchBase !== "") {
+		const from = Number(searchBase);
+		return {
+			mode: "search",
+			from: Number.isInteger(from) ? from : DEFAULT_SEARCH_BASE
+		};
+	}
 	const injected = env.PORT;
 	if (injected !== void 0 && injected !== "") return {
 		mode: "explicit",

package/dist/env_file.js

@@ -15,6 +15,14 @@ const resolveEnvFilePath = (location, file) => {
 	return join(dir, ".env.local");
 };
 /**
+* The dotenv files `neon dev` loads by default, in load order: the project directory's
+* `.env`, then `.env.local`, whose values override it. Missing files are skipped.
+*/
+const defaultDevEnvFiles = (location) => {
+	const dir = projectDir(location);
+	return [join(dir, ".env"), join(dir, ".env.local")].filter((path) => existsSync(path));
+};
+/**
 * Merge `updates` into the dotenv content at `path`, preserving every other line
 * (comments, blank lines, unrelated keys) and the file's existing order. Keys present in
 * both are updated in place; keys only in `updates` are appended. A non-existent file is
@@ -145,4 +153,4 @@ const trimTrailingBlank = (lines) => {
 	return out;
 };
 //#endregion
-export { loadEnvFileIntoProcess, mergeEnvContent, mergeEnvFile, readEnvFile, resolveEnvFilePath };
+export { defaultDevEnvFiles, loadEnvFileIntoProcess, mergeEnvContent, mergeEnvFile, readEnvFile, resolveEnvFilePath };

package/dist/init/auth.js

@@ -61,10 +61,7 @@ const runAuthenticatedMcp = async (options) => {
 const pullInitEnv = async (props) => {
 	const authenticated = authContext(props, ["env", "pull"]);
 	await ensureAuth(authenticated);
-	const opts = {
-		announce: true,
-		implyAiGateway: true
-	};
+	const opts = { announce: true };
 	try {
 		return await pull(authenticated, opts);
 	} catch (error) {

package/dist/init/choices.js

@@ -1,3 +1,5 @@
+import { FUNCTION_SLUG } from "../config_template.js";
+import { l as functionBaseUrlKey } from "../_chunks/env-BpP3Dqpe.js";
 //#region src/init/choices.ts
 const INIT_CONFIG_SERVICES_CONFLICT = "--no-config cannot be combined with --services.";
 const resolveInitConfigChoice = (input) => {
@@ -21,11 +23,23 @@ const configPlanFromResolution = (resolution, accepted) => {
 	if (resolution.kind === "skip") return { kind: "skip" };
 	return resolution;
 };
-const shouldRefreshEnvAfterNewConfig = (input) => input.wroteNewFile && typeof input.projectId === "string" && input.projectId.length > 0 && typeof input.branch === "string" && input.branch.length > 0;
-const shouldPullEnvAfterInitConfig = (input) => !input.extraServices && !input.alreadyPulled && shouldRefreshEnvAfterNewConfig({
-	wroteNewFile: input.wroteNewFile,
-	...input.projectId !== void 0 ? { projectId: input.projectId } : {},
-	...input.branch !== void 0 ? { branch: input.branch } : {}
-});
+/**
+* A neon.ts policy pull fails while the branch lacks a declared service. These two need
+* no `deploy`: the AI Gateway exists on every branch, and function URLs derive from the
+* branch host.
+*/
+const DEPLOY_FREE_SERVICES = /* @__PURE__ */ new Set(["ai-gateway", "functions"]);
+const needsDeploy = (declared) => declared.some((service) => !DEPLOY_FREE_SERVICES.has(service));
+const initEnvPullAfterConfig = (input) => {
+	if (!input.projectId || !input.branch) return { kind: "skip" };
+	if (!input.linkDeferredPull && !input.wroteNewFile) return { kind: "skip" };
+	if (input.claimable && input.declared.length > 0) return { kind: "skip" };
+	if (!needsDeploy(input.declared)) return { kind: "policy" };
+	return {
+		kind: "services",
+		services: input.declared.includes("ai-gateway") ? ["postgres", "ai-gateway"] : ["postgres"],
+		envKeys: input.declared.includes("functions") ? [functionBaseUrlKey(FUNCTION_SLUG)] : []
+	};
+};
 //#endregion
-export { INIT_CONFIG_SERVICES_CONFLICT, configPlanFromResolution, resolveInitConfigChoice, shouldPullEnvAfterInitConfig, shouldRefreshEnvAfterNewConfig };
+export { INIT_CONFIG_SERVICES_CONFLICT, configPlanFromResolution, initEnvPullAfterConfig, resolveInitConfigChoice };

package/dist/init/copy.js

@@ -99,16 +99,22 @@ const offlinePinNext = (input) => [
 	...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 = () => [
-	"Review neon.ts and confirm the linked project and branch before deploying.",
+const extraServicesNext = (input) => [
 	"Preview the changes:",
 	`${getCliName()} config plan`,
 	"",
-	"Deploy when the changes and target are correct:",
+	"Deploy when the changes and target are correct. Deploy also pulls the branch's environment variables:",
 	`${getCliName()} deploy`,
 	"",
-	"Refresh local environment variables after deployment:",
-	`${getCliName()} env pull`
+	"Optional, once deployed:",
+	...input.functions ? [
+		"Run Neon Functions locally:",
+		`${getCliName()} dev`,
+		""
+	] : [],
+	"Work on a development branch created from neon.ts:",
+	`${getCliName()} checkout dev --create`,
+	...input.skills ? ["", "Set up the services declared in neon.ts with your coding agent. The Neon agent skills cover best practices for each one."] : []
 ];
 const existingConfigNext = () => ["The existing Neon config was preserved. Refresh environment variables when its declared services are available:", `${getCliName()} env pull`];
 const claimableNext = (expiresAt) => [
@@ -128,10 +134,18 @@ const claimableThenServicesNext = (expiresAt) => [
 	"Refresh local environment variables:",
 	`${getCliName()} env pull`
 ];
-const installFailedNext = (command) => ({
+const installFailedNext = (command, envPull) => ({
 	heading: HEADING_FAILED,
 	body: "Could not install the Neon dependencies.",
-	next: ["Install the dependencies, then run neon init again:", command]
+	next: [
+		"Install the dependencies, then run neon init again:",
+		command,
+		...envPull ? [
+			"",
+			"Then pull the branch's environment variables:",
+			`${getCliName()} env pull`
+		] : []
+	]
 });
 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. */

package/dist/init/run.js

@@ -26,7 +26,7 @@ import { InitCancelled, raceSigint, restoreCursor } from "./cancelled.js";
 import { pickAgentSetupInteractively, pickInitAgentsInteractively, pickInitConfigInteractively, pickInitMcpAuthInteractively, pickInitMcpConfigLocationInteractively, pickInitModeInteractively, pickInitPackageManagerInteractively, pickInitProjectSetupInteractively, pickInitServicesInteractively, pickInitSkillsInteractively } from "./wizard.js";
 import { runToolingSteps } from "./tooling.js";
 import { create } from "../commands/claim.js";
-import { INIT_CONFIG_SERVICES_CONFLICT, configPlanFromResolution, resolveInitConfigChoice, shouldPullEnvAfterInitConfig } from "./choices.js";
+import { INIT_CONFIG_SERVICES_CONFLICT, configPlanFromResolution, initEnvPullAfterConfig, resolveInitConfigChoice } from "./choices.js";
 import { detectInitEnvironment } from "./detect.js";
 import { createInitFunnel, emitInitStart, finishInitFunnel, initStartProperties } from "./funnel.js";
 import { assertAgentSetupFlags, hasInitMcpFlags, inferInitAgentSetup, resolveInitMode } from "./mode.js";
@@ -369,7 +369,6 @@ const runInit = async (props) => {
 		});
 		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;
@@ -394,6 +393,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);
+		const deferLinkPull = !existingConfig && props.config !== false;
 		const linkProps = {
 			apiClient: props.apiClient,
 			apiKey: props.apiKey,
@@ -404,6 +404,7 @@ const runInit = async (props) => {
 			clear: false,
 			checks: true,
 			envPull: true,
+			deferEnvPull: deferLinkPull,
 			config: false,
 			cwd,
 			...linkInputs,
@@ -425,13 +426,11 @@ const runInit = async (props) => {
 				apiKey: props.apiKey,
 				...props.profile !== void 0 ? { profile: props.profile } : {}
 			});
-			linkedNow = true;
 			funnel.link = "claimable";
 			claimExpiresAt = readLinkedClaimableCredentials(configDir, readContextFile(contextFile))?.expiresAt;
 		} else if (projectSetup === "link") {
 			printInitProgress(detection.authenticated ? PROGRESS.link : PROGRESS.auth);
 			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;
@@ -441,7 +440,6 @@ const runInit = async (props) => {
 				checks: false,
 				envPull: false
 			});
-			linkedNow = true;
 			funnel.link = "linked";
 		}
 		if (delayMcp && tooling.setup !== "skip" && props.mcpProjectScoped === true && funnel.link === "skipped" && !noLink) mcpState.deferredPin = linkInputs.projectId !== void 0 ? quoteFlagValue(linkInputs.projectId) : "<project-id>";
@@ -501,11 +499,13 @@ const runInit = async (props) => {
 		};
 		let wroteNewFile = false;
 		let extraServices = false;
+		let declared = [];
 		let selectedServices = null;
+		const linkDeferredPull = deferLinkPull && projectSetup === "link" && funnel.link === "linked";
 		if (configPlan.kind === "write") {
 			const planned = existingConfig ? void 0 : configPlan.services ?? ["postgres"];
 			if (planned !== void 0) {
-				const declared = parseConfigInitServices(planned);
+				declared = parseConfigInitServices(planned);
 				extraServices = declared.length > 0;
 				selectedServices = expandTelemetryServices(declared);
 				funnel.services = selectedServices;
@@ -528,7 +528,7 @@ const runInit = async (props) => {
 				});
 			} catch (error) {
 				if (error instanceof ConfigInstallFailed) {
-					const failed = installFailedNext(error.command);
+					const failed = installFailedNext(error.command, linkDeferredPull);
 					printInitDone(formatInitDone({
 						heading: failed.heading,
 						body: failed.body,
@@ -546,14 +546,15 @@ const runInit = async (props) => {
 		const context = readContextFile(contextFile);
 		const branch = contextBranch(context);
 		const linked = isLinked(contextFile);
-		const alreadyPulled = linkedNow && funnel.link === "linked" && !pinnedOffline;
-		if (funnel.link !== "skipped" && !pinnedOffline && shouldPullEnvAfterInitConfig({
+		const envPullPlan = funnel.link === "skipped" || pinnedOffline ? { kind: "skip" } : initEnvPullAfterConfig({
+			linkDeferredPull,
 			wroteNewFile,
-			extraServices,
-			alreadyPulled,
+			declared,
+			claimable: funnel.link === "claimable",
 			...typeof context.projectId === "string" ? { projectId: context.projectId } : {},
 			...branch !== void 0 ? { branch } : {}
-		})) try {
+		});
+		if (envPullPlan.kind !== "skip") try {
 			if (typeof context.projectId !== "string" || typeof branch !== "string") throw new Error("Env pull requires a linked project and branch.");
 			printInitProgress(PROGRESS.env);
 			await raceSigint((props.envPull ?? pullInitEnv)({
@@ -561,7 +562,11 @@ const runInit = async (props) => {
 				output: props.output,
 				cwd,
 				projectId: context.projectId,
-				branch
+				branch,
+				...envPullPlan.kind === "services" ? {
+					services: envPullPlan.services,
+					envKeys: envPullPlan.envKeys
+				} : {}
 			}));
 		} catch (error) {
 			if (error instanceof InitCancelled) throw error;
@@ -617,7 +622,10 @@ const runInit = async (props) => {
 			next.push(...claimableNext(claimExpiresAt));
 		} else if (pendingServices) {
 			if (next.length > 0) next.push("");
-			next.push(...extraServicesNext());
+			next.push(...extraServicesNext({
+				skills: installsSkills(reportedTooling()),
+				functions: declared.includes("functions")
+			}));
 		} else if (pendingExisting) {
 			if (next.length > 0) next.push("");
 			next.push(...existingConfigNext());
@@ -698,6 +706,8 @@ const withoutMcp = (tooling) => {
 	};
 	return tooling;
 };
+/** The Neon plugin bundles the skills. */
+const installsSkills = (tooling) => tooling.setup === "skills-mcp" ? tooling.skillsAgents.length > 0 : tooling.setup !== "skip";
 const agentsFromTooling = (tooling) => {
 	switch (tooling.setup) {
 		case "skip": return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "8.5.0",
+  "version": "8.6.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -70,10 +70,10 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/sdk": "7.2.0",
-    "@neon/realtime": "0.1.0",
+    "@neon/config": "1.9.1",
     "@neon/config-runtime": "1.10.0",
-    "@neon/config": "1.9.1"
+    "@neon/realtime": "0.1.0",
+    "@neon/sdk": "7.2.0"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",
@@ -111,8 +111,8 @@
     "vitest": "^3.0.9",
     "@neon-internals/cli-core": "0.0.0",
     "@neon-internals/env-core": "0.0.32",
-    "@neon/env": "1.6.2",
     "@neon/e2e-harness": "0.0.0",
+    "@neon/env": "1.6.2",
     "@neon/functions": "0.11.0"
   },
   "publishConfig": {