plutonium 0.65.0 → 0.66.0

data/docs/guides/multi-tenancy.md

@@ -8,15 +8,15 @@ Each tenant sees only their own records. Queries are filtered, forms inject the
 
 ## 🚨 Critical
 
-- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins triggers `verify_default_relation_scope_applied!` at runtime. Make sure `default_relation_scope(relation)` is called somewhere in the chain — explicitly here, or via `super(relation)` (the framework's `Plutonium::Resource::Policy` base calls it for you).
+- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins triggers `verify_default_relation_scope_applied!` at runtime. Make sure `default_relation_scope(relation)` is called somewhere in the chain: explicitly here, or via `super(relation)` (the framework's `Plutonium::Resource::Policy` base calls it for you).
 - **Always declare an association path from the model to the entity.** Direct `belongs_to`, `has_one :through`, or a custom `associated_with_<entity>` scope. If `associated_with` can't resolve, fix the **model**, not the policy.
-- **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.
 
 After login, users with memberships in multiple entities land on a workspace selector:
 
 ![Workspace selector after login](/images/guides/multi-tenancy-welcome.png)
 
-Picking one lands them on the entity-scoped dashboard — note the entity slug in the URL:
+Picking one lands them on the entity-scoped dashboard: note the entity slug in the URL:
 
 ![Tenant-scoped dashboard](/images/guides/multi-tenancy-dashboard.png)
 
@@ -62,14 +62,17 @@ end
 
 Or pass `--scope=Organization` to `pu:pkg:portal` and the engine wires this automatically.
 
-### 4. Mount the portal
+### 4. Check the mount
+
+`pu:pkg:portal` already mounted the engine in `packages/customer_portal/config/routes.rb`:
 
 ```ruby
-# config/routes.rb
 mount CustomerPortal::Engine, at: "/customer"
 ```
 
-URLs now include the entity id as the first path segment after the mount: `/customer/42/posts`. The underlying param name is `organization_scoped` (Plutonium suffixes `_scoped` to avoid a name collision with any `belongs_to :organization` on child models — `params[:organization_scoped]` vs `params[:organization]`). Pass `param_key:` to `scope_to_entity` if you want a different param name.
+To change the path, edit `at:` there. Don't add a second `mount` to `config/routes.rb`; Rails raises `Invalid route name, already in use`.
+
+URLs now include the entity id as the first path segment after the mount: `/customer/42/posts`. The underlying param name is `organization_scoped` (Plutonium suffixes `_scoped` to avoid a name collision with any `belongs_to :organization` on child models: `params[:organization_scoped]` vs `params[:organization]`). Pass `param_key:` to `scope_to_entity` if you want a different param name.
 
 ### 5. Compound uniqueness
 
@@ -82,6 +85,10 @@ end
 
 🚨 Without the `scope:`, the same slug in different orgs would collide.
 
+### 6. Leave the entity in the policy
+
+`organization` can stay in `permitted_attributes_for_create`. In the scoped portal the controller removes it from the form and params and sets it from the current entity (a forged `organization_id` is overwritten), while an unscoped admin portal using the same policy still gets a normal select.
+
 ## Strategies
 
 ### Path strategy (default)
@@ -143,7 +150,7 @@ class Membership < ResourceRecord
 end
 ```
 
-### 3. Grandchild — `has_one :through`
+### 3. Grandchild: `has_one :through`
 
 ```ruby
 class Post < ResourceRecord
@@ -187,9 +194,9 @@ relation_scope do |relation|
 end
 ```
 
-🚨 `default_relation_scope(relation)` must be called somewhere in the chain — otherwise the runtime verification raises. `super(relation)` works when extending `Plutonium::Resource::Policy` directly (its block calls `default_relation_scope`); call `default_relation_scope` by name when you're not chaining via `super`.
+🚨 `default_relation_scope(relation)` must be called somewhere in the chain, otherwise the runtime verification raises. `super(relation)` works when extending `Plutonium::Resource::Policy` directly (its block calls `default_relation_scope`); call `default_relation_scope` by name when you're not chaining via `super`.
 
-## Cross-tenant operations — super-admin portal
+## Cross-tenant operations: super-admin portal
 
 Create a separate portal **without** `scope_to_entity`:
 
@@ -197,7 +204,7 @@ Create a separate portal **without** `scope_to_entity`:
 module SuperAdminPortal
   class Engine < Rails::Engine
     include Plutonium::Portal::Engine
-    # No scope_to_entity — sees all tenants
+    # No scope_to_entity: sees all tenants
   end
 end
 ```
@@ -206,14 +213,14 @@ This portal's policies see everything. Don't enable public signup here.
 
 ## Multiple associations to the same entity
 
-If a model has two `belongs_to` to the entity class (e.g. `Match belongs_to :home_team, :away_team`), Plutonium raises:
+If a model has two `belongs_to` to the entity class (e.g. `Match belongs_to :home_team, :away_team`), the controller raises:
 
 ```
 Match has multiple associations to Competition::Team: home_team, away_team.
 Plutonium cannot auto-detect which one to use for entity scoping.
 ```
 
-Override on the controller:
+Override on the portal controller:
 
 ```ruby
 class MatchesController < ::ResourceController
@@ -222,18 +229,24 @@ class MatchesController < ::ResourceController
 end
 ```
 
+Query scoping (`associated_with`) raises `AmbiguousAssociationError` too, so add an explicit scope on the model:
+
+```ruby
+scope :associated_with_competition_team, ->(team) { where(home_team: team) }
+```
+
 ## Common issues
 
-- **`verify_default_relation_scope_applied!` raises** — your custom `relation_scope` doesn't call `default_relation_scope(relation)`. Fix by composing: `default_relation_scope(relation).where(...)`.
-- **`Could not resolve the association between 'Model' and 'Entity'`** — the model has no path to the entity. Fix on the **model** (declare `has_one :through` or a custom `associated_with_<entity>` scope). Never paper over with `where` in the policy.
-- **Records leak across tenants** — likely a missing compound-uniqueness scope on the model. Add `validates :code, uniqueness: {scope: :organization_id}`.
-- **Forms show the entity field anyway** — check `present_scoped_entity?` / `submit_scoped_entity?` on the controller (defaults are `false`).
-- **Want to bypass scoping in one place** — use `skip_default_relation_scope!` explicitly, NOT a silent `where` bypass.
+- **`verify_default_relation_scope_applied!` raises**: your custom `relation_scope` doesn't call `default_relation_scope(relation)`. Fix by composing: `default_relation_scope(relation).where(...)`.
+- **`Could not resolve the association between 'Model' and 'Entity'`**: the model has no path to the entity. Fix on the **model** (declare `has_one :through` or a custom `associated_with_<entity>` scope). Never paper over with `where` in the policy.
+- **Records leak across tenants**: likely a missing compound-uniqueness scope on the model. Add `validates :code, uniqueness: {scope: :organization_id}`.
+- **Forms show the entity field anyway**: check `present_scoped_entity?` / `submit_scoped_entity?` on the controller (defaults are `false`).
+- **Want to bypass scoping in one place**: use `skip_default_relation_scope!` explicitly, NOT a silent `where` bypass.
 
 ## Related
 
-- [Reference › Tenancy › Entity scoping](/reference/tenancy/entity-scoping) — full surface
-- [Reference › Behavior › Policies](/reference/behavior/policies) — `relation_scope` syntax
-- [Reference › App › Portals](/reference/app/portals) — `scope_to_entity` engine config
-- [Nested resources](./nested-resources) — parent scoping (takes precedence over entity scoping)
-- [User invites](./user-invites) — invitation-based membership onboarding
+- [Reference › Tenancy › Entity scoping](/reference/tenancy/entity-scoping): full surface
+- [Reference › Behavior › Policies](/reference/behavior/policies): `relation_scope` syntax
+- [Reference › App › Portals](/reference/app/portals): `scope_to_entity` engine config
+- [Nested resources](./nested-resources): parent scoping (takes precedence over entity scoping)
+- [User invites](./user-invites): invitation-based membership onboarding

data/docs/guides/nested-resources.md

@@ -11,7 +11,7 @@ Set up parent/child relationships so `/companies/:id/nested_properties` works au
 - Forms that auto-fill the parent (no manual hidden field).
 - Queries scoped to the parent (sibling companies' properties invisible).
 
-All of this happens with no manual route wiring — Plutonium generates it from the association.
+All of this happens with no manual route wiring; Plutonium generates it from the association.
 
 ## Steps
 
@@ -65,7 +65,7 @@ Plutonium prefixes nested routes with `nested_` so they don't conflict with top-
 | `/companies/:company_id/nested_company_profile` | `has_one` show (no `:id`) |
 | `/companies/:company_id/nested_company_profile/new` | `has_one` new |
 
-`has_one` associations get singular routes — index redirects to show (or new if no record exists).
+`has_one` associations get singular routes: index redirects to show (or new if no record exists).
 
 Every routable association gets one by default. To draw only some of them:
 
@@ -149,7 +149,7 @@ end
 ```
 
 ::: warning Always pass `as:`
-Without `as:`, `resource_url_for(property, parent: company, action: :analytics)` fails — no named route to look up.
+Without `as:`, `resource_url_for(property, parent: company, action: :analytics)` fails: no named route to look up.
 :::
 
 ## Policy authorization context
@@ -167,13 +167,13 @@ class PropertyPolicy < ResourcePolicy
 end
 ```
 
-The parent is authorized for `:read?` before `current_parent` returns — children inherit the parent's access requirements.
+The parent is authorized for `:read?` before `current_parent` returns; children inherit the parent's access requirements.
 
 ## Parent scoping 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 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 entity-scoped during its own authorization; double-scoping isn't needed.
 
-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:
 
 ```ruby
 relation_scope do |relation|
@@ -194,7 +194,7 @@ For deeper hierarchies, use top-level routes plus association tabs on the show p
 
 ## Nested inputs (sub-records inside a parent form)
 
-A different feature with a confusingly similar name. **Nested *resources*** (above) give you separate URLs for the child collection. **Nested *inputs*** let you edit child records inline inside the parent's form — a single submit creates/updates/deletes them in one go, backed by Rails' `accepts_nested_attributes_for`.
+A different feature with a confusingly similar name. **Nested *resources*** (above) give you separate URLs for the child collection. **Nested *inputs*** let you edit child records inline inside the parent's form: a single submit creates/updates/deletes them in one go, backed by Rails' `accepts_nested_attributes_for`.
 
 Use nested inputs when the children are conceptually part of the parent (line items on an order, variants on a product, contact methods on a person) and don't deserve their own page.
 
@@ -214,7 +214,7 @@ class PostDefinition < ResourceDefinition
   end
 end
 
-# Policy — list the association name (NOT `comments_attributes`)
+# Policy: list the association name (NOT `comments_attributes`)
 class PostPolicy < ResourcePolicy
   def permitted_attributes_for_create
     [:title, :body, :comments]
@@ -223,7 +223,7 @@ end
 ```
 
 ::: warning Permit the association, not the strong-params shape
-List `:comments` in `permitted_attributes_for_*` — Plutonium translates it to `comments_attributes: [...]` for you. If you write the raw hash, the form renders the field name as a literal label instead of the nested editor.
+List `:comments` in `permitted_attributes_for_*`: Plutonium translates it to `comments_attributes: [...]` for you. If you write the raw hash, the form renders the field name as a literal label instead of the nested editor.
 :::
 
 ### Result
@@ -251,13 +251,13 @@ nested_input :profile,  macro: :has_one   # singular sub-form, no Add button
 
 | | Nested inputs (`nested_input :comments`) | Nested resources (this guide's main topic) |
 |---|---|---|
-| URL | None — inline in parent form | `/posts/:id/nested_comments` |
-| Submit | One — saves parent + children together | Independent CRUD per child |
+| URL | None, inline in parent form | `/posts/:id/nested_comments` |
+| Submit | One, saves parent + children together | Independent CRUD per child |
 | Discoverability | Always visible in parent form | Tab on parent show page (with `permitted_associations`) |
 | Best for | Tightly-owned children (line items, variants) | Children users browse on their own (orders, posts) |
 | Backing | `accepts_nested_attributes_for` | Plutonium's nested controller routing |
 
-You can use both on the same association — they're not mutually exclusive.
+You can use both on the same association; they're not mutually exclusive.
 
 ## Inline `+` add on the parent form
 
@@ -265,15 +265,15 @@ When a form has an association select (e.g. picking the company on a Property fo
 
 ## Common issues
 
-- **Nested route doesn't exist** — both parent AND child must be registered in the same portal (`pu:res:conn`).
-- **Parent shows up in the form anyway** — check `present_parent?` / `submit_parent?` on the controller. Default is to hide on nested routes.
-- **Multiple `belongs_to` to the same parent class** (e.g. `Match belongs_to :home_team, :away_team`) — Plutonium raises. Override `scoped_entity_association` to specify. See [Reference › Tenancy › Entity scoping](/reference/tenancy/entity-scoping#multiple-associations-to-the-same-entity-class).
-- **`resource_url_for` returns wrong URL for a nested resource** — check that custom routes use `as:`.
+- **Nested route doesn't exist**: both parent AND child must be registered in the same portal (`pu:res:conn`).
+- **Parent shows up in the form anyway**: check `present_parent?` / `submit_parent?` on the controller. Default is to hide on nested routes.
+- **Multiple `belongs_to` to the same parent class** (e.g. `Match belongs_to :home_team, :away_team`): give the parent one `has_many` per side (`has_many :home_matches, class_name: "Match", foreign_key: :home_team_id`). Each becomes its own nested route, and Plutonium fills in the matching `belongs_to` through `inverse_of` or the foreign key, so nothing raises. `scoped_entity_association` only matters when the parent class is also the portal's entity; see [Reference › Tenancy › Entity scoping](/reference/tenancy/entity-scoping#multiple-associations-to-the-same-entity-class).
+- **`resource_url_for` returns wrong URL for a nested resource**: check that custom routes use `as:`.
 
 ## Related
 
-- [Reference › Tenancy › Nested resources](/reference/tenancy/nested-resources) — full surface
-- [Reference › Behavior › Controllers](/reference/behavior/controllers) — `current_parent`, presentation hooks
-- [Reference › Behavior › Policies](/reference/behavior/policies#association-permissions) — `permitted_associations`
-- [Multi-tenancy](./multi-tenancy) — how entity scoping interacts with parent scoping
-- [Adding resources](./adding-resources) — basic resource setup
+- [Reference › Tenancy › Nested resources](/reference/tenancy/nested-resources): full surface
+- [Reference › Behavior › Controllers](/reference/behavior/controllers): `current_parent`, presentation hooks
+- [Reference › Behavior › Policies](/reference/behavior/policies#association-permissions): `permitted_associations`
+- [Multi-tenancy](./multi-tenancy): how entity scoping interacts with parent scoping
+- [Adding resources](./adding-resources): basic resource setup

data/docs/guides/performance.md

@@ -20,7 +20,7 @@ Index pages, kanban boards and CSV exports already eager-load the associations a
 
 Each rendering passes its own field set, because they differ: the index renders its permitted attributes, an export renders `permitted_attributes_for_export`, and a kanban card renders its `card_fields`.
 
-It covers every association kind — `belongs_to`, `has_one`, `has_many` — and attachments on both ActiveStorage and Shrine.
+It covers every association kind (`belongs_to`, `has_one`, `has_many`) and attachments on both ActiveStorage and Shrine.
 
 Turn it off globally:
 
@@ -99,6 +99,6 @@ Those need to leave the request rather than be optimised inside it. An interacti
 
 ## Related
 
-- **Search fallback.** A resource with no `search` block falls back to a leading-wildcard `LIKE`, which cannot use a b-tree index. Write an explicit `search` block for large tables — see [Resource › Query](/reference/resource/query#search).
+- **Search fallback.** A resource with no `search` block falls back to a leading-wildcard `LIKE`, which cannot use a b-tree index. Write an explicit `search` block for large tables; see [Resource › Query](/reference/resource/query#search).
 - **Page size.** Query cost scales with rows per page.
-- [Async Interactions](/reference/behavior/async-interactions) — moving slow work out of the request
+- [Async Interactions](/reference/behavior/async-interactions): moving slow work out of the request

data/docs/guides/search-filtering.md

@@ -28,7 +28,7 @@ All declared in the definition.
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  # Search box — searches title and body
+  # Search box: searches title and body
   search do |scope, query|
     scope.where("title ILIKE :q OR body ILIKE :q", q: "%#{query}%")
   end
@@ -81,7 +81,7 @@ end
 
 When an association input targets this resource, the dropdown's autocomplete calls the resource's `search` block. Same code, two surfaces.
 
-### Without a `search` block — typeahead fallback
+### Without a `search` block: typeahead fallback
 
 The framework falls back to a case-insensitive `LIKE` on the first column it finds, in priority order:
 
@@ -89,7 +89,7 @@ The framework falls back to a case-insensitive `LIKE` on the first column it fin
 2. Otherwise the first match from `[name, title, label, slug, display_name, email]`.
 3. Otherwise the relation is returned unfiltered (capped).
 
-For large tables, write an explicit `search` block — the leading-wildcard `LIKE` can't use a b-tree index. See [Reference › Resource › Query › Search](/reference/resource/query#search).
+For large tables, write an explicit `search` block: the leading-wildcard `LIKE` can't use a b-tree index. See [Reference › Resource › Query › Search](/reference/resource/query#search).
 
 ## Filters
 
@@ -154,7 +154,7 @@ class PostDefinition < ResourceDefinition
   scope :published    # uses Post.published
   scope :draft        # uses Post.draft
 
-  # Inline scope — block runs with scope as argument
+  # Inline scope: block runs with scope as argument
   scope(:recent) { |s| s.where('created_at > ?', 1.week.ago) }
 
   # Scope with controller context
@@ -206,9 +206,9 @@ Query params are namespaced under `q`:
 ## Performance tips
 
 - **Add indexes** for filtered and sorted columns.
-- **Use `.distinct`** when joining associations in search — duplicate rows otherwise.
+- **Use `.distinct`** when joining associations in search: duplicate rows otherwise.
 - **Prefer scopes over filters** for queries used often (no input parsing).
-- **`LIKE '%q%'` can't use a b-tree index** — for large tables, use `pg_search` or a trigram/GIN/full-text index.
+- **`LIKE '%q%'` can't use a b-tree index**: for large tables, use `pg_search` or a trigram/GIN/full-text index.
 
 ## Full-text search with `pg_search`
 
@@ -227,13 +227,13 @@ end
 
 ## Common issues
 
-- **Filter not showing up** — make sure the attribute is in `permitted_attributes_for_index` on the policy.
-- **Slow search on large tables** — `LIKE '%q%'` can't be indexed by a b-tree. Switch to FTS or trigram.
-- **Duplicate rows in results** — add `.distinct` when joining associations.
-- **Typeahead works on small dev tables but slows in production** — same b-tree issue. Write an explicit `search` block backed by a proper index.
+- **Filter not showing up**: make sure the attribute is in `permitted_attributes_for_index` on the policy.
+- **Slow search on large tables**: `LIKE '%q%'` can't be indexed by a b-tree. Switch to FTS or trigram.
+- **Duplicate rows in results**: add `.distinct` when joining associations.
+- **Typeahead works on small dev tables but slows in production**: same b-tree issue. Write an explicit `search` block backed by a proper index.
 
 ## Related
 
-- [Reference › Resource › Query](/reference/resource/query) — full surface
-- [Adding resources](./adding-resources) — basic resource setup
-- [Authorization](./authorization) — `permitted_attributes_for_index` gates which fields can be filtered
+- [Reference › Resource › Query](/reference/resource/query): full surface
+- [Adding resources](./adding-resources): basic resource setup
+- [Authorization](./authorization): `permitted_attributes_for_index` gates which fields can be filtered

data/docs/guides/testing.md

@@ -1,6 +1,6 @@
 # Testing
 
-Plutonium ships `Plutonium::Testing` — opt-in Minitest concerns that give your app default test coverage for resources, policies, definitions, interactions, models, nested scoping, portal access, and authentication.
+Plutonium ships `Plutonium::Testing`, opt-in Minitest concerns that give your app default test coverage for resources, policies, definitions, interactions, models, nested scoping, portal access, and authentication.
 
 ## Quick start
 
@@ -75,7 +75,7 @@ resource_tests_for ResourceClass,
   has_cents:        %i[price]                              # ResourceModel only
 ```
 
-The **portal symbol** drives path prefix, default auth strategy, and scoping expectations. The resolver walks `Rails.application.routes.routes` for the engine mount — no manual configuration.
+The **portal symbol** drives path prefix, default auth strategy, and scoping expectations. The resolver walks `Rails.application.routes.routes` for the engine mount, with no manual configuration.
 
 ## Concerns
 
@@ -84,15 +84,17 @@ The **portal symbol** drives path prefix, default auth strategy, and scoping exp
 | `ResourceCrud` | index/show/new/create/edit/update/destroy | `create_resource!`, `valid_create_params`, `valid_update_params` |
 | `ResourcePolicy` | permit? × role × action matrix + relation_scope smoke | `policy_roles`, `policy_record`, `policy_matrix` |
 | `ResourceDefinition` | definition class + defineable prop smoke | none |
-| `ResourceInteraction` | `assert_interaction_success/failure` helpers | `interaction_class`, `valid_interaction_input` |
+| `ResourceInteraction` | `assert_interaction_success/failure` helpers | none |
 | `ResourceModel` | `associated_with`, SGID, `has_cents` | `model_test_record` |
 | `NestedResource` | nested CRUD + sibling-tenant boundaries | `parent_record!`, `other_parent_record!`, `create_resource!(parent:)` |
 | `PortalAccess` | cross-portal access matrix | `login_as_role`, `portal_root_path` |
 
-Mix and match — `include` only what you want.
+Mix and match: `include` only what you want.
 
 ## Auth helpers
 
+`login_as` and friends come from `Plutonium::Testing::AuthHelpers`. Only `ResourceCrud`, `NestedResource` and `PortalAccess` include it; the policy, definition, model and interaction concerns don't. A bare `login_as(account)` takes its portal from `resource_tests_for`, so in a `PortalAccess` class (or a hand-written test that adds `include Plutonium::Testing::AuthHelpers` itself) pass `portal:` every time.
+
 ```ruby
 login_as(account)                    # uses portal from DSL
 login_as(account, portal: :admin)    # explicit override
@@ -130,7 +132,7 @@ Idempotent. Adds the require line and creates the override stub.
 |---|---|---|
 | `--portals=admin,org` | required | Emit one file per portal |
 | `--concerns=...` | `crud,policy,definition` | Subset of concerns to include |
-| `--parent=organization` | none | Wires `NestedResource` parent |
+| `--parent=organization` | none | Adds `parent:` to `resource_tests_for`; the `NestedResource` include and stubs also need `nested` in `--concerns` (`--concerns=crud,nested --parent=organization`) |
 | `--dest=main_app\|<package>` | `main_app` | Output destination |
 
 Output: `test/integration/<portal>_portal/<resource>_test.rb`.
@@ -144,16 +146,18 @@ Output: `test/integration/<portal>_portal/<resource>_test.rb`.
 
 ## Common pitfalls
 
-- **Forgotten stubs raise `NotImplementedError`** with the stub name — look for the missing method.
+- **Forgotten stubs raise `NotImplementedError`** with the stub name: look for the missing method.
 - **Portal mismatch:** `:admin` expects `AdminPortal::Engine`. Pass `path_prefix:` if your engine is named differently.
 - **Tenant leakage in stubs:** for an org portal, `create_resource!` must return a record bound to the test's `@org`.
-- **`policy_record` for tenant-scoped resources** must belong to a tenant the role can access — otherwise even allowed roles see `false`.
-- **Nested resources need `parent:` in the DSL AND a parent record** from `parent_record!`. Both are required for path interpolation.
+- **`policy_record` for tenant-scoped resources** must belong to a tenant the role can access, otherwise even allowed roles see `false`.
+- **Nested paths come from `parent_record!.id`**, so it must return the same persisted tenant on every call (e.g. `@org`). `parent:` in the DSL documents the relationship; the concern doesn't read it.
+- **Entity-scoped (`:path`) portals need two classes** for CRUD and tenant isolation, since `ResourceCrud` needs the tenant in `current_path_prefix` and `NestedResource` adds it itself. See [Reference › Testing](/reference/testing/#entity-scoped-portals-crud-tenant-isolation).
+- **`valid_update_params` is compared literally** after the PATCH: use strings for enums and leave association SGIDs out.
 - **`PortalAccess` uses `portal_access_for`**, not `resource_tests_for`. Don't mix them on the same class.
 
 ## Related
 
-- [Reference › Testing](/reference/testing/) — full DSL reference, all concern stubs, override hooks
-- [Authorization](./authorization) — write the policy this concern verifies
-- [Multi-tenancy](./multi-tenancy) — entity scoping that drives nested-resource tests
-- [Authentication](./authentication) — Rodauth setup behind the default login flow
+- [Reference › Testing](/reference/testing/): full DSL reference, all concern stubs, override hooks
+- [Authorization](./authorization): write the policy this concern verifies
+- [Multi-tenancy](./multi-tenancy): entity scoping that drives nested-resource tests
+- [Authentication](./authentication): Rodauth setup behind the default login flow

data/docs/guides/theming.md

@@ -18,11 +18,12 @@ Adapt Plutonium's defaults to match your brand: primary color, fonts, logo, dark
 
 ## 🚨 Critical
 
-- **Always register Stimulus controllers** — `registerControllers(application)`. Without it, the entire interactive layer is dead.
-- **Use `plutoniumTailwindConfig.merge`** when overriding Tailwind theme — plain object spread drops Plutonium's defaults.
-- **Tokens are CSS variables, not Tailwind keys** — `bg-[var(--pu-surface)]`, NOT `bg-pu-surface`.
-- **Dark mode is `selector`, not `class`** — toggle by adding/removing `dark` on `<html>`.
-- **Prefer `.pu-*` classes and `var(--pu-*)` tokens** over hardcoded `gray-X/dark:gray-Y` pairs — they switch with dark mode automatically.
+- **Run `pu:core:assets` before any CSS or brand-color change.** Out of the box the app serves the gem's prebuilt `plutonium.css` / `plutonium.min.js`, so app-side Tailwind classes, palette changes and token overrides have nowhere to compile. Don't hand-write the Tailwind/PostCSS pipeline.
+- **Once the app owns its JS bundle, register Stimulus controllers** with `registerControllers(application)` (`pu:core:assets` adds it). Your bundle replaces the gem's, so without it the entire interactive layer is dead.
+- **Use `plutoniumTailwindConfig.merge`** when overriding Tailwind theme: plain object spread drops Plutonium's defaults.
+- **Tokens are CSS variables, not Tailwind keys**: `bg-[var(--pu-surface)]`, NOT `bg-pu-surface`.
+- **Dark mode is `selector`, not `class`**: toggle by adding/removing `dark` on `<html>`.
+- **Style with `.pu-*` classes first, `var(--pu-*)` tokens second, raw palette pairs last.** Banners, badges, cards and buttons all have a `.pu-*` class that carries its own `.dark` rule; a hand-written `bg-warning-50 dark:bg-warning-950/30` pair duplicates that and drifts from the theme.
 
 ## Step 1: Run the assets generator
 
@@ -30,7 +31,9 @@ Adapt Plutonium's defaults to match your brand: primary color, fonts, logo, dark
 rails generate pu:core:assets
 ```
 
-This installs npm packages, creates `tailwind.config.js`, imports Plutonium CSS, registers Stimulus controllers, and points `Plutonium.configure` at your asset files. Run once per app.
+This installs npm packages, creates `tailwind.config.js` and `postcss.config.js`, imports Plutonium CSS, registers Stimulus controllers, and points `Plutonium.configure` at your asset files. Run once per app.
+
+It aborts unless `app/assets/stylesheets/application.tailwind.css` and `app/javascript/controllers/index.js` exist (an app created with `-j esbuild -c tailwind` plus Stimulus). For an app without them, run `bin/rails javascript:install:esbuild`, `css:install:tailwind` and `stimulus:install` first. See [Reference › UI › Assets › Generator](/reference/ui/assets#generator).
 
 ## Step 2: Asset configuration
 
@@ -75,6 +78,8 @@ theme: plutoniumTailwindConfig.merge(plutoniumTailwindConfig.theme, {
 })
 ```
 
+These palettes are compiled into the CSS at build time (`.pu-btn-primary` is `@apply bg-primary-600 ...`), so a brand color change needs this `merge` plus a rebuild (the `build:css` script, or the running `bin/dev` watcher). A `--pu-*` override won't recolor `primary`.
+
 ### Default palette
 
 | Color | Use |
@@ -105,7 +110,15 @@ theme: plutoniumTailwindConfig.merge(plutoniumTailwindConfig.theme, {
 }
 ```
 
-Tokens auto-switch when the user toggles dark mode. See [Reference › UI › Assets › Design tokens](/reference/ui/assets#design-tokens) for the full token catalog.
+Tokens auto-switch when the user toggles dark mode.
+
+::: warning Mirror every `:root` override in `.dark`
+Your stylesheet loads after Plutonium's and `:root` / `.dark` have equal specificity, so a token overridden only in `:root` wins in dark mode too and ships your light value there. Re-assert every customized color token in `.dark`, shadows included: `--pu-shadow-sm/md/lg` have their own dark values in `src/css/tokens.css`.
+
+Put dark values in a `.dark { ... }` block, not `@media (prefers-color-scheme: dark)`. Dark mode is the `dark` class on `<html>`, so a media query ignores the user's toggle.
+:::
+
+See [Reference › UI › Assets › Design tokens](/reference/ui/assets#design-tokens) for the full token catalog.
 
 ## Using tokens in your code
 
@@ -145,6 +158,8 @@ Pre-styled ready-to-use components:
 | Buttons | `.pu-btn`, `.pu-btn-md/-sm/-xs`, `.pu-btn-primary/-secondary/-danger/-success/-warning/-info/-accent`, `.pu-btn-ghost/-outline`, `.pu-btn-soft-*` |
 | Inputs | `.pu-input/-invalid/-valid`, `.pu-label/-required`, `.pu-hint`, `.pu-error`, `.pu-checkbox` |
 | Cards | `.pu-card`, `.pu-card-body`, `.pu-panel-header`, `.pu-panel-title`, `.pu-panel-description` |
+| Badges | `.pu-badge`, `.pu-badge-neutral/-primary/-secondary/-success/-danger/-warning/-info/-accent` |
+| Alerts (inline banners) | `.pu-alert`, `.pu-alert-success/-warning/-danger/-info`, `.pu-alert-message`, `.pu-alert-close` |
 | Tables | `.pu-table-wrapper`, `.pu-table`, `-header`, `-header-cell`, `-body-row`, `-body-row-selected`, `-body-cell`, `.pu-selection-cell` |
 | Toolbars / empty states | `.pu-toolbar`, `-text`, `-actions`; `.pu-empty-state`, `-icon`, `-title`, `-description` |
 
@@ -184,7 +199,7 @@ end
 ```
 
 ::: warning Always `super.merge(...)`
-Don't replace the theme wholesale — Plutonium's defaults handle invalid states, focus rings, and dark mode. `super.merge` keeps them.
+Don't replace the theme wholesale (Plutonium's defaults handle invalid states, focus rings, and dark mode). `super.merge` keeps them.
 :::
 
 Full theme key catalog: [Reference › UI › Assets › Phlexi component themes](/reference/ui/assets#phlexi-component-themes).
@@ -225,7 +240,7 @@ document.documentElement.classList.toggle('dark')
 
 If you've overridden tokens via `:root` and `.dark`, both modes Just Work.
 
-## Per-portal chrome — eject the shell
+## Per-portal chrome: eject the shell
 
 For per-portal headers/sidebars:
 
@@ -245,7 +260,7 @@ Copies `layouts/resource.html.erb` for layout-level edits.
 
 ```ruby
 Plutonium.configure do |config|
-  config.shell = :modern     # default — topbar + icon rail
+  config.shell = :modern     # default: topbar + icon rail
   # config.shell = :classic  # legacy header + sidebar (only when upgrading)
 end
 ```
@@ -268,13 +283,13 @@ Bundled controllers: `color-mode`, `form` (pre-submit), `nested-resource-form-fi
 
 ## Common issues
 
-- **Stimulus controllers silently fail** — if `registerControllers(application)` isn't called, the entire UI's interactive layer is dead (color-mode toggle, slim-select, flatpickr, easymde, pre-submit). No error — just no behavior.
-- **`plutoniumTailwindConfig.merge` is mandatory** — plain spread drops defaults silently.
-- **Tokens not switching in dark mode** — you used `bg-pu-surface` instead of `bg-[var(--pu-surface)]`. Tokens are CSS variables, not Tailwind keys.
-- **`.pu-btn` styles not applying** — check that Plutonium CSS is imported BEFORE Tailwind: `@import "gem:plutonium/src/css/plutonium.css";` then `@import "tailwindcss";`.
+- **Stimulus controllers silently fail**: once the app serves its own JS bundle, if `registerControllers(application)` isn't called, the entire UI's interactive layer is dead (color-mode toggle, slim-select, flatpickr, easymde, pre-submit). No error: just no behavior.
+- **`plutoniumTailwindConfig.merge` is mandatory**: plain spread drops defaults silently.
+- **Tokens not switching in dark mode**: you used `bg-pu-surface` instead of `bg-[var(--pu-surface)]`. Tokens are CSS variables, not Tailwind keys.
+- **`.pu-btn` styles not applying**: check that Plutonium CSS is imported BEFORE Tailwind: `@import "gem:plutonium/src/css/plutonium.css";` then `@import "tailwindcss";`.
 
 ## Related
 
-- [Reference › UI › Assets](/reference/ui/assets) — full Tailwind / Stimulus / design tokens / component classes surface
-- [Reference › UI › Layouts](/reference/ui/layouts) — shell, eject, ResourceLayout
-- [Reference › UI › Forms › Theming](/reference/ui/forms#theming) — Form theme keys
+- [Reference › UI › Assets](/reference/ui/assets): full Tailwind / Stimulus / design tokens / component classes surface
+- [Reference › UI › Layouts](/reference/ui/layouts): shell, eject, ResourceLayout
+- [Reference › UI › Forms › Theming](/reference/ui/forms#theming): Form theme keys

data/docs/guides/troubleshooting.md

@@ -79,6 +79,6 @@ If you encounter an issue not covered here, please [open an issue](https://githu
 
 - [Nested resources](./nested-resources)
 - [Adding resources](./adding-resources)
-- [Reference › Behavior › Controllers](/reference/behavior/controllers) — `controller_for`, `resource_url_for`, `current_parent`
-- [Reference › Tenancy › Nested resources](/reference/tenancy/nested-resources) — nested URL generation
+- [Reference › Behavior › Controllers](/reference/behavior/controllers): `controller_for`, `resource_url_for`, `current_parent`
+- [Reference › Tenancy › Nested resources](/reference/tenancy/nested-resources): nested URL generation
 - [Rails Inflections](https://api.rubyonrails.org/classes/ActiveSupport/Inflector/Inflections.html)

data/docs/guides/user-invites.md

@@ -8,7 +8,7 @@ An admin enters an email, the user gets an invite link, clicks it, signs up (or
 
 ## Prerequisites
 
-You need a user model, an entity model, and a membership model. The fastest path is `pu:saas:setup` — it creates all three and runs `pu:invites:install` automatically:
+You need a user model, an entity model, and a membership model. The fastest path is `pu:saas:setup`: it creates all three and runs `pu:invites:install` automatically:
 
 ```bash
 rails g pu:saas:setup --user Customer --entity Organization
@@ -43,7 +43,7 @@ rails g pu:invites:install \
 | `--enforce-domain` | `false` | Require email domain to match entity |
 
 ::: info Roles come from the membership model
-`pu:invites:install` reads the role list from the membership model's `enum :role` — it does not accept a `--roles=` flag. Define roles when you generate the membership model (`pu:saas:membership --roles=...`), or edit the enum directly. **Index 0 is the most privileged** (typically `owner`); the invite interaction excludes `owner` from selectable choices and defaults new invitees to the second role.
+`pu:invites:install` reads the role list from the membership model's `enum :role`; it does not accept a `--roles=` flag. Define roles when you generate the membership model (`pu:saas:membership --roles=...`), or edit the enum directly. **Index 0 is the most privileged** (typically `owner`); the invite interaction excludes `owner` from selectable choices and defaults new invitees to the second role.
 :::
 
 ### 2. Migrate
@@ -112,7 +112,7 @@ Users land on `/welcome` where pending invites are shown. Including `Plutonium::
 include Plutonium::Invites::PendingInviteCheck
 ```
 
-## Invitables — app models notified on acceptance
+## Invitables: app models notified on acceptance
 
 An invitable is a model that gets notified when its invitation is accepted. Examples: `Tenant`, `TeamMember`, `ProjectCollaborator`.
 
@@ -137,7 +137,7 @@ end
 ```
 
 ::: warning Without `on_invite_accepted`
-The invitable never learns about the new user — the invite is consumed but your app doesn't update its state.
+The invitable never learns about the new user: the invite is consumed but your app doesn't update its state.
 :::
 
 ## Multiple invite flows in one app
@@ -158,7 +158,7 @@ rails g pu:invites:install \
 
 Each invocation creates an independent flow: model, controller, route, helper all named for the invite-model.
 
-The shared `Invites::WelcomeController` accumulates each new class into its `invite_classes` array — `pending_invite` checks all flows in priority order (first-match wins).
+The shared `Invites::WelcomeController` accumulates each new class into its `invite_classes` array; `pending_invite` checks all flows in priority order (first-match wins).
 
 See [Reference › Tenancy › Invites › Multiple invite flows](/reference/tenancy/invites#multiple-invite-flows).
 
@@ -222,27 +222,27 @@ entity.user_invites.pending    # list pending
 
 ## Security
 
-- **Token security** — `SecureRandom.urlsafe_base64(32)` — 256 bits, URL-safe. Stored hashed, raw token shown only at creation.
-- **Email validation** — `enforce_email?` is `true` by default. The accepting user's email must match the invited email — prevents account hijacking via invite forwarding.
-- **Rate limiting** — use Rack::Attack or similar to throttle invite creation per admin and acceptance attempts per IP.
+- **Token security**: `SecureRandom.urlsafe_base64(32)`, 256 bits, URL-safe. Stored hashed, raw token shown only at creation.
+- **Email validation**: `enforce_email?` is `true` by default. The accepting user's email must match the invited email; this prevents account hijacking via invite forwarding.
+- **Rate limiting**: use Rack::Attack or similar to throttle invite creation per admin and acceptance attempts per IP.
 
 ::: danger Don't disable enforce_email?
 ```ruby
 def enforce_email? = false   # ← only if you fully understand the trade-off
 ```
-Without this, anyone with the token can sign up — defeats the purpose of an invitation system.
+Without this, anyone with the token can sign up, which defeats the purpose of an invitation system.
 :::
 
 ## Common issues
 
-- **"Invitation not found or expired"** — token expired (default 1 week), invite cancelled, or no longer `pending`.
-- **Email mismatch error** — the accepting user's email doesn't match the invited email. This is by design (security).
-- **Rodauth redirect after login doesn't go to `/welcome`** — check `login_redirect "/welcome"` in the rodauth plugin's `configure` block.
-- **`on_invite_accepted` not called** — ensure the invitable model `include Plutonium::Invites::Concerns::Invitable` and defines `on_invite_accepted`.
+- **"Invitation not found or expired"**: token expired (default 1 week), invite cancelled, or no longer `pending`.
+- **Email mismatch error**: the accepting user's email doesn't match the invited email. This is by design (security).
+- **Rodauth redirect after login doesn't go to `/welcome`**: check `login_redirect "/welcome"` in the rodauth plugin's `configure` block.
+- **`on_invite_accepted` not called**: ensure the invitable model `include Plutonium::Invites::Concerns::Invitable` and defines `on_invite_accepted`.
 
 ## Related
 
-- [Reference › Tenancy › Invites](/reference/tenancy/invites) — full surface, multi-flow apps, customization
-- [Multi-tenancy](./multi-tenancy) — entity scoping (invites are entity-scoped automatically)
-- [Authentication](./authentication) — Rodauth setup
-- [User profile](./user-profile) — account-settings page
+- [Reference › Tenancy › Invites](/reference/tenancy/invites): full surface, multi-flow apps, customization
+- [Multi-tenancy](./multi-tenancy): entity scoping (invites are entity-scoped automatically)
+- [Authentication](./authentication): Rodauth setup
+- [User profile](./user-profile): account-settings page