plutonium 0.45.2 → 0.46.0

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

@@ -1,10 +1,31 @@
 ---
 name: plutonium-policy
-description: Use when configuring authorization - action permissions, attribute visibility, relation scoping, or per-portal policies
+description: Use BEFORE writing relation_scope, permitted_attributes, permitted_associations, or any policy override. For tenant-scoped relation_scope, also load plutonium-entity-scoping.
 ---
 
 # Plutonium Policies
 
+## 🚨 Critical (read first)
+- **Use generators.** `pu:res:scaffold` and `pu:res:conn` create policies — never hand-write policy files.
+- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with a raw `where(organization: …)` or manual joins skips entity scoping and triggers `verify_default_relation_scope_applied!` at runtime. Compose like this: `relation_scope { |r| default_relation_scope(r).where(archived: false) }`. Call `default_relation_scope(r)` **explicitly** — `super` is unreliable inside the DSL block. Full rules in `plutonium-entity-scoping`.
+- **Derived actions inherit.** `update?` falls back to `create?`, `show?` falls back to `read?` — don't duplicate unless the rules genuinely differ. Override `create?` and `read?` explicitly; they default to `false`.
+- **Define `permitted_attributes_for_*` explicitly.** Auto-detection works in development but raises in production.
+- **For `has_cents` fields, list the virtual name (`:price`), not the column (`:price_cents`).** Generators occasionally emit the wrong one — fix it (and verify the model has `has_cents`). See `plutonium-model` › Monetary Handling.
+- **Related skills:** `plutonium-entity-scoping` (tenant-scoped overrides — required for `relation_scope`), `plutonium-model` (`associated_with`), `plutonium-definition` (`permitted_attributes` usage), `plutonium-controller` (how controllers use policies).
+
+## Quick checklist
+
+Writing / editing a policy:
+
+1. Confirm the policy was created by `pu:res:scaffold` or `pu:res:conn`.
+2. Override `create?` and `read?` explicitly — they default to `false`.
+3. Define `permitted_attributes_for_read` and `permitted_attributes_for_create` (derived methods inherit).
+4. For custom actions, add `def <action>?` matching the definition's `action :<action>`.
+5. If you need `relation_scope`, compose with `default_relation_scope(relation).where(...)` — never bypass it.
+6. For tenant scoping, load `plutonium-entity-scoping` and fix the **model**, not the policy.
+7. Per-portal overrides go in the portal's policy file (created by `pu:res:conn`).
+8. Test: log in as a user who should NOT see a record, verify it's filtered out.
+
 **Policies are generated automatically** - never create them manually:
 - `rails g pu:res:scaffold` creates the base policy
 - `rails g pu:res:conn` creates portal-specific policies with attribute permissions
@@ -153,119 +174,89 @@ def permitted_attributes_for_read
 end
 ```
 
-### Auto-Detection (Development Only)
-
-In development, undefined attribute methods auto-detect from the model. This raises errors in production - always define explicitly.
+**Key insight:** `permitted_attributes_for_*` controls *which fields appear* on each view (form, show, index). The `column`/`field`/`input`/`display` declarations in the **definition** only control *how those fields render* — they do NOT add or remove fields from the page. If your index page is showing fields you didn't want, override `permitted_attributes_for_index` (it does NOT inherit from `_for_read` automatically when you want a different shape). The same applies to forms: a `field :name` in the definition won't be rendered unless `:name` is in `permitted_attributes_for_create`/`_update`.
 
-## Association Permissions
-
-Control which associations can be rendered:
+### Anti-pattern: nested_attributes hashes in permitted_attributes
 
 ```ruby
-def permitted_associations
-  %i[comments tags author]
+# ❌ DO NOT DO THIS
+def permitted_attributes_for_create
+  [
+    :name,
+    {variants_attributes: [:id, :name, :_destroy]},
+    {comments_attributes: [:id, :body, :_destroy]}
+  ]
 end
 ```
 
-Used for:
-- Nested forms
-- Related data displays
-- Association fields in tables
-
-## Collection Scoping
+Plutonium's form pipeline extracts nested params via the **form definition** (`build_form(...).extract_input(...)`), not the policy. Hash entries in `permitted_attributes_for_*` get iterated as field names by the form renderer and end up as literal text inputs with names like `model[{:variants_attributes=>[...]}]`.
 
-Filter which records users can see:
+The correct pattern:
 
 ```ruby
