plutonium 0.44.0 → 0.45.0

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

@@ -1,10 +1,16 @@
 ---
 name: plutonium-model
-description: Overview of Plutonium resource models - structure, setup, and best practices
+description: Use when working with Plutonium resource models - setup, structure, has_cents, associations, SGID support, entity scoping, and routing
 ---
 
 # Plutonium Resource Models
 
+**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
+```
+See `plutonium-create-resource` for full field type syntax and generator options.
+
 A model becomes a Plutonium resource by including `Plutonium::Resource::Record`. This provides enhanced ActiveRecord functionality for routing, labeling, field introspection, associations, and monetary handling.
 
 ## Setup
@@ -122,88 +128,220 @@ end
 13. **Misc attribute macros** - `has_rich_text`, `has_secure_token`, `has_secure_password`
 14. **Methods** - Public methods above, private methods below
 
-## Common Patterns
+## Monetary Handling (has_cents)
 
-### Archiving (State-Based)
+Store monetary values as integers (cents) while exposing decimal interfaces.
 
-```ruby
-class Property < ResourceRecord
-  enum :state, archived: 0, active: 1
+### Basic Usage
 
-  scope :active, -> { where(state: :active) }
-  scope :archived, -> { where(state: :archived) }
+```ruby
+class Product < ResourceRecord
+  has_cents :price_cents                    # Creates price getter/setter
+  has_cents :cost_cents, name: :wholesale   # Custom accessor name
+  has_cents :tax_cents, rate: 1000          # 3 decimal places
+  has_cents :quantity_cents, rate: 1        # Whole numbers only
+end
 
-  def archive!
-    update!(state: :archived)
-  end
+product = Product.new
+product.price = 19.99
+product.price_cents  # => 1999
+product.price        # => 19.99
 
-  def restore!
-    update!(state: :active)
-  end
-end
+# Truncates (doesn't round)
+product.price = 10.999
+product.price_cents  # => 1099
 ```
 
-### Multi-Tenant Scoping
+### Options
 
 ```ruby
-class Property < ResourceRecord
-  belongs_to :company
+has_cents :field_cents,
+  name: :custom_name,    # Accessor name (default: field without _cents)
+  rate: 100,             # Conversion rate (default: 100)
+  suffix: "amount"       # Suffix for generated name (default: "amount")
+```
 
-  # Compound uniqueness for multi-tenant
-  validates :property_code, uniqueness: {scope: :company_id}
+### Validation
 
-  # Custom scope for entity scoping
-  scope :associated_with_company, ->(company) { where(company: company) }
+```ruby
+class Product < ResourceRecord
+  has_cents :price_cents
+
+  # Validate the cents field
+  validates :price_cents, numericality: {greater_than: 0}
 end
+
+product = Product.new(price: -10)
+product.valid?  # => false
+product.errors[:price_cents]  # => ["must be greater than 0"]
+product.errors[:price]        # => ["is invalid"] (propagated)
 ```
 
-### Custom Validation
+### Introspection
 
 ```ruby
-class Contact < ResourceRecord
-  validates :contact_type, presence: true
+Product.has_cents_attributes
+# => {price_cents: {name: :price, rate: 100}, ...}
 
-  validate :ensure_contact_provided
+Product.has_cents_attribute?(:price_cents)  # => true
+```
 
-  private
+## Association SGID Support
 
-  def ensure_contact_provided
-    return unless [email, phone, website].all?(&:blank?)
-    errors.add(:base, "Please provide at least one contact method")
-  end
+All associations get Signed Global ID (SGID) methods for secure serialization.
+
+### Singular Associations (belongs_to, has_one)
+
+```ruby
+class Post < ResourceRecord
+  belongs_to :user
+  has_one :featured_image
 end
+
+post = Post.first
+
+# Get SGID
+post.user_sgid           # => "BAh7CEkiCG..."
+post.featured_image_sgid # => "BAh7CEkiCG..."
+
+# Set by SGID (finds and assigns)
+post.user_sgid = "BAh7CEkiCG..."
+post.featured_image_sgid = "BAh7CEkiCG..."
 ```
 
