plutonium 0.65.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/gemfiles/rails_8.1.gemfile.lock

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

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/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/form/concerns/typeahead_attributes.rb

@@ -64,6 +64,11 @@ module Plutonium
             return nil unless name
 
             route_key = resource_class.model_name.route_key
+            # Path-scoped portals prefix every route name with the entity
+            # param key (`organization_scoped_`) and take the entity as the
+            # first positional arg, the same as Controller#resource_url_for.
+            path_scoped = current_engine.scoped_to_entity? && current_engine.scoped_entity_strategy == :path
+            route_key = "#{current_engine.scoped_entity_param_key}_#{route_key}" if path_scoped
             helper = (kind == :filter) ? :"typeahead_filter_#{route_key}_path" : :"typeahead_input_#{route_key}_path"
 
             # Engine route helpers are the source of truth for routes
@@ -74,7 +79,8 @@ module Plutonium
             # uses its eager list.
             url_helpers = current_engine.routes.url_helpers
             return nil unless url_helpers.respond_to?(helper)
-            url_helpers.public_send(helper, name: name)
+            helper_args = path_scoped ? [view_context.current_scoped_entity.to_param] : []
+            url_helpers.public_send(helper, *helper_args, name: name)
           end
         end
       end

data/lib/plutonium/version.rb

@@ -1,5 +1,5 @@
 module Plutonium