-relation_scope do |relation|
-  if user.admin?
-    relation
-  else
-    relation.where(author: user)
-  end
+# ✅ Policy permits just the association name
+def permitted_attributes_for_create
+  [:name, :variants, :comments]
 end
 ```
 
-### With Parent Scoping (Nested Resources)
-
-For nested resources, call `super` to apply automatic parent scoping:
-
 ```ruby
-relation_scope do |relation|
-  relation = super(relation)  # Applies parent scoping automatically
-
-  if user.admin?
-    relation
-  else
-    relation.where(published: true)
+# ✅ Definition declares the nested input (this drives both rendering AND param extraction)
+class PostDefinition < ResourceDefinition
+  nested_input :variants do |n|
+    n.input :name
+    n.input :is_default, as: :boolean
   end
 end
 ```
 
-**Parent scoping takes precedence over entity scoping.** When a parent is present:
-- For `has_many`: scopes via `parent.association_name`
-- For `has_one`: scopes via `where(foreign_key: parent.id)`
-
-### With Entity Scoping (Multi-tenancy)
-
-When no parent is present, `super` applies entity scoping:
-
 ```ruby
-relation_scope do |relation|
-  relation = super(relation)  # Apply entity scope if no parent
+# ✅ Model declares accepts_nested_attributes_for + inverse_of on the back-reference
+class Post < ApplicationRecord
+  has_many :variants, inverse_of: :post, dependent: :destroy
+  accepts_nested_attributes_for :variants, allow_destroy: true, reject_if: :all_blank
+end
 
-  if user.admin?
-    relation
-  else
-    relation.where(published: true)
-  end
+class Variant < ApplicationRecord
+  belongs_to :post, inverse_of: :variants  # ← required for nested validation
 end
 ```
 
-### default_relation_scope is Required
-
-Plutonium verifies that `default_relation_scope` is called in every `relation_scope`. This prevents accidental multi-tenancy leaks when overriding scopes.
+See `plutonium-definition` for the full `nested_input` API.
 
-```ruby
-# ❌ This will raise an error
-relation_scope do |relation|
-  relation.where(published: true)  # Missing default_relation_scope!
-end
+### Auto-Detection (Development Only)
 
-# ✅ Correct - call default_relation_scope
-relation_scope do |relation|
-  default_relation_scope(relation).where(published: true)
-end
+In development, undefined attribute methods auto-detect from the model. This raises errors in production - always define explicitly.
 
-# ✅ Also correct - super calls default_relation_scope
-relation_scope do |relation|
-  super(relation).where(published: true)
-end
-```
+## Association Permissions
 
-When overriding an inherited scope:
+Control which associations can be rendered:
 
 ```ruby
-class AdminPostPolicy < PostPolicy
-  relation_scope do |relation|
-    # Replace inherited scope but keep Plutonium's parent/entity scoping
-    default_relation_scope(relation)
-  end
+def permitted_associations
+  %i[comments tags author]
 end
 ```
 
-### Skipping Default Scoping (Rare)
+Used for:
+- Nested forms
+- Related data displays
+- Association fields in tables
 
-If you intentionally need to skip scoping, call `skip_default_relation_scope!`:
+## Collection Scoping (relation_scope)
+
+Filter which records users can see:
 
 ```ruby
 relation_scope do |relation|
-  skip_default_relation_scope!
-  relation  # No parent/entity scoping applied
+  relation = default_relation_scope(relation)
+  user.admin? ? relation : relation.where(author: user)
 end
 ```
 
-Consider using a separate portal instead of skipping scoping.
+**Always compose with `default_relation_scope(relation)` explicitly** — not `super`. Plutonium enforces this via `verify_default_relation_scope_applied!`. Anything else (a raw `where(organization: ...)`, manual joins) bypasses Plutonium's tenancy handling and will raise.
+
+> **For the full rules — why `default_relation_scope` is required, how parent vs entity scoping interact, safe override patterns, `skip_default_relation_scope!`, and how `associated_with` resolution works — see the [plutonium-entity-scoping](../plutonium-entity-scoping/SKILL.md) skill. It is the single source of truth for Plutonium tenant scoping.**
 
 ## Portal-Specific Policies
 
@@ -453,7 +444,7 @@ end
 
 1. **Always override `create?` and `read?`** - They default to `false`
 2. **Define attributes explicitly** - Auto-detection only works in development
-3. **Call `super` in `relation_scope`** - Preserves entity scoping
+3. **Call `default_relation_scope(relation)` in `relation_scope`** - Preserves parent/entity scoping (do not rely on `super` from inside the block)
 4. **Use derived methods** - Let `update?` inherit from `create?` when appropriate
 5. **Keep policies focused** - Authorization logic only, no business logic
 6. **Test edge cases** - Archived records, nil associations, role combinations
@@ -461,5 +452,5 @@ end
 ## Related Skills
 
 - `plutonium` - How policies fit in the resource architecture
-- `plutonium-definition-actions` - Actions that need policy methods
+- `plutonium-definition` - Actions that need policy methods
 - `plutonium-controller` - How controllers use policies

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

@@ -1,12 +1,32 @@
 ---
 name: plutonium-portal
-description: Use when creating portals, connecting resources to portals, configuring authentication, entity scoping, or portal routes
+description: Use BEFORE creating a portal, mounting a portal engine, running pu:pkg:portal, configuring entity strategies, or routing portal-specific resources. For tenancy mechanics, also load plutonium-entity-scoping.
 ---
 
 # Plutonium Portals
 
+## 🚨 Critical (read first)
+- **Use `pu:pkg:portal`.** Never hand-craft a portal engine — the generator wires up the controller concerns, routes, and layout.
+- **Always use `pu:res:conn` to connect resources to portals** — resources are invisible until connected. Pass resources directly (not via `--src`) to skip prompts.
+- **Entity scoping is portal-level.** `scope_to_entity Entity, strategy: :path` in the portal engine; then every resource in that portal is scoped automatically. For mechanics, see `plutonium-entity-scoping`.
+- **Pass `--auth=<account>` / `--public` / `--byo`** to `pu:pkg:portal` for unattended runs.
+- **Related skills:** `plutonium-entity-scoping` (tenancy mechanics), `plutonium-auth` (Rodauth integration), `plutonium-package` (portal vs feature packages), `plutonium-policy` (portal-specific policies).
+
 Portals are Rails engines that provide web interfaces for specific user types.
 
+## Quick checklist
+
+Creating a portal and connecting resources:
+
+1. Run `rails g pu:pkg:portal <name> --auth=<account>` (or `--public` / `--byo`). Add `--scope=Entity` for multi-tenancy.
+2. Mount the engine in `config/routes.rb`: `mount <Name>Portal::Engine, at: "/<name>"`.
+3. For each resource, run `rails g pu:res:conn ResourceName --dest=<name>_portal`.
+4. For singular resources (profile, settings), pass `--singular`.
+5. Customize the portal's `Concerns::Controller` for auth / before_action hooks.
+6. Override portal-specific policies/definitions as needed.
+7. Verify: `bin/rails routes | grep <name>_portal`.
+8. For multi-tenancy specifics, load `plutonium-entity-scoping`.
+
 ## Creating a Portal
 
 ```bash
@@ -181,11 +201,7 @@ end
 
 ## Entity Scoping (Multi-tenancy)
 
-Automatically scope all data to a parent entity.
-
-### Path Strategy
-
-Entity ID in URL path:
+Portals can scope all data to a parent entity via `scope_to_entity`:
 
 ```ruby
 module AdminPortal
@@ -199,71 +215,11 @@ module AdminPortal
 end
 ```
 
-Routes become: `/organizations/:organization_id/posts`
-
-### Custom Strategy
-
-Implement your own lookup method:
-
-```ruby
-module AdminPortal
-  class Engine < Rails::Engine
-    include Plutonium::Portal::Engine
+Strategies: `:path` (entity id in URL) or a custom method name on the portal controller concern.
 
-    config.after_initialize do
-      scope_to_entity Organization, strategy: :current_organization
-    end
-  end
-end
+Access in controllers/views: `current_scoped_entity`, `scoped_to_entity?`. In policies: `entity_scope`.
 
-# In controller concern
-module AdminPortal
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Portal::Controller
-
-      private
-
-      # Method name must match strategy
-      def current_organization
-        @current_organization ||= Organization.find_by!(subdomain: request.subdomain)
-      end
-    end
-  end
-end
-```
-
-### Accessing the Scoped Entity
-
-```ruby
-current_scoped_entity  # The current Organization/Account/etc.
-scoped_to_entity?      # true if scoping is active
-```
-
-### Model Requirements
-
-Models must have an association path to the scoped entity:
-
-```ruby
-# Direct association (preferred)
-class Post < ResourceRecord
-  belongs_to :organization
-end
-
-# Through association
-class Comment < ResourceRecord
-  belongs_to :post
-  has_one :organization, through: :post
-end
-
-# Complex (define custom scope)
-class AuditLog < ResourceRecord
-  scope :associated_with_organization, ->(org) {
-    joins(:user).where(users: { organization_id: org.id })
-  }
-end
-```
+> **For the full entity scoping picture — the three model shapes, `associated_with` resolution, `default_relation_scope` rules, safe `relation_scope` overrides, and how parent scoping takes precedence — see the [plutonium-entity-scoping](../plutonium-entity-scoping/SKILL.md) skill. It is the single source of truth.**
 
 ## Routes
 
