plutonium 0.65.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

@@ -37,7 +37,7 @@ Passing a version older than the earliest available raises rather than silently
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `load_defaults(version)` | — | Apply versioned framework defaults. Call first. |
+| `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. |
@@ -116,8 +116,8 @@ export PLUTONIUM_DEV=1
 
 ## 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`
-- [Wizards › Storage & config](./wizard/storage-config) — the `wizards.*` settings in context
-- [Async interactions](./behavior/async-interactions) — the `async_interactions.*` settings in context
+- [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

data/docs/reference/dashboard/dsl.md

@@ -48,8 +48,8 @@ Keys are unique per dashboard; a duplicate raises at class load. Cards render in
 | `description:` | String, lazy `t` | convention | Caption |
 | `icon:` | Phlex icon class | none | Shown beside the title |
 | `span:` | `1`..`12`, `:full` | metric `3`, chart `6`, card `6` | Columns of the 12-column grid. `:full` is `12`. On tablets (2 columns) a span of `6` or more takes the row; phones are one column |
-| `lazy:` | Boolean | `true` | `true`: own lazy turbo frame, block runs in a separate request. `false`: inline, block runs in the page request; no frame, never refreshes. See the [guide](/guides/dashboards#lazy-and-inline-cards) |
-| `refresh:` | Integer seconds, or `false` | dashboard `refresh` | Reload interval; requires `lazy: true`. `false` opts the card out of the dashboard's `refresh` |
+| `lazy:` | Boolean | `true` | `true`: own lazy turbo frame, block runs in a separate request. `false`: inline, block runs in the page request (adding its query time to every page load); no frame, never refreshes. When `config.consider_all_requests_local` is true (development and test), an inline card's exception fails the whole page. See the [guide](/guides/dashboards#lazy-and-inline-cards) |
+| `refresh:` | Integer seconds, or `false` | dashboard `refresh` | Reload interval; requires `lazy: true` (a number on a `lazy: false` card raises `ArgumentError`). `false` opts the card out of the dashboard's `refresh` |
 | `condition:` | Proc, Symbol | none | Hides the card and 404s its endpoint when false |
 | `href:` | String, Proc | none | Links the title |
 

data/docs/reference/dashboard/index.md

@@ -4,7 +4,7 @@
 Dashboards are experimental: the DSL and behavior may change in a future release.
 :::
 
-Reference documentation for Plutonium dashboards: pages of metric, chart and free-form cards, each loaded in its own lazy turbo frame.
+Reference documentation for Plutonium dashboards: pages of metric, chart and free-form cards, each loaded in its own lazy turbo frame by default.
 
 ## In this section
 

data/docs/reference/generators/lite.md

@@ -16,10 +16,10 @@ rails g pu:lite:tune
 
 It writes a `pragmas:` mapping:
 
-- `cache_size: -64000` — 64 MB page cache (the ~2 MB default is too small).
-- `temp_store: 2` — MEMORY; sorts and temp indexes stay off disk.
-- `mmap_size: 536870912` — 512 MB memory-mapped I/O.
-- `wal_autocheckpoint: 10000` — checkpoint roughly every 40 MB of WAL.
+- `cache_size: -64000`: 64 MB page cache (the ~2 MB default is too small).
+- `temp_store: 2`: MEMORY; sorts and temp indexes stay off disk.
+- `mmap_size: 536870912`: 512 MB memory-mapped I/O.
+- `wal_autocheckpoint: 10000`: checkpoint roughly every 40 MB of WAL.
 
 On Rails < 8.1 it also writes the baseline pragmas (`journal_mode: WAL`,
 `synchronous: NORMAL`, `foreign_keys: true`, `journal_size_limit`) that Rails 8.1+
@@ -30,7 +30,7 @@ constant-poll busy handler (`busy_handler_timeout`), which has better tail-laten
 than SQLite's internal exponential backoff. Setting a busy-timeout pragma would
 replace the better handler with the worse one, so this generator never emits it.
 
-The generator is idempotent — re-running it detects the existing pragmas and skips.
+The generator is idempotent: re-running it detects the existing pragmas and skips.
 It only ever touches the `default:` block, so a `pragmas:` mapping nested under
 another environment is left untouched.
 
@@ -47,7 +47,7 @@ rails g pu:lite:maintenance --schedule="every day at 4am"
 
 The job runs `PRAGMA optimize` on every configured SQLite database and `VACUUM`
 only on databases without live 24/7 writers (`primary`, `errors`, `rails_pulse`
-by default — edit `VACUUM_DBS` in the generated job to suit your app).
+by default; edit `VACUUM_DBS` in the generated job to suit your app).
 
 **Why VACUUM only some databases?** SolidQueue, Solid Cache and Solid Cable write
 to their databases constantly. `VACUUM` takes a global *exclusive* lock for its
@@ -61,5 +61,5 @@ Databases listed in the job that don't exist in `config/database.yml` are skippe
 at runtime, so the same job is safe regardless of which `pu:lite:*` generators you
 have run.
 
-If `solid_queue` is not installed, the job file is still created but not scheduled —
+If `solid_queue` is not installed, the job file is still created but not scheduled:
 add a `sqlite_maintenance` entry to whatever scheduler you use.

data/docs/reference/i18n.md

@@ -120,6 +120,29 @@ index_page_description t("blog.index.description")
 
 When a definition sets no title, the page falls back to the resource's translated model name.
 
+The setter's proc is called with no record context, so a title that depends on the record belongs in a `page_title` override on the nested page class (`class ShowPage < ShowPage`), where `object` is available.
+
+## Your own components and pages
+
+Text you add to the UI goes in a locale file too. Which `t` you call depends on where the code runs:
+
+| Where | Call |
+|---|---|
+| Components, pages, and nested `Form` / `Display` / `Table` classes (render hooks included) | `t("full.key", **opts)`, a protected method from `Plutonium::UI::Component::Behaviour` |
+| `display` / `input` / `column` blocks in a definition | `t("full.key")`, since the block runs inside the rendering component |
+| Definition class body (`label:`, `hint:`, `placeholder:`, page titles) | the class-level lazy `t("full.key")` above |
+| A bare Phlexi field component that does not include `Behaviour` | `Plutonium::Translation.t("full.key")` |
+
+All of them take full keys only. Use one key per sentence with `%{name}` placeholders rather than concatenating fragments around a value, and `count:` for plurals:
+
+```ruby
+def render_before_content
+  div(class: "pu-alert pu-alert-info", role: "status") do
+    div(class: "pu-alert-message") { t("blog.posts.show.comment_count", count: object.comments.count) }
+  end
+end
+```
+
 ## Derived labels
 
 Actions, scopes, filters, kanban columns and wizard steps default to a humanized version of their key. Each has a convention key that takes precedence over that fallback, and a `label:` option that takes precedence over both. For an action backed by an interaction, the interaction's explicit `presents label:` also counts as declared and wins over the convention; only the class-name default yields to it.

data/docs/reference/index.md

@@ -7,7 +7,7 @@ aside: false
 <SectionLanding
   eyebrow="Reference"
   title="Every API, in one place."
-  lede="The full surface area of Plutonium — controllers, policies, definitions, fields, interactions, generators."
+  lede="The full surface area of Plutonium: controllers, policies, definitions, fields, interactions, generators."
   mode="categorized"
   :rail="[
     { group: 'App', items: [