plutonium 0.51.0 → 0.53.0

data/docs/superpowers/plans/2026-05-15-public-pages-overhaul.md.tasks.json

@@ -0,0 +1,109 @@
+{
+  "planPath": "docs/superpowers/plans/2026-05-15-public-pages-overhaul.md",
+  "tasks": [
+    {
+      "id": 1,
+      "subject": "Task 0: Shared CSS tokens and primitives",
+      "status": "pending",
+      "description": "**Goal:** Add design-system tokens to docs/.vitepress/theme/custom.css.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/custom.css\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"tokens defined\",\"primitives render\",\"no regressions\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 2,
+      "subject": "Task 1: HomeHero component",
+      "status": "pending",
+      "blockedBy": [1],
+      "description": "**Goal:** Build the locked hero.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeHero.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"hero renders\",\"cursor blinks\",\"responsive\",\"CTAs work\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 3,
+      "subject": "Task 2: HomeStopWriting (Section 1)",
+      "status": "pending",
+      "blockedBy": [1, 2],
+      "description": "**Goal:** Surface-area before/after.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeStopWriting.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"section renders\",\"stats correct\",\"responsive\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 4,
+      "subject": "Task 3: HomePillars (Section 2)",
+      "status": "pending",
+      "blockedBy": [1, 3],
+      "description": "**Goal:** Four-pillar grid.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomePillars.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"4 pillars render\",\"copy verbatim\",\"responsive\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 5,
+      "subject": "Task 4: HomeWalkthrough layout (Section 3)",
+      "status": "pending",
+      "blockedBy": [1, 4],
+      "description": "**Goal:** Walkthrough section layout with placeholders.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeWalkthrough.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"layout reserves space\",\"labels visible\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 6,
+      "subject": "Task 5: HomeAudienceSplit (Section 4)",
+      "status": "pending",
+      "blockedBy": [1, 5],
+      "description": "**Goal:** Side-by-side audience split.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeAudienceSplit.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"two columns\",\"locked copy\",\"responsive\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 7,
+      "subject": "Task 6: HomeInTheBox (Section 5)",
+      "status": "pending",
+      "blockedBy": [1, 6],
+      "description": "**Goal:** Categorized in-the-box section.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeInTheBox.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"3 rows render\",\"copy matches spec\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 8,
+      "subject": "Task 7: HomeCta with template-toggle pills (Section 6)",
+      "status": "pending",
+      "blockedBy": [1, 7],
+      "description": "**Goal:** Manifesto CTA with reactive template-toggle pills.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeCta.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"pills toggle\",\"URLs correct\",\"CTAs link\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 9,
+      "subject": "Task 8: SectionLanding shared component",
+      "status": "pending",
+      "blockedBy": [1],
+      "description": "**Goal:** Reusable rail+sidebar layout for section landings.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/SectionLanding.vue\",\"docs/.vitepress/theme/index.ts\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"numbered renders\",\"categorized renders\",\"responsive\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 10,
+      "subject": "Task 9: Getting Started landing",
+      "status": "pending",
+      "blockedBy": [9],
+      "description": "**Goal:** Rewrite getting-started/index.md.\n\n```json:metadata\n{\"files\":[\"docs/getting-started/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"8 steps render\",\"links resolve\",\"prereqs preserved\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 11,
+      "subject": "Task 10: Guides landing",
+      "status": "pending",
+      "blockedBy": [9],
+      "description": "**Goal:** Rewrite guides/index.md.\n\n```json:metadata\n{\"files\":[\"docs/guides/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"categories render\",\"links resolve\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 12,
+      "subject": "Task 11: Reference landing",
+      "status": "pending",
+      "blockedBy": [9],
+      "description": "**Goal:** Rewrite reference/index.md.\n\n```json:metadata\n{\"files\":[\"docs/reference/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"categories match real sidebar\",\"links resolve\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 13,
+      "subject": "Task 12: Demo app + asciinema + screenshots",
+      "status": "pending",
+      "description": "**Goal:** Produce walkthrough assets from a fresh demo app.\n\n```json:metadata\n{\"files\":[\"docs/public/images/home-portal.png\",\"docs/public/images/home-index.png\",\"docs/public/images/home-form.png\",\"docs/public/asciinema/home-scaffold.cast\"],\"verifyCommand\":\"ls -la docs/public/images/home-*.png docs/public/asciinema/home-scaffold.cast\",\"acceptanceCriteria\":[\"4 assets exist\",\"non-empty\",\"correct format\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 14,
+      "subject": "Task 13: Wire assets into HomeWalkthrough",
+      "status": "pending",
+      "blockedBy": [5, 13],
+      "description": "**Goal:** Replace placeholders with real screenshots + asciinema embed.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeWalkthrough.vue\",\"docs/.vitepress/theme/index.ts\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"screenshots render\",\"asciinema plays\",\"no console errors\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 15,
+      "subject": "Task 14: Visual sweep + user verification",
+      "status": "pending",
+      "blockedBy": [8, 10, 11, 12, 14],
+      "description": "**Goal:** Cross-cutting sweep and user sign-off.\n\n```json:metadata\n{\"files\":[],\"verifyCommand\":\"yarn docs:build\",\"acceptanceCriteria\":[\"all 4 pages render in both modes\",\"no console errors\",\"build succeeds\",\"user approved\"],\"requiresUserVerification\":true,\"userVerificationPrompt\":\"All four public pages are live in `yarn docs:dev`. Have you reviewed Home, Getting Started, Guides, and Reference and are they ready to ship?\"}\n```"
+    }
+  ],
+  "lastUpdated": "2026-05-15T00:00:00Z"
+}

