docs: add flow-definition examples (#233)

Adds six worked examples under
api/openapi/endpoints/flow_definitions/examples, ordered from minimal
(single-purpose password login) to full (combined login+register with
password, passkey, and post-signup upsell). Each example ships a
flow-definition.json plus a README with a Mermaid graph, capabilities
exercised, walk-through, and gotchas. The root README indexes the ladder
and cross-links to the engine's capabilities and definition-rules docs.

Scope is deliberately what the engine runs today; cross-flow
transitions, SSO, gates, OTP, and recovery are called out as not shown.

The flow definitions were also added as examples in the OpenAPI spec:

<img width="1074" height="911" alt="Screenshot 2026-06-10 at 12 34 42"
src="https://github.com/user-attachments/assets/6829eae2-5132-416d-9395-2477ee191485"
/>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: vitorbari

api/openapi/endpoints/flow_definitions/examples/01-password-login/README.md

@@ -0,0 +1,50 @@
+# 01 — Password Login
+
+The minimal login flow. Collect an identifier, then a password, then complete.
+
+## Capabilities exercised
+
+- Single-purpose definition (`login` only — no flip-table coverage required).
+- Identifier-shaped field (`email` is `x-unique` in the user schema) drives
+  implicit identifier dispatch on submit.
+- Password-shaped field (`password` is `x-password`) drives implicit password
+  verification on submit.
+- Terminal `complete: show` — the frontend renders a success screen and the
+  flow handoff token is returned alongside the terminal step.
+
+## Graph
+
+```mermaid
+flowchart TD
+    start([Start: purpose=login]) --> identifier
+    identifier["identifier<br/>field: email<br/>action: submit"]
+    password["password<br/>field: password<br/>action: submit"]
+    done([done<br/>complete: show])
+
+    identifier -- submit --> password
+    password -- submit --> done
+```
+
+## Walk-through
+
+1. `POST /flow` with `purpose: login` → engine resolves this definition, mints
+   an auth attempt, and returns the `identifier` step.
+2. The user submits `email`. The engine resolves the identifier against the
+   user schema's `x-unique` index. If found, it transitions on `submit` to
+   `password`. If not found, the engine emits `user_not_found`; this step does
+   not wire that outcome, so the submit fails with an error (the step
+   re-renders with `Error` set).
+3. The user submits `password`. The engine verifies against the stored
+   credential. On success, it transitions to `done` and issues a handoff
+   token on the terminal `FlowStepResult`.
+
+## Notes
+
+- No `user_not_found` route means unknown identifiers fail loudly rather than
+  routing to a register branch. That is the engine's documented behavior for
+  solo-purpose login flows. To route unknown users into a registration
+  sub-flow, add `register` as a purpose and wire `user_not_found` — see
+  example 05.
+- The identifier and password steps are separate, so submitted fields are
+  validated in two rounds. Putting both fields on a single step is allowed
+  but only useful for `create_user` registration (example 02).

api/openapi/endpoints/flow_definitions/examples/01-password-login/flow-definition.json

@@ -0,0 +1,37 @@
+{
+  "project_id": "${PROJECT_ID}",
+  "schema_uri": "https://nextgen.com/flow-definition.json",
+  "flow_definition": {
+    "name": "password-login",
+    "user_schema": "${USER_SCHEMA_URL}",
+    "purposes": {
+      "login": "identifier"
+    },
+    "steps": [
+      {
+        "name": "identifier",
+        "fields": ["email"],
+        "actions": {
+          "submit": { "primary": true }
+        },
+        "transitions": {
+          "submit": { "target": "password" }
+        }
+      },
+      {
+        "name": "password",
+        "fields": ["password"],
+        "actions": {
+          "submit": { "primary": true }
+        },
+        "transitions": {
+          "submit": { "target": "done" }
+        }
+      },
+      {
+        "name": "done",
+        "complete": "show"
+      }
+    ]
+  }
+}

api/openapi/endpoints/flow_definitions/examples/02-password-register/README.md

@@ -0,0 +1,49 @@
+# 02 — Password Register
+
+Single-step password signup with `on_success: create_user`. The user submits
+identifier and password together; the engine creates the user row and the
+credential atomically, marks the new user as verified on the auth attempt,
+then completes.
+
+## Capabilities exercised
+
+- Single-purpose definition (`register` only).
+- `on_success: create_user` writer — hashes the password (argon2id), creates
+  the user, persists the password credential, then registers the new user on
+  the auth attempt so the terminal handoff issues.
+- Writer-manifest validation: `create_user`'s manifest is
+  `[identifier, password]`; both kinds are collected on this step, so the
+  validator accepts the definition.
+- Terminal `complete: show`.
+
+## Graph
+
+```mermaid
+flowchart TD
+    start([Start: purpose=register]) --> signup
+    signup["signup<br/>fields: email, password<br/>on_success: create_user"]
+    done([done<br/>complete: show])
+
+    signup -- submit --> done
+```
+
+## Walk-through
+
+1. `POST /flow` with `purpose: register` → engine returns the `signup` step.
+2. The user submits `email` and `password`. Field validation runs against the
+   user schema (email format, password min length, uniqueness lookup).
+3. `on_success: create_user` fires before the transition: user row + password
+   credential are written in one transaction; the auth attempt is marked as
+   having a registered user.
+4. The `submit` transition routes to `done`. The terminal step issues the
+   handoff token.
+
+## Notes
+
+- Multi-step password signup (collect identifier on one step, password on the
+  next, then `on_success: create_user`) is supported through the
+  ancestor-chain manifest pattern — the validator walks reverse adjacency
+  from the `on_success` step and accepts identifier collection on any
+  upstream step. Example 05 uses this pattern.
+- Adding a `user_already_exists` transition is optional here. Without it, a
+  duplicate email errors loudly on `email`'s uniqueness check.

api/openapi/endpoints/flow_definitions/examples/02-password-register/flow-definition.json

@@ -0,0 +1,28 @@
+{
+  "project_id": "${PROJECT_ID}",
+  "schema_uri": "https://nextgen.com/flow-definition.json",
+  "flow_definition": {
+    "name": "password-register",
+    "user_schema": "${USER_SCHEMA_URL}",
+    "purposes": {
+      "register": "signup"
+    },
+    "steps": [
+      {
+        "name": "signup",
+        "fields": ["email", "password"],
+        "actions": {
+          "submit": { "primary": true }
+        },
+        "on_success": "create_user",
+        "transitions": {
+          "submit": { "target": "done" }
+        }
+      },
+      {
+        "name": "done",
+        "complete": "show"
+      }
+    ]
+  }
+}

api/openapi/endpoints/flow_definitions/examples/03-passkey-login/README.md

@@ -0,0 +1,58 @@
+# 03 — Passkey Login (Discoverable)
+
+A single-step passkey login. The user is identified entirely through the
+WebAuthn assertion — no identifier is collected up front, so the engine issues
+the assertion challenge with an empty `allowCredentials` list and the
+authenticator picks a credential it holds for the relying party.
+
+## Capabilities exercised
+
+- Action-driven dispatch: the `passkey` action is engine-handled. Selecting
+  it triggers the two-phase ceremony rather than a field-shaped submit.
+- **Phase 1 (issue)** — the step re-renders with a `challenge` payload
+  (`method`, `challenge_id`, `options`) and the state cookie rotates.
+- **Phase 2 (verify)** — the user submits the assertion `proof`. The engine
+  verifies via `auth-attempt.SubmitPasskey`, resolves the user from the
+  credential, marks the attempt verified, then routes through the `passkey`
+  transition.
+- Terminal `complete: show`.
+
+## Graph
+
+```mermaid
+flowchart TD
+    start([Start: purpose=login]) --> signin
+    signin["signin<br/>action: passkey<br/>no fields"]
+    issue{{"phase 1: issue<br/>(challenge emitted)"}}
+    verify{{"phase 2: verify<br/>(proof submitted)"}}
+    done([done<br/>complete: show])
+
+    signin -- "passkey action" --> issue
+    issue -- "challenge_response.proof" --> verify
+    verify -- "passkey (after verify)" --> done
+```
+
+## Walk-through
+
+1. `POST /flow` with `purpose: login` → engine returns the `signin` step with
+   the `passkey` action.
+2. The user picks `passkey`. The engine calls
+   `auth-attempt.IssuePasskeyChallenge`; the step re-renders with the
+   assertion options. `allowCredentials` is empty because no user is
+   identified — discoverable credentials only.
+3. The browser produces an assertion. The frontend re-submits with
+   `challenge_response.{challenge_id, proof, method}`. The engine verifies,
+   resolves the user, and transitions on `passkey` to `done`.
+4. The terminal step issues the handoff token.
+
+## Notes
+
+- To support **non-discoverable** credentials (passkeys not stored in a
+  resident key), add an identifier field on a prior step so the engine can
+  populate `allowCredentials` with the resolved user's credential IDs before
+  issuing the assertion. Example 06 illustrates this pattern (identifier step
+  exposes both `submit` and `passkey` actions).
+- RPID is derived per-request from `WithRequestHostMiddleware` so same-origin
+  fetches without an `Origin` header still work.
+- The state cookie rotates on every step transition, including the issue and
+  verify legs of the ceremony.

api/openapi/endpoints/flow_definitions/examples/03-passkey-login/flow-definition.json

@@ -0,0 +1,26 @@
+{
+  "project_id": "${PROJECT_ID}",
+  "schema_uri": "https://nextgen.com/flow-definition.json",
+  "flow_definition": {
+    "name": "passkey-login",
+    "user_schema": "${USER_SCHEMA_URL}",
+    "purposes": {
+      "login": "signin"
+    },
+    "steps": [
+      {
+        "name": "signin",
+        "actions": {
+          "passkey": { "primary": true }
+        },
+        "transitions": {
+          "passkey": { "target": "done" }
+        }
+      },
+      {
+        "name": "done",
+        "complete": "show"
+      }
+    ]
+  }
+}

api/openapi/endpoints/flow_definitions/examples/04-passkey-register/README.md

@@ -0,0 +1,67 @@
+# 04 — Passkey Register
+
+Identifier-first passkey signup. The user submits an email, then the WebAuthn
+ceremony runs; the engine creates the user row in the same transaction that
+persists the credential.
+
+## Capabilities exercised
+
+- Action-driven dispatch via the engine-handled `passkey_register` action.
+- Field validation runs on the submitted `email` (format + uniqueness)
+  before the ceremony begins; a duplicate fails loudly on the field rather
+  than after challenge issue.
+- **Provisional user pattern**:
+  - On the issue leg, the engine calls `GenerateUserID()` and stashes the
+    result in `CollectedData["_user_id"]`, plus a `_passkey_provisional`
+    marker so the verify leg knows to finalize the user.
+  - On the verify leg, `HandleProvisional` writes the user row (with `email`
+    as the identifier attribute) **inside the same DB transaction** that
+    persists the credential. If verification fails, neither row is written.
+  - After verify, `RegisterCreatedUser` marks the user as verified on the
+    auth attempt so the terminal handoff issues.
+- No `on_success: create_user` — its writer manifest is
+  `[identifier, password]`, and this flow collects no password. The
+  provisional pattern handles user creation instead.
+
+## Graph
+
+```mermaid
+flowchart TD
+    start([Start: purpose=register]) --> signup
+    signup["signup<br/>field: email<br/>action: passkey_register"]
+    issue{{"phase 1: issue<br/>mint provisional _user_id<br/>(challenge emitted)"}}
+    verify{{"phase 2: verify<br/>HandleProvisional creates user<br/>RegisterCreatedUser"}}
+    done([done<br/>complete: show])
+
+    signup -- "passkey_register action" --> issue
+    issue -- "challenge_response.proof" --> verify
+    verify -- "passkey_register (after verify)" --> done
+```
+
+## Walk-through
+
+1. `POST /flow` with `purpose: register` → engine returns the `signup` step
+   with the `email` field and `passkey_register` action.
+2. The user enters `email` and picks `passkey_register`. The engine validates
+   `email` against the schema, merges it into collected data, mints a
+   provisional `_user_id`, calls
+   `passkey-registration.IssuePasskeyRegistrationChallenge`, and re-renders
+   the step with the creation `options`.
+3. The browser produces an attestation. The frontend re-submits with
+   `challenge_response.{challenge_id, proof, method}`.
+4. The engine sees the `_passkey_provisional` marker and calls
+   `HandleProvisional` to write the user row (with `email` as the identifier
+   attribute), then `SubmitPasskeyRegistration` to persist the credential —
+   all within one transaction. Finally `RegisterCreatedUser` is called against
+   the auth attempt.
+5. The `passkey_register` transition routes to `done`; the terminal step
+   issues the handoff token.
+
+## Notes
+
+- The `passkey_register` action short-circuits the field-shaped identifier
+  dispatch — `user_not_found` is not emitted on submit, so a register-only
+  flow does not need to wire it. Field validation (format, uniqueness) still
+  runs on the email before the ceremony begins.
+- The WebAuthn `user.id` is the provisional `_user_id`, kept stable across
+  phase 1 and phase 2.

api/openapi/endpoints/flow_definitions/examples/04-passkey-register/flow-definition.json

@@ -0,0 +1,27 @@
+{
+  "project_id": "${PROJECT_ID}",
+  "schema_uri": "https://nextgen.com/flow-definition.json",
+  "flow_definition": {
+    "name": "passkey-register",
+    "user_schema": "${USER_SCHEMA_URL}",
+    "purposes": {
+      "register": "signup"
+    },
+    "steps": [
+      {
+        "name": "signup",
+        "fields": ["email"],
+        "actions": {
+          "passkey_register": { "primary": true }
+        },
+        "transitions": {
+          "passkey_register": { "target": "done" }
+        }
+      },
+      {
+        "name": "done",
+        "complete": "show"
+      }
+    ]
+  }
+}