plutonium 0.51.0 → 0.53.0

data/docs/reference/app/generators.md

@@ -185,7 +185,7 @@ rails rodauth_admin:create[admin@example.com,password123]
 
 ```bash
 rails g pu:saas:setup --user Customer --entity Organization
-rails g pu:saas:setup --user Customer --entity Organization --roles=member,admin
+rails g pu:saas:setup --user Customer --entity Organization --roles=admin,member
 rails g pu:saas:setup --user Customer --entity Organization --no-allow-signup
 rails g pu:saas:setup --user Customer --entity Organization \
   --user-attributes=name:string --entity-attributes=slug:string
@@ -216,7 +216,7 @@ For when you don't want the full `pu:saas:setup` meta-generator:
 ```bash
 rails g pu:saas:user Customer
 rails g pu:saas:entity Organization --extra-attributes=slug:string
-rails g pu:saas:membership --user Customer --entity Organization --roles=member,admin
+rails g pu:saas:membership --user Customer --entity Organization --roles=admin,member
 rails g pu:saas:portal customer --entity Organization
 rails g pu:saas:welcome --user Customer --entity Organization
 ```
@@ -305,10 +305,10 @@ rails g pu:invites:install --entity-model=Organization --user-model=Customer --i
 | `--entity-model=NAME` | `Entity` | Entity model name |
 | `--user-model=NAME` | `User` | User model name |
 | `--invite-model=NAME` | `<EntityModel><UserModel>Invite` | Invite class name |
-| `--membership-model=NAME` | `EntityUser` | Membership join model |
-| `--roles` | `member,admin` | Comma-separated |
+| `--membership-model=NAME` | `EntityUser` | Membership join model (must already exist; roles read from its `enum :role`) |
 | `--rodauth=NAME` | `user` | Rodauth configuration for signup |
 | `--enforce-domain` | `false` | Require email domain to match entity |
+| `--dest=PACKAGE` | `main_app` | Package where the entity model lives (controls where `invite_user_interaction.rb` is generated) |
 
 Multiple invite flows are supported — run `pu:invites:install` once per flow.
 

data/docs/reference/auth/accounts.md

@@ -14,7 +14,6 @@ rails generate pu:rodauth:account user [options]
 |---|---|
 | `--defaults` | Enables login, logout, remember, password reset |
 | `--kitchen_sink` | Enables ALL features |
-| `--primary` | Mark as primary account (no URL prefix) |
 | `--no-mails` | Skip mailer setup |
 | `--argon2` | Use Argon2 instead of bcrypt |
 | `--api_only` | JSON API only (no sessions) |
@@ -50,9 +49,6 @@ rails generate pu:rodauth:account user [options]
 # Basic account
 rails g pu:rodauth:account user
 
-# Primary account (no URL prefix)
-rails g pu:rodauth:account user --primary
-
 # With 2FA
 rails g pu:rodauth:account user --otp --recovery_codes
 
@@ -84,13 +80,16 @@ rails g pu:rodauth:admin admin --extra-attributes=name:string,department:string
 enum :role, super_admin: 0, admin: 1
 ```
 
-Rake task for direct admin creation:
+Rake task for direct admin creation (generated alongside the account — namespace is `rodauth`, task name is the account name):
 
 ```bash
-rails rodauth_admin:create[admin@example.com,password123]
+EMAIL=admin@example.com rails rodauth:admin
+# (run without EMAIL to be prompted)
 ```
 
-## SaaS setup — `pu:saas:setup` (meta-generator)
+The task creates the account and triggers a verification email; the admin sets their own password via that flow. No password is passed on the command line.
+
+## SaaS setup — `pu:saas:setup` (meta-generator) {#saas-setup}
 
 Creates the User + Entity + Membership trio AND runs:
 