data/docs/superpowers/specs/2026-05-15-public-pages-overhaul-design.md

@@ -0,0 +1,263 @@
+# Public Pages Overhaul — Design
+
+**Date:** 2026-05-15
+**Scope:** `docs/index.md`, `docs/getting-started/index.md`, `docs/guides/index.md`, `docs/reference/index.md`
+**Goal:** Overhaul the four public landing pages of the Plutonium docs site. Blend Filament's polish with Rails' editorial voice. Address two audiences (Rails developers, founders/teams) without choosing one. Make AI-readiness an equal pillar, not the headline.
+
+---
+
+## Direction at a glance
+
+- **Voice:** plain & honest, peer-to-peer to Rails devs, accessible to founders. No hyped numerals, no "0% AI-comprehensible" framing.
+- **Polish:** Filament-style two-column hero, animated terminal, dark sections punctuated by light section bands.
+- **Proof:** real screenshots captured from a fresh scaffolded demo app; asciinema recording captured during the same scaffolding session.
+- **Sequence (home):** proof-first arc — show what it does, then why it's built that way, then who it's for.
+
+---
+
+## Home page (`docs/index.md`)
+
+Seven blocks. Hero first, then six numbered sections. Section ordering is fixed.
+
+### 0. Hero — locked
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│  PLUTONIUM · THE RAILS RAD FRAMEWORK                           │
+│                                                                │
+│  The Rails framework                  ┌────────────────────┐  │
+│  for things you should never          │ $ rails g pu:res:  │  │
+│  write again.                         │   scaffold Post …  │  │
+│                                       │ $ rails g pu:res:  │  │
+│  Convention over configuration,       │   conn Post --dest │  │
+│  extended to everything you           │   =admin_portal    │  │
+│  keep rebuilding.                     │ $ _                │  │
+│                                       └────────────────────┘  │
+│  CRUD. Auth. Authorization. Multi-                             │
+│  tenancy. Admin portals. Search,                               │
+│  filters, bulk actions. All generated.                         │
+│  All customizable. All Rails.                                  │
+│                                                                │
+│  [ Get started → ]  [ 15-min tutorial ]                        │
+└────────────────────────────────────────────────────────────────┘
+```
+
+- **Layout:** dark background (`#0d1117`), two columns. Left: eyebrow → headline → lede → pillar list → CTAs. Right: animated terminal (asciinema embed once recorded; CSS-animated placeholder until then).
+- **Eyebrow:** `PLUTONIUM · THE RAILS RAD FRAMEWORK`
+- **Headline:** "The Rails framework for things you should never write again."
+- **Lede:** "Convention over configuration, extended to everything you keep rebuilding."
+- **Pillar line:** "**CRUD. Auth. Authorization. Multi-tenancy. Admin portals. Search, filters, bulk actions.** All generated. All customizable. All Rails."
+- **CTAs:** primary "Get started →" → `/getting-started/`; ghost "15-min tutorial" → `/getting-started/tutorial/`.
+- **Terminal content:**
+  ```
+  $ rails g pu:res:scaffold Post title:string body:text
+        create  app/models/post.rb
+        create  app/resource_registries/post_definition.rb
+        create  db/migrate/...create_posts.rb
+  $ rails g pu:res:conn Post --dest=admin_portal
+        route   resource :posts
+        ✓ Connected Post to AdminPortal
+  $ _
+  ```
+
+### 1. What you stop writing — capability comparison
+
+Surface-area before/after. Compares **what's included** rather than lines or time. Two columns side-by-side: hand-rolled file tree (with "before search, filters, bulk actions, auth…" trailing) vs Plutonium two-command terminal. Stat row below each side compares capabilities (Just CRUD / No auth / No search vs Full CRUD / + Auth / + Search / + Filters / + Bulk actions).
+
+Section title: "What you stop writing."
+Subtitle: "A blog with posts, comments, an admin panel, and authorization. Same feature, two paths."
+
+### 2. Four pillars
+
+Plain & honest naming. Four equal cards in a 4-column grid. Light section band.
+
+- **Convention over configuration** — Extended to resources, policies, portals, and tenancy — not just routes and views.
+- **It's just Rails** — Generated code lives in your repo. Edit it, override it, delete it. The "magic" is regular Ruby mixins you can read.
+- **Multi-tenant ready** — Path or domain tenancy. Scoped relations. Invites and memberships out of the box.
+- **AI-readable** — Predictable file layout and naming. Built-in skills teach AI assistants the patterns.
+
+Section title: "Built on principles, not magic."
+
+### 3. A real example, walked through
+
+Hero portal shot up top (wide), then a 3-column strip below: asciinema terminal · index page screenshot · form page screenshot.
+
+- **Wide shot:** the portal layout with sidebar/nav and the posts index visible.
+- **Asciinema:** the scaffold commands captured during the demo-app creation (see Assets section).
+- **Index screenshot:** `/admin/posts` table view.
+- **Form screenshot:** `/admin/posts/new` auto-generated form.
+
+Section title: "Two commands. A whole portal."
+
+### 4. For Rails devs / For founders
+
+Side-by-side audience split. Two columns of equal weight separated by a thin divider.
+
+**Left — For Rails developers**
+> The missing layer between Rails and the apps you keep building.
+- Convention extended to CRUD, policies, and portals
+- Generated code lives in your repo — edit anything
+- Mountable Rails engines for packages and portals
+- ActionPolicy authorization, baked in
+
+**Right — For founders & teams**
+> Skip the SaaS template debate. Plutonium turns Rails into a SaaS toolkit.
+- Admin panel, signup, and invites on day one
+- Multi-tenant scoping when you need it
+- No template lock-in — it's just your Rails app
+- Ship faster with AI tools that understand your code
+
+Section title: "Plutonium fits two kinds of teams."
+
+### 5. What's in the box — categorized
+
+Three category rows. Each row has a small uppercase header (red `#d33`) and a 3-column grid of capabilities. Each capability has a bold name and a one-line description.
+
+- **Resources** — Scaffolds · Search & filters · Custom & bulk actions
+- **App structure** — Portals · Packages · Multi-tenancy
+- **People & access** — Auth (Rodauth) · Authorization · Invites & memberships
+
+Section title: "Organized the way you'll use it."
+
+### 6. CTA — manifesto close
+
+Centered block with subtle gradient background.
+
+- **Line:** *"Stop writing the parts of every Rails app you've already written. Plutonium is what should have been there all along."*
+- **Template toggle pills (centered):**
+  - `plutonium` — *core + portals*
+  - `pluton8` — *+ SaaS lite stack*
+- **Install command (changes with selected pill):**
+  - `plutonium`: `rails new my_app -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb`
+  - `pluton8`: `rails new my_app -m https://radioactive-labs.github.io/plutonium-core/templates/pluton8.rb`
+- **CTAs:** primary "Get started →" → `/getting-started/`; ghost "GitHub" → repo.
+
+The pill toggle is a small Vue component (the docs site is VitePress, not a Plutonium app — so no Stimulus). Swaps the install command line on click.
+
+---
+
+## Section landings (`getting-started/`, `guides/`, `reference/`)
+
+All three use **Pattern B — numbered rail with sidebar**. Eyebrow + h1 + lede above; below, a two-column layout: left rail = numbered/categorized list of the section's content (vertical red bar), right sidebar = shortcuts and help.
+
+### Getting Started (`docs/getting-started/index.md`)
+
+- **Eyebrow:** GETTING STARTED
+- **H1:** "Get a working Plutonium app in 15 minutes."
+- **Lede:** "Walk the path top to bottom, or skip to the part you need."
+- **Left rail (numbered steps from the tutorial):**
+  1. Project setup
+  2. First resource
+  3. Authentication
+  4. Authorization
+  5. Custom actions
+  6. Nested resources
+  7. Author portal
+  8. Customizing UI
+- **Right sidebar:**
+  - *Already know your way around?* — Installation · Concepts overview · Generators reference
+  - *Need help?* — GitHub Discussions · Open an issue
+
+### Guides (`docs/guides/index.md`)
+
+- **Eyebrow:** GUIDES
+- **H1:** "How to do the things Plutonium apps do."
+- **Lede:** "Task-oriented walkthroughs for the parts of the framework you reach for most."
+- **Left rail (categorized, not numbered — uses category headers between groups):**
+  - Setup & Resources — Adding Resources · Creating Packages
+  - Auth — Authentication · Authorization
+  - Features — Custom Actions · Nested Resources · Multi-tenancy · Search & Filtering · User Invites
+  - Customization — Theming
+  - Quality — Testing
+- **Right sidebar:**
+  - *New to Plutonium?* — Start with the tutorial
+  - *Looking for APIs?* — Browse the reference
+  - *Need help?* — GitHub Discussions
+
+### Reference (`docs/reference/index.md`)
+
+- **Eyebrow:** REFERENCE
+- **H1:** "Every API, in one place."
+- **Lede:** "The full surface area of Plutonium — controllers, policies, definitions, fields, interactions, generators."
+- **Left rail (categorized, not numbered):**
+  - App — Overview · Packages · Portals
+  - Resource — Definitions · Fields · Policies · Controllers · Interactions
+  - UI — Pages · Forms · Tables · Displays
+  - Tooling — Generators · Testing helpers
+- **Right sidebar:**
+  - *Learning?* — Tutorial · Concepts
+  - *Solving a problem?* — Guides
+  - *Need help?* — GitHub Discussions
+
+---
+
+## Visual system
+
+Reused across all four pages so they feel like one product.
+
+- **Type:** system sans, headlines with `-0.02em` to `-0.025em` letter-spacing for tightness.
+- **Color tokens:**
+  - Dark surface: `#0d1117`
+  - Light surface: `#fff`
+  - Subtle band: `#fafafa`
+  - Border: `#e0e0e0`
+  - Muted text: `#666`
+  - Accent (red): `#d33` (matches existing Plutonium brand)
+  - Success pill: `#ecf9f1` / `#0a7c3f`
+- **Terminal block:** rounded 6–8px, `#161b22` body on dark sections, `#0d1117` on light sections, `#7ee787` for prompts, `#58a6ff` cursor.
+- **Animated cursor:** blink every 1s.
+- **Buttons:** primary red (`#d33` bg, white text); ghost (transparent, border, current color).
+- **Eyebrow style:** 11–12px uppercase, `0.1em` letter-spacing.
+
+These tokens should be added as CSS variables in `docs/.vitepress/theme/custom.css` (or wherever existing landing styles live) so they're shareable across pages.
+
+---
+
+## Assets to produce
+
+1. **Demo Rails app for screenshots + asciinema** — scaffold a fresh Rails app via the `plutonium` template, generate `Post(title:string, body:text, published:boolean)` and `Comment(post:references, body:text)`, connect both to an `AdminPortal`. Capture asciinema during this scaffold + boot session.
+
+2. **Asciinema recording** — saved alongside the page assets (likely `docs/public/asciinema/` or `docs/public/images/`). Trim to ~30s. Loop. Embedded via asciinema-player or a CSS-animated SVG/gif fallback.
+
+3. **Screenshots (3)** —
+   - `home-portal.png` — wide shot of the portal layout with sidebar + posts index visible
+   - `home-index.png` — close shot of `/admin/posts` table
+   - `home-form.png` — close shot of `/admin/posts/new` form
+
+   All captured at consistent viewport size (e.g., 1280×800), light mode, with seeded data (3–5 posts including a draft to show the boolean pill).
+
+---
+
+## Interaction
+
+Only one interactive element across the four pages:
+
+- **Template toggle pills** in the home-page CTA. Swaps between `plutonium.rb` and `pluton8.rb` install commands. Implementation: a Vue component registered in `docs/.vitepress/theme/index.ts` (the standard VitePress theme extension point), used in `docs/index.md` via `<TemplateToggle />`.
+
+Everything else is static.
+
+---
+
+## Structure of work
+
+Each piece below is independently buildable.
+
+1. **CSS theme tokens** — add the variables, button styles, terminal block, eyebrow class to the VitePress custom CSS. Foundation for everything else.
+2. **Home hero + section 1** — through the first proof block.
+3. **Home sections 2–4** — pillars, walkthrough placeholders (asciinema/screenshots come last), audience split.
+4. **Home sections 5–6** — in-the-box grid, manifesto CTA with template-toggle pills + Stimulus controller.
+5. **Getting Started landing** — Pattern B page.
+6. **Guides landing** — Pattern B page.
+7. **Reference landing** — Pattern B page.
+8. **Demo app + asciinema + screenshots** — produce the assets. Can run in parallel to 1–7.
+9. **Wire assets into home section 3** — replace placeholders.
+
+---
+
+## Out of scope
+
+- Inner pages (tutorial chapters, individual guides, reference subpages) — only the four landing pages are in scope.
+- Vitepress theme switch (light/dark toggle) — keep current behavior.
+- Logo, favicon, brand mark changes.
+- Pricing, blog, changelog — no such pages exist; not adding them here.
+- Search UX, sidebar/nav changes — those live in `.vitepress/config.ts` and aren't part of this overhaul.

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.50.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.50.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.50.0)
+    plutonium (0.52.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/lib/generators/pu/core/assets/assets_generator.rb

@@ -30,6 +30,8 @@ module Pu
       end
 
       def install_dependencies
+        failed = []
+
         [
           "@radioactive-labs/plutonium",
           "postcss", "postcss-cli", "postcss-import",
@@ -38,9 +40,17 @@ module Pu
           "flowbite-typography"
         ].each do |package|
           run "yarn add #{package}"
+          failed << "yarn add #{package}" unless $?.success?
         end
 
         run "yarn upgrade tailwindcss --latest"
+        failed << "yarn upgrade tailwindcss --latest" unless $?.success?
+
+        return if failed.empty?
+
+        say_status :warn,
+          "the following commands failed — your app may not boot until you resolve them:\n  #{failed.join("\n  ")}",
+          :yellow
       end
 
       def configure_application

data/lib/generators/pu/invites/install_generator.rb

@@ -429,12 +429,56 @@ module Pu
         say_status :info, "Integrated invite check into WelcomeController", :green
       end
 
+      def verify_active_record_encryption
+        return if behavior == :revoke
+        return if active_record_encryption_configured?
+
+        say_status :warning, "ActiveRecord encryption keys are not configured", :yellow
+        say <<~MSG.indent(2)
+
+          Invite tokens use `encrypts :token, deterministic: true`. Without keys,
+          creating or accepting an invite raises
+          ActiveRecord::Encryption::Errors::Configuration.
+
+          Generate keys and add them to credentials with:
+
+              bin/rails db:encryption:init
+
+          Then paste the printed `active_record_encryption:` block into
+          config/credentials.yml.enc (or set the equivalent ENV vars in
+          production).
+
+        MSG
+      end
+
       def show_instructions
         readme "INSTRUCTIONS" if behavior == :invoke
       end
 
       private
 
+      # Detect AR encryption configuration without booting the host app.
+      # Returns true if credentials.yml(.enc) has the keys, or if all three
+      # ENV vars are set. False otherwise — we'd rather over-warn than miss.
+      def active_record_encryption_configured?
+        env_keys = %w[
+          ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY
+          ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY
+          ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT
+        ]
+        return true if env_keys.all? { |k| ENV[k].to_s.length > 0 }
+
+        creds_path = Rails.root.join("config/credentials.yml.enc")
+        return false unless creds_path.exist?
+
+        decrypted = begin
+          Rails.application.credentials.config
+        rescue
+          nil
+        end
+        decrypted&.dig(:active_record_encryption, :primary_key).to_s.length > 0
+      end
+
       def entity_model
         options[:entity_model].camelize
       end

data/lib/generators/pu/invites/templates/packages/invites/app/controllers/invites/user_invitations_controller.rb.tt

@@ -7,6 +7,7 @@ module Invites
 <% end -%>
     include Plutonium::Invites::Controller
 
+    prepend_view_path Invites::Engine.root.join("app/views")
     layout "invites/invitation"
     helper_method :login_path