@zitadel/cli 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -1,19 +1,22 @@
-import { $ as checkGivenCustomFlags, $t as isPortableShellWord, A as readJsonDirEntries, At as toVariableRow, B as selectSchema, Bt as installUserAgent, C as isPolicyTestFile, Cn as isErrno$2, Ct as checkFlow, D as policyFileName, Dt as parseVariableValue, E as policyFileIssues, Et as assertVariableName, F as authMethods, Ft as variableReadScope, G as republishArgs, Gt as resolveConsent, H as publishClientId, Ht as hostAgent, I as enabledMethods, It as variableScope, J as askConnectionEndpoints, Jt as inShell, K as republishCommands, Kt as envEnabled, L as methodsOf, Lt as reportWarning, Mt as valuesOfKind, N as CommandGroups, Nt as variableCells, O as toPolicyWireBody, Ot as readStdin, Pt as variableInventoryCells, Q as SETUP_FLAG_NAMES, Qt as unscopedCommand, R as readFlowFiles, Rt as takeReportedWarnings, S as POLICY_TEST_SUFFIX, Sn as ZitadelError, St as FLOWS_DIR, T as passwordPolicyFile, Tn as toZitadelError, Tt as VARIABLE_TYPES, U as reportClientIdOutcome, Ut as ciProvider, V as SCHEMAS_DIR, Vt as processUserAgentFacts, W as reportSecretOutcome, Wt as loadOrCreateIdentity, X as ENABLE_FLAG_NAMES, Xt as projectCommand, Y as ENABLE_FLAG_KEYS, Yt as portableSuggestions, Z as SETUP_FLAG_KEYS, Zt as shellCommand, _ as servesPrimary, _n as sanitizeRejection, _t as credentialVariablesOf, a as serverLogAction, an as normalizePublicCliProse, at as loopbackIssuerWarning, b as PASSWORD_POLICY_PATH, bn as listenForInterrupt, bt as refuseChangedIssuer, c as wrapForBox, cn as sdkVersionForCli, ct as applySsoToFlow, d as validateStep, dn as parseJsonObject, dt as removeSsoFromSchema, en as isTrainVersion, et as customExample, f as headSha, fn as setTopLevelJsonKey, ft as ssoEditRefusal, g as rollbackDeployment, gn as escapeControlCharacters, gt as checkCustomSlug, h as listLiveDeployments, hn as createZitadelClient, ht as IDPS_DIR, i as exploreAllCommands, in as normalizePublicCliJson, it as givenCustomFlags, j as BRANDING_DIR, jt as toVariableRows, k as readJsonDir, kt as toInventoryRows, l as DEPLOY_ARGS, ln as collectPages, lt as applySsoToSchema, m as createDeployment, mn as REQUEST_TIMEOUT_MS$1, mt as CONNECTION_SCHEMA_REF, n as brandingGuidanceAction, nn as normalizePublicCliCommand, nt as customFlagValues, o as verifyLoginAction, on as optionArgs, ot as selectionFromFlags, p as worktreeIsDirty, pn as stableStringify, pt as ssoProvidersRefusal, q as storeClientSecret, qt as asEnvironmentSelector, r as customizeAndPublishActions, rn as normalizePublicCliCommands, rt as flagText, s as renderBoxActions, sn as publicCliCommand, st as ssoEnableArgs, t as showSkillsHint, tn as maskPublicCliVersion, tt as customFlagText, u as diffStep, un as isObject, ut as removeSsoFromFlow, v as buildBundle, vn as sanitizeResponse, vt as planConnection, w as parsePasswordMinLength, wn as isMissingEndpoint, wt as offeredSignInMethods, x as POLICIES_DIR, xn as stopListeningForInterrupt, xt as storedCustomSettings, yn as interruptSignal, yt as readConnectionFiles, z as readSchemaFiles, zt as buildUserAgent } from "./skills-hint-N1H5-ny1.mjs";
+import { $ as republishCommands, $t as processUserAgentFacts, A as isPolicyTestFile, An as sanitizeResponse, At as checkFlow, B as CommandGroups, Bt as valuesOfKind, C as createReleaseFromBundle, Cn as parseJsonObject, Ct as checkCustomSlug, D as PASSWORD_POLICY_PATH, Dn as createZitadelClient$1, Dt as refuseChangedIssuer, En as REQUEST_TIMEOUT_MS$1, Et as readConnectionFiles, F as toPolicyWireBody, Fn as isErrno$2, Ft as parseVariableValue, G as readFlowFiles, Gt as renderDetail, H as authMethods, Ht as variableInventoryCells, I as readJsonDir, In as isMissingEndpoint, It as readStdin, J as SCHEMAS_DIR, Jt as renderTable, K as readSchemaFiles, Kt as renderList, L as readJsonDirEntries, Ln as toZitadelError, Lt as toInventoryRows, M as passwordPolicyFile, Mn as listenForInterrupt, Mt as VARIABLE_TYPES, N as policyFileIssues, Nn as stopListeningForInterrupt, Nt as assertVariableName, O as POLICIES_DIR, On as escapeControlCharacters, Ot as storedCustomSettings, P as policyFileName, Pn as ZitadelError, Pt as frozenVariables, Q as republishArgs, Qt as installUserAgent, R as BRANDING_DIR, Rt as toVariableRow, S as servesPrimary, Sn as isObject, St as IDPS_DIR, T as buildBundle, Tn as stableStringify, Tt as planConnection, U as enabledMethods, Ut as variableReadScope, Vt as variableCells, W as methodsOf, Wt as variableScope, X as reportClientIdOutcome, Xt as takeReportedWarnings, Y as publishClientId, Yt as reportWarning, Z as reportSecretOutcome, Zt as buildUserAgent, _ as worktreeIsDirty, _n as normalizePublicCliJson, _t as removeSsoFromFlow, a as serverLogAction, an as nonBlankArg, at as SETUP_FLAG_NAMES, b as createDeployment, bn as publicCliCommand, bt as ssoProvidersRefusal, c as wrapForBox, cn as inShell, ct as customFlagText, d as deployMessage, dn as shellCommand, dt as givenCustomFlags, en as hostAgent, et as storeClientSecret, f as messageFlag, fn as unscopedCommand, ft as loopbackIssuerWarning, g as headSha, gn as normalizePublicCliCommands, gt as applySsoToSchema, h as runSteps, hn as maskPublicCliVersion, ht as applySsoToFlow, i as exploreAllCommands, in as envEnabled, it as SETUP_FLAG_KEYS, j as parsePasswordMinLength, jn as interruptSignal, jt as offeredSignInMethods, k as POLICY_TEST_SUFFIX, kn as sanitizeRejection, kt as FLOWS_DIR, l as DEPLOY_ARGS, ln as portableSuggestions, lt as customFlagValues, m as validateStep, mn as isTrainVersion, mt as ssoEnableArgs, n as brandingGuidanceAction, nn as loadOrCreateIdentity, nt as ENABLE_FLAG_KEYS, o as verifyLoginAction, on as nonBlankString, ot as checkGivenCustomFlags, p as deployInitialRelease, pn as isPortableShellWord, pt as selectionFromFlags, q as selectSchema, qt as renderRows, r as customizeAndPublishActions, rn as resolveConsent, rt as ENABLE_FLAG_NAMES, s as renderBoxActions, sn as asEnvironmentSelector, st as customExample, t as showSkillsHint, tn as ciProvider, tt as askConnectionEndpoints, u as diffStep, un as projectCommand, ut as flagText, v as Repository, vn as normalizePublicCliProse, vt as removeSsoFromSchema, w as revokeRelease, wn as setTopLevelJsonKey, wt as credentialVariablesOf, x as rollbackDeployment, xn as sdkVersionForCli, xt as CONNECTION_SCHEMA_REF, y as RepositoryError, yn as optionArgs, yt as ssoEditRefusal, zt as toVariableRows } from "./skills-hint-C8oe8cCo.mjs";
 import { createRequire } from "node:module";
 import { Args, Command, Flags } from "@oclif/core";
 import consola$1, { consola } from "consola";
 import { ApiError, CSRF_HEADER, request } from "@zitadel/api/runtime/fetch";
