plutonium 0.65.0 → 0.66.0

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

@@ -1,66 +1,66 @@
 ---
 name: plutonium-tenancy
-description: Use BEFORE any multi-tenant work — scoping a model to a tenant, writing relation_scope, configuring portal entity strategies, setting up parent/child nested resources, or wiring user invitations. The single source for entity scoping, nested resources, and invites.
+description: 'Use BEFORE any multi-tenant work: scoping a model to a tenant, writing relation_scope, configuring portal entity strategies, setting up parent/child nested resources, or wiring user invitations. The single source for entity scoping, nested resources, and invites.'
 ---
 
-# Plutonium Tenancy — Entity Scoping, Nested Resources, Invites
+# Plutonium Tenancy: Entity Scoping, Nested Resources, Invites
 
 Three closely-coupled concerns:
 
-1. **Entity scoping** — every record belongs to a tenant; queries are filtered automatically.
-2. **Nested resources** — parent/child URLs; parent scoping takes precedence over entity scoping.
-3. **Invites** — onboarding users into a tenant's membership.
+1. **Entity scoping**: every record belongs to a tenant; queries are filtered automatically.
+2. **Nested resources**: parent/child URLs; parent scoping takes precedence over entity scoping.
+3. **Invites**: onboarding users into a tenant's membership.
 
 Cross-references back to [[plutonium-resource]] (models, definitions) and [[plutonium-behavior]] (policies, controllers).
 
 ## 🚨 Critical (read first)
 
-- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins to the entity triggers `verify_default_relation_scope_applied!`. Make sure the chain ends up calling `default_relation_scope(relation)` — explicitly, or via `super(relation)` (the framework base calls it).
+- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins to the entity triggers `verify_default_relation_scope_applied!`. Make sure the chain ends up calling `default_relation_scope(relation)`, explicitly, or via `super(relation)` (the framework base calls it).
 - **Always declare an association path from model to entity.** Direct `belongs_to`, `has_one :through`, or a custom `associated_with_<entity>` scope. If `associated_with` can't resolve, Plutonium raises. Fix the **model**, not the policy.
 - **Parent scoping beats entity scoping.** When a parent is present (nested resource), `default_relation_scope` scopes via the parent, NOT via `entity_scope`. Don't double-scope.
 - **One level of nesting only.** Grandparent → parent → child nested routes are NOT supported. Use top-level routes for deeper relationships.
-- **Compound uniqueness scoped to the tenant FK.** `validates :code, uniqueness: {scope: :organization_id}` — without this, uniqueness leaks across tenants.
+- **Compound uniqueness scoped to the tenant FK.** `validates :code, uniqueness: {scope: :organization_id}`; without this, uniqueness leaks across tenants.
 - **Invite email must match the accepting user's email.** Security feature. Don't disable `enforce_email?` lightly.
 - **Use generators.** `pu:saas:setup`, `pu:pkg:portal --scope=Entity`, `pu:res:scaffold`, `pu:invites:install`, `pu:invites:invitable`. Hand-wiring is how leaks happen.
 
 ---
 
-## 🛑 Before you scope anything: confirm the shape (ASK — don't infer)
+## 🛑 Before you scope anything: confirm the shape (ASK: don't infer)
 
 Tenancy decisions are **underspecified by a one-line request and have high blast radius**: guess the entity, the strategy, or the association path and you ship a model that *compiles but leaks across tenants*, *raises at runtime*, or *produces the wrong URL*. "Scope X to the tenant" does **not** determine any of the below.
 
-Resolve each decision — **by inspecting the app (next section), not by guessing** — then restate the resolved shape in a sentence and confirm:
+Resolve each decision, **by inspecting the app (next section), not by guessing**; then restate the resolved shape in a sentence and confirm:
 
 1. **Is this portal even entity-scoped?** A model is only tenant-filtered inside a portal that declares `scope_to_entity`. No `scope_to_entity` ⇒ your model change does nothing. (Verify it exists *before* touching the model.)
-2. **Which entity model, and which strategy?** `Organization` / `Account` / `Tenant` / `Company`? `:path` (most common) or custom (subdomain/session)? **Never default to `Organization` + `:path`** — read it.
-3. **What is the association PATH from this model to the entity?** Direct `belongs_to`, multi-hop `has_one :through`, a membership/join, or polymorphic needing a custom `associated_with_<entity>` scope (§ Three model shapes). This is the #1 thing to confirm against the **actual model** — wrong path ⇒ leak *or* raise.
-4. **Nested (parent-scoped) or entity-scoped?** Reached through a parent ⇒ parent scoping wins, don't double-scope. And **nesting is ONE level only** — a three-level URL request can't be met with `register_resource` nesting; say so before wiring it.
+2. **Which entity model, and which strategy?** `Organization` / `Account` / `Tenant` / `Company`? `:path` (most common) or custom (subdomain/session)? **Never default to `Organization` + `:path`**; read it.
+3. **What is the association PATH from this model to the entity?** Direct `belongs_to`, multi-hop `has_one :through`, a membership/join, or polymorphic needing a custom `associated_with_<entity>` scope (§ Three model shapes). This is the #1 thing to confirm against the **actual model**: wrong path ⇒ leak *or* raise.
+4. **Nested (parent-scoped) or entity-scoped?** Reached through a parent ⇒ parent scoping wins, don't double-scope. And **nesting is ONE level only**: a three-level URL request can't be met with `register_resource` nesting; say so before wiring it.
 5. **Uniqueness scoped to the tenant FK?** Any `validates … uniqueness` must scope to the tenant FK (`scope: :organization_id`) or it leaks across tenants.
 
 **Never emit applied scoping code from a *guessed* association path.** Confirm the path against the real model first; fall back to `AskUserQuestion` only for genuinely product-level choices you can't read off the code (which entity, which strategy). The decisions compound: *no scoped portal ⇒ nothing filters*; *nested ⇒ parent-scoped, not entity-scoped*; *multi-hop ⇒ needs `has_one :through` or a custom scope*.
 
-## ✅ Before you edit: verify the ground truth (CHECK — read it, don't ask for it)
+## ✅ Before you edit: verify the ground truth (CHECK: read it, don't ask for it)
 
-You have file access — **use it.** "Paste me the model" is a fallback for when you genuinely can't read the repo, **not** the default. Inspect first, then act:
+You have file access, **use it.** "Paste me the model" is a fallback for when you genuinely can't read the repo, **not** the default. Inspect first, then act:
 
 | Check | How | Why it matters |
 |---|---|---|
 | Portal is scoped | `rg "scope_to_entity" -n` in the portal engine(s) | Confirms entity class + strategy; absent ⇒ scoping is a no-op |
-| Model is a resource | Read the model — `include Plutonium::Resource::Record` / `< ResourceRecord` | `associated_with` only exists on resource records |
+| Model is a resource | Read the model, `include Plutonium::Resource::Record` / `< ResourceRecord` | `associated_with` only exists on resource records |
 | Association path resolves | Read the model's `belongs_to`/`has_one :through` chain to the entity (or a `associated_with_<entity>` scope) | This is the real fix site; missing path ⇒ raise |
 | Denormalized FK already present | Read the schema/migration for an existing `<entity>_id` column | Collapses a multi-hop chain to a one-line `belongs_to` |
-| No leaky override | `rg "relation_scope" -n` in the policy | A manual `where(<entity>:…)` is the leak — **remove it**, don't patch it |
+| No leaky override | `rg "relation_scope" -n` in the policy | A manual `where(<entity>:…)` is the leak, **remove it**, don't patch it |
 | (Invites) prerequisites | Membership model exists with `enum :role`; AR encryption keys set (`bin/rails db:encryption:init`) | `pu:invites:install` fails loudly without both |
 
 Do this inspection with your own tools **before** proposing code. Surfacing a concrete edit you haven't grounded in the real files is how the "looks right, leaks anyway" bug ships.
 
-## 🛠 Use the generator — and verify its precondition first
+## 🛠 Use the generator, and verify its precondition first
 
 Hand-wiring tenancy (invite models, membership tables, join records) is how leaks happen. Reach for the generator, run it with `--dest=` to avoid prompts, and **confirm the precondition before running**:
 
 | Task | Generator | Verify first |
 |---|---|---|
-| New SaaS spine (user + entity + membership + join) | `pu:saas:setup --user U --entity E` | None — this is the bootstrap |
+| New SaaS spine (user + entity + membership + join) | `pu:saas:setup --user U --entity E` | None; this is the bootstrap |
 | Scope a portal to an entity | `pu:pkg:portal --scope=Entity` | Entity model exists |
 | New tenant-scoped model | `pu:res:scaffold Model entity:belongs_to …` then `pu:res:conn` | Migrations from prior scaffolds are run |
 | Invite flow | `pu:invites:install` | Membership model exists (`enum :role`) **and** AR encryption keys configured |
@@ -68,7 +68,7 @@ Hand-wiring tenancy (invite models, membership tables, join records) is how leak
 
 ---
 
-# Part 1 — Entity Scoping
+# Part 1: Entity Scoping
 
 Built on three cooperating pieces:
 
@@ -82,12 +82,12 @@ Built on three cooperating pieces:
 
 `Model.associated_with(entity)` tries, in order:
 
-1. **Custom scope** `associated_with_<entity_name>` — highest priority, full SQL control.
-2. **Direct `belongs_to` to entity class** — `WHERE <entity>_id = ?`, most efficient.
-3. **`has_one` / `has_one :through` to entity class** — JOIN + WHERE, auto-detected via `reflect_on_all_associations`.
-4. **Reverse `has_many` from entity** — JOIN required, logs a warning (less efficient).
+1. **Custom scope** `associated_with_<entity_name>`: highest priority, full SQL control.
+2. **Direct `belongs_to` to entity class**: `WHERE <entity>_id = ?` (most efficient).
+3. **`has_one` / `has_one :through` to entity class**: JOIN + WHERE, auto-detected via `reflect_on_all_associations`.
+4. **Reverse `has_many` from entity**: JOIN required, logs a warning (less efficient).
 
-If none apply: `Could not resolve the association between 'Model' and 'Entity'`. Fix on the **model** — either declare an association path (`belongs_to`, `has_one :through`) OR define a custom `associated_with_<entity>` scope. Never work around this by overriding `relation_scope` in the policy.
+If none apply: `Could not resolve the association between 'Model' and 'Entity'`. Fix on the **model**: either declare an association path (`belongs_to`, `has_one :through`) OR define a custom `associated_with_<entity>` scope. Never work around this by overriding `relation_scope` in the policy.
 
 ## Three model shapes
 
@@ -176,7 +176,7 @@ Use when:
 
 Picked up BEFORE association detection.
 
-## `relation_scope` — safe overrides
+## `relation_scope`: safe overrides
 
 `default_relation_scope(relation)` does two things:
 
@@ -186,7 +186,7 @@ Picked up BEFORE association detection.
 ### Correct
 
 ```ruby
-# ✅ Best: don't override — the inherited scope already does it.
+# ✅ Best: don't override: the inherited scope already does it.
 
 # ✅ Extra filters on top
 relation_scope do |relation|
@@ -203,23 +203,25 @@ end
 ### Wrong
 
 ```ruby
-# ❌ Manually filtering by entity — bypasses default_relation_scope
+# ❌ Manually filtering by entity: bypasses default_relation_scope
 relation_scope { |r| r.where(organization: current_scoped_entity) }
 
-# ❌ Manual joins — same problem
+# ❌ Manual joins: same problem
 relation_scope { |r| r.joins(:project).where(projects: {organization_id: current_scoped_entity.id}) }
 
-# ❌ Missing default_relation_scope entirely — raises at runtime
+# ❌ Missing default_relation_scope entirely: raises at runtime
 relation_scope { |r| r.where(published: true) }
 ```
 
-**`default_relation_scope(relation)` must end up being called somewhere in the chain** — runtime verification just checks it was hit, not that you wrote it in this class. Both work:
+**`default_relation_scope(relation)` must end up being called somewhere in the chain**; runtime verification just checks it was hit, not that you wrote it in this class. Both work:
 
-- `default_relation_scope(relation).where(...)` — explicit, always safe
-- `super(relation).where(...)` — `Plutonium::Resource::Policy`'s `relation_scope` block calls `default_relation_scope`, so chaining through `super` picks it up
+- `default_relation_scope(relation).where(...)`: explicit, always safe
+- `super(relation).where(...)`: `Plutonium::Resource::Policy`'s `relation_scope` block calls `default_relation_scope`, so chaining through `super` picks it up
 
 Pick the one that reads better for the situation.
 
+Verify a role-based scope with an integration test that logs in as each role and checks another tenant's records never appear. The login helpers (`login_as`) come from `Plutonium::Testing::AuthHelpers`, which your test must include; see [[plutonium-testing]].
+
 ### Intentionally skipping
 
 Rare. Before reaching for this, consider a separate, unscoped portal.
@@ -247,7 +249,7 @@ module AdminPortal
 end
 ```
 
-Routes become `/<mount>/:organization_scoped/posts` (resolving to `/<mount>/42/posts` at request time — the entity id is the first path segment after the mount). Portal extracts `params[:organization_scoped]` and loads the entity automatically. The `_scoped` suffix on the param name avoids colliding with `params[:organization]` from a `belongs_to :organization` on child models.
+Routes become `/<mount>/:organization_scoped/posts` (resolving to `/<mount>/42/posts` at request time; the entity id is the first path segment after the mount). Portal extracts `params[:organization_scoped]` and loads the entity automatically. The `_scoped` suffix on the param name avoids colliding with `params[:organization]` from a `belongs_to :organization` on child models.
 
 ### Custom strategy (subdomain, session, etc.)
 
@@ -279,19 +281,65 @@ scoped_to_entity?
 entity_scope
 ```
 
+## The entity field in permitted attributes
+
+Listing the entity association in the policy is fine, and usually what you want:
+
+```ruby
+def permitted_attributes_for_create
+  [:organization, :name]
+end
+```
+
+In an entity-scoped portal the controller drops the entity field from both the rendered form/display and the accepted params, then sets it from `current_scoped_entity` on create and update. The same policy then works unchanged in an unscoped portal (e.g. admin), where `organization` stays a normal, selectable input. So don't write a portal-specific policy just to remove the entity field, and don't treat its presence as a leak: a forged `organization_id` in the request is overwritten.
+
+What gets removed is the portal's param key plus the scoping association and its `_id` (`organization_scoped`, `organization_scoped_id`, `organization`, `organization_id`). Other associations to the same class are untouched. To show the entity field anyway, override `present_scoped_entity?` on the controller (and `submit_scoped_entity?` to let users change it; it defaults to `present_scoped_entity?`).
+
+## Two associations to the entity class
+
+Example: a `Referral` where the current org refers another org.
+
+```ruby
+class Referral < ResourceRecord
+  belongs_to :organization                                       # the tenant
+  belongs_to :referred_organization, class_name: "Organization"  # a normal input
+
+  # Required: associated_with raises AmbiguousAssociationError without it
+  scope :associated_with_organization, ->(organization) { where(organization:) }
+
+  validates :referred_organization, uniqueness: {scope: :organization_id}
+end
+```
+
+Two pieces of code pick "the" entity association, and both refuse to guess:
+
+- **Controller** (`scoped_entity_association`) raises when the model has more than one `belongs_to` to the entity class, on any scoped page that renders fields. Override it on the portal controller to name the tenant association:
+
+  ```ruby
+  class OrgPortal::ReferralsController < ::ReferralsController
+    private
+
+    def scoped_entity_association = :organization
+  end
+  ```
+
+- **Model** (`associated_with`) raises `Plutonium::Resource::Record::AssociatedWith::AmbiguousAssociationError` when more than one association links the two classes (in either direction) and no `associated_with_<entity>` scope exists. Define that scope (as above); the error message names it.
+
+With both in place, the policy can permit `[:organization, :referred_organization, :note, :status]`: in the org portal `organization` is stripped and forced to the current org, while `referred_organization` stays a select the user fills in.
+
 ## Gotchas
 
-- **Multiple associations to the same entity class.** E.g. `Match belongs_to :home_team, :away_team` both pointing at `Team`. Plutonium raises — override `scoped_entity_association` on the controller to pick one (`def scoped_entity_association = :home_team`).
-- **`param_key` differs from association name.** Fine — Plutonium matches by **class**, not param key. `scope_to_entity Competition::Team, param_key: :team` works with `belongs_to :competition_team`.
-- **Default `param_key` includes `_scoped` suffix.** `scope_to_entity Organization` reads `params[:organization_scoped]` (not `params[:organization]`) so it doesn't collide with `params[:organization]` from a `belongs_to :organization` on child models. The URL itself is unchanged — the entity id is just the first path segment after the mount (`/<mount>/42/posts`). Pass `param_key:` only if you want a different param name in your controllers.
+- **Multiple associations to the same entity class.** E.g. `Match belongs_to :home_team, :away_team` both pointing at `Team`. The controller raises; override `scoped_entity_association` (`def scoped_entity_association = :home_team`) and add an `associated_with_team` scope. See § Two associations to the entity class.
+- **`param_key` differs from association name.** That's fine: Plutonium matches by **class**, not param key. `scope_to_entity Competition::Team, param_key: :team` works with `belongs_to :competition_team`.
+- **Default `param_key` includes `_scoped` suffix.** `scope_to_entity Organization` reads `params[:organization_scoped]` (not `params[:organization]`) so it doesn't collide with `params[:organization]` from a `belongs_to :organization` on child models. The URL itself is unchanged; the entity id is just the first path segment after the mount (`/<mount>/42/posts`). Pass `param_key:` only if you want a different param name in your controllers.
 - **Forgetting compound uniqueness.** `validates :code, uniqueness: true` leaks across tenants. Use `uniqueness: {scope: :organization_id}`.
 - **"Temporary" `where` bypass for debugging.** Use `skip_default_relation_scope!` explicitly. Never leave a `where` bypass in code.
 
 ---
 
-# Part 2 — Nested Resources
+# Part 2: Nested Resources
 
-Plutonium auto-generates nested routes from `has_many` / `has_one` associations on a registered parent. **One level only** — no grandparent → parent → child chains.
+Plutonium auto-generates nested routes from `has_many` / `has_one` associations on a registered parent. **One level only**: no grandparent → parent → child chains.
 
 ## Setup
 
@@ -340,7 +388,7 @@ behaves the same either way, and top-level routes are unaffected.
 
 **Before turning `:declared` on:** it is global, so every resource naming nothing
 loses its nested routes, and a policy's `permitted_associations` panel links to the
-nested route — permit an association there without declaring it here and the panel
+nested route; permit an association there without declaring it here and the panel
 points nowhere.
 
 ## Automatic behavior in nested routes
@@ -370,14 +418,14 @@ current_nested_association  # :properties
 parent_input_param          # :company
 ```
 
