plutonium 0.65.0 → 0.66.0

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

@@ -4,7 +4,7 @@ How a wizard binds to an existing record (anchoring), how a running wizard is id
 
 ## 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.
+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
@@ -28,12 +28,12 @@ end
 | 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. |
+| `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.
+# A generic, shareable wizard: bound to a concrete type at registration.
 class ArchiveWithReasonWizard < Plutonium::Wizard::Base
   anchored
 
@@ -59,15 +59,15 @@ anchor   # => the record, for an anchored wizard
 
 `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.
+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.
+- **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.
@@ -75,7 +75,7 @@ Because the anchor comes from `resource_record!` (the same scoped lookup CRUD an
 
 ## 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)):
+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:
@@ -86,11 +86,11 @@ 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.
+- **`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.
+- **`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), so there is 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.
+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.
@@ -100,7 +100,7 @@ Because the salt is `secret_key_base`, rotating it changes every instance-key di
 
 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).
+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
 
@@ -109,39 +109,40 @@ 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**.
+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.
+**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.
+**`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, which is 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:`.
+- Enrichment is the costly part: every returned row gets its resume and cancel URLs resolved and its anchor loaded. Fetching the full list and then `select { |e| e.wizard_class == X }` pays that cost for every draft you throw away, so pass `wizard:` instead. Avoid filtering on `e.session.anchor` (a polymorphic load per row); use `anchor:`.
+- The one case for post-filtering: the **same render** already calls the unfiltered `in_progress_for` (a full "continue where you left off" list plus a per-wizard callout on one page). Those entries are already enriched, so `select` on `e.wizard_class` is free, while a second `wizard:` call would query and enrich those rows again.
 
 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).
+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.
+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).
+- `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.
+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:
+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
@@ -149,13 +150,13 @@ 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.
+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`.
+- 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.
 
@@ -179,7 +180,7 @@ class GuestSignupWizard < Plutonium::Wizard::Base
 
   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
+    # sign the account in here (the host calls Rodauth), no special framework handling
     succeed(account)
   end
 end
@@ -189,6 +190,6 @@ An `anonymous` wizard must be [mounted on a public route](/reference/wizard/regi
 
 ## 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.
+- [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

@@ -1,37 +1,37 @@
 # Wizard DSL
 
 ::: warning Experimental
-Wizards are experimental — the DSL and behavior may change in a future release.
+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.
+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.
+- **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.
+- **`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. |
+| `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). |
+| `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). |
-| `width <size>` | Width of this wizard's step pages: `:sm` `:md` `:lg` `:xl` `:full`. Inherits to subclasses; otherwise `config.wizards.width` (default `:md`). Deliberately independent of `config.default_page_width` — see [Storage & config](/reference/wizard/storage-config). |
-| `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). |
+| `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). |
+| `width <size>` | Width of this wizard's step pages: `:sm` `:md` `:lg` `:xl` `:full`. Inherits to subclasses; otherwise `config.wizards.width` (default `:md`). Deliberately independent of `config.default_page_width`, see [Storage & config](/reference/wizard/storage-config). |
+| `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
@@ -76,17 +76,17 @@ The block is optional only when `using:` supplies everything.
 
 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.
+- `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.
 
 #### Runtime input options
 
-A step's fields are fixed when the class loads, so a **proc** is how an option depends on the run. Proc-valued field/input options are resolved on every render, and the proc **takes the form** — `form.wizard` is the run, `form.object` is that step's staged data:
+A step's fields are fixed when the class loads, so a **proc** is how an option depends on the run. Proc-valued field/input options are resolved on every render, and the proc **takes the form**: `form.wizard` is the run, `form.object` is that step's staged data:
 
 ```ruby
 step :plan do
@@ -104,15 +104,15 @@ input :answers, as: MyManifestComponent, config: ->(form) { form.wizard.anchor.m
 ```
 
 ::: warning Take the argument
-A **zero-argument** proc here will not work. It keeps its own binding — the same rule as [everywhere else](/reference/resource/definition#options-that-vary-per-render) — and a step block is `instance_exec`'d against an internal field recorder when the class loads, so `-> { anchor.available_tiers }` looks `anchor` up on that recorder and raises `NameError`.
+A **zero-argument** proc here will not work. It keeps its own binding (the same rule as [everywhere else](/reference/resource/definition#options-that-vary-per-render)), and a step block is `instance_exec`'d against an internal field recorder when the class loads, so `-> { anchor.available_tiers }` looks `anchor` up on that recorder and raises `NameError`.
 
 That is deliberate: it is the same trade a `form_layout` section option makes, and it means an `input` line keeps its meaning when moved between a definition and a step. Nothing silently swaps `self`.
 :::
 
 Two limits worth knowing:
 
-- The **field set** is still fixed at class load. A proc varies an option, not which fields exist. To collect a shape known only at runtime, declare one `structured_input` and let a custom component render the inner controls. For bespoke markup, pass a block to `input` instead — it renders in the form's context with the field yielded.
-- `condition:` is **not** resolved this way, because it is not an option — it asks "should this render here, now?", so it always runs *against* the thing doing the rendering and reads it with no argument. A *step's* `condition:` runs against the **wizard** (it is evaluated in the runner to decide which steps exist, before any form is built — which is exactly why it can't be handed a form); a *field's* runs against the **form**, where `object` is that step's staged data. See [Definition › `condition:` is not an option](/reference/resource/definition#condition-is-not-an-option).
+- The **field set** is still fixed at class load. A proc varies an option, not which fields exist. To collect a shape known only at runtime, declare one `structured_input` and let a custom component render the inner controls. For bespoke markup, pass a block to `input` instead, it renders in the form's context with the field yielded.
+- `condition:` is **not** resolved this way, because it is not an option (it asks "should this render here, now?", so it always runs *against* the thing doing the rendering and reads it with no argument. A *step's* `condition:` runs against the **wizard** (it is evaluated in the runner to decide which steps exist, before any form is built) which is exactly why it can't be handed a form); a *field's* runs against the **form**, where `object` is that step's staged data. See [Definition › `condition:` is not an option](/reference/resource/definition#condition-is-not-an-option).
 
 ### `using:` a model
 
@@ -132,7 +132,7 @@ 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. |
+| `<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. |
 
@@ -144,10 +144,10 @@ What gets imported:
 | `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.
+**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.
+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
@@ -162,31 +162,31 @@ step :photo, label: "Photo" do
 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.
+`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. |
+| **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.
+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.
+`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.
+- `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
@@ -232,13 +232,13 @@ What it renders depends on completion state and the `summary:` / block options:
 |---|---|
 | `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. |
+| `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. |
 
 The auto-summary renders each field through the display pipeline, honoring the input's declared `as:`/`label:`. An input hidden by its own `condition:` is left out, just as it was left off the step, so the summary never shows an empty row for a question the user wasn't asked:
 
 - a **choice input** (`select`/`radio_buttons` with `choices:`) resolves the stored value back to its label (`"pro"` → `"Pro"`) using the same choice mapper the form uses, so the recap matches what the user picked;
-- an **`as: :currency`** input formats the value as currency (`"1500.5"` → `"$1,500.50"`) rather than echoing a bare decimal — pass `unit:` on the input (the data snapshot has no `has_cents` reflection to infer it from).
+- an **`as: :currency`** input formats the value as currency (`"1500.5"` → `"$1,500.50"`) rather than echoing a bare decimal, pass `unit:` on the input (the data snapshot has no `has_cents` reflection to infer it from).
 
 ```ruby
 review label: "Review & submit"                       # auto-summary + gated finish
@@ -256,10 +256,10 @@ review summary: false, header: false                  # fully chromeless → "re
 
 ### 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:
+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(...)`;
+- **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.
@@ -269,7 +269,7 @@ review label: "Review & submit" do |wizard|
   div(class: "text-sm") do
     plain "Billing to "
     strong { wizard.data.company.name }
-    plain " — "
+    plain ", "
     plain helpers.link_to("see our terms", helpers.terms_path)
   end
 end
@@ -285,9 +285,9 @@ completed do |wizard|
 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).
+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):
+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
@@ -315,13 +315,13 @@ def execute
 end
 ```
 
-- Returns a `succeed(value)` / `failed(errors)` Outcome (the same Outcome interactions use — `.with_message`, `.with_redirect_response`, etc. all work).
+- 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?`
+## 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).
+A `register_wizard` wizard (portal or main-app) 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). The default is `def authorize? = true`, so define it on every `register_wizard` wizard, including gated `one_time` ones.
 
 ```ruby
 def authorize?
@@ -330,7 +330,7 @@ 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).)
+Define `def authorize?` on the wizard. (Resource-attached wizards instead use their action's policy predicate, see [Registration & launch](/reference/wizard/registration-launch).)
 :::
 
 ## Accessors
@@ -339,12 +339,12 @@ 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` | 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). |
 
-A **proc-valued field/input option** on a step reaches the same accessors through `form.wizard` — see [Runtime input options](#runtime-input-options).
+A **proc-valued field/input option** on a step reaches the same accessors through `form.wizard`, see [Runtime input options](#runtime-input-options).
 
 ## Outcome helpers
 
@@ -360,7 +360,7 @@ A **proc-valued field/input option** on a step reaches the same accessors throug
 |---|---|
 | `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. |
+| `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
 

data/docs/reference/wizard/index.md

@@ -1,16 +1,16 @@
 # 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.
+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.
+- **[DSL](./dsl)**: every author-facing macro and accessor, including `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 via 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
 

data/docs/reference/wizard/one-time.md

@@ -1,10 +1,10 @@
 # One-time wizards
 
-A **one-time** wizard runs once — for onboarding, a one-shot setup, a "welcome" flow. It needs a durable completion marker (you can't remember "done forever" in a session), which the DB store provides as a `completed` session row.
+A **one-time** wizard runs once, for onboarding, a one-shot setup, a "welcome" flow. It needs a durable completion marker (you can't remember "done forever" in a session), which the DB store provides as a `completed` session row.
 
 ## Declaring `one_time`
 
-A one-time wizard is a **keyed** wizard (`concurrency_key`) that **retains** its completed row instead of deleting it. So `one_time` always pairs with a `concurrency_key` — the stable key the retained marker lives at (and the key the gate recomputes).
+A one-time wizard is a **keyed** wizard (`concurrency_key`) that **retains** its completed row instead of deleting it. So `one_time` always pairs with a `concurrency_key`: the stable key the retained marker lives at (and the key the gate recomputes).
 
 ```ruby
 class WelcomeWizard < Plutonium::Wizard::Base
@@ -28,15 +28,15 @@ end
 ```
 
 - **Completion** = the instance row reaching `status: completed`, **retained** at the wizard's `instance_key`.
-- **`one_time` requires a `concurrency_key`** — declaring `one_time` without one raises (there's no stable row to retain). A wizard without `one_time` deletes its row on completion (repeatable).
+- **`one_time` requires a `concurrency_key`**: declaring `one_time` without one raises (there's no stable row to retain). A wizard without `one_time` deletes its row on completion (repeatable).
 - **`concurrency_key { current_user }`** keys completion per user; **`concurrency_key { anchor }`** keys it per anchored record ("set up *this* workspace once"). The **tenant (`current_scoped_entity`) is folded in automatically**, so in a tenant portal it's per-(user, tenant) for free.
 - On completion, the row is kept as the marker but its `data` / `tracked_records` are nulled out (privacy + size).
 
-The completion marker is recorded by the wizard's own finalize, the same `execute` → PRG path as any wizard — no extra code in `execute`.
+The completion marker is recorded by the wizard's own finalize, the same `execute` → PRG path as any wizard, no extra code in `execute`.
 
 ## Re-opening a completed wizard
 
-Navigating back to a finished one-time wizard (its URL, or its bare launch route) doesn't re-run it — the retained `completed` row has had its `data` cleared, so there's nothing to resume or review. Instead the wizard renders a standalone **"already completed" page**: a success badge, the wizard's label, a short message, and a Continue button out.
+Navigating back to a finished one-time wizard (its URL, or its bare launch route) doesn't re-run it; the retained `completed` row has had its `data` cleared, so there's nothing to resume or review. Instead the wizard renders a standalone **"already completed" page**: a success badge, the wizard's label, a short message, and a Continue button out.
 
 Supply a [`completed` block](/reference/wizard/dsl#completed) on the wizard to replace that body with your own:
 
@@ -47,9 +47,9 @@ completed do |wizard|
 end
 ```
 
-This is a one-time-only concept: a **repeatable** wizard deletes its row on completion, so re-launching simply starts a fresh run — there's no completed page.
+This is a one-time-only concept: a **repeatable** wizard deletes its row on completion, so re-launching simply starts a fresh run; there's no completed page.
 
-## Gating a controller — `ensure_wizard_completed`
+## Gating a controller: `ensure_wizard_completed`
 
 The `Plutonium::Wizard::Gate` concern installs a `before_action` that redirects users into the wizard until they complete it.
 
@@ -83,10 +83,10 @@ The gate **recomputes the wizard's `instance_key`** from its `concurrency_key`,
 
 ### Gating an anchored wizard
 
-An anchor-keyed wizard (explicit `{ anchor }`, or the [implied anchored key](/reference/wizard/anchoring-resume#the-implied-anchored-key)) keys completion by its anchor — so the gate needs that anchor to recompute the key. It resolves it two ways:
+An anchor-keyed wizard (explicit `{ anchor }`, or the [implied anchored key](/reference/wizard/anchoring-resume#the-implied-anchored-key)) keys completion by its anchor, so the gate needs that anchor to recompute the key. It resolves it two ways:
 
-- **Automatic** for a `via:`-anchored wizard — the gate calls the wizard's own `anchor_via` method on the host controller. Gating a `via: :current_scoped_entity` wizard inside its own entity-scoped portal is zero-config (`ConfigureOrgWizard` gated on an org-portal controller just works).
-- **Explicit** otherwise — pass `anchor:` (a method name or proc, evaluated on the controller) when the anchor isn't auto-resolvable (a `with:`-anchored wizard, or gating from a different context):
+- **Automatic** for a `via:`-anchored wizard, the gate calls the wizard's own `anchor_via` method on the host controller. Gating a `via: :current_scoped_entity` wizard inside its own entity-scoped portal is zero-config (`ConfigureOrgWizard` gated on an org-portal controller just works).
+- **Explicit** otherwise, pass `anchor:` (a method name or proc, evaluated on the controller) when the anchor isn't auto-resolvable (a `with:`-anchored wizard, or gating from a different context):
 
   ```ruby
   ensure_wizard_completed ConfigureWizard, anchor: :current_widget
@@ -95,10 +95,10 @@ An anchor-keyed wizard (explicit `{ anchor }`, or the [implied anchored key](/re
 
 If an anchor-keyed wizard's anchor can't be resolved and no `anchor:` is given, the gate **raises** (rather than silently mis-keying and looping you into the wizard forever). A wizard keyed by a *non-anchor* method the controller doesn't expose still gives the same clear error.
 
-A wizard keyed by an anchor is only gateable **where that anchor can be reconstructed** — a tenant-anchored wizard, within that tenant's context. That's a property of the keying, not a gap in the gate.
+A wizard keyed by an anchor is only gateable **where that anchor can be reconstructed**, a tenant-anchored wizard, within that tenant's context. That's a property of the keying, not a gap in the gate.
 
 ::: warning Only one-time wizards are gateable
-`ensure_wizard_completed` raises unless the wizard is `one_time` (a `concurrency_key` **plus** `one_time`) — only a retained marker can be checked. Repeatable wizards have nothing durable to gate on.
+`ensure_wizard_completed` raises unless the wizard is `one_time` (a `concurrency_key` **plus** `one_time`), only a retained marker can be checked. Repeatable wizards have nothing durable to gate on.
 :::
 
 ## The launch action hides itself once completed
@@ -112,10 +112,10 @@ end
 ```
 
 - It keys exactly like the wizard's own completion: per-user for `concurrency_key { current_user }`, per-anchor for `concurrency_key { anchor }` (the anchor is the record the action sits on), with the tenant folded in.
-- This is **display-only** — like every action `condition:`, it hides the button but does **not** revoke the route. Keep authorization in the policy (`def onboard? = …`).
-- **Repeatable** (non-`one_time`) wizards get **no** completion condition — their launch action always shows.
+- This is **display-only**: like every action `condition:`, it hides the button but does **not** revoke the route. Keep authorization in the policy (`def onboard? = …`).
+- **Repeatable** (non-`one_time`) wizards get **no** completion condition, their launch action always shows.
 
-A custom `condition:` **composes** with the completion check (they're AND-ed) — the action shows only when your condition is met **and** the wizard isn't already completed:
+A custom `condition:` **composes** with the completion check (they're AND-ed): the action shows only when your condition is met **and** the wizard isn't already completed:
 
 ```ruby
 wizard :onboard, CompanyOnboardingWizard,
@@ -124,6 +124,6 @@ wizard :onboard, CompanyOnboardingWizard,
 
 ## Related
 
-- [DSL reference](/reference/wizard/dsl) — `concurrency_key`, `one_time`, `authorize?`.
-- [Storage & config](/reference/wizard/storage-config) — the durable completion row.
-- [Registration & launch](/reference/wizard/registration-launch) — mounting the wizard the gate redirects into.
+- [DSL reference](/reference/wizard/dsl): `concurrency_key`, `one_time`, `authorize?`.
+- [Storage & config](/reference/wizard/storage-config): the durable completion row.
+- [Registration & launch](/reference/wizard/registration-launch): mounting the wizard the gate redirects into.