plutonium 0.65.0 → 0.66.0

data/docs/reference/auth/profile.md

@@ -1,12 +1,12 @@
 # Profile
 
-Manages Rodauth account settings as a Plutonium resource — users view/edit personal fields and access Rodauth security features (change password, 2FA, etc.) on one page.
+Manages Rodauth account settings as a Plutonium resource: users view/edit personal fields and access Rodauth security features (change password, 2FA, etc.) on one page.
 
 ## 🚨 Critical
 
-- **Profile association is always `:profile`** regardless of the model class — `current_user.profile`, `build_profile`, `params.require(:profile)` always work.
-- **Profile needs `pu:profile:conn`** — without it, no route, no `profile_url` helper, no user-menu link.
-- **Every user needs a profile row** — add an `after_create` callback (or `find_or_create_by`). Without it, `current_user.profile` is nil and the profile route errors.
+- **Profile association is always `:profile`** regardless of the model class: `current_user.profile`, `build_profile`, `params.require(:profile)` always work. `pu:profile:conn` hardcodes `current_user.profile` in the code it generates.
+- **Profile needs `pu:profile:conn`.** Without it: no route, no `profile_url` override, no user-menu link.
+- **Check an existing profile policy for `update?`.** Policies generated by older versions lack `def update? = true`, which leaves the profile read-only once it exists. See [What `pu:profile:conn` generates](#what-pu-profile-conn-generates).
 
 ## Quick setup
 
@@ -42,7 +42,7 @@ rails g pu:profile:install AccountSettings bio:text --dest=main_app
 
 ## What gets created
 
-By default the model is `{UserModel}Profile` — `UserProfile`, `StaffUserProfile`, etc. — derived from `--user-model`.
+By default the model is `{UserModel}Profile` (`UserProfile`, `StaffUserProfile`, etc.), derived from `--user-model`.
 
 ```
 app/models/[package/]user_profile.rb
@@ -59,10 +59,10 @@ has_one :profile, class_name: "UserProfile", dependent: :destroy
 ```
 
 ::: warning Association name is fixed
-Even when the class is `StaffUserProfile`, the association is `:profile`. Don't rename it — `current_user.profile`, `build_profile`, `params.require(:profile)` all assume this.
+Even when the class is `StaffUserProfile`, the association is `:profile`. Don't rename it: `current_user.profile`, `build_profile`, `params.require(:profile)` all assume this.
 :::
 
-The generated definition injects a custom `ShowPage` that renders the `SecuritySection` component.
+If you reuse a profile model whose user association has a different name (e.g. `has_one :user_profile`), add `has_one :profile, class_name: "UserProfile"` to the user model rather than editing `current_user.profile` out of the generated policy and `profile_url`. Then connect it with `pu:profile:conn UserProfile --dest=<portal>`.
 
 ## The `SecuritySection` component
 
@@ -78,7 +78,7 @@ Dynamically lists Rodauth security links based on which features are enabled on
 | `active_sessions` | Active Sessions |
 | `close_account` | Close Account |
 
-If a feature isn't enabled on the account, its link doesn't render — no configuration needed.
+If a feature isn't enabled on the account, its link doesn't render; no configuration needed.
 
 To customize (e.g. add chrome, reorder), override `ShowPage#render_after_content`:
 
@@ -96,40 +96,77 @@ end
 
 See [UI › Pages](/reference/ui/pages) for page-class customization.
 
-## Required: every user gets a profile
+## Connecting to a portal
+
+`pu:profile:conn` registers the profile as a **singular** resource: `/profile` (no `:id`), and overrides the `profile_url` helper:
+
+```bash
+rails g pu:profile:conn --dest=customer_portal
+```
+
+This is what makes the profile visible. Without it, the model exists but has no route in any portal.
+
+### What `pu:profile:conn` generates
+
+It runs `pu:res:conn` with `--singular --policy --definition`, then injects:
+
+- **Policy:** `relation_scope { skip_default_relation_scope!; relation.where(user: user) }` (a profile belongs to the user, not the portal's entity), `create? = user.profile.nil?`, `update? = true`, `destroy? = false`, and `permitted_attributes_for_create` minus `:user`.
+- **Controller:** `resource_params` merged with `user: current_user`, so the owner is set server-side.
+- **Definition:** a `ShowPage` whose `render_after_content` renders `Plutonium::Profile::SecuritySection`.
+- **Portal controller concern:** `profile_url`, which points at the profile or, when the user has none yet, at the new-profile form.
+
+The explicit `update?` matters: the base policy's `update?` delegates to `create?`, which is false once the profile exists. Policies generated by older versions lack it and leave the profile read-only, so add it if it's missing:
 
 ```ruby
-class User < ApplicationRecord
-  after_create :create_profile!
+def update?
+  true
+end
+```
 
-  private
-  def create_profile! = create_profile
+## Users without a profile row
+
+The generated `profile_url` sends a user with no profile to the new-profile form, and `create?` allows exactly one, so a missing row does not break the route. It does mean the first visit is a "create profile" form, and the `SecuritySection` only appears after it is saved. If you want the show page from the first click, create the row up front:
+
+```ruby
+class User < ApplicationRecord
+  after_create :create_profile
 end
 ```
 
-Without this, `current_user.profile` returns nil and the profile route errors. For existing users at migration time, run a one-off backfill:
+and backfill existing users:
 
 ```bash
-rails runner "User.find_each(&:create_profile)"
+rails runner "User.find_each { |u| u.profile || u.create_profile }"
 ```
 
-## Connecting to a portal
+Skip this when the profile has required fields the user must fill in, or when existing code creates profiles itself (the unique `user_id` index makes a second insert fail).
 
-`pu:profile:conn` registers the profile as a **singular** resource — `/profile` (no `:id`), and exposes the `profile_url` helper:
+## Linking to the profile
 
-```bash
-rails g pu:profile:conn --dest=customer_portal
+Nothing to add. `Plutonium::Auth::Rodauth` defines `profile_url` returning `nil`, and the topbar avatar menu renders a "Profile" entry whenever it returns a URL. `pu:profile:conn` overrides it in the portal's controller concern, which is what makes the link appear. Elsewhere:
+
+```ruby
+link_to("Profile", profile_url) if profile_url
 ```
 
-This is what makes the profile visible. Without it, the model exists but has no route in any portal.
+## Account features on the profile page
 
-## Linking to the profile
+Per-user settings that aren't part of the profile row (API tokens, connected accounts, notification preferences) are discovered from the profile page. Link them from the same `ShowPage` hook that renders `SecuritySection`, instead of adding custom items to the sidebar or overriding the topbar partial:
 
 ```ruby
-link_to("Profile", profile_url) if respond_to?(:profile_url)
+class ShowPage < ShowPage
+  private
+
+  def render_after_content
+    render Plutonium::Profile::SecuritySection.new
+    div(class: "mt-8") do
+      a(href: resource_url_for(ApiToken), class: "font-medium text-[var(--pu-text)] hover:underline") { "API tokens" }
+    end
+  end
+end
 ```
 
-The `respond_to?` guard is defensive — only portals that ran `pu:profile:conn` have the helper.
+A resource like `ApiToken` belongs to the user, not the portal's entity, so connect it with `pu:res:conn ApiToken --dest=<portal> --policy` and give it the same shape the profile has: `skip_default_relation_scope!` plus `relation.where(user: user)` in the policy, and `resource_params` merged with `user: current_user` in the controller.
 
 ## Customizing the definition
 
@@ -173,13 +210,14 @@ rails g pu:profile:conn StaffUserProfile --dest=admin_portal
 
 ## Gotchas
 
-- **`current_user.profile` is nil** — every user needs a profile row. Add `after_create :create_profile!` to the user model.
-- **`profile_url` is undefined** — the profile isn't connected to this portal. Run `pu:profile:conn --dest=<portal>`.
-- **Custom resource name** — pass it as the first positional argument to `pu:profile:install`. The association is still `:profile`.
-- **SecuritySection shows nothing** — none of the relevant Rodauth features are enabled on the account. Enable `change_password`, `otp`, etc. on the Rodauth plugin.
+- **Profile is read-only after creation.** The policy predates the generated `update?`, so `update?` falls back to `create?` (`user.profile.nil?`). Add `def update? = true`.
+- **First visit shows a "create profile" form.** The user has no profile row yet. Not an error; add `after_create :create_profile` plus a backfill if they should land on the show page.
+- **No Profile link in the user menu.** `profile_url` still returns the default `nil` because the profile isn't connected to this portal. Run `pu:profile:conn --dest=<portal>`.
+- **Custom resource name**: pass it as the first positional argument to `pu:profile:install`. The association is still `:profile`.
+- **SecuritySection shows nothing**: none of the relevant Rodauth features are enabled on the account. Enable `change_password`, `otp`, etc. on the Rodauth plugin.
 
 ## Related
 
-- [Accounts](./accounts) — Rodauth feature flags that gate SecuritySection links
-- [Resource › Definition](/reference/resource/definition) — customizing the profile definition
+- [Accounts](./accounts): Rodauth feature flags that gate SecuritySection links
+- [Resource › Definition](/reference/resource/definition): customizing the profile definition
 - [App › Generators › Profile generators](/reference/app/generators#profile-generators)

data/docs/reference/behavior/async-interactions.md

@@ -1,10 +1,10 @@
 # Async Interactions
 
 ::: warning Experimental
-Async interactions are experimental — the DSL and behavior may change in a future release.
+Async interactions are experimental: the DSL and behavior may change in a future release.
 :::
 
-For the task-oriented walkthrough — declaring the action, its policy, and where it appears — start with the [Custom actions guide](/guides/custom-actions). This page is the reference.
+For the task-oriented walkthrough (declaring the action, its policy, and where it appears), start with the [Custom actions guide](/guides/custom-actions). This page is the reference.
 
 `async` turns an interaction from "does the work inline" into "persists a run, enqueues it, and redirects to it."
 
@@ -42,7 +42,7 @@ The flag gates the migration, not just the behaviour: while it is off the runs m
 ```ruby
 class Blogging::ArchivePosts < ResourceInteraction
   presents label: "Archive", icon: Phlex::TablerIcons::Archive
-  attribute :resources          # bulk — perform_on runs once per record
+  attribute :resources          # bulk: perform_on runs once per record
   attribute :reason, :string
 
   async do
@@ -59,7 +59,7 @@ One class. There is no second file, and no name to invent for the run.
 
 ### Why the block declares `perform_on` rather than executing
 
-The block is **not** the body of `#execute`. The work happens later, in a job, in a process with no controller, no request and no `view_context` — it cannot be a closure over anything in the interaction, which is the same reason the row records the initiator and tenant instead of serialising them. So the block declares a `Plutonium::Interaction::Async::Run` subclass with exactly the API a standalone run has, and the validated attributes arrive through `options`.
+The block is **not** the body of `#execute`. The work happens later, in a job, in a process with no controller, no request and no `view_context`, so it cannot be a closure over anything in the interaction, which is the same reason the row records the initiator and tenant instead of serialising them. So the block declares a `Plutonium::Interaction::Async::Run` subclass with exactly the API a standalone run has, and the validated attributes arrive through `options`.
 
 `def` opens a fresh scope, so those method bodies cannot accidentally capture the interaction's locals.
 
@@ -82,13 +82,13 @@ async do
 end
 ```
 
-`options` is a JSON column, so dispatch writes it through `ActiveJob::Arguments`. Primitives are stored verbatim — a String stays a String in the column — and only values needing one get a serializer envelope, so a `Date` arrives as a `Date` and a `BigDecimal` as a `BigDecimal` rather than as strings. Hosts can register their own serializers.
+`options` is a JSON column, so dispatch writes it through `ActiveJob::Arguments`. Primitives are stored verbatim (a String stays a String in the column) and only values needing one get a serializer envelope, so a `Date` arrives as a `Date` and a `BigDecimal` as a `BigDecimal` rather than as strings. Hosts can register their own serializers.
 
 An attribute that can't be carried at all is refused at dispatch, naming the interaction, rather than being written to a row whose work then fails deep in a job.
 
 ### Files
 
-A file can't ride the options column: JSON has no files, and the request's tempfile is deleted on the way out. So an uploaded file is staged to its backend's cache at dispatch and carried as the token — `options["import_file"]` is that token, a String.
+A file can't ride the options column: JSON has no files, and the request's tempfile is deleted on the way out. So an uploaded file is staged to its backend's cache at dispatch and carried as the token: `options["import_file"]` is that token, a String.
 
 Use `attachment` to read it back:
 
@@ -110,16 +110,16 @@ end
 
 #### Per-field backend and uploader
 
-`backend:` and `uploader:` are read off the attribute's own `input` declaration — the same options, in the same place, a wizard step reads them from:
+`backend:` and `uploader:` are read off the attribute's own `input` declaration, the same options in the same place a wizard step reads them from:
 
 ```ruby
 attribute :import_file
 input :import_file, as: :uppy, uploader: Catalog::ImportUploader
 ```
 
-The uploader's `Attacher.validate` rules run when the interaction validates, so a file that breaks them **fails the form** — the submitter sees a field error and nothing is dispatched. Without that the interaction would validate clean, dispatch, and the author's `validate_max_size` would surface as a run failure on a page the submitter has already left. A no-op for ActiveStorage fields and for uploaders declaring no rules.
+The uploader's `Attacher.validate` rules run when the interaction validates, so a file that breaks them **fails the form**: the submitter sees a field error and nothing is dispatched. Without that the interaction would validate clean, dispatch, and the author's `validate_max_size` would surface as a run failure on a page the submitter has already left. A no-op for ActiveStorage fields and for uploaders declaring no rules.
 
-Validating means staging first, since Shrine validates an assigned cached file — so an upload that fails validation has still been written to the cache, and is reaped by the backend's own unattached-cache cleanup. Wizards make the same trade on every step submit.
+Validating means staging first, since Shrine validates an assigned cached file, so an upload that fails validation has still been written to the cache, and is reaped by the backend's own unattached-cache cleanup. Wizards make the same trade on every step submit.
 
 Where no `backend:` is declared: `config.async_interactions.attachment_backend`, then `config.attachment_backend`, then auto-detection (active_shrine loaded → Shrine, else ActiveStorage). Same layering wizards use.
 
@@ -139,7 +139,7 @@ class Blogging::ArchivePosts < ResourceInteraction
 end
 ```
 
-Passing both a class and a block raises `ArgumentError` — the block *is* a run class, so there is nothing to combine.
+Passing both a class and a block raises `ArgumentError`: the block *is* a run class, so there is nothing to combine.
 
 `async` must be the only thing that defines `#execute` on the class. Declaring it on a class that already has its own `execute` raises `ArgumentError` at load time (an interaction either executes inline or runs async, never both).
 
@@ -149,7 +149,7 @@ Nothing is passed in explicitly. Everything the run needs is already reachable f
 
 - **Targets.** `attribute :resource` / `attribute :resources`, already narrowed by the controller's policy scope, stored as ids (`target_ids`) and re-resolved at perform time, never serialized as records.
 - **Initiator + tenant.** `current_user` / `current_scoped_entity`, two of the things every Plutonium policy authorizes on.
-- **Nested-route parent.** `current_parent` and `current_nested_association` — `/orgs/1/posts/5/comments` records `(Post#5, :comments)`. Both halves or neither, since `Policy#default_relation_scope` raises on one alone. This is the third policy input, and it is not optional detail: that method picks **one** branch, parent *or* entity, so a nested run without its parent re-derives targets under the tenant where dispatch used the parent — wider than the scope the initiator was shown. It also leaves a host predicate reading `parent` looking at `nil`, which (being declared `optional: true`) answers false rather than raising, refusing every target for a reason that names the predicate instead of the missing context.
+- **Nested-route parent.** `current_parent` and `current_nested_association`: `/orgs/1/posts/5/comments` records `(Post#5, :comments)`. Both halves or neither, since `Policy#default_relation_scope` raises on one alone. This is the third policy input, and it is not optional detail: that method picks **one** branch, parent *or* entity, so a nested run without its parent re-derives targets under the tenant where dispatch used the parent, wider than the scope the initiator was shown. It also leaves a host predicate reading `parent` looking at `nil`, which (being declared `optional: true`) answers false rather than raising, refusing every target for a reason that names the predicate instead of the missing context.
 - **The policy actually resolved.** `policy_class_name`, not an inferred `"#{Model}Policy"` (a namespaced portal or an STI fallback would make that guess wrong), plus `policy_action`, the predicate dispatch checked (e.g. `"archive?"`).
 - **`authorization_namespace`.** The portal's module name, so perform-time policy lookup finds the same narrowed policy dispatch did.
 
@@ -159,10 +159,10 @@ An opaque (untargeted) run records none of the target/policy columns: there's no
 
 The job has no controller, no request, no `current_user`. `Async::Context` rebuilds the authorization triple from the row and re-checks it from scratch. It does not trust anything the dispatching request already decided:
 
-- The **scope** check re-runs `Post.associated_with(tenant)` style filtering — or, for a nested dispatch, the parent's association. A target that left the tenant or the parent, or was deleted, between dispatch and perform is reported `missing`/`unauthorized`, never silently skipped.
+- The **scope** check re-runs `Post.associated_with(tenant)` style filtering (or, for a nested dispatch, the parent's association). A target that left the tenant or the parent, or was deleted, between dispatch and perform is reported `missing`/`unauthorized`, never silently skipped.
 - The **predicate** check re-asks the policy the same question dispatch asked (`policy_action`), per target, immediately before `perform_on`, not once up front. An initiator whose permission was revoked mid-run stops applying to the remaining targets.
 - A **policy mismatch** (the class renamed/re-parented/re-namespaced since dispatch) refuses to run at all, rather than silently authorizing under a different policy than the initiator was ever subject to.
-- A **deleted subject** — initiator, tenant or parent — refuses the run. In each case the association nils out, and nil reads as "there was never one": no tenant, or not a nested dispatch. Both of those drop a filter rather than narrowing, so the `*_type` column is what tells "carries none" apart from "carries one that is gone".
+- A **deleted subject** (initiator, tenant or parent) refuses the run. In each case the association nils out, and nil reads as "there was never one": no tenant, or not a nested dispatch. Both of those drop a filter rather than narrowing, so the `*_type` column is what tells "carries none" apart from "carries one that is gone".
 
 This is deliberate and asymmetric: a resolution failure always fails **closed** (refuse / report missing), never open (never "assume permitted").
 
@@ -201,12 +201,12 @@ end
 
 `controller_for` is required: the controller's name doesn't match `Run`'s real, namespaced class, so inference can't find it on its own. No policy/definition files are generated: `Plutonium::Interaction::Async::RunPolicy`/`Async::RunDefinition` already resolve automatically (Rails matches `Plutonium::Interaction::Async::RunDefinition` by the exact class name, and ActionPolicy's own lookup finds `AsyncRunPolicy` the same way).
 
-If Solid Queue is in the bundle, this also schedules `Async::ReapJob` in `config/recurring.yml` (`--schedule` to override the default `every 15 minutes`) — see [Stalled runs and ReapJob](#stalled-runs-and-reapjob). Idempotent, so running the generator against a second portal doesn't duplicate the entry.
+If Solid Queue is in the bundle, this also schedules `Async::ReapJob` in `config/recurring.yml` (`--schedule` to override the default `every 15 minutes`), see [Stalled runs and ReapJob](#stalled-runs-and-reapjob). Idempotent, so running the generator against a second portal doesn't duplicate the entry.
 
 A registered run resource gets, for free:
 
 - **A progress page.** The show page IS the progress page. It self-refreshes via polling (not ActionCable) while `state` is `pending`/`running`, and stops carrying the poll once the run settles, so a finished run is a static page, not a background request per viewer.
-- **A self-refreshing index.** The runs index polls on the same terms as the progress page: one frame around the whole collection, armed only while some run is still working, disarmed the moment none is. One request per interval regardless of page size, and it re-fetches the URL you are on, so filters, sort and page survive the refresh. A frame per row is not an option — `turbo-frame` is not in the content model of `tr`, so the parser hoists it out of the table before Turbo sees it.
+- **A self-refreshing index.** The runs index polls on the same terms as the progress page: one frame around the whole collection, armed only while some run is still working, disarmed the moment none is. One request per interval regardless of page size, and it re-fetches the URL you are on, so filters, sort and page survive the refresh. A frame per row is not an option: `turbo-frame` is not in the content model of `tr`, so the parser hoists it out of the table before Turbo sees it.
 - **A running banner.** Any OTHER resource's index page lists runs currently in progress against it, above the collection, so a user who dispatched a bulk action and navigated away can find it again. Scoped through the same `authorized_resource_scope` every cross-resource read goes through, so a run in another tenant can never surface. If a resource_class is registered in a portal that never registered `Run`, the banner is skipped there instead of raising while trying to build a link to a route that doesn't exist.
 - **Tenant scoping.** A run's `associated_with` scope filters on the tenant it was dispatched in (recorded on the row), not on walking the object graph, since the two polymorphic tenant columns make the generic scope unusable.
 - **A humanized target label.** `run.target_label` reads the target class through `model_name.human` ("Post", not "Blogging::Post"), falling back to the raw string if that class has since been renamed or removed.
@@ -235,7 +235,7 @@ production:
     schedule: every 15 minutes
 ```
 
-Without Solid Queue — or for another scheduler like `whenever` — add it yourself:
+Without Solid Queue, or for another scheduler like `whenever`, add it yourself:
 
 ```ruby
 # whenever gem
@@ -249,13 +249,13 @@ A 15 to 30 minute cadence is reasonable against the default 1-hour `stall_after`
 ::: warning This is a time heuristic, not a lease
 Resuming is based on elapsed time, not a true distributed lock. A run that is merely slow (not dead) and happens to cross `stall_after` gets resumed too.
 
-What bounds that is `lock_version`. Both the reaper's resume and the executor's claim bump it, so the worker that is still alive holds a version the row no longer has: its very next write raises `ActiveRecord::StaleObjectError`, and the executor treats that as "no longer mine" — it abandons the pass without marking the run failed and without overwriting the new worker's progress. Two things it deliberately does not do: it cannot interrupt a `perform_on` already in flight, so one target may be applied twice (once by each side), and it cannot roll back what the superseded worker already committed. Set `stall_after` well above this app's slowest legitimate run — the fence bounds the damage of a bad value, it does not make one free.
+What bounds that is `lock_version`. Both the reaper's resume and the executor's claim bump it, so the worker that is still alive holds a version the row no longer has: its very next write raises `ActiveRecord::StaleObjectError`, and the executor treats that as "no longer mine": it abandons the pass without marking the run failed and without overwriting the new worker's progress. Two things it deliberately does not do: it cannot interrupt a `perform_on` already in flight, so one target may be applied twice (once by each side), and it cannot roll back what the superseded worker already committed. Set `stall_after` well above this app's slowest legitimate run: the fence bounds the damage of a bad value, it does not make one free.
 
 ### Long work must say it is alive
 
 `stall_after` is a **silence** threshold, not a runtime limit. Every write the executor makes refreshes the clock, so a targeted run with quick targets heartbeats once per target for free. Two shapes get nothing, and both are exactly the "long-running task" case:
 
-- **Opaque work.** Between the claim and `finish!` the executor writes nothing, because there is nothing to count. A `perform` that outlives `stall_after` is reaped mid-flight and — having no `handled_target_ids` to resume from — re-runs **from scratch**.
+- **Opaque work.** Between the claim and `finish!` the executor writes nothing, because there is nothing to count. A `perform` that outlives `stall_after` is reaped mid-flight and, having no `handled_target_ids` to resume from, re-runs **from scratch**.
 - **A single `perform_on`** that outlives `stall_after` on its own.
 
 Call `heartbeat!` from inside such work:
@@ -265,7 +265,7 @@ class Billing::ReissueInvoicesRun < Plutonium::Interaction::Async::Run
   def perform
     invoices.each_slice(500) do |slice|
       reissue(slice)
-      heartbeat!        # "still working" — resets the stall clock
+      heartbeat!        # "still working", resets the stall clock
     end
   end
 end
@@ -273,11 +273,11 @@ end
 
 This is deliberately not automatic. A background thread would have to guess a cadence, and would go on reporting a wedged worker as healthy; only the work itself knows it is making progress.
 
-`heartbeat!` also **answers**. The write is conditional on this worker still holding the row's `lock_version`, so one that was superseded inside a long `perform` raises `ActiveRecord::StaleObjectError` at its next beat and abandons the pass — for opaque work that is the only place it can find out before `finish!`. Under `:transactional` the beat is inside the batch transaction like everything else, so it stays invisible to the reaper until the batch commits.
+`heartbeat!` also **answers**. The write is conditional on this worker still holding the row's `lock_version`, so one that was superseded inside a long `perform` raises `ActiveRecord::StaleObjectError` at its next beat and abandons the pass; for opaque work that is the only place it can find out before `finish!`. Under `:transactional` the beat is inside the batch transaction like everything else, so it stays invisible to the reaper until the batch commits.
 
 ### Queue-level concurrency
 
-On a queue that provides ActiveJob concurrency controls — Solid Queue does, whenever it is in the bundle — the run job also declares a per-run semaphore, and the reaper a global one:
+On a queue that provides ActiveJob concurrency controls (Solid Queue does, whenever it is in the bundle), the run job also declares a per-run semaphore, and the reaper a global one:
 
 | Job | Key | Limit | Duration |
 |---|---|---|---|
@@ -286,10 +286,10 @@ On a queue that provides ActiveJob concurrency controls — Solid Queue does, wh
 
 This is declared only when the method exists; Plutonium depends on no queue backend, and nothing above requires one.
 
-It is not a second copy of the claim. `claim!` can only *refuse* a duplicate delivery, and only once a worker is already running it — by which point a reaper's resume has re-entered `perform_on` for one target. The semaphore removes the race a step earlier: the second delivery waits instead of racing, so on a queue that supports it the double-applied target does not happen at all. Keying the run job on `stall_after` matters here — Solid Queue's 3-minute default would expire the semaphore mid-batch on any run big enough to be worth dispatching.
+It is not a second copy of the claim. `claim!` can only *refuse* a duplicate delivery, and only once a worker is already running it, by which point a reaper's resume has re-entered `perform_on` for one target. The semaphore removes the race a step earlier: the second delivery waits instead of racing, so on a queue that supports it the double-applied target does not happen at all. Keying the run job on `stall_after` matters here: Solid Queue's 3-minute default would expire the semaphore mid-batch on any run big enough to be worth dispatching.
 :::
 
 ## Related
 
-- [Interactions](/reference/behavior/interactions) — `async` is declared inside `Plutonium::Resource::Interaction`; everything else about inputs, validation and outcomes is unchanged.
-- [Policies](/reference/behavior/policies) — the policy dispatch checks and the job re-checks are the same predicate.
+- [Interactions](/reference/behavior/interactions): `async` is declared inside `Plutonium::Resource::Interaction`; everything else about inputs, validation and outcomes is unchanged.
+- [Policies](/reference/behavior/policies): the policy dispatch checks and the job re-checks are the same predicate.

data/docs/reference/behavior/controllers.md

@@ -1,25 +1,25 @@
 # Controller
 
-Plutonium controllers ship full CRUD out of the box; nearly all customization belongs elsewhere. The controller stays thin — when in doubt, push the change to the definition (UI) or the policy (auth).
+Plutonium controllers ship full CRUD out of the box; nearly all customization belongs elsewhere. The controller stays thin; when in doubt, push the change to the definition (UI) or the policy (auth).
 
 ## 🚨 Critical
 
 - **Don't override CRUD actions.** Use hooks (`resource_params`, `redirect_url_after_submit`, presentation hooks). Overriding `create` / `update` usually breaks authorization, params filtering, or both.
-- **Named custom routes only.** Always pass `as:` — without it, `resource_url_for` can't build URLs (critical for nested resources).
-- **Authorization is verified after every action** — if you write a custom action, you MUST call `authorize_current!` yourself or use `skip_verify_authorize_current` / `skip_verify_authorize_current!`.
+- **Named custom routes only.** Always pass `as:`. Without it, `resource_url_for` can't build URLs (critical for nested resources).
+- **Authorization is verified after every action.** If you write a custom action, you MUST call `authorize_current!` yourself or use `skip_verify_authorize_current` / `skip_verify_authorize_current!`.
 - **Cross-resource queries: use `authorized_resource_scope(OtherModel)`, not raw `where`.** Otherwise you bypass that resource's tenancy and visibility rules.
 
 ## Base classes
 
 ```ruby
-# app/controllers/resource_controller.rb — installed once
+# app/controllers/resource_controller.rb (installed once)
 class ResourceController < ApplicationController
   include Plutonium::Resource::Controller
 end
 
-# app/controllers/posts_controller.rb — per resource, generated
+# app/controllers/posts_controller.rb (per resource, generated)
 class PostsController < ::ResourceController
-  # Empty — all CRUD inherited
+  # Empty: all CRUD inherited
 end
 ```
 
@@ -59,10 +59,10 @@ Plus interactive-action routes for every action declared in the definition (`/po
 |---|---|
 | Field rendering (inputs, displays, columns) | [Definition](/reference/resource/definition) |
 | Search, filters, scopes, sorting | [Query](/reference/resource/query) |
-| Custom operations (publish, archive, import) — the *button* | [Interaction](./interactions) + action on definition |
-| The operation itself, once a job/API/task also needs it | The **model** — see [Interactions › What an interaction is for](./interactions#what-an-interaction-is-for) |
+| Custom operations (publish, archive, import): the *button* | [Interaction](./interactions) + action on definition |
+| The operation itself, once a job/API/task also needs it | The **model**, see [Interactions › What an interaction is for](./interactions#what-an-interaction-is-for) |
 | Authorization rules | [Policy](./policies) |
-| Form / show / page chrome | Definition (custom page classes — see [UI › Pages](/reference/ui/pages)) |
+| Form / show / page chrome | Definition (custom page classes, see [UI › Pages](/reference/ui/pages)) |
 | **Custom redirect logic** | **[Controller hook](#redirect-hooks)** |
 | **Param munging** | **[Controller hook](#parameter-hook)** |
 | **Custom index query shape** | **[Controller hook](#index-query-hook)** |
@@ -128,7 +128,7 @@ def present_scoped_entity?  = true
 def submit_scoped_entity?   = true
 ```
 
-Conditional pattern — show parent only when accessed standalone:
+Conditional pattern: show parent only when accessed standalone:
 
 ```ruby
 def present_parent?
@@ -156,9 +156,9 @@ end
 
 ## Custom actions
 
-Prefer **interactive actions** (definition + interaction — see [Resource › Actions](/reference/resource/actions)) for anything a user triggers from a page: you get the button, the policy check, the form, and the flash for free. The only reasons to hand-write a controller action: unusual response shapes, external service callbacks, etc.
+Prefer **interactive actions** (definition + interaction, see [Resource › Actions](/reference/resource/actions)) for anything a user triggers from a page: you get the button, the policy check, the form, and the flash for free. The only reasons to hand-write a controller action: unusual response shapes, external service callbacks, etc.
 
-Either way the *operation* should be a named method on the model — that's what keeps it reachable from a job or an API. The controller and the interaction are two different front doors to the same `post.publish!`.
+Either way the *operation* should be a named method on the model; that's what keeps it reachable from a job or an API. The controller and the interaction are two different front doors to the same `post.publish!`.
 
 ```ruby
 class PostsController < ::ResourceController
@@ -179,7 +179,7 @@ end
 ```
 
 ::: warning Always name custom routes
-Without `as:`, `resource_url_for` can't build the URL — particularly critical for nested resources.
+Without `as:`, `resource_url_for` can't build the URL, which is particularly critical for nested resources.
 :::
 
 ## Key methods
@@ -206,10 +206,10 @@ permitted_attributes                        # Allowed attributes for the current
 current_authorized_scope                    # Scoped collection the user can access
 ```
 
-**Other resources** — cross-resource auth. Use these, NOT raw `where` / `find`:
+**Other resources**: cross-resource auth. Use these, NOT raw `where` / `find`:
 
 ```ruby
-authorize! other_record, to: :show?         # ActionPolicy — raises if denied
+authorize! other_record, to: :show?         # ActionPolicy: raises if denied
 allowed_to?(:show?, other_record)           # Boolean check
 policy_for(OtherModel)                      # Policy instance for class or record
 policy_for(other_record).show?
@@ -219,7 +219,7 @@ authorized_resource_scope(OtherModel, relation: OtherModel.published)  # On a re
 authorized_resource_scope(OtherModel, type: :create)             # Different action
 ```
 
-`authorized_resource_scope` applies the *other* resource's `relation_scope` AND the current policy context (entity scope, etc.). **Always prefer it over `OtherModel.all` / raw `where`** in cross-resource controller code — otherwise you bypass that resource's tenancy and visibility rules.
+`authorized_resource_scope` applies the *other* resource's `relation_scope` AND the current policy context (entity scope, etc.). **Always prefer it over `OtherModel.all` / raw `where`** in cross-resource controller code; otherwise you bypass that resource's tenancy and visibility rules.
 
 ### Definition access
 
@@ -268,7 +268,7 @@ current_nested_association  # :posts
 parent_input_param          # :user
 ```
 
-The nesting is declared by the route, not inferred from the URL: each nested route carries the key of its own registration, and `current_parent_class` / `current_nested_association` read it back. (There is no `parent_route_param` — the id parameter is derived from the parent's own route, and a singular parent contributes none at all.)
+The nesting is declared by the route, not inferred from the URL: each nested route carries the key of its own registration, and `current_parent_class` / `current_nested_association` read it back. (There is no `parent_route_param`; the id parameter is derived from the parent's own route, and a singular parent contributes none at all.)
 
 Parent fields are excluded from forms/displays by default. Toggle with the [presentation hooks](#presentation-hooks).
 
@@ -295,7 +295,7 @@ Plutonium auto-detects which `belongs_to` association points to the scoped class
 # Portal config
 scope_to_entity Competition::Team, param_key: :team
 
-# Model — association name differs from param_key, but Plutonium finds by class
+# Model: association name differs from param_key, but Plutonium finds by class
 class Match < ApplicationRecord
   belongs_to :competition_team
 end
@@ -327,14 +327,14 @@ Full mechanics in [Tenancy › Entity scoping](/reference/tenancy/entity-scoping
 After-action callbacks ensure authorization happened:
 
 ```ruby
-verify_authorize_current         # all actions — `authorize_current!` must have been called
-verify_current_authorized_scope  # all except :new and :create — scope must have been loaded
+verify_authorize_current         # all actions: `authorize_current!` must have been called
+verify_current_authorized_scope  # all except :new and :create: scope must have been loaded
 ```
 
 Skip only when handling auth manually. Two forms:
 
 ```ruby
-# Class-level — across multiple actions
+# Class-level: across multiple actions
 class PostsController < ::ResourceController
   skip_verify_authorize_current only: [:preview]
   skip_verify_current_authorized_scope only: [:preview]
@@ -344,7 +344,7 @@ class PostsController < ::ResourceController
   end
 end
 
-# Per-action — bang methods, inside the action body
+# Per-action: bang methods, inside the action body
 def preview
   skip_verify_authorize_current!
   skip_verify_current_authorized_scope!
@@ -352,7 +352,7 @@ def preview
 end
 ```
 
-Prefer the per-action bang form when only one action skips — keeps the exception co-located with the code that needs it.
+Prefer the per-action bang form when only one action skips, which keeps the exception co-located with the code that needs it.
 
 ## Response formats
 
@@ -401,8 +401,8 @@ See [App › Portals](/reference/app/portals) for the full portal controller sto
 
 ## Related
 
-- [Policies](./policies) — authorization called from controllers
-- [Interactions](./interactions) — business logic for custom actions
-- [Resource › Definition](/reference/resource/definition) — UI config (where most "controller-like" tweaks belong)
-- [Resource › Actions](/reference/resource/actions) — registering interactive actions
-- [Tenancy › Nested resources](/reference/tenancy/nested-resources) — parent/child routing
+- [Policies](./policies): authorization called from controllers
+- [Interactions](./interactions): business logic for custom actions
+- [Resource › Definition](/reference/resource/definition): UI config (where most "controller-like" tweaks belong)
+- [Resource › Actions](/reference/resource/actions): registering interactive actions
+- [Tenancy › Nested resources](/reference/tenancy/nested-resources): parent/child routing

data/docs/reference/behavior/index.md

@@ -2,15 +2,15 @@
 
 The behavior layer is intentionally thin:
 
-- **[Controllers](./controllers) route** — handle requests, redirect after submit, transform params.
-- **[Policies](./policies) authorize** — decide who can do what, which fields they can see, which records they can access.
-- **[Interactions](./interactions) present** — declare the inputs for a custom operation (publish, archive, import, send invitation), render as a button and a form, and hand back an outcome.
-- **[Async Interactions](./async-interactions)** — `async` declares a persisted, resumable run instead of executing inline, for bulk operations and anything else too slow to hold a request open.
+- **[Controllers](./controllers) route**: handle requests, redirect after submit, transform params.
+- **[Policies](./policies) authorize**: decide who can do what, which fields they can see, which records they can access.
+- **[Interactions](./interactions) present**: declare the inputs for a custom operation (publish, archive, import, send invitation), render as a button and a form, and hand back an outcome.
+- **[Async Interactions](./async-interactions)**: `async` declares a persisted, resumable run instead of executing inline, for bulk operations and anything else too slow to hold a request open.
 
 Registering an action and rendering it lives in [Resource › Definition](/reference/resource/definition) and [Resource › Actions](/reference/resource/actions). This section covers **writing** the controller hook, policy method, or interaction class behind it.
 
 ::: tip And the operation itself lives on the model
-An interaction is a presentation object — it can only be constructed with a `view_context`. Logic may *start* in `execute`, but the second caller (a job, an API controller, a rake task, the console) is the trigger to move it onto the record, Rails-style. See [Interactions › What an interaction is for](./interactions#what-an-interaction-is-for).
+An interaction is a presentation object, so it can only be constructed with a `view_context`. Logic may *start* in `execute`, but the second caller (a job, an API controller, a rake task, the console) is the trigger to move it onto the record, Rails-style. See [Interactions › What an interaction is for](./interactions#what-an-interaction-is-for).
 :::
 
 For multi-tenant `relation_scope` and entity scoping, see [Tenancy › Entity scoping](/reference/tenancy/entity-scoping).