-### One-to-One Relationships
+### Collection Associations (has_many, has_and_belongs_to_many)
 
 ```ruby
-# Parent side
-class Tenant < ResourceRecord
-  has_one :residential_profile, class_name: "ResidentialTenantProfile"
-  has_one :commercial_profile, class_name: "CommercialTenantProfile"
+class User < ResourceRecord
+  has_many :posts
+  has_and_belongs_to_many :roles
 end
 
-# Child side (unique index on foreign key)
-class ResidentialTenantProfile < ResourceRecord
-  belongs_to :tenant
-  # Migration: t.index :tenant_id, unique: true
+user = User.first
+
+# Get SGIDs
+user.post_sgids  # => ["BAh7CEkiCG...", "BAh7CEkiCG..."]
+user.role_sgids  # => ["BAh7CEkiCG...", "BAh7CEkiCG..."]
+
+# Bulk assignment
+user.post_sgids = ["BAh7CEkiCG...", ...]
+
+# Individual manipulation
+user.add_post_sgid("BAh7CEkiCG...")     # Add to collection
+user.remove_post_sgid("BAh7CEkiCG...")  # Remove from collection
+```
+
+## Entity Scoping (associated_with)
+
+Query records associated with another record. Essential for multi-tenant apps.
+
+### Basic Usage
+
+```ruby
+class Comment < ResourceRecord
+  belongs_to :post
 end
+
+# Find comments for a 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 = ?
 ```
 
-### Polymorphic Associations
+### Custom Scopes
+
+For optimal performance, define custom scopes:
 
 ```ruby
 class Comment < ResourceRecord
-  belongs_to :commentable, polymorphic: true
+  # Custom scope naming: associated_with_{model_name}
+  scope :associated_with_user, ->(user) do
+    joins(:post).where(posts: {user_id: user.id})
+  end
 end
 
-class Post < ResourceRecord
-  has_many :comments, as: :commentable
+# 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 }
+```
+
+## URL Routing
+
+### Default Behavior
+
+```ruby
+user = User.find(1)
+user.to_param  # => "1"
+```
+
+### Custom Path Parameters
+
+Use a stable, unique field instead of ID:
+
+```ruby
+class User < ResourceRecord
+  private
+
+  def path_parameter(param_name)
+    :username  # Must be unique
+  end
 end
 
-class Photo < ResourceRecord
-  has_many :comments, as: :commentable
+user = User.create(username: "john_doe")
+user.to_param  # => "john_doe"
+# URLs: /users/john_doe
+```
+
+### Dynamic Path Parameters (SEO-friendly)
+
+Include ID prefix for uniqueness with human-readable suffix:
+
+```ruby
+class Article < ResourceRecord
+  private
+
+  def dynamic_path_parameter(param_name)
+    :title
+  end
 end
+
+article = Article.create(id: 1, title: "My Great Article")
+article.to_param  # => "1-my-great-article"
+# URLs: /articles/1-my-great-article
+```
+
+### Path Parameter Lookup
+
+```ruby
+User.from_path_param("john_doe")
+Article.from_path_param("1-my-great-article")  # Extracts ID
 ```
 
 ## Labeling
