plutonium 0.50.0 → 0.52.0

data/docs/guides/user-profile.md

@@ -1,322 +1,163 @@
 # User Profile
 
-Plutonium provides a Profile resource generator for user account settings. The Profile page allows users to manage their personal information and access Rodauth security features like password changes, two-factor authentication, and session management.
+Add a profile / account-settings page where users edit personal fields and access Rodauth security features (change password, 2FA, etc.) in one place.
 
-## Overview
+## Goal
 
-The profile system provides:
-- **Profile Resource**: A standard Plutonium resource linked to the User model
-- **Security Section**: Automatic display of enabled Rodauth security features
-- **Customizable Fields**: Add any fields you need (bio, avatar, preferences, etc.)
+A `/profile` URL that shows the user's personal fields plus a "Security" section linking to Rodauth-managed features.
 
-## Prerequisites
+## 🚨 Critical
 
-Before installing the profile, ensure you have:
+- **Profile association is always `:profile`** regardless of the model class — `current_user.profile`, `build_profile`, `params.require(:profile)` always work.
+- **Profile needs `pu:profile:conn` to be visible** — without it, no `/profile` route, no `profile_url` helper.
+- **Every user needs a profile row.** Add an `after_create :create_profile!` callback to the user model. Without it, `current_user.profile` is nil.
 
-1. **User Authentication**: A Rodauth user account set up
-2. **Model Markers**: The User model with marker comments
+The show page renders the user's fields, then the **Security Settings** block with Rodauth-backed actions:
 
-The easiest way to set this up is with the SaaS generator:
+![User profile show page with SecuritySection](/images/guides/user-profile-show.png)
 
-```bash
-rails g pu:saas:user User
-```
+Editing produces a regular Plutonium form — same form generator the rest of your resources use:
 
-## Installation
+![User profile edit form](/images/guides/user-profile-edit.png)
 
-### Step 1: Install the Profile Resource
+## Quick path
 
 ```bash
-rails generate pu:profile:install --dest=main_app
+rails g pu:profile:setup date_of_birth:date bio:text \
+  --dest=competition \
+  --portal=competition_portal
 ```
 
-With custom fields:
+`pu:profile:setup` is a meta-generator — runs `pu:profile:install` + `pu:profile:conn` in one shot.
+
+## Step-by-step
+
+### 1. Install
 
 ```bash
-rails g pu:profile:install \
-    bio:text \
-    avatar:attachment \
-    'timezone:string?' \
-    notifications_enabled:boolean \
-    --dest=main_app
+rails generate pu:profile:install bio:text avatar:attachment 'timezone:string?' \
+  --dest=customer
 ```
 
-### Options
-
 | Option | Default | Description |
-|--------|---------|-------------|
-| `--dest` | (prompts) | Target destination package or main_app |
-| `--user-model` | User | Rodauth user model name |
+|---|---|---|
+| `--dest=DEST` | (prompts) | Target package or `main_app` |
+| `--user-model=NAME` | `User` | Rodauth user model |
 
-### Step 2: Run Migrations
+Custom resource name (first positional argument):
 
 ```bash
-rails db:migrate
+rails g pu:profile:install AccountSettings bio:text --dest=main_app
 ```
 
-### Step 3: Connect to Portal
+By default the model is `{UserModel}Profile` (`UserProfile`, `StaffUserProfile`, etc.).
 
-Connect the Profile to your portal using the profile connect generator:
+### 2. Migrate
 
 ```bash
-rails g pu:profile:conn --dest=customer_portal
+rails db:migrate
 ```
 
-This:
-- Registers the Profile as a singular resource (`/profile` instead of `/profiles/:id`)
-- Configures the `profile_url` helper to enable the "Profile" link in the user menu
-
-## Generated Files
+### 3. Connect to a portal
 
