@rebasepro/cli 0.13.0 → 0.13.1-canary.g1822133

package/dist/index.es.js

@@ -12,9 +12,10 @@ import crypto from "crypto";
 import { execSync, spawn, spawnSync } from "child_process";
 import os from "os";
 import { createRebaseClient } from "@rebasepro/client";
+import dotenv from "dotenv";
+import { BUNDLE_FORMAT_VERSION, DEFAULT_DATA_SOURCE_KEY, RUNTIME_CONTRACT_VERSION, computeSchemaVersion, deserializeCollections, findStorageSuffixCollision, getDataSourceCapabilities, normalizeStorageSources, storageEnvSuffix } from "@rebasepro/types";
+import { CodegenError, generateSDK, toSafeIdentifier } from "@rebasepro/codegen";
 import { createRequire } from "module";
-import { BUNDLE_FORMAT_VERSION, RUNTIME_CONTRACT_VERSION, computeSchemaVersion, deserializeCollections, findStorageSuffixCollision, normalizeStorageSources, storageEnvSuffix } from "@rebasepro/types";
-import { generateSDK } from "@rebasepro/codegen";
 //#region src/utils/package-manager.ts
 /**
 * Package manager detection and command abstraction.
@@ -190,6 +191,90 @@ function getPMCommands(pm) {
 	};
 }
 //#endregion
+//#region src/utils/args.ts
+/**
+* Argument parsing for the commands that take positional arguments.
+*
+* Every command in the small group used to parse its own line the same way:
+* `arg(spec, { argv: rawArgs.slice(4), permissive: true })`, then read `_[0]`
+* and `_[1]`. Both halves of that are wrong in a way that costs data.
+*
+*  - **`permissive: true` turns an unknown flag into a positional.** `arg`
+*    pushes an undeclared flag into `_` as a bare token, so `_[1]` is whatever
+*    came second on the line, flag or not. `rebase auth reset-password
+*    bob@example.com --debug` set Bob's password to the literal `--debug` — and
+*    `--debug` is what `bin/rebase.js` prints after *every* failure as the thing
+*    to re-run with, so the single most likely next keystroke after a failed
+*    reset was the one that reset the account to a two-word string.
+*  - **`slice(4)` assumes the command words are at fixed indices.** They are
+*    not: a flag before the command shifts everything, so `rebase --debug auth
+*    reset-password bob@example.com NewPass1!` read the email as
+*    `reset-password` and the password as `bob@example.com`.
+*
+* So: parse the *whole* line — `rawArgs` is `process.argv` — against a spec
+* strictly, with no permissive mode. `arg` then consumes every flag wherever it
+* appears and rejects the ones nobody declared, which leaves `_` holding the
+* command words followed by the real positionals, in order and at a known
+* offset. An unrecognised flag becomes an error naming the command's help,
+* which is the only safe answer: the alternative is guessing that it was meant
+* as a value.
+*
+* `commands/cloud/index.ts` resolves its positionals against its own spec for
+* the same reason; this is that idea for the commands whose positionals are
+* credentials rather than resource names.
+*/
+/**
+* Flags accepted on top of whatever a command declares.
+*
+* `--debug` is read by `bin/rebase.js` off `process.argv` and never by a
+* command, but it has to be *declared* somewhere or strict parsing rejects the
+* exact flag the CLI tells people to add. `--help`/`-h` are answered by each
+* command's dispatcher before any work happens.
+*/
+var GLOBAL_COMMAND_FLAGS = {
+	"--debug": Boolean,
+	"--help": Boolean,
+	"-h": "--help"
+};
+/** Did the line ask for help? Answered before dispatch, never by a handler. */
+function wantsHelp(rawArgs) {
+	return rawArgs.includes("--help") || rawArgs.includes("-h");
+}
+/**
+* Resolve a command's flags and positionals from the full `process.argv`.
+*
+* `commandWords` is how many words name the command itself — 2 for
+* `auth reset-password`, 1 for `start` — and is applied to the *parsed*
+* positionals rather than to `argv`, so a flag placed before the command no
+* longer shifts them.
+*
+* `command` names the command in error messages, e.g. `auth reset-password`.
+*
+* Throws on an unknown flag, on a positional that looks like a flag, and on
+* more positionals than the command takes. `bin/rebase.js` turns each into a
+* one-line `✗ …` and exit 1.
+*/
+function parseCommandArgs({ spec, rawArgs, commandWords, command, maxPositionals }) {
+	let parsed;
+	try {
+		parsed = arg({
+			...GLOBAL_COMMAND_FLAGS,
+			...spec
+		}, { argv: rawArgs.slice(2) });
+	} catch (err) {
+		if (err instanceof Error && err.code === "ARG_UNKNOWN_OPTION") throw new Error(`${err.message} — run \`rebase ${command} --help\` for the options it takes.`);
+		throw err;
+	}
+	const positionals = parsed._.slice(commandWords);
+	for (const value of positionals) if (value.startsWith("-")) throw new Error(`\`${value}\` looks like an option, not a value — pass it with an explicit flag (\`rebase ${command} --help\`).`);
+	if (maxPositionals !== void 0 && positionals.length > maxPositionals) throw new Error(`rebase ${command} takes ${maxPositionals} argument${maxPositionals === 1 ? "" : "s"}, got ${positionals.length}: ${positionals.join(" ")}`);
+	return {
+		flags: parsed,
+		positionals,
+		help: Boolean(parsed["--help"])
+	};
+}
+//#endregion
 //#region src/utils/project.ts
 /**
 * Project discovery utilities for the Rebase CLI.
@@ -289,6 +374,34 @@ function findEnvFile(projectRoot) {
 	return null;
 }
 /**
+* Read the project's `.env` into a plain object.
+*
+* One reader, because there were four: `dotenv` in `start`, a hand-rolled
+* `indexOf("=")` loop in `api-keys`, a single-key regex in `auth`, and its own
+* splitting in `cloud env`. `dotenv` is a declared dependency of this package,
+* so the other three existed for no reason and disagreed with the correct one
+* on the two things people actually write in a `.env`:
+*
+*   - `export KEY=value`, which the hand-rolled parser keyed as
+*     `export KEY` — so the command reported the key as unset while it was
+*     right there in the file;
+*   - `KEY=value # comment`, whose comment travelled into the value and then
+*     into an `Authorization` header, coming back as a 401 with nothing
+*     pointing at the cause.
+*
+* Returns `{}` when the project has no `.env`, so callers can treat "absent"
+* and "empty" alike.
+*/
+function readEnvFile(projectRoot) {
+	const envFile = findEnvFile(projectRoot);
+	if (!envFile || !fs.existsSync(envFile)) return {};
+	try {
+		return dotenv.parse(fs.readFileSync(envFile, "utf-8"));
+	} catch {
+		return {};
+	}
+}
+/**
 * Resolve a binary from the project's node_modules/.bin.
 * Checks backend, root, parent monorepo root, then falls back to PATH.
 */
