@zitadel/cli 0.1.0-alpha.8 → 1.0.0-alpha.20

package/dist/commands/setup.mjs

@@ -1,95 +1,181 @@
-import { D as ZitadelError, O as toZitadelError, n as DEFAULT_SERVER, t as BaseCommand, x as publicCliCommand } from "../oclif-VkCTGIEk.mjs";
-import { n as RENDERER_IDS, r as issuerFromPort, t as createOrca } from "../orca-CfKDQRop.mjs";
-import { n as hasZitadelSecret, t as hasZitadelConfig } from "../project-CKAHtHML.mjs";
+import { n as brandingDesignLabel, t as BRANDING_DESIGN_INFO } from "../designs-Ckz18Dpo.mjs";
+import { D as toZitadelError, E as ZitadelError, T as stableStringify, j as publicCliCommand, k as normalizePublicCliProse, n as DEFAULT_SERVER, t as BaseCommand, u as detectHealthyLocalServer } from "../oclif-CanO3zdt.mjs";
+import { n as claimCommand, r as claimState, t as claimAction } from "../claim-state-DlfD6Res.mjs";
+import { n as customizeAndPublishActions, r as verifyLoginAction, t as brandingGuidanceAction } from "../journey-guidance-BGrOX_gT.mjs";
+import { i as RENDERER_IDS, n as inspectScaffoldTarget, r as AVAILABLE_RENDERER_IDS, s as issuerFromPort, t as createOrca } from "../orca-BzQIQqzt.mjs";
+import { n as hasZitadelSecret, t as hasZitadelConfig } from "../project-CHhot85s.mjs";
+import { a as updateState, t as SCHEMAS_DIR } from "../user-schema-DTuOsdKE.mjs";
+import { a as runPackageCommand, c as writeScaffoldManifest, i as installCommandFor, n as detectPackageManager, r as devCommandFor } from "../package-manager-DFdLcDx1.mjs";
+import { i as toBrandingWireBody, t as BRANDING_DIR } from "../branding-cygSBPkV.mjs";
+import { c as writeBackResource, o as hashForState, u as FLOWS_DIR } from "../sync-BBlACKzT.mjs";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import { cancel, confirm, intro, isCancel, outro, select, spinner, text } from "@clack/prompts";
 import { Flags } from "@oclif/core";
 import { createZitadelClient } from "@zitadel/api/client";
+import { BRANDING_DESIGNS, DEFAULT_BRANDING_CONFIG_PATH, 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, schemasReadmeContent } from "@zitadel/config/defaults";
 import { consola as consola$1 } from "consola";
-import { basename, join } from "node:path";
-import { readFile, stat } from "node:fs/promises";
-import { execFile, spawn } from "node:child_process";
+import { BRANDING_FILE_SCHEMA_REF } from "@zitadel/config/meta-schemas";
+import { normalizeFlowBody, normalizeSchemaBody } from "@zitadel/config/normalize";
 import pc from "picocolors";
-//#region src/lib/package-manager.ts
-async function detectPackageManager(cwd) {
-	const declared = await packageManagerFromManifest(cwd);
-	if (declared) return declared;
-	if (await exists(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-	if (await exists(join(cwd, "yarn.lock"))) return "yarn";
-	if (await exists(join(cwd, "bun.lock"))) return "bun";
-	if (await exists(join(cwd, "bun.lockb"))) return "bun";
-	if (await exists(join(cwd, "package-lock.json"))) return "npm";
-	return "npm";
-}
-function installCommandFor(packageManager) {
-	return command(packageManager, ["install"]);
-}
-function devCommandFor(packageManager) {
-	switch (packageManager) {
-		case "npm": return command("npm", ["run", "dev"]);
-		case "pnpm": return command("pnpm", ["dev"]);
-		case "yarn": return command("yarn", ["dev"]);
-		case "bun": return command("bun", ["run", "dev"]);
-	}
+//#region src/lib/orca/patchers/posture.ts
+/**
+* Frameworks whose patchers add route files without owning the app shell —
+* the only ones where a pre-existing app keeps a layout for the widget
+* posture to inherit (ADR 044). The SPA families write the app's root
+* component, so nothing survives for a widget to embed into; they keep the
+* page posture until a non-destructive route/layout insertion contract
+* exists for their routers.
+*/
+const ROUTE_BASED_FRAMEWORKS = new Set(["next", "nuxt"]);
+/**
+* The default embedding posture of the scaffolded auth/profile pages
+* (ADR 044), derived from the same hinge as the framework homepage: whether
+* setup created the app skeleton itself. A fresh scaffold has no design to
+* respect — full-page chrome is the strongest start. A pre-existing
+* route-based app has its own shell and theme, so the pages embed
+* `variant="widget"` cards in a layout-neutral wrapper instead of painting
+* token-colored chrome underneath the host layout.
+*
+* Derived once at setup time and recorded in the scaffold manifest;
+* `doctor --fix` restores from the record rather than re-deriving (a
+* manifest-less legacy scaffold could not answer the hinge).
+*/
+function derivePosture(frameworkId, scaffoldedFramework) {
+	if (!ROUTE_BASED_FRAMEWORKS.has(frameworkId)) return "page";
+	return scaffoldedFramework ? "page" : "widget";
 }
-async function runPackageCommand(packageCommand, options) {
-	await new Promise((resolve, reject) => {
-		const child = spawn(packageCommand.command, packageCommand.args, {
-			cwd: options.cwd,
-			env: options.env ?? process.env,
-			stdio: options.redirectStdoutToStderr ? [
-				"ignore",
-				"pipe",
-				"pipe"
-			] : "inherit"
-		});
-		if (options.redirectStdoutToStderr) {
-			child.stdout?.on("data", (chunk) => process.stderr.write(chunk));
-			child.stderr?.on("data", (chunk) => process.stderr.write(chunk));
-		}
-		child.on("error", reject);
-		child.on("close", (code, signal) => {
-			if (code === 0) {
-				resolve();
-				return;
-			}
-			const detail = signal ? `signal ${signal}` : `exit ${String(code ?? 1)}`;
-			const error = /* @__PURE__ */ new Error(`${packageCommand.display} failed with ${detail}`);
-			Object.assign(error, {
-				code: code ?? 1,
-				signal
-			});
-			reject(error);
-		});
+//#endregion
+//#region src/lib/setup-resources.ts
+/**
+* Scaffolds the versioned local default resources for a new project, uploads
+* them through the schema/flow APIs, and seeds `.zitadel/state.json` with the
+* IDs, hashes, and flow metadata the sync engine expects. Setup calls this only
+* after the framework patcher has created `.zitadel/{flows,schemas}` and the
+* initial state file.
+*
+* The schema is uploaded without an `$id`: the server assigns an opaque id on
+* `POST /schemas`, and the flow file can only be rendered after that id comes
+* back because `flow_definition.user_schema` must reference it.
+*/
+async function materializeSetupResources(opts) {
+	await mkdir(join(opts.cwd, FLOWS_DIR), { recursive: true });
+	await mkdir(join(opts.cwd, SCHEMAS_DIR), { recursive: true });
+	const filesWritten = [];
+	const preset = opts.preset ?? DEFAULT_SETUP_PRESET;
+	const useCase = opts.useCase ?? DEFAULT_SETUP_USE_CASE;
+	const { $id: _templateId, ...schemaBody } = getDefaultHumanUserSchema({
+		preset,
+		useCase
 	});
+	if (await writeResourceFile(opts.cwd, DEFAULT_SCHEMA_CONFIG_PATH, schemaBody, opts.force)) filesWritten.push(join(opts.cwd, DEFAULT_SCHEMA_CONFIG_PATH));
+	const schemaId = requiredString((await opts.client.createSchema(schemaBody, { project_id: opts.projectId })).id, "created schema id");
+	let schemaHash = hashForState({ normalize: normalizeSchemaBody }, schemaBody);
+	try {
+		const canonical = (await opts.client.getSchemaById(encodeURIComponent(schemaId))).schema;
+		schemaHash = (await writeBackResource(opts.cwd, DEFAULT_SCHEMA_CONFIG_PATH, { normalize: normalizeSchemaBody }, canonical)).hash;
+	} catch (err) {
+		consola$1.debug(`fetch created schema ${schemaId} during setup failed:`, err);
+	}
+	await updateState(opts.cwd, DEFAULT_SCHEMA_CONFIG_PATH, {
+		id: schemaId,
+		hash: schemaHash
+	});
+	const flowBody = getDefaultLoginFlow({
+		userSchemaUrl: schemaId,
+		preset,
+		useCase
+	});
+	if (await writeResourceFile(opts.cwd, DEFAULT_FLOW_CONFIG_PATH, flowBody, opts.force)) filesWritten.push(join(opts.cwd, DEFAULT_FLOW_CONFIG_PATH));
+	const flow = await opts.client.createFlowDefinition({
+		project_id: opts.projectId,
+		schema_uri: DEFAULT_FLOW_SCHEMA_URI,
+		flow_definition: flowBody
+	});
+	let flowHash = hashForState({ normalize: normalizeFlowBody }, flowBody);
+	if (flow.flow_definition) flowHash = (await writeBackResource(opts.cwd, DEFAULT_FLOW_CONFIG_PATH, {
+		normalize: normalizeFlowBody,
+		normalizeWrite: normalizeFlowBody
+	}, flow.flow_definition)).hash;
+	await updateState(opts.cwd, DEFAULT_FLOW_CONFIG_PATH, {
+		id: requiredString(flow.id, "created flow definition id"),
+		hash: flowHash,
+		name: flowBody.name,
+		status: flowBody.status
+	});
+	if (opts.design) {
+		await mkdir(join(opts.cwd, BRANDING_DIR), { recursive: true });
+		const { branding, template } = getDefaultBrandingConfig(opts.design);
+		const descriptor = {
+			$schema: BRANDING_FILE_SCHEMA_REF,
+			...branding
+		};
+		if (await writeResourceFile(opts.cwd, DEFAULT_BRANDING_CONFIG_PATH, descriptor, opts.force)) filesWritten.push(join(opts.cwd, DEFAULT_BRANDING_CONFIG_PATH));
+		if (await writeRawFile(opts.cwd, DEFAULT_BRANDING_TEMPLATE_PATH, template, opts.force)) filesWritten.push(join(opts.cwd, DEFAULT_BRANDING_TEMPLATE_PATH));
+		const brandingNormalize = (data) => toBrandingWireBody(opts.cwd, data);
+		const created = await opts.client.createBranding(brandingNormalize(descriptor), { project_id: opts.projectId });
+		await updateState(opts.cwd, DEFAULT_BRANDING_CONFIG_PATH, {
+			id: requiredString(created.id, "created branding revision id"),
+			hash: hashForState({ normalize: brandingNormalize }, descriptor)
+		});
+		const brandingReadme = join(BRANDING_DIR, "README.md");
+		if (await writeReadmeFile(opts.cwd, brandingReadme, normalizePublicCliProse(brandingReadmeContent(), opts.cliVersion))) filesWritten.push(join(opts.cwd, brandingReadme));
+	}
+	const schemasReadme = join(SCHEMAS_DIR, "README.md");
+	const flowsReadme = join(FLOWS_DIR, "README.md");
+	if (await writeReadmeFile(opts.cwd, schemasReadme, normalizePublicCliProse(schemasReadmeContent(), opts.cliVersion))) filesWritten.push(join(opts.cwd, schemasReadme));
+	if (await writeReadmeFile(opts.cwd, flowsReadme, normalizePublicCliProse(flowsReadmeContent(), opts.cliVersion))) filesWritten.push(join(opts.cwd, flowsReadme));
+	return { filesWritten };
 }
-function command(packageManager, args) {
-	return {
-		command: packageManager,
-		args,
-		display: [packageManager, ...args].join(" ")
-	};
-}
-async function packageManagerFromManifest(cwd) {
+/**
+* Write a non-JSON scaffold file (the `.liquid` template) with the same
+* conflict semantics as {@link writeResourceFile}: `--force` overwrites,
+* otherwise an existing file is an `E_CONFLICT`.
+*/
+async function writeRawFile(cwd, relPath, content, force) {
+	const dest = join(cwd, relPath);
+	await mkdir(dirname(dest), { recursive: true });
 	try {
-		const raw = await readFile(join(cwd, "package.json"), "utf8");
-		const parsed = JSON.parse(raw);
-		return typeof parsed.packageManager === "string" ? packageManagerFromString(parsed.packageManager) : void 0;
-	} catch {
-		return;
+		await writeFile(dest, content, force ? void 0 : { flag: "wx" });
+		return true;
+	} catch (error) {
+		if (isErrno(error, "EEXIST")) throw new ZitadelError("E_CONFLICT", `${relPath} already exists`, { hint: "Move the file aside or rerun setup with --force if you want setup to replace it." });
+		throw error;
 	}
 }
-function packageManagerFromString(value) {
-	const name = value.split("@")[0];
-	return name === "npm" || name === "pnpm" || name === "yarn" || name === "bun" ? name : void 0;
+/**
+* Write a README file, but never overwrite an existing one. A developer who
+* has edited the README should keep their edits when `setup --force` is
+* re-run.
+*/
+async function writeReadmeFile(cwd, relPath, content) {
+	const dest = join(cwd, relPath);
+	await mkdir(dirname(dest), { recursive: true });
+	try {
+		await writeFile(dest, content, { flag: "wx" });
+		return true;
+	} catch (error) {
+		if (isErrno(error, "EEXIST")) return false;
+		throw error;
+	}
 }
-async function exists(path) {
+async function writeResourceFile(cwd, relPath, body, force) {
+	const contents = `${stableStringify(body)}\n`;
 	try {
-		await stat(path);
+		await writeFile(join(cwd, relPath), contents, force ? void 0 : { flag: "wx" });
 		return true;
-	} catch {
-		return false;
+	} catch (error) {
+		if (isErrno(error, "EEXIST")) throw new ZitadelError("E_CONFLICT", `${relPath} already exists`, { hint: "Move the file aside or rerun setup with --force if you want setup to replace it." });
+		throw error;
 	}
 }
+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;
+}
 //#endregion
 //#region src/commands/setup/install.ts
 async function installDependenciesForSetup(input) {
@@ -104,6 +190,7 @@ async function installDependenciesForSetup(input) {
 			reason: "no-dependency-changes"
 		},
 		devCommand: devCommand.display,
+		cliVersion: input.cliVersion,
 		issuer: input.issuer,
 		includeInstallCommand: false
 	});
@@ -115,6 +202,7 @@ async function installDependenciesForSetup(input) {
 			reason: input.dryRun ? "dry-run" : "skip-install"
 		},
 		devCommand: devCommand.display,
+		cliVersion: input.cliVersion,
 		issuer: input.issuer,
 		includeInstallCommand: true
 	});
@@ -136,22 +224,30 @@ async function installDependenciesForSetup(input) {
 			command: installCommand.display
 		},
 		devCommand: devCommand.display,
+		cliVersion: input.cliVersion,
 		issuer: input.issuer,
 		includeInstallCommand: false
 	});
 }
 function outcome(input) {
-	const startAction = `Start your project: ${input.devCommand} (then open ${input.issuer})`;
-	const verifyAction = "Verify auth in the browser: register a user, log out, log in again with the same user, and confirm /profile shows Signed in.";
+	const planCommand = publicCliCommand("plan", input.cliVersion);
+	const statusCommand = publicCliCommand("status", input.cliVersion);
+	const verifyActions = [
+		...input.includeInstallCommand ? [`Install dependencies: ${input.install.command}`] : [],
+		`Start your project: ${input.devCommand} (then open ${input.issuer}/login)`,
+		verifyLoginAction()
+	];
+	const breadcrumb = `Once login works: ${statusCommand} shows your next steps; customizing is covered in your README's Zitadel section.`;
 	return {
 		install: input.install,
 		devCommand: input.devCommand,
-		nextActions: input.includeInstallCommand ? [
-			`Install dependencies: ${input.install.command}`,
-			startAction,
-			verifyAction
-		] : [startAction, verifyAction],
-		nextCommands: input.includeInstallCommand ? [input.install.command, input.devCommand] : [input.devCommand]
+		boxActions: [...verifyActions, breadcrumb],
+		nextActions: [...verifyActions, ...customizeAndPublishActions(input.cliVersion)],
+		nextCommands: input.includeInstallCommand ? [
+			input.install.command,
+			input.devCommand,
+			planCommand
+		] : [input.devCommand, planCommand]
 	};
 }
 function installFailed(error, installCommand, devCommand, cwd) {
@@ -187,6 +283,54 @@ function bail(value) {
 	}
 }
 //#endregion
+//#region src/commands/setup/prompts/design.ts
+/**
+* Sentinel select value for "keep the built-in login" — clack option values
+* must be strings, and `undefined` in {@link SetupAnswers.design} is the
+* real representation of that choice.
+*/
+const BUILT_IN = "built-in";
+/**
+* "How should the login look?" — the last wizard question (#676). Asks after
+* the sign-in preset so the order tells a story: the use case owns what is
+* collected, the preset owns how users authenticate, the design owns how
+* that experience looks.
+*
+* The built-in default is preselected and writes nothing. Picking a starter
+* design forks its Liquid template into `.zitadel/branding/` and publishes
+* it as branding revision 1 — from then on the template is repo-owned and
+* stops tracking built-in improvements, so the option labels make the
+* file-write explicit and keep ownership an opt-in. `--design` is
+* authoritative; non-interactive runs keep the built-in template.
+*/
+var DesignPrompt = class {
+	async ask(answers, ctx) {
+		if (ctx.designFromFlag) return answers;
+		const value = await select({
+			message: "How should the login look? A starter design adds its editable template to .zitadel/branding/.",
+			initialValue: answers.design ?? BUILT_IN,
+			options: [{
+				value: BUILT_IN,
+				label: "Built-in",
+				hint: "no files added; pick a design anytime later with `branding eject`"
+			}, ...BRANDING_DESIGNS.map((design) => ({
+				value: design,
+				label: BRANDING_DESIGN_INFO[design].label,
+				hint: BRANDING_DESIGN_INFO[design].hint
+			}))]
+		});
+		bail(value);
+		if (value === BUILT_IN) return {
+			...answers,
+			design: void 0
+		};
+		return {
+			...answers,
+			design: value
+		};
+	}
+};
+//#endregion
 //#region src/commands/setup/prompts/dev-port.ts
 /**
 * "Dev server port" — defaults to the detected port. The validated answer
@@ -230,137 +374,27 @@ var FrameworkConfirmPrompt = class {
 	}
 };
 //#endregion
-//#region src/lib/prober/ports.ts
-/**
-* Enumerate TCP ports currently in LISTEN state on the loopback interface
-* (`127.0.0.1`, `::1`, or the wildcard `*`). Spawns `lsof -iTCP -sTCP:LISTEN
-* -P -n -F n` and parses its machine-readable output. Returns the unique,
-* numerically-sorted list of ports.
-*
-* Never throws. Returns `[]` whenever lsof is unavailable (e.g. Windows,
-* unusual PATH), the spawn errors, exits non-zero, or the call exceeds
-* `timeoutMs` (default 1000ms). The caller treats an empty list the same as
-* "no listeners worth probing."
-*/
-async function listListeningPorts(opts) {
-	const timeoutMs = opts?.timeoutMs ?? 1e3;
-	try {
-		return parseLsofPorts(await runLsof(timeoutMs));
-	} catch {
-		return [];
-	}
-}
-/**
-* Spawn `lsof` with the canned argv and resolve to its stdout. Hand-rolled
-* rather than `util.promisify(execFile)` because the latter resolves with a
-* `{stdout, stderr}` object via its custom-promisify symbol — a heavier shape
-* to mock and worse to read at the call site, where we only ever want stdout.
-*/
-function runLsof(timeoutMs) {
-	return new Promise((resolve, reject) => {
-		execFile("lsof", [
-			"-iTCP",
-			"-sTCP:LISTEN",
-			"-P",
-			"-n",
-			"-F",
-			"n"
-		], {
-			timeout: timeoutMs,
-			encoding: "utf8"
-		}, (err, stdout) => {
-			if (err) {
-				reject(err);
-				return;
-			}
-			resolve(stdout);
-		});
-	});
-}
-/**
-* Parse the `n` records emitted by `lsof -F n`. Each record is a single line
-* `n<address>` where `<address>` ends in `:<port>` (e.g. `n*:8080`,
-* `n127.0.0.1:3000`, `n[::1]:5050`). Only loopback/wildcard hosts are kept;
-* external interface bindings are ignored.
-*/
-function parseLsofPorts(stdout) {
-	const ports = /* @__PURE__ */ new Set();
-	for (const line of stdout.split(/\r?\n/)) {
-		if (!line.startsWith("n")) continue;
-		const address = line.slice(1);
-		const colon = address.lastIndexOf(":");
-		if (colon < 0) continue;
-		const host = address.slice(0, colon);
-		const portStr = address.slice(colon + 1);
-		if (!isLoopback(host)) continue;
-		const port = Number.parseInt(portStr, 10);
-		if (Number.isFinite(port) && port > 0 && port < 65536) ports.add(port);
-	}
-	return [...ports].sort((a, b) => a - b);
-}
-/** Recognised loopback host strings as emitted by `lsof -F n`. */
-function isLoopback(host) {
-	return host === "*" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
-}
-//#endregion
-//#region src/lib/prober/http.ts
-/**
-* Fetch `url` with a per-call timeout and pass the resulting `Response` to
-* `predicate`. Returns the predicate's value, or `null` on any failure: a
-* network error, an `AbortError` from the timeout, a thrown predicate, or the
-* predicate returning `null`.
-*
-* Never throws. The predicate decides what counts as a match — it gets the
-* raw `Response` and may read `.json()` / `.headers` / `.status` as needed.
-*
-* `timeoutMs` defaults to 500ms. The implementation uses
-* `AbortSignal.timeout`, so the underlying fetch is cancelled when the
-* timeout fires (no orphaned sockets).
-*/
-async function probeUrl(url, predicate, opts) {
-	const timeoutMs = opts?.timeoutMs ?? 500;
-	try {
-		return await predicate(await fetch(url, { signal: AbortSignal.timeout(timeoutMs) }));
-	} catch {
-		return null;
-	}
-}
-/**
-* Probe many URLs in parallel and return the non-null matches, preserving
-* the input order. Each URL is bounded by `timeoutMs` independently — one
-* slow target can't hold up the others.
-*/
-async function probeUrls(urls, predicate, opts) {
-	const list = [...urls];
-	return (await Promise.all(list.map(async (url) => {
-		const value = await probeUrl(url, predicate, opts);
-		return value === null ? null : {
-			url,
-			value
-		};
-	}))).filter((match) => match !== null);
-}
-//#endregion
 //#region src/commands/setup/prompts/server.ts
 /** Sentinel returned by the choice select when the user picks "Custom URL". */
 const CUSTOM = "__custom__";
-/** Per-probe timeout for the localhost OIDC scan — generous enough for a TLS handshake on a busy laptop. */
-const OIDC_PROBE_TIMEOUT_MS = 300;
 /**
-* "Which server should `zitadel.json` point to?" — Zitadel Cloud, a localhost
-* OIDC server we discovered, or a custom URL.
+* "Which server should `zitadel.json` point to?" — Zitadel Cloud, the managed
+* local server we detected, or a custom URL.
 *
-* Before asking, it scans the loopback for listening ports (via the generic
-* `lib/prober`) and `GET`s `/.well-known/openid-configuration` on each. Every
-* 2xx response with a string `issuer` becomes an extra option in the choice
-* list. Picking a discovered URL writes it directly to `answers.server` and
-* skips the follow-up text prompt. Picking "Custom URL" still asks for a
+* Before asking, it looks for a healthy local Zitadel server the same way the
+* rest of the CLI does (`detectHealthyLocalServer`: the runtime metadata that
+* `zitadel start` wrote to `.zitadel/local/runtime.json`, falling back to a
+* `/healthz` probe on the default localhost port). A detected server becomes
+* an extra option in the choice list *and* the preselected answer — a user
+* who just ran `zitadel start` almost certainly wants it, and `start`'s own
+* next-step hint says `setup --server local`. Picking it writes the URL
+* directly to `answers.server`; picking "Custom URL" still asks for a
 * validated URL exactly as before.
 */
 var ServerPrompt = class {
 	async ask(answers, ctx) {
 		if (ctx.serverFlag) return answers;
-		const discovered = await discoverLocalOidc();
+		const detected = await detectLocalServer(ctx.cwd);
 		const choice = await select({
 			message: "Which server should zitadel.json point to?",
 			options: [
@@ -369,17 +403,17 @@ var ServerPrompt = class {
 					label: "Zitadel Cloud (api.zitadel.cloud)",
 					hint: "recommended for real projects"
 				},
-				...discovered.map((server) => ({
-					value: server,
-					label: server,
-					hint: "detected — OIDC"
-				})),
+				...detected ? [{
+					value: detected,
+					label: `Local Zitadel server (${detected})`,
+					hint: "detected — started with zitadel start"
+				}] : [],
 				{
 					value: CUSTOM,
 					label: "Custom URL (self-hosted)"
 				}
 			],
-			initialValue: answers.server ?? "https://api.zitadel.cloud"
+			initialValue: detected ?? answers.server ?? "https://api.zitadel.cloud"
 		});
 		bail(choice);
 		if (choice !== CUSTOM) return {
@@ -406,38 +440,89 @@ var ServerPrompt = class {
 	}
 };
 /**
-* Returns the loopback origins (`http://localhost:<port>`) whose
-* `/.well-known/openid-configuration` endpoint responds with a valid OIDC
-* discovery document. Sniffs purely via the generic prober — the only
-* Zitadel-shaped detail here is the OIDC predicate, which is the standard
-* "any OIDC server" contract (no `zitadel`-keyword check), so Keycloak/dex/
-* etc. also surface and the user picks the right one.
+* Wraps {@link detectHealthyLocalServer} in a spinner: the unhealthy paths
+* block on up to two 1.5s `/healthz` probes, long enough that the wizard
+* should say what it is doing.
 */
-async function discoverLocalOidc() {
+async function detectLocalServer(cwd) {
 	const s = spinner();
-	s.start("Scanning localhost for OIDC servers");
-	try {
-		const ports = await listListeningPorts();
-		if (ports.length === 0) {
-			s.stop("No local servers detected.");
-			return [];
-		}
-		const origins = (await probeUrls(ports.map((port) => `http://localhost:${port}/.well-known/openid-configuration`), async (response) => {
-			if (!response.ok) return null;
-			try {
-				const body = await response.json();
-				return typeof body.issuer === "string" ? body.issuer : null;
-			} catch {
-				return null;
+	s.start("Checking for a local Zitadel server");
+	const detected = await detectHealthyLocalServer(cwd);
+	s.stop(detected ? `Found local Zitadel server at ${detected}.` : "No local Zitadel server detected.");
+	return detected;
+}
+//#endregion
+//#region src/commands/setup/prompts/sign-in-preset.ts
+/**
+* "How should users sign in?" — picks the schema+flow preset the scaffold
+* starts from (#448: app-type/preset selection before any `.zitadel/` file
+* is written). `--preset` is authoritative; non-interactive runs keep the
+* password-first default seeded by the command.
+*/
+var SignInPresetPrompt = class {
+	async ask(answers, ctx) {
+		if (ctx.presetFromFlag) return answers;
+		const labels = {
+			"password-first": "Password first — email + password, passkey optional during registration",
+			"passkey-first": "Passkey first — one-tap passkey up front, email + password fallback"
+		};
+		const value = await select({
+			message: "How should users sign in?",
+			initialValue: answers.preset,
+			options: SETUP_PRESETS.map((preset) => ({
+				value: preset,
+				label: labels[preset]
+			}))
+		});
+		bail(value);
+		return {
+			...answers,
+			preset: value
+		};
+	}
+};
+//#endregion
+//#region src/commands/setup/prompts/use-case.ts
+/**
+* "Who will sign in to your app?" — picks the use case, which owns the
+* schema field set the scaffold collects (#448). Orthogonal to the sign-in
+* preset, so this asks first: what a user *is* before *how* they sign in.
+* `--use-case` is authoritative; non-interactive runs keep the minimal
+* default seeded by the command.
+*/
+var UseCasePrompt = class {
+	async ask(answers, ctx) {
+		if (ctx.useCaseFromFlag) return answers;
+		const options = {
+			minimal: {
+				label: "Just me or a small group",
+				hint: "collects email"
+			},
+			consumer: {
+				label: "Consumers",
+				hint: "collects email, given & family name"
+			},
+			business: {
+				label: "Business",
+				hint: "collects email, given & family name, company"
 			}
-		}, { timeoutMs: OIDC_PROBE_TIMEOUT_MS })).map((match) => new URL(match.url).origin);
-		s.stop(origins.length === 0 ? "No local OIDC servers found." : `Found ${origins.length} local OIDC server${origins.length === 1 ? "" : "s"}.`);
-		return origins;
-	} catch (error) {
-		s.stop("Discovery skipped.");
-		throw error;
+		};
+		const value = await select({
+			message: "Who will sign in to your app? Collected fields stay editable after setup.",
+			initialValue: answers.useCase,
+			options: SETUP_USE_CASES.map((useCase) => ({
+				value: useCase,
+				label: options[useCase].label,
+				hint: options[useCase].hint
+			}))
+		});
+		bail(value);
+		return {
+			...answers,
+			useCase: value
+		};
 	}
-}
+};
 //#endregion
 //#region src/commands/setup/prompts/pick-framework.ts
 /**
@@ -477,11 +562,24 @@ var PickFrameworkPrompt = class {
 const SETUP_PROMPTS = [
 	new FrameworkConfirmPrompt(),
 	new ServerPrompt(),
-	new DevPortPrompt()
+	new DevPortPrompt(),
+	new UseCasePrompt(),
+	new SignInPresetPrompt(),
+	new DesignPrompt()
 ];
 //#endregion
 //#region src/commands/setup/summary.ts
 /**
+* Renders a path under `cwd` with stable POSIX separators. Setup's summary
+* matches generated artifacts against repository-style suffixes such as
+* `.zitadel/schemas/default-human-user.json`; normalizing here keeps those
+* matches working when Node returns Windows paths with backslashes.
+*/
+function relativeDisplayPath(cwd, absolute) {
+	const boundary = absolute[cwd.length];
+	return (absolute.startsWith(cwd) && (boundary === "/" || boundary === "\\") ? absolute.slice(cwd.length + 1) : absolute).replaceAll("\\", "/");
+}
+/**
 * Renders the section list as a single multi-line string. Labels are
 * padded to a common width per section so the `✓ label  value` columns
 * line up, the title prints in dim gray, and `✓` is green. Values come
@@ -510,6 +608,8 @@ const path = (s) => pc.cyan(s);
 const url = (s) => pc.cyan(s);
 /** Yellow, for opaque ids the user shouldn't try to read. */
 const id = (s) => pc.yellow(s);
+/** Dim, for separators and secondary detail. */
+const dim = (s) => pc.dim(s);
 /**
 * Reads the project root to identify the framework version, TS presence,
 * and which package manager the user runs. Returns safe defaults (npm
@@ -570,6 +670,29 @@ function stripRange(range) {
 function fileNameOf(p) {
 	return basename(p);
 }
+/**
+* Layout caveats for the chosen login design, shown to humans after the
+* summary box and carried in the JSON envelope's `warnings`.
+*
+* The split family's brand pane is keyed to the **login's own container**
+* width — a `@container (max-width: 48rem)` query on the widget's mount, not
+* a viewport media query. Above that the pane renders; below it the pane is
+* `display: none` and the compact brand mark takes its place — and the split
+* template only emits that mark when `branding.json` names `logo_url` or
+* `hero_url`, so without one the narrow layout loses the branding entirely.
+*
+* Independent of posture, because the container query is: a full-page login
+* hits the same collapse on a phone that an embedded card hits in a sidebar.
+* Gating on `widget` would have been a guess about the container, and a wrong
+* one in both directions — the wrapper setup scaffolds for a widget is
+* full-width (the pane renders there), and a page-posture login on a phone is
+* exactly the narrow case the advice is for. `hero` stays quiet: its compact
+* fallback is editable text, so a narrow container never leaves it blank.
+*/
+function designWarnings(design) {
+	if (design !== "split" && design !== "split-right") return [];
+	return [`The ${design} design shows its brand pane only when the login's container is wide; a narrow container — a card-width embed, or any phone-width viewport — collapses it to the compact brand mark. Set logo_url (or hero_url) in .zitadel/branding/branding.json so that mark isn't empty.`];
+}
 //#endregion
 //#region src/commands/setup/index.ts
 /**
@@ -579,13 +702,23 @@ function fileNameOf(p) {
 * load.
 */
 const FRAMEWORK_OPTIONS = createOrca().availableFrameworks().map((framework) => framework.id);
+/**
+* `--renderer` offers only ids `getRenderer` will resolve: a
+* declared-but-unpublished renderer (ADR 006) keeps its registry entry to
+* reserve the id, but is surfaced as unavailable in the flag description
+* instead of in `options`, so `--help` never advertises a value that is
+* guaranteed to fail and an explicit pass is rejected at parse time — before
+* any remote project is created.
+*/
+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(", ")}.`;
 /** `zitadel setup` — create a project and scaffold local auth.
 *
 * Detects (or, for an empty directory, scaffolds then re-detects) the
 * framework, runs the wizard prompts to fill in any answers not pre-supplied
-* by flags, creates the remote project (whose default user schema and login
-* flow are provisioned server-side), and patches the local files via
-* `Orca`'s framework patcher.
+* by flags, creates the remote project without server fallback defaults,
+* patches the local files via `Orca`'s framework patcher, then scaffolds and
+* uploads editable schema/flow config from `.zitadel/**`.
 *
 * Every interactive question lives in {@link SETUP_PROMPTS} (the main wizard
 * — each entry is a small class) and {@link PickFrameworkPrompt} (the
@@ -600,18 +733,30 @@ var Setup = class Setup extends BaseCommand {
 			options: FRAMEWORK_OPTIONS
 		}),
 		renderer: Flags.string({
-			description: "Renderer (default: react).",
-			options: [...RENDERER_IDS]
+			description: RENDERER_FLAG_DESCRIPTION,
+			options: [...AVAILABLE_RENDERER_IDS]
 		}),
 		"dev-port": Flags.integer({ description: "Dev-server port; also the issuer origin registered with Zitadel. Defaults to the detected port. Use distinct ports to run several scaffolded apps side by side." }),
-		"skip-install": Flags.boolean({ description: "Do not install dependencies after setup updates package.json." })
+		"skip-install": Flags.boolean({ description: "Do not install dependencies after setup updates package.json." }),
+		preset: Flags.string({
+			description: "Sign-in preset for the scaffolded schema and login flow (default: password-first).",
+			options: [...SETUP_PRESETS]
+		}),
+		"use-case": Flags.string({
+			description: "Use case for the scaffolded schema fields: who signs in to the app (default: minimal).",
+			options: [...SETUP_USE_CASES]
+		}),
+		design: Flags.string({
+			description: "Login design to eject into .zitadel/branding/ and publish as branding revision 1. Skips the wizard's design question. When omitted in non-interactive runs, the login uses the built-in template; run the `branding eject` command later to customize. Split-family designs (split, split-right, hero) collapse their brand pane by container width: narrow containers — including widget-posture embeds at card width — render the compact brand mark instead (logo_url, else hero_url, from .zitadel/branding/branding.json; hero falls back to editable text).",
+			options: [...BRANDING_DESIGNS]
+		})
 	};
 	async run() {
 		const { flags } = await this.parse(Setup);
 		try {
 			await this.toMeta(flags);
 		} catch (error) {
-			throw localSetupHint(error, flags.framework, this.config.version);
+			throw localSetupHint(error, retryOptionsFromFlags(flags), this.config.version);
 		}
 		const { cwd, nonInteractive, dryRun, force } = this.meta;
 		if (await hasZitadelConfig(cwd)) return this.emit({
@@ -627,13 +772,26 @@ var Setup = class Setup extends BaseCommand {
 			framework = await orca.detect(cwd, flags.framework);
 			consola$1.success(`Detected ${framework.id}${framework.devPort ? ` (dev port ${framework.devPort})` : ""}`);
 		} catch (error) {
-			if (error instanceof ZitadelError && error.code === "E_FRAMEWORK_NOT_DETECTED" && await orca.isFreshScaffoldTarget(cwd)) {
+			if (error instanceof ZitadelError && error.code === "E_FRAMEWORK_NOT_DETECTED") {
+				const target = await inspectScaffoldTarget(cwd);
+				if (!target.scaffoldable) throw frameworkDetectionWithScaffoldTarget(error, cwd, target);
 				consola$1.info("Fresh app directory — scaffolding a fresh project");
 				framework = await orca.scaffold(cwd, await resolveScaffoldFramework(flags.framework, nonInteractive, orca));
 				scaffoldedFramework = true;
 				consola$1.success(`Scaffolded ${framework.id} skeleton`);
 			} else throw error;
 		}
+		this.recordTelemetry({
+			framework: framework.id,
+			renderer: flags.renderer ?? "react",
+			scaffolded_skeleton: scaffoldedFramework,
+			skip_install: Boolean(flags["skip-install"]),
+			dev_port_explicit: flags["dev-port"] !== void 0,
+			preset: flags.preset ?? DEFAULT_SETUP_PRESET,
+			use_case: flags["use-case"] ?? DEFAULT_SETUP_USE_CASE,
+			design: flags.design ?? "built-in",
+			step: "framework_resolved"
+		});
 		if (flags["dev-port"] !== void 0) {
 			const devPort = flags["dev-port"];
 			if (!Number.isInteger(devPort) || devPort < 1 || devPort > 65535) throw new ZitadelError("E_VALIDATION", `--dev-port must be an integer in 1..65535, got ${devPort}`);
@@ -645,18 +803,30 @@ var Setup = class Setup extends BaseCommand {
 		}
 		let answers = {
 			server: this.meta.source,
-			devPort: framework.devPort
+			devPort: framework.devPort,
+			preset: flags.preset ?? DEFAULT_SETUP_PRESET,
+			useCase: flags["use-case"] ?? DEFAULT_SETUP_USE_CASE,
+			design: flags.design
 		};
 		if (!nonInteractive && !dryRun) {
 			intro("Zitadel setup");
 			const promptCtx = {
 				framework,
+				cwd,
 				serverFlag: this.meta.serverFlag,
-				devPortFromFlag: flags["dev-port"] !== void 0
+				devPortFromFlag: flags["dev-port"] !== void 0,
+				presetFromFlag: flags.preset !== void 0,
+				useCaseFromFlag: flags["use-case"] !== void 0,
+				designFromFlag: flags.design !== void 0
 			};
 			for (const prompt of SETUP_PROMPTS) answers = await prompt.ask(answers, promptCtx);
 			outro("Configuration captured");
 		}
+		this.recordTelemetry({
+			preset: answers.preset,
+			use_case: answers.useCase,
+			design: answers.design ?? "built-in"
+		});
 		const issuer = issuerFromPort(answers.devPort);
 		framework = {
 			...framework,
@@ -665,8 +835,18 @@ var Setup = class Setup extends BaseCommand {
 		};
 		consola$1.start(`Creating project on ${answers.server}${dryRun ? " (dry run)" : ""}`);
 		const unauthClient = createZitadelClient({ baseUrl: answers.server });
-		const project = dryRun ? dryRunProject(issuer) : await createProjectWithLocalHint(unauthClient, answers.server, this.meta.cliVersion, issuer, framework.id);
+		const projectName = defaultProjectName(cwd, framework.id);
+		const project = dryRun ? dryRunProject(issuer) : await createProjectWithLocalHint(unauthClient, answers.server, this.meta.cliVersion, projectName, issuer, {
+			...retryOptionsFromFlags(flags),
+			framework: framework.id,
+			preset: answers.preset,
+			useCase: answers.useCase,
+			design: answers.design,
+			devPort: answers.devPort
+		});
 		consola$1.success(`Created project ${project.id}`);
+		this.recordTelemetry({ step: "project_created" });
+		const posture = derivePosture(framework.id, scaffoldedFramework);
 		const ctx = {
 			framework,
 			rendererId: flags.renderer ?? "react",
@@ -674,7 +854,10 @@ var Setup = class Setup extends BaseCommand {
 			issuer,
 			server: answers.server,
 			cliVersion: this.meta.cliVersion,
-			scaffoldedFramework
+			scaffoldedFramework,
+			posture,
+			preset: answers.preset,
+			useCase: answers.useCase
 		};
 		consola$1.start(`Patching project files${dryRun ? " (dry run)" : ""}`);
 		const result = await orca.patcherFor(framework.id).patch(ctx, {
@@ -683,12 +866,62 @@ var Setup = class Setup extends BaseCommand {
 			force
 		});
 		for (const file of result.filesWritten) {
-			const sentence = describeWrittenFile(relativeDisplay(cwd, file), dryRun);
+			const sentence = describeWrittenFile(relativeDisplayPath(cwd, file), dryRun);
+			if (sentence) consola$1.info(sentence);
+		}
+		for (const file of result.filesSkipped) consola$1.info(`Left ${relativeDisplayPath(cwd, file)} unchanged (already matches target)`);
+		let resourceResult;
+		try {
+			resourceResult = dryRun ? { filesWritten: [] } : await materializeSetupResources({
+				cwd,
+				client: createZitadelClient({
+					baseUrl: answers.server,
+					token: project.project_secret
+				}),
+				projectId: project.id,
+				force,
+				preset: answers.preset,
+				useCase: answers.useCase,
+				design: answers.design,
+				cliVersion: this.meta.cliVersion
+			});
+		} catch (error) {
+			await rm(join(cwd, "zitadel.json"), { force: true });
+			await rm(join(cwd, ".zitadel/secret"), { force: true });
+			const cause = toZitadelError(error);
+			throw new ZitadelError(cause.code, `Default resource setup failed: ${cause.message}`, {
+				hint: "The project was created but its default schema/flow upload did not finish. Re-run `zitadel setup` to start over (add --force to overwrite partially written .zitadel files).",
+				nextCommands: ["zitadel setup --force"],
+				details: cause.details
+			});
+		}
+		for (const file of resourceResult.filesWritten) {
+			const sentence = describeWrittenFile(relativeDisplayPath(cwd, file), dryRun);
 			if (sentence) consola$1.info(sentence);
 		}
-		for (const file of result.filesSkipped) consola$1.info(`Left ${relativeDisplay(cwd, file)} unchanged (already matches target)`);
-		consola$1.success(`Patched ${result.filesWritten.length} file${result.filesWritten.length === 1 ? "" : "s"}` + (result.filesSkipped.length > 0 ? ` (${result.filesSkipped.length} unchanged)` : ""));
+		const allFilesWritten = [...result.filesWritten, ...resourceResult.filesWritten];
+		consola$1.success(`Patched ${allFilesWritten.length} file${allFilesWritten.length === 1 ? "" : "s"}` + (result.filesSkipped.length > 0 ? ` (${result.filesSkipped.length} unchanged)` : ""));
+		this.recordTelemetry({
+			step: "files_patched",
+			files_written_count: allFilesWritten.length
+		});
+		if (!dryRun) try {
+			await writeScaffoldManifest({
+				cwd,
+				actions: orca.patcherFor(framework.id).artifacts({
+					framework,
+					rendererId: ctx.rendererId
+				}),
+				written: [...result.filesWritten, ...result.filesSkipped],
+				scaffoldedFramework,
+				devPort: answers.devPort,
+				posture
+			});
+		} catch (error) {
+			consola$1.debug("Failed to record the scaffold manifest", error);
+		}
 		const installOutcome = await installDependenciesForSetup({
+			cliVersion: this.meta.cliVersion,
 			cwd,
 			depsAdded: result.depsAdded,
 			dryRun,
@@ -698,7 +931,22 @@ var Setup = class Setup extends BaseCommand {
 			scaffoldedFramework,
 			skipInstall: Boolean(flags["skip-install"])
 		});
-		const writtenRel = result.filesWritten.map((file) => relativeDisplay(cwd, file));
+		this.recordTelemetry({
+			step: "dependencies_installed",
+			package_manager: installOutcome.install.package_manager
+		});
+		const writtenRel = allFilesWritten.map((file) => relativeDisplayPath(cwd, file));
+		const claimNudge = claimState({
+			secret: {},
+			server: answers.server
+		}).kind === "detached" ? {
+			actions: [claimAction(this.meta.cliVersion)],
+			commands: [claimCommand(this.meta.cliVersion)]
+		} : {
+			actions: [],
+			commands: []
+		};
+		const warnings = designWarnings(answers.design);
 		if (!this.jsonEnabled()) {
 			const sections = buildSummary({
 				projectFacts: await detectProjectFacts(cwd, framework.id),
@@ -706,14 +954,15 @@ var Setup = class Setup extends BaseCommand {
 				project,
 				server: answers.server,
 				issuer,
-				scaffoldedFramework
+				scaffoldedFramework,
+				design: answers.design
 			});
 			consola$1.box({
 				title: "Zitadel is ready",
 				message: [
 					renderSummary(sections),
 					"",
-					installOutcome.nextActions.join("\n")
+					[...installOutcome.boxActions, ...claimNudge.actions].join("\n")
 				].join("\n"),
 				style: {
 					padding: 1,
@@ -721,9 +970,11 @@ var Setup = class Setup extends BaseCommand {
 					borderColor: "green"
 				}
 			});
+			for (const warning of warnings) consola$1.warn(warning);
 		}
 		return this.emit({
 			status: "ok",
+			warnings,
 			pretty: "",
 			data: {
 				title: "Zitadel is ready.",
@@ -733,15 +984,35 @@ var Setup = class Setup extends BaseCommand {
 				},
 				framework: framework.id,
 				server: answers.server,
-				files_written: result.filesWritten.map((file) => relativeDisplay(cwd, file)),
-				files_skipped: result.filesSkipped.map((file) => relativeDisplay(cwd, file)),
+				files_written: allFilesWritten.map((file) => relativeDisplayPath(cwd, file)),
+				files: result.files.map((file) => ({
+					path: relativeDisplayPath(cwd, file.path),
+					kind: file.kind,
+					action: file.action
+				})),
+				files_skipped: result.filesSkipped.map((file) => relativeDisplayPath(cwd, file)),
 				install: installOutcome.install,
-				next_actions: installOutcome.nextActions,
-				next_commands: installOutcome.nextCommands
+				design: answers.design ?? null,
+				next_actions: [
+					...installOutcome.nextActions,
+					brandingGuidanceAction(answers.design, this.meta.cliVersion),
+					...claimNudge.actions
+				],
+				next_commands: [...installOutcome.nextCommands, ...claimNudge.commands]
 			}
 		});
 	}
 };
+function frameworkDetectionWithScaffoldTarget(error, cwd, target) {
+	return new ZitadelError(error.code, "Could not detect a supported app framework, and this directory is not a fresh scaffold target", {
+		hint: `${target.reason ?? "Directory is not empty."} Run setup from an empty directory to scaffold a new app, or run setup from an existing supported app project.`,
+		details: {
+			cwd,
+			entries: target.entries,
+			reason: target.reason
+		}
+	});
+}
 /**
 * Resolves which framework to scaffold into an empty directory: the explicit
 * `--framework`, else PickFrameworkPrompt, else a hard error in non-interactive
@@ -756,20 +1027,59 @@ async function resolveScaffoldFramework(framework, nonInteractive, orca) {
 function dryRunProject(issuer) {
 	return {
 		id: "dry-run-0000",
-		projectSecret: "sk_proj_dry_run_full",
-		previewSecret: "sk_proj_dry_run_preview",
-		previewOrigins: [issuer],
-		createdAt: "2026-04-21T14:03:11.000Z"
+		project_secret: "sk_proj_dry_run_full",
+		preview_secret: "sk_proj_dry_run_preview",
+		preview_origins: [issuer],
+		created_at: "2026-04-21T14:03:11.000Z"
+	};
+}
+/**
+* Reconstructs the flag list of the current invocation for retry guidance,
+* ending in `--server local`. Flags whose resolved value equals the default
+* are omitted — the retry reproduces the same outcome without them.
+*/
+function setupRetryFlags(opts) {
+	const parts = [];
+	if (opts.framework) parts.push(`--framework ${opts.framework}`);
+	if (opts.preset && opts.preset !== DEFAULT_SETUP_PRESET) parts.push(`--preset ${opts.preset}`);
+	if (opts.useCase && opts.useCase !== DEFAULT_SETUP_USE_CASE) parts.push(`--use-case ${opts.useCase}`);
+	if (opts.design) parts.push(`--design ${opts.design}`);
+	if (opts.renderer && opts.renderer !== "react") parts.push(`--renderer ${opts.renderer}`);
+	if (opts.devPort !== void 0) parts.push(`--dev-port ${opts.devPort}`);
+	if (opts.nonInteractive) parts.push("--non-interactive");
+	parts.push("--server local");
+	return parts.join(" ");
+}
+/**
+* Retry options straight from parsed flags, for failures before the wizard
+* resolves answers. `--non-interactive` is echoed only when explicitly passed
+* — TTY/JSON-inferred non-interactivity re-infers itself on the retry.
+*/
+function retryOptionsFromFlags(flags) {
+	return {
+		framework: flags.framework,
+		preset: flags.preset,
+		useCase: flags["use-case"],
+		design: flags.design,
+		renderer: flags.renderer,
+		devPort: flags["dev-port"],
+		nonInteractive: Boolean(flags["non-interactive"])
 	};
 }
-async function createProjectWithLocalHint(client, server, cliVersion, issuer, framework) {
+async function createProjectWithLocalHint(client, server, cliVersion, projectName, issuer, retry) {
 	try {
-		return await client.createProject({ previewOrigins: [issuer] });
+		const payload = {
+			name: projectName,
+			preview_origins: [issuer],
+			seed_defaults: false
+		};
+		return await client.createProject(payload);
 	} catch (error) {
 		const normalized = toZitadelError(error);
+		const retryFlags = setupRetryFlags(retry);
 		throw new ZitadelError(normalized.code, normalized.message, {
-			hint: `${normalized.hint ? `${normalized.hint} ` : ""}If you meant to use a local Zitadel server, start it first and retry setup with --framework ${framework} --server local.`,
-			nextCommands: [publicCliCommand("start", cliVersion), publicCliCommand(`setup --framework ${framework} --server local`, cliVersion)],
+			hint: `${normalized.hint ? `${normalized.hint} ` : ""}If you meant to use a local Zitadel server, start it first and retry setup with ${retryFlags}.`,
+			nextCommands: [publicCliCommand("start", cliVersion), publicCliCommand(`setup ${retryFlags}`, cliVersion)],
 			details: {
 				server,
 				original: normalized.details
@@ -777,20 +1087,20 @@ async function createProjectWithLocalHint(client, server, cliVersion, issuer, fr
 		});
 	}
 }
-function localSetupHint(error, framework, cliVersion) {
+function defaultProjectName(cwd, framework) {
+	const fromDirectory = basename(cwd).trim();
+	return fromDirectory.length > 0 ? fromDirectory : `zitadel-${framework}-app`;
+}
+function localSetupHint(error, retry, cliVersion) {
 	const normalized = toZitadelError(error);
 	if (normalized.code !== "E_LOCAL_SERVER_NOT_RUNNING") return error;
-	const setupCommand = framework ? `setup --framework ${framework} --server local` : "setup --server local";
+	const setupCommand = `setup ${setupRetryFlags(retry)}`;
 	return new ZitadelError(normalized.code, normalized.message, {
 		hint: `${normalized.hint ? `${normalized.hint} ` : ""}Start local Zitadel first, then rerun setup. After setup succeeds, follow its next_commands to start the app and verify registration, logout, and login in the browser.`,
 		nextCommands: [publicCliCommand("start", cliVersion), publicCliCommand(setupCommand, cliVersion)],
 		details: normalized.details
 	});
 }
-/** Renders an absolute path relative to `cwd` for human-readable output. */
-function relativeDisplay(cwd, path) {
-	return path.startsWith(cwd) ? path.slice(cwd.length + 1) : path;
-}
 /**
 * Replaces the user's `$HOME` with `~` in a path for compact terminal output.
 * Falls back to the raw path when `HOME` isn't set or doesn't match.
@@ -811,15 +1121,13 @@ function pickWrittenFile(written, suffix) {
 }
 /**
 * Translates a patcher-written path into a single sentence the user can
-* read at narration speed. Returns `null` for directories and other
-* scaffolding artefacts that aren't worth narrating individually — the
-* file count in the closing `success(...)` and the summary's INSTALLED
-* section already cover them. The verb tense flips for `--dry-run` so
-* the user sees a preview ("Would write ...") instead of a claim that
-* something happened.
+* read at narration speed. The patch result's `filesWritten` carries
+* deduplicated file paths only (directories stay in the typed `files`
+* rows), so no artefact filtering is needed here. The verb tense flips
+* for `--dry-run` so the user sees a preview ("Would write ...") instead
+* of a claim that something happened.
 */
 function describeWrittenFile(relPath, dryRun) {
-	if (relPath === ".zitadel" || relPath === ".zitadel/flows" || relPath === ".zitadel/schemas") return null;
 	const verb = dryRun ? "Would write" : "Wrote";
 	const sentence = SENTENCE_BY_PATH[relPath];
 	if (sentence) return `${verb} ${sentence.subject} (${path(relPath)})`;
@@ -837,8 +1145,21 @@ const SENTENCE_BY_PATH = {
 	"zitadel.json": { subject: "the Zitadel project configuration" },
 	".env.example": { subject: "the .env example template" },
 	".env.local": { subject: "the local development environment variables" },
-	".zitadel/state.json": { subject: "the empty sync state file" },
-	"app/page.tsx": { subject: "the auth home page" },
+	".zitadel/state.json": { subject: "the sync state file" },
+	".zitadel/flows/default-login.json": { subject: "the editable default login flow" },
+	".zitadel/flows/README.md": { subject: "the flows folder README" },
+	".zitadel/schemas/default-human-user.json": { subject: "the editable default human user schema" },
+	".zitadel/schemas/README.md": { subject: "the schemas folder README" },
+	".zitadel/meta/flow-definition.json": { subject: "the flow dialect spec (editor $schema)" },
+	".zitadel/meta/user-schema.json": { subject: "the user-schema dialect spec" },
+	".zitadel/meta/user-property.json": { subject: "the user-property dialect spec" },
+	".zitadel/meta/branding.json": { subject: "the branding dialect spec" },
+	".zitadel/branding/branding.json": { subject: "the branding descriptor (layout + asset URLs)" },
+	".zitadel/branding/login.liquid": { subject: "the editable login template" },
+	".zitadel/branding/README.md": { subject: "the branding folder README" },
+	"AGENTS.md": { subject: "the agent guidance (golden journey + config dialect)" },
+	"README.md": { subject: "the README's Zitadel section" },
+	"app/page.tsx": { subject: "the home page redirect" },
 	"app/login/page.tsx": { subject: "the login page" },
 	"app/register/page.tsx": { subject: "the registration page" },
 	"app/profile/page.tsx": { subject: "the profile page" },
@@ -849,7 +1170,7 @@ const SENTENCE_BY_PATH = {
 };
 /** Builds the section list driving {@link renderSummary} for the setup command. */
 function buildSummary(opts) {
-	const { projectFacts, writtenRel, project, server, issuer, scaffoldedFramework } = opts;
+	const { projectFacts, writtenRel, project, server, issuer, scaffoldedFramework, design } = opts;
 	const sdkPackage = "@zitadel/sdk-next";
 	const packageJsonHit = pickWrittenFile(writtenRel, "package.json");
 	const detected = [{
@@ -867,7 +1188,7 @@ function buildSummary(opts) {
 		secondary: path(fileNameOf(packageJsonHit))
 	});
 	for (const [label, suffix] of [
-		["Home page", "app/page.tsx"],
+		["Home redirect", "app/page.tsx"],
 		["Login page", "app/login/page.tsx"],
 		["Register page", "app/register/page.tsx"],
 		["Profile page", "app/profile/page.tsx"],
@@ -881,6 +1202,28 @@ function buildSummary(opts) {
 			value: path(hit)
 		});
 	}
+	const customizeRows = [];
+	for (const [label, suffix, dir] of [
+		[
+			"User schema",
+			".zitadel/schemas/default-human-user.json",
+			".zitadel/schemas/"
+		],
+		[
+			"Login flow",
+			".zitadel/flows/default-login.json",
+			".zitadel/flows/"
+		],
+		[
+			"Login template",
+			".zitadel/branding/login.liquid",
+			".zitadel/branding/"
+		]
+	]) if (pickWrittenFile(writtenRel, suffix)) customizeRows.push({
+		label,
+		value: path(dir),
+		secondary: "see its README.md"
+	});
 	const projectRows = [
 		{
 			label: "Project id",
@@ -893,6 +1236,14 @@ function buildSummary(opts) {
 		{
 			label: "App will run",
 			value: url(issuer)
+		},
+		design ? {
+			label: "Login design",
+			value: brandingDesignLabel(design),
+			secondary: `${design} · ${path(".zitadel/branding/")}`
+		} : {
+			label: "Login design",
+			value: dim("built-in template")
 		}
 	];
 	return [
@@ -904,6 +1255,10 @@ function buildSummary(opts) {
 			title: "Installed",
 			rows: installedRows
 		},
+		{
+			title: "Customize",
+			rows: customizeRows
+		},
 		{
 			title: "Project",
 			rows: projectRows