plutonium 0.65.0 → 0.67.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/gemfiles/rails_7.gemfile

@@ -3,6 +3,7 @@
 source "https://rubygems.org"
 
 gem "rotp"
+gem "no_fly_list", github: "radioactive-labs/no_fly_list", branch: "feat/scoped-tags"
 gem "rails", "~> 7.2"
 gem "sqlite3"
 gem "puma", ">= 5.0"

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,15 @@
+GIT
+  remote: https://github.com/radioactive-labs/no_fly_list.git
+  revision: e1e88d9c7d898ef269e3cabfa12da2fb327459cc
+  branch: feat/scoped-tags
+  specs:
+    no_fly_list (0.7.4)
+      activerecord (>= 7.2)
+
 PATH
   remote: ..
   specs:
-    plutonium (0.64.0)
+    plutonium (0.66.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)
@@ -490,6 +498,7 @@ DEPENDENCIES
   importmap-rails
   minitest
   minitest-reporters
+  no_fly_list!
   plutonium!
   propshaft
   puma (>= 5.0)
@@ -521,7 +530,7 @@ CHECKSUMS
   activerecord (7.2.3.2) sha256=e62d24ba7e5f820d24ed122eb9225491b0aaa8398778783b400067c3467285c7
   activestorage (7.2.3.2) sha256=863cb4b21b83505555be2addb939fefb856ab05f6c6d24bab00d6f1a7e4edbfc
   activesupport (7.2.3.2) sha256=ddc90d11dd88086d78ace03407fe3c2a3f5c8853c3c3046313db5ed823ef3312
-  acts_as_list (1.2.6)
+  acts_as_list (1.2.6) sha256=8345380900b7bee620c07ad00991ccee59af3d8c9e8574f426e321da2865fdc8
   addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
   ansi (1.6.0) sha256=ac9ea0c0ea8d32fb4e271348e609963ac78882f34b73836c2a02b3622e666658
   appraisal (2.5.0) sha256=36989221be127913b0dba8d114da2001e6b2dceea7bd4951200eaba764eed3ce
@@ -580,6 +589,7 @@ CHECKSUMS
   net-protocol (0.2.2) sha256=aa73e0cba6a125369de9837b8d8ef82a61849360eba0521900e2c3713aa162a8
   net-smtp (0.5.1) sha256=ed96a0af63c524fceb4b29b0d352195c30d82dd916a42f03c62a3a70e5b70736
   nio4r (2.7.5) sha256=6c90168e48fb5f8e768419c93abb94ba2b892a1d0602cb06eef16d8b7df1dca1
+  no_fly_list (0.7.4)
   nokogiri (1.19.4-aarch64-linux-gnu) sha256=1269fb644a6de405057a53dd5c762b1209b43ca7424f839454d3dbc677c31a8f
   nokogiri (1.19.4-aarch64-linux-musl) sha256=35c65b9ce72b3bb03207bdbe7067915019dc18c1b9b59139684bd6690fdd01af
   nokogiri (1.19.4-arm-linux-gnu) sha256=a301313e38bb065d68239e79734bcd6f56fb6efaacebde29e9abf2a4735340ca
@@ -601,7 +611,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.64.0)
+  plutonium (0.66.0)
   pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85

data/gemfiles/rails_8.0.gemfile

@@ -3,6 +3,7 @@
 source "https://rubygems.org"
 
 gem "rotp"
+gem "no_fly_list", github: "radioactive-labs/no_fly_list", branch: "feat/scoped-tags"
 gem "rails", "~> 8.0.0"
 gem "sqlite3"
 gem "puma", ">= 5.0"

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,15 @@
+GIT
+  remote: https://github.com/radioactive-labs/no_fly_list.git
+  revision: e1e88d9c7d898ef269e3cabfa12da2fb327459cc
+  branch: feat/scoped-tags
+  specs:
+    no_fly_list (0.7.4)
+      activerecord (>= 7.2)
+
 PATH
   remote: ..
   specs:
-    plutonium (0.62.2)
+    plutonium (0.66.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)
@@ -457,6 +465,7 @@ DEPENDENCIES
   importmap-rails
   minitest
   minitest-reporters
+  no_fly_list!
   plutonium!
   propshaft
   puma (>= 5.0)

data/gemfiles/rails_8.1.gemfile

@@ -3,6 +3,7 @@
 source "https://rubygems.org"
 
 gem "rotp"
+gem "no_fly_list", github: "radioactive-labs/no_fly_list", branch: "feat/scoped-tags"
 gem "rails", "~> 8.1.0"
 gem "sqlite3"
 gem "puma", ">= 5.0"

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,15 @@
+GIT
+  remote: https://github.com/radioactive-labs/no_fly_list.git
+  revision: e1e88d9c7d898ef269e3cabfa12da2fb327459cc
+  branch: feat/scoped-tags
+  specs:
+    no_fly_list (0.7.4)
+      activerecord (>= 7.2)
+
 PATH
   remote: ..
   specs:
-    plutonium (0.64.0)
+    plutonium (0.66.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)
@@ -459,6 +467,7 @@ DEPENDENCIES
   importmap-rails
   minitest
   minitest-reporters
+  no_fly_list!
   plutonium!
   propshaft
   puma (>= 5.0)

data/lib/generators/pu/profile/conn_generator.rb

@@ -65,6 +65,12 @@ module Pu
     user.#{profile_association}.nil?
   end
 
+  # The base update? delegates to create?, which is false once the profile
+  # exists. relation_scope already limits this to the user's own profile.
+  def update?
+    true
+  end
+
   def destroy?
     false
   end

data/lib/plutonium/auth/rodauth.rb

@@ -24,6 +24,13 @@ module Plutonium
             rodauth.rails_account
           end
 
+          # A request Rodauth authenticated with a valid JWT reads its session
+          # from the token, not the cookie, so there is nothing for a forged
+          # request to ride on. Everything else gets the CSRF token check.
+          def verified_request?
+            super || (rodauth.features.include?(:jwt) && rodauth.valid_jwt?)
+          end
+
           def logout_url
             rodauth.logout_path
           end

data/lib/plutonium/core/controller.rb

@@ -10,8 +10,6 @@ module Plutonium
       included do
         add_flash_types :success, :warning, :error
 
-        protect_from_forgery with: :null_session, if: -> { request.headers["Authorization"].present? }
-
         rescue_from ::ActionPolicy::Unauthorized do |exception|
           respond_to do |format|
             format.any(:html, :turbo_stream) do

data/lib/plutonium/helpers/content_helper.rb

@@ -10,9 +10,6 @@ module Plutonium
           title: content,
           data: {
             controller: "timeago",
-            timeago_refresh_interval_value: 1000,
-            timeago_include_seconds_value: true,
-            timeago_add_suffix_value: true,
             timeago_datetime_value: date.iso8601
           }
         )

data/lib/plutonium/query/filter.rb

@@ -10,7 +10,8 @@ module Plutonium
         def lookup(type)
           return type if type.is_a?(Class) && type < Filter
 
-          class_name = "Plutonium::Query::Filters::#{type.to_s.classify}"
+          # camelize, not classify: classify singularizes (`:tags` -> `Tag`).
+          class_name = "Plutonium::Query::Filters::#{type.to_s.camelize}"
           class_name.constantize
         rescue NameError
           raise ArgumentError, "Unknown filter type: #{type}. Expected #{class_name} to exist."

data/lib/plutonium/query/filters/tags.rb