-The parent class and association are read from the **route** (each nested route carries its registration key), not inferred from the URL — which is why a `singular: true` parent works as a parent despite contributing no id segment. There is no `parent_route_param`.
+The parent class and association are read from the **route** (each nested route carries its registration key), not inferred from the URL; this is why a `singular: true` parent works as a parent despite contributing no id segment. There is no `parent_route_param`.
 
 ## Parent vs entity scoping
 
-When a parent is present, **parent scoping wins**: `default_relation_scope` scopes via the parent association, not `entity_scope`. The parent was already authorized and entity-scoped during its own authorization — double-scoping isn't needed.
+When a parent is present, **parent scoping wins**: `default_relation_scope` scopes via the parent association, not `entity_scope`. The parent was already authorized and entity-scoped during its own authorization, so double-scoping isn't needed.
 
 ```ruby
-# In the child policy — just call default_relation_scope, it handles both cases
+# In the child policy: just call default_relation_scope; it handles both cases
 relation_scope do |relation|
   default_relation_scope(relation)      # uses parent when present, entity_scope otherwise
 end
@@ -437,7 +485,7 @@ class PropertiesController < ResourceController
 end
 ```
 
-Conditional pattern — show parent only when accessed standalone:
+Conditional pattern: show parent only when accessed standalone:
 
 ```ruby
 def present_parent?
@@ -472,7 +520,7 @@ Auto-include parent: `Companies > Acme Corp > Properties > Property #123`.
 
 ---
 
-# Part 3 — Invites
+# Part 3: Invites
 
 A complete user-invitation system: token-based emails, secure acceptance, Rodauth integration, entity membership creation, and "invitable" hooks for app-specific behavior.
 
@@ -505,11 +553,11 @@ rails generate pu:invites:install
 | `--dest=PACKAGE` | `main_app` | Package where the entity model lives (controls where `invite_user_interaction.rb` is generated) |
 
 ::: 🚨 No `--roles` flag here
-Role list is derived from the membership model's `enum :role`. Set roles via `pu:saas:membership --roles=...` (or edit the enum directly). **Index 0 is the most privileged** — typically `owner`, which the invite UI excludes from selectable choices; new invitees default to the second role (`roles[1]`).
+Role list is derived from the membership model's `enum :role`. Set roles via `pu:saas:membership --roles=...` (or edit the enum directly). **Index 0 is the most privileged**, typically `owner`; the invite UI excludes it from selectable choices, and new invitees default to the second role (`roles[1]`).
 :::
 
 ::: 🚨 ActiveRecord encryption keys required
-The invite model uses `encrypts :token, deterministic: true`. Without configured AR encryption keys, creating or accepting an invite raises `ActiveRecord::Encryption::Errors::Configuration`. The generator detects this and warns at install time — generate keys with `bin/rails db:encryption:init`, then paste the printed `active_record_encryption:` block into `config/credentials.yml.enc` (or set the equivalent `ACTIVE_RECORD_ENCRYPTION_*` ENV vars in production).
+The invite model uses `encrypts :token, deterministic: true`. Without configured AR encryption keys, creating or accepting an invite raises `ActiveRecord::Encryption::Errors::Configuration`. The generator detects this and warns at install time; generate keys with `bin/rails db:encryption:init`, then paste the printed `active_record_encryption:` block into `config/credentials.yml.enc` (or set the equivalent `ACTIVE_RECORD_ENCRYPTION_*` ENV vars in production).
 :::
 
 ### What gets created
@@ -544,7 +592,7 @@ post "invitations/:token/signup",     to: "invites/user_invitations#signup"
 
 ## Multiple invite flows in one app
 
-Run `pu:invites:install` once per flow. Default class name derives as `<EntityModel><UserModel>Invite` — no literal `UserInvite` default. Single-flow apps don't need `--invite-model`.
+Run `pu:invites:install` once per flow. Default class name derives as `<EntityModel><UserModel>Invite`, with no literal `UserInvite` default. Single-flow apps don't need `--invite-model`.
 
 ```bash
 rails g pu:invites:install \
@@ -579,7 +627,7 @@ def invitation_path_for(token)
 end
 ```
 
-## Invitables — app models notified on accept
+## Invitables: app models notified on accept
 
 An "invitable" is an app model that triggers invitations and gets notified when one is accepted. Examples: `Tenant`, `TeamMember`, `ProjectCollaborator`.
 
@@ -737,15 +785,16 @@ Invites are entity-scoped automatically: `Invites::UserInvite belongs_to :entity
 
 ## Common issues
 
-- **"Invite not found"** — token expired (default 1 week), invite cancelled, or no longer `pending`.
-- **Email mismatch** — `enforce_email?` is on by default. The accepting user's email must match the invited email. Override `def enforce_email? = false` only if you fully understand the security trade-off.
-- **Rodauth redirect after login** — make sure `login_redirect "/welcome"` is set in the rodauth plugin.
+- **"Invite not found"**: token expired (default 1 week), invite cancelled, or no longer `pending`.
+- **Email mismatch**: `enforce_email?` is on by default. The accepting user's email must match the invited email. Override `def enforce_email? = false` only if you fully understand the security trade-off.
+- **Rodauth redirect after login**: make sure `login_redirect "/welcome"` is set in the rodauth plugin.
 
 ---
 
 ## Related skills
 
-- [[plutonium-resource]] — model declarations (`belongs_to`, `has_one :through`, custom scopes), `permitted_associations` for show-page tabs.
-- [[plutonium-behavior]] — `relation_scope` syntax, policy authorization context, controller presentation hooks.
-- [[plutonium-app]] — portal setup, `scope_to_entity`, mounting engines.
-- [[plutonium-auth]] — Rodauth signup flow for invite acceptance.
+- [[plutonium-resource]]: model declarations (`belongs_to`, `has_one :through`, custom scopes), `permitted_associations` for show-page tabs.
+- [[plutonium-behavior]]: `relation_scope` syntax, policy authorization context, controller presentation hooks.
+- [[plutonium-app]]: portal setup, `scope_to_entity`, mounting engines.
+- [[plutonium-auth]]: Rodauth signup flow for invite acceptance.
+- [[plutonium-testing]]: integration tests for scoped portals, `login_as` via `Plutonium::Testing::AuthHelpers`.

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

@@ -1,6 +1,6 @@
 ---
 name: plutonium-testing
-description: Use BEFORE writing tests for a Plutonium resource, running pu:test:scaffold, or including Plutonium::Testing::* concerns. Covers the full testing toolkit — CRUD, policy, definition, interaction, model, nested, portal access, and auth helpers.
+description: 'Use BEFORE writing tests for a Plutonium resource, running pu:test:scaffold, or including Plutonium::Testing::* concerns. Covers the full testing toolkit: CRUD, policy, definition, interaction, model, nested, portal access, and auth helpers.'
 ---
 
 # Plutonium Testing
@@ -8,45 +8,46 @@ description: Use BEFORE writing tests for a Plutonium resource, running pu:test:
 ## 🚨 Critical (read first)
 
 - **Use the generators.** `pu:test:install` once per app, then `pu:test:scaffold ResourceClass --portals=...` per resource × portal. Hand-written test files drift from conventions.
-- **Tests are opt-in.** `Plutonium::Testing` is only loaded when `require "plutonium/testing"` runs — it's never autoloaded, never present in production.
+- **Tests are opt-in.** `Plutonium::Testing` is only loaded when `require "plutonium/testing"` runs; it's never autoloaded, never present in production.
 - **One file per (resource × portal).** Same model in admin and org portals = two test files. Each portal has different auth, scoping, and allowed actions.
-- **Stub methods are required.** Concerns ship with `NotImplementedError` stubs — your test class supplies the test data via `create_resource!`, `valid_create_params`, `policy_roles`, etc.
+- **Stub methods are required.** Concerns ship with `NotImplementedError` stubs: your test class supplies the test data via `create_resource!`, `valid_create_params`, `policy_roles`, etc.
 
 ---
 
-## 🛑 Before you scaffold tests: confirm the shape (ASK — don't infer)
+## 🛑 Before you scaffold tests: confirm the shape (ASK: don't infer)
 
-"Write tests for X" leaves out what actually drives the files. Resolve each — confirming by inspection (next section):
+"Write tests for X" leaves out what actually drives the files. Resolve each, confirming by inspection (next section):
 
-1. **Which concerns?** `crud` / `policy` / `definition` / `model` / `nested` / `interaction` / `portal_access`. Don't scaffold all blindly — pick what the resource needs.
-2. **Which portals?** **One file per (resource × portal)** — each has different auth, scoping, and allowed actions. A resource in admin + org ⇒ two files.
-3. **Nested?** A child resource needs `--parent=` **and** a real `parent_record!` stub.
+1. **Which concerns?** `crud` / `policy` / `definition` / `model` / `nested` / `interaction` / `portal_access`. Don't scaffold all blindly, pick what the resource needs.
+2. **Which portals?** **One file per (resource × portal)**: each has different auth, scoping, and allowed actions. A resource in admin + org ⇒ two files.
+3. **Nested or entity-scoped?** If the portal calls `scope_to_entity Model, strategy: :path` (e.g. `/org/:id/...`), any "records from another tenant aren't reachable" requirement is the `NestedResource` concern with the entity as the parent: scaffold with `--concerns=crud,nested --parent=organization`. `--parent` alone does not add the `NestedResource` include. See [Entity-scoped portals](#entity-scoped-portals-crud--tenant-isolation) for the two-class layout this needs.
 4. **Auth flavor.** Rodauth (the default `login_as` POSTs the hardcoded `password123`) or custom (override `sign_in_for_tests`)?
 
-**Never ship a guessed policy matrix, factory name, or field list** — read the model/definition/policy for the real actions, roles, and fields before filling stubs.
+**Never ship a guessed policy matrix, factory name, or field list**: read the model/definition/policy for the real actions, roles, and fields before filling stubs.
 
-## ✅ Before you scaffold: verify the ground truth (CHECK — read it, don't ask for it)
+## ✅ Before you scaffold: verify the ground truth (CHECK: read it, don't ask for it)
 
-You have file access — **inspect**; don't ask the user to describe their setup.
+You have file access: **inspect**; don't ask the user to describe their setup.
 
 | Check | How | Why it matters |
 |---|---|---|
-| Harness installed | grep `test/test_helper.rb` for `require "plutonium/testing"` | Concerns never autoload — run `pu:test:install` first |
+| Harness installed | grep `test/test_helper.rb` for `require "plutonium/testing"` | Concerns never autoload; run `pu:test:install` first |
 | Resource exposed in each named portal | The resource is `register_resource`'d in each portal | `--portals=` must match mounted engines |
 | Portal engine names | `:admin` ⇒ `AdminPortal::Engine` | Mismatch ⇒ pass `path_prefix:` explicitly |
 | Login password | Test accounts seeded with `password123` (fixtures/factories) | `login_as` POSTs that hardcoded value, or use `sign_in_for_tests` |
 | Tenant binding | `create_resource!`/`policy_record` return `@tenant`-bound records | Else scope tests pass for the wrong reason |
+| Entity strategy | grep the portal's `lib/engine.rb` for `scope_to_entity` | `:path` strategy ⇒ the resolved prefix is the bare mount (`/org`), so CRUD needs a `current_path_prefix` override and tenant isolation needs `NestedResource` |
 
 Inspect with your own tools **before** scaffolding.
 
-## 🛠 Use the generator — fill the stubs, don't hand-write
+## 🛠 Use the generator: fill the stubs, don't hand-write
 
 | Task | Generator | Verify first |
 |---|---|---|
 | Install harness (once per app) | `pu:test:install` | Not already in `test_helper.rb` |
 | Scaffold tests | `pu:test:scaffold Klass --portals=… --concerns=…` | Harness installed; resource exposed in those portals |
 
-Hand-written test files drift from conventions — scaffold, then fill the `NotImplementedError` stubs with tenant-correct data.
+Hand-written test files drift from conventions; scaffold, then fill the `NotImplementedError` stubs with tenant-correct data.
 
 ---
 
@@ -126,6 +127,11 @@ class AdminPortal::BloggingPostsTest < ActionDispatch::IntegrationTest
 end
 ```
 
