plutonium 0.64.0 → 0.66.0

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

@@ -1,10 +1,10 @@
 # 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)).
+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
+## 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.
+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
@@ -14,19 +14,19 @@ class CompanyDefinition < Plutonium::Resource::Definition
 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?`).
+- **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. |
+| `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.
+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)
 
@@ -42,9 +42,9 @@ 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`
+## 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`:
+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
@@ -55,7 +55,7 @@ AdminPortal::Engine.routes.draw do
   register_resource ::Company
 end
 
-# config/routes.rb — a main-app (portal-less) wizard
+# config/routes.rb: a main-app (portal-less) wizard
 Rails.application.routes.draw do
   register_wizard ::AppOnboardingWizard, at: "onboarding"                     # main-app default → :basic
 end
@@ -66,21 +66,21 @@ end
 | `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`**. |
+| `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.
+`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, 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:
+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
@@ -94,17 +94,17 @@ end
 
 ### 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:` 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`) |
+| `: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 | — |
+| *(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).
+- **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
@@ -123,7 +123,7 @@ The POST `_direction` param carries `next` / `back` / `cancel`. **Where Cancel s
 
 ## 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:
+A `register_wizard` wizard (portal or main-app) 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
@@ -135,12 +135,12 @@ 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).
+::: danger A `register_wizard` wizard with no `authorize?` is open to ANY authenticated user
+A wizard registered with `register_wizard` (in a portal or on the main app) has **no resource policy**, and the base class defines `def authorize? = true`. If you omit it, every authenticated user of that portal or app can run it. **Define `def authorize?` on every `register_wizard` wizard.** A gated `one_time` wizard is no exception: the gate forces users *into* the wizard but doesn't decide who may run it. For a flow that is genuinely fine for any signed-in user (e.g. self-service onboarding), say so with `def authorize? = true`.
 :::
 
 ::: 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).
+Define `def authorize?` on the wizard. The controller checks it before every request; the inherited default returns `true`.
 :::
 
 ## Public mount for `anonymous` wizards
@@ -154,12 +154,12 @@ register_wizard ::GuestSignupWizard, at: "signup", public: true
 ```
 
 - `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).
+- 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`).
+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).
 
@@ -167,11 +167,11 @@ For a **one-time** wizard, the launch action this macro synthesizes also **hides
 
 - **`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.)
+- **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.
+- [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

@@ -23,25 +23,25 @@ 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.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.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). |
+| `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.
+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.
+- `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 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`
+## The table: `plutonium_wizard_sessions`
 
 One framework-owned table serves everything; **no changes to your models.**
 
@@ -51,7 +51,7 @@ One framework-owned table serves everything; **no changes to your models.**
 | `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. |
+| `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). |
@@ -64,14 +64,14 @@ One framework-owned table serves everything; **no changes to your models.**
 
 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`.
+- **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.
+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
@@ -85,7 +85,7 @@ class CheckoutWizard < Plutonium::Wizard::Base
 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.
+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:
 
@@ -99,7 +99,7 @@ class PublicSurveyWizard < Plutonium::Wizard::Base
 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.
+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:
 
@@ -107,17 +107,17 @@ Resolution: an explicit `encrypt_data` / `encrypt_data false` on the wizard alwa
 { "_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.
+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.
+`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.
+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
 
@@ -126,7 +126,7 @@ A staged-then-abandoned upload is an unattached blob / cached Shrine file. **Eac
 `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).
+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
@@ -147,6 +147,6 @@ On completion of a one-time wizard, the row is kept as the durable marker but it
 
 ## 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.
+- [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/esbuild.config.js

@@ -6,7 +6,8 @@ if (process.argv.includes("--dev")) {
   _context({
     outdir: "src/build",
     entryPoints: [
-      "src/js/plutonium.js"
+      "src/js/plutonium.js",
+      "src/js/plutonium-charts.js"
     ],
     plugins: [
       manifestPlugin({
@@ -24,6 +25,7 @@ else {
       outdir: "src/dist/js",
       entryPoints: [
         "src/js/plutonium.js",
+        "src/js/plutonium-charts.js"
       ],
       minify,
       sourcemap: true,
@@ -34,7 +36,8 @@ else {
     _build({
       outdir: "app/assets",
       entryPoints: [
-        "src/js/plutonium.js"
+        "src/js/plutonium.js",
+        "src/js/plutonium-charts.js"
       ],
       minify,
       sourcemap: true,

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.62.2)
+    plutonium (0.64.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)
@@ -601,7 +601,7 @@ CHECKSUMS
   phlexi-form (0.14.3) sha256=47d69c4a49ba22279ba541b9b110e81d62acc4602513f21bb5c3d29fa9c8d5ca
   phlexi-menu (0.4.1) sha256=f6eeb1eb9597caadeee33a53f1520b3613a6ac616cf1e395e9d734a412895fb2
   phlexi-table (0.2.0) sha256=73bee135adbe73fcdb6fdd2672444373556dd9e6bba61e7b5b20ca8b7a1f822c
-  plutonium (0.62.2)
+  plutonium (0.64.0)
   pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.62.2)
+    plutonium (0.65.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)

data/lib/active_model/validations/array_validator.rb

@@ -52,7 +52,7 @@ module ActiveModel
         errors = record.errors.delete attribute
         return if errors.nil?
 
-        @existing_errors += errors.map { |e| "item #{index + 1} #{e}" }
+        @existing_errors += errors.map { |e| I18n.t("errors.messages.array_item", index: index + 1, message: e) }
       end
 
       def skip?(value, validator_options)

data/lib/active_model/validations/attached_validator.rb

@@ -10,7 +10,7 @@ module ActiveModel
     #
     class AttachedValidator < EachValidator
       def validate_each(record, attribute, value)
-        record.errors.add(attribute, options[:message] || "must be attached") unless value.attached?
+        record.errors.add(attribute, options[:message] || :not_attached) unless value.attached?
       end
     end
   end

data/lib/active_model/validations/url_validator.rb

@@ -35,7 +35,7 @@ module ActiveModel
       def validate_url
         return true if URL_PATTERN.match?(value)
 
-        record.errors.add attribute, (options[:message] || "is not a valid URL")
+        record.errors.add attribute, (options[:message] || :invalid_url)
         false
       end
 
@@ -43,7 +43,7 @@ module ActiveModel
         return true unless options[:image].present?
         return true unless FastImage.type(value).nil?
 
-        record.errors.add(attribute, options[:message] || "is not a valid image URL")
+        record.errors.add(attribute, options[:message] || :invalid_image_url)
         false
       end
     end

data/lib/generators/pu/core/assets/assets_generator.rb

@@ -25,15 +25,23 @@ module Pu
 
       private
 
-      # The asset pipeline assumes the app was generated with esbuild + Tailwind.
-      # Without those, `application.tailwind.css` doesn't exist and the generator
-      # later crashes with a cryptic inject_into_file error. Fail early with a fix.
+      # The asset pipeline assumes the app was generated with esbuild + Tailwind + Stimulus.
+      # Without those, `application.tailwind.css` (Tailwind) and/or
+      # `app/javascript/controllers/index.js` (Stimulus) don't exist, and the generator
+      # later crashes with a cryptic inject_into_file error. Fail early listing every
+      # missing file with a fix.
       def verify_prerequisites
-        return if File.exist?("app/assets/stylesheets/application.tailwind.css")
+        required = [
+          "app/assets/stylesheets/application.tailwind.css",
+          "app/javascript/controllers/index.js"
+        ]
+        missing = required.reject { |path| File.exist?(path) }
+        return if missing.empty?
 
         error <<~MSG
-          Plutonium assets require a Rails app generated with esbuild and Tailwind.
-          Expected app/assets/stylesheets/application.tailwind.css, but it is missing.
+          Plutonium assets require a Rails app generated with esbuild, Tailwind, and Stimulus.
+          Missing files:
+            - #{missing.join("\n  - ")}
 
           Re-create the app with the required flags:
             rails new myapp -a propshaft -j esbuild -c tailwind \\
@@ -46,28 +54,35 @@ module Pu
         copy_file "postcss.config.js", force: true
       end
 
+      # Every package goes through one `add` built for the app's package manager
+      # (bun, yarn 1, yarn 2+, npm or pnpm; see Concerns::JsPackageManager).
+      # Versions ride inline because `pkg@latest` and `pkg@^x.y.z` are the one
+      # spelling all of them share; yarn 1's `upgrade --latest` does not exist
+      # on yarn 2+, and running yarn inside a bun app leaves two lockfiles.
       def install_dependencies
-        failed = []
+        ensure_yarn_node_modules_linker
 
+        command = js_add_command(npm_packages)
+        return if run(command)
+
+        say_status :warn,
+          "`#{command}` failed — your app may not boot until you re-run it",
+          :yellow
+      end
+
+      def npm_packages
         [
-          "@radioactive-labs/plutonium",
+          # Pinned to the gem so the two halves never drift; pu:core:update
+          # keeps them together afterwards.
+          "@radioactive-labs/plutonium@^#{Plutonium::VERSION}",
+          # cssbundling-rails already installs the latest Tailwind on new apps;
+          # apps created on Tailwind 3 are moved to 4 here.
+          "tailwindcss@latest",
           "postcss", "postcss-cli", "postcss-import",
           "@tailwindcss/postcss", "@tailwindcss/forms", "@tailwindcss/typography",
           "cssnano", "marked",
           "flowbite-typography"
-        ].each do |package|
-          run "yarn add #{package}"
-          failed << "yarn add #{package}" unless $?.success?
-        end
-
-        run "yarn upgrade tailwindcss --latest"
-        failed << "yarn upgrade tailwindcss --latest" unless $?.success?
-
-        return if failed.empty?
-
-        say_status :warn,
-          "the following commands failed — your app may not boot until you resolve them:\n  #{failed.join("\n  ")}",
-          :yellow
+        ]
       end
 
       def configure_application

