plutonium 0.65.0 → 0.66.0

data/docs/guides/authentication.md

@@ -6,7 +6,7 @@ Add Rodauth-based authentication to your Plutonium app.
 
 Authenticated users can sign up, log in, change passwords, and reset forgotten passwords. Pages in protected portals are gated.
 
-## Quick path — basic user auth
+## Quick path: basic user auth
 
 ```bash
 # 1. Install Rodauth
@@ -22,7 +22,7 @@ rails db:prepare
 #    (when you run `pu:pkg:portal admin --auth=user`, this happens automatically)
 ```
 
-If you generated the portal with `--auth=user`, the engine is already mounted with the `Rodauth::Rails.authenticate(:user)` constraint — open `packages/admin_portal/config/routes.rb` to see it. The wiring looks like:
+If you generated the portal with `--auth=user`, the engine is already mounted with the `Rodauth::Rails.authenticate(:user)` constraint: open `packages/admin_portal/config/routes.rb` to see it. The wiring looks like:
 
 ```ruby
 # packages/admin_portal/config/routes.rb (generated)
@@ -64,13 +64,13 @@ EMAIL=admin@example.com rails rodauth:admin
 
 The task creates the account and triggers a verification email; the admin sets their own password through that flow. No password is passed on the command line.
 
-### Multi-tenant SaaS — user + entity + membership in one shot
+### Multi-tenant SaaS: user + entity + membership in one shot
 
 ```bash
 rails generate pu:saas:setup --user Customer --entity Organization
 ```
 
-⚠️ This is a **meta-generator** — it also runs `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, and `pu:invites:install`. Don't re-run those manually. See [Reference › Auth › Accounts › SaaS setup](/reference/auth/accounts#saas-setup).
+⚠️ This is a **meta-generator**: it also runs `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, and `pu:invites:install`. Don't re-run those manually. See [Reference › Auth › Accounts › SaaS setup](/reference/auth/accounts#saas-setup).
 
 ### API-only (JWT)
 
@@ -103,7 +103,7 @@ module CustomerPortal::Concerns::Controller
 end
 ```
 
-Multiple account types — different portals use different Rodauth instances:
+Multiple account types (different portals use different Rodauth instances):
 
 ```ruby
 # Admin portal
@@ -117,40 +117,40 @@ See [Reference › App › Portals](/reference/app/portals#controller-concern-au
 
 ## Multiple portals in one browser
 
-A person can hold a session in several portals at once — signed into the admin portal and the customer portal in the same browser, with neither evicting the other. Two settings make that work, and the generators emit both:
+A person can hold a session in several portals at once (signed into the admin portal and the customer portal in the same browser, with neither evicting the other). Two settings make that work, and the generators emit both:
 
 ```ruby
-# app/rodauth/rodauth_plugin.rb — the shared base
+# app/rodauth/rodauth_plugin.rb: the shared base
 configure do
   enable :session_isolation
 end
 ```
 
 ```ruby
-# app/rodauth/admin_rodauth_plugin.rb — once per account type
+# app/rodauth/admin_rodauth_plugin.rb: once per account type
 configure do
   session_key_prefix "admin_"
   remember_cookie_key "_admin_remember"
 end
 ```
 
-Both are required. `session_key_prefix` namespaces *every* session key a configuration touches — the account id plus `authenticated_by`, `login_redirect`, `two_factor_auth_setup` and the rest. `session_isolation` uses that prefix to decide which entries belong to whom, and stops one configuration's login from clearing another's.
+Both are required. `session_key_prefix` namespaces *every* session key a configuration touches, the account id plus `authenticated_by`, `login_redirect`, `two_factor_auth_setup` and the rest. `session_isolation` uses that prefix to decide which entries belong to whom, and stops one configuration's login from clearing another's.
 
 ::: danger Do not also set `session_key`
-An explicit `session_key` is **not** prefixed (`convert_session_key`, `rodauth/features/base.rb:686` — only the default value passes through it). Setting both leaves the account id on a different name from every other key, so they stop rotating together. A session that holds an account id but no `authenticated_by` makes Rodauth raise on *every request* — `logged_in_via_remember_key?` calls `nil.include?` (`remember.rb:175`).
+An explicit `session_key` is **not** prefixed (`convert_session_key`, `rodauth/features/base.rb:686`, only the default value passes through it). Setting both leaves the account id on a different name from every other key, so they stop rotating together. A session that holds an account id but no `authenticated_by` makes Rodauth raise on *every request*, `logged_in_via_remember_key?` calls `nil.include?` (`remember.rb:175`).
 
 A config without a prefix at all is also not isolated: its keys are Rodauth's unprefixed defaults, indistinguishable from any other unprefixed config's, so `session_isolation` carries nothing for it.
 :::
 
 ::: details Why this is needed
-Rodauth resets the session on every login — including the `remember` feature's `load_memory` autologin — to defend against session fixation, and rodauth-rails implements that reset as a full `reset_session`.
+Rodauth resets the session on every login, including the `remember` feature's `load_memory` autologin, to defend against session fixation, and rodauth-rails implements that reset as a full `reset_session`.
 
 Without `session_isolation`, signing into one portal wipes every other portal's session. And because `RodauthApp#route` calls `load_memory` for *every* configuration on *every* request, the evicted configuration immediately autologins from its remember cookie and evicts the new one right back. The last `load_memory` call in the route block wins permanently, so the other portal can never hold a session at all.
 
 `session_isolation` carries only the *other configurations'* session entries across the reset. The session id is still rotated and application session data is still cleared, so session fixation is still defeated.
 :::
 