+**`valid_update_params` is also the assertion.** After the PATCH, the update test runs `assert_equal value, record.reload.public_send(attr)` for every key. So:
+
+- Use values that read back identically: enums as strings (`status: "published"`, since the enum reader returns a String and `:published` would fail).
+- Keep association SGIDs out of it. The loop only skips values starting with `gid://`, but `to_sgid.to_s` is a signed token, so it would compare the token to the associated record and fail. Reassigning an association belongs in its own `test` block that PATCHes the SGID and asserts `record.reload.user == other_user`. `valid_create_params` has no such check, so SGIDs are fine there.
+
 ### `Plutonium::Testing::ResourcePolicy`
 
 Asserts the `permit?` matrix across action × role and verifies `relation_scope` returns an `ActiveRecord::Relation`.
@@ -145,6 +151,8 @@ def policy_matrix = {
 }
 ```
 
+Each role lambda is `instance_exec`'d inside the test, once per (action × role), so returning accounts built in `setup` is the intended shape. A lambda that calls `create_user!` would mint a new account on every call, without the membership a tenant-scoped policy checks. Read the policy for the real answers: the matrix above is an example, not a default.
+
 ### `Plutonium::Testing::ResourceDefinition`
 
 Smoke-tests the resource definition: the class is constantize-able, every defineable prop dictionary (fields/inputs/displays/columns/scopes/filters/sorts/actions) is queryable, and declared fields exist on the model.
@@ -158,18 +166,31 @@ Outcome-assertion helpers for `Plutonium::Interaction::Base` subclasses.
 **Helpers:**
 - `assert_interaction_success(klass, **input)` → returns the success outcome
 - `assert_interaction_failure(klass, **input)` → returns the failure outcome
-- `interaction_view_context` (overridable) → defaults to a mock view context
+- `interaction_view_context` (overridable) → the view context both helpers pass in; override it only when the interaction reads something from the view context
+
+Use the helpers for both outcomes; they build the interaction and call it for you.
 
 ```ruby
-test "RebuildSearchInteraction succeeds" do
-  outcome = assert_interaction_success(RebuildSearchInteraction, since: 1.day.ago)
-  assert_equal 42, outcome.value[:rebuilt_count]
+test "PublishProduct moves a draft to active" do
+  product = create_product!(status: :draft)
+  assert_interaction_success(Catalog::PublishProduct, resource: product)
+  assert product.reload.active?
+end
+
+test "PublishProduct fails for a product that isn't a draft" do
+  product = create_product!(status: :active)
+  assert_interaction_failure(Catalog::PublishProduct, resource: product)
+  assert product.reload.active?   # state unchanged
 end
 ```
 
+The failure outcome carries no validation errors (they live on the interaction instance), so assert the unchanged state rather than building the interaction by hand to read `errors`.
+
+`ResourceInteraction` includes neither the DSL nor `AuthHelpers`. A file scaffolded with only `--concerns=interaction` still has the template's `resource_tests_for` and `login_as(@account)`, which raise `NoMethodError`: delete both (the helpers need no portal and no login).
+
 ### `Plutonium::Testing::ResourceModel`
 
-Tests `associated_with` scope, SGID routing, and `has_cents` accessors — gated by DSL flags.
+Tests `associated_with` scope, SGID routing, and `has_cents` accessors, gated by DSL flags.
 
 **Stubs:**
 - `model_test_record` → persisted record
@@ -190,13 +211,77 @@ Only the flagged features generate tests.
 Asserts CRUD under a parent + scope-boundary tests (sibling tenants invisible).
 
 **Stubs:**
-- `parent_record!` → current tenant
+- `parent_record!` → current tenant (called several times per test, so return the same record each time, e.g. `@org`)
 - `other_parent_record!` → sibling tenant
 - `create_resource!(parent:)` → persisted record under given parent
 
+The concern builds its URLs as `"#{current_path_prefix}/#{parent.id}/#{collection}"`, so it expects the bare portal mount as the prefix and inserts the parent id itself.
+
+#### Entity-scoped portals: CRUD + tenant isolation
+
+In a `strategy: :path` portal, the two concerns need different prefixes and different `create_resource!` signatures:
+
+| | `ResourceCrud` | `NestedResource` |
+|---|---|---|
+| URL built | `prefix/collection` | `prefix/parent.id/collection` |
+| Prefix needed | `/org/#{@org.to_param}` (override `current_path_prefix`) | `/org` (the resolved default) |
+| Calls | `create_resource!` | `create_resource!(parent:)` |
+
+One class can't satisfy both, so split the scaffolded file into two classes:
+
+```bash
+rails g pu:test:scaffold Catalog::Variant --portals=org --concerns=crud,nested --parent=organization
+```
+
+```ruby
+class OrgPortal::CatalogVariantTest < ActionDispatch::IntegrationTest
+  include IntegrationTestHelper
+  include Plutonium::Testing::ResourceCrud
+
+  resource_tests_for Catalog::Variant, portal: :org
+
+  setup do
+    @org = create_organization!
+    @user = create_user!
+    create_membership!(organization: @org, user: @user)
+    @product = create_product!(user: @user, organization: @org)
+    login_as(@user)                       # :org logs in through /users/login
+  end
+
+  def current_path_prefix = "/org/#{@org.to_param}"
+  def create_resource! = create_variant!(product: @product)
+  def valid_create_params = {name: "Red", sku: "RED-1", stock_count: 5, product: @product.to_sgid.to_s}
+  def valid_update_params = {name: "Red / Large"}
+end
+
+class OrgPortal::CatalogVariantNestedTest < ActionDispatch::IntegrationTest
+  include IntegrationTestHelper
+  include Plutonium::Testing::NestedResource
+
+  resource_tests_for Catalog::Variant, portal: :org, parent: :organization
+
+  setup do
+    @org = create_organization!
+    @other_org = create_organization!
+    @user = create_user!
+    create_membership!(organization: @org, user: @user)
+    login_as(@user)
+  end
+
+  def parent_record! = @org
+  def other_parent_record! = @other_org
+
+  def create_resource!(parent:)
+    create_variant!(product: create_product!(organization: parent))
+  end
+end
+```
+
+`create_resource!(parent:)` must create under `parent`, not always under `@org`: the isolation test passes `other_parent_record!` and expects a 404 (or redirect) for that record.
+
 ### `Plutonium::Testing::PortalAccess`
 
-Cross-portal access boundaries. Uses its own DSL — not `resource_tests_for`.
+Cross-portal access boundaries. Uses its own DSL, not `resource_tests_for`.
 
 ```ruby
 class PortalAccessTest < ActionDispatch::IntegrationTest
@@ -233,7 +318,16 @@ Generates one test per (role × portal). Allowed = `200|302`; blocked = `302|401
 
 ## Auth helpers
 
-`Plutonium::Testing::AuthHelpers` is included transitively by every concern.
+`login_as` and friends come from `Plutonium::Testing::AuthHelpers`, which only some concerns pull in. The default portal comes from the DSL (`resource_tests_for`), which is a separate include:
+
+| Concern | `login_as` available | Bare `login_as(account)` works |
+|---|---|---|
+| `ResourceCrud`, `NestedResource` | yes | yes (portal from `resource_tests_for`) |
+| `PortalAccess` | yes | no: pass `portal:` every time |
+| `ResourcePolicy`, `ResourceDefinition`, `ResourceModel` | no | no |
+| `ResourceInteraction` | no | no |
+
+A hand-written integration test that only includes the app's own helpers (e.g. an `IntegrationTestHelper`) has no `login_as` at all. Add `include Plutonium::Testing::AuthHelpers` (and `require "plutonium/testing"` if `test_helper.rb` doesn't) and pass `portal:` explicitly. Likewise, delete the scaffold's `login_as(@account)` from a file whose concerns don't provide it.
 
 ```ruby
 login_as(account)                          # uses portal from DSL
@@ -245,7 +339,7 @@ current_account(portal: :admin)
 with_portal(:org) { ... }                  # scoped portal switch
 ```
 
-**Default Rodauth login expects `password: "password123"`** — `login_as` POSTs to `/<account_table>/login` with that hardcoded password. Either seed test accounts with it (fixtures/factories) or override via `sign_in_for_tests` below.
+**Default Rodauth login expects `password: "password123"`.** `login_as` POSTs to `/<account_table>/login` with that hardcoded password. The table comes from the portal: `:admin` ⇒ `/admins/login`, `:user` and `:org` ⇒ `/users/login`, anything else is pluralized (`:locus` ⇒ `/locus/login`), so log org members in with `portal: :user` from portals that aren't named `:org`. Either seed test accounts with it (fixtures/factories) or override via `sign_in_for_tests` below.
 
 **Override hook for non-Rodauth apps (or to bypass Rodauth in tests):** define `sign_in_for_tests(account, portal:)` in your test class (or in `test/support/plutonium_testing.rb` for project-wide use). `AuthHelpers` will defer to it.
 
@@ -278,16 +372,18 @@ rails g pu:test:scaffold Blogging::Post --portals=org --parent=organization --de
 |---|---|---|
 | `--portals=admin,org` | required | Emit one file per portal |
 | `--concerns=...` | `crud,policy,definition` | Concerns to include (`crud,policy,definition,nested,model,interaction,portal_access`) |
-| `--parent=organization` | none | Wires `NestedResource` parent |
+| `--parent=organization` | none | Adds `parent:` to `resource_tests_for` and, only together with `nested` in `--concerns`, the `parent_record!`/`other_parent_record!` stubs |
 | `--dest=main_app\|<package>` | `main_app` | Output destination |
 
 Output path: `test/integration/<portal>_portal/<resource_underscored>_test.rb`.
 
+The template is one class with every requested include, a `setup` that calls `login_as(@account)`, and a no-argument `create_resource!`. Treat it as a starting point: drop `login_as`/`resource_tests_for` where the concerns don't provide them (see Auth helpers), and split `crud` and `nested` into two classes for entity-scoped portals.
+
 ## Customization & escape hatches
 
 - **Skip individual tests:** `resource_tests_for Klass, portal: :admin, skip: %i[destroy]`
 - **Restrict action set:** `resource_tests_for Klass, portal: :admin, actions: %i[index show]`
-- **Custom assertions:** add regular `test "..."` blocks alongside the generated matrix — they coexist.
+- **Custom assertions:** add regular `test "..."` blocks alongside the generated matrix; they coexist.
 - **Non-Rodauth auth:** override `sign_in_for_tests`. See AuthHelpers section.
 - **Custom path prefix:** `path_prefix: "/v2/admin"` overrides portal resolution.
 
@@ -296,14 +392,15 @@ Output path: `test/integration/<portal>_portal/<resource_underscored>_test.rb`.
 - **Forgotten stubs raise `NotImplementedError`** with the stub name. Look for the missing method in your test class.
 - **Portal mismatch:** `:admin` portal expects `AdminPortal::Engine` constant. If your portal is named differently, pass `path_prefix:` explicitly.
 - **Tenant leakage in stubs:** `create_resource!` for an org portal must return a record bound to the test's `@org`. Otherwise scope filtering tests will pass for the wrong reason.
-- **`policy_record` for tenant-scoped resources** must belong to a tenant the role has access to — otherwise even allowed roles will see `false`.
-- **Nested resources need `parent: :foo`** in the DSL AND a real parent record from `parent_record!`. Without both, path interpolation fails.
-- **`PortalAccess` doesn't use `resource_tests_for`** — use `portal_access_for` instead. Mixing them on the same class is undefined behavior.
+- **`policy_record` for tenant-scoped resources** must belong to a tenant the role has access to; otherwise even allowed roles will see `false`.
+- **Nested paths come from `parent_record!.id`**, so it must return a real, persisted tenant the logged-in account belongs to. `parent: :foo` in the DSL documents the relationship; the concern doesn't read it.
+- **Entity-scoped CRUD hitting `/org/<collection>`** (404 or routing error): a `:path` portal resolves to the bare mount, so override `current_path_prefix` to include the tenant. Don't do this in a `NestedResource` class, which adds the id itself.
+- **`PortalAccess` doesn't use `resource_tests_for`**: use `portal_access_for` instead. Mixing them on the same class is undefined behavior.
 
 ## Related skills
 
-- [[plutonium-behavior]] — policies (verified by `ResourcePolicy`), interactions (asserted by `ResourceInteraction`)
-- [[plutonium-resource]] — definition props the smoke test introspects (`field`, `input`, `display`, `column`, `scope`, `filter`, `sort`, `action`)
-- [[plutonium-tenancy]] — `relation_scope`, parent scoping, nested resources (matched by `NestedResource`)
-- [[plutonium-app]] — portal mounting and entity strategies that drive auth/scoping
-- [[plutonium-auth]] — Rodauth setup behind the default login flow
+- [[plutonium-behavior]]: policies (verified by `ResourcePolicy`), interactions (asserted by `ResourceInteraction`)
+- [[plutonium-resource]]: definition props the smoke test introspects (`field`, `input`, `display`, `column`, `scope`, `filter`, `sort`, `action`)
+- [[plutonium-tenancy]]: `relation_scope`, parent scoping, nested resources (matched by `NestedResource`)
+- [[plutonium-app]]: portal mounting and entity strategies that drive auth/scoping
+- [[plutonium-auth]]: Rodauth setup behind the default login flow