@zitadel/cli 1.0.0-alpha.25 → 1.0.0-alpha.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zitadel/cli",
-  "version": "1.0.0-alpha.25",
+  "version": "1.0.0-alpha.28",
   "description": "Agent-friendly Zitadel CLI",
   "homepage": "https://github.com/zitadel/nextgen/tree/main/apps/cli#readme",
   "bugs": {
@@ -72,8 +72,17 @@
       "branding": {
         "description": "Work with login branding revisions."
       },
-      "sso": {
-        "description": "Manage the identity providers users can sign in with."
+      "auth-method": {
+        "description": "Turn sign-in methods on or off for a user schema."
+      },
+      "auth-method:password": {
+        "description": "Turn password sign-in on or off."
+      },
+      "auth-method:passkey": {
+        "description": "Turn passkey sign-in on or off."
+      },
+      "auth-method:sso": {
+        "description": "Add or remove identity providers."
       }
     }
   },
@@ -88,32 +97,34 @@
     "@oclif/plugin-search": "^1.2.50",
     "@oclif/plugin-version": "^2.2.46",
     "@oclif/plugin-which": "^3.2.55",
+    "@zitadel/api": "1.0.0-alpha.28",
+    "@zitadel/config": "1.0.0-alpha.28",
+    "@zitadel/server": "1.0.0-alpha.28",
     "ajv": "^8.20.0",
     "consola": "^3.4.2",
     "magicast": "^0.5.3",
     "mixpanel": "^0.18.1",
     "safe-stable-stringify": "^2.5.0",
     "semver": "^7.7.3",
-    "undici": "^7.24.7",
+    "undici": "^7.29.1",
     "wrap-ansi": "^7.0.0",
     "zod": "^4.3.6",
     "picocolors": "^1.1.1",
-    "@zitadel/api": "1.0.0-alpha.25",
-    "@zitadel/config": "1.0.0-alpha.25",
-    "@zitadel/server": "1.0.0-alpha.25"
+    "rosie-skills": "^0.8.5"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^24.19.1",
     "@types/semver": "^7.7.1",
     "@types/wrap-ansi": "^3.0.0",
     "@vitest/coverage-v8": "^4.1.11",
+    "@zitadel/api-mock": "0.0.0",
+    "@zitadel/sdk-next": "1.0.0-alpha.28",
     "msw": "^2.14.6",
     "oclif": "^4.17.46",
     "tsdown": "^0.23.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11",
-    "@zitadel/api-mock": "0.0.0",
-    "@zitadel/sdk-next": "1.0.0-alpha.25"
+    "vite": "^8.3.1",
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "build": "tsdown",
@@ -121,6 +132,9 @@
     "pretest": "pnpm run build",
     "test": "vitest run",
     "test:all": "pnpm run test",
-    "readme": "oclif readme"
+    "check-advisories": "vitest run --config vitest.advisories.config.ts",
+    "readme": "oclif readme",
+    "lint": "biome check .",
+    "build-release": "node ../../scripts/release-clean.mjs local-dist && pnpm run build"
   }
 }

package/skills/zitadel-cli/SKILL.md

@@ -4,8 +4,9 @@ description: >-
   Set up and manage Zitadel authentication in a local project with the
   agent-friendly `zitadel` CLI. Use when the user wants to add login,
   registration, or session handling, create a Zitadel project, scaffold auth
-  for a Next.js, React, Vue, Angular, Nuxt, Solid, Svelte, or Qwik app, or plan and apply Zitadel
-  config changes from repo state.
+  for a Next.js, Nuxt, SvelteKit, SolidStart, Qwik Router, TanStack Start, React,
+  Vue, Angular, Solid, Svelte, or Qwik app, or plan and apply Zitadel config
+  changes from repo state.
 ---
 
 # Zitadel CLI