-Reading a raw Rodauth session key? Go through its accessor, never the literal — with a prefix set, the literal is the wrong key:
+Reading a raw Rodauth session key? Go through its accessor, never the literal: with a prefix set, the literal is the wrong key:
 
 ```ruby
 after_login do
@@ -159,9 +159,9 @@ after_login do
 end
 ```
 
-**Upgrading an app generated before this existed:** add `enable :session_isolation` once in the base plugin and `session_key_prefix` in each account plugin — and **delete the existing `session_key "_x_session"` line** while you're there, for the reason above.
+**Upgrading an app generated before this existed:** add `enable :session_isolation` once in the base plugin and `session_key_prefix` in each account plugin, and **delete the existing `session_key "_x_session"` line** while you're there, for the reason above.
 
-Every key name changes together, so old session cookies stop matching and are ignored — the safe outcome. Keeping the old `session_key` to "preserve" logins is what produces the half-migrated session that crashes.
+Every key name changes together, so old session cookies stop matching and are ignored (the safe outcome). Keeping the old `session_key` to "preserve" logins is what produces the half-migrated session that crashes.
 
 In practice only *unremembered* sessions drop: `remember_cookie_key` is a cookie name and isn't touched by the prefix, so anyone holding a valid `_x_remember` cookie is restored by `load_memory` on their next request, which writes the new prefixed keys. Expect logouts for users who never ticked "Remember Me", not a full sign-out.
 