-The generator creates a standard Plutonium resource:
-
-```
-app/models/profile.rb
-db/migrate/xxx_create_profiles.rb
-app/controllers/profiles_controller.rb
-app/policies/profile_policy.rb
-app/definitions/profile_definition.rb
+```bash
+rails g pu:profile:conn --dest=customer_portal
 ```
 
-And modifies:
-- **User model**: Adds `has_one :profile, dependent: :destroy`
-- **Definition**: Injects custom ShowPage with security links
-
-## Security Section
-
-The ShowPage automatically displays links to enabled Rodauth security features.
-
-Available features (only shown if enabled in Rodauth):
-
-| Feature | Link Label | Description |
-|---------|------------|-------------|
-| `change_password` | Change Password | Update account password |
-| `change_login` | Change Email | Update email address |
-| `otp` | Two-Factor Authentication | Set up TOTP authenticator |
-| `recovery_codes` | Recovery Codes | View or regenerate backup codes |
-| `webauthn` | Security Keys | Manage passkeys and hardware keys |
-| `active_sessions` | Active Sessions | View and revoke sessions |
-| `close_account` | Close Account | Permanently delete account |
-
-## Creating Profiles for Users
+This registers the profile as a **singular** resource — exposes `/profile` (no `:id`) and the `profile_url` helper.
 
-Users need a profile created before they can access it. Choose one approach:
-
-### Option A: Automatic Creation on User Signup
+### 4. Add the auto-create callback
 
 ```ruby
-# app/models/user.rb
+# app/models/user.rb (modified by pu:profile:install)
 class User < ApplicationRecord
-  has_one :profile, dependent: :destroy
+  has_one :profile, class_name: "UserProfile", dependent: :destroy
 
   after_create :create_profile!
 
   private
-
-  def create_profile!
-    create_profile
-  end
-
-  # add has_one associations above.
+  def create_profile! = create_profile
 end
 ```
 
-### Option B: Create on First Access
-
-In your portal's application controller:
+For existing users at migration time:
 
-```ruby
-class ApplicationController < PlutoniumController
-  before_action :ensure_profile
-
-  private
-
-  def ensure_profile
-    return unless current_user
-    current_user.profile || current_user.create_profile
-  end
-end
+```bash
+rails runner "User.find_each(&:create_profile)"
 ```
 
-### Option C: Find or Create in Profile Controller
+## What you get
 
-```ruby
-# app/controllers/profiles_controller.rb
-class ProfilesController < ResourceController
-  private
+The generated definition injects a custom `ShowPage` that renders `SecuritySection` — dynamically lists Rodauth security links based on which features are enabled:
 
-  def current_resource
-    @current_resource ||= current_user.profile || current_user.create_profile
-  end
-end
-```
+| Feature enabled | Link rendered |
+|---|---|
+| `change_password` | Change Password |
+| `change_login` | Change Email |
+| `otp` | Two-Factor Authentication |
+| `recovery_codes` | Recovery Codes |
+| `webauthn` | Security Keys |
+| `active_sessions` | Active Sessions |
+| `close_account` | Close Account |
 
-## Customization
+If a feature isn't enabled, its link doesn't render — no configuration needed.
 
-### Adding Custom Fields
-
-Edit the generated definition to configure how fields appear:
+## Linking to the profile
 
 ```ruby
-# app/definitions/profile_definition.rb
-class ProfileDefinition < Plutonium::Resource::Definition
-  form do |f|
-    f.field :bio, as: :text
-    f.field :avatar, as: :attachment
-    f.field :timezone, collection: ActiveSupport::TimeZone.all.map(&:name)
-    f.field :notifications_enabled
-  end
-
-  display do |d|
-    d.field :bio
-    d.field :avatar
-    d.field :timezone
-    d.field :notifications_enabled
-  end
-
-  class ShowPage < ShowPage
-    private
-
-    def render_after_content
-      render Plutonium::Profile::SecuritySection.new
-    end
-  end
-end
+link_to("Profile", profile_url) if respond_to?(:profile_url)
 ```
 
-### Custom Security Section
+The `respond_to?` guard is defensive — only portals that ran `pu:profile:conn` have the helper.
+
+## Customizing the definition
 