@@ -32,10 +33,19 @@ to install first:
 npx @zitadel/cli@alpha <command> --non-interactive --json
 ```
 
-During the public alpha, bare `npx @zitadel/cli` is promoted to the same tested
-alpha CLI so discovery works for first-time users. Prefer `@alpha`, or an exact
-`0.1.0-alpha.N` selector in agent scripts and bug reports, for reproducibility.
-The CLI requires Node.js 24+.
+Always pass `@alpha`: bare `npx @zitadel/cli` resolves npm's `latest` tag,
+which still points at an early `0.0.0` build. Use an exact `1.0.0-alpha.N`
+selector in agent scripts and bug reports for reproducibility.
+The CLI requires Node.js 24+. When `setup` creates a new app it first checks the running Node.js against the `engines.node` of the framework CLI it is about to run (`@angular/cli`, `nuxi`, `create-vite`, `create-next-app`). Only the Angular CLI refuses a Node it does not accept, and that range can be newer than 24.0: if `setup` refuses with `E_VALIDATION` naming the Node versions Angular accepts, switch to one of them and run it again. The Angular CLI checks each major on its own, so only 22.22.3+ on 22, 24.15.0+ on 24 and 26.x are accepted (23 and 25 run with a warning), and Node 27 or later is refused even though the published range reads `>=26.0.0`. For the other frameworks the CLI carries on, so `setup` adds a warning to the envelope's `warnings` and continues.
+
+The app's framework must be at or above a minimum version: Next.js 15.2.3,
+React 18, Vue 3.2, Nuxt 4, Angular 17, Solid 1.6, Svelte 5, Qwik 2.0.0-beta.45. Newer major
+versions are not refused. `setup` and `doctor` refuse an app below its minimum,
+by declared range or installed release, with `E_UNSUPPORTED_PROJECT_SHAPE`
+(exit 3); `setup` refuses before it scaffolds or patches anything, while
+`doctor --fix` can still repair unrelated files, so do not assume a floor error
+left the project untouched. The message names the minimum and the hint says to
+upgrade, so upgrade the app and rerun rather than retrying.
 
 ## Using the CLI
 
@@ -74,12 +84,28 @@ The CLI requires Node.js 24+.
   Two deliberate deviations worth knowing: `-n` is `--non-interactive` (not
   `--dry-run`, which is long-only), and machine output is `--json` (not
   `--output json`).
+- **Writing a resource's body.** A `create` or `update` takes every field of
+  its body as a flag, nested ones too: a nested field's flag is its dot path
+  joined with `-` (`oidc.client_id` is `--oidc-client-id`), a list is a
+  repeated flag, a boolean takes `--no-<flag>` for `false`, and an open record
+  (`attributes`) takes repeated `key=value` entries. `--set <path>=<value>`
+  (or `<path>:=<json>` for JSON) reaches any field by its dot path, and
+  `--data` / `--file` take the whole document. They combine: the document
+  first, then the field flags, then each `--set`, with objects merging key by
+  key. `resources --json` lists each write's fields with their dot path
+  (`name`), `flag` (`null` when only `--set` reaches it), `kind` and
+  `required`; `--dry-run --json` returns the body that would be sent. For a
+  deeply nested body, writing the document and passing it with `--file -` is
+  often simplest.
 - **Never put secrets on the command line.** A property whose name reads as a
   credential (`password`, `client_secret`, `api_key`, …) is refused anywhere on
-  argv — as an `--attributes` entry and inside an inline `--data` body alike,
-  since argv is visible to other processes and kept in shell history. Send such
-  bodies with `--file <path>` or `--file -` (stdin), which never pass through
-  argv.
+  argv when it holds free-form text — as a field flag, a `--set` or
+  `--attributes` entry, and inside an inline `--data` body alike, since argv is
+  visible to other processes and kept in shell history. Send such bodies with
+  `--file <path>` or `--file -` (stdin), which never pass through argv. A
+  `${{ NAME }}` reference to a project variable is not a secret and may stay on
+  argv (a connection's `client_secret` takes nothing else); write it in single
+  quotes, since inside double quotes the shell reads `${` as its own expansion.
 - **Streams.** Capture stdout and stderr separately when scripting. The machine
   contract is one parseable JSON object on stdout; installer, audit, and
   package-manager progress belongs on stderr.
@@ -114,8 +140,9 @@ once — every resource, its verbs, each verb's `create_fields` / `update_fields
 (flag name, kind, `required`, any closed value set), its `filter_fields` /
 `sort_fields`, and the `delete_outcome` a destructive verb returns — so prefer it
 over reading `<resource> --help` one at a time. A `list` verb's envelope carries
-`data.count`, so a "how many …?" question is one `list --json` call: read the
-count, do not page and tally.
+`data.count`, the number of items it returned. A list returns one page unless
+you pass `--all`, so a "how many …?" question is one `list --all --json` call:
+read the count, do not page and tally.
 
 ## Reading the envelope
 
@@ -124,10 +151,13 @@ Each invocation prints one JSON object:
 - `status`: `ok` | `skipped` | `error`.
 - `cli_version`, `command`, `source`: always present.
 - On success: `data` with the command-specific payload.
-- On a no-op: `reason` (e.g. `no-framework-detected`, `orphaned-config`).
+- On a no-op: `reason` (e.g. `already-initialized`, `already-claimed`,
+  `nothing-to-eject`).
 - On failure: `code` (e.g. `E_VALIDATION`, `E_NETWORK`, `E_NOT_FOUND`,
-  `E_CONFLICT`) and `message`.
-- `next_commands`: the suggested follow-ups. Prefer these over free-text hints.
+  `E_CONFLICT`) and `message`, usually with a `hint`, and `details` when there
+  is structured context.
+- `next_commands`: the suggested follow-ups, inside `data` on success and at
+  the top level on a no-op or failure. Prefer these over free-text hints.
 - `warnings`: things that went wrong without stopping the command, such as a
   value that was not published. Always present on success (often empty), and
   present on a no-op or failure when there are any. Read them before you report
