plutonium 0.64.0 → 0.66.0

data/docs/reference/behavior/interactions.md

@@ -5,11 +5,11 @@ The entry point from a Plutonium page into an operation. An interaction declares
 ## 🚨 Critical
 
 - **`ActiveRecord::RecordInvalid` is NOT rescued automatically.** Always rescue when using `create!` / `update!` / `save!`, return `failed(e.record.errors)`.
-- **Return `succeed(...)` or `failed(...)` from `execute`** — the controller can't tell what happened otherwise. Returning anything else raises.
-- **Redirect is automatic on success** — only use `with_redirect_response` for a *different* destination.
-- **Bulk actions use `attribute :resources` (plural).** Policy authorization is checked per record — if any fails, the whole request fails.
+- **Return `succeed(...)` or `failed(...)` from `execute`**: the controller can't tell what happened otherwise. Returning anything else raises.
+- **Redirect is automatic on success**: only use `with_redirect_response` for a *different* destination.
+- **Bulk actions use `attribute :resources` (plural).** Policy authorization is checked per record; if any fails, the whole request fails.
 - **The shape of the action (record / bulk / resource) is inferred from the interaction's attributes.** See [Resource › Actions](/reference/resource/actions#inferred-visibility-interactive-actions).
-- **An interaction is a presentation object.** Logic may *start* in `execute`; the **second caller** — a job, an API controller, a rake task, the console — is the signal to move it to the model. See [below](#what-an-interaction-is-for).
+- **An interaction is a presentation object.** Logic may *start* in `execute`; the **second caller** (a job, an API controller, a rake task, the console) is the signal to move it to the model. See [below](#what-an-interaction-is-for).
 
 ## What an interaction is for {#what-an-interaction-is-for}
 
@@ -17,20 +17,20 @@ An interaction is a **presentation object**. It exists so Plutonium can render a
 
 | An interaction owns | An interaction does not own |
 |---|---|
-| The button — `presents label:` / `icon:` | *Who* may click it. That's the [policy](./policies). |
-| The form — `attribute` + `input` declarations | — |
-| **Input shape** validation: present? parses? right type? | **Business invariants** — they must hold for every caller, so they belong on the model |
-| The user-facing outcome — `succeed` / `failed`, messages, redirect | The domain operation itself, once more than one caller needs it |
+| The button: `presents label:` / `icon:` | *Who* may click it. That's the [policy](./policies). |
+| The form: `attribute` + `input` declarations | - |
+| **Input shape** validation: present? parses? right type? | **Business invariants**: they must hold for every caller, so they belong on the model |
+| The user-facing outcome: `succeed` / `failed`, messages, redirect | The domain operation itself, once more than one caller needs it |
 
 ### Logic may start in `execute`
 
-A one-off operation with exactly one caller is perfectly fine written inline. Don't pre-extract a service object for a two-line `update!` — that's YAGNI, and Plutonium deliberately ships no service layer to put it in. The rule below is a **refactoring trigger**, not a prohibition.
+A one-off operation with exactly one caller is perfectly fine written inline. Don't pre-extract a service object for a two-line `update!`; that's YAGNI, and Plutonium deliberately ships no service layer to put it in. The rule below is a **refactoring trigger**, not a prohibition.
 
 ### The second caller is the trigger to extract
 
 The moment a background job, an API controller, a rake task, the console, or another interaction needs the same behaviour, move it to the model.
 
-The deadline is *the second caller* — and not "as soon as it looks like business logic" — because of one line in the base class:
+The deadline is *the second caller*, not "as soon as it looks like business logic", because of one line in the base class:
 
 ```ruby
 def initialize(view_context:, **attributes)
@@ -61,9 +61,9 @@ rescue ActiveRecord::RecordInvalid => e
 end
 ```
 
-Name it for the domain (`publish!`, `archive!`, `register!`), not for the persistence (`update_published_at`) — the point is that a scheduler job can now call `post.publish!` and read as if it meant it. And resist inventing a `PublishPostService`: the model is the destination, not a new layer.
+Name it for the domain (`publish!`, `archive!`, `register!`), not for the persistence (`update_published_at`); the point is that a scheduler job can now call `post.publish!` and read as if it meant it. And resist inventing a `PublishPostService`: the model is the destination, not a new layer.
 
-### Worked counter-example — chained interactions
+### Worked counter-example: chained interactions
 
 ```ruby
 # 🚫 Every link demands a view_context that has nothing to do with the work
@@ -72,7 +72,7 @@ CreateUserInteraction.call(view_context:, **user_params)
   .and_then { |user| LogActivity.call(view_context:, user:) }
 ```
 
-Sending a welcome email and writing an audit row are precisely what a signup API endpoint, a seeds script, or a console session also has to do — none of which has a `view_context`. Modelled as interactions, they are unreachable from anywhere but a Plutonium page.
+Sending a welcome email and writing an audit row are precisely what a signup API endpoint, a seeds script, or a console session also has to do, none of which has a `view_context`. Modelled as interactions, they are unreachable from anywhere but a Plutonium page.
 
 ```ruby
 # ✅ The model owns registering a user; the interaction presents it
@@ -82,12 +82,12 @@ def execute
 end
 ```
 
-Chaining three interactions is usually the signal that you have one model method wearing three presentation costumes. `and_then` is real API and stays [documented below](#chaining) — just don't reach for it to sequence business operations.
+Chaining three interactions is usually the signal that you have one model method wearing three presentation costumes. `and_then` is real API and stays [documented below](#chaining), just don't reach for it to sequence business operations.
 
 ## Structure
 
 ```ruby
-# app/interactions/resource_interaction.rb — installed once
+# app/interactions/resource_interaction.rb: installed once
 class ResourceInteraction < Plutonium::Resource::Interaction
 end
 
@@ -107,7 +107,7 @@ class PublishPostInteraction < ResourceInteraction
   private
 
   def execute
-    resource.publish!(on: publish_date)   # Post#publish! — see above
+    resource.publish!(on: publish_date)   # Post#publish!, see above
     succeed(resource).with_message("Post published!")
   rescue ActiveRecord::RecordInvalid => e
     failed(e.record.errors)
@@ -115,7 +115,7 @@ class PublishPostInteraction < ResourceInteraction
 end
 ```
 
-Note the division: the interaction declares the input, validates that a date was supplied, and phrases the flash. `Post#publish!` decides what publishing a post *means* — so the scheduled-publishing job can call it too.
+Note the division: the interaction declares the input, validates that a date was supplied, and phrases the flash. `Post#publish!` decides what publishing a post *means*, so the scheduled-publishing job can call it too.
 
 ## Attributes
 
@@ -132,11 +132,11 @@ attribute :metadata, :hash
 attribute :date, :datetime
 ```
 
-The presence of `:resource` / `:resources` / neither determines the action type — see [Resource › Actions › Inferred visibility](/reference/resource/actions#inferred-visibility-interactive-actions).
+The presence of `:resource` / `:resources` / neither determines the action type, see [Resource › Actions › Inferred visibility](/reference/resource/actions#inferred-visibility-interactive-actions).
 
 ## Inputs
 
-Same DSL as definition `input`. Auto-detection from the attribute type applies — declare `as:` only when overriding.
+Same DSL as definition `input`. Auto-detection from the attribute type applies; declare `as:` only when overriding.
 
 ```ruby
 input :email                          # auto: :email type from name match
@@ -164,7 +164,7 @@ MyInteraction.description  # => "Move to archive"
 
 If `action :foo, interaction: FooInteraction` doesn't override `label:` / `icon:` etc., these `presents` values are used.
 
-## `execute` — outcomes
+## `execute`: outcomes
 
 `execute` MUST return a `succeed(...)` or `failed(...)` outcome. Validations run automatically before `execute`; if they fail, the interaction short-circuits to `failed()`.
 
@@ -220,7 +220,7 @@ end
 ```
 
 ::: warning Don't use `and_then` to sequence business operations
-A chain of three interactions is a chain of three things that each demand a `view_context`, none of which a job or an API controller can supply. That's one model method wearing three costumes — see [Worked counter-example](#what-an-interaction-is-for). `and_then` earns its keep composing outcomes *within* one interaction, or in a test.
+A chain of three interactions is a chain of three things that each demand a `view_context`, none of which a job or an API controller can supply. That's one model method wearing three costumes, see [Worked counter-example](#what-an-interaction-is-for). `and_then` earns its keep composing outcomes *within* one interaction, or in a test.
 :::
 
 ## Validations
@@ -242,18 +242,18 @@ end
 
 ### Which validation goes where
 
-Interactions have validations and so do models, and they are not competing — they answer different questions:
+Interactions have validations and so do models, and they are not competing: they answer different questions:
 
 | | Interaction validation | Model validation |
 |---|---|---|
-| Asks | "Can I read this input?" — present, parses, right type, plausible format | "Is this record legal?" — invariants that hold no matter who is calling |
+| Asks | "Can I read this input?": present, parses, right type, plausible format | "Is this record legal?": invariants that hold no matter who is calling |
 | Exists to | render a form error next to the field | protect the data from every caller, including the ones with no form |
-| Runs | before `execute`, without ever touching the model | inside `save!` / `update!` — i.e. inside your model method |
+| Runs | before `execute`, without ever touching the model | inside `save!` / `update!`, i.e. inside your model method |
 
 Both surface to the user, but **not identically**, and the difference should inform where you put a rule:
 
 - An **interaction** validation attaches to a declared attribute. The re-rendered modal shows it inline against that input, and again in the summary at the top of the form.
-- `failed(record.errors)` flattens `ActiveModel::Errors` into **full messages on `:base`** (`Array(errors)` calls `errors.to_a`, which is `full_messages`). Those land in the form's error summary only — never against a field — and they're phrased with the *model's* attribute names, which need not match your inputs.
+- `failed(record.errors)` flattens `ActiveModel::Errors` into **full messages on `:base`** (`Array(errors)` calls `errors.to_a`, which is `full_messages`). Those land in the form's error summary only, never against a field, and they're phrased with the *model's* attribute names, which need not match your inputs.
 
 So it is fine, and often right, to *duplicate* a cheap invariant as an interaction validation purely for the better error placement, while the model keeps the authoritative copy. What must not happen is the model-side copy going missing: the moment a job calls `post.publish!`, the interaction's validations are not in the picture at all.
 
@@ -268,7 +268,7 @@ def execute
 end
 ```
 
-This one is *correctly* inline. "Who clicked the button" is context the presentation layer holds and nothing else does — `current_user` is read straight off the `view_context`. A job has no answer for it, so there is no second caller to extract for.
+This one is *correctly* inline. "Who clicked the button" is context the presentation layer holds and nothing else does: `current_user` is read straight off the `view_context`. A job has no answer for it, so there is no second caller to extract for.
 
 ## Interaction types
 
@@ -306,7 +306,7 @@ class BulkArchiveInteraction < Plutonium::Resource::Interaction
 end
 ```
 
-`update_all` stays inline on purpose: it's a single-statement SQL update whose *whole point* is skipping per-record model machinery. If archiving means more than setting a column — callbacks, an audit row, a webhook — this is the wrong shape; call `resources.each(&:archive!)` and let the model own it.
+`update_all` stays inline on purpose: it's a single-statement SQL update whose *whole point* is skipping per-record model machinery. If archiving means more than setting a column (callbacks, an audit row, a webhook), this is the wrong shape; call `resources.each(&:archive!)` and let the model own it.
 
 Per-record authorization details in [Resource › Actions › Bulk action](/reference/resource/actions#bulk-action).
 
@@ -327,10 +327,10 @@ end
 
 ## Calling interactions directly
 
-The controller handles this for interactive actions. You can also call one by hand — chiefly in **tests**, where you're exercising the interaction itself.
+The controller handles this for interactive actions. You can also call one by hand, chiefly in **tests**, where you're exercising the interaction itself.
 
 ::: tip Needing this in a job or a rake task is the signal to refactor
-Both entry points require `view_context:`, and a job doesn't have one. If you find yourself reaching for a stub to satisfy it, you don't want the interaction — you want the model method it wraps. See [What an interaction is for](#what-an-interaction-is-for).
+Both entry points require `view_context:`, and a job doesn't have one. If you find yourself reaching for a stub to satisfy it, you don't want the interaction, you want the model method it wraps. See [What an interaction is for](#what-an-interaction-is-for).
 :::
 
 ### Class method
@@ -352,14 +352,14 @@ interaction = PublishPost.new(view_context: view_context, resource: post)
 outcome = interaction.call
 ```
 
-The `view_context:` argument is required — interactions use it to access controller helpers and the current user. It is also the boundary marker: everything reachable *only* through an interaction is reachable only from a page.
+The `view_context:` argument is required: interactions use it to access controller helpers and the current user. It is also the boundary marker: everything reachable *only* through an interaction is reachable only from a page.
 
 ## Immediate vs form
 
 | Interaction shape | Behavior |
 |---|---|
-| Only `:resource` / `:resources` (no extra `attribute` or `input`) | **Immediate** — browser confirmation (`"#{label}?"`, e.g. `"Archive?"`), then runs. Override with `confirmation: "Custom"` or `confirmation: false` on the action. |
-| Additional `attribute` / `input` declared | **Form** — renders modal form first; no auto-confirmation. |
+| Only `:resource` / `:resources` (no extra `attribute` or `input`) | **Immediate**: browser confirmation (`"#{label}?"`, e.g. `"Archive?"`), then runs. Override with `confirmation: "Custom"` or `confirmation: false` on the action. |
+| Additional `attribute` / `input` declared | **Form**: renders modal form first; no auto-confirmation. |
 
 See [Resource › Actions › Immediate vs form](/reference/resource/actions#immediate-vs-form).
 
@@ -368,15 +368,15 @@ See [Resource › Actions › Immediate vs form](/reference/resource/actions#imm
 `resource_url_for` with the `interaction:` kwarg. The action type (record / bulk / resource) is inferred from the element and the presence of `ids:`:
 
 ```ruby
-# Record action — instance argument
+# Record action: instance argument
 resource_url_for(@post, interaction: :publish)
 # => /posts/:id/record_actions/publish
 
-# Resource action — class, no ids
+# Resource action: class, no ids
 resource_url_for(Post, interaction: :import)
 # => /posts/resource_actions/import
 
-# Bulk action — class + ids
+# Bulk action: class + ids
 resource_url_for(Post, interaction: :archive, ids: [1, 2, 3])
 # => /posts/bulk_actions/archive?ids[]=1&ids[]=2&ids[]=3
 
@@ -384,11 +384,11 @@ resource_url_for(Post, interaction: :archive, ids: [1, 2, 3])
 resource_url_for(@post, parent: @user, interaction: :publish)
 ```
 
-The same URL serves GET (form/confirmation) and POST (commit) — the HTTP verb routes to the right controller action. Passing both `interaction:` and `action:` raises `ArgumentError`.
+The same URL serves GET (form/confirmation) and POST (commit), the HTTP verb routes to the right controller action. Passing both `interaction:` and `action:` raises `ArgumentError`.
 
 ## Complete example
 
-Inviting a user is a textbook second-caller case — a seats-provisioning job, an admin rake task and a signup API all need to send the same invitation. So the operation lives on `Company`, and the interaction is the button in front of it.
+Inviting a user is a textbook second-caller case: a seats-provisioning job, an admin rake task and a signup API all need to send the same invitation. So the operation lives on `Company`, and the interaction is the button in front of it.
 
 ```ruby
 # app/models/company.rb
@@ -419,7 +419,7 @@ class Company::InviteUserInteraction < Plutonium::Resource::Interaction
   input :email
   input :role, as: :select, choices: -> { UserInvite.roles.keys }
 
-  # Input shape — is this a readable email, is this a role that exists?
+  # Input shape: is this a readable email, is this a role that exists?
   validates :email, presence: true, format: {with: URI::MailTo::EMAIL_REGEXP}
   validates :role,  presence: true, inclusion: {in: UserInvite.roles.keys}
   validate  :not_already_invited
@@ -460,12 +460,12 @@ RSpec.describe PublishPost do
 end
 ```
 
-See [Testing](/reference/testing/) for Plutonium's built-in testing helpers — `ResourceInteraction` concern wraps these patterns.
+See [Testing](/reference/testing/) for Plutonium's built-in testing helpers. The `ResourceInteraction` concern wraps these patterns.
 
 ## Related
 
-- [Async Interactions](./async-interactions) — `async` a persisted run instead of running `execute` inline
-- [Resource › Actions](/reference/resource/actions) — registering interactions, inferred visibility, immediate vs form
-- [Policies](./policies) — `def <action>?` authorization methods
-- [Controllers](./controllers) — `resource_url_for(..., interaction: …)` URL generation
-- [UI › Forms](/reference/ui/forms) — customizing the modal form rendered for actions with inputs
+- [Async Interactions](./async-interactions): `async` a persisted run instead of running `execute` inline
+- [Resource › Actions](/reference/resource/actions): registering interactions, inferred visibility, immediate vs form
+- [Policies](./policies): `def <action>?` authorization methods
+- [Controllers](./controllers): `resource_url_for(..., interaction: …)` URL generation
+- [UI › Forms](/reference/ui/forms): customizing the modal form rendered for actions with inputs

data/docs/reference/behavior/policies.md

@@ -11,20 +11,20 @@ Authorization for resources. Built on [ActionPolicy](https://actionpolicy.evilma
 
 - **`create?` and `read?` default to `false`.** You MUST override them explicitly. Everything else (`update?`, `destroy?`, `index?`, `show?`, …) derives from one of those.
 - **`permitted_attributes_for_*` must be explicit in production.** Dev auto-detects; production raises.
-- **`relation_scope` must end up calling `default_relation_scope(relation)` somewhere in the chain.** Prefer calling it explicitly in your override. `super` is fine when extending a parent policy (e.g., a package base) that itself calls it. The runtime check verifies it was hit somewhere — not in this specific class.
+- **`relation_scope` must end up calling `default_relation_scope(relation)` somewhere in the chain.** Prefer calling it explicitly in your override. `super` is fine when extending a parent policy (e.g., a package base) that itself calls it. The runtime check verifies it was hit somewhere, not in this specific class.
 - **For `has_cents` fields, use the virtual name** (`:price`), NEVER `:price_cents`.
 - **Don't put `*_attributes` hashes in `permitted_attributes_for_*`.** Nested forms are extracted from the form definition, not the policy. List the association name (`:variants`) and the `nested_input` in the definition handles the rest.
 - **Custom action ⇒ policy method.** `action :publish` needs `def publish?`. Undefined methods return `false` → action silently disappears.
-- **Index has no `record`.** Record-dependent `_for_read` overrides need an explicit `_for_index` too (see [below](#index-has-no-record)).
+- **Index has no `record` instance.** On collection routes `record` is the resource class. Record-dependent `_for_read` overrides need an explicit `_for_index` too (see [below](#index-has-no-record)).
 
 ## Base class
 
 ```ruby
-# app/policies/resource_policy.rb — installed once
+# app/policies/resource_policy.rb: installed once
 class ResourcePolicy < Plutonium::Resource::Policy
 end
 
-# app/policies/post_policy.rb — per resource, generated
+# app/policies/post_policy.rb: per resource, generated
 class PostPolicy < ResourcePolicy
   def create? = user.present?
   def read?   = true
@@ -46,7 +46,7 @@ Inside a policy:
 | Variable | Description |
 |---|---|
 | `user` | Current authenticated user (required) |
-| `record` | Resource being authorized |
+| `record` | Resource being authorized (the resource class on collection routes such as `index` and `new`) |
 | `entity_scope` | Current scoped entity (multi-tenancy) |
 | `parent` | Parent record for nested resources (nil otherwise) |
 | `parent_association` | Association name on parent (e.g. `:comments`) |
@@ -88,7 +88,7 @@ def archive? = create? && !record.archived?
 def invite_user? = user.admin?
 ```
 
-### Bulk actions — per-record authorization
+### Bulk actions: per-record authorization
 
 ```ruby
 def bulk_archive?
@@ -101,7 +101,7 @@ How it works:
 - Policy is checked **per record** in the selected set.
 - **Backend:** if any record fails, the entire request is rejected.
 - **UI:** only actions ALL selected records support are shown (intersection).
-- Records come from `current_authorized_scope` — users can only select records they're allowed to access.
+- Records come from `current_authorized_scope`, so users can only select records they're allowed to access.
 
 ## Attribute permissions
 
@@ -122,6 +122,7 @@ end
 |---|---|
 | `permitted_attributes_for_update` | `permitted_attributes_for_create` |
 | `permitted_attributes_for_index` | `permitted_attributes_for_read` |
+| `permitted_attributes_for_export` | `permitted_attributes_for_index` |
 | `permitted_attributes_for_show` | `permitted_attributes_for_read` |
 | `permitted_attributes_for_new` | `permitted_attributes_for_create` |
 | `permitted_attributes_for_edit` | `permitted_attributes_for_update` |
@@ -140,7 +141,7 @@ end
 
 ### Index has no `record`
 
-🚨 `permitted_attributes_for_index` is evaluated at the **collection level** — `record` is `nil`. `permitted_attributes_for_show` (and `_for_read`) ARE evaluated per record.
+🚨 `permitted_attributes_for_index` is evaluated at the **collection level**. There is no record instance: the policy subject is the resource **class**, so `record == Post`. The same class-bound policy feeds the table, the CSV export (`_for_export` defaults to `_for_index`) and kanban cards. `permitted_attributes_for_show` (and `_for_read`) ARE evaluated per record.
 
 If you write a record-dependent `_for_read`:
 
@@ -152,7 +153,7 @@ def permitted_attributes_for_read
 end
 ```
 
-…you MUST also define an explicit `permitted_attributes_for_index` — otherwise inheritance kicks in, runs the `_for_read` body during the table render, and `record.archived?` blows up on `NoMethodError: undefined method 'archived?' for nil`.
+…you MUST also define an explicit `permitted_attributes_for_index` whose body never touches `record`. Otherwise `_for_index` falls back to `_for_read`, runs it against the class during the table render, and `record.archived?` raises `NoMethodError` (`undefined method 'archived?'` for the `Post` class).
 
 ```ruby
 def permitted_attributes_for_index
@@ -160,7 +161,7 @@ def permitted_attributes_for_index
 end
 ```
 
-Same rule for `permitted_attributes_for_create` vs `_for_new` (new has no persisted record).
+Same rule for `permitted_attributes_for_create` vs `_for_new`: `new` is a collection route too, so `record` is the class there.
 
 ### Conditional attribute access
 
@@ -184,7 +185,7 @@ end
 
 `permitted_attributes_for_*` controls **which fields appear** on a view. The definition's `field`/`input`/`display`/`column` declarations only control **how** they render. A `field :name` in the definition does nothing unless `:name` is also in the relevant `permitted_attributes_for_*`.
 
-Common mistake: adding a definition declaration and wondering why the field doesn't show — check the policy.
+Common mistake: adding a definition declaration and wondering why the field doesn't show. Check the policy.
 
 ### Anti-pattern: nested-attributes hashes
 
@@ -229,17 +230,34 @@ def permitted_associations
 end
 ```
 
-Declares which associations get their own **tab on the show page**. When non-empty, the show page renders a tablist: a "Details" tab (the main field card + metadata aside) plus one tab per association — each lazy-loaded via a frame navigator panel pointing at the associated `has_many` collection, `has_one` record, or `belongs_to` target. When empty, the show page renders without tabs. If `permitted_attributes_for_show` resolves to **no fields**, the empty Details tab is omitted and the first association tab leads instead.
+Declares which associations get their own **tab on the show page**. When non-empty, the show page renders a tablist: a "Details" tab (the main field card + metadata aside) plus one tab per association, each lazy-loaded via a frame navigator panel pointing at the associated `has_many` collection, `has_one` record, or `belongs_to` target. When empty, the show page renders without tabs. If `permitted_attributes_for_show` resolves to **no fields**, the empty Details tab is omitted and the first association tab leads instead.
 
 Each named association must:
 
 - Exist on the model (raises `ArgumentError: unknown association ...` otherwise).
 - Point to a class that's itself a registered Plutonium resource (raises `... is not a registered resource` otherwise).
 
+🚨 **"Registered" means registered in the portal rendering the page.** Each portal engine keeps its own resource register, so a policy shared by several portals can only list associations whose class every one of those portals registers (`register_resource` in its `config/routes.rb`). Otherwise that portal's show page raises instead of dropping the tab:
+
+```
+ArgumentError: Catalog::Product#product_metadata defined in #permitted_associations, but Catalog::ProductMetadata is not a registered resource
+```
+
+To give only one portal the tab, leave the shared policy alone and add the association in a [portal-specific policy](#portal-specific-policies):
+
+```ruby
+# rails g pu:res:conn Catalog::Product --dest=admin_portal --policy
+class AdminPortal::Catalog::ProductPolicy < ::Catalog::ProductPolicy
+  include AdminPortal::ResourcePolicy
+
+  def permitted_associations = [*super, :product_metadata]
+end
+```
+
 This is **NOT** the same as:
 
-- **Nested forms** — declared with `nested_input :variants` in the definition, requires `accepts_nested_attributes_for` on the model. See [Resource › Definition › Nested inputs](/reference/resource/definition#nested-inputs).
-- **Association fields on tables / show details** — controlled by `permitted_attributes_for_index` / `_for_show` listing the association name.
+- **Nested forms**: declared with `nested_input :variants` in the definition, requires `accepts_nested_attributes_for` on the model. See [Resource › Definition › Nested inputs](/reference/resource/definition#nested-inputs).
+- **Association fields on tables / show details**: controlled by `permitted_attributes_for_index` / `_for_show` listing the association name.
 
 ## Collection scoping (`relation_scope`)
 
@@ -247,10 +265,10 @@ Filter which records the user can see.
 
 ### Always compose with `default_relation_scope`
 
-🚨 `relation_scope` MUST end up calling `default_relation_scope(relation)` somewhere in the chain. `super` works — `Plutonium::Resource::Policy` defines a default scope block that calls `default_relation_scope`, so a subclass that does `super(relation).where(...)` is fine. Calling `default_relation_scope` explicitly is also fine (and required when you skip the parent chain). Plutonium enforces this at runtime via `verify_default_relation_scope_applied!`.
+🚨 `relation_scope` MUST end up calling `default_relation_scope(relation)` somewhere in the chain. `super` works: `Plutonium::Resource::Policy` defines a default scope block that calls `default_relation_scope`, so a subclass that does `super(relation).where(...)` is fine. Calling `default_relation_scope` explicitly is also fine (and required when you skip the parent chain). Plutonium enforces this at runtime via `verify_default_relation_scope_applied!`.
 
 ```ruby
-# ✅ Best — don't override at all. The inherited scope already calls default_relation_scope.
+# ✅ Best: don't override at all. The inherited scope already calls default_relation_scope.
 
 # ✅ Extra filters on top
 relation_scope do |relation|
@@ -267,13 +285,13 @@ end
 ### Wrong patterns
 
 ```ruby
-# ❌ Manually filtering by entity — bypasses default_relation_scope
+# ❌ Manually filtering by entity, bypasses default_relation_scope
 relation_scope { |r| r.where(organization: current_scoped_entity) }
 
-# ❌ Manual joins — same problem
+# ❌ Manual joins, same problem
 relation_scope { |r| r.joins(:project).where(projects: {organization_id: current_scoped_entity.id}) }
 
-# ❌ Missing default_relation_scope entirely — raises at runtime
+# ❌ Missing default_relation_scope entirely, raises at runtime
 relation_scope { |r| r.where(published: true) }
 ```
 
@@ -282,13 +300,13 @@ relation_scope { |r| r.where(published: true) }
 1. If a **parent** is present (nested resource), scopes via the parent association.
 2. Otherwise, applies `relation.associated_with(entity_scope)` for multi-tenancy.
 
-Parent scoping takes precedence over entity scoping — the parent was already authorized and entity-scoped during its own authorization, so double-scoping isn't needed.
+Parent scoping takes precedence over entity scoping. The parent was already authorized and entity-scoped during its own authorization, so double-scoping isn't needed.
 
 Full mechanics in [Tenancy › Entity scoping](/reference/tenancy/entity-scoping).
 
 ### Intentionally skipping
 
-Rare. Use `skip_default_relation_scope!` explicitly — never silently bypass:
+Rare. Use `skip_default_relation_scope!` explicitly, never silently bypass:
 
 ```ruby
 relation_scope do |relation|
@@ -301,12 +319,14 @@ Before reaching for this, consider a separate, unscoped portal.
 
 ## Portal-specific policies
 
+Generate the override with `rails g pu:res:conn <Resource> --dest=<portal> --policy` (`--policy` forces the file even when a base policy exists). It subclasses the base policy and includes the portal's `ResourcePolicy`, so override only what differs and call `super` for the rest.
+
 ```ruby
 class PostPolicy < ResourcePolicy
   def create? = user.present?
 end
 
-# Admin — more permissive
+# Admin: more permissive
 class AdminPortal::PostPolicy < ::PostPolicy
   include AdminPortal::ResourcePolicy
 
@@ -314,7 +334,7 @@ class AdminPortal::PostPolicy < ::PostPolicy
   def permitted_attributes_for_create = %i[title content featured internal_notes]
 end
 
-# Public — read-only
+# Public: read-only
 class PublicPortal::PostPolicy < ::PostPolicy
   include PublicPortal::ResourcePolicy
   def create? = false
@@ -410,8 +430,8 @@ policy.permitted_attributes_for_update
 
 ## Related
 
-- [Controllers](./controllers) — call policies via `authorize_current!` and `authorized_resource_scope`
-- [Interactions](./interactions) — custom actions whose policy methods you define
-- [Resource › Actions](/reference/resource/actions) — registering actions that need policy methods
-- [Tenancy › Entity scoping](/reference/tenancy/entity-scoping) — `default_relation_scope`, three model shapes, custom scopes
-- [ActionPolicy docs](https://actionpolicy.evilmartians.io/) — the underlying library
+- [Controllers](./controllers): call policies via `authorize_current!` and `authorized_resource_scope`
+- [Interactions](./interactions): custom actions whose policy methods you define
+- [Resource › Actions](/reference/resource/actions): registering actions that need policy methods
+- [Tenancy › Entity scoping](/reference/tenancy/entity-scoping): `default_relation_scope`, three model shapes, custom scopes
+- [ActionPolicy docs](https://actionpolicy.evilmartians.io/): the underlying library

data/docs/reference/configuration.md

@@ -1,24 +1,27 @@
 # Configuration
 
-Plutonium is configured through `Plutonium.configure` in an initializer. A generated app has this at `config/initializers/plutonium.rb`:
+Plutonium is configured through `Plutonium.configure` in an initializer. `pu:core:install` writes `config/initializers/plutonium.rb`:
 
 ```ruby
-# config/initializers/plutonium.rb
+# Configure plutonium
+
 Plutonium.configure do |config|
   config.load_defaults 1.0
 
-  # config.shell = :modern
-  # config.navii_host_url = "https://api.navii.dev"
-  # config.auto_eager_load_collections = true
-
-  config.assets.logo       = "plutonium.png"
-  config.assets.favicon    = "plutonium.ico"
-  config.assets.stylesheet = "plutonium.css"
-  config.assets.script     = "plutonium.min.js"
+  # Shell variant: :modern (icon rail), :plain (no rail), or :classic (legacy).
+  config.shell = :modern
+  # Configure plutonium above.
 end
 ```
 
-Access the live config anywhere via `Plutonium.configuration`.
+Everything else is opt-in. Read the live config anywhere via `Plutonium.configuration`, and query development mode with `Plutonium.configuration.development?`.
+
+Other generators edit this file in place. `pu:core:assets` rewrites two lines to point at your own bundles:
+
+```ruby
+config.assets.stylesheet = "application"
+config.assets.script = "application"
+```
 
 ## Versioned defaults
 
@@ -26,41 +29,95 @@ Access the live config anywhere via `Plutonium.configuration`.
 config.load_defaults 1.0
 ```
 
-Loads the baseline defaults for a given framework version. Call this first; later versions layer their changes on top. Read the resolved version with `config.defaults_version`.
+Applies the baseline defaults for a framework version, and every earlier version in order. Call it first, before any option you set yourself, or the defaults overwrite you. `1.0` is currently the only version. Read back what resolved with `config.defaults_version`, which is `nil` until you call this.
+
+Passing a version older than the earliest available raises rather than silently applying nothing.
+
+## Core
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `load_defaults(version)` | - | Apply versioned framework defaults. Call first. |
+| `development` | `ENV["PLUTONIUM_DEV"]` | Development mode for the framework itself (local assets, hot reload, verbose errors). Query with `config.development?`. Apps rarely set this, see [Development mode](#development-mode). |
+| `cache_discovery` | `true` outside the `development` env | Cache resource/route discovery. Disable to pick up new resources without a reboot. |
+| `enable_hotreload` | `true` in the `development` env | Hot-reload Plutonium components on change. |
 
-## Options
+## Appearance
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `load_defaults(version)` | — | Apply versioned framework defaults. Call first. |
-| `development` | `ENV["PLUTONIUM_DEV"]` | Development mode for the framework itself (local assets, hot reload, verbose errors). Query with `config.development?`. You rarely set this in an app — see [Development mode](#development-mode). |
-| `cache_discovery` | `true` outside `development` env | Cache resource/route discovery. Disable to pick up new resources without a reboot. |
-| `enable_hotreload` | `true` in `development` env | Hot-reload Plutonium components on change. |
 | `shell` | `:modern` | Chrome style: `:modern` (topbar + icon rail), `:plain` (topbar, no icon rail), or `:classic` (legacy header + sidebar, only for upgrades). See [Layouts](./ui/layouts). |
+| `default_page_width` | `:md` | Width of detail-style pages: the show page and resource forms. One of `:sm` `:md` `:lg` `:xl` `:full` (`:full` opts out of any constraint). Index and table pages are unaffected. Override per-resource with `page_width` / `form_width` / `display_width`, see [Definition › Page width](./resource/definition#page-width). |
 | `navii_host_url` | `"https://api.navii.dev"` | Host of the [Navii](https://navii.dev) avatar service used by [`Avatar`](./ui/components#avatar). The component appends `/avatar/:seed`. Repoint to self-host or proxy. |
-| `auto_eager_load_collections` | `true` | Index pages, kanban boards and CSV exports preload the associations and attachments they render. Set `false` to disable globally, or override `auto_eager_load_collections?` in a controller. See [Performance](/guides/performance). |
-| `default_page_width` | `:md` | Width of detail-style pages — the show page and resource forms. One of `:sm :md :lg :xl :full` (`:full` = unconstrained). Index and table pages are unaffected. Override per-resource with `page_width` / `form_width` / `display_width`; see [Definition › Page width](./resource/definition#page-width). |
-| `wizards.width` | `:md` | Default width of wizard step pages. **Independent of `default_page_width`** — a wizard is a self-contained flow, so widening resource pages leaves wizards alone. Override per wizard with `width`. Same size tokens. |
-| `nested_association_routes` | `:detected` | Where a resource's nested routes come from. `:detected` draws one for every `has_many` / `has_one` whose child is registered. `:declared` draws only what `register_resource ..., associations:` names, so a resource that names none gets none. See [Nested resources › Declaring which associations get routes](./tenancy/nested-resources#declaring-which-associations-get-routes). |
 | `assets.logo` | `"plutonium.png"` | Brand logo asset. See [Assets](./ui/assets). |
 | `assets.favicon` | `"plutonium.ico"` | Favicon asset. |
-| `assets.stylesheet` | `"plutonium.css"` | Stylesheet entry. |
-| `assets.script` | `"plutonium.min.js"` | JavaScript entry. |
+| `assets.stylesheet` | `"plutonium.css"` | Stylesheet entry. `pu:core:assets` sets this to `"application"`. |
+| `assets.script` | `"plutonium.min.js"` | JavaScript entry. `pu:core:assets` sets this to `"application"`. |
+
+## Rendering and routing
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `auto_eager_load_collections` | `true` | Index pages, kanban boards and CSV exports preload the associations and attachments they render. The field set comes from the policy, so it is known before the collection loads. Set `false` to disable globally, or override `auto_eager_load_collections?` in a controller. See [Performance](/guides/performance). |
+| `nested_association_routes` | `:detected` | Where a resource's nested routes come from. `:detected` draws one for every `has_many` / `has_one` whose child is a registered resource. `:declared` draws only what `register_resource ..., associations:` names, so a resource that names none gets none. Any other value raises `ArgumentError` rather than drawing the wrong route table for a typo. See [Nested resources](./tenancy/nested-resources#declaring-which-associations-get-routes). |
+| `default_currency_unit` | `nil` | Symbol used when rendering a currency value with no unit set on `has_cents` or the display. `nil` falls back to the i18n `number.currency.format.unit` when the locale defines one, otherwise no symbol. Set a literal like `"£"`, or `false` (or `""`) for no symbol application-wide. See [`has_cents`](./resource/model#has-cents) and [Currency fields](./ui/forms#currency-fields). |
+| `default_phone_country` | `nil` | Default country (ISO2, e.g. `"gh"`) for `as: :phone` inputs that set no `initial_country:`. `nil` leaves it to intl-tel-input, with no country preselected. Stored verbatim; `config.normalized_default_phone_country` returns it downcased, so `"GH"` and `"gh"` are interchangeable. See [Phone fields](./ui/forms#phone-fields). |
+
+## Attachments
+
+`attachment_backend` picks which library stages a file that travels as a plain string: `:active_storage` or `:shrine`. It is the shared default, and each subsystem layers its own override on top, so setting it once covers both and setting one of theirs narrows it to that subsystem.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `attachment_backend` | `nil` | Shared default for staged attachments. `nil` auto-detects. |
+| `wizards.attachment_backend` | `nil` | Overrides the above for wizard attachment fields. `nil` falls through. |
+| `async_interactions.attachment_backend` | `nil` | Overrides the above for run dispatch. `nil` falls through. |
+
+Resolution runs first match wins:
+
+1. The field's own `backend:` option.
+2. The subsystem setting, `wizards.attachment_backend` or `async_interactions.attachment_backend`.
+3. `config.attachment_backend`.
+4. Auto-detection: `:shrine` if `ActiveShrine` is loaded, else `:active_storage`.
+
+Only plain uploads are affected. A direct-upload field already arrives as a token and ignores all of this.
+
+## Wizards
+
+`enabled` gates the subsystem and its migrations. Full detail in [Wizards › Storage & config](./wizard/storage-config).
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `wizards.enabled` | `false` | Enable wizards and their migrations. See [Enabling the subsystem](./wizard/storage-config#enabling-the-subsystem). |
+| `wizards.width` | `:md` | Width of wizard step pages. **Independent of `default_page_width`**: a wizard is a self-contained flow, so widening resource pages leaves wizards where they are. Same size tokens. Override per wizard with `width`. |
+| `wizards.cleanup_after` | `14.days` | How long completed and abandoned sessions are kept before `SweepJob` removes them. See [Cleanup & the SweepJob](./wizard/storage-config#cleanup-the-sweepjob). |
+| `wizards.database` | `:primary` | Which database the wizard tables live in. |
+| `wizards.encrypt_data` | `false` | Encrypt every wizard's staged `data` at rest. Off by default because it needs ActiveRecord encryption keys configured. A wizard can still opt in with `encrypt_data` or out with `encrypt_data false` regardless. See [Encryption](./wizard/storage-config#encryption). |
+| `wizards.attachment_backend` | `nil` | See [Attachments](#attachments). |
+
+## Async interactions
+
+`enabled` gates the runs subsystem and its migrations. Full detail in [Async interactions](./behavior/async-interactions).
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `async_interactions.enabled` | `false` | Enable persisted runs and their migrations. See [Enabling](./behavior/async-interactions#enabling). |
+| `async_interactions.queue` | `:default` | ActiveJob queue for run jobs. |
+| `async_interactions.stall_after` | `1.hour` | How long a run may sit with no progress write before `ReapJob` treats it as stalled. See [Stalled runs and ReapJob](./behavior/async-interactions#stalled-runs-and-reapjob). |
+| `async_interactions.attachment_backend` | `nil` | See [Attachments](#attachments). |
 
 ## Development mode
 
-`config.development?` is driven by the `PLUTONIUM_DEV` environment variable, not set in the initializer. It’s primarily for working **on the Plutonium gem** (uses local `src/` assets, enables hot reloading, and shows more detailed errors). Applications generally leave it unset.
+`config.development?` is driven by the `PLUTONIUM_DEV` environment variable, not by the initializer. It is for working **on the Plutonium gem**: it uses local `src/` assets, enables hot reloading, and shows more detailed errors. Applications leave it unset.
 
 ```bash
 export PLUTONIUM_DEV=1
 ```
 
-## Assets
-
-Asset entries live under `config.assets` and point the framework at your compiled stylesheet/script and brand imagery. The `pu:core:assets` generator wires these up. See [Assets](./ui/assets) for the full asset/Tailwind/Stimulus setup.
-
 ## Related
 
-- [Assets](./ui/assets) — stylesheet, script, Tailwind, and design tokens
-- [Layouts](./ui/layouts) — the `shell` option and ejecting chrome
-- [Components › Avatar](./ui/components#avatar) — `navii_host_url`
+- [Assets](./ui/assets): stylesheet, script, Tailwind, and design tokens
+- [Layouts](./ui/layouts): the `shell` option and ejecting chrome
+- [Components › Avatar](./ui/components#avatar): `navii_host_url`
+- [Wizards › Storage & config](./wizard/storage-config): the `wizards.*` settings in context
+- [Async interactions](./behavior/async-interactions): the `async_interactions.*` settings in context