@zitadel/config 0.1.0-alpha.18 → 1.0.0-alpha.20

package/README.md

@@ -0,0 +1,27 @@
+# @zitadel/config
+
+Versioned Zitadel local config schemas and defaults — the contract behind the
+`.zitadel/` directory that `zitadel setup` scaffolds into your project.
+
+## What's in here
+
+| Import                                             | What it carries                                                                                           |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `@zitadel/config/schemas`                          | Zod schemas for the local config files (`schemaConfigSchema`, `flowConfigSchema`, `brandingConfigSchema`) |
+| `@zitadel/config/branding-url`                     | Canonical loopback HTTP URL predicate shared by config and browser render gates                           |
+| `@zitadel/config/validate`                         | Validation entry points the CLI runs on `plan`/`apply`                                                    |
+| `@zitadel/config/normalize`                        | Normalization used to compare local files against server state                                            |
+| `@zitadel/config/defaults`                         | The versioned default user schema, login flow, and branding designs                                       |
+| `@zitadel/config/meta-schemas`                     | The JSON meta-schemas the defaults pin                                                                    |
+| `@zitadel/config/template`                         | Liquid template helpers                                                                                   |
+| `@zitadel/config/defaults/default-login.json`      | The default login flow — the authority for flow step shape                                                |
+| `@zitadel/config/defaults/default-human-user.json` | The default user schema                                                                                   |
+
+## The customer-facing part
+
+`zitadel setup` copies the defaults into your repo as
+`.zitadel/{schemas,flows,branding}/`, each with a README explaining how to
+edit it (`defaults/README-schemas.md`, `README-flows.md`,
+`README-branding.md` in this package become those files). Those files are
+yours to edit; `zitadel plan` / `zitadel apply` reconcile them with the
+server, and edits publish new revisions rather than mutating state in place.

package/defaults/README-branding.md

@@ -6,7 +6,7 @@ and asset URLs) plus `login.liquid`, the LiquidJS template the
 
 ## Workflow
 
-1. Edit `login.liquid` (and `branding.json` for logo/font/hero URLs).
+1. Edit `login.liquid` (and `branding.json` for logo/hero URLs).
 2. `zitadel plan` — validates the template (LiquidJS parse, banned patterns,
    the required `{% mandatory_gates %}` tag) and shows the pending revision.
 3. `zitadel apply` — publishes an immutable branding revision. The login UI
@@ -27,6 +27,40 @@ by re-applying an earlier template.
 
 ## Make it yours
 
+- Brand asset URLs go in `branding.json` and must use `https://`. Each template
+  decides which fields it renders: `centered` and `hero` use `logo_url`; `split`
+  and `split-right` use both `logo_url` and `hero_url`; `minimal` uses neither
+  until you add them to `login.liquid`. The `hero` design's brand pane is
+  editable markup rather than a `hero_url` background. Custom fonts are not
+  configurable here yet; load them from the embedding page.
+
+  ```json
+  {
+    "$schema": "../meta/branding.json",
+    "layout": "split",
+    "liquid_template_file": "./login.liquid",
+    "logo_url": "https://example.com/logo.svg",
+    "hero_url": "https://example.com/hero.jpg"
+  }
+  ```
+
+  A well-formed URL that serves nothing is the one branding mistake nothing
+  else catches — it passes validation, publishes a revision, and then renders
+  as an invisible image. So `zitadel plan` probes each asset URL and warns
+  (never fails) when it is unreachable, bodyless, or not an image, and the
+  login UI hides an asset that fails to load, restoring the shipped design's
+  no-asset content rather than leaving a gap. If the host is only
+  reachable from where the login page renders — or you are offline — set
+  `ZITADEL_SKIP_ASSET_PROBE=1` to skip the check. The probe contacts public
+  HTTPS destinations only and re-checks redirects; loopback/private/internal
+  targets are left to the browser-side fallback instead of being requested by
+  the machine running `plan`.
+
+  `layout` is the degrade preset (`centered` or `split`), **not** the complete
+  design catalog. All named designs (`centered`, `split`, `split-right`, `hero`,
+  `minimal`) are delivered as templates and map onto those two values. Switch
+  designs with `zitadel branding eject --design <name>`, don't edit `layout`.
+
 - In the split-family designs (`split`, `split-right`, `hero`) the
   `.zl-split__brand` pane is yours: structural HTML plus inline `style=""`
   attributes are allowed; `button`, `input`, and `form` tags are stripped —
