plutonium 0.51.0 → 0.53.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fd905a5d5a930d6805e0df02632a59a0c5ecd9052c190d341f22264640c3425
-  data.tar.gz: db6fbe37f645953c545c1f1fcd10ef82e0dc58cc996b47c2ef574812b0d6394b
+  metadata.gz: 1575a79af57aa89f49041cbdb1e31364cea08fb3d541398e095772470a3da6b8
+  data.tar.gz: a3d4dfebbec5836c9557c903393f7deebcfb17b94ca8d61ccb5a1dd1ffbd7aee
 SHA512:
-  metadata.gz: d30de7e455c8798a60a92777141197507595f8a5d37b7e9d355e0530d4590369470f24a36f62554f6c2dcede93e9de8ac0dc6e732fa8f984b64b41d75525a3a2
-  data.tar.gz: e95d855a9d9aee83d2edc4dac9d44f001389d4ef0f10cc9338f13c371e6798db4f73f67197b2d03b8699111ab8cb56ec8ed7335b34ec622c08dff9d8af336b1d
+  metadata.gz: 8c6954af1d7e64be809c28e06140b5660f58e94ec254fe2960c4d0b28b615f515df84d107528899d791ab3cc5bf38ac18cf623aa4c00d3a683bf7b963b96bc47
+  data.tar.gz: a5f6a8ea0ad4e9fafc6559aac4b488c131a6c796c58506a49a49e8088dd3408cd04641ab4ffef357b66a373f88bd6c99476eb2d1cd7cb79eaaf2c993c6322cf5

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

@@ -505,6 +505,8 @@ register_resource ::Post
 register_resource ::Profile, singular: true   # if --singular
 ```
 
+Re-running `pu:res:conn` for the same resource is **idempotent** — already-registered entries report `identical` and are not duplicated. Insertion falls back gracefully when the conventional `# register resources above` marker is missing (uses the `routes.draw do` opening), and warns clearly if it can't find any anchor.
+
 ### Generated controller
 
 ```ruby

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

@@ -45,7 +45,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) |
@@ -90,12 +89,15 @@ rails generate pu:rodauth:admin admin --extra-attributes=name:string,department:
 enum :role, super_admin: 0, admin: 1
 ```
 
-Rake task for direct admin creation:
+Rake task for direct admin creation (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)
 ```
 
+Creates the account and sends a verification email; the admin sets their own password through the flow. No password is passed on the command line.
+
 ### SaaS setup — `pu:saas:setup` (meta-generator)
 
 Creates the User + Entity + Membership trio AND runs:
@@ -109,7 +111,7 @@ Don't generate another entity portal after this. Pass `--force` to re-run.
 
 ```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/.claude/skills/plutonium-behavior/SKILL.md

