plutonium 0.60.5 → 0.61.0

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

@@ -0,0 +1,129 @@
+# 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.
+
+## 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).
+
+```ruby
+class WelcomeWizard < Plutonium::Wizard::Base
+  presents label: "Welcome"
+
+  concurrency_key { current_user }   # the stable row to retain (tenant folded in)
+  one_time                            # retain the completed row → never again
+
+  step :greeting do
+    attribute :acknowledged, :string
+    input :acknowledged
+    validates :acknowledged, presence: true
+  end
+
+  review label: "Review"
+
+  def execute
+    succeed.with_message("Welcome aboard!")
+  end
+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).
+- **`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`.
+
+## 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.
+
+Supply a [`completed` block](/reference/wizard/dsl#completed) on the wizard to replace that body with your own:
+
+```ruby
+completed do |wizard|
+  h1 { "You're already set up." }
+  a(href: "/dashboard") { "Back to your dashboard" }
+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.
+
+## 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.
+
+```ruby
+module AdminPortal
+  class DashboardController < AdminPortal::PlutoniumController
+    include Plutonium::Wizard::Gate
+    ensure_wizard_completed ::WelcomeWizard
+  end
+end
+```
+
+Flow:
+
+1. An un-completed user hits the gated page → the gate stashes their destination (`session[:return_to]`) and redirects to the wizard's first step.
+2. The user completes the wizard → finalize records the durable completion marker.
+3. The gate now passes them through; the controller bounces them back to the stashed destination (PRG).
+4. A completed user passes straight through, every time.
+
+Extra options (`only:` / `except:`) are forwarded to `before_action`:
+
+```ruby
+ensure_wizard_completed ::WelcomeWizard, only: %i[index show]
+```
+
+The entry URL is derived from the `register_wizard` route helper (`<name>_wizard_path(step: <first_step>)`). Override `wizard_entry_path` for a custom mount. When gating from **outside** the wizard's own portal, also override `wizard_gate_route_set` (default `current_engine.routes`) so the gate looks the launch route up in the route set where the wizard is actually mounted.
+
+## How the gate keys completion
+
+The gate **recomputes the wizard's `instance_key`** from its `concurrency_key`, resolving the key block against the **host controller**, so `current_user`, `current_scoped_entity` (folded automatically), `anchor`, and any custom host method are available. It then checks `completed?(instance_key:)`. This digest is computed by the same `Plutonium::Wizard.compute_instance_key` the runner uses, so the gate sees exactly the marker the wizard recorded.
+
+### 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:
+
+- **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
+  ensure_wizard_completed ConfigureWizard, anchor: -> { current_account.widget }
+  ```
+
+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.
+
+::: 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.
+:::
+
+## The launch action hides itself once completed
+
+When you register a one-time wizard on a resource definition with the [`wizard` macro](/reference/wizard/registration-launch), the synthesized launch action (button/link) is **automatically hidden once the current user has completed it**. The macro attaches a render-time `condition:` to the action that recomputes the wizard's `instance_key` for the current context (the same `Plutonium::Wizard.compute_instance_key` the driving layer and the [gate](#how-the-gate-keys-completion) use) and returns false when a retained `completed` row exists at that key:
+
+```ruby
+class CompanyDefinition < Plutonium::Resource::Definition
+  wizard :onboard, CompanyOnboardingWizard   # one_time → button vanishes after completion
+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.
+
+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,
+  condition: -> { current_user.admin? }   # admin AND not yet completed
+```
+
+## 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.

data/docs/reference/wizard/registration-launch.md

@@ -0,0 +1,177 @@
+# Registration & launch
+
+A wizard reaches a user one of two ways: as a **resource action** (the `wizard` macro on a definition) or as a **route-mounted entry** (`register_wizard`) — inside a portal *or* on the main application. A portal mount inherits the portal's authentication, tenant scoping entity, layout, and Phlex rendering, exactly like a resource; a main-app mount runs standalone (you supply the auth — see [Hosting & the controller override hook](#hosting-the-controller-override-hook)).
+
+## On a resource — the `wizard` macro
+
+A `wizard` macro in a resource definition registers a wizard and synthesizes its launching action — sugar over the Action system.
+
+```ruby
+class CompanyDefinition < Plutonium::Resource::Definition
+  wizard :configure, ConfigureCompanyWizard            # anchored → record action
+  wizard :onboard,   CompanyOnboardingWizard           # no anchor → resource action
+  wizard :archive,   ArchiveWithReasonWizard, record_action: true   # override placement
+end
+```
+
+- **Placement is dictated by the wizard, not chosen** — an **anchored** wizard is a **record** action (it needs a record, the anchor); a **non-anchored** wizard is a collection-level **resource** action (index header). A record-action wizard surfaces on BOTH the record's show page *and* each list row (`collection_record_action`, scoped to that row's record), exactly like `edit`/`destroy`. The only thing you configure is **where a record action shows** (see the table); a flag that doesn't apply to the wizard's kind (e.g. `resource_action:` on an anchored wizard) **raises**.
+- **Auto-mounted on the resource controller** — the `wizard` macro's routes are drawn on the resource's own controller, exactly like interactive record/resource actions. There is nothing else to wire up.
+- **The anchor is IDOR-safe** — an anchored (record) wizard resolves its anchor through the resource controller's scoped, policy-gated `resource_record!`. A record outside the portal's authorized scope (another tenant's, or a non-existent id) **404s**; it is never loaded via an unscoped `find_by`.
+- **Bulk wizards are not supported** — wizards are inherently per-instance flows. Use a bulk interaction instead.
+- **Authorization mirrors actions** — a resource policy predicate named after the wizard key gates it (`def configure? = update?`, `def onboard? = create?`).
+
+| Option | Meaning |
+|---|---|
+| `record_action:` | **(Record wizards only)** show on the record's **show page**. Default `true`; `false` removes it from there. |
+| `collection_record_action:` | **(Record wizards only)** show on each **list row** (scoped to that row's record). Default `true`; `false` keeps it on the show page but off the list. |
+| `label:` / `icon:` / `position:` / `category:` / `confirmation:` / `turbo_frame:` | Standard action chrome — any `action` option passes through. |
+
+Placement isn't an option — it follows `anchored?`. Passing a flag that doesn't apply (`resource_action:` on a record wizard, or `record_action:`/`collection_record_action:` on a resource wizard) raises.
+
+### Synthesized routes (resource-mounted)
+
+```
+# anchored → member route (anchor = the scoped resource_record!)
+GET       /companies/:id/wizards/:wizard_name                 → launch (redirect to step)
+GET/POST  /companies/:id/wizards/:wizard_name(/:token)/:step
+
+# non-anchored → collection route (create flow)
+GET       /companies/wizards/:wizard_name                     → launch (redirect to step)
+GET/POST  /companies/wizards/:wizard_name(/:token)/:step
+```
+
+The synthesized launch action points at the **bare** wizard URL (no step). A `GET` there resolves the run (minting the per-run `:token` for a tokened wizard, or resolving the keyed identity) and redirects to its current step: the **resumed cursor** for an in-progress keyed run, else the **first step**, with the token already in the URL. So clicking the launch button resumes where the user left off (rather than jumping back to step 1) and never forks a fresh run on a first-step reload.
+
+## Route-mounted — `register_wizard`
+
+For a wizard not tied to a single resource (onboarding, welcome, set-up), register it with `register_wizard` — **inside a portal engine's routes** (most common) or **on the main application's routes**, alongside `register_resource`:
+
+```ruby
+# packages/admin_portal/config/routes.rb
+AdminPortal::Engine.routes.draw do
+  register_wizard ::OnboardOrganizationWizard, at: "onboarding"               # in-shell (portal default)
+  register_wizard ::SetupOrgWizard, at: "setup", layout: :basic               # bare (BasicLayout)
+
+  register_resource ::Company
+end
+
+# config/routes.rb — a main-app (portal-less) wizard
+Rails.application.routes.draw do
+  register_wizard ::AppOnboardingWizard, at: "onboarding"                     # main-app default → :basic
+end
+```
+
+| Argument | Meaning |
+|---|---|
+| `at:` (required) | The host-relative base path for the wizard's steps. |
+| `as:` | Override the route helper name prefix (defaults to `at:`, then the wizard's name, e.g. `OnboardOrganizationWizard` → `onboarding`). |
+| `public:` | Mount on a **public (unauthenticated) route** for an [`anonymous`](#public-mount-for-anonymous-wizards) wizard. Defaults to the wizard's own `anonymous?` flag. |
+| `layout:` | The Rails [layout](#layout) to render in (a layout name, like the controller `layout` macro): `:basic` (bare), `:resource` (shell), or any app layout. Defaults by host — **portal → the resource shell**, **main-app → `:basic`**. |
+
+This draws the wizard's step routes within the host (so a portal mount inherits the portal's scope/auth/layout) and dispatches them to a wizard controller. It provides `<name>_wizard_path` / `_url` helpers.
+
+### Hosting & the controller override hook
+
+`register_wizard` resolves the controller it dispatches to **override-first**: if you've defined the conventional controller it is used as-is; otherwise one is synthesized. This is the same "app owns the controller" contract as `register_resource` — there is no hand-written file unless you want to customize.
+
+| Host | Controller | Base / auth |
+|---|---|---|
+| **Portal** | `<Portal>::WizardsController` if defined, else synthesized | the portal's `PlutoniumController` (inherits its auth/scope/layout) |
+| **Main app, authenticated** | `::WizardsController` — **you define it** | yours: a base + `include Plutonium::Auth::Rodauth(:account)` |
+| **Main app, public** (`anonymous`) | `::PublicWizardsController` (synthesized) | a bare base + `Plutonium::Auth::Public` (guest) |
+
+The synthesized **main-app** controller is **bare** — rooted in `ApplicationController`/`ActionController::Base`, deliberately *not* in `::PlutoniumController` (which portals inherit and may carry auth, which would leak into a guest flow). A bare controller has **no `current_user`**, so an **authenticated** main-app wizard requires you to define `::WizardsController` yourself with the auth concern:
+
+```ruby
+# app/controllers/wizards_controller.rb
+class WizardsController < ApplicationController
+  include Plutonium::Wizard::Controller          # the complete include surface
+  include Plutonium::Auth::Rodauth(:user)        # supplies current_user
+end
+```
+
+`Plutonium::Wizard::Controller` is the whole mechanism: including it on any base yields a renderable wizard controller. It pulls in `Plutonium::Core::Controller` (asset/layout machinery) and **contributes the `"plutonium"` view-lookup prefix itself**, so even a bare `ActionController::Base` host resolves the gem's shared partials (`plutonium/_flash`, …). For an app that needs no custom auth base, subclass the ready-made `Plutonium::Wizard::BaseController` (`< ActionController::Base` with the module already included). The module is the contract; the class is sugar.
+
+### Layout
+
+`layout:` is the **Rails layout** the wizard renders in — a layout *name*, exactly like the controller `layout` macro. It's applied at render time, so it works regardless of which controller serves the wizard (without touching the `Page` component):
+
+| `layout:` | Appearance | Layout |
+|---|---|---|
+| `:basic` | no sidebar/topbar — e.g. "set up your organization" | `basic` (`BasicLayout`) |
+| `:resource` | sidebar + topbar + wizard (in-app) | the `resource` shell layout |
+| *(any app layout)* | whatever that layout renders | passed straight to Rails |
+| *(omitted)* | host default — see below | — |
+
+- **Defaults by host:** portal → the `resource` shell; main-app → `:basic` (a bare main-app host has no shell to embed in). Pass `layout:` to override.
+- **Turbo-frame requests are always layout-less** regardless of the setting — that's the embedded/modal path (how resource-anchored `wizard`-macro launches render).
+- `layout:` is a **`register_wizard` option only**; it travels with the mount, not the wizard class. Resource-defined wizards take no `layout:` (always embedded).
+
+### Synthesized routes
+
+```
+GET  /onboarding                  → launch: resolve/mint the run, redirect to its step
+GET  /onboarding(/:token)/:step   → renders the step
+POST /onboarding(/:token)/:step   → advances (the `_direction` param carries next/back/cancel)
+```
+
+The bare **`/onboarding`** is the canonical entry point (helper `onboarding_wizard_launch_path`). A `GET` there resolves the run (minting the per-run `:token` for a tokened wizard, or resolving the keyed/guest identity) and `303`-redirects to its entry step: the **resumed cursor** for an in-progress keyed/guest run, else the **first visible step**. Because the redirect target already carries the token, the address bar shows a stable, shareable run URL from the first paint (the token no longer "appears" only after the first submit, and reloading the first step can't fork a second run). Link to `/onboarding` from menus/dashboards; the stepped `/onboarding(/:token)/:step` URLs are built for you by the engine.
+
+The POST `_direction` param carries `next` / `back` / `cancel`. **Where Cancel sends the user** is captured at launch from a `?return_to=` query param (or the referer), sanitized to a same-host local path that isn't the wizard's own mount (open-redirect-safe); Cancel returns there, falling back to the host root. So linking to `/onboarding?return_to=/dashboard` lands a cancelled run back on the dashboard.
+
+`scope_gid` (folded into the instance key) comes from the portal's scoping entity when the portal is entity-scoped.
+
+## Entry authorization
+
+A portal-level wizard has no resource policy, so gate entry with an `authorize?` instance method on the wizard — checked before each request:
+
+```ruby
+class WelcomeWizard < Plutonium::Wizard::Base
+  def authorize?
+    current_user.present? && !current_user.onboarded?
+  end
+end
+```
+
+A falsy return → `ActionPolicy::Unauthorized` (403). Resource-attached wizards instead use their action's policy predicate (`def onboard?` etc.).
+
+::: danger A portal-level wizard with no `authorize?` is open to ANY authenticated portal user
+A portal-level wizard (registered with `register_wizard`) has **no resource policy** and **defaults to allowed** — so if you omit `authorize?`, every authenticated user of that portal can run it. **Always define `def authorize?`** for anything privileged (admin-only flows, per-user gating, tenant checks). The default-allow is only safe for flows that are genuinely fine for any signed-in portal user (e.g. self-service onboarding).
+:::
+
+::: warning As-built: `authorize?` is an instance method
+Define `def authorize?` on the wizard. The controller checks it only when the wizard responds to it (default: allowed).
+:::
+
+## Public mount for `anonymous` wizards
+
+**Wizards require authentication by default.** A guest ([`anonymous`](/reference/wizard/anchoring-resume#authentication)) wizard needs a route reachable **before** login. Because a portal engine is mounted *inside* the host's authentication constraint (`constraints Rodauth::Rails.authenticate(:user) { mount ... }`), a route drawn in the portal is unreachable pre-login. So `register_wizard` draws an `anonymous` wizard's route on the **main application's** route set, outside that constraint:
+
+```ruby
+# in the portal engine's routes (register_wizard is available there)
+register_wizard ::GuestSignupWizard, at: "signup", public: true
+#   → GET/POST /signup(/:token)/:step  (a top-level, unauthenticated route)
+```
+
+- `public: true` is the **default for an `anonymous` wizard**; you can pass it explicitly for clarity.
+- A **non-`anonymous`** wizard may **not** be mounted public (raises) — and an **`anonymous`** wizard may **not** be mounted authenticated (it would be unreachable pre-login).
+- The public route dispatches to a synthesized top-level `::PublicWizardsController` (a **distinct** const from an authenticated main-app `::WizardsController`, so the two never collapse onto each other) that renders **full-page** with a standalone layout (no resource sidebar / user menu) and treats the request as a guest via `Plutonium::Auth::Public`.
+
+## One-time gating
+
+To make a wizard run once and gate a controller behind it, see [One-time wizards](/reference/wizard/one-time) — a `concurrency_key` + `one_time` + the `Plutonium::Wizard::Gate` concern (`ensure_wizard_completed`).
+
+For a **one-time** wizard, the launch action this macro synthesizes also **hides itself once the current user has completed it** (via a render-time action `condition:`); a custom `condition:` composes with that check. See [The launch action hides itself once completed](/reference/wizard/one-time#the-launch-action-hides-itself-once-completed).
+
+## Constraints
+
+- **`with:`-anchored wizards mount on the resource, not route-level.** Register a `with:`-anchored wizard on the anchored resource's definition with the `wizard` macro (it auto-mounts a member action whose anchor is the scoped `resource_record!`). Passing a `with:`-anchored wizard to **`register_wizard`** raises: a route-level mount has no resource record to anchor to. A **`via:`-anchored** (context-anchored) wizard *does* mount route-level; its anchor is resolved by a controller method, not a URL `:id`.
+- **An authenticated main-app wizard needs an app-defined controller.** The synthesized main-app controller is bare (no `current_user`); supply your own `::WizardsController` with an auth concern (see [Hosting & the controller override hook](#hosting-the-controller-override-hook)). Portal mounts and `anonymous` public mounts need nothing.
+- **Route-helper names must be unique across public mounts.** A public (`anonymous`) wizard's route is drawn on the main app, keyed by its helper name (`as:` → `at:` → class-derived). Two distinct public wizards resolving to the **same** helper name **raise** at draw time — give one an explicit `as:`. (Re-drawing the *same* wizard on a route reload is a no-op, not a collision.)
+
+## Related
+
+- [DSL reference](/reference/wizard/dsl) — `authorize?`, the wizard body.
+- [Anchoring & resume](/reference/wizard/anchoring-resume) — anchors, instance keys.
+- [One-time wizards](/reference/wizard/one-time) — completion + gating.
+- [Custom actions guide](/guides/custom-actions) — the Action system the `wizard` macro builds on.

data/docs/reference/wizard/storage-config.md

@@ -0,0 +1,151 @@
+# Storage & config
+
+The wizard subsystem is DB-backed by a single framework table, gated by an opt-in config flag. This page covers enabling it, the table, configuration, encryption, and the cleanup sweep.
+
+## Enabling the subsystem
+
+Wizards are core code, but the storage table is **opt-in** so apps that don't use wizards stay schema-clean.
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure do |config|
+  config.wizards.enabled = true            # false by default
+  config.wizards.cleanup_after = 14.days   # global default idle TTL for the sweep
+  config.wizards.encrypt_data = true       # encrypt every wizard's data at rest (needs AR encryption keys)
+  config.wizards.attachment_backend = nil  # server-side attachment staging backend (nil = auto-detect)
+end
+```
+
+```bash
+rails db:migrate
+```
+
+| Config | Default | Meaning |
+|---|---|---|
+| `config.wizards.enabled` | `false` | The subsystem's master switch. Registers the gem migration (so `rails db:migrate` creates the table) **and** draws wizard routes — both `register_wizard` and the resource-mounted `wizard`-macro actions. While `false`, `register_wizard` is a no-op (it logs a warning so a registered-but-disabled wizard isn't a silent 404) and no wizard routes are mounted. Required to use wizards. |
+| `config.wizards.cleanup_after` | `14.days` | Global default idle TTL for the abandonment sweep; overridable per wizard via `cleanup_after`. |
+| `config.wizards.database` | `:primary` | Which database connection the wizard table lives on. **v1 supports the primary database only** — see below. |
+| `config.wizards.encrypt_data` | `false` | Encrypt **every** wizard's staged `data` at rest by default. Off by default because it needs ActiveRecord encryption keys; a wizard still overrides it individually with `encrypt_data` / `encrypt_data false`. See [Encryption](#encryption). |
+| `config.wizards.attachment_backend` | `nil` | Storage backend for **server-side** [attachment](/reference/wizard/dsl#attachment-fields) staging (a plain `as: :file` field). `nil` auto-detects — active_shrine installed → `:shrine`, else `:active_storage`. Override per field with `input …, backend:`. Direct-upload fields ignore it (they arrive as a token). |
+
+## Gem-shipped migration
+
+The migration ships **in the gem** and Rails runs it **in place** — there is no copy-into-your-app step (unlike `pu:rodauth`/`pu:invites`, which are app-customized templates). Enabling `config.wizards.enabled` registers the gem migration path; `rails db:migrate` then runs it.
+
+- Once run, the table is dumped into your `schema.rb` / `structure.sql` like any other, so `db:schema:load` on fresh/CI databases recreates it normally.
+- Disable later → the path isn't registered; the existing table is left alone (never auto-dropped).
+- `db:migrate:status` shows the migration's file living in the gem (cosmetic; reads "file missing" if the gem is later removed) — standard for gem-shipped migrations.
+
+::: warning v1 supports the primary database only
+The wizard table lives on your app's **primary** database in v1. `config.wizards.database` is **reserved for future use** — multi-database routing for wizard sessions is a roadmap follow-up. Setting it to anything other than `:primary` (while wizards are enabled) **raises at boot**, rather than silently registering the migration on the primary database.
+:::
+
+## The table — `plutonium_wizard_sessions`
+
+One framework-owned table serves everything; **no changes to your models.**
+
+| Column | Purpose |
+|---|---|
+| `wizard` | The wizard class name. |
+| `status` | `in_progress` \| `completing` \| `completed` (see the note below). |
+| `current_step` | The step cursor. |
+| `instance_key` (unique) | The deterministic identity digest (see [Anchoring & resume](/reference/wizard/anchoring-resume#instance-identity)). |
+| `owner_type` / `owner_id` | The user (nullable — `null` for an `anonymous`/guest run). Authenticated lookups are owner-scoped against this. |
+| `anchor_type` / `anchor_id` | The anchor record (nullable). |
+| `scope_type` / `scope_id` | The portal scoping entity / tenant (nullable). |
+| `engine` | The portal (engine class name) the run was launched in, e.g. `"OrgPortal::Engine"`. The "continue where you left off" listing only shows (and links) runs whose `engine` matches the portal being viewed (two portals can share an entity scope, so `scope` alone can't identify the portal). |
+| `token` | The per-run id for guest/tokened (no-`concurrency_key`) instances (nullable). |
+| `data` | Staged field values (JSON; `jsonb` on PostgreSQL). |
+| `tracked_records` | GlobalIDs of records registered via `persist`, by step key. Exposed to authors as `persisted[:key]`. |
+| `visited` | Visited step keys. |
+| `expires_at` | Concrete expiry, stamped `now + cleanup_after` on every write (`nil` = `:never`). |
+| `completed_at` | Completion timestamp. |
+
+What the single table powers:
+
+- **Resume** — look up the `in_progress` row by `instance_key`.
+- **One-time check** — does a `completed` row exist for `(wizard, owner)` or `(wizard, anchor)`.
+- **In-progress listing** — by owner, portal (`engine`), and tenant scope, so a run is only ever listed by the portal it was launched in.
+- **Multi-tenancy** — the portal scoping entity is folded into `instance_key` and stored as `scope_*`, so the same user's same non-anchored wizard doesn't collide across tenants.
+- **Sweep** — idle `in_progress`/`completing` rows past `expires_at`.
+
+::: tip The `persisted` / `tracked_records` naming
+The column is `tracked_records`, not `persisted` — an AR attribute named `persisted` collides with `ActiveRecord::Persistence#persisted?`. The author-facing accessor stays `persisted[:key]`; the store maps it to the column.
+:::
+
+## Encryption
+
+A wizard may opt into encrypting its staged field values at rest, for flows that stage PII:
+
+```ruby
+class CheckoutWizard < Plutonium::Wizard::Base
+  encrypt_data
+  # ...
+end
+```
+
+This encrypts the `data` column (the staged step values) — off by default. The `tracked_records` column (record GlobalIDs only) and the queried `owner`/`anchor`/`scope`/`token` columns stay plaintext.
+
+**Encrypt everything by default.** Once your app has ActiveRecord encryption keys, you can flip encryption on for *all* wizards with one global flag, then override per wizard:
+
+```ruby
+config.wizards.encrypt_data = true   # every wizard's `data` is encrypted at rest
+```
+
+```ruby
+class PublicSurveyWizard < Plutonium::Wizard::Base
+  encrypt_data false   # explicit opt-OUT, even when the global default is on
+end
+```
+
+Resolution: an explicit `encrypt_data` / `encrypt_data false` on the wizard always wins; a wizard that declares neither inherits `config.wizards.encrypt_data` (off unless you set it). It stays opt-in globally because it requires keys — see the warning below.
+
+**How it works.** Because `data` is one shared `jsonb` column across all wizards (some opting in, some not), a static model-level `encrypts :data` doesn't fit (it would encrypt every row, and fights the `jsonb` type). Instead, the store encrypts at write time using **ActiveRecord's configured encryptor** (`ActiveRecord::Encryption.encryptor`, the same keys as `encrypts`) and stores a self-describing envelope inside the column:
+
+```json
+{ "_enc": "<ciphertext>" }
+```
+
+A row therefore decrypts based on its **own shape**, independent of the wizard's current `encrypt_data?` — so toggling the flag never strands existing runs.
+
+::: warning Requires ActiveRecord encryption keys
+`encrypt_data` reuses your app's ActiveRecord encryption keys (`active_record.encryption.primary_key` / `deterministic_key` / `key_derivation_salt`, typically via credentials). If a wizard declares `encrypt_data` but no keys are configured, the **first write raises** a `Configuration` error naming the wizard — rather than ActiveRecord's later, context-free failure. Set the keys (`bin/rails db:encryption:init`) before enabling it.
+:::
+
+## Files
+
+A file can't sit in the JSON `data` column, so a wizard stages only the backend's **upload token** (an ActiveStorage `signed_id`, or Shrine cached-file data) and `execute` assigns it to the model's attachment. This works for both server-side and direct uploads, ActiveStorage and active_shrine. See [DSL › Attachment fields](/reference/wizard/dsl#attachment-fields) and the [guide](/guides/wizards#file-uploads-attachments) for the full surface (`backend:`, `multiple:`, direct upload).
+
+A staged-then-abandoned upload is an unattached blob / cached Shrine file. **Each storage backend's own unattached-cache cleanup reaps it — the wizard `SweepJob` does not** (it only tracks records registered via `persist`). Ensure that backend cleanup runs.
+
+## Cleanup & the SweepJob
+
+`cleanup_after` stamps a concrete `expires_at` (`now + ttl`) on every write, so an actively-progressing wizard keeps pushing its expiry forward. A later change to the wizard's TTL never retroactively shifts existing rows. `cleanup_after :never` stores a null `expires_at`, opting out of sweeping (partial records persist by design).
+
+`Plutonium::Wizard::SweepJob` reaps idle `in_progress` / `completing` rows past `expires_at`: for each it runs the wizard's cleanup (each step's `on_rollback` if declared, then always destroy every tracked record, in reverse order) and deletes the row. Completed rows are never touched. The job is idempotent and safe to re-run.
+
+::: tip The `completing` state and its grace window
+A healthy finalize flips the row to `completing` and runs `execute` **outside** the completion lock (so a long `execute` doesn't block other requests), without bumping `expires_at`. To avoid sweeping a finalize that's still running, the sweep only reaps a `completing` row once it's been idle for a 15-minute grace window — long enough that a still-`completing` row past it is a *crashed* finalize, not a slow one. Keep individual `execute`s well under 15 minutes (offload long work to a job).
+:::
+
+### SweepJob is load-bearing for save-as-you-go
+
+::: warning Schedule the SweepJob
+- For **`execute`-only** wizards, an unscheduled sweep merely leaves stale session rows (harmless).
+- For **`on_submit` (save-as-you-go)** wizards, the sweep is the **only** thing that cleans up abandoned real domain records. Without it, partial records accumulate forever.
+
+Schedule `Plutonium::Wizard::SweepJob` as a recurring job (e.g. via your scheduler / cron / `solid_queue` recurring tasks) for any app that uses `on_submit`.
+:::
+
+```ruby
+# e.g. a recurring job
+Plutonium::Wizard::SweepJob.perform_later
+```
+
+On completion of a one-time wizard, the row is kept as the durable marker but its `data` / `tracked_records` are nulled out (privacy + size).
+
+## Related
+
+- [Anchoring & resume](/reference/wizard/anchoring-resume) — `instance_key`, resume.
+- [DSL reference](/reference/wizard/dsl) — `cleanup_after`, `encrypt_data`, `persist`.
+- [One-time wizards](/reference/wizard/one-time) — durable completion markers.

data/docs/superpowers/plans/2026-06-14-form-sectioning.md

@@ -169,7 +169,7 @@ module Plutonium
       UNGROUPED_KEY = :ungrouped
 
       # One declared section, or the implicit `ungrouped` bucket (empty `fields`).
-      Section = Struct.new(:key, :fields, :options, keyword_init: true) do
+      Section = Struct.new(:key, :fields, :options) do
         def ungrouped? = key == UNGROUPED_KEY
         def label = options.fetch(:label) { key.to_s.humanize }
         def description = options[:description]
@@ -181,7 +181,7 @@ module Plutonium
 
       # A section paired with the concrete fields it will render (after policy
       # filtering). Produced by #resolve_form_sections.
-      ResolvedSection = Struct.new(:section, :fields, keyword_init: true)
+      ResolvedSection = Struct.new(:section, :fields)
 
       # Collects section/ungrouped calls from a form_layout block in order.
       class Builder