@@ -180,9 +180,9 @@ after_login { remember_login }
 ```
 
 ::: warning Compare the value, don't just check presence
-`param_or_nil(remember_param)` on its own is a truthiness check, and `remember_param` is shared with Rodauth's `/remember` settings page — which submits `forget` and `disable` as well as `remember`. A bare presence check means `remember=disable` would remember you. Compare against `remember_remember_param_value`, as above.
+`param_or_nil(remember_param)` on its own is a truthiness check, and `remember_param` is shared with Rodauth's `/remember` settings page, which submits `forget` and `disable` as well as `remember`. A bare presence check means `remember=disable` would remember you. Compare against `remember_remember_param_value`, as above.
 
-Plutonium's login form also passes `include_hidden: false` to `check_box`, so an unticked box sends nothing at all rather than Rails' default `"0"`. With the value comparison that's belt-and-braces rather than load-bearing (`"0" == "remember"` is already false) — but it keeps a junk param off the wire and keeps the form correct for anyone who reverts the hook to a bare truthiness check.
+Plutonium's login form also passes `include_hidden: false` to `check_box`, so an unticked box sends nothing at all rather than Rails' default `"0"`. With the value comparison that's belt-and-braces rather than load-bearing (`"0" == "remember"` is already false), but it keeps a junk param off the wire and keeps the form correct for anyone who reverts the hook to a bare truthiness check.
 :::
 
 Logged-in users can change the setting later on Rodauth's `/remember` page (Remember / Forget / Disable).
@@ -254,15 +254,15 @@ user
 
 ## Common issues
 
-- **"You need to set up Rodauth"** — run `pu:rodauth:install` first.
-- **Portal redirects to login even though you're authenticated** — the portal mount constraint references a different Rodauth account than the portal's controller concern uses. Match them up.
-- **Email confirmation never arrives in development** — Plutonium sets ActionMailer to `:test` by default. Check `tmp/letter_opener/` or your mail interceptor. In production, configure SMTP (see above).
-- **Signing into one portal signs you out of another** — or one portal can never stay signed in at all. Missing `enable :session_isolation` and/or `session_key_prefix`; see [Multiple portals in one browser](#multiple-portals-in-one-browser).
+- **"You need to set up Rodauth"**: run `pu:rodauth:install` first.
+- **Portal redirects to login even though you're authenticated**: the portal mount constraint references a different Rodauth account than the portal's controller concern uses. Match them up.
+- **Email confirmation never arrives in development**: Plutonium sets ActionMailer to `:test` by default. Check `tmp/letter_opener/` or your mail interceptor. In production, configure SMTP (see above).
+- **Signing into one portal signs you out of another**: or one portal can never stay signed in at all. Missing `enable :session_isolation` and/or `session_key_prefix`; see [Multiple portals in one browser](#multiple-portals-in-one-browser).
 
 ## Related
 
-- [Reference › Auth](/reference/auth/) — full auth surface
-- [Authorization](./authorization) — controlling who can do what AFTER login
-- [Multi-tenancy](./multi-tenancy) — entity scoping for SaaS apps
-- [User invites](./user-invites) — invitation-based onboarding
-- [User profile](./user-profile) — account-settings page
+- [Reference › Auth](/reference/auth/): full auth surface
+- [Authorization](./authorization): controlling who can do what AFTER login
+- [Multi-tenancy](./multi-tenancy): entity scoping for SaaS apps
+- [User invites](./user-invites): invitation-based onboarding
+- [User profile](./user-profile): account-settings page

data/docs/guides/authorization.md

@@ -10,9 +10,9 @@ For each resource, decide who can create / read / update / destroy / run custom
 
 Every policy controls three things:
 
-1. **Action permissions** — `create?`, `read?`, `update?`, `destroy?`, plus your custom action methods.
-2. **Attribute permissions** — `permitted_attributes_for_create`, `_for_read`, etc.
-3. **Collection scope** — `relation_scope` (which records show up in lists).
+1. **Action permissions**: `create?`, `read?`, `update?`, `destroy?`, plus your custom action methods.
+2. **Attribute permissions**: `permitted_attributes_for_create`, `_for_read`, etc.
+3. **Collection scope**: `relation_scope` (which records show up in lists).
 
 ## 🚨 Critical
 
@@ -39,7 +39,7 @@ class PostPolicy < ResourcePolicy
 end
 ```
 
-These default to `false` — without an explicit override, nobody can create or read records.
+These default to `false`, without an explicit override, nobody can create or read records.
 
 ### 3. Override derived methods only when rules differ
 
@@ -55,7 +55,7 @@ def destroy?
 end
 ```
 
-🚨 **`record` is the resource CLASS on collection routes.** `read?` backs both `show?` (called with the record) and `index?` (called with the class — there is no single record to pass). The same goes for `create?`/`new?`, `export_csv?`, `search?`, and resource-action gates. So `def read? = record.published?` raises `NoMethodError` the moment the index renders. Keep record-state rules out of these methods: filter what the list shows in `relation_scope` (step 6 below), and gate individual records in `show?` (which always receives the record). Record-action methods like `publish?` are safe — they are always evaluated against an instance.
+🚨 **`record` is the resource CLASS on collection routes.** `read?` backs both `show?` (called with the record) and `index?` (called with the class: there is no single record to pass). The same goes for `create?`/`new?`, `export_csv?`, `search?`, and resource-action gates. So `def read? = record.published?` raises `NoMethodError` the moment the index renders. Keep record-state rules out of these methods: filter what the list shows in `relation_scope` (step 6 below), and gate individual records in `show?` (which always receives the record). Record-action methods like `publish?` are safe; they are always evaluated against an instance.
 
 ### 4. Declare attribute permissions
 
@@ -69,8 +69,8 @@ def permitted_attributes_for_read
 end
 ```
 