@@ -0,0 +1,36 @@
+module Plutonium
+  module Query
+    module Filters
+      # Filter by a no_fly_list `has_tags` context, through the gem's own
+      # query scopes.
+      #
+      # @example Records with any of the chosen tags
+      #   filter :labels, with: :tags
+      #
+      # @example Records with every chosen tag
+      #   filter :labels, with: :tags, match: :all
+      #
+      class Tags < Filter
+        def initialize(match: :any, **)
+          super(**)
+          @match = match
+        end
+
+        def apply(scope, value:)
+          tags = Array(value).compact_blank
+          return scope if tags.empty?
+
+          scope.public_send(:"with_#{@match}_#{key}", tags)
+        end
+
+        def humanize_value(value)
+          Array(value).compact_blank.join(", ")
+        end
+
+        def customize_inputs
+          input :value, as: Plutonium::UI::Form::Components::TagsFilter, context: key
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/resource/record/associated_with.rb

@@ -6,6 +6,12 @@ module Plutonium
       module AssociatedWith
         extend ActiveSupport::Concern
 
+        # Raised when more than one association links the two classes and no
+        # `associated_with_<record>` scope says which one to use. Picking the
+        # first would scope by declaration order, so a reordered model could
+        # silently widen what a tenant sees.
+        class AmbiguousAssociationError < StandardError; end
+
         included do
           scope :associated_with, ->(record) do
             # If scoping to same class, just match by ID (e.g., Team scoped to Team)
@@ -45,21 +51,27 @@ module Plutonium
 
         class_methods do
           def find_association_from_self_to_record(record)
-            reflect_on_all_associations.find do |assoc|
+            matches = reflect_on_all_associations.select do |assoc|
               assoc.klass.name == record.class.name unless assoc.polymorphic?
             rescue
               assoc.check_validity!
               raise
             end
+            raise_ambiguous_association_error(self, record.class, matches, record) if matches.size > 1
+
+            matches.first
           end
 
           def find_association_to_self_from_record(record)
-            record.class.reflect_on_all_associations.find do |assoc|
+            matches = record.class.reflect_on_all_associations.select do |assoc|
               assoc.klass.name == name
             rescue
               assoc.check_validity!
               raise
             end
+            raise_ambiguous_association_error(record.class, self, matches, record) if matches.size > 1
+
+            matches.first
           end
 
           def query_based_on_association(assoc, record)
@@ -75,6 +87,15 @@ module Plutonium
             end
           end
 
+          def raise_ambiguous_association_error(from, to, matches, record)
+            named_scope = :"associated_with_#{record.model_name.singular}"
+            raise AmbiguousAssociationError,
+              "#{from.name} has multiple associations to #{to.name}: #{matches.map(&:name).join(", ")}. " \
+              "Plutonium cannot tell which one scopes #{name} to a #{record.class.name}.\n\n" \
+              "Define a named scope on #{name} e.g.\n\n" \
+              "scope :#{named_scope}, ->(#{record.model_name.singular}) { do_something_here }"
+          end
+
           def raise_unresolvable_association_error(record, named_scope)
             raise "Could not resolve the association between '#{name}' and '#{record.class.name}'\n\n" \
                   "Define\n" \

data/lib/plutonium/ui/component/resolves_tags.rb

@@ -34,9 +34,22 @@ module Plutonium
           tag ||= inferred_field_component
           return create_component(tag, component_theme_key(tag), **attributes, &) if tag.is_a?(Class)
 
+          # `field :x, as:` reaches every surface, but some aliases exist on
+          # only one (`:toggle` is form-only, `:badge` display-only). Those
+          # surfaces render what they would have inferred instead of raising.
+          # A tag NO surface defines is a typo and still raises below.
+          tag = inferred_field_component if !respond_to?(:"#{tag}_tag") && ResolvesTags.surface_tag?(tag)
+
           send(:"#{tag}_tag", **attributes, &)
         end
 
+        # Whether any field surface (form or display; the table renders through
+        # a display builder) defines `tag`.
+        def self.surface_tag?(tag)
+          [Plutonium::UI::Form::Base::Builder, Plutonium::UI::Display::Base::Builder]
+            .any? { |builder| builder.method_defined?(:"#{tag}_tag") }
+        end
+
         private
 
         # Theme key for a directly-rendered component class: