@zitadel/cli 0.3.0 → 0.4.0

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

@@ -0,0 +1,124 @@
+### Driving the login UI
+
+`<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
+pierce shadow roots recursively:
+
+```js
+function deepQuery(sel, root = document) {
+  const hit = root.querySelector(sel);
+  if (hit) return hit;
+  for (const el of root.querySelectorAll("*")) {
+    if (el.shadowRoot) {
+      const result = deepQuery(sel, el.shadowRoot);
+      if (result) return result;
+    }
+  }
+  return null;
+}
+```
+
+Use host hooks such as `zitadel-field-email`, `zitadel-field-password`, and
+`zitadel-action-submit` when targeting the Lit atoms. Use native shadow-control
+hooks such as `zitadel-input-email`, `zitadel-input-password`, and
+`zitadel-action-submit-button` when filling or clicking the underlying input or
+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, 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.
+
+Repo config is authoritative: edit `zitadel.json` or files under `.zitadel/`,
+then re-run `deploy` (or `deploy --dry-run` to validate and preview the diff
+without publishing). Schema and flow files are synced from
+`.zitadel/schemas/*.json` and `.zitadel/flows/*.json`. Login templates
+(branding) are synced from `.zitadel/branding/`: a single `branding.json`
+descriptor (layout, asset URLs) plus a sibling `login.liquid` LiquidJS
+template referenced as `"liquid_template": { "$file": "./login.liquid" }`. Scaffold them with the
+`branding eject` command (`--design centered|minimal`,
+interactive picker on a TTY); setup never scaffolds them. Branding is
+revisioned and immutable: every edit — including a `.liquid`-only edit —
+is published as part of the next release when you `deploy`, and the login
+serves the newest release. `deploy` validates templates with the authoritative
+LiquidJS validator (and `deploy --dry-run` runs the same validation without
+publishing; `E_VALIDATION` lists rule ids such as `no-script-tag` and
+`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 is published as a new immutable flow revision
+in the next `deploy`. 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 `deploy` checks each flow
+against the schema it names. 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 deployed
+without one doesn't take that earlier revision out of the running. Removing a
+flow file does not retire the
+flow. Operation policies live in `.zitadel/policies/`: one `<operation>.json`
+per guarded operation, named after its `operation`, holding
+`{"$schema": "../meta/policy.json", "operation": "auth.factor.password.set",
+"config": {"min_length": 15}}`. `deploy` checks each file against
+`.zitadel/meta/policy.json` (known operation, only the template's settings,
+within their bounds) and its name before anything is sent; settings that
+contradict each other (a `min_length` above `max_length`) are refused by the
+server's release build with `rel.invalid`, the policy's entry carrying
+`pol.invalid`. A changed file publishes a new revision of the same policy,
+which applies the next time a password is set. A setting left out is off, and
+`"config": {}` switches every rule off. A sign-in or sign-up uses the policy
+the deployed release carries, so deploying without the file switches it off
+there; a password set through the API, or before the first deploy, uses the
+newest revision, which only `"config": {}` switches off. `policies list` and
+`policies get <id|operation>` read them back. A policy's cases live beside it
+in `<operation>.test.json` (`.zitadel/meta/policy-test.json`): each names an
+`input` in the operation's terms (`{"password": "…"}`), optional `facts` the
+operation would look up (`self_service`, `history_matches`), and the expected
+decision (`allowed`, optionally `code` and exactly the `violations`). The
+decision and rules hold in the login too; `code` is the API's answer, and a
+flow shows each rule as `error.x-auth-methods#password_<rule>` instead.
+`policies test [operation]` evaluates every case on the server against the
+sibling policy file, or with `--release <id>` against the revision that
+release pins; a missing policy is tested as none. It fails with `E_VALIDATION`
+(exit 3) when a case does not hold, `data`/`details` carrying `source`,
+`operations[].cases[]` (`name`, `passed`, `expected`, `actual`), `passed` and
+`failed`; with no test files it is `skipped` (`no-policy-tests`). `deploy`
+never carries test files. Until #2331, a release that pins no flow is tested
+with a warning: its sign-ins use the newest revisions instead. Write cases from
+what the user wants enforced; never invent expectations for them. `setup` writes and publishes
+the password policy with a `min_length` of 15; pass `--password-min-length <n>`
+only when the user asks for another value (`0` sets none). 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@latest 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/skills/zitadel-components/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: zitadel-components
+description: >-
+  Embed, theme, customise, or drive the Zitadel login web component directly —
+  the framework-agnostic `<zitadel-login>` / `<zitadel-logout>` Lit elements
+  from `@zitadel/components`. Use when dropping the login widget onto a plain
+  HTML page, styling it with `--zl-*` design tokens or `::part(...)` hooks,
+  pinning its theme/variant/locale, wiring its flow events, or automating it in
+  a browser via its shadow-DOM hooks — i.e. using the Zitadel login widget
+  itself, outside any framework SDK wrapper.
+---
+
+# @zitadel/components
+
+Lit web components for the Zitadel auth UI: the `<zitadel-login>` orchestrator
+(a drop-in element that calls the flow API and renders every step),
+`<zitadel-logout>` / `<zitadel-session>`, and the `<zl-*>` atoms.
+
+## When to use
+
+Use this skill when you embed, theme, or automate the login/logout web
+component **directly** — on a static page, in a server-rendered app, or inside
+any shell where you hold the custom element yourself. The framework SDK skills
+(Next, Nuxt, React, etc.) wrap this same element for a specific framework; reach
+for those when the user is in that framework. Reach for this one when the work
+is the component itself: attributes, tokens, parts, events, shadow-DOM hooks.
+
+## Install / use
+
+```sh
+corepack pnpm add @zitadel/components@latest
+```
+
+`lit`, `liquidjs`, `dompurify` are externalised peer/runtime deps (consumers
+dedupe their own copies). A CDN `standalone` build is published (`unpkg` /
+`jsdelivr` → `./dist/standalone.mjs`). Subpath exports exist for `./atoms`,
+`./orchestrator`, `./tokens`, `./manifests`, and JSX types at `./jsx`. Importing
+the barrel side-effect-registers every element; import leaf subpaths to
+tree-shake.
+
+## Embed & configure
+
+Configure the SDK once, then drop the element — it reads the global project
+handle from `configureZitadel()` via `getZitadelConfig()`:
+
+```html
+<script type="module">
+  import '@zitadel/components';
+  import { configureZitadel } from '@zitadel/api/config';
+  configureZitadel({ projectId: 'proj_123', proxyPath: '/__nextgen' });
+</script>
+<zitadel-login id="login" variant="page" purpose="login"></zitadel-login>
+```
+
+`<zitadel-login>` props (the authoritative list is in the README table and the
+TS types — discover, don't assume): `variant` (`widget` default: content-sized,
+transparent, no font injection, no focus grab / `page`: full-page chrome),
+`theme` (`light`/`dark`/`auto`, resolved value lands on `data-theme`), `purpose`
+(`login`/`register`/`reset_password`/…), `flow-name`, `project` (object property,
+not an attribute — assign via `ref`/JS, not markup), `lang` + `locales`,
+`post-sign-in-url` (`force-post-sign-in-url`: see below), `resume-flow-id`,
+`preview-state` / `preview-success-step`.
+After sign-in the widget returns to the path in the page's `next` query
+parameter, which every server SDK's middleware sets when it sends a signed-out
+visit to a protected route to the login page, and goes to `post-sign-in-url`
+when there is none or it is not a path on the page's origin. A page that uses
+`next` for something of its own sets `force-post-sign-in-url`.
+It emits `zitadel-flow-input`, `-step`, `-complete`, `-error`, `-redirect`
+events (`-step` fires for every step including the first; `-redirect` is a
+non-cancelable notification — the widget navigates to the IdP itself).
+
+`<zitadel-logout>`: `project`, `post-sign-out-url`; supports a light-DOM
+`<template>` slot for a custom menu.
+
+Theming levers (strongest-first resolution, documented in the README):
+
+- **Host CSS tokens** — set `--zl-*` custom properties in your own stylesheet on
+  `zitadel-login { ... }`. These inherit across shadow boundaries and **outrank**
+  both the design-system defaults and server-side tenant branding. The stable
+  names are listed in
+  [Customize the login design](https://preview.zitadel.com/docs/guides/customize-design.md).
+- **`::part(...)`** — e.g. `zitadel-login::part(form)`, `::part(field-input)`,
+  `::part(button-root)`. Atom parts forward through the orchestrator as
+  `<atom>-<part>`; bare names (`zl-field::part(input)`) apply when composing
+  atoms directly.
+- **`variant` + `--zl-page-min-height`** for sizing/placement; width-responsive
+  chrome keys off the widget's own width (container queries).
+- Server branding payload, and a tenant Liquid template via the payload's
+  `liquid_template` field (a declarative `template` attribute is not yet
+  exposed).
+- **`suppress-header`** (boolean attribute, reflected) hides the widget's own
+  heading — use it when the host page already shows a title and you want to
+  avoid a duplicate. The login moves between sign-in and sign-up by itself, so
+  that title must follow its `zitadel-flow-step` event: `step.purpose` is
+  `login` or `register`.
+  Otherwise control chrome through `variant` and tokens.
+- **`suppress-password-toggle`** (boolean attribute) hides the show/hide button
+  the login shows on password fields by default. It applies to custom Liquid
+  templates too; templates have nothing to wire.
+
+Automation hooks (stable `data-testid`s the default template emits): host atoms
+`zitadel-field-email` / `zitadel-field-password` / `zitadel-action-submit`;
+native shadow controls `zitadel-input-email` / `zitadel-input-password` /
+`zitadel-action-submit-button`. Hooks are method-named even when the flow engine
+names a credential field `x-auth-methods#<method>` — the `name` attribute keeps
+the raw wire key; only the hook is normalised (`hookName` in
+`src/internal/hook-name.ts`). For sign-out, the button inside `<zitadel-session>`
+(the signed-in card setup's profile pages render) carries
+`zitadel-session-logout`, and its native button `zitadel-session-logout-button`.
+`<zitadel-logout>` has no hook: open its avatar menu ("Open user menu"), then
+pierce to `.signout-btn`. Given a `<template>` child, it shows no menu, and the
+element marked `data-action="logout"` signs out.
+
+## Read these, don't guess
+
+The component surface moves faster than any list here, so treat these as
+authoritative and discover the current shape first:
+
+- `node_modules/@zitadel/components/README.md` — the element API tables, the
+  customisation tiers, and the **canonical hook list** live here.
+- The published TypeScript types (`./dist/index.d.mts` and the `./atoms`,
+  `./orchestrator`, `./tokens`, `./jsx` subpaths) — exact prop/event/manifest
+  shapes.
+- [Customize the login design](https://preview.zitadel.com/docs/guides/customize-design.md)
+  — the stable `--zl-*` tokens and the `::part()` names the login forwards.
+- Per-atom manifests (`@zitadel/components/manifests`) — the allowed
+  attributes/parts/events for each atom.
+
+Read the pattern, then confirm the specific attribute/part/token/event against
+these before writing it — don't reproduce a catalogue from memory.
+
+## Gotchas
+
+- **Server rendering.** If your app renders on the server, mount the widget on the client only, after hydration, or give a raw `<zitadel-login>` element `project-id` and `proxy-path` as attributes, because a widget that starts before its configuration arrives shows an error instead of the flow.
+- **Open shadow roots, nested.** The automation hooks sit inside nested shadow
+  roots, so a flat `document.querySelector('[data-testid="zitadel-input-email"]')`
+  misses them. Use a shadow-aware locator (Playwright) or recurse through
+  `el.shadowRoot`. Enter submits the step only for key events carrying
+  `key: "Enter"`; CDP wrappers that omit it should click `zitadel-action-submit`.
+- **Same-origin proxy.** The element calls the typed `@zitadel/api` fetch client
+  directly with `credentials: "include"`; the stateless server's `_zflow`
+  HttpOnly cookie is the source of truth between requests. There is no transport
+  to swap — mock at the network layer (`@zitadel/api-mock` MSW handlers) for
+  offline/test.
+- **Theming through shadow DOM.** `--zl-*` custom properties inherit across
+  shadow boundaries, so host-page token overrides reach the atoms' own shadow
+  roots and win over `:host` defaults and server branding — deliberate, so an
+  embedding app matches its design system without a server round-trip. Internals
+  you can't reach with a token need `::part(...)`, not a descendant selector.
+- **`project` is a property, not an attribute** — it's a typed object, so set it
+  via JS/`ref` (or configure globally and let the element read it), never as
+  markup.

package/dist/skills/zitadel-sdk-angular/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: zitadel-sdk-angular
+description: >-
+  Integrate Zitadel authentication into an Angular app with
+  @zitadel/sdk-angular — the client-side SPA components for login,
+  registration, logout, and the signed-in session card. Use when adding or
+  wiring Zitadel auth, a login or registration screen, or session handling into
+  an Angular app, and especially when the app already exists and the CLI's
+  setup stops on it (then wire it in by hand with this skill).
+---
+
+# @zitadel/sdk-angular
+
+Angular wrapper components for the Zitadel auth UI in a client-side SPA.
+
+## When to use
+
+You are adding Zitadel login, registration, logout, or session handling to an
+Angular app and wiring the auth UI in by hand.
+
+The `zitadel` CLI scaffolds a *fresh* Angular app
+(`npx @zitadel/cli@latest setup --framework angular`) with this SDK already wired in. In an
+**existing** Angular app it writes the root component to `src/app/app.ts`, and
+stops with `E_CONFLICT` when the app has one there, or when `src/main.ts`
+bootstraps a root from another file (Angular 17–19's
+`src/app/app.component.ts`). When setup stops, follow this skill to install the
+package and wire the components in manually.
+
+## Install
+
+```sh
+npm install @zitadel/sdk-angular@latest
+```
+
+Peer dependencies: `@angular/core` and `@angular/common`, both `>=17`. Requires TypeScript ≥ 5.0 (the published types use `export type *`).
+
+## Integrate
+
+The components are **standalone** — import them directly into a component's
+`imports`. There is no NgModule, provider, or route guard to register.
+
+1. Build a project handle once with `configureZitadel(...)` and pass it to the
+   components via the `[project]` input:
+
+   ```ts
+   import { Component } from '@angular/core';
+   import { ZitadelLoginComponent, configureZitadel } from '@zitadel/sdk-angular';
+
+   const project = configureZitadel({ projectId: '…', proxyPath: '/__nextgen' });
+
+   @Component({
+     standalone: true,
+     imports: [ZitadelLoginComponent],
+     template: `<zitadel-auth-login
+       [project]="project"
+       purpose="login"
+       postSignInUrl="/"
+     />`,
+   })
+   export class LoginPage {
+     project = project;
+   }
+   ```
+
+2. Logout and the signed-in session card follow the same shape:
+
+   ```html
+   <zitadel-auth-logout [project]="project" postSignOutUrl="/login" />
+   <zitadel-auth-session [project]="project" postSignOutUrl="/login" />
+   ```
+
+3. Wire them into your routes as ordinary standalone components, e.g. a
+   `/login` route rendering `LoginPage` and a `/logout` route rendering a
+   component that imports `ZitadelLogoutComponent`. `purpose="login"` vs
+   `purpose="register"` on `<zitadel-auth-login>` selects sign-in vs
+   registration; `postSignInUrl` / `postSignOutUrl` are where the widget sends
+   the user afterwards.
+
+4. The widgets call `${proxyPath}/…` **same-origin** (default `/__nextgen`). For
+   local development you can instead point `proxyPath` straight at the backend
+   (cross-origin), e.g. `proxyPath: 'http://localhost:8080'` (the `zitadel start`
+   local runtime default port).
+
+## Widget props and events
+
+`ZitadelLogin`, `ZitadelLogout` and `ZitadelSession` take the props below, spelled the same in every SPA SDK. An unset prop keeps the widget's own default.
+
+| Prop | Type | Default | Widgets | Description |
+| --- | --- | --- | --- | --- |
+| `project` | `ZitadelProject` | unset | Login, Logout, Session | The handle from `configureZitadel(...)`. Wins over `projectId` and `proxyPath`. |
+| `projectId` | `string` | unset | Login, Logout, Session | Project id, read when no `project` handle is passed. |
+| `proxyPath` | `string` | `"/__nextgen"` | Login, Logout, Session | Same-origin path the widget calls. |
+| `purpose` | `CreateFlowBodyPurpose` | `"login"` | Login | Flow purpose. |
+| `flowName` | `string` | unset | Login | Runs the flow definition with this `name`; unset runs the project's default flow for the purpose. |
+| `postSignInUrl` | `string` | unset | Login | Where to navigate after a completed sign-in. When the page's `next` query parameter names a path on the same origin, as the server SDKs' middleware sets it for a signed-out visit to a protected route, the widget returns there instead. |
+| `forcePostSignInUrl` | `boolean` | `false` | Login | Navigates to `postSignInUrl` even when the page's `next` query parameter names a path, for a page that uses `next` for something of its own. |
+| `postSignOutUrl` | `string` | unset | Logout, Session | Where to navigate after sign-out. |
+| `resumeFlowId` | `string` or `null` | unset | Login | An existing flow's id to resume instead of starting a new flow; unset, `null` or `""` falls back to the `flow` query parameter, and an id that no longer resolves starts a new flow. |
+| `variant` | `"widget"` or `"page"` | `"widget"` | Login, Session | `widget` is content-sized and paints no page chrome; `page` claims the viewport, paints the surface background and loads the brand font, and on Login focuses the first field. |
+| `theme` | `"light"`, `"dark"` or `"auto"` | unset | Login, Logout, Session | Colour mode. Unset follows the tenant's branding theme on Login, then the variant default (`dark` for `page`, `auto` for `widget`); Logout defaults to `auto`. `auto` follows `prefers-color-scheme`. |
+| `suppressHeader` | `boolean` | `false` | Login, Session | Visually hides the widget's own heading block while keeping it in the accessibility tree, for pages that already carry the heading. |
+| `suppressPasswordToggle` | `boolean` | `false` | Login | Hides the show/hide button on password fields. |
+| `heading` | `string` | `"Signed in as"` | Session | Heading text override. |
+| `logoutLabel` | `string` | `"Sign out"` | Session | Logout action label override. |
+| `locales` | `Record<string, Partial<Record<string, string>>>` | unset | Login | Copy overrides merged over the builtin dictionaries, keyed by primary language subtag, for example `{ en: { "identifier.title": "Welcome back" } }`. |
+| `lang` | `string` | browser language | Login | BCP-47 language override. |
+
+Each widget event reaches the callback in the last column, which receives the event's `detail` payload.
+
+| Widget event | Fires when | Detail | Widgets | Callback |
+| --- | --- | --- | --- | --- |
+| `zitadel-flow-step` | Login shows a step, the first one included. | `{ step }` | Login | `(flowStep)` |
+| `zitadel-flow-input` | The visitor edits a field. | `{ name, value }` | Login | `(flowInput)` |
+| `zitadel-flow-complete` | The flow reaches a terminal step. | `{ behavior, redirect_uri?, handoff_token?, handoff_token_expires_at? }` | Login | `(flowComplete)` |
+| `zitadel-flow-redirect` | The widget hands the browser to an identity provider; nobody is signed in yet. | `{ redirect_url, step }` | Login | `(flowRedirect)` |
+| `zitadel-flow-error` | The flow reports an error. | `{ message }` | Login | `(flowError)` |
+| `zitadel-signout` | The user signs out. | `{ display, identifier }` | Logout, Session | `(signout)` |
+
+```html
+<zitadel-auth-login [project]="project" theme="light" (flowComplete)="track($event)" />
+```
+
+The `zitadel-flow-complete`, `zitadel-flow-redirect` and `zitadel-signout` details carry a `waitUntil(promise)`; call it from your handler to make the widget wait for your async work before it navigates.
+
+## Read these, don't guess
+
+This skill shows the *pattern*; it is not an API catalog and will drift. For
+exact names, inputs, and props, treat the installed package as authoritative:
+
+- `node_modules/@zitadel/sdk-angular/README.md` — the install, usage, and
+  proxy/deployment notes.
+- The TypeScript types / exports (`node_modules/@zitadel/sdk-angular/dist/types/public-api.d.ts`)
+  — the exported symbols (`ZitadelLoginComponent`, `ZitadelLogoutComponent`,
+  `ZitadelSessionComponent`, `configureZitadel`, `ZitadelConfig`,
+  `ZitadelProject`, `businessLocales`) and every component `@Input()` /
+  `@Output()`. Read them before using an input you are unsure of.
+
+## Gotchas
+
+- **Server rendering.** If your app renders on the server, mount the widget on the client only, after hydration (the `zitadel-auth-login` wrapper sets `projectId` and `proxyPath` as element properties, so adding them to the wrapper does not put them in server markup), or use a raw `<zitadel-login>` element with `project-id` and `proxy-path` as attributes, because a widget that starts before its configuration arrives shows an error instead of the flow.
+- **Selector is `zitadel-auth-login`, not `zitadel-login`.** The wrapper's
+  selector is `zitadel-auth-login` (and `zitadel-auth-logout`,
+  `zitadel-auth-session`); `<zitadel-login>` is the underlying custom element
+  the wrapper renders internally — don't use it directly.
+- **Production SPA deployment is not yet supported.** The same-origin
+  `${proxyPath}` must be provided by your hosting platform, and the CLI cannot
+  yet scaffold those configs. The CLI dev proxy covers local development only.
+- **Session card export name.** `<zitadel-auth-session>` is exported as
+  `ZitadelSessionComponent`.

package/dist/skills/zitadel-sdk-next/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: zitadel-sdk-next
+description: >-
+  Integrate Zitadel authentication into a Next.js App Router app with
+  @zitadel/sdk-next. Use whenever the user wants to add Zitadel login,
+  registration, logout, or session handling to a Next.js project — wiring the
+  auth middleware/proxy, reading sessions in Server or Client Components,
+  rendering the `<zitadel-login>` UI, or customizing an existing Zitadel + Next
+  integration.
+---
+
+# @zitadel/sdk-next
+
+Next.js middleware and helpers that wire the Zitadel auth UI and session
+verification into an App Router app.
+
+## When to use
+
+Use this when adding or customizing Zitadel auth in an **existing or custom**
+Next.js app, or when you need to understand how the pieces fit together.
+
+For a brand-new app, prefer the CLI: `npx @zitadel/cli@latest setup --framework next` scaffolds
+the whole integration (middleware, login page, env) and wires it for you. Reach
+for this skill when that scaffold already exists and you are editing it, or when
+the app is bespoke and you are integrating by hand.
+
+## Install
+
+```bash
+pnpm add @zitadel/sdk-next@latest
+```
+
+Peer deps the package expects: `next >=15.2.3`, `react >=18`, `react-dom >=18`.
+TypeScript `>=5.0` (the SDK consumer floor; the package is built against a
+newer TypeScript, but that does not raise the floor for your project).
+
+## Integrate
+
+The package has per-runtime entry points — import from the one that matches
+where the code runs, not the root, from client modules:
+
+| Import                         | Runs in                           | Provides                           |
+| ------------------------------ | --------------------------------- | ---------------------------------- |
+| `@zitadel/sdk-next/middleware` | Edge middleware                   | `nextgenMiddleware`, `createProxy` |
+| `@zitadel/sdk-next/server`     | Server Components, Route Handlers | `auth()`, `NextgenProvider`        |
+| `@zitadel/sdk-next/react`      | Client Components                 | `useAuth()`, `AuthContextProvider` |
+| `@zitadel/sdk-next/session`    | Client Components                 | `getSession()`                     |
+| `@zitadel/sdk-next/client`     | Client boundary                   | `configureZitadel()`, web components |
+| `@zitadel/sdk-next/components` | Client Components                 | `ZitadelLogin`, `ZitadelLogout`, `ZitadelSession` |
+
+**1. Request-boundary proxy.** It proxies `/__nextgen/*` to the auth backend
+(same-origin), verifies the session JWT via JWKS, and redirects unauthenticated
+users on protected routes. **The filename and exported function depend on the
+Next.js major version** — `proxy.ts`/`proxy` is Next 16+, while Next 15 uses the
+request middleware:
+
+- **Next 16+:** create `src/proxy.ts` exporting `proxy`.
+- **Next 15:** create `src/middleware.ts` exporting `middleware`.
+
+The body is the same either way (only the file and function name change):
+
+```ts
+// Next 16+: src/proxy.ts, exporting `proxy`.
+// Next 15:  src/middleware.ts, exporting `middleware` (rename the function).
+import { nextgenMiddleware } from '@zitadel/sdk-next/middleware';
+import type { NextRequest } from 'next/server';
+
+export function proxy(req: NextRequest) {
+  return nextgenMiddleware(req, {
+    url: process.env.ZITADEL_URL,
+    protectedRoutes: ['/admin', '/dashboard*'],
+    loginPath: '/login',
+  });
+}
+
+// Every route but Next.js's build files: protectedRoutes alone decides what
+// needs a sign-in. A protected route a narrower matcher leaves out stays public.
+export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] };
+```
+
+When unsure which the installed Next.js uses, check the CLI's own output — its
+patcher emits `middleware.ts` for Next 15 and `proxy.ts` for Next 16+.
+
+**2. Read the session server-side** with `auth()` (it re-verifies the tunnelled
+token — the header alone is never trusted):
+
+```tsx
+import { auth } from '@zitadel/sdk-next/server';
+
+// Render <Greeting /> inside <Suspense>: with Cache Components on (the
+// create-next-app default), Next.js refuses request data outside it.
+async function Greeting() {
+  const session = await auth();
+  if (!session.isAuthenticated) return <p>Not signed in</p>;
+  return <p>Hello {session.session.display ?? session.session.userId}</p>;
+}
+```
+
+**3. Seed client components** by rendering `NextgenProvider` (server-only — it
+strips the raw token before the server→client boundary) in your root layout,
+then read with `useAuth()` in any client component. For chrome on pages the
+matcher does not cover, read client-side with `getSession()` from
+`@zitadel/sdk-next/session` instead — it fetches same-origin
+`{proxyPath}/api/v1/sessions/me`.
+
+**4. Login page.** Render `ZitadelLogin` from `@zitadel/sdk-next/components`
+client-side only (via `next/dynamic` with `ssr: false`); call
+`configureZitadel({ projectId, proxyPath })` from the same entry inside the
+dynamic import, and set the `postSignInUrl` prop. `ZitadelLogout` and
+`ZitadelSession` exist for logout and profile UI. Sign-in/out navigate to `post-sign-in-url` /
+`post-sign-out-url`, so chrome re-reads on the next page load.
+
+## Widget props and events
+
+`ZitadelLogin`, `ZitadelLogout` and `ZitadelSession` from `@zitadel/sdk-next/components` are the `@zitadel/sdk-react` wrappers, so they take the same camelCase props, which the `@zitadel/sdk-react` skill lists. They set object props such as `project` and `locales` as element properties on React 18 and 19, through server-rendered hydration too. The table below lists the events and their callbacks.
+
+Each widget event reaches the callback in the last column, which receives the event's `detail` payload.
+
+| Widget event | Fires when | Detail | Widgets | Callback |
+| --- | --- | --- | --- | --- |
+| `zitadel-flow-step` | Login shows a step, the first one included. | `{ step }` | Login | `onFlowStep` |
+| `zitadel-flow-input` | The visitor edits a field. | `{ name, value }` | Login | `onFlowInput` |
+| `zitadel-flow-complete` | The flow reaches a terminal step. | `{ behavior, redirect_uri?, handoff_token?, handoff_token_expires_at? }` | Login | `onFlowComplete` |
+| `zitadel-flow-redirect` | The widget hands the browser to an identity provider; nobody is signed in yet. | `{ redirect_url, step }` | Login | `onFlowRedirect` |
+| `zitadel-flow-error` | The flow reports an error. | `{ message }` | Login | `onFlowError` |
+| `zitadel-signout` | The user signs out. | `{ display, identifier }` | Logout, Session | `onSignout` |
+
+```tsx
+<ZitadelLogin project={project} theme="light" onFlowComplete={(detail) => track(detail)} />
+```
+
+## Read these, don't guess
+
+This skill is the **pattern**, not an API catalog — it deliberately omits exact
+prop/option names so it does not drift with the package version. For the
+authoritative, version-correct specifics:
+
+- `node_modules/@zitadel/sdk-next/README.md` — the full setup walkthrough with
+  every code sample.
+- The package's TypeScript types (`.d.ts` per entry point) — exact exported
+  names, component props, `configureZitadel()` config, and the full middleware
+  options table (`proxyPath`, `ignoredRoutes`, `audience`, `allowedAlgorithms`,
+  timeouts, …).
+
+Confirm names against those before writing code.
+
+## Gotchas
+
+- **Never import the package root from a `"use client"` module.** The root
+  re-exports the server-only `auth()`; pulling it into a client graph fails the
+  build. Client code imports from `/react` or `/session` only.
+- **`NextgenProvider` is server-only** and must not be re-exported through a
+  `"use client"` `providers.tsx` wrapper — that would leak the unstripped token
+  into the RSC flight payload. To seed from client state, use
+  `AuthContextProvider` from `/react` (it only takes the token-less shape).
+- **Same-origin proxy is required.** The widgets and `getSession()` hit
+  `{proxyPath}/api/v1/sessions/me` on the same origin; the middleware `matcher` must
+  cover `{proxyPath}/:path*` or the proxy breaks.
+- **A protected route must be in the matcher too.** Next.js runs the
+  middleware only on routes the matcher covers, so a `protectedRoutes` entry a
+  narrower matcher misses is never redirected. Keep the every-route matcher.
+- **`auth()` only sees a session on routes the matcher covers.** A header on an
+  unmatched public page always looks signed out — use `getSession()` there.
+- **A rejected `getSession()` means *unknown*, not signed out** (broken proxy /
+  network / 5xx). Render a neutral or error state, never the signed-out CTA.
+- **Config handles:** `ZITADEL_URL` (backend, server-side),
+  `ZITADEL_PROJECT_ID` (server-side) and `NEXT_PUBLIC_ZITADEL_PROJECT_ID`
+  (passed to `configureZitadel`). If the middleware runs with custom
+  verification options, pass the same ones to `auth()` so both layers accept
+  the same tokens.
+- **Sessions count only in the app's own project:** `projectId`, else
+  `ZITADEL_PROJECT_ID`, else `NEXT_PUBLIC_ZITADEL_PROJECT_ID`. With none set,
+  nobody is signed in. A session of another project on the same host reads as
+  signed out.