@selvajs/cli 4.8.0-beta.11 → 4.8.0-beta.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "4.8.0-beta.11",
+  "version": "4.8.0-beta.13",
   "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
   "license": "MIT",
   "author": "VektorNode",

package/src/checks/config.js

@@ -65,6 +65,106 @@ export function checkOrigin(env) {
 	return green(`ORIGIN=${env.ORIGIN}`);
 }
 
+// Duplicated from HeaderAuthProvider.DEFAULT_HEADERS to avoid loading the runtime here.
+// A test in providers/header-auth pins both sides, so drift surfaces in CI.
+export const DEFAULT_HEADER_NAMES = {
+	upn: 'SELVA-UserPrincipalName',
+	email: 'SELVA-Email',
+	displayName: 'SELVA-DisplayName'
+};
+
+// oauth2-proxy's `set_xauthrequest` names. Two proxy styles are documented and
+// both are correct, but they need opposite env config:
+//
+//   rewrite      — Caddy maps X-Auth-Request-* onto SELVA-* before proxying.
+//                  Selva sees SELVA-*, so the overrides must be UNSET.
+//   copy-through — Caddy forwards X-Auth-Request-* unchanged.
+//                  Selva sees those names, so all three must be overridden.
+//
+// Mixing them is the failure this check exists to catch: a name Selva reads but
+// the proxy never sends yields `null` from identifyFromHeaders (for the UPN, a
+// total login failure) with nothing in the logs pointing at the env var.
+const OAUTH2_PROXY_HEADERS = new Set([
+	'x-auth-request-user',
+	'x-auth-request-email',
+	'x-auth-request-preferred-username'
+]);
+
+/**
+ * Reports the header names the provider will actually read, and flags the
+ * combinations that can't match any documented proxy config.
+ *
+ * Deliberately not a "did you override all three" count: with the rewrite
+ * style, zero overrides is the correct answer, so counting alone would push
+ * operators toward breaking a working deployment.
+ */
+export function checkHeaderNames(env) {
+	const resolved = {
+		upn: env.HEADER_AUTH_UPN_HEADER || DEFAULT_HEADER_NAMES.upn,
+		email: env.HEADER_AUTH_EMAIL_HEADER || DEFAULT_HEADER_NAMES.email,
+		displayName: env.HEADER_AUTH_DISPLAY_NAME_HEADER || DEFAULT_HEADER_NAMES.displayName
+	};
+	const list = `UPN=${resolved.upn}, Email=${resolved.email}, DisplayName=${resolved.displayName}`;
+
+	const oauth2 = Object.values(resolved).filter((h) =>
+		OAUTH2_PROXY_HEADERS.has(h.toLowerCase())
+	).length;
+	const defaults = Object.entries(resolved).filter(
+		([slot, name]) => name === DEFAULT_HEADER_NAMES[slot]
+	).length;
+
+	if (oauth2 === 0) {
+		return defaults === 3
+			? green(`header names (bundled defaults): ${list}`)
+			: green(`header names (custom): ${list}`);
+	}
+
+	// Some X-Auth-Request-*, some SELVA-* defaults — neither proxy style emits
+	// that mix, so whichever slots are still on a default are being read from a
+	// header nothing sets.
+	if (defaults > 0) {
+		const stale = Object.entries(resolved)
+			.filter(([slot, name]) => name === DEFAULT_HEADER_NAMES[slot])
+			.map(([slot, name]) => `${slot}=${name}`)
+			.join(', ');
+		return yellow(
+			`header names mix oauth2-proxy and bundled-default names: ${list} — ` +
+				`${stale} will never arrive if your proxy forwards X-Auth-Request-* unchanged. ` +
+				`Either override all three with the X-Auth-Request-* names, or map them to SELVA-* ` +
+				`in the proxy and unset all three overrides.`
+		);
+	}
+
+	return green(`header names (oauth2-proxy pass-through): ${list}`);
+}
+
+// Below this, an annotated .env is just a slightly chatty config file; above it
+// the operator is scrolling past screens of prose that no command can correct.
+const COMMENT_LINE_BUDGET = 40;
+
+/**
+ * Flags a `.env` still carrying the shipped documentation block.
+ *
+ * The block is a snapshot of the release the deployment was installed at.
+ * `migrate` rewrites keys but never prose, so those comments keep describing
+ * vars the code has since renamed or retired — confidently wrong instructions
+ * sitting in the file an operator reaches for first. Nothing breaks, which is
+ * why this is yellow, and why it needs saying at all.
+ */
+export function checkEnvDocumentation(commentLines, fix) {
+	if (commentLines <= COMMENT_LINE_BUDGET) {
+		return green('.env is values-only');
+	}
+	return yellow(
+		`.env carries ~${commentLines} lines of shipped documentation. Comments are ` +
+			`never updated by \`selva migrate\`, so they still describe the release this ` +
+			`deployment was installed at — including variables the code no longer reads. ` +
+			`Strip them (values and your own inline notes are kept, .env.bak written):\n     ` +
+			`npx selva doctor --fix`,
+		fix
+	);
+}
+
 // A rename is auto-fixable (`selva migrate` rewrites the key). A replacement
 // encodes a value in the new name, so migrate leaves it alone rather than
 // guessing — it's reported here and nowhere else.

package/src/checks/runtime.js

@@ -15,7 +15,7 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { green, red, yellow } from './result.js';
+import { fixable, green, red, yellow } from './result.js';
 import { PM2_VERSION } from '../deployment-package.js';
 
 /** The real OS. Tests pass a stand-in with the same shape. */
@@ -56,7 +56,8 @@ export function checkRuntimeEnvironment(dir, env = runtimeEnv) {
 		checkNpm(env),
 		checkNodeProvenance(env),
 		...checkPm2Install(dir, env),
-		...checkPm2Daemon(dir, env)
+		...checkPm2Daemon(dir, env),
+		...checkPm2LogRotation(dir, env)
 	];
 }
 