@@ -105,7 +104,7 @@ After `pu:saas:setup` runs, don't separately run `pu:saas:portal`, `pu:profile:s
 
 ```bash
 rails g pu:saas:setup --user Customer --entity Organization
-rails g pu:saas:setup --user Customer --entity Organization --roles=member,admin
+rails g pu:saas:setup --user Customer --entity Organization --roles=admin,member
 rails g pu:saas:setup --user Customer --entity Organization --no-allow-signup
 rails g pu:saas:setup --user Customer --entity Organization \
   --user-attributes=name:string --entity-attributes=slug:string

data/docs/reference/auth/index.md

@@ -43,7 +43,7 @@ class AdminController < PlutoniumController
 end
 ```
 
-`Plutonium::Auth::Rodauth(:name)` exposes `current_user`, `logout_url`, and `rodauth` in the controller.
+`Plutonium::Auth::Rodauth(:name)` exposes `current_user`, `logout_url`, `profile_url`, and `rodauth` in the controller (all available as helper methods in views too).
 
 For portal wiring (`AdminPortal::Concerns::Controller`), see [App › Portals](/reference/app/portals#controller-concern-auth).
 

data/docs/reference/behavior/policies.md

@@ -11,7 +11,7 @@ Authorization for resources. Built on [ActionPolicy](https://actionpolicy.evilma
 
 - **`create?` and `read?` default to `false`.** You MUST override them explicitly. Everything else (`update?`, `destroy?`, `index?`, `show?`, …) derives from one of those.
 - **`permitted_attributes_for_*` must be explicit in production.** Dev auto-detects; production raises.
-- **`relation_scope` must call `default_relation_scope(relation)` explicitly** — never `super`. Bypassing it triggers `verify_default_relation_scope_applied!`.
+- **`relation_scope` must end up calling `default_relation_scope(relation)` somewhere in the chain.** Prefer calling it explicitly in your override. `super` is fine when extending a parent policy (e.g., a package base) that itself calls it. The runtime check verifies it was hit somewhere — not in this specific class.
 - **For `has_cents` fields, use the virtual name** (`:price`), NEVER `:price_cents`.
 - **Don't put `*_attributes` hashes in `permitted_attributes_for_*`.** Nested forms are extracted from the form definition, not the policy. List the association name (`:variants`) and the `nested_input` in the definition handles the rest.
 - **Custom action ⇒ policy method.** `action :publish` needs `def publish?`. Undefined methods return `false` → action silently disappears.
@@ -247,7 +247,7 @@ Filter which records the user can see.
 
 ### Always compose with `default_relation_scope`
 
-🚨 `relation_scope` MUST call `default_relation_scope(relation)` explicitly. Never `super` — the semantics depend on how ActionPolicy's DSL registered the scope. Plutonium enforces this at runtime via `verify_default_relation_scope_applied!`.
+🚨 `relation_scope` MUST end up calling `default_relation_scope(relation)` somewhere in the chain. `super` works — `Plutonium::Resource::Policy` defines a default scope block that calls `default_relation_scope`, so a subclass that does `super(relation).where(...)` is fine. Calling `default_relation_scope` explicitly is also fine (and required when you skip the parent chain). Plutonium enforces this at runtime via `verify_default_relation_scope_applied!`.
 
 ```ruby
 # ✅ Best — don't override at all. The inherited scope already calls default_relation_scope.

data/docs/reference/configuration.md

@@ -0,0 +1,61 @@
+# Configuration
+
+Plutonium is configured through `Plutonium.configure` in an initializer. A generated app has this at `config/initializers/plutonium.rb`:
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure do |config|
+  config.load_defaults 1.0
+
+  # config.shell = :modern
+  # config.navii_host_url = "https://api.navii.dev"
+
+  config.assets.logo       = "plutonium.png"
+  config.assets.favicon    = "plutonium.ico"
+  config.assets.stylesheet = "plutonium.css"
+  config.assets.script     = "plutonium.min.js"
+end
+```
+
+Access the live config anywhere via `Plutonium.configuration`.
+
+## Versioned defaults
+
+```ruby
+config.load_defaults 1.0
+```
+
+Loads the baseline defaults for a given framework version. Call this first; later versions layer their changes on top. Read the resolved version with `config.defaults_version`.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `load_defaults(version)` | — | Apply versioned framework defaults. Call first. |
+| `development` | `ENV["PLUTONIUM_DEV"]` | Development mode for the framework itself (local assets, hot reload, verbose errors). Query with `config.development?`. You rarely set this in an app — see [Development mode](#development-mode). |
+| `cache_discovery` | `true` outside `development` env | Cache resource/route discovery. Disable to pick up new resources without a reboot. |
+| `enable_hotreload` | `true` in `development` env | Hot-reload Plutonium components on change. |
+| `shell` | `:modern` | Chrome style: `:modern` (topbar + icon rail) or `:classic` (legacy header + sidebar, only for upgrades). See [Layouts](./ui/layouts). |
+| `navii_host_url` | `"https://api.navii.dev"` | Host of the [Navii](https://navii.dev) avatar service used by [`Avatar`](./ui/components#avatar). The component appends `/avatar/:seed`. Repoint to self-host or proxy. |
+| `assets.logo` | `"plutonium.png"` | Brand logo asset. See [Assets](./ui/assets). |
+| `assets.favicon` | `"plutonium.ico"` | Favicon asset. |
+| `assets.stylesheet` | `"plutonium.css"` | Stylesheet entry. |
+| `assets.script` | `"plutonium.min.js"` | JavaScript entry. |
+
+## Development mode
+
+`config.development?` is driven by the `PLUTONIUM_DEV` environment variable, not set in the initializer. It’s primarily for working **on the Plutonium gem** (uses local `src/` assets, enables hot reloading, and shows more detailed errors). Applications generally leave it unset.
+
+```bash
+export PLUTONIUM_DEV=1
+```
+
+## Assets
+
+Asset entries live under `config.assets` and point the framework at your compiled stylesheet/script and brand imagery. The `pu:core:assets` generator wires these up. See [Assets](./ui/assets) for the full asset/Tailwind/Stimulus setup.
+
+## Related
+
+- [Assets](./ui/assets) — stylesheet, script, Tailwind, and design tokens
+- [Layouts](./ui/layouts) — the `shell` option and ejecting chrome
+- [Components › Avatar](./ui/components#avatar) — `navii_host_url`

data/docs/reference/index.md

@@ -1,56 +1,68 @@
-# Reference
+---
+layout: page
+sidebar: false
+aside: false
+---
 
-Concept-by-concept API documentation. For task-oriented walkthroughs, see [Guides](/guides/).
-
-## The seven areas
-
-### [App](/reference/app/)
-Installation, packages (feature + portal), portal engines, mounting, route registration (including singular and custom routes), connecting resources via `pu:res:conn`, full generator catalog.
-
-### [Resource](/reference/resource/)
-The four-layer resource — model, definition, query, actions. `pu:res:scaffold` field-type syntax, `has_cents`, SGID, URL routing, definition DSL (fields, inputs, displays, columns), page chrome, metadata panel, index views (table & grid), search, filters, scopes, sorting, custom + bulk actions.
-
-### [Behavior](/reference/behavior/)
-Controllers, policies, interactions. Controller hooks (redirect, params, presentation), policy action methods and `permitted_attributes_for_*`, `permitted_associations`, `relation_scope`, interaction structure, outcomes, chaining, URL generation.
-
-### [UI](/reference/ui/)
-Pages, forms, displays, tables, components, layouts, assets. Custom page classes, form field builders, association inputs (typeahead + inline `+`), built-in component kit, custom Phlex components, the shell, design tokens, `.pu-*` component classes, Phlexi themes.
-
-### [Auth](/reference/auth/)
-Rodauth installation, account types (basic / admin / SaaS), profile resource with the SecuritySection component.
-
-### [Tenancy](/reference/tenancy/)
-Multi-tenant entity scoping (`associated_with`, `default_relation_scope`, three model shapes), nested resources (parent/child routes, scoping), user invitations.
-
-### [Testing](/reference/testing/)
-The `Plutonium::Testing::*` concerns — CRUD, policy matrix, definition smoke tests, model concerns, nested resources, portal access, interaction outcomes.
-
-## Quick reference
-
-| I need to… | See |
-|---|---|
-| Install Plutonium | [App › Index](/reference/app/) |
-| Run a generator | [App › Generators](/reference/app/generators) |
-| Create a portal | [App › Portals](/reference/app/portals) |
-| Scaffold a resource | [App › Generators › `pu:res:scaffold`](/reference/app/generators#pu-res-scaffold) |
-| Configure form fields | [Resource › Definition](/reference/resource/definition) |
-| Add search / filters | [Resource › Query](/reference/resource/query) |
-| Add custom buttons / bulk actions | [Resource › Actions](/reference/resource/actions) |
-| Override CRUD redirects / params | [Behavior › Controllers](/reference/behavior/controllers) |
-| Control who can see what | [Behavior › Policies](/reference/behavior/policies) |
-| Write business logic | [Behavior › Interactions](/reference/behavior/interactions) |
-| Customize a page | [UI › Pages](/reference/ui/pages) |
-| Customize a form | [UI › Forms](/reference/ui/forms) |
-| Style the UI | [UI › Assets](/reference/ui/assets) |
-| Set up Rodauth | [Auth › Accounts](/reference/auth/accounts) |
-| Add a profile page | [Auth › Profile](/reference/auth/profile) |
-| Scope to a tenant | [Tenancy › Entity scoping](/reference/tenancy/entity-scoping) |
-| Wire user invitations | [Tenancy › Invites](/reference/tenancy/invites) |
-| Test a resource | [Testing](/reference/testing/) |
-
-## Reading this reference
-
-- **🚨 Critical blocks** at the top of each page surface the "you'll regret this" rules. Skim them even if you're skimming the rest.
-- **Option / DSL tables** are designed for scanning — find your option name without reading prose.
-- **Cross-references** use VitePress relative paths. If a link points somewhere that doesn't exist yet, it's a known gap.
-- **Concrete decision rules** ("use X when…, Y when…") sit alongside the option references. Reach for them when in doubt.
+<SectionLanding
+  eyebrow="Reference"
+  title="Every API, in one place."
+  lede="The full surface area of Plutonium — controllers, policies, definitions, fields, interactions, generators."
+  mode="categorized"
+  :rail="[
+    { group: 'App', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/app/' },
+      { name: 'Packages', link: '/plutonium-core/reference/app/packages' },
+      { name: 'Portals', link: '/plutonium-core/reference/app/portals' },
+      { name: 'Generators', link: '/plutonium-core/reference/app/generators' },
+    ]},
+    { group: 'Resource', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/resource/' },
+      { name: 'Model', link: '/plutonium-core/reference/resource/model' },
+      { name: 'Definition', link: '/plutonium-core/reference/resource/definition' },
+      { name: 'Query', link: '/plutonium-core/reference/resource/query' },
+      { name: 'Actions', link: '/plutonium-core/reference/resource/actions' },
+    ]},
+    { group: 'Behavior', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/behavior/' },
+      { name: 'Controllers', link: '/plutonium-core/reference/behavior/controllers' },
+      { name: 'Policies', link: '/plutonium-core/reference/behavior/policies' },
+      { name: 'Interactions', link: '/plutonium-core/reference/behavior/interactions' },
+    ]},
+    { group: 'UI', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/ui/' },
+      { name: 'Pages', link: '/plutonium-core/reference/ui/pages' },
+      { name: 'Forms', link: '/plutonium-core/reference/ui/forms' },
+      { name: 'Displays', link: '/plutonium-core/reference/ui/displays' },
+      { name: 'Tables', link: '/plutonium-core/reference/ui/tables' },
+      { name: 'Components', link: '/plutonium-core/reference/ui/components' },
+      { name: 'Layouts', link: '/plutonium-core/reference/ui/layouts' },
+      { name: 'Assets', link: '/plutonium-core/reference/ui/assets' },
+    ]},
+    { group: 'Auth', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/auth/' },
+      { name: 'Accounts', link: '/plutonium-core/reference/auth/accounts' },
+      { name: 'Profile', link: '/plutonium-core/reference/auth/profile' },
+    ]},
+    { group: 'Tenancy', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/tenancy/' },
+      { name: 'Entity scoping', link: '/plutonium-core/reference/tenancy/entity-scoping' },
+      { name: 'Nested resources', link: '/plutonium-core/reference/tenancy/nested-resources' },
+      { name: 'Invites', link: '/plutonium-core/reference/tenancy/invites' },
+    ]},
+    { group: 'Testing', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/testing/' },
+    ]},
+  ]"
+  :sidebar="[
+    { heading: 'Learning?', items: [
+      { label: 'Tutorial', href: '/plutonium-core/getting-started/tutorial/' },
+    ]},
+    { heading: 'Solving a problem?', items: [
+      { label: 'Guides', href: '/plutonium-core/guides/' },
+    ]},
+    { heading: 'Need help?', items: [
+      { label: 'GitHub Discussions', href: 'https://github.com/radioactive-labs/plutonium-core/discussions' },
+    ]},
+  ]"
+/>