-  VERSION = "0.65.0"
+  VERSION = "0.66.0"
   NEXT_MAJOR_VERSION = VERSION.split(".").tap { |v|
     v[1] = v[1].to_i + 1
     v[2] = 0

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radioactive-labs/plutonium",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "description": "Build production-ready Rails apps in minutes, not days. Convention-driven, fully customizable, AI-ready.",
   "type": "module",
   "main": "src/js/core.js",

data/src/css/components.css

@@ -971,7 +971,7 @@ html.pu-rail-pinned .icon-rail-pin-expand {
   @apply flex items-center p-4 mb-4 rounded-lg;
 }
 .dark .pu-alert {
-  @apply bg-stone-300;
+  @apply bg-gray-800;
 }
 
 .pu-alert-message {
@@ -982,7 +982,7 @@ html.pu-rail-pinned .icon-rail-pin-expand {
   @apply ms-auto -mx-1.5 -my-1.5 rounded-lg focus:ring-2 p-1.5 inline-flex items-center justify-center h-8 w-8;
 }
 .dark .pu-alert-close {
-  @apply bg-stone-300 hover:bg-gray-700;
+  @apply bg-gray-800 hover:bg-gray-700;
 }
 
 /* --- Variants: success / warning / danger / info ---
@@ -995,11 +995,11 @@ html.pu-rail-pinned .icon-rail-pin-expand {
 .pu-toast-success .pu-toast-icon       { @apply text-success-500 bg-success-100; }
 .dark .pu-toast-success .pu-toast-icon { @apply bg-success-800 text-success-200; }
 .pu-toast-success .pu-toast-close       { @apply bg-success-50 text-success-400 hover:bg-success-200 focus:ring-success-400; }
-.dark .pu-toast-success .pu-toast-close { @apply text-success-400; }
+.dark .pu-toast-success .pu-toast-close { @apply bg-gray-800 text-success-400 hover:bg-gray-700; }
 .pu-alert-success           { @apply bg-success-50 text-success-800; }
 .dark .pu-alert-success     { @apply text-success-400; }
 .pu-alert-success .pu-alert-close       { @apply bg-success-50 text-success-500 hover:bg-success-200 focus:ring-success-400; }
-.dark .pu-alert-success .pu-alert-close { @apply text-success-400; }
+.dark .pu-alert-success .pu-alert-close { @apply bg-gray-800 text-success-400 hover:bg-gray-700; }
 
 /* warning */
 .pu-toast-warning           { @apply bg-warning-50; }
@@ -1007,11 +1007,11 @@ html.pu-rail-pinned .icon-rail-pin-expand {
 .pu-toast-warning .pu-toast-icon       { @apply text-warning-500 bg-warning-100; }
 .dark .pu-toast-warning .pu-toast-icon { @apply bg-warning-800 text-warning-200; }
 .pu-toast-warning .pu-toast-close       { @apply bg-warning-50 text-warning-400 hover:bg-warning-200 focus:ring-warning-400; }
-.dark .pu-toast-warning .pu-toast-close { @apply text-warning-400; }
+.dark .pu-toast-warning .pu-toast-close { @apply bg-gray-800 text-warning-400 hover:bg-gray-700; }
 .pu-alert-warning           { @apply bg-warning-50 text-warning-800; }
 .dark .pu-alert-warning     { @apply text-warning-400; }
 .pu-alert-warning .pu-alert-close       { @apply bg-warning-50 text-warning-500 hover:bg-warning-200 focus:ring-warning-400; }
-.dark .pu-alert-warning .pu-alert-close { @apply text-warning-400; }
+.dark .pu-alert-warning .pu-alert-close { @apply bg-gray-800 text-warning-400 hover:bg-gray-700; }
 
 /* danger */
 .pu-toast-danger            { @apply bg-danger-50; }
@@ -1019,11 +1019,11 @@ html.pu-rail-pinned .icon-rail-pin-expand {
 .pu-toast-danger .pu-toast-icon       { @apply text-danger-500 bg-danger-100; }
 .dark .pu-toast-danger .pu-toast-icon { @apply bg-danger-800 text-danger-200; }
 .pu-toast-danger .pu-toast-close       { @apply bg-danger-50 text-danger-400 hover:bg-danger-200 focus:ring-danger-400; }
-.dark .pu-toast-danger .pu-toast-close { @apply text-danger-400; }
+.dark .pu-toast-danger .pu-toast-close { @apply bg-gray-800 text-danger-400 hover:bg-gray-700; }
 .pu-alert-danger            { @apply bg-danger-50 text-danger-800; }
 .dark .pu-alert-danger      { @apply text-danger-400; }
 .pu-alert-danger .pu-alert-close       { @apply bg-danger-50 text-danger-500 hover:bg-danger-200 focus:ring-danger-400; }
-.dark .pu-alert-danger .pu-alert-close { @apply text-danger-400; }
+.dark .pu-alert-danger .pu-alert-close { @apply bg-gray-800 text-danger-400 hover:bg-gray-700; }
 
 /* info (default / :notice) */
 .pu-toast-info              { @apply bg-info-50; }
@@ -1031,11 +1031,11 @@ html.pu-rail-pinned .icon-rail-pin-expand {
 .pu-toast-info .pu-toast-icon       { @apply text-info-500 bg-info-100; }
 .dark .pu-toast-info .pu-toast-icon { @apply bg-info-800 text-info-200; }
 .pu-toast-info .pu-toast-close       { @apply bg-info-50 text-info-400 hover:bg-info-200 focus:ring-info-400; }
-.dark .pu-toast-info .pu-toast-close { @apply text-info-400; }
+.dark .pu-toast-info .pu-toast-close { @apply bg-gray-800 text-info-400 hover:bg-gray-700; }
 .pu-alert-info              { @apply bg-info-50 text-info-800; }
 .dark .pu-alert-info        { @apply text-info-400; }
 .pu-alert-info .pu-alert-close       { @apply bg-info-50 text-info-500 hover:bg-info-200 focus:ring-info-400; }
-.dark .pu-alert-info .pu-alert-close { @apply text-info-400; }
+.dark .pu-alert-info .pu-alert-close { @apply bg-gray-800 text-info-400 hover:bg-gray-700; }
 
 /* ===========================================================================
    Wizard — horizontal "steps" stepper (numbered nodes on a connector track)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: plutonium
 version: !ruby/object:Gem::Version
-  version: 0.65.0
+  version: 0.66.0
 platform: ruby
 authors:
 - Stefan Froelich
 bindir: exe
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk