plutonium 0.45.2 → 0.46.0

data/.claude/skills/plutonium-entity-scoping/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: plutonium-entity-scoping
+description: Use BEFORE writing relation_scope, associated_with, scoping a model to a tenant, or any multi-tenancy work. Also when configuring entity strategies on a portal. The single source of truth for Plutonium entity scoping.
+---
+
+# Plutonium Entity Scoping
+
+The single source of truth for how Plutonium scopes records to a tenant/entity in multi-tenant apps. Entity scoping spans models, policies, portals, and invites — this skill consolidates the canonical rules so you don't have to stitch them together from four other skills.
+
+## 🚨 Critical (read first)
+
+- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins to the entity skips Plutonium's scoping and triggers `verify_default_relation_scope_applied!`. Always call `default_relation_scope(relation)` explicitly (not `super`).
+- **Always declare an association path from the model to the entity.** If `associated_with` can't find a path — direct `belongs_to`, `has_one :through`, or a custom `associated_with_<entity>` scope — Plutonium raises. Fix the **model**, not the policy.
+- **Use a generator to scaffold scoped resources.** `pu:saas:setup`, `pu:pkg:portal --scope=Entity`, and `pu:res:scaffold` do the right thing. Hand-wiring scoping is how leaks happen.
+- **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.
+- **Related skills:** `plutonium-model` (associations, `associated_with`), `plutonium-policy` (`relation_scope` overrides), `plutonium-portal` (entity strategies), `plutonium-invites` (membership-backed scoping).
+
+## Quick checklist
+
+Scoping a new model to a tenant:
+
+1. Pick the shape: direct child, join table, or grandchild (see [Three model shapes](#three-model-shapes)).
+2. Declare the association path on the model (`belongs_to`, `has_one :through`, or a custom `associated_with_<entity>` scope).
+3. Verify `Model.associated_with(entity)` returns the right records in `rails runner`.
+4. Confirm the portal is scoped: `scope_to_entity Entity, strategy: :path` (or custom) in the portal engine.
+5. Leave `relation_scope` alone in the policy unless you need **extra** filters on top of the default.
+6. If you do override `relation_scope`, wrap with `default_relation_scope(relation).where(...)`.
+7. Add compound uniqueness scoped to the entity on the model (`validates :code, uniqueness: {scope: :organization_id}`).
+8. Test: create a record in org A, confirm it does NOT appear when scoped to org B.
+
+## How entity scoping works
+
+Plutonium's entity scoping is built on three cooperating pieces:
+
+- **Portal**: declares which entity class it scopes to (`scope_to_entity Organization, strategy: :path`) and how to resolve the current entity from the request.
+- **Policy**: `default_relation_scope(relation)` calls `relation.associated_with(entity_scope)`, applying the scope to every collection query.
+- **Model**: `associated_with(entity)` resolves the scope via a custom scope, a direct association, or auto-detected `has_one :through` chain.
+
+The `default_relation_scope` is enforced — if you override `relation_scope` without calling it, `verify_default_relation_scope_applied!` raises at runtime.
+
+## `associated_with` resolution
+
+`Model.associated_with(entity)` resolves in this order:
+
+1. **Custom named scope** `associated_with_<model_name>` (e.g. `associated_with_organization`) — highest priority, full control over the SQL.
+2. **Direct `belongs_to` to the entity class** — `WHERE <entity>_id = ?`, most efficient.
+3. **`has_one` / `has_one :through` to the entity class** — JOIN + WHERE, auto-detected via `reflect_on_all_associations`.
+4. **Reverse `has_many` from the entity** — JOIN required, logs a warning (less efficient).
+
+If none apply, raises:
+
+```
+Could not resolve the association between 'Model' and 'Entity'
+```
+
+with guidance to either add an association or define the custom scope.
+
+## `default_relation_scope` and safe `relation_scope` overrides
+
+`default_relation_scope(relation)` does two things:
+
+1. If a **parent** is present (nested resource), scopes the relation via the parent association.
+2. Otherwise, applies `relation.associated_with(entity_scope)`.
+
+### Correct overrides
+
+```ruby
+# ✅ Best: don't override at all — the inherited scope already calls default_relation_scope.
+
+# ✅ Add extra filters on top of default scope
+relation_scope do |relation|
+  default_relation_scope(relation).where(archived: false)
+end
+
+# ✅ Role-based extra filter
+relation_scope do |relation|
+  relation = default_relation_scope(relation)
+  user.admin? ? relation : relation.where(author: user)
+end
+```
+
+### Wrong overrides
+
+```ruby
+# ❌ Manually filtering by the scoped entity — bypasses default_relation_scope
+relation_scope do |relation|
+  relation.where(organization: current_scoped_entity)
+end
+
+# ❌ Manual joins — same problem
+relation_scope do |relation|
+  relation.joins(:project).where(projects: {organization_id: current_scoped_entity.id})
+end
+
+# ❌ Missing default_relation_scope entirely — raises at runtime
+relation_scope do |relation|
+  relation.where(published: true)
+end
+```
+
+**Do not rely on `super`** from inside `relation_scope do ... end`. `default_relation_scope` is the documented public contract; `super` semantics depend on how ActionPolicy's DSL registered the scope and aren't guaranteed.
+
+### Intentionally skipping the scope
+
+Rare, but possible:
+
+```ruby
+relation_scope do |relation|
+  skip_default_relation_scope!
+  relation
+end
+```
+
+Before reaching for this, consider a separate portal without scoping.
+
+## Entity strategies (portal configuration)
+
+The portal declares how the current entity is resolved from the request.
+
+### Path strategy
+
+```ruby
+module AdminPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      scope_to_entity Organization, strategy: :path
+    end
+  end
+end
+```
+
+Routes become `/organizations/:organization_id/posts`. The portal extracts `params[:organization_id]` and loads the entity automatically.
+
+### Custom strategy
+
+```ruby
+module AdminPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      scope_to_entity Organization, strategy: :current_organization
+    end
+  end
+end
+
+module AdminPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+
+      private
+
+      def current_organization
+        @current_organization ||= Organization.find_by!(subdomain: request.subdomain)
+      end
+    end
+  end
+end
+```
+
+The strategy symbol must match a method name on the controller.
+
+### Accessing the scoped entity
+
+```ruby
+current_scoped_entity  # => current Organization
+scoped_to_entity?      # => true/false
+```
+
+Inside a policy, the same entity is available as `entity_scope`.
+
+## Three model shapes
+
+The `associated_with` resolver handles three common model shapes. Pick the lightest one that fits.
+
+### Shape 1: Direct child (belongs_to the entity)
+
+```ruby
+class Organization < ResourceRecord
+  has_many :projects
+end
+
+class Project < ResourceRecord
+  belongs_to :organization
+end
+
+# Usage
+Project.associated_with(org)
+# => Project.where(organization: org)     # simple WHERE, most efficient
+```
+
+**When to use:** the model naturally has a direct foreign key to the entity. No extra work; auto-detected.
+
+### Shape 2: Join table (membership-style)
+
+A join table linking users to entities, where the entity is reachable via one of the `belongs_to`:
+
+```ruby
+class User < ResourceRecord
+  has_many :memberships
+  has_many :organizations, through: :memberships
+end
+
+class Organization < ResourceRecord
+  has_many :memberships
+  has_many :users, through: :memberships
+end
+
+class Membership < ResourceRecord
+  belongs_to :user
+  belongs_to :organization
+
+  # ← auto-detection already finds :organization via belongs_to
+end
+
+# Usage
+Membership.associated_with(org)
+# => Membership.where(organization: org)
+```
+
+**When to use:** a pure join table. The `belongs_to :organization` is sufficient.
+
+If instead the join table is the scope target and you want to scope `Project` → `Membership` → `Organization`, add a `has_one :through`:
+
+```ruby
+class ProjectMember < ResourceRecord
+  belongs_to :project
+  belongs_to :user
+  has_one :organization, through: :project  # ← enables auto-scoping
+end
+```
+
+Now `ProjectMember.associated_with(org)` resolves via the `has_one :through` automatically.
+
+### Shape 3: Grandchild (multiple hops via `has_one :through`)
+
+```ruby
+class Organization < ResourceRecord
+  has_many :projects
+end
+
+class Project < ResourceRecord
+  belongs_to :organization
+  has_many :tasks
+end
+
+class Task < ResourceRecord
+  belongs_to :project
+  has_one :organization, through: :project   # ← critical line
+end
+
+# Deeper
+class Comment < ResourceRecord
+  belongs_to :task
+  has_one :project, through: :task
+  has_one :organization, through: :project   # ← enables auto-scoping
+end
+
+# Usage
+Task.associated_with(org)
+# => resolves via the :organization has_one :through
+
+Comment.associated_with(org)
+# => resolves via Comment -> Task -> Project -> Organization
+```
+
+**When to use:** the model is two+ hops away from the entity. Declaring `has_one :organization, through: ...` is the **lightest fix** — `associated_with` finds it via `reflect_on_all_associations` with no policy override needed.
+
+### When to fall back to a custom scope
+
+Use a custom `associated_with_<model_name>` scope when:
+
+- The path is polymorphic.
+- The path needs conditional logic.
+- You want explicit SQL for performance (e.g. avoid a multi-join chain).
+
+```ruby
+class Comment < ResourceRecord
+  scope :associated_with_organization, ->(org) do
+    joins(task: :project).where(projects: {organization_id: org.id})
+  end
+end
+
+# Plutonium picks this up BEFORE trying association detection.
+```
+
+## How the pieces fit together
+
+1. An admin opens `/organizations/42/projects`.
+2. Portal's `scope_to_entity Organization, strategy: :path` extracts `42`, loads the `Organization`, sets `current_scoped_entity`.
+3. The controller calls the policy. The policy's inherited `relation_scope` calls `default_relation_scope(relation)`.
+4. `default_relation_scope` has no parent (this is a top-level nested resource from the portal's perspective), so it calls `relation.associated_with(current_scoped_entity)`.
+5. `Project.associated_with(org)` resolves via the direct `belongs_to :organization` → `Project.where(organization: org)`.
+6. The controller renders only that organization's projects. Records from other orgs are invisible.
+
+Any model that cannot be reached from the entity via these rules must declare a `has_one :through` or a custom scope. Policies must never work around this — work around it in the **model**.
+
+## Gotchas
+
+- **Policy tries to filter by entity directly.** Wrong — that bypasses `default_relation_scope`. Add the association path to the model instead.
+- **`super` inside `relation_scope`.** Unreliable. Call `default_relation_scope(relation)` explicitly.
+- **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.
+- **`param_key` differs from association name.** Fine — Plutonium finds the association by **class**, not param key. You can still `scope_to_entity Competition::Team, param_key: :team` and have the model use `belongs_to :competition_team`.
+- **Forgetting compound uniqueness.** A unique constraint on `:code` alone leaks uniqueness across tenants. Use `validates :code, uniqueness: {scope: :organization_id}`.
+- **Skipping the scope "temporarily" for debugging.** Use `skip_default_relation_scope!` explicitly — never leave a `where` bypass in the code.
+
+## Related skills
+
+- `plutonium-model` — `associated_with` mechanics, declaring associations, `has_one :through` patterns.
+- `plutonium-policy` — writing `relation_scope` safely, bulk authorization, attribute permissions.
+- `plutonium-portal` — entity strategies (path, custom), `scope_to_entity`, mounting.
+- `plutonium-invites` — how invites and memberships interact with entity scoping.
+- `plutonium-nested-resources` — parent scoping semantics, which take precedence over entity scoping.

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

@@ -1,10 +1,17 @@
 ---
 name: plutonium-forms
-description: Use when building custom form templates, overriding field builders, or theming form components in Plutonium
+description: Use BEFORE customizing a form template, field builder, or input component in Plutonium. Also when overriding Form in a definition.
 ---
 
 # Plutonium Forms
 
+## 🚨 Critical (read first)
+- **Use `pu:field:input NAME` for custom input components.** Don't hand-write Phlexi field classes — the generator registers them correctly.
+- **Configure inputs in the definition, render them in the form.** `input :foo, as: :markdown` in the definition; `render_resource_field :foo` in the custom form template.
+- **Override via `class Form < Form` in the definition.** Don't replace the form root class.
+- **`render_actions` renders the submit buttons.** Always call it at the end of a custom `form_template` or the form won't submit.
+- **Related skills:** `plutonium-definition` (input configuration), `plutonium-views` (custom page classes), `plutonium-assets` (theming), `plutonium-interaction` (interaction forms).
+
 **Use generators for custom field types:**
 - `rails g pu:field:input NAME` creates a custom form input component
 - `rails g pu:field:renderer NAME` creates a custom display renderer

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

@@ -1,10 +1,31 @@
 ---
 name: plutonium-installation
-description: Use when installing Plutonium in a new or existing Rails app - generators, configuration, and initial setup
+description: Use BEFORE installing Plutonium in a Rails app, running pu:core:install, or configuring initial Plutonium setup. Covers generators, gemfile, and initial config.
 ---
 
 # Plutonium Installation
 
+## 🚨 Critical (read first)
+- **Use the generators.** `pu:core:install`, `pu:rodauth:install`, `pu:pkg:portal`, `pu:res:scaffold`, `pu:res:conn` — never hand-write base controllers, policies, or layouts.
+- **Use `base.rb`, not `plutonium.rb`, for existing apps.** The `plutonium.rb` template reruns the full bootstrap (dotenv, annotate, solid_*, assets) and clobbers git history. For any pre-existing app, use `base.rb`.
+- **Pass `--dest`, `--force`, `--auth`, `--skip-bundle` for unattended runs** so generators don't block on prompts. See `plutonium` index for the full flag matrix.
+- **Related skills:** `plutonium` (architecture overview), `plutonium-auth` (Rodauth setup), `plutonium-portal` (portal config), `plutonium-create-resource` (scaffolding resources).
+
+## Quick checklist
+
+Fresh install in a new Rails app:
+
+1. Generate the Rails app with `rails new myapp -a propshaft -j esbuild -c tailwind -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb` (greenfield) OR `bin/rails app:template LOCATION=.../base.rb` (existing app).
+2. Run `bundle install` if you added the gem manually.
+3. Run `rails generate pu:core:install` to create base controllers, policies, definitions, and config.
+4. Run `rails generate pu:rodauth:install` + `rails generate pu:rodauth:account user` for auth.
+5. Run `rails generate pu:pkg:portal admin --auth=user` to create a portal.
+6. Run `rails generate pu:res:scaffold Post title:string 'content:text?' --dest=main_app` for a first resource.
+7. Run `rails db:migrate`.
+8. Run `rails generate pu:res:conn Post --dest=admin_portal` to connect the resource.
+9. Mount the portal in `config/routes.rb`: `mount AdminPortal::Engine, at: "/admin"`.
+10. Start the server and visit `/admin`.
+
 ## New Rails App (Recommended)
 
 Use the Rails template for a fully configured setup:
@@ -18,6 +39,8 @@ This sets up Rails with Propshaft, esbuild, TailwindCSS, and Plutonium in one co
 
 ## Existing Rails App
 
+> **⚠️ Use `base.rb`, not `plutonium.rb`.** The `plutonium.rb` template is for `rails new` only — it re-runs the full app bootstrap (dotenv, annotate, solid_*, assets) and creates generic "initial commit" commits that clobber history. For any pre-existing app, always use `base.rb`.
+
 ### Option 1: Rails Template
 
 ```bash
@@ -293,7 +316,7 @@ For models that already exist in your app:
 ## Related Skills
 
 - `plutonium` - Resource architecture overview
-- `plutonium-rodauth` - Authentication setup and configuration
+- `plutonium-auth` - Authentication setup and configuration
 - `plutonium-package` - Feature and portal packages
 - `plutonium-portal` - Portal configuration
 - `plutonium-views` - Custom pages, layouts, and Phlex components

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

@@ -1,10 +1,17 @@
 ---
 name: plutonium-interaction
-description: Use when writing interaction classes for custom business logic, multi-step operations, or actions beyond basic CRUD
+description: Use BEFORE writing an interaction class, encapsulating business logic, or building multi-step operations beyond basic CRUD. Covers Plutonium::Resource::Interaction.
 ---
 
 # Plutonium Interactions
 
+## 🚨 Critical (read first)
+- **`ActiveRecord::RecordInvalid` is NOT rescued automatically.** Always rescue it when using `create!`/`update!`/`save!` and return `failed(e.record.errors)`.
+- **Return `succeed(...)` or `failed(...)`** from `execute` — the controller won't know what happened otherwise.
+- **Redirect is automatic on success.** Only call `with_redirect_response` for a *different* destination.
+- **Bulk actions use `resources` (plural).** Policy methods are checked per record; if any fails, the whole request fails.
+- **Related skills:** `plutonium-definition` (registering actions), `plutonium-policy` (authorizing actions), `plutonium-forms` (interaction form templates).
+
 Interactions encapsulate business logic into reusable, testable units. They handle input validation, execution, and outcomes.
 
 ## Basic Structure
@@ -377,7 +384,7 @@ end
 
 ## Related Skills
 
-- `plutonium-definition-actions` - Declaring actions in definitions
+- `plutonium-definition` - Declaring actions in definitions
 - `plutonium-forms` - Custom interaction form templates
 - `plutonium-policy` - Controlling access to actions
 - `plutonium` - How interactions fit in the architecture

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

@@ -1,10 +1,17 @@
 ---
 name: plutonium-invites
-description: Use when setting up user invitations with entity membership in a multi-tenant Plutonium app
+description: Use BEFORE setting up user invitations, pu:invites:install, or entity membership in a multi-tenant Plutonium app. Also load plutonium-entity-scoping.
 ---
 
 # Plutonium User Invites
 
+## 🚨 Critical (read first)
+- **Use the generators.** `pu:invites:install` and `pu:invites:invitable` — never hand-write invite models, mailers, or controllers. Prerequisites: user model, entity model, membership model (`pu:saas:setup` creates all three).
+- **Invite email must match the accepting user's email.** This is a security feature. Don't disable `enforce_email?` unless you fully understand the implications.
+- **Entity scoping applies to invites** — invites are automatically filtered by the current entity. See `plutonium-entity-scoping`.
+- **Implement `on_invite_accepted` on invitable models.** Plutonium calls it when the invite is accepted; without it, the invitable never learns about the new user.
+- **Related skills:** `plutonium-entity-scoping` (tenant scoping for invites), `plutonium-auth` (Rodauth signup flow), `plutonium-portal` (portal connection), `plutonium-interaction` (custom invite logic).
+
 Plutonium provides a complete user invitation system for multi-tenant applications. The system handles:
 - Sending email invitations to new users
 - Token-based invite acceptance flow
@@ -307,12 +314,9 @@ end
 
 ### Entity-Scoped Invite Management
 
-The `Invites::UserInvite` definition automatically scopes to the current entity:
+Invites are automatically filtered by the current entity — admins only see invites for their organization. This works because `Invites::UserInvite` has `belongs_to :entity`, which `associated_with` picks up.
 
-```ruby
-# In your portal, invites are automatically filtered by entity_scope
-# Admins only see invites for their organization
-```
+> **For how entity scoping works end-to-end (model shapes, `default_relation_scope`, portal strategies), see the [plutonium-entity-scoping](../plutonium-entity-scoping/SKILL.md) skill. It is the single source of truth.**
 
 ## Troubleshooting
 
@@ -357,7 +361,7 @@ end
 
 ## Related Skills
 
-- `plutonium-rodauth` - Authentication setup
+- `plutonium-auth` - Authentication setup
 - `plutonium-interaction` - Custom business logic
 - `plutonium-portal` - Portal configuration
 - `plutonium-policy` - Authorization for invite actions

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

@@ -1,10 +1,30 @@
 ---
 name: plutonium-model
-description: Use when working with Plutonium resource models - setup, structure, has_cents, associations, SGID support, entity scoping, and routing
+description: Use BEFORE editing a Plutonium resource model, adding associations, has_cents, SGID, or routing helpers. For tenancy / associated_with / relation_scope, also load plutonium-entity-scoping.
 ---
 
 # Plutonium Resource Models
 
+## 🚨 Critical (read first)
+- **Use `pu:res:scaffold`.** Never hand-write resource model files — the scaffold sets up `Plutonium::Resource::Record`, associations, and the expected section layout.
+- **Declare associations for the entity.** For multi-tenant apps, add `belongs_to`, `has_one :through`, or an `associated_with_<entity>` scope so `associated_with` can resolve. Fix the model, not the policy.
+- **Compound uniqueness** — in multi-tenant models, scope unique constraints to the tenant FK (`uniqueness: {scope: :organization_id}`), or you leak across tenants.
+- **Keep business logic out of the model.** Use interactions for multi-step ops, policies for authorization.
+- **Related skills:** `plutonium-entity-scoping` (tenancy mechanics), `plutonium-create-resource` (scaffold), `plutonium-definition` (UI), `plutonium-policy` (authorization).
+
+## Quick checklist
+
+Adding/editing a Plutonium model:
+
+1. Use `pu:res:scaffold` for new models; include `Plutonium::Resource::Record` on existing ones.
+2. Place associations/enums/validations in the right section (enums → belongs_to → has_one → has_many → scopes → validations → callbacks).
+3. For monetary fields, use `has_cents :field_cents`.
+4. For multi-tenancy, declare an association path to the entity (`belongs_to`, `has_one :through`, or a custom `associated_with_<entity>` scope).
+5. Add compound uniqueness scoped to the tenant FK.
+6. For SEO URLs, override `path_parameter` or `dynamic_path_parameter`.
+7. Override `to_label` if `:name`/`:title` isn't meaningful.
+8. Verify with `rails runner "puts Model.first.associated_with(entity).count"`.
+
 **Always use generators to create models** - never create model files manually:
 ```bash
 rails g pu:res:scaffold Post title:string content:text --dest=main_app
@@ -161,6 +181,31 @@ has_cents :field_cents,
   suffix: "amount"       # Suffix for generated name (default: "amount")
 ```
 
+### Using `has_cents` fields in policies and definitions
+
+**Always reference the virtual accessor (`:price`), never the underlying column (`:price_cents`).**
+
+```ruby
+# Model
+class Product < ResourceRecord
+  has_cents :price_cents   # exposes virtual :price
+end
+
+# ✅ Policy — use the virtual name
+class ProductPolicy < ResourcePolicy
+  def permitted_attributes_for_create
+    %i[name price]   # NOT :price_cents
+  end
+end
+
+# ✅ Definition — use the virtual name
+class ProductDefinition < ResourceDefinition
+  field :price, as: :decimal
+end
+```
+
+The virtual accessor handles form input, validation, and display as a decimal. Using `:price_cents` directly in a policy or definition forces users to enter integer cents and bypasses the conversion. Generators sometimes emit the `_cents` name in the policy — fix it by hand if you see it (and add `has_cents` if it's missing from the model).
+
 ### Validation
 
 ```ruby
@@ -233,64 +278,19 @@ user.remove_post_sgid("BAh7CEkiCG...")  # Remove from collection
 
 ## Entity Scoping (associated_with)
 
-Query records associated with another record. Essential for multi-tenant apps.
+`Plutonium::Resource::Record` provides `Model.associated_with(entity)` for multi-tenant queries. It resolves via a custom `associated_with_<entity>` scope, a direct `belongs_to`, or an auto-detected `has_one :through` chain.
 
-### Basic Usage
+Quick example:
 
 ```ruby
 class Comment < ResourceRecord
   belongs_to :post
 end
 
-# Find comments for a post
-Comment.associated_with(post)
-# => Comment.where(post: post)
+Comment.associated_with(post)  # => Comment.where(post: post)
 ```
 
-### Association Detection
-
-Works with:
-- `belongs_to` - Uses WHERE clause (most efficient)
-- `has_one` - Uses JOIN + WHERE
-- `has_many` - Uses JOIN + WHERE
-
-```ruby
-# Direct association (preferred)
-Comment.associated_with(post)  # WHERE post_id = ?
-
-# Reverse association (less efficient, logs warning)
-Post.associated_with(comment)  # JOIN comments WHERE comments.id = ?
-```
-
-### Custom Scopes
-
-For optimal performance, define custom scopes:
-
-```ruby
-class Comment < ResourceRecord
-  # Custom scope naming: associated_with_{model_name}
-  scope :associated_with_user, ->(user) do
-    joins(:post).where(posts: {user_id: user.id})
-  end
-end
-
-# Automatically uses custom scope
-Comment.associated_with(user)
-```
-
-### Error Handling
-
-```ruby
-# When no association exists
-UnrelatedModel.associated_with(user)
-# Raises: Could not resolve the association between 'UnrelatedModel' and 'User'
-#
-# Define:
-#  1. the associations between the models
-#  2. a named scope on UnrelatedModel e.g.
-#
-# scope :associated_with_user, ->(user) { do_something_here }
-```
+> **For entity scoping details — the three model shapes (direct child, join table, grandchild), `has_one :through` patterns, custom scopes, `default_relation_scope`, and how it fits with policies and portals — see the [plutonium-entity-scoping](../plutonium-entity-scoping/SKILL.md) skill. It is the single source of truth.**
 
 ## URL Routing
 

data/.claude/skills/plutonium-nested-resources/SKILL.md

@@ -1,10 +1,17 @@
 ---
 name: plutonium-nested-resources
-description: Use when configuring parent/child resource relationships, nested routes, or scoped URL generation in Plutonium
+description: Use BEFORE configuring parent/child resource relationships, nested routes, or scoped URL generation with resource_url_for(parent:).
 ---
 
 # Nested Resources
 
+## 🚨 Critical (read first)
+- **Use `pu:res:scaffold` + `pu:res:conn`** for both parent and child. Nested routes are generated from the `belongs_to` + association on the parent — no manual route wiring.
+- **Parent scoping beats entity scoping.** When a parent is present, `default_relation_scope` scopes via the parent, not via `entity_scope`. Don't double-scope in the policy.
+- **Plutonium supports one level of nesting.** Grandparent → parent → child nested routes are NOT supported. Use top-level routes for deeper relationships.
+- **Named custom routes only.** When adding member/collection routes on a nested resource, always pass `as:` — otherwise `resource_url_for` will fail.
+- **Related skills:** `plutonium-entity-scoping` (how parent scoping interacts with entity scoping), `plutonium-policy` (parent scoping in `relation_scope`), `plutonium-controller` (presentation hooks), `plutonium-portal` (route registration).
+
 **Always use generators** to create both parent and child resources, then connect them to portals:
 ```bash
 rails g pu:res:scaffold Company name:string --dest=main_app

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

@@ -1,10 +1,17 @@
 ---
 name: plutonium-package
-description: Use when creating feature packages or portal packages to organize a Plutonium app into modular engines
+description: Use BEFORE creating a feature package or portal package via pu:pkg:package / pu:pkg:portal, or organizing a Plutonium app into modular engines.
 ---
 
 # Plutonium Packages
 
+## 🚨 Critical (read first)
+- **Use the generators.** `pu:pkg:package` for feature packages, `pu:pkg:portal` for portal packages — never hand-write engine files or directory structures.
+- **Feature vs portal is a hard split.** Feature packages hold models/policies/definitions/interactions; portal packages hold controllers/views/routes/auth. Don't mix.
+- **Package classes are auto-namespaced** (`packages/blogging/app/models/blogging/post.rb` → `Blogging::Post`). Don't fight the namespacing.
+- **Cross-package resource references** use the full namespace: `rails g pu:res:conn Blogging::Post --dest=admin_portal`.
+- **Related skills:** `plutonium-portal` (portal-specific features), `plutonium-create-resource` (creating resources in packages), `plutonium-installation` (package loading).
+
 Packages are specialized Rails engines for organizing code. There are two types:
 
 | Type | Purpose | Generator |