plutonium 0.60.5 → 0.61.0

data/docs/reference/wizard/anchoring-resume.md

@@ -0,0 +1,194 @@
+# Anchoring & resume
+
+How a wizard binds to an existing record (anchoring), how a running wizard is identified, and how a user resumes where they left off.
+
+## Anchoring
+
+An **anchored** wizard runs against an existing record — the analogue of `attribute :resource` on an interaction. The anchor is read-only context, available from any step (and `condition:`/`on_submit`/`execute`) via the `anchor` accessor.
+
+```ruby
+class ConfigureCompanyWizard < Plutonium::Wizard::Base
+  anchored with: Company           # operate on a Company
+
+  step :branding, label: "Branding" do
+    attribute :logo, :string
+    input :logo
+    on_submit { anchor.update!(logo: data.branding.logo) }   # mutate the anchor
+  end
+
+  def execute
+    anchor.update!(configured_at: Time.current)
+    succeed(anchor)
+  end
+end
+```
+
+### Forms of `anchored`
+
+| Declaration | Meaning |
+|---|---|
+| `anchored with: Company` | A single concrete type. |
+| `anchored with: [Company, Organization]` | Polymorphic — accepts any listed type. |
+| `anchored` (no `with:`) | Generic — the type binds at registration to whichever resource hosts it (shareable library wizard). |
+| *(omit `anchored`)* | No anchor — a pure data → create flow. |
+
+```ruby
+# A generic, shareable wizard — bound to a concrete type at registration.
+class ArchiveWithReasonWizard < Plutonium::Wizard::Base
+  anchored
+
+  step :reason do
+    attribute :reason, :string
+    input :reason, as: :textarea
+    validates :reason, presence: true
+  end
+
+  def execute
+    anchor.update!(archived_at: Time.current, archive_reason: data.reason.reason)
+    succeed(anchor)
+  end
+end
+```
+
+### `anchor` raises when absent
+
+```ruby
+anchor   # => the record, for an anchored wizard
+         # => raises Plutonium::Wizard::NotAnchoredError, for a non-anchored one
+```
+
+`anchor` never returns `nil`. Anchored-vs-not is a static property of the wizard, so reaching for `anchor` when the wizard isn't `anchored` is a programming error, not a runtime condition to guard.
+
+The anchor is **not** part of `persisted` — `persisted` holds only records the wizard creates. The anchor is an input the wizard was launched against.
+
+### Anchor resolution per surface
+
+The wizard body never cares where the anchor came from; the launch surface resolves it:
+
+- **Record action** (`wizard :configure, ...` on a definition for a `with:`-anchored wizard) — auto-mounted as a **member route** (`/companies/:id/wizards/configure/:step`) on the resource controller. The anchor is resolved through that controller's scoped, policy-gated `resource_record!` — never an unscoped `find_by`, so a record outside the portal's authorized scope (or a non-existent id) 404s instead of leaking another tenant's record.
+- **Context anchor** (`anchored via: :method`) — mounted **portal-level** with `register_wizard`; the anchor is resolved by calling that method on the controller (e.g. `via: :current_scoped_entity` for the tenant). No URL `:id`, IDOR-safe (trusted context). An optional `with:` type-asserts the result.
+- **Collection action / create flow** — no anchor.
+
+::: tip Anchored member routes are IDOR-safe by construction
+Because the anchor comes from `resource_record!` (the same scoped lookup CRUD and interactive record actions use), a `with:`-anchored wizard can only ever operate on a record the current user is authorized to see in this portal. A `via:`-anchored wizard is IDOR-safe by trusting the resolved context.
+:::
+
+## Instance identity
+
+Every running wizard has a deterministic **instance key** — a digest the session row is uniquely keyed by. There are two recipes, by identity axis ([see Identity, concurrency & repeatability](/reference/wizard/dsl)):
+
+```
+# concurrency_key set:
+instance_key = SHA256(JSON([secret_key_base, "concurrency", wizard, serialized(concurrency_key)]))
+# no concurrency_key:
+instance_key = SHA256(JSON([secret_key_base, "tokened", wizard, wizard_token]))
+```
+
+The digest hashes the **JSON of a structured array**, not a flat-joined string, and is **salted with the app's `secret_key_base`**:
+
+- **`concurrency_key`** is serialized records → GID, scalars → string, arrays kept as a **nested structure (not joined)** — so two distinct keys can never collide into one row (`["a", "b"]` ≠ `"a|b"`). The **tenant (`current_scoped_entity`) is folded in automatically**, so the same user running the same keyed wizard in two tenant portals gets two distinct rows.
+- **The `secret_key_base` salt** makes the digest a MAC over otherwise-public identifiers (the wizard name + key GIDs), so a run's existence/state can't be probed by recomputing the digest off-app.
+- **`wizard_token`** is the **per-run id** for runs with no `concurrency_key` — a fresh, unguessable token per launch makes each run distinct and repeatable. Its source depends on the run identity: an **authenticated** repeatable run carries it in the URL `:token` segment (guarded by [owner-scoping](#authentication)); a **guest (`anonymous`)** run keys off the **Rails session** (never the URL — no leak surface). It is **not** a pre-auth principal that survives login, and a wizard never crosses the auth boundary mid-flow.
+
+The owner, anchor, and scope are also stored as plain polymorphic columns (`owner_type`/`owner_id`, etc.) for listing and querying — but identity is the digest.
+
+::: warning Rotating `secret_key_base` invalidates in-progress runs
+Because the salt is `secret_key_base`, rotating it changes every instance-key digest. In-progress runs become unresumable (their rows no longer match the recomputed key) and **one-time gates re-open** (the retained `completed` marker no longer matches). This only affects rows live at rotation time; new runs key off the new secret. Drain or accept the reset when rotating.
+:::
+
+## Resume
+
+A `concurrency_key`-keyed wizard's `in_progress` row **is the lock**: a second launch at the same key resumes it instead of forking. Look up the row by `instance_key`; if one exists, the user continues where they left off. A tokened (no `concurrency_key`) wizard resumes via its per-run id (carried in the URL `:token` segment for an authenticated run, or the Rails session for a guest run) and starts a fresh run otherwise.
+
+For a non-`anonymous` (authenticated) wizard, **every resume is owner-scoped**: a row may only be resumed by the user that owns it. A run id leaked in a URL can't be picked up by another logged-in user — the engine treats a foreign row as not-found (404). See [Authentication](#authentication).
+
+### Listing in-progress wizards
+
+```ruby
+Plutonium::Wizard.in_progress_for(view_context, anchor: nil, wizard: nil)
+#   → Array<Resume::Entry>, newest-first   (delegates to Resume.entries_for)
+```
+
+Like interactions, it takes the `view_context` and derives everything from it — the run **owner** (`current_user`), the **tenant scope** (`current_scoped_entity` when `scoped_to_entity?`, else `nil`), and the **portal** — returning that owner's in-progress runs **for the current portal**.
+
+**Each `entry` exposes:** `label`, `icon`, `current_step` (+ `current_step_label`), `updated_at`, `resume_url` (or `nil`), `resume_unresolved_reason`, `wizard_class`, and the raw `session` row.
+
+**Portal scoping.** A run is only ever listed (and linked) by the portal it was launched in — a non-scoped portal lists only unscoped runs; a scoped portal narrows to the current tenant. Two portals can share an entity scope, so the launching portal (the `engine` column) is recorded per-run because scope alone can't identify it.
+
+**`resume_url`** is built through the current portal's routes:
+- `wizard`-macro **anchored** mount → `resource_url_for(record, wizard:, step:)`.
+- `register_wizard` mount → the named route (with the scope segment, and the `:token` for tokened runs).
+- Unresolvable here (e.g. a non-anchored `wizard`-macro run, whose resource identity isn't on the row) → `resume_url: nil` + a `resume_unresolved_reason` string. Render those without a link rather than guessing.
+
+**`anchor:` / `wizard:` filters** (for a per-record resume widget — "does this record have an unfinished draft of wizard X?"):
+- They narrow **in the query, before enrichment**, so discarded rows are never resume-URL-resolved or anchor-loaded — cheaper than filtering the returned array.
+- They compose, and the `wizard + anchor` pair is index-covered: `in_progress_for(vc, wizard: ConfigureCompanyWizard, anchor: record).first`. `wizard:` takes the wizard **class**.
+- For ad-hoc post-filtering the array still works (`select { |e| e.wizard_class == X }` is free — the class is on each entry). Avoid filtering on `e.session.anchor` (a polymorphic load per row) — use `anchor:`.
+
+See the [guide](/guides/wizards#listing-in-progress-wizards) for a worked dashboard example.
+
+### The implied anchored key
+
+An `anchored` wizard with **no explicit `concurrency_key`** is keyed by default — `{ [anchor, current_user] }`, with the tenant folded in. So an anchored wizard, out of the box, is **one in-progress draft per user per record**: re-launching it for the same record resumes your draft, and two users editing the same record get **independent** runs (no collision).
+
+This is the right default because anchoring without keying is a footgun in both directions: a *tokened* anchored wizard forks a new run on every launch, while `{ anchor }` (record-only) keys across users — so a second user editing the same record collides with the first and is owner-scoped out (a 404). The implied key threads the needle. The anchor's GlobalID is already globally unique (and pins the tenant for a tenant-scoped record), so `[anchor, current_user]` is the full identity; the auto-folded tenant is redundant there but load-bearing for non-anchor keys.
+
+Override when you want different semantics:
+- `concurrency_key { anchor }` — a true singleton: **one run per record, any user** ("configure this once, by anyone"). A concurrent second user is blocked (owner-scoped) until the first finishes.
+- `concurrency_key { wizard_token }` — make the anchored wizard **repeatable** (a fresh run per launch).
+
+Anonymous (guest) anchored wizards are exempt — a guest has no real user to key by, so they stay session-tokened.
+
+### Relaunching a tokened wizard
+
+A keyed wizard auto-resumes (its keyed row is the lock), so a bare launch always continues the single in-progress run. A **tokened** wizard has no such single run — each bare launch could mint a fresh one. By default it doesn't silently fork: it prompts. Opt out for flows that should always start clean:
+
+```ruby
+on_relaunch :new
+```
+
+With the default (`on_relaunch :prompt`), a bare launch (e.g. `GET /onboarding`) checks the user's pending runs (owner- and tenant-scoped, via the same listing as above). If any exist, it renders a **"resume or start new" page** (each pending run with a Resume link, plus a **Start new** button) instead of silently discarding that in-progress work. With no pending runs it starts fresh as usual, and **Start new** (the bare launch URL with `?new=1`) always forces a fresh run. Because the chooser only appears when a pending run exists, `:prompt` is a safe superset of `:new`. Use `on_relaunch :new` to opt out (always fork a fresh run) for flows meant to be run repeatedly from scratch.
+
+This only applies to authenticated tokened wizards: keyed wizards already auto-resume, and `anonymous` (guest) runs are session-keyed to a single run — `on_relaunch` is a no-op for both.
+
+On resume the engine:
+
+- Restores the step cursor and `data` (typed snapshot rehydrated from the JSON column).
+- Re-renders the current step's form seeded from staged `data` — including repeater rows (a `structured_input ..., repeat:` step re-renders the right number of filled rows, not one blank row).
+- Lazily rehydrates `persisted[:key]` from stored GlobalIDs on first access (memoized per request), so a per-step `on_submit` create flow returning later still sees records made by earlier steps — without paying a `GlobalID.locate` on requests that never read `persisted`.
+
+Navigation never loses data: **Back** moves the cursor without validating and never discards `data`. A step whose answer is later **un-chosen** (its `condition:` flips false) leaves the visible path and is **fully pruned**: its staged `data` is dropped, and if its `on_submit` had **persisted records** (save-as-you-go) those records are **rolled back**: its `on_rollback` runs first if declared (additive side-effect cleanup), then the engine **always** destroys them, so nothing is orphaned. The step's `persisted` / `data` / `visited` state is cleared, so re-entering that branch re-runs its `on_submit` from scratch. Pruning fires as soon as the branch is hidden (during the advance that flips it) and again as a safety net at finalize.
+
+## Authentication
+
+**Wizards require authentication by default.** Entry without a `current_user` is rejected (redirect to login / 401). A wizard never crosses the auth boundary mid-flow.
+
+- **Default (authenticated).** `current_user` is required throughout. Every session lookup/resume is **owner-scoped** (`where(owner: current_user)` + an owner check), so a run id leaked in a URL can't be resumed by another logged-in user. `current_user` comes from the host: a portal mount inherits the portal's auth concern, while an **authenticated main-app** mount requires an app-defined `::WizardsController` carrying the auth concern (see [the override hook](/reference/wizard/registration-launch#hosting-the-controller-override-hook)).
+- **`anonymous` (guest).** Opt in with the `anonymous` macro. The wizard may run with no `current_user`; its identity is the server-minted, unguessable `wizard_token` held in the **Rails session** (`session["plutonium_wizards"][<wizard_key>]`): **not a cookie, no TTL** (the row's `cleanup_after` → sweep is the authoritative lifetime; the session id is just a pointer). Session storage gives browser-close ephemerality, **auto-clear on login/logout** (Rodauth's `clear_session` → `reset_session`), and clearing on completion; the id never appears in a URL. It guards only the user's own in-progress data. Its terminal `execute` **may** authenticate (e.g. a signup flow that creates the account and logs in); that login goes through Rodauth, which rotates the Rails session. There is **no** mid-flow owner-stamping, token-survives-login, or instance_key rekey.
+
+```ruby
+class GuestSignupWizard < Plutonium::Wizard::Base
+  anonymous                       # may run pre-login
+
+  step :account do
+    attribute :email, :string
+    input :email, as: :email
+    validates :email, presence: true
+  end
+  review label: "Review"
+
+  def execute                     # the ONE boundary a guest wizard may cross
+    account = Account.create!(email: data.account.email)
+    # sign the account in here (the host calls Rodauth) — no special framework handling
+    succeed(account)
+  end
+end
+```
+
+An `anonymous` wizard must be [mounted on a public route](/reference/wizard/registration-launch#public-mount-for-anonymous-wizards).
+
+## Related
+
+- [DSL reference](/reference/wizard/dsl) — `anchored`, `anchor`, `persisted`.
+- [Storage & config](/reference/wizard/storage-config) — the session table + columns.
+- [One-time wizards](/reference/wizard/one-time) — durable completion + the gate.

data/docs/reference/wizard/dsl.md

@@ -0,0 +1,332 @@
+# Wizard DSL
+
+::: warning Experimental
+Wizards are experimental — the DSL and behavior may change in a future release.
+:::
+
+A wizard is a Ruby class — `class X < Plutonium::Wizard::Base`. It declares ordered `step`s, an optional terminal `review` step, wizard-level options, and an `execute` commit hook. This page is the full reference for the author-facing DSL.
+
+For task-oriented walkthroughs, start with the [Wizards guide](/guides/wizards).
+
+## 🚨 Critical
+
+- **Use bang methods** (`create!`/`update!`/`save!`) in `on_submit` and `execute`. Failure is signalled by a raised exception — a non-bang `false` return advances the wizard and silently loses data.
+- **`condition:` lambdas must be nil-safe.** They run against the typed `data` snapshot at every transition, including before their deciding step is filled (`nil`).
+- **`review` must be the last step.** Declaring a step after `review` raises at load time.
+- **`using:` targets a model only** — not an interaction, not a bare definition.
+- **`execute` returns an Outcome** — `succeed(...)` / `failed(...)`, or raise to fail.
+
+## Wizard-level macros
+
+| Macro | Meaning |
+|---|---|
+| `presents label:, icon:, description:` | The launch button's label + icon (same as interactions), plus an optional `description:` rendered as the wizard's header subheading. |
+| `navigation :linear \| :free` | Stepper jump policy. `:linear` (default) — back to any visited step; `:free` — any visible visited step. Forward jumps to unvisited steps are never allowed. |
+| `stepper false` | Hide the top rail (the step indicator). On by default. |
+| `on_relaunch :new` | Controls a bare relaunch of a **tokened** wizard when the user has pending (in-progress) runs. Default `:prompt` shows a "resume or start new" chooser instead of silently forking; `:new` opts out and always mints a fresh run. No-op for keyed/`anonymous` wizards (they already auto-resume their single run). See [Anchoring & resume](/reference/wizard/anchoring-resume#relaunching-a-tokened-wizard). |
+| `anchored with: Model` / `anchored via: :method` | Run against an existing record; read via `anchor`. `with:` resolves from the URL `:id` (resource-mounted); `via:` resolves by calling a controller method (portal-level, context-anchored). See [Anchoring & resume](/reference/wizard/anchoring-resume). |
+| `cleanup_after <ttl> \| :never` | Idle TTL before the abandonment sweep reaps a session and rolls back its tracked records. Defaults to `config.wizards.cleanup_after`. `:never` opts out. |
+| `concurrency_key { … }` / `concurrency_key :method` | Key a run by the returned value(s) (records → GID, scalars → string, arrays serialized element-wise — structured, **not** flat-joined; the tenant is folded in automatically). The keyed `in_progress` row is the lock — a second launch at the same key resumes, never forks. Omit → unlimited concurrent `wizard_token`-keyed runs — **except** an `anchored` wizard, which defaults to `{ [anchor, current_user] }` (one draft per user per record). See [Anchoring & resume](/reference/wizard/anchoring-resume#the-implied-anchored-key). |
+| `one_time` | Retain the completed row at the `concurrency_key` (blocks restart, gate-able). **Requires a `concurrency_key`.** Omit → row deleted on completion (repeatable). See [One-time wizards](/reference/wizard/one-time). |
+| `completed do \|wizard\| … end` | Custom body for the "already completed" page a finished **one-time** wizard shows when re-opened (replaces the default confirmation). See [`completed`](#completed) below and [One-time wizards](/reference/wizard/one-time#re-opening-a-completed-wizard). |
+| `encrypt_data` | Encrypt the staged `data` column at rest using ActiveRecord's encryption keys (off by default), for flows that stage PII. Requires `active_record.encryption` keys — see [Storage & config](/reference/wizard/storage-config#encryption). |
+| `anonymous` | Opt into **guest (unauthenticated) access** — the wizard runs pre-login (auth is required otherwise). The guest's identity is a server-minted run-id in the Rails session; it crosses the auth boundary only at its terminal `execute`. Mount it `public: true` (the default for `anonymous`). **Mutually exclusive with `concurrency_key`/`one_time`** — a guest is already session-keyed and repeatable, so declaring both raises (whichever is declared last). See [Authentication](/reference/wizard/anchoring-resume#authentication). |
+
+```ruby
+class CompanyOnboardingWizard < Plutonium::Wizard::Base
+  presents label: "Onboard a company", icon: Phlex::TablerIcons::BuildingSkyscraper
+  navigation :linear
+  # ... steps ...
+end
+```
+
+## `step`
+
+```ruby
+step(key, label: nil, description: nil, condition: nil, using: nil, **using_opts, &block)
+```
+
+A `step` is one screen. The block declares its fields with the existing field DSL (`attribute`/`input`/`validates`/`structured_input`/`form_layout`) and may attach the per-step hooks `on_submit`/`on_rollback`.
+
+```ruby
+step :company, label: "Company details", condition: -> { data.plan.kind == "business" } do
+  attribute :name, :string
+  attribute :subdomain, :string
+  input :name
+  input :subdomain
+  validates :name, :subdomain, presence: true
+
+  form_layout do
+    section :identity, :name, :subdomain, label: "Identity", columns: 2
+  end
+end
+```
+
+| Option | Meaning |
+|---|---|
+| `label:` | The step's display label (stepper + heading). Defaults to `key.to_s.humanize`. |
+| `description:` | Optional sub-label rendered under the step heading. |
+| `condition:` | Lambda over `data` (and `anchor`) gating inclusion. Subtractive branching. Must be nil-safe. |
+| `using:` | Import a field surface from a **model**. See below. |
+
+The block is optional only when `using:` supplies everything.
+
+### Fields inside a step
+
+A step's block is the same field DSL used on definitions and interactions:
+
+- `attribute :name, :type` — declares a typed attribute (feeds the `data` snapshot).
+- `input :name, as:, ...` — how the field renders.
+- `validates :name, ...` — ActiveModel validations, run on Next. These also drive the form's field affordances exactly like a resource form: a `presence` validation renders the required marker (`*`), and `length`/`numericality`/`format`/`inclusion` feed `maxlength`/`min`/`max`/`pattern`/auto-choices. Validations imported via `using:` surface these too.
+- `structured_input :name, repeat: N do |f| ... end` — a repeatable/structured group → `data.<step>.name` is an array of typed sub-objects. The sub-fields can come from the block (above), or from a model via `using:` / `fields:` (same selectors as a step's `using:`) instead of a block.
+- `form_layout do ... end` — section the step's fields (`section`, `columns:`, `collapsible:`, etc.), scoped to this step.
+
+See [plutonium-resource › Definition](/reference/resource/definition) for the full field/input/layout vocabulary.
+
+### `using:` a model
+
+`using:` imports field declarations from an ActiveRecord model so a step needn't re-declare them. It is a **step option**, not a block method (avoids Ruby's `Module#using` refinements clash), and it targets a **model only**.
+
+```ruby
+step :branding, label: "Branding", using: Company, fields: %i[logo brand_color]
+
+step :details, label: "Details", using: Company, only: %i[tagline] do
+  attribute :referral_code, :string   # plus a wizard-local field
+  input :referral_code
+end
+```
+
+What gets imported:
+
+| Source | Imported |
+|---|---|
+| `Model.attribute_names` / `attribute_types` | The field universe + cast types. |
+| `<Model>Definition` (auto-resolved) | Input styling (`as:`, options, labels). Best-effort — no definition is fine. |
+| Transient `Model.new(slice).valid?` | Validations, keeping errors on imported fields + `:base`. |
+| `<Model>Definition#form_layout` | Section layout, filtered to imported fields. |
+
+| Selector / flag | Effect |
+|---|---|
+| `fields:` (alias `only:`) | Import only these attributes. |
+| `except:` | Import everything except these. |
+| `validate: false` | Skip validation reuse (write your own inline `validates`). |
+| `layout: false` | Skip inherited `form_layout` (default single grid). |
+| `validation_context:` | Run `valid?(context)` for context-scoped model validations. |
+
+**Declaration reuse only** — `using:` never pulls in the model's persistence or callbacks. Data stages into `data`; your `execute`/`on_submit` does the writes.
+
+::: tip Why a model, not a definition
+A `Plutonium::Resource::Definition` carries no link to its model — the controller binds them at request time. The only reliable direction is **model → definition**, so the model is the reuse target, and `<Model>Definition` is auto-resolved from it for styling.
+:::
+
+### Attachment fields
+
+A file field is a **`:string`** attribute (it holds the upload **token**, not the bytes) plus a file input (`as: :file`, `:uppy`, or `:attachment`):
+
+```ruby
+step :photo, label: "Photo" do
+  attribute :photo, :string
+  input :photo, as: :file                    # server-side staged (default)
+  # input :photo, as: :uppy, direct_upload: true, endpoint: "/upload"  # direct upload
+end
+```
+
+`data` is JSON staged across requests, so a file can't ride along — only its backend **token** (an ActiveStorage signed_id, or active_shrine/Shrine cached-file data). `execute` assigns the token to the model's attachment natively (`model.photo.attach(data.photo.photo)` for AS, `model.update!(photo: data.photo.photo)` for active_shrine). The review summary and the input preview (on Back/resume) resolve the token to a displayable attachment automatically.
+
+| | Declare | Behaviour |
+|---|---|---|
+| **Server-side** (default) | `as: :file` | file submitted with the step; the wizard uploads it to the backend cache while staging. AS *and* active_shrine. |
+| **Direct upload** | `as: :uppy, direct_upload: true, endpoint:` | browser uploads to the endpoint, posts a token (async UI). |
+| **Backend** (server-side) | `backend: :active_storage` / `:shrine` | defaults to `config.wizards.attachment_backend` (auto-detects active_shrine, else AS). **Must match the model** `execute` assigns to. |
+| **Uploader** (Shrine only) | `uploader: PhotoUploader` | cache the file through a specific Shrine uploader (its cache-stage plugins — mime/dimension extraction, `generate_location`, processing — run instead of base `Shrine`'s). The minted token stays uploader-agnostic, so display + promotion are unaffected. Accepts a class or a class-name string; raises for the AS backend. Server-side staging only (direct upload configures the uploader at its endpoint). Its **validations are enforced on the step** — see the note below. |
+| **Multiple** | array attribute + `multiple: true` | staged value is an array of tokens. |
+
+::: tip Uploader validations are enforced on the step
+A Shrine file field is validated **on its step** against the field's **effective uploader** — its `uploader:` if given, else base `Shrine` (whichever carries the `Attacher.validate` rules). A file that violates them is rejected right there (a field error + re-render), exactly like a `validates` — *not* deferred to `execute`. Mechanically: `Uploader.upload` caches the file (running no validations), then the step's validation pass runs the attacher's validations against the staged token. This needs Shrine's optional `validation`/`validation_helpers` plugin — without it there's nothing to enforce and it's a clean no-op. ActiveStorage fields are likewise unaffected.
+:::
+
+## Per-step hooks
+
+`execute` is the default commit point (atomic, at the end). Per-step `on_submit` is opt-in save-as-you-go — use it only when a real record must exist mid-flow.
+
+### `on_submit`
+
+Runs in its own transaction when the step completes (after its fields validate). Inside it:
+
+- `persist record` (or a list) — register record(s) the engine tracks for resume + cleanup → `persisted[:step_key]`.
+- `fail!("message")` — abort with a base (form-level) error.
+- `fail!(:field, "message")` — abort with a field-level error.
+
+```ruby
+on_submit do
+  charge = PaymentApi.authorize!(anchor, data.billing.card_token)
+  fail!("Card was declined") unless charge.ok?
+  persist Billing.create!(company: anchor, token: data.billing.card_token, charge_id: charge.id)
+end
+```
+
+The wizard never advances past a failed `on_submit`. Earlier committed steps are untouched (undo them via Cancel → cleanup).
+
+### `on_rollback`
+
+Rollback happens on Cancel, abandonment-sweep, **or when this step becomes branch-hidden** (a later answer flips its `condition:` false, so save-as-you-go records it created would otherwise be orphaned). On any of these, the engine **always** destroys every `persist`'d record in reverse step order via `destroy!` (which respects a model's own soft-delete/paranoia override). When a step is pruned this way its `data` / `persisted` / `visited` state is also cleared, so re-entering that branch re-runs `on_submit` from scratch.
+
+`on_rollback` is an **optional, ADDITIONAL** compensating block for side effects the engine can't see: refunding a charge, calling an external API, deleting something `persist` didn't track. It reads `persisted[...]` and runs **before** the engine's destroy (records still alive), **in addition to** it, never instead of it. Don't destroy the `persist`'d record yourself in the block; the engine does that.
+
+```ruby
+# The engine destroys persisted[:billing] for you; this just refunds the charge.
+on_rollback { PaymentApi.refund!(persisted[:billing].charge_id) }
+```
+
+Supply an `on_rollback` when abandonment must do more than drop the record(s) (refund a charge, call an external API), or when `on_submit` registered no record at all (side-effect-only steps, whose `on_rollback` still runs). To *keep* a partial record rather than destroy it, make the model itself soft-delete (so its `destroy!` detaches) or use `cleanup_after :never`.
+
+## `review`
+
+```ruby
+review(label: "Review", description: nil, condition: nil, summary: true, header: true, &block)
+```
+
+The built-in **terminal** step. Must be last. It lists outstanding (invalid/unvisited) steps as jump links and gates Finish until all visible steps are valid. It declares no fields of its own.
+
+What it renders depends on completion state and the `summary:` / block options:
+
+| State | Body |
+|---|---|
+| **Incomplete** (a visible step is invalid/unvisited) | The outstanding "fix this" links **+** the auto-summary of what's entered so far (the review-and-fix view). |
+| **Complete**, `summary: true` (default) | The auto-summary of every visible step; the custom block, if any, renders **below** it. |
+| **Complete**, `summary: false`, with a block | The custom block **replaces** the summary (author owns the body). |
+| **Complete**, `summary: false`, no block | A built-in "ready to complete" confirmation panel. |
+
+| Option | Meaning |
+|---|---|
+| `label:` | The review step's label (default `"Review"`). |
+| `description:` | Optional sub-label under the review heading. |
+| `summary:` | Show the auto-summary of completed steps (default `true`). When `false`, the complete-state body is your block — or the built-in "ready to complete" panel if there's no block. The summary always renders in the incomplete state. |
+| `header:` | Show the step-header section (the label plus the "check everything over" prompt, which only appears when the summary is shown) above the body (default `true`). `false` drops it for a chromeless finish. |
+
+```ruby
+review label: "Review & submit"                       # auto-summary + gated finish
+
+review label: "Review & submit" do |wizard|           # custom content BELOW the summary
+  "By submitting you agree to the #{wizard.data.plan.plan} plan terms."
+end
+
+review summary: false, header: false                  # fully chromeless → "ready to complete" panel
+```
+
+::: tip
+`stepper false` (a wizard-level macro) + `review summary: false, header: false` + no block gives a fully chromeless flow (no rail, no header, no summary), ending on the built-in "ready to complete" panel.
+:::
+
+### The custom block's render context
+
+The block runs **in the Phlex view context** (`self` is the rendering component), not the controller — that's what lets it emit markup. So you can:
+
+- **return a String** (the simplest case) — it renders as the block's text;
+- **emit Phlex** directly — `div`, `span`, `plain`, `render SomeComponent.new(...)`;
+- reach **view / route helpers** via `helpers.*` (e.g. `helpers.link_to`, `helpers.current_user`, a path helper).
+
+The block is **yielded the wizard**, so `wizard.data`, `wizard.anchor`, `wizard.persisted`, and `wizard.current_user` are all in hand.
+
+```ruby
+review label: "Review & submit" do |wizard|
+  div(class: "text-sm") do
+    plain "Billing to "
+    strong { wizard.data.company.name }
+    plain " — "
+    plain helpers.link_to("see our terms", helpers.terms_path)
+  end
+end
+```
+
+Don't mix styles in one block: Phlex emits a returned String *in addition to* anything you wrote with `div`/`render`, so returning a String after emitting markup double-renders it. Pick one.
+
+## `completed`
+
+```ruby
+completed do |wizard|
+  # …Phlex body…
+end
+```
+
+A custom body for the **"already completed" page** — what a finished [one-time wizard](/reference/wizard/one-time#re-opening-a-completed-wizard) shows when a user re-opens it. On completion a one-time wizard retains its row but clears the `data`, so there's nothing to review; re-entry renders this standalone page instead of re-running the flow. Only meaningful for one-time wizards (repeatable ones leave no completed row, so re-launching just starts fresh).
+
+Without `completed`, a built-in confirmation renders (a success badge, the wizard's label, a short message, and a Continue button out). The block **replaces that body entirely** — you supply your own content (and your own way out):
+
+```ruby
+class WelcomeWizard < Plutonium::Wizard::Base
+  concurrency_key { current_user }
+  one_time
+  # …steps…
+
+  completed do |wizard|
+    h1 { "You're all set up!" }
+    a(href: "/dashboard") { "Go to your dashboard" }
+  end
+end
+```
+
+The block runs in the **same Phlex view context** as the [review block](#the-custom-block-s-render-context) (`self` is the component; reach helpers via `helpers.*`) and is yielded the `wizard`. The same don't-mix-styles caveat applies.
+
+## `execute`
+
+The at-end commit hook, run once after the last visible step, in one transaction.
+
+```ruby
+def execute
+  company = Company.create!(name: data.company.name, subdomain: data.company.subdomain)
+  succeed(company).with_message("You're all set!")
+end
+```
+
+- Returns a `succeed(value)` / `failed(errors)` Outcome (the same Outcome interactions use — `.with_message`, `.with_redirect_response`, etc. all work).
+- **Use bang methods** so a failure raises. The engine catches `ActiveRecord::RecordInvalid` (→ field errors) and `Plutonium::Wizard::StepError` (→ base error via `fail!`); any other error re-raises as a 500.
+- On success the wizard marks the session completed, clears `data`/`persisted`, and redirects (PRG) so a back-button replay can't re-run `execute`.
+
+## Entry authorization — `authorize?`
+
+A portal-level (standalone) wizard has no resource policy, so gate entry by defining an `authorize?` instance method. The controller checks it before each request; a falsy return → `ActionPolicy::Unauthorized` (403).
+
+```ruby
+def authorize?
+  current_user.present? && !current_user.onboarded?
+end
+```
+
+::: warning As-built: `authorize?` is an instance method
+Define `def authorize?` on the wizard. (Resource-attached wizards instead use their action's policy predicate — see [Registration & launch](/reference/wizard/registration-launch).)
+:::
+
+## Accessors
+
+Available inside steps, `condition:`, `on_submit`, `on_rollback`, and `execute`:
+
+| Accessor | Returns |
+|---|---|
+| `data` | Typed, dot-accessible snapshot of everything entered so far, **step-keyed** — read a field through its owning step: `data.<step>.<field>`. Read-only; not-yet-collected fields read as `nil` or their `default:`. Each step has its own sub-object, so two steps may declare the same field name without colliding. |
+| `data.<step>.<field>` | The cast value (real Boolean/Integer/Date, not raw string). `data.<step>.<structured>` → array of typed sub-objects. An unknown step key reads as `nil`. |
+| `anchor` | The record the wizard was launched against. Raises `NotAnchoredError` if the wizard isn't `anchored`. |
+| `persisted[:step_key]` | Record(s) a per-step `on_submit` registered via `persist`. Lazily rehydrated on first access (located from stored GlobalIDs the first time you read the key, memoized thereafter). |
+
+## Outcome helpers
+
+| Helper | Use |
+|---|---|
+| `succeed(value = nil)` | Success outcome (alias `success`). Chain `.with_message(...)`, `.with_redirect_response(...)`. |
+| `failed(errors = nil, attribute = :base)` | Failure outcome. Accepts a string, an array, a hash (`{field => msg}`), or an errors object. |
+| `fail!("message")` / `fail!(:field, "message")` | Raise a `StepError` from `on_submit`/`execute` (sugar over `raise`). |
+
+## Errors
+
+| Error | Raised when |
+|---|---|
+| `Plutonium::Wizard::NotAnchoredError` | `anchor` called on a non-anchored wizard (also raised when a `via:` anchor resolves to `nil` or the wrong type). |
+| `Plutonium::Wizard::StepError` | Raised by `fail!` (or directly) for a custom, non-AR step failure → maps to a form error. |
+| `Plutonium::Wizard::UnknownWizardError` | A mount's `wizard_class` doesn't resolve to a loaded `Plutonium::Wizard::Base` subclass — a misconfigured mount or a tampered route param. |
+
+## Related
+
+- [Anchoring & resume](/reference/wizard/anchoring-resume)
+- [Storage & config](/reference/wizard/storage-config)
+- [Registration & launch](/reference/wizard/registration-launch)
+- [One-time wizards](/reference/wizard/one-time)

data/docs/reference/wizard/index.md

@@ -0,0 +1,33 @@
+# Wizard Reference
+
+The wizard subsystem builds **multi-step flows** — onboarding, checkout, multi-model create, branching questionnaires — as a single declarative class (`< Plutonium::Wizard::Base`). It orchestrates Plutonium's existing field DSL, form rendering, actions, and policies rather than inventing a parallel stack.
+
+For a task-oriented walkthrough, start with the [Wizards guide](/guides/wizards).
+
+## In this section
+
+- **[DSL](./dsl)** — every author-facing macro and accessor: `step`, `review`, `using:`, `condition:`, per-step `on_submit`/`persist`/`on_rollback`, `execute`, `data`/`anchor`/`persisted`.
+- **[Anchoring & resume](./anchoring-resume)** — running against an existing record (`anchored` / `anchor`), instance identity, and how a user resumes where they left off.
+- **[Storage & config](./storage-config)** — enabling the subsystem, the `plutonium_wizard_sessions` table, `config.wizards.*`, encryption, and the cleanup `SweepJob`.
+- **[Registration & launch](./registration-launch)** — reaching a user: the `wizard` definition macro and portal-level `register_wizard`.
+- **[One-time wizards](./one-time)** — `concurrency_key` + `one_time` durable completion markers and the `ensure_wizard_completed` gate.
+
+## At a glance
+
+| Concept | Macro / accessor |
+|---|---|
+| Launch chrome | `presents label:, icon:, description:` |
+| A screen | `step :key, label:, condition:, using: do ... end` |
+| Branching | `condition: -> { data.<step>.<field> ... }` (subtractive, nil-safe) |
+| Field reuse | `using: Model, fields:/only:/except:` (model only) |
+| Terminal recap | `review label:` |
+| Per-step write | `on_submit { persist record; fail!(...) }` + `on_rollback` |
+| Commit | `def execute` → `succeed(...)` / `failed(...)` (use bang methods) |
+| Existing record | `anchored with: Model` / `anchored via: :method` → `anchor` |
+| Concurrency / resume | `concurrency_key { … }` (keyed row is the lock; tenant folded in) |
+| Run once | `concurrency_key { … }` + `one_time` + `ensure_wizard_completed` |
+| Cleanup TTL | `cleanup_after <ttl> \| :never` (+ `SweepJob`) |
+
+## Prerequisite
+
+Wizards are opt-in. Set `config.wizards.enabled = true` and run `rails db:migrate`. See [Storage & config](./storage-config).