@@ -112,7 +113,9 @@ function checkNodeProvenance(env) {
 		?.trim();
 
 	if (!onPath) {
-		return yellow(`Node v${process.versions.node} at ${running} (${source}) — not resolvable on PATH`);
+		return yellow(
+			`Node v${process.versions.node} at ${running} (${source}) — not resolvable on PATH`
+		);
 	}
 
 	if (env.realpath(onPath) === running) {
@@ -268,6 +271,81 @@ function checkPm2Daemon(dir, env) {
 	];
 }
 
+// ── pm2 log rotation ────────────────────────────────────────────────────
+
+// pm2 appends to `$PM2_HOME/logs/*.log` forever. Nothing in a default install
+// truncates them, and the app writes a line per solve — so the only bound is
+// the disk. It fails late and all at once: the partition fills, and pm2 and the
+// app go down together on a box that looked healthy the day before.
+//
+// Detected from the filesystem, never by running `pm2 ls`: an invocation with
+// no live daemon spawns one as a side effect, which doctor must not do (see
+// checkPm2Daemon). Installed modules live in `$PM2_HOME/node_modules`.
+function checkPm2LogRotation(dir, env) {
+	const bin = join(dir, 'node_modules', '.bin', env.platform() === 'win32' ? 'pm2.cmd' : 'pm2');
+	if (!env.exists(bin)) return [];
+
+	const pm2Home = env.env().PM2_HOME ?? join(env.homedir(), '.pm2');
+	if (env.exists(join(pm2Home, 'node_modules', 'pm2-logrotate'))) {
+		return [green('pm2-logrotate installed — pm2 logs are rotated')];
+	}
+
+	return [
+		yellow(
+			'pm2-logrotate is not installed — pm2 logs grow without bound and are only\n     ' +
+				'capped by free disk. Install it (takes effect immediately, no restart):\n     ' +
+				'npx pm2 install pm2-logrotate\n     ' +
+				`npx pm2 set pm2-logrotate:rotateInterval "${LOGROTATE_SETTINGS.rotateInterval}"\n     ` +
+				`npx pm2 set pm2-logrotate:retain ${LOGROTATE_SETTINGS.retain}\n     ` +
+				`npx pm2 set pm2-logrotate:compress ${LOGROTATE_SETTINGS.compress}`,
+			fixable('install pm2-logrotate (weekly rotation, 8 kept, compressed)', () =>
+				installLogRotate(bin, dir, env)
+			)
+		)
+	];
+}
+
+/**
+ * Weekly on Sunday 00:00, keeping 8 — about two months of history, compressed.
+ *
+ * Weekly rather than pm2's daily default: a Selva deployment writes a line per
+ * solve, so daily files are mostly idle days, and two months of them is a lot
+ * of near-empty archives to page through when tracing an incident.
+ */
+const LOGROTATE_SETTINGS = {
+	rotateInterval: '0 0 * * 0',
+	retain: 8,
+	compress: true
+};
+
+// `pm2 install` needs no root and doesn't restart managed processes, which is
+// what makes it eligible as a doctor fixer at all. The settings are applied
+// after: failing to set one leaves rotation on at pm2's defaults, which still
+// beats unbounded growth, so a failed `set` is reported, not fatal.
+function installLogRotate(bin, dir, env) {
+	const install = env.run(bin, ['install', 'pm2-logrotate'], { cwd: dir });
+	if ((install.status ?? 1) !== 0) {
+		const detail = String(install.stderr ?? install.stdout ?? '')
+			.trim()
+			.split('\n')
+			.pop();
+		return red(`\`pm2 install pm2-logrotate\` failed${detail ? `: ${detail}` : ''}`);
+	}
+
+	const failed = [];
+	for (const [key, value] of Object.entries(LOGROTATE_SETTINGS)) {
+		const set = env.run(bin, ['set', `pm2-logrotate:${key}`, String(value)], { cwd: dir });
+		if ((set.status ?? 1) !== 0) failed.push(key);
+	}
+	if (failed.length > 0) {
+		return yellow(
+			`pm2-logrotate installed, but could not set: ${failed.join(', ')}. ` +
+				`Rotation is active at pm2's defaults; set them by hand with \`npx pm2 set\`.`
+		);
+	}
+	return green('pm2-logrotate installed — weekly rotation, 8 kept, compressed');
+}
+
 function parseSkew(output) {
 	// eslint-disable-next-line no-control-regex -- pm2 colourises via chalk on a TTY
 	const clean = output.replace(/\[[0-9;]*m/g, '');

package/src/cli.js

@@ -18,6 +18,59 @@ const COMMANDS = {
 	keys: () => import('./commands/keys.js').then((m) => keysDispatch(m))
 };
 
+// `selva doctor --help` used to run the full doctor: commands own their argv,
+// and only `doctor` reads a flag at all, so every other command silently
+// ignored `--help` and did its work. Intercepting here keeps `--help` uniform
+// across the whole surface without each command re-implementing it.
+const USAGE = {
+	init: {
+		usage: 'selva init',
+		blurb:
+			'Reconfigure this deployment. Prompts for the same values as scaffolding\nand rewrites .env; generated secrets are left alone.'
+	},
+	doctor: {
+		usage: 'selva doctor [--fix]',
+		blurb:
+			'Validate .env, providers, Node engine, pm2 boot persistence, and package\npins. Read-only without --fix.',
+		flags: [['--fix', 'Apply the repairs doctor reports as automatic. Prompts before each.']]
+	},
+	start: { usage: 'selva start', blurb: 'pm2 start ecosystem.config.cjs' },
+	stop: { usage: 'selva stop', blurb: 'pm2 stop selva-compute' },
+	restart: {
+		usage: 'selva restart',
+		blurb:
+			'pm2 restart selva-compute --update-env. The --update-env is why this\nexists: without it a pm2 restart keeps the old .env in memory.'
+	},
+	logs: { usage: 'selva logs', blurb: 'pm2 logs selva-compute' },
+	update: {
+		usage: 'selva update',
+		blurb:
+			'npm update @selvajs/cli + @selvajs/selva, then restart. Rolls the\ndependency tree back if the install fails.'
+	},
+	migrate: {
+		usage: 'selva migrate',
+		blurb:
+			'Bring package.json and the deployment layout onto the current release.\nRewrites keys, never comments.'
+	},
+	keys: {
+		usage: 'selva keys rotate <hmac|at-rest>',
+		blurb:
+			'Rotate one secret in .env. Destructive and not reversible — the command\nspells out the blast radius and asks before writing.'
+	}
+};
+
+function printCommandHelp(command) {
+	const entry = USAGE[command];
+	const lines = [pc.bold(entry.usage), '', entry.blurb];
+	if (entry.flags) {
+		lines.push('', pc.bold('Flags:'));
+		for (const [flag, description] of entry.flags) {
+			lines.push(`  ${flag.padEnd(22)}${description}`);
+		}
+	}
+	console.log(lines.join('\n'));
+}
+
 function keysDispatch(m) {
 	return async (argv) => {
 		const sub = argv[0];
@@ -51,6 +104,11 @@ export async function runSelva(argv) {
 		process.exit(1);
 	}
 
+	if (rest.includes('--help') || rest.includes('-h')) {
+		printCommandHelp(command);
+		return;
+	}
+
 	const run = await loader();
 	await run(rest);
 }
@@ -60,6 +118,8 @@ function printHelp() {
 		[
 			pc.bold('selva') + ' — operate a Selva deployment',
 			'',
+			pc.bold('Usage:') + '  npx selva <command>',
+			'',
 			pc.bold('Commands:'),
 			'  init                    Reconfigure this deployment (prompts again)',
 			'  doctor [--fix]          Validate env, providers, Node engine, and packages',
@@ -71,7 +131,15 @@ function printHelp() {
 			'  migrate                 Bring package.json onto the current layout',
 			'  keys rotate <hmac|at-rest>   Rotate a secret in .env (destructive)',
 			'',
-			pc.dim('To scaffold a new deployment: ') + pc.cyan('npx @selvajs/cli <dir>')
+			pc.dim('`npx selva <command> --help` explains one command.'),
+			'',
+			pc.bold('Two commands, two jobs:'),
+			'  ' + pc.cyan('npx @selvajs/cli <dir>') + '   scaffold a NEW deployment into <dir>',
+			'  ' + pc.cyan('npx selva <command>') + '      operate the deployment you are standing in',
+			'',
+			pc.dim('`npx selva` works in a deployment directory because @selvajs/cli is one of'),
+			pc.dim('its dependencies. The package.json scripts (`npm run doctor`, `npm start`)'),
+			pc.dim('are thin aliases for the same commands.')
 		].join('\n')
 	);
 }

package/src/commands/create.js

@@ -15,7 +15,11 @@ import {
 	runtimeTemplatePath,
 	scaffoldVersion
 } from '../paths.js';
-import { buildDeploymentPackageJson } from '../deployment-package.js';
+import {
+	buildDeploymentPackageJson,
+	npmDistTagVersion,
+	resolveSelvaPins
+} from '../deployment-package.js';
 import { satisfiesNodeRange } from '../node-range.js';
 
 export async function runCreate(argv) {
@@ -57,9 +61,19 @@ export async function runCreate(argv) {
 
 	const deployName = basename(targetDir);
 
+	// Resolve the dist-tags to concrete versions before writing. A stored
+	// `"latest"` re-resolves on every later `npm install`, so the deployment
+	// would follow the tag instead of the version it was scaffolded against —
+	// and `selva doctor` reports a floating pin as drift.
+	const { pins } = resolveSelvaPins({}, npmDistTagVersion);
+
 	// package.json first: npm install needs it, and the runtime templates below
 	// only exist once @selvajs/selva is installed into node_modules.
-	const pkgJson = JSON.stringify(buildDeploymentPackageJson({ name: deployName }), null, 2);
+	const pkgJson = JSON.stringify(
+		buildDeploymentPackageJson({ name: deployName, dependencies: pins }),
+		null,
+		2
+	);
 	writeFileSync(join(targetDir, 'package.json'), pkgJson + '\n', 'utf8');
 
 	if (!skipInstall) {
@@ -201,11 +215,37 @@ function runNpmInstall(cwd) {
 	});
 }
 
+// `npx @selvajs/cli` resolves to the `cli` bin — the scaffolder — while every
+// operate command lives on the sibling `selva` bin. So `npx @selvajs/cli doctor
+// --fix` lands here, where "doctor" is just a directory name and `--fix` an
+// unknown flag. Name the bin split rather than letting the operator conclude
+// their CLI is too old for a flag it has shipped for releases.
+const OPERATE_COMMANDS = new Set([
+	'doctor',
+	'start',
+	'stop',
+	'restart',
+	'logs',
+	'update',
+	'migrate',
+	'keys',
+	'init'
+]);
+
 function parseArgs(argv) {
 	let dir;
 	let force = false;
 	let skipInstall = false;
 	let yes = false;
+
+	if (OPERATE_COMMANDS.has(argv[0])) {
+		throw new Error(
+			`\`${argv[0]}\` is an operate command, but \`npx @selvajs/cli\` runs the scaffolder.\n` +
+				`  Run it through the deployment's own CLI instead:\n` +
+				`    npx selva ${argv.join(' ')}`
+		);
+	}
+
 	for (const arg of argv) {
 		if (arg === '--force') force = true;
 		else if (arg === '--skip-install') skipInstall = true;

package/src/commands/doctor.js

@@ -8,6 +8,8 @@
 import {
 	existsSync,
 	readFileSync,
+	writeFileSync,
+	copyFileSync,
 	readdirSync,
 	accessSync,
 	constants,
@@ -18,7 +20,7 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { readEnvFile } from '../env.js';
+import { readEnvFile, parseEnv, countEnvCommentLines, stripEnvComments } from '../env.js';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 import { satisfiesNodeRange } from '../node-range.js';
 import { green, yellow, red, fixable } from '../checks/result.js';
@@ -26,13 +28,15 @@ import { checkBootPersistence } from '../checks/boot.js';
 import { checkRuntimeEnvironment } from '../checks/runtime.js';
 import {
 	checkDeprecatedEnv,
+	checkEnvDocumentation,
+	checkHeaderNames,
 	checkOrigin,
 	checkProviders,
 	checkSecret,
 	checkTenancy,
 	resolveProviders
 } from '../checks/config.js';
-import { detectDrift, NODE_MODULES_STASH } from './migrate.js';
+import { BACKUP_AGE_DAYS, classifyBackups, detectDrift, NODE_MODULES_STASH } from './migrate.js';
 
 export async function runDoctor(argv = []) {
 	const fix = argv.includes('--fix');
@@ -48,6 +52,7 @@ export async function runDoctor(argv = []) {
 	checks.push(checkFile(join(dir, 'ecosystem.config.cjs'), 'ecosystem.config.cjs present'));
 	checks.push(checkLayoutDrift(dir));
 	checks.push(checkMigrationLeftovers(dir));
+	checks.push(checkAgedBackups(dir));
 	checks.push(checkSecret(env.SELVA_HMAC_KEY, 'SELVA_HMAC_KEY is a 32-byte hex string'));
 	checks.push(checkSecret(env.SELVA_AT_REST_KEY, 'SELVA_AT_REST_KEY is a 32-byte hex string'));
 
@@ -78,6 +83,7 @@ export async function runDoctor(argv = []) {
 	checks.push(...checkBootPersistence(dir));
 	checks.push(checkOrigin(env));
 	checks.push(...checkDeprecatedEnv(env));
+	checks.push(checkEnvDocs(dir));
 
 	// ── Render ─────────────────────────────────────────────────────────
 	const resolved = await Promise.all(checks);
@@ -94,7 +100,7 @@ export async function runDoctor(argv = []) {
 		if (repairable > 0) {
 			p.log.info(
 				`${repairable} issue${repairable === 1 ? '' : 's'} can be repaired automatically — ` +
-					`re-run with \`selva doctor --fix\`.`
+					`re-run with \`npx selva doctor --fix\`.`
 			);
 		}
 	}
@@ -372,6 +378,94 @@ function checkMigrationLeftovers(dir) {
 	);
 }
 
+// Migration backups are timestamped so a later migration can't overwrite an
+// earlier one's (#184), which means they accumulate. Deleting them silently
+// would throw away the operator's only copy of a pre-migration config, so this
+// reports and lets `--fix` opt in. `classifyBackups` always keeps the newest
+// run, so the escape hatch is never emptied — only superseded generations go.
+function checkAgedBackups(dir) {
+	let names;
+	try {
+		names = readdirSync(dir);
+	} catch {
+		return green('no aged migration backups');
+	}
+
+	const { aged } = classifyBackups(names);
+	if (aged.length === 0) return green('no aged migration backups');
+
+	const shown = aged.slice(0, 3).join(', ');
+	const more = aged.length > 3 ? `, +${aged.length - 3} more` : '';
+	return yellow(
+		`${aged.length} migration backup${aged.length === 1 ? '' : 's'} older than ` +
+			`${BACKUP_AGE_DAYS} days (${shown}${more}). The newest set is kept either way.`,
+		fixable(`delete ${aged.length} aged migration backup${aged.length === 1 ? '' : 's'}`, () => {
+			const failed = [];
+			for (const name of aged) {
+				try {
+					rmSync(join(dir, name), { force: true });
+				} catch (err) {
+					failed.push(`${name} (${err instanceof Error ? err.message : err})`);
+				}
+			}
+			if (failed.length > 0) return red(`could not remove: ${failed.join(', ')}`);
+			return green(`removed ${aged.length} aged backup${aged.length === 1 ? '' : 's'}`);
+		})
+	);
+}
+
+// Reads the raw file rather than the parsed env: the finding IS the comments,
+// which parseEnv discards. The repair is attached here (not in checks/config.js)
+// to keep that module filesystem-free.
+function checkEnvDocs(dir) {
+	const envPath = join(dir, '.env');
+	if (!existsSync(envPath)) return green('.env documentation check skipped (no .env)');
+
+	let text;
+	try {
+		text = readFileSync(envPath, 'utf8');
+	} catch (err) {
+		return yellow(`.env unreadable (${err instanceof Error ? err.message : err})`);
+	}
+
+	return checkEnvDocumentation(
+		countEnvCommentLines(text),
+		fixable('strip the shipped documentation from .env (backup: .env.bak)', () => {
+			try {
+				// Re-read at repair time: doctor may have run minutes ago in --fix's
+				// confirmation loop, and rewriting from a stale snapshot would silently
+				// revert an edit made in between.
+				const current = readFileSync(envPath, 'utf8');
+				const { text: strippedText, removed } = stripEnvComments(current);
+				// A rewrite that changes which settings are live is a bug, not a
+				// cleanup — refuse rather than hand back a subtly different deployment.
+				const before = parseEnv(current);
+				const after = parseEnv(strippedText);
+				const drift = diffEnvKeys(before, after);
+				if (drift) return red(`refused to strip .env — ${drift}`);
+
+				copyFileSync(envPath, envPath + '.bak');
+				writeFileSync(envPath, strippedText, 'utf8');
+				return green(`stripped ${removed} comment lines from .env (backup: .env.bak)`);
+			} catch (err) {
+				return red(`could not rewrite .env: ${err instanceof Error ? err.message : err}`);
+			}
+		})
+	);
+}
+
+// Names the first discrepancy between two parsed envs, or null when identical.
+function diffEnvKeys(before, after) {
+	for (const key of Object.keys(before)) {
+		if (!(key in after)) return `${key} would be lost`;
+		if (before[key] !== after[key]) return `${key} would change value`;
+	}
+	for (const key of Object.keys(after)) {
+		if (!(key in before)) return `${key} would be added`;
+	}
+	return null;
+}
+
 function checkLayoutDrift(dir) {
 	const pkgPath = join(dir, 'package.json');
 	if (!existsSync(pkgPath)) return yellow('package.json missing — cannot check layout');
@@ -389,14 +483,6 @@ function checkLayoutDrift(dir) {
 	);
 }
 
-// Duplicated from HeaderAuthProvider.DEFAULT_HEADERS to avoid loading the runtime here.
-// A test in providers/header-auth pins both sides, so drift surfaces in CI.
-const DEFAULT_HEADER_NAMES = {
-	upn: 'SELVA-UserPrincipalName',
-	email: 'SELVA-Email',
-	displayName: 'SELVA-DisplayName'
-};
-
 // Static config only — runtime invariants like spoofing protection can't be checked from here.
 function checkHeaderAuth(dir, env, dataProvider) {
 	const out = [];
@@ -466,29 +552,7 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		out.push(green(`BOOTSTRAP_INSTANCE_ADMIN_EMAIL=${env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL}`));
 	}
 
-	const resolved = {
-		upn: env.HEADER_AUTH_UPN_HEADER || DEFAULT_HEADER_NAMES.upn,
-		email: env.HEADER_AUTH_EMAIL_HEADER || DEFAULT_HEADER_NAMES.email,
-		displayName: env.HEADER_AUTH_DISPLAY_NAME_HEADER || DEFAULT_HEADER_NAMES.displayName
-	};
-	const overrides = [
-		Boolean(env.HEADER_AUTH_UPN_HEADER),
-		Boolean(env.HEADER_AUTH_EMAIL_HEADER),
-		Boolean(env.HEADER_AUTH_DISPLAY_NAME_HEADER)
-	].filter(Boolean).length;
-	const headerList = `UPN=${resolved.upn}, Email=${resolved.email}, DisplayName=${resolved.displayName}`;
-	if (overrides === 0) {
-		out.push(green(`header names (bundled defaults): ${headerList}`));
-	} else if (overrides === 3) {
-		out.push(green(`header names (all overridden): ${headerList}`));
-	} else {
-		out.push(
-			yellow(
-				`header names partially overridden (${overrides}/3 set): ${headerList} — ` +
-					`a partial override is usually a typo. Set all three or none.`
-			)
-		);
-	}
+	out.push(checkHeaderNames(env));
 
 	return out;
 }

package/src/commands/init.js

@@ -42,7 +42,11 @@ export async function runInit() {
 		p.log.warn('SELVA_AT_REST_KEY was missing — generated a fresh one.');
 	}
 
-	writeEnvFile(envPath, readEnvTemplate(dir), values);
+	// A values-only rewrite drops anything it isn't handed, and the prompts cover
+	// only the vars they ask about — every tuned knob the operator set by hand
+	// (BODY_SIZE_LIMIT, COMPUTE_*, LOG_LEVEL, …) lives outside that set. Carry
+	// the existing file forward and let the prompt answers win on top.
+	writeEnvFile(envPath, readEnvTemplate(dir), { ...current, ...values });
 
 	p.outro(
 		[

package/src/commands/migrate.js

@@ -13,8 +13,12 @@ import {
 	buildDeploymentPackageJson,
 	CANONICAL_FIELDS,
 	DEPENDENCIES,
+	isFloatingPin,
 	LEGACY_DEPENDENCIES,
-	OVERRIDES
+	npmDistTagVersion,
+	OVERRIDES,
+	resolveSelvaPins,
+	SELVA_PACKAGES
 } from '../deployment-package.js';
 import { APP_NAME, runPm2 } from './pm2.js';
 
@@ -23,6 +27,74 @@ import { APP_NAME, runPm2 } from './pm2.js';
 // flags a surviving stash as an interrupted migration.
 export const NODE_MODULES_STASH = 'node_modules.selva-migrate-bak';
 
+// Matches the backups migrate writes: `.env.2026-08-10T05-43-12.bak`. Anchored
+// at both ends so an operator's own `notes.bak` is never picked up as ours.
+export const BACKUP_PATTERN = /\.(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2})\.bak$/;
+
+/**
+ * Colons are illegal in Windows filenames, so this is ISO with `:` swapped for
+ * `-` and the fractional seconds dropped: 2026-08-10T05-43-12.
+ */
+export function backupStamp(now = new Date()) {
+	return now
+		.toISOString()
+		.replace(/\.\d+Z$/, '')
+		.replace(/:/g, '-');
+}
+
+/**
+ * A migration used to write `package.json.bak` at a fixed path, so the second
+ * substantive migration overwrote the first's copy — and since each run backs
+ * up the *current* file, that left the operator's original config recoverable
+ * from nowhere (#184). One stamp per run keeps a whole migration's backups
+ * together and makes them sortable.
+ *
+ * Not auto-pruned here: deleting an operator's only copy of their old config is
+ * worse than a few small files accumulating. `selva doctor` reports aged ones
+ * with a `--fix`, which keeps the decision theirs.
+ */
+export function backupPathFor(filePath, stamp) {
+	return `${filePath}.${stamp}.bak`;
+}
+
+// Old enough that the migration which wrote it is long settled.
+export const BACKUP_AGE_DAYS = 30;
+
+/**
+ * Split migration backups into what to keep and what `doctor --fix` may delete.
+ *
+ * The newest run's backups are always kept, however old they are — on a
+ * deployment that migrates once a year, age alone would delete the only copy of
+ * the pre-migration config, which is the whole point of keeping them. So the
+ * rule is: keep the newest stamp, offer to delete stamps older than
+ * `BACKUP_AGE_DAYS`.
+ *
+ * `names` are basenames; the stamp is read from the filename rather than mtime,
+ * which a copy or restore would reset.
+ */
+export function classifyBackups(names, now = new Date(), maxAgeDays = BACKUP_AGE_DAYS) {
+	const found = [];
+	for (const name of names) {
+		const m = BACKUP_PATTERN.exec(name);
+		if (m) found.push({ name, stamp: m[1] });
+	}
+	if (found.length === 0) return { keep: [], aged: [], newest: null };
+
+	// Stamps are fixed-width and zero-padded, so lexical order is chronological.
+	const newest = found.reduce((a, b) => (b.stamp > a.stamp ? b : a)).stamp;
+	const cutoff = now.getTime() - maxAgeDays * 24 * 60 * 60 * 1000;
+
+	const keep = [];
+	const aged = [];
+	for (const entry of found) {
+		// `2026-08-10T05-43-12` → parseable by restoring the colons.
+		const at = Date.parse(entry.stamp.replace(/T(\d{2})-(\d{2})-(\d{2})$/, 'T$1:$2:$3') + 'Z');
+		if (entry.stamp === newest || !Number.isFinite(at) || at >= cutoff) keep.push(entry.name);
+		else aged.push(entry.name);
+	}
+	return { keep, aged, newest };
+}
+
 // `deps` are seams for tests: the rollback path destroys and restores a real
 // dependency tree, so it has to run against a real directory — but not against
 // a real npm or pm2 daemon.
@@ -34,7 +106,8 @@ export async function runMigrate(
 		// predates the release being migrated to.
 		install = (cwd) => execSync('npm install --prefer-online', { cwd, stdio: 'pipe' }),
 		confirm = (message) => p.confirm({ message, initialValue: true }),
-		pm2 = runPm2
+		pm2 = runPm2,
+		resolveVersion = npmDistTagVersion
 	} = {}
 ) {
 	const dir = injectedDir ?? resolveDeploymentDir();
@@ -49,7 +122,7 @@ export async function runMigrate(
 	}
 
 	const before = JSON.parse(readFileSync(pkgPath, 'utf8'));
-	const target = buildTargetPackageJson(before);
+	const { pkg: target, notes: pinNotes } = buildTargetPackageJson(before, resolveVersion);
 	const pkgDiff = diffPackageJson(before, target);
 
 	const configPath = join(dir, 'selva.config.js');
@@ -94,6 +167,23 @@ export async function runMigrate(
 	for (const line of pkgDiff) console.log('  ' + line);
 	for (const line of sideFileChanges) console.log('  ' + line);
 
+	// The diff shows the pin that will be written; these explain why it is that
+	// pin. A preserved beta and a pin that couldn't be resolved both look like
+	// "no change" in the diff, and the second one is a stale pin, not a stable one.
+	for (const note of pinNotes) {
+		if (note.kind === 'prerelease') {
+			p.log.info(
+				`${note.name} stays on ${note.pin} — a prerelease pin is kept, since \`latest\` ` +
+					`means newest stable and would move this deployment backwards.`
+			);
+		} else {
+			p.log.warn(
+				`Could not resolve the current version of ${note.name} (${note.reason}). ` +
+					`Keeping ${JSON.stringify(note.pin ?? null)}; re-run migrate when the registry is reachable.`
+			);
+		}
+	}
+
 	const confirmed = await confirm('Apply these changes, reinstall, and restart?');
 	if (p.isCancel(confirmed) || !confirmed) {
 		p.cancel('Cancelled.');
@@ -113,17 +203,24 @@ export async function runMigrate(
 		p.log.warn('No deployment-local pm2 to stop — continuing.');
 	}
 
-	const bakPath = pkgPath + '.bak';
+	// One stamp for the whole run, so a migration's backups sort together and a
+	// later migration cannot overwrite this one's (#184).
+	const stamp = backupStamp();
+	const bakPath = backupPathFor(pkgPath, stamp);
+	const configBak = backupPathFor(configPath, stamp);
+	const ecoBak = backupPathFor(ecoPath, stamp);
+	const envBak = backupPathFor(envPath, stamp);
+
 	copyFileSync(pkgPath, bakPath);
 	writeFileSync(pkgPath, JSON.stringify(target, null, 2) + '\n', 'utf8');
 
 	if (hasStaleConfig) {
-		copyFileSync(configPath, configPath + '.bak');
+		copyFileSync(configPath, configBak);
 		rmSync(configPath, { force: true });
 	}
 
 	if (ecoHasStaleRuntime) {
-		copyFileSync(ecoPath, ecoPath + '.bak');
+		copyFileSync(ecoPath, ecoBak);
 		// Text substitution, not regeneration, so any operator customizations to the file survive.
 		const ecoContent = readFileSync(ecoPath, 'utf8').replace(
 			/@selvajs\/runtime/g,
@@ -133,7 +230,7 @@ export async function runMigrate(
 	}
 
 	if (envRename.changes.length > 0) {
-		copyFileSync(envPath, envPath + '.bak');
+		copyFileSync(envPath, envBak);
 		writeFileSync(envPath, envRename.text, 'utf8');
 	}
 
@@ -160,14 +257,14 @@ export async function runMigrate(
 	} catch (err) {
 		s.stop(pc.red('npm install failed — rolling back'));
 		copyFileSync(bakPath, pkgPath);
-		if (hasStaleConfig && existsSync(configPath + '.bak')) {
-			copyFileSync(configPath + '.bak', configPath);
+		if (hasStaleConfig && existsSync(configBak)) {
+			copyFileSync(configBak, configPath);
 		}
-		if (ecoHasStaleRuntime && existsSync(ecoPath + '.bak')) {
-			copyFileSync(ecoPath + '.bak', ecoPath);
+		if (ecoHasStaleRuntime && existsSync(ecoBak)) {
+			copyFileSync(ecoBak, ecoPath);
 		}
-		if (envRename.changes.length > 0 && existsSync(envPath + '.bak')) {
-			copyFileSync(envPath + '.bak', envPath);
+		if (envRename.changes.length > 0 && existsSync(envBak)) {
+			copyFileSync(envBak, envPath);
 		}
 
 		// A half-installed node_modules from the failed attempt is worse than the old
@@ -202,10 +299,10 @@ export async function runMigrate(
 	const pm2Notice = buildPm2UpgradeNotice(before.dependencies?.pm2, target.dependencies.pm2);
 	if (pm2Notice) p.log.warn(pm2Notice);
 
-	const backupHints = ['package.json.bak'];
-	if (hasStaleConfig) backupHints.push('selva.config.js.bak');
-	if (ecoHasStaleRuntime) backupHints.push('ecosystem.config.cjs.bak');
-	if (envRename.changes.length > 0) backupHints.push('.env.bak');
+	const backupHints = [`package.json.${stamp}.bak`];
+	if (hasStaleConfig) backupHints.push(`selva.config.js.${stamp}.bak`);
+	if (ecoHasStaleRuntime) backupHints.push(`ecosystem.config.cjs.${stamp}.bak`);
+	if (envRename.changes.length > 0) backupHints.push(`.env.${stamp}.bak`);
 
 	if (status === 0) {
 		p.outro(
@@ -242,12 +339,15 @@ function restartAfterRollback(dir, pm2 = runPm2) {
 	}
 }
 
-function buildTargetPackageJson(current) {
-	return buildDeploymentPackageJson({
+function buildTargetPackageJson(current, resolveVersion = npmDistTagVersion) {
+	const { pins, notes } = resolveSelvaPins(current.dependencies, resolveVersion);
+	const pkg = buildDeploymentPackageJson({
 		name: current.name ?? 'selva-deployment',
 		version: current.version ?? '0.1.0',
-		engines: current.engines
+		engines: current.engines,
+		dependencies: pins
 	});
+	return { pkg, notes };
 }
 
 // Format package.json diff for confirmation prompt (concise, not full diff).
@@ -331,6 +431,20 @@ export function detectDrift(pkgJson, dir) {
 		reasons.push(`pm2 is pinned to ${deps.pm2} (current scaffold pins ${DEPENDENCIES.pm2})`);
 	}
 
+	// A stored dist-tag re-resolves on every `npm install`, so the deployment
+	// follows the tag instead of a version an operator chose. Worse on a
+	// prerelease line, where `latest` points at the older stable release and the
+	// "upgrade" is a downgrade. Migrate wrote these before it learned to resolve
+	// tags, so existing deployments carry one and nothing else reports it.
+	for (const name of SELVA_PACKAGES) {
+		if (deps[name] && isFloatingPin(deps[name])) {
+			reasons.push(
+				`${name} is pinned to the floating tag ${JSON.stringify(deps[name])} ` +
+					`(re-resolves on every install; migrate writes a concrete version)`
+			);
+		}
+	}
+
 	// Overrides are security shims for vulnerable transitive deps — a
 	// deployment without them installs the vulnerable version on its next
 	// `npm install`, silently.
@@ -370,8 +484,14 @@ export function buildPm2UpgradeNotice(beforeVersion, afterVersion) {
 		`still the old version. Finish the upgrade (brief restart of managed processes):`,
 		``,
 		`  npx pm2 update`,
+		`  npx pm2 list          # ${APP_NAME} must be listed and 'online' before the next step`,
 		`  npx pm2 save`,
 		``,
+		`Do not run \`pm2 save\` until the list looks right. \`pm2 update\` empties the`,
+		`process table before restoring it, so saving a failed restore overwrites`,
+		`~/.pm2/dump.pm2 — the only record of what to bring back. If the list is empty,`,
+		`recover with \`npx pm2 resurrect\`, or \`npx pm2 start ecosystem.config.cjs\`.`,
+		``,
 		`If doctor reports a pm2 outside this deployment (global or apt install), follow`,
 		`the full procedure in the docs instead: self-hosting → deployment → prerequisites.`
 	].join('\n');

package/src/deployment-package.js

@@ -4,6 +4,7 @@
 // exactly the field where a silent difference costs the most.
 
 import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -51,6 +52,11 @@ const SCRIPTS = {
  * Packages a deployment carries. Providers are bundled into `@selvajs/selva`;
  * the CLI is a dependency so `npm run start` resolves the `selva` bin locally
  * instead of relying on a global install.
+ *
+ * The `latest` entries are what `create` resolves at scaffold time, never what
+ * gets written: `resolveSelvaPins` turns them into concrete versions. A stored
+ * `"latest"` re-resolves on every `npm install`, so the deployment follows the
+ * dist-tag forever and can change under the operator with no migrate at all.
  */
 const DEPENDENCIES = {
 	'@selvajs/cli': 'latest',
@@ -58,6 +64,34 @@ const DEPENDENCIES = {
 	pm2: PM2_VERSION
 };
 
+/** The `@selvajs/*` packages whose pin belongs to the operator, not the scaffold. */
+export const SELVA_PACKAGES = ['@selvajs/cli', '@selvajs/selva'];
+
+/**
+ * True for a pin that names no version — a dist-tag (`latest`, `beta`) or the
+ * empty-ish values npm also accepts (`*`, `""`). These are the pins that move
+ * on their own, which is what makes them unfit to store.
+ */
+export function isFloatingPin(pin) {
+	if (typeof pin !== 'string') return true;
+	const trimmed = pin.trim();
+	if (trimmed === '' || trimmed === '*' || trimmed === 'x') return true;
+	// A range still names versions; only a bare tag has no digits at all.
+	return !/\d/.test(trimmed);
+}
+
+/**
+ * True for a pin on a prerelease line (`^4.8.0-beta.11`).
+ *
+ * These are preserved across a migration. An operator on a beta channel chose
+ * it, and npm's `latest` tag points at the newest *stable* release — so
+ * resolving their pin through `latest` is a downgrade that reads as an upgrade
+ * in the confirmation diff.
+ */
+export function isPrereleasePin(pin) {
+	return typeof pin === 'string' && /\d+\.\d+\.\d+-/.test(pin);
+}
+
 /**
  * npm `overrides` forced onto every deployment — security patches for
  * transitive deps whose direct parent hasn't picked up the fix yet. Each entry
@@ -100,21 +134,98 @@ export const LEGACY_DEPENDENCIES = {
  * deliberately, and dropping it removes a guard whose absence shows up only
  * under real traffic (issue #176). Everything else a migration discards is
  * listed by `diffPackageJson` before the operator confirms.
+ *
+ * `dependencies` is the second exception, for the same reason: a version pin is
+ * an operator choice too. `migrate` passes the resolved `@selvajs/*` pins in
+ * here; a fresh scaffold passes none and inherits the defaults.
  */
-export function buildDeploymentPackageJson({ name, version = '0.1.0', engines }) {
+export function buildDeploymentPackageJson({ name, version = '0.1.0', engines, dependencies }) {
 	const pkg = {
 		name: sanitizePackageName(name),
 		version,
 		private: true,
 		type: 'module',
 		scripts: { ...SCRIPTS },
-		dependencies: { ...DEPENDENCIES },
+		dependencies: { ...DEPENDENCIES, ...dependencies },
 		overrides: { ...OVERRIDES }
 	};
 	if (engines && typeof engines === 'object') pkg.engines = { ...engines };
 	return pkg;
 }
 
+/**
+ * Ask npm what a dist-tag currently points at. Kept beside the pin logic it
+ * serves, and injected rather than called directly so tests never hit the
+ * network.
+ */
+export function npmDistTagVersion(name, tag) {
+	const out = execSync(`npm view ${name}@${tag} version`, {
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe']
+	});
+	const version = String(out).trim().split('\n').pop()?.trim();
+	if (!version || !/^\d+\.\d+\.\d+/.test(version)) {
+		throw new Error(`npm view returned no usable version for ${name}@${tag}`);
+	}
+	return version;
+}
+
+/**
+ * Decide the `@selvajs/*` pins a migration should write.
+ *
+ * Two rules, both aimed at the same failure: a migration silently moving a
+ * deployment to a version the operator didn't ask for.
+ *
+ *   - A prerelease pin is kept as-is. `latest` means newest stable, so
+ *     resolving a beta pin through it walks the deployment backwards.
+ *   - Anything else resolves to a concrete version via `resolveVersion`, so
+ *     `"latest"` never reaches disk and the diff can show what it resolved to.
+ *
+ * `resolveVersion` hits the network. When it fails — offline, registry down, a
+ * package with no such tag — the existing pin is kept and the reason returned,
+ * so migrate can report it rather than inventing a version or aborting a
+ * migration whose other half (layout, overrides, env renames) is still valid.
+ */
+export function resolveSelvaPins(currentDeps, resolveVersion) {
+	const pins = {};
+	const notes = [];
+
+	for (const name of SELVA_PACKAGES) {
+		const current = currentDeps?.[name];
+
+		if (isPrereleasePin(current)) {
+			pins[name] = current;
+			notes.push({ name, kind: 'prerelease', pin: current });
+			continue;
+		}
+
+		let resolved = null;
+		try {
+			resolved = resolveVersion(name, 'latest');
+		} catch (err) {
+			notes.push({ name, kind: 'unresolved', pin: current, reason: err?.message ?? String(err) });
+		}
+
+		if (resolved) {
+			pins[name] = `^${resolved}`;
+			continue;
+		}
+
+		// Nothing resolvable and nothing worth keeping — fall back to the tag so
+		// the install still succeeds. Rare: offline *and* a floating pin.
+		if (isFloatingPin(current)) {
+			pins[name] = DEPENDENCIES[name];
+			if (!notes.some((n) => n.name === name)) {
+				notes.push({ name, kind: 'unresolved', pin: current, reason: 'no version returned' });
+			}
+		} else {
+			pins[name] = current;
+		}
+	}
+
+	return { pins, notes };
+}
+
 /**
  * Top-level keys the canonical package.json defines. Anything outside this set
  * that an operator added is dropped by `migrate` — `diffPackageJson` reports

package/src/env.js

@@ -19,6 +19,142 @@ export const REPLACED_ENV_VARS = {
 	SELVA_FLAG_COMPUTE_DEBUG_VERBOSE: 'SELVA_FLAG_COMPUTE_DEBUG=verbose'
 };
 
+// Header written above the settings in a stripped .env. The pointer matters:
+// without it the operator has no way back to what a var means, and the reflex
+// is to paste the old annotated template back in.
+export const ENV_HEADER = [
+	'# Selva deployment configuration.',
+	'#',
+	'# Values only — every variable is documented in the runtime template at',
+	'# node_modules/@selvajs/selva/templates/.env.example, which is refreshed on',
+	'# every update. Do not paste that template in here: a copy stops tracking',
+	'# the release and starts describing variables the code no longer reads.'
+].join('\n');
+
+/**
+ * Strip a deployment `.env` down to its live settings, dropping the shipped
+ * documentation block.
+ *
+ * A comment block copied onto a server is a snapshot with no update path —
+ * `migrate` rewrites keys but never prose, so a deployment keeps documenting
+ * the release it was installed at, describing vars the code has since renamed
+ * or retired. Deleting it is what makes the file navigable AND unable to lie.
+ *
+ * Operator comments are NOT prose to be discarded: a short `#` run directly
+ * above a setting (no blank line between) is that setting's note and rides
+ * along with it. Everything else goes.
+ *
+ * "Short" is doing real work here. The shipped template also writes prose
+ * immediately above a setting — its banner blocks run 40+ lines and end with a
+ * bare `#` — so proximity alone would keep the very documentation this exists
+ * to remove. A hand-written note is a line or two; a block longer than
+ * ATTACHED_NOTE_MAX_LINES, or one containing a `# ====` banner rule, is the
+ * template's and is dropped.
+ *
+ * Returns `{ text, removed }`, `removed` being the count of dropped comment
+ * lines. `removed === 0` means the file was already values-only.
+ */
+export function stripEnvComments(text, { header = ENV_HEADER } = {}) {
+	// Our own header is re-emitted below, so counting it as prose we removed
+	// would make every run report work it didn't do — and break idempotency,
+	// which is what lets doctor call a stripped file clean. Matched as a whole
+	// leading block, not line-by-line: the header contains a bare `#`, and
+	// excluding that by value would silently stop counting an operator's own
+	// `#` separators anywhere in the file.
+	let lines = text.split(/\r?\n/);
+	if (header) {
+		const headerLines = header.split('\n');
+		const leads = headerLines.every((h, i) => lines[i]?.trim() === h.trim());
+		if (leads) lines = lines.slice(headerLines.length);
+	}
+	const out = [];
+	let pending = [];
+	let removed = 0;
+	let sawSetting = false;
+	// Whether a blank line or dropped prose separated the last setting from the
+	// next one — the original file's own grouping, worth carrying over.
+	let groupBreak = false;
+
+	const flushDropped = () => {
+		const dropped = pending.filter((l) => l.trim().startsWith('#'));
+		removed += dropped.length;
+		// A discarded banner marked a section boundary in the original; keep that
+		// boundary as a blank line so the result still reads as grouped settings.
+		if (dropped.length > 0 && sawSetting) groupBreak = true;
+		pending = [];
+	};
+
+	for (const line of lines) {
+		const stripped = line.trim();
+
+		if (stripped.startsWith('#')) {
+			pending.push(line);
+			continue;
+		}
+
+		// A blank line ends whatever comment block was accumulating: those
+		// comments float free rather than annotating the next setting.
+		if (!stripped) {
+			if (sawSetting) groupBreak = true;
+			flushDropped();
+			continue;
+		}
+
+		if (stripped.indexOf('=') === -1) {
+			flushDropped();
+			continue;
+		}
+
+		// Comments still pending sit directly above this setting. Keep them only
+		// if they read as a hand-written note rather than a template banner.
+		const note = isAttachedNote(pending);
+		// Blank line only where it earns one: before a kept note, or where the
+		// original had a break. Separating every key would just trade a wall of
+		// prose for a file twice as long as it needs to be.
+		if (sawSetting && (note || groupBreak)) out.push('');
+		if (note) {
+			out.push(...pending);
+		} else {
+			flushDropped();
+		}
+		pending = [];
+		groupBreak = false;
+		out.push(line);
+		sawSetting = true;
+	}
+
+	// Trailing comments annotate nothing.
+	flushDropped();
+
+	const body = out.join('\n');
+	return {
+		text: header ? `${header}\n\n${body}\n` : `${body}\n`,
+		removed
+	};
+}
+
+// A hand-written note is a line or two. Longer than this and it is the shipped
+// template's prose, which is what stripping exists to remove.
+const ATTACHED_NOTE_MAX_LINES = 3;
+
+// A `# ====` rule is the template's section-banner style; nothing hand-written
+// above a single setting uses it.
+const BANNER_RULE = /^#\s*[=-]{4,}/;
+
+function isAttachedNote(pending) {
+	if (pending.length === 0 || pending.length > ATTACHED_NOTE_MAX_LINES) return false;
+	return !pending.some((l) => BANNER_RULE.test(l.trim()));
+}
+
+/**
+ * How many lines of the file are shipped documentation rather than config.
+ * Used by `selva doctor` to flag an annotated `.env` without rewriting it.
+ */
+export function countEnvCommentLines(text) {
+	const { removed } = stripEnvComments(text);
+	return removed;
+}
+
 export function parseEnv(text) {
 	const out = {};
 	for (const rawLine of text.split(/\r?\n/)) {
@@ -88,8 +224,55 @@ export function mergeEnv(template, values) {
 	return out.join('\n') + '\n';
 }
 
-export function writeEnvFile(path, template, values) {
-	writeFileSync(path, mergeEnv(template, values), 'utf8');
+/**
+ * Render a values-only `.env` — the scaffold's default shape.
+ *
+ * The annotated template is genuinely useful while you are deciding what to
+ * set, which is why the runtime still ships it; it stops being useful the
+ * moment it is written to a server and cannot be corrected there. So the
+ * template stays a reference and the deployment gets values, in the template's
+ * own key order (it groups related settings) with anything unknown appended.
+ */
+export function renderEnvValues(template, values, { header = ENV_HEADER } = {}) {
+	const ordered = [];
+	const seen = new Set();
+
+	// The template names a var three ways — live (`KEY=v`), commented-out
+	// (`# KEY=v`), and as a bare mention in prose (`# KEY   single | multi`).
+	// All three signal where the var belongs, so the first token of any line is
+	// enough; anything that isn't a known key is filtered out below.
+	for (const rawLine of template.split(/\r?\n/)) {
+		const stripped = rawLine.trim().replace(/^#\s*/, '');
+		const key = stripped.split(/[\s=]/)[0]?.trim();
+		if (!key || !/^[A-Z][A-Z0-9_]{2,}$/.test(key)) continue;
+		if (seen.has(key)) continue;
+		if (!Object.prototype.hasOwnProperty.call(values, key)) continue;
+		seen.add(key);
+		ordered.push(key);
+	}
+
+	for (const key of Object.keys(values)) {
+		if (!seen.has(key)) ordered.push(key);
+	}
+
+	const lines = [];
+	for (const key of ordered) {
+		const value = values[key];
+		if (value === undefined || value === null || value === '') continue;
+		lines.push(`${key}=${quoteIfNeeded(value)}`);
+	}
+
+	return header ? `${header}\n\n${lines.join('\n')}\n` : `${lines.join('\n')}\n`;
+}
+
+/**
+ * Writes the deployment `.env`. Values-only by default — pass
+ * `{ annotated: true }` to merge into the template's comments instead, which
+ * only an operator who explicitly wants the old shape should do.
+ */
+export function writeEnvFile(path, template, values, { annotated = false } = {}) {
+	const text = annotated ? mergeEnv(template, values) : renderEnvValues(template, values);
+	writeFileSync(path, text, 'utf8');
 }
 
 /**