plutonium 0.62.2 → 0.64.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75154d0671bfe1934ecdb6d045b6a0e119be04f3d9faa37740cf8c50eb113dab
-  data.tar.gz: e2dd3963d7a7862918a0ff3f3b482dec18115fec0c54ab5b186178a13006ae05
+  metadata.gz: 6abf981b5e375a2c576de8bfe5fe6448b115753356b6c91f1c3b0ae946e66935
+  data.tar.gz: b519f55b96e20f592baab81b34a633de562dcd8060dbe2bf65cbff7342ae76dd
 SHA512:
-  metadata.gz: 9cbfdd419b58dbef8e5f70c91de197065edfdbc108dd93062f407ebff187e61be334c8ff63e96b05a5bee5e4333b51681dfb8403ea294d41c232d4b1885eae38
-  data.tar.gz: 1114c97d24fd9c5341779419b545bb376503d2cc7e6b8b403b35ae8260c63f5c8db0483894c288ef8960ce72420952246e1e15f42f2bdb33e3e4da114130eaa8
+  metadata.gz: cbf194184d5d16439031b3802f5fc7b05b7f22b24a2075cac2d03a5e6869160f5332ea6cc4d83d3a580169db7405266435e5f9b7f4f1b42befd334a93a470f53
+  data.tar.gz: ec740ece535648156d103872cb0362347b6b2f2823d425aa0b94134f336a32355c807f767d05a673f173670fb1efd572c42240542b48b44f0ab5dc8b23ed63cc

data/.claude/skills/plutonium/SKILL.md

@@ -20,6 +20,48 @@ Entry point for all Plutonium work. Does three things:
 - **Unattended execution:** always pass `--dest=`, `--force` (when re-running meta-generators), `--auth=`, `--skip-bundle`, `--quiet` so generators don't block on prompts. See [Unattended execution](#unattended-execution).
 - **Inspect before you act.** Every targeted skill now opens with a CHECK gate — read the relevant files yourself before scaffolding or editing. Don't ask the user to describe their app when you can read it.
 
+## The mental model (read once — it decides what you should write)
+
+Plutonium applies Rails' bargain — follow the convention and the framework carries you; reach for an escape hatch when you need one — to the layer **above CRUD**: auth, authorization, multi-tenancy, admin UI, business operations. Four consequences change what you should actually type.
+
+### 1. Everything is derived from something you already declared
+
+Not "defaults someone picked for you" — **computed from existing declarations**:
+
+| Derived | From |
+|---|---|
+| Field types, required markers, select choices | model columns, associations, attachments, enums, **and validations** (`presence: true` → required; `inclusion:` → select choices) |
+| A collection's preloads (index, kanban, export) | the policy's permitted field set — there is **no `includes` list to write or maintain** |
+| Tenant scope | your associations — direct `belongs_to`, then `has_one`/`has_one :through`, then reverse `has_many` |
+| Action type (record / bulk / resource) | whether the interaction declares `:resource`, `:resources`, or neither |
+| An association input's typeahead | the **target resource's own `search` block** |
+| CRUD, nested and action routes | one `register_resource` line |
+
+⇒ **Declare only what differs.** A `field :title` matching the detected type is dead code — and one more line to fall out of step when the column changes. This is the single most common way generated-looking code goes wrong.
+
+### 2. Definition and policy answer different questions
+
+- **Definition** = *how* a field renders.
+- **Policy** = *whether it appears at all*.
+
+"Only admins see this field" is `permitted_attributes_for_*`. Never a definition declaration, and never a `condition:` (that only hides UI — the route stays live).
+
+### 3. Overrides are plain Ruby inheritance
+
+`AdminPortal::PostDefinition < ::PostDefinition`, and the same for policies and controllers. App-level default, portal-level subclass. No registry of overrides, no precedence DSL, no merge semantics — so "why does this field show here but not there" is always readable as a class hierarchy.
+
+### 4. Climb the escape-hatch ladder only as far as the problem requires
+
+1. **Change an option** — `input :content, as: :markdown`
+2. **Render inline** — `display :priority, as: :phlexi_render, with: ->(value, attrs) do … end`
+3. **Write a component** — a *field* component (subclasses the Phlexi base) plugs into `as:`; anything with its own constructor goes through a block (`display :card do |field| … end`)
+4. **Implement a hook** — controller hooks instead of reopening `create`/`update`; page `render_before_*` / `render_after_*` instead of `view_template`
+5. **Replace the page** — `view_template` on the nested class, or an ERB view at the controller path (ERB wins when both exist)
+
+Reaching for rung 5 on a rung-1 problem is how you end up owning breadcrumbs, the header and turbo frame wiring you never meant to touch.
+
+**Underneath all of it, it stays Rails.** Models are plain ActiveRecord, controllers inherit from Rails controllers, views resolve through Rails view paths. A Plutonium resource and a hand-written controller coexist in one app.
+
 ## ✅ Orient before you route (CHECK — read the app, don't assume)
 
 A one-line request rarely says whether this is a new app, a half-built one, or a multi-tenant one — and those change which path you take. Spend 30 seconds reading the app **before** loading a bundle or running anything:
@@ -40,6 +82,7 @@ This is the global "look before you leap"; each targeted skill carries its own A
 | **[[plutonium-app]]** | Installation, packages (feature + portal), portal engines, mounting, `register_resource` (including singular and custom routes), `pu:res:conn` |
 | **[[plutonium-resource]]** | The resource itself — `pu:res:scaffold`, field types, model layer (`Plutonium::Resource::Record`, `has_cents`, SGID, routing), definition layer (fields/inputs/displays/columns, search/filters/scopes/sorting, custom actions, bulk actions, index views, page customization) |
 | **[[plutonium-behavior]]** | Controllers (hooks, key methods, presentation), policies (action methods, `permitted_attributes_for_*`, `permitted_associations`), interactions (structure, outcomes, chaining, URL generation) |
+| **[[plutonium-async-interactions]]** | Async interactions — `async`, the Run STI model, failure policies (`halt`/`continue`/`transactional`), authorization re-derivation at perform time, registering AsyncRun as a resource (progress page + running banner), scheduling `ReapJob` |
 | **[[plutonium-ui]]** | Page classes, forms, displays, tables, custom Phlex components, layouts, modals & tabs, Tailwind config, Stimulus, design tokens, `.pu-*` classes, Phlexi themes |
 | **[[plutonium-kanban]]** | `kanban do…end` DSL in a Definition — columns, `card_fields`, `position_on`, `realtime`, column actions, `kanban_move?` policy, quick-add, static vs dynamic boards |
 | **[[plutonium-auth]]** | Rodauth install, account types (basic / admin / SaaS), profile resource, security section |
@@ -74,6 +117,7 @@ Add when relevant:
 | Override a controller action, hook, redirect, or `resource_params` | **[[plutonium-behavior]]** |
 | Write `relation_scope`, `permitted_attributes_for_*`, `permitted_associations`, action methods, or any policy override | **[[plutonium-behavior]]** (+ **[[plutonium-tenancy]]** if scoping) |
 | Write an interaction class for business logic | **[[plutonium-behavior]]** |
+| Make a bulk/long-running interaction async (`async`), or schedule the stalled-run reaper | **[[plutonium-async-interactions]]** |
 | Scope a model to a tenant, write `associated_with`, set portal entity strategy | **[[plutonium-tenancy]]** |
 | Configure parent/child nested routes, custom parent resolution | **[[plutonium-tenancy]]** |
 | Set up user invitations or entity membership | **[[plutonium-tenancy]]** |

data/.claude/skills/plutonium-app/SKILL.md

@@ -402,13 +402,13 @@ end
 ## Per-portal overrides
 
 ```ruby
-# Definition
+# Definition — how fields render (NOT whether they appear)
 class AdminPortal::PostDefinition < ::PostDefinition
-  input :internal_notes, as: :text     # admins see this; customers don't
   scope :pending_review
+  input :internal_notes, hint: "Not shown to the author"
 end
 
-# Policy
+# Policy — whether a field appears at all
 class AdminPortal::PostPolicy < ::PostPolicy
   include AdminPortal::ResourcePolicy
   def destroy? = true

data/.claude/skills/plutonium-async-interactions/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: plutonium-async-interactions
+description: Use BEFORE building any bulk operation or long-running interaction. Covers async, the Run STI model, failure policies (halt/continue/transactional), authorization re-derivation at perform time, registering AsyncRun as a resource (progress page + running banner), and scheduling ReapJob for stalled runs. The single source for "how do I make an interaction async".
+---
+
+# Plutonium Async Interactions
+
+`async` turns an interaction from "does the work inline" into "persists a run, enqueues it, and redirects to it." Reach for it once the work is too slow to hold a request open — thousands of records, report generation, a third-party call.
+
+For everything about the interaction itself (inputs, validation, outcomes, `execute`), load [[plutonium-behavior]] first. `async` only replaces what `execute` does, not the rest of the interaction's shape.
+
+## 🚨 Critical (read first)
+
+- **Experimental.** The DSL and behavior may change in a future release — same status as [[plutonium-wizard]] and [[plutonium-kanban]]. Fine to build on; expect to revisit it on upgrade.
+- **Enable the subsystem first.** `rails g pu:async_interactions:install --dest=<portal>` flips `config.async_interactions.enabled = true`, schedules `ReapJob`, and connects the run resource to that portal; then `rails db:migrate`. Pass `--skip-portal` to enable it before any portal exists. Off by default, so no `plutonium_async_runs` table otherwise.
+- **`async` fully replaces `#execute`.** An interaction either executes inline or runs async — declaring both raises `ArgumentError` at load.
+- **Define `perform_on(record)` for targeted work, `perform` for opaque work.** A run class implementing neither fails loudly (naming the class) the first time it's performed, rather than a bare `NoMethodError`.
+- **A nested dispatch records its parent.** `parent_type`/`parent_id`/`parent_association` join initiator and tenant on the row, because `Policy#default_relation_scope` picks parent scoping **or** entity scoping, not both — a nested run missing its parent re-derives targets under the wider tenant scope, and any predicate reading `parent` silently answers false. A parent deleted mid-run refuses the run, exactly like a deleted tenant.
+- **Permissions are re-derived at perform time, never replayed from dispatch.** The job rebuilds `(initiator, tenant)` from the row and re-checks the policy scope and predicate per target, immediately before each `perform_on`. A permission revoked mid-run stops applying to what's left. Both failure directions (scope, predicate) fail closed (refuse/report), never open.
+- **Register `Run` as a resource per portal.** Its show page IS the progress page, and other resources' index pages get a "runs in progress" banner for free. Nothing renders without registration.
+- **Read `outcome`, never bare `state`, when displaying a run's result.** A `:continue` run that under-applied still has `state == "completed"`; only `outcome` says `"completed_with_errors"`.
+- **Long work must call `heartbeat!`.** `stall_after` measures SILENCE, and the executor only writes per target — so opaque `perform` writes nothing at all between claim and finish. An opaque run longer than `stall_after` is reaped and, having no `handled_target_ids`, re-run from scratch. Call `heartbeat!` inside the loop. It also raises `StaleObjectError` if another worker took the run over, which for opaque work is the only way to find out.
+- **A crashed/stalled run does not auto-heal.** Nothing revisits a `"running"` row on its own. `pu:async_interactions:install` schedules `Plutonium::Interaction::Async::ReapJob` for you when Solid Queue is in the bundle; otherwise (or on another scheduler) you must schedule it yourself. Unscheduled, a crash mid-batch leaves that row stuck forever.
+
+---
+
+## ✅ Before you build: verify the ground truth (CHECK, don't ask for it)
+
+| Check | How | Why it matters |
+|---|---|---|
+| Subsystem enabled | grep `config/initializers/plutonium.rb` for `async_runs.enabled` | Not enabled means no table; `async` raises `Dispatchable::NotEnabledError` the moment it dispatches, naming the flag |
+| Run registered in the target portal | grep the portal's `config/routes.rb` for `register_resource ::Plutonium::Interaction::Async::Run` | Unregistered means dispatch redirects to a 404; the running banner silently skips that portal (by design, see below) |
+| Existing run classes for the pattern | `ls app/runs/` or grep `< Plutonium::Interaction::Async::Run` | Match the host's existing `on_failure` conventions rather than guessing |
+| ReapJob scheduled | grep `config/recurring.yml` / `config/schedule.rb` for `ReapJob` | An `on_submit`-shaped bulk workflow with no reaper leaves crashed runs stuck |
+
+---
+
+## Declaring the work
+
+`async` with a block. One file — the run is declared inline and needs no name:
+
+```ruby
+class Blogging::ArchivePosts < ResourceInteraction
+  presents label: "Archive", icon: Phlex::TablerIcons::Archive
+  attribute :resources          # bulk: perform_on runs once per record
+  attribute :reason, :string
+
+  async do
+    on_failure :continue        # :halt (default) | :continue | :transactional
+    def perform_on(post)        # targeted: called once per resolved target
+      post.archive!(reason: options["reason"])
+    end
+  end
+end
+
+class Reports::GenerateMonthly < ResourceInteraction
+  attribute :period, :string
+
+  async do
+    def perform                 # opaque: no target, called once
+      Reports::Monthly.generate!(options["period"])
+    end
+  end
+end
+```
+
+**The block is the run's class body, not the body of `#execute`.** The work happens later, in a process with no controller and no `view_context`, so it cannot close over anything in the interaction — which is why it declares `perform_on`/`perform` rather than executing directly. Validated attributes arrive through `options`, and `def` opens a fresh scope, so those bodies can't accidentally capture the interaction's locals.
+
+The block defines `<Interaction>::Run` — a real, named constant, because the class name is persisted in `type` and constantized in the job process.
+
+**Pass a class instead** to share one run across several interactions that do the same kind of work:
+
+```ruby
+async Blogging::ArchivePostsRun
+```
+
+| `on_failure` | One target raises |
+|---|---|
+| `:halt` (default) | Stop immediately; run ends `"failed"`; remaining targets never attempted |
+| `:continue` | Record the failure (`errors_log`), keep going; run ends `"completed"`. Check `outcome`, not `state`, to see it under-applied |
+| `:transactional` | Whole batch in one DB transaction; any failure rolls back everything, including targets already applied |
+
+`attribute :resource` (singular) means a one-target run; `attribute :resources` (plural) means bulk; neither means opaque. Same inference rule ordinary interactive actions use, see [[plutonium-resource]] › Actions.
+
+### What's recorded, and why
+
+Nothing is passed explicitly. Dispatch reads it off the interaction/controller it's already running in:
+
+- **Targets** as ids (`target_ids`), re-resolved through the policy scope at perform time. Never serialized records, which would be stale and unauthorized the moment anything changed.
+- **Initiator + tenant** (`current_user` / `current_scoped_entity`), the pair every Plutonium policy authorizes on.
+- **`policy_class_name`**, the policy dispatch actually resolved, not an inferred `"#{Model}Policy"` (wrong under a namespaced portal or an STI target).
+- **`policy_action`**, the predicate dispatch checked (e.g. `"archive?"`), re-asked per target at perform time.
+- **`authorization_namespace`**, the portal's module name, so perform-time lookup finds the same policy dispatch did.
+
+An opaque run records none of the target/policy columns. Nothing to re-verify without a subject.
+
+## Attributes and files
+
+Validated attributes reach the run through `options`, a JSON column written via `ActiveJob::Arguments` — primitives verbatim, `Date`/`BigDecimal`/`Time` round-tripped with their types. An attribute that can't be carried is refused at dispatch.
+
+Files can't ride a JSON column, and the request's tempfile is gone by the time the job runs, so an uploaded file is staged to its backend's cache and carried as a token. Read it back with `attachment`:
+
+```ruby
+attribute :import_file
+
+async do
+  def perform
+    attachment(:import_file).open { |f| CSV.foreach(f, headers: true) { |row| ... } }
+  end
+end
+```
+
+`attachment(:key)` / `attachments(:key)` give `filename`, `content_type`, `url`, `open`, `download`.
+
+`backend:` and `uploader:` come off the attribute's `input` declaration, exactly as in a wizard step — `input :import_file, as: :uppy, uploader: Catalog::ImportUploader`. The uploader's `Attacher.validate` rules run when the interaction validates, so a bad file **fails the form** rather than surfacing as a run failure the submitter never sees. Where no `backend:` is declared: `config.async_interactions.attachment_backend` → `config.attachment_backend` → auto-detect.
+
+## Registering the Run resource
+
+Use the generator, per portal. Never hand-write the route/controller:
+
+```bash
+rails g pu:async_interactions:install --dest=admin_portal
+```
+
+```ruby
+# packages/admin_portal/config/routes.rb
+register_resource ::Plutonium::Interaction::Async::Run
+```
+
+```ruby
+# packages/admin_portal/app/controllers/admin_portal/async_runs_controller.rb
+class AdminPortal::AsyncRunsController < AdminPortal::ResourceController
+  controller_for ::Plutonium::Interaction::Async::Run
+
+  include AdminPortal::Concerns::Controller
+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 (exact class-name match for the definition, ActionPolicy's own lookup for the policy).
+
+If Solid Queue is in the bundle, this also schedules `Async::ReapJob` in `config/recurring.yml` — see [Scheduling ReapJob](#scheduling-reapjob-stalled-runs). `--schedule` overrides the default `every 15 minutes`. Idempotent, so running it against a second portal doesn't duplicate the entry.
+
+Registering gets you, for free:
+
+- **Progress page.** The show page IS the progress page, self-polling while `pending`/`running`, and stops carrying the poll once settled (a finished run is a static page, not an eternal background request per viewer).
+- **Self-refreshing index.** The runs index polls on the same terms, one frame around the whole collection, armed only while some run is still working. One request per interval whatever the page size, and it re-fetches the current URL so filters, sort and page survive. No action needed on your part.
+- **Running banner.** Any OTHER registered resource's index lists in-progress runs targeting it, above the collection, scoped through the same `authorized_resource_scope` every cross-resource read uses (a run in another tenant can't surface). If a `resource_class` is registered in a portal that never registered `Run`, the banner is skipped there instead of raising while building a link to a nonexistent route. No action needed on your part.
+- **`target_label`.** The show page/table read `run.target_label` (`model_name.human`, e.g. `"Post"`) rather than the raw `target_type` string (`"Blogging::Post"`).
+- **Tenant scoping via `associated_with`.** Filters on the tenant the run was dispatched in (recorded on the row), because the two tenant columns are polymorphic and the generic object-graph scope can't walk them.
+
+## Scheduling ReapJob (stalled runs)
+
+A worker crash mid-batch, or a job the queue silently drops, leaves a run `"running"`/`"pending"` forever. Nothing else revisits it. `ReapJob` finds runs with no activity (`last_activity_at`, or `created_at` if never picked up) past `config.async_interactions.stall_after` (default `1.hour`), and resumes them: resets to `"pending"`, re-enqueues.
+
+This is safe, not a blind replay. The executor tracks `handled_target_ids` and only re-attempts what's left.
+
+Safe *given a heartbeat*: `handled_target_ids` only exists for targeted work, so opaque work resumes by re-running `perform` whole. Long opaque work must call `heartbeat!` (see Critical, above) so it is never judged stalled in the first place.
+
+`rails g pu:async_interactions:install` schedules it automatically when Solid Queue is in the bundle:
+
+```yaml
+# config/recurring.yml (Solid Queue)
+production:
+  reap_stalled_async_runs:
+    class: Plutonium::Interaction::Async::ReapJob
+    schedule: every 15 minutes
+```
+
+Without Solid Queue — or for another scheduler like `whenever` — add it yourself:
+
+```ruby
+# whenever gem
+every 15.minutes do
+  runner "Plutonium::Interaction::Async::ReapJob.perform_later"
+end
+```
+
+15 to 30 minutes is a reasonable cadence against the default 1-hour `stall_after`. This is a time heuristic, not a true lease: a merely-slow (not dead) run that crosses `stall_after` gets resumed too. `lock_version` bounds what that costs — the resumed row's version no longer matches the still-live worker's, so that worker stops at its next write instead of racing the new one. It does **not** interrupt an in-flight `perform_on` (one target can be applied twice, once by each side), and it does not roll back what the superseded worker already committed. Set `stall_after` well above the app's slowest legitimate run.
+
+On Solid Queue (or any queue providing ActiveJob concurrency controls) this is tightened further, automatically and with no configuration: `Async::Job` declares a semaphore of 1 keyed on the run id, held for `stall_after`, and `ReapJob` one global sweep at a time. A second delivery of the same run then waits rather than racing, so the one target the fence cannot save from a double apply is not applied twice either. Nothing declares it when the queue does not support it.
+
+## Full reference
+
+`docs/reference/behavior/async-interactions.md` has the complete write-up: authorization re-derivation in detail, outcome-vs-state, everything above with more context.
+
+## Related Skills
+
+- [[plutonium-behavior]] — the interaction itself: inputs, validation, `succeed`/`failed`, policies.
+- [[plutonium-resource]] — Actions (inferred bulk/record/resource shape), Definition (`field`/`display`/`column`).
+- [[plutonium-tenancy]] — entity scoping, `associated_with`, portal tenant strategies.
+- [[plutonium-wizard]] — the other long-lived, persisted flow primitive (multi-step, not async execution). `Wizard::SweepJob` is `ReapJob`'s sibling for abandoned wizard sessions.

data/.claude/skills/plutonium-auth/SKILL.md

@@ -222,6 +222,39 @@ For portal wiring (`AdminPortal::Concerns::Controller`), see [[plutonium-app]]
 
 ---
 
+## Multiple portals in one browser
+
+Each portal authenticates through its own Rodauth configuration, and a person can hold a session in several at once — sign into the admin portal and the customer portal in the same browser without either evicting the other.
+
+Two settings make that work, and the generators emit both:
+
+```ruby
+# app/rodauth/rodauth_plugin.rb — the shared base
+configure do
+  enable :session_isolation
+end
+
+# app/rodauth/<name>_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`, … `session_isolation` uses that prefix to decide ownership and stops a login from clearing the other configurations' keys.
+
+🚨 **Never set `session_key` alongside it.** Explicit values bypass `convert_session_key` (`rodauth/features/base.rb:686`) so they are NOT prefixed — the account id then rotates separately from every other key. A session holding an account id with no `authenticated_by` makes Rodauth raise on every request (`logged_in_via_remember_key?` → `nil.include?`, `remember.rb:175`). A config with no prefix at all is simply not isolated: its keys are the unprefixed defaults, so nothing is carried for it.
+
+**Why:** 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 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 autologins from its remember cookie on the next request and evicts the new one right back. The last `load_memory` 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 — `session.delete(login_redirect_session_key)`, not `session.delete(:login_redirect)`. With a prefix set, the literal is the wrong key.
+
+**Upgrading an app generated before this existed:** add `enable :session_isolation` once in the base plugin, add `session_key_prefix` to each account plugin, and **delete any existing `session_key "_x_session"` line**. Every key name changes together, so stale session cookies are simply ignored — the safe outcome. Keeping the old `session_key` to preserve logins is exactly what produces the crashing half-migrated session. Only *unremembered* sessions actually drop: `remember_cookie_key` is a cookie name and is not prefixed, so anyone holding a valid `_x_remember` cookie is restored by `load_memory` on their next request.
+
+---
+
 ## Common customizations
 
 All inside the Rodauth `configure do ... end` block in `app/rodauth/<name>_rodauth_plugin.rb`.
@@ -410,6 +443,9 @@ link_to("Profile", profile_url) if respond_to?(:profile_url)
 - **`pu:saas:setup` runs four other generators** — don't re-run portal, profile, welcome, or invites separately.
 - **Profile requires `pu:profile:conn`** — without it, no route, no `profile_url`, no menu link.
 - **Users need a profile row.** Add an `after_create` callback (or `find_or_create_by`) — `current_user.profile` is otherwise nil.
+- **Concurrent portal logins need `enable :session_isolation` + `session_key_prefix`.** Missing either and signing into one portal silently evicts the others — see Multiple portals in one browser.
+- **Never hardcode a Rodauth session key.** Use the accessor (`login_redirect_session_key`), since `session_key_prefix` changes the literal.
+- **"Remember me" is opt-in.** Configs use `after_login { remember_login if param_or_nil(remember_param) == remember_remember_param_value }` and the login form renders the checkbox. Compare against the value, not just presence — a bare truthiness check means `remember=disable` would remember you. Plutonium's form also passes `include_hidden: false` so an unticked box sends nothing — belt-and-braces next to the value comparison, not the thing holding it up.
 
 ---
 

data/.claude/skills/plutonium-behavior/SKILL.md

@@ -17,6 +17,7 @@ For tenant-scoped `relation_scope` and entity scoping, load [[plutonium-tenancy]
 - **`permitted_attributes_for_*` must be explicit in production.** Dev auto-detection works; production raises.
 - **`ActiveRecord::RecordInvalid` is NOT rescued automatically in interactions.** 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.
+- **An interaction is a presentation object** (it can only be built with a `view_context`). Logic may *start* in `execute`; the **second caller** — a job, an API controller, a rake task, the console — is the trigger to move it onto the **model**. Don't pre-extract, and don't invent a service layer. See Part 3 › Where the logic goes.
 - **Redirect is automatic on success** — only use `with_redirect_response` for a *different* destination.
 - **`relation_scope` must end up calling `default_relation_scope(relation)` somewhere in the chain.** Prefer calling it explicitly. `super` works when extending a parent policy (e.g., a package base) that itself calls it. See [[plutonium-tenancy]].
 - **For `has_cents` fields, use the virtual name (`:price`), not `:price_cents`** in `permitted_attributes_for_*`.
@@ -32,7 +33,8 @@ For tenant-scoped `relation_scope` and entity scoping, load [[plutonium-tenancy]
 | The requirement (in plain words) | Goes in | **NOT** in |
 |---|---|---|
 | "only \<role/owner\> may do X" — *who is allowed* | **Policy** `def x?` | a `condition:` proc — that only hides the button; the route stays live and callable |
-| "doing X changes state / sends mail / charges a card" — *the work* | **Interaction** `execute`, registered as an action | a hand-written controller action; an override of `create`/`update` |
+| "there's a button that does X" — *the trigger* | **Interaction** (+ action in the definition) | a hand-written controller action; an override of `create`/`update` |
+| "doing X changes state / sends mail / charges a card" — *the work* | a named **model** method the interaction calls (`post.publish!`) — inline in `execute` is fine while the button is the only caller | a service-object layer; three chained interactions |
 | "after create/update go to Y" · "munge a param" · "reshape the index query" | **Controller hook** (`redirect_url_after_submit`, `resource_params`, `filtered_resource_collection`) | overriding `create`/`update`/`index` |
 | "which fields are visible / editable" | **Policy** `permitted_attributes_for_*` | the definition — that only controls *how* a field renders |
 
@@ -109,7 +111,8 @@ Plus interactive-action routes for every action declared in the definition.
 |---|---|
 | Field rendering (inputs, displays, columns) | Definition |
 | Search, filters, scopes, sorting | Definition |
-| Custom operations (publish, archive, import) | Interaction (+ action in definition) |
+| Custom operations (publish, archive, import) — the *button* | Interaction (+ action in definition) |
+| The operation itself, once a job/API/task also needs it | The **model** (`post.publish!`) — see Part 3 › Where the logic goes |
 | Authorization rules | Policy |
 | Form/show/page chrome | Definition (custom page classes) |
 | **Custom redirect logic** | **Controller hook** |
@@ -158,6 +161,10 @@ def filtered_resource_collection
 end
 ```
 
+**Don't add eager loading unprompted.** Which associations a page renders is decided by the definition, so an `includes` list written now is a guess that goes stale when a column is added. Adding one is a performance change the user didn't ask for.
+
+When a user actually reports a slow index or an N+1: suggest [goldiloader](https://github.com/salsify/goldiloader) first — it eager-loads on traversal, so it tracks whatever the definition renders and needs no list to maintain. Only hand-write `def filtered_resource_collection = super.includes(...)` if they decline the gem, and use the policy's `relation_scope` instead when the association is also read on show/export/typeahead. Full detail: [Guides › Performance](/guides/performance).
+
 ### Presentation hooks
 
 Control whether parent / scoped-entity fields appear in forms and displays. Defaults are `false` (hidden, since they're inferred from the URL/portal).
@@ -171,13 +178,15 @@ def submit_scoped_entity?   = true
 
 ## Custom actions
 
-Prefer **interactive actions** (definition + interaction) for anything with business logic. The only reason to hand-write a controller action is unusual flows (custom response shapes, external service callbacks, etc.).
+Prefer **interactive actions** (definition + interaction) for anything a user triggers from a page. The only reason to hand-write a controller action is unusual flows (custom response shapes, external service callbacks, etc.).
+
+Either way the *operation* is a named model method — the controller and the interaction are two front doors onto the same `post.publish!`.
 
 ```ruby
 class PostsController < ::ResourceController
   def publish
     authorize_current!(resource_record!, to: :publish?)
-    resource_record!.update!(published: true)
+    resource_record!.publish!
     redirect_to resource_url_for(resource_record!), notice: "Published!"
   end
 end
@@ -279,10 +288,12 @@ end
 | Method | Returns |
 |---|---|
 | `current_parent` | Parent record |
+| `current_parent_class` | `User` |
 | `current_nested_association` | `:posts` |
-| `parent_route_param` | `:user_id` |
 | `parent_input_param` | `:user` |
 
+The parent class and association come from the **route** (each nested route carries its registration key), not from parsing the URL. There is no `parent_route_param`.
+
 Parent fields are excluded from forms/displays by default — toggle with the presentation hooks above. For `has_one` associations, routes are singular (no `:id`); index redirects to show (or new if no record exists). See [[plutonium-tenancy]] for the full nested-routing story.
 
 ## Entity scoping (multi-tenancy)
@@ -423,6 +434,8 @@ end
 | `search?` | `index?` | Search-specific rules |
 | `typeahead?` | `index?` | Autocomplete-specific rules |
 
+🚨 **`record` is the resource CLASS on collection routes** (`current_policy_subject = resource_record? || resource_class`). `read?` backs both `show?` (instance) and `index?` (class); `create?`/`new?`, `export_csv?`, `search?`, and resource-action gates (incl. kanban column actions) are class-backed too. `def read? = record.published?` raises `NoMethodError` on index — filter the list in `relation_scope`, gate individual records in `show?`. Record actions (`publish?` etc.) and bulk actions are always evaluated per record instance — no type guard needed.
+
 `export_csv?` is the exception — it defaults to `false` (not derived) so CSV export is strictly opt-in. Override it to `true` (or `index?`) to enable the built-in export. The exported column set is `permitted_attributes_for_export` (defaults to `permitted_attributes_for_index`). See [[plutonium-resource]] → CSV Export.
 
 ### Custom actions
@@ -656,7 +669,41 @@ end
 
 # Part 3 — Interactions
 
-Interactions encapsulate business logic into testable units. They're registered as actions in definitions (see [[plutonium-resource]] › Actions) and executed by the controller.
+An interaction is the entry point from a Plutonium page into an operation: it declares the inputs, renders as a button and a form, is gated by a policy, and returns an outcome the controller turns into a flash + redirect. Registered as actions in definitions (see [[plutonium-resource]] › Actions) and executed by the controller.
+
+For a bulk operation, or anything too slow to hold a request open, `async` declares a persisted, resumable run instead of executing inline. See [[plutonium-async-interactions]].
+
+## Where the logic goes
+
+An interaction is a **presentation object**. Its job is the button, the form, input-shape validation, and the user-facing outcome. It is not the home of a domain operation, because of one line in the base class:
+
+```ruby
+def initialize(view_context:, **attributes)
+```
+
+`view_context:` is required. So a caller that isn't a Plutonium page has two options: duplicate the logic, or manufacture a `view_context` it has no business owning. **`view_context` is the tell.**
+
+| | |
+|---|---|
+| **Logic may start in `execute`** | A one-off with a single caller is fine inline. Don't pre-extract — Plutonium ships no service layer to put it in, and YAGNI. |
+| **The trigger to extract is the second caller** | A background job, an API controller, a rake task, the console, another interaction. |
+| **The destination is the model** | Fat models, per Rails convention. Name it in domain language — `publish!`, `archive!`, `register!` — not persistence (`update_published_at`). Never a `PublishPostService`. |
+
+```ruby
+# 🚫 Three interactions, three view_contexts. A signup API or a seeds script
+#    can supply none of them — the email and the audit row are stranded.
+CreateUserInteraction.call(view_context:, **user_params)
+  .and_then { |user| SendWelcomeEmail.call(view_context:, user:) }
+  .and_then { |user| LogActivity.call(view_context:, user:) }
+
+# ✅ One model method; the interaction presents it
+def execute
+  user = User.register!(**attributes)   # welcome email + audit row live in here
+  succeed(user).with_message("Welcome aboard!")
+end
+```
+
+Chaining three interactions is usually one model method wearing three presentation costumes.
 
 ## Structure
 
@@ -665,7 +712,14 @@ Interactions encapsulate business logic into testable units. They're registered
 class ResourceInteraction < Plutonium::Resource::Interaction
 end
 
-# A real interaction
+# app/models/post.rb — what publishing MEANS (a scheduler job can call this too)
+class Post < ApplicationRecord
+  def publish!(on: Time.current)
+    update!(published: true, published_at: on)
+  end
+end
+
+# A real interaction — the button in front of it
 class PublishPostInteraction < ResourceInteraction
   presents label: "Publish",
            icon: Phlex::TablerIcons::Send,
@@ -681,7 +735,7 @@ class PublishPostInteraction < ResourceInteraction
   private
 
   def execute
-    resource.update!(published_at: publish_date)
+    resource.publish!(on: publish_date)
     succeed(resource).with_message("Post published!")
   rescue ActiveRecord::RecordInvalid => e
     failed(e.record.errors)
@@ -778,22 +832,32 @@ failed(email: "is invalid", name: "is required")  # hash form
 failed("Invalid value", :email)                   # string + attribute
 ```
 
-### Chaining
+### Chaining — `and_then`
+
+On a `Success`, `and_then` yields **the value** (NOT the outcome — there is no `r.value` in the block) and returns whatever the block returns; on a `Failure` it short-circuits, returning the failure untouched.
+
+Use it to compose outcomes **inside one `execute`**, e.g. a guard:
 
 ```ruby
 def execute
-  CreateUserInteraction.call(view_context:, **user_params)
-    .and_then { |r| SendWelcomeEmail.call(view_context:, user: r.value) }
-    .and_then { |r| LogActivity.call(view_context:, user: r.value) }
-    .with_message("User created and welcomed!")
+  unlocked_resource.and_then do |post|
+    post.publish!(on: publish_date)
+    succeed(post).with_message("Post published!")
+  end
+end
+
+private
+
+def unlocked_resource
+  resource.locked? ? failed("This post is locked") : succeed(resource)
 end
 ```
 
-The chain short-circuits on the first failure.
+⚠️ **Don't chain interactions to sequence business operations** — see Where the logic goes above.
 
 ## Validations
 
-Standard ActiveModel — run automatically before `execute`:
+Standard ActiveModel — run automatically before `execute`; if they fail, `execute` never runs:
 
 ```ruby
 validates :email, presence: true, format: {with: URI::MailTo::EMAIL_REGEXP}
@@ -808,6 +872,21 @@ def custom_check
 end
 ```
 
+### Which validation goes where
+
+| | 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 calls |
+| Exists to | render a form error next to the field | protect the data from every caller, including ones with no form |
+| Runs | before `execute`, never touching the model | inside `save!`/`update!` — i.e. inside the model method |
+
+They surface **differently**, and that should inform where a rule lives:
+
+- An interaction validation attaches to a declared attribute → the re-rendered modal shows it inline against that input **and** in the summary.
+- `failed(record.errors)` flattens `ActiveModel::Errors` to **full messages on `:base`** (`Array(errors)` → `errors.to_a` → `full_messages`) → error summary only, never against a field, phrased with the *model's* attribute names.
+
+So it's fine — 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: when a job calls `post.publish!`, the interaction's validations aren't in the picture.
+
 ## Accessing context
 
 ```ruby
@@ -818,6 +897,8 @@ def execute
 end
 ```
 
+This write is **correctly inline**. "Who clicked the button" is context only the presentation layer holds — a job has no answer for it, so there's no second caller to extract for.
+
 A shorter `current_user` helper is conventional:
 
 ```ruby
@@ -860,7 +941,25 @@ The same URL serves GET (form/confirmation) and POST (commit) — the HTTP verb
 
 ## 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`; the interaction is the button in front of it.
+
+```ruby
+# app/models/company.rb — what inviting MEANS: the row, the mail, the audit trail
+class Company < ApplicationRecord
+  has_many :user_invites
+
+  def invite!(email:, role:, by:)
+    user_invites.create!(email: email, role: role, invited_by: by).tap do |invite|
+      UserInviteMailer.invitation(invite).deliver_later
+    end
+  end
+
+  def pending_invite_for?(email) = user_invites.exists?(email: email, state: :pending)
+end
+```
+
 ```ruby
+# app/interactions/company/invite_user_interaction.rb
 class Company::InviteUserInteraction < Plutonium::Resource::Interaction
   presents label: "Invite User",
            icon: Phlex::TablerIcons::UserPlus
@@ -872,6 +971,7 @@ class Company::InviteUserInteraction < Plutonium::Resource::Interaction
   input :email
   input :role, as: :select, choices: -> { UserInvite.roles.keys }
 
+  # Input shape only — readable email? 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
@@ -879,21 +979,18 @@ class Company::InviteUserInteraction < Plutonium::Resource::Interaction
   private
 
   def execute
-    invite = UserInvite.create!(
-      company: resource, email: email, role: role,
-      invited_by: current_user
-    )
-    UserInviteMailer.invitation(invite).deliver_later
+    resource.invite!(email: email, role: role, by: current_user)
     succeed(resource).with_message("Invitation sent to #{email}")
   rescue ActiveRecord::RecordInvalid => e
     failed(e.record.errors)
   end
 
+  # Deliberately duplicated. UserInvite enforces uniqueness for real (a job calling
+  # company.invite! must hit it too); this copy exists only so the message lands on
+  # the :email field instead of in the base error summary.
   def not_already_invited
-    return unless email.present?
-    if UserInvite.exists?(company: resource, email: email, state: :pending)
-      errors.add(:email, "already has a pending invitation")
-    end
+    return if email.blank?
+    errors.add(:email, "already has a pending invitation") if resource.pending_invite_for?(email)
   end
 
   def current_user = view_context.controller.helpers.current_user