data/docs/reference/resource/actions.md

@@ -70,7 +70,8 @@ action :name,
   turbo_frame:  "_top",
   return_to:    "/custom/path",
   route_options: {action: :foo},
-  modal: :slideover                      # :centered (default) or :slideover — chrome for the action's interaction form
+  modal: :slideover,                     # :slideover / :centered — overrides the definition's modal mode
+  size:  :lg                             # :sm / :md / :lg / :xl / :auto / :full — overrides the definition's modal size
 ```
 
 ### Deriving variants — `Action#with(...)`

data/docs/reference/resource/definition.md

@@ -111,7 +111,7 @@ end
 
 ### Display types (show / index)
 
-`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`
+`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`, `:color`
 
 ## Field options
 
@@ -410,15 +410,16 @@ class PostDefinition < ResourceDefinition
   #   false           — always hide
   submit_and_continue false
 
-  # How :new / :edit render
+  # How :new / :edit and interactive actions render
   #   :slideover   (default) — slide-in panel from the right
   #   :centered              — centered dialog
   #   false                  — full standalone pages (no modal)
-  modal :centered
+  # size: optional, one of :sm, :md (default), :lg, :xl, :auto, :full
+  modal :centered, size: :lg
 end
 ```
 
-`modal:` only affects framework `:new`/`:edit` actions. Custom interactive actions have their own per-action `modal:` option — see [Actions](./actions).
+`modal:` is the default for framework `:new`/`:edit` *and* every interactive action on this definition. Per-action `modal:` / `size:` overrides win — see [Actions](./actions).
 
 ## Metadata panel (show page)
 

data/docs/reference/tenancy/entity-scoping.md

@@ -4,8 +4,7 @@ Multi-tenant data isolation. Built on three cooperating pieces — portal, polic
 
 ## 🚨 Critical
 
-- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins to the entity triggers `verify_default_relation_scope_applied!`. Always call `default_relation_scope(relation)` explicitly.
-- **Don't rely on `super`** inside `relation_scope` — call `default_relation_scope(relation)` by name.
+- **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)` somewhere (explicitly, or via `super` to a parent that calls it — `Plutonium::Resource::Policy` does).
 - **Fix the MODEL, not the policy.** If `associated_with` can't resolve, declare an association path (`belongs_to`, `has_one :through`) OR a custom `associated_with_<entity>` scope on the model. Never paper over it with a `where` in the policy.
 - **Compound uniqueness scoped to the tenant FK** — `validates :code, uniqueness: {scope: :organization_id}`.
 - **Multiple associations to the same entity class** require overriding `scoped_entity_association` on the controller.