@@ -135,9 +165,18 @@ Each invocation prints one JSON object:
 - A `list` verb emits `data: { items, count, next_page_token }`; when a page
   remains, `data.next_commands` carries the exact command for the next page.
 - `plan` and `apply` emit `data.changes`: one row per touched resource
-  (`{kind, action, file, id?, previous_id?}`, action ∈ create/update/revision/
-  delete). Plan rows preview; apply rows report, with the resulting platform
-  ids. Use it to verify an edit did what you intended.
+  (`{kind, action, file, id?, previous_id?, moved_from?}`, action ∈ create/
+  update/revision/delete/move). A `move` is a file that took over a resource
+  from a removed one (`moved_from`). Plan rows preview; apply rows report, with
+  the resulting platform ids. Use it to verify an edit did what you intended.
+  `data.unsupported_deletions` counts removed files whose resource cannot be
+  deleted yet (they are kept, and are not part of `total`); on `apply` the files
+  are listed in `data.unsupported_deletion_files`.
+- `apply` leaves the files under `.zitadel/` as written: what the server stores
+  is never written back, and a field a file leaves out reads as the server's
+  default, so `plan` reports no change after an `apply`. `data.files_updated`
+  lists the one rewrite: a flow whose `user_schema` pinned a schema revision id
+  the apply superseded, re-pinned to the new revision's id.
 - A write verb's `--dry-run` reports what it would send without calling the
   platform, so you can preview a mutation before making it.
 
@@ -145,6 +184,9 @@ Common error codes point at their own fix in `next_commands`:
 
 - `E_VALIDATION`: the body or flags are wrong; `message` names what, and
   `details` often lists the missing or available values.
+- `E_CREDENTIAL_MISSING`: a connection's `client_id` or `client_secret` names a
+  project variable that does not exist; `details.variable` is the name. Publish it
+  with `variables set NAME --project-level` (add `--secret` for the secret), then retry.
 - `E_LOCAL_SERVER_NOT_RUNNING`: start the local runtime, then retry with
   `--server local`.
 - `E_NOT_FOUND`: an HTTP 404 — a missing resource, or a `--server` that is not a
@@ -181,16 +223,44 @@ the conversation: you clarify with the human, then drive the CLI headlessly.
 Ask about:
 
 - **Sign-in methods** — password (the usual default), passkeys, and single
-  sign-on. If they want SSO, which providers?
-- **Profile fields** — the user schema starts with first name, last name, and
-  the login identifier plus a password. Which additional fields do they want
-  (for example phone, username, or a display name)?
+  sign-on. If they want SSO, which providers? A provider the CLI does not list
+  by name is still possible: run `zitadel auth-method sso enable --help` to see
+  whether the installed CLI takes one, and which settings it needs, and ask for
+  those too.
+- **Profile fields** — which attributes sign-up collects. The starting field
+  set depends on the use-case you pick (see *Presets and use-cases* below) —
+  the default (`minimal`) is the login identifier only, **not** names. Confirm
+  which fields they want (first/last name, phone, username, display name) and
+  choose the use-case or edit the schema accordingly.
 
 Offer only what the installed CLI actually supports: read the real sign-in
 presets, profile fields, and SSO options from the CLI first (`setup --help`,
 `resources --json`) and present those, not a list you remember — the options
 move with the CLI version.
 
+## Presets and use-cases — map the answers, don't trust the names
+
+`setup` has two independent axes, and their names do **not** mean what they look
+like. Read the current sets from `setup --help`, but know the traps:
+
+- **Use-case = which profile fields the schema collects.** `minimal` is the
+  login identifier **only** — it does *not* include names. First + last name is
+  `--use-case consumer` (adds `givenName` + `familyName`); add a company with
+  `--use-case business`. Choosing `minimal` because the developer said "keep it
+  minimal" leaves an identifier-only schema that ignores the names they asked
+  for.
+- **Preset = how they sign in (the login flow + auth methods).**
+  `password-first` makes password the primary step **but still leaves passkeys
+  enabled**; `passkey-first` leads with a passkey. Neither one gives you
+  password-only. If the developer does not want passkeys, turn them off
+  yourself: set `x-auth-methods.passkey.enabled` to `false` in
+  `.zitadel/schemas/*.json`, then `apply`.
+
+Translate the developer's answers into the right axis values, then **verify
+against what actually deployed**: read the live schema back
+(`schemas get <objectType> --json`) and confirm the fields and auth methods
+match what they asked for — don't assume a preset name did it.
+
 Skip the questions and proceed with the defaults above — stating the assumptions
 you made so the user can correct them — in exactly two cases: the user already
 told you what they want, or you are running non-interactively (a one-shot/headless
@@ -220,33 +290,123 @@ framework, sign-in preset, and profile-field options):
 ```sh
 npx @zitadel/cli@alpha doctor --non-interactive --json
 npx @zitadel/cli@alpha start --non-interactive --json
-npx @zitadel/cli@alpha setup --framework next --server local --force --non-interactive --json
+npx @zitadel/cli@alpha setup --framework next --server local --non-interactive --json
 npx @zitadel/cli@alpha doctor --non-interactive --json
 npx @zitadel/cli@alpha plan --non-interactive --json
 npx @zitadel/cli@alpha apply --non-interactive --json
 ```
 
 `setup` scaffolds into an empty directory, or patches an existing app project
-where it detects a framework. It stops on any other non-empty directory and
-asks for `--force` — which the golden path passes because `start` has already
-written `.zitadel/local` into the directory. If you run `setup` before `start`,
-in a truly empty directory, `--force` is not needed.
+where it detects a framework. What `start` leaves in a directory —
+`.zitadel/local/` and the `.gitignore` line that ignores it — still counts as
+empty, so the golden path runs `setup` right after `start` in the same
+directory. Any other non-empty directory stops setup with a hint to pass
+`--force`. Pass it only for a directory whose contents may be replaced: files
+the new app also has, such as `package.json`, are overwritten. Without a
+terminal `setup` cannot ask which framework to scaffold, so pass `--framework`;
+the error lists the choices in `details.frameworks`. `setup --dry-run` creates
+no app: where it would scaffold one, it previews the project, and
+`data.files_written` is empty, because those files depend on the generated app.
+When setup fails after scaffolding a new app, before its default schema and
+flow are uploaded, it removes the app again and puts back what the directory
+held, so rerunning the same `setup` starts over.
+
+`start` reuses a server already running in the directory only when it is the
+release this CLI ships; one an earlier release started is restarted, and its
+data stays. `setup --server local` refuses a binary-runtime server another
+release started with `E_CONFLICT` before it creates anything: that server's API
+is its own release's. Its `next_commands` run `start`, then `setup` again.
+
+In an existing app, `--framework` has to name the framework setup detects
+there; another one stops setup with `E_CONFLICT` instead of offering
+`--force`. Setup reports its conflicts with the app before it creates a
+project, and the error's `hint` says whether `--force` resolves one: it
+replaces a file at a path setup writes, but not the app's root component or
+request boundary at another path.
 
 The app may also live in a subdirectory of the one `start` ran in: `setup`,
-`console` and `--server local` read `.zitadel/local/` from the working
+`console`, `--server local` and `doctor` read `.zitadel/local/` from the working
 directory or the nearest parent that has it (up to the home directory), so