@@ -38,7 +72,7 @@ by re-applying an earlier template.
 - The split chrome is tunable from your template root's `style` attribute
   (`--zl-split-columns`, `--zl-split-align`, `--zl-split-brand-mobile`), and
   `zl-split--right` on the wrapper mirrors the panes. Knob reference:
-  `docs/design/branding/templates.md` in the Zitadel repo.
+  [`docs/design/branding/templates.md`](https://github.com/zitadel/nextgen/blob/main/docs/design/branding/templates.md).
 - The "Secured with Zitadel" attribution is licence-gated and on by default.
 - Back-navigation: the engine injects a `kind: "back"` action on steps
   that can return to their predecessor, and the browser's back gesture

package/defaults/README-flows.md

@@ -37,8 +37,25 @@ Typical edits:
   tokens).
 - **Add or remove a step** — extend `steps[]`.
 - **Rewire transitions** — edit `steps[].transitions` to point at a
-  different next step, or use `action: switch` / `pivot` to jump to
-  another flow.
+  different next step. Cross-flow jumps (`action: switch` / `pivot`)
+  validate in a definition but are **not yet executed by the runtime** —
+  submitting through one fails with a 400 (`code: "flow.unsupported"`);
+  keep transitions within one flow, using a purpose switch (next bullet)
+  for login ↔ register navigation.
+- **Offer a purpose switch in the card** — pair a `kind: navigate`
+  action with a transition that declares a local `purpose`. The default
+  login flow ships this in both directions:
+
+  ```json
+  "register": { "target": "register", "purpose": "register" }
+  ```
+
+  Navigation skips field validation (an empty email box can't block the
+  link), and the declared purpose is what makes the landing leg run with
+  the right semantics — register creates the user instead of trying to
+  verify one. Rules: the purpose must be one this flow's `purposes`
+  serves, the target must be that purpose's entry step, and `purpose`
+  never combines with `action` (which targets another flow instead).
 - **Add another flow** — drop a new JSON file with its own `purposes`
   and a distinct `name` (e.g. a per-team login). See
   [Multiple flows](#multiple-flows) for how it gets selected at runtime.
@@ -70,8 +87,8 @@ experiment can't silently take over `/login` — scope it or pin
 
 ## Presets
 
-`zitadel setup` scaffolds this folder from a preset (`--preset
-password-first` or `--preset passkey-first`). The passkey-first flow
+`zitadel setup` scaffolds this folder from a preset: `password-first` (the
+default root files) or `--preset passkey-first`. The passkey-first flow
 enters login on a fields-less passkey step with an email → password
 fallback path. The preset only decides the starting point — edit
 anything here afterwards.

package/defaults/README-schemas.md

@@ -16,7 +16,13 @@ Here's a simplified example:
 ``` json
 {
   "objectType": "customer",
+  "x-identifier": "email",
   "properties": {
+    "email": {
+      "type": "string",
+      "format": "email",
+      "x-unique": "project"
+    },
     "firstName": {
       "type": "string"
     },
@@ -25,11 +31,12 @@ Here's a simplified example:
     }
   },
   "required": [
+    "email",
     "firstName"
   ],
   "x-auth-methods": {
-    "password": { "enabled": true, "position": 1 },
-    "passkey": { "enabled": true, "position": 2 }
+    "password": { "enabled": true },
+    "passkey": { "enabled": true }
   }
 }
 ```

package/defaults/branding/centered/login.liquid

@@ -11,18 +11,9 @@
       {% endif %}
     {% endif %}
 
-    {% if errors and errors.size > 0 %}
-      {% for err in errors %}
-        {% if err | formLevelError %}
-          {% assign alert_heading = err.text_key | alertHeading %}
-          {% assign alert_body = err.text_key | alertBody %}
-          <zl-alert severity="error" dismissible data-zl-step-error{% if alert_heading != "" %} heading="{{ alert_heading | t }}"{% endif %}>
-            {% if alert_body != "" %}{{ alert_body | t }}{% elsif err.text_key %}{{ err.text_key | t }}{% else %}{{ err.message }}{% endif %}
-          </zl-alert>
-        {% endif %}
-      {% endfor %}
-    {% endif %}
-
+    {% assign recover = actions | where: "name", "recover" | first %}
+    {% assign password_field = fields | where: "type", "password" | first %}
+    <div class="zl-field-group">
     {% for f in fields %}
       {% assign field_placeholder = f.text_key | fieldPlaceholder %}
       {% assign field_help = f.text_key | fieldHelp %}
@@ -67,6 +58,7 @@
           {% if f.required %}required{% endif %}
           {% if field_placeholder != "" %}placeholder="{{ field_placeholder }}"{% endif %}
           {% if field_err != "" %}invalid error="{{ field_err }}"{% endif %}
+          {% if recover and f.type == 'password' %}forgot-password-href="#" forgot-password-action="{{ recover.name }}" forgot-password-label="{{ recover.text_key | t }}"{% endif %}
         >
           {% if field_help != "" %}
             <span slot="help">{{ field_help }}</span>
@@ -75,8 +67,31 @@
       {% endcase %}
     {% endfor %}
 
-    {% assign recover = actions | where: "name", "recover" | first %}
-    {% if recover %}
+    {% comment %}
+      Form-level errors close the field group rather than opening the card: the
+      design puts the alert directly above the actions, where it reads as a
+      reason the last attempt failed rather than a banner about the screen.
+    {% endcomment %}
+    {% if errors and errors.size > 0 %}
+      {% for err in errors %}
+        {% if err | formLevelError %}
+          {% assign alert_heading = err.text_key | alertHeading %}
+          {% assign alert_body = err.text_key | alertBody %}
+          <zl-alert data-zl-step-error{% if alert_heading != "" %} heading="{{ alert_heading | t }}"{% endif %}>
+            {% if alert_body != "" %}{{ alert_body | t }}{% elsif err.text_key %}{{ err.text_key | t }}{% else %}{{ err.message }}{% endif %}
+          </zl-alert>
+        {% endif %}
+      {% endfor %}
+    {% endif %}
+    </div>
+
+    <div class="zl-card-actions">
+    {% comment %}
+      A step can offer recovery without asking for a password (an identifier-only
+      screen, say). With no label row to sit on, the affordance keeps its own row
+      rather than disappearing.
+    {% endcomment %}
+    {% if recover and password_field == nil %}
       <p class="zl-card-forgot">
         <a href="#" class="zl-card-forgot__link" data-action="recover">{{ recover.text_key | t }}</a>
       </p>
@@ -139,6 +154,7 @@
         {{ 'register.action.sign_in.lead' | t }}<a href="#" class="zl-card-nav__link" data-action="sign_in" data-testid="zitadel-action-sign_in-link">{{ 'register.action.sign_in.link' | t }}</a>
       </p>
     {% endif %}
+    </div>
 
     {% if challenge %}
       {% if challenge.method == "passkey" or challenge.method == "passkey_register" %}

package/defaults/branding/hero/login.liquid

@@ -19,7 +19,8 @@
         <nav class="zl-hero__nav">
           <span class="zl-hero__brand">
             {% if branding.logo_url %}
-              <img class="zl-hero__brand-logo" src="{{ branding.logo_url }}" alt="" />
+              <img class="zl-hero__brand-logo" src="{{ branding.logo_url }}" alt="" data-zl-asset-fallback />
+              <span class="zl-hero__brand-mark" aria-hidden="true" hidden data-zl-asset-fallback-content></span>
             {% else %}
               <span class="zl-hero__brand-mark" aria-hidden="true"></span>
             {% endif %}
@@ -54,7 +55,8 @@
     </aside>
     <section class="zl-split__form">
     {% if branding.logo_url %}
-      <img class="zl-split__compact" src="{{ branding.logo_url }}" alt="" />
+      <img class="zl-split__compact" src="{{ branding.logo_url }}" alt="" data-zl-asset-fallback />
+      <p class="zl-split__compact zl-hero__compact-brand" hidden data-zl-asset-fallback-content>Your brand</p>
     {% else %}
       <p class="zl-split__compact zl-hero__compact-brand">Your brand</p>
     {% endif %}
@@ -67,18 +69,9 @@
         {% endif %}
       {% endif %}
 
-      {% if errors and errors.size > 0 %}
-        {% for err in errors %}
-          {% if err | formLevelError %}
-            {% assign alert_heading = err.text_key | alertHeading %}
-            {% assign alert_body = err.text_key | alertBody %}
-            <zl-alert severity="error" dismissible data-zl-step-error{% if alert_heading != "" %} heading="{{ alert_heading | t }}"{% endif %}>
-              {% if alert_body != "" %}{{ alert_body | t }}{% elsif err.text_key %}{{ err.text_key | t }}{% else %}{{ err.message }}{% endif %}
-            </zl-alert>
-          {% endif %}
-        {% endfor %}
-      {% endif %}
-
+      {% assign recover = actions | where: "name", "recover" | first %}
+      {% assign password_field = fields | where: "type", "password" | first %}
+      <div class="zl-field-group">
       {% for f in fields %}
         {% assign field_placeholder = f.text_key | fieldPlaceholder %}
         {% assign field_help = f.text_key | fieldHelp %}
@@ -123,6 +116,7 @@
             {% if f.required %}required{% endif %}
             {% if field_placeholder != "" %}placeholder="{{ field_placeholder }}"{% endif %}
             {% if field_err != "" %}invalid error="{{ field_err }}"{% endif %}
+            {% if recover and f.type == 'password' %}forgot-password-href="#" forgot-password-action="{{ recover.name }}" forgot-password-label="{{ recover.text_key | t }}"{% endif %}
           >
             {% if field_help != "" %}
               <span slot="help">{{ field_help }}</span>
@@ -131,8 +125,26 @@
         {% endcase %}
       {% endfor %}
 
-      {% assign recover = actions | where: "name", "recover" | first %}
-      {% if recover %}
+      {% if errors and errors.size > 0 %}
+        {% for err in errors %}
+          {% if err | formLevelError %}
+            {% assign alert_heading = err.text_key | alertHeading %}
+            {% assign alert_body = err.text_key | alertBody %}
+            <zl-alert data-zl-step-error{% if alert_heading != "" %} heading="{{ alert_heading | t }}"{% endif %}>
+              {% if alert_body != "" %}{{ alert_body | t }}{% elsif err.text_key %}{{ err.text_key | t }}{% else %}{{ err.message }}{% endif %}
+            </zl-alert>
+          {% endif %}
+        {% endfor %}
+      {% endif %}
+      </div>
+
+      <div class="zl-card-actions">
+      {% comment %}
+        A step can offer recovery without asking for a password (an identifier-only
+        screen, say). With no label row to sit on, the affordance keeps its own row
+        rather than disappearing.
+      {% endcomment %}
+      {% if recover and password_field == nil %}
         <p class="zl-card-forgot">
           <a href="#" class="zl-card-forgot__link" data-action="recover">{{ recover.text_key | t }}</a>
         </p>
@@ -181,7 +193,6 @@
         {% endunless %}
       {% endif %}
 
-
       {% assign register = actions | where: "name", "register" | first %}
       {% if register %}
         <p class="zl-card-nav">
@@ -195,6 +206,7 @@
           {{ 'register.action.sign_in.lead' | t }}<a href="#" class="zl-card-nav__link" data-action="sign_in" data-testid="zitadel-action-sign_in-link">{{ 'register.action.sign_in.link' | t }}</a>
         </p>
       {% endif %}
+      </div>
 
       {% if challenge %}
         {% if challenge.method == "passkey" or challenge.method == "passkey_register" %}
@@ -217,6 +229,10 @@
 
       {% mandatory_gates %}
     </zl-card>
+    {% comment %} The orchestrator swaps this for the trustmark, so it sits with
+       the card rather than under the seam between the panes. Removing it falls
+       back to the page-shell footer. {% endcomment %}
+    <div data-zl-attribution-anchor></div>
     </section>
   </div>
 </zl-page-shell>

package/defaults/branding/minimal/login.liquid

@@ -2,18 +2,9 @@
   <section class="zl-minimal">
     <h1 class="zl-card-title">{{ step.texts.title_key | t: identity.display_name }}</h1>
 
-    {% if errors and errors.size > 0 %}
-      {% for err in errors %}
-        {% if err | formLevelError %}
-          {% assign alert_heading = err.text_key | alertHeading %}
-          {% assign alert_body = err.text_key | alertBody %}
-          <zl-alert severity="error" dismissible data-zl-step-error{% if alert_heading != "" %} heading="{{ alert_heading | t }}"{% endif %}>
-            {% if alert_body != "" %}{{ alert_body | t }}{% elsif err.text_key %}{{ err.text_key | t }}{% else %}{{ err.message }}{% endif %}
-          </zl-alert>
-        {% endif %}
-      {% endfor %}
-    {% endif %}
-
+    {% assign recover = actions | where: "name", "recover" | first %}
+    {% assign password_field = fields | where: "type", "password" | first %}
+    <div class="zl-field-group">
     {% for f in fields %}
       {% assign field_placeholder = f.text_key | fieldPlaceholder %}
       {% assign field_help = f.text_key | fieldHelp %}
@@ -58,6 +49,7 @@
           {% if f.required %}required{% endif %}
           {% if field_placeholder != "" %}placeholder="{{ field_placeholder }}"{% endif %}
           {% if field_err != "" %}invalid error="{{ field_err }}"{% endif %}
+          {% if recover and f.type == 'password' %}forgot-password-href="#" forgot-password-action="{{ recover.name }}" forgot-password-label="{{ recover.text_key | t }}"{% endif %}
         >
           {% if field_help != "" %}
             <span slot="help">{{ field_help }}</span>
@@ -66,8 +58,26 @@
       {% endcase %}
     {% endfor %}
 
-    {% assign recover = actions | where: "name", "recover" | first %}
-    {% if recover %}
+    {% if errors and errors.size > 0 %}
+      {% for err in errors %}
+        {% if err | formLevelError %}
+          {% assign alert_heading = err.text_key | alertHeading %}
+          {% assign alert_body = err.text_key | alertBody %}
+          <zl-alert data-zl-step-error{% if alert_heading != "" %} heading="{{ alert_heading | t }}"{% endif %}>
+            {% if alert_body != "" %}{{ alert_body | t }}{% elsif err.text_key %}{{ err.text_key | t }}{% else %}{{ err.message }}{% endif %}
+          </zl-alert>
+        {% endif %}
+      {% endfor %}
+    {% endif %}
+    </div>
+
+    <div class="zl-card-actions">
+    {% comment %}
+      A step can offer recovery without asking for a password (an identifier-only
+      screen, say). With no label row to sit on, the affordance keeps its own row
+      rather than disappearing.
+    {% endcomment %}
+    {% if recover and password_field == nil %}
       <p class="zl-card-forgot">
         <a href="#" class="zl-card-forgot__link" data-action="recover">{{ recover.text_key | t }}</a>
       </p>
@@ -129,6 +139,7 @@
         {{ 'register.action.sign_in.lead' | t }}<a href="#" class="zl-card-nav__link" data-action="sign_in" data-testid="zitadel-action-sign_in-link">{{ 'register.action.sign_in.link' | t }}</a>
       </p>
     {% endif %}
+    </div>
 
     {% if challenge %}
       {% if challenge.method == "passkey" or challenge.method == "passkey_register" %}

package/defaults/branding/split/login.liquid

@@ -7,6 +7,11 @@
       {% if branding.hero_url %}
         <img class="zl-split__hero" src="{{ branding.hero_url }}" alt="" />
       {% endif %}
+      {% unless branding.logo_url or branding.hero_url %}
+        {% comment %} Until branding.json names an asset, a decorative panel
+           keeps the split composition readable. {% endcomment %}
+        <div class="zl-split__placeholder" aria-hidden="true"></div>
+      {% endunless %}
     </aside>
     <section class="zl-split__form">
     {% if branding.logo_url %}
@@ -23,18 +28,9 @@
         {% endif %}
       {% endif %}
 
-      {% if errors and errors.size > 0 %}
-        {% for err in errors %}
-          {% if err | formLevelError %}
-            {% assign alert_heading = err.text_key | alertHeading %}
-            {% assign alert_body = err.text_key | alertBody %}
-            <zl-alert severity="error" dismissible data-zl-step-error{% if alert_heading != "" %} heading="{{ alert_heading | t }}"{% endif %}>
-              {% if alert_body != "" %}{{ alert_body | t }}{% elsif err.text_key %}{{ err.text_key | t }}{% else %}{{ err.message }}{% endif %}
-            </zl-alert>
-          {% endif %}
-        {% endfor %}
-      {% endif %}
-
+      {% assign recover = actions | where: "name", "recover" | first %}
+      {% assign password_field = fields | where: "type", "password" | first %}
+      <div class="zl-field-group">
       {% for f in fields %}
         {% assign field_placeholder = f.text_key | fieldPlaceholder %}
         {% assign field_help = f.text_key | fieldHelp %}
@@ -79,6 +75,7 @@
             {% if f.required %}required{% endif %}
             {% if field_placeholder != "" %}placeholder="{{ field_placeholder }}"{% endif %}
             {% if field_err != "" %}invalid error="{{ field_err }}"{% endif %}
+            {% if recover and f.type == 'password' %}forgot-password-href="#" forgot-password-action="{{ recover.name }}" forgot-password-label="{{ recover.text_key | t }}"{% endif %}
           >
             {% if field_help != "" %}
               <span slot="help">{{ field_help }}</span>
@@ -87,8 +84,26 @@
         {% endcase %}
       {% endfor %}
 
-      {% assign recover = actions | where: "name", "recover" | first %}
-      {% if recover %}
+      {% if errors and errors.size > 0 %}
+        {% for err in errors %}
+          {% if err | formLevelError %}
+            {% assign alert_heading = err.text_key | alertHeading %}
+            {% assign alert_body = err.text_key | alertBody %}
+            <zl-alert data-zl-step-error{% if alert_heading != "" %} heading="{{ alert_heading | t }}"{% endif %}>
+              {% if alert_body != "" %}{{ alert_body | t }}{% elsif err.text_key %}{{ err.text_key | t }}{% else %}{{ err.message }}{% endif %}
+            </zl-alert>
+          {% endif %}
+        {% endfor %}
+      {% endif %}
+      </div>
+
+      <div class="zl-card-actions">
+      {% comment %}
+        A step can offer recovery without asking for a password (an identifier-only
+        screen, say). With no label row to sit on, the affordance keeps its own row
+        rather than disappearing.
+      {% endcomment %}
+      {% if recover and password_field == nil %}
         <p class="zl-card-forgot">
           <a href="#" class="zl-card-forgot__link" data-action="recover">{{ recover.text_key | t }}</a>
         </p>
@@ -137,7 +152,6 @@
         {% endunless %}
       {% endif %}
 
-
       {% assign register = actions | where: "name", "register" | first %}
       {% if register %}
         <p class="zl-card-nav">
@@ -151,6 +165,7 @@
           {{ 'register.action.sign_in.lead' | t }}<a href="#" class="zl-card-nav__link" data-action="sign_in" data-testid="zitadel-action-sign_in-link">{{ 'register.action.sign_in.link' | t }}</a>
         </p>
       {% endif %}
+      </div>
 
       {% if challenge %}
         {% if challenge.method == "passkey" or challenge.method == "passkey_register" %}
@@ -173,6 +188,10 @@
 
       {% mandatory_gates %}
     </zl-card>
+    {% comment %} The orchestrator swaps this for the trustmark, so it sits with
+       the card rather than under the seam between the panes. Removing it falls
+       back to the page-shell footer. {% endcomment %}
+    <div data-zl-attribution-anchor></div>
     </section>
   </div>
 </zl-page-shell>

package/defaults/branding/split-right/login.liquid

@@ -7,6 +7,11 @@
       {% if branding.hero_url %}
         <img class="zl-split__hero" src="{{ branding.hero_url }}" alt="" />
       {% endif %}
+      {% unless branding.logo_url or branding.hero_url %}
+        {% comment %} Until branding.json names an asset, a decorative panel
+           keeps the split composition readable. {% endcomment %}
+        <div class="zl-split__placeholder" aria-hidden="true"></div>
+      {% endunless %}
     </aside>
     <section class="zl-split__form">
     {% if branding.logo_url %}
@@ -23,18 +28,9 @@
         {% endif %}
       {% endif %}
 
-      {% if errors and errors.size > 0 %}
-        {% for err in errors %}
-          {% if err | formLevelError %}
-            {% assign alert_heading = err.text_key | alertHeading %}
-            {% assign alert_body = err.text_key | alertBody %}
-            <zl-alert severity="error" dismissible data-zl-step-error{% if alert_heading != "" %} heading="{{ alert_heading | t }}"{% endif %}>
-              {% if alert_body != "" %}{{ alert_body | t }}{% elsif err.text_key %}{{ err.text_key | t }}{% else %}{{ err.message }}{% endif %}
-            </zl-alert>
-          {% endif %}
-        {% endfor %}
-      {% endif %}
-
+      {% assign recover = actions | where: "name", "recover" | first %}
+      {% assign password_field = fields | where: "type", "password" | first %}
+      <div class="zl-field-group">
       {% for f in fields %}
         {% assign field_placeholder = f.text_key | fieldPlaceholder %}
         {% assign field_help = f.text_key | fieldHelp %}
@@ -79,6 +75,7 @@
             {% if f.required %}required{% endif %}
             {% if field_placeholder != "" %}placeholder="{{ field_placeholder }}"{% endif %}
             {% if field_err != "" %}invalid error="{{ field_err }}"{% endif %}
+            {% if recover and f.type == 'password' %}forgot-password-href="#" forgot-password-action="{{ recover.name }}" forgot-password-label="{{ recover.text_key | t }}"{% endif %}
           >
             {% if field_help != "" %}
               <span slot="help">{{ field_help }}</span>
@@ -87,8 +84,26 @@
         {% endcase %}
       {% endfor %}
 
-      {% assign recover = actions | where: "name", "recover" | first %}
-      {% if recover %}
+      {% if errors and errors.size > 0 %}
+        {% for err in errors %}
+          {% if err | formLevelError %}
+            {% assign alert_heading = err.text_key | alertHeading %}
+            {% assign alert_body = err.text_key | alertBody %}
+            <zl-alert data-zl-step-error{% if alert_heading != "" %} heading="{{ alert_heading | t }}"{% endif %}>
+              {% if alert_body != "" %}{{ alert_body | t }}{% elsif err.text_key %}{{ err.text_key | t }}{% else %}{{ err.message }}{% endif %}
+            </zl-alert>
+          {% endif %}
+        {% endfor %}
+      {% endif %}
+      </div>
+
+      <div class="zl-card-actions">
+      {% comment %}
+        A step can offer recovery without asking for a password (an identifier-only
+        screen, say). With no label row to sit on, the affordance keeps its own row
+        rather than disappearing.
+      {% endcomment %}
+      {% if recover and password_field == nil %}
         <p class="zl-card-forgot">
           <a href="#" class="zl-card-forgot__link" data-action="recover">{{ recover.text_key | t }}</a>
         </p>
@@ -137,7 +152,6 @@
         {% endunless %}
       {% endif %}
 
-
       {% assign register = actions | where: "name", "register" | first %}
       {% if register %}
         <p class="zl-card-nav">
@@ -151,6 +165,7 @@
           {{ 'register.action.sign_in.lead' | t }}<a href="#" class="zl-card-nav__link" data-action="sign_in" data-testid="zitadel-action-sign_in-link">{{ 'register.action.sign_in.link' | t }}</a>
         </p>
       {% endif %}
+      </div>
 
       {% if challenge %}
         {% if challenge.method == "passkey" or challenge.method == "passkey_register" %}
@@ -173,6 +188,10 @@
 
       {% mandatory_gates %}
     </zl-card>
+    {% comment %} The orchestrator swaps this for the trustmark, so it sits with
+       the card rather than under the seam between the panes. Removing it falls
+       back to the page-shell footer. {% endcomment %}
+    <div data-zl-attribution-anchor></div>
     </section>
   </div>
 </zl-page-shell>

package/defaults/default-human-user.json

@@ -6,15 +6,14 @@
   "objectType": "human-user",
   "kind": "user-schema",
   "type": "object",
+  "x-identifier": "email",
   "description": "The default editable schema for human users.",
   "x-auth-methods": {
     "password": {
-      "enabled": true,
-      "position": 1
+      "enabled": true
     },
     "passkey": {
-      "enabled": true,
-      "position": 2
+      "enabled": true
     }
   },
   "required": [

package/defaults/default-login.json

@@ -25,6 +25,12 @@
           "kind": "passkey",
           "primary": false,
           "text_key": "identifier.action.passkey"
+        },
+        {
+          "name": "register",
+          "kind": "navigate",
+          "primary": false,
+          "text_key": "identifier.action.register.link"
         }
       ],
       "transitions": {
@@ -36,6 +42,10 @@
         },
         "user_not_found": {
           "target": "register"
+        },
+        "register": {
+          "target": "register",
+          "purpose": "register"
         }
       }
     },
@@ -84,6 +94,12 @@
           "kind": "passkey_register",
           "primary": false,
           "text_key": "register.action.passkey"
+        },
+        {
+          "name": "sign_in",
+          "kind": "navigate",
+          "primary": false,
+          "text_key": "register.action.sign_in.link"
         }
       ],
       "transitions": {
@@ -95,6 +111,10 @@
         },
         "user_already_exists": {
           "target": "password"
+        },
+        "sign_in": {
+          "target": "identifier",
+          "purpose": "login"
         }
       }
     },