@@ -180,8 +179,8 @@ relation_scope { |r| r.joins(:project).where(projects: {organization_id: current
 relation_scope { |r| r.where(published: true) }
 ```
 
-::: danger Don't use `super`
-`super` inside `relation_scope` is unreliable — its semantics depend on how ActionPolicy's DSL registered the scope. Call `default_relation_scope(relation)` by name.
+::: tip `super` works too
+`Plutonium::Resource::Policy`'s `relation_scope` block calls `default_relation_scope(relation)`, so `super(relation)` from a subclass picks it up and the runtime check passes. Use whichever reads more clearly — `super(relation).where(archived: false)` and `default_relation_scope(relation).where(archived: false)` are equivalent when extending the framework base. Call `default_relation_scope` explicitly when you're not chaining via `super` (e.g. replacing the scope entirely).
 :::
 
 ### Intentionally skipping the scope
@@ -215,7 +214,7 @@ module CustomerPortal
 end
 ```
 
-Routes become `/organizations/:organization_id/posts`. The portal extracts `params[:organization_id]` and loads the entity automatically.
+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). The portal extracts `params[:organization_scoped]` and loads the entity automatically.
 
 ### Custom strategy (subdomain, session, etc.)
 
@@ -239,11 +238,19 @@ The strategy symbol must match a method name on the controller concern.
 
 ### Custom param key
 
-When the param name differs from the entity model name:
+The default `param_key` derives from the entity class — `<singular_route_key>_scoped` (e.g. `:organization_scoped`) — to avoid colliding with a `belongs_to :organization` on child models when reading `params[:organization]`. The URL itself just uses the entity id as the first segment after the mount:
+
+```
+mount CustomerPortal::Engine, at: "/customer"
+# → /customer/:organization_scoped/posts   (route definition)
+# → /customer/42/posts                     (request URL)
+```
+
+Override when you want a different param name (e.g. for readability when reading params in custom controllers):
 
 ```ruby
 scope_to_entity Organization, strategy: :path, param_key: :org_id
-# → /orgs/:org_id/posts
+# → params[:org_id] instead of params[:organization_scoped]
 ```
 
 ### Accessing the scoped entity
@@ -346,7 +353,6 @@ Without the scope, uniqueness leaks across tenants — Org A and Org B could col
 ## Gotchas
 
 - **Policy tries to filter by entity directly.** Wrong — bypasses `default_relation_scope`. Add the association path to the model instead.
-- **`super` inside `relation_scope`.** Unreliable. Use `default_relation_scope(relation)` explicitly.
 - **Multiple associations to the same entity class.** Override `scoped_entity_association`.
 - **`param_key` differs from association name.** Fine — Plutonium finds the association by class.
 - **Forgetting compound uniqueness.** A unique constraint on `:code` alone leaks across tenants.

data/docs/reference/tenancy/index.md

@@ -20,7 +20,7 @@ Configure the portal once. The policy and model conventions then carry tenancy a
 
 ## 🚨 Critical (applies to all three sub-pages)
 
-- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins triggers `verify_default_relation_scope_applied!`. Always call `default_relation_scope(relation)` explicitly — not `super`.
+- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins triggers `verify_default_relation_scope_applied!`. Make sure `default_relation_scope(relation)` is called somewhere in the chain — explicitly here, or via `super` to a parent policy (e.g., a package base) that calls it.
 - **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.
 - **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.

data/docs/reference/tenancy/invites.md

@@ -36,19 +36,21 @@ rails generate pu:invites:install
 | `--entity-model=NAME` | `Entity` | Entity model name |
 | `--user-model=NAME` | `User` | User model name |
 | `--invite-model=NAME` | `<EntityModel><UserModel>Invite` | Invite class name (omit for single-flow apps) |
-| `--membership-model=NAME` | `EntityUser` | Membership join model |
-| `--roles` | `member,admin` | Comma-separated roles |
+| `--membership-model=NAME` | `EntityUser` | Membership join model (must already exist) |
 | `--rodauth=NAME` | `user` | Rodauth configuration for signup |
 | `--enforce-domain` | `false` | Require invited email domain to match entity domain |
 
+::: info Roles come from the membership model
+The role list is read from the membership model's `enum :role` — there is no `--roles=` flag on `pu:invites:install`. Set roles when generating the membership model (`pu:saas:membership --roles=...`) or edit its 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.
+:::
+
 Example with custom models:
 
 ```bash
 rails g pu:invites:install \
   --entity-model=Organization \
   --user-model=Customer \
-  --membership-model=OrganizationMember \
-  --roles=member,manager,admin
+  --membership-model=OrganizationMember
 ```
 
 After install:
@@ -317,10 +319,15 @@ Requires the invited email's domain to match the entity's domain.
 
 ### Custom roles
 
+Roles are defined on the membership model, not on the invites generator. Set them at membership generation time (ordering matters — **index 0 is the most privileged**, typically `owner`):
+
 ```bash
-rails g pu:invites:install --roles=viewer,editor,admin,owner
+rails g pu:saas:membership --user Customer --entity Organization --roles=admin,editor,viewer
+# → enum :role, { owner: 0, admin: 1, editor: 2, viewer: 3 }  (owner is auto-prepended)
 ```
 
+Or edit `enum :role` on the existing membership model directly. Then run `pu:invites:install`.
+
 ### Custom expiration
 
 Override on the model:

data/docs/reference/ui/components.md

@@ -10,6 +10,7 @@ Inside any `Plutonium::UI::Component::Base` subclass (or any page/form/display c
 PageHeader(title: "Dashboard", description: "...", actions: [...])
 Panel(class: "mt-4") { p { "Content" } }
 Block { TabList(items: tabs) }
+Avatar(user)
 EmptyCard("No items found")
 ActionButton(action, url: "/posts/new")
 DynaFrameHost(src: "/some/path", loading: :lazy)
@@ -23,6 +24,58 @@ Breadcrumbs()
 
 These are shorthand for `render Plutonium::UI::PageHeader.new(...)` etc. — they work because every component class is exposed as a method on `Plutonium::UI::Component::Base`.
 
+## Avatar
+
+`Plutonium::UI::Avatar` renders a profile image for a subject. It resolves an optional image source and falls back to a deterministic avatar from the hosted [Navii](https://navii.dev) service, then to a generic user icon when there's nothing to show.
+
+![Avatar — Navii fallback across sizes, deterministic faces for string subjects, explicit image src, and the icon fallback](/images/components/avatar.png)
+
+```ruby
+Avatar(user)                      # Navii fallback seeded from the record
+Avatar(user, src: :avatar)        # user.avatar if present, else Navii fallback
+Avatar(user, src: user.avatar)    # pass the attachment/uploader/URL directly
+Avatar("acme-team")               # a String subject is a deterministic seed
+Avatar("https://.../p.png")       # a URL-shaped subject is shown as the image
+Avatar(src: "https://.../p.png")  # a bare image, no subject/fallback
+```
+
+| Param     | Default | Notes |
+|-----------|---------|-------|
+| `subject` | `nil`   | **Positional.** The identity the fallback is seeded from: a record (hashed to a PII-free seed) or a String. Also the default `alt`. A **URL-shaped** String (`http(s)://…` or `/…`) is treated as `src` instead, so `Avatar(photo_url)` shows the image. |
+| `src:`    | `nil`   | The image. A **Symbol** names a method on the subject (`:avatar` → `subject.avatar`); otherwise an ActiveStorage attachment, [active_shrine](https://github.com/radioactive-labs/active_shrine)/Shrine uploader, or URL string. |
+| `size:`   | `:md`   | Semantic `:xs 24 / :sm 32 / :md 40 / :lg 48 / :xl 64`, or a raw Integer (px). |
+| `alt:`    | derived | Defaults to the String subject, or the record's display name. |
+| `class:`  | —       | Merged over the default `rounded-full` classes. |
+
+### How the source resolves
+
+`src` is resolved in this order, so the same component works across attachment libraries:
+
+- **ActiveStorage** attachment → `helpers.url_for` (the Rails-routable redirect path)
+- **active_shrine** / Shrine `UploadedFile` / CarrierWave (anything responding to `#url`) → `value.url`
+- **URL string** (`"https://…"` or `"/…"`) → used as-is
+
+When `src` is absent or unattached, a Navii avatar is rendered from the subject; with no subject either, a generic user icon is shown.
+
+::: tip Symbol `src` is a contract
+`Avatar(user, src: :avatar)` calls `user.avatar` — the subject **must** respond to it (a `NoMethodError` is raised otherwise). Use a Symbol `src` only with a record subject, not a value that might be a plain string (e.g. a guest `current_user`).
+:::
+
+### Privacy
+
+The value sent to Navii is **always a hash** of the subject's identity (`Digest::SHA256` of `"Class:id"` for a record, or of the string for a String subject). No model names, IDs, emails, or seed strings ever reach the external service, and the avatar stays deterministic (same subject → same avatar).
+
+### Configuration
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure do |config|
+  config.navii_host_url = "https://api.navii.dev"  # default; repoint to self-host/proxy
+end
+```
+
+The component appends Navii's `/avatar/:seed` route to this host.
+
 ## Writing custom Phlex components
 
 ```ruby

data/docs/reference/ui/forms.md

@@ -150,7 +150,7 @@ end
 - Bare tag — just the input element. Use when you're laying out custom wrappers.
 - `wrapped(class: "...")` — pass classes to the wrapper div.
 
-## Association inputs (`secure_association_tag`)
+## Association inputs (`secure_association_tag`) {#association-inputs}
 
 Association inputs render with two affordances out of the box:
 

data/docs/reference/ui/pages.md

@@ -133,17 +133,18 @@ See [Forms › Association inputs](./forms#association-inputs).
 
 ## Modals & slideovers
 
-The framework's `:new` / `:edit` actions render inline inside a modal. Choose the chrome per-resource via the definition:
+The framework's `:new` / `:edit` actions and any interactive action render inline inside a modal. Choose the chrome (and optional width) per-resource via the definition — interactive actions inherit the same default:
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  modal :slideover    # default — slide-in panel from the right
-  # modal :centered   # centered dialog
-  # modal false       # full standalone pages (no modal)
+  modal :slideover               # default — slide-in panel from the right
+  # modal :centered              # centered dialog
+  # modal :centered, size: :lg   # centered, wider container
+  # modal false                  # full standalone pages (no modal)
 end
 ```
 
-Custom interactive actions render in their own dialog with their own per-action `modal:` option (`:centered` default, or `:slideover`). See [Resource › Actions](/reference/resource/actions#action-options).
+`size:` accepts `:sm`, `:md` (default), `:lg`, `:xl`, `:auto` (hugs content width), or `:full`. Per-action `modal:` / `size:` on an interactive action overrides the definition's default. See [Resource › Actions](/reference/resource/actions#action-options).
 
 ## Tabs on the show page
 

data/docs/reference/ui/tables.md

@@ -8,8 +8,9 @@ The index page's table rendering. Override the `Table` nested class in your defi
 class PostDefinition < ResourceDefinition
   class Table < Table
     def view_template
-      render_search_bar
-      render_scopes_bar
+      render_toolbar         # search + view toggle + filter buttons
+      render_scopes_pills    # scope chips (if any scopes defined)
+      render_filter_pills    # active-filter chips
 
       if collection.empty?
         render_empty_card
@@ -20,6 +21,7 @@ class PostDefinition < ResourceDefinition
         end
       end
 
+      render_bulk_actions_toolbar
       render_footer
     end
   end
@@ -30,8 +32,10 @@ end
 
 | Method | Purpose |
 |---|---|
-| `render_search_bar` | Toolbar search input |
-| `render_scopes_bar` | Quick-filter scope buttons |
+| `render_toolbar` | Search input + view toggle + filter button |
+| `render_scopes_pills` | Quick-filter scope chips (only renders if scopes defined) |
+| `render_filter_pills` | Active-filter chips |
+| `render_bulk_actions_toolbar` | Bulk action bar (only renders when rows selected) |
 | `render_table` | Default table rendering |
 | `render_empty_card` | Empty state |
 | `render_footer` | Pagination |