plutonium 0.52.0 → 0.53.0

data/app/views/plutonium/_resource_header.html.erb

@@ -7,7 +7,8 @@
     <%=
       render Plutonium::UI::NavUser.new(
         name: nil,
-        email: current_user.try(:email) || current_user
+        email: current_user.try(:email) || current_user,
+        record: (current_user if current_user.respond_to?(:id))
       ) do |nav|
         if try(:profile_url)
           nav.with_section do |section|

data/docs/.vitepress/config.ts

@@ -108,6 +108,7 @@ export default defineConfig(withMermaid({
           text: "Reference",
           items: [
             { text: "Overview", link: "/reference/" },
+            { text: "Configuration", link: "/reference/configuration" },
           ]
         },
         {

data/docs/guides/authentication.md

@@ -70,7 +70,7 @@ The task creates the account and triggers a verification email; the admin sets t
 rails generate pu:saas:setup --user Customer --entity Organization
 ```
 
-⚠️ This is a **meta-generator** — it also runs `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, and `pu:invites:install`. Don't re-run those manually. See [Reference › Auth › Accounts › SaaS setup](/reference/auth/accounts#saas-setup-pu-saas-setup).
+⚠️ This is a **meta-generator** — it also runs `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, and `pu:invites:install`. Don't re-run those manually. See [Reference › Auth › Accounts › SaaS setup](/reference/auth/accounts#saas-setup).
 
 ### API-only (JWT)
 

data/docs/guides/custom-actions.md

@@ -186,7 +186,8 @@ action :name,
 
   # Behavior
   confirmation: "Are you sure?",
-  modal: :slideover                      # :centered (default) or :slideover
+  modal: :slideover,                     # :slideover / :centered — overrides definition's modal mode
+  size:  :lg                             # :sm / :md / :lg / :xl / :auto / :full — overrides definition's modal size
 ```
 
 Full options: [Reference › Resource › Actions › Action options](/reference/resource/actions#action-options).

data/docs/guides/customizing-ui.md

@@ -162,17 +162,18 @@ end
 
 ## Modals and slideovers
 
-By default `:new` and `:edit` render in a slideover panel. Switch to a centered modal or a full standalone page from the definition:
+By default `:new`, `:edit`, and every interactive action render in a slideover panel. Switch the chrome and width from the definition:
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  modal :slideover    # default — slide-in from the right
-  # modal :centered   # centered dialog
-  # modal false       # full standalone page
+  modal :slideover               # default — slide-in from the right
+  # modal :centered              # centered dialog
+  # modal :centered, size: :lg   # centered, wider container
+  # modal false                  # full standalone page
 end
 ```
 
-→ See [Reference › Resource › Actions](/reference/resource/actions) for per-action `modal:` options on interactive actions.
+`size:` accepts `:sm`, `:md` (default), `:lg`, `:xl`, `:auto` (hugs content), or `:full`. See [Reference › Resource › Actions](/reference/resource/actions) for per-action `modal:` / `size:` overrides on interactive actions.
 
 ## Layouts and the shell
 

data/docs/guides/multi-tenancy.md

@@ -8,7 +8,7 @@ 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` to a parent policy (e.g., a package base) that calls it.
+- **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.
 
@@ -28,7 +28,7 @@ rails g pu:saas:setup --user Customer --entity Organization
 
 This **meta-generator** creates the user + entity + membership trio AND runs `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, and `pu:invites:install` in one shot. The portal is fully wired for entity scoping.
 
-See [Reference › Auth › Accounts › SaaS setup](/reference/auth/accounts#saas-setup-pu-saas-setup).
+See [Reference › Auth › Accounts › SaaS setup](/reference/auth/accounts#saas-setup).
 
 ## Manual setup
 
@@ -69,7 +69,7 @@ Or pass `--scope=Organization` to `pu:pkg:portal` and the engine wires this auto
 mount CustomerPortal::Engine, at: "/customer"
 ```
 
-URLs now include the entity id: `/customer/organizations/42/posts`.
+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
 
@@ -88,14 +88,14 @@ end
 
 ```ruby
 scope_to_entity Organization, strategy: :path
-# → /organizations/:organization_id/posts
+# → /<mount>/:organization_scoped/posts   (request URL: /<mount>/42/posts)
 ```
 
 ### Custom param key
 
 ```ruby
 scope_to_entity Organization, strategy: :path, param_key: :org_id
-# → /orgs/:org_id/posts
+# → /<mount>/:org_id/posts   (same URL shape, just renames params[:organization_scoped] → params[:org_id])
 ```
 
 ### Subdomain / session / custom
@@ -187,7 +187,7 @@ relation_scope do |relation|
 end
 ```
 
-🚨 `default_relation_scope(relation)` must be called somewhere in the chain — otherwise the runtime verification raises. Calling it explicitly here is safest; `super` works only if the parent policy also calls it.
+🚨 `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
 

data/docs/guides/theming.md

@@ -148,7 +148,7 @@ Pre-styled ready-to-use components:
 | 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` |
 
-Full catalog: [Reference › UI › Assets › Component classes](/reference/ui/assets#component-classes-pu-).
+Full catalog: [Reference › UI › Assets › Component classes](/reference/ui/assets#component-classes-pu).
 
 ## Migrating from hardcoded classes
 

data/docs/reference/auth/accounts.md

@@ -89,7 +89,7 @@ EMAIL=admin@example.com rails rodauth:admin
 
 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 — `pu:saas:setup` (meta-generator) {#saas-setup}
 
 Creates the User + Entity + Membership trio AND runs:
 

data/docs/reference/behavior/policies.md

@@ -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/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

@@ -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,18 +238,19 @@ The strategy symbol must match a method name on the controller concern.
 
 ### Custom param key
 
-The default `param_key` derives from the entity class — `<singular_route_key>_scoped` — to avoid collisions with a `belongs_to :organization` on child models. So `scope_to_entity Organization` produces routes like `/organization_scoped/:organization_scoped_id/posts`. Override when you want a cleaner URL:
+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:
 
-```ruby
-scope_to_entity Organization, strategy: :path, param_key: :org_id
-# → /org_id/:org_id/posts
+```
+mount CustomerPortal::Engine, at: "/customer"
+# → /customer/:organization_scoped/posts   (route definition)
+# → /customer/42/posts                     (request URL)
 ```
 
-Pair with `route_key:` to control the path segment as well:
+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, route_key: :orgs
-# → /orgs/:org_id/posts
+scope_to_entity Organization, strategy: :path, param_key: :org_id
+# → params[:org_id] instead of params[:organization_scoped]
 ```
 
 ### Accessing the scoped entity
@@ -353,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/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/superpowers/specs/2026-05-29-avatar-component-design.md

@@ -0,0 +1,153 @@
+# Avatar Component (Navii fallback) — Design
+
+**Date:** 2026-05-29
+**Status:** Approved, ready for implementation plan
+
+## Summary
+
+Add a reusable `Plutonium::UI::Avatar` Phlex component that renders a profile
+image from an optional attachment/uploader/URL, and falls back to a
+deterministic avatar generated by the hosted [Navii](https://navii.dev) service
+when no image is supplied. Adopt it in `NavUser` and `Card`.
+
+## Motivation
+
+`NavUser` currently renders a supplied `avatar_url` or a generic User icon, and
+`Card`'s `:image` slot resolves attachments/URLs but has no fallback. There is no
+shared, reusable way to render a profile image with a sensible default. Navii
+provides deterministic, zero-dependency avatars via a simple image URL, which
+fits a server-rendered Phlex component cleanly.
+
+## Integration approach
+
+**Hosted URL, server-rendered.** Render a plain `<img>` whose `src` points at the
+Navii hosted API. No npm dependency, no Stimulus controller, no build step, fully
+SSR-friendly.
+
+Navii URL shape: `https://api.navii.dev/avatar/{seed}?size={px}` (SVG by default,
+which scales cleanly inside an `<img>`).
+
+## Component API
+
+New component: `lib/plutonium/ui/avatar.rb` → `Plutonium::UI::Avatar`, extending
+`Plutonium::UI::Component::Base`, sitting alongside `NavUser` as a general UI
+primitive. Registered in `Component::Kit` as `Avatar(...)`.
+
+```ruby
+Avatar(user)                     # → Navii fallback seeded from the record
+Avatar(user, src: :photo)        # → user.photo if present, else Navii fallback
+Avatar(user, src: user.photo)    # → pass the attachment/uploader/URL directly
+Avatar("acme-team")              # → String subject = literal seed
+Avatar(src: "https://.../p.png") # → bare image, no subject/fallback
+```
+
+### Parameters
+
+| Param      | Default | Notes |
+|------------|---------|-------|
+| `subject`  | `nil`   | **Positional.** The identity the fallback is seeded from: a record (hashed to a PII-free seed) or a String (used verbatim). Also the default `alt`. |
+| `src:`     | `nil`   | The image. A Symbol names a method on the subject (`:avatar` → `subject.avatar`); otherwise an ActiveStorage attachment, 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). Drives the Navii `?size=`, the `<img>` width/height, and the `w-/h-` classes. |
+| `alt:`     | derived | Defaults to the String subject, or `display_name_of(record)`. |
+| `class:`   | —       | Merged over the default `rounded-full` classes (passthrough). |
+
+The earlier `record:`/`seed:` split collapsed into the single positional
+`subject` (record **or** String), and `size:` moved from raw pixels to a
+semantic scale (Integer still accepted as an escape hatch).
+
+## Resolution + seed logic
+
+1. **Resolve `src`** using the logic currently in `card.rb`'s `image_src_for`:
+   - ActiveStorage (`responds_to? :attached?`) → `helpers.url_for(value)` when attached, else `nil`
+   - Uploader (`responds_to? :url`) → `value.url`
+   - String starting with `http` or `/` → passthrough
+   - rescue `ArgumentError`/`URI::InvalidURIError` → `nil`
+
+   This method is **extracted into the Avatar component** (or a shared resolver
+   module) and `Card` delegates to it, removing the current duplication.
+
+2. If `src` resolves to a URL → render it.
+
+3. Otherwise build a Navii URL from the seed.
+
+### Seed derivation (no PII)
+
+The value sent to Navii is **always** a short SHA256 hash, regardless of subject
+type — no plaintext ever leaves the app:
+
+- Record `subject` → identity `"#{record.class.name}:#{record.id}"`, then hashed.
+- String `subject` → the string is hashed (not sent verbatim).
+- Final seed = `Digest::SHA256.hexdigest(identity)[0, 16]`.
+
+This keeps model names, raw IDs, emails, and any caller-provided seed string out
+of the URL that reaches the external service, while preserving determinism (same
+identity → same hash → same avatar).
+
+### Navii host configuration
+
+Add `config.navii_host_url` to `lib/plutonium/configuration.rb`, defaulting to
+`https://api.navii.dev` (host only — the component appends the `/avatar/:seed`
+route, which is Navii's API shape). Lets apps self-host or repoint the service
+without code changes.
+
+## Rendering
+
+A single `<img>`:
+- `src` = resolved image URL or Navii URL
+- default classes `rounded-full object-cover`, plus the semantic `w-/h-` size
+  class (so Tailwind preflight's `img { height: auto }` doesn't collapse the
+  dimensions), with caller `class:` merged over
+- `width` / `height` = pixel size; raw-Integer sizes also emit an inline
+  `width/height` style
+- `loading: "lazy"`
+- `alt:` from `alt:` or the subject
+
+No JavaScript; fully server-rendered.
+
+### Last-resort guard
+
+If there is no resolvable `src` **and** no `subject` to derive a seed from, fall
+back to a generic User icon (sized to match) rather than emitting a broken Navii
+URL. In all other cases a Navii avatar is rendered (the generic-icon branch in
+`NavUser` is otherwise removed).
+
+## Integration points
+
+### NavUser (`lib/plutonium/ui/nav_user.rb`)
+
+- Add a `record:` parameter, passed `current_user` from
+  `app/views/plutonium/_resource_header.html.erb`.
+- Replace the inline `<img>` / icon-fallback branch in `render_trigger_button`
+  with `Avatar(record, src: avatar_url, size: :sm, ...)`.
+- `avatar_url:` continues to work as an explicit override.
+- The generic-User-icon fallback is removed (now handled by the component's
+  last-resort guard only).
+
+### Card (`lib/plutonium/ui/grid/card.rb`)
+
+- The small `:image` slot renders `Avatar(src: value, size: :lg)` — **no
+  subject is passed**, so an image-less card falls back to Avatar's generic
+  icon rather than firing a per-card request to the external Navii service
+  (which would mean one third-party request per record in a grid). The
+  `:cover` banner stays a plain `<img>` (no avatar fallback).
+- The `:cover` branch calls `Avatar.resolve_image_src` directly; the old
+  `image_src_for` helper (duplicated resolution logic) is removed.
+
+## Testing
+
+Unit tests for `Avatar` (`test/plutonium/ui/avatar_test.rb`):
+- `resolve_image_src` paths: nil, URL strings, uploader `#url`, ActiveStorage via
+  `url_for`, and active_shrine-style wrappers (attached?+url) via `#url`
+- `src` precedence; Symbol `src` sent to the subject; Symbol `src` with no subject
+- record seed determinism + absence of PII; String subject as literal seed (+escaping)
+- semantic size → `?size=`, `w-/h-` classes, `width`/`height`; Integer size → inline style
+- `alt` default vs explicit
+- last-resort icon when there is neither `src` nor subject (and record without id)
+- configured Navii base URL
+
+## Out of scope (YAGNI)
+
+- Client-side `@usenavii` SDK / Stimulus rendering
+- Self-hosted/vendored generation
+- Non-circular shapes, status badges, image cropping/upload UI
+- Caching / proxying Navii responses

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.51.0)
+    plutonium (0.52.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.51.0)
+    plutonium (0.52.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.51.0)
+    plutonium (0.52.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/lib/generators/pu/lite/solid_errors/solid_errors_generator.rb

@@ -44,9 +44,13 @@ module Pu
 
           Rails.application.configure do
             config.solid_errors.connects_to = {database: {writing: :#{@db_name}}}
-            config.solid_errors.send_emails = ENV["SOLID_ERRORS_SEND_EMAILS"].present?
-            config.solid_errors.email_from = ENV["SOLID_ERRORS_EMAIL_FROM"]
-            config.solid_errors.email_to = ENV["SOLID_ERRORS_EMAIL_TO"]
+            config.solid_errors.email_from = ENV["SOLID_ERRORS_EMAIL_FROM"].presence
+            config.solid_errors.email_to = ENV["SOLID_ERRORS_EMAIL_TO"].presence
+            # Only deliver notifications when explicitly opted in AND both addresses are
+            # configured. Enabling send_emails without a valid from/to makes Solid Errors
+            # attempt to deliver malformed mail.
+            config.solid_errors.send_emails = ENV["SOLID_ERRORS_SEND_EMAILS"].present? &&
+              config.solid_errors.email_from.present? && config.solid_errors.email_to.present?
             config.solid_errors.username = ENV.fetch("SOLID_ERRORS_USERNAME", nil)
             config.solid_errors.password = ENV.fetch("SOLID_ERRORS_PASSWORD", nil)
           end