@@ -497,7 +610,7 @@ function normalizeUrl(url) {
 function createCloudClient(url) {
 	return createRebaseClient({
 		baseUrl: url,
-		websocketUrl: "",
+		realtime: false,
 		auth: {
 			storage: createFileAuthStorage(url),
 			persistSession: true,
@@ -516,11 +629,11 @@ async function requireClient(rawArgs) {
 	const url = resolveCloudUrl(rawArgs);
 	const client = createCloudClient(url);
 	const session = client.auth.getSession();
-	if (!session || !session.accessToken) fail(`Not logged in to ${chalk.cyan(url)}.`, `Run ${chalk.bold("rebase cloud login")} first.`);
+	if (!session || !session.accessToken) fail(`Not logged in to ${chalk.cyan(url)}.`, `Run ${chalk.bold("rebase cloud login")} first.`, "not_logged_in");
 	if (session.expiresAt <= Date.now() + EXPIRY_BUFFER_MS) try {
 		await client.auth.refreshSession();
 	} catch {
-		fail(`Your session for ${chalk.cyan(url)} has expired.`, `Run ${chalk.bold("rebase cloud login")} to sign in again.`);
+		fail(`Your session for ${chalk.cyan(url)} has expired.`, `Run ${chalk.bold("rebase cloud login")} to sign in again.`, "session_expired");
 	}
 	return {
 		client,
@@ -672,7 +785,7 @@ function requireProjectRef(rawArgs) {
 	if (parsed["--project"]) return parsed["--project"];
 	const link = readLink();
 	if (link?.projectId) return link.projectId;
-	fail("No project specified and this directory is not linked.", `Pass ${chalk.bold("--project <slug>")} or run ${chalk.bold("rebase cloud link")}.`);
+	fail("No project specified and this directory is not linked.", `Pass ${chalk.bold("--project <slug>")} or run ${chalk.bold("rebase cloud link")}.`, "no_project");
 }
 /**
 * Resolve a project reference — slug or UUID — to the internal id the API
@@ -691,7 +804,7 @@ async function lookupProjectId(ref, client) {
 /** Like `lookupProjectId`, but exits with guidance when the ref matches nothing. */
 async function resolveProjectRef(ref, client) {
 	const id = await lookupProjectId(ref, client);
-	if (id === void 0) fail(`No project with slug ${chalk.bold(ref)}.`, `List yours with ${chalk.bold("rebase cloud projects")}.`);
+	if (id === void 0) fail(`No project with slug ${chalk.bold(ref)}.`, `List yours with ${chalk.bold("rebase cloud projects")}.`, "project_not_found");
 	return id;
 }
 /** `requireProjectRef` + `resolveProjectRef` in one step. */
@@ -760,6 +873,28 @@ function emit(human, json) {
 	else human();
 }
 /**
+* Print a help page — the human one, or a machine-readable description of the
+* same command in JSON mode.
+*
+* `--help` is the one place where "stdout is not a TTY" is a weak signal: a
+* person runs `rebase cloud db --help | less` and wants the page. But the rule
+* this family promises is that stdout carries one JSON value whenever it is not
+* a terminal, and a help page is the easiest possible thing to describe
+* structurally — so rather than carve out an exception, help answers the same
+* question in the reader's own language. For an agent, `--help` piped is then a
+* discovery call rather than 60 lines of ANSI to scrape.
+*
+* `env` shipped this shape first, alone; this generalises it so every group
+* answers the same way.
+*/
+function emitHelp(command, actions, human, extra = {}) {
+	emit(human, {
+		command,
+		actions,
+		...extra
+	});
+}
+/**
 * Print a warning (+ optional hint) — in every output mode, always to stderr.
 *
 * `emit` is for a command's *result*, and JSON mode legitimately replaces the
@@ -788,12 +923,27 @@ function warn(message, hint) {
 	console.error(chalk.yellow(`  ⚠ ${message}`));
 	if (hint) console.error(chalk.gray(`    ${hint}`));
 }
-/** Print an error (+ optional hint) and exit non-zero. Never returns. */
+/**
+* Print an error (+ optional hint) and exit non-zero. Never returns.
+*
+* `code` is the field a caller branches on, and it defaults to `"error"` rather
+* than `null`. An envelope whose only machine-readable field is null is not
+* machine-readable — `{"error":{"message":"No project specified…","code":null}}`
+* forced the very substring-matching on `message` that the envelope exists to
+* make unnecessary, and `message` is the field most likely to be reworded.
+*
+* `"error"` is deliberately a poor code: it says "this refusal has not been
+* classified yet" without ever being absent. Anything a caller might plausibly
+* want to distinguish — `usage`, `not_found`, `unauthenticated` — passes a real
+* one. Codes are part of the CLI's contract once shipped; see
+* `cloud-reporting.test.ts`, which pins the ones commands are documented to
+* return.
+*/
 function fail(message, hint, code) {
 	if (JSON_MODE) {
 		printJson({ error: {
 			message: stripAnsi(message),
-			code: code ?? null,
+			code: code ?? "error",
 			hint: hint ? stripAnsi(hint) : void 0
 		} });
 		process.exit(1);
@@ -822,26 +972,139 @@ async function confirmDestructive(opts) {
 		message: opts.prompt
 	}]);
 	if (!confirmed) {
-		console.log(chalk.gray("  Aborted."));
+		console.error(chalk.gray("  Aborted."));
 		process.exit(0);
 	}
 }
 /**
-* Positional tokens after `rebase cloud` — `[group, action, arg1, …]`.
+* Refuse, rather than prompt, when there is nobody to answer.
+*
+* `confirmDestructive` has always done this for yes/no confirmations. The
+* *value* prompts had no such guard: `cloud login`, `cloud link`, `cloud use`,
+* `cloud orgs create` and `cloud db create` all called `inquirer.prompt`
+* unconditionally, so piping any of them — which is how an agent runs every
+* command in this family — parked the process on a prompt reading from a stdin
+* that was never going to produce a line. A hang is the worst failure mode
+* available here: no output, no exit code, nothing to retry on.
+*
+* @param what   what the prompt would have asked for, e.g. "an email and password"
+* @param flags  the flags that supply it non-interactively
+*/
+function requireInteractive(what, flags) {
+	if (JSON_MODE || process.stdin.isTTY !== true) fail(`This command needs ${what}, and there is no terminal to ask on.`, `Pass ${chalk.bold(flags)}.`, "input_required");
+}
+/**
+* Resolve one cloud command's flags and ARGUMENTS from the full `process.argv`.
+*
+* This replaces `cloudPositionals`, which was `rawArgs.slice(3).filter(a =>
+* !a.startsWith("-"))`. Dropping `-`-prefixed tokens looks like it solves the
+* permissive-parse problem and does not: a flag that takes a VALUE leaves the
+* value behind, an ordinary word in the argument position that no filter can
+* tell from a real one. `--project` is the flag every one of these commands
+* documents, so the failure was reachable from the help page:
+*
+*   rebase cloud env unset -p acme            → removed the variable "acme"
+*   rebase cloud env set KEY -p acme          → stored the value "acme"
+*   rebase cloud domains add -p acme          → registered the domain "acme"
+*   rebase cloud webhooks delete -p acme 42   → deleted webhook "acme", not 42
+*   rebase cloud cancel -p acme               → cancelled deployment id "acme"
+*
+* The filter's other half is quieter. A flag nobody declared *is* dropped by
+* it — but only from the operands, never from the run: nothing rejects it, so
+* the command proceeds with the argument missing or defaulted. `db backup
+* --dry-run` listed backups, `domains remove --dry-run` detached the domain,
+* and `env set KEY=v --secrett` stored the value as an ordinary variable that
+* `env reveal` will hand back. The one place an undeclared flag became the
+* argument outright is `projects info|delete`, which resolved its id through
+* `positionals()` instead — that skips only LEADING `-` tokens, so `projects
+* delete --force` looked up a project named "--force".
+*
+* So: parse the whole line strictly, through the same `parseCommandArgs` the
+* non-cloud commands use — `arg` then consumes each declared flag *with its
+* value* wherever it appears, and rejects the undeclared, leaving `_` holding
+* the command words followed by the real arguments. `commandWords` counts from
+* `cloud` itself (`cloud env set` ⇒ 3), and is applied to the parsed
+* positionals, so a flag written before the group shifts nothing.
+*
+* Two things this adds over calling `parseCommandArgs` directly, and the reason
+* it is worth a wrapper:
+*
+*  - `GLOBAL_CLOUD_FLAGS` is merged in. `--json`, `--yes` and `--project` may
+*    appear anywhere on a cloud line including before the group, so a strict
+*    parse that did not declare them would reject the CLI's own documented
+*    usage. (`parseCommandArgs` adds `--debug`/`--help` on top of that.)
+*  - A parse error is reported through `fail`, not thrown. A throw reaches
+*    `bin/rebase.js`, which prints `✗ …` to stderr — which is right for every
+*    other command and wrong here: `rebase cloud` is in JSON mode whenever
+*    stdout is not a TTY, i.e. always for the agents this family is built for,
+*    and it promises them exactly one JSON value. `fail` keeps that promise,
+*    with the same `usage` code the other refusals in this family use.
+*/
+function parseCloudArgs(opts) {
+	const spec = {
+		...GLOBAL_CLOUD_FLAGS,
+		...opts.spec
+	};
+	try {
+		const parsed = parseCommandArgs({
+			...opts,
+			spec
+		});
+		return {
+			flags: parsed.flags,
+			positionals: parsed.positionals
+		};
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err), void 0, "usage");
+	}
+}
+/**
+* Announce an outcome — "Logged in as …", "Deleted project …".
 *
-* Deliberately NOT `arg({}, { permissive: true })._`: in permissive mode `arg`
-* pushes UNKNOWN FLAGS onto `_` too, so `rollback --yes --json` would report
-* `--yes` as the deployment id. Operand extraction must see operands only, so
-* anything starting with `-` is dropped — the same filter the db backup handler
-* has always used.
+* On **stderr**, in both modes. It reads like a result and is not one: the
+* result is the JSON value (or the table) on stdout, and every JSON payload in
+* this family already carries `success: true`. Leaving this on stdout meant a
+* successful `rebase cloud link | jq` was handed a green tick followed by an
+* object — one stream, two syntaxes, and only the second parseable.
+*
+* It stays visible in JSON mode, unlike `note`: an agent that got a `success`
+* line on a command it expected to refuse has learned something.
 */
-function cloudPositionals(rawArgs) {
-	return rawArgs.slice(3).filter((a) => !a.startsWith("-"));
-}
 function success(message) {
-	console.log("");
-	console.log(chalk.bold.green(`  ✓ ${message}`));
-	console.log("");
+	if (JSON_MODE) {
+		process.stderr.write(`${stripAnsi(message)}\n`);
+		return;
+	}
+	console.error("");
+	console.error(chalk.bold.green(`  ✓ ${message}`));
+	console.error("");
+}
+/**
+* Narrate progress, or point at the next step — "Signing in to …", "Redeploy
+* for the tenant to pick this up".
+*
+* stderr, and **suppressed entirely in JSON mode**. This is the one helper that
+* a mode may silence, and the distinction from `warn` is worth keeping sharp:
+*
+*   - A warning is a *condition*. It is as true when piped as when watched, so
+*     silencing it hides something the caller would want to know. `warn` never
+*     silences.
+*   - A note is *hand-holding*. "Next: run `rebase generate-sdk`" tells a person
+*     what to type; the agent reading the JSON already has the same information
+*     structurally, or does not need it. Printing it anyway is transcript noise.
+*
+* When in doubt it is a warning. The cost of a needless warning is a line; the
+* cost of a swallowed one is the deploy that ejected a project off the managed
+* runtime and said so only to a terminal nobody was looking at.
+*/
+function note(message, indent = "  ") {
+	if (JSON_MODE) return;
+	console.error(`${indent}${message}`);
+}
+/** A blank spacer line on the narration stream. No-op in JSON mode. */
+function noteBlank() {
+	if (JSON_MODE) return;
+	console.error("");
 }
 /** Colorize a deployment / resource status token. */
 function colorStatus(status) {
@@ -879,7 +1142,7 @@ function reportError(e, context) {
 	if (JSON_MODE) {
 		printJson({ error: {
 			message: err?.message ? stripAnsi(err.message) : String(e),
-			code: err?.code ?? null,
+			code: err?.code ?? (err?.status ? `http_${err.status}` : "request_failed"),
 			status: err?.status ?? null,
 			context
 		} });
@@ -888,13 +1151,18 @@ function reportError(e, context) {
 	fail(`${context}${err?.status ? ` (${err.status})` : ""}: ${err?.message ?? String(e)}`);
 }
 /**
-* Open a URL in the user's default browser (best effort). Always prints the URL
-* first so it stays usable over SSH or when no browser is available.
+* Open a URL in the user's default browser (best effort). Always announces the
+* URL first so it stays usable over SSH or when no browser is available.
+*
+* The announcement is narration, not the result — it goes to stderr, and in
+* JSON mode it is silent. Every caller `emit`s the same URL in its payload, so
+* a machine reader gets it from the one place it is guaranteed to be parseable
+* rather than from a line that happens to end in a URL.
 */
 function openUrl(target, label = "Opening") {
-	console.log("");
-	console.log(`  ${label} ${chalk.cyan(target)}`);
-	console.log("");
+	noteBlank();
+	note(`${label} ${chalk.cyan(target)}`);
+	noteBlank();
 	const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
 	try {
 		const child = spawn(opener, [target], {
@@ -949,13 +1217,35 @@ function sanitize(properties) {
 	}
 	return out;
 }
+/**
+* The CLI's own version, read by walking up to this package's manifest.
+*
+* The obvious `require("../../package.json")` was wrong everywhere, not only on
+* one install path: `vite build` bundles this module into `dist/index.es.js`, so
+* the specifier resolves relative to `<pkg>/dist/` and lands on
+* `<parent-of-pkg>/package.json` — a file that does not exist under npm, pnpm or
+* the monorepo. Every event ever sent carried `cliVersion: "unknown"`, which is
+* the one field that makes the rest of a payload interpretable.
+*
+* So walk up and check the manifest's `name` rather than counting directory
+* levels: the count differs between `src/telemetry/` and the bundled `dist/`,
+* and a wrong count fails silently by finding *some* package.json — the nearest
+* dependency's, under a hoisted layout. Matching the name cannot do that.
+*/
 function cliVersion() {
 	try {
-		const pkg = createRequire(import.meta.url)("../../package.json");
-		return typeof pkg?.version === "string" ? pkg.version : "unknown";
-	} catch {
-		return "unknown";
-	}
+		let dir = path.dirname(fileURLToPath(import.meta.url));
+		const root = path.parse(dir).root;
+		while (dir && dir !== root) {
+			const manifest = path.join(dir, "package.json");
+			if (fs.existsSync(manifest)) {
+				const pkg = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+				if (pkg?.name === "@rebasepro/cli" && typeof pkg.version === "string" && pkg.version) return pkg.version;
+			}
+			dir = path.dirname(dir);
+		}
+	} catch {}
+	return "unknown";
 }
 function buildEvent(event, properties, identity) {
 	return {
@@ -1455,7 +1745,7 @@ ${chalk.bold("Examples")}
 `);
 }
 async function createRebaseApp(rawArgs) {
-	if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+	if (wantsHelp(rawArgs)) {
 		printInitHelp();
 		return;
 	}
@@ -1464,26 +1754,31 @@ ${chalk.bold("Rebase")} — Create a new project 🚀
 `);
 	await createProject$1(await promptForOptions(rawArgs, detectPackageManager()));
 }
+/** The flags `rebase init` takes. */
+var INIT_FLAGS = {
+	"--git": Boolean,
+	"--install": Boolean,
+	"--database-url": String,
+	"--introspect": Boolean,
+	"--template": String,
+	"--headless": Boolean,
+	"--project": String,
+	"--setup-key": String,
+	"--yes": Boolean,
+	"-g": "--git",
+	"-i": "--install",
+	"-t": "--template",
+	"-y": "--yes"
+};
 async function promptForOptions(rawArgs, pm) {
-	const args = arg({
-		"--git": Boolean,
-		"--install": Boolean,
-		"--database-url": String,
-		"--introspect": Boolean,
-		"--template": String,
-		"--headless": Boolean,
-		"--project": String,
-		"--setup-key": String,
-		"--yes": Boolean,
-		"-g": "--git",
-		"-i": "--install",
-		"-t": "--template",
-		"-y": "--yes"
-	}, {
-		argv: rawArgs.slice(3),
-		permissive: true
+	const { flags: args, positionals } = parseCommandArgs({
+		spec: INIT_FLAGS,
+		rawArgs,
+		commandWords: 1,
+		command: "init",
+		maxPositionals: 1
 	});
-	const nameArg = args._[0];
+	const nameArg = positionals[0];
 	const isNonInteractive = args["--yes"] || false;
 	if (nameArg) {
 		const resolvedName = path.basename(path.resolve(process.cwd(), nameArg));
@@ -1606,6 +1901,49 @@ async function linkScaffoldToCloud(options) {
 		console.warn(chalk.yellow(`  ${linkLater}`));
 	}
 }
+/**
+* Make the initial commit, after everything that writes into the project has run.
+*
+* It used to happen immediately after `git init`, which is before dependency
+* installation and before introspection — so `init --git --install` ended on a
+* dirty tree whose only untracked file was `pnpm-lock.yaml`. A lockfile is
+* precisely the thing that should be in a project's first commit, and a brand
+* new scaffold whose first `git status` is dirty invites the reader to conclude
+* the lockfile is deliberately ignored and never commit it at all.
+*
+* Introspection has the same shape: it generates `config/collections` and
+* `schema.generated.ts`, which belong in the commit describing the scaffold that
+* produced them.
+*
+* `git init` stays where it was. Creating the repository early costs nothing and
+* means a failed install still leaves the user a repository to commit into.
+*/
+async function commitScaffold(targetDirectory) {
+	try {
+		await execa("git", ["add", "-A"], { cwd: targetDirectory });
+		let identity = {};
+		try {
+			await execa("git", ["config", "user.email"], { cwd: targetDirectory });
+		} catch {
+			identity = {
+				GIT_AUTHOR_NAME: "Rebase",
+				GIT_AUTHOR_EMAIL: "noreply@rebase.pro",
+				GIT_COMMITTER_NAME: "Rebase",
+				GIT_COMMITTER_EMAIL: "noreply@rebase.pro"
+			};
+		}
+		await execa("git", [
+			"commit",
+			"-m",
+			"Initial commit from Rebase"
+		], {
+			cwd: targetDirectory,
+			env: identity
+		});
+	} catch {
+		console.warn(chalk.yellow("  Warning: Failed to create the initial commit"));
+	}
+}
 async function createProject$1(options) {
 	const startedAt = Date.now();
 	if (fs.existsSync(options.targetDirectory)) {
@@ -1645,6 +1983,7 @@ async function createProject$1(options) {
 	await applyHeadless(options.targetDirectory, options.headless);
 	await replacePlaceholders(options);
 	await configureEnvFile(options.targetDirectory, options.databaseUrl);
+	let gitInitialized = false;
 	if (options.git) {
 		console.log(chalk.gray("  Initializing git repository..."));
 		try {
@@ -1656,26 +1995,7 @@ async function createProject$1(options) {
 					"refs/heads/main"
 				], { cwd: options.targetDirectory });
 			} catch {}
-			await execa("git", ["add", "-A"], { cwd: options.targetDirectory });
-			let identity = {};
-			try {
-				await execa("git", ["config", "user.email"], { cwd: options.targetDirectory });
-			} catch {
-				identity = {
-					GIT_AUTHOR_NAME: "Rebase",
-					GIT_AUTHOR_EMAIL: "noreply@rebase.pro",
-					GIT_COMMITTER_NAME: "Rebase",
-					GIT_COMMITTER_EMAIL: "noreply@rebase.pro"
-				};
-			}
-			await execa("git", [
-				"commit",
-				"-m",
-				"Initial commit from Rebase"
-			], {
-				cwd: options.targetDirectory,
-				env: identity
-			});
+			gitInitialized = true;
 		} catch {
 			console.warn(chalk.yellow("  Warning: Failed to initialize git repository"));
 		}
@@ -1732,6 +2052,7 @@ async function createProject$1(options) {
 			console.warn(chalk.yellow(`  Run \`${installCmd.join(" ")}\` then \`${execCmd.join(" ")}\` manually.`));
 		}
 	}
+	if (gitInitialized) await commitScaffold(options.targetDirectory);
 	await linkScaffoldToCloud(options);
 	console.log("");
 	console.log(`${chalk.green.bold("✓")} Project ${chalk.bold(options.projectName)} created successfully!`);
@@ -1789,7 +2110,7 @@ async function createProject$1(options) {
 		console.log(`  ${chalk.cyan(runDev.join(" "))}`);
 	}
 	console.log("");
-	console.log(isBaas ? chalk.gray("This starts a headless API (Hono + PostgreSQL). There are no collection files: ") + chalk.gray("the API is derived from your database schema. Once it serves a table, docs are at /api/swagger.") : chalk.gray("This starts both the backend (Hono + PostgreSQL)") + chalk.gray(" and the frontend (Vite + React) concurrently."));
+	console.log(isBaas ? introspected ? chalk.gray("This starts a headless API (Hono + PostgreSQL) over the collections just ") + chalk.gray("generated from your database in config/collections. Edit them to change what the ") + chalk.gray("API exposes; docs are at /api/swagger.") : chalk.gray("This starts a headless API (Hono + PostgreSQL). There are no collection files: ") + chalk.gray("the API is derived from your database schema. Once it serves a table, docs are at /api/swagger.") : chalk.gray("This starts both the backend (Hono + PostgreSQL)") + chalk.gray(" and the frontend (Vite + React) concurrently."));
 	console.log("");
 	console.log(chalk.gray("Docs: https://rebase.pro/docs"));
 	console.log(chalk.gray("GitHub: https://github.com/rebasepro/rebase"));
@@ -1976,18 +2297,51 @@ project directory ${path.basename(options.targetDirectory)}/ was created and is
 		fs.writeFileSync(fullPath, content, "utf-8");
 	}
 }
-async function isPortAvailable(port) {
+/** `undefined` binds the wildcard address, which is a different question — see isPortAvailable. */
+function canBind(port, host) {
 	return new Promise((resolve) => {
 		const server = net.createServer();
-		server.once("error", () => {
-			resolve(false);
+		server.once("error", (err) => {
+			resolve(err.code === "EAFNOSUPPORT" || err.code === "EADDRNOTAVAIL");
 		});
 		server.once("listening", () => {
 			server.close(() => resolve(true));
 		});
-		server.listen(port);
+		if (host === void 0) server.listen(port);
+		else server.listen(port, host);
 	});
 }
+/**
+* Whether `port` is free — on the wildcard address *and* on both loopback addresses.
+*
+* All three, because on macOS/BSD a successful bind does not mean the port is
+* unused. Sockets carry `SO_REUSEADDR` (Node sets it), under which a wildcard
+* bind and a specific-address bind on the same port do not conflict — in either
+* direction. So each probe alone has a blind spot, and they are different ones:
+*
+* - **Wildcard only** (what this used to do) misses a server bound to
+*   `127.0.0.1` and `[::1]` — a Homebrew or Postgres.app install, i.e. most
+*   developer machines. 5432 was reported free while it was already serving
+*   another project's database. Docker then published `*:5432` for the same
+*   reason and the container started cleanly, with no "port already allocated"
+*   error anywhere to hint at the collision. `DATABASE_URL` pointed at
+*   `localhost:5432`, `localhost` resolves to `::1` first, and every command
+*   reported success while reading and writing the *pre-existing* database — a
+*   `db push` would have created tables, roles and RLS policies inside it.
+*
+* - **Loopback only** misses the opposite case: Docker Desktop publishes a
+*   container's port on `*`, and a specific-address bind succeeds right past it.
+*   That port is free to probe and unusable to publish, so `docker compose up -d
+*   db` fails on "Bind for 0.0.0.0:PORT failed: port is already allocated" —
+*   loudly, but only after the project has been generated around the bad port.
+*
+* Requiring all three costs three sockets and leaves neither gap. The wildcard
+* bind is the one the container itself has to make; the loopback binds are the
+* addresses `DATABASE_URL` will actually name.
+*/
+async function isPortAvailable(port) {
+	return await canBind(port) && await canBind(port, "127.0.0.1") && await canBind(port, "::1");
+}
 async function findAvailablePort(startPort) {
 	let port = startPort;
 	while (!await isPortAvailable(port)) port++;
@@ -2013,11 +2367,38 @@ function readCliVersion() {
 	} catch {}
 	return "latest";
 }
+/**
+* The runtime image tag to pin, given the version of the CLI doing the scaffolding.
+*
+* Only a stable release publishes `rebasepro/server` — a multi-arch build on
+* every push to main would cost minutes per commit for an image nobody pulls.
+* So pinning a prerelease CLI's own version writes a tag that cannot exist, and
+* `docker compose up` fails on `manifest unknown`, which is the same dead end
+* as the missing-repository bug this pinning was added to prevent.
+*
+* A prerelease therefore falls back to `latest`, which is correct rather than
+* merely available: a bundle's manifest declares the runtime range it needs
+* (`^1`), the image supplies only `@rebasepro/server`, and the framework a
+* bundle runs is installed from its own `deps.declared` at boot. The current
+* stable runtime boots a canary bundle by design.
+*
+* A floating tag is a real cost — it is what pinning exists to avoid — so say
+* so in the file rather than leaving a reader to discover it.
+*/
+function resolveRuntimeImageTag(cliVersion) {
+	if (/^\d+\.\d+\.\d+-/.test(cliVersion)) return {
+		tag: "latest",
+		note: `# Scaffolded by a prerelease CLI (${cliVersion}), which publishes no runtime image,\n# so this floats to the newest stable runtime. Pin an exact version once you
+# deploy: a moving tag changes what you are running with no version changing.`
+	};
+	return { tag: cliVersion };
+}
 async function configureEnvFile(targetDirectory, databaseUrl) {
 	const envExamplePath = path.join(targetDirectory, ".env.example");
 	const envPath = path.join(targetDirectory, ".env");
 	if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) {
 		fs.copyFileSync(envExamplePath, envPath);
+		fs.chmodSync(envPath, 384);
 		const jwtSecret = crypto.randomBytes(32).toString("hex");
 		const dbPassword = crypto.randomBytes(16).toString("hex");
 		const serviceKey = crypto.randomBytes(48).toString("base64");
@@ -2031,8 +2412,10 @@ async function configureEnvFile(targetDirectory, databaseUrl) {
 		envContent = envContent.replace(/^#\s*REBASE_SERVICE_KEY=.*$/m, `REBASE_SERVICE_KEY=${serviceKey}`);
 		const composeApiPort = /^PORT=(\d+)/m.exec(envContent)?.[1] ?? "3001";
 		envContent = envContent.replace(/^#\s*CORS_ORIGINS=.*$/m, `CORS_ORIGINS=http://localhost:${composeApiPort}`);
-		const runtimeVersion = readCliVersion();
-		envContent = /^#?\s*REBASE_VERSION=.*$/m.test(envContent) ? envContent.replace(/^#?\s*REBASE_VERSION=.*$/m, `REBASE_VERSION=${runtimeVersion}`) : `${envContent.trimEnd()}\n\n# The Rebase runtime image tag docker-compose.yml pulls.\n# Change this and restart to upgrade; your project bundle is untouched.\nREBASE_VERSION=${runtimeVersion}\n`;
+		envContent = envContent.replace(/^#?\s*VITE_API_URL=.*$/m, "VITE_API_URL=");
+		const { tag: runtimeVersion, note } = resolveRuntimeImageTag(readCliVersion());
+		const pinned = `${note ? `${note}\n` : ""}REBASE_VERSION=${runtimeVersion}`;
+		envContent = /^#?\s*REBASE_VERSION=.*$/m.test(envContent) ? envContent.replace(/^#?\s*REBASE_VERSION=.*$/m, pinned) : `${envContent.trimEnd()}\n\n# The Rebase runtime image tag docker-compose.yml pulls.\n# Change this and restart to upgrade; your project bundle is untouched.\n${pinned}\n`;
 		if (databaseUrl) {
 			if (/[\r\n]/.test(databaseUrl)) throw new Error("Invalid DATABASE_URL: multiline values are not allowed.");
 			const { pinSearchPath } = await import("@rebasepro/server-postgres");
@@ -2040,7 +2423,7 @@ async function configureEnvFile(targetDirectory, databaseUrl) {
 			envContent = envContent.replace(/^DATABASE_URL=.*$/m, `DATABASE_URL=${pinnedUrl}\nDATABASE_PASSWORD=${dbPassword}`);
 		} else {
 			const dbPort = await findAvailablePort(5432);
-			envContent = envContent.replace(/^DATABASE_URL=.*$/m, `DATABASE_URL=postgresql://rebase:${dbPassword}@localhost:${dbPort}/rebase?options=-c%20search_path=public&sslmode=disable\nDATABASE_PASSWORD=${dbPassword}`);
+			envContent = envContent.replace(/^DATABASE_URL=.*$/m, `DATABASE_URL=postgresql://rebase_app:${dbPassword}@127.0.0.1:${dbPort}/rebase?options=-c%20search_path=public&sslmode=disable\nDATABASE_PASSWORD=${dbPassword}`);
 			const dockerComposePath = path.join(targetDirectory, "docker-compose.yml");
 			if (fs.existsSync(dockerComposePath)) {
 				let dockerComposeContent = fs.readFileSync(dockerComposePath, "utf-8");
@@ -2048,7 +2431,11 @@ async function configureEnvFile(targetDirectory, databaseUrl) {
 				fs.writeFileSync(dockerComposePath, dockerComposeContent, "utf-8");
 			}
 		}
-		fs.writeFileSync(envPath, envContent, "utf-8");
+		fs.writeFileSync(envPath, envContent, {
+			encoding: "utf-8",
+			mode: 384
+		});
+		fs.chmodSync(envPath, 384);
 	}
 }
 //#endregion
@@ -2318,7 +2705,17 @@ async function generateSdkCommand(args) {
 	console.log(chalk.green(`  ✓ Found ${collections.length} collection(s): ${collections.map((c) => c.slug).join(", ")}`));
 	console.log("");
 	console.log(chalk.cyan("  → Generating SDK files..."));
-	const files = generateSDK(collections);
+	let files;
+	try {
+		files = generateSDK(collections);
+	} catch (err) {
+		if (err instanceof CodegenError) {
+			console.log("");
+			console.log(chalk.red(`  ✗ ${err.message}`));
+			process.exit(1);
+		}
+		throw err;
+	}
 	const schemaVersion = remoteSchemaVersion ?? computeSchemaVersion(collections);
 	files.push({
 		path: "schema.meta.ts",
@@ -2330,7 +2727,6 @@ async function generateSdkCommand(args) {
 //     curl -s <api-url>/api/meta/schema-version
 //
 export const SCHEMA_VERSION = ${JSON.stringify(schemaVersion)};
-export const GENERATED_AT = ${JSON.stringify((/* @__PURE__ */ new Date()).toISOString())};
 `
 	});
 	console.log(chalk.green(`  ✓ Generated ${files.length} file(s)`));
@@ -2352,8 +2748,9 @@ export const GENERATED_AT = ${JSON.stringify((/* @__PURE__ */ new Date()).toISOS
 	console.log(chalk.gray("        // token: 'your-jwt-token',"));
 	console.log(chalk.gray("    });"));
 	console.log("");
-	console.log(chalk.gray(`    const { data } = await rebase.data.collection('${exampleSlug}').find();`));
-	if (isIdentifierLike(exampleSlug)) console.log(chalk.gray(`    // …or in property style: rebase.data.${exampleSlug}.find()`));
+	const exampleAccessor = toSafeIdentifier(exampleSlug);
+	const exampleAccess = isIdentifierLike(exampleAccessor) ? `rebase.data.${exampleAccessor}` : `rebase.data[${JSON.stringify(exampleAccessor)}]`;
+	console.log(chalk.gray(`    const { data } = await ${exampleAccess}.find();`));
 	console.log("");
 }
 //#endregion
@@ -2367,7 +2764,7 @@ async function schemaCommand(subcommand, rawArgs) {
 		return;
 	}
 	const projectRoot = requireProjectRoot();
-	recordEvent("cli.schema_generate", { subcommand: subcommand ?? "none" }, { projectRoot });
+	recordEvent("cli.schema", { subcommand: subcommand ?? "none" }, { projectRoot });
 	const backendDir = requireBackendDir(projectRoot);
 	const activePlugin = getActiveBackendPlugin(backendDir);
 	if (!activePlugin) {
@@ -2436,7 +2833,7 @@ async function dbCommand(subcommand, rawArgs) {
 		return;
 	}
 	const projectRoot = requireProjectRoot();
-	recordEvent("cli.db_push", { subcommand: subcommand ?? "none" }, { projectRoot });
+	recordEvent("cli.db", { subcommand: subcommand ?? "none" }, { projectRoot });
 	const backendDir = requireBackendDir(projectRoot);
 	const activePlugin = getActiveBackendPlugin(backendDir);
 	if (!activePlugin) {
@@ -2834,13 +3231,20 @@ function validateManifest(raw) {
 		byPath.set(at, name);
 	}
 	const storage = validateStorageSources(raw.storage, issues);
+	let telemetry;
+	if (raw.telemetry !== void 0) if (typeof raw.telemetry === "boolean") telemetry = raw.telemetry;
+	else issues.push({
+		path: "telemetry",
+		message: "must be a boolean — only `false` does anything, and it opts this repository out of usage sharing"
+	});
 	if (issues.length > 0) return { issues };
 	return {
 		manifest: {
 			$schema: typeof raw.$schema === "string" ? raw.$schema : void 0,
 			rebase: raw.rebase,
 			apps,
-			...storage ? { storage } : {}
+			...storage ? { storage } : {},
+			...telemetry !== void 0 ? { telemetry } : {}
 		},
 		issues
 	};
@@ -2949,7 +3353,7 @@ function synthesizeManifest(projectRoot) {
 		if (exists("backend/functions")) backend.functions = DEFAULT_FUNCTIONS_DIR;
 		if (exists("backend/crons")) backend.crons = DEFAULT_CRONS_DIR;
 		apps.backend = backend;
-		if (!dockerfile && exists("backend/src/index.ts")) console.warn("⚠ backend/src/index.ts exists but this project's backend is managed — it is\n    never loaded. Delete it, or run `rebase eject` to make it the entrypoint.");
+		if (!dockerfile && exists("backend/src/index.ts")) console.warn("⚠ backend/src/index.ts exists but this project's backend is managed — it is\n    never loaded. Delete it, or move it aside and run `rebase eject`, which\n    writes an entrypoint of its own and owns the image. Eject does not adopt\n    this file: it refuses to replace it unless you pass --force.");
 	}
 	if (exists("frontend")) apps.web = {
 		type: "static",
@@ -2997,13 +3401,59 @@ function loadManifest(projectRoot) {
 		filePath
 	};
 }
-/** Write a manifest, with a trailing newline so it plays well with other tools. */
+/** The keys `writeManifest` knows how to write. Everything else is carried through. */
+var MODELLED_MANIFEST_KEYS = [
+	"$schema",
+	"rebase",
+	"apps",
+	"storage",
+	"telemetry"
+];
+/**
+* What is on disk right now, or `{}` — this is a *rewrite*, so the file that is
+* about to be replaced is the only record of the keys the caller did not model.
+* Unparseable is treated as absent: `loadManifest` refuses malformed JSON long
+* before anything gets here, and a writer is not the place to fail on it.
+*/
+function readManifestObject(filePath) {
+	try {
+		const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+		return isRecord(parsed) ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+/**
+* Write a manifest, with a trailing newline so it plays well with other tools.
+*
+* **Every key on disk survives.** This used to emit exactly `$schema`, `rebase`
+* and `apps`, so a rewrite deleted the rest of the file — and two commands with
+* no visible relationship to either key rewrite it: `rebase eject` and
+* `rebase apps init --force`. A repository that had committed
+* `"telemetry": false` lost its opt-out, and a multi-bucket project lost its
+* whole `storage` block, in a commit whose stated change was `runtime: custom`.
+*
+* So: the caller's manifest wins for what it models, the file supplies the rest.
+* `storage` and `telemetry` fall back to the file because the callers that
+* synthesize a manifest (`apps init --force`) cannot know them — they are
+* authored, not inferred — and unknown top-level keys are copied verbatim
+* rather than listed, since a hand-listed set loses the next key too.
+*/
 function writeManifest(projectRoot, manifest) {
 	const filePath = manifestPath(projectRoot);
+	const existing = readManifestObject(filePath);
+	const carried = {};
+	for (const [key, value] of Object.entries(existing)) if (!MODELLED_MANIFEST_KEYS.includes(key)) carried[key] = value;
+	const schema = manifest.$schema ?? (typeof existing.$schema === "string" ? existing.$schema : void 0) ?? "https://rebase.pro/schemas/rebase.json";
+	const storage = manifest.storage ?? (isRecord(existing.storage) ? existing.storage : void 0);
+	const telemetry = manifest.telemetry ?? (typeof existing.telemetry === "boolean" ? existing.telemetry : void 0);
 	const ordered = {
-		$schema: manifest.$schema ?? "https://rebase.pro/schemas/rebase.json",
+		$schema: schema,
 		rebase: manifest.rebase,
-		apps: manifest.apps
+		apps: manifest.apps,
+		...storage ? { storage } : {},
+		...telemetry !== void 0 ? { telemetry } : {},
+		...carried
 	};
 	fs.writeFileSync(filePath, `${JSON.stringify(ordered, null, 4)}\n`, "utf8");
 	return filePath;
@@ -3074,6 +3524,106 @@ function resolveBackendPaths(app, projectRoot) {
 	};
 }
 //#endregion
+//#region src/utils/collection-drift.ts
+/**
+* Which edits under `config/collections` can put the *SQL* schema out of date.
+*
+* `rebase dev` watches that directory and, on any change, either tells the
+* developer to run `rebase schema generate` / `rebase db push` or runs them.
+* The watcher is recursive and knows nothing about what it is watching, so it
+* said that about every file under the directory — including a
+* `collections/firestore/exercises.ts`, whose documents live in Firestore and
+* for which there is no Drizzle schema to regenerate and no database to push
+* to. Advice that is wrong on every edit is advice a developer learns to
+* ignore, which is worse than none: the same box is the only warning for the
+* Postgres collection next to it, where it is real.
+*
+* Two independent reasons a change cannot affect the SQL schema, both checked
+* here:
+*
+* 1. **The loader would never read the file.** `loadCollectionsFromDirectory`
+*    reads the top level of the collections directory only — no recursion, no
+*    `index`, no tests, no declarations. A file it does not read cannot change
+*    what it returns, and the watcher must not claim otherwise.
+* 2. **Every collection in it is served by another engine.** A Firestore or
+*    MongoDB collection has no table, no migration and no policies.
+*
+* The engine check reads the source text rather than importing the module: the
+* CLI runs as plain Node and cannot evaluate a project's TypeScript, and a
+* watcher must answer in the time between two keystrokes. Anything it cannot
+* read confidently counts as SQL-affecting — a spurious warning is a nuisance,
+* a suppressed one hides real drift.
+*/
+/**
+* Would `loadCollectionsFromDirectory` load this file?
+*
+* Mirrors that loader's own `isCollectionFile` plus its flat (non-recursive)
+* scan. `relativePath` is relative to the collections directory, as `fs.watch`
+* reports it.
+*/
+function isLoadedCollectionFile(relativePath) {
+	const normalized = relativePath.split(path.sep).join("/");
+	if (normalized.includes("/")) return false;
+	const file = normalized;
+	if (!file.endsWith(".ts") && !file.endsWith(".js")) return false;
+	if (file.startsWith(".")) return false;
+	if (file.includes(".test.")) return false;
+	if (file.endsWith(".d.ts")) return false;
+	if (file === "index.ts" || file === "index.js") return false;
+	return true;
+}
+var ENGINE_LITERAL = /\bengine\s*:\s*["'`]([^"'`]+)["'`]/g;
+var DATA_SOURCE_LITERAL = /\bdataSource\s*:\s*["'`]([^"'`]+)["'`]/g;
+/**
+* Drop comments, so a `// engine: "firestore"` in a docblock cannot silence a
+* warning about the Postgres collection the file actually declares.
+*
+* Deliberately naive — it does not understand strings, so a `//` inside one
+* (a URL in a default value) eats the rest of that line. That only ever removes
+* text, and removing an engine literal makes this file *more* likely to warn,
+* which is the side to be wrong on.
+*/
+function stripComments(source) {
+	return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
+}
+function literals(source, pattern) {
+	const found = [];
+	for (const match of source.matchAll(pattern)) found.push(match[1]);
+	return found;
+}
+/**
+* Does this collection source declare anything a SQL toolchain would own?
+*
+* The fallback order matches `resolveDataSource`: an explicit `engine` wins,
+* and a collection that only names a `dataSource` is resolved as if the key
+* were the engine — which is what that function does when no registry is
+* available, and the CLI has none. An engine nobody recognises counts as
+* relational, for the reason `isRelationalCollection` gives.
+*
+* A file declaring several collections is SQL-affecting if *any* of them is.
+*/
+function declaresRelationalCollection(rawSource) {
+	const source = stripComments(rawSource);
+	const engines = literals(source, ENGINE_LITERAL);
+	const declared = engines.length > 0 ? engines : literals(source, DATA_SOURCE_LITERAL).filter((key) => key !== DEFAULT_DATA_SOURCE_KEY);
+	if (declared.length === 0) return true;
+	return declared.some((engine) => getDataSourceCapabilities(engine).supportsRelations);
+}
+/**
+* Can this edit have changed the generated SQL schema?
+*
+* Answers `true` when it cannot tell — an unreadable file is a reason to warn,
+* not a reason to go quiet.
+*/
+function affectsSqlSchema(collectionsDir, relativePath) {
+	if (!isLoadedCollectionFile(relativePath)) return false;
+	try {
+		return declaresRelationalCollection(fs.readFileSync(path.join(collectionsDir, relativePath), "utf8"));
+	} catch {
+		return true;
+	}
+}
+//#endregion
 //#region src/commands/dev.ts
 /**
 * CLI command: rebase dev
@@ -3167,38 +3717,67 @@ function getProjectPort(projectRoot) {
 * 3. Previously used port from .rebase-dev-port (port affinity across restarts)
 * 4. Deterministic hash from project path (unique per project)
 */
+/**
+* A TCP port, or `undefined` for anything that is not one.
+*
+* One predicate for both sources below. The port file was already checked for
+* range, and `PORT` — the source a human or a platform actually sets — was not,
+* so `PORT=oops` reached `parseInt` and was returned as `NaN`: the dev server
+* then bound to whatever the OS handed out and the CLI printed a URL for a port
+* nothing was listening on.
+*/
+function parsePort(raw) {
+	if (raw === void 0) return void 0;
+	const port = Number(raw.trim());
+	if (!Number.isInteger(port) || port <= 0 || port >= 65536) return void 0;
+	return port;
+}
 function resolveStartPort(projectRoot, explicitPort) {
 	if (explicitPort) return explicitPort;
-	if (process.env.PORT) return parseInt(process.env.PORT, 10);
+	if (process.env.PORT) {
+		const fromEnv = parsePort(process.env.PORT);
+		if (fromEnv !== void 0) return fromEnv;
+		console.warn(chalk.yellow(`  ⚠ Ignoring PORT="${process.env.PORT}" — not a port between 1 and 65535.`));
+	}
 	try {
 		const portFile = path.join(projectRoot, DEV_PORT_FILENAME);
 		if (fs.existsSync(portFile)) {
-			const saved = parseInt(fs.readFileSync(portFile, "utf-8").trim(), 10);
-			if (saved > 0 && saved < 65536) return saved;
+			const saved = parsePort(fs.readFileSync(portFile, "utf-8"));
+			if (saved !== void 0) return saved;
 		}
 	} catch {}
 	return getProjectPort(projectRoot);
 }
+/**
+* The flags `rebase dev` takes.
+*
+* Exported so `dev.test.ts` can assert that every short alias the help
+* advertises is declared here: the help said `--port, -p` while the spec has
+* only ever declared `-P`, so `rebase dev -p 4000` typed straight off the help
+* page passed `4000` as a positional and started on the default port.
+*/
+var DEV_FLAGS = {
+	"--backend-only": Boolean,
+	"--frontend-only": Boolean,
+	"--port": Number,
+	"--generate": Boolean,
+	"-b": "--backend-only",
+	"-f": "--frontend-only",
+	"-P": "--port",
+	"-g": "--generate"
+};
 async function devCommand(rawArgs) {
-	const args = arg({
-		"--backend-only": Boolean,
-		"--frontend-only": Boolean,
-		"--port": Number,
-		"--generate": Boolean,
-		"--help": Boolean,
-		"-b": "--backend-only",
-		"-f": "--frontend-only",
-		"-p": "--port",
-		"-g": "--generate",
-		"-h": "--help"
-	}, {
-		argv: rawArgs.slice(3),
-		permissive: true
-	});
-	if (args["--help"]) {
+	if (wantsHelp(rawArgs)) {
 		printDevHelp();
 		return;
 	}
+	const { flags: args } = parseCommandArgs({
+		spec: DEV_FLAGS,
+		rawArgs,
+		commandWords: 1,
+		command: "dev",
+		maxPositionals: 0
+	});
 	const projectRoot = requireProjectRoot();
 	recordEvent("cli.dev", {
 		backend_only: Boolean(args["--backend-only"]),
@@ -3345,6 +3924,20 @@ async function devCommand(rawArgs) {
 		} catch {}
 		/** Whether the frontend has been launched (we only launch it once). */
 		let frontendLaunched = false;
+		try {
+			const activePlugin = getActiveBackendPlugin(backendDir);
+			const pluginCli = activePlugin ? resolvePluginCliScript(backendDir, activePlugin) : null;
+			if (pluginCli) await execa(tsxBin, [
+				pluginCli,
+				"schema",
+				"stale",
+				"--fix"
+			], {
+				cwd: backendDir,
+				stdio: "inherit",
+				env
+			});
+		} catch {}
 		if (shouldGenerate) {
 			console.log(chalk.gray("  → Ensuring schema and SDK are generated on start..."));
 			try {
@@ -3372,14 +3965,18 @@ async function devCommand(rawArgs) {
 			const collectionsDir = path.join(projectRoot, "config", "collections");
 			if (fs.existsSync(collectionsDir)) {
 				let watchDebounce = null;
+				let sqlSchemaAffected = false;
 				fs.watch(collectionsDir, { recursive: true }, (eventType, filename) => {
 					if (!filename || filename.startsWith(".") || filename.endsWith(".tmp")) return;
+					sqlSchemaAffected = sqlSchemaAffected || affectsSqlSchema(collectionsDir, filename);
 					if (watchDebounce) clearTimeout(watchDebounce);
 					watchDebounce = setTimeout(async () => {
-						console.log(chalk.yellow(`\n  🔄 Collection change detected (${filename}). Regenerating schema & SDK...`));
+						const regenerateSchema = sqlSchemaAffected;
+						sqlSchemaAffected = false;
+						console.log(chalk.yellow(`\n  🔄 Collection change detected (${filename}). Regenerating ${regenerateSchema ? "schema & SDK" : "SDK"}...`));
 						try {
 							const activePlugin = getActiveBackendPlugin(backendDir);
-							const pluginCli = activePlugin ? resolvePluginCliScript(backendDir, activePlugin) : null;
+							const pluginCli = regenerateSchema && activePlugin ? resolvePluginCliScript(backendDir, activePlugin) : null;
 							if (pluginCli) await execa(tsxBin, [
 								pluginCli,
 								"schema",
@@ -3395,7 +3992,7 @@ async function devCommand(rawArgs) {
 								stdio: "inherit",
 								env
 							});
-							console.log(chalk.green("  ✓ Schema & SDK regenerated successfully. Hono will reload."));
+							console.log(chalk.green(`  ✓ ${regenerateSchema ? "Schema & SDK" : "SDK"} regenerated successfully. Hono will reload.`));
 						} catch (err) {
 							console.error(chalk.red(`  ✗ Failed to regenerate schema/SDK: ${err instanceof Error ? err.message : err}`));
 						}
@@ -3420,12 +4017,14 @@ async function devCommand(rawArgs) {
 				let driftDebounce = null;
 				fs.watch(collectionsDir, { recursive: true }, (_eventType, filename) => {
 					if (!filename || filename.startsWith(".") || filename.endsWith(".tmp")) return;
+					if (!affectsSqlSchema(collectionsDir, filename)) return;
 					if (driftDebounce) clearTimeout(driftDebounce);
 					driftDebounce = setTimeout(() => {
+						const shown = filename.length > 31 ? `…${filename.slice(-30)}` : filename.padEnd(31);
 						console.log([
 							"",
 							chalk.yellow("  ┌──────────────────────────────────────────────────────────────┐"),
-							chalk.yellow("  │  ⚠️  Collection file changed: ") + chalk.white(filename.padEnd(31)) + chalk.yellow("│"),
+							chalk.yellow("  │  ⚠️  Collection file changed: ") + chalk.white(shown) + chalk.yellow("│"),
 							chalk.yellow("  │                                                              │"),
 							chalk.yellow("  │  Your schema may be out of sync. Run:                        │"),
 							chalk.yellow("  │    ") + chalk.cyan("rebase schema generate") + chalk.yellow("   regenerate Drizzle schema        │"),
@@ -3520,7 +4119,7 @@ ${chalk.green.bold("Usage")}
 ${chalk.green.bold("Options")}
   ${chalk.blue("--backend-only, -b")}   Only start the backend server
   ${chalk.blue("--frontend-only, -f")}  Only start the frontend server
-  ${chalk.blue("--port, -p")}           Backend port (default: auto-detected per project)
+  ${chalk.blue("--port, -P")}           Backend port (default: auto-detected per project)
   ${chalk.blue("--generate, -g")}        Enable automatic schema and SDK generation on startup and file changes
 
 ${chalk.green.bold("Description")}
@@ -4245,10 +4844,11 @@ async function regenerateSchema(projectRoot, configDir, options) {
 * deployed green, and answered 404 on every one of them, with the file still
 * sitting in the repository looking exactly like the server.
 *
-* A project that means to keep its own entrypoint runs `rebase eject`, which
-* writes the entrypoint, a Dockerfile and a compose file together and flips the
+* A project that means to own its server process runs `rebase eject`, which
+* writes an entrypoint, a Dockerfile and a compose file together and flips the
 * backend to `runtime: "custom"`. The warning names that route rather than
-* implying the file is a mistake.
+* implying the file is a mistake — but eject writes *its* entrypoint, so the
+* warning must not read as "eject will keep what you wrote here".
 */
 function findUnusedServerEntry(projectRoot, functionsDir) {
 	const found = [path.join("backend", "src", "index.ts"), path.join(path.dirname(functionsDir), "src", "index.ts")].find((candidate) => fs.existsSync(path.join(projectRoot, candidate)));
@@ -4282,7 +4882,9 @@ async function buildBundle(options) {
 		console.log(chalk.yellow(`  ⚠ ${unusedEntry} is not the bundle's entry point — it is not compiled or shipped.`));
 		console.log(chalk.dim(`      The runtime boots the bundle itself and mounts ${compiled}.`));
 		console.log(chalk.dim(`      Routes defined there will not exist once deployed: move them to ${paths.functions}/,`));
-		console.log(chalk.dim("      or run `rebase eject` to make this file the entrypoint and own the image."));
+		console.log(chalk.dim("      or run `rebase eject`, which writes an entrypoint of its own and owns"));
+		console.log(chalk.dim("      the image — it does not adopt this file, and will not replace it"));
+		console.log(chalk.dim("      without --force."));
 	}
 	log(options, chalk.dim(`  compiling ${includes.length} source group(s) → ${path.relative(projectRoot, outDir)}/`));
 	cleanOutDir(projectRoot, outDir);
@@ -4651,6 +5253,61 @@ function assertBuiltForPath(indexHtml, basePath, appName) {
     build config — see docs/apps-and-runtimes.md §4.2.`);
 }
 /**
+* The environment every static app is built with, wherever that build is driven from.
+*
+* Shared because there are two drivers — `foldFrontendIntoBundle` here, and
+* `buildAssetApp` in `build.ts` for a standalone `type: "static"` app — and they
+* had already drifted: the path variables were duplicated into both, so a fix
+* applied to one shipped a bundle built the old way from the other. One function
+* makes that impossible rather than merely unlikely.
+*
+* ## REBASE_APP_*
+*
+* The declared path is a build-time input, not only a serving concern: Vite
+* reads `base` from REBASE_APP_BASE, and the trailing slash is that field's
+* convention. See `assertBuiltForPath`.
+*
+* ## NODE_ENV
+*
+* A built app is a production artifact by construction, so build it as one. Not
+* a formality: the scaffold's `.env` carries `NODE_ENV=development` for the dev
+* backend, and Vite's `loadEnv` promotes a `NODE_ENV` found in an env file into
+* the build unless the environment already sets one. So `rebase build` and
+* `rebase cloud deploy` shipped a *development* bundle — `import.meta.env.DEV
+* === true`, development React, dev-only branches live — from commands whose
+* whole purpose is to produce something deployable. Setting it here is what
+* closes it: Vite consults the env file's NODE_ENV only when `process.env`
+* has none.
+*
+* ## VITE_API_URL
+*
+* An app served by the backend it talks to has its API on its own origin by
+* construction, so a baked-in absolute URL can only be wrong. It was: that same
+* `.env` carries `VITE_API_URL=http://localhost:3001` and
+* `frontend/vite.config.ts` reads the project root via `envDir: ".."`, so a
+* stock deploy shipped a site whose every request went to whoever ran the build
+* — passing every server-side health check on the way out. Blanking it here
+* fixes the bundle even for a project whose `.env` predates the `init` fix, or
+* was written by hand. Empty is the right value rather than a missing one: the
+* client falls back to `window.location.origin`, which keeps working when a
+* custom domain is added.
+*
+* Vite prioritises `process.env.VITE_*` over `.env` files, so an explicit
+* `VITE_API_URL=https://api.example.com rebase cloud deploy` still wins — the
+* cross-origin escape hatch stays open, it just has to be deliberate. Nothing on
+* this path loads the project `.env` into `process.env`, so a value inherited
+* here really was set by the caller.
+*/
+function staticBuildEnv(appPath, appName) {
+	return {
+		REBASE_APP_PATH: appPath,
+		REBASE_APP_BASE: appPath === "/" ? "/" : `${appPath}/`,
+		REBASE_APP_NAME: appName,
+		NODE_ENV: "production",
+		VITE_API_URL: process.env.VITE_API_URL ?? ""
+	};
+}
+/**
 * Build the project's static apps and fold them into the backend bundle.
 *
 * Throws rather than exiting, so the caller decides whether a missing frontend
@@ -4669,11 +5326,7 @@ async function foldFrontendIntoBundle(options) {
 			cwd: projectRoot,
 			stdio: "inherit",
 			shell: true,
-			env: {
-				REBASE_APP_PATH: app.path,
-				REBASE_APP_BASE: app.path === "/" ? "/" : `${app.path}/`,
-				REBASE_APP_NAME: app.name
-			}
+			env: staticBuildEnv(app.path, app.name)
 		});
 		const assetsDir = path.join(projectRoot, app.output);
 		if (!fs.existsSync(assetsDir)) throw new Error(`"${app.name}" declared output "${app.output}" does not exist after building — the bundle would ship without a frontend.`);
@@ -4731,23 +5384,24 @@ ${chalk.bold("Examples")}
 `.trim());
 }
 async function buildCommand(rawArgs = []) {
-	const args = arg({
-		"--out": String,
-		"--skip-type-check": Boolean,
-		"--skip-schema": Boolean,
-		"--no-static": Boolean,
-		"--skip-static-build": Boolean,
-		"--legacy": Boolean,
-		"--help": Boolean,
-		"-h": "--help"
-	}, {
-		argv: rawArgs.slice(3),
-		permissive: true
-	});
-	if (args["--help"]) {
+	if (wantsHelp(rawArgs)) {
 		printHelp$5();
 		return;
 	}
+	const { flags: args, positionals: requested } = parseCommandArgs({
+		spec: {
+			"--output": String,
+			"--out": "--output",
+			"--skip-type-check": Boolean,
+			"--skip-schema": Boolean,
+			"--no-static": Boolean,
+			"--skip-static-build": Boolean,
+			"--legacy": Boolean
+		},
+		rawArgs,
+		commandWords: 1,
+		command: "build"
+	});
 	const projectRoot = requireProjectRoot();
 	if (args["--legacy"]) {
 		await runWorkspaceBuilds(projectRoot);
@@ -4765,7 +5419,6 @@ async function buildCommand(rawArgs = []) {
 		throw err;
 	}
 	const { manifest, source } = loaded;
-	const requested = args._.filter((a) => !a.startsWith("-"));
 	let targets = buildableApps(manifest);
 	if (requested.length > 0) {
 		const known = new Set(targets.map((t) => t.name));
@@ -4800,7 +5453,7 @@ async function buildCommand(rawArgs = []) {
 				projectRoot,
 				appName: name,
 				app,
-				outDir: args["--out"],
+				outDir: args["--output"],
 				runtimeRange: manifest.rebase,
 				storage: manifest.storage,
 				skipTypeCheck: args["--skip-type-check"],
@@ -4837,7 +5490,7 @@ async function buildCommand(rawArgs = []) {
 				});
 				for (const outcome of folded ?? []) console.log(chalk.green(`    ✓ ${outcome.appName} folded in`) + chalk.dim(` (${outcome.fileCount} file(s) → served at ${outcome.path})`));
 			}
-		} else if (app.type === "static") await buildAssetApp(projectRoot, name, app, manifest.rebase, args["--out"]);
+		} else if (app.type === "static") await buildAssetApp(projectRoot, name, app, manifest.rebase, args["--output"]);
 		console.log("");
 	}
 	console.log(chalk.green("✓ Build complete."));
@@ -4862,11 +5515,7 @@ async function buildAssetApp(projectRoot, name, app, runtimeRange, outOverride)
 			cwd: projectRoot,
 			stdio: "inherit",
 			shell: true,
-			env: {
-				REBASE_APP_PATH: basePath,
-				REBASE_APP_BASE: basePath === "/" ? "/" : `${basePath}/`,
-				REBASE_APP_NAME: name
-			}
+			env: staticBuildEnv(basePath, name)
 		});
 	} catch {
 		console.error(chalk.red(`  ✗ build command failed for "${name}"`));
@@ -4948,6 +5597,56 @@ function findCliRoot(from) {
 	}
 	return null;
 }
+/** The block names the payload may switch on. A typo has to be an error. */
+var SHAPE_FLAGS = ["collections", "frontend"];
+/**
+* Render one payload file for this project.
+*
+* The payload is one set of files rather than one per flavour, because the
+* flavours differ by about a dozen lines and two copies of a 230-line
+* entrypoint are how copies drift — the payload had already drifted from
+* `app/backend/src/index.ts` over `cronsDir`, which silently stopped every cron
+* job in an ejected project. So both branches live in the file, marked with
+* lines that are comments in TypeScript, YAML and Dockerfiles alike:
+*
+*     // {{#collections}}
+*     import { tables } from "./schema.generated.js";
+*     // {{/collections}}
+*     // {{^collections}}
+*     // No schema module: this project introspects the database.
+*     // {{/collections}}
+*
+* `{{#name}}` keeps its block when the flag is on, `{{^name}}` when it is off,
+* and the marker lines themselves never reach the user. The template stays
+* valid TypeScript with every marker line removed, which is the flavour a
+* typechecker would see.
+*/
+function renderPayload(contents, shape, projectName) {
+	const flags = shape;
+	const out = [];
+	let open = null;
+	for (const line of contents.split("\n")) {
+		const marker = /^\s*(?:\/\/|#)\s*\{\{([#^/])([A-Za-z]+)\}\}\s*$/.exec(line);
+		if (!marker) {
+			if (!open || open.keep) out.push(line);
+			continue;
+		}
+		const [, kind, name] = marker;
+		if (kind === "/") {
+			if (!open || open.name !== name) throw new Error(`Eject template: {{/${name}}} does not close an open block.`);
+			open = null;
+			continue;
+		}
+		if (open) throw new Error(`Eject template: {{${kind}${name}}} inside an open ${open.name} block.`);
+		if (!SHAPE_FLAGS.includes(name)) throw new Error(`Eject template: unknown block {{${kind}${name}}}.`);
+		open = {
+			name,
+			keep: kind === "#" ? flags[name] === true : flags[name] !== true
+		};
+	}
+	if (open) throw new Error(`Eject template: {{#${open.name}}} was never closed.`);
+	return out.join("\n").replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+}
 /** Files the eject payload contributes, as `<source> → <destination>`. */
 var PAYLOAD = [
 	{
@@ -4998,25 +5697,30 @@ ${chalk.bold("Usage")}
 
 ${chalk.bold("Options")}
   --dry-run                    List what would change, and change nothing
+  --force                      Replace an existing backend/src/index.ts or
+                               env.ts, keeping the current file as <name>.bak
   -h, --help                   Show this help
 `.trim());
 }
 async function ejectCommand(rawArgs = []) {
-	const args = arg({
-		"--dry-run": Boolean,
-		"--help": Boolean,
-		"-h": "--help"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
-	});
-	if (args["--help"]) {
+	if (wantsHelp(rawArgs)) {
 		printHelp$4();
 		return;
 	}
+	const { flags: args, positionals } = parseCommandArgs({
+		spec: {
+			"--dry-run": Boolean,
+			"--force": Boolean
+		},
+		rawArgs,
+		commandWords: 1,
+		command: "eject",
+		maxPositionals: 1
+	});
 	const projectRoot = requireProjectRoot();
 	const dryRun = Boolean(args["--dry-run"]);
-	const requested = args._.slice(1).find((value) => !value.startsWith("-"));
+	const force = Boolean(args["--force"]);
+	const requested = positionals[0];
 	let loaded;
 	try {
 		loaded = loadManifest(projectRoot);
@@ -5065,7 +5769,12 @@ async function ejectCommand(rawArgs = []) {
 		process.exit(1);
 	}
 	const payloadDir = path.join(cliRoot, "templates", "eject");
+	const shape = {
+		collections: resolveBackendPaths(app, projectRoot).hasCollections,
+		frontend: fs.existsSync(path.join(projectRoot, "frontend"))
+	};
 	const planned = [];
+	const blocked = [];
 	for (const file of PAYLOAD) {
 		const source = path.join(payloadDir, file.from);
 		if (!fs.existsSync(source)) {
@@ -5073,26 +5782,43 @@ async function ejectCommand(rawArgs = []) {
 			process.exit(1);
 		}
 		const exists = fs.existsSync(path.join(projectRoot, file.to));
+		if (exists && file.overwrite && !force) blocked.push(file.to);
 		planned.push({
 			to: file.to,
-			action: exists && !file.overwrite ? "keep" : "write"
+			action: !exists ? "write" : file.overwrite ? "overwrite" : "keep"
 		});
 	}
+	if (blocked.length > 0) {
+		console.error(chalk.red("✗ Ejecting would replace a file this project already has:"));
+		for (const item of blocked) console.error(chalk.red(`      ${item}`));
+		console.error(chalk.dim("  Eject writes its own entrypoint — it does not adopt yours."));
+		console.error(chalk.dim("  Move the file aside, or re-run with --force, which keeps the current"));
+		console.error(chalk.dim("  contents as <name>.bak."));
+		process.exit(1);
+	}
 	if (dryRun) {
 		console.log(chalk.bold(`Would eject "${appName}" to a custom runtime:`));
 		console.log("");
-		for (const item of planned) console.log(item.action === "write" ? `  ${chalk.green("write")}  ${item.to}` : `  ${chalk.dim("keep")}   ${item.to} ${chalk.dim("(already exists)")}`);
-		console.log(`  ${chalk.green("write")}  rebase.json ${chalk.dim("(runtime: \"custom\")")}`);
+		for (const item of planned) if (item.action === "write") console.log(`  ${chalk.green("write")}      ${item.to}`);
+		else if (item.action === "overwrite") console.log(`  ${chalk.yellow("overwrite")}  ${item.to} ${chalk.dim(`(kept as ${item.to}.bak)`)}`);
+		else console.log(`  ${chalk.dim("keep")}       ${item.to} ${chalk.dim("(already exists)")}`);
+		console.log(`  ${chalk.green("write")}      rebase.json ${chalk.dim("(runtime: \"custom\")")}`);
+		if (fs.existsSync(path.join(projectRoot, "backend", "package.json"))) console.log(`  ${chalk.green("write")}      backend/package.json ${chalk.dim("(main, dev and start scripts)")}`);
 		console.log("");
 		console.log(chalk.dim("Nothing was changed."));
 		return;
 	}
 	const projectName = projectNameOf(projectRoot);
+	const backups = [];
 	for (const [index, file] of PAYLOAD.entries()) {
 		if (planned[index].action === "keep") continue;
 		const destination = path.join(projectRoot, file.to);
+		if (planned[index].action === "overwrite") {
+			fs.copyFileSync(destination, `${destination}.bak`);
+			backups.push(`${file.to}.bak`);
+		}
 		fs.mkdirSync(path.dirname(destination), { recursive: true });
-		const contents = fs.readFileSync(path.join(payloadDir, file.from), "utf8").replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+		const contents = renderPayload(fs.readFileSync(path.join(payloadDir, file.from), "utf8"), shape, projectName);
 		fs.writeFileSync(destination, contents, "utf8");
 	}
 	const dockerfile = app.dockerfile ?? "Dockerfile";
@@ -5112,9 +5838,14 @@ async function ejectCommand(rawArgs = []) {
 	console.log(`  ${chalk.cyan(dockerfile.padEnd(26))} your image`);
 	console.log(`  ${chalk.cyan("docker-compose.custom.yml".padEnd(26))} runs it`);
 	console.log(`  ${chalk.cyan("rebase.json".padEnd(26))} runtime: custom`);
+	for (const backup of backups) console.log(`  ${chalk.cyan(backup.padEnd(26))} what was there before`);
 	console.log("");
 	console.log(chalk.yellow("  You now own CORS, auth wiring, storage and shutdown. Platform runtime"));
 	console.log(chalk.yellow("  upgrades no longer reach this project."));
+	if (!shape.collections) {
+		console.log(chalk.yellow("  This project declares no collections, so the entrypoint derives them"));
+		console.log(chalk.yellow("  from the live database, as the managed runtime did."));
+	}
 	console.log("");
 	console.log(chalk.dim(`  ${chalk.cyan("docker compose -f docker-compose.custom.yml up --build")}`));
 	console.log(chalk.dim("  docker-compose.yml is untouched — it still runs the managed shape if you go back."));
@@ -5171,19 +5902,20 @@ Build first with ${chalk.cyan("rebase build")}.
 `.trim());
 }
 async function startCommand(rawArgs = []) {
-	const args = arg({
-		"--bundle": String,
-		"--legacy": Boolean,
-		"--help": Boolean,
-		"-h": "--help"
-	}, {
-		argv: rawArgs.slice(3),
-		permissive: true
-	});
-	if (args["--help"]) {
+	if (wantsHelp(rawArgs)) {
 		printHelp$3();
 		return;
 	}
+	const { flags: args } = parseCommandArgs({
+		spec: {
+			"--bundle": String,
+			"--legacy": Boolean
+		},
+		rawArgs,
+		commandWords: 1,
+		command: "start",
+		maxPositionals: 0
+	});
 	const projectRoot = requireProjectRoot();
 	const envFile = findEnvFile(projectRoot);
 	const env = { ...process.env };
@@ -5198,7 +5930,10 @@ async function startCommand(rawArgs = []) {
 	}
 	ensureBundleDependencies(projectRoot, bundleDir);
 	console.log(`${chalk.bold("Rebase")} — starting runtime from ${chalk.cyan(path.relative(projectRoot, bundleDir))}/\n`);
-	if (envFile && fs.existsSync(envFile)) (await import("dotenv")).config({ path: envFile });
+	if (envFile && fs.existsSync(envFile)) (await import("dotenv")).config({
+		path: envFile,
+		quiet: true
+	});
 	process.env.REBASE_BUNDLE = bundleDir;
 	try {
 		const { runFromBundle } = await import("@rebasepro/server");
@@ -5286,8 +6021,50 @@ async function startWorkspaceBackend(projectRoot, env) {
 * Subcommands:
 *   reset-password — Reset a user's password
 */
+/**
+* Pick the user with exactly this email out of a search response.
+*
+* `/api/admin/users?search=` is an `ILIKE '%…%'` over email **or display
+* name**, ordered by role count descending. This used to take row `[0]` and
+* reset it, then print the email it had been *given* as confirmation — so two
+* ordinary situations ended in a successful-looking reset of somebody else's
+* account:
+*
+*   - a substring collision: `bob@example.com` also matches
+*     `robert.bob@example.com`;
+*   - a display name, which is user-controlled and accepted up to 255
+*     characters with no constraint on its content, containing an address
+*     belonging to someone else.
+*
+* The ordering makes it worse rather than better — `array_length(roles) DESC
+* NULLS LAST` puts the most privileged match first, so the account most likely
+* to be reset by mistake is an admin's.
+*
+* Returns `undefined` when nothing matched exactly, which the caller reports
+* rather than falling through to a guess. The direct-database fallback below
+* has always matched with `eq(usersTable.email, email)`; this is the same
+* definition, so the command no longer resets different accounts depending on
+* whether the backend happened to be running.
+*/
+function selectUserForEmail(payload, email) {
+	const wanted = email.trim().toLowerCase();
+	if (!wanted) return void 0;
+	const rows = Array.isArray(payload) ? payload : payload && typeof payload === "object" && Array.isArray(payload.users) ? payload.users : [];
+	for (const row of rows) {
+		if (!row || typeof row !== "object") continue;
+		const record = row;
+		const rowEmail = typeof record.email === "string" ? record.email.trim().toLowerCase() : void 0;
+		if (!rowEmail || rowEmail !== wanted) continue;
+		const id = typeof record.id === "string" ? record.id : typeof record.uid === "string" ? record.uid : void 0;
+		if (!id) continue;
+		return {
+			id,
+			email: record.email
+		};
+	}
+}
 async function authCommand(subcommand, rawArgs) {
-	if (!subcommand || subcommand === "--help") {
+	if (!subcommand || subcommand === "--help" || wantsHelp(rawArgs)) {
 		printAuthHelp();
 		return;
 	}
@@ -5302,32 +6079,58 @@ async function authCommand(subcommand, rawArgs) {
 			process.exit(1);
 	}
 }
-async function resetPassword(rawArgs) {
-	const args = arg({
-		"--email": String,
-		"--password": String,
-		"-e": "--email",
-		"-p": "--password"
-	}, {
-		argv: rawArgs.slice(4),
-		permissive: true
-	});
-	const email = args["--email"] || args._[0];
-	const newPassword = args["--password"] || args._[1];
-	if (!email) {
-		console.error(chalk.red("✗ Email is required."));
+/**
+* The flags `rebase auth reset-password` takes.
+*
+* `-p` was advertised in this command's own help and never declared here, so
+* `arg` — running permissively — pushed it into the positionals and the value
+* *after* it shifted out of reach: anyone following the help set the account's
+* password to the two-character string `-p`. Declared now, and `auth.test.ts`
+* asserts that the help and this spec list the same aliases.
+*/
+var RESET_PASSWORD_FLAGS = {
+	"--email": String,
+	"--password": String,
+	"-e": "--email",
+	"-p": "--password"
+};
+/**
+* Which account, and which password, this invocation names.
+*
+* Both may still be absent — the caller reports a missing email — but neither
+* can be a flag. `parseCommandArgs` parses the whole line strictly, so an
+* undeclared flag is an error rather than a positional. That is what stops
+* `rebase auth reset-password bob@example.com --debug` from setting Bob's
+* password to `--debug`, which is the flag the CLI itself prints after every
+* failure as the thing to re-run with.
+*
+* Exported so its tests can drive the real parser rather than a copy of it.
+*/
+function resolveResetPasswordArgs(rawArgs) {
+	const { flags, positionals } = parseCommandArgs({
+		spec: RESET_PASSWORD_FLAGS,
+		rawArgs,
+		commandWords: 2,
+		command: "auth reset-password",
+		maxPositionals: 2
+	});
+	return {
+		email: flags["--email"] || positionals[0],
+		password: flags["--password"] || positionals[1]
+	};
+}
+async function resetPassword(rawArgs) {
+	const { email, password: newPassword } = resolveResetPasswordArgs(rawArgs);
+	if (!email) {
+		console.error(chalk.red("✗ Email is required."));
 		console.log("");
 		console.log(chalk.gray("  Usage: rebase auth reset-password <email> [new-password]"));
 		console.log(chalk.gray("         rebase auth reset-password --email user@example.com --password NewPass123!"));
 		process.exit(1);
 	}
 	const projectRoot = requireProjectRoot();
-	let envServiceKey;
 	const envFile = findEnvFile(projectRoot);
-	if (envFile && fs.existsSync(envFile)) try {
-		const match = fs.readFileSync(envFile, "utf8").match(/^\s*REBASE_SERVICE_KEY\s*=\s*['"]?(.*?)['"]?\s*$/m);
-		if (match && match[1]) envServiceKey = match[1];
-	} catch {}
+	const envServiceKey = readEnvFile(projectRoot).REBASE_SERVICE_KEY;
 	let baseUrl = process.env.REBASE_BASE_URL;
 	let serviceKey = process.env.REBASE_SERVICE_KEY || envServiceKey;
 	const statePath = path.join(projectRoot, ".rebase", "state.json");
@@ -5347,7 +6150,7 @@ async function resetPassword(rawArgs) {
 		try {
 			const finalPass = newPassword || "NewPassword123!";
 			const cleanBaseUrl = baseUrl.replace(/\/+$/, "");
-			const searchUrl = `${cleanBaseUrl}/api/admin/users?search=${encodeURIComponent(email)}&limit=1`;
+			const searchUrl = `${cleanBaseUrl}/api/admin/users?search=${encodeURIComponent(email)}&limit=50`;
 			const searchRes = await fetch(searchUrl, { headers: {
 				"Authorization": `Bearer ${serviceKey}`,
 				"Accept": "application/json"
@@ -5355,18 +6158,9 @@ async function resetPassword(rawArgs) {
 			if (!searchRes.ok) throw new Error(`Failed to list users: ${searchRes.statusText}`);
 			const searchData = await searchRes.json();
 			if (!searchData || typeof searchData !== "object") throw new Error("Invalid response format from user search API.");
-			let userId;
-			if (Array.isArray(searchData)) {
-				const firstUser = searchData[0];
-				if (firstUser && typeof firstUser === "object" && "id" in firstUser && typeof firstUser.id === "string") userId = firstUser.id;
-				else if (firstUser && typeof firstUser === "object" && "uid" in firstUser && typeof firstUser.uid === "string") userId = firstUser.uid;
-			} else if ("users" in searchData && Array.isArray(searchData.users)) {
-				const firstUser = searchData.users[0];
-				if (firstUser && typeof firstUser === "object" && "id" in firstUser && typeof firstUser.id === "string") userId = firstUser.id;
-				else if (firstUser && typeof firstUser === "object" && "uid" in firstUser && typeof firstUser.uid === "string") userId = firstUser.uid;
-			}
-			if (!userId) throw new Error(`User not found with email: ${email}`);
-			const resetUrl = `${cleanBaseUrl}/api/admin/users/${userId}/reset-password`;
+			const matched = selectUserForEmail(searchData, email);
+			if (!matched) throw new Error(`No user has the email ${email}.`);
+			const resetUrl = `${cleanBaseUrl}/api/admin/users/${matched.id}/reset-password`;
 			const resetRes = await fetch(resetUrl, {
 				method: "POST",
 				headers: {
@@ -5383,7 +6177,7 @@ async function resetPassword(rawArgs) {
 			console.log("API reset successful.");
 			console.log(chalk.bold("  🔑 Rebase Auth — Reset Password (via API)"));
 			console.log("");
-			console.log(`  ${chalk.gray("Email:")} ${email}`);
+			console.log(`  ${chalk.gray("Email:")} ${matched.email}`);
 			console.log(`  ${chalk.gray("Password:")} ${finalPass}`);
 			console.log("");
 			return;
@@ -5413,7 +6207,7 @@ import * as dotenv from "dotenv";
 import path from "path";
 import fs from "fs";
 
-dotenv.config({ path: process.env.REBASE_ENV_FILE_PATH });
+dotenv.config({ path: process.env.REBASE_ENV_FILE_PATH, quiet: true });
 
 const email = process.env.REBASE_RESET_EMAIL!;
 const newPassword = process.env.REBASE_RESET_PASSWORD!;
@@ -5451,10 +6245,12 @@ async function resetPassword() {
     if (result.length > 0) {
         console.log("✅ Password reset for: " + result[0].email);
         ${!newPassword ? "console.log(\"   New password: \" + newPassword);" : ""}
-    } else {
-        console.log("✗ User not found: " + email);
+        process.exit(0);
     }
-    process.exit(0);
+    // Nothing was updated, so nothing was reset. Exiting 0 here reported
+    // success for a no-op, which is what a script would have believed.
+    console.error("✗ User not found: " + email);
+    process.exit(1);
 }
 
 resetPassword().catch(console.error);
@@ -5472,11 +6268,20 @@ resetPassword().catch(console.error);
 			stdio: "inherit",
 			env
 		});
+		const cleanup = () => {
+			try {
+				fs.unlinkSync(tmpScriptPath);
+			} catch {}
+		};
 		return new Promise((resolve) => {
+			child.on("error", (err) => {
+				cleanup();
+				console.error(chalk.red("✗ Could not run the reset script."));
+				console.error(chalk.gray(`  ${err.message}`));
+				process.exit(1);
+			});
 			child.on("close", (code) => {
-				try {
-					fs.unlinkSync(tmpScriptPath);
-				} catch {}
+				cleanup();
 				if (code !== 0) process.exit(code ?? 1);
 				resolve();
 			});
@@ -5514,7 +6319,34 @@ ${chalk.green.bold("Examples")}
 * Detects three-way schema drift between collection definitions,
 * the generated Drizzle schema, and the live PostgreSQL database.
 */
+/**
+* `--help` is answered before the project guard, not after.
+*
+* `doctor` declared no `--help` at all, so the flag fell through to the command
+* body and hit `requireProjectRoot()` — and `rebase doctor --help` outside a
+* project answered "✗ Could not find a Rebase project root." Asking a command
+* what it does is the one question that cannot require being somewhere
+* particular to ask.
+*/
+function printDoctorHelp() {
+	console.log(`
+${chalk.bold("rebase doctor")} — Detect drift between collections, schema and database
+
+${chalk.green.bold("Usage")}
+  rebase doctor
+
+Compares the collections you declare, the generated Drizzle schema, and the
+tables that actually exist, then reports what disagrees and how to reconcile it.
+
+Run from inside a Rebase project — it reads the project's collections and
+connects to its database.
+`);
+}
 async function doctorCommand(rawArgs) {
+	if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+		printDoctorHelp();
+		return;
+	}
 	const projectRoot = requireProjectRoot();
 	const backendDir = requireBackendDir(projectRoot);
 	const activePlugin = getActiveBackendPlugin(backendDir);
@@ -5555,12 +6387,21 @@ async function doctorCommand(rawArgs) {
 //#endregion
 //#region src/commands/skills.ts
 var require = createRequire(import.meta.url);
-/** Supported agent environments and their target directories. */
+/**
+* Supported agent environments and their target directories.
+*
+* `flatLayout` says where the installed rule file sits relative to the skill's
+* own assets. A subdirectory layout writes `<skill>/SKILL.md`, so a link the
+* skill spells `references/x.md` resolves as written; a flat layout writes
+* `<skill>.md` one level up, so those links have to be re-pointed at the
+* per-skill asset directory. See `rewriteAssetLinks`.
+*/
 var AGENTS = {
 	cursor: {
 		label: "Cursor",
 		detectDir: ".cursor",
 		targetDir: ".cursor/rules",
+		flatLayout: true,
 		/** Cursor uses .mdc files (Markdown with Context). */
 		transformFile: (skillName, content) => ({
 			fileName: `${skillName}.mdc`,
@@ -5571,6 +6412,7 @@ var AGENTS = {
 		label: "Claude Code",
 		detectDir: ".claude",
 		targetDir: ".claude/skills",
+		flatLayout: false,
 		/** Claude Code uses the standard SKILL.md format in subdirectories. */
 		transformFile: (skillName, content) => ({
 			fileName: path.join(skillName, "SKILL.md"),
@@ -5581,6 +6423,7 @@ var AGENTS = {
 		label: "Windsurf",
 		detectDir: ".windsurf",
 		targetDir: ".windsurf/rules",
+		flatLayout: true,
 		/** Windsurf uses plain .md files. */
 		transformFile: (skillName, content) => ({
 			fileName: `${skillName}.md`,
@@ -5591,6 +6434,7 @@ var AGENTS = {
 		label: "Gemini CLI / Antigravity",
 		detectDir: ".agents",
 		targetDir: ".agents/skills",
+		flatLayout: false,
 		/** Gemini uses the standard SKILL.md format in subdirectories. */
 		transformFile: (skillName, content) => ({
 			fileName: path.join(skillName, "SKILL.md"),
@@ -5609,21 +6453,65 @@ function getSkillsSourceDir() {
 	if (!fs.existsSync(skillsDir)) throw new Error(`Skills directory not found at ${skillsDir}. Make sure @rebasepro/agent-skills is installed.`);
 	return skillsDir;
 }
-/** Read all skill directories and return their names + content. */
+/**
+* Everything a skill ships alongside its SKILL.md — the `references/` tree the
+* Agent Skills format uses for progressive disclosure.
+*
+* These used to be dropped on install, because the installer read exactly
+* `<skill>/SKILL.md` and nothing else. That left `rebase-design-language`
+* telling the agent three separate times to read `references/view-patterns.md`
+* — 379 lines of view skeletons — in a project where the file had never
+* landed, and the instruction it carries is "extend an existing pattern; do not
+* invent a layout".
+*/
+function loadSkillAssets(skillDir) {
+	const found = [];
+	const walk = (dir, prefix) => {
+		for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+			if (entry.name.startsWith(".")) continue;
+			const rel = prefix ? path.join(prefix, entry.name) : entry.name;
+			if (entry.isDirectory()) walk(path.join(dir, entry.name), rel);
+			else if (rel !== "SKILL.md") found.push(rel);
+		}
+	};
+	walk(skillDir, "");
+	return found.sort();
+}
+/** Read all skill directories and return their names, content and assets. */
 function loadSkills(skillsDir) {
 	const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
 	const skills = [];
 	for (const entry of entries) {
 		if (!entry.isDirectory()) continue;
-		const skillMdPath = path.join(skillsDir, entry.name, "SKILL.md");
+		const skillDir = path.join(skillsDir, entry.name);
+		const skillMdPath = path.join(skillDir, "SKILL.md");
 		if (!fs.existsSync(skillMdPath)) continue;
 		skills.push({
 			name: entry.name,
-			content: fs.readFileSync(skillMdPath, "utf-8")
+			dir: skillDir,
+			content: fs.readFileSync(skillMdPath, "utf-8"),
+			assets: loadSkillAssets(skillDir)
 		});
 	}
 	return skills;
 }
+/**
+* Re-point a skill's own asset links at the per-skill subdirectory, for the
+* agents whose rule file does not live in it.
+*
+* Only paths that name a file the skill actually ships are rewritten, and only
+* where they start a path segment — so prose that happens to contain the same
+* words is left alone.
+*/
+function rewriteAssetLinks(content, assets, skillName) {
+	let out = content;
+	for (const asset of assets) {
+		const posix = asset.split(path.sep).join("/");
+		const escaped = posix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		out = out.replace(new RegExp(`(?<![\\w/.-])${escaped}`, "g"), `${skillName}/${posix}`);
+	}
+	return out;
+}
 /** Detect which agent environments already exist in the project. */
 function detectAgents(projectDir) {
 	const detected = [];
@@ -5636,16 +6524,31 @@ function installForAgent(agentKey, skills, projectDir) {
 	const targetBase = path.join(projectDir, agent.targetDir);
 	fs.mkdirSync(targetBase, { recursive: true });
 	let count = 0;
+	let assetCount = 0;
 	for (const skill of skills) {
-		const { fileName, content } = agent.transformFile(skill.name, skill.content);
+		const body = agent.flatLayout ? rewriteAssetLinks(skill.content, skill.assets, skill.name) : skill.content;
+		const { fileName, content } = agent.transformFile(skill.name, body);
 		const targetPath = path.join(targetBase, fileName);
 		fs.mkdirSync(path.dirname(targetPath), { recursive: true });
 		fs.writeFileSync(targetPath, content, "utf-8");
 		count++;
+		for (const asset of skill.assets) {
+			const assetTarget = path.join(targetBase, skill.name, asset);
+			fs.mkdirSync(path.dirname(assetTarget), { recursive: true });
+			fs.copyFileSync(path.join(skill.dir, asset), assetTarget);
+			assetCount++;
+		}
 	}
-	return count;
+	return {
+		skills: count,
+		assets: assetCount
+	};
 }
 async function skillsCommand(subcommand, rawArgs) {
+	if (wantsHelp(rawArgs)) {
+		printSkillsHelp();
+		return;
+	}
 	switch (subcommand) {
 		case "install":
 			await skillsInstall(rawArgs);
@@ -5663,7 +6566,8 @@ async function skillsCommand(subcommand, rawArgs) {
 }
 /**
 * Agents named explicitly on the command line, e.g. `--agent claude --agent cursor`
-* (also accepts a comma-separated list). Returns null when none were given.
+* (also accepts a comma-separated list, and `all`). Returns null when none were
+* given.
 */
 function parseAgentFlags(rawArgs) {
 	const requested = [];
@@ -5673,6 +6577,7 @@ function parseAgentFlags(rawArgs) {
 		if (value && !value.startsWith("-")) requested.push(...value.split(",").map((v) => v.trim()).filter(Boolean));
 	}
 	if (requested.length === 0) return null;
+	if (requested.includes("all")) return Object.keys(AGENTS);
 	const valid = Object.keys(AGENTS);
 	const unknown = requested.filter((a) => !valid.includes(a));
 	if (unknown.length > 0) {
@@ -5700,6 +6605,7 @@ async function skillsInstall(rawArgs = []) {
 		if (!process.stdin.isTTY) {
 			console.error(chalk.red("Cannot prompt: this is a non-interactive terminal (no TTY)."));
 			console.error(chalk.yellow(`  Name the agents explicitly, e.g. rebase skills install --agent ${Object.keys(AGENTS)[0]}`));
+			console.error(chalk.yellow("  Or install for every supported agent:  rebase skills install --agent all"));
 			console.error(chalk.gray(`  Available: ${Object.keys(AGENTS).join(", ")}`));
 			process.exit(1);
 		}
@@ -5725,9 +6631,10 @@ async function skillsInstall(rawArgs = []) {
 	console.log("");
 	for (const agentKey of agents) {
 		const agent = AGENTS[agentKey];
-		const count = installForAgent(agentKey, skills, projectDir);
+		const { skills: count, assets } = installForAgent(agentKey, skills, projectDir);
 		const shown = path.relative(process.cwd(), path.join(projectDir, agent.targetDir)) || agent.targetDir;
-		console.log(`  ${chalk.green("✓")} ${chalk.bold(agent.label)} — ${count} skills installed to ${chalk.gray(shown)}`);
+		const withAssets = assets > 0 ? ` (+ ${assets} reference file${assets === 1 ? "" : "s"})` : "";
+		console.log(`  ${chalk.green("✓")} ${chalk.bold(agent.label)} — ${count} skills installed${withAssets} to ${chalk.gray(shown)}`);
 	}
 	console.log("");
 	console.log(chalk.gray("  Skills are project-local. Commit them to share with your team."));
@@ -5747,13 +6654,16 @@ ${chalk.green.bold("Subcommands")}
 
 ${chalk.green.bold("Options")}
   ${chalk.blue("--agent, -a")}   Agent(s) to install for, skipping detection and the prompt.
-                Repeat the flag or pass a comma-separated list.
-                Available: ${Object.keys(AGENTS).join(", ")}
+                Repeat the flag or pass a comma-separated list, or ${chalk.bold("all")}.
+                Required without a TTY: a scaffolded project carries a marker
+                file for every agent, so detection cannot pick one for you.
+                Available: ${Object.keys(AGENTS).join(", ")}, all
 
 ${chalk.green.bold("Examples")}
   ${chalk.cyan("rebase skills install")}
   ${chalk.cyan("rebase skills install --agent claude")}
   ${chalk.cyan("rebase skills install --agent claude,cursor")}
+  ${chalk.cyan("rebase skills install --agent all")}   ${chalk.gray("# scripted / CI")}
 `);
 }
 //#endregion
@@ -5766,25 +6676,13 @@ ${chalk.green.bold("Examples")}
 *   create  — Create a new API key
 *   revoke  — Revoke an existing API key
 */
-function loadEnv(projectRoot) {
-	const envFile = findEnvFile(projectRoot);
-	const env = {};
-	if (envFile && fs.existsSync(envFile)) {
-		const content = fs.readFileSync(envFile, "utf-8");
-		for (const line of content.split("\n")) {
-			const trimmed = line.trim();
-			if (!trimmed || trimmed.startsWith("#")) continue;
-			const idx = trimmed.indexOf("=");
-			if (idx > 0) {
-				const key = trimmed.slice(0, idx).trim();
-				let value = trimmed.slice(idx + 1).trim();
-				if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
-				env[key] = value;
-			}
-		}
-	}
-	return env;
-}
+/**
+* Was a hand-rolled `indexOf("=")` loop. It keyed `export KEY=value` as
+* `export KEY` and carried a trailing `# comment` into the value — so a key
+* that was present read as absent, or reached an `Authorization` header with a
+* comment attached and came back 401. See `readEnvFile`.
+*/
+var loadEnv = readEnvFile;
 function resolveBaseUrl(env, projectRoot) {
 	if (env.REBASE_BASE_URL) return env.REBASE_BASE_URL;
 	if (projectRoot) try {
@@ -5797,7 +6695,7 @@ function resolveBaseUrl(env, projectRoot) {
 	return `http://localhost:${env.PORT || env.REBASE_PORT || "3001"}`;
 }
 async function apiKeysCommand(subcommand, rawArgs) {
-	if (!subcommand || subcommand === "--help") {
+	if (!subcommand || subcommand === "--help" || wantsHelp(rawArgs)) {
 		printApiKeysHelp();
 		return;
 	}
@@ -5859,20 +6757,43 @@ async function listKeys(_rawArgs) {
 		process.exit(1);
 	}
 }
-async function createKey(rawArgs) {
-	const args = arg({
-		"--name": String,
-		"--permissions": String,
-		"--full-access": Boolean,
-		"--admin": Boolean,
-		"--rate-limit": Number,
-		"--expires": String,
-		"-n": "--name"
-	}, {
-		argv: rawArgs.slice(4),
-		permissive: true
+/** The flags `rebase api-keys create` takes. */
+var CREATE_KEY_FLAGS = {
+	"--name": String,
+	"--permissions": String,
+	"--full-access": Boolean,
+	"--admin": Boolean,
+	"--rate-limit": Number,
+	"--expires": String,
+	"-n": "--name"
+};
+/**
+* What this invocation asks to be created.
+*
+* The name may be given either way — `--name "My Key"` or as the single
+* positional — and under the old permissive parse an undeclared flag became
+* that positional: `rebase api-keys create --debug --full-access` created a
+* key called `--debug` with read/write/delete on every collection, and
+* `--debug` is what the CLI prints after every failure as the thing to re-run
+* with. Strict parsing makes the flag an error instead of a name.
+*
+* Exported so its tests can drive the real parser rather than a copy of it.
+*/
+function resolveCreateKeyArgs(rawArgs) {
+	const { flags, positionals } = parseCommandArgs({
+		spec: CREATE_KEY_FLAGS,
+		rawArgs,
+		commandWords: 2,
+		command: "api-keys create",
+		maxPositionals: 1
 	});
-	const name = args["--name"] || args._[0];
+	return {
+		flags,
+		name: flags["--name"] || positionals[0]
+	};
+}
+async function createKey(rawArgs) {
+	const { flags: args, name } = resolveCreateKeyArgs(rawArgs);
 	const permissionsRaw = args["--permissions"];
 	if (!name) {
 		console.error(chalk.red("✗ Name is required."));
@@ -5973,12 +6894,30 @@ async function createKey(rawArgs) {
 		process.exit(1);
 	}
 }
-async function revokeKey(rawArgs) {
-	const args = arg({ "--id": String }, {
-		argv: rawArgs.slice(4),
-		permissive: true
+/** The flags `rebase api-keys revoke` takes. */
+var REVOKE_KEY_FLAGS = { "--id": String };
+/**
+* Which key this invocation names.
+*
+* The id is a positional, so the permissive parse handed one straight to the
+* DELETE: `rebase api-keys revoke --foo` sent
+* `DELETE /api/admin/api-keys/--foo`, and `rebase --debug api-keys revoke <id>`
+* shifted the words along and revoked the key named `revoke`.
+*
+* Exported so its tests can drive the real parser rather than a copy of it.
+*/
+function resolveRevokeKeyArgs(rawArgs) {
+	const { flags, positionals } = parseCommandArgs({
+		spec: REVOKE_KEY_FLAGS,
+		rawArgs,
+		commandWords: 2,
+		command: "api-keys revoke",
+		maxPositionals: 1
 	});
-	const id = args["--id"] || args._[0];
+	return { id: flags["--id"] || positionals[0] };
+}
+async function revokeKey(rawArgs) {
+	const { id } = resolveRevokeKeyArgs(rawArgs);
 	if (!id) {
 		console.error(chalk.red("✗ Key ID is required."));
 		console.log("");
@@ -6055,7 +6994,12 @@ ${chalk.green.bold("Examples")}
 * a documentation comment that quietly fell out of date two releases ago.
 */
 async function telemetryCommand(rawArgs) {
-	switch (rawArgs.slice(3).filter((a) => !a.startsWith("-"))[0]) {
+	const subcommand = rawArgs.slice(3).filter((a) => !a.startsWith("-"))[0];
+	if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+		printHelp$2();
+		return;
+	}
+	switch (subcommand) {
 		case "status":
 		case void 0:
 			printStatus();
@@ -6154,16 +7098,16 @@ async function loginCommand(rawArgs) {
 	const args = arg({
 		"--email": String,
 		"--password": String,
-		"-e": "--email",
-		"-p": "--password"
+		"-e": "--email"
 	}, {
 		argv: rawArgs.slice(3),
 		permissive: true
 	});
 	const url = resolveCloudUrl(rawArgs);
-	console.log("");
-	console.log(`  Signing in to ${chalk.cyan(url)}`);
-	console.log("");
+	noteBlank();
+	note(`Signing in to ${chalk.cyan(url)}`);
+	noteBlank();
+	if (!args["--email"] || !args["--password"]) requireInteractive("credentials", "--email and --password");
 	const prompts = [];
 	if (!args["--email"]) prompts.push({
 		type: "input",
@@ -6189,14 +7133,21 @@ async function loginCommand(rawArgs) {
 			if (orgs.data.length === 1 && !getContextOrg(url)) setContextOrg(url, String(orgs.data[0].id));
 		} catch {}
 		success(`Logged in as ${chalk.bold(user.email ?? email)}`);
-		keyValues([
-			["Host", url],
-			["User", user.email ?? void 0],
-			["Active org", getContextOrg(url)]
-		]);
-		console.log("");
+		emit(() => {
+			keyValues([
+				["Host", url],
+				["User", user.email ?? void 0],
+				["Active org", getContextOrg(url)]
+			]);
+			console.log("");
+		}, {
+			success: true,
+			host: url,
+			user: user.email ?? null,
+			activeOrg: getContextOrg(url) ?? null
+		});
 	} catch (e) {
-		if (e?.status === 401) fail("Invalid email or password.");
+		if (e?.status === 401) fail("Invalid email or password.", void 0, "invalid_credentials");
 		reportError(e, "Login failed");
 	}
 }
@@ -6204,34 +7155,60 @@ async function logoutCommand(rawArgs) {
 	const url = resolveCloudUrl(rawArgs);
 	const client = createCloudClient(url);
 	if (!client.auth.getSession()) {
-		console.log("");
-		console.log(chalk.gray(`  Not logged in to ${url}.`));
-		console.log("");
+		emit(() => {
+			console.log("");
+			console.log(chalk.gray(`  Not logged in to ${url}.`));
+			console.log("");
+		}, {
+			success: true,
+			host: url,
+			wasLoggedIn: false
+		});
 		return;
 	}
 	try {
 		await client.auth.signOut();
 	} catch {}
 	success(`Logged out of ${url}`);
+	emit(() => {}, {
+		success: true,
+		host: url,
+		wasLoggedIn: true
+	});
 }
 async function whoamiCommand(rawArgs) {
 	const { client, url } = await requireClient(rawArgs);
 	try {
 		const user = await client.auth.getUser();
-		if (!user) fail("Session is no longer valid.", "Run `rebase cloud login` again.");
+		if (!user) fail("Session is no longer valid.", "Run `rebase cloud login` again.", "session_invalid");
 		const link = readLink();
-		console.log("");
-		console.log(chalk.bold("  🔐 Rebase Cloud session"));
-		console.log("");
-		keyValues([
-			["Host", url],
-			["User", user.email ?? void 0],
-			["User ID", user.uid],
-			["Roles", user.roles?.length ? user.roles.join(", ") : void 0],
-			["Active org", getContextOrg(url)],
-			["Linked project", link ? `${link.projectName ?? ""} (${link.projectId})`.trim() : void 0]
-		]);
-		console.log("");
+		emit(() => {
+			console.log("");
+			console.log(chalk.bold("  🔐 Rebase Cloud session"));
+			console.log("");
+			keyValues([
+				["Host", url],
+				["User", user.email ?? void 0],
+				["User ID", user.uid],
+				["Roles", user.roles?.length ? user.roles.join(", ") : void 0],
+				["Active org", getContextOrg(url)],
+				["Linked project", link ? `${link.projectName ?? ""} (${link.projectId})`.trim() : void 0]
+			]);
+			console.log("");
+		}, {
+			host: url,
+			user: {
+				email: user.email ?? null,
+				uid: user.uid,
+				roles: user.roles ?? []
+			},
+			activeOrg: getContextOrg(url) ?? null,
+			linkedProject: link ? {
+				id: link.projectId,
+				name: link.projectName ?? null,
+				slug: link.slug ?? null
+			} : null
+		});
 	} catch (e) {
 		reportError(e, "Failed to fetch session");
 	}
@@ -6261,10 +7238,10 @@ async function linkDirect(target, rawArgs) {
 	try {
 		base = new URL(target);
 	} catch {
-		fail(`"${target}" is not a valid URL.`);
+		fail(`"${target}" is not a valid URL.`, void 0, "invalid_url");
 		return;
 	}
-	if (base.protocol !== "http:" && base.protocol !== "https:") fail("A project URL must be http or https.");
+	if (base.protocol !== "http:" && base.protocol !== "https:") fail("A project URL must be http or https.", void 0, "invalid_url");
 	const apiUrl = base.toString().replace(/\/+$/, "");
 	const probe = `${apiUrl}/api/meta/schema-version`;
 	let reachable = false;
@@ -6276,11 +7253,7 @@ async function linkDirect(target, rawArgs) {
 	} catch (err) {
 		detail = err instanceof Error ? err.message : String(err);
 	}
-	if (!reachable) {
-		console.log(chalk.yellow(`⚠ Could not reach ${probe}${detail ? ` (${detail})` : ""}.`));
-		console.log(chalk.dim("  Linking anyway — the server may not be running yet."));
-		console.log(chalk.dim("  It must be a Rebase backend of version 0.11 or newer."));
-	}
+	if (!reachable) warn(`Could not reach ${probe}${detail ? ` (${detail})` : ""}.`, "Linking anyway — the server may not be running yet. It must be a Rebase backend of version 0.11 or newer.");
 	writeLink({
 		url: apiUrl,
 		projectId: "",
@@ -6289,9 +7262,18 @@ async function linkDirect(target, rawArgs) {
 		projectName: base.host
 	});
 	success(`Linked to ${apiUrl}`);
-	console.log(chalk.dim(`  Written to ${projectLinkPath()}`));
-	console.log("");
-	console.log(`Next: ${chalk.cyan("rebase generate-sdk --from link")}`);
+	emit(() => {
+		note(chalk.dim(`Written to ${projectLinkPath()}`));
+		noteBlank();
+		note(`Next: ${chalk.cyan("rebase generate-sdk --from link")}`, "");
+	}, {
+		success: true,
+		mode: "direct",
+		apiUrl,
+		reachable,
+		projectName: base.host,
+		linkPath: projectLinkPath()
+	});
 }
 async function linkCommand(rawArgs) {
 	const args = arg({
@@ -6312,14 +7294,15 @@ async function linkCommand(rawArgs) {
 		if (args["--project"]) {
 			const projectId = await resolveProjectRef(args["--project"], client);
 			project = await client.data.collection("projects").findById(projectId);
-			if (!project) fail(`Project ${args["--project"]} not found.`);
+			if (!project) fail(`Project ${args["--project"]} not found.`, void 0, "project_not_found");
 		} else {
+			requireInteractive("a project to link", "--project <slug>");
 			const org = getContextOrg(url);
 			const projects = (await client.data.collection("projects").find({
 				where: org ? { organization: ["==", org] } : void 0,
 				limit: 100
 			})).data;
-			if (projects.length === 0) fail("No projects found for your account.", `Create one with ${chalk.bold("rebase cloud projects create")}.`);
+			if (projects.length === 0) fail("No projects found for your account.", `Create one with ${chalk.bold("rebase cloud projects create")}.`, "no_projects");
 			const { picked } = await inquirer.prompt([{
 				type: "select",
 				name: "picked",
@@ -6331,39 +7314,63 @@ async function linkCommand(rawArgs) {
 			}]);
 			project = picked;
 		}
-		if (!project) fail("No project selected.");
+		if (!project) fail("No project selected.", void 0, "no_project");
+		const orgId = project.organization !== void 0 ? String(project.organization) : void 0;
 		writeLink({
 			url,
 			projectId: String(project.id),
 			slug: project.subdomain,
 			projectName: project.name,
-			orgId: project.organization !== void 0 ? String(project.organization) : void 0
+			orgId
 		});
 		success(`Linked to ${chalk.bold(project.name ?? project.subdomain ?? "")}`);
-		console.log(chalk.gray(`  Wrote ${projectLinkPath()}`));
-		console.log("");
+		emit(() => {
+			note(chalk.gray(`Wrote ${projectLinkPath()}`));
+			noteBlank();
+		}, {
+			success: true,
+			mode: "cloud",
+			host: url,
+			projectId: String(project.id),
+			slug: project.subdomain ?? null,
+			projectName: project.name ?? null,
+			org: orgId ?? null,
+			linkPath: projectLinkPath()
+		});
 	} catch (e) {
 		reportError(e, "Failed to link project");
 	}
 }
 function unlinkCommand() {
 	if (!readLink()) {
-		console.log("");
-		console.log(chalk.gray("  This directory is not linked to a cloud project."));
-		console.log("");
+		emit(() => {
+			console.log("");
+			console.log(chalk.gray("  This directory is not linked to a cloud project."));
+			console.log("");
+		}, {
+			success: true,
+			unlinked: false,
+			linkPath: projectLinkPath()
+		});
 		return;
 	}
 	removeLink();
 	success("Unlinked from cloud project");
+	emit(() => {}, {
+		success: true,
+		unlinked: true,
+		linkPath: projectLinkPath()
+	});
 }
 async function selectOrgCommand(rawArgs) {
 	const target = rawArgs.slice(3).filter((a) => !a.startsWith("-"))[1];
 	const { client, url } = await requireClient(rawArgs);
 	try {
 		const orgs = (await client.data.collection("organizations").find({ limit: 100 })).data;
-		if (orgs.length === 0) fail("You are not a member of any organization.");
+		if (orgs.length === 0) fail("You are not a member of any organization.", void 0, "no_orgs");
 		let chosen = target ? orgs.find((o) => String(o.id) === target || o.slug === target) : void 0;
 		if (!chosen && !target) {
+			requireInteractive("an organization", "rebase cloud use <org-id|slug>");
 			const { picked } = await inquirer.prompt([{
 				type: "select",
 				name: "picked",
@@ -6375,9 +7382,18 @@ async function selectOrgCommand(rawArgs) {
 			}]);
 			chosen = picked;
 		}
-		if (!chosen) fail(`Organization "${target}" not found.`);
+		if (!chosen) fail(`Organization "${target}" not found.`, void 0, "org_not_found");
 		setContextOrg(url, String(chosen.id));
 		success(`Active organization set to ${chalk.bold(chosen.name ?? chosen.id)}`);
+		emit(() => {}, {
+			success: true,
+			host: url,
+			org: {
+				id: String(chosen.id),
+				name: chosen.name ?? null,
+				slug: chosen.slug ?? null
+			}
+		});
 	} catch (e) {
 		reportError(e, "Failed to set organization");
 	}
@@ -6386,7 +7402,12 @@ async function selectOrgCommand(rawArgs) {
 function openCommand(rawArgs) {
 	const url = resolveCloudUrl(rawArgs);
 	const link = readLink();
-	openUrl(link ? `${url}/projects/${link.projectId}` : url);
+	const target = link ? `${url}/projects/${link.projectId}` : url;
+	openUrl(target);
+	emit(() => {}, {
+		url: target,
+		projectId: link?.projectId ?? null
+	});
 }
 //#endregion
 //#region src/commands/cloud/projects.ts
@@ -6402,21 +7423,34 @@ async function listProjects(rawArgs) {
 			orderBy: ["name", "asc"],
 			limit: 100
 		}).then((res) => res.data), fetchTenantBaseDomain(client, url)]);
-		console.log("");
-		console.log(chalk.bold("  📦 Projects") + (org ? chalk.gray(`  (org ${org})`) : ""));
-		console.log("");
-		if (projects.length === 0) {
-			console.log(chalk.gray("  No projects yet. Create one with `rebase cloud projects create`."));
-			console.log("");
-			return;
-		}
 		const linkedId = readLink()?.projectId;
-		for (const p of projects) {
-			const marker = String(p.id) === linkedId ? chalk.green(" ●") : "  ";
-			console.log(`${marker}${chalk.bold(p.name ?? "(unnamed)")} ${chalk.gray(`[${p.subdomain ?? p.id}]`)} ${colorStatus(p.status)}`);
-			console.log(`    ${chalk.gray(projectHost(p, baseDomain) ?? "—")}${p.provider ? chalk.gray(`  ·  ${p.provider}`) : ""}`);
-		}
-		console.log("");
+		emit(() => {
+			console.log("");
+			console.log(chalk.bold("  📦 Projects") + (org ? chalk.gray(`  (org ${org})`) : ""));
+			console.log("");
+			if (projects.length === 0) {
+				console.log(chalk.gray("  No projects yet. Create one with `rebase cloud projects create`."));
+				console.log("");
+				return;
+			}
+			for (const p of projects) {
+				const marker = String(p.id) === linkedId ? chalk.green(" ●") : "  ";
+				console.log(`${marker}${chalk.bold(p.name ?? "(unnamed)")} ${chalk.gray(`[${p.subdomain ?? p.id}]`)} ${colorStatus(p.status)}`);
+				console.log(`    ${chalk.gray(projectHost(p, baseDomain) ?? "—")}${p.provider ? chalk.gray(`  ·  ${p.provider}`) : ""}`);
+			}
+			console.log("");
+		}, {
+			org: org ?? null,
+			projects: projects.map((p) => ({
+				id: String(p.id),
+				name: p.name ?? null,
+				slug: p.subdomain ?? null,
+				host: projectHost(p, baseDomain) ?? null,
+				status: p.status ?? null,
+				provider: p.provider ?? null,
+				linked: String(p.id) === linkedId
+			}))
+		});
 	} catch (e) {
 		reportError(e, "Failed to list projects");
 	}
@@ -6483,28 +7517,33 @@ function chooseRequestedTarget(requested, targets) {
 }
 async function resolveRequestedTarget(client, url, requested) {
 	const chosen = chooseRequestedTarget(requested, await fetchDeployTargets(client, url));
-	if (!chosen) fail("This control plane has no deploy targets configured.", `Register a cluster, or pass ${chalk.bold("--provider")} and ${chalk.bold("--region")} to record one anyway.`);
+	if (!chosen) fail("This control plane has no deploy targets configured.", `Register a cluster, or pass ${chalk.bold("--provider")} and ${chalk.bold("--region")} to record one anyway.`, "no_deploy_targets");
 	return chosen;
 }
+/** The flags `rebase cloud projects create` takes. */
+var CREATE_PROJECT_FLAGS = {
+	"--name": String,
+	"--subdomain": String,
+	"--repo": String,
+	"--branch": String,
+	"--provider": String,
+	"--region": String,
+	"--vm-size": String,
+	"--org": String,
+	"--link": Boolean,
+	"-n": "--name"
+};
 async function createProject(rawArgs) {
-	const args = arg({
-		"--name": String,
-		"--subdomain": String,
-		"--repo": String,
-		"--branch": String,
-		"--provider": String,
-		"--region": String,
-		"--vm-size": String,
-		"--org": String,
-		"--link": Boolean,
-		"-n": "--name"
-	}, {
-		argv: rawArgs.slice(4),
-		permissive: true
+	const { flags: args } = parseCloudArgs({
+		spec: CREATE_PROJECT_FLAGS,
+		rawArgs,
+		commandWords: 3,
+		command: "cloud projects create",
+		maxPositionals: 0
 	});
 	const { client, url } = await requireClient(rawArgs);
 	const org = args["--org"] || getContextOrg(url);
-	if (!org) fail("No organization selected.", `Pass ${chalk.bold("--org <id>")} or run ${chalk.bold("rebase cloud use")}.`);
+	if (!org) fail("No organization selected.", `Pass ${chalk.bold("--org <id>")} or run ${chalk.bold("rebase cloud use")}.`, "no_org");
 	const prompts = [];
 	if (!args["--name"]) prompts.push({
 		type: "input",
@@ -6526,14 +7565,14 @@ async function createProject(rawArgs) {
 	const defaults = providerDefaults(provider);
 	const region = (args["--region"] || target.region || defaults.region).trim();
 	const vmSize = (args["--vm-size"] || defaults.vmSize).trim();
-	if (!name || !subdomain) fail("Name and subdomain are required.");
+	if (!name || !subdomain) fail("Name and subdomain are required.", `Pass ${chalk.bold("--name <name>")} and ${chalk.bold("--subdomain <slug>")}.`, "input_required");
 	try {
 		const check = await client.functions.invoke("check-subdomain", { subdomain });
-		if (!check.available) fail(`Subdomain "${subdomain}" is not available${check.reason ? ` (${check.reason})` : ""}.`);
+		if (!check.available) fail(`Subdomain "${subdomain}" is not available${check.reason ? ` (${check.reason})` : ""}.`, void 0, "subdomain_unavailable");
 	} catch {}
 	try {
 		const user = await client.auth.getUser();
-		if (!user) fail("Session is no longer valid.", "Run `rebase cloud login` again.");
+		if (!user) fail("Session is no longer valid.", "Run `rebase cloud login` again.", "session_invalid");
 		const created = await client.data.collection("projects").create({
 			name,
 			subdomain,
@@ -6546,87 +7585,147 @@ async function createProject(rawArgs) {
 			createdById: user.uid,
 			status: "provisioning"
 		});
+		const host = projectHost(created, await fetchTenantBaseDomain(client, url));
+		const linked = Boolean(args["--link"]);
+		if (linked) writeLink({
+			url,
+			projectId: String(created.id),
+			slug: created.subdomain,
+			projectName: name,
+			orgId: String(org)
+		});
 		success(`Created project ${chalk.bold(name)}`);
-		keyValues([
-			["Slug", String(created.subdomain ?? "")],
-			["URL", projectHost(created, await fetchTenantBaseDomain(client, url))],
-			["Provider", provider],
-			["Branch", gitBranch]
-		]);
-		if (args["--link"]) {
-			writeLink({
-				url,
-				projectId: String(created.id),
-				slug: created.subdomain,
-				projectName: name,
-				orgId: String(org)
-			});
-			console.log(chalk.gray("  Linked this directory to the new project."));
-		}
-		console.log("");
-		console.log(chalk.gray(`  Deploy it with:  ${chalk.bold(`rebase cloud deploy --project ${created.subdomain ?? created.id}`)}`));
-		console.log("");
+		emit(() => {
+			keyValues([
+				["Slug", String(created.subdomain ?? "")],
+				["URL", host],
+				["Provider", provider],
+				["Branch", gitBranch]
+			]);
+			if (linked) note(chalk.gray("Linked this directory to the new project."));
+			noteBlank();
+			note(chalk.gray(`Deploy it with:  ${chalk.bold(`rebase cloud deploy --project ${created.subdomain ?? created.id}`)}`));
+			noteBlank();
+		}, {
+			success: true,
+			id: String(created.id),
+			name,
+			slug: created.subdomain ?? null,
+			host: host ?? null,
+			provider,
+			region,
+			vmSize,
+			branch: gitBranch,
+			org: String(org),
+			linked
+		});
 	} catch (e) {
 		reportError(e, "Failed to create project");
 	}
 }
+/**
+* Which project `projects info` / `projects delete` acts on.
+*
+* The id is optional — omitted, it falls back to `--project` or the link file —
+* and the dispatcher used to read it off `positionals()`, which skips only
+* LEADING `-` tokens and declares only the global cloud flags. So an undeclared
+* flag written after the action became the id: `rebase cloud projects delete
+* --force` looked up a project named "--force" and reported it missing, rather
+* than saying there is no such flag. Benign next to the deletes and writes the
+* rest of this family aimed at the wrong resource, but the same mistake, and
+* `positionals()` has no spec with which to do better — the handler's own
+* module does.
+*
+* Exported so its tests drive the real parser rather than a copy of it.
+*/
+function resolveProjectArg(rawArgs, action) {
+	const { positionals } = parseCloudArgs({
+		spec: {},
+		rawArgs,
+		commandWords: 3,
+		command: `cloud projects ${action}`,
+		maxPositionals: 1
+	});
+	return positionals[0] || requireProjectRef(rawArgs);
+}
 async function projectInfo(rawArgs, projectRef) {
 	const { client, url } = await requireClient(rawArgs);
 	try {
 		const projectId = await resolveProjectRef(projectRef, client);
 		const p = await client.data.collection("projects").findById(projectId);
-		if (!p) fail(`Project ${projectRef} not found.`);
+		if (!p) fail(`Project ${projectRef} not found.`, void 0, "project_not_found");
 		const [db, lastDeploy, baseDomain] = await Promise.all([
 			firstRow(client, "databases", projectId),
 			latestDeployment(client, projectId),
 			fetchTenantBaseDomain(client, url)
 		]);
-		console.log("");
-		console.log(`  ${chalk.bold(p.name ?? "(unnamed)")} ${chalk.gray(`[${p.subdomain ?? p.id}]`)} ${colorStatus(p.status)}`);
-		console.log("");
-		keyValues([
-			["Subdomain", projectHost(p, baseDomain)],
-			["Custom domain", p.customDomain],
-			["Repository", p.gitRepoUrl],
-			["Branch", p.gitBranch],
-			["Provider", p.provider],
-			["Region", p.region],
-			["Organization", p.organization !== void 0 ? String(p.organization) : void 0],
-			["Database", db ? `${db.type} (${colorStatus(db.connectionStatus)})` : "none"],
-			["Last deploy", lastDeploy ? `${colorStatus(lastDeploy.status)} · ${fmtDate(lastDeploy.createdAt)}` : "never"]
-		]);
-		console.log("");
+		emit(() => {
+			console.log("");
+			console.log(`  ${chalk.bold(p.name ?? "(unnamed)")} ${chalk.gray(`[${p.subdomain ?? p.id}]`)} ${colorStatus(p.status)}`);
+			console.log("");
+			keyValues([
+				["Subdomain", projectHost(p, baseDomain)],
+				["Custom domain", p.customDomain],
+				["Repository", p.gitRepoUrl],
+				["Branch", p.gitBranch],
+				["Provider", p.provider],
+				["Region", p.region],
+				["Organization", p.organization !== void 0 ? String(p.organization) : void 0],
+				["Database", db ? `${db.type} (${colorStatus(db.connectionStatus)})` : "none"],
+				["Last deploy", lastDeploy ? `${colorStatus(lastDeploy.status)} · ${fmtDate(lastDeploy.createdAt)}` : "never"]
+			]);
+			console.log("");
+		}, {
+			id: String(p.id),
+			name: p.name ?? null,
+			slug: p.subdomain ?? null,
+			host: projectHost(p, baseDomain) ?? null,
+			customDomain: p.customDomain ?? null,
+			repository: p.gitRepoUrl ?? null,
+			branch: p.gitBranch ?? null,
+			provider: p.provider ?? null,
+			region: p.region ?? null,
+			status: p.status ?? null,
+			org: p.organization !== void 0 ? String(p.organization) : null,
+			database: db ? {
+				type: db.type ?? null,
+				connectionStatus: db.connectionStatus ?? null
+			} : null,
+			lastDeploy: lastDeploy ? {
+				id: String(lastDeploy.id),
+				status: lastDeploy.status ?? null,
+				createdAt: lastDeploy.createdAt ?? null
+			} : null
+		});
 	} catch (e) {
 		reportError(e, "Failed to load project");
 	}
 }
 async function deleteProject(rawArgs, projectRef) {
-	const args = arg({
-		"--yes": Boolean,
-		"-y": "--yes"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
+	const { flags: args } = parseCloudArgs({
+		spec: {},
+		rawArgs,
+		commandWords: 3,
+		command: "cloud projects delete",
+		maxPositionals: 1
 	});
 	const { client } = await requireClient(rawArgs);
 	const projectId = await resolveProjectRef(projectRef, client);
 	const p = await client.data.collection("projects").findById(projectId).catch(() => void 0);
-	if (!p) fail(`Project ${projectRef} not found.`);
-	if (!args["--yes"]) {
-		const { confirmed } = await inquirer.prompt([{
-			type: "confirm",
-			name: "confirmed",
-			default: false,
-			message: `Permanently delete project "${p.name ?? projectRef}" (${p.subdomain ?? projectRef})? This tears down its deployment.`
-		}]);
-		if (!confirmed) {
-			console.log(chalk.gray("  Aborted."));
-			return;
-		}
-	}
+	if (!p) fail(`Project ${projectRef} not found.`, void 0, "project_not_found");
+	await confirmDestructive({
+		yes: Boolean(args["--yes"]),
+		prompt: `Permanently delete project "${p.name ?? projectRef}" (${p.subdomain ?? projectRef})? This tears down its deployment.`
+	});
 	try {
 		await client.data.collection("projects").delete(projectId);
 		success(`Deleted project ${chalk.bold(p.name ?? projectId)}`);
+		emit(() => {}, {
+			success: true,
+			id: projectId,
+			name: p.name ?? null,
+			slug: p.subdomain ?? null
+		});
 	} catch (e) {
 		reportError(e, "Failed to delete project");
 	}
@@ -7400,7 +8499,7 @@ async function orgsCommand(subcommand, rawArgs) {
 		case "--help":
 			printOrgsHelp();
 			break;
-		default: fail(`Unknown orgs command: ${subcommand}`);
+		default: fail(`Unknown orgs command: ${subcommand}`, "Run `rebase cloud orgs --help`.", "unknown_command");
 	}
 }
 async function listOrgs(rawArgs) {
@@ -7408,21 +8507,31 @@ async function listOrgs(rawArgs) {
 	try {
 		const orgs = (await client.data.collection("organizations").find({ limit: 100 })).data;
 		const active = getContextOrg(url);
-		console.log("");
-		console.log(chalk.bold("  🏢 Organizations"));
-		console.log("");
-		if (orgs.length === 0) {
-			console.log(chalk.gray("  You are not a member of any organization."));
+		emit(() => {
 			console.log("");
-			return;
-		}
-		for (const o of orgs) {
-			const marker = String(o.id) === active ? chalk.green(" ●") : "  ";
-			console.log(`${marker}${chalk.bold(o.name ?? "(unnamed)")} ${chalk.gray(`[${o.id}]`)}${o.slug ? chalk.gray(`  ${o.slug}`) : ""}`);
-		}
-		console.log("");
-		console.log(chalk.gray("  ● = active organization. Switch with `rebase cloud use <id>`."));
-		console.log("");
+			console.log(chalk.bold("  🏢 Organizations"));
+			console.log("");
+			if (orgs.length === 0) {
+				console.log(chalk.gray("  You are not a member of any organization."));
+				console.log("");
+				return;
+			}
+			for (const o of orgs) {
+				const marker = String(o.id) === active ? chalk.green(" ●") : "  ";
+				console.log(`${marker}${chalk.bold(o.name ?? "(unnamed)")} ${chalk.gray(`[${o.id}]`)}${o.slug ? chalk.gray(`  ${o.slug}`) : ""}`);
+			}
+			console.log("");
+			note(chalk.gray("● = active organization. Switch with `rebase cloud use <id>`."));
+			console.log("");
+		}, {
+			activeOrg: active ?? null,
+			organizations: orgs.map((o) => ({
+				id: String(o.id),
+				name: o.name ?? null,
+				slug: o.slug ?? null,
+				active: String(o.id) === active
+			}))
+		});
 	} catch (e) {
 		reportError(e, "Failed to list organizations");
 	}
@@ -7438,14 +8547,17 @@ async function createOrg(rawArgs) {
 	});
 	const { client, url } = await requireClient(rawArgs);
 	const prompts = [];
-	if (!args["--name"]) prompts.push({
-		type: "input",
-		name: "name",
-		message: "Organization name:"
-	});
+	if (!args["--name"]) {
+		requireInteractive("an organization name", "--name <name>");
+		prompts.push({
+			type: "input",
+			name: "name",
+			message: "Organization name:"
+		});
+	}
 	const answers = prompts.length ? await inquirer.prompt(prompts) : {};
 	const name = (args["--name"] || answers.name || "").trim();
-	if (!name) fail("Organization name is required.");
+	if (!name) fail("Organization name is required.", "Pass `--name <name>`.", "input_required");
 	const slug = (args["--slug"] || slugify(name)).trim();
 	try {
 		const created = await client.data.collection("organizations").create({
@@ -7455,6 +8567,13 @@ async function createOrg(rawArgs) {
 		});
 		setContextOrg(url, String(created.id));
 		success(`Created organization ${chalk.bold(name)} and set it active`);
+		emit(() => {}, {
+			success: true,
+			id: String(created.id),
+			name,
+			slug,
+			setActive: true
+		});
 	} catch (e) {
 		reportError(e, "Failed to create organization");
 	}
@@ -7462,22 +8581,31 @@ async function createOrg(rawArgs) {
 async function listMembers(rawArgs) {
 	const { client, url } = await requireClient(rawArgs);
 	const org = getContextOrg(url);
-	if (!org) fail("No active organization.", "Run `rebase cloud use` first.");
+	if (!org) fail("No active organization.", "Run `rebase cloud use` first.", "no_org");
 	try {
 		const members = (await client.data.collection("organization-members").find({
 			where: { organization: ["==", org] },
 			limit: 200
 		})).data;
-		console.log("");
-		console.log(chalk.bold(`  👥 Members — org ${org}`));
-		console.log("");
-		if (members.length === 0) {
-			console.log(chalk.gray("  No members found."));
+		emit(() => {
 			console.log("");
-			return;
-		}
-		for (const m of members) console.log(`  ${chalk.bold(m.userId ?? "?")}  ${colorStatus(m.role)}`);
-		console.log("");
+			console.log(chalk.bold(`  👥 Members — org ${org}`));
+			console.log("");
+			if (members.length === 0) {
+				console.log(chalk.gray("  No members found."));
+				console.log("");
+				return;
+			}
+			for (const m of members) console.log(`  ${chalk.bold(m.userId ?? "?")}  ${colorStatus(m.role)}`);
+			console.log("");
+		}, {
+			org,
+			members: members.map((m) => ({
+				id: String(m.id),
+				userId: m.userId ?? null,
+				role: m.role ?? null
+			}))
+		});
 	} catch (e) {
 		reportError(e, "Failed to list members");
 	}
@@ -7486,7 +8614,12 @@ function slugify(s) {
 	return s.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function printOrgsHelp() {
-	console.log(`
+	emitHelp("orgs", [
+		"list",
+		"create",
+		"members"
+	], () => {
+		console.log(`
 ${chalk.bold("rebase cloud orgs")} — Manage organizations
 
 ${chalk.green.bold("Commands")}
@@ -7494,6 +8627,7 @@ ${chalk.green.bold("Commands")}
   ${chalk.blue.bold("create")}            Create a new organization ${chalk.gray("(--name, --slug)")}
   ${chalk.blue.bold("members")}           List members of the active organization
 `);
+	});
 }
 //#endregion
 //#region src/commands/cloud/databases.ts
@@ -7529,7 +8663,7 @@ async function dbCommand$1(subcommand, rawArgs) {
 		case "--help":
 			printDbHelp();
 			break;
-		default: fail(`Unknown db command: ${subcommand}`);
+		default: fail(`Unknown db command: ${subcommand}`, "Run `rebase cloud db --help`.", "unknown_command");
 	}
 }
 async function listDatabases(rawArgs) {
@@ -7541,19 +8675,30 @@ async function listDatabases(rawArgs) {
 			where: { project: ["==", projectId] },
 			limit: 50
 		})).data;
-		console.log("");
-		console.log(chalk.bold(`  🗄  Databases — project ${projectRef}`));
-		console.log("");
-		if (dbs.length === 0) {
-			console.log(chalk.gray("  No database attached. Add one with `rebase cloud db create`."));
+		emit(() => {
 			console.log("");
-			return;
-		}
-		for (const d of dbs) {
-			console.log(`  ${chalk.bold(d.type ?? "unknown")} ${chalk.gray(`[${d.id}]`)}  ${colorStatus(d.connectionStatus)}`);
-			keyValues([["SSH tunnel", d.useSshTunnel ? "yes" : void 0], ["PITR", d.pitrEnabled ? "enabled" : void 0]]);
-		}
-		console.log("");
+			console.log(chalk.bold(`  🗄  Databases — project ${projectRef}`));
+			console.log("");
+			if (dbs.length === 0) {
+				console.log(chalk.gray("  No database attached. Add one with `rebase cloud db create`."));
+				console.log("");
+				return;
+			}
+			for (const d of dbs) {
+				console.log(`  ${chalk.bold(d.type ?? "unknown")} ${chalk.gray(`[${d.id}]`)}  ${colorStatus(d.connectionStatus)}`);
+				keyValues([["SSH tunnel", d.useSshTunnel ? "yes" : void 0], ["PITR", d.pitrEnabled ? "enabled" : void 0]]);
+			}
+			console.log("");
+		}, {
+			projectId,
+			databases: dbs.map((d) => ({
+				id: String(d.id),
+				type: d.type ?? null,
+				connectionStatus: d.connectionStatus ?? null,
+				useSshTunnel: Boolean(d.useSshTunnel),
+				pitrEnabled: Boolean(d.pitrEnabled)
+			}))
+		});
 	} catch (e) {
 		reportError(e, "Failed to list databases");
 	}
@@ -7573,6 +8718,7 @@ async function createDatabase(rawArgs) {
 	const projectRef = displayProjectRef(rawArgs);
 	let type = args["--type"];
 	if (!type) {
+		requireInteractive("a database type", "--type <managed|byodb>");
 		const { picked } = await inquirer.prompt([{
 			type: "select",
 			name: "picked",
@@ -7589,13 +8735,14 @@ async function createDatabase(rawArgs) {
 	}
 	let connectionString = args["--connection-string"];
 	if (type === "byodb" && !connectionString) {
+		requireInteractive("a connection string", "--connection-string <url>");
 		const { cs } = await inquirer.prompt([{
 			type: "input",
 			name: "cs",
 			message: "PostgreSQL connection string:"
 		}]);
 		connectionString = cs?.trim();
-		if (!connectionString) fail("A connection string is required for bring-your-own databases.");
+		if (!connectionString) fail("A connection string is required for bring-your-own databases.", "Pass `--connection-string <url>`.", "input_required");
 	}
 	try {
 		const created = await client.data.collection("databases").create({
@@ -7605,11 +8752,19 @@ async function createDatabase(rawArgs) {
 			connectionStatus: "untested"
 		});
 		success(`Attached ${type} database to project ${projectRef}`);
-		keyValues([["ID", String(created.id)]]);
-		if (type === "byodb") {
-			console.log(chalk.gray("  Verify it with `rebase cloud db test`."));
-			console.log("");
-		}
+		emit(() => {
+			keyValues([["ID", String(created.id)]]);
+			if (type === "byodb") {
+				note(chalk.gray("Verify it with `rebase cloud db test`."));
+				noteBlank();
+			}
+		}, {
+			success: true,
+			id: String(created.id),
+			projectId,
+			type,
+			connectionStatus: "untested"
+		});
 	} catch (e) {
 		reportError(e, "Failed to attach database");
 	}
@@ -7617,15 +8772,19 @@ async function createDatabase(rawArgs) {
 async function testDatabase(rawArgs) {
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
-	displayProjectRef(rawArgs);
-	console.log("");
-	console.log(`  Testing database connectivity for project ${chalk.bold(projectId)}...`);
+	const projectRef = displayProjectRef(rawArgs);
+	noteBlank();
+	note(`Testing database connectivity for project ${chalk.bold(projectRef)}...`);
 	try {
 		const res = await client.functions.invoke("db-test", { projectId });
-		console.log("");
-		if (res.logs) console.log(res.logs);
-		if (res.success) success("Database connection succeeded");
-		else fail("Database connection failed. See logs above.");
+		if (res.logs) console.error(`\n${res.logs}`);
+		if (!res.success) fail("Database connection failed.", "The connection log above (stderr) has the reason.", "db_connection_failed");
+		success("Database connection succeeded");
+		emit(() => {}, {
+			success: true,
+			projectId,
+			logs: res.logs ?? null
+		});
 	} catch (e) {
 		reportError(e, "Failed to test database");
 	}
@@ -7701,18 +8860,39 @@ async function dbInfo(rawArgs) {
 		reportError(e, "Failed to load database info");
 	}
 }
+/**
+* `db backup [action] [filename]`, resolved in one strict parse.
+*
+* Both halves were reachable by the old operand filter, and both are
+* destructive: `rebase cloud db backup -p acme` read `--project`'s value as the
+* ACTION (falling through to a list, so the flag silently changed what ran),
+* and `db backup restore -p acme` read it as the FILENAME — a restore staged
+* over the live database, named after the project slug. An undeclared flag was
+* dropped instead of refused, which is the same failure one step quieter: `db
+* backup --dry-run` ran a list, having silently discarded the flag that was
+* supposed to change what it did.
+*
+* Exported so its tests drive the real parser.
+*/
+function resolveBackupArgs(rawArgs) {
+	const { flags, positionals } = parseCloudArgs({
+		spec: { "--yes": Boolean },
+		rawArgs,
+		commandWords: 3,
+		command: "cloud db backup",
+		maxPositionals: 2
+	});
+	return {
+		flags,
+		action: positionals[0] || "list",
+		filename: positionals[1]
+	};
+}
 async function backupCommand(rawArgs) {
-	const action = rawArgs.slice(3).filter((a) => !a.startsWith("-"))[2] || "list";
+	const { flags: args, action, filename: backupFile } = resolveBackupArgs(rawArgs);
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	const projectRef = displayProjectRef(rawArgs);
-	const args = arg({
-		"--yes": Boolean,
-		"-y": "--yes"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
-	});
 	try {
 		if (action === "create") {
 			const res = await client.functions.invoke("backup", {
@@ -7727,7 +8907,7 @@ async function backupCommand(rawArgs) {
 			return;
 		}
 		if (action === "restore") {
-			const filename = cloudPositionals(rawArgs).slice(3)[0];
+			const filename = backupFile;
 			if (!filename) fail("Usage: rebase cloud db backup restore <filename>", void 0, "usage");
 			await confirmDestructive({
 				yes: Boolean(args["--yes"]),
@@ -7765,7 +8945,7 @@ async function backupCommand(rawArgs) {
 			return;
 		}
 		if (action === "download") {
-			const filename = cloudPositionals(rawArgs).slice(3)[0];
+			const filename = backupFile;
 			if (!filename) fail("Usage: rebase cloud db backup download <filename>", void 0, "usage");
 			const res = await client.functions.invoke("backup", void 0, {
 				method: "GET",
@@ -7823,17 +9003,17 @@ async function backupCommand(rawArgs) {
 * non-interactive use, and the CLI surfaces these staged semantics honestly.
 */
 async function pitrCommand(rawArgs) {
-	const args = arg({
-		"--target": String,
-		"--yes": Boolean,
-		"-y": "--yes",
-		"--project": String,
-		"-p": "--project"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
+	const { flags: args, positionals } = parseCloudArgs({
+		spec: {
+			"--target": String,
+			"--yes": Boolean
+		},
+		rawArgs,
+		commandWords: 3,
+		command: "cloud db pitr",
+		maxPositionals: 1
 	});
-	const action = cloudPositionals(rawArgs).slice(2)[0] || "status";
+	const action = positionals[0] || "status";
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	const projectRef = displayProjectRef(rawArgs);
@@ -7905,7 +9085,15 @@ async function pitrCommand(rawArgs) {
 	}
 }
 function printDbHelp() {
-	console.log(`
+	emitHelp("db", [
+		"list",
+		"create",
+		"info",
+		"test",
+		"backup",
+		"pitr"
+	], () => {
+		console.log(`
 ${chalk.bold("rebase cloud db")} — Database & backups
 
 ${chalk.green.bold("Commands")}
@@ -7930,6 +9118,7 @@ ${chalk.green.bold("Options")}
   ${chalk.blue("--connection-string")}       External DB URL ${chalk.gray("(byodb)")}
   ${chalk.blue("--json")}                    Machine-readable output
 `);
+	});
 }
 //#endregion
 //#region src/commands/cloud/env.ts
@@ -7966,7 +9155,7 @@ async function envCommand(action, rawArgs) {
 		case "unset":
 		case "delete":
 		case "rm":
-			await unsetEnv(rawArgs);
+			await unsetEnv(rawArgs, action);
 			break;
 		case "reveal":
 			await revealEnv(rawArgs);
@@ -8066,20 +9255,43 @@ var BUILD_TIME_ENV_PREFIXES = [
 function buildTimeEnvPrefix(key) {
 	return BUILD_TIME_ENV_PREFIXES.find((prefix) => key.toUpperCase().startsWith(prefix));
 }
-async function setEnv(rawArgs) {
-	const args = arg({
-		"--secret": Boolean,
-		"--force": Boolean,
-		"--project": String,
-		"-p": "--project"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
+/** The flags `rebase cloud env set` takes, on top of the global cloud ones. */
+var ENV_SET_FLAGS = {
+	"--secret": Boolean,
+	"--force": Boolean
+};
+/**
+* What `env set` was asked to store.
+*
+* The sharp one in this family: the old operand filter left `--project`'s value
+* in the operand list, so `rebase cloud env set KEY -p acme` parsed as the
+* `KEY VALUE` form and stored the project slug as KEY's value — a write that
+* succeeds, reports success, and is wrong. Strict parsing consumes `-p` with
+* its value, leaving `["KEY"]` and the documented empty value.
+*
+* A value beginning with `-` must use the `KEY=-v` form; the bare `KEY -v` form
+* is refused rather than guessed at, as everywhere else strict parsing is used.
+*
+* Exported so its tests drive the real parser rather than a copy of it.
+*/
+function resolveEnvSetArgs(rawArgs) {
+	const { flags, positionals } = parseCloudArgs({
+		spec: ENV_SET_FLAGS,
+		rawArgs,
+		commandWords: 3,
+		command: "cloud env set",
+		maxPositionals: 2
 	});
+	return {
+		flags,
+		assignment: parseEnvAssignment(positionals)
+	};
+}
+async function setEnv(rawArgs) {
+	const { flags: args, assignment: parsed } = resolveEnvSetArgs(rawArgs);
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	displayProjectRef(rawArgs);
-	const parsed = parseEnvAssignment(cloudPositionals(rawArgs).slice(2));
 	if (!parsed || !parsed.key) fail("Usage: rebase cloud env set KEY=VALUE [--secret]", void 0, "usage");
 	const buildTimePrefix = buildTimeEnvPrefix(parsed.key);
 	if (buildTimePrefix && !args["--force"]) fail(`${parsed.key} is read by your bundler at BUILD time, and project variables are applied at rollout — after the image is built. Setting it here would not reach the bundle.`, `Put ${buildTimePrefix}* variables in the source you deploy (a committed .env, or your build config), then \`rebase cloud deploy\`. Pass --force if your build genuinely reads this at run time.`, "build_time_variable");
@@ -8105,12 +9317,32 @@ async function setEnv(rawArgs) {
 		reportError(e, "Failed to set environment variable");
 	}
 }
-async function unsetEnv(rawArgs) {
+/**
+* The variable `env unset` / `env reveal` names.
+*
+* `unset` is a delete, and the operand filter aimed it at the wrong variable:
+* `rebase cloud env unset -p acme` removed a variable called "acme" from the
+* linked project instead of reporting a missing KEY, and `env unset -p acme
+* KEY` removed "acme" instead of KEY. Both read `--project`'s value as the
+* operand — a plain word in the right position that no flag filter can catch.
+*
+* `action` is the word the caller used (`unset`, `rm`, `delete`, `reveal`); the
+* count of command words is the same for all of them.
+*/
+function resolveEnvKeyArg(rawArgs, action) {
+	return parseCloudArgs({
+		spec: {},
+		rawArgs,
+		commandWords: 3,
+		command: `cloud env ${action}`,
+		maxPositionals: 1
+	}).positionals[0];
+}
+async function unsetEnv(rawArgs, action) {
+	const key = resolveEnvKeyArg(rawArgs, action);
+	if (!key) fail("Usage: rebase cloud env unset KEY", void 0, "usage");
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
-	displayProjectRef(rawArgs);
-	const key = cloudPositionals(rawArgs).slice(2)[0];
-	if (!key) fail("Usage: rebase cloud env unset KEY", void 0, "usage");
 	try {
 		emit(() => {
 			success(`Removed ${chalk.bold(key)}`);
@@ -8129,11 +9361,11 @@ async function unsetEnv(rawArgs) {
 	}
 }
 async function revealEnv(rawArgs) {
+	const key = resolveEnvKeyArg(rawArgs, "reveal");
+	if (!key) fail("Usage: rebase cloud env reveal KEY", void 0, "usage");
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	const projectRef = displayProjectRef(rawArgs);
-	const key = cloudPositionals(rawArgs).slice(2)[0];
-	if (!key) fail("Usage: rebase cloud env reveal KEY", void 0, "usage");
 	let list;
 	try {
 		list = await fetchEnvVars(client, projectId);
@@ -8161,20 +9393,20 @@ async function revealEnv(rawArgs) {
 	}
 }
 async function pullEnv(rawArgs) {
-	const args = arg({
-		"--out": String,
-		"--yes": Boolean,
-		"-y": "--yes",
-		"--project": String,
-		"-p": "--project"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
+	const { flags: args } = parseCloudArgs({
+		spec: {
+			"--output": String,
+			"--out": "--output"
+		},
+		rawArgs,
+		commandWords: 3,
+		command: "cloud env pull",
+		maxPositionals: 0
 	});
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	displayProjectRef(rawArgs);
-	const outPath = path.resolve(args["--out"] || ".env");
+	const outPath = path.resolve(args["--output"] || ".env");
 	try {
 		const list = await fetchEnvVars(client, projectId);
 		if (fs.existsSync(outPath)) await confirmDestructive({
@@ -8223,11 +9455,14 @@ async function pullEnv(rawArgs) {
 	}
 }
 function printEnvHelp() {
-	if (isJsonMode()) {
-		printEnvHelpJson();
-		return;
-	}
-	console.log(`
+	emitHelp("env", [
+		"list",
+		"set",
+		"unset",
+		"reveal",
+		"pull"
+	], () => {
+		console.log(`
 ${chalk.bold("rebase cloud env")} — Environment variables
 
 ${chalk.green.bold("Commands")}
@@ -8247,18 +9482,7 @@ ${chalk.gray("Values are encrypted at rest (AES-256-GCM) and only decrypted at d
 ${chalk.gray("VITE_* / NEXT_PUBLIC_* / PUBLIC_* / REACT_APP_* are read by your bundler at BUILD time;")}
 ${chalk.gray("these are applied at rollout, after the image is built, so they never reach the bundle.")}
 `);
-}
-function printEnvHelpJson() {
-	process.stdout.write(JSON.stringify({
-		command: "env",
-		actions: [
-			"list",
-			"set",
-			"unset",
-			"reveal",
-			"pull"
-		]
-	}) + "\n");
+	});
 }
 //#endregion
 //#region src/commands/cloud/domains.ts
@@ -8346,12 +9570,28 @@ async function listDomains(rawArgs) {
 		reportError(e, "Failed to load custom domain");
 	}
 }
+/**
+* The domain `domains add` was asked to register.
+*
+* Exported so its tests drive the real parser. Under the old operand filter
+* `rebase cloud domains add -p acme` registered a domain called "acme" — the
+* project slug, read out of `--project`'s own value — and a registered domain
+* is a project-record write, not a no-op.
+*/
+function resolveDomainArg(rawArgs) {
+	return parseCloudArgs({
+		spec: {},
+		rawArgs,
+		commandWords: 3,
+		command: "cloud domains add",
+		maxPositionals: 1
+	}).positionals[0];
+}
 async function addDomain(rawArgs) {
+	const domain = resolveDomainArg(rawArgs);
+	if (!domain) fail("Usage: rebase cloud domains add <domain>", void 0, "usage");
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
-	displayProjectRef(rawArgs);
-	const domain = cloudPositionals(rawArgs).slice(2)[0];
-	if (!domain) fail("Usage: rebase cloud domains add <domain>", void 0, "usage");
 	try {
 		await client.data.collection("projects").update(projectId, { customDomain: domain });
 		const setup = await fetchDomainSetup(client, projectId);
@@ -8406,14 +9646,12 @@ async function verifyDomains(rawArgs) {
 	}
 }
 async function removeDomain(rawArgs) {
-	const args = arg({
-		"--yes": Boolean,
-		"-y": "--yes",
-		"--project": String,
-		"-p": "--project"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
+	const { flags: args } = parseCloudArgs({
+		spec: {},
+		rawArgs,
+		commandWords: 3,
+		command: "cloud domains remove",
+		maxPositionals: 0
 	});
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
@@ -8433,7 +9671,13 @@ async function removeDomain(rawArgs) {
 	}
 }
 function printDomainsHelp() {
-	console.log(`
+	emitHelp("domains", [
+		"list",
+		"add",
+		"verify",
+		"remove"
+	], () => {
+		console.log(`
 ${chalk.bold("rebase cloud domains")} — Custom domain
 
 ${chalk.green.bold("Commands")}
@@ -8446,6 +9690,7 @@ ${chalk.green.bold("Options")}
   ${chalk.blue("--json")}                    Machine-readable output
   ${chalk.blue("--project, -p")}             Project slug ${chalk.gray("(defaults to the linked project)")}
 `);
+	});
 }
 //#endregion
 //#region src/commands/cloud/extensions.ts
@@ -8523,22 +9768,33 @@ async function listExtensions(rawArgs) {
 	} catch (e) {
 		reportError(e, "Failed to list extensions");
 	}
-}
-async function enableExtension(rawArgs) {
-	const args = arg({
-		"--yes": Boolean,
-		"-y": "--yes",
-		"--project": String,
-		"-p": "--project"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
+}
+/**
+* The extension `enable`/`disable` names, plus the flags that gate it.
+*
+* Under the old operand filter `rebase cloud extensions enable -p acme` read
+* `--project`'s value as the extension name and asked the server to install one
+* called "acme"; `extensions disable -p acme vector` dropped "acme" rather than
+* vector. Strict parsing consumes the flag with its value.
+*/
+function resolveExtensionArgs(rawArgs, action) {
+	const { flags, positionals } = parseCloudArgs({
+		spec: {},
+		rawArgs,
+		commandWords: 3,
+		command: `cloud extensions ${action}`,
+		maxPositionals: 1
 	});
+	return {
+		flags,
+		name: positionals[0]
+	};
+}
+async function enableExtension(rawArgs) {
+	const { flags: args, name: raw } = resolveExtensionArgs(rawArgs, "enable");
+	if (!raw) fail("Usage: rebase cloud extensions enable <name>", void 0, "usage");
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
-	displayProjectRef(rawArgs);
-	const raw = cloudPositionals(rawArgs).slice(2)[0];
-	if (!raw) fail("Usage: rebase cloud extensions enable <name>", void 0, "usage");
 	const name = resolveExtensionAlias(raw);
 	try {
 		const ext = (await fetchExtensions(client, projectId)).extensions.find((e) => e.name === name);
@@ -8575,20 +9831,10 @@ async function enableExtension(rawArgs) {
 	}
 }
 async function disableExtension(rawArgs) {
-	const args = arg({
-		"--yes": Boolean,
-		"-y": "--yes",
-		"--project": String,
-		"-p": "--project"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
-	});
+	const { flags: args, name: raw } = resolveExtensionArgs(rawArgs, "disable");
+	if (!raw) fail("Usage: rebase cloud extensions disable <name>", void 0, "usage");
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
-	displayProjectRef(rawArgs);
-	const raw = cloudPositionals(rawArgs).slice(2)[0];
-	if (!raw) fail("Usage: rebase cloud extensions disable <name>", void 0, "usage");
 	const name = resolveExtensionAlias(raw);
 	try {
 		const ext = (await fetchExtensions(client, projectId)).extensions.find((e) => e.name === name);
@@ -8614,7 +9860,12 @@ async function disableExtension(rawArgs) {
 	}
 }
 function printExtensionsHelp() {
-	console.log(`
+	emitHelp("extensions", [
+		"list",
+		"enable",
+		"disable"
+	], () => {
+		console.log(`
 ${chalk.bold("rebase cloud extensions")} — Postgres extensions
 
 ${chalk.green.bold("Commands")}
@@ -8627,6 +9878,7 @@ ${chalk.green.bold("Options")}
   ${chalk.blue("--json")}                    Machine-readable output
   ${chalk.blue("--project, -p")}             Project slug ${chalk.gray("(defaults to the linked project)")}
 `);
+	});
 }
 //#endregion
 //#region src/commands/cloud/settings.ts
@@ -8738,7 +9990,8 @@ async function setSettings(rawArgs) {
 	}
 }
 function printSettingsHelp() {
-	console.log(`
+	emitHelp("settings", ["show", "set"], () => {
+		console.log(`
 ${chalk.bold("rebase cloud settings")} — Project configuration
 
 ${chalk.green.bold("Commands")}
@@ -8755,6 +10008,7 @@ ${chalk.green.bold("Options")}
   ${chalk.blue("--json")}                    Machine-readable output
   ${chalk.blue("--project, -p")}             Project slug ${chalk.gray("(defaults to the linked project)")}
 `);
+	});
 }
 //#endregion
 //#region src/commands/cloud/deployments.ts
@@ -8865,14 +10119,15 @@ function parseDeploymentsLimit(raw) {
 	return raw;
 }
 async function deploymentsListCommand(rawArgs) {
-	const args = arg({
-		"--limit": Number,
-		"--all": Boolean,
-		"--project": String,
-		"-p": "--project"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
+	const { flags: args } = parseCloudArgs({
+		spec: {
+			"--limit": Number,
+			"--all": Boolean
+		},
+		rawArgs,
+		commandWords: 2,
+		command: "cloud deployments list",
+		maxPositionals: 1
 	});
 	const limit = args["--all"] ? MAX_DEPLOYMENTS_LIMIT : parseDeploymentsLimit(args["--limit"]);
 	const { client } = await requireClient(rawArgs);
@@ -8913,20 +10168,34 @@ async function deploymentsListCommand(rawArgs) {
 		reportError(e, "Failed to list deployments");
 	}
 }
-async function rollbackCommand(rawArgs) {
-	const args = arg({
-		"--yes": Boolean,
-		"-y": "--yes",
-		"--project": String,
-		"-p": "--project"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
+/**
+* The deployment id `rollback`/`cancel` was given, if any.
+*
+* Both take an optional id, which is what made the old operand filter so easy
+* to trip: `rebase cloud rollback -p acme` — the documented way to act on an
+* unlinked project — read `--project`'s value as the id and refused with
+* "Deployment acme not found", and `cancel -p acme` sent "acme" to the server
+* as the deployment to cancel. Strict parsing consumes the flag with its value,
+* so an id given as a flag value is never mistaken for an argument.
+*/
+function resolveDeploymentIdArg(rawArgs, command) {
+	const { flags, positionals } = parseCloudArgs({
+		spec: {},
+		rawArgs,
+		commandWords: 2,
+		command,
+		maxPositionals: 1
 	});
+	return {
+		flags,
+		id: positionals[0]
+	};
+}
+async function rollbackCommand(rawArgs) {
+	const { flags: args, id: explicitId } = resolveDeploymentIdArg(rawArgs, "cloud rollback");
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	const projectRef = displayProjectRef(rawArgs);
-	const explicitId = cloudPositionals(rawArgs).slice(1)[0];
 	let rows;
 	try {
 		rows = await fetchDeployments(client, projectId);
@@ -8974,19 +10243,10 @@ async function rollbackCommand(rawArgs) {
 	}
 }
 async function cancelCommand(rawArgs) {
-	const args = arg({
-		"--yes": Boolean,
-		"-y": "--yes",
-		"--project": String,
-		"-p": "--project"
-	}, {
-		argv: rawArgs.slice(2),
-		permissive: true
-	});
+	const { flags: args, id: explicitId } = resolveDeploymentIdArg(rawArgs, "cloud cancel");
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	const projectRef = displayProjectRef(rawArgs);
-	const explicitId = cloudPositionals(rawArgs).slice(1)[0];
 	await confirmDestructive({
 		yes: Boolean(args["--yes"]),
 		prompt: `Cancel the in-flight build for project ${projectRef}?`
@@ -9768,7 +11028,16 @@ async function debugCommand(action, rawArgs) {
 	}
 }
 function printDebugHelp() {
-	console.log(`
+	emitHelp("debug", [
+		"health",
+		"logs",
+		"errors",
+		"requests",
+		"boot",
+		"pod",
+		"db"
+	], () => {
+		console.log(`
 ${chalk.bold("rebase cloud debug")} — Find out why a deployed project is misbehaving
 
 ${chalk.green.bold("Usage")}
@@ -9799,6 +11068,7 @@ ${chalk.green.bold("Options")}
 ${chalk.gray("Everything here is read-only. `health` exits non-zero when a check fails,")}
 ${chalk.gray("so it works in a deploy script. To restart a workload, use `rebase cloud restart`.")}
 `);
+	});
 }
 //#endregion
 //#region src/commands/cloud/resources.ts
@@ -9938,37 +11208,73 @@ async function metricsCommand(rawArgs) {
 			method: "GET",
 			path: projectId
 		});
-		console.log("");
-		console.log(chalk.bold(`  📊 Metrics — project ${displayProjectRef(rawArgs)}`));
-		console.log("");
-		keyValues([
-			["Status", m.status ? colorStatus(m.status === "running" ? "active" : m.status) : void 0],
-			["CPU", m.cpu],
-			["Memory", m.memory ? `${m.memory}${m.memoryPercent ? ` (${m.memoryPercent})` : ""}` : void 0],
-			["Disk", m.disk]
-		]);
-		console.log("");
+		emit(() => {
+			console.log("");
+			console.log(chalk.bold(`  📊 Metrics — project ${displayProjectRef(rawArgs)}`));
+			console.log("");
+			keyValues([
+				["Status", m.status ? colorStatus(m.status === "running" ? "active" : m.status) : void 0],
+				["CPU", m.cpu],
+				["Memory", m.memory ? `${m.memory}${m.memoryPercent ? ` (${m.memoryPercent})` : ""}` : void 0],
+				["Disk", m.disk]
+			]);
+			console.log("");
+		}, {
+			projectId,
+			status: m.status ?? null,
+			cpu: m.cpu ?? null,
+			memory: m.memory ?? null,
+			memoryPercent: m.memoryPercent ?? null,
+			disk: m.disk ?? null
+		});
 	} catch (e) {
 		reportError(e, "Failed to fetch metrics");
 	}
 }
+/**
+* The webhook `webhooks delete` names.
+*
+* The worst instance of the operand-filter bug in this family, because the
+* argument is consumed by a DELETE and the wrong value looks entirely
+* plausible: `rebase cloud webhooks delete --project acme 42` filtered out
+* `--project` and kept "acme", so the id it deleted was the project slug rather
+* than the 42 the caller wrote. Strict parsing consumes the flag with its
+* value, leaving `["42"]`.
+*
+* Exported so its tests drive the real parser.
+*/
+function resolveWebhookIdArg(rawArgs) {
+	return parseCloudArgs({
+		spec: {},
+		rawArgs,
+		commandWords: 3,
+		command: "cloud webhooks delete",
+		maxPositionals: 1
+	}).positionals[0];
+}
 async function webhooksCommand(subcommand, rawArgs) {
+	const create = subcommand === "create" ? parseCloudArgs({
+		spec: {
+			"--name": String,
+			"--table": String,
+			"--url": String,
+			"--events": String
+		},
+		rawArgs,
+		commandWords: 3,
+		command: "cloud webhooks create",
+		maxPositionals: 0
+	}).flags : void 0;
+	const deleteId = subcommand === "delete" ? resolveWebhookIdArg(rawArgs) : void 0;
+	if (subcommand === "delete" && !deleteId) fail("Usage: rebase cloud webhooks delete <id>", void 0, "usage");
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	try {
 		if (subcommand === "create") {
-			const args = arg({
-				"--name": String,
-				"--table": String,
-				"--url": String,
-				"--events": String
-			}, {
-				argv: rawArgs.slice(4),
-				permissive: true
-			});
-			const name = args["--name"] || fail("--name is required.");
-			const table = args["--table"] || fail("--table is required.");
-			const url = args["--url"] || fail("--url (endpoint) is required.");
+			const args = create;
+			const name = args["--name"] || fail("--name is required.", void 0, "usage");
+			const table = args["--table"] || fail("--table is required.", void 0, "usage");
+			const url = args["--url"] || fail("--url (endpoint) is required.", void 0, "usage");
 			const events = (args["--events"] || "insert,update,delete").split(",").map((s) => s.trim());
 			const created = await client.data.collection("webhooks").create({
 				project: projectId,
@@ -9979,33 +11285,58 @@ async function webhooksCommand(subcommand, rawArgs) {
 				enabled: true
 			});
 			success(`Created webhook ${chalk.bold(name)} [${created.id}]`);
+			emit(() => {}, {
+				success: true,
+				id: String(created.id),
+				projectId,
+				name,
+				table,
+				url,
+				events,
+				enabled: true
+			});
 			return;
 		}
 		if (subcommand === "delete") {
-			const id = rawArgs.slice(3).filter((a) => !a.startsWith("-"))[2];
-			if (!id) fail("Usage: rebase cloud webhooks delete <id>");
-			await client.data.collection("webhooks").delete(id);
-			success(`Deleted webhook ${id}`);
+			await client.data.collection("webhooks").delete(deleteId);
+			success(`Deleted webhook ${deleteId}`);
+			emit(() => {}, {
+				success: true,
+				id: deleteId,
+				projectId
+			});
 			return;
 		}
 		const hooks = (await client.data.collection("webhooks").find({
 			where: { project: ["==", projectId] },
 			limit: 100
 		})).data;
-		console.log("");
-		console.log(chalk.bold(`  🔗 Webhooks — project ${displayProjectRef(rawArgs)}`));
-		console.log("");
-		if (hooks.length === 0) {
-			console.log(chalk.gray("  No webhooks. Add one with `rebase cloud webhooks create`."));
+		emit(() => {
 			console.log("");
-			return;
-		}
-		for (const h of hooks) {
-			const state = h.enabled ? chalk.green("enabled") : chalk.gray("disabled");
-			console.log(`  ${chalk.bold(h.name ?? "(unnamed)")} ${chalk.gray(`[${h.id}]`)} ${state}`);
-			console.log(`    ${chalk.gray(`${h.table ?? "?"} → ${h.url ?? "?"}  (${(h.events ?? []).join(", ")})`)}`);
-		}
-		console.log("");
+			console.log(chalk.bold(`  🔗 Webhooks — project ${displayProjectRef(rawArgs)}`));
+			console.log("");
+			if (hooks.length === 0) {
+				console.log(chalk.gray("  No webhooks. Add one with `rebase cloud webhooks create`."));
+				console.log("");
+				return;
+			}
+			for (const h of hooks) {
+				const state = h.enabled ? chalk.green("enabled") : chalk.gray("disabled");
+				console.log(`  ${chalk.bold(h.name ?? "(unnamed)")} ${chalk.gray(`[${h.id}]`)} ${state}`);
+				console.log(`    ${chalk.gray(`${h.table ?? "?"} → ${h.url ?? "?"}  (${(h.events ?? []).join(", ")})`)}`);
+			}
+			console.log("");
+		}, {
+			projectId,
+			webhooks: hooks.map((h) => ({
+				id: String(h.id),
+				name: h.name ?? null,
+				table: h.table ?? null,
+				url: h.url ?? null,
+				events: h.events ?? [],
+				enabled: h.enabled ?? null
+			}))
+		});
 	} catch (e) {
 		reportError(e, "Webhook operation failed");
 	}
@@ -10021,78 +11352,116 @@ async function storageCommand(action, rawArgs) {
 			where: { project: ["==", projectId] },
 			limit: 50
 		})).data;
-		console.log("");
-		console.log(chalk.bold(`  🪣 Storage — project ${displayProjectRef(rawArgs)}`));
-		console.log("");
-		if (stores.length === 0) {
-			console.log(chalk.gray("  No storage buckets attached."));
+		emit(() => {
 			console.log("");
-			return;
-		}
-		for (const s of stores) {
-			console.log(`  ${chalk.bold(s.bucketName ?? s.type ?? "bucket")} ${chalk.gray(`[${s.id}]`)} ${colorStatus(s.status)}`);
-			keyValues([["Provider", s.provider], ["Type", s.type]]);
-		}
-		console.log("");
+			console.log(chalk.bold(`  🪣 Storage — project ${displayProjectRef(rawArgs)}`));
+			console.log("");
+			if (stores.length === 0) {
+				console.log(chalk.gray("  No storage buckets attached."));
+				console.log("");
+				return;
+			}
+			for (const s of stores) {
+				console.log(`  ${chalk.bold(s.bucketName ?? s.type ?? "bucket")} ${chalk.gray(`[${s.id}]`)} ${colorStatus(s.status)}`);
+				keyValues([["Provider", s.provider], ["Type", s.type]]);
+			}
+			console.log("");
+		}, {
+			projectId,
+			stores: stores.map((s) => ({
+				id: String(s.id),
+				bucketName: s.bucketName ?? null,
+				type: s.type ?? null,
+				provider: s.provider ?? null,
+				status: s.status ?? null
+			}))
+		});
 	} catch (e) {
 		reportError(e, "Failed to list storage");
 	}
 }
 function printStorageHelp() {
-	console.log("");
-	console.log(chalk.bold("  rebase cloud storage"));
-	console.log("");
-	console.log("  " + chalk.blue.bold("storage") + "                   List this project's storage");
-	console.log("  " + chalk.blue.bold("storage create") + "            Provision platform-managed storage");
-	console.log("  " + chalk.blue.bold("storage attach") + "            Attach your own S3-compatible bucket");
-	console.log("");
-	console.log(chalk.gray("  attach options:"));
-	console.log(chalk.gray("    --bucket <name>          Bucket name (required)"));
-	console.log(chalk.gray("    --access-key-id <id>     Access key ID (required)"));
-	console.log(chalk.gray("    --secret-access-key <s>  Secret access key (required)"));
-	console.log(chalk.gray("    --endpoint <url>         S3 endpoint; omit for AWS"));
-	console.log(chalk.gray("    --region <region>        Region"));
-	console.log(chalk.gray("    --force-path-style       Required by MinIO and some gateways"));
-	console.log("");
-	console.log(chalk.gray("  Without either, file storage stays off: uploads are refused with"));
-	console.log(chalk.gray("  501 STORAGE_NOT_CONFIGURED rather than written to a container"));
-	console.log(chalk.gray("  filesystem that is erased on the next restart."));
-	console.log("");
+	emitHelp("storage", [
+		"list",
+		"create",
+		"attach"
+	], () => {
+		console.log("");
+		console.log(chalk.bold("  rebase cloud storage"));
+		console.log("");
+		console.log("  " + chalk.blue.bold("storage") + "                   List this project's storage");
+		console.log("  " + chalk.blue.bold("storage create") + "            Provision platform-managed storage");
+		console.log("  " + chalk.blue.bold("storage attach") + "            Attach your own S3-compatible bucket");
+		console.log("");
+		console.log(chalk.gray("  attach options:"));
+		console.log(chalk.gray("    --bucket <name>          Bucket name (required)"));
+		console.log(chalk.gray("    --access-key-id <id>     Access key ID (required)"));
+		console.log(chalk.gray("    --secret-access-key <s>  Secret access key (required)"));
+		console.log(chalk.gray("    --endpoint <url>         S3 endpoint; omit for AWS"));
+		console.log(chalk.gray("    --region <region>        Region"));
+		console.log(chalk.gray("    --force-path-style       Required by MinIO and some gateways"));
+		console.log("");
+		console.log(chalk.gray("  Without either, file storage stays off: uploads are refused with"));
+		console.log(chalk.gray("  501 STORAGE_NOT_CONFIGURED rather than written to a container"));
+		console.log(chalk.gray("  filesystem that is erased on the next restart."));
+		console.log("");
+	});
 }
 async function storageCreateCommand(rawArgs) {
+	parseCloudArgs({
+		spec: {},
+		rawArgs,
+		commandWords: 3,
+		command: "cloud storage create",
+		maxPositionals: 0
+	});
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	try {
-		console.log("");
-		console.log(chalk.gray("  Provisioning managed storage — this creates a bucket and its credentials..."));
+		noteBlank();
+		note(chalk.gray("Provisioning managed storage — this creates a bucket and its credentials..."));
 		const res = await client.functions.invoke(`storage-provision/${encodeURIComponent(projectId)}`, void 0, { method: "POST" });
 		const info = res.data ?? res.data;
 		success(`Managed storage provisioned for ${displayProjectRef(rawArgs)}.`);
-		keyValues([
-			["Bucket", info.bucketName],
-			["Region", info.region],
-			["Endpoint", info.endpoint],
-			["Access key", info.accessKeyId]
-		]);
-		console.log("");
-		console.log(chalk.gray("  The secret key is stored encrypted and injected at deploy time; it is not displayed."));
-		console.log(chalk.gray("  Redeploy for the tenant to pick it up:  ") + chalk.bold("rebase cloud deploy"));
-		console.log("");
+		emit(() => {
+			keyValues([
+				["Bucket", info.bucketName],
+				["Region", info.region],
+				["Endpoint", info.endpoint],
+				["Access key", info.accessKeyId]
+			]);
+			noteBlank();
+			note(chalk.gray("The secret key is stored encrypted and injected at deploy time; it is not displayed."));
+			note(chalk.gray("Redeploy for the tenant to pick it up:  ") + chalk.bold("rebase cloud deploy"));
+			noteBlank();
+		}, {
+			success: true,
+			projectId,
+			bucketName: info.bucketName,
+			region: info.region,
+			endpoint: info.endpoint,
+			accessKeyId: info.accessKeyId,
+			secretAccessKey: null,
+			pendingRedeploy: true
+		});
 	} catch (e) {
 		reportError(e, "Failed to provision managed storage");
 	}
 }
 async function storageAttachCommand(rawArgs) {
-	const parsed = arg({
-		"--bucket": String,
-		"--access-key-id": String,
-		"--secret-access-key": String,
-		"--endpoint": String,
-		"--region": String,
-		"--force-path-style": Boolean
-	}, {
-		argv: rawArgs.slice(3),
-		permissive: true
+	const { flags: parsed } = parseCloudArgs({
+		spec: {
+			"--bucket": String,
+			"--access-key-id": String,
+			"--secret-access-key": String,
+			"--endpoint": String,
+			"--region": String,
+			"--force-path-style": Boolean
+		},
+		rawArgs,
+		commandWords: 3,
+		command: "cloud storage attach",
+		maxPositionals: 0
 	});
 	const bucket = parsed["--bucket"];
 	const accessKeyId = parsed["--access-key-id"];
@@ -10102,7 +11471,7 @@ async function storageAttachCommand(rawArgs) {
 		!accessKeyId && "--access-key-id",
 		!secretAccessKey && "--secret-access-key"
 	].filter(Boolean);
-	if (missing.length > 0) fail(`Missing ${missing.join(", ")}.`, "A bucket without credentials cannot be used, and would be stored as though it could. Run `rebase cloud storage --help` for the full list.");
+	if (missing.length > 0) fail(`Missing ${missing.join(", ")}.`, "A bucket without credentials cannot be used, and would be stored as though it could. Run `rebase cloud storage --help` for the full list.", "usage");
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	try {
@@ -10125,17 +11494,29 @@ async function storageAttachCommand(rawArgs) {
 			row.region = parsed["--region"];
 		}
 		if (parsed["--force-path-style"]) row.s3ForcePathStyle = true;
+		const replaced = Boolean(existing?.id);
 		if (existing?.id) await client.data.collection("storages").update(String(existing.id), row);
 		else await client.data.collection("storages").create(row);
 		success(`Storage attached to ${displayProjectRef(rawArgs)}.`);
-		keyValues([
-			["Bucket", bucket],
-			["Endpoint", parsed["--endpoint"] ?? "AWS S3"],
-			["Region", parsed["--region"] ?? "(default)"]
-		]);
-		console.log("");
-		console.log(chalk.gray("  Redeploy for the tenant to pick it up:  ") + chalk.bold("rebase cloud deploy"));
-		console.log("");
+		emit(() => {
+			keyValues([
+				["Bucket", bucket],
+				["Endpoint", parsed["--endpoint"] ?? "AWS S3"],
+				["Region", parsed["--region"] ?? "(default)"]
+			]);
+			noteBlank();
+			note(chalk.gray("Redeploy for the tenant to pick it up:  ") + chalk.bold("rebase cloud deploy"));
+			noteBlank();
+		}, {
+			success: true,
+			projectId,
+			bucket,
+			endpoint: parsed["--endpoint"] ?? null,
+			region: parsed["--region"] ?? null,
+			forcePathStyle: Boolean(parsed["--force-path-style"]),
+			replaced,
+			pendingRedeploy: true
+		});
 	} catch (e) {
 		reportError(e, "Failed to attach storage");
 	}
@@ -10144,40 +11525,55 @@ async function clustersCommand(rawArgs) {
 	const { client } = await requireClient(rawArgs);
 	try {
 		const clusters = (await client.data.collection("clusters").find({ limit: 100 })).data;
-		console.log("");
-		console.log(chalk.bold("  ☸  Clusters"));
-		console.log("");
-		if (clusters.length === 0) {
-			console.log(chalk.gray("  No clusters registered."));
+		emit(() => {
 			console.log("");
-			return;
-		}
-		for (const c of clusters) {
-			console.log(`  ${chalk.bold(c.name ?? "(unnamed)")} ${chalk.gray(`[${c.id}]`)} ${colorStatus(c.status)}`);
-			keyValues([["Provider", c.provider], ["Region", c.region]]);
-		}
-		console.log("");
+			console.log(chalk.bold("  ☸  Clusters"));
+			console.log("");
+			if (clusters.length === 0) {
+				console.log(chalk.gray("  No clusters registered."));
+				console.log("");
+				return;
+			}
+			for (const c of clusters) {
+				console.log(`  ${chalk.bold(c.name ?? "(unnamed)")} ${chalk.gray(`[${c.id}]`)} ${colorStatus(c.status)}`);
+				keyValues([["Provider", c.provider], ["Region", c.region]]);
+			}
+			console.log("");
+		}, { clusters: clusters.map((c) => ({
+			id: String(c.id),
+			name: c.name ?? null,
+			provider: c.provider ?? null,
+			region: c.region ?? null,
+			status: c.status ?? null
+		})) });
 	} catch (e) {
 		reportError(e, "Failed to list clusters");
 	}
 }
 async function billingCommand(rawArgs) {
+	const action = parseCloudArgs({
+		spec: {},
+		rawArgs,
+		commandWords: 2,
+		command: "cloud billing",
+		maxPositionals: 1
+	}).positionals[0];
 	const { client, url } = await requireClient(rawArgs);
 	const org = getContextOrg(url);
-	const action = rawArgs.slice(3).filter((a) => !a.startsWith("-"))[1];
 	if (action === "setup") {
-		if (!org) fail("No active organization.", "Run `rebase cloud use` first.");
+		if (!org) fail("No active organization.", "Run `rebase cloud use` first.", "no_org");
 		try {
 			const res = await client.functions.invoke("stripe-billing", { organizationId: org }, { path: "setup-session" });
-			if (!res.url) fail("Could not start billing setup.");
+			if (!res.url) fail("Could not start billing setup.", void 0, "billing_setup_failed");
 			openUrl(res.url, "Add a payment method in your browser:");
-			if (res.simulated) {
-				console.log(chalk.gray("  (dev mode — Stripe not configured; complete setup from the console)"));
-				console.log("");
-			} else {
-				console.log(chalk.gray("  Once you've added a card, `rebase cloud deploy` runs without further prompts."));
-				console.log("");
-			}
+			emit(() => {
+				note(chalk.gray(res.simulated ? "(dev mode — Stripe not configured; complete setup from the console)" : "Once you've added a card, `rebase cloud deploy` runs without further prompts."));
+				noteBlank();
+			}, {
+				url: res.url,
+				org,
+				simulated: Boolean(res.simulated)
+			});
 		} catch (e) {
 			reportError(e, "Failed to start billing setup");
 		}
@@ -10187,24 +11583,36 @@ async function billingCommand(rawArgs) {
 		const projectId = await requireProject(rawArgs, client);
 		try {
 			const res = await client.functions.invoke("stripe-billing", { projectId }, { path: "session" });
-			if (!res.url) fail("Billing session could not be created.");
-			console.log("");
-			console.log("  Complete checkout in your browser:");
-			console.log(`  ${chalk.cyan(res.url)}`);
-			console.log("");
+			if (!res.url) fail("Billing session could not be created.", void 0, "checkout_failed");
+			emit(() => {
+				console.log("");
+				console.log("  Complete checkout in your browser:");
+				console.log(`  ${chalk.cyan(res.url)}`);
+				console.log("");
+			}, {
+				url: res.url,
+				projectId
+			});
 		} catch (e) {
 			reportError(e, "Failed to start checkout");
 		}
 		return;
 	}
-	if (!org) fail("No active organization.", "Run `rebase cloud use` first.");
+	if (!org) fail("No active organization.", "Run `rebase cloud use` first.", "no_org");
 	try {
 		const orgRow = await client.data.collection("organizations").findById(org);
 		const billingId = orgRow?.billing_account_id ?? orgRow?.billingAccount;
 		if (!billingId) {
-			console.log("");
-			console.log(chalk.gray(`  Organization ${org} has no billing account yet.`));
-			console.log("");
+			emit(() => {
+				console.log("");
+				console.log(chalk.gray(`  Organization ${org} has no billing account yet.`));
+				console.log("");
+			}, {
+				org,
+				account: null,
+				plan: null,
+				paymentMethod: null
+			});
 			return;
 		}
 		const acct = await client.data.collection("billing-accounts").findById(billingId);
@@ -10237,17 +11645,34 @@ async function billingCommand(rawArgs) {
 				} catch {}
 			}
 		} catch {}
-		console.log("");
-		console.log(chalk.bold(`  💳 Billing — org ${org}`));
-		console.log("");
-		keyValues([
-			["Account", acct ? String(acct.id) : void 0],
-			["Email", acct?.billingEmail],
-			["Status", acct?.status ? colorStatus(acct.status) : void 0],
-			["Plan", plan],
-			["Payment method", card.hasPaymentMethod ? `${card.brand ?? "card"} •••• ${card.last4 ?? "????"}${card.expMonth ? ` (exp ${card.expMonth}/${card.expYear})` : ""}` : chalk.yellow("none — run `rebase cloud billing setup`")]
-		]);
-		console.log("");
+		emit(() => {
+			console.log("");
+			console.log(chalk.bold(`  💳 Billing — org ${org}`));
+			console.log("");
+			keyValues([
+				["Account", acct ? String(acct.id) : void 0],
+				["Email", acct?.billingEmail],
+				["Status", acct?.status ? colorStatus(acct.status) : void 0],
+				["Plan", plan],
+				["Payment method", card.hasPaymentMethod ? `${card.brand ?? "card"} •••• ${card.last4 ?? "????"}${card.expMonth ? ` (exp ${card.expMonth}/${card.expYear})` : ""}` : chalk.yellow("none — run `rebase cloud billing setup`")]
+			]);
+			console.log("");
+		}, {
+			org,
+			account: acct ? {
+				id: String(acct.id),
+				billingEmail: acct.billingEmail ?? null,
+				status: acct.status ?? null
+			} : null,
+			plan: plan ?? null,
+			paymentMethod: {
+				hasPaymentMethod: Boolean(card.hasPaymentMethod),
+				brand: card.brand ?? null,
+				last4: card.last4 ?? null,
+				expMonth: card.expMonth ?? null,
+				expYear: card.expYear ?? null
+			}
+		});
 	} catch (e) {
 		reportError(e, "Failed to load billing");
 	}
@@ -10293,15 +11718,43 @@ function positionals(rawArgs) {
 	while (i < rest.length && rest[i].startsWith("-")) i++;
 	return rest.slice(i);
 }
+/**
+* The help page for each group, keyed by every alias the dispatch below accepts.
+*
+* Aliases are listed explicitly rather than normalised first, so a group that
+* gains one and forgets it here degrades to the index page — wrong, but a page.
+* `cloud-help.test.ts` asserts the two stay in step.
+*
+* A group absent from this map has no page of its own; the index lists it.
+*/
+var GROUP_HELP = {
+	env: printEnvHelp,
+	domains: printDomainsHelp,
+	domain: printDomainsHelp,
+	extensions: printExtensionsHelp,
+	extension: printExtensionsHelp,
+	settings: printSettingsHelp,
+	orgs: printOrgsHelp,
+	org: printOrgsHelp,
+	db: printDbHelp,
+	database: printDbHelp,
+	debug: printDebugHelp,
+	storage: printStorageHelp
+};
 async function cloudCommand(subcommand, rawArgs) {
 	initOutputMode(rawArgs);
 	const pos = positionals(rawArgs);
 	const group = pos[0] ?? (subcommand !== "--help" ? subcommand : void 0);
+	const wantsHelp = rawArgs.includes("--help") || rawArgs.includes("-h");
 	const action = pos[1];
-	if (!group || subcommand === "--help") {
+	if (!group) {
 		printCloudHelp();
 		return;
 	}
+	if (wantsHelp) {
+		(GROUP_HELP[group] ?? printCloudHelp)();
+		return;
+	}
 	switch (group) {
 		case "login":
 			await loginCommand(rawArgs);
@@ -10392,11 +11845,7 @@ async function cloudCommand(subcommand, rawArgs) {
 		case "billing":
 			await billingCommand(rawArgs);
 			break;
-		default:
-			console.error(chalk.red(`Unknown cloud command: ${group}`));
-			console.log("");
-			printCloudHelp();
-			process.exit(1);
+		default: fail(`Unknown cloud command: ${group}`, "Run `rebase cloud --help`.", "unknown_command");
 	}
 }
 async function projectsGroup(action, rawArgs) {
@@ -10409,17 +11858,15 @@ async function projectsGroup(action, rawArgs) {
 			await createProject(rawArgs);
 			break;
 		case "info":
-			await projectInfo(rawArgs, positionals(rawArgs)[2] || requireProjectRef(rawArgs));
+			await projectInfo(rawArgs, resolveProjectArg(rawArgs, "info"));
 			break;
 		case "delete":
-			await deleteProject(rawArgs, positionals(rawArgs)[2] || requireProjectRef(rawArgs));
+			await deleteProject(rawArgs, resolveProjectArg(rawArgs, "delete"));
 			break;
 		case "--help":
 			printCloudHelp();
 			break;
-		default:
-			console.error(chalk.red(`Unknown projects command: ${action}`));
-			process.exit(1);
+		default: fail(`Unknown projects command: ${action}`, "Run `rebase cloud --help`.", "unknown_command");
 	}
 }
 async function deploymentsGroup(action, rawArgs) {
@@ -10431,13 +11878,51 @@ async function deploymentsGroup(action, rawArgs) {
 		case "--help":
 			printCloudHelp();
 			break;
-		default:
-			console.error(chalk.red(`Unknown deployments command: ${action}`));
-			process.exit(1);
-	}
-}
+		default: fail(`Unknown deployments command: ${action}`, "Run `rebase cloud --help`.", "unknown_command");
+	}
+}
+/**
+* Every group `cloudCommand` dispatches, canonical name first.
+*
+* This is the index page's JSON form, and the list an agent discovers the
+* family from. `cloud-help.test.ts` holds it to the dispatch switch, so a group
+* added there without being added here is a test failure rather than a
+* command that exists but cannot be found.
+*/
+var CLOUD_GROUPS = [
+	"login",
+	"logout",
+	"whoami",
+	"link",
+	"unlink",
+	"use",
+	"open",
+	"projects",
+	"deploy",
+	"logs",
+	"deployments",
+	"rollback",
+	"cancel",
+	"start",
+	"stop",
+	"restart",
+	"status",
+	"metrics",
+	"debug",
+	"env",
+	"domains",
+	"extensions",
+	"settings",
+	"orgs",
+	"db",
+	"webhooks",
+	"storage",
+	"clusters",
+	"billing"
+];
 function printCloudHelp() {
-	console.log(`
+	emitHelp("cloud", CLOUD_GROUPS, () => {
+		console.log(`
 ${chalk.bold("rebase cloud")} — Manage your apps on Rebase Cloud
 
 ${chalk.green.bold("Usage")}
@@ -10502,6 +11987,7 @@ ${chalk.green.bold("Global options")}
 ${chalk.gray("Most commands act on the linked project (.rebase/cloud.json) unless --project is given.")}
 ${chalk.gray("Docs: https://rebase.pro/docs")}
 `);
+	});
 }
 //#endregion
 //#region src/commands/apps.ts
@@ -10534,19 +12020,20 @@ ${chalk.bold("Options")}
 `.trim());
 }
 async function appsCommand(subcommand, rawArgs = []) {
-	const args = arg({
-		"--json": Boolean,
-		"--force": Boolean,
-		"--help": Boolean,
-		"-h": "--help"
-	}, {
-		argv: rawArgs.slice(3),
-		permissive: true
-	});
-	if (args["--help"] || !subcommand || subcommand === "--help") {
+	if (!subcommand || subcommand === "--help" || wantsHelp(rawArgs)) {
 		printHelp$1();
 		return;
 	}
+	const { flags: args, positionals } = parseCommandArgs({
+		spec: {
+			"--json": Boolean,
+			"--force": Boolean
+		},
+		rawArgs,
+		commandWords: 1,
+		command: "apps",
+		maxPositionals: 2
+	});
 	switch (subcommand) {
 		case "list":
 			await listApps(Boolean(args["--json"]));
@@ -10555,7 +12042,7 @@ async function appsCommand(subcommand, rawArgs = []) {
 			await initManifest(Boolean(args["--force"]));
 			break;
 		case "config":
-			await printAppConfig(args._[1], Boolean(args["--json"]));
+			await printAppConfig(positionals[1], Boolean(args["--json"]));
 			break;
 		default:
 			console.error(chalk.red(`Unknown subcommand: ${subcommand}`));
@@ -10704,7 +12191,25 @@ function getVersion() {
 	} catch {}
 	return "unknown";
 }
+/**
+* Silence dotenv's own banner, for this process and everything it spawns.
+*
+* dotenv 17 prints `injected env (13) from .env // tip: ◈ encrypted .env
+* [www.dotenvx.com]` on every `config()` — a third-party advertisement that
+* appeared in `rebase dev`, `rebase build` and, because `rebase start` loads
+* the same way, in production server logs. `DOTENV_CONFIG_QUIET` is dotenv's
+* documented switch (`lib/main.js` reads it before `options.quiet`), and
+* setting it in `process.env` also reaches the backend, Vite and Atlas child
+* processes, which inherit it. Errors are unaffected — `quiet` gates the
+* success banner only.
+*
+* Not forced: an explicit `DOTENV_CONFIG_QUIET=false` still turns it back on.
+*/
+function silenceDotenvBanner() {
+	if (process.env.DOTENV_CONFIG_QUIET === void 0) process.env.DOTENV_CONFIG_QUIET = "true";
+}
 async function entry(args) {
+	silenceDotenvBanner();
 	const parsedArgs = arg({
 		"--version": Boolean,
 		"--help": Boolean,
@@ -10741,7 +12246,7 @@ async function entry(args) {
 		printHelp();
 		return;
 	}
-	const effectiveSubcommand = parsedArgs["--help"] ? "--help" : subcommand;
+	const effectiveSubcommand = parsedArgs["--help"] && !subcommand ? "--help" : subcommand;
 	switch (command) {
 		case "init":
 			await createRebaseApp(args);
@@ -10860,9 +12365,11 @@ ${chalk.green.bold("API Keys")}
   ${chalk.blue.bold("api-keys list")}           List all service API keys
   ${chalk.blue.bold("api-keys create")}         Create a new scoped API key
   ${chalk.blue.bold("api-keys revoke")}         Revoke an existing API key
-  ${chalk.blue.bold("telemetry")}               Anonymous usage sharing (opt-in, off by default)
   ${chalk.blue.bold("api-keys")} ${chalk.gray("--help")}         Show API key command help
 
+${chalk.green.bold("Usage sharing")}
+  ${chalk.blue.bold("telemetry")}               Anonymous usage sharing (opt-in, off by default)
+
 ${chalk.green.bold("Rebase Cloud")}
   ${chalk.blue.bold("cloud login")}             Sign in to the hosted control plane
   ${chalk.blue.bold("cloud link")}              Link this directory to a cloud project
@@ -10893,6 +12400,6 @@ function telemetryNotice() {
 	return chalk.gray(`Usage sharing: ${sharing ? "on" : "off"} — ${chalk.cyan("rebase telemetry")} to inspect or change\n`);
 }
 //#endregion
-export { CURRENT_RUNTIME_RANGE, DEFAULT_BUNDLE_DIR, DEFAULT_CONFIG_DIR, DEFAULT_CRONS_DIR, DEFAULT_FUNCTIONS_DIR, DEFAULT_SCHEMA_FILE, DEV_PORT_FILENAME, MANIFEST_FILENAME, ManifestError, TEMPLATE_PLACEHOLDER_FILES, appsCommand, assessManagedCompatibility, authCommand, buildBundle, buildCommand, buildInitQuestions, buildStaticBundle, buildableApps, cloudCommand, collectDeclaredDependencies, configureEnvFile, createRebaseApp, dbCommand, detectFrameworkDepDrift, detectNativeDependencies, detectPackageManager, detectStorageAuthorize, devCommand, doctorCommand, ejectCommand, entry, findBackendApp, findBackendDir, findEnvFile, findFrontendDir, findProjectRoot, findUnusedServerEntry, foldStaticIntoBundle, formatCdTarget, generateSdkCommand, getActiveBackendPlugin, getPMCommands, getProjectPort, isIdentifierLike, isPnpmAvailable, loadManifest, manifestExists, manifestPath, normalizeEsmSpecifiers, pnpmAvailabilityFromProbe, positionals, printInitHelp, requireBackendDir, requireProjectRoot, resetPnpmAvailabilityCache, resolveBackendPaths, resolveCliVersion, resolveExampleBaseUrl, resolveLocalBin, resolvePluginCliScript, resolveStartPort, resolveTsx, schemaCommand, startCommand, synthesizeManifest, validateManifest, validateProjectName, validateTsxInstallation, writeManifest };
+export { CURRENT_RUNTIME_RANGE, DEFAULT_BUNDLE_DIR, DEFAULT_CONFIG_DIR, DEFAULT_CRONS_DIR, DEFAULT_FUNCTIONS_DIR, DEFAULT_SCHEMA_FILE, DEV_FLAGS, DEV_PORT_FILENAME, INIT_FLAGS, MANIFEST_FILENAME, ManifestError, RESET_PASSWORD_FLAGS, TEMPLATE_PLACEHOLDER_FILES, appsCommand, assessManagedCompatibility, authCommand, buildBundle, buildCommand, buildInitQuestions, buildStaticBundle, buildableApps, cloudCommand, collectDeclaredDependencies, configureEnvFile, createRebaseApp, dbCommand, detectFrameworkDepDrift, detectNativeDependencies, detectPackageManager, detectStorageAuthorize, devCommand, doctorCommand, ejectCommand, entry, findBackendApp, findBackendDir, findEnvFile, findFrontendDir, findProjectRoot, findUnusedServerEntry, foldStaticIntoBundle, formatCdTarget, generateSdkCommand, getActiveBackendPlugin, getPMCommands, getProjectPort, isIdentifierLike, isPnpmAvailable, isPortAvailable, loadManifest, manifestExists, manifestPath, normalizeEsmSpecifiers, pnpmAvailabilityFromProbe, positionals, printInitHelp, readEnvFile, renderPayload, requireBackendDir, requireProjectRoot, resetPnpmAvailabilityCache, resolveBackendPaths, resolveCliVersion, resolveExampleBaseUrl, resolveLocalBin, resolvePluginCliScript, resolveResetPasswordArgs, resolveRuntimeImageTag, resolveStartPort, resolveTsx, schemaCommand, selectUserForEmail, startCommand, synthesizeManifest, validateManifest, validateProjectName, validateTsxInstallation, writeManifest };
 
 //# sourceMappingURL=index.es.js.map