-Create your own security section component:
+The generated profile is a normal Plutonium definition. Customize like any other:
 
 ```ruby
-# app/components/custom_security_section.rb
-class CustomSecuritySection < Plutonium::UI::Component::Base
-  def view_template
-    div(class: "mt-8") do
-      h2(class: "text-lg font-semibold") { "Account Security" }
-
-      if rodauth.features.include?(:change_password)
-        a(href: rodauth.change_password_path) { "Change Password" }
-      end
-
-      # Add your custom links
-      a(href: "/settings/notifications") { "Notification Preferences" }
-    end
-  end
-end
-```
+class UserProfileDefinition < Plutonium::Resource::Definition
+  field :bio, as: :markdown
+  input :avatar, as: :uppy
+  field :timezone, as: :select, choices: ActiveSupport::TimeZone.all.map(&:name)
 
-Use it in your definition:
+  metadata :created_at, :updated_at
 
-```ruby
-class ProfileDefinition < Plutonium::Resource::Definition
   class ShowPage < ShowPage
     private
 
     def render_after_content
-      render CustomSecuritySection.new
+      render Plutonium::Profile::SecuritySection.new
     end
   end
 end
 ```
 
-### Adding Profile Actions
-
-Add custom actions to the profile:
-
-```ruby
-class ProfileDefinition < Plutonium::Resource::Definition
-  action :export_data,
-    interaction: Profile::ExportDataInteraction,
-    icon: Phlex::TablerIcons::Download
-
-  action :verify_email,
-    interaction: Profile::VerifyEmailInteraction,
-    category: :secondary
-end
-```
-
-### Profile Link in Navigation
-
-Add a profile link to your application layout or header:
-
-```ruby
-# In your header component
-if current_user && respond_to?(:profile_path)
-  a(href: profile_path) { "My Profile" }
-end
-```
-
-## Policy Configuration
-
-The generated policy controls access:
-
-```ruby
-# app/policies/profile_policy.rb
-class ProfilePolicy < Plutonium::Resource::Policy
-  # Users can only access their own profile
-  def read?
-    resource.user == user
-  end
-
-  def update?
-    resource.user == user
-  end
-
-  def destroy?
-    false # Disable deletion through the UI
-  end
-
-  # Only allow editing these attributes
-  def permitted_attributes_for_update
-    [:bio, :avatar, :timezone, :notifications_enabled]
-  end
-end
-```
-
-## Troubleshooting
-
-### "Profile not found" Error
+See [Reference › Resource › Definition](/reference/resource/definition) for the full definition surface.
 
-Ensure the user has a profile created. Use one of the creation strategies above.
+## Multiple account types
 
-### Security Links Not Showing
+If your app has both `User` and `StaffUser` accounts, run `pu:profile:install` once per:
 
-Security links only appear for features enabled in your Rodauth configuration:
-
-```ruby
-# app/rodauth/user_rodauth_plugin.rb
-class UserRodauthPlugin < Plutonium::Auth::RodauthPlugin
-  configure do
-    enable :change_password, :change_login, :otp, :active_sessions
-    # Only these features will show in the security section
-  end
-end
+```bash
+rails g pu:profile:install --user-model=User --dest=main_app
+rails g pu:profile:install --user-model=StaffUser --dest=main_app
 ```
 
-### Profile Routes Conflicting
-
-Ensure you use `--singular` when connecting:
+Each gets its own `*Profile` model with `:profile` association on the respective user. Connect each to the appropriate portal:
 
 ```bash
-rails g pu:res:conn Profile --dest=my_portal --singular
+rails g pu:profile:conn UserProfile      --dest=customer_portal
+rails g pu:profile:conn StaffUserProfile --dest=admin_portal
 ```
 
-This creates `/profile` (singular) instead of `/profiles/:id`.
+## Common issues
 
-### Changes Not Saving
-
-Check your policy's `permitted_attributes_for_update`:
-
-```ruby
-def permitted_attributes_for_update
-  [:bio, :avatar, :timezone, :notifications_enabled]
-end
-```
+- **`current_user.profile` is nil** — every user needs a profile row. Add `after_create :create_profile!` to the user model.
+- **`profile_url` is undefined** — the profile isn't connected to this portal. Run `pu:profile:conn --dest=<portal>`.
+- **`SecuritySection` shows nothing** — none of the relevant Rodauth features are enabled. Enable `change_password`, `otp`, etc. on the Rodauth plugin.
 
-## Next Steps
+## Related
 
-- [Authentication](/guides/authentication) - Set up Rodauth features
-- [Custom Actions](/guides/custom-actions) - Add profile actions
-- [Views](/guides/views) - Customize the profile page
-- [Authorization](/guides/authorization) - Configure profile policies
+- [Reference › Auth › Profile](/reference/auth/profile) — full surface
+- [Reference › Auth › Accounts](/reference/auth/accounts) — Rodauth feature flags that gate SecuritySection
+- [Authentication](./authentication) — the underlying auth setup

data/docs/index.md

@@ -1,228 +1,19 @@
 ---
-layout: home
-hero:
-  name: Plutonium
-  text: Ship Rails Apps 10x Faster
-  tagline: Build production-ready Rails applications in minutes, not days. Convention-driven, fully customizable. Built for the AI era.
-  image:
-    src: /plutonium.png
-    alt: Plutonium
-  actions:
-    - theme: brand
-      text: Get Started →
-      link: /getting-started/
-    - theme: alt
-      text: GitHub
-      link: https://github.com/radioactive-labs/plutonium-core
+layout: page
+sidebar: false
+aside: false
 ---
 
-<div class="landing-content">
+<HomeHero />
 
-<section class="before-after">
-  <h2>The Old Way vs The Plutonium Way</h2>
-  <div class="comparison">
-    <div class="before">
-      <h3>Without Plutonium</h3>
-      <div class="file-tree">
-        <div class="file">app/controllers/posts_controller.rb</div>
-        <div class="file">app/controllers/comments_controller.rb</div>
-        <div class="file">app/views/posts/index.html.erb</div>
-        <div class="file">app/views/posts/show.html.erb</div>
-        <div class="file">app/views/posts/new.html.erb</div>
-        <div class="file">app/views/posts/edit.html.erb</div>
-        <div class="file">app/views/posts/_form.html.erb</div>
-        <div class="file dim">...12 more files</div>
-      </div>
-      <div class="stats">
-        <span>~200 lines</span>
-        <span>30+ minutes</span>
-        <span>No auth yet</span>
-      </div>
-    </div>
-    <div class="arrow">→</div>
-    <div class="after">
-      <h3>With Plutonium</h3>
+<HomeStopWriting />
 
-```bash
-rails g pu:res:scaffold Post \
-  title:string body:text
+<HomePillars />
 