-`mkdir my-app && cd my-app` after `start` works without `--force`. On a local
+`mkdir my-app && cd my-app` after `start` works too. `doctor` checks that
+server and its port, but runs its project checks in the working directory, so run
+it from the app. When that server is unhealthy it suggests `start` and
+`reset --force` with `--cwd` set to the directory that holds it (when that path needs
+shell quoting the commands are left out, the hint names the directory, and
+`doctor --json` returns the argument lists in `details.suggested_args` to run as they are). `stop`,
+`reset`, `logs` and `status` read only the working directory's
+`.zitadel/local/`, so run them where `start` ran. On a local
 server that hosts the platform project, `setup` attaches the project to the
 local admin's team and ends `data.next_commands` with `console`; when it finds
 no local admin for that server on the way up, it says so in the envelope's
 `warnings` and the project stays unattached, so the local console does not
 list it.
 
+When `setup --sso` or `sso enable` adds a social sign-in provider, the user
+must register the connection's redirect URI with the provider themselves: give
+them `data.sso[].callback_uri` from `setup`, or `data.callback_uri` from
+`sso enable`, verbatim. Each connection has its own URI, so a URI from another
+provider or an older CLI version does not work.
+
 After `setup`, follow `data.next_commands` to start the app. Prove the generated
 auth flow in a visible browser by registering a unique user, logging out, logging
 back in with the same email/password, and ending on the signed-in profile page.
 Do not treat a rendered login or registration form as completion.
 
+To move a set-up app to another dev port (the dev server exits with
+`EADDRINUSE`, or another app needs the port), run `setup --dev-port <port>` in
+the app; never change the port in one file by hand. In a directory with a
+`zitadel.json`, `setup` returns `status: "skipped"` with `reason:
+"already-initialized"`, unless `--dev-port` is given: then it moves the app.
+It allows the new origin on the server first, and a refusal changes nothing.
+It then rewrites the dev script or dev-server config, `ZITADEL_ISSUER` in
+`.env.local`, `zitadel.json`, `.zitadel/secret` and the README/AGENTS.md
+guidance, and removes the old origin. `data.previous_issuer` and `data.issuer`
+name both origins, and `data.moved` is `false` when the app was already on that
+port. A social sign-in provider still redirects to the old port: `warnings`
+names the redirect URI to add at each provider. Restart the dev server
+afterwards.
+
+To change how users sign in after setup, use the `auth-method` commands. Each
+sign-in method has its own command, with `--schema` when the project has more
+than one:
+
+- `auth-method password enable` and `auth-method password disable`
+- `auth-method passkey enable` and `auth-method passkey disable`
+- `auth-method sso enable --provider google` adds a provider. It prompts for
+  the client id and secret, or takes `--client-id` with the secret piped on
+  stdin when non-interactive. Any other OpenID Connect provider is
+  `--provider custom` with `--slug`, `--display-name`, `--issuer` and optionally
+  `--scopes` (default `openid profile email`).
+  An issuer on `http://localhost:<port>` (a test provider on this machine)
+  works against a server `zitadel start` runs as a process: `start` sets
+  `NEXTGEN_HTTPCLIENT_ALLOW_LIST=localhost,127.0.0.0/8,::1/128` unless
+  `.env.local`, `.env` or the shell sets it, and setting it empty turns it off.
+  Under `--runtime docker` localhost is the container, so the provider is not
+  reachable. Otherwise `sso enable` warns in `warnings` that sign-in will fail.
+  `auth-method sso disable --provider google` removes a provider; a custom one
+  is named by its slug, as in `auth-method sso disable --provider acme-sso`.
+
+The commands change only local files, apart from
+`auth-method sso enable`, which also stores the provider's credentials on the
+project. When they refuse, they write and publish nothing, on a dry run too.
+They refuse to disable a method a login flow still asks for, to change a method
+while a login flow has errors that prevent checking it, to enable password on a
+schema without `x-identifier`, to edit a value that is not the shape they edit,
+and to edit a schema that points at an external URL. Disabling the schema's last
+way to sign in needs `--force` when non-interactive; only pass it for a schema
+whose users are managed through the API, and ask the user first. That refusal's
+`details.suggested_args` lists the `--force` re-run first, then the methods that
+could be enabled instead. A dry run of the change is not refused: it previews it
+and warns that no way to sign in would be left. A method that is enabled but not
+offered by any active flow is reported in `warnings` (and in `data.not_offered`
+for password and passkey). Every command reports `data.changed`, the
+project-relative files it wrote (on a dry run, the files it would write), empty
+when nothing changed. Follow `data.next_commands` (`plan`, `apply`, and
+`variables set` when a credential did not reach the project) to publish the
+change. When a path or schema name would need shell quoting, `next_commands` is
+empty and `data.next_args` (or `details.suggested_args` on a refusal) holds the
+same commands as argument lists.
+
 Repo config is authoritative: edit `zitadel.json` or files under `.zitadel/`,
 then re-run `plan` and `apply`. See the reference below for driving the login UI
 and the config-sync details.

