@zitadel/cli 0.1.0 → 0.3.0

package/dist/skills-hint-N1H5-ny1.mjs

@@ -0,0 +1,4444 @@
+import consola$1, { consola } from "consola";
+import { ApiError, NetworkError, apiErrorCode, apiErrorMessage } from "@zitadel/api/runtime/fetch";
+import { createZitadelClient } from "@zitadel/api/client";
+import { stringify } from "safe-stable-stringify";
+import { copyFile, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import { PublishPolicyBody, publishPolicyBodyOneConfigMinLengthMax } from "@zitadel/api/generated/endpoints/zitadelNextGen.zod";
+import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir, release, tmpdir } from "node:os";
+import { promisify } from "node:util";
+import { BlockList, isIP } from "node:net";
+import pc from "picocolors";
+import { Agent, getGlobalDispatcher, setGlobalDispatcher } from "undici";
+import { RECOMMENDED_PASSWORD_MIN_LENGTH, brandingConfigSchema, flowConfigSchema, idpConnectionConfigSchema, policyConfigSchema, schemaConfigSchema } from "@zitadel/config/schemas";
+import { PURPOSE_FLIP_TARGETS, validateFlowDefinition, validateProject } from "@zitadel/config/validate";
+import { CUSTOM_PROVIDER, IDP_PROVIDERS, RESERVED_SLUGS, credentialVariables, idpProvider, isLoopbackIssuer, isVariableReference, missingEndpoints, parseConnectionSlug, parseDisplayName, parseIssuer, parseProviderSelection, parseScopes, referencedVariable, selectionName } from "@zitadel/config/idp";
+import { SETUP_PRESETS, getDefaultLoginFlow } from "@zitadel/config/defaults";
+import { POLICY_FILE_SCHEMA_REF } from "@zitadel/config/meta-schemas";
+import { lookup } from "node:dns/promises";
+import { validateLoginTemplate } from "@zitadel/config/template";
+import wrapAnsi from "wrap-ansi";
+import * as rosie from "rosie-skills";
+//#region src/lib/errors.ts
+/**
+* Maps each {@link ZitadelErrorCode} to the process exit code the CLI
+* returns. The table is the single source of truth for exit semantics so
+* scripts and CI can branch on stable, documented numbers.
+*/
+const EXIT_CODES = {
+	E_ALREADY_INIT: 0,
+	E_FRAMEWORK_NOT_DETECTED: 3,
+	E_UNSUPPORTED_PROJECT_SHAPE: 3,
+	E_NETWORK: 4,
+	E_AUTH: 1,
+	E_CONFLICT: 5,
+	E_LOCAL_SERVER_NOT_RUNNING: 4,
+	E_NOT_FOUND: 4,
+	E_PORT_IN_USE: 5,
+	E_VALIDATION: 3,
+	E_CREDENTIAL_MISSING: 3,
+	E_NOT_IMPLEMENTED: 2,
+	E_CANCELLED: 130
+};
+/**
+* The CLI's single error type. Carries a {@link ZitadelErrorCode} so the
+* top-level handler can derive an exit code and structured output without
+* pattern-matching on messages. Throwing this anywhere guarantees the user
+* gets a categorised, hint-bearing failure instead of a raw stack trace.
+*/
+var ZitadelError = class extends Error {
+	code;
+	hint;
+	nextCommands;
+	details;
+	constructor(code, message, opts = {}) {
+		super(message);
+		this.name = "ZitadelError";
+		this.code = code;
+		this.hint = opts.hint;
+		this.nextCommands = opts.nextCommands;
+		this.details = opts.details;
+	}
+	get exitCode() {
+		return EXIT_CODES[this.code] ?? 1;
+	}
+};
+/**
+* Normalises any thrown value into a {@link ZitadelError}. Inspection is
+* ordered most-specific-first (already-normalised, HTTP status, then
+* errno/filesystem, no response, Zod-like, generic `Error`, then a
+* catch-all) so the most actionable category and hint win. A cancelled
+* request arrives already normalised, as the `E_CANCELLED` error that
+* `./interrupt` aborts it with. This is the boundary that lets the rest
+* of the CLI `throw` plain errors yet still produce consistent, categorised
+* output. The original error shape is preserved under `details` for
+* debugging without leaking it into the user-facing message.
+*/
+function toZitadelError(error) {
+	if (error instanceof ZitadelError) return error;
+	if (error instanceof ApiError) {
+		const details = {
+			status: error.status,
+			url: error.url,
+			body: error.body
+		};
+		if (error.status === 404) {
+			if (apiErrorCode(error) === "req.not_found") return new ZitadelError("E_NOT_FOUND", `${error.url} has no such endpoint on this Zitadel server`, {
+				hint: "The server and this CLI are different versions. Run the CLI release that matches the server, or upgrade the server.",
+				details
+			});
+			return new ZitadelError("E_NOT_FOUND", !isPlatformErrorEnvelope(error.body) ? `${apiErrorMessage(error)} — ${error.url} has no such endpoint; is this a Zitadel platform API?` : apiErrorMessage(error), { details });
+		}
+		const code = error.status === 403 && error.body?.code === "proj.origin_not_allowed" ? "E_VALIDATION" : error.status === 401 || error.status === 403 ? "E_AUTH" : error.status === 409 ? "E_CONFLICT" : error.status >= 500 ? "E_NETWORK" : "E_VALIDATION";
+		const fields = listedInDetails(error.body, "fields");
+		const missing = listedInDetails(error.body, "missing");
+		const hint = [...fields.length > 0 ? [`The server rejected ${fields.length === 1 ? "this field" : "these fields"}: ${fields.join(", ")}.`] : [], ...missing.length > 0 ? [`The server reports ${missing.length === 1 ? "this endpoint" : "these endpoints"} missing: ${missing.join(", ")}.`] : []].join(" ");
+		return new ZitadelError(code, apiErrorMessage(error), {
+			...hint !== "" ? { hint } : {},
+			details
+		});
+	}
+	if (isErrnoException(error)) {
+		const details = { original: pickErrorShape(error) };
+		if (error.code === "EACCES" || error.code === "EPERM") return new ZitadelError("E_AUTH", `Permission denied: ${error.message}`, {
+			hint: "Check file permissions or run with the right user.",
+			details
+		});
+		if (error.code === "EEXIST") return new ZitadelError("E_CONFLICT", error.message, {
+			hint: "A file already exists. Use --force to overwrite or remove it first.",
+			details
+		});
+		if (error.code === "ENOENT") return new ZitadelError("E_VALIDATION", error.message, {
+			hint: "A required file or directory is missing.",
+			details
+		});
+	}
+	if (error instanceof NetworkError) return new ZitadelError("E_NETWORK", error.message, {
+		hint: error.reason === "timeout" ? "The server accepted the connection but did not answer in time. Check that it is healthy, then retry." : "Check your connection and the server URL (ZITADEL_URL or --server).",
+		details: {
+			url: error.url,
+			reason: error.reason
+		}
+	});
+	if (isZodLikeError(error)) return new ZitadelError("E_VALIDATION", errorMessage(error), { details: { issues: error.issues } });
+	if (error instanceof Error) return new ZitadelError("E_VALIDATION", error.message, { details: { original: pickErrorShape(error) } });
+	return new ZitadelError("E_VALIDATION", "Unknown error", { details: error });
+}
+/**
+* True when a response body looks like the platform's structured error
+* envelope (`{ code, message, … }`). Its presence proves the request reached
+* a real Zitadel platform API rather than an arbitrary HTTP server.
+*/
+/**
+* The names a platform error envelope lists under `key`, if any: the dotted
+* field paths it blames (`fields`), or what it reports missing (`missing`).
+*
+* The envelope nests them under `details`, and the server wraps its own
+* `details` map in the response's `details` field, so the names arrive at
+* `body.details.details.<key>`. Both depths are read: the extra wrapper is
+* the serialiser's doing rather than part of the contract, and a reader that
+* insisted on it would go silent the day it goes away.
+*/
+function listedInDetails(body, key) {
+	const seen = /* @__PURE__ */ new Set();
+	let node = body;
+	for (let depth = 0; depth < 4 && isObject$2(node); depth += 1) {
+		const listed = node[key];
+		if (Array.isArray(listed)) {
+			for (const name of listed) if (typeof name === "string" && name !== "") seen.add(name);
+		}
+		node = node.details;
+	}
+	return [...seen];
+}
+function isObject$2(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Whether a request reached a server that has no such endpoint: a 404 without
+* the platform's error envelope. A Zitadel API answers a miss it knows about
+* with the envelope, so this is a route the server does not serve, such as one
+* added in a later release.
+*/
+function isMissingEndpoint(error) {
+	return error instanceof ApiError && error.status === 404 && !isPlatformErrorEnvelope(error.body);
+}
+function isPlatformErrorEnvelope(body) {
+	return typeof body === "object" && body !== null && typeof body.code === "string";
+}
+function isErrnoException(error) {
+	return error instanceof Error && typeof error.code === "string";
+}
+function isZodLikeError(error) {
+	return typeof error === "object" && error !== null && "issues" in error && Array.isArray(error.issues);
+}
+/** Whether a caught error is the given `errno` code. */
+function isErrno$1(error, code) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function errorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	return String(error);
+}
+function pickErrorShape(error) {
+	return {
+		name: error.name,
+		message: error.message,
+		code: error.code
+	};
+}
+//#endregion
+//#region src/lib/interrupt.ts
+/**
+* Ctrl-C for the running command.
+*
+* Node exits on SIGINT only while nothing listens for it, and a spinner does
+* listen — clack's stops its animation and returns — so a request stalled
+* behind one used to outlive the keypress. Instead the command listens for
+* itself: the first Ctrl-C aborts {@link interruptSignal}, which every platform
+* request is bound to, so a waiting request rejects with `E_CANCELLED` and the
+* command unwinds through its normal error path.
+*
+* Work that is not a request does not see the signal, so the first Ctrl-C also
+* arms a short grace: a command still running when it lapses exits 130. A
+* second Ctrl-C exits at once. A command with its own handler (`logs --follow`
+* stops following) finishes inside the grace and exits as it always did.
+*/
+const GRACE_MS = 1e3;
+let controller = new AbortController();
+let grace;
+/**
+* Aborted once Ctrl-C has been pressed in the current command, and stays
+* aborted, so a caller that swallows the first rejection cannot start another
+* request.
+*/
+function interruptSignal() {
+	return controller.signal;
+}
+function onInterrupt() {
+	if (controller.signal.aborted) process.exit(130);
+	controller.abort(new ZitadelError("E_CANCELLED", "Cancelled", { hint: "The command was cancelled with Ctrl-C." }));
+	grace = setTimeout(() => process.exit(130), GRACE_MS);
+	grace.unref();
+}
+/** Starts listening as a command begins, with a signal of its own. */
+function listenForInterrupt() {
+	stopListeningForInterrupt();
+	controller = new AbortController();
+	process.on("SIGINT", onInterrupt);
+}
+/**
+* Stops listening as the command ends. Only matters when commands share a
+* process, as specs do: the grace must not outlive the command that armed it.
+*/
+function stopListeningForInterrupt() {
+	process.off("SIGINT", onInterrupt);
+	clearTimeout(grace);
+	grace = void 0;
+}
+//#endregion
+//#region src/lib/api-client.ts
+/**
+* How long one platform request may take, response body included, before it
+* fails as `E_NETWORK`. Without it a server that accepts the connection and
+* never answers holds the command for the runtime's own limit — minutes.
+*/
+const REQUEST_TIMEOUT_MS = 3e4;
+/**
+* Characters that can drive a terminal rather than print on it: the C0
+* controls (ESC among them), DEL and the C1 controls (`\p{Cc}`), the format
+* and bidi controls (`\p{Cf}`), and the line and paragraph separators. Newline
+* and tab are left alone unless the caller asks otherwise, because they are
+* how a description or a multi-line value is written.
+*/
+const CONTROL = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
+/**
+* Escape every character that could drive the reader's terminal to its
+* visible `\xNN`/`\uNNNN` spelling, or `\u{NNNNN}` above the BMP so the
+* spelling cannot run into the character that follows it.
+*
+* Anything the server returns was written by someone — a user's name, a
+* branding value, a variable — and an ESC or OSC sequence in it would
+* otherwise clear the screen, set the window title, write the clipboard
+* through OSC 52, or disguise a link through OSC 8 when printed. Ordinary text
+* is unchanged, so readable values stay readable.
+*/
+function escapeControlCharacters(text, opts = {}) {
+	const keepLayout = opts.keepLayout ?? true;
+	return text.replace(CONTROL, (char) => {
+		if (keepLayout && (char === "\n" || char === "	")) return char;
+		const code = char.codePointAt(0) ?? 0;
+		if (code <= 255) return `\\x${code.toString(16).padStart(2, "0")}`;
+		return code <= 65535 ? `\\u${code.toString(16).padStart(4, "0")}` : `\\u{${code.toString(16)}}`;
+	});
+}
+/**
+* Escape an object key. Unlike a value, a key must stay distinct from its
+* siblings: a key holding a raw ESC and one holding the literal text `\x1b`
+* would otherwise both come out as `\x1b`, and one of the two fields would be
+* lost. Doubling the backslash first makes the spelling unambiguous.
+*/
+function escapeKey(key) {
+	return escapeControlCharacters(key.replaceAll("\\", "\\\\"));
+}
+/**
+* Escape every string in a decoded JSON value, keys included, at any depth.
+* Numbers, booleans and `null` pass through untouched; the result has the
+* same shape as the input, with the same number of fields.
+*
+* The walk keeps its own work list rather than recursing. A user attribute
+* holds arbitrary JSON, and a few thousand levels of nesting — which
+* `JSON.parse` and `JSON.stringify` both accept — would otherwise exhaust the
+* call stack, letting one writer make `list` and `get` fail for every reader.
+*/
+function sanitizeResponse(value) {
+	const pending = [];
+	const copy = (item) => {
+		if (typeof item === "string") return escapeControlCharacters(item);
+		if (typeof item !== "object" || item === null) return item;
+		const target = Array.isArray(item) ? [] : {};
+		pending.push({
+			source: item,
+			target
+		});
+		return target;
+	};
+	const root = copy(value);
+	for (let next = pending.pop(); next; next = pending.pop()) {
+		const { source, target } = next;
+		if (Array.isArray(source)) {
+			for (const item of source) target.push(copy(item));
+			continue;
+		}
+		for (const [key, item] of Object.entries(source)) Object.defineProperty(target, escapeKey(key), {
+			value: copy(item),
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
+	return root;
+}
+/**
+* Rebuild a rejected call's {@link ApiError} with the server's text escaped.
+* The error envelope's `message` and `details` are printed as the failure, so
+* they are as attacker-influenceable as any response body. It stays an
+* `ApiError`, with the same status and URL, so `toZitadelError` classifies it
+* as before. Exported for `zitadel api`, which sends its requests itself.
+*/
+function sanitizeRejection(error) {
+	if (!(error instanceof ApiError)) throw error;
+	const sanitized = new ApiError(error.status, error.url, sanitizeResponse(error.body), escapeControlCharacters(error.message));
+	sanitized.stack = error.stack === void 0 ? void 0 : escapeControlCharacters(error.stack);
+	throw sanitized;
+}
+/**
+* Build the typed Zitadel client the CLI talks to the server through.
+*
+* It is `@zitadel/api`'s client with every resolved response, and every
+* server-supplied error, passed through {@link sanitizeResponse} — the approach
+* the GitHub CLI takes with go-gh's `asciisanitizer`, widened to the format
+* and bidi controls that can disguise text. Doing it once here, rather than
+* in each renderer, covers every command, table, detail view and `--json`
+* envelope, including ones not yet written; only a caller that asks for
+* {@link SanitizeOptions.verbatim} bodies escapes for itself. The shared
+* package is left raw: the console renders into a DOM, which does not
+* interpret escape codes.
+*
+* Every request is also bounded by {@link REQUEST_TIMEOUT_MS} and cancelled by
+* Ctrl-C (see `./interrupt`), unless the caller sets its own `signal` or
+* `timeoutMs`.
+*/
+function createZitadelClient$1(opts, sanitize = {}) {
+	const onResolve = sanitize.verbatim ? (value) => value : sanitizeResponse;
+	const client = createZitadelClient({
+		signal: interruptSignal(),
+		timeoutMs: REQUEST_TIMEOUT_MS,
+		...opts
+	});
+	return new Proxy(client, { get(target, prop, receiver) {
+		const value = Reflect.get(target, prop, receiver);
+		if (typeof value !== "function") return value;
+		return (...args) => {
+			const result = value(...args);
+			return result instanceof Promise ? result.then(onResolve, sanitizeRejection) : result;
+		};
+	} });
+}
+//#endregion
+//#region src/lib/json.ts
+/**
+* Serialise a value to pretty-printed JSON with object keys sorted at every
+* depth. Determinism is the point: managed files written by the CLI must be
+* byte-stable across runs so diffs stay clean and content hashes don't churn
+* when only key ordering would otherwise differ. Delegates the deterministic
+* sort to `safe-stable-stringify`, matching `JSON.stringify(value, null, 2)`
+* formatting. The `?? "null"` only applies to `undefined`/function inputs,
+* which the CLI never serialises.
+*/
+function stableStringify(value) {
+	return stringify(value, null, 2) ?? "null";
+}
+/**
+* Replace (or insert) one top-level key's value in a JSON document by
+* splicing text, leaving every other byte of the source untouched. The
+* counterpart of {@link stableStringify} for files the CLI does *not* own
+* (the user's `package.json`): blank lines, inline nested objects, key
+* order, indentation style, line endings, and the trailing newline all
+* survive, because nothing outside the spliced value is reserialized. The
+* replaced value itself is rendered at the document's detected indent (a
+* compact document stays compact).
+*
+* Defensive by construction: the result is re-parsed and compared against
+* the expected mutation, so a splice that would corrupt the document throws
+* instead of writing it.
+*/
+function setTopLevelJsonKey(source, path, key, value) {
+	const parsed = parseJsonObject(source, path);
+	const eol = source.includes("\r\n") ? "\r\n" : "\n";
+	const indent = detectIndent(source);
+	const rendered = renderValueAtDepthOne(value, indent, eol);
+	const layout = scanTopLevel(source);
+	const member = layout.members.find((candidate) => candidate.key === key);
+	let next;
+	if (member) next = `${source.slice(0, member.valueStart)}${rendered}${source.slice(member.valueEnd)}`;
+	else if (layout.members.length === 0) {
+		const inner = indent === 0 ? `${JSON.stringify(key)}:${rendered}` : `${eol}${indentString(indent)}${JSON.stringify(key)}: ${rendered}${eol}`;
+		next = `${source.slice(0, layout.open + 1)}${inner}${source.slice(layout.close)}`;
+	} else {
+		const last = layout.members.at(-1);
+		if (!last) throw new Error(`refusing to write ${path}: the JSON layout scan found no members`);
+		const inner = indent === 0 ? `,${JSON.stringify(key)}:${rendered}` : `,${eol}${indentString(indent)}${JSON.stringify(key)}: ${rendered}`;
+		next = `${source.slice(0, last.valueEnd)}${inner}${source.slice(last.valueEnd)}`;
+	}
+	const verification = parseJsonObject(next, path);
+	const expected = {
+		...parsed,
+		[key]: value
+	};
+	if (JSON.stringify(verification) !== JSON.stringify(expected)) throw new Error(`refusing to write ${path}: the targeted JSON edit did not verify`);
+	return next;
+}
+/**
+* Infers the indentation unit of a JSON document: the whitespace prefix of
+* its first indented line, a compact document stays compact (`0`), and
+* anything unrecognizable falls back to two spaces.
+*/
+function detectIndent(source) {
+	const match = source.match(/\n([ \t]+)\S/);
+	if (match?.[1]) return match[1];
+	return source.trimEnd().includes("\n") ? 2 : 0;
+}
+function indentString(indent) {
+	return typeof indent === "number" ? " ".repeat(indent) : indent;
+}
+/** Serializes a value as it should appear as a top-level member's value. */
+function renderValueAtDepthOne(value, indent, eol) {
+	if (indent === 0) return JSON.stringify(value);
+	const unit = indentString(indent);
+	return JSON.stringify(value, null, unit).split("\n").join(`${eol}${unit}`);
+}
+/**
+* Single-pass, string-aware scan of a JSON object document, collecting the
+* exact text span of every top-level member's value plus the root braces.
+* Only structural understanding needed for the splice — the document has
+* already been validated by `JSON.parse`, so this can assume well-formed
+* input and does not re-validate.
+*/
+function scanTopLevel(source) {
+	const members = [];
+	let open = -1;
+	let close = -1;
+	let depth = 0;
+	let index = 0;
+	while (index < source.length) {
+		const char = source.charAt(index);
+		if (char === "\"") {
+			const start = index;
+			index = skipString(source, index);
+			if (depth === 1 && isKeyPosition(source, start)) {
+				const key = JSON.parse(source.slice(start, index));
+				while (source[index] !== ":") index += 1;
+				index += 1;
+				while (index < source.length && isWhitespace(source.charAt(index))) index += 1;
+				const valueStart = index;
+				index = skipValue(source, index);
+				members.push({
+					key,
+					valueStart,
+					valueEnd: index
+				});
+			}
+			continue;
+		}
+		if (char === "{" || char === "[") {
+			depth += 1;
+			if (depth === 1 && open === -1) open = index;
+		} else if (char === "}" || char === "]") {
+			depth -= 1;
+			if (depth === 0) close = index;
+		}
+		index += 1;
+	}
+	return {
+		open,
+		close,
+		members
+	};
+}
+/** True when the string starting at `start` is a top-level key, not a value. */
+function isKeyPosition(source, start) {
+	for (let index = start - 1; index >= 0; index -= 1) {
+		const char = source.charAt(index);
+		if (isWhitespace(char)) continue;
+		return char === "{" || char === ",";
+	}
+	return false;
+}
+/** Returns the index just past the value starting at `index`. */
+function skipValue(source, index) {
+	const char = source.charAt(index);
+	if (char === "\"") return skipString(source, index);
+	if (char === "{" || char === "[") {
+		let depth = 0;
+		let cursor = index;
+		while (cursor < source.length) {
+			const current = source.charAt(cursor);
+			if (current === "\"") {
+				cursor = skipString(source, cursor);
+				continue;
+			}
+			if (current === "{" || current === "[") depth += 1;
+			if (current === "}" || current === "]") {
+				depth -= 1;
+				if (depth === 0) return cursor + 1;
+			}
+			cursor += 1;
+		}
+		return cursor;
+	}
+	let cursor = index;
+	while (cursor < source.length && !",}]".includes(source.charAt(cursor)) && !isWhitespace(source.charAt(cursor))) cursor += 1;
+	return cursor;
+}
+/** Returns the index just past the closing quote of the string at `index`. */
+function skipString(source, index) {
+	let cursor = index + 1;
+	while (cursor < source.length) {
+		const char = source.charAt(cursor);
+		if (char === "\\") {
+			cursor += 2;
+			continue;
+		}
+		if (char === "\"") return cursor + 1;
+		cursor += 1;
+	}
+	return cursor;
+}
+function isWhitespace(char) {
+	return char === " " || char === "	" || char === "\n" || char === "\r";
+}
+/**
+* Parse `contents` as JSON and assert the root is a plain object (not an
+* array or scalar). The CLI's config and secret files are always objects, so
+* this guards callers from the `JSON.parse` return type of `any` and produces
+* a `path`-qualified error message pointing at the offending file.
+*/
+function parseJsonObject(contents, path) {
+	const value = JSON.parse(contents);
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must contain a JSON object`);
+	return value;
+}
+/**
+* Narrows an unknown value to a plain (non-array, non-null) object. Shared by
+* the commands and the file-writer that walk parsed JSON, so the predicate
+* isn't reimplemented per call site.
+*/
+function isObject$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/lib/oclif/crud/paging.ts
+/** The list commands' own: `--all`, and `--limit` with `--page-token`. */
+const LIST_FLAGS = {
+	all: "--all",
+	onePage: "--limit and --page-token"
+};
+/**
+* Walk a cursor-paginated endpoint. `request` performs one page; the
+* response must carry the items under `items` and, while more remain, a
+* the cursor property `nextPageToken` names. With `all` the pages are drained
+* in order and `next`
+* is `null`; otherwise one page is fetched and `next` is its token. `flags`
+* names the caller's own flags in the errors.
+*/
+const collectPages = async (request, { items, all, token, nextPageToken, flags = LIST_FLAGS }) => {
+	const collected = [];
+	const seen = /* @__PURE__ */ new Set();
+	let cursor = token;
+	for (;;) {
+		const response = await request(cursor);
+		const page = items === void 0 ? response : isObject$1(response) ? response[items] : void 0;
+		if (!Array.isArray(page)) throw new ZitadelError("E_VALIDATION", items === void 0 ? "Unexpected list response: expected an array" : `Unexpected list response: missing "${items}" array`, { details: { response } });
+		collected.push(...page);
+		const cursor_ = isObject$1(response) ? response[nextPageToken] : void 0;
+		const next = typeof cursor_ === "string" ? cursor_ || null : null;
+		if (!all) return {
+			items: collected,
+			next
+		};
+		if (!next) return {
+			items: collected,
+			next: null
+		};
+		if (seen.has(next)) throw new ZitadelError("E_VALIDATION", `The server repeated a page cursor, so ${flags.all} would never finish`, {
+			hint: `Fetch one page at a time with ${flags.onePage}, and report the repeated cursor.`,
+			details: {
+				cursor: next,
+				pages_fetched: seen.size + 1
+			}
+		});
+		seen.add(next);
+		cursor = next;
+	}
+};
+//#endregion
+//#region src/lib/public-cli.ts
+const CLI_PACKAGE_NAME = "@zitadel/cli";
+function npmDistTagForCliVersion(cliVersion) {
+	return cliVersion.trim().replace(/^v/, "").match(/^\d+\.\d+\.\d+-([0-9A-Za-z][0-9A-Za-z-]*)/)?.[1] ?? "latest";
+}
+/**
+* Whether a version is one the release train publishes: a release (`0.1.0`) or
+* an alpha prerelease (`1.0.0-alpha.25`). Any other prerelease (`1.0.0-beta.2`,
+* `0.0.0-test`) has only its dist-tag to point at.
+*/
+function isTrainVersion(version) {
+	return /^\d+\.\d+\.\d+(-alpha\.\d+)?$/.test(version.trim().replace(/^v/, ""));
+}
+function npmSelectorForCliVersion(cliVersion) {
+	const normalized = cliVersion.trim().replace(/^v/, "");
+	if (isTrainVersion(normalized)) return normalized;
+	return npmDistTagForCliVersion(normalized);
+}
+/**
+* The version a scaffold writes for the `@zitadel/*` packages it adds: the
+* CLI's own exact version on the train, else its dist-tag (`beta` for
+* `1.0.0-beta.2`). The packages publish as one lockstep train, so the exact pin
+* keeps the app on the SDK that matches the files this CLI wrote, and lets
+* doctor's `dependency-version` check compare it against the CLI.
+*/
+function sdkVersionForCli(cliVersion) {
+	return npmSelectorForCliVersion(cliVersion);
+}
+/**
+* Whether a value can sit in a suggested command unquoted on every shell the
+* CLI runs under (POSIX shells, PowerShell and cmd.exe). Quoting differs
+* between them, so a value that needs quoting is not put in a suggested
+* command at all; callers hand it over as an argument list instead.
+*/
+function isPortableShellWord(value) {
+	return /^[A-Za-z0-9_./-]+$/.test(value);
+}
+/**
+* An option and its value as arguments for a suggested command. A value that
+* starts with `-` would be read as the next flag, so it is joined with `=`
+* instead. That token is not a portable shell word, so it also keeps the
+* string form out of {@link portableCommands}.
+*
+* @param option - The option, with its dashes, e.g. `--schema`.
+* @param value - The value it takes, as the user or a file name gave it.
+*/
+function optionArgs(option, value) {
+	return value.startsWith("-") ? [`${option}=${value}`] : [option, value];
+}
+function publicCliCommand(args, cliVersion) {
+	const prefix = `npx ${CLI_PACKAGE_NAME}@${npmSelectorForCliVersion(cliVersion)}`;
+	return args.length > 0 ? `${prefix} ${args}` : prefix;
+}
+function normalizePublicCliCommand(command, cliVersion) {
+	if (command === "zitadel") return publicCliCommand("", cliVersion);
+	if (command.startsWith("zitadel ")) return publicCliCommand(command.slice(8), cliVersion);
+	return command;
+}
+function normalizePublicCliCommands(commands, cliVersion) {
+	return commands?.map((command) => normalizePublicCliCommand(command, cliVersion));
+}
+/**
+* Rewrites `zitadel …` command mentions in scaffolded prose (the
+* `.zitadel/**` READMEs) to the public `npx @zitadel/cli@<version> …` form.
+*
+* The checked-in README sources stay written with the bare `zitadel`
+* command — that is the canonical, readable spelling — but the CLI is not a
+* dependency of the scaffolded app, so the bare command does not exist on
+* the user's PATH (and `npx zitadel` would fetch an unrelated npm package).
+* Covers inline code spans (`` `zitadel deploy` ``) and fenced-block lines
+* that start with `zitadel `; prose file names like `zitadel.json` and
+* `zitadel.db` don't match because the word must end the span or be
+* followed by a space.
+*/
+function normalizePublicCliProse(content, cliVersion) {
+	const prefix = publicCliCommand("", cliVersion);
+	return rewriteCliCodeSpans(content, cliVersion).replace(/^(\s*)zitadel (.*)$/gm, (_match, indent, rest) => `${indent}${prefix} ${rest}`);
+}
+/** The inline-code-span half of {@link normalizePublicCliProse}. */
+function rewriteCliCodeSpans(content, cliVersion) {
+	const prefix = publicCliCommand("", cliVersion);
+	return content.replace(/`zitadel( [^`\n]*)?`/g, (_match, args) => `\`${prefix}${args ?? ""}\``);
+}
+/**
+* Rewrites `zitadel …` command mentions inside every string of a scaffolded
+* JSON document — today the `.zitadel/meta/*.json` dialect files — returning
+* a rewritten copy. The input is never mutated: the meta-schema bodies are
+* imported JSON modules shared across calls.
+*
+* Those files are generated copies of the meta-schemas the server embeds
+* (`api/openapi/endpoints/schemas/*.json`), where the bare `zitadel` spelling
+* is the correct one — the server documents the product command, not one
+* project's install. Their `description` strings surface as editor tooltips
+* on the scaffolded `.zitadel/**` files, where the bare command does not
+* exist on the user's PATH, so the copy is normalized on the way out instead
+* of the shared source being edited (same fix PR #872 made for the READMEs).
+*
+* Unlike {@link normalizePublicCliProse} this rewrites inline code spans
+* only: a JSON `description` is prose, so a value that merely begins with
+* the word `zitadel` is a sentence, not a command line.
+*/
+function normalizePublicCliJson(value, cliVersion) {
+	if (typeof value === "string") return rewriteCliCodeSpans(value, cliVersion);
+	if (Array.isArray(value)) return value.map((item) => normalizePublicCliJson(item, cliVersion));
+	if (typeof value === "object" && value !== null) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, normalizePublicCliJson(item, cliVersion)]));
+	return value;
+}
+/** The version selector of a public `npx @zitadel/cli@<selector>` mention. */
+const PUBLIC_CLI_VERSION = new RegExp(`${CLI_PACKAGE_NAME.replaceAll("/", "\\/")}@[^\\s\`]+`, "g");
+/**
+* Replaces the version in every public CLI mention inside a JSON document
+* with `*`, so two documents {@link normalizePublicCliJson} wrote for
+* different CLI versions compare equal when nothing else differs. Returns a
+* rewritten copy.
+*/
+function maskPublicCliVersion(value) {
+	if (typeof value === "string") return value.replace(PUBLIC_CLI_VERSION, `${CLI_PACKAGE_NAME}@*`);
+	if (Array.isArray(value)) return value.map((item) => maskPublicCliVersion(item));
+	if (typeof value === "object" && value !== null) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskPublicCliVersion(item)]));
+	return value;
+}
+//#endregion
+//#region src/lib/suggestion.ts
+/** Brands a suffix built by `environmentSelectorSuffix`; nothing else calls it. */
+function asEnvironmentSelector(suffix) {
+	return suffix;
+}
+/**
+* A `zitadel` command aimed at the same project as the run that suggests it.
+* The selector is appended to `args`, so `args` must not end with a shell
+* redirection; put that after the result instead.
+*/
+function projectCommand(args, selector, cliVersion) {
+	return publicCliCommand(`${args}${selector}`, cliVersion);
+}
+/**
+* A `zitadel` command that does not target a project: `setup`, `start`,
+* `doctor`, the local runtime. Without `cliVersion` it is the bare `zitadel …`
+* spelling, which the envelope rewrites to the public `npx` form on the way
+* out; pass it when the command is also quoted in a hint.
+*/
+function unscopedCommand(args, cliVersion) {
+	return cliVersion === void 0 ? `zitadel ${args}` : publicCliCommand(args, cliVersion);
+}
+/**
+* Commands built from argument lists, for a caller that also reports the lists
+* (`next_args`). Every argument must be a portable shell word, or none is
+* returned and the lists stand alone, which no shell interprets. The lists
+* carry whatever selector the command needs: they are the arguments as run.
+*/
+function portableSuggestions(argLists, cliVersion, placeholders = []) {
+	const allowed = (word) => placeholders.includes(word) || isPortableShellWord(word);
+	if (!argLists.every((args) => args.every(allowed))) return [];
+	return argLists.map((args) => publicCliCommand(args.map((word) => placeholders.includes(word) ? `'${word}'` : word).join(" "), cliVersion));
+}
+/** A command that is not the CLI (`npm install …`, `rm …`), suggested as written. */
+function shellCommand(command) {
+	return command;
+}
+/**
+* A suggestion wrapped in shell around it: a pipe that feeds it a secret
+* (`printf '%s' "$SECRET" | `) or the `< value.txt` redirection that must
+* follow the selector. The command itself stays the one a builder made.
+*/
+function inShell(command, shell) {
+	return `${shell.before ?? ""}${command}${shell.after ?? ""}`;
+}
+//#endregion
+//#region src/lib/telemetry/dimensions/env-flag.ts
+const DISABLED_VALUES$1 = /* @__PURE__ */ new Set([
+	"",
+	"0",
+	"false",
+	"off",
+	"no"
+]);
+/**
+* Whether an environment variable is set to an enabled value. A present-but-
+* falsey string (`CI=false`, `CI=0`) counts as disabled — unlike a bare
+* `Boolean(env.CI)` check, which is true for any non-empty string.
+*/
+function envEnabled(value) {
+	return value !== void 0 && !DISABLED_VALUES$1.has(value.trim().toLowerCase());
+}
+//#endregion
+//#region src/lib/telemetry/consent.ts
+/** The cross-tool opt-out. */
+const DO_NOT_TRACK = {
+	name: "DO_NOT_TRACK",
+	flag: "telemetry",
+	description: "Any value but `0` or an empty one turns telemetry off (https://consoledonottrack.com).",
+	precedence: "Turns telemetry off even with `--telemetry`."
+};
+/** The values of {@link ZITADEL_TELEMETRY}, trimmed and lowercased, that turn telemetry off. */
+const DISABLED_VALUES = /* @__PURE__ */ new Set([
+	"",
+	"0",
+	"false",
+	"off",
+	"no"
+]);
+/** The CLI's own opt-out. */
+const ZITADEL_TELEMETRY = {
+	name: "ZITADEL_TELEMETRY",
+	flag: "telemetry",
+	description: `An empty value or one of ${[...DISABLED_VALUES].filter((value) => value !== "").map((value) => `\`${value}\``).join(", ")} turns telemetry off.`,
+	precedence: "Turns telemetry off even with `--telemetry`."
+};
+/**
+* Resolve telemetry consent under an opt-out model: on by default, but any of
+* several explicit signals turns it off, in precedence order.
+*
+* 1. `--no-telemetry` on the command line — the most explicit, per-invocation.
+* 2. `DO_NOT_TRACK` — the cross-tool standard (https://consoledonottrack.com);
+*    any value other than `0`/empty disables.
+* 3. `ZITADEL_TELEMETRY` set to a falsey token (`0`/`false`/`off`/`no`).
+* 4. An automated test run (`VITEST`/`NODE_ENV=test`) — never emit synthetic
+*    traffic or pay the shutdown flush; spawned CLI subprocesses inherit it.
+*
+* The user's own choices (1–3) come first so `reason` reports them even in a
+* test shell: the user agent reads it to decide whether to describe the
+* user's environment.
+*
+* Consent being enabled does not by itself send anything; the caller still
+* needs somewhere to send (a Mixpanel token or the Vercel copy) and fails open
+* on any transport error.
+*/
+function resolveConsent(input) {
+	if (input.flag === false) return {
+		enabled: false,
+		reason: "flag-opt-out"
+	};
+	const doNotTrack = input.env[DO_NOT_TRACK.name]?.trim();
+	if (doNotTrack && doNotTrack !== "0") return {
+		enabled: false,
+		reason: "do-not-track"
+	};
+	const explicit = input.env[ZITADEL_TELEMETRY.name]?.trim().toLowerCase();
+	if (explicit !== void 0 && DISABLED_VALUES.has(explicit)) return {
+		enabled: false,
+		reason: "env-opt-out"
+	};
+	if (input.env.VITEST || input.env.NODE_ENV === "test") return {
+		enabled: false,
+		reason: "test-runner"
+	};
+	return {
+		enabled: true,
+		reason: "enabled"
+	};
+}
+//#endregion
+//#region src/lib/telemetry/identity.ts
+/**
+* Resolve the directory the CLI persists cross-invocation state in, honoring
+* the platform conventions: `XDG_CONFIG_HOME` then `~/.config` on Unix, and
+* `%APPDATA%` on Windows. The anonymous id lives here so it survives between
+* runs without touching the user's project tree.
+*/
+function telemetryConfigDir(env) {
+	if (process.platform === "win32" && env.APPDATA) return join(env.APPDATA, "zitadel", "cli");
+	const base = env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+	return join(base, "zitadel", "cli");
+}
+/**
+* Load the persisted anonymous id, minting and storing a new one on first run.
+*
+* Fail-open: if the config dir cannot be resolved, read, or written — including
+* an `os.homedir()` throw in a restricted/containerized environment, a
+* read-only home, a CI sandbox, or a permissions error — fall back to an
+* ephemeral per-process id and report `isFirstRun: false` so we neither crash
+* nor nag the user with the notice on every run. Telemetry is best-effort,
+* never load-bearing.
+*/
+function loadOrCreateIdentity(env) {
+	let dir;
+	try {
+		dir = telemetryConfigDir(env);
+	} catch {
+		return {
+			distinctId: randomUUID(),
+			isFirstRun: false
+		};
+	}
+	const file = join(dir, "telemetry.json");
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		if (typeof parsed.distinctId === "string" && parsed.distinctId.length > 0) return {
+			distinctId: parsed.distinctId,
+			isFirstRun: false
+		};
+	} catch {}
+	const distinctId = randomUUID();
+	try {
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(file, `${JSON.stringify({ distinctId })}\n`, { mode: 384 });
+		return {
+			distinctId,
+			isFirstRun: true
+		};
+	} catch {
+		return {
+			distinctId,
+			isFirstRun: false
+		};
+	}
+}
+const ciProvider = new class CiProvider {
+	/** Provider-marker env var → reported name, in match order. */
+	static providers = [
+		["GITHUB_ACTIONS", "github_actions"],
+		["GITLAB_CI", "gitlab_ci"],
+		["CIRCLECI", "circleci"],
+		["BUILDKITE", "buildkite"],
+		["JENKINS_URL", "jenkins"]
+	];
+	value(env) {
+		const named = CiProvider.providers.find(([marker]) => envEnabled(env[marker]));
+		if (named) return named[1];
+		return envEnabled(env.CI) ? "unknown" : void 0;
+	}
+}();
+const hostAgent = new class HostAgent {
+	/** Predicate → reported name, in match order. */
+	static agents = [
+		[(env) => Boolean(env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT), "claude_code"],
+		[(env) => Boolean(env.CURSOR_TRACE_ID || env.CURSOR_AGENT), "cursor"],
+		[(env) => env.TERM_PROGRAM === "vscode", "vscode"]
+	];
+	value(env) {
+		return HostAgent.agents.find(([matches]) => matches(env))?.[1] ?? "unknown";
+	}
+}();
+//#endregion
+//#region src/lib/user-agent.ts
+/**
+* The `User-Agent` the CLI sends on every HTTP request it makes through
+* undici — the Zitadel API, local-server health checks, branding asset probes
+* — so a server (and its logs and session records) can tell CLI traffic apart
+* from any other Node client, and tell CLI versions apart. Node's `fetch`
+* otherwise sends the bare `node`.
+*
+* Space-separated `product/version` tokens (RFC 9110 §10.1.5), in the style of
+* npm and the AWS CLI, most significant first:
+*
+*     zitadel-cli/1.0.0 node/v24.12.0 darwin/24.6.0 arch/arm64 ci/github_actions host/claude_code
+*
+* `ci/` and `host/` use the vocabulary of the telemetry `ci_provider` and
+* `host_agent` dimensions. They appear only when detected, and never once the
+* user has opted out of telemetry: they describe the user's environment, so
+* the same opt-out covers them.
+*/
+const USER_AGENT_HEADER = "user-agent";
+/**
+* Consent outcomes that are the user's own choice. A test run also disables
+* telemetry, but says nothing about what the user wants reported.
+*/
+const OPT_OUT_REASONS = /* @__PURE__ */ new Set([
+	"flag-opt-out",
+	"do-not-track",
+	"env-opt-out"
+]);
+/** The {@link UserAgentFacts} of the running process. */
+function processUserAgentFacts(cliVersion, telemetryFlag) {
+	return {
+		cliVersion,
+		nodeVersion: process.version,
+		platform: process.platform,
+		osRelease: release(),
+		arch: process.arch,
+		env: process.env,
+		telemetryFlag
+	};
+}
+function buildUserAgent(facts) {
+	const tokens = [
+		product("zitadel-cli", facts.cliVersion),
+		product("node", facts.nodeVersion),
+		product(facts.platform, facts.osRelease),
+		product("arch", facts.arch)
+	];
+	const consent = resolveConsent({
+		env: facts.env,
+		flag: facts.telemetryFlag
+	});
+	if (!OPT_OUT_REASONS.has(consent.reason)) {
+		const ci = ciProvider.value(facts.env);
+		if (ci !== void 0) tokens.push(product("ci", ci));
+		const host = hostAgent.value(facts.env);
+		if (host !== "unknown") tokens.push(product("host", host));
+	}
+	return tokens.join(" ");
+}
+/**
+* One `name/version` product token. Characters outside the RFC 9110 `token`
+* set (an OS release string is free-form) become `_`, so a stray space or
+* slash can never split one token into two.
+*/
+function product(name, version) {
+	return `${sanitizeToken(name)}/${sanitizeToken(version)}`;
+}
+function sanitizeToken(value) {
+	return value.replace(/[^!#$%&'*+\-.^_`|~0-9A-Za-z]/g, "_") || "unknown";
+}
+/**
+* Stored on `globalThis`, like the dispatcher it wraps, so every copy of this
+* module in the process shares one value: with module-local state, a second
+* copy would compose a second interceptor whose stale value overwrote the
+* first's on every request.
+*/
+const SLOT = Symbol.for("@zitadel/cli/user-agent");
+function slot() {
+	const scope = globalThis;
+	scope[SLOT] ??= {};
+	return scope[SLOT];
+}
+/**
+* undici interceptor that sets the installed user agent on every request,
+* replacing whatever the caller or `fetch` put there. Exported so a module
+* that builds its own dispatcher (and so bypasses the global one) can
+* compose it; a no-op until {@link installUserAgent} runs.
+*/
+const userAgentInterceptor = (dispatch) => (options, handler) => {
+	const userAgent = slot().userAgent;
+	return dispatch(userAgent === void 0 ? options : {
+		...options,
+		headers: withUserAgent(options.headers, userAgent)
+	}, handler);
+};
+/**
+* Make every request through the global dispatcher — which is what `fetch`
+* uses, including the `@zitadel/api` client — carry `userAgent`. Composes
+* onto the existing global dispatcher, so a proxy agent installed before
+* (`NODE_USE_ENV_PROXY`) keeps working. Calling it again only replaces the
+* value, unless something has since swapped the global dispatcher out, in
+* which case the interceptor is composed onto the new one.
+*
+* Importing the `undici` package installs its own `Agent` as the global
+* dispatcher when none is set yet, so Node's bundled `fetch` dispatches
+* through the package's undici. Keep its major version on the one the
+* supported Node release bundles.
+*/
+function installUserAgent(userAgent) {
+	const state = slot();
+	state.userAgent = userAgent;
+	const current = getGlobalDispatcher();
+	if (current !== state.dispatcher) {
+		state.dispatcher = current.compose(userAgentInterceptor);
+		setGlobalDispatcher(state.dispatcher);
+	}
+}
+/**
+* Rewrite `headers` — in any of the shapes undici accepts — as a flat
+* name/value list with every existing `user-agent` dropped and `userAgent`
+* appended. The flat list keeps repeated headers intact. A malformed
+* odd-length list is returned untouched, for undici to reject.
+*/
+function withUserAgent(headers, userAgent) {
+	if (Array.isArray(headers) && headers.length % 2 !== 0) return headers;
+	const flat = [];
+	for (const [name, value] of headerEntries(headers)) {
+		if (name.toLowerCase() === USER_AGENT_HEADER) continue;
+		const values = value === void 0 ? [] : Array.isArray(value) ? value : [value];
+		for (const item of values) flat.push(name, item);
+	}
+	flat.push(USER_AGENT_HEADER, userAgent);
+	return flat;
+}
+function headerEntries(headers) {
+	if (headers == null) return [];
+	if (Array.isArray(headers)) {
+		const pairs = [];
+		for (let index = 0; index < headers.length; index += 2) pairs.push([headers[index], headers[index + 1]]);
+		return pairs;
+	}
+	if (Symbol.iterator in headers) return headers;
+	return Object.entries(headers);
+}
+//#endregion
+//#region src/lib/warnings.ts
+/**
+* Warnings reported during this invocation. The CLI runs one command per
+* process, so a module-level list is the invocation's list; `BaseCommand`
+* clears it when a command starts and drains it into the envelope when the
+* command emits.
+*/
+const reported = [];
+/**
+* Report a warning. This is the only way the CLI warns: never call
+* `consola.warn` directly (see `apps/cli/AGENTS.md`).
+*
+* A terminal shows the warning at once, which matters when it comes before a
+* long wait. `--json` silences that output, so the warning is also kept for
+* the envelope's `warnings`, and both kinds of reader see it.
+*/
+function reportWarning(message) {
+	consola.warn(message);
+	reported.push(message);
+}
+/** Take every warning reported so far, leaving none behind. */
+function takeReportedWarnings() {
+	return reported.splice(0);
+}
+//#endregion
+//#region src/lib/variables.ts
+/** The scope a variable write or delete addresses, from the project and `--preview`. */
+function variableScope(projectId, preview) {
+	return preview ? {
+		project_id: projectId,
+		kind: "preview"
+	} : { project_id: projectId };
+}
+/**
+* The scope of a read. A read names one kind, because the platform answers a
+* name with a value per kind and the two are never merged: `--preview` reads the
+* preview values, and without it the primary ones.
+*/
+function variableReadScope(projectId, preview) {
+	return {
+		project_id: projectId,
+		kind: preview ? "preview" : "primary"
+	};
+}
+/** The values of one kind in a read, keyed by name. */
+function valuesOfKind(body, kind) {
+	return Object.fromEntries(Object.entries(body).flatMap(([name, byKind]) => byKind[kind] === void 0 ? [] : [[name, byKind[kind]]]));
+}
+/**
+* Project one wire value into a row. Both endpoints answer in the same two
+* forms — a bare scalar for a non-secret, `{"secret": true}` for a secret — so
+* the collection and the single-name read share this.
+*/
+function toVariableRow(name, value) {
+	return typeof value === "object" && value !== null ? {
+		name,
+		secret: true
+	} : {
+		name,
+		secret: false,
+		value
+	};
+}
+/**
+* Project the values into rows, sorted by name so output is stable between
+* runs.
+*/
+function toVariableRows(values) {
+	return Object.entries(values).map(([name, value]) => toVariableRow(name, value)).sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Stands in for a secret's value, which the platform never discloses. */
+const SECRET_MARKER = "(secret)";
+/** Stands in for a kind the name holds no value for at all. */
+const NO_VALUE = "-";
+/**
+* Every name on the project with the primary value it holds and the preview
+* value beside it, sorted by name. A read without a kind answers both, so one
+* request covers the inventory; a name is listed when either kind holds a
+* value, so a preview-only name does not disappear (#1617).
+*/
+function toInventoryRows(body) {
+	return Object.entries(body).map(([name, byKind]) => {
+		const primary = byKind.primary === void 0 ? void 0 : toVariableRow(name, byKind.primary);
+		const preview = byKind.preview === void 0 ? void 0 : toVariableRow(name, byKind.preview);
+		return {
+			name,
+			secret: primary?.secret ?? false,
+			...primary?.value === void 0 ? {} : { value: primary.value },
+			...preview === void 0 ? {} : { preview: {
+				secret: preview.secret,
+				...preview.value === void 0 ? {} : { value: preview.value }
+			} }
+		};
+	}).sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+* {@link variableCells} plus the preview column, for the inventory. A kind the
+* name holds nothing for prints `-`: an empty cell would read as an empty
+* value, and a secret prints its marker in either column.
+*/
+function variableInventoryCells(rows) {
+	const cell = (held) => held === void 0 ? NO_VALUE : held.secret ? SECRET_MARKER : held.value === void 0 ? NO_VALUE : renderScalar(held.value);
+	return rows.map((row) => ({
+		name: row.name,
+		value: cell(row.value === void 0 && !row.secret ? void 0 : row),
+		preview: cell(row.preview)
+	}));
+}
+/**
+* Render a stored scalar for a terminal.
+*
+* A value is attacker-influenceable — anyone holding `variable.write` chooses
+* it — so it is never interpolated raw. The client already escapes what could
+* drive the terminal; this also escapes a newline and a tab, which would
+* break the table out of its own row or split a tab-separated line.
+*/
+function renderScalar(value) {
+	if (typeof value !== "string") return String(value);
+	return escapeControlCharacters(value, { keepLayout: false });
+}
+/**
+* The rows as the cells the resource commands' renderers print, one per
+* column. Those renderers print a string verbatim, so every value is escaped
+* here first: a stored value is chosen by whoever holds `variable.write`, and a
+* newline or an ESC byte must not reach the reader's terminal. A secret prints
+* a marker rather than a value — there is none to print, and an empty cell would
+* read as an empty value rather than a withheld one.
+*/
+function variableCells(rows) {
+	return rows.map((row) => ({
+		name: row.name,
+		value: row.secret ? SECRET_MARKER : renderScalar(row.value)
+	}));
+}
+/**
+* Names the platform accepts, from `variable-name.yaml`: word characters only,
+* which is exactly what the `${{ NAME }}` reference syntax can address
+* (ADR 062 §2). Checked before the patch so one bad line in a `.env` file is
+* named locally rather than failing the whole transaction at the edge.
+*/
+const VARIABLE_NAME = /^\w+$/;
+/** Longest name the same schema accepts. */
+const VARIABLE_NAME_MAX = 255;
+/** Reject a name the platform would refuse, naming it. */
+function assertVariableName(name) {
+	if (!VARIABLE_NAME.test(name)) throw new ZitadelError("E_VALIDATION", `Invalid variable name ${JSON.stringify(name)}.`, { hint: "A variable name contains only letters, digits and underscores." });
+	if (name.length > VARIABLE_NAME_MAX) throw new ZitadelError("E_VALIDATION", `Variable name is ${name.length} characters; the limit is ${VARIABLE_NAME_MAX}.`, { hint: "Shorten the name." });
+}
+/**
+* The scalar types a variable can hold — the API's JSON scalars (ADR 062 §1).
+* The server resolves `${{ NAME }}` only in an OIDC connection's `client_id`
+* and `client_secret` (`flow_sso_redirect_issuer.go`, `flow_sso_callback.go`),
+* and both must hold a string, so no reference resolves to a number or boolean
+* yet.
+*/
+const VARIABLE_TYPES = [
+	"string",
+	"number",
+	"boolean"
+];
+/**
+* A JSON number, spelled strictly. `Number()` alone would accept `0x10`, a
+* blank string, or surrounding whitespace, none of which is a number anyone
+* means when they type one.
+*/
+const JSON_NUMBER = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/;
+/**
+* Turn what was typed or piped into the scalar to store, as the type asks, or
+* say what is wrong with it. The problem carries its hint, so a caller that
+* only has the problem to show loses nothing.
+*
+* The type is stated, never guessed: an integer past 2^53 has no exact JSON
+* number, so an ID or a numeric credential would be stored with different
+* digits than were entered. It is refused rather than silently rounded.
+*/
+function parseVariableValue(raw, type) {
+	const refuse = (problem, hint) => ({
+		ok: false,
+		problem: `${problem} ${hint}`
+	});
+	switch (type) {
+		case "string": return {
+			ok: true,
+			value: raw
+		};
+		case "boolean":
+			if (raw === "true" || raw === "false") return {
+				ok: true,
+				value: raw === "true"
+			};
+			return refuse(`Expected true or false, got ${JSON.stringify(raw)}.`, "A boolean variable is exactly `true` or `false`.");
+		case "number": {
+			const value = Number(raw);
+			if (!JSON_NUMBER.test(raw) || !Number.isFinite(value)) return refuse(`Expected a number, got ${JSON.stringify(raw)}.`, "Write it as a JSON number, such as 5, -1.5 or 1e3.");
+			if (Number.isInteger(value) && !Number.isSafeInteger(value)) return refuse(`${raw} is too large to store exactly as a number.`, "Store it as a string, which keeps every digit.");
+			return {
+				ok: true,
+				value
+			};
+		}
+	}
+}
+/**
+* Read a value from stdin, for the non-interactive path
+* (`variable set NAME --secret < secret.txt`).
+*
+* A single trailing newline is stripped — a here-doc or `echo` adds one and it
+* is not part of the credential — but nothing else is trimmed, because
+* whitespace inside a value is the caller's to decide.
+*/
+async function readStdin(stream) {
+	const chunks = [];
+	for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+	return Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+}
+//#endregion
+//#region src/lib/flows/env-refs.ts
+/**
+* Collects the environment variables a flows document depends on, sorted and
+* de-duplicated. Recognises two reference styles: inline `${VAR}` interpolations
+* inside string values, and keys ending in `_env` whose value names a single
+* variable. `deploy` uses this to fail before contacting the platform when
+* a required variable is absent.
+*/
+function flowEnvRefs(value) {
+	const refs = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		if (typeof node === "string") for (const match of node.matchAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g)) {
+			const ref = match[1];
+			if (ref) refs.add(ref);
+		}
+		else if (Array.isArray(node)) node.forEach(visit);
+		else if (isObject$1(node)) for (const [key, child] of Object.entries(node)) if (key.endsWith("_env") && typeof child === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(child)) refs.add(child);
+		else visit(child);
+	};
+	visit(value);
+	return [...refs].sort();
+}
+//#endregion
+//#region src/lib/flows/sign-in.ts
+/**
+* Check what a schema change from `before` to `after` does to a flow.
+*
+* Only new errors count. A schema-rule error the flow already had is `deploy`'s
+* to report, and refusing an unrelated change because of it would block the
+* developer from an edit that might be part of the fix.
+*
+* @param flow - The flow as it is on disk.
+* @param before - The schema as it is on disk.
+* @param after - The schema as the change leaves it.
+* @param flowAfter - The flow as the change leaves it. Password and passkey
+*   never edit a flow, so it defaults to the flow itself; `auth-method sso
+*   disable` removes the provider from it.
+*/
+function checkFlow(flow, before, after, flowAfter = flow) {
+	const shape = flowConfigSchema.safeParse(flowAfter);
+	if (!shape.success) return {
+		kind: "unchecked",
+		issues: shape.error.issues.map((issue) => ({
+			severity: "error",
+			rule: "definition",
+			message: `${issue.path.join(".") || "(root)"}: ${issue.message}`
+		}))
+	};
+	const structural = validateFlowDefinition(flowAfter);
+	if (structural.length > 0) return {
+		kind: "unchecked",
+		issues: structural
+	};
+	const key = (issue) => `${issue.rule}\u0000${issue.message}`;
+	const existing = new Set(validateFlowDefinition(flow, before).filter((issue) => issue.severity === "error").map(key));
+	return {
+		kind: "checked",
+		introduced: validateFlowDefinition(flowAfter, after).filter((issue) => issue.severity === "error" && !existing.has(key(issue)))
+	};
+}
+/**
+* The sign-in methods (`password`, `passkey`, `sso`) that some active flow
+* lets an existing user sign in with.
+*
+* Only an active flow is served, so a draft offers nothing. Passkey counts
+* only through a `passkey` action: `passkey_register` enrols a new credential
+* and signs nobody in. SSO counts only through a step offering one of
+* `providers`.
+*
+* @param flows - The flows that run against the schema, whatever their status.
+* @param providers - The SSO providers the schema enables.
+*/
+function offeredSignInMethods(flows, providers) {
+	const journeys = flows.filter((flow) => flow.status === "active").map(loginJourney);
+	const offered = (signsIn) => journeys.some(signsIn);
+	return [
+		...offered(collectsPassword) ? ["password"] : [],
+		...offered(signsInWithPasskey) ? ["passkey"] : [],
+		...offered((flow) => offersSso(flow, providers)) ? ["sso"] : []
+	];
+}
+/**
+* Outcomes the engine answers by switching from login to register without a
+* `purpose` on the transition: the validator's flip table, plus
+* `sso_user_not_found`, which it leaves out of that table on purpose but
+* which routes to registration the same way.
+*/
+const LOGIN_LEAVING_OUTCOMES = /* @__PURE__ */ new Set([...Object.keys(PURPOSE_FLIP_TARGETS.login ?? {}), "sso_user_not_found"]);
+/**
+* The flow cut down to the steps reachable from its `login` entry, following
+* transitions that stay in the login purpose. No `login` purpose means no
+* steps: such a flow signs nobody in.
+*/
+function loginJourney(flow) {
+	const entry = (isObject$1(flow.purposes) ? flow.purposes : {}).login;
+	const byName = new Map(steps$1(flow).map((step) => [step.name, step]));
+	const reached = /* @__PURE__ */ new Set();
+	const queue = typeof entry === "string" ? [entry] : [];
+	while (queue.length > 0) {
+		const name = queue.shift();
+		const step = byName.get(name);
+		if (reached.has(name) || step === void 0) continue;
+		reached.add(name);
+		const transitions = isObject$1(step.transitions) ? Object.entries(step.transitions) : [];
+		for (const [outcome, transition] of transitions) {
+			if (LOGIN_LEAVING_OUTCOMES.has(outcome)) continue;
+			if (isObject$1(transition) && typeof transition.target === "string" && (transition.action === void 0 || transition.action === null) && (transition.purpose === void 0 || transition.purpose === null || transition.purpose === "login")) queue.push(transition.target);
+		}
+	}
+	return {
+		...flow,
+		steps: steps$1(flow).filter((step) => reached.has(step.name))
+	};
+}
+function steps$1(flow) {
+	return Array.isArray(flow.steps) ? flow.steps.filter(isObject$1) : [];
+}
+/** Password is field-shaped: a step collects `x-auth-methods#password`. */
+function collectsPassword(flow) {
+	return steps$1(flow).some((step) => Array.isArray(step.fields) && step.fields.includes("x-auth-methods#password"));
+}
+function signsInWithPasskey(flow) {
+	return steps$1(flow).some((step) => Array.isArray(step.actions) && step.actions.some((action) => isObject$1(action) && action.kind === "passkey"));
+}
+function offersSso(flow, providers) {
+	return steps$1(flow).some((step) => Array.isArray(step.sso_providers) && step.sso_providers.some((p) => typeof p === "string" && providers.includes(p)));
+}
+//#endregion
+//#region src/lib/flows/index.ts
+/**
+* Relative directory (from the project root) where local flow files
+* live. Owned here so callers (`commands/*`, `sync/syncers.ts`) and
+* tests share a single source of truth for the path; the runtime
+* never depends on it directly because `lib/flows` does not touch
+* the filesystem.
+*/
+const FLOWS_DIR = ".zitadel/flows";
+//#endregion
+//#region src/lib/idp/connections.ts
+/**
+* Relative directory (from the project root) where local connection files
+* live, one per provider. Owned here alongside the only reader of it, and
+* re-exported from `lib/idp` so callers and tests share one source of truth
+* for the path, as `FLOWS_DIR` and `SCHEMAS_DIR` do for their domains.
+*/
+const IDPS_DIR = ".zitadel/idps";
+/**
+* `$schema` pointer a scaffolded connection carries, relative to
+* {@link IDPS_DIR}: the meta-schema `zitadel setup` writes under
+* `.zitadel/meta/`, so an editor validates the file as it is typed.
+*/
+const CONNECTION_SCHEMA_REF = "../meta/idp-connection.json";
+/**
+* Read every connection file under `.zitadel/idps/`, in lexical order so a
+* duplicate report is stable. A missing directory reads as no connections:
+* the first provider a Project enables creates it.
+*
+* Unlike `readJsonDir`, this keeps each file's name. Every decision below is
+* reported to the developer in terms of the file they have to look at.
+*/
+async function readConnectionFiles(cwd) {
+	const dir = join(cwd, IDPS_DIR);
+	let entries;
+	try {
+		entries = await readdir(dir);
+	} catch (error) {
+		if (isErrno$1(error, "ENOENT")) return [];
+		throw error;
+	}
+	const files = [];
+	for (const name of entries.filter((e) => e.endsWith(".json")).sort()) {
+		const path = `${IDPS_DIR}/${name}`;
+		let body;
+		try {
+			body = JSON.parse(await readFile(join(dir, name), "utf8"));
+		} catch (error) {
+			throw new ZitadelError("E_VALIDATION", `${path} is not valid JSON`, {
+				hint: "Fix or remove the file, then run the command again.",
+				details: {
+					file: path,
+					parse_error: describeParseError(error)
+				}
+			});
+		}
+		if (!isObject$1(body)) throw new ZitadelError("E_VALIDATION", `${path} does not contain a JSON object`, { details: { file: path } });
+		files.push({
+			name,
+			path,
+			body
+		});
+	}
+	return files;
+}
+/**
+* What went wrong parsing a file, without the text of the file. V8 quotes the
+* source it choked on, and this file is where a pasted secret would be.
+*/
+function describeParseError(error) {
+	const position = error instanceof Error ? /position (\d+)/.exec(error.message)?.[1] : void 0;
+	return position === void 0 ? "invalid JSON" : `invalid JSON at position ${position}`;
+}
+/**
+* Whether a connection file describes the catalog entry's provider.
+*
+* `template` names the catalog entry the file was scaffolded from. When it was
+* edited away, the file still counts if it carries the catalog's own slug and
+* issuer. A different slug on the same issuer is a custom connection that
+* happens to point at the provider, which a Project may hold alongside the
+* catalog one, so the catalog provider does not claim it.
+*/
+function describesProvider(file, entry) {
+	if (file.body.template === entry.template) return true;
+	const oidc = file.body.oidc;
+	return String(file.body.slug ?? "").trim() === entry.slug && isObject$1(oidc) && oidc.issuer === entry.issuer;
+}
+/** The client id a connection file carries. */
+function clientIdOf(file) {
+	return credentialOf(file, "client_id");
+}
+/** One credential field, from the file's `oidc` block. */
+function credentialOf(file, field) {
+	const block = file.body.oidc;
+	return isObject$1(block) && typeof block[field] === "string" ? block[field] : void 0;
+}
+/**
+* The variables a connection's credentials reference, falling back to the
+* names this CLI would have written.
+*
+* A connection is editable and may name its own variables, so publishing to a
+* slug-derived name would store the credential where the connection never
+* looks and report it as stored.
+*/
+function credentialVariablesOf(file, slug) {
+	const scaffolded = slug === void 0 ? void 0 : credentialVariables(slug);
+	return {
+		clientId: named(file, "client_id", scaffolded?.clientId),
+		clientSecret: named(file, "client_secret", scaffolded?.clientSecret)
+	};
+}
+/**
+* The variable a credential field names, as the type of its fallback.
+*
+* A field absent from the file is where this command would have pointed it and
+* will point it now, so it reads as `fallback`, which is `undefined` when the
+* caller has no slug to derive one from. A field holding a literal is the value
+* itself: there is no variable behind it, and naming one would publish where
+* the connection never looks. Whatever a `client_id` field references is a
+* client id's variable, whatever it is called, which is what the brand records;
+* the type parameter keeps the two credentials from being swapped.
+*/
+function named(file, field, fallback) {
+	const value = credentialOf(file, field);
+	return value === void 0 ? fallback : referencedVariable(value);
+}
+/**
+* Stop when a connection document hands back a credential value.
+*
+* `client_secret` is always a `${{ NAME }}` reference — the syncer refuses to
+* upload anything else — so a value here is the server having resolved the
+* reference. Every path that reaches this has somewhere worse to put it than a
+* log: a plan preview prints it, and a file written from it would commit it to
+* `.zitadel/idps/`, which is the one place the secret must never reach.
+*/
+function refuseResolvedSecret(definition, id) {
+	const block = definition.oidc;
+	const stored = isObject$1(block) ? block.client_secret : void 0;
+	if (typeof stored === "string" && !isVariableReference(stored)) throw new ZitadelError("E_VALIDATION", `${id} came back holding a client_secret value`, {
+		hint: "A stored connection must keep the ${{ NAME }} reference. Report this: the endpoint is resolving secrets, and the value would be written to disk.",
+		details: {
+			id,
+			block: "oidc"
+		}
+	});
+}
+/**
+* Stop when two connections' credentials would land in the same variable.
+*
+* Two ways that happens. A slug may hold `-` and `_`
+* (`^[a-z0-9][a-z0-9_-]*$`) and the variable name replaces every
+* non-alphanumeric with `_`, so `google-work` and `google_work` both read
+* `GOOGLE_WORK_CLIENT_SECRET`. And a connection is editable, so one may simply
+* point at a name another already uses, or point both of its own credentials
+* at one name. Either way a publish overwrites what the other credential put
+* there, and the loser signs in with the wrong application — a failure that
+* surfaces at the provider, not here.
+*
+* What an existing file *references* is what counts, not what its slug would
+* derive: an `okta` connection referencing `GOOGLE_CLIENT_SECRET` collides
+* with Google however its slug reads.
+*
+* The derivation stays legible on purpose — these names get typed into
+* `variable set` by hand — so the ambiguity is refused rather than encoded
+* around.
+*
+* @param ours - The variables this run will publish to.
+* @param except - The connection being reused, which is not its own collision.
+*/
+function refuseCollidingVariables(ours, slug, files, except) {
+	if (ours.clientId !== void 0 && ours.clientId === ours.clientSecret) throw new ZitadelError("E_CONFLICT", `This connection points both credentials at ${ours.clientId}`, {
+		hint: "Give client_id and client_secret separate ${{ NAME }} references, then run the command again.",
+		details: {
+			slug,
+			variable: ours.clientId
+		}
+	});
+	for (const file of files) {
+		if (file === except) continue;
+		const theirSlug = parseConnectionSlug(String(file.body.slug ?? ""));
+		const theirs = credentialVariablesOf(file, theirSlug.ok ? theirSlug.value : void 0);
+		const shared = [ours.clientId, ours.clientSecret].find((name) => name !== void 0 && (name === theirs.clientId || name === theirs.clientSecret));
+		if (shared === void 0) continue;
+		throw new ZitadelError("E_CONFLICT", `${file.path} and ${slug} both use ${shared}`, {
+			hint: "Point one of them at a variable of its own, then run the command again.",
+			details: {
+				file: file.path,
+				slug,
+				other_slug: theirSlug.ok ? theirSlug.value : String(file.body.slug ?? ""),
+				variable: shared
+			}
+		});
+	}
+}
+/**
+* Decide whether a catalog provider already has a connection in this Project.
+*
+* Reuse is the default: a Project has one connection per provider, and a
+* second one for the same provider is nearly always an accident. Anything
+* ambiguous stops instead of guessing, because both alternatives — editing
+* the wrong connection, or silently adding a duplicate — are worse than
+* asking the developer which they meant.
+*
+* @param clientId - When given, a single match whose client id differs is a
+*   conflict rather than a reuse: the developer is pointing at a different
+*   OAuth application than the one already configured.
+*/
+function planCatalogConnection(options) {
+	const entry = options.provider;
+	const slug = entry.slug;
+	const matches = options.files.filter((file) => describesProvider(file, entry));
+	if (matches.length > 1) {
+		const names = matches.map((m) => m.path).join(", ");
+		throw new ZitadelError("E_CONFLICT", `More than one ${entry.displayName} connection exists: ${names}`, {
+			hint: "Keep the one this Project should use and remove the others, then run the command again.",
+			details: {
+				provider: slug,
+				files: matches.map((m) => m.path)
+			}
+		});
+	}
+	const [match] = matches;
+	if (match !== void 0) {
+		refuseDifferentClientId(match, options.clientId);
+		const matchSlug = parseConnectionSlug(String(match.body.slug ?? ""));
+		if (!matchSlug.ok) throw new ZitadelError("E_VALIDATION", `${match.path} is a ${entry.displayName} connection with no usable slug`, {
+			hint: "Give the connection file a slug -- the schemas and flows reference it by that name.",
+			details: {
+				file: match.path,
+				problem: matchSlug.problem
+			}
+		});
+		refuseCollidingVariables(credentialVariablesOf(match, matchSlug.value), matchSlug.value, options.files, match);
+		return {
+			action: "reuse",
+			file: match,
+			slug: matchSlug.value
+		};
+	}
+	const name = `${slug}.json`;
+	const path = `${IDPS_DIR}/${name}`;
+	const occupied = options.files.find((file) => file.name === name);
+	if (occupied !== void 0) {
+		const theirSlug = String(occupied.body.slug ?? "").trim();
+		throw new ZitadelError("E_CONFLICT", theirSlug === slug ? `${path} is a connection called ${slug}, but not to ${entry.displayName}: its issuer is not ${entry.issuer}` : `${path} already exists and its slug is ${theirSlug === "" ? "missing" : theirSlug}, not ${slug}`, {
+			hint: theirSlug === slug ? `Point it at ${entry.displayName} if it is that connection. Otherwise change its slug, in the file and in the schemas and flows that name it, then run the command again.` : `Rename or remove that file, or give it the slug ${slug} if it is the ${entry.displayName} connection, then run the command again.`,
+			details: {
+				file: path,
+				slug: occupied.body.slug ?? null
+			}
+		});
+	}
+	refuseCollidingVariables(credentialVariables(slug), slug, options.files);
+	const alsoUsesIssuer = options.files.filter((file) => isObject$1(file.body.oidc) && file.body.oidc.issuer === entry.issuer).map((file) => file.path);
+	return {
+		action: "create",
+		name,
+		path,
+		slug,
+		...alsoUsesIssuer.length > 0 ? { alsoUsesIssuer } : {}
+	};
+}
+/**
+* Stop when the developer names a client id other than the one a connection
+* already holds.
+*
+* A scaffolded connection stores `${{ NAME }}`, not an id, so there is no
+* identity in the file to disagree with and the command stays idempotent.
+* A hand-written connection may still hold a literal, and that one is
+* worth refusing: rerunning with a different id would otherwise reuse a
+* file configured for another client.
+*/
+function refuseDifferentClientId(match, clientId) {
+	const existing = clientIdOf(match);
+	const literal = existing !== void 0 && !isVariableReference(existing);
+	if (clientId !== void 0 && literal && existing !== clientId) throw new ZitadelError("E_VALIDATION", `${match.path} already uses client id ${existing}, not ${clientId}`, {
+		hint: "Edit the connection file to change its client id, or run the command without one to reuse it.",
+		details: {
+			file: match.path,
+			stored_client_id: existing,
+			supplied_client_id: clientId
+		}
+	});
+}
+/**
+* Decide what to do with a custom connection, identified by the slug the
+* developer supplied.
+*
+* Unlike {@link planConnection} this never looks at the template or the
+* issuer to find a connection: a Project may hold several connections to one
+* issuer, with different credentials or mappings, and what tells them apart
+* is the name. The slug is also what schemas and flows reference, so it is
+* the only thing that can say "the same connection".
+*
+* A slug already in use is reused only when it is the same provider — the
+* same issuer — so that repeating a command changes nothing. The same name on
+* a connection to somewhere else is somebody else's, and replacing it would
+* repoint every schema and flow that names it.
+*/
+function planCustomConnection(options) {
+	const { slug, issuer } = options.input;
+	const name = `${slug}.json`;
+	const path = `${IDPS_DIR}/${name}`;
+	const match = checkCustomSlug(options.files, slug, options.slugFlag);
+	if (match === void 0) return {
+		action: "create",
+		name,
+		path,
+		slug
+	};
+	refuseChangedIssuer(match, slug, issuer, options.slugFlag);
+	const oidc = match.body.oidc;
+	refuseDifferentClientId(match, options.clientId);
+	refuseCollidingVariables(credentialVariablesOf(match, slug), slug, options.files, match);
+	const storedScopes = isObject$1(oidc) && Array.isArray(oidc.scopes) ? oidc.scopes.join(" ") : "";
+	const notApplied = [...match.body.display_name === options.input.displayName ? [] : ["display name"], ...options.scopesGiven !== true || storedScopes === options.input.scopes.join(" ") ? [] : ["scopes"]];
+	return {
+		action: "reuse",
+		file: match,
+		slug,
+		...notApplied.length > 0 ? { notApplied } : {}
+	};
+}
+/**
+* What a custom connection's slug alone decides: the file it already names, or
+* a refusal. More than one file with the slug, or a file name the slug would
+* take that holds another connection, or variable names a new connection would
+* collide on, are all knowable before anything else about the connection is, so
+* a command can raise them as soon as it has the slug.
+*
+* @returns The single file that declares the slug, or `undefined` when the
+*   slug is free and a new connection can be created.
+*/
+function checkCustomSlug(files, slug, slugFlag) {
+	const name = `${slug}.json`;
+	const path = `${IDPS_DIR}/${name}`;
+	const holders = files.filter((file) => String(file.body.slug ?? "").trim() === slug);
+	if (holders.length > 1) throw new ZitadelError("E_CONFLICT", `More than one connection is named ${slug}: ${holders.map((h) => h.path).join(", ")}`, {
+		hint: "A slug names one connection. Remove or rename all but one, then run the command again.",
+		details: {
+			slug,
+			files: holders.map((h) => h.path)
+		}
+	});
+	const [match] = holders;
+	if (match !== void 0) return match;
+	if (files.some((file) => file.name === name)) throw new ZitadelError("E_CONFLICT", `${path} already exists and is not the ${slug} connection`, {
+		hint: `Rename or remove that file, or choose another ${slugFlag}, then run the command again.`,
+		details: {
+			file: path,
+			slug
+		}
+	});
+	refuseCollidingVariables(credentialVariables(slug), slug, files);
+}
+/**
+* Refuse an issuer other than the one an existing connection was written with.
+* An applied connection keeps its issuer, so naming another one for the same
+* slug is a conflict, raised as soon as both are known.
+*/
+function refuseChangedIssuer(file, slug, issuer, slugFlag) {
+	const oidc = file.body.oidc;
+	const existingIssuer = isObject$1(oidc) && typeof oidc.issuer === "string" ? oidc.issuer : void 0;
+	if (existingIssuer === issuer) return;
+	throw new ZitadelError("E_CONFLICT", existingIssuer === void 0 ? `${file.path} is already named ${slug} and is not an OIDC connection to ${issuer}` : `${file.path} is already named ${slug} and connects to ${existingIssuer}, not ${issuer}`, {
+		hint: `An applied connection keeps its issuer, and the server compares it exactly, so even a trailing slash names another provider. Choose another ${slugFlag} for this connection, then move the schemas and flows that name the old one to it.`,
+		details: {
+			file: file.path,
+			slug,
+			issuer,
+			existing_issuer: existingIssuer ?? null
+		}
+	});
+}
+/**
+* The display name and issuer a custom connection's file holds, as written, for
+* the ones it has. Nothing is checked here: a hand-edited file may hold
+* anything. Scopes are left out because reusing a connection never applies them.
+*/
+function storedCustomSettings(file) {
+	const oidc = file.body.oidc;
+	return {
+		...typeof file.body.display_name === "string" ? { displayName: file.body.display_name } : {},
+		...isObject$1(oidc) && typeof oidc.issuer === "string" ? { issuer: oidc.issuer } : {}
+	};
+}
+/**
+* Decide what to do with the connection for a provider in this Project.
+*
+* A catalog provider has one connection, found by what it is. Reuse is the
+* default: a second one for the same provider is nearly always an accident.
+* A custom connection is found by the slug the developer gave it, because a
+* Project may hold several connections to one issuer and the name is the only
+* thing that tells them apart.
+*
+* Anything ambiguous stops instead of guessing, because both alternatives —
+* editing the wrong connection, or silently adding a duplicate — are worse
+* than asking the developer which they meant.
+*
+* @param clientId - When given, a single match whose client id differs is a
+*   conflict rather than a reuse: the developer is pointing at a different
+*   OAuth application than the one already configured.
+*/
+function planConnection(options) {
+	const { selection, files, clientId, scopesGiven, slugFlag } = options;
+	return selection.kind === "custom" ? planCustomConnection({
+		input: selection.connection,
+		files,
+		clientId,
+		scopesGiven,
+		slugFlag
+	}) : planCatalogConnection({
+		provider: idpProvider(selection.id),
+		files,
+		clientId,
+		slugFlag
+	});
+}
+//#endregion
+//#region src/lib/idp/documents.ts
+/**
+* Enabling a provider on an existing Project edits two files: the user schema
+* gains an `sso` authentication method, and the login flow gains the steps and
+* routes a provider round trip needs.
+*
+* Both functions are pure — they take parsed documents and return new ones, so
+* the caller owns reading, writing and reporting. Both are idempotent: running
+* them again on their own output changes nothing.
+*
+* Only the regions below are ever written. Anything a developer has edited by
+* hand is left exactly as it stands and reported back, because silently
+* rewriting it would discard deliberate work.
+*/
+/**
+* Steps a flow starts at, by purpose, plus the steps that collect an
+* identifier. The provider button belongs on all of them: a developer landing
+* on the first screen expects it there, and someone who has already gone to
+* the email screen should not have to go back for it.
+*
+* On the shipped password-first flow the login entry *is* `identifier`, so
+* this is exactly `identifier` and `register` — which is what the design's
+* reference flow shows. On passkey-first it also picks up the passkey entry
+* screen, which the reference never considered.
+*/
+function providerSteps(flow) {
+	const purposes = isObject(flow.purposes) ? flow.purposes : {};
+	const names = [
+		purposes.login,
+		purposes.register,
+		"identifier",
+		"register"
+	];
+	const wanted = [];
+	for (const name of names) if (typeof name === "string" && !wanted.includes(name) && stepNamed(flow, name) !== void 0) wanted.push(name);
+	return wanted;
+}
+/**
+* The step a flow starts its login purpose at, which a transition that
+* re-purposes to `login` must target.
+*
+* The engine rejects a `purpose: "login"` transition pointing anywhere else,
+* so this cannot be hardcoded: `identifier` is only the password-first flow's
+* entry, and a passkey-first flow starts at its passkey screen.
+*/
+function loginEntry(flow) {
+	const purposes = isObject(flow.purposes) ? flow.purposes : {};
+	const named = purposes.login;
+	if (typeof named === "string" && stepNamed(flow, named) !== void 0) return named;
+	return stepNamed(flow, "identifier") !== void 0 && purposes.login !== void 0 ? "identifier" : void 0;
+}
+/** Step the engine sends a new external identity to. */
+const REGISTER_SSO = "register-sso";
+/** Step shown when the provider's email already has an account. */
+const SSO_CONFLICT = "sso-conflict";
+/** The step that asks the identified user for a password. */
+const PASSWORD_STEP = "password";
+/** Outcomes the engine fires after a provider returns, and where they go. */
+function providerOutcomes(terminal) {
+	return {
+		sso_authenticated: terminal,
+		sso_user_not_found: REGISTER_SSO,
+		user_already_exists: SSO_CONFLICT
+	};
+}
+/**
+* The step a completed sign-in ends at.
+*
+* Derived, not assumed to be called `done`. Step names are not fixed by the
+* contract — `purposes` names entry points, not terminals — and what marks a
+* terminal is the `complete` property, which both shipped flows carry. A flow
+* whose terminal is called something else was valid before this edit, and
+* writing `done` into the generated routes would point them at a step that
+* does not exist: `validateFlowDefinition` rejects that on the next `deploy`
+* ("transition ... targets unknown step"), so enabling a provider would break
+* a flow that worked.
+*
+* `undefined` when the flow has no single terminal to route to, which the
+* caller refuses rather than guesses at.
+*/
+function terminalStep(flow) {
+	const complete = steps(flow).filter((step) => step.complete !== void 0 && typeof step.name === "string");
+	if (complete.length === 1) return complete[0]?.name;
+	return stepNamed(flow, "done") === void 0 ? void 0 : "done";
+}
+function clone(value) {
+	return structuredClone(value);
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function steps(flow) {
+	return Array.isArray(flow.steps) ? flow.steps : [];
+}
+/**
+* Why this document cannot be edited for SSO, or `undefined` when it can.
+*
+* The editors below read a missing region as empty and write the generated one
+* in its place. That is right for a document that has simply not got there yet,
+* and wrong for one whose region holds something else: that value was put there
+* by hand, and replacing it is the one thing these functions promise not to do.
+* A flow whose `steps` is a string, for instance, would otherwise be read as
+* having no steps and written back with two — the hand-written value gone, and
+* nothing said about it.
+*
+* Reported rather than skipped: unlike a hand-edited step, which the caller can
+* leave alone and still produce a working flow, none of the edits can proceed
+* here, so a partial success would be a misleading thing to report.
+*/
+function ssoEditRefusal(document, target) {
+	const body = document;
+	return target === "flow" ? flowRefusal(body) : schemaRefusal(body);
+}
+function flowRefusal(flow) {
+	const providers = ssoProvidersRefusal(flow);
+	if (providers !== void 0) return providers;
+	if (terminalStep(flow) === void 0) return "no step marks where a completed sign-in ends";
+}
+/**
+* Why a flow's steps cannot be read for their provider lists, or `undefined`
+* when they can. This is all removing a provider needs
+* (`auth-method sso disable`): unlike enabling, it writes no route, so it does
+* not care where a completed sign-in ends.
+*/
+function ssoProvidersRefusal(document) {
+	const flow = document;
+	if (flow.steps !== void 0 && !Array.isArray(flow.steps)) return "steps is not a list";
+	for (const [index, step] of steps(flow).entries()) {
+		if (!isObject(step)) return `steps[${index}] is not a step`;
+		const name = typeof step.name === "string" ? step.name : String(index);
+		if (step.transitions !== void 0 && !isObject(step.transitions)) return `steps.${name}.transitions is not an object`;
+		if (step.sso_providers !== void 0 && !Array.isArray(step.sso_providers)) return `steps.${name}.sso_providers is not a list`;
+	}
+}
+function schemaRefusal(schema) {
+	const methods = schema["x-auth-methods"];
+	if (methods === void 0) return;
+	if (!isObject(methods)) return "x-auth-methods is not an object";
+	if (methods.sso === void 0) return;
+	if (!isObject(methods.sso)) return "x-auth-methods.sso is not an object";
+	if (typeof methods.sso.enabled !== "boolean") return "x-auth-methods.sso.enabled is not a boolean";
+	const providers = methods.sso.providers;
+	if (providers !== void 0 && !Array.isArray(providers)) return "x-auth-methods.sso.providers is not a list";
+}
+function stepNamed(flow, name) {
+	return steps(flow).find((step) => step.name === name);
+}
+/**
+* Enable the provider on a user schema.
+*
+* Only `x-auth-methods.sso` is touched: password and passkey configuration
+* belongs to whoever set it, and a provider is added to the list rather than
+* replacing it, so enabling a second one later keeps the first.
+*/
+function applySsoToSchema(schema, slug) {
+	const document = clone(schema);
+	const methods = isObject(document["x-auth-methods"]) ? { ...document["x-auth-methods"] } : {};
+	const existing = isObject(methods.sso) ? methods.sso : void 0;
+	const providers = Array.isArray(existing?.providers) ? [...existing.providers] : [];
+	if (existing?.enabled === true && providers.includes(slug)) return {
+		document: schema,
+		changed: false,
+		skipped: []
+	};
+	if (!providers.includes(slug)) providers.push(slug);
+	methods.sso = {
+		...existing,
+		enabled: true,
+		providers
+	};
+	document["x-auth-methods"] = methods;
+	return {
+		document,
+		changed: true,
+		skipped: []
+	};
+}
+/**
+* The properties this project collects when someone registers.
+*
+* Read from the register purpose's own entry step rather than from the schema:
+* that step is where the project decided what to ask for, and the use case
+* chosen at setup already shaped it (`minimal` asks for an email, `business`
+* also for names and a company). Taking the schema instead would collect every
+* property it defines, including ones the project deliberately does not ask
+* about.
+*
+* Credential fields are dropped. The provider is the proof for an account
+* `create_user_with_sso` creates, so the scaffold asks for no password. An
+* author who adds a password field gets it stored with the user.
+*
+* Falls back to the identifier-collecting step, and then to nothing, so a flow
+* shaped unlike the shipped one still produces a step that can collect the one
+* property the mutation cannot do without.
+*/
+function registrationFields(flow) {
+	const purposes = isObject(flow.purposes) ? flow.purposes : {};
+	const named = typeof purposes.register === "string" ? purposes.register : "register";
+	for (const name of [
+		named,
+		"register",
+		"identifier"
+	]) {
+		const step = stepNamed(flow, name);
+		const collected = (isObject(step) && Array.isArray(step.fields) ? step.fields : []).filter((field) => typeof field === "string" && !field.startsWith("x-auth-methods#"));
+		if (collected.length > 0) return collected;
+	}
+	return [];
+}
+/**
+* The step that collects what the provider did not supply.
+*
+* It asks for everything registration asks for, because a provider is not
+* obliged to supply any of it: the engine creates the account outright when
+* the claims satisfy the schema and shows this step when they do not, and a
+* step that can only collect the identifier is a dead end for every property
+* beyond it.
+*/
+function registerSsoStep(fields, terminal) {
+	return {
+		name: REGISTER_SSO,
+		fields,
+		actions: [{
+			name: "submit",
+			kind: "submit",
+			primary: true,
+			text_key: `${REGISTER_SSO}.action.submit`
+		}],
+		on_success: "create_user_with_sso",
+		transitions: {
+			submit: { target: terminal },
+			user_already_exists: { target: SSO_CONFLICT }
+		}
+	};
+}
+/**
+* The step shown when the provider's email already has an account. It offers
+* only the methods the schema actually enables — a password box on a schema
+* without passwords is a dead end.
+*/
+function ssoConflictStep(slug, methods, loginStep, terminal) {
+	const actions = [];
+	const fields = [];
+	if (methods.password) {
+		fields.push("x-auth-methods#password");
+		actions.push({
+			name: "submit",
+			kind: "submit",
+			primary: true,
+			text_key: `${SSO_CONFLICT}.action.submit`
+		});
+	}
+	if (methods.passkey) actions.push({
+		name: "passkey",
+		kind: "passkey",
+		primary: false,
+		text_key: `${SSO_CONFLICT}.action.passkey`
+	});
+	if (loginStep !== void 0) actions.push({
+		name: "sign_in",
+		kind: "navigate",
+		primary: false,
+		text_key: `${SSO_CONFLICT}.action.sign_in`
+	});
+	const transitions = {};
+	if (methods.password) transitions.submit = { target: terminal };
+	if (methods.passkey) transitions.passkey = { target: terminal };
+	transitions.sso_authenticated = { target: terminal };
+	transitions.user_already_exists = { target: SSO_CONFLICT };
+	if (loginStep !== void 0) transitions.sign_in = {
+		target: loginStep,
+		purpose: "login"
+	};
+	transitions.sso_user_not_found = { target: REGISTER_SSO };
+	return {
+		name: SSO_CONFLICT,
+		fields,
+		actions,
+		sso_providers: [slug],
+		transitions
+	};
+}
+/**
+* Whether a step is still what this generator would write for it.
+*
+* Compared key-sorted at every depth: the CLI writes its managed files with a
+* stable serialiser, so a step that has been through `setup`
+* has its keys in a different order from the object built here while being
+* the same step. Comparing the raw JSON would report the generator's own
+* output as hand-edited.
+*/
+function matches(step, expected) {
+	return canonical(withoutServerDefaults(step)) === canonical(withoutServerDefaults(expected));
+}
+/**
+* A step without what the platform leaves out when it answers.
+*
+* `setup` writes the canonical definition into the file, and the server
+* omits an action's `primary: false` (a default), an empty `fields` list, and
+* an empty `gates` map, so the step in the file is not byte for byte what this
+* generator wrote though it is the same step. Reading it as hand-edited would
+* skip the step on the next provider.
+*/
+function withoutServerDefaults(step) {
+	const copy = { ...step };
+	for (const key of ["fields", "gates"]) {
+		const value = copy[key];
+		if (Array.isArray(value) ? value.length === 0 : isObject(value) && Object.keys(value).length === 0) delete copy[key];
+	}
+	if (Array.isArray(copy.actions)) copy.actions = copy.actions.map((action) => {
+		if (!isObject(action) || action.primary !== false) return action;
+		const { primary: _default, ...rest } = action;
+		return rest;
+	});
+	return copy;
+}
+let shippedPasswordForms;
+/**
+* The password steps the shipped flows carry, one per preset, in the form
+* {@link withoutSsoRoutes} reduces any password step to. A step that reduces to
+* one of these is the one `setup` wrote, however many providers it offers.
+* The shipped steps carry no provider routes, so the terminal does not matter.
+*/
+function shippedPasswordSteps() {
+	shippedPasswordForms ??= SETUP_PRESETS.flatMap((preset) => {
+		const step = stepNamed(getDefaultLoginFlow({ preset }), PASSWORD_STEP);
+		return step === void 0 ? [] : [canonical(withoutSsoRoutes(step, "done"))];
+	});
+	return shippedPasswordForms;
+}
+/**
+* A password step without what offering providers adds to it: the provider
+* list, and the routes this generator writes for what comes back from one.
+*
+* A route that goes somewhere else is the developer's and stays, which is what
+* makes the step read as edited. The platform's own rewrite is not an edit
+* ({@link withoutServerDefaults}).
+*/
+function withoutSsoRoutes(step, terminal) {
+	const copy = { ...withoutServerDefaults(step) };
+	delete copy.sso_providers;
+	if (isObject(copy.transitions)) {
+		const written = providerOutcomes(terminal);
+		copy.transitions = Object.fromEntries(Object.entries(copy.transitions).filter(([outcome, route]) => !(outcome in written && isObject(route) && route.target === written[outcome] && Object.keys(route).length === 1)));
+	}
+	return copy;
+}
+/**
+* Whether a password step already lists the provider and carries the routes the
+* generator writes, whatever else it has been edited to say.
+*/
+function offersAlready(step, slug, terminal) {
+	if (!Array.isArray(step.sso_providers) || !step.sso_providers.includes(slug)) return false;
+	const transitions = isObject(step.transitions) ? step.transitions : {};
+	return Object.entries(providerOutcomes(terminal)).every(([outcome, target]) => {
+		const route = transitions[outcome];
+		return isObject(route) && route.target === target;
+	});
+}
+/** The provider list a step should end up with: what it has, plus this slug. */
+function mergedProviders(step, slug) {
+	const providers = Array.isArray(step.sso_providers) ? [...step.sso_providers] : [];
+	return providers.includes(slug) ? providers : [...providers, slug];
+}
+/**
+* Offer a provider on a step, keeping any already there. Returns whether the
+* step changed, so a rerun is a no-op.
+*/
+function addProvider(step, slug) {
+	const providers = Array.isArray(step.sso_providers) ? [...step.sso_providers] : [];
+	if (providers.includes(slug)) return false;
+	providers.push(slug);
+	step.sso_providers = providers;
+	return true;
+}
+/** Stable JSON: object keys sorted at every depth, arrays left in order. */
+function canonical(value) {
+	return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+	if (Array.isArray(value)) return value.map(sortKeys);
+	if (isObject(value)) return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortKeys(value[key])]));
+	return value;
+}
+/** Outcome keys the previous CLI wrote, and the names the engine now raises. */
+const LEGACY_OUTCOMES = [["callback", "sso_authenticated"], ["identity_unknown", "sso_user_not_found"]];
+/**
+* Rename the previous outcome keys on every step, in place. The validator
+* rejects the old keys, so leaving them would make `auth-method sso enable`
+* write an invalid flow. Where a step already has the new key, that one wins. A
+* key that is also one of the step's action names is the action's transition
+* and stays. A new key that is an action name is refused: the old route would
+* be dropped for the action's. A legacy key with `purpose` or `action` is
+* refused: the new keys may declare neither, and dropping them would change the
+* author's routing.
+*/
+function migrateLegacyOutcomes(document) {
+	let changed = false;
+	for (const step of steps(document)) {
+		if (!isObject(step.transitions)) continue;
+		const transitions = step.transitions;
+		const actions = Array.isArray(step.actions) ? step.actions : [];
+		const actionNames = new Set(actions.map((action) => isObject(action) ? action.name : void 0));
+		for (const [old, next] of LEGACY_OUTCOMES) {
+			if (!(old in transitions) || actionNames.has(old)) continue;
+			if (actionNames.has(next)) throw new ZitadelError("E_VALIDATION", `steps.${String(step.name)}: transition "${old}" is renamed to "${next}", which is an action on this step`, {
+				hint: `Rename the action "${next}" on step "${String(step.name)}" (and its transition), then run auth-method sso enable again.`,
+				details: {
+					step: step.name,
+					action: next
+				}
+			});
+			if (!(next in transitions)) {
+				const transition = transitions[old];
+				if (isObject(transition) && ((transition.purpose ?? null) !== null || (transition.action ?? null) !== null)) throw new ZitadelError("E_VALIDATION", `steps.${String(step.name)}: transition "${old}" declares purpose or action, which "${next}" cannot`, {
+					hint: `Remove purpose and action from the transition "${old}" on step "${String(step.name)}", then run auth-method sso enable again.`,
+					details: {
+						step: step.name,
+						transition: old
+					}
+				});
+				transitions[next] = transition;
+			}
+			delete transitions[old];
+			changed = true;
+		}
+	}
+	return changed;
+}
+/**
+* Refuse a flow where a step this command writes declares an action named like
+* an outcome key the generator writes on that step. Those names were free
+* before the rename; the generated route would silently replace the action's.
+*/
+function refuseOutcomeActionCollision(document) {
+	const outcomes = [
+		"sso_authenticated",
+		"sso_user_not_found",
+		"user_already_exists"
+	];
+	const entries = [
+		...providerSteps(document).map((name) => [name, outcomes]),
+		[SSO_CONFLICT, outcomes],
+		[REGISTER_SSO, ["user_already_exists"]],
+		["register-password", ["user_already_exists"]]
+	];
+	const written = /* @__PURE__ */ new Map();
+	for (const [name, keys] of entries) written.set(name, /* @__PURE__ */ new Set([...written.get(name) ?? [], ...keys]));
+	for (const [name, keys] of written) {
+		const step = stepNamed(document, name);
+		const actions = step !== void 0 && Array.isArray(step.actions) ? step.actions : [];
+		for (const action of actions) if (isObject(action) && typeof action.name === "string" && keys.has(action.name)) throw new ZitadelError("E_VALIDATION", `steps.${name}: action "${action.name}" uses a name auth-method sso enable writes as an outcome on this step`, {
+			hint: `Rename the action "${action.name}" on step "${name}" (and its transition), then run auth-method sso enable again.`,
+			details: {
+				step: name,
+				action: action.name
+			}
+		});
+	}
+}
+/**
+* Add the provider to a login flow.
+*
+* @param enabled - The authentication methods the target schema enables,
+*   which decide what the conflict step may offer.
+*/
+function applySsoToFlow(flow, slug, enabled) {
+	const document = clone(flow);
+	refuseOutcomeActionCollision(document);
+	const skipped = [];
+	let changed = false;
+	const terminal = terminalStep(document) ?? "done";
+	if (migrateLegacyOutcomes(document)) changed = true;
+	for (const name of providerSteps(document)) {
+		const step = stepNamed(document, name);
+		if (step === void 0) continue;
+		if (addProvider(step, slug)) changed = true;
+		const transitions = isObject(step.transitions) ? { ...step.transitions } : {};
+		for (const [outcome, target] of Object.entries(providerOutcomes(terminal))) {
+			const current = transitions[outcome];
+			if (isObject(current) && current.target === target) continue;
+			transitions[outcome] = { target };
+			changed = true;
+		}
+		step.transitions = transitions;
+	}
+	const password = stepNamed(document, PASSWORD_STEP);
+	if (password !== void 0 && !providerSteps(document).includes(PASSWORD_STEP)) {
+		if (offersAlready(password, slug, terminal)) {} else if (!shippedPasswordSteps().includes(canonical(withoutSsoRoutes(password, terminal)))) skipped.push({
+			step: PASSWORD_STEP,
+			region: `steps.${PASSWORD_STEP}`,
+			reason: "hand-edited"
+		});
+		else {
+			const offered = providerSteps(document).flatMap((name) => {
+				const entry = stepNamed(document, name);
+				return entry !== void 0 && Array.isArray(entry.sso_providers) ? entry.sso_providers : [];
+			});
+			for (const provider of /* @__PURE__ */ new Set([...offered, slug])) if (typeof provider === "string" && addProvider(password, provider)) changed = true;
+			const transitions = isObject(password.transitions) ? { ...password.transitions } : {};
+			for (const [outcome, target] of Object.entries(providerOutcomes(terminal))) {
+				const current = transitions[outcome];
+				if (!isObject(current) || current.target !== target) {
+					transitions[outcome] = { target };
+					changed = true;
+				}
+			}
+			password.transitions = transitions;
+		}
+	}
+	const registerPassword = stepNamed(document, "register-password");
+	if (registerPassword !== void 0) {
+		const transitions = isObject(registerPassword.transitions) ? { ...registerPassword.transitions } : {};
+		const current = transitions.user_already_exists;
+		if (!isObject(current) || current.target !== SSO_CONFLICT) {
+			transitions.user_already_exists = { target: SSO_CONFLICT };
+			registerPassword.transitions = transitions;
+			changed = true;
+		}
+	}
+	const list = steps(document);
+	const terminalIndex = list.findIndex((step) => step.name === terminal);
+	const insertAt = terminalIndex === -1 ? list.length : terminalIndex;
+	const wanted = [{
+		step: registerSsoStep(registrationFields(document), terminal),
+		earlier: []
+	}, {
+		step: ssoConflictStep(slug, enabled, loginEntry(document), terminal),
+		earlier: [true, false].flatMap((password) => [true, false].map((passkey) => ssoConflictStep(slug, {
+			password,
+			passkey
+		}, loginEntry(document), terminal)))
+	}];
+	let offset = 0;
+	for (const { step, earlier } of wanted) {
+		const name = step.name;
+		const existing = stepNamed(document, name);
+		if (existing === void 0) {
+			list.splice(insertAt + offset, 0, step);
+			offset += 1;
+			changed = true;
+			continue;
+		}
+		const merged = step.sso_providers === void 0 ? void 0 : mergedProviders(existing, slug);
+		const expected = merged === void 0 ? step : {
+			...step,
+			sso_providers: merged
+		};
+		const candidate = merged === void 0 ? existing : {
+			...existing,
+			sso_providers: merged
+		};
+		if (matches(candidate, expected)) {
+			if (merged !== void 0 && addProvider(existing, slug)) changed = true;
+		} else if (merged !== void 0 && earlier.some((form) => matches(candidate, {
+			...form,
+			sso_providers: merged
+		}))) {
+			list[list.indexOf(existing)] = expected;
+			changed = true;
+		} else skipped.push({
+			step: name,
+			region: `steps.${name}`,
+			reason: "hand-edited"
+		});
+	}
+	document.steps = list;
+	return changed || skipped.length > 0 ? {
+		document,
+		changed,
+		skipped
+	} : {
+		document: flow,
+		changed: false,
+		skipped
+	};
+}
+/**
+* Remove a provider from a user schema (`auth-method sso disable`, ADR 070).
+*
+* Only `x-auth-methods.sso` is touched. The provider leaves the list, and when
+* none is left `sso` becomes `{ "enabled": false }`: the meta-schema requires
+* at least one provider whenever the list is present. A provider the schema
+* does not offer is a no-op.
+*/
+function removeSsoFromSchema(schema, slug) {
+	const document = clone(schema);
+	const methods = isObject(document["x-auth-methods"]) ? { ...document["x-auth-methods"] } : {};
+	const sso = methods.sso;
+	if (!isObject(sso) || !Array.isArray(sso.providers) || !sso.providers.includes(slug)) return {
+		document: schema,
+		changed: false,
+		skipped: []
+	};
+	const providers = sso.providers.filter((provider) => provider !== slug);
+	methods.sso = providers.length === 0 ? { enabled: false } : {
+		...sso,
+		providers
+	};
+	document["x-auth-methods"] = methods;
+	return {
+		document,
+		changed: true,
+		skipped: []
+	};
+}
+/**
+* Remove a provider from every step of a login flow that offers it.
+*
+* Only the `sso_providers` lists change; a list left empty is dropped. The
+* routes and steps `auth-method sso enable` added stay: without a provider they
+* are never reached, they validate as they are, and enabling a provider again
+* uses them as they stand rather than rebuilding them.
+*/
+function removeSsoFromFlow(flow, slug) {
+	const document = clone(flow);
+	let changed = false;
+	for (const step of steps(document)) {
+		if (!Array.isArray(step.sso_providers) || !step.sso_providers.includes(slug)) continue;
+		const providers = step.sso_providers.filter((provider) => provider !== slug);
+		if (providers.length === 0) delete step.sso_providers;
+		else step.sso_providers = providers;
+		changed = true;
+	}
+	return changed ? {
+		document,
+		changed,
+		skipped: []
+	} : {
+		document: flow,
+		changed: false,
+		skipped: []
+	};
+}
+//#endregion
+//#region src/lib/idp/custom.ts
+/**
+* The flag keys the two commands define for a custom connection, once. Each
+* command builds its flag definitions from these, reads its parsed flags
+* through them, and the names a message suggests come from them, so renaming
+* one renames the flag, what is read from it, and what is suggested.
+*/
+const ENABLE_FLAG_KEYS = {
+	provider: "provider",
+	slug: "slug",
+	displayName: "display-name",
+	issuer: "issuer",
+	scopes: "scopes"
+};
+/** The `--sso-*` flags on `setup` that describe the same settings. */
+const SETUP_FLAG_KEYS = {
+	provider: "sso",
+	slug: "sso-slug",
+	displayName: "sso-display-name",
+	issuer: "sso-issuer",
+	scopes: "sso-scopes"
+};
+const flagNamesOf = (keys) => ({
+	provider: `--${keys.provider}`,
+	slug: `--${keys.slug}`,
+	displayName: `--${keys.displayName}`,
+	issuer: `--${keys.issuer}`,
+	scopes: `--${keys.scopes}`
+});
+/** The flags on `auth-method sso enable`, which a failed setup suggests running instead. */
+const ENABLE_FLAG_NAMES = flagNamesOf(ENABLE_FLAG_KEYS);
+/** The `--sso-*` flags on `setup` that describe the same settings. */
+const SETUP_FLAG_NAMES = flagNamesOf(SETUP_FLAG_KEYS);
+/**
+* What a command's parsed flags say about a custom connection. Typed by the
+* keys, so the flags a command parsed must carry them.
+*/
+function customFlagValues(flags, keys) {
+	const read = (key) => flags[key];
+	return {
+		slug: read(keys.slug),
+		displayName: read(keys.displayName),
+		issuer: read(keys.issuer),
+		scopes: read(keys.scopes)
+	};
+}
+/** The warning a loopback issuer earns on a server that cannot reach it, or `undefined`. */
+function loopbackIssuerWarning(selection, reach = "unknown") {
+	if (selection.kind !== "custom" || !isLoopbackIssuer(selection.connection.issuer) || reach === "allowed") return;
+	const { issuer } = selection.connection;
+	return reach === "container" ? `${issuer} is on this machine, but the local server runs in Docker, where localhost is the container itself, so sign-in will fail. Start the server with \`zitadel start --runtime binary\` instead.` : `${issuer} is on this machine, and a server blocks requests to localhost unless NEXTGEN_HTTPCLIENT_ALLOW_LIST allows it, so sign-in will fail until it does. A server \`zitadel start\` runs allows it by default.`;
+}
+/**
+* What a command line describing a custom connection looks like, spelled with
+* the flags the command defines, for an error or a help example to show.
+*/
+function customExample(flag, withScopes = false) {
+	return [
+		`${flag.provider} ${CUSTOM_PROVIDER}`,
+		`${flag.slug} acme-sso`,
+		`${flag.displayName} 'Acme SSO'`,
+		`${flag.issuer} https://sso.acme.example`,
+		...withScopes ? [`${flag.scopes} 'openid profile email groups'`] : []
+	].join(" ");
+}
+/** The names of the custom settings that were given, as the command spells them. */
+function givenCustomFlags(values, flag) {
+	return [
+		[flag.slug, values.slug],
+		[flag.displayName, values.displayName],
+		[flag.issuer, values.issuer],
+		[flag.scopes, values.scopes]
+	].filter(([, value]) => value !== void 0).map(([name]) => name);
+}
+/** One setting's complaint, under the flag that carried it. */
+function checkedUnder(name, parsed) {
+	if (!parsed.ok) throw new ZitadelError("E_VALIDATION", `${name}: ${parsed.problem}`, {
+		hint: `Fix ${name} and run the command again.`,
+		details: { flag: name }
+	});
+	return parsed.value;
+}
+/**
+* Check the settings that were given, and only those, naming the flag that
+* carried a bad one. For a run that will ask for the rest: a slug the server
+* would refuse is refused before the first question, as a missing client id is.
+*/
+function checkGivenCustomFlags(values, flag) {
+	if (values.slug !== void 0) checkedUnder(flag.slug, parseConnectionSlug(values.slug, RESERVED_SLUGS));
+	if (values.displayName !== void 0) checkedUnder(flag.displayName, parseDisplayName(values.displayName));
+	if (values.issuer !== void 0) checkedUnder(flag.issuer, parseIssuer(values.issuer));
+	if (values.scopes !== void 0) checkedUnder(flag.scopes, parseScopes(values.scopes));
+}
+/**
+* The provider a command line names, with its settings checked as a whole.
+*
+* A catalog provider is just its name. A custom one is described by the
+* settings that follow it, each checked against the contract the server
+* enforces on apply. Every complaint is raised here, so a caller that wants a
+* mistake named before a secret is asked for calls it before asking: being
+* turned away after typing a credential would mean typing it again. The
+* settings are flags on purpose — a name, issuer and scopes are what a script
+* or an agent supplies, and what a person can read back from their shell
+* history.
+*/
+function selectionFromFlags(provider, values, flag, example) {
+	const given = givenCustomFlags(values, flag);
+	if (provider !== CUSTOM_PROVIDER) {
+		if (given.length > 0) throw new ZitadelError("E_VALIDATION", `${given.join(", ")} only applies to a custom connection`, {
+			hint: `Add ${flag.provider} ${CUSTOM_PROVIDER}, or remove ${given.length === 1 ? "it" : "them"}.`,
+			details: { flags: given }
+		});
+		const selection = parseProviderSelection(provider);
+		if (selection === void 0) throw new ZitadelError("E_VALIDATION", `Unknown provider ${provider}`, { hint: `Use one of ${[...IDP_PROVIDERS, CUSTOM_PROVIDER].join(", ")}.` });
+		return selection;
+	}
+	const { slug, displayName, issuer } = values;
+	if (slug === void 0 || displayName === void 0 || issuer === void 0) {
+		const missing = [
+			flag.slug,
+			flag.displayName,
+			flag.issuer
+		].filter((name) => !given.includes(name));
+		throw new ZitadelError("E_VALIDATION", `A custom connection needs ${missing.join(", ")}`, {
+			hint: `Describe the connection, e.g. ${example}`,
+			details: { missing }
+		});
+	}
+	const checked = checkedUnder;
+	return {
+		kind: "custom",
+		connection: {
+			slug: checked(flag.slug, parseConnectionSlug(slug, RESERVED_SLUGS)),
+			displayName: checked(flag.displayName, parseDisplayName(displayName)),
+			issuer: checked(flag.issuer, parseIssuer(issuer)),
+			scopes: checked(flag.scopes, parseScopes(values.scopes))
+		}
+	};
+}
+/**
+* The flags that restate a custom connection, for a command offered as text.
+*
+* Suggested commands are run verbatim, so a display name with a space or a
+* metacharacter in it must arrive as one argument. Nothing here is a
+* credential: the name, issuer and scopes are the developer's own settings.
+*/
+function customFlagText(custom, flag) {
+	return flagText({
+		slug: custom.slug,
+		displayName: custom.displayName,
+		issuer: custom.issuer,
+		scopes: custom.scopes.join(" ")
+	}, flag);
+}
+/**
+* The `auth-method sso enable` arguments that add `selection` to a project:
+* the provider, and for a custom connection the settings that describe it. A
+* suggestion builder wraps them with the selector its command needs.
+*/
+function ssoEnableArgs(selection) {
+	return `auth-method sso enable --provider ${selectionName(selection)}${selection.kind === "custom" ? ` ${customFlagText(selection.connection, ENABLE_FLAG_NAMES)}` : ""}`;
+}
+/** The same for whichever settings were given, each as one shell word. */
+function flagText(values, flag) {
+	const word = (value) => /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+	return [
+		[flag.slug, values.slug],
+		[flag.displayName, values.displayName],
+		[flag.issuer, values.issuer],
+		[flag.scopes, values.scopes]
+	].flatMap(([name, value]) => value === void 0 ? [] : [`${name} ${word(value)}`]).join(" ");
+}
+//#endregion
+//#region src/lib/idp/endpoints.ts
+/**
+* Ask where a provider lives, on a development run only.
+*
+* Someone working on the CLI runs it against a local stand-in constantly, and
+* before this the connection document had to be hand-edited afterwards and
+* re-applied. Someone who installed the CLI is configuring the real vendor and
+* must never meet the question — so it is gated on `developmentBuild`
+* (`isDevelopmentBuild()`, the explicit `ZITADEL_CLI_DEV` opt-in). A published
+* CLI never sets it, so the question stays out of its `--help` and prompts.
+*
+* Returns `undefined` for a normal run and for a scripted run, and the
+* catalog's own issuer is dropped when written, so an ordinary run produces
+* the document it would if none of this existed.
+*/
+async function askConnectionEndpoints(options) {
+	const { provider, developmentBuild, ask } = options;
+	if (!developmentBuild) return;
+	return { issuer: await ask({
+		kind: "text",
+		name: "issuer",
+		message: "What is the issuer URL of the provider?",
+		parse: parseIssuer,
+		initialValue: idpProvider(provider).issuer
+	}) };
+}
+//#endregion
+//#region src/lib/idp/credentials.ts
+/**
+* Publish a client secret to the project.
+*
+* Nothing is written to disk. The value is a credential, the project stores it
+* encrypted under the project's own key (ADR 029), and no runtime reads it
+* from the environment — the token exchange happens on the server. A copy in
+* `.env.local` would be a credential sitting in the working tree for the
+* convenience of nobody, and one `git add -A` away from being published.
+*
+* Passing no value publishes nothing and is not an error: the developer may
+* intend to publish it themselves.
+*/
+async function storeClientSecret(options) {
+	const { name, value, publish } = options;
+	if (value === void 0) return {
+		name,
+		published: "deferred"
+	};
+	return {
+		name,
+		published: await publishSecret(publish, name, value)
+	};
+}
+/**
+* Publish the connection's client id.
+*
+* An ordinary variable, not a secret: the id travels in the browser's
+* authorize URL, so it is public by construction and hiding it would only cost
+* the developer the ability to read back what was configured.
+*/
+async function publishClientId(options) {
+	return publishSecret(options.publish, options.name, options.value, false);
+}
+/**
+* Send the value to the project, reporting a refusal instead of raising it.
+*
+* By the time this runs the connection document is already on disk and, in
+* `setup`, the whole project is provisioned. Failing the command there would
+* leave the developer with a half-written Project to clean up over something
+* one later command fixes, so the caller warns and points at `variable set`.
+*/
+async function publishSecret(publish, name, value, secret = true) {
+	if (publish === void 0) return "deferred";
+	try {
+		await publish(name, value, { secret });
+		return "stored";
+	} catch (error) {
+		consola.debug(`Publishing ${name} to the project failed`, error);
+		return "failed";
+	}
+}
+/**
+* The `variable set` arguments that publish one credential to the project.
+*
+* Without `--preview` the write takes the platform's default: a client id,
+* which is not secret, is stored for both kinds, and a client secret for the
+* primary kind only. The engine resolves a connection's `${{ NAME }}` from the
+* project's own variables.
+*/
+function republishArgsFor(name, secret) {
+	return [
+		"variable",
+		"set",
+		name,
+		...secret ? ["--secret"] : []
+	];
+}
+/**
+* The command that puts a credential the project never received where the
+* connection looks for it.
+*
+* Shared so the warning printed to a terminal and the `next_commands` a JSON
+* run reports cannot drift apart — a JSON run prints no warnings at all, so
+* that list is the only place the recovery step appears.
+*/
+function republishCommand(name, secret, cliVersion, selector) {
+	return projectCommand(republishArgsFor(name, secret).join(" "), selector, cliVersion);
+}
+/**
+* The arguments that finish the job for every credential the project did not
+* receive — empty in the ordinary case, where both were stored.
+*
+* Argument lists rather than command strings, for a caller that also reports
+* them as `next_args`; {@link republishCommands} is built from this, so the
+* two forms list the same commands.
+*
+* @param credentials - Each credential of the run and what became of it.
+* @param extraArgs - Appended to every command, such as the `--cwd` the run
+*   was given, so the recovery reaches the same Project.
+*/
+function republishArgs(credentials, extraArgs = []) {
+	return credentials.flatMap(({ name, secret, published }) => name !== void 0 && published !== void 0 && published !== "stored" ? [[...republishArgsFor(name, secret), ...extraArgs]] : []);
+}
+/**
+* {@link republishArgs} as commands to run.
+*
+* Built for a run that prints nothing: with `--json` consola is disabled, so
+* the warnings above never appear and this list is the only place the recovery
+* step is stated.
+*/
+function republishCommands(credentials, cliVersion, selector) {
+	return republishArgs(credentials).map((args) => projectCommand(args.join(" "), selector, cliVersion));
+}
+/**
+* Say whether the project received a credential, and how to retry when it did
+* not. Shared by both credentials, because the project is the destination that
+* decides whether sign-in works and the wording should not drift between them.
+*
+* `noValue` separates the two ways a publish can be deferred: nothing was
+* supplied, or there was no project to publish to. They read the same to the
+* code and call for different things from the developer.
+*/
+function reportPublished(name, state, republish, noValue) {
+	switch (state) {
+		case "stored":
+			consola.success(`Published ${name} to the project`);
+			break;
+		case "deferred":
+			reportWarning(noValue ? `${name} has no value yet. Publish it with: ${republish}` : `${name} was not published to the project. Publish it with: ${republish}`);
+			break;
+		case "failed": reportWarning(`${name} could not be published. Sign-in fails until it is: ${republish}`);
+	}
+}
+/** Tell the developer what became of the secret. */
+function reportSecretOutcome(outcome, cliVersion, noValue, selector) {
+	reportPublished(outcome.name, outcome.published, republishCommand(outcome.name, true, cliVersion, selector), noValue);
+}
+/**
+* Tell the developer what became of the client id.
+*
+* A missing one is never "no value yet": the command refuses without a client
+* id, so the only way here is a project it could not reach.
+*/
+function reportClientIdOutcome(name, state, cliVersion, selector) {
+	reportPublished(name, state, republishCommand(name, false, cliVersion, selector), false);
+}
+//#endregion
+//#region src/lib/user-schema/index.ts
+/**
+* Public surface for the user-schema domain. Every caller outside this
+* module imports from here (not from individual files), the same
+* discipline as `lib/flows/`.
+*
+* **Source of truth.** The wire shape lives in
+* `@zitadel/api/generated/model` (orval-generated from the
+* OpenAPI spec). Callers that need the type import `CreateSchemaBody`
+* from there directly; callers that need the runtime validator import
+* the matching Zod schema from
+* `@zitadel/api/generated/endpoints/zitadelNextGen.zod`. The default
+* schema/flow bodies the CLI scaffolds are composed in
+* `@zitadel/config/defaults` (`getDefaultHumanUserSchema`) — the single
+* source of field defaults.
+*
+* **Dependency rule.** No upward imports (`commands/`, `sync/`, etc.)
+* and no filesystem I/O. Reading and writing local files is the
+* caller's responsibility, served by `apps/cli/src/lib/json-dir.ts`
+* plus this module's {@link SCHEMAS_DIR} constant.
+*/
+/**
+* Relative directory (from the project root) where local user-schema
+* files live. Owned here so callers (`commands/*`, `sync/syncers.ts`)
+* and tests share a single source of truth for the path; the runtime
+* never depends on it directly because `lib/user-schema` does not touch
+* the filesystem. The counterpart of `lib/flows`' `FLOWS_DIR`.
+*/
+const SCHEMAS_DIR = ".zitadel/schemas";
+//#endregion
+//#region src/lib/idp/schemas.ts
+/**
+* The authentication methods a schema document enables, sorted: every entry
+* under `x-auth-methods` whose `enabled` is `true`. What the login engine can
+* actually serve is narrower, and is the caller's to decide.
+*/
+function methodsOf(body) {
+	const methods = body["x-auth-methods"];
+	if (!isObject$1(methods)) return [];
+	return Object.entries(methods).filter(([, value]) => isObject$1(value) && value.enabled === true).map(([name]) => name).sort();
+}
+/**
+* Read the Project's user schemas.
+*
+* READMEs sit in the same directory, so only `.json` files count. A schema
+* that cannot be parsed stops the command: enabling a provider edits these
+* files, and editing one we could not read is how a working setup gets
+* corrupted.
+*/
+async function readSchemaFiles(cwd) {
+	const dir = join(cwd, SCHEMAS_DIR);
+	let entries;
+	try {
+		entries = await readdir(dir);
+	} catch (error) {
+		if (isErrno$1(error, "ENOENT")) return [];
+		throw error;
+	}
+	const files = [];
+	for (const entry of entries.filter((e) => e.endsWith(".json")).sort()) {
+		const path = `${SCHEMAS_DIR}/${entry}`;
+		let body;
+		try {
+			body = JSON.parse(await readFile(join(dir, entry), "utf8"));
+		} catch (error) {
+			throw new ZitadelError("E_VALIDATION", `${path} is not valid JSON`, {
+				hint: "Fix the file, then run the command again.",
+				details: {
+					file: path,
+					parse_error: String(error)
+				}
+			});
+		}
+		if (!isObject$1(body)) throw new ZitadelError("E_VALIDATION", `${path} does not contain a JSON object`, { details: { file: path } });
+		files.push({
+			name: basename(entry, ".json"),
+			path,
+			properties: isObject$1(body.properties) ? Object.keys(body.properties) : [],
+			methods: methodsOf(body),
+			body
+		});
+	}
+	return files;
+}
+/**
+* Pick the schema to change.
+*
+* One schema is the common case and is chosen without asking. Several is
+* ambiguous, and picking silently would edit the wrong user type, so the name
+* has to be given — the interactive picker is the caller's, because this
+* module does not prompt.
+*/
+function selectSchema(files, requested) {
+	if (files.length === 0) throw new ZitadelError("E_NOT_FOUND", `This Project has no user schema under ${SCHEMAS_DIR}`, { hint: "Run `zitadel setup` first." });
+	if (requested !== void 0) {
+		const wanted = requested.endsWith(".json") ? basename(requested, ".json") : requested;
+		const match = files.find((file) => file.name === wanted);
+		if (match === void 0) throw new ZitadelError("E_NOT_FOUND", `This Project has no user schema named ${wanted}`, {
+			hint: `Known schemas: ${files.map((f) => f.name).join(", ")}`,
+			details: {
+				requested: wanted,
+				known: files.map((f) => f.name)
+			}
+		});
+		return match;
+	}
+	const [only, ...rest] = files;
+	if (rest.length > 0 || only === void 0) throw new ZitadelError("E_VALIDATION", "This Project has more than one user schema", {
+		hint: `Name the one to change with --schema. Known schemas: ${files.map((f) => f.name).join(", ")}`,
+		details: { known: files.map((f) => f.name) }
+	});
+	return only;
+}
+/**
+* Read the Project's flow files.
+*
+* A flow names the schema it runs against, so the caller can pick the ones
+* belonging to the schema being changed rather than editing every flow.
+*/
+async function readFlowFiles(cwd) {
+	const dir = join(cwd, FLOWS_DIR);
+	let entries;
+	try {
+		entries = await readdir(dir);
+	} catch (error) {
+		if (isErrno$1(error, "ENOENT")) return [];
+		throw error;
+	}
+	const files = [];
+	for (const entry of entries.filter((e) => e.endsWith(".json")).sort()) {
+		const path = `${FLOWS_DIR}/${entry}`;
+		let body;
+		try {
+			body = JSON.parse(await readFile(join(dir, entry), "utf8"));
+		} catch (error) {
+			throw new ZitadelError("E_VALIDATION", `${path} is not valid JSON`, {
+				hint: "Fix the file, then run the command again.",
+				details: {
+					file: path,
+					parse_error: String(error)
+				}
+			});
+		}
+		if (!isObject$1(body)) throw new ZitadelError("E_VALIDATION", `${path} does not contain a JSON object`, { details: { file: path } });
+		files.push({
+			name: basename(entry, ".json"),
+			path,
+			body
+		});
+	}
+	return files;
+}
+/**
+* Read the enabled methods straight off a schema document.
+*
+* Setup composes its schema in memory and never reads it back from disk, so
+* it needs this before a {@link SchemaFile} exists.
+*/
+function authMethods(body) {
+	const enabled = methodsOf(body);
+	return {
+		password: enabled.includes("password"),
+		passkey: enabled.includes("passkey")
+	};
+}
+/** Whether a schema file enables a given authentication method. */
+function enabledMethods(schema) {
+	return {
+		password: schema.methods.includes("password"),
+		passkey: schema.methods.includes("passkey")
+	};
+}
+//#endregion
+//#region src/lib/oclif/groups.ts
+/**
+* The groups the root help lists commands under, declared in print order and
+* named for what a developer is trying to do: get going, work against a local
+* server, manage who can sign in and how, change the project's configuration,
+* or check on it. Every command declares its own group (`static group` on the
+* class) so nothing has to be registered centrally; oclif's own utilities
+* (`autocomplete`, `search`, …) declare none and are listed with the last group.
+*/
+const CommandGroups = {
+	gettingStarted: "Getting started",
+	localDevelopment: "Local development",
+	usersAndTeams: "Users and teams",
+	authentication: "Authentication",
+	configuration: "Configuration and releases",
+	diagnostics: "Diagnostics and utilities"
+};
+const COMMAND_GROUPS = Object.values(CommandGroups);
+/**
+* The order within a group, which the root help and the docs' CLI reference
+* (`./reference`) share: `groupOrder` first, lowest first, then the command id.
+*/
+function compareInGroup(a, b) {
+	return (a.groupOrder ?? Number.MAX_SAFE_INTEGER) - (b.groupOrder ?? Number.MAX_SAFE_INTEGER) || a.id.localeCompare(b.id);
+}
+//#endregion
+//#region src/lib/local-files.ts
+/**
+* Local file references in `.zitadel/` resource files.
+*
+* Wherever the OpenAPI YAML marks a string field `x-local: file`, the
+* generated editor meta-schema accepts `{ "$file": "<path>" }` in its place,
+* so a long value such as a login template lives in its own file instead of a
+* JSON-escaped string. The API never sees a reference: before upload every
+* one is replaced by the referenced file's content.
+*
+* Resolution is generic. Nothing here knows which fields may carry a
+* reference; the Zod gate and the editor schema decide that.
+*
+* Paths are relative to the directory of the resource file that holds them
+* and must stay inside the project, because upload reads them. The check
+* applies to the real target: a symlink, or a symlinked directory on the way,
+* that leads outside the project is refused.
+*/
+const FILE_REFERENCE_KEY = "$file";
+const omittedReference = Symbol("omittedReference");
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function isErrno(error, code) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+/** A file's content, or undefined when it is absent. */
+function readIfPresent(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (isErrno(error, "ENOENT") || isErrno(error, "ENOTDIR")) return;
+		throw error;
+	}
+}
+function readFileReference(path, ref, options) {
+	let content;
+	try {
+		content = readIfPresent(path);
+	} catch {
+		throw new ZitadelError("E_VALIDATION", `$file ${JSON.stringify(ref)} cannot be read`, { hint: "Create the referenced file or fix the path." });
+	}
+	if (content !== void 0) return content;
+	if (options.onMissing === "omit") return omittedReference;
+	throw new ZitadelError("E_VALIDATION", `$file ${JSON.stringify(ref)} cannot be read`, { hint: "Create the referenced file or fix the path." });
+}
+/** Whether `path` is `root` itself or lies beneath it. */
+function isWithin(root, path) {
+	const rel = relative(root, path);
+	return !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel));
+}
+/** Whether `path` itself is a symlink, without following it. */
+function isSymlink(path) {
+	try {
+		return lstatSync(path).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+/**
+* `path` with every symlink resolved, symlinked parent directories included,
+* even when its last segments do not exist yet. Undefined when a segment is a
+* symlink that resolves nowhere, since what it names could be anywhere.
+*/
+function realTarget(path) {
+	const missing = [];
+	let current = path;
+	for (;;) try {
+		return join(realpathSync(current), ...missing);
+	} catch (error) {
+		if (!isErrno(error, "ENOENT") && !isErrno(error, "ENOTDIR")) throw error;
+		if (isSymlink(current)) return;
+		const parent = dirname(current);
+		if (parent === current) return path;
+		missing.unshift(basename(current));
+		current = parent;
+	}
+}
+/** A `{ "$file": "<path>" }` object and nothing else. */
+function isFileReference(value) {
+	return isPlainObject(value) && Object.keys(value).length === 1 && typeof value["$file"] === "string";
+}
+/**
+* The absolute path a reference points at. E_VALIDATION when the path, or the
+* real target behind any symlink on the way, leaves the project.
+*/
+function resolveFileReference(context, ref) {
+	const absolute = resolve(context.cwd, context.baseDir, ref);
+	const root = realTarget(resolve(context.cwd));
+	const target = realTarget(absolute);
+	if (!(isWithin(resolve(context.cwd), absolute) && root !== void 0 && target !== void 0 && isWithin(root, target))) throw new ZitadelError("E_VALIDATION", `$file ${JSON.stringify(ref)} points outside the project`, { hint: "Keep referenced files inside the project, next to the file that references them; a symlink on the way must resolve inside the project too." });
+	return absolute;
+}
+/** Every reference in `document`, with the path that leads to it. */
+function findFileReferences(document) {
+	const found = [];
+	const walk = (node, path) => {
+		if (isFileReference(node)) found.push({
+			path,
+			ref: node[FILE_REFERENCE_KEY]
+		});
+		else if (Array.isArray(node)) node.forEach((item, index) => {
+			walk(item, [...path, index]);
+		});
+		else if (isPlainObject(node)) for (const [key, value] of Object.entries(node)) walk(value, [...path, key]);
+	};
+	walk(document, []);
+	return found;
+}
+/**
+* Returns a copy of `document` with every reference replaced by the content
+* of the file it points at. With `onMissing: "throw"` an unreadable file is
+* E_VALIDATION, which is what plan's gate wants; with `"omit"` the value is
+* dropped instead (the key from an object, the element from an array), so
+* normalizing and hashing stay total. A path leaving the project is always
+* E_VALIDATION.
+*/
+function inlineFileReferences(document, context, options) {
+	const inline = (node) => {
+		if (isFileReference(node)) {
+			const ref = node[FILE_REFERENCE_KEY];
+			return readFileReference(resolveFileReference(context, ref), ref, options);
+		}
+		if (Array.isArray(node)) return node.map(inline).filter((item) => item !== omittedReference);
+		if (isPlainObject(node)) {
+			const out = {};
+			for (const [key, value] of Object.entries(node)) {
+				const inlined = inline(value);
+				if (inlined !== omittedReference) out[key] = inlined;
+			}
+			return out;
+		}
+		return node;
+	};
+	return inline(document);
+}
+//#endregion
+//#region src/lib/branding/index.ts
+/**
+* Relative directory (from the project root) where local branding files live:
+* the `branding.json` descriptor plus the sibling `.liquid` template it
+* references. Owned here so commands, syncers, and tests share one source of
+* truth; only `*.json` files are sync-discovered, the template rides along as
+* a `$file` reference in `liquid_template`.
+*/
+const BRANDING_DIR = ".zitadel/branding";
+/**
+* The key descriptors used before `$file` references. It is still recognised
+* so plan can say how to migrate instead of reporting an unknown key.
+*/
+const LEGACY_TEMPLATE_FILE_KEY = "liquid_template_file";
+/**
+* References in a descriptor resolve against its directory; all descriptors
+* live flat in {@link BRANDING_DIR}.
+*/
+const referenceContext = (cwd) => ({
+	cwd,
+	baseDir: BRANDING_DIR
+});
+/** E_VALIDATION with a migration hint when a descriptor still carries `liquid_template_file`. */
+function assertNoLegacyTemplateKey(data) {
+	const legacy = data[LEGACY_TEMPLATE_FILE_KEY];
+	if (legacy === void 0) return;
+	throw new ZitadelError("E_VALIDATION", `${LEGACY_TEMPLATE_FILE_KEY} is no longer supported`, { hint: `Replace it with "liquid_template": { "$file": ${JSON.stringify(typeof legacy === "string" ? legacy : "./login.liquid")} }.` });
+}
+/**
+* Returns the template string a descriptor carries, inline or behind a
+* `$file` reference. Undefined when it has none (a legal descriptor that only
+* sets layout or asset URLs); E_VALIDATION when a reference cannot be read.
+*/
+function readDescriptorTemplate(cwd, data) {
+	const { liquid_template } = inlineFileReferences(data, referenceContext(cwd), { onMissing: "throw" });
+	return typeof liquid_template === "string" ? liquid_template : void 0;
+}
+/**
+* Converts a local descriptor to the wire body of `POST /branding`: strips the
+* editor `$schema` affordance and inlines every `$file` reference. Non-throwing
+* on an unreadable file (the field is left out) so normalizing and hashing stay
+* total; `validate` reports that case with a hint before any planning happens.
+*/
+/**
+* The project-relative files a descriptor's `$file` references point at, for a
+* diff's pathspec: the bundle inlines them, so editing one changes what a
+* deploy publishes even though the file may sit outside `.zitadel/branding/`.
+*/
+function brandingReferencePaths(cwd, data) {
+	return findFileReferences(data).map(({ ref }) => relative(cwd, resolveFileReference(referenceContext(cwd), ref)));
+}
+function toBrandingWireBody(cwd, data) {
+	const { $schema, ...rest } = data;
+	return inlineFileReferences(rest, referenceContext(cwd), { onMissing: "omit" });
+}
+//#endregion
+//#region src/lib/json-dir.ts
+/**
+* Read every `*.json` file under `absDir` and return each body as a plain
+* object. Files are read in lexical filename order so the result is
+* deterministic for downstream hashing and diffs. Each file is parsed by
+* `JSON.parse`; this function does **not** apply any schema validation —
+* unknown keys, forward-compatible fields, and `${VAR}` placeholders survive
+* intact. Callers that need a typed shape pass the result through their
+* resource's Zod schema.
+*
+* Returns an empty array when the directory is missing. Throws `E_VALIDATION`
+* `ZitadelError` on invalid JSON or when a file's root value is not an object.
+*
+* @param absDir - Absolute path to the directory to scan.
+*/
+async function readJsonDir(absDir) {
+	return (await readJsonDirEntries(absDir)).map((entry) => entry.body);
+}
+/**
+* {@link readJsonDir}, keeping each body's file name — for callers that report
+* a problem against the file it came from. `skip` leaves out files by name
+* before they are read, so a file the caller does not own (a policy test file
+* beside the policies) can never fail it.
+*/
+async function readJsonDirEntries(absDir, { skip } = {}) {
+	let entries;
+	try {
+		entries = await readdir(absDir);
+	} catch (error) {
+		if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+	const result = [];
+	for (const entry of entries.filter((name) => name.endsWith(".json") && !skip?.(name)).sort()) {
+		const abs = join(absDir, entry);
+		let raw;
+		try {
+			raw = JSON.parse(await readFile(abs, "utf8"));
+		} catch {
+			throw new ZitadelError("E_VALIDATION", `${entry} is not valid JSON`);
+		}
+		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new ZitadelError("E_VALIDATION", `${entry} must contain a JSON object at the root`);
+		result.push({
+			name: entry,
+			body: raw
+		});
+	}
+	return result;
+}
+//#endregion
+//#region src/lib/policies/index.ts
+/**
+* Operation policies (ADR 066): one `.zitadel/policies/<operation>.json` file
+* per guarded operation, which `deploy` carries in the release bundle. The
+* server publishes each as the operation's newest revision when the config
+* changed, and the release pins it.
+*
+* **Source of truth.** The file is the publish body plus `$schema`; its shape
+* is `policy.json`, the meta-schema generated from the OpenAPI spec and
+* shipped by `@zitadel/config`, and the CLI checks it with
+* `policyConfigSchema` from the same generated contract. The server's template
+* checks it again on the build, together with the rules that relate settings
+* to each other.
+*
+* **Dependency rule.** No upward imports (`commands/`, `release/`).
+*/
+/** Project-relative directory the policy files live in. */
+const POLICIES_DIR = ".zitadel/policies";
+/**
+* The body `POST /policies` takes, and the form a stored policy compares in:
+* the file without its editor pointer.
+*/
+function toPolicyWireBody(file) {
+	return {
+		operation: file.operation,
+		config: file.config
+	};
+}
+/**
+* The suffix of a policy test file (`<operation>.test.json`), which sits
+* beside the policies but is never deployed: `zitadel policies test` runs it.
+*/
+const POLICY_TEST_SUFFIX = ".test.json";
+/** Whether a file in `.zitadel/policies/` is a test file rather than a policy. */
+function isPolicyTestFile(name) {
+	return name.endsWith(POLICY_TEST_SUFFIX);
+}
+/** The name a policy file must have: its operation, so one file holds one operation's policy. */
+function policyFileName(operation) {
+	return `${operation}.json`;
+}
+/**
+* What is wrong with a policy file, each as a line naming the file, or none.
+* The file must parse against the strict `policyConfigSchema`, built from the
+* generated publish body, and be named after its operation: one file per
+* operation, so two files can never carry the same policy. The rules that
+* relate settings to each other (a minimum above the maximum) are the server
+* template's, and fail the release build.
+*/
+function policyFileIssues(data, file) {
+	const result = policyConfigSchema.safeParse(data);
+	if (!result.success) return result.error.issues.map((issue) => `${file}: ${issue.path.join(".") || "(root)"} ${issue.message}`);
+	const expected = policyFileName(result.data.operation);
+	if (file.split("/").at(-1) !== expected) return [`${file} holds the ${result.data.operation} policy, so it must be named ${expected}`];
+	return [];
+}
+/** The operation the password policy guards, and the name of its file. */
+const PASSWORD_POLICY_OPERATION = "auth.factor.password.set";
+/** Where `setup` writes the password policy. */
+const PASSWORD_POLICY_PATH = `${POLICIES_DIR}/${policyFileName(PASSWORD_POLICY_OPERATION)}`;
+/**
+* The password policy file `setup` writes for a new project: the given
+* minimum, {@link RECOMMENDED_PASSWORD_MIN_LENGTH} when none was given, and an
+* empty `config`, which enforces nothing, for an explicit "none".
+*/
+function passwordPolicyFile(minLength) {
+	const value = minLength === void 0 ? RECOMMENDED_PASSWORD_MIN_LENGTH : minLength;
+	return {
+		$schema: POLICY_FILE_SCHEMA_REF,
+		operation: PASSWORD_POLICY_OPERATION,
+		config: value === null ? {} : { min_length: value }
+	};
+}
+/**
+* Reads a minimum password length the way `setup` takes one, from its flag or
+* its prompt: empty or 0 means none (`null`), anything else a whole number the
+* template's bounds accept. The bounds come from the generated publish body,
+* so the CLI and the server cannot disagree on them.
+*/
+function parsePasswordMinLength(value) {
+	const text = value.trim();
+	if (text === "" || /^0+$/.test(text)) return {
+		ok: true,
+		value: null
+	};
+	const result = PublishPolicyBody.shape.config.shape.min_length.safeParse(Number(text));
+	if (!/^\d+$/.test(text) || !result.success || result.data === void 0) return {
+		ok: false,
+		problem: `Must be a whole number from 1 to ${publishPolicyBodyOneConfigMinLengthMax}, or 0 for none`
+	};
+	return {
+		ok: true,
+		value: result.data
+	};
+}
+//#endregion
+//#region src/lib/release/bundle.ts
+/** The most resources a release may pin — the cap `POST /releases/build` enforces. */
+const MAX_BUNDLE_RESOURCES = 50;
+/** Drop the editor-only `$schema` pointer; the server never echoes it. */
+function stripSchema(resource) {
+	const { $schema, ...rest } = resource;
+	return rest;
+}
+/**
+* Read `.zitadel/` and assemble the bundle a deploy sends. Schemas and flows
+* are taken as authored with their `$schema` affordance removed; the branding
+* descriptor is converted to its wire body, which inlines the `$file` template
+* and strips `$schema`. An empty directory and a bundle over the cap both fail
+* before any server call, with the same messages the server would answer.
+*/
+async function buildBundle(cwd) {
+	const schemas = (await readJsonDir(join(cwd, SCHEMAS_DIR))).map(stripSchema);
+	const flow_definitions = (await readJsonDir(join(cwd, FLOWS_DIR))).map(stripSchema);
+	const idpEntries = await readJsonDirEntries(join(cwd, IDPS_DIR));
+	const idps = idpEntries.map((entry) => stripSchema(entry.body));
+	const policyEntries = await readJsonDirEntries(join(cwd, POLICIES_DIR), { skip: isPolicyTestFile });
+	const policies = policyEntries.map((entry) => stripSchema(entry.body));
+	const brandingSources = (await readJsonDir(join(cwd, BRANDING_DIR))).map((descriptor) => ({ ...descriptor }));
+	if (brandingSources.length > 1) throw new ZitadelError("E_VALIDATION", `A release carries at most one branding, but .zitadel/branding/ holds ${brandingSources.length}`, { hint: "A project has a single branding; keep one descriptor under .zitadel/branding/." });
+	const [descriptor] = brandingSources;
+	const branding = descriptor === void 0 ? void 0 : toBrandingWireBody(cwd, descriptor);
+	const resourceCount = schemas.length + flow_definitions.length + idps.length + policies.length + (branding === void 0 ? 0 : 1);
+	if (resourceCount === 0) throw new ZitadelError("E_VALIDATION", "There is nothing in .zitadel/ to deploy", { hint: "Add a schema, flow, policy or branding under .zitadel/, or run `zitadel setup` to scaffold one." });
+	if (resourceCount > MAX_BUNDLE_RESOURCES) throw new ZitadelError("E_VALIDATION", `A release pins at most ${MAX_BUNDLE_RESOURCES} resources, but .zitadel/ holds ${resourceCount}`);
+	return {
+		bundle: {
+			schemas,
+			flow_definitions,
+			idps,
+			...policies.length === 0 ? {} : { policies },
+			...branding === void 0 ? {} : { branding }
+		},
+		resourceCount,
+		brandingSources,
+		idpFiles: idpEntries.map((entry) => entry.name),
+		policyFiles: policyEntries.map((entry) => entry.name)
+	};
+}
+//#endregion
+//#region src/lib/release/deployment.ts
+/**
+* Every live deployment of the project, newest first, drained across pages: one
+* live preview per open pull request can push the primary origins' deployment
+* off the first page, and a guard, a baseline or a rollback read from that page
+* alone would quietly miss it.
+*/
+async function listLiveDeployments(client, projectId, options = {}) {
+	const { items } = await collectPages((token) => client.listDeployments({
+		project_id: projectId,
+		live: true,
+		...options.origin === void 0 ? {} : { origin: options.origin },
+		...options.withRelease ? { expand: ["release"] } : {},
+		...token === void 0 ? {} : { page_token: token }
+	}), {
+		items: "deployments",
+		all: true,
+		nextPageToken: "next_page_token"
+	});
+	return items;
+}
+/**
+* Whether a deployment serves a primary origin. A preview deployment's targets
+* carry an expiry; it is never the baseline, the guard or the thing a bare
+* rollback undoes.
+*/
+function servesPrimary(deployment) {
+	return deployment.targets.some((target) => target.expires_at == null);
+}
+/**
+* Make a release live. The release is named by id or by content digest, never
+* both, and the targets are `primary` (every primary origin), one exact primary
+* origin, or the preview URLs a pull-request build registers. `ttl` sets how
+* long each preview stays live and is only valid with preview URLs. The server
+* answers 201 when it wrote a deployment and 200 when every target already
+* served the release.
+*/
+async function createDeployment(client, projectId, input) {
+	return await client.createDeployment({
+		...input.releaseId === void 0 ? {} : { release_id: input.releaseId },
+		...input.contentHash === void 0 ? {} : { content_hash: input.contentHash },
+		targets: input.targets,
+		...input.message === void 0 ? {} : { message: input.message },
+		...input.ttl === void 0 ? {} : { ttl: input.ttl },
+		...input.expectedDeploymentId === void 0 ? {} : { expected_deployment_id: input.expectedDeploymentId }
+	}, { project_id: projectId });
+}
+/**
+* Re-apply a deployment: a new deployment with its release and its targets,
+* recorded as a rollback. Returns 200 when the targets already serve it.
+*/
+async function rollbackDeployment(client, projectId, deploymentId, options) {
+	const body = {
+		...options?.message === void 0 ? {} : { message: options.message },
+		...options?.expectedDeploymentId === void 0 ? {} : { expected_deployment_id: options.expectedDeploymentId }
+	};
+	return client.rollbackDeployment(deploymentId, { project_id: projectId }, Object.keys(body).length === 0 ? void 0 : body);
+}
+//#endregion
+//#region src/lib/release/git.ts
+const run = promisify(execFile);
+/**
+* The directories a release is built from, the only paths a deploy diffs. Not
+* the whole of `.zitadel/`: `state.json` and `meta/` are not published, and
+* `.zitadel/secret` or `.zitadel/local/`, left untracked but not ignored, would
+* otherwise be marked for the diff and their contents printed.
+*/
+const CONFIG_PATHS = [
+	".zitadel/schemas/",
+	".zitadel/flows/",
+	".zitadel/branding/",
+	".zitadel/idps/"
+];
+/** Run git in `cwd`, returning its stdout, or null when git cannot answer. */
+async function git(cwd, args, env) {
+	try {
+		const { stdout } = await run("git", args, {
+			cwd,
+			maxBuffer: 16777216,
+			...env ? { env: {
+				...process.env,
+				...env
+			} } : {}
+		});
+		return stdout;
+	} catch {
+		return null;
+	}
+}
+/** The current commit, or null when there is no repo or no commit yet. */
+async function headSha(cwd) {
+	const stdout = await git(cwd, ["rev-parse", "HEAD"]);
+	return stdout === null ? null : stdout.trim() || null;
+}
+/**
+* Whether the repository's working tree has any uncommitted change, anywhere —
+* not only under `.zitadel/`. A release records the provenance of the whole
+* commit it was built from, so a change outside `.zitadel/` (a code change that
+* the config depends on, say) makes that provenance just as inexact.
+*/
+async function worktreeIsDirty(cwd) {
+	const stdout = await git(cwd, ["status", "--porcelain"]);
+	return stdout !== null && stdout.trim() !== "";
+}
+/**
+* The `git diff` options the terminal's diff and the `--json` one share, so
+* the two never disagree: git's own unified diff, never an external diff
+* program's, with paths relative to the project, as the CLI reports them
+* everywhere else.
+*/
+const DIFF_OPTIONS = ["--no-ext-diff", "--relative"];
+/**
+* The coloured diff of `.zitadel/` against `sha`, or null when no diff can be
+* shown: git is missing, this is not a repo, or the commit is not in local
+* history (a shallow clone, say). A dead commit is told apart from a clean tree
+* by first checking the commit resolves.
+*/
+async function diffConfigAgainst(cwd, sha, color, referenced = []) {
+	return diffConfig(cwd, sha, [color ? "--color=always" : "--no-color"], referenced);
+}
+/**
+* {@link diffConfigAgainst}, uncoloured and split by file: joined back
+* together, the patches are the diff the terminal shows. Null when no diff can
+* be shown, for the same reasons.
+*/
+async function diffConfigFilesAgainst(cwd, sha, referenced = []) {
+	const output = await diffConfig(cwd, sha, [
+		"--no-color",
+		"--raw",
+		"-z",
+		"--patch"
+	], referenced);
+	return output === null ? null : splitByFile(output);
+}
+/**
+* Pair the `--raw -z` records with the patch's per-file sections. git writes
+* both from one list of files, in one order, so they line up one to one, except
+* for a file whose type changed (a file replaced by a symlink): git shows it as
+* a deletion and a creation, two sections under one header, joined here.
+*/
+function splitByFile(output) {
+	let at = 0;
+	const field = () => {
+		const end = output.indexOf("\0", at);
+		const value = output.slice(at, end === -1 ? output.length : end);
+		at = end === -1 ? output.length : end + 1;
+		return value;
+	};
+	const records = [];
+	while (output.startsWith(":", at)) {
+		const meta = field();
+		const letter = meta.charAt(meta.lastIndexOf(" ") + 1);
+		const path = field();
+		if (letter === "R" || letter === "C") {
+			const status = letter === "R" ? "renamed" : "copied";
+			records.push({
+				path: field(),
+				status,
+				previous_path: path
+			});
+		} else {
+			const status = letter === "A" ? "added" : letter === "D" ? "deleted" : "modified";
+			records.push({
+				path,
+				status
+			});
+		}
+	}
+	const sections = output.slice(at + 1).split(/^(?=diff --git )/m);
+	let next = 0;
+	return records.map((record) => {
+		let patch = sections[next++] ?? "";
+		while (next < sections.length && headerOf(sections[next]) === headerOf(patch)) patch += sections[next++];
+		return {
+			...record,
+			patch
+		};
+	});
+}
+/** A patch section's first line, its `diff --git` header. */
+function headerOf(section = "") {
+	const end = section.indexOf("\n");
+	return end === -1 ? section : section.slice(0, end);
+}
+/** `git diff` of the release's paths against `sha`, in `format`. */
+async function diffConfig(cwd, sha, format, referenced) {
+	const paths = [...CONFIG_PATHS, ...referenced];
+	if (await git(cwd, [
+		"cat-file",
+		"-e",
+		`${sha}^{commit}`
+	]) === null) return null;
+	const diffArgs = [
+		"diff",
+		...DIFF_OPTIONS,
+		...format,
+		sha,
+		"--",
+		...paths
+	];
+	const indexPath = (await git(cwd, [
+		"rev-parse",
+		"--git-path",
+		"index"
+	]))?.trim();
+	if (!indexPath) return git(cwd, diffArgs);
+	let scratch;
+	try {
+		scratch = await mkdtemp(join(tmpdir(), "zitadel-diff-"));
+		const tempIndex = join(scratch, "index");
+		await copyFile(resolve(cwd, indexPath), tempIndex).catch(() => void 0);
+		const env = { GIT_INDEX_FILE: tempIndex };
+		const present = paths.filter((path) => existsSync(join(cwd, path)));
+		if (present.length > 0) await git(cwd, [
+			"add",
+			"-N",
+			"--",
+			...present
+		], env);
+		return await git(cwd, diffArgs, env) ?? await git(cwd, diffArgs);
+	} finally {
+		if (scratch) await rm(scratch, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/lib/release/steps/asset-probe.ts
+/**
+* Branding descriptor fields whose value is a URL the login page fetches as
+* an image. Both are optional and both fail the same invisible way when the
+* URL is well-formed but dead.
+*/
+const ASSET_FIELDS = ["logo_url", "hero_url"];
+/**
+* Per-URL probe budget. Short on purpose: this runs on the critical path of
+* every `deploy` and `preview`, and a dead host that never answers must cost a
+* couple of seconds, not a hung command.
+*/
+const DEFAULT_TIMEOUT_MS = 2500;
+/** Keep redirect chains bounded and re-validate every destination ourselves. */
+const MAX_REDIRECTS = 5;
+/**
+* Addresses an untrusted descriptor must never make the planning host contact.
+* The browser-side render gate still supports canonical loopback HTTP for local
+* development; the CLI probe deliberately leaves those URLs inconclusive
+* instead of turning `deploy` over repo content into a localhost/network scanner.
+*/
+const UNSAFE_IPV4_ADDRESSES = new BlockList();
+for (const [network, prefix] of [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.0.0.0", 24],
+	["192.0.2.0", 24],
+	["192.88.99.0", 24],
+	["192.168.0.0", 16],
+	["198.18.0.0", 15],
+	["198.51.100.0", 24],
+	["203.0.113.0", 24],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4]
+]) UNSAFE_IPV4_ADDRESSES.addSubnet(network, prefix, "ipv4");
+const UNSAFE_IPV6_ADDRESSES = new BlockList();
+for (const [network, prefix] of [
+	["::", 3],
+	["4000::", 2],
+	["8000::", 1],
+	["2001::", 23],
+	["2001:db8::", 32],
+	["2002::", 16],
+	["3fff::", 20]
+]) UNSAFE_IPV6_ADDRESSES.addSubnet(network, prefix, "ipv6");
+/** Content types that are images despite not being `image/*`. */
+const EXTRA_IMAGE_TYPES = /* @__PURE__ */ new Set(["application/octet-stream"]);
+/**
+* Probe every asset URL the bundle's branding descriptors carry and return one
+* warning line per URL that is well-formed but will not render: an unreachable
+* host, a non-2xx status, or a response that is not an image.
+*
+* Why the CLI probes at all: a bad `logo_url` clears every gate on the way in
+* (the CLI's Zod shape check, the server's save gate) and then fails silently
+* in the browser as a 0×0 `<img>` — no deploy output, no console error. The
+* probe is the only place in the pipeline that can see it.
+*
+* Deliberately non-fatal and best-effort. A developer on a plane, behind a
+* proxy, or pointing at a CDN that only resolves from production gets a
+* warning, never a failed deploy — the machine running `deploy` is not
+* necessarily the machine that renders the login page. Set
+* `ZITADEL_SKIP_ASSET_PROBE` to turn it off entirely, and
+* `ZITADEL_ASSET_PROBE_TIMEOUT_MS` to retune the per-URL budget. Only public
+* HTTPS destinations are contacted: loopback/private/internal targets and
+* redirects to them stay inconclusive so repo config cannot scan the running
+* host's network.
+*/
+async function brandingAssetWarnings(brandings) {
+	if (process.env.ZITADEL_SKIP_ASSET_PROBE) {
+		consola.debug("Branding asset probe skipped (ZITADEL_SKIP_ASSET_PROBE is set)");
+		return [];
+	}
+	const fields = brandings.flatMap((branding) => assetUrlsOf(branding));
+	const urls = new Set(fields.map(({ url }) => url));
+	if (urls.size === 0) return [];
+	const timeoutMs = probeTimeoutMs();
+	const verdicts = new Map(await Promise.all([...urls].map(async (url) => [url, await probeAsset(url, timeoutMs)])));
+	const warnings = [];
+	for (const { field, url } of fields) {
+		const warning = describeVerdict(field, url, verdicts.get(url) ?? { kind: "inconclusive" });
+		if (warning) warnings.push(warning);
+	}
+	return warnings;
+}
+/**
+* The probe itself: a HEAD request bounded by an abort timeout. HEAD keeps a
+* multi-megabyte hero image off the wire — we only need the status line and
+* the content type.
+*/
+async function probeAsset(url, timeoutMs) {
+	let current;
+	try {
+		current = new URL(url);
+	} catch {
+		return { kind: "inconclusive" };
+	}
+	const signal = AbortSignal.timeout(timeoutMs);
+	try {
+		for (let redirects = 0;; redirects += 1) {
+			if (!isSafeProbeUrl(current)) {
+				consola.debug(`asset probe ${url} skipped unsafe/private target: ${current.href}`);
+				return { kind: "inconclusive" };
+			}
+			const response = await requestHead(current, signal);
+			if (isRedirect(response.status)) {
+				const location = response.location;
+				if (!location) return {
+					kind: "status",
+					status: response.status
+				};
+				if (redirects >= MAX_REDIRECTS) return {
+					kind: "unreachable",
+					detail: `more than ${MAX_REDIRECTS} redirects`
+				};
+				current = new URL(location, current);
+				continue;
+			}
+			if (response.status === 405 || response.status === 501) return { kind: "inconclusive" };
+			if (response.status < 200 || response.status >= 300) return {
+				kind: "status",
+				status: response.status
+			};
+			if (response.status === 204 || response.status === 205) return {
+				kind: "empty",
+				status: response.status
+			};
+			const contentType = response.contentType?.split(";")[0]?.trim().toLowerCase();
+			if (!contentType) return { kind: "ok" };
+			if (contentType.startsWith("image/") || EXTRA_IMAGE_TYPES.has(contentType)) return { kind: "ok" };
+			return {
+				kind: "content-type",
+				contentType
+			};
+		}
+	} catch (error) {
+		if (isUnsafeProbeTargetError(error)) {
+			consola.debug(`asset probe ${url} skipped unsafe/private target`);
+			return { kind: "inconclusive" };
+		}
+		consola.debug(`asset probe ${url} failed:`, error);
+		return {
+			kind: "unreachable",
+			detail: describeProbeError(error, timeoutMs)
+		};
+	}
+}
+function isRedirect(status) {
+	return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+/**
+* Reject targets whose URL alone proves they are unsafe. Hostname resolution
+* happens inside the connector lookup below so validation and connection use
+* the same DNS answer, without a rebinding window.
+*/
+function isSafeProbeUrl(url) {
+	if (url.protocol !== "https:" || url.username !== "" || url.password !== "") return false;
+	const hostname = url.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+	if (hostname === "localhost" || !hostname.includes(".") || hostname.endsWith(".localhost") || hostname.endsWith(".local") || hostname.endsWith(".internal") || hostname.endsWith(".lan") || hostname.endsWith(".home.arpa")) return false;
+	const literalFamily = isIP(hostname);
+	return literalFamily === 0 || !isUnsafeAddress(hostname, literalFamily);
+}
+/** Resolve once and accept the answer only when every address is public. */
+async function resolvePublicAddresses(hostname) {
+	const addresses = await lookup(hostname, {
+		all: true,
+		verbatim: true
+	});
+	return addresses.length > 0 && addresses.every(({ address, family }) => !isUnsafeAddress(address, family)) ? addresses : void 0;
+}
+function isUnsafeAddress(address, family) {
+	return family === 6 ? UNSAFE_IPV6_ADDRESSES.check(address, "ipv6") : UNSAFE_IPV4_ADDRESSES.check(address, "ipv4");
+}
+const UNSAFE_PROBE_TARGET_CODE = "ERR_ZITADEL_UNSAFE_ASSET_TARGET";
+function unsafeProbeTargetError(hostname) {
+	return Object.assign(/* @__PURE__ */ new Error(`asset target ${hostname} resolves to a non-public address`), { code: UNSAFE_PROBE_TARGET_CODE });
+}
+/**
+* Validate DNS in the connector's own lookup and return only approved
+* addresses. The socket cannot perform a second lookup, which closes the DNS
+* rebinding gap while preserving the hostname for TLS SNI/certificate checks.
+*/
+async function requestHead(url, signal) {
+	const safeLookup = (hostname, options, callback) => {
+		resolvePublicAddresses(hostname).then((addresses) => {
+			if (!addresses) {
+				callback(unsafeProbeTargetError(hostname), "", 0);
+				return;
+			}
+			const candidates = options.family === 4 || options.family === 6 ? addresses.filter(({ family }) => family === options.family) : addresses;
+			const candidate = candidates[0];
+			if (!candidate) {
+				callback(unsafeProbeTargetError(hostname), "", 0);
+				return;
+			}
+			if (options.all) {
+				callback(null, candidates);
+				return;
+			}
+			callback(null, candidate.address, candidate.family);
+		}, (error) => callback(error, "", 0));
+	};
+	const dispatcher = new Agent({ connect: { lookup: safeLookup } }).compose(userAgentInterceptor);
+	try {
+		const response = await fetch(url, {
+			method: "HEAD",
+			redirect: "manual",
+			signal,
+			dispatcher
+		});
+		return {
+			status: response.status,
+			location: response.headers.get("location") ?? void 0,
+			contentType: response.headers.get("content-type") ?? void 0
+		};
+	} finally {
+		await dispatcher.destroy();
+	}
+}
+function isUnsafeProbeTargetError(error) {
+	let current = error;
+	for (let depth = 0; depth < 4 && current instanceof Error; depth += 1) {
+		if (current.code === UNSAFE_PROBE_TARGET_CODE) return true;
+		current = current.cause;
+	}
+	return false;
+}
+function describeVerdict(field, url, verdict) {
+	switch (verdict.kind) {
+		case "ok":
+		case "inconclusive": return;
+		case "status": return `${field} ${url} returned HTTP ${verdict.status} — the login page renders a well-formed URL that serves nothing as a 0×0 image, with no error anywhere.`;
+		case "empty": return `${field} ${url} returned HTTP ${verdict.status} with no representation — the login page has no image bytes to render.`;
+		case "unreachable": return `${field} ${url} could not be reached (${verdict.detail}) — the login page renders an unreachable URL as a 0×0 image. Ignore this if the host is only reachable from where the login page renders; set ZITADEL_SKIP_ASSET_PROBE to stop checking.`;
+		case "content-type": return `${field} ${url} responded with content-type "${verdict.contentType}", not an image — the login page renders a non-image response as a 0×0 image.`;
+	}
+}
+/** The `logo_url` / `hero_url` values a descriptor actually sets. */
+function assetUrlsOf(content) {
+	const body = content;
+	const out = [];
+	for (const field of ASSET_FIELDS) {
+		const value = body[field];
+		if (typeof value === "string" && value !== "") out.push({
+			field,
+			url: value
+		});
+	}
+	return out;
+}
+function probeTimeoutMs() {
+	const raw = Number(process.env.ZITADEL_ASSET_PROBE_TIMEOUT_MS);
+	return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+}
+function describeProbeError(error, timeoutMs) {
+	if (error instanceof Error && (error.name === "TimeoutError" || error.cause instanceof Error && error.cause.name === "TimeoutError")) return `no response within ${timeoutMs}ms`;
+	if (error instanceof Error) {
+		const cause = error.cause;
+		return (cause instanceof Error ? cause.message : error.message) || error.name;
+	}
+	return String(error);
+}
+//#endregion
+//#region src/lib/release/steps/idp-checks.ts
+/**
+* The checks a connection file gets before the release is built.
+*
+* The server creates the connections from the bundle, inside the release's own
+* transaction, and holds them to the same rules. These run first anyway so a
+* bad file is named locally — with the file it came from and the command that
+* fixes it — rather than coming back as one bulk `rel.invalid`. Two of them the
+* server cannot run for us: that a `client_secret` references a variable rather
+* than holding a value, which must fail before anything leaves the machine, and
+* that the variables a connection names are the kind the engine needs.
+*
+* A preview is checked the same way, except that its token may not read the
+* project's variables; that check then belongs to the deploy that merges it.
+*/
+async function validateConnections(ctx) {
+	const files = ctx.idpFiles;
+	const named = ctx.bundle.idps.map((body, index) => ({
+		body,
+		file: `${IDPS_DIR}/${files[index] ?? "(unnamed)"}`
+	}));
+	for (const { body, file } of named) validateConnection(body, file, ctx.suggest);
+	if (named.length === 0) return;
+	const held = await heldVariables(ctx);
+	if (held === void 0) return;
+	for (const { body, file } of named) checkCredentialVariables(body, file, held, ctx.suggest, ctx.mode === "preview");
+}
+/**
+* The connection's shape, and the one mistake that would publish a credential:
+* a `client_secret` held as a value rather than a `${{ NAME }}` reference.
+*/
+function validateConnection(data, file, suggest) {
+	const result = idpConnectionConfigSchema.safeParse(data);
+	if (!result.success) {
+		const literalSecret = result.error.issues.some((issue) => {
+			if (issue.path[issue.path.length - 1] !== "client_secret") return false;
+			const stored = valueAt(data, issue.path);
+			return typeof stored === "string" && !isVariableReference(stored);
+		});
+		throw new ZitadelError("E_VALIDATION", literalSecret ? "Connection file's client_secret must reference a variable, not hold a value" : "Connection file is not a valid identity provider connection", {
+			hint: literalSecret ? `Use "client_secret": "\${{ NAME }}" and publish the value with \`${suggest("variable set NAME --secret")}\`.` : void 0,
+			details: { issues: result.error.issues }
+		});
+	}
+	const missing = missingEndpoints(data.oidc);
+	if (missing.length > 0) throw new ZitadelError("E_VALIDATION", `${file}: oidc names some endpoints but not ${missing.join(", ")}`, {
+		hint: "Name every endpoint (authorization_endpoint, jwks_uri, token_endpoint, and userinfo_endpoint unless id_token_mapping is true), or none to read them from the issuer's discovery document.",
+		details: {
+			file,
+			missing
+		}
+	});
+	refuseResolvedSecret(data, "the connection");
+}
+/** The value a Zod issue path points at, or undefined when it is absent. */
+function valueAt(data, path) {
+	let current = data;
+	for (const key of path) {
+		if (typeof current !== "object" || current === null) return;
+		current = current[key];
+	}
+	return current;
+}
+/**
+* The variables the deploy would freeze, by name, and whether each is a secret:
+* the primary kind's for a deploy and the preview kind's for a preview, with no
+* fallback from one to the other (ADR 069). A preview's token may not read them,
+* which leaves the check to the deploy that merges it.
+*/
+async function heldVariables(ctx) {
+	const kind = ctx.mode === "preview" ? "preview" : "primary";
+	let held;
+	try {
+		held = await ctx.client.getVariables({
+			project_id: ctx.projectId,
+			kind
+		});
+	} catch (error) {
+		if (ctx.mode === "preview" && error instanceof ApiError && error.status === 403) return;
+		throw error;
+	}
+	return new Map(Object.entries(valuesOfKind(held, kind)).map(([name, value]) => [name, typeof value === "object"]));
+}
+/**
+* What the engine needs from the variables a connection names: they exist,
+* the client id is a plain one it can put in the authorize URL, the client
+* secret is a secret one, and they are not one and the same.
+*/
+function checkCredentialVariables(connection, file, held, suggest, preview) {
+	const setCommand = (name, secret) => suggest(`variable set ${name}${secret ? " --secret" : ""}${preview ? " --preview" : ""}`);
+	const block = connection.oidc;
+	const nameOf = (value) => typeof value === "string" ? referencedVariable(value) : void 0;
+	const named = [{
+		field: "client_id",
+		secret: false,
+		name: nameOf(block?.client_id)
+	}, {
+		field: "client_secret",
+		secret: true,
+		name: nameOf(block?.client_secret)
+	}].flatMap((credential) => credential.name === void 0 ? [] : [{
+		...credential,
+		name: credential.name
+	}]);
+	const [id, secret] = named;
+	if (id !== void 0 && secret !== void 0 && id.name === secret.name) throw new ZitadelError("E_VALIDATION", `${file}: client_id and client_secret both name the variable ${id.name}`, {
+		hint: "Give each its own variable: a plain one for the client id, a secret one for the client secret.",
+		details: {
+			variable: id.name,
+			file
+		}
+	});
+	for (const { field, secret: wantsSecret, name } of named) {
+		const isSecret = held.get(name);
+		if (isSecret === void 0) throw new ZitadelError("E_CREDENTIAL_MISSING", `${file}: ${field} names the variable ${name}, which the project does not have`, {
+			hint: "Publish it with the command below, then deploy again.",
+			nextCommands: [setCommand(name, wantsSecret)],
+			details: {
+				variable: name,
+				field,
+				file
+			}
+		});
+		if (isSecret !== wantsSecret) throw new ZitadelError("E_VALIDATION", `${file}: ${field} names the variable ${name}, which is ${isSecret ? "a secret" : "not a secret"}`, {
+			hint: wantsSecret ? "The client secret must be a secret variable: publish it with the command below." : "The client id must be a plain variable the engine can read back: publish it with the command below, without --secret.",
+			nextCommands: [setCommand(name, wantsSecret)],
+			details: {
+				variable: name,
+				field,
+				file,
+				secret: isSecret
+			}
+		});
+	}
+}
+//#endregion
+//#region src/lib/release/steps/sso-consistency.ts
+/**
+* Cross-file checks on the SSO configuration, before anything is sent.
+*
+* A flow that offers a provider its schema does not list, or a schema that
+* lists a provider with no connection file, is only visible when the files are
+* read together, and the server would reveal it late or not at all. This reads
+* the whole of `.zitadel/` so the rules can see what each file points at, and
+* throws one `E_VALIDATION` naming every problem, so a deploy (or a dry run)
+* stops before any request.
+*
+* A deploy publishes everything under `.zitadel/`, so everything is judged;
+* there is no narrower set of files a deploy "touches".
+*/
+async function validateSsoConsistency(cwd) {
+	const [schemas, flows, connections] = await Promise.all([
+		readJsonDirEntries(join(cwd, SCHEMAS_DIR)),
+		readJsonDirEntries(join(cwd, FLOWS_DIR)),
+		readJsonDirEntries(join(cwd, IDPS_DIR))
+	]);
+	const keyed = (dir, entries) => new Map(entries.map((entry) => [`${dir}/${entry.name}`, entry.body]));
+	const schemaFiles = keyed(SCHEMAS_DIR, schemas);
+	const tree = {
+		schemas: schemaFiles,
+		flows: new Map(flows.map((flow) => {
+			const path = `${FLOWS_DIR}/${flow.name}`;
+			const schemaPath = pinnedSchemaPath(flow.body, schemaFiles);
+			if (schemaPath === void 0 && offeredProviders(flow.body).length > 0) reportWarning(`${path}: could not tell which local schema this flow pins, so its provider rules were not checked against a schema`);
+			return [path, {
+				body: flow.body,
+				schemaPath
+			}];
+		})),
+		connections: keyed(IDPS_DIR, connections)
+	};
+	const issues = validateProject(tree);
+	if (issues.length === 0) return;
+	const noun = issues.length === 1 ? "issue" : "issues";
+	throw new ZitadelError("E_VALIDATION", `SSO configuration is not consistent (${issues.length} ${noun}):\n` + issues.map((issue) => `  - ${issue.file}: ${issue.message}`).join("\n"), {
+		hint: "These checks read the schemas, flows and connection files together. Fix the files named above and re-run; no changes were made. Only the CLI makes these checks.",
+		details: { issues: issues.map(({ rule, file, steps, message }) => ({
+			rule,
+			path: file,
+			...steps === void 0 ? {} : { steps },
+			message
+		})) }
+	});
+}
+/** The provider slugs the steps of a flow offer. */
+function offeredProviders(flow) {
+	const steps = flow.steps;
+	if (!Array.isArray(steps)) return [];
+	return steps.flatMap((step) => {
+		const providers = typeof step === "object" && step !== null ? step.sso_providers : void 0;
+		return Array.isArray(providers) ? providers.filter((item) => typeof item === "string") : [];
+	});
+}
+/**
+* The local schema a flow's `user_schema` pins, or `undefined` when it cannot
+* be told. A flow names its schema by `objectType`; a schema's `$id` is also
+* accepted for a flow written against the URL form.
+*/
+function pinnedSchemaPath(flow, schemas) {
+	const ref = flow.user_schema;
+	if (typeof ref !== "string" || ref === "") return;
+	for (const [path, schema] of schemas) {
+		const { $id, objectType } = schema;
+		if ($id === ref || objectType === ref) return path;
+	}
+}
+//#endregion
+//#region src/lib/release/steps/validate.ts
+/**
+* Validate the bundle the way the server does before it builds the release, so
+* a misconfiguration fails here with the file named rather than as a bulk
+* `rel.invalid` from the server. Two checks the server cannot run live earn
+* their place: every `${VAR}` / `*_env` reference must resolve in the running
+* environment, and every branding asset URL must actually serve an image.
+*
+* Moved out of the sync engine, where it validated a diff; here it validates
+* the bundle a deploy (and, later, a preview) assembles.
+*/
+const validateStep = {
+	name: "validate",
+	runsFor: ["deploy", "preview"],
+	async run(ctx) {
+		assertEnvRefsResolve(ctx);
+		validateBundleShapes(ctx);
+		validateFlows(ctx);
+		await validateConnections(ctx);
+		await validateSsoConsistency(ctx.cwd);
+		for (const warning of await brandingAssetWarnings(brandingsOf(ctx))) reportWarning(warning);
+	}
+};
+/**
+* Parse every schema, flow, policy and branding descriptor against the same Zod
+* the server enforces, before any writing step runs. Without this a malformed
+* schema, flow or branding only fails at `createRelease`, after the IdP-sync
+* step has already written — leaving a half-applied deploy. Errors across
+* every bundle kind aggregate into one `E_VALIDATION`. Branding is parsed from
+* the descriptor as authored (not the inlined wire body), so a `$file` that
+* cannot be read is reported here rather than silently dropped.
+*/
+function validateBundleShapes(ctx) {
+	const failures = [];
+	ctx.bundle.schemas.forEach((schema, index) => {
+		const result = schemaConfigSchema.safeParse(schema);
+		if (!result.success) {
+			const handle = typeof schema.objectType === "string" ? schema.objectType : `schema #${index + 1}`;
+			for (const issue of result.error.issues) failures.push(`${handle}: ${issue.path.join(".") || "(root)"} ${issue.message}`);
+		}
+	});
+	ctx.bundle.flow_definitions.forEach((flow, index) => {
+		const result = flowConfigSchema.safeParse(flow);
+		if (!result.success) {
+			const handle = typeof flow.name === "string" ? flow.name : `flow #${index + 1}`;
+			for (const issue of result.error.issues) failures.push(`${handle}: ${issue.path.join(".") || "(root)"} ${issue.message}`);
+		}
+	});
+	(ctx.bundle.policies ?? []).forEach((policy, index) => {
+		const file = `${POLICIES_DIR}/${ctx.policyFiles[index] ?? "(unnamed)"}`;
+		failures.push(...policyFileIssues(policy, file));
+	});
+	ctx.brandingSources.forEach((descriptor, index) => {
+		const handle = `branding #${index + 1}`;
+		try {
+			assertNoLegacyTemplateKey(descriptor);
+		} catch (error) {
+			const hint = error instanceof ZitadelError && error.hint ? ` ${error.hint}` : "";
+			failures.push(`${handle}: ${error instanceof Error ? error.message : String(error)}.${hint}`);
+			return;
+		}
+		const result = brandingConfigSchema.safeParse(descriptor);
+		if (!result.success) for (const issue of result.error.issues) failures.push(`${handle}: ${issue.path.join(".") || "(root)"} ${issue.message}`);
+		let template;
+		try {
+			template = readDescriptorTemplate(ctx.cwd, descriptor);
+		} catch (error) {
+			failures.push(`${handle}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (template !== void 0) {
+			for (const issue of validateLoginTemplate(template)) if (issue.severity === "error") failures.push(`${handle}: template ${issue.rule}: ${issue.message}`);
+		}
+	});
+	if (failures.length === 0) return;
+	const noun = failures.length === 1 ? "issue" : "issues";
+	throw new ZitadelError("E_VALIDATION", `Configuration validation failed (${failures.length} ${noun}):\n` + failures.map((failure) => `  - ${failure}`).join("\n"), {
+		hint: "These are the same rules the server enforces. Fix the file(s) and re-run.",
+		details: { issues: failures }
+	});
+}
+/** The schema a flow's `user_schema` names, found by `objectType` in the bundle. */
+function schemaFor(ctx, flow) {
+	const ref = flow.user_schema;
+	if (typeof ref !== "string" || ref === "") return;
+	return ctx.bundle.schemas.find((schema) => schema.objectType === ref);
+}
+/**
+* The semantic flow validation the server enforces when it builds the release:
+* errors aggregate into one `E_VALIDATION`, warnings are reported as they are
+* found. The schema a flow pins is resolved from the bundle so schema-aware
+* rules run.
+*/
+function validateFlows(ctx) {
+	const failures = [];
+	for (const flow of ctx.bundle.flow_definitions) {
+		const handle = typeof flow.name === "string" ? flow.name : "flow";
+		for (const issue of validateFlowDefinition(flow, schemaFor(ctx, flow))) if (issue.severity === "error") failures.push({
+			handle,
+			issue
+		});
+		else reportWarning(`${handle}: ${issue.message}`);
+	}
+	if (failures.length === 0) return;
+	const noun = failures.length === 1 ? "issue" : "issues";
+	throw new ZitadelError("E_VALIDATION", `Flow validation failed (${failures.length} ${noun}):\n` + failures.map(({ handle, issue }) => `  - ${handle}: ${issue.message}`).join("\n"), {
+		hint: "These are the same rules the server enforces. Fix the flow definition(s) and re-run.",
+		details: { issues: failures.map(({ handle, issue }) => ({
+			handle,
+			rule: issue.rule,
+			message: issue.message,
+			...issue.step === void 0 ? {} : { step: issue.step }
+		})) }
+	});
+}
+/**
+* Fail when a `${VAR}` or `*_env` reference names an environment variable the
+* running environment does not hold: the deploy would otherwise send the
+* placeholder literally, and the login page would never resolve it. The server
+* cannot check this — the references point at the deployer's environment.
+*/
+/** The bundle's branding as a list, empty when it carries none. */
+function brandingsOf(ctx) {
+	return ctx.bundle.branding === void 0 ? [] : [ctx.bundle.branding];
+}
+function assertEnvRefsResolve(ctx) {
+	const missing = /* @__PURE__ */ new Set();
+	for (const resource of [
+		...ctx.bundle.schemas,
+		...ctx.bundle.flow_definitions,
+		...brandingsOf(ctx)
+	]) for (const name of flowEnvRefs(resource)) if (!ctx.env[name]) missing.add(name);
+	if (missing.size > 0) throw new ZitadelError("E_VALIDATION", `Missing environment variables: ${[...missing].sort().join(", ")}`);
+}
+//#endregion
+//#region src/lib/release/steps/diff.ts
+/**
+* Show what `.zitadel/` changed since the release the target serves now.
+*
+* It reads the live release's `git_sha` from its metadata and runs
+* `git diff <sha> -- .zitadel/` against the working tree. There is no diff
+* library and no server fallback: when git is missing, this is not a repo, the
+* commit is not in local history, or the live release carries no `git_sha`, it
+* prints one line saying no diff is available and carries on. Colour is
+* suppressed under `--no-color` and a non-terminal. Under `--json` nothing is
+* printed, so the envelope travels alone on stdout: the diff, split by file, or
+* the line saying why there is none, is reported as `diff` instead.
+*/
+const diffStep = {
+	name: "diff",
+	runsFor: ["deploy", "preview"],
+	async run(ctx) {
+		const deployments = await listLiveDeployments(ctx.client, ctx.projectId, { withRelease: true });
+		const live = deployments.find(servesPrimary)?.release?.metadata;
+		const sha = live?.git_sha;
+		if (!sha) return noDiff(ctx, null, "No diff available: nothing is deployed yet, or the live release has no commit.");
+		if (live?.git_dirty) return noDiff(ctx, sha, `No reliable diff available: the live release was built from an uncommitted tree at ${sha.slice(0, 12)}.`);
+		const releases = new Set(deployments.filter(servesPrimary).map((entry) => entry.release_id));
+		const note = releases.size > 1 ? `The primary origins serve ${releases.size} different releases; the diff is against the newest, ${sha.slice(0, 12)}.` : void 0;
+		const unknown = `No diff available: ${sha.slice(0, 12)} is not in this repository's history.`;
+		const referenced = ctx.brandingSources.flatMap((descriptor) => brandingReferencePaths(ctx.cwd, descriptor));
+		if (ctx.json) {
+			const files = await diffConfigFilesAgainst(ctx.cwd, sha, referenced);
+			if (files === null) return noDiff(ctx, sha, unknown);
+			return { diff: {
+				against: sha,
+				files,
+				...note === void 0 ? {} : { note }
+			} };
+		}
+		if (note !== void 0) process.stdout.write(`${note}\n`);
+		const diff = await diffConfigAgainst(ctx.cwd, sha, ctx.color, referenced);
+		if (diff === null) return noDiff(ctx, sha, unknown);
+		const shown = diff.trim() === "" ? `No changes to .zitadel/ since ${sha.slice(0, 12)}.` : diff;
+		process.stdout.write(shown.endsWith("\n") ? shown : `${shown}\n`);
+	}
+};
+/** No diff to show: the line saying why, printed, or reported under `--json`. */
+function noDiff(ctx, against, note) {
+	if (!ctx.json) {
+		process.stdout.write(`${note}\n`);
+		return;
+	}
+	return { diff: {
+		against,
+		files: null,
+		note
+	} };
+}
+//#endregion
+//#region src/lib/release/index.ts
+/**
+* The arguments of a suggested publish. `deploy` refuses to run without `-m` when
+* no one can be asked for a message, which is every agent and every `--json`
+* run, so a suggested deploy carries one for the reader to fill in.
+*/
+const DEPLOY_ARGS = "deploy -m '<what changed>'";
+//#endregion
+//#region src/lib/box.ts
+/**
+* Frame overhead of a `consola.box` with `padding: 1`: two border columns,
+* the padding columns, and consola's left margin. Content wrapped to the
+* terminal width minus this stays inside the frame instead of soft-wrapping
+* under the right border.
+*/
+const BOX_OVERHEAD = 8;
+const MIN_CONTENT_WIDTH = 20;
+const MAX_TERMINAL_WIDTH = 80;
+/** Bold cyan, for commands the user should run (URLs/paths stay plain cyan). */
+const command = (s) => pc.bold(pc.cyan(s));
+/**
+* Wraps box content to the terminal (capped at 80 columns) so consola's
+* frame, which sizes itself to the longest content line, never exceeds the
+* window. ANSI-aware, preserves hard line breaks and indentation, and never
+* splits a token: URLs and commands stay whole for clicking, copying, and the
+* journey e2e scrape (claim.spec.ts), even when such a token alone is wider
+* than a very narrow window.
+*/
+function wrapForBox(message, columns = process.stdout.columns) {
+	const width = Math.max(MIN_CONTENT_WIDTH, Math.min(columns ?? MAX_TERMINAL_WIDTH, MAX_TERMINAL_WIDTH) - BOX_OVERHEAD);
+	return wrapAnsi(message, width, {
+		hard: false,
+		trim: false
+	});
+}
+function renderBoxActions(actions) {
+	return actions.map((action) => action.command ? `${action.text}\n\n  ${command(action.command)}` : action.text).join("\n\n");
+}
+//#endregion
+//#region src/lib/journey-guidance.ts
+/**
+* Guidance copy that commands share, so the story doesn't fork; most of it is
+* the journey-staged copy of `setup` and `status`.
+*
+* The staging exists because of alpha tester feedback (Elina, alpha.15):
+* printing customize/publish steps before the user has logged in once reads
+* as noise, but dropping them entirely recreates the round-1 dead end where
+* nothing pointed to the next step. So the guidance tracks journey position —
+* verify first, customize/publish once login demonstrably works — and both
+* commands quote the same copy so the story doesn't fork.
+*/
+/**
+* The verify mission: prove the scaffolded auth round-trips before touching
+* config. `openUrl` prefixes the browser destination for callers that have
+* not already narrated it (setup's box has a separate "Start your project"
+* line; status has only the issuer).
+*/
+function verifyLoginAction(openUrl) {
+	return `Verify auth in the browser: ${openUrl ? `open ${openUrl}, ` : ""}register a user, log out, log in again with the same user, and confirm /profile shows Signed in.`;
+}
+/**
+* Where to look when something fails against the local server, shared by
+* `start` and `doctor`. A sign-in step only says that a provider or a check
+* failed, because the login is public; the server logs why.
+*/
+function serverLogAction(cliVersion) {
+	return `When a sign-in or a request fails, the server's log says why: run ${publicCliCommand("logs --follow", cliVersion)} in another terminal to watch it.`;
+}
+/**
+* Where the list of every command is: the CLI run with no subcommand. Setup,
+* status and every command's help end with it, after their own next steps, so
+* the overview can be found without already knowing it exists. The command is on
+* a line of its own, with nothing around it, so it can be copied as written.
+*/
+function exploreAllCommands(cliVersion) {
+	return ["Explore all commands:", `  ${publicCliCommand("", cliVersion)}`].join("\n");
+}
+/**
+* The customize/publish pair, in Elina's tested wording. `selector` is the
+* run's environment selection, so the quoted commands publish to the project
+* the run was about.
+*/
+function customizeAndPublishActions(cliVersion, selector) {
+	return ["Customize what you ask for and how people sign in: edit .zitadel/schemas/ to change the information you collect, and .zitadel/flows/ to change the sign-up/sign-in experience. Each folder has a README with examples.", `See your changes before they go live: ${projectCommand("deploy --dry-run", selector, cliVersion)} to preview, then ${projectCommand(DEPLOY_ARGS, selector, cliVersion)} to publish. Nothing is released yet, so publishing is what pins this configuration rather than leaving the project on whatever its newest revisions happen to be.`];
+}
+/**
+* How to change the login's look after setup. Setup never ejects a template
+* or publishes a branding revision (#1039): the app embeds the maintained
+* `<zitadel-login>`, so its look is the app's own CSS (`--zl-*` tokens) and
+* layout around it. Taking ownership of the widget's structure stays the
+* opt-in `branding eject`, surfaced here so it remains discoverable.
+*/
+function brandingGuidanceAction(cliVersion) {
+	return `Change how the login looks: it is a component in your app, so theme it with \`--zl-*\` custom properties in your own stylesheet and build any page layout around it in your code. To change the widget's structure, ${publicCliCommand("branding eject", cliVersion)} scaffolds an editable template in .zitadel/branding/.`;
+}
+//#endregion
+//#region src/lib/skills-hint.ts
+const SHOWN_FILE = "skills-hint.json";
+const INSTALL_COMMAND = "npx skills add zitadel/nextgen --full-depth";
+/**
+* Tell a developer who has AI coding agents installed how to give them the
+* Zitadel skills, once per machine and after the command's own next steps.
+* The CLI never installs anything itself: it names the command and the
+* developer runs it. Modelled on Wrangler's skills suggestion, minus the prompt.
+*
+* The marker lives in the user's CLI config directory (`telemetryConfigDir`),
+* not in a project, so a second project on the same machine does not show it
+* again. It is written only once the note is about to be shown, and removed
+* again if showing it fails.
+*
+* Silent in CI, in non-interactive runs, when no agent is detected, once it has
+* been shown, and when `NO_SKILLS_PROMPT` is set. Fail-open: nothing here may
+* fail the command the user actually ran, and losing the race to create the marker
+* (`EEXIST`) just means another run is showing the note.
+*/
+async function showSkillsHint({ env, interactive }) {
+	try {
+		if (!interactive || isCI(env) || isOptedOut(env)) return;
+		const shownPath = join(telemetryConfigDir(env), SHOWN_FILE);
+		if (existsSync(shownPath)) return;
+		if (!(await rosie.agents()).some((agent) => agent.detected && agent.installPath !== null)) return;
+		mkdirSync(dirname(shownPath), { recursive: true });
+		writeFileSync(shownPath, `${JSON.stringify({ date: (/* @__PURE__ */ new Date()).toISOString() })}\n`, { flag: "wx" });
+		try {
+			consola$1.log([
+				"",
+				"Using an AI coding agent?",
+				"Install Zitadel skills to help your agent work with Zitadel’s CLI and authentication integrations:",
+				"",
+				`  ${command(INSTALL_COMMAND)}`,
+				"",
+				"Optional. You can continue without installing skills."
+			].join("\n"));
+		} catch (error) {
+			unlinkSync(shownPath);
+			throw error;
+		}
+	} catch {}
+}
+function isCI(env) {
+	return Boolean(env.CI) && env.CI !== "0" && env.CI !== "false";
+}
+function isOptedOut(env) {
+	const value = env.NO_SKILLS_PROMPT?.trim().toLowerCase();
+	return value !== void 0 && value !== "" && value !== "0" && value !== "false";
+}
+//#endregion
+export { checkGivenCustomFlags as $, isPortableShellWord as $t, readJsonDirEntries as A, toVariableRow as At, selectSchema as B, installUserAgent as Bt, isPolicyTestFile as C, isErrno$1 as Cn, checkFlow as Ct, policyFileName as D, parseVariableValue as Dt, policyFileIssues as E, assertVariableName as Et, authMethods as F, variableReadScope as Ft, republishArgs as G, resolveConsent as Gt, publishClientId as H, hostAgent as Ht, enabledMethods as I, variableScope as It, askConnectionEndpoints as J, inShell as Jt, republishCommands as K, envEnabled as Kt, methodsOf as L, reportWarning as Lt, COMMAND_GROUPS as M, valuesOfKind as Mt, CommandGroups as N, variableCells as Nt, toPolicyWireBody as O, readStdin as Ot, compareInGroup as P, variableInventoryCells as Pt, SETUP_FLAG_NAMES as Q, unscopedCommand as Qt, readFlowFiles as R, takeReportedWarnings as Rt, POLICY_TEST_SUFFIX as S, ZitadelError as Sn, FLOWS_DIR as St, passwordPolicyFile as T, toZitadelError as Tn, VARIABLE_TYPES as Tt, reportClientIdOutcome as U, ciProvider as Ut, SCHEMAS_DIR as V, processUserAgentFacts as Vt, reportSecretOutcome as W, loadOrCreateIdentity as Wt, ENABLE_FLAG_NAMES as X, projectCommand as Xt, ENABLE_FLAG_KEYS as Y, portableSuggestions as Yt, SETUP_FLAG_KEYS as Z, shellCommand as Zt, servesPrimary as _, sanitizeRejection as _n, credentialVariablesOf as _t, serverLogAction as a, normalizePublicCliProse as an, loopbackIssuerWarning as at, PASSWORD_POLICY_PATH as b, listenForInterrupt as bn, refuseChangedIssuer as bt, wrapForBox as c, sdkVersionForCli as cn, applySsoToFlow as ct, validateStep as d, parseJsonObject as dn, removeSsoFromSchema as dt, isTrainVersion as en, customExample as et, headSha as f, setTopLevelJsonKey as fn, ssoEditRefusal as ft, rollbackDeployment as g, escapeControlCharacters as gn, checkCustomSlug as gt, listLiveDeployments as h, createZitadelClient$1 as hn, IDPS_DIR as ht, exploreAllCommands as i, normalizePublicCliJson as in, givenCustomFlags as it, BRANDING_DIR as j, toVariableRows as jt, readJsonDir as k, toInventoryRows as kt, DEPLOY_ARGS as l, collectPages as ln, applySsoToSchema as lt, createDeployment as m, REQUEST_TIMEOUT_MS as mn, CONNECTION_SCHEMA_REF as mt, brandingGuidanceAction as n, normalizePublicCliCommand as nn, customFlagValues as nt, verifyLoginAction as o, optionArgs as on, selectionFromFlags as ot, worktreeIsDirty as p, stableStringify as pn, ssoProvidersRefusal as pt, storeClientSecret as q, asEnvironmentSelector as qt, customizeAndPublishActions as r, normalizePublicCliCommands as rn, flagText as rt, renderBoxActions as s, publicCliCommand as sn, ssoEnableArgs as st, showSkillsHint as t, maskPublicCliVersion as tn, customFlagText as tt, diffStep as u, isObject$1 as un, removeSsoFromFlow as ut, buildBundle as v, sanitizeResponse as vn, planConnection as vt, parsePasswordMinLength as w, isMissingEndpoint as wn, offeredSignInMethods as wt, POLICIES_DIR as x, stopListeningForInterrupt as xn, storedCustomSettings as xt, PASSWORD_POLICY_OPERATION as y, interruptSignal as yn, readConnectionFiles as yt, readSchemaFiles as z, buildUserAgent as zt };
+
+//# sourceMappingURL=skills-hint-N1H5-ny1.mjs.map