@@ -18,7 +18,7 @@ For tenant-scoped `relation_scope` and entity scoping, load [[plutonium-tenancy]
 - **`ActiveRecord::RecordInvalid` is NOT rescued automatically in interactions.** Always rescue when using `create!` / `update!` / `save!`, return `failed(e.record.errors)`.
 - **Return `succeed(...)` or `failed(...)`** from `execute` — the controller can't tell what happened otherwise.
 - **Redirect is automatic on success** — only use `with_redirect_response` for a *different* destination.
-- **`relation_scope` must compose with `default_relation_scope(relation)` explicitly** — not `super`. See [[plutonium-tenancy]].
+- **`relation_scope` must end up calling `default_relation_scope(relation)` somewhere in the chain.** Prefer calling it explicitly. `super` works when extending a parent policy (e.g., a package base) that itself calls it. See [[plutonium-tenancy]].
 - **For `has_cents` fields, use the virtual name (`:price`), not `:price_cents`** in `permitted_attributes_for_*`.
 - **Custom action ⇒ policy method.** `action :publish` needs `def publish?` on the policy (undefined methods return `false`).
 - **Named custom routes.** When adding custom routes, always pass `as:` so `resource_url_for` can build URLs.

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

@@ -725,9 +725,10 @@ class PostDefinition < ResourceDefinition
   # nil (default) = auto (hidden for singular, shown for plural)
   submit_and_continue false
 
-  # How :new / :edit render
+  # How :new / :edit + interactive actions render
   #   :slideover (default), :centered, or false (full pages)
-  modal :centered
+  #   size: :sm / :md (default) / :lg / :xl / :auto / :full
+  modal :centered, size: :lg
 
   # Titles
   index_page_title "All Posts"
@@ -757,7 +758,7 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-`modal:` only affects the framework `:new` / `:edit` actions. Custom actions have their own per-action `modal:` option (default `:centered`).
+`modal:` is the default for framework `:new` / `:edit` *and* every interactive action on this definition. Per-action `modal:` / `size:` overrides win.
 
 ## Metadata Panel (show page)
 
@@ -983,7 +984,8 @@ action :name,
   confirmation: "Are you sure?",
   turbo_frame: "_top",
   route_options: {action: :foo},
-  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
 ```
 
 `Action#with(...)` — actions are frozen value objects; clone with overrides:

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

@@ -15,7 +15,7 @@ Cross-references back to [[plutonium-resource]] (models, definitions) and [[plut
 
 ## 🚨 Critical (read first)
 
-- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins to the entity triggers `verify_default_relation_scope_applied!`. Always call `default_relation_scope(relation)` explicitly — not `super`.
+- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins to the entity triggers `verify_default_relation_scope_applied!`. Make sure the chain ends up calling `default_relation_scope(relation)` — explicitly, or via `super(relation)` (the framework base calls it).
 - **Always declare an association path from model to entity.** Direct `belongs_to`, `has_one :through`, or a custom `associated_with_<entity>` scope. If `associated_with` can't resolve, Plutonium raises. Fix the **model**, not the policy.
 - **Parent scoping beats entity scoping.** When a parent is present (nested resource), `default_relation_scope` scopes via the parent, NOT via `entity_scope`. Don't double-scope.
 - **One level of nesting only.** Grandparent → parent → child nested routes are NOT supported. Use top-level routes for deeper relationships.
@@ -170,7 +170,12 @@ relation_scope { |r| r.joins(:project).where(projects: {organization_id: current
 relation_scope { |r| r.where(published: true) }
 ```
 
-**Do not use `super`** from inside `relation_scope`. Call `default_relation_scope(relation)` explicitly — `super` semantics depend on how ActionPolicy's DSL registered the scope.
+**`default_relation_scope(relation)` must end up being called somewhere in the chain** — runtime verification just checks it was hit, not that you wrote it in this class. Both work:
+
+- `default_relation_scope(relation).where(...)` — explicit, always safe
+- `super(relation).where(...)` — `Plutonium::Resource::Policy`'s `relation_scope` block calls `default_relation_scope`, so chaining through `super` picks it up
+
+Pick the one that reads better for the situation.
 
 ### Intentionally skipping
 
@@ -199,7 +204,7 @@ module AdminPortal
 end
 ```
 
-Routes become `/organizations/:organization_id/posts`. 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). Portal extracts `params[:organization_scoped]` and loads the entity automatically. The `_scoped` suffix on the param name avoids colliding with `params[:organization]` from a `belongs_to :organization` on child models.
 
 ### Custom strategy (subdomain, session, etc.)
 
@@ -235,6 +240,7 @@ entity_scope
 
 - **Multiple associations to the same entity class.** E.g. `Match belongs_to :home_team, :away_team` both pointing at `Team`. Plutonium raises — override `scoped_entity_association` on the controller to pick one (`def scoped_entity_association = :home_team`).
 - **`param_key` differs from association name.** Fine — Plutonium matches by **class**, not param key. `scope_to_entity Competition::Team, param_key: :team` works with `belongs_to :competition_team`.
+- **Default `param_key` includes `_scoped` suffix.** `scope_to_entity Organization` reads `params[:organization_scoped]` (not `params[:organization]`) so it doesn't collide with `params[:organization]` from a `belongs_to :organization` on child models. The URL itself is unchanged — the entity id is just the first path segment after the mount (`/<mount>/42/posts`). Pass `param_key:` only if you want a different param name in your controllers.
 - **Forgetting compound uniqueness.** `validates :code, uniqueness: true` leaks across tenants. Use `uniqueness: {scope: :organization_id}`.
 - **"Temporary" `where` bypass for debugging.** Use `skip_default_relation_scope!` explicitly. Never leave a `where` bypass in code.
 
@@ -421,10 +427,18 @@ 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=ROLES` | `member,admin` | Comma-separated |
+| `--membership-model=NAME` | `EntityUser` | Membership join model (must already exist; roles are read from its `enum :role`) |
 | `--rodauth=NAME` | `user` | Rodauth configuration for signup |
 | `--enforce-domain` | `false` | Require invited email domain to match entity |
+| `--dest=PACKAGE` | `main_app` | Package where the entity model lives (controls where `invite_user_interaction.rb` is generated) |
+
+::: 🚨 No `--roles` flag here
+Role list is derived from the membership model's `enum :role`. Set roles via `pu:saas:membership --roles=...` (or edit the enum directly). **Index 0 is the most privileged** — typically `owner`, which the invite UI excludes from selectable choices; new invitees default to the second role (`roles[1]`).
+:::
+
+::: 🚨 ActiveRecord encryption keys required
+The invite model uses `encrypts :token, deterministic: true`. Without configured AR encryption keys, creating or accepting an invite raises `ActiveRecord::Encryption::Errors::Configuration`. The generator detects this and warns at install time — generate keys with `bin/rails db:encryption:init`, then paste the printed `active_record_encryption:` block into `config/credentials.yml.enc` (or set the equivalent `ACTIVE_RECORD_ENCRYPTION_*` ENV vars in production).
+:::
 
 ### What gets created
 
@@ -619,13 +633,23 @@ class Invites::UserInvite < Invites::ResourceRecord
 end
 ```
 
-### Domain enforcement / custom roles
+### Domain enforcement
 
 ```bash
 rails g pu:invites:install --enforce-domain
-rails g pu:invites:install --roles=viewer,editor,admin,owner
 ```
 
+### Custom roles
+
+Set roles when generating the membership model (ordering: index 0 = most privileged):
+
+```bash
+rails g pu:saas:membership --user Customer --entity Organization --roles=admin,editor,viewer
+# → enum :role, { owner: 0, admin: 1, editor: 2, viewer: 3 }   (owner auto-prepended)
+```
+
+Or edit `enum :role` on the existing membership model directly. Then run `pu:invites:install`.
+
 ## Portal connection
 
 ```ruby

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

@@ -207,7 +207,9 @@ current_account(portal: :admin)
 with_portal(:org) { ... }                  # scoped portal switch
 ```
 
-**Override hook for non-Rodauth apps:** define `sign_in_for_tests(account, portal:)` in your test class (or in `test/support/plutonium_testing.rb` for project-wide use). `AuthHelpers` will defer to it.
+**Default Rodauth login expects `password: "password123"`** — `login_as` POSTs to `/<account_table>/login` with that hardcoded password. Either seed test accounts with it (fixtures/factories) or override via `sign_in_for_tests` below.
+
+**Override hook for non-Rodauth apps (or to bypass Rodauth in tests):** define `sign_in_for_tests(account, portal:)` in your test class (or in `test/support/plutonium_testing.rb` for project-wide use). `AuthHelpers` will defer to it.
 
 ```ruby
 def sign_in_for_tests(account, portal:)

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

@@ -351,8 +351,8 @@ end
 class PostDefinition < ResourceDefinition
   class Table < Table
     def view_template
-      render_search_bar
-      render_scopes_bar
+      render_toolbar
+      render_scopes_pills
 
       if collection.empty?
         render_empty_card
@@ -371,7 +371,7 @@ end
 
 | Method | Purpose |
 |---|---|
-| `render_search_bar`, `render_scopes_bar` | Toolbar pieces |
+| `render_toolbar`, `render_scopes_pills`, `render_filter_pills`, `render_bulk_actions_toolbar` | Toolbar pieces |
 | `render_table` | Default table |
 | `render_empty_card` | Empty state |
 | `render_footer` | Pagination |
@@ -390,6 +390,7 @@ Inside any `Plutonium::UI::Component::Base` (or any page/form/display):
 PageHeader(title: "Dashboard", description: "...", actions: [...])
 Panel(class: "mt-4") { p { "Content" } }
 Block { TabList(items: tabs) }
+Avatar(user)                      # profile image: src → Navii fallback → icon
 EmptyCard("No items found")
 ActionButton(action, url: "/posts/new")
 DynaFrameHost(src: "/some/path", loading: :lazy)
@@ -401,6 +402,28 @@ TablePagination(pagy)
 Breadcrumbs()
 ```
 
+## Avatar
+
+`Avatar(subject = nil, src: nil, size: :md, alt: nil, **attrs)` — profile image with a deterministic [Navii](https://navii.dev) fallback. Registered in the kit.
+
+```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")               # String subject = deterministic seed
+Avatar("https://.../p.png")       # URL-shaped subject is shown as the image
+Avatar(src: avatar_url)           # bare image, no subject/fallback
+```
+
+- **subject** (positional): record → PII-free hashed seed + default `alt` (display name); String → seed. A URL-shaped String (`http(s)://…` or `/…`) is routed to `src` (shown as the image), not used as a seed.
+- **src**: a Symbol is sent to the subject (`:avatar` → `subject.avatar`, a **contract** — raises if absent); otherwise an ActiveStorage attachment, active_shrine/Shrine uploader, or URL string. ActiveStorage resolves via `helpers.url_for`; everything else via its own `#url`.
+- **size**: `:xs 24 / :sm 32 / :md 40 / :lg 48 / :xl 64`, or a raw Integer.
+- **Privacy**: the value sent to Navii is **always** a SHA256 hash — no ids, emails, or seed strings leave the app. Deterministic per subject.
+- **Resolution order**: resolved `src` → Navii (from subject) → generic user icon.
+- **Config**: `config.navii_host_url` (default `https://api.navii.dev`); the component appends `/avatar/:seed`.
+
+🚨 Ejected shells: `Avatar` only shows a Navii avatar when `NavUser` is passed `record:`. The gem's `_resource_header.html.erb` passes `record: (current_user if current_user.respond_to?(:id))`; portals that **ejected** the header before this must re-eject (`rails g pu:eject:shell --dest=<portal>`) or add the `record:` line, otherwise they keep the icon fallback. Pass a record only — a String `current_user` (e.g. a guest) would otherwise be seeded as a literal identity.
+
 ## Custom Phlex components
 
 ```ruby
@@ -450,17 +473,18 @@ All pages inherit this. Modals and frame navigation work without special handlin
 
 # Part 5 — Modals, Slideovers, Tabs
 
-## Modal/slideover for `:new` / `:edit`
+## Modal/slideover for `:new` / `:edit` + interactive actions
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  modal :slideover    # default — slide-in panel from the right
-  # modal :centered   # centered dialog
-  # modal false       # full standalone page
+  modal :slideover               # default — slide-in panel from the right
+  # modal :centered              # centered dialog
+  # modal :centered, size: :lg   # centered, wider container
+  # modal false                  # full standalone page
 end
 ```
 
-Custom interactive actions render in their own dialog with their own per-action `modal:` option (`:centered` default, or `:slideover`). See [[plutonium-resource]] › Action Options.
+Drives both framework `:new` / `:edit` and every interactive action on the definition. `size:` accepts `:sm`, `:md` (default), `:lg`, `:xl`, `:auto` (hugs content), or `:full`. Per-action `modal:` / `size:` overrides win. See [[plutonium-resource]] › Action Options.
 
 ## Tabs on the show page
 

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+## [0.53.0] - 2026-05-31
+
+### 🚀 Features
+
+- *(ui)* Add Avatar component with Navii fallback (#59)
+
+### 🐛 Bug Fixes
+
+- *(docs)* Correct broken cross-page anchors in guides
+- *(docs)* Retract incorrect "never super" guidance in relation_scope
+- *(docs)* Correct scoped-URL shape in multi-tenancy docs
+- *(rodauth)* Match change_password_notify mailer template name
+
+### 🚜 Refactor
+
+- *(helpers)* Remove dead view helpers superseded by Phlex components
+## [0.52.0] - 2026-05-21
+
+### 🐛 Bug Fixes
+
+- *(generators)* Use inclusion validation for required booleans
+- *(generators/assets)* Warn on failed yarn add instead of silently continuing
+- *(docs)* Let StopWriting terminals scroll horizontally instead of overflowing the column
+- *(docs)* Drop misleading 15-min claim — hero CTA → 'Tutorial', getting-started title → 'Learn Plutonium by building'
+- *(generators,docs)* Tutorial walkthrough + reference audit (#57)
+- *(ui/form)* Scope form ids per turbo frame to prevent stream-replace collisions
+- *(ui/form)* Hide secure_association "+" inside secondary modal
+- *(js/form)* Dedupe pre_submit hidden field on repeat change events
+- *(ui)* Form error alert margin + include model name in New/Edit page titles
+
+### ⚙️ Miscellaneous Tasks
+
+- *(appraisal)* Refresh rails-8.1 gemfile.lock for v0.51.0
 ## [0.51.0] - 2026-05-14
 
 ### 🚀 Features