-::: warning Index has no `record`
-`permitted_attributes_for_index` runs at collection level — `record` is `nil`. If you write a `record`-dependent `_for_read`, you MUST also declare an explicit `_for_index`. See [Reference › Behavior › Policies › Index has no record](/reference/behavior/policies#index-has-no-record).
+::: warning Index has no `record` instance
+`permitted_attributes_for_index` runs at collection level, where `record` is the resource class. `_for_index` falls back to `_for_read` (and `_for_export` to `_for_index`), so if you write a `record`-dependent `_for_read`, you MUST also declare an explicit `_for_index` that never touches `record`. See [Reference › Behavior › Policies › Index has no record](/reference/behavior/policies#index-has-no-record).
 :::
 
 ### 5. Custom action methods
@@ -87,7 +87,7 @@ end
 
 The method name matches the action name plus `?`. Undefined methods return `false`.
 
-### 6. Optionally filter the collection — `relation_scope`
+### 6. Optionally filter the collection: `relation_scope`
 
 ```ruby
 relation_scope do |relation|
@@ -95,7 +95,7 @@ relation_scope do |relation|
 end
 ```
 
-🚨 `default_relation_scope(relation)` must be called somewhere in the chain — otherwise `verify_default_relation_scope_applied!` raises at runtime. Calling it explicitly here is safest. `super` works only when the parent policy also calls it.
+🚨 `default_relation_scope(relation)` must be called somewhere in the chain, otherwise `verify_default_relation_scope_applied!` raises at runtime. Calling it explicitly here is safest. `super` works only when the parent policy also calls it.
 
 ## Common patterns
 
@@ -143,7 +143,7 @@ def update?
 end
 ```
 
-## Bulk action authorization — per record
+## Bulk action authorization: per record
 
 ```ruby
 def bulk_archive?
@@ -154,7 +154,7 @@ end
 - **Backend:** if any selected 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 can access.
+Records come from `current_authorized_scope`; users can only select records they can access.
 
 ## Portal-specific policies
 
@@ -163,7 +163,7 @@ class PostPolicy < ResourcePolicy
   def create? = user.present?
 end
 
-# Admin — more permissive
+# Admin: more permissive
 class AdminPortal::PostPolicy < ::PostPolicy
   include AdminPortal::ResourcePolicy
 
@@ -171,7 +171,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
@@ -186,7 +186,7 @@ def permitted_associations
 end
 ```
 
-Drives the show-page tablist. Each named association must exist on the model AND be a registered Plutonium resource. See [Reference › Behavior › Policies › Association permissions](/reference/behavior/policies#association-permissions).
+Drives the show-page tablist. Each named association must exist on the model AND be a registered Plutonium resource in every portal that uses the policy; a portal that doesn't register the child raises `ArgumentError ... is not a registered resource` on its show page. To add a tab in one portal only, put it in a portal-specific policy (`rails g pu:res:conn <Resource> --dest=<portal> --policy`). See [Reference › Behavior › Policies › Association permissions](/reference/behavior/policies#association-permissions).
 
 ::: warning Not for nested forms
 `permitted_associations` is for show-page navigation tabs, NOT nested forms. Nested forms come from `nested_input :variants` in the definition. See [Reference › Resource › Definition › Nested inputs](/reference/resource/definition#nested-inputs).
@@ -194,7 +194,7 @@ Drives the show-page tablist. Each named association must exist on the model AND
 
 ## Multi-tenant scoping
 
-When the portal sets `scope_to_entity Organization`, the inherited `relation_scope` automatically filters everything to the current org — no work in the policy. To add filters on top:
+When the portal sets `scope_to_entity Organization`, the inherited `relation_scope` automatically filters everything to the current org, no work in the policy. To add filters on top:
 
 ```ruby
 relation_scope do |relation|
@@ -243,15 +243,15 @@ end
 
 ## Common issues
 
-- **Undefined custom action policy method** — the button silently disappears (undefined returns `false`). Add `def my_action?` to the policy.
-- **`record.X` crashes during index** — `record` is `nil` on index. Add an explicit `permitted_attributes_for_index` that doesn't depend on `record`.
-- **`verify_default_relation_scope_applied!` raises** — your custom `relation_scope` doesn't call `default_relation_scope(relation)`. Fix by composing: `default_relation_scope(relation).where(...)`.
-- **`super` in `relation_scope`** — works when you're extending a parent policy that itself calls `default_relation_scope`. If you're not sure (or you're inheriting from `Plutonium::Resource::Policy` directly), call `default_relation_scope(relation)` explicitly. The runtime check verifies `default_relation_scope` was hit somewhere — not that you wrote it in this class.
+- **Undefined custom action policy method**: the button silently disappears (undefined returns `false`). Add `def my_action?` to the policy.
+- **`record.X` crashes during index**: `record` is the resource class on index, not an instance. Add an explicit `permitted_attributes_for_index` that doesn't depend on `record`.
+- **`verify_default_relation_scope_applied!` raises**: your custom `relation_scope` doesn't call `default_relation_scope(relation)`. Fix by composing: `default_relation_scope(relation).where(...)`.
+- **`super` in `relation_scope`**; works when you're extending a parent policy that itself calls `default_relation_scope`. If you're not sure (or you're inheriting from `Plutonium::Resource::Policy` directly), call `default_relation_scope(relation)` explicitly. The runtime check verifies `default_relation_scope` was hit somewhere: not that you wrote it in this class.
 
 ## Related
 
-- [Reference › Behavior › Policies](/reference/behavior/policies) — full policy surface
-- [Reference › Tenancy › Entity scoping](/reference/tenancy/entity-scoping) — `default_relation_scope`, multi-tenant patterns
-- [Authentication](./authentication) — who's the user in the first place
-- [Multi-tenancy](./multi-tenancy) — entity scoping setup
-- [Custom actions](./custom-actions) — defining the actions that need policy methods
+- [Reference › Behavior › Policies](/reference/behavior/policies): full policy surface
+- [Reference › Tenancy › Entity scoping](/reference/tenancy/entity-scoping): `default_relation_scope`, multi-tenant patterns
+- [Authentication](./authentication): who's the user in the first place
+- [Multi-tenancy](./multi-tenancy): entity scoping setup
+- [Custom actions](./custom-actions): defining the actions that need policy methods

data/docs/guides/creating-packages.md

@@ -13,7 +13,7 @@ Domain code (models, policies, definitions, interactions) lives in **feature pac
 | **Feature** | Business logic | `pu:pkg:package NAME` | `blogging`, `billing`, `inventory` |
 | **Portal** | Web interface | `pu:pkg:portal NAME` | `admin_portal`, `customer_portal`, `public_portal` |
 
-🚨 Don't mix the two. Feature packages own the **domain code** — models, interactions, policies/definitions for resources owned by that feature. Portal packages own the **web surface** — controllers, routes, auth, and portal-specific policy/definition *overrides* for resources they expose.
+🚨 Don't mix the two. Feature packages own the **domain code**: models, interactions, policies/definitions for resources owned by that feature. Portal packages own the **web surface**: controllers, routes, auth, and portal-specific policy/definition *overrides* for resources they expose.
 
 ## Feature package
 
@@ -59,12 +59,12 @@ rails g pu:pkg:portal admin --auth=user
 
 Options:
 
-- `--auth=NAME` — Rodauth account to authenticate with.
-- `--public` — public access, no auth.
-- `--byo` — bring your own auth.
-- `--scope=CLASS` — entity class for multi-tenancy.
+- `--auth=NAME`: Rodauth account to authenticate with.
+- `--public`: public access, no auth.
+- `--byo`: bring your own auth.
+- `--scope=CLASS`: entity class for multi-tenancy.
 
-The generator mounts the engine for you — at `/admin` in this case, wrapped in `constraints Rodauth::Rails.authenticate(:user)` because you passed `--auth=user`. Open `packages/admin_portal/config/routes.rb` to see the generated mount.
+The generator mounts the engine for you: at `/admin` in this case, wrapped in `constraints Rodauth::Rails.authenticate(:user)` because you passed `--auth=user`. Open `packages/admin_portal/config/routes.rb` to see the generated mount.
 
 ### 2. Connect resources
 
@@ -87,7 +87,7 @@ Every file under `app/<kind>/blogging/` resolves to `Blogging::*`:
 - `app/models/blogging/post.rb` → `Blogging::Post`
 - `app/policies/blogging/post_policy.rb` → `Blogging::PostPolicy`
 
-Each feature package gets base classes — `Blogging::ApplicationRecord`, `Blogging::ResourceRecord`, `Blogging::ResourcePolicy`, `Blogging::ResourceDefinition`, `Blogging::ResourceInteraction` — that inherit from the main app's.
+Each feature package gets base classes, `Blogging::ApplicationRecord`, `Blogging::ResourceRecord`, `Blogging::ResourcePolicy`, `Blogging::ResourceDefinition`, `Blogging::ResourceInteraction`, that inherit from the main app's.
 
 ## Cross-package references
 
@@ -129,7 +129,7 @@ packages/
 └── customer_portal/         # Portal: customer dashboard
 ```
 
-The portals expose the features. A single feature can be exposed by multiple portals — usually with different policies and definitions per portal.
+The portals expose the features. A single feature can be exposed by multiple portals, usually with different policies and definitions per portal.
 
 ## Package loading
 
@@ -147,13 +147,13 @@ Loaded from `config/application.rb`. Migrations from all packages are picked up
 ## Per-portal overrides
 
 ```ruby
-# Definition — how fields render per portal
+# Definition: how fields render per portal
 class AdminPortal::PostDefinition < ::PostDefinition
   scope :pending_review
   input :internal_notes, hint: "Not shown to the author"
 end
 
-# Policy — which fields exist, and who may act
+# Policy: which fields exist, and who may act
 #          `internal_notes` appears for admins because THIS permits it,
 #          not because the definition above mentions it.
 class AdminPortal::PostPolicy < ::PostPolicy
@@ -166,13 +166,13 @@ end
 
 ## Common issues
 
-- **Class not loading** — namespace must match the directory: `app/models/blogging/post.rb` MUST be `Blogging::Post`.
-- **Migration not running** — package migrations are auto-included. If they aren't running, check `config/packages.rb` is loaded from `application.rb`.
-- **Cross-package association fails** — use `blogging/post:belongs_to` in `pu:res:scaffold`, OR manually set `class_name: "Blogging::Post"` on the `belongs_to`.
+- **Class not loading**: namespace must match the directory: `app/models/blogging/post.rb` MUST be `Blogging::Post`.
+- **Migration not running**: package migrations are auto-included. If they aren't running, check `config/packages.rb` is loaded from `application.rb`.
+- **Cross-package association fails**: use `blogging/post:belongs_to` in `pu:res:scaffold`, OR manually set `class_name: "Blogging::Post"` on the `belongs_to`.
 
 ## Related
 
-- [Reference › App › Packages](/reference/app/packages) — full package surface
-- [Reference › App › Portals](/reference/app/portals) — portal-specific configuration
-- [Adding resources](./adding-resources) — `pu:res:scaffold` and `pu:res:conn`
-- [Authentication](./authentication) — portal auth setup
+- [Reference › App › Packages](/reference/app/packages): full package surface
+- [Reference › App › Portals](/reference/app/portals): portal-specific configuration
+- [Adding resources](./adding-resources): `pu:res:scaffold` and `pu:res:conn`
+- [Authentication](./authentication): portal auth setup

data/docs/guides/custom-actions.md

@@ -1,6 +1,6 @@
 # Custom Actions
 
-Add buttons beyond CRUD — Publish, Archive, Import, Send invitation, Bulk-update, etc.
+Add buttons beyond CRUD: Publish, Archive, Import, Send invitation, Bulk-update, etc.
 
 ## Goal
 
@@ -10,17 +10,17 @@ A button appears in the right place (show page / table row / index header / bulk
 
 | Flavor | Use for |
 |---|---|
-| **Simple action** — navigate to a URL | Linking to external docs, jumping to a custom page that does its own thing |
-| **Interactive action** — run an interaction class | Anything that *does* something (the common case) |
+| **Simple action**: navigate to a URL | Linking to external docs, jumping to a custom page that does its own thing |
+| **Interactive action**: run an interaction class | Anything that *does* something (the common case) |
 
-Prefer interactive actions. They handle authorization, form rendering, modal chrome, success/failure messaging, and automatic redirects — all for free.
+Prefer interactive actions. They handle authorization, form rendering, modal chrome, success/failure messaging, and automatic redirects, all for free.
 
-## Quick recipe — interactive action
+## Quick recipe: interactive action
 
 ### 1. Write the interaction
 
 ```ruby
-# app/models/post.rb — what publishing actually means
+# app/models/post.rb: what publishing actually means
 class Post < ApplicationRecord
   def publish!(on: Time.current)
     update!(published: true, published_at: on)
@@ -29,7 +29,7 @@ end
 ```
 
 ```ruby
-# app/interactions/publish_post_interaction.rb — the button in front of it
+# app/interactions/publish_post_interaction.rb: the button in front of it
 class PublishPostInteraction < ResourceInteraction
   presents label: "Publish",
            icon:  Phlex::TablerIcons::Send,
@@ -51,7 +51,7 @@ Plutonium doesn't rescue it automatically. Always rescue when using `create!` /
 :::
 
 ::: tip Why `publish!` is on the model
-An interaction can only be built with a `view_context` — it's a presentation object. A two-line `update!` inline in `execute` is fine while the button is the only caller; the moment a scheduled-publishing job wants the same behaviour it has to duplicate it or fake a view context. Full rule: [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
+An interaction can only be built with a `view_context`; it's a presentation object. A two-line `update!` inline in `execute` is fine while the button is the only caller; the moment a scheduled-publishing job wants the same behaviour it has to duplicate it or fake a view context. Full rule: [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
 :::
 
 ### 2. Register it in the definition
@@ -62,7 +62,7 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-Action visibility (record / bulk / resource) is **inferred** from the interaction's attributes — no need to declare `record_action: true`. See [Inferred visibility](#inferred-visibility) below.
+Action visibility (record / bulk / resource) is **inferred** from the interaction's attributes; no need to declare `record_action: true`. See [Inferred visibility](#inferred-visibility) below.
 
 ### 3. Add a policy method
 
@@ -88,7 +88,7 @@ For `interaction:`-based actions, visibility flags are inferred from the interac
 | `attribute :resources` (plural) | `bulk_action: true` → bulk toolbar |
 | neither | `resource_action: true` → index page header |
 
-User-supplied flags can only **opt OUT** of inferred ones. Don't try to "broaden" — the interaction's attribute shape is semantic:
+User-supplied flags can only **opt OUT** of inferred ones. Don't try to "broaden"; the interaction's attribute shape is semantic:
 
 ```ruby
 # Hide from per-row menu, keep on show page
@@ -127,7 +127,7 @@ class Company::InviteUserInteraction < ResourceInteraction
 end
 ```
 
-`Company#invite!` creates the row *and* sends the mail. Both are things a seat-provisioning job needs to do without a browser anywhere in sight — see the [full worked example](/reference/behavior/interactions#complete-example).
+`Company#invite!` creates the row *and* sends the mail. Both are things a seat-provisioning job needs to do without a browser anywhere in sight, see the [full worked example](/reference/behavior/interactions#complete-example).
 
 ## Bulk actions
 
@@ -146,7 +146,7 @@ class BulkArchiveInteraction < ResourceInteraction
 end
 ```
 
-Policy — checked **per record** (fails the whole request if any record is unauthorized):
+Policy: checked **per record** (fails the whole request if any record is unauthorized):
 
 ```ruby
 def bulk_archive?
@@ -181,13 +181,13 @@ class BulkArchiveInteraction < ResourceInteraction
 end
 ```
 
-Nothing else about the action changes — the definition, the policy method and the form are the same. Only the work moves.
+Nothing else about the action changes: the definition, the policy method and the form are the same. Only the work moves.
 
 Three things worth knowing:
 
 - **The block is the run's class body, not `execute`.** The work runs later, in a job with no controller, so it cannot close over anything in the interaction. Its inputs arrive through `options`.
 - **The user is sent back where they were**, and the index they land on shows a banner for the run with a link to its progress page.
-- **Permissions are re-checked per record, at perform time** — not replayed from dispatch. A permission revoked while the run is working stops applying to the rest of it.
+- **Permissions are re-checked per record, at perform time**: not replayed from dispatch. A permission revoked while the run is working stops applying to the rest of it.
 
 Full detail, including file attributes, failure policies and resuming a crashed run: [Async Interactions](/reference/behavior/async-interactions).
 
@@ -212,8 +212,8 @@ end
 
 ## Immediate vs form
 
-- **Immediate** — interaction has only `:resource` / `:resources` (no extra inputs). Browser confirmation (`"#{label}?"`, e.g. `"Archive?"`), then runs. Override with `confirmation: "Custom message"` or `confirmation: false` on the action.
-- **Form** — interaction has additional `attribute` / `input`. Renders modal form first; no auto-confirmation (the form is the confirmation).
+- **Immediate**: interaction has only `:resource` / `:resources` (no extra inputs). Browser confirmation (`"#{label}?"`, e.g. `"Archive?"`), then runs. Override with `confirmation: "Custom message"` or `confirmation: false` on the action.
+- **Form**: interaction has additional `attribute` / `input`. Renders modal form first; no auto-confirmation (the form is the confirmation).
 
 ## Action options
 
@@ -231,10 +231,10 @@ action :name,
 
   # Behavior
   confirmation: "Are you sure?",
-  modal: :slideover,                     # :slideover / :centered — overrides definition's modal mode
-  size:  :lg,                            # :sm / :md / :lg / :xl / :auto / :full — overrides definition's modal size
+  modal: :slideover,                     # :slideover / :centered, overrides definition's modal mode
+  size:  :lg,                            # :sm / :md / :lg / :xl / :auto / :full, overrides definition's modal size
 
-  # HTML attributes — author wins over the framework's on every key
+  # HTML attributes: author wins over the framework's on every key
   link:   {target: "_blank", rel: "noopener"},  # every <a> rendering (toolbar GET link, dropdown items, bulk links, card show link)
   button: {data: {analytics: "archive"}}        # the button_to <form> wrapper (non-GET toolbar rendering)
 ```
@@ -283,7 +283,7 @@ Every resource gets `:archive` automatically.
 
 ## Where the logic goes
 
-Interactions are presentation objects — they need a `view_context` to exist at all. So the reflex to reach for when an operation grows:
+Interactions are presentation objects: they need a `view_context` to exist at all. So the reflex to reach for when an operation grows:
 
 ```ruby
 # 🚫 Three interactions, three view contexts, none of it callable from a job
@@ -300,22 +300,22 @@ def execute
 end
 ```
 
-Sending a welcome email and writing an audit row are exactly what a signup API endpoint or a rake task also does — and neither has a view context to hand.
+Sending a welcome email and writing an audit row are exactly what a signup API endpoint or a rake task also does, and neither has a view context to hand.
 
-The rule isn't "never put logic in an interaction". A single-caller operation can stay inline in `execute`; don't pre-extract. **The second caller is the trigger** — and the destination is the model, Rails-style, not a new service layer. Chaining three interactions is usually the tell that you already crossed it. Full explanation: [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
+The rule isn't "never put logic in an interaction". A single-caller operation can stay inline in `execute`; don't pre-extract. **The second caller is the trigger**, and the destination is the model, Rails-style, not a new service layer. Chaining three interactions is usually the tell that you already crossed it. Full explanation: [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
 
 ## Common issues
 
-- **Action button missing** — check the policy method (`def my_action?`). Undefined returns `false`.
-- **`ActiveRecord::RecordInvalid` crashes the action** — not rescued automatically. Wrap with `rescue`, return `failed(e.record.errors)`.
-- **Bulk action fails on some records** — that's by design. Bulk policy is checked per-record; if any fails, the whole request is rejected. Either fix authorization or pre-filter the selection.
-- **Confirmation prompt shows when you don't want one** — pass `confirmation: false` on the action.
-- **The action times out on a large selection** — the work is running inside the request. Move it to a background run with `async`, above.
+- **Action button missing**: check the policy method (`def my_action?`). Undefined returns `false`.
+- **`ActiveRecord::RecordInvalid` crashes the action**: not rescued automatically. Wrap with `rescue`, return `failed(e.record.errors)`.
+- **Bulk action fails on some records**: that's by design. Bulk policy is checked per-record; if any fails, the whole request is rejected. Either fix authorization or pre-filter the selection.
+- **Confirmation prompt shows when you don't want one**: pass `confirmation: false` on the action.
+- **The action times out on a large selection**: the work is running inside the request. Move it to a background run with `async`, above.
 
 ## Related
 
-- [Reference › Resource › Actions](/reference/resource/actions) — full action options and bulk patterns
-- [Reference › Behavior › Interactions](/reference/behavior/interactions) — interaction class anatomy
-- [Reference › Behavior › Async Interactions](/reference/behavior/async-interactions) — `async`, progress pages, resuming a crashed run
-- [Reference › Behavior › Policies](/reference/behavior/policies) — `def <action>?` methods
-- [Authorization](./authorization) — policy patterns
+- [Reference › Resource › Actions](/reference/resource/actions): full action options and bulk patterns
+- [Reference › Behavior › Interactions](/reference/behavior/interactions): interaction class anatomy
+- [Reference › Behavior › Async Interactions](/reference/behavior/async-interactions): `async`, progress pages, resuming a crashed run
+- [Reference › Behavior › Policies](/reference/behavior/policies): `def <action>?` methods
+- [Authorization](./authorization): policy patterns