@zitadel/config 1.0.0-alpha.21 → 1.0.0-alpha.23

package/meta-schemas/flow-definition.json

@@ -1,7 +1,7 @@
 {
+  "$comment": "Code generated by scripts/generate-meta-schemas.ts; DO NOT EDIT.",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "FlowDefinition",
-  "description": "Admin-authored configuration for a flow. A flow definition is a directed graph of steps backed by a user schema. The flow engine selects a definition based on `purpose` and `audience`, then walks the graph by evaluating `transitions` against client submissions.  This schema describes the configuration shape only. Runtime emission to the client (capability dictionaries, branding, localized text) is a separate concern and is not modelled here.",
   "type": "object",
   "required": [
     "name",
@@ -10,11 +10,12 @@
     "purposes",
     "steps"
   ],
+  "description": "A flow definition is the server-side configuration that describes a complete\nauthentication or identity flow. It is NOT sent to the frontend — the flow\nengine evaluates it and produces FlowResponse payloads (steps with capability\ndictionaries) for the client.\n\nFlow definitions are created by administrators and stored in the project/team\nconfiguration hierarchy. The engine selects the matching definition based on\nthe purpose + audience when a flow is created via POST /flow.\n",
   "additionalProperties": false,
   "properties": {
     "$schema": {
       "type": "string",
-      "description": "Editor affordance: path or URL of this meta-schema so editors validate and autocomplete the file (scaffolded flow files point at `.zitadel/meta/flow-definition.json`). Ignored by the platform."
+      "description": "Editor affordance: path or URL of this file's JSON meta-schema, so an\neditor validates and autocompletes it. The CLI strips it before upload;\nthe platform ignores it.\n"
     },
     "name": {
       "type": "string",
@@ -23,163 +24,363 @@
         "standard-login",
         "combined-auth"
       ],
-      "description": "Stable identifier for this flow, used as the target of cross-flow `switch` and `pivot` transitions. Renaming is not supported — the `name` is part of the public contract another definition may reference. Acts as the human display label as well; no separate slug."
+      "description": "Stable identifier for this flow, used as the target of cross-flow\n`switch` and `pivot` transitions. Every revision of a flow shares its\n`name`; publishing a definition under an existing `name` adds a\nrevision to that flow. Renaming is not supported — the `name` is part\nof the public contract another definition may reference. Acts as the\nhuman display label as well; no separate slug.\n"
     },
     "status": {
-      "type": "string",
-      "enum": [
-        "active",
-        "draft"
-      ],
-      "description": "Lifecycle state. - active: the engine can select this definition for new flows. - draft: never selected for new flows; existing flows referencing it must handle it gracefully."
+      "$ref": "#/$defs/FlowDefinitionStatus"
     },
     "user_schema": {
       "type": "string",
+      "description": "Server-assigned identifier of the user schema this flow operates on,\nas returned by `POST /schemas`. Opaque to the client — the shape is a\nserver implementation detail. Step `fields` reference properties\ndefined in the resolved schema; the engine resolves field types, validation, and\nimplicit outcomes from schema annotations at runtime.\n",
       "examples": [
         "sch_01KWHF18816ZQESRCS7Z2STJ05"
-      ],
-      "description": "Server-assigned identifier of the user schema this flow operates on, as returned by `POST /schemas`. Opaque to the client — the shape is a server implementation detail. Step `fields` reference property names defined in that schema; the engine resolves field type, validation, and implicit transition outcomes from the schema's `x-*` annotations at runtime."
+      ]
     },
     "purposes": {
       "type": "object",
+      "description": "Maps each purpose this definition handles to its entry-point step.\nKeys are purpose names; values must match a `name` in `steps`. A\ndefinition can serve multiple purposes (e.g. a combined login/register\nflow) by listing one entry per purpose.\n",
       "minProperties": 1,
       "propertyNames": {
-        "$ref": "#/$defs/Purpose"
+        "type": "string",
+        "enum": [
+          "login",
+          "register",
+          "recovery",
+          "profiling",
+          "reauth",
+          "link_account"
+        ]
       },
       "additionalProperties": {
-        "type": "string",
-        "description": "Name of an entry-point step within this definition."
+        "type": "string"
       },
       "examples": [
         {
           "login": "identify"
-        },
-        {
-          "login": "identify",
-          "register": "identify"
         }
-      ],
-      "description": "Maps each purpose this definition handles to the step that begins the flow for that purpose. Every value must match a `name` in `steps`; the check is enforced by the engine, not by this schema."
+      ]
     },
     "audience": {
-      "$ref": "#/$defs/Audience",
-      "description": "Scopes which requests this definition applies to. Omitted or empty arrays mean project-wide. The engine ranks matches by specificity (app > team > project-wide)."
+      "$ref": "#/$defs/FlowAudience",
+      "examples": [
+        {
+          "app_ids": [
+            "app_saas"
+          ]
+        }
+      ]
     },
     "steps": {
       "type": "array",
-      "minItems": 1,
       "items": {
-        "$ref": "#/$defs/Step"
+        "$ref": "#/$defs/FlowDefinitionStep"
       },
-      "description": "Step graph. Order is for human readability; actual sequencing is determined entirely by `transitions`. Every step's `name` must be unique within this array."
+      "minItems": 1,
+      "description": "Ordered list of steps in this flow. The order is for human readability —\nactual step sequencing is determined by transitions.\n",
+      "examples": [
+        [
+          {
+            "name": "identify",
+            "fields": [
+              "email"
+            ],
+            "actions": [
+              {
+                "name": "submit",
+                "kind": "submit",
+                "primary": true
+              }
+            ],
+            "transitions": {
+              "submit": {
+                "target": "authenticate"
+              },
+              "user_not_found": {
+                "target": "register",
+                "action": "switch"
+              }
+            }
+          },
+          {
+            "name": "authenticate",
+            "fields": [
+              "password"
+            ],
+            "actions": [
+              {
+                "name": "submit",
+                "kind": "submit",
+                "primary": true
+              }
+            ],
+            "transitions": {
+              "submit": {
+                "target": "done"
+              }
+            }
+          },
+          {
+            "name": "done",
+            "complete": "redirect"
+          }
+        ]
+      ]
     }
   },
   "$defs": {
-    "Purpose": {
+    "FlowDefinitionStatus": {
       "type": "string",
       "enum": [
-        "login",
-        "register",
-        "recovery",
-        "profiling",
-        "reauth",
-        "link_account"
+        "active",
+        "draft"
       ],
-      "description": "What the user is trying to accomplish. - login: authenticate an existing user. - register: create a new user. - recovery: recover access (e.g. password reset). - profiling: collect required profile fields after authentication. - reauth: re-verify factors on an active session for step-up. - link_account: attach an external identity to an existing user."
+      "description": "The lifecycle state of this flow definition. \n\nactive: The flow definition is ready to be used. The flow engine can select it for new flows.\ndraft: The engine will not select it for new flows, and existing flows must handle it gracefully if they reference this definition.\n\nA revision's status is fixed at creation. Publish a new revision to change it.\n"
     },
-    "Audience": {
+    "FlowAudience": {
       "type": "object",
       "additionalProperties": false,
+      "description": "Scopes which teams or apps this flow definition applies to. Empty or\nomitted fields mean \"no restriction\"; when both are empty the definition\nmatches every request in the project. The engine picks the most specific\nmatching definition: app > team > project-wide.\n",
       "properties": {
         "team_ids": {
           "type": "array",
-          "uniqueItems": true,
           "items": {
             "type": "string"
           },
+          "description": "Restrict to specific teams (organizations). Empty means no team restriction.",
+          "uniqueItems": true,
           "examples": [
             [
               "team_acme"
             ]
-          ],
-          "description": "Restrict to specific teams (organizations)."
+          ]
         },
         "app_ids": {
           "type": "array",
-          "uniqueItems": true,
           "items": {
             "type": "string"
           },
+          "description": "Restrict to specific applications. Empty means no app restriction.",
+          "uniqueItems": true,
           "examples": [
             [
-              "app_dashboard"
+              "app_saas"
             ]
-          ],
-          "description": "Restrict to specific applications."
+          ]
         }
       }
     },
-    "Step": {
+    "FlowDefinitionStep": {
       "type": "object",
       "required": [
         "name"
       ],
       "additionalProperties": false,
+      "not": {
+        "anyOf": [
+          {
+            "required": [
+              "sso_providers"
+            ],
+            "properties": {
+              "sso_providers": {
+                "minItems": 1
+              }
+            },
+            "anyOf": [
+              {
+                "not": {
+                  "required": [
+                    "transitions"
+                  ]
+                }
+              },
+              {
+                "properties": {
+                  "transitions": {
+                    "not": {
+                      "required": [
+                        "callback"
+                      ]
+                    }
+                  }
+                }
+              }
+            ]
+          },
+          {
+            "required": [
+              "complete"
+            ],
+            "anyOf": [
+              {
+                "required": [
+                  "fields"
+                ],
+                "properties": {
+                  "fields": {
+                    "minItems": 1
+                  }
+                }
+              },
+              {
+                "required": [
+                  "actions"
+                ],
+                "properties": {
+                  "actions": {
+                    "minItems": 1
+                  }
+                }
+              },
+              {
+                "required": [
+                  "sso_providers"
+                ],
+                "properties": {
+                  "sso_providers": {
+                    "minItems": 1
+                  }
+                }
+              },
+              {
+                "required": [
+                  "gates"
+                ],
+                "properties": {
+                  "gates": {
+                    "minProperties": 1
+                  }
+                }
+              },
+              {
+                "required": [
+                  "transitions"
+                ],
+                "properties": {
+                  "transitions": {
+                    "minProperties": 1
+                  }
+                }
+              }
+            ]
+          },
+          {
+            "not": {
+              "required": [
+                "complete"
+              ]
+            },
+            "properties": {
+              "fields": {
+                "maxItems": 0
+              },
+              "actions": {
+                "maxItems": 0
+              },
+              "sso_providers": {
+                "maxItems": 0
+              },
+              "gates": {
+                "maxProperties": 0
+              },
+              "transitions": {
+                "not": {
+                  "required": [
+                    "callback"
+                  ]
+                }
+              }
+            }
+          }
+        ]
+      },
+      "description": "A step in a flow definition. This is the admin-authored configuration,\nnot the runtime payload sent to the frontend.\n\nSteps are schema-driven: `fields` references properties from the flow's\nuser schema, and the engine resolves field metadata (type, validation,\nimplicit outcomes) from schema annotations at runtime.\n\nA step with only `complete` set is a terminal step. All other steps are\nrendered to the frontend as capability payloads.\n",
       "properties": {
         "name": {
           "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Unique step identifier within this flow. Used as transition targets\nand returned in the API response as `step.name`.\n",
+          "pattern": "^[a-z][a-z0-9_-]*$",
           "examples": [
-            "identify",
-            "authenticate",
-            "done"
-          ],
-          "description": "Unique step identifier within this definition. Slug-shaped so it is safe to use as a transition `target` and as a value in `purposes`. Referenced by other steps in the same definition."
+            "login"
+          ]
         },
         "fields": {
           "type": "array",
-          "uniqueItems": true,
+          "description": "Schema property names to collect from the user. Each entry references\na property in the flow's user schema. The engine resolves field type,\nvalidation rules, and implicit outcomes from schema annotations\n(e.g. a property with `x-unique` set implies a `user_not_found`\ntransition outcome).\n",
           "items": {
             "type": "string"
           },
+          "uniqueItems": true,
+          "default": [],
           "examples": [
-            [
-              "email"
-            ],
             [
               "email",
               "password"
             ]
-          ],
-          "description": "Schema property names to collect from the user on this step. Each entry must resolve to a property in the definition's `user_schema`, or use the reserved token `x-auth-methods#<method>` (e.g. `x-auth-methods#password`) to collect a credential proof for a method enabled at the schema root. The engine reads the schema's `x-*` annotations to derive: - field type and validation (rendered into the runtime payload), - implicit transition outcomes - e.g. a property with a non-empty `x-unique` scope makes `user_not_found` a valid `transitions` key on this step."
+          ]
         },
         "actions": {
           "type": "array",
+          "description": "Ordered list of actions the user can take. The action name is what the\nfrontend sends back in the submit request. If omitted, the engine\nprovides a default `submit` action.\n",
           "items": {
-            "$ref": "#/$defs/Action"
+            "$ref": "#/$defs/StepAction"
           },
-          "description": "Ordered list of actions the user can take on this step. The `name` is what the client echoes back on submit. Every action's name must have a matching key in `transitions`; the engine rejects submissions for actions without a defined transition."
+          "default": [],
+          "examples": [
+            [
+              {
+                "name": "submit",
+                "kind": "submit",
+                "primary": true
+              },
+              {
+                "name": "forgot_password",
+                "kind": "navigate"
+              }
+            ]
+          ]
         },
         "gates": {
           "type": "object",
+          "description": "Security gates that must be satisfied before submission. Keyed by gate\nname. Each gate selects a kind (e.g. \"captcha\") and provider-specific\nconfiguration. The engine may also inject gates dynamically based on\npolicy.\n",
           "additionalProperties": {
             "$ref": "#/$defs/Gate"
           },
-          "description": "Security challenges that must be satisfied before this step's submission is accepted. Keyed by gate name (free identifier; referenced as the key in the runtime `step.gates` dictionary). The engine may inject additional gates at runtime based on policy or risk evaluation."
+          "default": {},
+          "examples": [
+            {
+              "bot_check": {
+                "kind": "captcha",
+                "provider": "altcha"
+              }
+            }
+          ]
         },
         "sso_providers": {
           "type": "array",
+          "description": "Slugs of the identity provider connections this step offers, in display\norder. Each names the `slug` of a connection under `.zitadel/idps/`; the\nconnection carries the display name and template, so a rename there\nreaches every step without editing the flow. The rendered step the client\nreceives carries the resolved `{id, name, template}` objects instead.\n",
+          "uniqueItems": true,
           "items": {
-            "$ref": "#/$defs/SSOProvider"
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "maxLength": 64
           },
-          "description": "Identity providers available on this step. When non-empty, the step must define a `transitions.callback` entry — the engine handles the reserved `sso` action transparently (redirect to the IdP, code exchange, user resolution) and fires `callback` on this step when the IdP returns. The flow author never writes a `transitions.sso`."
+          "default": [],
+          "examples": [
+            [
+              "google"
+            ]
+          ]
         },
         "on_success": {
           "type": "string",
           "enum": [
             "create_user"
           ],
-          "description": "Server-side mutation to run after the step's fields validate and before the transition fires. - create_user: materialize the user from collected schema   fields. Used by register flows."
+          "description": "Server-side mutation to execute when this step completes successfully.\nRuns after field validation passes, before the transition fires.\n\n- create_user: creates the user record (registration flows)\n",
+          "examples": [
+            "create_user"
+          ]
         },
         "complete": {
           "type": "string",
@@ -187,30 +388,112 @@
             "redirect",
             "show"
           ],
-          "description": "Marks this step as terminal. A terminal step has no `fields`, `actions`, `transitions`, `gates`, or `sso_providers`. - redirect: client navigates to a `redirect_uri` resolved from   the originating protocol request (OIDC, SAML). - show: client renders the step as a success or info screen."
+          "description": "Marks this as a terminal step. Tells the frontend what to do:\n- redirect: navigate to redirect_uri (OIDC/SAML callback done)\n- show: render as a success/info screen\n",
+          "examples": [
+            "redirect"
+          ]
         },
         "transitions": {
           "type": "object",
+          "description": "Maps action/outcome names to their transition descriptor.\n\nKeys match action names from the `actions` array. Additional keys\ncome from implicit outcomes based on schema annotations\n(e.g. `user_not_found` from `x-unique` fields) and engine\nevents (e.g. `sso`, `callback`).\n",
           "additionalProperties": {
-            "$ref": "#/$defs/Transition"
+            "type": "object",
+            "required": [
+              "target"
+            ],
+            "properties": {
+              "target": {
+                "type": "string",
+                "description": "Step name within this flow (when `action` is null), or the name\nof another flow (when `action` is `switch` or `pivot`).\n",
+                "examples": [
+                  "password"
+                ]
+              },
+              "action": {
+                "oneOf": [
+                  {
+                    "type": "string",
+                    "enum": [
+                      "switch",
+                      "pivot"
+                    ]
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "How to interpret `target`:\n- null (omitted): transition to a step in the current flow.\n- switch: replace the current flow with the target flow.\n  No return — the current flow is discarded.\n  Example: login ↔ register.\n- pivot: push the target flow onto the stack. The current flow\n  is paused and resumes when the target flow completes (auto-pop).\n  Example: login → recovery → back to login.\n"
+              },
+              "purpose": {
+                "oneOf": [
+                  {
+                    "type": "string",
+                    "enum": [
+                      "login",
+                      "register",
+                      "recovery",
+                      "profiling",
+                      "reauth",
+                      "link_account"
+                    ]
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Local re-purposing. When set, taking this transition changes the\nflow's current purpose to this value — the dispatch mode a step's\nchallenges run under — while the flow's original purpose stays\npinned. Must be a purpose this definition serves, and `target`\nmust be that purpose's entry step. Mutually exclusive with\n`action`: a transition either re-purposes within this flow or\ntargets another flow, never both.\nExample: a \"Sign up\" navigation on the login identifier step\n(`{ target: register, purpose: register }`).\n"
+              }
+            },
+            "additionalProperties": false,
+            "not": {
+              "required": [
+                "purpose",
+                "action"
+              ],
+              "properties": {
+                "purpose": {
+                  "type": "string"
+                },
+                "action": {
+                  "type": "string"
+                }
+              }
+            }
           },
-          "description": "Maps action names and engine-emitted outcomes to the next state. Keys are either: - an action name declared in this step's `actions`, or - a reserved outcome the engine produces: - `user_not_found` - emitted when a unique field (`x-unique`) does not match an existing user. - `user_already_exists` - emitted when registration matches an existing user. - `callback` - emitted when an external system returns control to the flow (SSO callback, device authorization poll, etc.). A transition's `action` field controls whether the target is interpreted as a step in this definition (default) or as the name of another definition to switch or pivot into."
+          "examples": [
+            {
+              "submit": {
+                "target": "password"
+              },
+              "recover": {
+                "target": "recovery",
+                "action": "pivot"
+              },
+              "register": {
+                "target": "register",
+                "action": "switch"
+              }
+            }
+          ]
         }
       }
     },
-    "Action": {
+    "StepAction": {
       "type": "object",
+      "required": [
+        "name",
+        "kind"
+      ],
       "additionalProperties": false,
+      "description": "An action a flow author declares on a step of a flow definition. The\n`name` is sent back in the submit request as `action`; the engine resolves\nthe action's declared `kind` to decide how to handle the submission.\n",
       "properties": {
         "name": {
           "type": "string",
           "minLength": 1,
+          "description": "Action identifier. Sent back in the submit request as `action`.",
           "examples": [
-            "submit",
-            "passkey",
-            "email_fallback"
-          ],
-          "description": "Action identifier, echoed back by the client on submit and matched against `transitions`. The name `back` is reserved for engine-injected back navigation."
+            "submit"
+          ]
         },
         "kind": {
           "type": "string",
@@ -220,142 +503,63 @@
             "passkey_register",
             "navigate"
           ],
-          "description": "How the engine handles the action. - submit: collect the step's fields and run validate/dispatch/on_success. - passkey: issue a WebAuthn assertion challenge; the matching transition fires once the assertion verifies. - passkey_register: issue a WebAuthn registration challenge; the matching transition fires once the attestation verifies. - navigate: route through the transition without running the input pipeline. (`back` exists on the wire but is engine-injected; declaring it is rejected.)"
+          "description": "Classifies how the engine handles this action. `back` is not declarable:\nthe engine injects it into runtime steps (see `flow-step-action.yaml`)\nwhenever going back is available.\n- `submit`: collect the step's fields and run validate/dispatch/on_success.\n- `passkey`: issue a WebAuthn assertion challenge; the matching transition\n  fires once the returned assertion verifies.\n- `passkey_register`: issue a WebAuthn registration challenge; the matching\n  transition fires once the returned attestation verifies.\n- `navigate`: route through the transition without running the input\n  pipeline. Used for pure-routing actions declared in the flow definition.\n",
+          "examples": [
+            "submit"
+          ]
         },
         "primary": {
           "type": "boolean",
           "default": false,
-          "description": "Marks this as the default/primary action. The runtime template uses this hint to choose visual emphasis. At most one action per step should be primary; this is not enforced here."
+          "description": "Marks this as the default/primary action. The runtime template uses\nthis hint to choose visual emphasis. At most one action per step\nshould be primary; this is not enforced here.\n",
+          "examples": [
+            true
+          ]
         },
         "text_key": {
           "type": "string",
+          "description": "Optional localization key override for the action's label. When\nomitted, the engine derives a key from the step and action names.\nDisplay text is resolved client-side from a locale dictionary, never\nby the engine.\n",
           "examples": [
             "actions.signin.submit"
-          ],
-          "description": "Optional localization key override for the action's label. When omitted, the engine derives a key from the step and action names. Display text is resolved client-side from a locale dictionary, never by the engine."
+          ]
         }
-      },
-      "description": "Configuration for a user-invokable action on a step.",
-      "required": [
-        "name",
-        "kind"
-      ]
+      }
     },
     "Gate": {
       "type": "object",
+      "additionalProperties": false,
       "required": [
         "kind",
         "provider"
       ],
-      "additionalProperties": false,
+      "description": "A security challenge that must be satisfied before this step's submission\nis accepted. The engine may also inject gates at runtime based on policy\nor risk evaluation.\n",
       "properties": {
         "kind": {
           "type": "string",
           "enum": [
             "captcha"
           ],
-          "description": "The gate category. Only `captcha` is currently defined. Authenticator ceremonies (e.g. passkey) are modelled as credential auth_attempts via `x-credential` on a field, not as gates."
+          "description": "The gate category. Only `captcha` is currently defined. Authenticator\nceremonies (e.g. passkey) are modelled as credential auth_attempts via\n`x-credential` on a field, not as gates.\n",
+          "examples": [
+            "captcha"
+          ]
         },
         "provider": {
           "type": "string",
+          "description": "Provider identifier within the gate kind — e.g. `altcha`, `turnstile`,\n`hcaptcha`. The engine looks up an implementation in its provider\nregistry.\n",
           "examples": [
-            "altcha",
-            "turnstile",
-            "hcaptcha"
-          ],
-          "description": "Provider identifier within the gate kind — e.g. `altcha`, `turnstile`, `hcaptcha`. The engine looks up an implementation in its provider registry."
+            "altcha"
+          ]
         },
         "config": {
           "type": "object",
+          "description": "Provider-specific configuration consumed by the implementation when\nissuing the per-render challenge. Opaque to the engine.\n",
           "additionalProperties": true,
           "examples": [
             {
-              "site_key": "0x4AAAAAAAxxxxxxxxxxxxxx"
+              "site_key": "0x4AAAAAAA-example-site-key"
             }
-          ],
-          "description": "Provider-specific configuration consumed by the implementation when issuing the per-render challenge. Opaque to the engine."
-        }
-      }
-    },
-    "SSOProvider": {
-      "type": "object",
-      "required": [
-        "id",
-        "name",
-        "template"
-      ],
-      "additionalProperties": false,
-      "properties": {
-        "id": {
-          "type": "string",
-          "examples": [
-            "google",
-            "corp_idp"
-          ],
-          "description": "Provider instance identifier. Echoed back by the client when the user picks a provider; routed to the corresponding configured IdP at the engine."
-        },
-        "name": {
-          "type": "string",
-          "examples": [
-            "Google",
-            "Acme SSO"
-          ],
-          "description": "Display name surfaced to the user. Localized client-side if a matching text key exists in the locale dictionary."
-        },
-        "template": {
-          "type": "string",
-          "examples": [
-            "google",
-            "entraid",
-            "github"
-          ],
-          "description": "Hint for rendering (logo, brand colors) — e.g. `google`, `entraid`, `github`. Consumed by the runtime template, not by the engine."
-        }
-      }
-    },
-    "Transition": {
-      "type": "object",
-      "required": [
-        "target"
-      ],
-      "additionalProperties": false,
-      "properties": {
-        "target": {
-          "type": "string",
-          "examples": [
-            "authenticate",
-            "register",
-            "recovery"
-          ],
-          "description": "When `action` is omitted, the `name` of a step in the same definition. When `action` is `switch` or `pivot`, the `name` of another flow definition in the same project."
-        },
-        "action": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "enum": [
-            "switch",
-            "pivot",
-            null
-          ],
-          "description": "How to interpret `target`. - Omitted: transition to a step in the current definition. - `switch`: replace the current flow with the target flow.   No return; the current flow is discarded. Typical use:   navigating between peer flows like login ↔ register. - `pivot`: push the target flow onto the stack. The current   flow is paused; when the target flow completes the engine   auto-pops back. Typical use: login → recovery → back to login."
-        },
-        "purpose": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "enum": [
-            "login",
-            "register",
-            "recovery",
-            "profiling",
-            "reauth",
-            "link_account",
-            null
-          ],
-          "description": "Local re-purposing. When set, taking this transition changes the flow's current purpose to this value — the dispatch mode a step's challenges run under — while the flow's original purpose stays pinned. Must be a purpose this definition serves, and `target` must be that purpose's entry step. Mutually exclusive with `action`: a transition either re-purposes within this flow or targets another flow, never both. Example: a \"Sign up\" navigation on the login identifier step (`{ \"target\": \"register\", \"purpose\": \"register\" }`)."
+          ]
         }
       }
     }