@zitadel/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/commands/setup.mjs

@@ -1,19 +1,51 @@
-import { D as ZitadelError, E as stableStringify, O as toZitadelError, n as DEFAULT_SERVER, t as BaseCommand, u as detectHealthyLocalServer, x as publicCliCommand } from "../oclif-BRdjVNne.mjs";
-import { n as inspectScaffoldTarget, o as issuerFromPort, r as RENDERER_IDS, t as createOrca } from "../orca-Dip6DPJ2.mjs";
-import { n as hasZitadelSecret, t as hasZitadelConfig } from "../project-BGgv7Bba.mjs";
-import { c as writeBackResource, d as FLOWS_DIR, l as updateState, o as hashForState } from "../sync-Cd3z7Q1R.mjs";
-import { t as SCHEMAS_DIR } from "../user-schema-DDz5-lX5.mjs";
-import { n as verifyLoginAction, t as customizeAndPublishActions } from "../journey-guidance-CYVpQszz.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-Cu0iW1mv.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-Bd6vASgg.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 { DEFAULT_FLOW_CONFIG_PATH, DEFAULT_FLOW_SCHEMA_URI, DEFAULT_SCHEMA_CONFIG_PATH, DEFAULT_SETUP_PRESET, SETUP_PRESETS, flowsReadmeContent, getDefaultHumanUserSchema, getDefaultLoginFlow, schemasReadmeContent } from "@zitadel/config/defaults";
+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 { 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/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";
+}
+//#endregion
 //#region src/lib/setup-resources.ts
 /**
 * Scaffolds the versioned local default resources for a new project, uploads
@@ -31,12 +63,16 @@ async function materializeSetupResources(opts) {
 	await mkdir(join(opts.cwd, SCHEMAS_DIR), { recursive: true });
 	const filesWritten = [];
 	const preset = opts.preset ?? DEFAULT_SETUP_PRESET;
-	const { $id: _templateId, ...schemaBody } = getDefaultHumanUserSchema({ 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), { project_id: opts.projectId });
+		const canonical = await opts.client.getSchemaById(encodeURIComponent(schemaId));
 		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);
@@ -47,7 +83,8 @@ async function materializeSetupResources(opts) {
 	});
 	const flowBody = getDefaultLoginFlow({
 		userSchemaUrl: schemaId,
-		preset
+		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({
@@ -66,13 +103,47 @@ async function materializeSetupResources(opts) {
 		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, schemasReadmeContent())) filesWritten.push(join(opts.cwd, schemasReadme));
-	if (await writeReadmeFile(opts.cwd, flowsReadme, flowsReadmeContent())) filesWritten.push(join(opts.cwd, flowsReadme));
+	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 };
 }
 /**
+* 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 {
+		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;
+	}
+}
+/**
 * 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.
@@ -106,88 +177,6 @@ function isErrno(error, code) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 //#endregion
-//#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"]);
-	}
-}
-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);
-		});
-	});
-}
-function command(packageManager, args) {
-	return {
-		command: packageManager,
-		args,
-		display: [packageManager, ...args].join(" ")
-	};
-}
-async function packageManagerFromManifest(cwd) {
-	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;
-	}
-}
-function packageManagerFromString(value) {
-	const name = value.split("@")[0];
-	return name === "npm" || name === "pnpm" || name === "yarn" || name === "bun" ? name : void 0;
-}
-async function exists(path) {
-	try {
-		await stat(path);
-		return true;
-	} catch {
-		return false;
-	}
-}
-//#endregion
 //#region src/commands/setup/install.ts
 async function installDependenciesForSetup(input) {
 	const packageManager = await detectPackageManager(input.cwd);
@@ -294,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
@@ -445,6 +482,48 @@ var SignInPresetPrompt = class {
 	}
 };
 //#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"
+			}
+		};
+		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
 /**
 * "Choose a framework to scaffold" — the only prompt outside the main wizard.
@@ -484,11 +563,23 @@ const SETUP_PROMPTS = [
 	new FrameworkConfirmPrompt(),
 	new ServerPrompt(),
 	new DevPortPrompt(),
-	new SignInPresetPrompt()
+	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
@@ -517,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
@@ -577,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
 /**
@@ -586,6 +702,16 @@ 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
@@ -607,14 +733,22 @@ 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." }),
 		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() {
@@ -654,6 +788,8 @@ var Setup = class Setup extends BaseCommand {
 			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) {
@@ -668,7 +804,9 @@ var Setup = class Setup extends BaseCommand {
 		let answers = {
 			server: this.meta.source,
 			devPort: framework.devPort,
-			preset: flags.preset ?? DEFAULT_SETUP_PRESET
+			preset: flags.preset ?? DEFAULT_SETUP_PRESET,
+			useCase: flags["use-case"] ?? DEFAULT_SETUP_USE_CASE,
+			design: flags.design
 		};
 		if (!nonInteractive && !dryRun) {
 			intro("Zitadel setup");
@@ -677,12 +815,18 @@ var Setup = class Setup extends BaseCommand {
 				cwd,
 				serverFlag: this.meta.serverFlag,
 				devPortFromFlag: flags["dev-port"] !== void 0,
-				presetFromFlag: flags.preset !== 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 });
+		this.recordTelemetry({
+			preset: answers.preset,
+			use_case: answers.useCase,
+			design: answers.design ?? "built-in"
+		});
 		const issuer = issuerFromPort(answers.devPort);
 		framework = {
 			...framework,
@@ -696,10 +840,13 @@ var Setup = class Setup extends BaseCommand {
 			...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",
@@ -708,7 +855,9 @@ var Setup = class Setup extends BaseCommand {
 			server: answers.server,
 			cliVersion: this.meta.cliVersion,
 			scaffoldedFramework,
-			preset: answers.preset
+			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, {
@@ -717,21 +866,24 @@ 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 ${relativeDisplay(cwd, file)} unchanged (already matches target)`);
+		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.projectSecret
+					token: project.project_secret
 				}),
 				projectId: project.id,
 				force,
-				preset: answers.preset
+				preset: answers.preset,
+				useCase: answers.useCase,
+				design: answers.design,
+				cliVersion: this.meta.cliVersion
 			});
 		} catch (error) {
 			await rm(join(cwd, "zitadel.json"), { force: true });
@@ -744,7 +896,7 @@ var Setup = class Setup extends BaseCommand {
 			});
 		}
 		for (const file of resourceResult.filesWritten) {
-			const sentence = describeWrittenFile(relativeDisplay(cwd, file), dryRun);
+			const sentence = describeWrittenFile(relativeDisplayPath(cwd, file), dryRun);
 			if (sentence) consola$1.info(sentence);
 		}
 		const allFilesWritten = [...result.filesWritten, ...resourceResult.filesWritten];
@@ -753,6 +905,21 @@ var Setup = class Setup extends BaseCommand {
 			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,
@@ -768,7 +935,18 @@ var Setup = class Setup extends BaseCommand {
 			step: "dependencies_installed",
 			package_manager: installOutcome.install.package_manager
 		});
-		const writtenRel = allFilesWritten.map((file) => relativeDisplay(cwd, file));
+		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),
@@ -776,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.boxActions.join("\n")
+					[...installOutcome.boxActions, ...claimNudge.actions].join("\n")
 				].join("\n"),
 				style: {
 					padding: 1,
@@ -791,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.",
@@ -803,11 +984,21 @@ var Setup = class Setup extends BaseCommand {
 				},
 				framework: framework.id,
 				server: answers.server,
-				files_written: allFilesWritten.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]
 			}
 		});
 	}
@@ -836,10 +1027,10 @@ 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"
 	};
 }
 /**
@@ -851,6 +1042,8 @@ 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");
@@ -866,6 +1059,8 @@ 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"])
@@ -875,8 +1070,8 @@ async function createProjectWithLocalHint(client, server, cliVersion, projectNam
 	try {
 		const payload = {
 			name: projectName,
-			previewOrigins: [issuer],
-			seedDefaults: false
+			preview_origins: [issuer],
+			seed_defaults: false
 		};
 		return await client.createProject(payload);
 	} catch (error) {
@@ -906,10 +1101,6 @@ function localSetupHint(error, retry, 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.
@@ -930,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" || relPath === ".zitadel/meta") return null;
 	const verb = dryRun ? "Would write" : "Wrote";
 	const sentence = SENTENCE_BY_PATH[relPath];
 	if (sentence) return `${verb} ${sentence.subject} (${path(relPath)})`;
@@ -964,6 +1153,10 @@ const SENTENCE_BY_PATH = {
 	".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" },
@@ -977,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 = [{
@@ -1009,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",
@@ -1021,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 [
@@ -1032,6 +1255,10 @@ function buildSummary(opts) {
 			title: "Installed",
 			rows: installedRows
 		},
+		{
+			title: "Customize",
+			rows: customizeRows
+		},
 		{
 			title: "Project",
 			rows: projectRows