@@ -244,6 +382,49 @@ User.has_one_attached_field_names         # Active Storage single
 User.has_many_attached_field_names        # Active Storage multiple
 ```
 
+## Common Patterns
+
+### Archiving (State-Based)
+
+```ruby
+class Property < ResourceRecord
+  enum :state, archived: 0, active: 1
+
+  scope :active, -> { where(state: :active) }
+  scope :archived, -> { where(state: :archived) }
+end
+```
+
+### Multi-Tenant Scoping
+
+```ruby
+class Property < ResourceRecord
+  belongs_to :company
+
+  # Compound uniqueness for multi-tenant
+  validates :property_code, uniqueness: {scope: :company_id}
+
+  # Custom scope for entity scoping
+  scope :associated_with_company, ->(company) { where(company: company) }
+end
+```
+
+## Performance Tips
+
+```ruby
+# Efficient: Direct belongs_to
+Comment.associated_with(post)  # Simple WHERE
+
+# Less efficient: Reverse has_many (logs warning)
+Post.associated_with(comment)  # JOIN required
+
+# Optimal: Custom scope when direct isn't possible
+scope :associated_with_user, ->(user) { where(user_id: user.id) }
+
+# SGID: Batch assignment over individual adds
+user.post_sgids = sgid_array  # Single operation
+```
+
 ## Best Practices
 
 1. **Use enums for state** - `enum :state, archived: 0, active: 1` instead of soft-delete
@@ -253,15 +434,7 @@ User.has_many_attached_field_names        # Active Storage multiple
 5. **Validate at boundaries** - Validate user input, trust internal code
 6. **Use scopes** - Define commonly used queries as scopes
 
-## Integration
-
-Models integrate with:
-- **Policies** - `resource_field_names` for auto-detection
-- **Definitions** - Field introspection for forms/displays
-- **Controllers** - `from_path_param` for lookups
-- **Query Objects** - Association detection for sorting
-
 ## Related Skills
 
-- `plutonium-model-features` - has_cents, associations, scopes, routes
 - `plutonium-create-resource` - Scaffold generator for new resources
+- `plutonium-definition` - Definition overview, fields, inputs, displays

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

@@ -1,10 +1,17 @@
 ---
 name: plutonium-nested-resources
-description: Plutonium nested resources - parent/child routes, scoping, and URL generation
+description: Use when configuring parent/child resource relationships, nested routes, or scoped URL generation in Plutonium
 ---
 
 # Nested Resources
 
+**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
+rails g pu:res:scaffold Property company:belongs_to name:string --dest=main_app
+rails g pu:res:conn Company Property --dest=admin_portal
+```
+
 Plutonium automatically creates nested routes for `has_many` and `has_one` associations, scopes queries to the parent, and handles URL generation.
 
 ## How It Works
@@ -333,4 +340,4 @@ Generates nested routes:
 - `plutonium-portal` - Route registration
 - `plutonium-policy` - Authorization and scoping
 - `plutonium-controller` - Presentation hooks
-- `plutonium-model-features` - associated_with scope
+- `plutonium-model` - associated_with scope

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

@@ -1,6 +1,6 @@
 ---
 name: plutonium-package
-description: Plutonium packages - modular Rails engines for organizing features and portals
+description: Use when creating feature packages or portal packages to organize a Plutonium app into modular engines
 ---
 
 # Plutonium Packages
@@ -186,6 +186,6 @@ rails db:migrate  # Runs migrations from all packages
 ## Related Skills
 
 - `plutonium-portal` - Portal-specific features (auth, entity scoping, routes)
-- `plutonium-resource` - Resource architecture overview
-- `plutonium-connect-resource` - Connecting resources to portals
+- `plutonium` - Resource architecture overview
+- `plutonium-portal` - Connecting resources to portals
 - `plutonium-create-resource` - Creating resources

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

@@ -1,10 +1,14 @@
 ---
 name: plutonium-policy
-description: Plutonium resource policies - authorization, attribute permissions, and scoping
+description: Use when configuring authorization - action permissions, attribute visibility, relation scoping, or per-portal policies
 ---
 
 # Plutonium Policies
 
+**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
+
 Policies control WHO can do WHAT with resources. Built on [ActionPolicy](https://actionpolicy.evilmartians.io/).
 
 Plutonium extends ActionPolicy with:
@@ -456,6 +460,6 @@ end
 
 ## Related Skills
 
-- `plutonium-resource` - How policies fit in the resource architecture
+- `plutonium` - How policies fit in the resource architecture
 - `plutonium-definition-actions` - Actions that need policy methods
 - `plutonium-controller` - How controllers use policies

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

@@ -1,6 +1,6 @@
 ---
 name: plutonium-portal
-description: Plutonium portals - web interfaces with authentication, entity scoping, and routes
+description: Use when creating portals, connecting resources to portals, configuring authentication, entity scoping, or portal routes
 ---
 
 # Plutonium Portals
@@ -32,10 +32,7 @@ rails g pu:pkg:portal custom --byo
 rails g pu:pkg:portal admin --auth=admin --scope=Organization
 ```
 
-Without flags, the generator prompts interactively:
-- **Rodauth account** - Use existing Rodauth authentication
-- **Public access** - No authentication required
-- **Bring your own** - Implement custom `current_user`
+Without flags, the generator prompts interactively.
 
 ## Portal Engine
 
@@ -53,6 +50,86 @@ module DashboardPortal
 end
 ```
 
+## Connecting Resources to Portals
+
+Resources must be connected to a portal to be accessible via its web interface.
+
+### Command Syntax
+
+```bash
+rails g pu:res:conn RESOURCE [RESOURCE...] --dest=PORTAL_NAME [--singular]
+```
+
+**Always specify resources directly** - this avoids interactive prompts.
+
+### Usage Patterns
+
+```bash
+# Main app resources
+rails g pu:res:conn Post Comment Tag --dest=dashboard_portal
+
+# Namespaced resources (from a feature package)
+rails g pu:res:conn Blogging::Post Blogging::Comment --dest=admin_portal
+
+# Singular resources (profile, dashboard, settings)
+rails g pu:res:conn Profile --dest=customer_portal --singular
+```
+
+### What Gets Generated
+
+For a resource `Post` connected to `admin_portal`:
+
+```
+packages/admin_portal/app/
+├── controllers/admin_portal/posts_controller.rb   # Portal controller
+├── policies/admin_portal/post_policy.rb           # Portal policy
+└── definitions/admin_portal/post_definition.rb    # Portal definition
+```
+
+Plus route registration in `packages/admin_portal/config/routes.rb`.
+
+### Generated Controller
+
+```ruby
+class AdminPortal::PostsController < ::PostsController
+  include AdminPortal::Concerns::Controller
+end
+```
+
+### Generated Policy
+
+```ruby
+class AdminPortal::PostPolicy < ::PostPolicy
+  include AdminPortal::ResourcePolicy
+
+  def permitted_attributes_for_create
+    [:title, :content, :user_id]
+  end
+
+  def permitted_attributes_for_read
+    [:title, :content, :user_id, :created_at, :updated_at]
+  end
+
+  def permitted_associations
+    %i[]
+  end
+end
+```
+
+### Route Registration
+
+```ruby
+# In packages/admin_portal/config/routes.rb
+register_resource ::Post
+register_resource ::Profile, singular: true  # With --singular
+```
+
+### Important Notes
+
+1. **Always specify resources directly** - avoids prompts, no `--src` needed
+2. **Always use the generator** - never manually connect resources
+3. **Run after migrations** - the generator reads model columns for policy attributes
+
 ## Authentication
 
 ### Rodauth Integration
@@ -224,13 +301,6 @@ register_resource ::Post do
 end
 ```
 
-This generates:
-- `GET /posts/:id/preview`
-- `GET /posts/:id/analytics`
-- `POST /posts/:id/publish`
-- `GET /posts/archived`
-- `POST /posts/bulk_publish`
-
 ### Mounting in Main App
 
 ```ruby
@@ -263,8 +333,6 @@ end
 
 ### Portal ResourceController
 
-The portal's `ResourceController` serves as the base class for resource controllers when no feature package controller exists. It includes the portal's `Concerns::Controller` so individual resource controllers don't need to.
-
 ```ruby
 # packages/dashboard_portal/app/controllers/dashboard_portal/resource_controller.rb
 module DashboardPortal
@@ -279,7 +347,6 @@ end
 For portal pages not tied to a resource (dashboard, settings, etc.), inherit from `PlutoniumController`:
 
 ```ruby
-# packages/dashboard_portal/app/controllers/dashboard_portal/dashboard_controller.rb
 module DashboardPortal
   class DashboardController < PlutoniumController
     def index
@@ -294,10 +361,7 @@ end
 ### Override Definition
 
 ```ruby
-# packages/dashboard_portal/app/definitions/dashboard_portal/post_definition.rb
 class DashboardPortal::PostDefinition < ::PostDefinition
-  # Hide certain actions from this portal
-  # Add portal-specific scopes
   scope :my_posts, -> { where(user: current_user) }
 end
 ```
@@ -305,7 +369,6 @@ end
 ### Override Policy
 
 ```ruby
-# packages/dashboard_portal/app/policies/dashboard_portal/post_policy.rb
 class DashboardPortal::PostPolicy < ::PostPolicy
   include DashboardPortal::ResourcePolicy
 
@@ -322,7 +385,6 @@ end
 ### Override Controller
 
 ```ruby
-# packages/dashboard_portal/app/controllers/dashboard_portal/posts_controller.rb
 module DashboardPortal
   class PostsController < ResourceController
     private
@@ -334,39 +396,6 @@ module DashboardPortal
 end
 ```
 
-## Layout and Views
-
-### Portal Layout
-
-```erb
-<!-- packages/dashboard_portal/app/views/layouts/dashboard_portal.html.erb -->
-<!DOCTYPE html>
-<html>
-<head>
-  <title>Dashboard</title>
-  <%= csrf_meta_tags %>
-  <%= stylesheet_link_tag "application" %>
-</head>
-<body>
-  <nav><!-- Portal navigation --></nav>
-  <main><%= yield %></main>
-</body>
-</html>
-```
-
-### Dashboard Controller
-
-```ruby
-# packages/dashboard_portal/app/controllers/dashboard_portal/dashboard_controller.rb
-module DashboardPortal
-  class DashboardController < PlutoniumController
-    def index
-      # Dashboard home page
-    end
-  end
-end
-```
-
 ## Multiple Portals Example
 
 ```ruby
@@ -400,17 +429,26 @@ module PublicPortal
 end
 ```
 
-Each portal can:
-- Have different authentication
-- Show different fields
-- Allow different actions
-- Use different layouts
+## Typical Workflow
+
+```bash
+# 1. Create portal
+rails g pu:pkg:portal admin --auth=admin --scope=Organization
+
+# 2. Create resources
+rails g pu:res:scaffold Post user:belongs_to title:string 'content:text?' --dest=main_app
+rails db:migrate
+
+# 3. Connect resources to portal
+rails g pu:res:conn Post --dest=admin_portal
+
+# 4. Customize portal-specific definitions/policies as needed
+```
 
 ## Related Skills
 
 - `plutonium-package` - Package overview (features vs portals)
 - `plutonium-rodauth` - Authentication setup and configuration
-- `plutonium-connect-resource` - Connecting resources to portals
 - `plutonium-policy` - Portal-specific policies
 - `plutonium-definition` - Portal-specific definitions
 - `plutonium-controller` - Portal-specific controllers

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

@@ -1,6 +1,6 @@
 ---
 name: plutonium-profile
-description: Plutonium user profile - account settings page with Rodauth security links
+description: Use when adding a user profile or account settings page with Rodauth security features
 ---
 
 # Plutonium User Profile
@@ -273,4 +273,4 @@ current_user.profile || current_user.create_profile
 - `plutonium-rodauth` - Authentication configuration
 - `plutonium-definition` - Customizing the profile definition
 - `plutonium-views` - Custom pages and components
-- `plutonium-connect-resource` - Connecting resources to portals
+- `plutonium-portal` - Connecting resources to portals

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

@@ -1,6 +1,6 @@
 ---
 name: plutonium-rodauth
-description: Plutonium Rodauth integration - authentication setup, account types, and configuration
+description: Use when setting up authentication - Rodauth configuration, account types, login flows, or multi-account support
 ---
 
 # Plutonium Rodauth Authentication

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

@@ -1,6 +1,6 @@
 ---
 name: plutonium-theming
-description: Plutonium design token system - CSS custom properties, component classes, and consistent styling patterns
+description: Use when customizing colors, typography, spacing, or component appearance via Plutonium design tokens
 ---
 
 # Plutonium Design Token System