-import { access, chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { itemsOf, nextToken, pages } from "@zitadel/api/runtime/paging";
+import { pagedFunctions } from "@zitadel/api/client";
+import { access, chmod, cp, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { text } from "node:stream/consumers";
 import * as schemas from "@zitadel/api/generated/endpoints/zitadelNextGen.zod";
 import { CreateGrantBody, CreateIdpBody, CreateTeamBody, CreateUserBody, GetBrandingByIdResponse, GetFlowDefinitionResponse, GetGrantResponse, GetIdpByIdResponse, GetPolicyResponse, GetProjectResponse, GetReleaseByIdResponse, GetSchemaByIdResponse, GetSessionResponse, GetTeamResponse, GetUserByIDResponse, ListBrandingResponse, ListEventsResponse, ListFlowDefinitionsResponse, ListPoliciesResponse, ListReleasesResponse, ListSchemasResponse, PatchProjectBody, PatchUserByIDBody, PublishPolicyBody, QueryGrantsBody, QueryGrantsResponse, QueryIdpsBody, QueryIdpsResponse, QueryProjectsBody, QueryProjectsResponse, QuerySessionsBody, QuerySessionsResponse, QueryTeamsBody, QueryTeamsResponse, QueryUsersBody, QueryUsersResponse, UpdateTeamBody, getClaimStatusQueryChallengeIdRegExp } from "@zitadel/api/generated/endpoints/zitadelNextGen.zod";
+import { API_PREFIX, apiBaseUrl } from "@zitadel/api/runtime/base-url";
 import { operations } from "@zitadel/api/generated/operations";
 import { createHash, pbkdf2Sync, randomBytes, randomUUID } from "node:crypto";
 import { execFile, spawn, spawnSync } from "node:child_process";
 import { basename, delimiter, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
 import { constants, existsSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { isDeepStrictEqual, parseEnv, promisify } from "node:util";
+import { isDeepStrictEqual, parseEnv } from "node:util";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { StringDecoder } from "node:string_decoder";
 import { resolveServerBinary, serverBinaryPath } from "@zitadel/server/binary";
@@ -24,12 +27,41 @@ import mixpanelLib from "mixpanel";
 import { cancel, confirm, intro, isCancel, log, multiselect, note, outro, password, select, spinner, text as text$1 } from "@clack/prompts";
 import { RECOMMENDED_PASSWORD_MIN_LENGTH, policyConfigSchema, policyTestFileSchema, schemaConfigSchema } from "@zitadel/config/schemas";
 import { CUSTOM_PROVIDER, DEFAULT_SCOPES, IDP_PROVIDERS, RESERVED_SLUGS, credentialVariables, idpProvider, isVariableReference, parseClientId, parseClientSecret, parseConnectionSlug, parseDisplayName, parseIssuer, parseScopes, providerOf, selectionName, validated } from "@zitadel/config/idp";
-import { BRANDING_DESIGNS, DEFAULT_BRANDING_CONFIG_PATH, DEFAULT_BRANDING_DESIGN, DEFAULT_BRANDING_TEMPLATE_PATH, DEFAULT_FLOW_CONFIG_PATH, DEFAULT_FLOW_SCHEMA_URI, DEFAULT_SCHEMA_CONFIG_PATH, DEFAULT_SETUP_PRESET, DEFAULT_SETUP_USE_CASE, SETUP_PRESETS, SETUP_USE_CASES, brandingReadmeContent, flowsReadmeContent, getDefaultBrandingConfig, getDefaultHumanUserSchema, getDefaultLoginFlow, policiesReadmeContent, schemasReadmeContent } from "@zitadel/config/defaults";
+import { BRANDING_DESIGNS, DEFAULT_BRANDING_CONFIG_PATH, DEFAULT_BRANDING_DESIGN, DEFAULT_BRANDING_TEMPLATE_PATH, DEFAULT_FLOW_CONFIG_PATH, DEFAULT_FLOW_SCHEMA_URI, DEFAULT_SCHEMA_CONFIG_PATH, DEFAULT_SETUP_PRESET, DEFAULT_SETUP_USE_CASE, SETUP_PRESETS, SETUP_USE_CASES, brandingReadmeContent, flowsReadmeContent, getDefaultBrandingConfig, getDefaultHumanUserSchemaBody, getDefaultLoginFlow, policiesReadmeContent, schemasReadmeContent } from "@zitadel/config/defaults";
 import { BRANDING_FILE_SCHEMA_REF, META_SCHEMA_DIR, PROJECT_FILE_SCHEMA_REF, metaSchemaFiles } from "@zitadel/config/meta-schemas";
 import { defaultHumanUserSchemaUrl } from "@zitadel/config";
 import semver from "semver";
 import { builders, generateCode, parseModule } from "magicast";
+import { ListEventsCategoryItem, ListFlowDefinitionsRevisions, ListSchemasRevisions, QueryGrantsBodyFilterItemOperation, QueryIdpsBodyFilterItemOperation, QueryProjectsBodyFilterItemOperation, QuerySessionsBodyFilterItemOperation, QueryTeamsBodyFilterItemOperation, QueryUsersBodyFilterItemOperation } from "@zitadel/api/generated/model";
 import { normalizeFlowBody, normalizeIdpBody, normalizeSchemaBody } from "@zitadel/config/normalize";
+import * as rosie from "rosie-skills";
+//#region src/lib/oclif/crud/paging.ts
+/**
+* The first page `pages` yields, or with `all` every page in order, as one
+* list of the items `items` takes from each page. `next` reads a page's
+* cursor to report it: the cursor to the page after the first, or `null` once
+* `all` has read the last page.
+*
+* Following the cursor is the walk's job, not this one's: a client function's
+* `.pages()` reads it from the page as the server sent it, before the CLI
+* escapes the page, so it goes back to the server unchanged. Without `all`
+* the walk is left after its first page, so no second one is fetched.
+*/
+const collectPages = async (pages, { items, all, next }) => {
+	const collected = [];
+	for await (const page of pages) {
+		collected.push(...items(page));
+		if (!all) return {
+			items: collected,
+			next: next(page) || null
+		};
+	}
+	return {
+		items: collected,
+		next: null
+	};
+};
+//#endregion
 //#region src/lib/oclif/crud/zod.ts
 /**
 * Depth limit for peeling wrappers. A generated schema nests a handful at
@@ -549,7 +581,7 @@ const fieldExample = (fields) => {
 //#endregion
 //#region src/lib/api/operations.ts
 /** Every operation of the API the CLI was built with. */
-const OPERATIONS = operations;
+const OPERATIONS$1 = operations;
 const LIST = unscopedCommand("api ls --json");
 /**
 * Why the CLI cannot call an operation, or `undefined` when it can. It holds a
@@ -566,7 +598,7 @@ const uncallable = (operation) => {
 * The operations `zitadel api ls` lists: those of one tag, and those whose id,
 * path, summary or tag contains the filter, both in any case.
 */
-const findOperations = ({ filter, tag }) => OPERATIONS.filter((operation) => (tag === void 0 || operation.tag.toLowerCase() === tag.toLowerCase()) && (filter === void 0 || [
+const findOperations = ({ filter, tag }) => OPERATIONS$1.filter((operation) => (tag === void 0 || operation.tag.toLowerCase() === tag.toLowerCase()) && (filter === void 0 || [
 	operation.id,
 	operation.path,
 	operation.summary,
@@ -576,12 +608,13 @@ const findOperations = ({ filter, tag }) => OPERATIONS.filter((operation) => (ta
 const pathParameterNames = (operation) => [...operation.path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1] ?? "");
 /**
 * The operation an argument names: an `operationId` (in any case, as the docs
-* and `@zitadel/api` spell it), or a path starting with `/`, matched against
-* the spec's templates. `method` is `-X`: with a path it picks among the
+* and `@zitadel/api` spell it), or a path starting with `/`, with or without
+* the API prefix, matched against the spec's templates. `method` is `-X`: with a path it picks among the
 * path's methods; with an id it must be the operation's own.
 */
 const resolveTarget = (ref, method) => {
 	const wanted = method?.toUpperCase();
+	if (ref.startsWith(`${API_PREFIX}/`)) return byPath(ref.slice(API_PREFIX.length), wanted);
 	if (!ref.startsWith("/")) {
 		const operation = byId(ref);
 		if (wanted !== void 0 && wanted !== operation.method) throw new ZitadelError("E_VALIDATION", `${operation.id} is ${operation.method} ${operation.path}, not ${wanted}`, { hint: `Leave out -X, or pass -X ${operation.method}.` });
@@ -594,10 +627,10 @@ const resolveTarget = (ref, method) => {
 	return byPath(ref, wanted);
 };
 const byId = (ref) => {
-	const operation = OPERATIONS.find((candidate) => candidate.id.toLowerCase() === ref.toLowerCase());
+	const operation = OPERATIONS$1.find((candidate) => candidate.id.toLowerCase() === ref.toLowerCase());
 	if (operation) return operation;
 	const wanted = ref.toLowerCase();
-	const near = OPERATIONS.filter((candidate) => {
+	const near = OPERATIONS$1.filter((candidate) => {
 		const id = candidate.id.toLowerCase();
 		return id.includes(wanted) || distance(id, wanted) <= 2;
 	}).map((candidate) => candidate.id);
@@ -653,7 +686,7 @@ const byPath = (ref, method) => {
 	const path = at === -1 ? ref : ref.slice(0, at);
 	const query = new URLSearchParams(at === -1 ? "" : ref.slice(at + 1));
 	const segments = segmentsOf(path.length > 1 ? path.replace(/\/$/, "") : path);
-	const matches = (segments ? OPERATIONS : []).map((operation) => ({
+	const matches = (segments ? OPERATIONS$1 : []).map((operation) => ({
 		operation,
 		match: matchOf(operation.path, segments ?? [])
 	})).filter((candidate) => candidate.match !== void 0);
@@ -663,7 +696,7 @@ const byPath = (ref, method) => {
 		hint: "List the paths with `zitadel api ls`.",
 		nextCommands: [LIST]
 	});
-	const methods = OPERATIONS.filter((operation) => operation.path === template.operation.path);
+	const methods = OPERATIONS$1.filter((operation) => operation.path === template.operation.path);
 	const operation = method === void 0 ? methods.length === 1 ? methods[0] : methods.find((candidate) => candidate.method === "GET") : methods.find((candidate) => candidate.method === method);
 	if (!operation) {
 		const offered = methods.map((candidate) => candidate.method).join(", ");
@@ -679,11 +712,11 @@ const byPath = (ref, method) => {
 //#region src/lib/api/request.ts
 /** The flag a field is given with, which errors name. */
 const FIELD = "--field";
-/** The URL a request goes to on `server`. */
+/** The URL a request goes to on `server`: the API under `/api/v1` there, then the spec's path. */
 const urlOf = (server, request) => {
 	const query = new URLSearchParams(request.query.map(([name, value]) => [name, value]));
 	const search = query.size > 0 ? `?${query}` : "";
-	return `${server.replace(/\/+$/, "")}${request.path}${search}`;
+	return `${apiBaseUrl(server)}${request.path}${search}`;
 };
 /**
 * The generated Zod schema for one part of an operation's request:
@@ -834,7 +867,15 @@ const readBody = async (res) => {
 * (`createZitadelClient`), and what the server says is escaped the same way:
 * a non-2xx is the {@link ApiError} `toZitadelError` maps to an exit code.
 */
-const send = async (server, token, request$1) => {
+const send = async (server, token, request) => {
+	const { status, raw } = await sendRaw(server, token, request);
+	return {
+		status,
+		body: sanitizeResponse(raw)
+	};
+};
+/** {@link send}, answering the body as the server sent it; a failure is escaped all the same. */
+const sendRaw = async (server, token, request$1) => {
 	const url = urlOf(server, request$1);
 	const { method } = request$1.operation;
 	const headers = new Headers({ accept: "application/json" });
@@ -851,7 +892,7 @@ const send = async (server, token, request$1) => {
 	if (!res.ok) sanitizeRejection(new ApiError(res.status, url, rawBody, `${method} ${url} returned ${res.status}`));
 	return {
 		status: res.status,
-		body: sanitizeResponse(rawBody)
+		raw: rawBody
 	};
 };
 /** The request for the page `token` names; `undefined` leaves the request as it is. */
@@ -872,33 +913,39 @@ const pageOf = (request, token) => {
 };
 /**
 * Send a paged request until the server's `next_page_token` runs out, and
-* answer the last page with the page field holding every page's items. The
-* walk is `collectPages`, the resource lists' `--all`, so a server that
-* repeats a cursor is caught the same way.
+* answer the last page with the page field holding every page's items.
 */
 const sendAll = async (server, token, request) => {
 	const paging = request.operation.paging;
 	if (paging === null) return send(server, token, request);
 	let last = {
 		status: 200,
-		body: void 0
+		raw: void 0
 	};
-	const { items } = await collectPages(async (cursor) => {
-		last = await send(server, token, pageOf(request, cursor));
-		return last.body;
-	}, {
-		items: paging.items,
+	const walk = pages(async (cursor) => {
+		last = await sendRaw(server, token, pageOf(request, cursor));
+		return last.raw;
+	}, { next: nextToken });
+	const { items } = await collectPages(walk, {
+		items: (raw) => {
+			try {
+				return sanitizeResponse(itemsOf(raw, paging.items));
+			} catch (error) {
+				throw new ZitadelError("E_VALIDATION", error instanceof Error ? error.message : String(error), { details: { response: sanitizeResponse(raw) } });
+			}
+		},
 		all: true,
-		nextPageToken: "next_page_token",
-		flags: {
-			all: "--paginate",
-			onePage: "-F limit=<n> and -F page_token=<token>"
-		}
+		next: nextToken
+	});
+	const page = isObject(last.raw) ? last.raw : {};
+	const body = sanitizeResponse({
+		...page,
+		[paging.items]: []
 	});
 	return {
 		status: last.status,
 		body: {
-			...last.body,
+			...body,
 			[paging.items]: items
 		}
 	};
@@ -919,41 +966,6 @@ const curlOf = (server, request) => [
 	...request.body === void 0 ? [] : ["-H 'Content-Type: application/json'", `-d ${quote(JSON.stringify(request.body))}`]
 ].join(" \\\n  ");
 //#endregion
-//#region src/lib/oclif/flags.ts
-/**
-* Refuse a value that is present but holds nothing.
-*
-* `required: true` is no help: it asks whether a token arrived in argv, and an
-* empty one satisfies it. The way this happens is the shell, not a typo —
-* `--client-id "$CLIENT_ID"` with the variable unset sends exactly that, the
-* expansion dropping the value while the quotes keep the word, so argv carries
-* `["--client-id", ""]`. Unquoted, the word vanishes and oclif refuses with
-* "expects a value"; quoted, nothing complained and the empty string travelled
-* on as if it were a real answer.
-*
-* Refusing during parse rather than in each command puts it at the same point
-* oclif's own refusal lands, so both spellings of a missing value fail the same
-* way, and the value that reaches `run` is already trimmed.
-*/
-function refuseBlank(input, label, message) {
-	const value = input.trim();
-	if (value === "") throw new ZitadelError("E_VALIDATION", message, {
-		hint: `Pass a value for ${label}, or omit it entirely.`,
-		details: { argument: label }
-	});
-	return value;
-}
-/**
-* A string flag whose value must not be blank. See {@link refuseBlank}.
-*
-* Not for a flag that writes a field value: an empty string is a legitimate
-* thing to store, so the generated resource flags in `crud/fields.ts` keep
-* plain `Flags.string`.
-*/
-const nonBlankString = Flags.custom({ parse: async (input, _command, flag) => refuseBlank(input, `--${flag.name}`, "the value is empty") });
-/** A positional argument whose value must not be blank. See {@link refuseBlank}. */
-const nonBlankArg = Args.custom({ parse: async (input, _command, arg) => refuseBlank(input, arg.name, `${arg.name} was given an empty value`) });
-//#endregion
 //#region src/lib/local-server/processes.ts
 /** The real answer: the machine's processes, read with `ps`. */
 var PsLocalServers = class {
@@ -4428,6 +4440,36 @@ function deviceProfileProperties(meta, distinctId) {
 	};
 }
 //#endregion
+//#region src/lib/oclif/next-steps.ts
+/** Made right after a command printed its next steps itself; nothing else calls it. */
+function asStepsShown() {
+	return {};
+}
+/**
+* The steps as envelope keys: `next_actions` and `next_commands`, each one
+* present exactly when the command set that list.
+*/
+function nextStepsData(next) {
+	return {
+		...next.actions === void 0 ? {} : { next_actions: [...next.actions] },
+		...next.commands === void 0 ? {} : { next_commands: [...next.commands] }
+	};
+}
+/**
+* The block a run ends with: the prose, then each command on a `$` line, or
+* `""` when there is nothing to do next.
+*/
+function renderNextSteps(next) {
+	const actions = next.actions ?? [];
+	const commands = next.commands ?? [];
+	if (actions.length === 0 && commands.length === 0) return "";
+	return [
+		"Next:",
+		...actions.map((action) => `  ${action}`),
+		...commands.map((command) => `  $ ${command}`)
+	].join("\n");
+}
+//#endregion
 //#region src/lib/shell.ts
 /**
 * Quote a value for safe interpolation into a `nextCommands` string an agent or
@@ -4687,9 +4729,10 @@ var BaseCommand = class extends Command {
 		return Boolean(process.stdout.isTTY && process.stdin.isTTY);
 	}
 	/**
-	* Final step of every command: in human mode it prints the rendered result
-	* (oclif suppresses {@link Command.log} under `--json`); it returns the
-	* envelope so oclif's `--json` path serialises it.
+	* Final step of every command: in human mode it prints the rendered result,
+	* then the result's next steps, then its footer (oclif suppresses
+	* {@link Command.log} under `--json`); it returns the envelope so oclif's
+	* `--json` path serialises it.
 	*/
 	emit(result) {
 		const normalized = normalizeCommandResult(result, this.meta);
@@ -4698,8 +4741,11 @@ var BaseCommand = class extends Command {
 			status: result.status,
 			duration_ms: Date.now() - this.telemetryStartedAt
 		}));
-		const rendered = renderPretty(normalized, this.meta);
+		const next = normalized.status === "ok" && normalized.nextShown !== void 0 ? "" : renderNextSteps(normalized.next ?? {});
+		const beside = normalized.status === "ok" && normalized.machineReadable === true;
+		const rendered = renderPretty(normalized, this.meta, beside ? "" : next);
 		if (rendered !== "") this.log(rendered);
+		if (beside && next !== "") this.logToStderr(rendered !== "" && process.stdout.isTTY ? `\n${next}` : next);
 		if (normalized.status === "ok" && normalized.footer !== void 0) this.log(`\n${normalized.footer}`);
 		const reported = takeReportedWarnings();
 		const envelope = toEnvelope(withReportedWarnings(normalized, reported), this.meta);
@@ -4774,22 +4820,26 @@ var BaseCommand = class extends Command {
 		};
 	}
 };
+/** Rewrites each suggested `zitadel …` command to the public form the reader can run. */
 function normalizeCommandResult(result, meta) {
-	if (result.status === "ok") return {
-		...result,
-		data: normalizeDataNextCommands(result.data, meta)
-	};
+	if (result.next?.commands === void 0) return result;
+	const commands = normalizePublicCliCommands(result.next.commands, meta.cliVersion);
 	return {
 		...result,
-		data: normalizeDataNextCommands(result.data, meta),
-		nextCommands: normalizePublicCliCommands(result.nextCommands, meta.cliVersion)
+		next: {
+			...result.next,
+			commands
+		}
 	};
 }
-function normalizeDataNextCommands(data, meta) {
-	if (!isObject(data) || !Array.isArray(data.next_commands)) return data;
-	return {
+/**
+* The data with its next steps written in. Data that is not an object (a
+* write the server answered without a body) has nowhere to hold them.
+*/
+function withNextSteps(data, next) {
+	return next === void 0 || !isObject(data) ? data : {
 		...data,
-		next_commands: data.next_commands.map((command) => typeof command === "string" ? normalizePublicCliCommand(command, meta.cliVersion) : command)
+		...nextStepsData(next)
 	};
 }
 /** Add the warnings reported while the command ran to an ok result. */
@@ -4820,7 +4870,7 @@ function toEnvelope(result, meta) {
 	if (result.status === "ok") return {
 		...base,
 		status: "ok",
-		data: result.data,
+		data: withNextSteps(result.data, result.next),
 		warnings: result.warnings ? [...result.warnings] : []
 	};
 	return {
@@ -4828,7 +4878,7 @@ function toEnvelope(result, meta) {
 		status: "skipped",
 		reason: result.reason,
 		data: result.data,
-		next_commands: result.nextCommands ? [...result.nextCommands] : void 0
+		next_commands: result.next?.commands ? [...result.next.commands] : void 0
 	};
 }
 /** Builds the failure envelope from a {@link ZitadelError} and the invocation metadata. */
@@ -4849,20 +4899,21 @@ function toErrorEnvelope(error, meta) {
 * Renders a {@link CommandResult} as human-facing text for non-JSON mode. A
 * command may supply a bespoke `pretty` string (e.g. `deploy`'s summary);
 * otherwise success payloads are summarised by {@link formatData} and skips are
-* shown with their reason and follow-up commands.
+* shown with their reason. `next` is the rendered next-step block, which
+* follows the rendering whichever it is, and comes before the warnings.
 */
-function renderPretty(result, meta) {
+function renderPretty(result, meta, next) {
 	if (result.pretty !== void 0) {
 		const warnings = result.status === "ok" ? result.warnings ?? [] : [];
-		return [result.pretty, ...warnings.map((warning) => `Warning: ${warning}`)].filter((line) => line !== "").join("\n");
-	}
-	if (result.status === "ok") return formatData(result.data, result.warnings ? [...result.warnings] : [], meta);
-	const lines = [`Skipped: ${result.reason}${suffixBlock(meta)}`];
-	if (result.nextCommands && result.nextCommands.length > 0) {
-		lines.push("Next:");
-		for (const cmd of result.nextCommands) lines.push(`  $ ${cmd}`);
+		const gap = result.status === "ok" ? "\n" : "";
+		return [
+			next === "" || result.pretty === "" ? result.pretty : `${result.pretty.replace(/\n+$/, "")}${gap}`,
+			next,
+			...warnings.map((warning) => `Warning: ${warning}`)
+		].filter((line) => line !== "").join("\n");
 	}
-	return lines.join("\n");
+	if (result.status === "ok") return formatData(result.data, result.warnings ? [...result.warnings] : [], meta, next);
+	return [`Skipped: ${result.reason}${suffixBlock(meta)}`, next].filter(Boolean).join("\n");
 }
 /**
 * Renders a {@link ZitadelError} as a human-readable block for stderr: the
@@ -4871,38 +4922,23 @@ function renderPretty(result, meta) {
 function renderError(error, meta) {
 	const lines = [`Error ${error.code}: ${error.message}`];
 	if (error.hint) lines.push(error.hint);
-	const nextCommands = normalizePublicCliCommands(error.nextCommands, meta.cliVersion);
-	if (nextCommands && nextCommands.length > 0) {
-		lines.push("Next:");
-		for (const cmd of nextCommands) lines.push(`  $ ${cmd}`);
-	}
+	const next = renderNextSteps({ commands: normalizePublicCliCommands(error.nextCommands, meta.cliVersion) });
+	if (next !== "") lines.push(next);
 	return lines.join("\n");
 }
-function formatData(data, warnings, opts) {
+function formatData(data, warnings, opts, next) {
 	if (typeof data === "string") {
 		const suffix = sourceSuffix(opts);
-		return suffix ? `${data}\n${suffix}` : data;
+		const text = suffix ? `${data}\n${suffix}` : data;
+		return next === "" ? text : `${text}\n\n${next}`;
 	}
 	const lines = [];
 	const titleLine = isObject(data) && typeof data.title === "string" ? String(data.title) : "Zitadel command completed.";
 	lines.push(titleLine);
 	const suffix = sourceSuffix(opts);
 	if (suffix) lines.push(suffix);
-	if (isObject(data)) {
-		renderKnownSections(lines, data);
-		if (Array.isArray(data.next_actions) && data.next_actions.length > 0) {
-			lines.push("");
-			lines.push("Next:");
-			for (const action of data.next_actions) lines.push(`  ${String(action)}`);
-		}
-		if (Array.isArray(data.next_commands) && data.next_commands.length > 0) {
-			if (!Array.isArray(data.next_actions) || data.next_actions.length === 0) {
-				lines.push("");
-				lines.push("Next:");
-			}
-			for (const cmd of data.next_commands) lines.push(`  $ ${String(cmd)}`);
-		}
-	}
+	if (isObject(data)) renderKnownSections(lines, data);
+	if (next !== "") lines.push("", next);
 	for (const warning of warnings.filter((warning) => !warningRenderedInChecks(data, warning))) lines.push(`Warning: ${warning}`);
 	return lines.join("\n");
 }
@@ -5772,8 +5808,8 @@ var EnvironmentCommand = class extends BaseCommand {
 	* terminal: on a pipe the result travels alone, and `--json` silences them
 	* either way. `quiet` is for a command whose own output is that summary.
 	*
-	* `verbatim` is for a caller that stores or compares what it reads (see
-	* `SanitizeOptions`).
+	* `verbatim` is for a caller that stores, compares or sends back what it
+	* reads (see `SanitizeOptions`).
 	* `prompt: false` is for a best-effort probe that must never stop to ask
 	* (or write `.env.<name>.local`): a missing value then fails as it would
 	* non-interactively.
@@ -5797,7 +5833,7 @@ var EnvironmentCommand = class extends BaseCommand {
 			consola.info(`Server    ${server}`);
 		}
 		return {
-			client: createZitadelClient({
+			client: createZitadelClient$1({
 				baseUrl: server,
 				token
 			}, { verbatim: options.verbatim }),
@@ -6149,71 +6185,6 @@ async function publishedIdsOf(cwd, path) {
 	}
 }
 //#endregion
-//#region src/lib/oclif/envelope.ts
-/**
-* Builders for the `data` of a command's JSON envelope.
-*
-* Every command emits `data`, and an agent reads all of them, so the shapes
-* must not drift. These builders are the one place each shape is defined; the
-* spec harness (`assertEnvelope`) enforces the same shapes on every `--json`
-* invocation, so a command that hand-builds a divergent shape fails in its own
-* spec. Use the builder rather than an object literal.
-*/
-/**
-* The canonical list/collection envelope: `{ items, count, next_page_token }`,
-* plus optional `next_commands`. Every command that returns a collection emits
-* this, so `{ items, count, next_page_token }` reads uniformly across all of
-* them. A single-page endpoint passes `nextPageToken: null` (the default); a
-* paginated one passes the server cursor (or `null` once drained).
-*/
-function listData(items, opts = {}) {
-	const base = {
-		items,
-		count: items.length,
-		next_page_token: opts.nextPageToken ?? null
-	};
-	return opts.nextCommands && opts.nextCommands.length > 0 ? {
-		...base,
-		next_commands: opts.nextCommands
-	} : base;
-}
-/**
-* The canonical delete/remove confirmation: the resource's identifier plus
-* `deleted: true`. The verb is always `deleted` — never `removed` — so an agent
-* reads "did the delete succeed?" the same way for every resource, whether it is
-* addressed by `id` or by a natural key (`url`, `pattern`, `name`). A lifecycle
-* verb (revoke, deactivate) uses {@link mutatedData} instead.
-*/
-function deletedData(identifier) {
-	return {
-		...identifier,
-		deleted: true
-	};
-}
-/**
-* A mutation confirmation whose verb is the lifecycle action, not `deleted`:
-* the identifier plus `<verb>: true` (e.g. `revoked`, `deactivated`). Keeps the
-* `{ identifier, <past-tense>: true }` shape of {@link deletedData} while naming
-* the specific action.
-*/
-function mutatedData(identifier, verb) {
-	return {
-		...identifier,
-		[verb]: true
-	};
-}
-/**
-* The `next_commands` a command's `data` carries, spread into the data object:
-* `{ ...result, ...nextCommandsData(commands) }`. It takes `SuggestedCommand`s,
-* which only the `lib/suggestion` builders make, so every entry has had its
-* environment selector decided (#1689). A Biome GritQL rule
-* (`biome-plugins/no-raw-next-commands.grit`) rejects a hand-written
-* `next_commands:` key anywhere else.
-*/
-function nextCommandsData(commands) {
-	return { next_commands: commands };
-}
-//#endregion
 //#region src/lib/oclif/promptable.ts
 /**
 * Marks a command that can ask a person a question, and gives it the one way
@@ -6353,7 +6324,8 @@ var AuthMethodCommand = class extends Promptable(EnvironmentCommand) {
 	}
 	/**
 	* The follow-up commands of a result, as strings when every argument is
-	* safe to run as written, and always as argument lists.
+	* safe to run as written (the result's `next` commands), and always as
+	* argument lists (its `next_args`).
 	*
 	* @param changed - Whether a file changed, which `deploy` then publishes.
 	* @param cwdArgs - `--cwd` for `deploy`, from {@link target}.
@@ -6372,8 +6344,8 @@ var AuthMethodCommand = class extends Promptable(EnvironmentCommand) {
 			...cwdArgs
 		]] : []];
 		return {
-			...nextCommandsData(portableSuggestions(args, this.meta.cliVersion, [DEPLOY_MESSAGE])),
-			next_args: args
+			commands: portableSuggestions(args, this.meta.cliVersion, [DEPLOY_MESSAGE]),
+			args
 		};
 	}
 	/**
@@ -6443,12 +6415,14 @@ var AuthMethodCommand = class extends Promptable(EnvironmentCommand) {
 			consola.success(`Updated ${schema.path}`);
 		} else consola.info(`${method} is already ${verb}d for ${schema.name}`);
 		this.reportOutcome(outcome);
+		const followUps = this.followUps(change.changed, cwdArgs);
 		return this.emit({
 			status: "ok",
 			data: {
 				...data,
-				...this.followUps(change.changed, cwdArgs)
+				next_args: followUps.args
 			},
+			next: { commands: followUps.commands },
 			pretty: change.changed ? `${enabled ? "Enabled" : "Disabled"} ${method} for ${schema.name}` : `Nothing to ${verb} for ${schema.name}`
 		});
 	}
@@ -6607,7 +6581,7 @@ var Api = class Api extends Promptable(BaseCommand) {
 	}
 	/** Choose an operation the CLI can call: its part of the API, then the operation. */
 	async chooseOperation() {
-		const callable = OPERATIONS.filter((operation) => uncallable(operation) === void 0);
+		const callable = OPERATIONS$1.filter((operation) => uncallable(operation) === void 0);
 		const retry = this.suggestUnscoped("api ls --json");
 		const tag = await this.input({
 			kind: "select",
@@ -6652,69 +6626,6 @@ var Api = class Api extends Promptable(BaseCommand) {
 	}
 };
 //#endregion
-//#region src/lib/oclif/crud/table.ts
-/**
-* The machine form of a list: one record per line, fields separated by tabs,
-* no header and no padding, so `cut -f2` and `awk -F'\t'` work. This is what a
-* piped run emits — the aligned table is for a terminal, where nothing is
-* parsing it. Tabs and newlines inside a value would break the record, so they
-* are escaped rather than passed through.
-*/
-const renderRows = (columns, items) => items.map((item) => columns.map((column) => readCell(column, item).replaceAll("	", "\\t").replaceAll("\n", "\\n")).join("	")).join("\n");
-/**
-* Render `items` as an aligned text table, one column per dot-path in
-* `columns`, headed by each path's last segment. Nested paths resolve
-* through objects; missing values render empty; non-strings render as JSON.
-*/
-const renderTable = (columns, items) => {
-	const headers = columns.map((column) => column.split(".").at(-1) ?? column);
-	const rows = items.map((item) => columns.map((column) => readCell(column, item)));
-	const widths = rows.reduce((current, row) => current.map((width, i) => Math.max(width, row[i]?.length ?? 0)), headers.map((header) => header.length));
-	const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join("  ").trimEnd();
-	return [
-		line(headers),
-		line(widths.map((width) => "-".repeat(width))),
-		...rows.map(line)
-	].join("\n");
-};
-/**
-* The whole terminal rendering of a list, so no command re-derives the
-* plain/TTY/empty/footer logic (and so none forgets `--plain`): a pipe (or
-* `--plain`) gets tab-separated rows with no header and nothing when empty, so
-* `cut`/`awk`/`wc -l` work; a terminal gets the aligned table, a blank line, a
-* `${n} ${singular|plural}` count, and any `footer` lines. Pair it with
-* `listData()` for the JSON envelope.
-*/
-const renderList = (columns, rows, opts) => {
-	if (opts.plain) return renderRows(columns, rows);
-	if (rows.length === 0) return opts.empty;
-	const count = `${rows.length} ${rows.length === 1 ? opts.singular : opts.plural ?? `${opts.singular}s`}`;
-	return [
-		renderTable(columns, rows),
-		"",
-		count,
-		...opts.footer ?? []
-	].join("\n");
-};
-/** One cell: a dot-path resolved through objects, rendered as text. */
-const readCell = (column, item) => {
-	const value = column.split(".").reduce((current, key) => isObject(current) ? current[key] : void 0, item);
-	return value == null ? "" : typeof value === "string" ? value : JSON.stringify(value);
-};
-/**
-* One record for a person: the heading first, then a labelled field per line.
-* Nested paths are labelled by their last segment, so `metadata.status` reads
-* as `status`. It is the terminal rendering of `get`; a pipe (and `--json`)
-* still receives the whole object, since a script wants the record, not a view
-* of it.
-*/
-const renderDetail = (heading, fields, item) => {
-	const rows = fields.map((field) => [field.split(".").at(-1) ?? field, readCell(field, item)]).filter(([, value]) => value !== "");
-	const width = Math.max(0, ...rows.map(([label]) => label.length));
-	const body = rows.map(([label, value]) => `${label.padEnd(width)}  ${value}`);
-	return [...heading ? [heading, ""] : [], ...body].join("\n");
-};
-//#endregion
 //#region src/commands/api/ls.ts
 /** One operation as `api ls` lists it. */
 const entryOf = (operation) => ({
@@ -6920,12 +6831,14 @@ var AuthMethodSsoDisable = class AuthMethodSsoDisable extends AuthMethodCommand
 		for (const path of changed) consola.success(`Updated ${path}`);
 		if (changed.length === 0) consola.info(`${schema.name} does not offer ${provider}`);
 		this.reportOutcome(outcome);
+		const followUps = this.followUps(changed.length > 0, cwdArgs);
 		return this.emit({
 			status: "ok",
 			data: {
 				...data,
-				...this.followUps(changed.length > 0, cwdArgs)
+				next_args: followUps.args
 			},
+			next: { commands: followUps.commands },
 			pretty: changed.length > 0 ? `Removed ${provider} from ${where}` : `${schema.name} does not offer ${provider}`
 		});
 	}
@@ -7166,11 +7079,11 @@ var AuthMethodSsoEnable = class AuthMethodSsoEnable extends AuthMethodCommand {
 		const unpublished = !reusing || written.length > 0;
 		const stored = secret?.published === "stored" && (clientIdState === void 0 || clientIdState === "stored") ? ["Provider credentials are stored on your Project."] : [];
 		const name = entry.displayName;
+		const followUps = this.followUps(unpublished, scopeArgs, recovery);
 		return this.emit({
 			status: "ok",
 			data: {
 				title: unpublished ? [`${name} sign-in is configured locally.`, ...stored].join(" ") : `${name} sign-in is already configured locally.`,
-				...unpublished ? { next_actions: [`Deploy the configuration to make ${name} sign-in available in your app, then reload your app and test ${name} sign-in.`] } : {},
 				...this.payload({
 					projectId,
 					provider,
@@ -7183,7 +7096,11 @@ var AuthMethodSsoEnable = class AuthMethodSsoEnable extends AuthMethodCommand {
 					changed: written,
 					skipped: edits.skipped
 				}),
-				...this.followUps(unpublished, scopeArgs, recovery)
+				next_args: followUps.args
+			},
+			next: {
+				...unpublished ? { actions: [`Deploy the configuration to make ${name} sign-in available in your app, then reload your app and test ${name} sign-in.`] } : {},
+				commands: followUps.commands
 			}
 		});
 	}
@@ -7557,50 +7474,6 @@ async function linkOnPath(cwd, path) {
 	}
 }
 //#endregion
-//#region src/lib/release/release.ts
-/**
-* Build a release from the `.zitadel/` bundle (`POST /releases/build`). The
-* server reuses the revisions that already match and allocates the rest, and
-* dedupes on content: re-posting the same bundle returns the release that
-* already carries it. (`POST /releases` pins pre-existing revision ids and is
-* not a CLI flow.)
-*/
-async function createReleaseFromBundle(client, projectId, bundle, source) {
-	const body = {
-		bundle,
-		...source.message === void 0 ? {} : { message: source.message },
-		...source.gitSha === null ? {} : { git_sha: source.gitSha },
-		git_dirty: source.gitDirty
-	};
-	return await client.buildRelease(body, { project_id: projectId });
-}
-/** Revoke a release so its content is never served again. Idempotent. */
-async function revokeRelease(client, projectId, releaseId) {
-	return client.revokeRelease(releaseId, { project_id: projectId });
-}
-//#endregion
-//#region src/lib/release/pipeline.ts
-/**
-* Run the before-release steps in order, skipping the ones that do not apply to
-* this publish or that write on a dry run, and return what they report, for the
-* command's `--json` data. The command creates the release and the deployment
-* itself, between and after the step groups: before-release steps → create
-* release → before-deploy steps → create deployment.
-*/
-async function runSteps(steps, ctx) {
-	let report = {};
-	for (const step of steps) {
-		if (!step.runsFor.includes(ctx.mode)) continue;
-		if (ctx.dryRun && step.writes) continue;
-		const reported = await step.run(ctx);
-		if (reported) report = {
-			...report,
-			...reported
-		};
-	}
-	return report;
-}
-//#endregion
 //#region src/lib/release/origins.ts
 /**
 * Whether an origin pattern covers a concrete origin URL, matching the server's
@@ -7681,9 +7554,11 @@ var BrandingEject = class BrandingEject extends Promptable(BaseCommand) {
 			status: "ok",
 			data: {
 				design,
-				files_written: filesWritten,
-				next_actions: [`Edit ${DEFAULT_BRANDING_TEMPLATE_PATH} — the login UI is yours now.`, "Deploy --dry-run validates the template and shows the diff; deploy publishes it."],
-				...nextCommandsData([this.suggestUnscoped("deploy --dry-run"), this.suggestUnscoped(DEPLOY_ARGS)])
+				files_written: filesWritten
+			},
+			next: {
+				actions: [`Edit ${DEFAULT_BRANDING_TEMPLATE_PATH} — the login UI is yours now.`, "Deploy --dry-run validates the template and shows the diff; deploy publishes it."],
+				commands: [this.suggestUnscoped("deploy --dry-run"), this.suggestUnscoped(DEPLOY_ARGS)]
 			}
 		});
 	}
@@ -7811,12 +7686,15 @@ async function policiesFromFiles(cwd, operations = []) {
 async function policiesFromRelease(client, projectId, releaseId) {
 	const release = await client.getReleaseById(releaseId, { project_id: projectId });
 	const pinned = release.pointers.filter((pointer) => pointer.kind === "policy");
-	const revisions = await Promise.all(pinned.map((pointer) => client.getPolicyRevision(pointer.revision_id, { project_id: projectId })));
-	return {
-		policies: new Map(pinned.map((pointer, index) => [pointer.handle, {
-			config: revisions[index]?.config,
+	const revisions = await Promise.all(pinned.map(async (pointer) => {
+		const revision = await client.getPolicyRevision(pointer.revision_id, { project_id: projectId });
+		return [pointer.handle, {
+			config: revision.config,
 			source: { revision_id: pointer.revision_id }
-		}])),
+		}];
+	}));
+	return {
+		policies: new Map(revisions),
 		revoked: release.revoked_at !== null,
 		pinsFlow: release.pointers.some((pointer) => pointer.kind === "flow_definition")
 	};
@@ -8408,7 +8286,7 @@ var Claim = class Claim extends EnvironmentCommand {
 					project_id: projectId,
 					would: localRecord && !flags["no-wait"] ? `${action}, then record the owning team in .zitadel/secret.` : `${action}.`
 				},
-				nextCommands: [challengeId === void 0 ? startOver : this.suggest(`claim --challenge-id ${challengeId}`)]
+				next: { commands: [challengeId === void 0 ? startOver : this.suggest(`claim --challenge-id ${challengeId}`)] }
 			});
 		}
 		const { client } = prompted ?? await this.connect();
@@ -8478,9 +8356,9 @@ var Claim = class Claim extends EnvironmentCommand {
 				project_id: projectId,
 				team_id: completed.team_id,
 				claimed_at: completed.claimed_at,
-				dashboard_url: completed.dashboard_url,
-				next_actions: ["Manage your Project and collaborate in the Console:", completed.dashboard_url]
-			}
+				dashboard_url: completed.dashboard_url
+			},
+			next: { actions: ["Manage your Project and collaborate in the Console:", completed.dashboard_url] }
 		});
 	}
 	/**
@@ -8558,9 +8436,11 @@ var Claim = class Claim extends EnvironmentCommand {
 				project_id: projectId,
 				claim_url: challenge.claim_url,
 				challenge_id: challenge.challenge_id,
-				expires_at: challenge.expires_at,
-				next_actions: ["Wait for the browser step to finish with:"],
-				...nextCommandsData(isChallengeId(challenge.challenge_id) ? [this.suggest(`claim --challenge-id ${challenge.challenge_id}`)] : [])
+				expires_at: challenge.expires_at
+			},
+			next: {
+				actions: ["Wait for the browser step to finish with:"],
+				commands: isChallengeId(challenge.challenge_id) ? [this.suggest(`claim --challenge-id ${challenge.challenge_id}`)] : []
 			}
 		});
 	}
@@ -8834,14 +8714,18 @@ async function consoleSignInUrl(serverUrl, admin) {
 	const { handoffToken } = await signIn(serverUrl, admin);
 	return `${serverUrl}/ui/console/login?handoff=${encodeURIComponent(handoffToken)}`;
 }
+/** The names the server sets its session cookie under (ADR 083), over plain http to a loopback host and over https. */
+const SESSION_COOKIES = ["zitadel_session", "__Host-zitadel_session"];
 /**
-* Signs in and trades the handoff token for the `__nextgen_session` cookie —
-* the credential endpoints like `claim/complete` authenticate against, which a
-* bare handoff token cannot satisfy.
+* Signs in and trades the handoff token for the session cookie — the
+* credential endpoints like `claim/complete` authenticate against, which a bare
+* handoff token cannot satisfy. It is `zitadel_session` from a server on
+* loopback http and `__Host-zitadel_session` from one on https, and goes back
+* under the name it came with.
 */
 async function adminSessionCookie(serverUrl, admin) {
 	const { handoffToken, publishableKey } = await signIn(serverUrl, admin);
-	const { res } = await request(`${serverUrl}/sessions/exchange?project_id=${encodeURIComponent(PLATFORM_PROJECT_ID)}`, {
+	const { res } = await request(`${apiBaseUrl(serverUrl)}/sessions/exchange?project_id=${encodeURIComponent(PLATFORM_PROJECT_ID)}`, {
 		...localAdminRequest(serverUrl, {
 			"content-type": "application/json",
 			authorization: `Bearer ${publishableKey}`
@@ -8849,7 +8733,7 @@ async function adminSessionCookie(serverUrl, admin) {
 		method: "POST",
 		body: JSON.stringify({ handoff_token: handoffToken })
 	}, { signal: interruptSignal() });
-	const cookie = res.headers.getSetCookie().find((value) => value.startsWith("__nextgen_session="))?.split(";", 1)[0];
+	const cookie = res.headers.getSetCookie().map((value) => value.split(";", 1)[0] ?? "").find((pair) => SESSION_COOKIES.some((name) => pair.startsWith(`${name}=`)));
 	if (!res.ok || !cookie) throw new ZitadelError("E_AUTH", `Local admin session exchange failed (${String(res.status)})`, { details: { status: res.status } });
 	return cookie;
 }
@@ -8864,7 +8748,7 @@ async function signIn(serverUrl, admin) {
 		nextCommands: [unscopedCommand("stop"), unscopedCommand("start")],
 		details: { server_url: serverUrl }
 	});
-	const client = createZitadelClient({
+	const client = createZitadelClient$1({
 		baseUrl: serverUrl,
 		token: runtime.publishable_key
 	});
@@ -8957,9 +8841,9 @@ var Console = class Console extends BaseCommand {
 				title: "Local console sign-in link.",
 				signed_in_as: admin.email,
 				sign_in_url: signInUrl,
-				browser_opened: opened,
-				next_actions: ["The link signs you in once. Run `zitadel console` again for a fresh one."]
-			}
+				browser_opened: opened
+			},
+			next: { actions: ["The link signs you in once. Run `zitadel console` again for a fresh one."] }
 		});
 	}
 };
@@ -9017,30 +8901,30 @@ var Deploy = class Deploy extends EnvironmentCommand {
 	static group = CommandGroups.configuration;
 	static groupOrder = 1;
 	static examples = ["<%= config.bin %> deploy -m 'add phone_number to human-user'", "<%= config.bin %> deploy --dry-run"];
-	static flags = { message: Flags.string({
-		char: "m",
-		description: "A short summary of what this release changes."
-	}) };
+	static flags = { message: messageFlag("A short summary of what this release changes. Defaults to the pull request's title or the current commit's subject.") };
 	async run() {
 		const { flags } = await this.parse(Deploy);
 		await this.toMeta(flags);
 		const { cwd, env, dryRun, isTTY, nonInteractive } = this.meta;
 		const json = this.jsonEnabled();
 		const color = !json && isTTY && flags.color !== false && !process.env.NO_COLOR;
-		const message = flags.message?.trim() ? flags.message.trim() : void 0;
-		if (nonInteractive && !dryRun && message === void 0) throw new ZitadelError("E_VALIDATION", "A deploy needs a message in non-interactive mode", { hint: "Pass -m/--message with a short summary of what this release changes." });
+		const message = dryRun ? void 0 : await deployMessage(flags.message, cwd, env);
+		if (nonInteractive && !dryRun && message === void 0) throw new ZitadelError("E_VALIDATION", "A deploy needs a message in non-interactive mode", { hint: "Pass -m/--message with a short summary of what this release changes, or deploy from a clean git commit." });
 		const { client, projectId } = await this.connect();
 		let landing = [];
 		if (!dryRun) {
-			const origins = (await client.getProject(projectId)).origins ?? [];
+			const origins = (await client.getProject(projectId)).origins;
 			landing = origins.filter((entry) => entry.kind === "primary").map((entry) => entry.pattern);
-			if (landing.length === 0) throw noPrimaryOriginError({
-				origins,
-				issuer: this.environment.values.ZITADEL_ISSUER?.value,
-				setupProject: await setupProjectId(cwd) === projectId,
-				selector: this.environmentSelector(),
-				cliVersion: this.meta.cliVersion
-			});
+			if (landing.length === 0) {
+				const setupProject = await setupProjectId(cwd);
+				throw noPrimaryOriginError({
+					origins,
+					issuer: this.environment.values.ZITADEL_ISSUER?.value,
+					setupProject: setupProject === projectId,
+					selector: this.environmentSelector(),
+					cliVersion: this.meta.cliVersion
+				});
+			}
 		}
 		const { bundle, resourceCount, brandingSources, idpFiles, policyFiles } = await buildBundle(cwd);
 		this.recordTelemetry({ resources: resourceCount });
@@ -9076,7 +8960,10 @@ var Deploy = class Deploy extends EnvironmentCommand {
 			gitSha: await headSha(cwd),
 			gitDirty
 		});
-		const observed = (await listLiveDeployments(client, projectId)).find((deployment) => deployment.targets.some((entry) => landing.includes(entry.origin)))?.id;
+		const observed = (await client.listDeployments.all({
+			project_id: projectId,
+			live: true
+		})).find((deployment) => deployment.targets.some((entry) => landing.includes(entry.origin)))?.id;
 		const targets = ["primary"];
 		let deployment;
 		try {
@@ -9095,7 +8982,10 @@ var Deploy = class Deploy extends EnvironmentCommand {
 					content_hash: release.content_hash
 				}
 			});
-			const current = (await listLiveDeployments(client, projectId)).find(servesPrimary);
+			const current = (await client.listDeployments.all({
+				project_id: projectId,
+				live: true
+			})).find(servesPrimary);
 			throw new ZitadelError("E_CONFLICT", "Another deploy changed the targets since this one was prepared", {
 				hint: `Re-run \`zitadel ${DEPLOY_ARGS}${this.environmentSelector()}\`; it will build and deploy against the current state.`,
 				details: current === void 0 ? void 0 : { current_deployment: current },
@@ -9112,9 +9002,9 @@ var Deploy = class Deploy extends EnvironmentCommand {
 				deployment_id: deployment.id,
 				resources: resourceCount,
 				origins: servedOrigins,
-				...reported,
-				...nextCommandsData([this.suggest("deployment list")])
+				...reported
 			},
+			next: { commands: [this.suggest("deployment list")] },
 			pretty: [
 				`Deployed ${release.content_hash}`,
 				`  ${resourceCount} resource${resourceCount === 1 ? "" : "s"} to ${servedOrigins.length} origin${servedOrigins.length === 1 ? "" : "s"}`,
@@ -9222,9 +9112,9 @@ var DeploymentCreate = class DeploymentCreate extends EnvironmentCommand {
 			data: {
 				deployment_id: deployment.id,
 				release_id: deployment.release_id,
-				origins,
-				...nextCommandsData([this.suggest("deployment list")])
+				origins
 			},
+			next: { commands: [this.suggest("deployment list")] },
 			pretty: [`Deployed ${deployment.release_id} to ${origins.length} origin${origins.length === 1 ? "" : "s"}`, ...origins.map((origin) => `  - ${origin}`)].join("\n")
 		});
 	}
@@ -9233,7 +9123,8 @@ var DeploymentCreate = class DeploymentCreate extends EnvironmentCommand {
 //#region src/commands/deployment/get.ts
 /**
 * `zitadel deployment get <deployment_id>` — read one deployment record: the
-* release it made live, the origins it went to, and when.
+* release it made live, the origins it went to, when, and the variables it
+* froze.
 */
 var DeploymentGet = class DeploymentGet extends EnvironmentCommand {
 	static description = "Read one deployment by id.";
@@ -9247,7 +9138,8 @@ var DeploymentGet = class DeploymentGet extends EnvironmentCommand {
 		const { args, flags } = await this.parse(DeploymentGet);
 		await this.toMeta(flags);
 		const { client, projectId } = await this.connect();
-		const deployment = await client.getDeploymentById(args.deployment_id, { project_id: projectId });
+		const scope = { project_id: projectId };
+		const [deployment, variables] = await Promise.all([client.getDeploymentById(args.deployment_id, scope), this.jsonEnabled() ? void 0 : client.getDeploymentVariables(args.deployment_id, scope)]);
 		const origins = deployment.targets.map((target) => target.origin);
 		return this.emit({
 			status: "ok",
@@ -9257,12 +9149,62 @@ var DeploymentGet = class DeploymentGet extends EnvironmentCommand {
 				`  release   ${deployment.release_id}`,
 				`  reason    ${deployment.metadata.reason ?? "deploy"}`,
 				`  deployed  ${deployment.deployed_at}`,
-				`  origins   ${origins.join(", ")}`
+				`  origins   ${origins.join(", ")}`,
+				...variables === void 0 ? [] : ["", frozenVariables(toVariableRows(variables))]
 			].join("\n")
 		});
 	}
 };
 //#endregion
+//#region src/lib/oclif/envelope.ts
+/**
+* Builders for the `data` of a command's JSON envelope.
+*
+* Every command emits `data`, and an agent reads all of them, so the shapes
+* must not drift. These builders are the one place each shape is defined; the
+* spec harness (`assertEnvelope`) enforces the same shapes on every `--json`
+* invocation, so a command that hand-builds a divergent shape fails in its own
+* spec. Use the builder rather than an object literal.
+*/
+/**
+* The canonical list/collection envelope: `{ items, count, next_page_token }`.
+* Every command that returns a collection emits this, so it reads uniformly
+* across all of them. A single-page endpoint passes `nextPageToken: null` (the
+* default); a paginated one passes the server cursor (or `null` once drained).
+*/
+function listData(items, opts = {}) {
+	return {
+		items,
+		count: items.length,
+		next_page_token: opts.nextPageToken ?? null
+	};
+}
+/**
+* The canonical delete/remove confirmation: the resource's identifier plus
+* `deleted: true`. The verb is always `deleted` — never `removed` — so an agent
+* reads "did the delete succeed?" the same way for every resource, whether it is
+* addressed by `id` or by a natural key (`url`, `pattern`, `name`). A lifecycle
+* verb (revoke, deactivate) uses {@link mutatedData} instead.
+*/
+function deletedData(identifier) {
+	return {
+		...identifier,
+		deleted: true
+	};
+}
+/**
+* A mutation confirmation whose verb is the lifecycle action, not `deleted`:
+* the identifier plus `<verb>: true` (e.g. `revoked`, `deactivated`). Keeps the
+* `{ identifier, <past-tense>: true }` shape of {@link deletedData} while naming
+* the specific action.
+*/
+function mutatedData(identifier, verb) {
+	return {
+		...identifier,
+		[verb]: true
+	};
+}
+//#endregion
 //#region src/commands/deployment/list.ts
 /** The columns `list` renders, in order. */
 const COLUMNS$6 = [
@@ -9310,24 +9252,22 @@ var DeploymentList = class DeploymentList extends EnvironmentCommand {
 		const { flags } = await this.parse(DeploymentList);
 		await this.toMeta(flags);
 		const { client, projectId } = await this.connect();
-		const request = (token) => client.listDeployments({
+		const params = {
 			project_id: projectId,
-			...flags.origin === void 0 ? {} : { origin: flags.origin },
-			...flags.live ? { live: true } : {},
-			...flags.limit === void 0 ? {} : { limit: flags.limit },
-			...token === void 0 ? {} : { page_token: token }
-		});
-		const { items, next } = await collectPages(request, {
-			items: "deployments",
+			origin: flags.origin,
+			live: flags.live,
+			limit: flags.limit,
+			page_token: flags["page-token"]
+		};
+		const { items: deployments, next } = await collectPages(client.listDeployments.pages(params), {
+			items: (page) => page.deployments,
 			all: flags.all === true,
-			token: flags["page-token"],
-			nextPageToken: "next_page_token"
+			next: (page) => page.next_page_token
 		});
-		const deployments = items;
 		const rows = deployments.map((deployment) => ({
 			id: deployment.id,
 			release_id: deployment.release_id,
-			reason: deployment.metadata.reason ?? "deploy",
+			reason: deployment.metadata.reason,
 			origins: deployment.targets.map((target) => target.origin).join(", "),
 			deployed_at: deployment.deployed_at
 		}));
@@ -9342,10 +9282,9 @@ var DeploymentList = class DeploymentList extends EnvironmentCommand {
 		const plain = flags.plain || !process.stdout.isTTY;
 		return this.emit({
 			status: "ok",
-			data: listData(deployments, {
-				nextPageToken: next,
-				nextCommands: nextCommand === void 0 ? void 0 : [nextCommand]
-			}),
+			data: listData(deployments, { nextPageToken: next }),
+			...nextCommand === void 0 ? {} : { next: { commands: [nextCommand] } },
+			machineReadable: plain,
 			pretty: renderList(COLUMNS$6, rows, {
 				plain,
 				singular: "deployment",
@@ -9380,31 +9319,26 @@ var DeploymentRollback = class DeploymentRollback extends Promptable(Environment
 		required: false,
 		description: "The deployment to re-apply. Omit to undo the last deploy."
 	}) };
-	static flags = { force: Flags.boolean({
-		char: "f",
-		description: "Roll back without the confirmation prompt. Required when non-interactive."
-	}) };
+	static flags = {
+		force: Flags.boolean({
+			char: "f",
+			description: "Roll back without the confirmation prompt. Required when non-interactive."
+		}),
+		message: messageFlag("A short summary of why this rolls back.")
+	};
 	async run() {
 		const { args, flags } = await this.parse(DeploymentRollback);
 		await this.toMeta(flags);
 		const { dryRun } = this.meta;
 		const { client, projectId } = await this.connect();
 		let targetId = args.deployment_id;
-		let bareGuard;
+		let expectedDeploymentId;
 		if (targetId === void 0) {
-			const { items } = await collectPages((token) => client.listDeployments({
-				project_id: projectId,
-				...token === void 0 ? {} : { page_token: token }
-			}), {
-				items: "deployments",
-				all: true,
-				nextPageToken: "next_page_token"
-			});
-			const [latest, prior] = items.filter(servesPrimary);
+			const [latest, prior] = (await client.listDeployments.all({ project_id: projectId })).filter(servesPrimary);
 			if (!latest) throw new ZitadelError("E_VALIDATION", "There is no deployment to roll back", { hint: `Nothing has been deployed yet; check \`zitadel deployment list${this.environmentSelector()}\`.` });
 			if (!prior) throw new ZitadelError("E_VALIDATION", "There is no earlier deployment to roll back to", { hint: `Name a deployment to re-apply, or check \`zitadel deployment list${this.environmentSelector()}\`.` });
 			targetId = prior.id;
-			bareGuard = latest.id;
+			expectedDeploymentId = latest.id;
 		}
 		if (dryRun) return this.emit({
 			status: "ok",
@@ -9414,7 +9348,10 @@ var DeploymentRollback = class DeploymentRollback extends Promptable(Environment
 			},
 			pretty: `Would re-apply ${targetId}. Nothing was rolled back (dry run).`
 		});
-		const expectedDeploymentId = bareGuard ?? await liveGuard(client, projectId);
+		if (expectedDeploymentId === void 0) expectedDeploymentId = (await client.listDeployments.all({
+			project_id: projectId,
+			live: true
+		})).find(servesPrimary)?.id;
 		if (!await this.input({
 			kind: "confirm",
 			name: `re-apply ${targetId}`,
@@ -9424,7 +9361,10 @@ var DeploymentRollback = class DeploymentRollback extends Promptable(Environment
 			status: "skipped",
 			reason: "rollback-cancelled"
 		});
-		const deployment = await rollbackDeployment(client, projectId, targetId, { ...expectedDeploymentId === void 0 ? {} : { expectedDeploymentId } });
+		const deployment = await rollbackDeployment(client, projectId, targetId, {
+			...flags.message === void 0 ? {} : { message: flags.message },
+			...expectedDeploymentId === void 0 ? {} : { expectedDeploymentId }
+		});
 		let pointers;
 		try {
 			pointers = (await client.getReleaseById(deployment.release_id, { project_id: projectId })).pointers;
@@ -9454,10 +9394,6 @@ var DeploymentRollback = class DeploymentRollback extends Promptable(Environment
 		});
 	}
 };
-/** The project's newest primary deployment, which a rollback is guarded by. */
-async function liveGuard(client, projectId) {
-	return (await listLiveDeployments(client, projectId)).find(servesPrimary)?.id;
-}
 //#endregion
 //#region src/lib/orca/detectors/package-json.ts
 /**
@@ -10590,7 +10526,7 @@ function agentsGuidanceSection(ctx) {
 	const jsxTypesNote = ctx.framework.id === "next" ? " React JSX types for the `<zitadel-*>` elements ship with the SDK — `custom-elements.d.ts` references `@zitadel/sdk-next/jsx`." : "";
 	const presentationParagraph = ctx.posture === "widget" ? "Presentation, by contrast, is edited in the generated pages: this app pre-dates setup, so they embed the sign-in widgets as `variant=\"widget\"` cards (with `theme=\"auto\"`) inside your existing layout; switch to `variant=\"page\"` for the widget's own full-page chrome, and set `theme` (`light` | `dark` | `auto`) to pick the color scheme — `auto` follows the OS `prefers-color-scheme`, not this app's own theme, so pin `light` or `dark` when the app fixes its scheme." : "Presentation, by contrast, is edited in the generated pages: they pin the sign-in widgets to `variant=\"page\"` (full-page chrome); switch to `variant=\"widget\"` to embed a card inside your own layout, and set `theme` (`light` | `dark` | `auto`) to pick the color scheme — `auto` follows the OS `prefers-color-scheme`, not this app's own theme, so pin `light` or `dark` when the app fixes its scheme.";
 	const themingParagraph = "Theming the widgets from your app: two hooks in your own stylesheet reach into their shadow DOM — the stable `--zl-*` design tokens, set on the element, and the parts `<zitadel-login>` forwards from its inner components as `zitadel-login::part(<atom>-<part>)` (the `card` part of `zl-card` is `zitadel-login::part(card-card)`). Both are listed under \"Style the login from your app\" in https://preview.zitadel.com/docs/guides/customize-design#style-the-login-from-your-app; any other `--zl-*` variable is internal. When your page already carries the heading, set the `suppress-header` attribute on `<zitadel-login>` / `<zitadel-session>` (SDK wrappers: `suppressHeader`) to visually hide the widget's own heading block — it stays in the accessibility tree. The login moves between sign-in and sign-up by itself (its own switch link, and an email it does or does not know), so a heading of your own must follow its `zitadel-flow-step` event, which the SDK wrappers forward: `step.purpose` is `login` while it signs in and `register` while it signs up. When it switches without being asked, the login tells the visitor why itself. To only reword the widget's heading, pass `locales` instead. Page layout around the widget (split screens, hero panes, marketing copy) is your app's code, not a Zitadel template.";
-	const sessionStateParagraph = ctx.framework.id === "next" ? "Your app's own chrome (header navigation, account menus) reads session state with `getSession({ projectId: process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID })` from `@zitadel/sdk-next/session` — a no-store client read of the same-origin `/__nextgen/sessions/me?project_id=…` that the session card itself uses. It returns identity only for 200 with a non-empty `user_id` in this app's project, and signed-out for the backend's canonical `401/auth.unauthorized`, `403/sess.project_mismatch` (a session of another project on the same host, such as the console's on localhost) or `404/sess.not_found`; any other response is unknown/error, never signed-out. In Server Components, `auth()` from `@zitadel/sdk-next/server` works too, on every page: the request boundary's `matcher` covers every route, which also makes `protectedRoutes` the one list of routes that need a sign-in (a protected route that a narrower `matcher` leaves out stays public). Sign-in and sign-out navigate (`post-sign-in-url` / `post-sign-out-url`), so chrome re-reads on the next page load without extra wiring." : ctx.framework.id === "nuxt" ? "Your app's own chrome (header navigation, account menus) reads session state with the auto-imported `useAuth()` composable — seeded from the server on every render by the scaffolded auth plugin. Sign-in and sign-out navigate (`post-sign-in-url` / `post-sign-out-url`), so the state is fresh on every page load." : "Your app's own chrome (header navigation, account menus) can read session state from the same-origin `/__nextgen/sessions/me?project_id=<project id>`, naming the project id the app passes to `configureZitadel()` — the same server-answered read the session card performs. Fetch with `credentials: \"include\"`, `cache: \"no-store\"`, and `Accept: application/json`; treat 200 as signed-in only with a non-empty `user_id` and that `project_id`, and signed-out only for the canonical error envelope `401/auth.unauthorized`, `403/sess.project_mismatch` (a session of another project on the same host, such as the console's on localhost) or `404/sess.not_found`. Any other response is unknown/error, never signed-out. Sign-in and sign-out navigate (`post-sign-in-url` / `post-sign-out-url`), so chrome re-reads on the next page load.";
+	const sessionStateParagraph = ctx.framework.id === "next" ? "Your app's own chrome (header navigation, account menus) reads session state with `getSession({ projectId: process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID })` from `@zitadel/sdk-next/session` — a no-store client read of the same-origin `/__nextgen/api/v1/sessions/me?project_id=…` that the session card itself uses. It returns identity only for 200 with a non-empty `user_id` in this app's project, and signed-out for the backend's canonical `401/auth.unauthorized`, `403/sess.project_mismatch` (a session of another project on the same host, such as the console's on localhost) or `404/sess.not_found`; any other response is unknown/error, never signed-out. In Server Components, `auth()` from `@zitadel/sdk-next/server` works too, on every page: the request boundary's `matcher` covers every route, which also makes `protectedRoutes` the one list of routes that need a sign-in (a protected route that a narrower `matcher` leaves out stays public). Sign-in and sign-out navigate (`post-sign-in-url` / `post-sign-out-url`), so chrome re-reads on the next page load without extra wiring." : ctx.framework.id === "nuxt" ? "Your app's own chrome (header navigation, account menus) reads session state with the auto-imported `useAuth()` composable — seeded from the server on every render by the scaffolded auth plugin. Sign-in and sign-out navigate (`post-sign-in-url` / `post-sign-out-url`), so the state is fresh on every page load." : "Your app's own chrome (header navigation, account menus) can read session state from the same-origin `/__nextgen/api/v1/sessions/me?project_id=<project id>`, naming the project id the app passes to `configureZitadel()` — the same server-answered read the session card performs. Fetch with `credentials: \"include\"`, `cache: \"no-store\"`, and `Accept: application/json`; treat 200 as signed-in only with a non-empty `user_id` and that `project_id`, and signed-out only for the canonical error envelope `401/auth.unauthorized`, `403/sess.project_mismatch` (a session of another project on the same host, such as the console's on localhost) or `404/sess.not_found`. Any other response is unknown/error, never signed-out. Sign-in and sign-out navigate (`post-sign-in-url` / `post-sign-out-url`), so chrome re-reads on the next page load.";
 	return `## Authentication (Zitadel)
 
 This app's login is managed by Zitadel. Local config is the source of truth for what the login collects and how sign-in works (step 3 below). The app files setup generated are yours to change, from the pages to the request boundary that protects routes in a server-rendered app: \`doctor\` reports a file you changed as \`edited\`, or as \`adopted\` once you delete its \`zitadel-cli: managed-file\` comment, and \`doctor --fix\` restores only a missing file, never one you changed.
@@ -10866,6 +10802,11 @@ var AbstractRulePatcher = class {
 					path,
 					wiring: op.wiring,
 					state: verdict
+				} : "outdated" in verdict ? {
+					path,
+					wiring: op.wiring,
+					state: "outdated",
+					reason: verdict.outdated
 				} : {
 					path,
 					wiring: op.wiring,
@@ -11571,8 +11512,27 @@ function angularRoutesEdit() {
 const PROXY_PATH = "/__nextgen";
 //#endregion
 //#region src/lib/orca/patchers/rule/proxy-credential-policy.ts
-/** Marker emitted after the exchange-only credential policy was introduced. */
-const PROXY_CREDENTIAL_POLICY_MARKER = "zitadel:proxy:v2";
+/**
+* Marker emitted with the exchange-only credential policy. Its v3 also attaches
+* the secret to the exchange under the API prefix (ADR 077).
+*/
+const PROXY_CREDENTIAL_POLICY_MARKER = "zitadel:proxy:v3";
+/** The marker of the exchange-only policy as it was before it knew the API prefix. */
+const PROXY_CREDENTIAL_POLICY_V2_MARKER = "zitadel:proxy:v2";
+/** Whether `source` carries the credential-policy marker of either version. */
+function hasProxyCredentialPolicyMarker(source) {
+	return source.includes("zitadel:proxy:v3") || source.includes("zitadel:proxy:v2");
+}
+/** The session exchange under the API prefix (ADR 077), as a browser calls it through the proxy. */
+const PREFIXED_EXCHANGE_PATH = `${API_PREFIX}/sessions/exchange`;
+/**
+* The generated proxies' path check: the exchange with and without the API
+* prefix, since the server answers both until 1.0.0 and an app's packages may
+* call either.
+*/
+const EXCHANGE_PATH_CHECK = `(pathname === "/sessions/exchange" || pathname === "${PREFIXED_EXCHANGE_PATH}")`;
+/** The path check of a v2 proxy, which knew only the unprefixed exchange. */
+const V2_EXCHANGE_PATH_CHECK = "pathname === \"/sessions/exchange\"";
 /**
 * Rejects a browser-reachable proxy that still appears to attach the project
 * secret without the complete exchange-only guard. Known generated legacy
@@ -11582,7 +11542,47 @@ const PROXY_CREDENTIAL_POLICY_MARKER = "zitadel:proxy:v2";
 */
 function assertNoUnreviewedProjectSecretProxy(source, label) {
 	if (!source.includes("/__nextgen") || !source.includes("ZITADEL_PROJECT_SECRET") || !/authorization/i.test(source) || hasExchangeOnlyGuard(source)) return;
-	throw new ZitadelError("E_VALIDATION", `${label} may forward ZITADEL_PROJECT_SECRET outside POST /sessions/exchange`, { hint: "Review the proxy manually: restrict the bearer to the exact POST /sessions/exchange pathname and preserve caller-provided authorization." });
+	throw new ZitadelError("E_VALIDATION", `${label} may forward ZITADEL_PROJECT_SECRET outside POST /sessions/exchange`, { hint: `Review the proxy manually: restrict the bearer to the exact POST /sessions/exchange or ${PREFIXED_EXCHANGE_PATH} pathname and preserve caller-provided authorization.` });
+}
+/** `code` without whitespace, with double quotes, so a formatter's layout compares equal. */
+function normalized(code) {
+	return code.replace(/\s+/g, "").replace(/'/g, "\"");
+}
+/** The terms of the conditions a guard may be built from, normalized. */
+const POST_TERM = "proxyReq.method===\"POST\"";
+const NO_OVERWRITE_TERM = "!proxyReq.getHeader(\"authorization\")";
+const PATH_TERMS = /* @__PURE__ */ new Set([
+	normalized(V2_EXCHANGE_PATH_CHECK),
+	normalized(EXCHANGE_PATH_CHECK),
+	normalized(`(pathname === "${PREFIXED_EXCHANGE_PATH}" || pathname === "/sessions/exchange")`)
+]);
+/** `condition`'s terms joined by `&&` outside any parentheses. */
+function andTerms(condition) {
+	const terms = [];
+	let depth = 0;
+	let start = 0;
+	for (let index = 0; index < condition.length; index++) {
+		const char = condition[index];
+		if (char === "(") depth++;
+		else if (char === ")") depth--;
+		else if (depth === 0 && condition.startsWith("&&", index)) {
+			terms.push(condition.slice(start, index));
+			start = index + 2;
+			index++;
+		}
+	}
+	terms.push(condition.slice(start));
+	return terms;
+}
+/**
+* Whether an `if` condition holds the bearer to the exchange: exactly the POST
+* check, the path check (the exchange, or both its spellings joined by `||`)
+* and the no-overwrite check, in any order. Anything more could widen it, as
+* `… || true` would, so it does not qualify.
+*/
+function isExchangeOnlyCondition(condition) {
+	const terms = andTerms(normalized(condition));
+	return terms.length === 3 && terms.includes(POST_TERM) && terms.includes(NO_OVERWRITE_TERM) && terms.some((term) => PATH_TERMS.has(term));
 }
 function hasExchangeOnlyGuard(source) {
 	const setterOffsets = [...source.matchAll(/proxyReq\s*\.\s*setHeader\s*\(\s*["']authorization["']\s*,/gi)].map((match) => match.index);
@@ -11590,7 +11590,7 @@ function hasExchangeOnlyGuard(source) {
 	const safeBodyRanges = [];
 	for (const match of source.matchAll(/if\s*\(([\s\S]*?)\)\s*\{([\s\S]*?)\}/g)) {
 		const [whole = "", condition = "", body = ""] = match;
-		if (!/proxyReq\s*\.\s*method\s*===\s*["']POST["']/i.test(condition) || !/pathname\s*===\s*["']\/sessions\/exchange["']/i.test(condition) || !/!\s*proxyReq\s*\.\s*getHeader\s*\(\s*["']authorization["']\s*\)/i.test(condition) || !/proxyReq\s*\.\s*setHeader\s*\(\s*["']authorization["']\s*,/i.test(body)) continue;
+		if (!isExchangeOnlyCondition(condition) || !/proxyReq\s*\.\s*setHeader\s*\(\s*["']authorization["']\s*,/i.test(body)) continue;
 		const bodyOffset = whole.lastIndexOf(body);
 		const start = match.index + bodyOffset;
 		safeBodyRanges.push({
@@ -11600,21 +11600,61 @@ function hasExchangeOnlyGuard(source) {
 	}
 	return setterOffsets.every((offset) => safeBodyRanges.some(({ start, end }) => offset >= start && offset < end));
 }
+//#endregion
+//#region src/lib/orca/patchers/rule/session-cookie.ts
+/**
+* The session-cookie hooks of the dev proxies the CLI writes for the SPA
+* frameworks (ADR 073, ADR 083). The server sets one session cookie,
+* `__Host-zitadel_session`, or `zitadel_session` over plain http to a loopback
+* host, and reads it as `__Host-zitadel_session`; a browser shares a host's
+* cookies across every port, so under that name alone an SPA on `localhost`
+* and the Console of a local server would keep their sessions in one slot and
+* sign each other out. The hooks keep the app's session in
+* `zitadel_session_<project id>` on a dev server reached over plain http to a
+* loopback host, and in `__Host-zitadel_session_<project id>` on any other,
+* the names the server SDKs use (`sessionCookieName` in `@zitadel/sdk-core`):
+*
+* - on the way up, the app's cookie goes once, under the server's
+*   `__Host-zitadel_session`, and every other session cookie stays back, those
+*   from before ADR 083 included;
+* - on the way back, the server's `Set-Cookie`, under either name, becomes the
+*   app's: its value and expiry with `Path=/`, `HttpOnly`, `SameSite=Lax`, and
+*   `Secure` unless the dev server is loopback http. A `Set-Cookie` of any
+*   other session cookie is dropped.
+*
+* The dev server's scheme is the first `X-Forwarded-Proto` (the entry's `xfwd`
+* sets it), else its own connection's, and its host the first
+* `X-Forwarded-Host`, else `Host`: the rule of `secureFor` in sdk-core.
+*
+* Without a project id the cookies pass through unchanged. The code is plain
+* JavaScript, so it runs in a `vite.config.*` and in Angular's CommonJS
+* `proxy.conf.cjs` alike, and in a `vite.config.ts` it type-checks under
+* `strict`: every parameter is one Vite's `configure(proxy)` typing reaches.
+*/
+/** Marks a generated dev proxy that carries the session-cookie hooks. */
+const SESSION_COOKIE_MARKER = "zitadel:session-cookie:v2";
+/**
+* Marks the hooks the CLI wrote before ADR 083, which name the
+* `__nextgen_session` cookies. The doctor fails on them, and `doctor --fix`
+* replaces them where they are as the CLI wrote them.
+*/
+const SESSION_COOKIE_MARKER_V1 = "zitadel:session-cookie:v1";
 /** Says what the hooks do, above them in the generated proxy. */
 const EXPLANATION = [
-	`/* zitadel:session-cookie:v1 */`,
+	`/* ${SESSION_COOKIE_MARKER} */`,
 	"// The browser keeps this app's session in a cookie named after its project,",
-	"// the server in __nextgen_session (ADR 073). Without a project id, cookies",
-	"// pass through."
+	"// zitadel_session_<project id>, prefixed __Host- unless this dev server is",
+	"// plain http on a loopback host; the server takes it as __Host-zitadel_session",
+	"// (ADR 083). Without a project id, cookies pass through."
 ];
 /**
-* `appCookie`, the app's cookie name for `projectId`, or `undefined` without
-* one. It percent-encodes every byte outside `[A-Za-z0-9_-]`, as
-* `sessionCookieName` in sdk-core does.
+* `appCookieSuffix`, what the app's cookie name adds for `projectId`, or
+* `undefined` without one. It percent-encodes every byte outside
+* `[A-Za-z0-9_-]`, as `sessionCookieName` in sdk-core does.
 */
-const APP_COOKIE = [
-	"const appCookie = projectId",
-	"  ? \"__nextgen_session_\" +",
+const APP_COOKIE_SUFFIX = [
+	"const appCookieSuffix = projectId",
+	"  ? \"_\" +",
 	"    projectId.replace(/[^\\w-]/gu, (char) =>",
 	"      Array.from(new TextEncoder().encode(char), (byte) =>",
 	"        \"%\" + byte.toString(16).toUpperCase().padStart(2, \"0\"),",
@@ -11622,11 +11662,28 @@ const APP_COOKIE = [
 	"    )",
 	"  : undefined;"
 ];
+/**
+* `secure` and `appCookie` for the browser's request `req`: the app's cookie
+* carries the prefix and `Secure` unless the dev server was reached over plain
+* http to a loopback host.
+*/
+const APP_COOKIE = [
+	"const proto = String(req.headers[\"x-forwarded-proto\"] ?? \"\").split(\",\")[0]?.trim() ||",
+	"  (\"encrypted\" in req.socket && req.socket.encrypted ? \"https\" : \"http\");",
+	"const host = String(req.headers[\"x-forwarded-host\"] ?? \"\").split(\",\")[0]?.trim() || (req.headers.host ?? \"\");",
+	"const secure =",
+	"  proto.toLowerCase() !== \"http\" ||",
+	"  !/^(?:localhost|127(?:\\.\\d{1,3}){3}|\\[::1\\])(?::\\d+)?$/i.test(host);",
+	"const appCookie = (secure ? \"__Host-zitadel_session\" : \"zitadel_session\") + appCookieSuffix;"
+];
+/** Matches a cookie of any session cookie family, the server's or an app's, on either transport or from before ADR 083. */
+const ANY_SESSION_COOKIE = "/^(?:__Host-)?(?:zitadel_session|__nextgen_session)(?:_[^=]*)?=/";
 /** The request hook's body, on `proxyReq`: only the app's cookie goes up, under the server's name. */
 const FORWARD_BODY = [
-	"if (!appCookie) {",
+	"if (!appCookieSuffix) {",
 	"  return;",
 	"}",
+	...APP_COOKIE,
 	"const cookies = String(proxyReq.getHeader(\"cookie\") ?? \"\")",
 	"  .split(\";\")",
 	"  .map((cookie) => cookie.trim())",
@@ -11634,9 +11691,9 @@ const FORWARD_BODY = [
 	"const own = cookies.find(",
 	"  (cookie) => cookie.startsWith(appCookie + \"=\") && cookie.length > appCookie.length + 1,",
 	");",
-	"const forwarded = cookies.filter((cookie) => !/^__nextgen_session(?:_[^=]*)?=/.test(cookie));",
+	`const forwarded = cookies.filter((cookie) => !${ANY_SESSION_COOKIE}.test(cookie));`,
 	"if (own) {",
-	"  forwarded.push(\"__nextgen_session\" + own.slice(appCookie.length));",
+	"  forwarded.push(\"__Host-zitadel_session\" + own.slice(appCookie.length));",
 	"}",
 	"if (forwarded.length > 0) {",
 	"  proxyReq.setHeader(\"cookie\", forwarded.join(\"; \"));",
@@ -11644,39 +11701,64 @@ const FORWARD_BODY = [
 	"  proxyReq.removeHeader(\"cookie\");",
 	"}"
 ];
-/** The response hook's body, on `proxyRes`: the server's `Set-Cookie` comes back under the app's name. */
+/**
+* The response hook's body, on `proxyRes`: the server's `Set-Cookie` comes back
+* as the app's, and one of any other session cookie not at all.
+*/
 const RENAME_BODY = [
 	"const setCookies = proxyRes.headers[\"set-cookie\"];",
-	"if (appCookie && setCookies) {",
-	"  proxyRes.headers[\"set-cookie\"] = setCookies.map((setCookie) =>",
-	"    setCookie.replace(/^__nextgen_session=/, appCookie + \"=\"),",
-	"  );",
-	"}"
+	"if (!appCookieSuffix || !setCookies) {",
+	"  return;",
+	"}",
+	...APP_COOKIE,
+	"proxyRes.headers[\"set-cookie\"] = setCookies.flatMap((setCookie) => {",
+	"  if (/^(?:__Host-)?zitadel_session=/.test(setCookie)) {",
+	"    const [pair = \"\", ...attributes] = setCookie.split(\";\");",
+	"    const expiry = attributes",
+	"      .map((attribute) => attribute.trim())",
+	"      .filter((attribute) => /^(?:max-age|expires)=/i.test(attribute));",
+	"    return [",
+	"      [",
+	"        appCookie + pair.slice(pair.indexOf(\"=\")),",
+	"        \"Path=/\",",
+	"        ...expiry,",
+	"        \"HttpOnly\",",
+	"        \"SameSite=Lax\",",
+	"        ...(secure ? [\"Secure\"] : []),",
+	"      ].join(\"; \"),",
+	"    ];",
+	"  }",
+	`  return ${ANY_SESSION_COOKIE}.test(setCookie) ? [] : [setCookie];`,
+	"});"
 ];
 /** `lines`, each indented by two more spaces. */
 function nested(lines) {
 	return lines.map((line) => line === "" ? "" : `  ${line}`);
 }
+/** How the Vite proxy entry reads the project id: from `.env.local` through Vite's `loadEnv`. */
+const VITE_PROJECT_ID = "const projectId = loadEnv(\"development\", process.cwd(), \"ZITADEL_\").ZITADEL_PROJECT_ID;";
 /**
 * The hooks as statements of a Vite proxy entry's `configure(proxy)` body,
 * after its bearer hook. The project id comes from `.env.local` through Vite's
 * `loadEnv`, as the project secret does. The hooks are the listeners
-* themselves, not functions they call, so Vite's types reach `proxyReq` and
-* `proxyRes` and a strict `vite.config.ts` type-checks.
+* themselves, not functions they call, so Vite's types reach `proxyReq`,
+* `proxyRes` and `req`, and a strict `vite.config.ts` type-checks.
 */
 function viteSessionCookieStatements() {
 	return [
 		...EXPLANATION,
-		"const projectId = loadEnv(\"development\", process.cwd(), \"ZITADEL_\").ZITADEL_PROJECT_ID;",
-		...APP_COOKIE,
-		"proxy.on(\"proxyReq\", (proxyReq) => {",
+		VITE_PROJECT_ID,
+		...APP_COOKIE_SUFFIX,
+		"proxy.on(\"proxyReq\", (proxyReq, req) => {",
 		...nested(FORWARD_BODY),
 		"});",
-		"proxy.on(\"proxyRes\", (proxyRes) => {",
+		"proxy.on(\"proxyRes\", (proxyRes, req) => {",
 		...nested(RENAME_BODY),
 		"});"
 	];
 }
+/** How Angular's `proxy.conf.cjs` reads the project id: from the environment, else `.env.local`. */
+const PROXY_CONF_PROJECT_ID = ["const projectId =", "  process.env.ZITADEL_PROJECT_ID ?? (typeof env === \"undefined\" ? undefined : env.ZITADEL_PROJECT_ID);"];
 /**
 * The hooks as top-level statements of Angular's `proxy.conf.cjs`, after its
 * bearer hook: the functions its entry attaches as `onProxyReq`/`onProxyRes`
@@ -11688,19 +11770,93 @@ function viteSessionCookieStatements() {
 function proxyConfSessionCookieStatements() {
 	return [
 		...EXPLANATION,
-		"const projectId =",
-		"  process.env.ZITADEL_PROJECT_ID ?? (typeof env === \"undefined\" ? undefined : env.ZITADEL_PROJECT_ID);",
-		...APP_COOKIE,
+		...PROXY_CONF_PROJECT_ID,
+		...APP_COOKIE_SUFFIX,
 		"",
-		"function forwardSessionCookie(proxyReq) {",
+		"function forwardSessionCookie(proxyReq, req) {",
 		...nested(FORWARD_BODY),
 		"}",
 		"",
-		"function renameSessionCookie(proxyRes) {",
+		"function renameSessionCookie(proxyRes, req) {",
 		...nested(RENAME_BODY),
 		"}"
 	];
 }
+const EXPLANATION_V1 = [
+	`/* ${SESSION_COOKIE_MARKER_V1} */`,
+	"// The browser keeps this app's session in a cookie named after its project,",
+	"// the server in __nextgen_session (ADR 073). Without a project id, cookies",
+	"// pass through."
+];
+const APP_COOKIE_V1 = [
+	"const appCookie = projectId",
+	"  ? \"__nextgen_session_\" +",
+	"    projectId.replace(/[^\\w-]/gu, (char) =>",
+	"      Array.from(new TextEncoder().encode(char), (byte) =>",
+	"        \"%\" + byte.toString(16).toUpperCase().padStart(2, \"0\"),",
+	"      ).join(\"\"),",
+	"    )",
+	"  : undefined;"
+];
+const FORWARD_BODY_V1 = [
+	"if (!appCookie) {",
+	"  return;",
+	"}",
+	"const cookies = String(proxyReq.getHeader(\"cookie\") ?? \"\")",
+	"  .split(\";\")",
+	"  .map((cookie) => cookie.trim())",
+	"  .filter((cookie) => cookie !== \"\");",
+	"const own = cookies.find(",
+	"  (cookie) => cookie.startsWith(appCookie + \"=\") && cookie.length > appCookie.length + 1,",
+	");",
+	"const forwarded = cookies.filter((cookie) => !/^__nextgen_session(?:_[^=]*)?=/.test(cookie));",
+	"if (own) {",
+	"  forwarded.push(\"__nextgen_session\" + own.slice(appCookie.length));",
+	"}",
+	"if (forwarded.length > 0) {",
+	"  proxyReq.setHeader(\"cookie\", forwarded.join(\"; \"));",
+	"} else {",
+	"  proxyReq.removeHeader(\"cookie\");",
+	"}"
+];
+const RENAME_BODY_V1 = [
+	"const setCookies = proxyRes.headers[\"set-cookie\"];",
+	"if (appCookie && setCookies) {",
+	"  proxyRes.headers[\"set-cookie\"] = setCookies.map((setCookie) =>",
+	"    setCookie.replace(/^__nextgen_session=/, appCookie + \"=\"),",
+	"  );",
+	"}"
+];
+/** The statements {@link viteSessionCookieStatements} produced before ADR 083. */
+function viteSessionCookieStatementsV1() {
+	return [
+		...EXPLANATION_V1,
+		VITE_PROJECT_ID,
+		...APP_COOKIE_V1,
+		"proxy.on(\"proxyReq\", (proxyReq) => {",
+		...nested(FORWARD_BODY_V1),
+		"});",
+		"proxy.on(\"proxyRes\", (proxyRes) => {",
+		...nested(RENAME_BODY_V1),
+		"});"
+	];
+}
+/** The statements {@link proxyConfSessionCookieStatements} produced before ADR 083. */
+function proxyConfSessionCookieStatementsV1() {
+	return [
+		...EXPLANATION_V1,
+		...PROXY_CONF_PROJECT_ID,
+		...APP_COOKIE_V1,
+		"",
+		"function forwardSessionCookie(proxyReq) {",
+		...nested(FORWARD_BODY_V1),
+		"}",
+		"",
+		"function renameSessionCookie(proxyRes) {",
+		...nested(RENAME_BODY_V1),
+		"}"
+	];
+}
 /** `lines`, each indented by `indent` (blank lines stay blank), joined with `eol`. */
 function indented(lines, indent, eol = "\n") {
 	return lines.map((line) => line === "" ? "" : `${indent}${line}`).join(eol);
@@ -11819,7 +11975,8 @@ function appTemplateHtml(ctx) {
 /**
 * The managed `proxy.conf.cjs` for `ng serve`: forwards `/__nextgen/*` to the
 * backend and attaches the project's service-key secret only to the current
-* app-plane `POST /sessions/exchange` request. Both the backend URL
+* app-plane `POST /sessions/exchange` request, which it knows with and without
+* the API prefix (`/api/v1`, ADR 077). Both the backend URL
 * (`ZITADEL_URL`) and the secret
 * (`ZITADEL_PROJECT_SECRET`) are read from `.env.local`, which `zitadel setup`
 * writes and `.gitignore` excludes — Angular's CLI does not auto-load env files
@@ -11831,7 +11988,8 @@ function appTemplateHtml(ctx) {
 * backend by its own name (`changeOrigin`), which a remote https server
 * requires, and forwards the app's origin in `X-Forwarded-Host` and
 * `X-Forwarded-Proto` (`xfwd`), and it keeps the session cookie under the
-* app's project's name in the browser (`ZITADEL_PROJECT_ID`, ADR 073).
+* app's project's name in the browser (`ZITADEL_PROJECT_ID`, ADR 073,
+* ADR 083).
 */
 function proxyConfTemplate() {
 	return `${MANAGED_MARKER}
@@ -11884,25 +12042,37 @@ ${SESSION_COOKIE_HOOKS}  },
 const LEGACY_UNCONDITIONAL_BEARER = `function setBearer(proxyReq) {
   proxyReq.setHeader("authorization", bearer);
 }`;
-const EXCHANGE_ONLY_BEARER = `/* ${PROXY_CREDENTIAL_POLICY_MARKER} */
+/** The bearer hook, marked with the credential policy `marker`, testing the path with `pathCheck`. */
+function exchangeOnlyBearer(marker, pathCheck) {
+	return `/* ${marker} */
 function setBearer(proxyReq) {
   const pathname = new URL(proxyReq.path, "http://zitadel.local").pathname;
   if (
     proxyReq.method === "POST" &&
-    pathname === "/sessions/exchange" &&
+    ${pathCheck} &&
     !proxyReq.getHeader("authorization")
   ) {
     proxyReq.setHeader("authorization", bearer);
   }
 }`;
-/** The session-cookie hooks' functions, after the bearer hook (ADR 073). */
+}
+const EXCHANGE_ONLY_BEARER = exchangeOnlyBearer(PROXY_CREDENTIAL_POLICY_MARKER, EXCHANGE_PATH_CHECK);
+/** The bearer hook as the CLI wrote it before it knew the API prefix (ADR 077). */
+const V2_EXCHANGE_ONLY_BEARER = exchangeOnlyBearer(PROXY_CREDENTIAL_POLICY_V2_MARKER, V2_EXCHANGE_PATH_CHECK);
+/** The exchange-only bearer hook `text` carries, of either version, or `undefined`. */
+function bearerIn(text) {
+	return [EXCHANGE_ONLY_BEARER, V2_EXCHANGE_ONLY_BEARER].find((bearer) => text.includes(bearer));
+}
+/** The session-cookie hooks' functions, after the bearer hook (ADR 073, ADR 083). */
 const SESSION_COOKIE_FUNCTIONS = indented(proxyConfSessionCookieStatements(), "");
+/** The session-cookie hooks' functions as the CLI wrote them before ADR 083. */
+const SESSION_COOKIE_FUNCTIONS_V1 = indented(proxyConfSessionCookieStatementsV1(), "");
 /** How the managed entry attached its hooks before it carried the session-cookie ones. */
 const BEARER_ONLY_HOOKS = `    onProxyReq: setBearer,
     configure: (proxy) => proxy.on("proxyReq", setBearer),
 `;
-/** How the managed entry attaches the bearer and the session-cookie hooks. */
-const SESSION_COOKIE_HOOKS = `    onProxyReq: (proxyReq) => {
+/** How the managed entry attached the bearer and the session-cookie hooks before ADR 083. */
+const SESSION_COOKIE_HOOKS_V1 = `    onProxyReq: (proxyReq) => {
       setBearer(proxyReq);
       forwardSessionCookie(proxyReq);
     },
@@ -11914,6 +12084,21 @@ const SESSION_COOKIE_HOOKS = `    onProxyReq: (proxyReq) => {
     },
 `;
 /**
+* How the managed entry attaches the bearer and the session-cookie hooks. Each
+* cookie hook takes the browser's request too, whose scheme names the cookie.
+*/
+const SESSION_COOKIE_HOOKS = `    onProxyReq: (proxyReq, req) => {
+      setBearer(proxyReq);
+      forwardSessionCookie(proxyReq, req);
+    },
+    onProxyRes: renameSessionCookie,
+    configure: (proxy) => {
+      proxy.on("proxyReq", setBearer);
+      proxy.on("proxyReq", forwardSessionCookie);
+      proxy.on("proxyRes", renameSessionCookie);
+    },
+`;
+/**
 * The managed entry as emitted before it forwarded the app's origin, and what
 * replaces it. Keeping the browser's `Host` also kept `localhost` as the TLS
 * server name, so that proxy could reach no remote https server.
@@ -11949,21 +12134,31 @@ function proxyConfEdit() {
 }
 /** Whether `text` (LF line ends) is the managed proxy as an earlier CLI wrote it, without the session-cookie hooks. */
 function hasBearerOnlyHooks(text) {
-	return text.includes("// zitadel-cli: managed-file v1") && text.includes(EXCHANGE_ONLY_BEARER) && text.includes(BEARER_ONLY_HOOKS);
+	return text.includes("// zitadel-cli: managed-file v1") && bearerIn(text) !== void 0 && text.includes(BEARER_ONLY_HOOKS);
+}
+/** Whether `text` (LF line ends) is the managed proxy with the session-cookie hooks the CLI wrote before ADR 083. */
+function hasV1Hooks(text) {
+	return text.includes("// zitadel-cli: managed-file v1") && text.includes(SESSION_COOKIE_FUNCTIONS_V1) && text.includes(SESSION_COOKIE_HOOKS_V1);
 }
 /**
-* Gives the managed proxy the session-cookie hooks (ADR 073) when it is the
-* exact file an earlier CLI wrote: the hook functions go after the bearer hook,
-* and the entry attaches them beside it. A file that carries them already, an
-* unmanaged one, and a managed one whose hooks were changed by hand are left as
-* they are; {@link proxyConfSessionCookieVerdict} tells the doctor which it is.
-* Line ends are the file's own (CRLF or LF). Creates the managed proxy when it
-* is absent, as {@link proxyConfEdit} does.
+* Gives the managed proxy the session-cookie hooks (ADR 073, ADR 083) when it
+* is the exact file an earlier CLI wrote: the hook functions go after the
+* bearer hook, and the entry attaches them beside it; the hooks from before
+* ADR 083 are replaced where they stand. A file that carries the current hooks
+* already, an unmanaged one, and a managed one whose hooks were changed by
+* hand are left as they are; {@link proxyConfSessionCookieVerdict} tells the
+* doctor which it is. Line ends are the file's own (CRLF or LF). Creates the
+* managed proxy when it is absent, as {@link proxyConfEdit} does.
 */
 function proxyConfSessionCookieEdit() {
 	return (source) => {
 		if (source === void 0) return proxyConfTemplate();
-		return withLfLineEnds(source, (text) => text.includes("zitadel:session-cookie:v1") || !hasBearerOnlyHooks(text) ? text : text.replace(EXCHANGE_ONLY_BEARER, `${EXCHANGE_ONLY_BEARER}\n\n${SESSION_COOKIE_FUNCTIONS}`).replace(BEARER_ONLY_HOOKS, SESSION_COOKIE_HOOKS));
+		return withLfLineEnds(source, (text) => {
+			if (text.includes("zitadel:session-cookie:v2")) return text;
+			if (hasV1Hooks(text)) return text.replace(SESSION_COOKIE_FUNCTIONS_V1, SESSION_COOKIE_FUNCTIONS).replace(SESSION_COOKIE_HOOKS_V1, SESSION_COOKIE_HOOKS);
+			const bearer = bearerIn(text);
+			return bearer && hasBearerOnlyHooks(text) ? text.replace(bearer, `${bearer}\n\n${SESSION_COOKIE_FUNCTIONS}`).replace(BEARER_ONLY_HOOKS, SESSION_COOKIE_HOOKS) : text;
+		});
 	};
 }
 /**
@@ -11971,13 +12166,48 @@ function proxyConfSessionCookieEdit() {
 * The managed file as an earlier CLI wrote it is `detached` (`doctor --fix`
 * adds them). One the edit cannot place them in, a managed file changed by
 * hand or a proxy of the developer's own, is `unknown`: only the developer can.
+* Hooks from before ADR 083 are `outdated`: they keep the session in cookies
+* the server no longer reads.
 */
 function proxyConfSessionCookieVerdict(source) {
 	const text = lfText(source);
-	if (text.includes("zitadel:session-cookie:v1")) return "applied";
+	if (text.includes("zitadel:session-cookie:v2")) return "applied";
+	if (text.includes("zitadel:session-cookie:v1")) return { outdated: hasV1Hooks(text) ? "its session-cookie hooks name the session cookies before ADR 083; doctor --fix updates them" : "its session-cookie hooks name the session cookies before ADR 083 and were changed since zitadel setup wrote them, so they must be updated by hand" };
 	if (hasBearerOnlyHooks(text)) return "detached";
 	return { unknown: text.includes("// zitadel-cli: managed-file v1") ? "it was changed since zitadel setup wrote it, so the session-cookie hooks (ADR 073) must be added by hand" : "it is not the proxy zitadel setup writes, so the session-cookie hooks (ADR 073) must be added by hand" };
 }
+/**
+* Moves the managed proxy's bearer hook from v2, which knew only
+* `/sessions/exchange`, to v3, which knows the exchange under the API prefix
+* too (ADR 077): once an app's packages call `/api/v1`, a v2 proxy no longer
+* attaches the project secret to the exchange. Only the exact hook an earlier
+* CLI wrote is replaced; a file that carries v3 already, an unmanaged one and a
+* hook changed by hand are left as they are, and
+* {@link proxyConfApiPrefixVerdict} tells the doctor which it is. Line ends are
+* the file's own. Creates the managed proxy when it is absent, as
+* {@link proxyConfEdit} does.
+*/
+function proxyConfApiPrefixEdit() {
+	return (source) => {
+		if (source === void 0) return proxyConfTemplate();
+		return withLfLineEnds(source, (text) => text.includes("// zitadel-cli: managed-file v1") && text.includes(V2_EXCHANGE_ONLY_BEARER) ? text.replace(V2_EXCHANGE_ONLY_BEARER, EXCHANGE_ONLY_BEARER) : text);
+	};
+}
+/**
+* Whether `proxy.conf.cjs` attaches the project secret to the exchange under
+* the API prefix too, for the doctor. The managed file with an earlier CLI's
+* v2 hook is `detached` (`doctor --fix` moves it to v3). A managed file whose
+* hook was changed by hand, and a proxy of the developer's own that attaches
+* the secret but never names `/api/v1/sessions/exchange`, are `unknown`: only
+* the developer can change them.
+*/
+function proxyConfApiPrefixVerdict(source) {
+	const text = lfText(source);
+	if (text.includes(EXCHANGE_ONLY_BEARER)) return "applied";
+	if (text.includes("// zitadel-cli: managed-file v1") && text.includes(V2_EXCHANGE_ONLY_BEARER)) return "detached";
+	if (!text.includes("ZITADEL_PROJECT_SECRET") || text.includes(PREFIXED_EXCHANGE_PATH)) return "applied";
+	return { unknown: text.includes("// zitadel-cli: managed-file v1") ? `it was changed since zitadel setup wrote it, so its project-secret check must accept ${PREFIXED_EXCHANGE_PATH} by hand (ADR 077)` : `it is not the proxy zitadel setup writes, so its project-secret check must accept ${PREFIXED_EXCHANGE_PATH} by hand (ADR 077)` };
+}
 //#endregion
 //#region src/lib/orca/patchers/rule/angular/index.ts
 const SDK_DEPENDENCY$10 = "@zitadel/sdk-angular";
@@ -12076,6 +12306,13 @@ var AngularPatcher = class extends AbstractRulePatcher {
 				wiring: "convenience",
 				verify: proxyConfSessionCookieVerdict
 			},
+			{
+				kind: "edit",
+				path: "proxy.conf.cjs",
+				edit: proxyConfApiPrefixEdit(),
+				wiring: "infrastructure",
+				verify: proxyConfApiPrefixVerdict
+			},
 			{
 				kind: "edit",
 				path: "angular.json",
@@ -12372,7 +12609,7 @@ const ZitadelSession = dynamic(
       "@zitadel/sdk-next/components"
     );
     // Build the SDK project handle and pass it to the session card via the
-    // \`project\` prop. The card reads identity from "/__nextgen/sessions/me"
+    // \`project\` prop. The card reads identity from "/__nextgen/api/v1/sessions/me"
     // and exposes a Sign out action. Your own components (a header, an
     // account menu) can make the same read with getSession() from
     // "@zitadel/sdk-next/session" to swap sign-in CTAs for account chrome.
@@ -13039,7 +13276,8 @@ var NuxtPatcher = class extends AbstractRulePatcher {
 * `/__nextgen/*` calls to the
 * backend, strips the prefix, and attaches the project's service-key secret
 * (read from `ZITADEL_PROJECT_SECRET` in `.env.local`) only to the current
-* app-plane `POST /sessions/exchange` operation. The secret stays server-side:
+* app-plane `POST /sessions/exchange` operation, which it knows with and
+* without the API prefix (`/api/v1`, ADR 077). The secret stays server-side:
 * Vite only exposes vars with the configured `envPrefix` (default `VITE_`) to
 * client bundles, so this server-only key never leaks into the browser.
 *
@@ -13053,7 +13291,8 @@ var NuxtPatcher = class extends AbstractRulePatcher {
 * browser's `Origin`, which the proxy passes on untouched.
 *
 * The session cookie travels under the app's project's name in the browser and
-* the server's name upstream ({@link viteSessionCookieStatements}, ADR 073).
+* the server's name upstream ({@link viteSessionCookieStatements}, ADR 073,
+* ADR 083).
 */
 function proxyEntryCode(server) {
 	return `/* ${PROXY_CREDENTIAL_POLICY_MARKER} */ {
@@ -13072,13 +13311,17 @@ ${indented(viteSessionCookieStatements(), "    ")}
   },
 }`;
 }
-/** The generated hook that attaches the project secret to the session exchange only. */
-function bearerListener(indent) {
+/**
+* The generated hook that attaches the project secret to the session exchange
+* only. `pathCheck` is the exchange's path test: both spellings, or the one a
+* v2 proxy knew.
+*/
+function bearerListener(indent, pathCheck = EXCHANGE_PATH_CHECK) {
 	return `${indent}proxy.on("proxyReq", (proxyReq) => {
 ${indent}  const pathname = new URL(proxyReq.path, "http://zitadel.local").pathname;
 ${indent}  if (
 ${indent}    proxyReq.method === "POST" &&
-${indent}    pathname === "/sessions/exchange" &&
+${indent}    ${pathCheck} &&
 ${indent}    !proxyReq.getHeader("authorization")
 ${indent}  ) {
 ${indent}    proxyReq.setHeader("authorization", bearer);
@@ -13096,7 +13339,7 @@ ${bearerListener(indent)}`;
 * surrounding `/__nextgen` proxy and any user changes elsewhere in the entry.
 */
 function isLegacyManagedProxy(source) {
-	if (source.includes("zitadel:proxy:v2")) return false;
+	if (hasProxyCredentialPolicyMarker(source)) return false;
 	return [
 		"loadEnv(\"development\", process.cwd(), \"ZITADEL_\").ZITADEL_PROJECT_SECRET",
 		"throw new Error(\"ZITADEL_PROJECT_SECRET is not set; add it to .env.local (zitadel setup writes it).\")",
@@ -13109,7 +13352,7 @@ function isLegacyManagedProxy(source) {
 * also kept `localhost` as the TLS server name, so that proxy could reach no
 * remote https server.
 */
-const HOST_KEEPING_ENTRY = /(["']\/__nextgen["']:\s*(?:\/\* zitadel:proxy:v2 \*\/\s*)?\{\r?\n([\t ]+)target: [^\r\n]+,\r?\n)\2changeOrigin: false,(\r?\n)/;
+const HOST_KEEPING_ENTRY = /(["']\/__nextgen["']:\s*(?:\/\* zitadel:proxy:v[23] \*\/\s*)?\{\r?\n([\t ]+)target: [^\r\n]+,\r?\n)\2changeOrigin: false,(\r?\n)/;
 /**
 * Moves the CLI's own host-keeping entry to the origin-forwarding shape of
 * {@link proxyEntryCode}. Only the generated layout in a config that carries
@@ -13118,7 +13361,7 @@ const HOST_KEEPING_ENTRY = /(["']\/__nextgen["']:\s*(?:\/\* zitadel:proxy:v2 \*\
 * is never touched.
 */
 function forwardAppOrigin(source) {
-	if (!source.includes("zitadel:proxy:v2") || /\bxfwd\s*:/.test(source)) return source;
+	if (!hasProxyCredentialPolicyMarker(source) || /\bxfwd\s*:/.test(source)) return source;
 	return source.replace(HOST_KEEPING_ENTRY, (_entry, head, indent, eol) => `${head}${indent}changeOrigin: true,${eol}${indent}xfwd: true,${eol}`);
 }
 /** The imports that the injected proxy entry depends on. */
@@ -13189,42 +13432,81 @@ function propertyOf(node, name) {
 function fingerprint(source) {
 	return source.replace(/\s+/g, "").replace(/'/g, "\"").replace(/;/g, "").replace(/,(?=[)\]}])/g, "").replace(/(^|[(,:=])([A-Za-z_$][\w$]*)=>/g, "$1($2)=>");
 }
+/** The bearer hook as the CLI writes it now, and as a v2 proxy carries it, fingerprinted. */
+const HOOK_FINGERPRINTS = [{
+	version: "v3",
+	fingerprint: fingerprint(bearerListener(""))
+}, {
+	version: "v2",
+	fingerprint: fingerprint(bearerListener("", V2_EXCHANGE_PATH_CHECK))
+}];
 /**
-* The statements of the `configure(proxy)` body of the `/__nextgen` entry the
-* CLI wrote: one carrying the credential-policy marker and the CLI's own
-* exchange-only bearer hook, however it was formatted since. A hand-written
-* entry, or one whose hook was changed, yields `undefined`.
+* The `/__nextgen` entry the CLI wrote: one carrying the credential-policy
+* marker and the CLI's own exchange-only bearer hook, of either version,
+* however it was formatted since. A hand-written entry, or one whose hook was
+* changed, yields `undefined`.
 */
-function cliConfigureStatements(config, source) {
+function cliEntryOf(config, source) {
 	const root = config.$ast;
 	const proxy = propertyOf(propertyOf(root, "server")?.value, "proxy")?.value;
 	const entry = propertyOf(proxy, PROXY_PATH);
 	const configure = propertyOf(entry?.value, "configure");
 	const body = (configure?.type === "ObjectMethod" ? configure : configure?.value)?.body;
-	if (!entry || !body || Array.isArray(body) || body.type !== "BlockStatement") return;
-	const block = body;
-	const statements = block.body;
-	return source.slice(entry.start, entry.end).includes("zitadel:proxy:v2") && fingerprint(source.slice(block.start, block.end)).includes(fingerprint(bearerListener(""))) && statements.length > 0 ? statements : void 0;
+	if (!entry || !body || Array.isArray(body) || body.type !== "BlockStatement" || !hasProxyCredentialPolicyMarker(source.slice(entry.start, entry.end))) return;
+	const statements = body.body;
+	for (const node of statements) {
+		const printed = fingerprint(source.slice(node.start, node.end));
+		const known = HOOK_FINGERPRINTS.find((hook) => hook.fingerprint === printed);
+		if (known) return {
+			entry,
+			statements,
+			hook: {
+				node,
+				version: known.version
+			}
+		};
+	}
 }
 /** What the session-cookie edit and its verdict call the file they read. */
 const VITE_CONFIG_LABEL = "the Vite config (vite.config.*)";
 /**
-* The statements of the CLI's own `/__nextgen` entry's `configure(proxy)` body
-* in `source` (LF line ends), or `undefined` when there is no such entry.
+* The CLI's own `/__nextgen` entry in `source` (LF line ends), or `undefined`
+* when there is no such entry.
 */
-function cliEntryStatements(source) {
-	return cliConfigureStatements(resolveDefaultExportObject(parseConfigModule(source, VITE_CONFIG_LABEL, { tabWidth: 1 }), VITE_CONFIG_LABEL), source);
+function cliEntry(source) {
+	return cliEntryOf(resolveDefaultExportObject(parseConfigModule(source, VITE_CONFIG_LABEL, { tabWidth: 1 }), VITE_CONFIG_LABEL), source);
+}
+/** How many statements the hooks before ADR 083 are: the project id, the cookie name and the two listeners. */
+const V1_HOOK_STATEMENTS = 4;
+/**
+* `text` (LF line ends) with the session-cookie hooks the CLI wrote before
+* ADR 083 replaced by the current ones, at their indentation, or `undefined`
+* when the CLI's entry does not carry them as the CLI wrote them, whatever a
+* formatter did to their layout.
+*/
+function withCurrentHooks(text) {
+	const marker = text.indexOf(`/* ${SESSION_COOKIE_MARKER_V1} */`);
+	const statements = marker === -1 ? void 0 : cliEntry(text)?.statements;
+	const first = statements?.findIndex((statement) => statement.start > marker) ?? -1;
+	const last = statements?.[first + V1_HOOK_STATEMENTS - 1];
+	if (first === -1 || !last) return;
+	const lineStart = text.lastIndexOf("\n", marker - 1) + 1;
+	if (fingerprint(text.slice(lineStart, last.end)) !== fingerprint(viteSessionCookieStatementsV1().join("\n"))) return;
+	const indent = /^[\t ]*/.exec(text.slice(lineStart, marker))?.[0] ?? "";
+	return `${text.slice(0, lineStart)}${indented(viteSessionCookieStatements(), indent)}${text.slice(last.end)}`;
 }
 /**
 * Builds the `edit` transform that gives the CLI's own `/__nextgen` entry the
-* session-cookie hooks (ADR 073), for apps set up before the entry carried
-* them: the hooks go after the last statement of its `configure(proxy)` body,
-* at that statement's indentation, and nothing else in the file changes. A
-* config whose entry carries them already, a hand-written entry, and one whose
-* bearer hook was changed are returned untouched; {@link viteSessionCookieVerdict}
-* tells the doctor which it is. Line ends are the file's own (CRLF or LF).
-* Throws `E_VALIDATION`, as {@link viteProxyEdit} does, when the file is absent
-* or unreadable.
+* session-cookie hooks (ADR 073, ADR 083), for apps set up before the entry
+* carried them: the hooks go after the last statement of its `configure(proxy)`
+* body, at that statement's indentation, and nothing else in the file changes.
+* The hooks the CLI wrote before ADR 083 are replaced where they stand. A
+* config whose entry carries the current hooks already, a hand-written entry,
+* one whose bearer hook was changed and one whose hooks before ADR 083 were
+* changed are returned untouched; {@link viteSessionCookieVerdict} tells the
+* doctor which it is. Line ends are the file's own (CRLF or LF). Throws
+* `E_VALIDATION`, as {@link viteProxyEdit} does, when the file is absent or
+* unreadable.
 */
 function viteSessionCookieEdit() {
 	return (source) => {
@@ -13233,8 +13515,9 @@ function viteSessionCookieEdit() {
 			return "";
 		}
 		return withLfLineEnds(source, (text) => {
-			if (text.includes("zitadel:session-cookie:v1")) return text;
-			const last = cliEntryStatements(text)?.at(-1);
+			if (text.includes("zitadel:session-cookie:v2")) return text;
+			if (text.includes("zitadel:session-cookie:v1")) return withCurrentHooks(text) ?? text;
+			const last = cliEntry(text)?.statements.at(-1);
 			if (!last) return text;
 			const lineStart = text.lastIndexOf("\n", last.start - 1) + 1;
 			const indent = /^[\t ]*/.exec(text.slice(lineStart, last.start))?.[0] ?? "";
@@ -13247,13 +13530,61 @@ function viteSessionCookieEdit() {
 * The CLI's entry without them is `detached` (`doctor --fix` adds them), and so
 * is a config without the CLI's entry, which the proxy edit writes with them.
 * An entry the CLI wrote whose bearer hook was changed by hand is `unknown`:
-* the edit cannot place the hooks there, and only the developer can.
+* the edit cannot place the hooks there, and only the developer can. Hooks
+* from before ADR 083 are `outdated`: they keep the session in cookies the
+* server no longer reads.
 */
 function viteSessionCookieVerdict(source) {
 	const text = lfText(source);
-	if (text.includes("zitadel:session-cookie:v1")) return "applied";
-	if (cliEntryStatements(text)) return "detached";
-	return text.includes("zitadel:proxy:v2") ? { unknown: "its /__nextgen proxy entry was changed since zitadel setup wrote it, so the session-cookie hooks (ADR 073) must be added by hand" } : "detached";
+	if (text.includes("zitadel:session-cookie:v2")) return "applied";
+	if (text.includes("zitadel:session-cookie:v1")) return { outdated: withCurrentHooks(text) === void 0 ? "its session-cookie hooks name the session cookies before ADR 083 and were changed since zitadel setup wrote them, so they must be updated by hand" : "its session-cookie hooks name the session cookies before ADR 083; doctor --fix updates them" };
+	if (cliEntry(text)) return "detached";
+	return hasProxyCredentialPolicyMarker(text) ? { unknown: "its /__nextgen proxy entry was changed since zitadel setup wrote it, so the session-cookie hooks (ADR 073) must be added by hand" } : "detached";
+}
+/**
+* Builds the `edit` transform that moves the CLI's own `/__nextgen` entry from
+* v2, whose bearer hook knew only `/sessions/exchange`, to v3, which knows the
+* exchange under the API prefix too (ADR 077): once an app's packages call
+* `/api/v1`, a v2 proxy no longer attaches the project secret to the exchange.
+* Only the hook statement and the entry's marker change, whatever the
+* formatter did to the rest; a hand-written entry, a hook changed by hand and
+* a v3 entry are returned untouched, and {@link viteApiPrefixVerdict} tells
+* the doctor which it is. Line ends are the file's own. Throws `E_VALIDATION`,
+* as {@link viteProxyEdit} does, when the file is absent or unreadable.
+*/
+function viteApiPrefixEdit() {
+	return (source) => {
+		if (source === void 0) {
+			parseConfigModule(source, VITE_CONFIG_LABEL, { tabWidth: 1 });
+			return "";
+		}
+		return withLfLineEnds(source, (text) => {
+			const found = cliEntry(text);
+			if (found?.hook.version !== "v2") return text;
+			const { entry, hook } = found;
+			const lineStart = text.lastIndexOf("\n", hook.node.start - 1) + 1;
+			const indent = /^[\t ]*/.exec(text.slice(lineStart, hook.node.start))?.[0] ?? "";
+			const migrated = text.slice(entry.start, hook.node.start) + bearerListener(indent).slice(indent.length) + text.slice(hook.node.end, entry.end);
+			return text.slice(0, entry.start) + migrated.replaceAll(PROXY_CREDENTIAL_POLICY_V2_MARKER, PROXY_CREDENTIAL_POLICY_MARKER) + text.slice(entry.end);
+		});
+	};
+}
+/**
+* Whether the Vite config's dev proxy attaches the project secret to the
+* exchange under the API prefix too, for the doctor. The CLI's v2 entry is
+* `detached` (`doctor --fix` moves it to v3); an entry the CLI wrote whose hook
+* was changed by hand, and a hand-written proxy that attaches the secret but
+* never names `/api/v1/sessions/exchange`, are `unknown`: only the developer can
+* change them. A config with no proxy that attaches the secret has nothing to
+* move.
+*/
+function viteApiPrefixVerdict(source) {
+	const text = lfText(source);
+	const found = cliEntry(text);
+	if (found) return found.hook.version === "v3" ? "applied" : "detached";
+	if (hasProxyCredentialPolicyMarker(text)) return { unknown: `its /__nextgen proxy entry was changed since zitadel setup wrote it, so its project-secret check must accept ${PREFIXED_EXCHANGE_PATH} by hand (ADR 077)` };
+	if (text.includes("/__nextgen") && text.includes("ZITADEL_PROJECT_SECRET") && !text.includes(PREFIXED_EXCHANGE_PATH)) return { unknown: `its /__nextgen proxy is not the one zitadel setup writes, so its project-secret check must accept ${PREFIXED_EXCHANGE_PATH} by hand (ADR 077)` };
+	return "applied";
 }
 /**
 * Candidate Vite config filenames, in resolution priority. The patcher hands
@@ -13280,6 +13611,16 @@ function buildViteSessionCookieOp() {
 		verify: viteSessionCookieVerdict
 	};
 }
+/** Builds the shared API-prefix {@link FileOp} for a {@link ViteSupport} patcher. */
+function buildViteApiPrefixOp() {
+	return {
+		kind: "edit",
+		path: [...VITE_CONFIG_PATHS$1],
+		edit: viteApiPrefixEdit(),
+		wiring: "infrastructure",
+		verify: viteApiPrefixVerdict
+	};
+}
 //#endregion
 //#region src/lib/orca/patchers/rule/qwik/templates.ts
 /**
@@ -13388,6 +13729,9 @@ var QwikPatcher = class extends AbstractRulePatcher {
 	viteSessionCookieOp() {
 		return buildViteSessionCookieOp();
 	}
+	viteApiPrefixOp() {
+		return buildViteApiPrefixOp();
+	}
 	async preflight(_ctx, cwd) {
 		await assertMountsRootComponent(cwd, await viteEntry(cwd), ROOT$4);
 	}
@@ -13403,6 +13747,7 @@ var QwikPatcher = class extends AbstractRulePatcher {
 			},
 			this.viteProxyOp(ctx.framework.devPort, ctx.server),
 			this.viteSessionCookieOp(),
+			this.viteApiPrefixOp(),
 			{
 				kind: "merge-env",
 				path: ".env.example",
@@ -13759,6 +14104,9 @@ var ReactPatcher = class extends AbstractRulePatcher {
 	viteSessionCookieOp() {
 		return buildViteSessionCookieOp();
 	}
+	viteApiPrefixOp() {
+		return buildViteApiPrefixOp();
+	}
 	async preflight(_ctx, cwd) {
 		await assertMountsRootComponent(cwd, await viteEntry(cwd), ROOT$3);
 	}
@@ -13774,6 +14122,7 @@ var ReactPatcher = class extends AbstractRulePatcher {
 			},
 			this.viteProxyOp(ctx.framework.devPort, ctx.server),
 			this.viteSessionCookieOp(),
+			this.viteApiPrefixOp(),
 			{
 				kind: "merge-env",
 				path: ".env.example",
@@ -13913,6 +14262,9 @@ var SolidPatcher = class extends AbstractRulePatcher {
 	viteSessionCookieOp() {
 		return buildViteSessionCookieOp();
 	}
+	viteApiPrefixOp() {
+		return buildViteApiPrefixOp();
+	}
 	async preflight(_ctx, cwd) {
 		await assertMountsRootComponent(cwd, await viteEntry(cwd), ROOT$2);
 	}
@@ -13928,6 +14280,7 @@ var SolidPatcher = class extends AbstractRulePatcher {
 			},
 			this.viteProxyOp(ctx.framework.devPort, ctx.server),
 			this.viteSessionCookieOp(),
+			this.viteApiPrefixOp(),
 			{
 				kind: "merge-env",
 				path: ".env.example",
@@ -14387,6 +14740,9 @@ var SveltePatcher = class extends AbstractRulePatcher {
 	viteSessionCookieOp() {
 		return buildViteSessionCookieOp();
 	}
+	viteApiPrefixOp() {
+		return buildViteApiPrefixOp();
+	}
 	async preflight(_ctx, cwd) {
 		await assertMountsRootComponent(cwd, await viteEntry(cwd), ROOT$1);
 	}
@@ -14402,6 +14758,7 @@ var SveltePatcher = class extends AbstractRulePatcher {
 			},
 			this.viteProxyOp(ctx.framework.devPort, ctx.server),
 			this.viteSessionCookieOp(),
+			this.viteApiPrefixOp(),
 			{
 				kind: "merge-env",
 				path: ".env.example",
@@ -15149,6 +15506,9 @@ var VuePatcher = class extends AbstractRulePatcher {
 	viteSessionCookieOp() {
 		return buildViteSessionCookieOp();
 	}
+	viteApiPrefixOp() {
+		return buildViteApiPrefixOp();
+	}
 	async preflight(_ctx, cwd) {
 		await assertMountsRootComponent(cwd, await viteEntry(cwd), ROOT);
 	}
@@ -15164,6 +15524,7 @@ var VuePatcher = class extends AbstractRulePatcher {
 			},
 			this.viteProxyOp(ctx.framework.devPort, ctx.server),
 			this.viteSessionCookieOp(),
+			this.viteApiPrefixOp(),
 			{
 				kind: "merge-env",
 				path: ".env.example",
@@ -16588,6 +16949,7 @@ var ManagedFilesCheck = class {
 		const detachedInfrastructure = wiring.filter((s) => s.state === "detached" && s.wiring === "infrastructure");
 		const detachedConvenience = wiring.filter((s) => s.state === "detached" && s.wiring === "convenience");
 		const unverifiable = wiring.filter((s) => s.state === "unknown");
+		const outdated = wiring.filter((s) => s.state === "outdated");
 		const conflicts = boundaries.filter((b) => b.disposition === "conflict");
 		const removable = boundaries.filter((b) => b.disposition === "removable");
 		const details = {
@@ -16599,6 +16961,7 @@ var ManagedFilesCheck = class {
 		const failures = [];
 		if (missingInfrastructure.length > 0) failures.push(`missing scaffolded infrastructure file(s): ${listPaths(missingInfrastructure)}`);
 		if (detachedInfrastructure.length > 0) failures.push(`detached managed config wiring: ${detachedInfrastructure.map((s) => s.path).join(", ")}`);
+		if (outdated.length > 0) failures.push(`outdated managed config wiring: ${outdated.map((s) => s.reason ? `${s.path} (${s.reason})` : s.path).join(", ")}`);
 		for (const conflict of conflicts) failures.push(`conflicting request boundaries: ${conflict.retired} is user-modified while the current templates use ${conflict.current} — migrate your changes and remove one of them manually`);
 		if (failures.length > 0) return {
 			name: this.name,
@@ -17338,13 +17701,13 @@ async function inspect(cwd) {
 		status: "pass",
 		message: `${issuer} is not recorded as a preview origin`
 	};
-	const client = createZitadelClient({
+	const client = createZitadelClient$1({
 		baseUrl: server,
 		token: secret.project_secret
 	});
 	let origins;
 	try {
-		origins = (await client.getProject(secret.project_id)).origins ?? [];
+		origins = (await client.getProject(secret.project_id)).origins;
 	} catch (error) {
 		return {
 			status: "pass",
@@ -17614,18 +17977,24 @@ var Doctor = class Doctor extends BaseCommand {
 				port
 			} : {},
 			project: { lifecycle: hasConfig ? "configured" : "not-configured" },
-			checks,
-			...nextActions.length > 0 ? { next_actions: nextActions } : {},
-			...warningAdvice ? nextCommandsData(warningAdvice.nextCommands) : {}
+			checks
+		};
+		const next = {
+			...nextActions.length > 0 ? { actions: nextActions } : {},
+			...warningAdvice ? { commands: warningAdvice.nextCommands } : {}
 		};
 		if (failed.length > 0) {
 			const advice = failureAdvice(failed, image, port, this.meta.cliVersion, selector, parentRuntimeDir, cwdFlag);
+			const report = {
+				...data,
+				...nextStepsData(next)
+			};
 			const code = failed.some((check) => check.name === "port") ? "E_PORT_IN_USE" : failed.find((check) => check.code !== void 0)?.code ?? "E_VALIDATION";
 			throw new ZitadelError(code, "Zitadel doctor found issues", {
 				hint: advice.hint,
 				nextCommands: advice.nextCommands,
-				details: advice.suggestedArgs === void 0 ? data : {
-					...data,
+				details: advice.suggestedArgs === void 0 ? report : {
+					...report,
 					suggested_args: advice.suggestedArgs
 				}
 			});
@@ -17633,6 +18002,7 @@ var Doctor = class Doctor extends BaseCommand {
 		return this.emit({
 			status: "ok",
 			data,
+			next,
 			warnings: warnings.map((warning) => `${warning.name}: ${warning.message}`)
 		});
 	}
@@ -17798,7 +18168,7 @@ async function runEnvironmentChecks(input) {
 		const token = environment.values.ZITADEL_PROJECT_SECRET?.value;
 		if (server === void 0 || projectId === void 0) throw new Error(`ZITADEL_URL and ZITADEL_PROJECT_ID must resolve for the ${name} environment`);
 		if (token === void 0) throw new Error(`ZITADEL_PROJECT_SECRET must resolve to verify project ${projectId} on ${server}`);
-		const project = await createZitadelClient({
+		const project = await createZitadelClient$1({
 			baseUrl: server,
 			token
 		}).getProject(projectId);
@@ -18191,9 +18561,9 @@ var Eject = class Eject extends Promptable(BaseCommand) {
 				files_removed: removed,
 				files_preserved: preserved,
 				backed_up: backedUp,
-				...nextCommandsData(nextCommands),
 				manual_steps: manualSteps
-			}
+			},
+			next: { commands: nextCommands }
 		});
 	}
 };
@@ -18276,7 +18646,7 @@ var Env = class Env extends EnvironmentCommand {
 /** The frameworks whose server needs the project secret at runtime (the session exchange). */
 const SERVER_RENDERED = ["next", "nuxt"];
 /** The message the release this command publishes carries. */
-const INITIAL_DEPLOY_MESSAGE = "Initial deployment from zitadel env add";
+const INITIAL_DEPLOY_MESSAGE$1 = "Initial deployment from zitadel env add";
 /**
 * `zitadel env add` — bind an environment to a project: create one on the
 * server, or bind an id a teammate sent over, and write the
@@ -18356,7 +18726,7 @@ var EnvAdd = class EnvAdd extends Promptable(BaseCommand) {
 		let projectSecret = env.ZITADEL_PROJECT_SECRET;
 		let previewToken = env.ZITADEL_PREVIEW_TOKEN;
 		if (projectId === void 0) {
-			const created = await createZitadelClient({ baseUrl: server }).createProject({
+			const created = await createZitadelClient$1({ baseUrl: server }).createProject({
 				name: `${basename(cwd)}-${name}`,
 				...issuer === void 0 ? {} : { origins: [{
 					pattern: issuer,
@@ -18488,19 +18858,16 @@ var EnvAdd = class EnvAdd extends Promptable(BaseCommand) {
 					content_hash: deployment.contentHash,
 					deployment_id: deployment.deploymentId,
 					origins: [...deployment.origins]
-				},
-				...nextCommandsData([
-					...needsOrigin && issuer !== void 0 && writtenKeys.has("ZITADEL_PROJECT_SECRET") ? [projectCommand(`origin add ${shellArg(issuer)} --kind primary`, newEnvironment, cliVersion)] : [],
-					...hasSomewhereToLand && deployment === void 0 ? [projectCommand(DEPLOY_ARGS, newEnvironment, cliVersion)] : [],
-					projectCommand("env", newEnvironment, cliVersion)
-				])
+				}
 			},
+			next: { commands: [
+				...needsOrigin && issuer !== void 0 && writtenKeys.has("ZITADEL_PROJECT_SECRET") ? [projectCommand(`origin add ${shellArg(issuer)} --kind primary`, newEnvironment, cliVersion)] : [],
+				...hasSomewhereToLand && deployment === void 0 ? [projectCommand(DEPLOY_ARGS, newEnvironment, cliVersion)] : [],
+				projectCommand("env", newEnvironment, cliVersion)
+			] },
 			pretty: [
 				`Wrote ${file} with ${Object.keys(values).join(", ")}`,
-				"",
-				...needsOrigin ? [writtenKeys.has("ZITADEL_PROJECT_SECRET") ? `Allow this project's origin: zitadel origin add ${issuer === void 0 ? "'<your-app-url>'" : shellArg(issuer)} --kind primary${newEnvironment}` : `Allow this project's origin once ZITADEL_PROJECT_SECRET is in ${file}: zitadel origin add ${issuer === void 0 ? "'<your-app-url>'" : shellArg(issuer)} --kind primary${newEnvironment}`] : [],
-				...createdProject && deployment === void 0 ? [`Nothing is deployed to ${name} yet, so it serves the server's defaults rather than .zitadel/.`, ...hasSomewhereToLand ? [`Deploy to it: zitadel ${DEPLOY_ARGS}${newEnvironment}`] : [`Give it an origin first: zitadel origin add '<your-app-url>' --kind primary${newEnvironment}`, `Then deploy to it: zitadel ${DEPLOY_ARGS}${newEnvironment}`]] : [],
-				`Check what resolves: zitadel env${newEnvironment}`,
+				...guidanceBlock([...needsOrigin ? writtenKeys.has("ZITADEL_PROJECT_SECRET") ? issuer === void 0 ? [`Allow this project's origin: zitadel origin add '<your-app-url>' --kind primary${newEnvironment}`] : [] : [`Allow this project's origin once ZITADEL_PROJECT_SECRET is in ${file}: zitadel origin add ${issuer === void 0 ? "'<your-app-url>'" : shellArg(issuer)} --kind primary${newEnvironment}`] : [], ...createdProject && deployment === void 0 ? [`Nothing is deployed to ${name} yet, so it serves the server's defaults rather than .zitadel/.`, ...hasSomewhereToLand ? [] : [`Give it an origin first: zitadel origin add '<your-app-url>' --kind primary${newEnvironment}`, `Then deploy to it: zitadel ${DEPLOY_ARGS}${newEnvironment}`]] : []]),
 				"",
 				"The deployed app never reads that file. Set these where it is built and run.",
 				"",
@@ -18516,10 +18883,8 @@ var EnvAdd = class EnvAdd extends Promptable(BaseCommand) {
 		});
 	}
 	/**
-	* Publish `.zitadel/` to the project this run just created, the way `deploy`
-	* does: build the bundle, validate it, create the release and deploy it to
-	* every primary origin. `deploy`'s diff step is left out, because nothing
-	* has ever been deployed here and there is no baseline to diff against.
+	* Publish `.zitadel/` to the project this run just created (see
+	* {@link deployInitialRelease}).
 	*
 	* It authenticates with the new project's own secret rather than the one
 	* this directory resolves to, since `env add` binds a different project from
@@ -18528,53 +18893,33 @@ var EnvAdd = class EnvAdd extends Promptable(BaseCommand) {
 	*/
 	async deployInitialRelease(opts) {
 		const json = this.jsonEnabled();
-		const client = createZitadelClient({
-			baseUrl: opts.server,
-			token: opts.projectSecret
-		});
 		consola.start("Deploying .zitadel/ to the new environment");
 		try {
-			const { bundle, brandingSources, idpFiles, policyFiles } = await buildBundle(opts.cwd);
-			const ctx = {
-				cwd: opts.cwd,
-				client,
+			const deployment = await deployInitialRelease({
+				client: createZitadelClient$1({
+					baseUrl: opts.server,
+					token: opts.projectSecret
+				}),
 				projectId: opts.projectId,
+				cwd: opts.cwd,
 				env: this.meta.env,
-				mode: "deploy",
-				dryRun: false,
 				json,
 				color: !json && Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
-				bundle,
-				brandingSources,
-				idpFiles,
-				policyFiles,
+				message: INITIAL_DEPLOY_MESSAGE$1,
 				suggest: (args) => projectCommand(args, opts.selector, this.meta.cliVersion)
-			};
-			await runSteps([validateStep], ctx);
-			const release = await createReleaseFromBundle(client, opts.projectId, bundle, {
-				message: INITIAL_DEPLOY_MESSAGE,
-				gitSha: await headSha(opts.cwd),
-				gitDirty: await worktreeIsDirty(opts.cwd)
 			});
-			const deployment = await createDeployment(client, opts.projectId, {
-				releaseId: release.id,
-				targets: ["primary"],
-				message: INITIAL_DEPLOY_MESSAGE
-			});
-			const origins = deployment.targets.map((target) => target.origin);
-			consola.success(`Deployed ${release.content_hash} to ${origins.length} origin${origins.length === 1 ? "" : "s"}`);
-			return {
-				releaseId: release.id,
-				contentHash: release.content_hash,
-				deploymentId: deployment.id,
-				origins
-			};
+			consola.success(`Deployed ${deployment.contentHash} to ${deployment.origins.length} origin${deployment.origins.length === 1 ? "" : "s"}`);
+			return deployment;
 		} catch (error) {
 			reportWarning(`The environment was bound but the first deploy failed: ${toZitadelError(error).message}. Run \`zitadel ${DEPLOY_ARGS}${opts.selector}\` to publish it.`);
 			return;
 		}
 	}
 };
+/** Lines under a blank line that sets them apart, or nothing when there are none. */
+function guidanceBlock(lines) {
+	return lines.length === 0 ? [] : ["", ...lines];
+}
 //#endregion
 //#region src/commands/env/list.ts
 /** The columns `list` renders, in order. */
@@ -18975,9 +19320,9 @@ var OriginAdd = class OriginAdd extends EnvironmentCommand {
 			status: "ok",
 			data: {
 				pattern: added.pattern,
-				kind: added.kind,
-				...nextCommandsData([this.suggest("origin list")])
+				kind: added.kind
 			},
+			next: { commands: [this.suggest("origin list")] },
 			pretty: `Added ${added.pattern} (${added.kind})`
 		});
 	}
@@ -19002,7 +19347,7 @@ var OriginList = class OriginList extends EnvironmentCommand {
 		const { flags } = await this.parse(OriginList);
 		await this.toMeta(flags);
 		const { client, projectId } = await this.connect();
-		const origins = (await client.getProject(projectId)).origins ?? [];
+		const origins = (await client.getProject(projectId)).origins;
 		const plain = flags.plain || !process.stdout.isTTY;
 		return this.emit({
 			status: "ok",
@@ -19059,7 +19404,7 @@ var OriginRm = class OriginRm extends Promptable(EnvironmentCommand) {
 			reason: "remove-cancelled"
 		});
 		await client.removeOrigin(projectId, { pattern });
-		const remaining = await client.getProject(projectId).then((project) => project.origins ?? [], (error) => {
+		const remaining = await client.getProject(projectId).then((project) => project.origins, (error) => {
 			reportWarning(`${pattern} was removed, but the project's remaining origins could not be read: ${error instanceof Error ? error.message : String(error)}`);
 		});
 		if (remaining?.length === 0) reportWarning(`${pattern} was the project's last origin, so the project now admits every origin. Add the ones it should admit with \`zitadel origin add <url> --kind primary${this.environmentSelector()}\`.`);
@@ -19192,10 +19537,12 @@ var Preview = class Preview extends PreviewCommand {
 	static examples = [
 		"<%= config.bin %> preview",
 		"<%= config.bin %> preview --origin https://acme-git-sso-acmeinc.vercel.app",
-		"<%= config.bin %> preview --ttl 24h"
+		"<%= config.bin %> preview --ttl 24h",
+		"<%= config.bin %> preview -m 'add phone_number to human-user'"
 	];
 	static flags = {
 		...previewFlags,
+		message: messageFlag("A short summary of what this release changes. Defaults to the pull request's title or the current commit's subject."),
 		strict: Flags.boolean({ description: `Fail instead of warning when no preview credential (${CREDENTIALS[PREVIEW_CREDENTIAL]}) is set.` })
 	};
 	async run() {
@@ -19266,13 +19613,16 @@ var Preview = class Preview extends PreviewCommand {
 			},
 			pretty: [`Validated the preview for ${urls.length} URL${urls.length === 1 ? "" : "s"}. Nothing was deployed (dry run).`, ...urls.map((url) => `  - ${url}`)].join("\n")
 		});
+		const message = await deployMessage(flags.message, cwd, env);
 		const release = await createReleaseFromBundle(client, projectId, bundle, {
+			message,
 			gitSha: await headSha(cwd),
 			gitDirty: await worktreeIsDirty(cwd)
 		});
 		const deployment = await createDeployment(client, projectId, {
 			releaseId: release.id,
 			targets: urls,
+			message,
 			...ttl === void 0 ? {} : { ttl: ttl.iso }
 		});
 		const previews = deployment.targets.map((target) => ({
@@ -19304,7 +19654,7 @@ var Preview = class Preview extends PreviewCommand {
 */
 async function primaryOrigins(client, projectId) {
 	try {
-		return ((await client.getProject(projectId)).origins ?? []).filter((entry) => entry.kind === "primary").map((entry) => entry.pattern);
+		return (await client.getProject(projectId)).origins.filter((entry) => entry.kind === "primary").map((entry) => entry.pattern);
 	} catch (error) {
 		if (error instanceof ApiError && error.status === 403) return [];
 		throw error;
@@ -19361,17 +19711,15 @@ var PreviewList = class PreviewList extends PreviewCommand {
 		const { flags } = await this.parse(PreviewList);
 		await this.toMeta(flags);
 		const { client, projectId } = await this.connect();
-		const request = (token) => client.listPreviews(projectId, {
-			...flags.limit === void 0 ? {} : { limit: flags.limit },
-			...token === void 0 ? {} : { page_token: token }
-		});
-		const { items, next } = await collectPages(request, {
-			items: "previews",
+		const params = {
+			limit: flags.limit,
+			page_token: flags["page-token"]
+		};
+		const { items: previews, next } = await collectPages(client.listPreviews.pages(projectId, params), {
+			items: (page) => page.previews,
 			all: flags.all === true,
-			token: flags["page-token"],
-			nextPageToken: "next_page_token"
+			next: (page) => page.next_page_token
 		});
-		const previews = items;
 		const rows = previews.map((preview) => ({
 			url: preview.origin,
 			expires: preview.expires_at,
@@ -19386,10 +19734,9 @@ var PreviewList = class PreviewList extends PreviewCommand {
 		const plain = flags.plain || !process.stdout.isTTY;
 		return this.emit({
 			status: "ok",
-			data: listData(previews, {
-				nextPageToken: next,
-				nextCommands: nextCommand === void 0 ? void 0 : [nextCommand]
-			}),
+			data: listData(previews, { nextPageToken: next }),
+			...nextCommand === void 0 ? {} : { next: { commands: [nextCommand] } },
+			machineReadable: plain,
 			pretty: renderList(COLUMNS$3, rows, {
 				plain,
 				singular: "preview",
@@ -19433,16 +19780,11 @@ var PreviewRm = class PreviewRm extends Promptable(PreviewCommand) {
 			});
 		}
 		const { client, projectId } = await this.connect();
-		const { items } = await collectPages((token) => client.listPreviews(projectId, token === void 0 ? {} : { page_token: token }), {
-			items: "previews",
-			all: true,
-			nextPageToken: "next_page_token"
-		});
-		if (!items.some((preview) => preview.origin === url)) return this.emit({
+		if (!(await client.listPreviews.all(projectId)).some((preview) => preview.origin === url)) return this.emit({
 			status: "skipped",
 			reason: "not-live",
 			pretty: `${url} is not a live preview of the project; nothing was removed`,
-			nextCommands: [this.suggest("preview list")]
+			next: { commands: [this.suggest("preview list")] }
 		});
 		if (!await this.input({
 			kind: "confirm",
@@ -19628,9 +19970,9 @@ var Pull = class Pull extends EnvironmentCommand {
 				release_id: release.id,
 				pulled,
 				skipped,
-				...dryRun ? { dry_run: true } : {},
-				...nextCommandsData(nextCommands)
+				...dryRun ? { dry_run: true } : {}
 			},
+			next: { commands: nextCommands },
 			pretty: dryRun ? `Would write ${pulled.length} file${pulled.length === 1 ? "" : "s"} from ${release.id} (dry run).\n${summary}` : `Pulled ${pulled.length} file${pulled.length === 1 ? "" : "s"} from ${release.id}.\n${summary}`
 		});
 	}
@@ -19645,7 +19987,10 @@ var Pull = class Pull extends EnvironmentCommand {
 		if (classified.kind === "release") return classified.id;
 		if (classified.kind === "deployment") return (await client.getDeploymentById(classified.id, { project_id: projectId })).release_id;
 		if (classified.kind === "latest") {
-			const deployment = (await listLiveDeployments(client, projectId)).find(servesPrimary);
+			const deployment = (await client.listDeployments.all({
+				project_id: projectId,
+				live: true
+			})).find(servesPrimary);
 			if (deployment === void 0) throw new ZitadelError("E_NOT_FOUND", "Nothing is deployed to a primary origin yet.", { hint: `Deploy first with \`zitadel ${DEPLOY_ARGS}${this.environmentSelector()}\`, then pull.` });
 			return deployment.release_id;
 		}
@@ -19727,9 +20072,9 @@ var ReleaseCreate = class ReleaseCreate extends EnvironmentCommand {
 			data: {
 				release_id: release.id,
 				content_hash: release.content_hash,
-				resources: resourceCount,
-				...nextCommandsData([this.suggest(`deployment create --release ${release.id}`)])
+				resources: resourceCount
 			},
+			next: { commands: [this.suggest(`deployment create --release ${release.id}`)] },
 			pretty: `Created ${release.id} (${release.content_hash})`
 		});
 	}
@@ -19819,9 +20164,9 @@ var Reset = class Reset extends Promptable(BaseCommand) {
 						log_path: runtime.log_path
 					} : { container_name: containerName },
 					data_deleted: true
-				},
-				...nextCommandsData([this.suggestUnscoped("reset --force")])
-			}
+				}
+			},
+			next: { commands: [this.suggestUnscoped("reset --force")] }
 		});
 		if (!await this.input({
 			kind: "confirm",
@@ -19872,9 +20217,13 @@ var ResourceCommand = class extends Promptable(EnvironmentCommand) {
 			args: parsed.args
 		}, meta));
 	}
-	/** Open the platform connection; deferred so `--dry-run` never connects. */
-	context() {
-		return this.definition.options.connect(() => this.connect());
+	/**
+	* Open the platform connection; deferred so `--dry-run` never connects.
+	* `verbatim` is for a caller that sends back what it reads, as a list sends
+	* back its cursor.
+	*/
+	context(options = {}) {
+		return this.definition.options.connect(() => this.connect(options));
 	}
 	/**
 	* The operation's work. Every concrete operation overrides this; the base
@@ -19968,8 +20317,10 @@ var DeleteOperation = class extends ResourceCommand {
 *
 * These live behind {@link WireConventions} rather than inline in the list
 * operation so the factory stays honest about what it assumes: a platform
-* whose cursor is `next_cursor`, or whose filters are a map rather than a
-* list, overrides the vocabulary instead of forking the factory.
+* that sends its cursor as `cursor`, reports it as `next_cursor`, or takes its
+* filters as a map rather than a list, overrides the vocabulary instead of
+* forking the factory. A response is never read by these names: each list
+* reads its items and cursor through its own typed `items` and `next`.
 */
 const DEFAULT_WIRE = {
 	limit: "limit",
@@ -19988,8 +20339,12 @@ const wireOf = (overrides) => ({
 });
 //#endregion
 //#region src/lib/oclif/crud/query.ts
-/** `field=operation:value`, or `field=value` for `equals`. */
-const parseFilter = (raw, filters) => {
+/**
+* `field=operation:value`, or `field=value` for `equals`. `known` is every
+* operation the platform has, so one the field does not offer is refused
+* rather than read as part of a value.
+*/
+const parseFilter = (raw, filters, known) => {
 	const names = filters.map((filter) => filter.field);
 	const [name, ...rest] = raw.split("=");
 	if (!name || rest.length === 0) throw new ZitadelError("E_VALIDATION", `Invalid --filter "${raw}"`, { hint: `Use field=operation:value, e.g. ${names[0]}=${filters[0]?.operations[0]}:<value>.` });
@@ -20008,7 +20363,7 @@ const parseFilter = (raw, filters) => {
 	const expression = rest.join("=");
 	const [candidate = "", ...rawValue] = expression.split(":");
 	const operations = field.operations;
-	if (operations.includes(candidate) && rawValue.length > 0) return checked({
+	if (operations.includes(candidate) && rawValue.length > 0) return checked$1({
 		field,
 		operation: candidate,
 		value: rawValue.join(":")
@@ -20023,7 +20378,7 @@ const parseFilter = (raw, filters) => {
 				operations: [...operations]
 			}
 		});
-		if (!operations.includes(candidate) && KNOWN_OPERATIONS.has(candidate)) throw new ZitadelError("E_VALIDATION", `Filter field "${name}" does not support the ${candidate} operation`, {
+		if (!operations.includes(candidate) && known.includes(candidate)) throw new ZitadelError("E_VALIDATION", `Filter field "${name}" does not support the ${candidate} operation`, {
 			hint: `${name} accepts: ${operations.join(", ")}.`,
 			details: {
 				field: name,
@@ -20039,29 +20394,14 @@ const parseFilter = (raw, filters) => {
 			operations: [...operations]
 		}
 	});
-	return checked({
+	return checked$1({
 		field,
 		operation: "equals",
 		value: expression
 	});
 };
-/**
-* Operation names the CLI recognises as operations at all, so a value that
-* merely looks like `something:else` is not mistaken for one.
-*/
-const KNOWN_OPERATIONS = /* @__PURE__ */ new Set([
-	"equals",
-	"not_equals",
-	"contains",
-	"not_contains",
-	"less_than",
-	"less_than_or_equal",
-	"greater_than",
-	"greater_than_or_equal",
-	"array_contains"
-]);
 /** Reject a value outside a field's closed set before any request is made. */
-const checked = (parsed) => {
+const checked$1 = (parsed) => {
 	const { values } = parsed.field;
 	if (values && !values.includes(parsed.value)) throw new ZitadelError("E_VALIDATION", `Invalid value "${parsed.value}" for filter field "${parsed.field.field}"`, {
 		hint: `Accepted values: ${values.join(", ")}.`,
@@ -20122,14 +20462,6 @@ const shapeOf = (schema) => {
 	const merged = Object.assign({}, ...options.map((option) => shapeOf(option) ?? {}));
 	return Object.keys(merged).length > 0 ? merged : void 0;
 };
-/**
-* The element schema of a list response's item array. `key` names the property
-* holding the array; without one the response schema is the array itself.
-*/
-const itemSchemaOf = (response, key) => {
-	const array = key === void 0 ? unwrap(response) : unwrap(shapeOf(response)?.[key]);
-	return unwrap(array?.def?.element) ?? void 0;
-};
 /** Walk a record schema into the paths a caller may name. */
 const fieldPaths = (schema, depth = 3) => {
 	const shape = shapeOf(schema);
@@ -20257,15 +20589,15 @@ var ListOperation = class extends ResourceCommand {
 	async execute({ flags }, _meta) {
 		const { topic, resource, spec, options } = this.definition;
 		const wire = wireOf(options.wire);
-		const shape = fieldPaths(itemSchemaOf(spec.response, spec.items));
+		const shape = fieldPaths(spec.item);
 		const early = shape ? chosenColumns(flags.fields, resource.columns, [], shape) : void 0;
-		const ctx = await this.context();
+		const ctx = await this.context({ verbatim: true });
 		const paged = spec.paged !== false;
 		const paging = (token) => paged ? {
 			...typeof flags.limit === "number" && { [wire.limit]: flags.limit },
 			...token && { [wire.pageToken]: token }
 		} : {};
-		const given = (Array.isArray(flags.filter) ? flags.filter : []).map((raw) => parseFilter(String(raw), spec.filters ?? []));
+		const given = (Array.isArray(flags.filter) ? flags.filter : []).map((raw) => parseFilter(String(raw), spec.filters ?? [], options.operations));
 		const defaults = (spec.filters ?? []).flatMap((field) => field.default !== void 0 && !given.some((one) => one.field.field === field.field) ? [{
 			field,
 			operation: "equals",
@@ -20292,16 +20624,17 @@ var ListOperation = class extends ResourceCommand {
 		progress?.start(`Fetching ${topic}`);
 		let fetched = 0;
 		let drained = false;
-		const { items, next } = await collectPages(async (token) => {
-			const page = await request(token);
+		const first = typeof flags["page-token"] === "string" ? flags["page-token"] : void 0;
+		const walk = pages(async (token) => {
+			const page = await request(token ?? first);
 			fetched += 1;
 			progress?.message(`Fetching ${topic} — page ${fetched}`);
 			return page;
-		}, {
-			items: spec.items,
+		}, { next: (response) => spec.next?.(response) || void 0 });
+		const { items, next } = await collectPages(walk, {
+			items: (response) => sanitizeResponse(spec.items(response)),
 			all,
-			nextPageToken: wire.nextPageToken,
-			token: paged && typeof flags["page-token"] === "string" ? flags["page-token"] : void 0
+			next: (response) => sanitizeResponse(spec.next?.(response))
 		}).then((page) => {
 			drained = true;
 			return page;
@@ -20322,9 +20655,10 @@ var ListOperation = class extends ResourceCommand {
 			data: {
 				items,
 				count: items.length,
-				[wire.nextPageToken]: next,
-				...nextCommands.length > 0 ? nextCommandsData(nextCommands) : {}
+				[wire.nextPageToken]: next
 			},
+			...nextCommands.length > 0 ? { next: { commands: nextCommands } } : {},
+			machineReadable: plain,
 			pretty: plain ? renderRows(columns, items) : items.length === 0 ? `No ${topic} found.` : [
 				renderTable(columns, items),
 				"",
@@ -20394,10 +20728,11 @@ var GetOperation = class extends ResourceCommand {
 			data: item,
 			pretty: JSON.stringify(item, null, 2)
 		};
+		const sections = flags.fields === void 0 ? spec.sections?.(item) ?? [] : [];
 		return {
 			status: "ok",
 			data: item,
-			pretty: renderDetail(headingOf(resource.heading ?? resource.idField, item), fields, item)
+			pretty: [renderDetail(headingOf(resource.heading ?? resource.idField, item), fields, item), ...sections].join("\n\n")
 		};
 	}
 };
@@ -20577,15 +20912,12 @@ var WriteOperation = class extends ResourceCommand {
 			references: options.references
 		});
 		const result = await this.send(await this.context(), body, id);
-		const resultId = isObject(result) ? result[resource.idField] : void 0;
-		const nextCommands = typeof resultId === "string" && resource.get ? [this.suggest(`${topic} get ${resultId} --json`)] : [];
 		return {
 			status: "ok",
-			data: isObject(result) && nextCommands.length > 0 ? {
-				...result,
-				...nextCommandsData(nextCommands)
-			} : result ?? {},
-			pretty: JSON.stringify(result, null, 2)
+			data: result ?? {},
+			...result && resource.get ? { next: { commands: [this.suggest(`${topic} get ${String(resource.idOf(result))} --json`)] } } : {},
+			pretty: JSON.stringify(result, null, 2),
+			machineReadable: true
 		};
 	}
 };
@@ -20705,26 +21037,49 @@ const update = (schema, call, shape = {}) => ({
 	schema,
 	call
 });
+const checked = Symbol("checked");
+const ranged = Symbol("ranged");
+/**
+* A field a `GET` list sends as one parameter per operation (a range, such as
+* `created_after` and `created_before`), keyed by operation: the operations it
+* offers are the keys, so each has the parameter it travels as.
+*/
+const range = (params) => ({
+	operations: Object.keys(params),
+	params,
+	[ranged]: true
+});
 const list = (spec) => spec;
-/** Filter operations of `POST /<resource>/query` endpoints (ADR 031). */
-const FILTER_OPERATIONS = [
-	"equals",
-	"not_equals",
-	"contains",
-	"not_contains",
-	"less_than",
-	"less_than_or_equal",
-	"greater_than",
-	"greater_than_or_equal"
-];
-const EVENT_CATEGORIES = [
-	"request",
-	"auth",
-	"session",
-	"admin",
-	"entity",
-	"signal"
-];
+const get = (spec) => spec;
+const resource = (descriptor) => ({
+	...descriptor,
+	idOf: (written) => written[descriptor.idField],
+	[checked]: true
+});
+const USER_OPERATIONS = Object.values(QueryUsersBodyFilterItemOperation);
+const TEAM_OPERATIONS = Object.values(QueryTeamsBodyFilterItemOperation);
+const SESSION_OPERATIONS = Object.values(QuerySessionsBodyFilterItemOperation);
+const GRANT_OPERATIONS = Object.values(QueryGrantsBodyFilterItemOperation);
+const IDP_OPERATIONS = Object.values(QueryIdpsBodyFilterItemOperation);
+const PROJECT_OPERATIONS = Object.values(QueryProjectsBodyFilterItemOperation);
+/** Every filter operation the API knows, so `--filter` tells one from a value. */
+const OPERATIONS = [.../* @__PURE__ */ new Set([
+	...USER_OPERATIONS,
+	...TEAM_OPERATIONS,
+	...SESSION_OPERATIONS,
+	...GRANT_OPERATIONS,
+	...IDP_OPERATIONS,
+	...PROJECT_OPERATIONS
+])];
+/** A release's pointers as an indented table, one pinned revision per row. */
+const releasePointers = (release) => {
+	const { pointers } = release;
+	return ["resources", ...renderTable([
+		"kind",
+		"handle",
+		"revision_id"
+	], pointers).split("\n").map((line) => `  ${line}`)].join("\n");
+};
 /** The operations a policy can guard, as the generated publish body names them. */
 const POLICY_OPERATIONS = PublishPolicyBody.shape.operation.options;
 /**
@@ -20735,7 +21090,7 @@ const POLICY_OPERATIONS = PublishPolicyBody.shape.operation.options;
 * truth. Adding a backend resource is adding an entry here.
 */
 const RESOURCES = {
-	users: {
+	users: resource({
 		group: CommandGroups.usersAndTeams,
 		groupOrder: 1,
 		singular: "user",
@@ -20757,21 +21112,20 @@ const RESOURCES = {
 			"metadata.updated_at"
 		],
 		list: list({
-			items: "users",
 			body: QueryUsersBody,
-			response: QueryUsersResponse,
+			item: QueryUsersResponse.shape.users.element,
 			filters: [
 				{
 					field: "created_at",
-					operations: FILTER_OPERATIONS
+					operations: USER_OPERATIONS
 				},
 				{
 					field: "id",
-					operations: FILTER_OPERATIONS
+					operations: USER_OPERATIONS
 				},
 				{
 					field: "schema",
-					operations: FILTER_OPERATIONS
+					operations: USER_OPERATIONS
 				},
 				{
 					field: "schema_object_type",
@@ -20783,15 +21137,15 @@ const RESOURCES = {
 				},
 				{
 					field: "status",
-					operations: FILTER_OPERATIONS
+					operations: USER_OPERATIONS
 				},
 				{
 					field: "team_id",
-					operations: FILTER_OPERATIONS
+					operations: USER_OPERATIONS
 				},
 				{
 					field: "lifecycle_owner_team_id",
-					operations: FILTER_OPERATIONS
+					operations: USER_OPERATIONS
 				}
 			],
 			sorts: [
@@ -20801,17 +21155,19 @@ const RESOURCES = {
 				"status",
 				"lifecycle_owner_team_id"
 			],
-			call: ({ client }, body) => client.queryUsers(body)
+			call: ({ client }, body) => client.queryUsers(body),
+			items: pagedFunctions.queryUsers.items,
+			next: pagedFunctions.queryUsers.next
 		}),
-		get: {
+		get: get({
 			call: ({ client }, id) => client.getUserByID(id),
 			response: GetUserByIDResponse
-		},
+		}),
 		create: create(CreateUserBody, ({ client, projectId }, body) => client.createUser(body, { project_id: projectId })),
 		update: update(PatchUserByIDBody, ({ client }, id, body) => client.patchUserByID(id, body)),
 		delete: { call: ({ client }, id) => client.deleteUserByID(id) }
-	},
-	teams: {
+	}),
+	teams: resource({
 		group: CommandGroups.usersAndTeams,
 		groupOrder: 2,
 		singular: "team",
@@ -20830,21 +21186,20 @@ const RESOURCES = {
 			"updated_at"
 		],
 		list: list({
-			items: "teams",
 			body: QueryTeamsBody,
-			response: QueryTeamsResponse,
+			item: QueryTeamsResponse.shape.teams.element,
 			filters: [
 				{
 					field: "created_at",
-					operations: FILTER_OPERATIONS
+					operations: TEAM_OPERATIONS
 				},
 				{
 					field: "name",
-					operations: FILTER_OPERATIONS
+					operations: TEAM_OPERATIONS
 				},
 				{
 					field: "status",
-					operations: FILTER_OPERATIONS
+					operations: TEAM_OPERATIONS
 				}
 			],
 			sorts: [
@@ -20852,20 +21207,22 @@ const RESOURCES = {
 				"name",
 				"status"
 			],
-			call: ({ client, projectId }, body) => client.queryTeams(body, { project_id: projectId })
+			call: ({ client, projectId }, body) => client.queryTeams(body, { project_id: projectId }),
+			items: pagedFunctions.queryTeams.items,
+			next: pagedFunctions.queryTeams.next
 		}),
-		get: {
+		get: get({
 			call: ({ client }, id) => client.getTeam(id),
 			response: GetTeamResponse
-		},
+		}),
 		create: create(CreateTeamBody, ({ client, projectId }, body) => client.createTeam(body, { project_id: projectId })),
 		update: update(UpdateTeamBody, ({ client }, id, body) => client.updateTeam(id, body)),
 		delete: {
 			verb: "deactivate",
 			call: ({ client }, id) => client.deleteTeam(id)
 		}
-	},
-	sessions: {
+	}),
+	sessions: resource({
 		group: CommandGroups.authentication,
 		singular: "session",
 		idField: "session_id",
@@ -20885,40 +21242,41 @@ const RESOURCES = {
 			"expires_at"
 		],
 		list: list({
-			items: "sessions",
 			body: QuerySessionsBody,
-			response: QuerySessionsResponse,
+			item: QuerySessionsResponse.shape.sessions.element,
 			filters: [
 				{
 					field: "created_at",
-					operations: FILTER_OPERATIONS
+					operations: SESSION_OPERATIONS
 				},
 				{
 					field: "user_id",
-					operations: FILTER_OPERATIONS
+					operations: SESSION_OPERATIONS
 				},
 				{
 					field: "state",
-					operations: FILTER_OPERATIONS
+					operations: SESSION_OPERATIONS
 				},
 				{
 					field: "lifecycle_owner_team_id",
-					operations: FILTER_OPERATIONS
+					operations: SESSION_OPERATIONS
 				}
 			],
 			sorts: ["created_at", "user_id"],
-			call: ({ client, projectId }, body) => client.querySessions(body, { project_id: projectId })
+			call: ({ client, projectId }, body) => client.querySessions(body, { project_id: projectId }),
+			items: pagedFunctions.querySessions.items,
+			next: pagedFunctions.querySessions.next
 		}),
-		get: {
+		get: get({
 			call: ({ client }, id) => client.getSession(id),
 			response: GetSessionResponse
-		},
+		}),
 		delete: {
 			verb: "revoke",
 			call: ({ client }, id) => client.revokeSession(id)
 		}
-	},
-	events: {
+	}),
+	events: resource({
 		group: CommandGroups.diagnostics,
 		singular: "event",
 		idField: "id",
@@ -20940,14 +21298,13 @@ const RESOURCES = {
 			"request_id",
 			"occurred_at"
 		],
-		list: {
-			items: "data",
-			response: ListEventsResponse,
+		list: list({
+			item: ListEventsResponse.shape.data.element,
 			filters: [
 				{
 					field: "category",
 					operations: ["equals"],
-					values: EVENT_CATEGORIES,
+					values: Object.values(ListEventsCategoryItem),
 					combine: "or"
 				},
 				{
@@ -20985,11 +21342,10 @@ const RESOURCES = {
 				},
 				{
 					field: "created_at",
-					operations: ["greater_than_or_equal", "less_than"],
-					params: {
+					...range({
 						greater_than_or_equal: "created_after",
 						less_than: "created_before"
-					}
+					})
 				}
 			],
 			sorts: ["occurred_at"],
@@ -20997,11 +21353,13 @@ const RESOURCES = {
 			call: ({ client, projectId }, params) => client.listEvents({
 				project_id: projectId,
 				...params
-			})
-		},
-		get: { call: ({ client, projectId }, id) => client.getEvent(id, { project_id: projectId }) }
-	},
-	grants: {
+			}),
+			items: pagedFunctions.listEvents.items,
+			next: pagedFunctions.listEvents.next
+		}),
+		get: get({ call: ({ client, projectId }, id) => client.getEvent(id, { project_id: projectId }) })
+	}),
+	grants: resource({
 		group: CommandGroups.usersAndTeams,
 		groupOrder: 3,
 		singular: "grant",
@@ -21024,29 +21382,28 @@ const RESOURCES = {
 			"expires_at"
 		],
 		list: list({
-			items: "grants",
 			body: QueryGrantsBody,
-			response: QueryGrantsResponse,
+			item: QueryGrantsResponse.shape.grants.element,
 			filters: [
 				{
 					field: "created_at",
-					operations: FILTER_OPERATIONS
+					operations: GRANT_OPERATIONS
 				},
 				{
 					field: "user_id",
-					operations: FILTER_OPERATIONS
+					operations: GRANT_OPERATIONS
 				},
 				{
 					field: "team_id",
-					operations: FILTER_OPERATIONS
+					operations: GRANT_OPERATIONS
 				},
 				{
 					field: "relation",
-					operations: FILTER_OPERATIONS
+					operations: GRANT_OPERATIONS
 				},
 				{
 					field: "expires_at",
-					operations: FILTER_OPERATIONS
+					operations: GRANT_OPERATIONS
 				}
 			],
 			sorts: [
@@ -21054,16 +21411,18 @@ const RESOURCES = {
 				"expires_at",
 				"id"
 			],
-			call: ({ client, projectId }, body) => client.queryGrants(body, { project_id: projectId })
+			call: ({ client, projectId }, body) => client.queryGrants(body, { project_id: projectId }),
+			items: pagedFunctions.queryGrants.items,
+			next: pagedFunctions.queryGrants.next
 		}),
-		get: {
+		get: get({
 			call: ({ client, projectId }, id) => client.getGrant(id, { project_id: projectId }),
 			response: GetGrantResponse
-		},
+		}),
 		create: create(CreateGrantBody, ({ client, projectId }, body) => client.createGrant(body, { project_id: projectId }), { example: "--relation viewer --user-identifier alice@acme.com" }),
 		delete: { call: ({ client, projectId }, id) => client.deleteGrant(id, { project_id: projectId }) }
-	},
-	idps: {
+	}),
+	idps: resource({
 		group: CommandGroups.authentication,
 		singular: "identity provider connection",
 		idField: "id",
@@ -21083,29 +21442,30 @@ const RESOURCES = {
 			"updated_at"
 		],
 		list: list({
-			items: "idps",
 			body: QueryIdpsBody,
-			response: QueryIdpsResponse,
+			item: QueryIdpsResponse.shape.idps.element,
 			filters: [{
 				field: "slug",
-				operations: FILTER_OPERATIONS
+				operations: IDP_OPERATIONS
 			}, {
 				field: "created_at",
-				operations: FILTER_OPERATIONS
+				operations: IDP_OPERATIONS
 			}],
 			sorts: ["slug", "created_at"],
-			call: ({ client, projectId }, body) => client.queryIdps(body, { project_id: projectId })
+			call: ({ client, projectId }, body) => client.queryIdps(body, { project_id: projectId }),
+			items: pagedFunctions.queryIdps.items,
+			next: pagedFunctions.queryIdps.next
 		}),
-		get: {
+		get: get({
 			call: ({ client, projectId }, id) => client.getIdpById(id, { project_id: projectId }),
 			response: GetIdpByIdResponse
-		},
+		}),
 		create: create(CreateIdpBody, ({ client, projectId }, body) => client.createIdp(body, { project_id: projectId }), {
 			root: "idp",
 			example: "--slug acme-sso --protocol oidc --display-name 'Acme SSO' --oidc-issuer https://sso.acme.example --oidc-client-id <client_id> --oidc-client-secret '${{ ACME_SSO_CLIENT_SECRET }}' --oidc-scopes openid --oidc-scopes profile --oidc-scopes email"
 		})
-	},
-	projects: {
+	}),
+	projects: resource({
 		group: CommandGroups.configuration,
 		singular: "project",
 		idField: "id",
@@ -21122,23 +21482,24 @@ const RESOURCES = {
 			"updated_at"
 		],
 		list: list({
-			items: "projects",
 			body: QueryProjectsBody,
-			response: QueryProjectsResponse,
+			item: QueryProjectsResponse.shape.projects.element,
 			filters: [{
 				field: "created_at",
-				operations: FILTER_OPERATIONS
+				operations: PROJECT_OPERATIONS
 			}],
 			sorts: ["created_at"],
-			call: ({ client }, body) => client.queryProjects(body)
+			call: ({ client }, body) => client.queryProjects(body),
+			items: pagedFunctions.queryProjects.items,
+			next: pagedFunctions.queryProjects.next
 		}),
-		get: {
+		get: get({
 			call: ({ client }, id) => client.getProject(id),
 			response: GetProjectResponse
-		},
+		}),
 		update: update(PatchProjectBody, ({ client }, id, body) => client.patchProject(id, body))
-	},
-	schemas: {
+	}),
+	schemas: resource({
 		group: CommandGroups.configuration,
 		singular: "schema",
 		idField: "id",
@@ -21157,9 +21518,8 @@ const RESOURCES = {
 			"schema.kind",
 			"metadata.created_at"
 		],
-		list: {
-			items: "schemas",
-			response: ListSchemasResponse,
+		list: list({
+			item: ListSchemasResponse.shape.schemas.element,
 			filters: [
 				{
 					field: "object_type",
@@ -21172,16 +21532,18 @@ const RESOURCES = {
 				{
 					field: "revisions",
 					operations: ["equals"],
-					values: ["all", "latest"],
-					default: "latest"
+					values: Object.values(ListSchemasRevisions),
+					default: ListSchemasRevisions.latest
 				}
 			],
 			call: ({ client, projectId }, params) => client.listSchemas({
 				...params,
 				project_id: projectId
-			})
-		},
-		get: {
+			}),
+			items: pagedFunctions.listSchemas.items,
+			next: pagedFunctions.listSchemas.next
+		}),
+		get: get({
 			response: GetSchemaByIdResponse,
 			call: async ({ client, projectId }, ref) => {
 				try {
@@ -21198,9 +21560,9 @@ const RESOURCES = {
 				if (!current) throw new ZitadelError("E_NOT_FOUND", `No schema named "${ref}"`, { hint: "Run `schemas list` to see the object types this project has." });
 				return current;
 			}
-		}
-	},
-	release: {
+		})
+	}),
+	release: resource({
 		group: CommandGroups.configuration,
 		singular: "release",
 		idField: "id",
@@ -21208,7 +21570,8 @@ const RESOURCES = {
 			"id",
 			"metadata.message",
 			"metadata.git_sha",
-			"revoked_at"
+			"revoked_at",
+			"metadata.created_at"
 		],
 		heading: "id",
 		detail: [
@@ -21220,20 +21583,22 @@ const RESOURCES = {
 			"metadata.git_sha",
 			"metadata.git_dirty"
 		],
-		list: {
-			items: "releases",
-			response: ListReleasesResponse,
+		list: list({
+			item: ListReleasesResponse.shape.releases.element,
 			call: ({ client, projectId }, params) => client.listReleases({
 				...params,
 				project_id: projectId
-			})
-		},
-		get: {
+			}),
+			items: pagedFunctions.listReleases.items,
+			next: pagedFunctions.listReleases.next
+		}),
+		get: get({
 			call: ({ client, projectId }, id) => client.getReleaseById(id, { project_id: projectId }),
-			response: GetReleaseByIdResponse
-		}
-	},
-	"flow-definitions": {
+			response: GetReleaseByIdResponse,
+			sections: (release) => [releasePointers(release)]
+		})
+	}),
+	"flow-definitions": resource({
 		group: CommandGroups.configuration,
 		singular: "flow definition",
 		idField: "id",
@@ -21253,9 +21618,8 @@ const RESOURCES = {
 			"created_at",
 			"updated_at"
 		],
-		list: {
-			items: "flow_definitions",
-			response: ListFlowDefinitionsResponse,
+		list: list({
+			item: ListFlowDefinitionsResponse.shape.flow_definitions.element,
 			filters: [
 				{
 					field: "name",
@@ -21268,16 +21632,18 @@ const RESOURCES = {
 				{
 					field: "revisions",
 					operations: ["equals"],
-					values: ["all", "latest"],
-					default: "latest"
+					values: Object.values(ListFlowDefinitionsRevisions),
+					default: ListFlowDefinitionsRevisions.latest
 				}
 			],
 			call: ({ client, projectId }, params) => client.listFlowDefinitions({
 				...params,
 				project_id: projectId
-			})
-		},
-		get: {
+			}),
+			items: pagedFunctions.listFlowDefinitions.items,
+			next: pagedFunctions.listFlowDefinitions.next
+		}),
+		get: get({
 			response: GetFlowDefinitionResponse,
 			call: async ({ client, projectId }, ref) => {
 				if (ref.startsWith("flowdef_")) return client.getFlowDefinition(ref);
@@ -21289,26 +21655,27 @@ const RESOURCES = {
 				if (!current) throw new ZitadelError("E_NOT_FOUND", `No flow definition named "${ref}"`, { hint: "Run `flow-definitions list` to see the flows this project has." });
 				return current;
 			}
-		}
-	},
-	branding: {
+		})
+	}),
+	branding: resource({
 		group: CommandGroups.configuration,
 		singular: "branding revision",
 		idField: "id",
 		columns: ["id", "created_at"],
 		heading: "id",
 		detail: ["id", "created_at"],
-		list: {
+		list: list({
 			paged: false,
-			response: ListBrandingResponse,
-			call: ({ client, projectId }) => client.listBranding({ project_id: projectId })
-		},
-		get: {
+			item: ListBrandingResponse.element,
+			call: ({ client, projectId }) => client.listBranding({ project_id: projectId }),
+			items: (page) => page
+		}),
+		get: get({
 			call: ({ client }, id) => client.getBrandingById(id),
 			response: GetBrandingByIdResponse
-		}
-	},
-	policies: {
+		})
+	}),
+	policies: resource({
 		group: CommandGroups.configuration,
 		singular: "policy",
 		idField: "id",
@@ -21330,9 +21697,8 @@ const RESOURCES = {
 			"created_at",
 			"updated_at"
 		],
-		list: {
-			items: "policies",
-			response: ListPoliciesResponse,
+		list: list({
+			item: ListPoliciesResponse.shape.policies.element,
 			filters: [{
 				field: "operation",
 				operations: ["equals"]
@@ -21340,9 +21706,11 @@ const RESOURCES = {
 			call: ({ client, projectId }, params) => client.listPolicies({
 				...params,
 				project_id: projectId
-			})
-		},
-		get: {
+			}),
+			items: pagedFunctions.listPolicies.items,
+			next: pagedFunctions.listPolicies.next
+		}),
+		get: get({
 			response: GetPolicyResponse,
 			call: async ({ client, projectId }, ref) => {
 				if (ref.startsWith("pol_")) return client.getPolicy(ref, { project_id: projectId });
@@ -21357,8 +21725,8 @@ const RESOURCES = {
 				if (!current) throw notFound();
 				return current;
 			}
-		}
-	}
+		})
+	})
 };
 /**
 * The `<resource> <verb>` commands, ready for the explicit command table. They
@@ -21366,7 +21734,7 @@ const RESOURCES = {
 * `EnvironmentCommand`), so they take `--env` and `--env-file` too.
 */
 const RESOURCE_COMMANDS = buildResourceCommands(RESOURCES, {
-	operations: FILTER_OPERATIONS,
+	operations: OPERATIONS,
 	references: {
 		matches: isVariableReference,
 		example: "'${{ NAME }}'"
@@ -21437,12 +21805,12 @@ var ResourcesList = class ResourcesList extends BaseCommand {
 */
 async function claimProjectAsAdmin(input) {
 	const { serverUrl, projectId, projectSecret, admin } = input;
-	const { challenge_id } = await createZitadelClient({
+	const { challenge_id } = await createZitadelClient$1({
 		baseUrl: serverUrl,
 		token: projectSecret
 	}).initClaim(projectId, localAdminRequest(serverUrl));
 	const cookie = await adminSessionCookie(serverUrl, admin);
-	const session = createZitadelClient({ baseUrl: serverUrl });
+	const session = createZitadelClient$1({ baseUrl: serverUrl });
 	const { csrf_token } = await session.getMySessionCsrfToken(void 0, localAdminRequest(serverUrl, { cookie }));
 	const { team_id, claimed_at } = await session.completeClaim(projectId, { challenge_id }, localAdminRequest(serverUrl, {
 		cookie,
@@ -21507,7 +21875,10 @@ async function materializeSetupResources(opts) {
 	const filesWritten = [];
 	const preset = opts.preset ?? DEFAULT_SETUP_PRESET;
 	const useCase = opts.useCase ?? DEFAULT_SETUP_USE_CASE;
-	const schemaTemplate = defaultSchemaTemplate(preset, useCase);
+	const schemaTemplate = getDefaultHumanUserSchemaBody({
+		preset,
+		useCase
+	});
 	const planned = planConnections(schemaTemplate, opts.sso);
 	await refuseResourceConflicts(opts.cwd, opts.force, planned);
 	const slugs = planned.map((entry) => entry.slug);
@@ -21516,7 +21887,7 @@ async function materializeSetupResources(opts) {
 		await mkdir(join(opts.cwd, IDPS_DIR), { recursive: true });
 		if (await writeResourceFile(opts.cwd, connectionPath, connection, false, connectionExists(selection))) filesWritten.push(join(opts.cwd, connectionPath));
 		await updateState(opts.cwd, connectionPath, {
-			id: requiredString(created.id, "created identity provider connection id"),
+			id: created.id,
 			hash: hashForState({ normalize: normalizeIdpBody }, connection)
 		});
 	}
@@ -21524,7 +21895,7 @@ async function materializeSetupResources(opts) {
 	if (await writeResourceFile(opts.cwd, DEFAULT_SCHEMA_CONFIG_PATH, schemaBody, opts.force)) filesWritten.push(join(opts.cwd, DEFAULT_SCHEMA_CONFIG_PATH));
 	const schema = await opts.client.createSchema(schemaBody, { project_id: opts.projectId });
 	await updateState(opts.cwd, DEFAULT_SCHEMA_CONFIG_PATH, {
-		id: requiredString(schema.id, "created schema id"),
+		id: schema.id,
 		hash: hashForState({ normalize: normalizeSchemaBody }, schemaBody)
 	});
 	const flowTemplate = getDefaultLoginFlow({
@@ -21539,7 +21910,7 @@ async function materializeSetupResources(opts) {
 		flow_definition: flowBody
 	});
 	await updateState(opts.cwd, DEFAULT_FLOW_CONFIG_PATH, {
-		id: requiredString(flow.id, "created flow definition id"),
+		id: flow.id,
 		hash: hashForState({ normalize: normalizeFlowBody }, flowBody),
 		name: flowBody.name,
 		status: flowBody.status
@@ -21557,7 +21928,7 @@ async function materializeSetupResources(opts) {
 		await mkdir(join(opts.cwd, POLICIES_DIR), { recursive: true });
 		if ((kept === void 0 || policy !== kept) && await writeResourceFile(opts.cwd, PASSWORD_POLICY_PATH, policy, opts.force)) filesWritten.push(join(opts.cwd, PASSWORD_POLICY_PATH));
 		await updateState(opts.cwd, PASSWORD_POLICY_PATH, {
-			id: requiredString(published.id, "published policy id"),
+			id: published.id,
 			hash: hashForState({ normalize: (body) => toPolicyWireBody(body) }, policy)
 		});
 	}
@@ -21583,16 +21954,11 @@ async function materializeSetupResources(opts) {
 * only the keys that file is missing.
 */
 async function assertNoSetupResourceConflicts(opts) {
-	const schemaTemplate = defaultSchemaTemplate(opts.preset ?? DEFAULT_SETUP_PRESET, opts.useCase ?? DEFAULT_SETUP_USE_CASE);
-	await refuseResourceConflicts(opts.cwd, opts.force, planConnections(schemaTemplate, opts.sso));
-}
-/** The default human user schema for a preset and use case, without the template's `$id`. */
-function defaultSchemaTemplate(preset, useCase) {
-	const { $id: _templateId, ...schemaTemplate } = getDefaultHumanUserSchema({
-		preset,
-		useCase
+	const schemaTemplate = getDefaultHumanUserSchemaBody({
+		preset: opts.preset ?? DEFAULT_SETUP_PRESET,
+		useCase: opts.useCase ?? DEFAULT_SETUP_USE_CASE
 	});
-	return schemaTemplate;
+	await refuseResourceConflicts(opts.cwd, opts.force, planConnections(schemaTemplate, opts.sso));
 }
 /** The connection each chosen provider gets, and the file it is written to. */
 function planConnections(schemaTemplate, sso) {
@@ -21738,10 +22104,6 @@ function resourceExists(relPath, onExists) {
 		nextCommands: onExists?.nextCommands
 	});
 }
-function requiredString(value, label) {
-	if (typeof value === "string" && value.length > 0) return value;
-	throw new ZitadelError("E_VALIDATION", `Missing ${label} in server response.`);
-}
 function isErrno(error, code) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
@@ -21862,8 +22224,31 @@ function errorShape(error) {
 	return { message: String(error) };
 }
 //#endregion
+//#region src/lib/secret-paths.ts
+/**
+* Whether `path` must never be committed: a `.zitadel/secret`, anything under `.zitadel/local/`, or an `.env*` file other than `.env.example`.
+*
+* Matched without regard to case, since `.ENV` is the same file as `.env` on
+* macOS and Windows.
+*/
+function isSecretPath(path) {
+	const lower = path.toLowerCase();
+	const name = lower.split("/").pop() ?? lower;
+	if (lower === ".zitadel/secret" || lower.endsWith("/.zitadel/secret")) return true;
+	if (isLocalRuntimePath(lower)) return true;
+	return name.startsWith(".env") && name !== ".env.example";
+}
+/**
+* Whether `path` is under `.zitadel/local/`, at any depth, where the local server keeps its admin credential and data.
+*
+* Matched with its case, since it names the directory `start` writes; on a
+* case-sensitive filesystem `.Zitadel/Local/` is someone else's.
+*/
+function isLocalRuntimePath(path) {
+	return /(^|\/)\.zitadel\/local(\/|$)/.test(path);
+}
+//#endregion
 //#region src/commands/setup/initial-commit.ts
-const run = promisify(execFile);
 /**
 * The subject of the commit setup makes. Conventional-commit style, like every
 * other commit this repository's tooling writes, and with no trailer of any
@@ -21871,19 +22256,6 @@ const run = promisify(execFile);
 */
 const INITIAL_COMMIT_SUBJECT = "chore: scaffold the project with zitadel setup";
 /**
-* Paths that must never be committed, whatever `.gitignore` happens to say.
-*
-* `.zitadel/local/` holds the local admin credential and the server's data
-* directory. Only the `.gitignore` line `start` appends keeps it out, so a
-* project missing that line would otherwise commit the credential.
-*/
-function isSecretPath(path) {
-	const name = path.split("/").pop() ?? path;
-	if (path === ".zitadel/secret" || path.endsWith("/.zitadel/secret")) return true;
-	if (isLocalRuntimePath(path)) return true;
-	return name.startsWith(".env") && name !== ".env.example";
-}
-/**
 * Paths the CLI writes itself, which therefore do not count as the
 * developer's uncommitted work. Matched against a path already made relative
 * to the project directory, never the repository root: in a monorepo the two
@@ -21900,156 +22272,16 @@ function isCliOwned(path) {
 	return path === ".gitignore" || path.endsWith("/.gitignore") || isLocalRuntimePath(path);
 }
 /**
-* `.zitadel/local/` at any depth, not only at the project root: a nested app
-* inside the project directory has its own, holding its own admin credential.
-*/
-function isLocalRuntimePath(path) {
-	return /(^|\/)\.zitadel\/local(\/|$)/.test(path);
-}
-/**
-* Run git in `cwd`, returning its stdout.
-*
-* `core.quotePath=false` stops git C-quoting any path holding a non-ASCII byte
-* or a space (`"caf\303\251.txt"`). A quoted path is not the path: it matches
-* no pathspec and no suffix test, so a secret under such a name would be
-* neither recognised nor unstaged.
-*/
-async function git(cwd, args, env) {
-	const { stdout } = await run("git", [
-		"-c",
-		"core.quotePath=false",
-		...args
-	], {
-		cwd,
-		maxBuffer: 16777216,
-		...env ? { env: {
-			...process.env,
-			...env
-		} } : {}
-	});
-	return stdout;
-}
-/**
-* Whether `cwd` already sits inside a git repository.
-*
-* Only git's own "not a git repository" counts as no. Every other failure — a
-* dubious-ownership refusal, a permission error, a broken `HOME` — is raised,
-* because answering "no" to one of those would skip the clean-tree check and
-* then `git init` a second repository nested inside the first.
+* Last resort, used only where git can build no identity of its own: a bare
+* CI container has no configured identity and often no passwd entry or
+* hostname to guess from, and there git refuses to commit. No commit means no
+* `git_sha`, and the next deploy has nothing to diff against.
 */
-async function insideRepository(cwd) {
-	try {
-		await git(cwd, ["rev-parse", "--git-dir"]);
-		return true;
-	} catch (error) {
-		const message = messageOf(error).toLowerCase();
-		if (message.includes("not a git repository") || message.includes("enoent")) return false;
-		throw error;
-	}
-}
-/**
-* Where the project sits inside its repository (`apps/web/`, or `""` at the
-* root). `git status` reports paths from the repository root whatever
-* directory it runs in, so this is what turns one into a project-relative path.
-*/
-async function projectPrefix(cwd) {
-	return (await git(cwd, ["rev-parse", "--show-prefix"])).trim();
-}
-/**
-* Whether the developer has an identity of their own for git to commit with,
-* from config or from `GIT_AUTHOR_*`/`GIT_COMMITTER_*`/`EMAIL`.
-*
-* Without one git does not fail: it guesses from the username and hostname and
-* commits anyway. `user.useConfigOnly` is what turns that guess back into an
-* error, so asking under it is the way to tell a real identity from a guessed
-* one. Nothing is passed to the commit either way — an identity this invented
-* would be a worse author than the one git derives from the machine.
-*/
-async function hasOwnIdentity(cwd) {
-	try {
-		await git(cwd, [
-			"-c",
-			"user.useConfigOnly=true",
-			"var",
-			"GIT_AUTHOR_IDENT"
-		]);
-		return true;
-	} catch {
-		return false;
-	}
-}
-/**
-* Whether git can produce any identity at all, its own guess included.
-*
-* A bare CI container has no configured identity and often no passwd entry or
-* hostname to guess from, and there git refuses to commit. Only then is an
-* identity supplied, because no commit means no `git_sha` and the next deploy
-* has nothing to diff against.
-*/
-async function canBuildIdentity(cwd) {
-	try {
-		await git(cwd, ["var", "GIT_AUTHOR_IDENT"]);
-		return true;
-	} catch {
-		return false;
-	}
-}
-/**
-* Last resort, used only where git can build no identity of its own.
-*
-* Passed as environment variables rather than `-c user.*`, because an
-* inherited `GIT_AUTHOR_NAME=` (empty, as some runners leave it) outranks
-* `-c` and git then refuses with "empty ident name". The environment beats
-* both the config and whatever was inherited.
-*/
-const FALLBACK_IDENTITY = {
-	GIT_AUTHOR_NAME: "Zitadel Setup",
-	GIT_AUTHOR_EMAIL: "setup@zitadel.local",
-	GIT_COMMITTER_NAME: "Zitadel Setup",
-	GIT_COMMITTER_EMAIL: "setup@zitadel.local"
+const FALLBACK_AUTHOR = {
+	name: "Zitadel Setup",
+	email: "setup@zitadel.local"
 };
 /**
-* Everything git considers a change under the project directory, untracked
-* files included. An untracked file counts: setup stages the whole project, so
-* one left lying about would be swept into setup's commit.
-*
-* Scoped to `.` so that in a monorepo a sibling package's work-in-progress —
-* which `git add` here would never touch — does not refuse the setup.
-*/
-async function changes(cwd) {
-	const fields = (await git(cwd, [
-		"status",
-		"--porcelain",
-		"-z",
-		"--untracked-files=all",
-		"--",
-		"."
-	])).split("\0");
-	const found = [];
-	for (let index = 0; index < fields.length; index += 1) {
-		const entry = fields[index];
-		if (entry === void 0 || entry === "") continue;
-		const status = entry.slice(0, 2);
-		if (status.includes("R") || status.includes("C")) index += 1;
-		found.push({
-			path: entry.slice(3),
-			untracked: status === "??"
-		});
-	}
-	return found;
-}
-/** The paths staged in `cwd`, relative to it and never quoted. */
-async function stagedPaths(cwd, env) {
-	return (await git(cwd, [
-		"diff",
-		"--cached",
-		"-z",
-		"--name-only",
-		"--no-renames",
-		"--relative"
-	], env)).split("\0").filter((path) => path !== "");
-}
-/**
 * Refuse a project whose repository has anything uncommitted, before setup
 * writes a single file.
 *
@@ -22060,19 +22292,22 @@ async function stagedPaths(cwd, env) {
 * apart, and committing someone's work-in-progress under setup's name is worse
 * than any diff it would buy. Checked up front rather than at commit time, so
 * a refusal costs nothing and leaves no half-made project behind.
+*
+* A repository where a commit would land where it should not (during a
+* merge, rebase, cherry-pick, revert or bisect, or on a detached HEAD) is
+* refused here too, for the same reason: found only at commit time, setup
+* would already have done all its work.
+*
+* When git cannot answer, setup refuses rather than carries on: the commit
+* does not check again, so going ahead would stage and commit the very work
+* this guard exists to protect.
 */
 async function assertCleanWorktree(cwd) {
-	if (!await insideRepository(cwd)) return;
-	let dirty;
-	try {
-		const prefix = await projectPrefix(cwd);
-		dirty = (await changes(cwd)).map((change) => ({
-			...change,
-			path: change.path.startsWith(prefix) ? change.path.slice(prefix.length) : change.path
-		})).filter((change) => !isCliOwned(change.path));
-	} catch (error) {
-		throw new ZitadelError("E_CONFLICT", `Could not tell whether the git working tree is clean: ${messageOf(error)}`, { hint: "Setup commits the files it writes, and will not do that without knowing the tree started clean. Fix what git is reporting, then run setup again, or pass --no-git to set up without touching version control." });
-	}
+	const repository = await Repository.open(cwd);
+	if (repository === null) return;
+	const blocked = await repository.readyToCommit().catch(cannotTell);
+	if (blocked !== null) throw new ZitadelError("E_CONFLICT", `Setup cannot commit here: ${blocked}`, { hint: "Setup commits the project so the first release records a commit. Finish or abort what is under way, or check out a branch, then run setup again, or pass --no-git to set up without touching version control." });
+	const dirty = (await repository.uncommittedFiles().catch(cannotTell)).filter((file) => !isCliOwned(file.path));
 	if (dirty.length === 0) return;
 	const modified = dirty.filter((change) => !change.untracked).map((change) => change.path);
 	const untracked = dirty.filter((change) => change.untracked).map((change) => change.path);
@@ -22085,6 +22320,10 @@ async function assertCleanWorktree(cwd) {
 		}
 	});
 }
+/** The refusal for a repository git could not answer about. */
+function cannotTell(error) {
+	throw new ZitadelError("E_CONFLICT", `Could not tell whether the git working tree is clean: ${messageOf(error)}`, { hint: "Setup commits the files it writes, and will not do that without knowing the tree started clean. Fix what git is reporting, then run setup again, or pass --no-git to set up without touching version control." });
+}
 /** `s` unless the list holds exactly one entry. */
 function plural(list) {
 	return list.length === 1 ? "" : "s";
@@ -22102,87 +22341,79 @@ function plural(list) {
 *
 * Nothing here prompts, so it behaves the same interactively and in CI, and no
 * failure is fatal: the worst case is the first release carrying no commit,
-* which is what happened before this existed.
+* which is what happened before this existed. When the commit fails after
+* setup ran `git init`, the outcome says so, since the repository now exists.
 */
 async function ensureInitialCommit(cwd) {
-	let scratch;
 	try {
-		const existing = await insideRepository(cwd);
-		if (!existing) await git(cwd, ["init", "--quiet"]);
-		scratch = await mkdtemp(join(tmpdir(), "zitadel-commit-"));
-		const index = { GIT_INDEX_FILE: join(scratch, "index") };
-		if (existing) await git(cwd, ["read-tree", "HEAD"], index).catch(() => void 0);
-		await git(cwd, [
-			"add",
-			"--all",
-			"--",
-			"."
-		], index);
-		const paths = await stagedPaths(cwd, index);
-		const secrets = paths.filter(isSecretPath);
-		if (secrets.length > 0) await git(cwd, [
-			"reset",
-			"--quiet",
-			"--",
-			...secrets
-		], index);
-		const stillStaged = (await stagedPaths(cwd, index)).filter(isSecretPath);
-		if (stillStaged.length > 0) return {
+		const existing = await Repository.open(cwd);
+		const outcome = await (existing ?? await Repository.create(cwd)).commitAll(INITIAL_COMMIT_SUBJECT, {
+			except: isSecretPath,
+			authorIfGitHasNone: FALLBACK_AUTHOR
+		}).catch((error) => ({
+			committed: false,
+			reason: firstLineOf(error)
+		}));
+		if (!outcome.committed) return {
 			kind: "unavailable",
-			reason: `${stillStaged[0]} could not be kept out of the commit, so nothing was committed`
+			reason: outcome.reason,
+			createdRepository: existing === null
 		};
-		if (paths.length === secrets.length) return {
-			kind: "unavailable",
-			reason: "there was nothing to commit"
+		const commit = {
+			sha: outcome.sha,
+			guessedIdentity: outcome.author !== "yours",
+			invented: outcome.author === "fallback"
 		};
-		const guessedIdentity = !await hasOwnIdentity(cwd);
-		const invented = !await canBuildIdentity(cwd);
-		await git(cwd, [
-			"-c",
-			"commit.gpgsign=false",
-			"commit",
-			"--quiet",
-			"--no-verify",
-			`--message=${INITIAL_COMMIT_SUBJECT}`
-		], {
-			...index,
-			...invented ? FALLBACK_IDENTITY : {}
-		});
-		const sha = await headSha(cwd);
-		if (sha === null) return {
-			kind: "unavailable",
-			reason: "the commit left no HEAD to record"
+		if (existing === null) return {
+			kind: "created",
+			...commit
 		};
-		await git(cwd, [
-			"reset",
-			"--quiet",
-			"--",
-			"."
-		]).catch(() => void 0);
 		return {
-			kind: existing ? "committed" : "created",
-			sha,
-			guessedIdentity,
-			invented
+			kind: "committed",
+			...commit
 		};
 	} catch (error) {
 		return {
 			kind: "unavailable",
-			reason: messageOf(error)
+			reason: firstLineOf(error),
+			createdRepository: false
 		};
-	} finally {
-		if (scratch) await rm(scratch, {
-			recursive: true,
-			force: true
-		});
 	}
 }
-/** git's own stderr where it has one, so the warning names the real cause. */
+/** The one line that says why the commit failed, since it goes into a one-line warning. */
+function firstLineOf(error) {
+	if (error instanceof RepositoryError) return error.headline();
+	return messageOf(error).split("\n")[0] ?? "";
+}
+/** git's own message, so the warning names the real cause. */
 function messageOf(error) {
-	const stderr = typeof error === "object" && error !== null ? error.stderr : void 0;
-	if (typeof stderr === "string" && stderr.trim() !== "") return stderr.trim().split("\n")[0] ?? stderr.trim();
 	return error instanceof Error ? error.message : String(error);
 }
+/** What `setup --json` reports under `git`: whether setup ran `git init`, even if the commit then failed, and the commit, or null. */
+function gitReport(outcome) {
+	if (outcome.kind === "created") return {
+		initialized: true,
+		commit: outcome.sha
+	};
+	if (outcome.kind === "committed") return {
+		initialized: false,
+		commit: outcome.sha
+	};
+	if (outcome.kind === "unavailable") return {
+		initialized: outcome.createdRepository,
+		commit: null
+	};
+	return {
+		initialized: false,
+		commit: null
+	};
+}
+/** The warning for a commit that could not be made, saying so when setup left a new, empty repository behind. */
+function unavailableWarning(outcome) {
+	const warning = `Could not commit the scaffolded project (${outcome.reason || "git gave no reason"}); the first release records no commit, so the next deploy cannot show a diff.`;
+	if (outcome.createdRepository) return `${warning} Setup created a new, empty git repository here.`;
+	return warning;
+}
 //#endregion
 //#region src/commands/setup/move-dev-port.ts
 /**
@@ -22204,7 +22435,7 @@ async function moveDevPort(opts) {
 	const issuer = issuerFromPort(devPort);
 	const secret = await readZitadelSecret(cwd);
 	const moving = previousIssuer !== issuer;
-	const client = createZitadelClient({
+	const client = createZitadelClient$1({
 		baseUrl: source,
 		token: secret.project_secret
 	});
@@ -22943,6 +23174,8 @@ const FRAMEWORK_OPTIONS = createOrca().availableFrameworks().map((framework) =>
 */
 const UNAVAILABLE_RENDERER_IDS = RENDERER_IDS.filter((id) => !AVAILABLE_RENDERER_IDS.includes(id));
 const RENDERER_FLAG_DESCRIPTION = UNAVAILABLE_RENDERER_IDS.length === 0 ? "Renderer (default: react)." : `Renderer (default: react). Not yet available: ${UNAVAILABLE_RENDERER_IDS.join(", ")}.`;
+/** The message the release setup publishes carries. */
+const INITIAL_DEPLOY_MESSAGE = "Initial deployment from zitadel setup";
 /**
 * The selector appended to setup's credential-recovery commands. `variable set`
 * is an `EnvironmentCommand` that resolves the project and server from the
@@ -23185,7 +23418,7 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 				force
 			});
 			consola.start(`Creating project on ${answers.server}${dryRun ? " (dry run)" : ""}`);
-			const unauthClient = createZitadelClient({ baseUrl: answers.server });
+			const unauthClient = createZitadelClient$1({ baseUrl: answers.server });
 			const projectName = defaultProjectName(cwd, app.framework);
 			project = dryRun ? dryRunProject(issuer) : await createProjectWithLocalHint(unauthClient, answers.server, this.meta.cliVersion, projectName, issuer, {
 				...retryOptionsFromFlags(flags),
@@ -23235,7 +23468,7 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 					passwordMinLengthSet: false
 				} : await materializeSetupResources({
 					cwd,
-					client: createZitadelClient({
+					client: createZitadelClient$1({
 						baseUrl: answers.server,
 						token: project.project_secret
 					}, { verbatim: true }),
@@ -23335,6 +23568,26 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 			package_manager: installOutcome.install.package_manager
 		});
 		const commit = await this.makeInitialCommit(cwd, dryRun, flags.git !== false);
+		const deployment = await this.deployScaffoldedProject({
+			cwd,
+			server: answers.server,
+			project,
+			dryRun,
+			selector: recoverySelector(flags.cwd)
+		});
+		const deployCommand = projectCommand(DEPLOY_ARGS, recoverySelector(flags.cwd), this.meta.cliVersion);
+		const deployStep = deployment === void 0 && !dryRun ? {
+			actions: [`Deploy .zitadel/ so the project serves its release: ${deployCommand}`],
+			boxActions: [{
+				text: "Deploy .zitadel/ so the project serves its release:",
+				command: deployCommand
+			}],
+			commands: [deployCommand]
+		} : {
+			actions: [],
+			boxActions: [],
+			commands: []
+		};
 		const writtenRel = allFilesWritten.map((file) => relativeDisplayPath(cwd, file));
 		let ownedByLocalAdmin;
 		const isLocal = serverKind.value(answers.server) === "local";
@@ -23389,6 +23642,7 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 			boxActions: [],
 			commands: []
 		};
+		let nextShown;
 		if (!this.jsonEnabled()) {
 			const sections = buildSummary({
 				projectFacts: await detectProjectFacts(cwd, app.framework),
@@ -23407,6 +23661,7 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 					renderSummary(sections),
 					"",
 					renderBoxActions([
+						...deployStep.boxActions,
 						...installOutcome.boxActions,
 						...consoleStep.boxActions,
 						...claimNudge.boxActions
@@ -23418,10 +23673,12 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 					borderColor: "green"
 				}
 			});
+			nextShown = asStepsShown();
 			consola.log(`\n${exploreAllCommands(this.meta.cliVersion)}`);
 			await showSkillsHint({
 				env: process.env,
-				interactive: !dryRun && !flags["non-interactive"] && Boolean(process.stdout.isTTY && process.stdin.isTTY)
+				interactive: !dryRun && !flags["non-interactive"] && Boolean(process.stdout.isTTY && process.stdin.isTTY),
+				cliVersion: this.meta.cliVersion
 			});
 		}
 		return this.emit({
@@ -23443,10 +23700,7 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 				})),
 				files_skipped: result.filesSkipped.map((file) => relativeDisplayPath(cwd, file)),
 				install: installOutcome.install,
-				git: {
-					initialized: commit.kind === "created",
-					commit: commit.kind === "created" || commit.kind === "committed" ? commit.sha : null
-				},
+				git: gitReport(commit),
 				sso: answers.sso.map((answer) => {
 					const slug = providerOf(answer.selection).slug;
 					const outcome = ssoOutcomes.get(slug);
@@ -23466,13 +23720,22 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 						} : null
 					};
 				}),
-				next_actions: [
+				deployment: deployment === void 0 ? null : {
+					release_id: deployment.releaseId,
+					content_hash: deployment.contentHash,
+					deployment_id: deployment.deploymentId,
+					origins: [...deployment.origins]
+				}
+			},
+			next: {
+				actions: [
+					...deployStep.actions,
 					...installOutcome.nextActions,
 					brandingGuidanceAction(this.meta.cliVersion),
 					...consoleStep.actions,
 					...claimNudge.actions
 				],
-				...nextCommandsData([
+				commands: [
 					...republishCommands(answers.sso.flatMap((answer) => {
 						const slug = providerOf(answer.selection).slug;
 						const outcome = ssoOutcomes.get(slug);
@@ -23486,11 +23749,13 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 							published: outcome?.secret.published
 						}];
 					}), this.meta.cliVersion, recoverySelector(flags.cwd)),
+					...deployStep.commands,
 					...installOutcome.nextCommands,
 					...consoleStep.commands,
 					...claimNudge.commands
-				])
-			}
+				]
+			},
+			nextShown
 		});
 	}
 	/**
@@ -23510,10 +23775,43 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 			if (outcome.invented) reportWarning("git could build no author identity on this machine, so the commit was made as Zitadel Setup <setup@zitadel.local>. Set user.name and user.email, then run `git commit --amend --reset-author` to put your own name on it.");
 			else if (outcome.guessedIdentity) reportWarning("This machine has no git user.name/user.email, so git guessed the author from your username and hostname. Set your identity and run `git commit --amend --reset-author` to put your own name on the commit.");
 		}
-		if (outcome.kind === "unavailable") reportWarning(`Could not commit the scaffolded project (${outcome.reason}); the first release records no commit, so the next deploy cannot show a diff.`);
+		if (outcome.kind === "unavailable") reportWarning(unavailableWarning(outcome));
 		return outcome;
 	}
 	/**
+	* Deploy `.zitadel/` to the project setup just created, to its primary
+	* origin. Narrated but never fatal: the app is scaffolded and committed, and
+	* a failure leaves the deploy one command away.
+	*/
+	async deployScaffoldedProject(opts) {
+		if (opts.dryRun) {
+			consola.info("Would deploy .zitadel/ to the project (dry run)");
+			return;
+		}
+		const json = this.jsonEnabled();
+		consola.start("Deploying .zitadel/ to the project");
+		try {
+			const deployment = await deployInitialRelease({
+				client: createZitadelClient$1({
+					baseUrl: opts.server,
+					token: opts.project.project_secret
+				}),
+				projectId: opts.project.id,
+				cwd: opts.cwd,
+				env: this.meta.env,
+				json,
+				color: !json && Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
+				message: INITIAL_DEPLOY_MESSAGE,
+				suggest: (args) => projectCommand(args, opts.selector, this.meta.cliVersion)
+			});
+			consola.success(`Deployed ${deployment.contentHash} to ${deployment.origins.length} origin${deployment.origins.length === 1 ? "" : "s"}`);
+			return deployment;
+		} catch (error) {
+			reportWarning(`The project was set up but its first deploy failed: ${toZitadelError(error).message}. Run \`zitadel ${DEPLOY_ARGS}${opts.selector}\` to publish .zitadel/.`);
+			return;
+		}
+	}
+	/**
 	* `setup --dev-port <n>` on an app setup already patched: moves the app to
 	* the new port (see {@link moveDevPort}) instead of skipping the directory.
 	*/
@@ -23542,9 +23840,9 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 				previous_issuer: move.previousIssuer,
 				issuer: move.issuer,
 				dev_port: devPort,
-				files_written: move.result.filesWritten.map((file) => relativeDisplayPath(cwd, file)),
-				next_actions: [`Restart the dev server and open ${move.issuer}/login.`]
-			}
+				files_written: move.result.filesWritten.map((file) => relativeDisplayPath(cwd, file))
+			},
+			next: { actions: [`Restart the dev server and open ${move.issuer}/login.`] }
 		});
 	}
 };
@@ -23801,7 +24099,7 @@ function retryOptionsFromFlags(flags) {
 */
 function ssoCredentialPublisher(server, project) {
 	if (server === "mock") return;
-	const client = createZitadelClient({
+	const client = createZitadelClient$1({
 		baseUrl: server,
 		token: project.project_secret
 	});
@@ -24138,6 +24436,99 @@ function buildSummary(opts) {
 	];
 }
 //#endregion
+//#region src/lib/skills/add.ts
+/** Where most coding agents read a project's skills: Codex, Cursor, GitHub Copilot, Gemini CLI and more. */
+const SHARED_SKILLS_DIR = ".agents/skills";
+/** Where Claude Code reads them, which reads no other folder. */
+const CLAUDE_SKILLS_DIR = ".claude/skills";
+/**
+* The skills this CLI ships, which its build copied into `dist/skills/`
+* (`./bundle.ts`): the set of the release the user runs.
+*/
+async function bundledSkills(packageRoot) {
+	return (await readdir(bundleDir(packageRoot), { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+/**
+* The project's folders to add the skills to: the shared one, and Claude
+* Code's as well when Claude Code is installed on this machine or the project
+* already has a `.claude/` folder, as one a teammate works on with it does.
+*/
+async function skillDirs(projectDir) {
+	return existsSync(join(projectDir, ".claude")) || await claudeCodeInstalled() ? [SHARED_SKILLS_DIR, CLAUDE_SKILLS_DIR] : [SHARED_SKILLS_DIR];
+}
+/**
+* Whether Claude Code is installed on this machine. A detection that fails
+* counts as no: it only decides the extra folder, never whether the skills
+* are added.
+*/
+async function claudeCodeInstalled() {
+	try {
+		return (await rosie.agents()).some((agent) => agent.name === "claude" && agent.detected);
+	} catch {
+		return false;
+	}
+}
+/**
+* Puts each skill's bundled folder at `<dir>/<skill>` in the project,
+* replacing whatever was there: an older version's copy, or the link
+* `npx skills add` leaves, which is removed rather than followed.
+*/
+async function addSkills(options) {
+	for (const dir of options.dirs) for (const skill of options.skills) {
+		const target = join(options.projectDir, dir, skill);
+		await rm(target, {
+			recursive: true,
+			force: true
+		});
+		await cp(join(bundleDir(options.packageRoot), skill), target, { recursive: true });
+	}
+}
+function bundleDir(packageRoot) {
+	return join(packageRoot, "dist", "skills");
+}
+//#endregion
+//#region src/commands/skills/add.ts
+/**
+* `zitadel skills add` — give the project's coding agents the Zitadel skills.
+*
+* The skills ship inside the CLI, so the ones added are those of the release
+* the user runs, which `setup` also pins the app's `@zitadel/*` packages to.
+* Adding them is this command's whole job, so it asks nothing; running it
+* again replaces them, which is how they follow a CLI update.
+*/
+var SkillsAdd = class SkillsAdd extends BaseCommand {
+	static description = "Add the Zitadel agent skills to this project.\n\nAdds the skills of this CLI's version to .agents/skills, which most coding agents read, and to .claude/skills for Claude Code. Run it again after updating the CLI to replace them with the new version's.";
+	static group = CommandGroups.gettingStarted;
+	static groupOrder = 5;
+	static examples = ["<%= config.bin %> <%= command.id %>", "<%= config.bin %> <%= command.id %> --cwd my-app"];
+	async run() {
+		const { flags } = await this.parse(SkillsAdd);
+		await this.toMeta(flags, { resolveServer: false });
+		const skills = await bundledSkills(this.config.root);
+		const dirs = await skillDirs(this.meta.cwd);
+		if (!this.meta.dryRun) await addSkills({
+			packageRoot: this.config.root,
+			projectDir: this.meta.cwd,
+			skills,
+			dirs
+		});
+		return this.emit({
+			status: "ok",
+			data: {
+				title: this.meta.dryRun ? "Zitadel agent skills to add." : "Zitadel agent skills added.",
+				skills,
+				directories: dirs,
+				...this.meta.dryRun ? { dry_run: true } : {}
+			},
+			pretty: [
+				`${this.meta.dryRun ? "Would add" : "Added"} the ${skills.length} Zitadel agent skills of CLI ${this.meta.cliVersion} to:`,
+				...dirs.map((dir) => `  ${dir}${dir === ".claude/skills" ? "  (Claude Code)" : ""}`),
+				"Run this again after updating the CLI to keep them in step with it."
+			].join("\n")
+		});
+	}
+};
+//#endregion
 //#region src/commands/start.ts
 var Start = class Start extends BaseCommand {
 	static description = "Start a local Zitadel server.";
@@ -24186,9 +24577,9 @@ var Start = class Start extends BaseCommand {
 				urls: {
 					api: serverUrl,
 					console: `${serverUrl}/ui/console/`
-				},
-				...nextCommandsData([this.suggestUnscoped("start")])
-			}
+				}
+			},
+			next: { commands: [this.suggestUnscoped("start")] }
 		});
 		await ensureLocalState(this.meta.cwd);
 		const env = await loadProjectEnv(this.meta.cwd, this.meta.env);
@@ -24213,7 +24604,8 @@ var Start = class Start extends BaseCommand {
 		};
 		return this.emit({
 			status: "ok",
-			data: readyData(runtime, alreadyRunning, this.meta.cliVersion, this.suggestUnscoped("setup --server local"))
+			data: readyData(runtime, alreadyRunning),
+			next: readyNext(this.meta.cliVersion, this.suggestUnscoped("setup --server local"))
 		});
 	}
 };
@@ -24227,7 +24619,7 @@ function platformBootstrapEnabled(env) {
 	const pinned = env.NEXTGEN_PLATFORM_PROJECT_ID;
 	return !pinned || pinned === "proj_platform";
 }
-function readyData(metadata, alreadyRunning, cliVersion, setupCommand) {
+function readyData(metadata, alreadyRunning) {
 	return {
 		title: alreadyRunning ? "Local Zitadel server is already running." : "Local Zitadel server is ready.",
 		runtime: {
@@ -24249,13 +24641,17 @@ function readyData(metadata, alreadyRunning, cliVersion, setupCommand) {
 		urls: {
 			api: metadata.server_url,
 			console: `${metadata.server_url}/ui/console/`
-		},
-		next_actions: [
+		}
+	};
+}
+function readyNext(cliVersion, setupCommand) {
+	return {
+		actions: [
 			"Create an app with authentication. Run setup in this directory or a subdirectory.",
 			"Setup asks for a framework and sign-in method, creates or updates your app, and installs its dependencies.",
 			serverLogAction(cliVersion)
 		],
-		...nextCommandsData([setupCommand])
+		commands: [setupCommand]
 	};
 }
 function validatePort(port) {
@@ -24316,9 +24712,11 @@ var Status = class Status extends EnvironmentCommand {
 						url: server.runtime?.server_url
 					}
 				},
-				project,
-				next_actions: nextActions,
-				...nextCommandsData(nextCommands)
+				project
+			},
+			next: {
+				actions: nextActions,
+				commands: nextCommands
 			},
 			footer: exploreAllCommands(this.meta.cliVersion)
 		});
@@ -24433,9 +24831,9 @@ var Stop = class Stop extends BaseCommand {
 					} : { container_name: containerName },
 					data_preserved: true,
 					data_dir: runtime?.data_dir
-				},
-				...nextCommandsData([this.suggestUnscoped("stop")])
-			}
+				}
+			},
+			next: { commands: [this.suggestUnscoped("stop")] }
 		});
 		const { stopped, outcome } = await LocalServer.at(this.meta.cwd, { cliVersion: this.meta.cliVersion }).stop();
 		return this.emit({
@@ -24620,7 +25018,11 @@ var VariableResolve = class VariableResolve extends EnvironmentCommand {
 		await this.toMeta(flags);
 		const { client, projectId } = await this.connect();
 		const origin = flags.origin;
-		const deployments = await listLiveDeployments(client, projectId, origin === void 0 ? {} : { origin });
+		const deployments = await client.listDeployments.all({
+			project_id: projectId,
+			live: true,
+			origin
+		});
 		if (origin === void 0 && deployments.length > 1) {
 			const origins = [...new Set(deployments.flatMap((deployment) => deployment.targets.map((t) => t.origin)))].sort();
 			throw new ZitadelError("E_VALIDATION", "More than one deployment is live; name which origin to resolve with --origin.", {
@@ -24661,7 +25063,7 @@ var VariableResolve = class VariableResolve extends EnvironmentCommand {
 			hint: `Deploy first with \`zitadel ${DEPLOY_ARGS}${this.environmentSelector()}\`, then resolve its variables.`,
 			nextCommands: [this.suggest(DEPLOY_ARGS)]
 		});
-		const origins = (await client.getProject(projectId)).origins ?? [];
+		const origins = (await client.getProject(projectId)).origins;
 		if (origins.some((entry) => entry.kind === "primary" && entry.pattern === origin)) return new ZitadelError("E_NOT_FOUND", `Nothing is deployed to ${origin}.`, {
 			hint: `Deploy to it first with \`zitadel ${DEPLOY_ARGS}${this.environmentSelector()}\`, then resolve its variables.`,
 			nextCommands: [this.suggest(DEPLOY_ARGS)]
@@ -24968,6 +25370,7 @@ const COMMANDS = {
 	"preview:rm": PreviewRm,
 	"release:create": ReleaseCreate,
 	"release:revoke": ReleaseRevoke,
+	"skills:add": SkillsAdd,
 	"variable:set": VariableSet,
 	"variable:get": VariableGet,
 	"variable:list": VariableList,