package/skills/zitadel-cli/references/driving-login-ui.md

@@ -1,7 +1,7 @@
 ### Driving the login UI
 
-`<zitadel-login>` and `<zitadel-logout>` are Lit elements with open shadow
-roots. The stable automation hooks live inside nested shadow roots, so a flat
+`<zitadel-login>`, `<zitadel-session>`, and `<zitadel-logout>` are Lit elements
+with open shadow roots. The stable automation hooks live inside nested shadow roots, so a flat
 `document.querySelector('[data-testid="zitadel-input-email"]')` will not find
 the native control. Browser drivers with shadow-DOM-aware locators, such as
 Playwright, can target the hooks directly. Generic DOM-eval drivers should
@@ -29,11 +29,18 @@ button. Hooks stay method-named even when the flow engine names a credential
 field `x-auth-methods#<method>`; only the `name` attribute carries that raw
 form key. Enter inside a field submits the step's primary action, but only for
 key events that carry `key: "Enter"` — drivers whose synthesized key events
-omit it (some CDP wrappers) should click `zitadel-action-submit` instead. For sign-out, open the user menu button if needed, then pierce to
-`.signout-btn`; Playwright-style locators may use `zitadel-logout .signout-btn`.
-The canonical component hook list lives in `packages/components/README.md`.
+omit it (some CDP wrappers) should click `zitadel-action-submit` instead.
 
-The checked-in automated regression path is `moon run workspace:journey`, which
+For sign-out, the profile page that setup generates renders `<zitadel-session>`:
+click its `zitadel-session-logout` host, or the native button inside it,
+`zitadel-session-logout-button`. An app that renders `<zitadel-logout>` instead
+hides sign-out behind an avatar menu: click the "Open user menu" button, then
+pierce to `.signout-btn` (Playwright: `zitadel-logout .signout-btn`), which
+carries no hook. A `<zitadel-logout>` with a `<template>` child shows no menu:
+click the app's own element marked `data-action="logout"`. The canonical
+component hook list lives in `packages/components/README.md`.
+
+The checked-in automated regression path is `moon run e2e:journey`, which
 exercises fresh-app setup plus registration, logout, and login across the
 supported frameworks.
 
@@ -49,24 +56,34 @@ revisioned and immutable: every edit — including a `.liquid`-only edit —
 plans as a `revise` and `apply` publishes a new revision; the login serves
 the newest one. `plan` validates templates with the authoritative LiquidJS
 validator (`E_VALIDATION` lists rule ids such as `no-script-tag` and
-`mandatory-gates`; every template must keep a trailing
-`{% mandatory_gates %}` tag). `font_url` is not writable yet; asset URLs
-must be absolute `https://`. Keep exactly one descriptor in
+`mandatory-gates`; every template must keep a `{% mandatory_gates %}` tag,
+where the login adds any required field and the primary action the template
+left out). Asset URLs must be absolute `https://`; during development, images
+may use `http://` on `localhost`, `127.x.x.x`, or `[::1]` (not `*.localhost`).
+`typography.font_url` needs a `typography.font_family`, is always `https://`,
+and is loaded only when the login runs as `variant="page"`, which setup
+generates only when it creates a Next.js or Nuxt app itself, in an empty
+directory. Keep exactly one descriptor in
 `.zitadel/branding/` — extra `*.json` files there fail the scan.
 Server-provisioned defaults remain a fallback for non-CLI project
 creation, but CLI-created projects are authored from local files first. Flows are
 revisioned like branding: an edit plans as a `revise` and `apply` publishes a new