@@ -448,7 +404,7 @@ rails g pu:res:conn Post --dest=admin_portal
 ## Related Skills
 
 - `plutonium-package` - Package overview (features vs portals)
-- `plutonium-rodauth` - Authentication setup and configuration
+- `plutonium-auth` - Authentication setup and configuration
 - `plutonium-policy` - Portal-specific policies
 - `plutonium-definition` - Portal-specific definitions
 - `plutonium-controller` - Portal-specific controllers

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

@@ -1,10 +1,17 @@
 ---
 name: plutonium-views
-description: Use when building custom pages, display panels, tables, or layouts using Phlex components in Plutonium
+description: Use BEFORE building a custom page, panel, table, layout, or Phlex component in Plutonium. Also when overriding IndexPage/ShowPage/Form classes in a definition.
 ---
 
 # Plutonium Views
 
+## 🚨 Critical (read first)
+- **Override via nested classes in the definition.** `class ShowPage < ShowPage; end`, `class Form < Form; end` — don't replace the entire view layer.
+- **Use the render hooks.** `render_before_content`, `render_after_content`, `render_before_toolbar`, etc. — they exist so you don't have to override `view_template` and re-implement everything.
+- **All pages inherit `DynaFrameContent`** so turbo-frame requests render only the content. Don't fight it — modals and frame nav "just work".
+- **For custom components, use `Plutonium::UI::Component::Base`** so you inherit the component kit (`PageHeader`, `Panel`, `Block`, etc.) and access to resource helpers.
+- **Related skills:** `plutonium-forms` (form customization), `plutonium-assets` (theming + component classes), `plutonium-definition` (field-level rendering), `plutonium-controller` (presentation hooks like `present_parent?`).
+
 Plutonium uses [Phlex](https://www.phlex.fun/) for all view components. This provides a Ruby-first approach to building HTML with full IDE support and type safety.
 
 ## Architecture Overview
@@ -580,6 +587,6 @@ end
 - `plutonium-forms` - Custom form templates and field builders
 - `plutonium-assets` - TailwindCSS and component theming
 - `plutonium-definition` - Field/input/display configuration
-- `plutonium-definition-actions` - Action buttons and interactions
+- `plutonium-definition` - Action buttons and interactions
 - `plutonium-controller` - Presentation hooks (`present_parent?`, etc.)
 - `plutonium-portal` - Portal-specific customization

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+## [0.46.0] - 2026-04-11
+
+### 🚀 Features
+
+- *(profile)* Default profile model to {UserModel}Profile
+- *(generators)* Sync skills during pu:core:update if plutonium skill is installed
+- *(generators/active_shrine)* Disable Active Storage railtie and include ActiveShrine::Model
+
+### 🐛 Bug Fixes
+
+- *(engine)* Resolve scoped entity class lazily to survive autoreload
+- *(rodauth)* Render page title in layout, drop per-view h1s
+- *(generators/invites)* Use derived user association in current_membership
+- *(generators/rodauth)* Redirect to login after verification email sent
+
+### 🚜 Refactor
+
+- *(generators)* Add inject_into_concerns_controller to merge included blocks
+
+### 📚 Documentation
+
+- *(skills)* Clarify generator gotchas for installation, rodauth, and unattended runs
+- *(skills)* Comprehensive Plutonium skills overhaul
+- *(skills)* Document nested_attributes gotchas in policy and definition
+
+### ⚙️ Miscellaneous Tasks
+
+- Update test lockfiles
+## [0.45.3] - 2026-04-07
+
+### 🐛 Bug Fixes
+
+- *(pagy)* Use Pagy::OPTIONS instead of frozen DEFAULT
 ## [0.45.2] - 2026-04-07
 
 ### 🐛 Bug Fixes