-rails g pu:res:conn Post \
-  --dest=admin_portal
-```
+<HomeWalkthrough />
 
-  <div class="stats success">
-    <span>2 commands</span>
-    <span>30 seconds</span>
-    <span>Auth included</span>
-  </div>
-    </div>
-  </div>
-</section>
+<HomeAudienceSplit />
 
-<section class="ai-section">
-  <h2>Built for the AI Era</h2>
-  <p class="ai-intro">Plutonium is the first Rails framework designed from the ground up for AI-assisted development. Every pattern, every convention, every file structure is optimized for AI comprehension.</p>
+<HomeInTheBox />
 
-  <div class="ai-features">
-    <div class="ai-feature">
-      <div class="ai-icon">🧠</div>
-      <h3>Claude Code Skills</h3>
-      <p>20+ built-in skills teach AI assistants your app's patterns. Resources, policies, definitions, interactions - Claude understands them all.</p>
-    </div>
-    <div class="ai-feature">
-      <div class="ai-icon">⚡</div>
-      <h3>Predictable Patterns</h3>
-      <p>Convention-heavy architecture means AI can accurately predict file locations, naming, and relationships. Less hallucination, more precision.</p>
-    </div>
-    <div class="ai-feature">
-      <div class="ai-icon">🔄</div>
-      <h3>Generate & Iterate</h3>
-      <p>Tell Claude what you need. It generates the scaffold, policy, and definition. You refine. Ship in minutes what used to take hours.</p>
-    </div>
-  </div>
-
-  <div class="ai-example">
-    <div class="ai-prompt">
-      <span class="prompt-label">You say:</span>
-      <p>"Add a blog with posts and comments. Posts belong to users. Only authors can edit their posts. Add a publish action."</p>
-    </div>
-    <div class="ai-result">
-      <span class="result-label">Claude generates:</span>
-      <p>Model, migration, policy, definition, interaction, and connects it to your portal. Ready to customize.</p>
-    </div>
-  </div>
-</section>
-
-<section class="features-detailed">
-  <h2>Everything You Need, Nothing You Don't</h2>
-
-  <div class="feature-row">
-    <div class="feature-text">
-      <h3>Resources Are Your Foundation</h3>
-      <p>Just ActiveRecord. Associations, scopes, validations you already know. No new ORM to learn.</p>
-    </div>
-    <div class="feature-code">
-
-```ruby
-class Post < ApplicationRecord
-  include Plutonium::Resource::Record
-
-  belongs_to :author, class_name: "User"
-  has_many :comments
-
-  scope :published, -> { where.not(published_at: nil) }
-  scope :drafts, -> { where(published_at: nil) }
-end
-```
-
-  </div>
-  </div>
-
-  <div class="feature-row reverse">
-    <div class="feature-text">
-      <h3>Definitions Control UI</h3>
-      <p>Declare how fields render. Add search, filters, scopes. Custom actions. All in one place.</p>
-    </div>
-    <div class="feature-code">
-
-```ruby
-class PostDefinition < ResourceDefinition
-  input :body, as: :markdown
-
-  search do |scope, query|
-    scope.where("title ILIKE ?", "%#{query}%")
-  end
-
-  scope :published
-  scope :drafts
-
-  action :publish, interaction: PublishPost
-end
-```
-
-  </div>
-  </div>
-
-  <div class="feature-row">
-    <div class="feature-text">
-      <h3>Interactions Encapsulate Logic</h3>
-      <p>Complex actions become simple classes. Validated inputs. Clear outcomes. Easy to test.</p>
-    </div>
-    <div class="feature-code">
-
-```ruby
-class PublishPost < ResourceInteraction
-  attribute :resource
-  attribute :publish_at, :datetime
-
-  def execute
-    resource.published_at = publish_at
-    if resource.save
-      succeed(resource).with_message("Published!")
-    else
-      failed(resource.errors)
-    end
-  end
-end
-```
-
-  </div>
-  </div>
-
-  <div class="feature-row reverse">
-    <div class="feature-text">
-      <h3>Policies Control Access</h3>
-      <p>Define who can do what. Attribute-level permissions. Automatic scoping. No more <code>if current_user.admin?</code> scattered everywhere.</p>
-    </div>
-    <div class="feature-code">
-
-```ruby
-class PostPolicy < ResourcePolicy
-  def update?
-    record.author == user || user.admin?
-  end
-
-  def permitted_attributes_for_create
-    %i[title body]
-  end
-end
-```
-
-  </div>
-  </div>
-</section>
-
-<section class="feature-grid">
-  <div class="grid-item">
-    <div class="icon">📦</div>
-    <h3>Modular Packages</h3>
-    <p>Split your app into Feature Packages and Portals. Each isolated, testable, and reusable.</p>
-  </div>
-  <div class="grid-item">
-    <div class="icon">🔐</div>
-    <h3>Auth Built In</h3>
-    <p>Rodauth integration with login, registration, 2FA, and password reset. Ready in one command.</p>
-  </div>
-  <div class="grid-item">
-    <div class="icon">🏢</div>
-    <h3>Multi-Tenancy</h3>
-    <p>Entity scoping works out of the box. Path-based or custom strategies. Data isolation guaranteed.</p>
-  </div>
-  <div class="grid-item">
-    <div class="icon">🎨</div>
-    <h3>Fully Customizable</h3>
-    <p>Override any layer. Custom views with Phlex. Your CSS. No black boxes.</p>
-  </div>
-</section>
-
-<section class="cta-section">
-  <h2>Ready to Build Faster?</h2>
-  <p>Get a complete admin interface running in under 5 minutes.</p>
-  <div class="cta-buttons">
-    <a href="./getting-started/" class="cta-primary">Get Started</a>
-    <a href="./getting-started/tutorial/" class="cta-secondary">Follow the Tutorial</a>
-  </div>
-</section>
-
-</div>
+<HomeCta />