plutonium 0.45.3 → 0.47.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-testing/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: plutonium-testing
+description: Use BEFORE writing tests for a Plutonium resource, running pu:test:scaffold, or including Plutonium::Testing::* concerns. Covers the full testing toolkit — CRUD, policy, definition, interaction, model, nested, portal access, and auth helpers.
+---
+
+# Plutonium Testing
+
+## 🚨 Critical (read first)
+
+- **Use the generators.** `pu:test:install` once per app, then `pu:test:scaffold ResourceClass --portals=...` per resource × portal. Hand-written test files drift from conventions.
+- **Tests are opt-in.** `Plutonium::Testing` is only loaded when `require "plutonium/testing"` runs — it's never autoloaded, never present in production.
+- **One file per (resource × portal).** Same model in admin and org portals = two test files. Each portal has different auth, scoping, and allowed actions.
+- **Stub methods are required.** Concerns ship with `NotImplementedError` stubs — your test class supplies the test data via `create_resource!`, `valid_create_params`, `policy_roles`, etc.
+
+## Quick start
+
+```bash
+# Once per app
+rails g pu:test:install
+
+# Per resource × portal pairing
+rails g pu:test:scaffold Blogging::Post --portals=admin,org
+
+# Run
+bin/rails test
+```
+
+`pu:test:install` adds `require "plutonium/testing"` to `test/test_helper.rb` and creates `test/support/plutonium_testing.rb` (a stub for non-Rodauth auth overrides).
+
+## DSL reference
+
+Every concern uses the same class-level DSL:
+
+```ruby
+resource_tests_for ResourceClass,
+  portal:           :admin,                                # required
+  path_prefix:      "/admin",                              # optional override
+  parent:           :organization,                         # for nested resources
+  actions:          %i[index show new create edit update destroy],
+  skip:             %i[destroy],
+  associated_with:  :organization,                         # ResourceModel only
+  sgid_routing:     true,                                  # ResourceModel only
+  has_cents:        %i[price]                              # ResourceModel only
+```
+
+The **portal symbol** drives:
+
+| Derived | `:admin` example | `:org` example |
+|---|---|---|
+| `path_prefix` | `/admin` | `/org` |
+| Default sign-in helper | admin Rodauth | user Rodauth |
+| Allowed action set | from definition | from definition |
+
+`path_prefix` is auto-resolved from the mounted portal engine. For mounts inside `constraints` (typical Plutonium setup), the resolver walks the route tree and finds the engine.
+
+## Concerns catalog
+
+Each concern is `include`d separately. Pick the ones you need.
+
+### `Plutonium::Testing::ResourceCrud`
+
+Generates index / show / new / create / edit / update / destroy integration tests against the portal-mounted resource.
+
+**Stubs:**
+- `create_resource!` → persisted record
+- `valid_create_params` → Hash for POST
+- `valid_update_params` → Hash for PATCH
+
+```ruby
+class AdminPortal::BloggingPostsTest < ActionDispatch::IntegrationTest
+  include IntegrationTestHelper
+  include Plutonium::Testing::ResourceCrud
+
+  resource_tests_for Blogging::Post, portal: :admin
+
+  setup do
+    @admin = create_admin!
+    @user = create_user!
+    @org = create_organization!
+    login_as(@admin)
+  end
+
+  def create_resource! = create_post!(user: @user, organization: @org)
+  def valid_create_params
+    {title: "x", body: "y", status: :draft, user: @user.to_sgid.to_s, organization: @org.to_sgid.to_s}
+  end
+  def valid_update_params = {title: "Updated"}
+end
+```
+
+### `Plutonium::Testing::ResourcePolicy`
+
+Asserts the `permit?` matrix across action × role and verifies `relation_scope` returns an `ActiveRecord::Relation`.
+
+**Stubs:**
+- `policy_roles` → `{role_sym => -> { account }}`
+- `policy_record` → persisted record under test
+- `policy_matrix` → `{action_sym => [allowed_role_syms]}`
+- `policy_context` (optional) → extra kwargs (defaults to `{entity_scope: nil}`)
+
+```ruby
+def policy_roles = {admin: -> { @admin }, member: -> { @user }}
+def policy_record = create_post!(user: @user, organization: @org)
+def policy_matrix = {
+  index: %i[admin member], show: %i[admin member],
+  create: %i[admin], update: %i[admin], destroy: %i[admin]
+}
+```
+
+### `Plutonium::Testing::ResourceDefinition`
+
+Smoke-tests the resource definition: the class is constantize-able, every defineable prop dictionary (fields/inputs/displays/columns/scopes/filters/sorts/actions) is queryable, and declared fields exist on the model.
+
+**No stubs required** for the happy path.
+
+### `Plutonium::Testing::ResourceInteraction`
+
+Outcome-assertion helpers for `Plutonium::Interaction::Base` subclasses.
+
+**Helpers:**
+- `assert_interaction_success(klass, **input)` → returns the success outcome
+- `assert_interaction_failure(klass, **input)` → returns the failure outcome
+- `interaction_view_context` (overridable) → defaults to a mock view context
+
+```ruby
+test "RebuildSearchInteraction succeeds" do
+  outcome = assert_interaction_success(RebuildSearchInteraction, since: 1.day.ago)
+  assert_equal 42, outcome.value[:rebuilt_count]
+end
+```
+
+### `Plutonium::Testing::ResourceModel`
+
+Tests `associated_with` scope, SGID routing, and `has_cents` accessors — gated by DSL flags.
+
+**Stubs:**
+- `model_test_record` → persisted record
+
+```ruby
+resource_tests_for Catalog::Product, portal: :admin,
+  associated_with: :organization,
+  sgid_routing: true,
+  has_cents: %i[price]
+
+def model_test_record = create_product!(user: @user, organization: @org)
+```
+
+Only the flagged features generate tests.
+
+### `Plutonium::Testing::NestedResource`
+
+Asserts CRUD under a parent + scope-boundary tests (sibling tenants invisible).
+
+**Stubs:**
+- `parent_record!` → current tenant
+- `other_parent_record!` → sibling tenant
+- `create_resource!(parent:)` → persisted record under given parent
+
+### `Plutonium::Testing::PortalAccess`
+
+Cross-portal access boundaries. Uses its own DSL — not `resource_tests_for`.
+
+```ruby
+class PortalAccessTest < ActionDispatch::IntegrationTest
+  include IntegrationTestHelper
+  include Plutonium::Testing::PortalAccess
+
+  portal_access_for portals: %i[admin org],
+    matrix: {admin: %i[admin], member: %i[org]}
+
+  setup do
+    @admin = create_admin!
+    @user = create_user!
+    @org = create_organization!
+    create_membership!(organization: @org, user: @user)
+  end
+
+  def login_as_role(role)
+    case role
+    when :admin then login_as(@admin, portal: :admin)
+    when :member then login_as(@user, portal: :user)
+    end
+  end
+
+  def portal_root_path(portal)
+    case portal
+    when :admin then "/admin"
+    when :org then "/org/#{@org.id}"
+    end
+  end
+end
+```
+
+Generates one test per (role × portal). Allowed = `200|302`; blocked = `302|401|403|404`.
+
+## Auth helpers
+
+`Plutonium::Testing::AuthHelpers` is included transitively by every concern.
+
+```ruby
+login_as(account)                          # uses portal from DSL
+login_as(account, portal: :admin)          # explicit override
+sign_out                                    # uses portal from DSL
+sign_out(portal: :admin)
+current_account                             # uses portal from DSL
+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.
+
+```ruby
+def sign_in_for_tests(account, portal:)
+  # your custom auth flow here
+end
+```
+
+## Generator reference
+
+### `pu:test:install`
+
+```bash
+rails g pu:test:install
+```
+
+- Adds `require "plutonium/testing"` to `test/test_helper.rb` (idempotent)
+- Creates `test/support/plutonium_testing.rb` with override stub
+
+### `pu:test:scaffold`
+
+```bash
+rails g pu:test:scaffold Blogging::Post --portals=admin,org
+rails g pu:test:scaffold Blogging::Post --portals=admin --concerns=crud,policy,definition
+rails g pu:test:scaffold Blogging::Post --portals=org --parent=organization --dest=blogging
+```
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--portals=admin,org` | required | Emit one file per portal |
+| `--concerns=...` | `crud,policy,definition` | Concerns to include (`crud,policy,definition,nested,model,interaction,portal_access`) |
+| `--parent=organization` | none | Wires `NestedResource` parent |
+| `--dest=main_app\|<package>` | `main_app` | Output destination |
+
+Output path: `test/integration/<portal>_portal/<resource_underscored>_test.rb`.
+
+## Customization & escape hatches
+
+- **Skip individual tests:** `resource_tests_for Klass, portal: :admin, skip: %i[destroy]`
+- **Restrict action set:** `resource_tests_for Klass, portal: :admin, actions: %i[index show]`
+- **Custom assertions:** add regular `test "..."` blocks alongside the generated matrix — they coexist.
+- **Non-Rodauth auth:** override `sign_in_for_tests`. See AuthHelpers section.
+- **Custom path prefix:** `path_prefix: "/v2/admin"` overrides portal resolution.
+
+## Common pitfalls
+
+- **Forgotten stubs raise `NotImplementedError`** with the stub name. Look for the missing method in your test class.
+- **Portal mismatch:** `:admin` portal expects `AdminPortal::Engine` constant. If your portal is named differently, pass `path_prefix:` explicitly.
+- **Tenant leakage in stubs:** `create_resource!` for an org portal must return a record bound to the test's `@org`. Otherwise scope filtering tests will pass for the wrong reason.
+- **`policy_record` for tenant-scoped resources** must belong to a tenant the role has access to — otherwise even allowed roles will see `false`.
+- **Nested resources need `parent: :foo`** in the DSL AND a real parent record from `parent_record!`. Without both, path interpolation fails.
+- **`PortalAccess` doesn't use `resource_tests_for`** — use `portal_access_for` instead. Mixing them on the same class is undefined behavior.
+
+## See also
+
+- `plutonium-policy` — write the policy this concern verifies
+- `plutonium-definition` — definition props the smoke test introspects
+- `plutonium-portal` — portal mounting and entity strategies that drive auth/scoping
+- `plutonium-auth` — Rodauth setup behind the default login flow

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/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

data/CHANGELOG.md

@@ -1,3 +1,41 @@
+## [0.47.0] - 2026-04-15
+
+### 🚀 Features
+
+- *(core)* Add `interaction:` kwarg to resource_url_for
+- *(testing)* Add Plutonium::Testing module, generators, skill, docs, and migrate in-repo tests
+
+### ⚙️ Miscellaneous Tasks
+
+- Update yarn
+## [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