data/lib/generators/pu/core/assets/templates/postcss.config.js

@@ -3,7 +3,7 @@ const plutoniumGemPath = execSync("bundle show plutonium").toString().trim();
 
 module.exports = {
   plugins: {
-    [`${plutoniumGemPath}/postcss-gem-import.js`]: {},
+    [`${plutoniumGemPath}/postcss-gem-import.cjs`]: {},
     'postcss-import': {},
     '@tailwindcss/postcss': {},
     cssnano: {}

data/lib/generators/pu/core/update/update_generator.rb

@@ -45,9 +45,10 @@ module Pu
 
       def update_npm_package
         gem_version = installed_gem_version
+        package = gem_version ? "@radioactive-labs/plutonium@^#{gem_version}" : "@radioactive-labs/plutonium@latest"
 
-        say_status :update, "Updating @radioactive-labs/plutonium to #{gem_version}...", :green
-        run "yarn add @radioactive-labs/plutonium@^#{gem_version}"
+        say_status :update, "Updating #{package} with #{js_package_manager}...", :green
+        run js_add_command(package)
       end
 
       def installed_gem_version

data/lib/generators/pu/dashboard/dashboard_generator.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "../lib/plutonium_generators"
+
+module Pu
+  # Scaffolds a dashboard class and mounts it in a portal (or the main app).
+  #
+  #   rails g pu:dashboard Sales --dest=admin_portal
+  #   rails g pu:dashboard Home --dest=admin_portal --at=/     # the portal root
+  #
+  # Writes `app/dashboards/<portal>/<name>_dashboard.rb` inside the package
+  # and adds `register_dashboard` to its routes. A root mount replaces the
+  # generated `root to: "dashboard#index"` line.
+  class DashboardGenerator < Rails::Generators::NamedBase
+    include PlutoniumGenerators::Generator
+
+    source_root File.expand_path("templates", __dir__)
+
+    desc(
+      "Create a dashboard and mount it in a portal\n\n" \
+      "e.g. rails g pu:dashboard Sales --dest=admin_portal\n" \
+      "     rails g pu:dashboard Home --dest=admin_portal --at=/"
+    )
+
+    class_option :at, type: :string, default: nil,
+      desc: "Mount path under the portal's dashboards/ segment (default: the dashboard name; \"/\" mounts at the root)"
+
+    def start
+      @app_namespace = portal_option(:dest, prompt: "Select destination portal").camelize
+
+      template "dashboard.rb", dashboard_file_path
+      register_dashboard_in_routes
+    rescue => e
+      exception "#{self.class} failed:", e
+    end
+
+    private
+
+    attr_reader :app_namespace
+
+    def main_app? = app_namespace == "MainApp"
+
+    def package_namespace = app_namespace.underscore
+
+    def dashboard_name = "#{class_name.delete_suffix("Dashboard")}Dashboard"
+
+    def dashboard_class_name
+      main_app? ? dashboard_name : "#{app_namespace}::#{dashboard_name}"
+    end
+
+    def dashboard_label = dashboard_name.delete_suffix("Dashboard").titleize
+
+    def mount_path
+      path = options[:at].presence || dashboard_name.delete_suffix("Dashboard").underscore
+      path.to_s.sub(%r{\A/+}, "").sub(%r{/+\z}, "")
+    end
+
+    def root_mount? = mount_path.empty?
+
+    def dashboard_file_path
+      file = "#{dashboard_name.underscore}.rb"
+      main_app? ? "app/dashboards/#{file}" : "packages/#{package_namespace}/app/dashboards/#{package_namespace}/#{file}"
+    end
+
+    def routes_path
+      main_app? ? "config/routes.rb" : "packages/#{package_namespace}/config/routes.rb"
+    end
+
+    def register_line
+      constant = main_app? ? "::#{dashboard_class_name}" : dashboard_class_name
+      %(register_dashboard #{constant}, at: "#{root_mount? ? "/" : mount_path}")
+    end
+
+    # Idempotent: skips when the routes already register this dashboard. A root
+    # mount replaces the portal's generated `root to:` line, since two roots
+    # would clash.
+    def register_dashboard_in_routes
+      content = File.read(File.join(destination_root, routes_path))
+
+      if /^\s*register_dashboard #{Regexp.escape("::" + dashboard_class_name)}\b|^\s*register_dashboard #{Regexp.escape(dashboard_class_name)}\b/.match?(content)
+        say_status :identical, "#{routes_path} already registers #{dashboard_class_name}", :blue
+        return
+      end
+
+      if root_mount? && (match = content.match(/^\s*root to: "dashboard#index".*\n/))
+        gsub_file routes_path, match[0], indent("#{register_line}\n", 2)
+      elsif /^\s*#\s*register resources above\b/.match?(content)
+        insert_into_file routes_path, indent("#{register_line}\n", 2), before: /^\s*#\s*register resources above\b.*/
+      elsif (match = content.match(/^\s*(\w+::Engine|Rails\.application)\.routes\.draw do.*\n/))
+        insert_into_file routes_path, indent("#{register_line}\n", 2), after: match[0]
+      else
+        say_status :warn, "Could not locate routes block in #{routes_path}; add manually: #{register_line}", :yellow
+      end
+    end
+  end
+end

data/lib/generators/pu/dashboard/templates/dashboard.rb.tt

@@ -0,0 +1,25 @@
+<%- if main_app? -%>
+class <%= dashboard_name %> < Plutonium::Dashboard::Base
+  presents label: "<%= dashboard_label %>"
+
+  # Cards sit on a 12-column grid (metric 3, chart and card 6 by default; `span:`
+  # overrides), each in its own lazy turbo frame. `group_by_day` is the groupdate gem.
+  #
+  # metric(:users, icon: Phlex::TablerIcons::Users) { authorized_resource_scope(User).count }
+  # chart(:signups, type: :line, span: 8) { User.group_by_day(:created_at, last: 30).count }
+  # card(:welcome) { p { "Signed in as #{current_user.email}" } }
+end
+<%- else -%>
+module <%= app_namespace %>
+  class <%= dashboard_name %> < Plutonium::Dashboard::Base
+    presents label: "<%= dashboard_label %>"
+
+    # Cards sit on a 12-column grid (metric 3, chart and card 6 by default; `span:`
+    # overrides), each in its own lazy turbo frame. `group_by_day` is the groupdate gem.
+    #
+    # metric(:users, icon: Phlex::TablerIcons::Users) { authorized_resource_scope(User).count }
+    # chart(:signups, type: :line, span: 8) { User.group_by_day(:created_at, last: 30).count }
+    # card(:welcome) { p { "Signed in as #{current_user.email}" } }
+  end
+end
+<%- end -%>