-immutable flow revision; a schema revise re-publishes the flows pinned to it with
-the new `user_schema` in the same run. A login pinned by `flow-name` serves that
-flow's newest revision; an unpinned login serves the newest active unscoped flow
-in the project, whatever its name. Removing a flow file does not retire the
+immutable flow revision. A flow names its schema by `objectType` in
+`user_schema` and runs against the schema's newest revision, so a schema revise
+needs no change to `user_schema`; one that removes or renames a property a step
+collects needs that step's `fields` updated, and `plan` checks only the flows it
+uploads. A login pinned by `flow-name` serves that flow's newest active
+revision; an unpinned login serves the newest active unscoped revision for its
+purpose in the project, whatever its flow's name. Older revisions stay active,
+so an `audience` added after a flow was applied without one doesn't take that
+earlier revision out of the running. Removing a flow file does not retire the
 flow. Managed files carry a marker comment; `eject` removes only
 files that still carry it, preserving anything the user replaced. For app-local
 development, `--server local` resolves through `.zitadel/local/runtime.json` and
 requires a healthy
-`npx @zitadel/cli@alpha start` runtime. Because `start` writes `.zitadel/local/`
-into the directory, it is no longer empty, so a same-directory `setup` that
-scaffolds must be passed `--force` (this is exactly what the golden path does).
+`npx @zitadel/cli@alpha start` runtime. The `.zitadel/local/` that `start`
+writes into the directory still counts as empty, so a same-directory `setup`
+scaffolds without `--force` (this is exactly what the golden path does).
 `setup` installs dependencies
 with the detected package manager by default; pass `--skip-install` when the
 agent or host workflow will install dependencies separately.

package/dist/groups-CbWm8kCm.mjs

@@ -1,22 +0,0 @@
-//#region src/lib/oclif/groups.ts
-/**
-* The groups the root help lists commands under, declared in print order: the
-* journey runs from setting up a project, to running the local server, to
-* managing its configuration, to acting on the resources inside it. Every command declares its own group
-* (`static group` on the class) so nothing has to be registered centrally; a
-* command without one lands in the trailing {@link ADDITIONAL_COMMANDS_GROUP}
-* with oclif's own utilities.
-*/
-const CommandGroups = {
-	project: "Project commands",
-	localServer: "Local server commands",
-	configuration: "Configuration commands",
-	resources: "Resource commands"
-};
-const COMMAND_GROUPS = Object.values(CommandGroups);
-/** Where ungrouped commands (oclif's `autocomplete`, `search`, …) are listed. */
-const ADDITIONAL_COMMANDS_GROUP = "Additional commands";
-//#endregion
-export { COMMAND_GROUPS as n, CommandGroups as r, ADDITIONAL_COMMANDS_GROUP as t };
-
-//# sourceMappingURL=groups-CbWm8kCm.mjs.map

package/dist/groups-CbWm8kCm.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"groups-CbWm8kCm.mjs","names":[],"sources":["../src/lib/oclif/groups.ts"],"sourcesContent":["/**\n * The groups the root help lists commands under, declared in print order: the\n * journey runs from setting up a project, to running the local server, to\n * managing its configuration, to acting on the resources inside it. Every command declares its own group\n * (`static group` on the class) so nothing has to be registered centrally; a\n * command without one lands in the trailing {@link ADDITIONAL_COMMANDS_GROUP}\n * with oclif's own utilities.\n */\nexport const CommandGroups = {\n  project: \"Project commands\",\n  localServer: \"Local server commands\",\n  configuration: \"Configuration commands\",\n  resources: \"Resource commands\",\n} as const;\n\nexport type CommandGroup = (typeof CommandGroups)[keyof typeof CommandGroups];\n\nexport const COMMAND_GROUPS: readonly CommandGroup[] = Object.values(CommandGroups);\n\n/** Where ungrouped commands (oclif's `autocomplete`, `search`, …) are listed. */\nexport const ADDITIONAL_COMMANDS_GROUP = \"Additional commands\";\n"],"mappings":";;;;;;;;;AAQA,MAAa,gBAAgB;CAC3B,SAAS;CACT,aAAa;CACb,eAAe;CACf,WAAW;AACb;AAIA,MAAa,iBAA0C,OAAO,OAAO,aAAa;;AAGlF,MAAa,4BAA4B"}