plutonium 0.51.0 → 0.52.0

data/docs/reference/app/generators.md

@@ -185,7 +185,7 @@ rails rodauth_admin:create[admin@example.com,password123]
 
 ```bash
 rails g pu:saas:setup --user Customer --entity Organization
-rails g pu:saas:setup --user Customer --entity Organization --roles=member,admin
+rails g pu:saas:setup --user Customer --entity Organization --roles=admin,member
 rails g pu:saas:setup --user Customer --entity Organization --no-allow-signup
 rails g pu:saas:setup --user Customer --entity Organization \
   --user-attributes=name:string --entity-attributes=slug:string
@@ -216,7 +216,7 @@ For when you don't want the full `pu:saas:setup` meta-generator:
 ```bash
 rails g pu:saas:user Customer
 rails g pu:saas:entity Organization --extra-attributes=slug:string
-rails g pu:saas:membership --user Customer --entity Organization --roles=member,admin
+rails g pu:saas:membership --user Customer --entity Organization --roles=admin,member
 rails g pu:saas:portal customer --entity Organization
 rails g pu:saas:welcome --user Customer --entity Organization
 ```
@@ -305,10 +305,10 @@ rails g pu:invites:install --entity-model=Organization --user-model=Customer --i
 | `--entity-model=NAME` | `Entity` | Entity model name |
 | `--user-model=NAME` | `User` | User model name |
 | `--invite-model=NAME` | `<EntityModel><UserModel>Invite` | Invite class name |
-| `--membership-model=NAME` | `EntityUser` | Membership join model |
-| `--roles` | `member,admin` | Comma-separated |
+| `--membership-model=NAME` | `EntityUser` | Membership join model (must already exist; roles read from its `enum :role`) |
 | `--rodauth=NAME` | `user` | Rodauth configuration for signup |
 | `--enforce-domain` | `false` | Require email domain to match entity |
+| `--dest=PACKAGE` | `main_app` | Package where the entity model lives (controls where `invite_user_interaction.rb` is generated) |
 
 Multiple invite flows are supported — run `pu:invites:install` once per flow.
 

data/docs/reference/auth/accounts.md

@@ -14,7 +14,6 @@ rails generate pu:rodauth:account user [options]
 |---|---|
 | `--defaults` | Enables login, logout, remember, password reset |
 | `--kitchen_sink` | Enables ALL features |
-| `--primary` | Mark as primary account (no URL prefix) |
 | `--no-mails` | Skip mailer setup |
 | `--argon2` | Use Argon2 instead of bcrypt |
 | `--api_only` | JSON API only (no sessions) |
@@ -50,9 +49,6 @@ rails generate pu:rodauth:account user [options]
 # Basic account
 rails g pu:rodauth:account user
 
-# Primary account (no URL prefix)
-rails g pu:rodauth:account user --primary
-
 # With 2FA
 rails g pu:rodauth:account user --otp --recovery_codes
 
@@ -84,12 +80,15 @@ rails g pu:rodauth:admin admin --extra-attributes=name:string,department:string
 enum :role, super_admin: 0, admin: 1
 ```
 
-Rake task for direct admin creation:
+Rake task for direct admin creation (generated alongside the account — namespace is `rodauth`, task name is the account name):
 
 ```bash
-rails rodauth_admin:create[admin@example.com,password123]
+EMAIL=admin@example.com rails rodauth:admin
+# (run without EMAIL to be prompted)
 ```
 
+The task creates the account and triggers a verification email; the admin sets their own password via that flow. No password is passed on the command line.
+
 ## SaaS setup — `pu:saas:setup` (meta-generator)
 
 Creates the User + Entity + Membership trio AND runs:
@@ -105,7 +104,7 @@ After `pu:saas:setup` runs, don't separately run `pu:saas:portal`, `pu:profile:s
 
 ```bash
 rails g pu:saas:setup --user Customer --entity Organization
-rails g pu:saas:setup --user Customer --entity Organization --roles=member,admin
+rails g pu:saas:setup --user Customer --entity Organization --roles=admin,member
 rails g pu:saas:setup --user Customer --entity Organization --no-allow-signup
 rails g pu:saas:setup --user Customer --entity Organization \
   --user-attributes=name:string --entity-attributes=slug:string

data/docs/reference/auth/index.md

@@ -43,7 +43,7 @@ class AdminController < PlutoniumController
 end
 ```
 
-`Plutonium::Auth::Rodauth(:name)` exposes `current_user`, `logout_url`, and `rodauth` in the controller.
+`Plutonium::Auth::Rodauth(:name)` exposes `current_user`, `logout_url`, `profile_url`, and `rodauth` in the controller (all available as helper methods in views too).
 
 For portal wiring (`AdminPortal::Concerns::Controller`), see [App › Portals](/reference/app/portals#controller-concern-auth).
 

data/docs/reference/behavior/policies.md

@@ -11,7 +11,7 @@ Authorization for resources. Built on [ActionPolicy](https://actionpolicy.evilma
 
 - **`create?` and `read?` default to `false`.** You MUST override them explicitly. Everything else (`update?`, `destroy?`, `index?`, `show?`, …) derives from one of those.
 - **`permitted_attributes_for_*` must be explicit in production.** Dev auto-detects; production raises.
-- **`relation_scope` must call `default_relation_scope(relation)` explicitly** — never `super`. Bypassing it triggers `verify_default_relation_scope_applied!`.
+- **`relation_scope` must end up calling `default_relation_scope(relation)` somewhere in the chain.** Prefer calling it explicitly in your override. `super` is fine when extending a parent policy (e.g., a package base) that itself calls it. The runtime check verifies it was hit somewhere — not in this specific class.
 - **For `has_cents` fields, use the virtual name** (`:price`), NEVER `:price_cents`.
 - **Don't put `*_attributes` hashes in `permitted_attributes_for_*`.** Nested forms are extracted from the form definition, not the policy. List the association name (`:variants`) and the `nested_input` in the definition handles the rest.
 - **Custom action ⇒ policy method.** `action :publish` needs `def publish?`. Undefined methods return `false` → action silently disappears.

data/docs/reference/index.md

@@ -1,56 +1,68 @@
-# Reference
+---
+layout: page
+sidebar: false
+aside: false
+---
 
-Concept-by-concept API documentation. For task-oriented walkthroughs, see [Guides](/guides/).
-
-## The seven areas
-
-### [App](/reference/app/)
-Installation, packages (feature + portal), portal engines, mounting, route registration (including singular and custom routes), connecting resources via `pu:res:conn`, full generator catalog.
-
-### [Resource](/reference/resource/)
-The four-layer resource — model, definition, query, actions. `pu:res:scaffold` field-type syntax, `has_cents`, SGID, URL routing, definition DSL (fields, inputs, displays, columns), page chrome, metadata panel, index views (table & grid), search, filters, scopes, sorting, custom + bulk actions.
-
-### [Behavior](/reference/behavior/)
-Controllers, policies, interactions. Controller hooks (redirect, params, presentation), policy action methods and `permitted_attributes_for_*`, `permitted_associations`, `relation_scope`, interaction structure, outcomes, chaining, URL generation.
-
-### [UI](/reference/ui/)
-Pages, forms, displays, tables, components, layouts, assets. Custom page classes, form field builders, association inputs (typeahead + inline `+`), built-in component kit, custom Phlex components, the shell, design tokens, `.pu-*` component classes, Phlexi themes.
-
-### [Auth](/reference/auth/)
-Rodauth installation, account types (basic / admin / SaaS), profile resource with the SecuritySection component.
-
-### [Tenancy](/reference/tenancy/)
-Multi-tenant entity scoping (`associated_with`, `default_relation_scope`, three model shapes), nested resources (parent/child routes, scoping), user invitations.
-
-### [Testing](/reference/testing/)
-The `Plutonium::Testing::*` concerns — CRUD, policy matrix, definition smoke tests, model concerns, nested resources, portal access, interaction outcomes.
-
-## Quick reference
-
-| I need to… | See |
-|---|---|
-| Install Plutonium | [App › Index](/reference/app/) |
-| Run a generator | [App › Generators](/reference/app/generators) |
-| Create a portal | [App › Portals](/reference/app/portals) |
-| Scaffold a resource | [App › Generators › `pu:res:scaffold`](/reference/app/generators#pu-res-scaffold) |
-| Configure form fields | [Resource › Definition](/reference/resource/definition) |
-| Add search / filters | [Resource › Query](/reference/resource/query) |
-| Add custom buttons / bulk actions | [Resource › Actions](/reference/resource/actions) |
-| Override CRUD redirects / params | [Behavior › Controllers](/reference/behavior/controllers) |
-| Control who can see what | [Behavior › Policies](/reference/behavior/policies) |
-| Write business logic | [Behavior › Interactions](/reference/behavior/interactions) |
-| Customize a page | [UI › Pages](/reference/ui/pages) |
-| Customize a form | [UI › Forms](/reference/ui/forms) |
-| Style the UI | [UI › Assets](/reference/ui/assets) |
-| Set up Rodauth | [Auth › Accounts](/reference/auth/accounts) |
-| Add a profile page | [Auth › Profile](/reference/auth/profile) |
-| Scope to a tenant | [Tenancy › Entity scoping](/reference/tenancy/entity-scoping) |
-| Wire user invitations | [Tenancy › Invites](/reference/tenancy/invites) |
-| Test a resource | [Testing](/reference/testing/) |
-
-## Reading this reference
-
-- **🚨 Critical blocks** at the top of each page surface the "you'll regret this" rules. Skim them even if you're skimming the rest.
-- **Option / DSL tables** are designed for scanning — find your option name without reading prose.
-- **Cross-references** use VitePress relative paths. If a link points somewhere that doesn't exist yet, it's a known gap.
-- **Concrete decision rules** ("use X when…, Y when…") sit alongside the option references. Reach for them when in doubt.
+<SectionLanding
+  eyebrow="Reference"
+  title="Every API, in one place."
+  lede="The full surface area of Plutonium — controllers, policies, definitions, fields, interactions, generators."
+  mode="categorized"
+  :rail="[
+    { group: 'App', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/app/' },
+      { name: 'Packages', link: '/plutonium-core/reference/app/packages' },
+      { name: 'Portals', link: '/plutonium-core/reference/app/portals' },
+      { name: 'Generators', link: '/plutonium-core/reference/app/generators' },
+    ]},
+    { group: 'Resource', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/resource/' },
+      { name: 'Model', link: '/plutonium-core/reference/resource/model' },
+      { name: 'Definition', link: '/plutonium-core/reference/resource/definition' },
+      { name: 'Query', link: '/plutonium-core/reference/resource/query' },
+      { name: 'Actions', link: '/plutonium-core/reference/resource/actions' },
+    ]},
+    { group: 'Behavior', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/behavior/' },
+      { name: 'Controllers', link: '/plutonium-core/reference/behavior/controllers' },
+      { name: 'Policies', link: '/plutonium-core/reference/behavior/policies' },
+      { name: 'Interactions', link: '/plutonium-core/reference/behavior/interactions' },
+    ]},
+    { group: 'UI', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/ui/' },
+      { name: 'Pages', link: '/plutonium-core/reference/ui/pages' },
+      { name: 'Forms', link: '/plutonium-core/reference/ui/forms' },
+      { name: 'Displays', link: '/plutonium-core/reference/ui/displays' },
+      { name: 'Tables', link: '/plutonium-core/reference/ui/tables' },
+      { name: 'Components', link: '/plutonium-core/reference/ui/components' },
+      { name: 'Layouts', link: '/plutonium-core/reference/ui/layouts' },
+      { name: 'Assets', link: '/plutonium-core/reference/ui/assets' },
+    ]},
+    { group: 'Auth', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/auth/' },
+      { name: 'Accounts', link: '/plutonium-core/reference/auth/accounts' },
+      { name: 'Profile', link: '/plutonium-core/reference/auth/profile' },
+    ]},
+    { group: 'Tenancy', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/tenancy/' },
+      { name: 'Entity scoping', link: '/plutonium-core/reference/tenancy/entity-scoping' },
+      { name: 'Nested resources', link: '/plutonium-core/reference/tenancy/nested-resources' },
+      { name: 'Invites', link: '/plutonium-core/reference/tenancy/invites' },
+    ]},
+    { group: 'Testing', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/testing/' },
+    ]},
+  ]"
+  :sidebar="[
+    { heading: 'Learning?', items: [
+      { label: 'Tutorial', href: '/plutonium-core/getting-started/tutorial/' },
+    ]},
+    { heading: 'Solving a problem?', items: [
+      { label: 'Guides', href: '/plutonium-core/guides/' },
+    ]},
+    { heading: 'Need help?', items: [
+      { label: 'GitHub Discussions', href: 'https://github.com/radioactive-labs/plutonium-core/discussions' },
+    ]},
+  ]"
+/>

data/docs/reference/resource/definition.md

@@ -111,7 +111,7 @@ end
 
 ### Display types (show / index)
 
-`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`
+`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`, `:color`
 
 ## Field options
 

data/docs/reference/tenancy/entity-scoping.md

@@ -239,10 +239,17 @@ The strategy symbol must match a method name on the controller concern.
 
 ### Custom param key
 
-When the param name differs from the entity model name:
+The default `param_key` derives from the entity class — `<singular_route_key>_scoped` — to avoid collisions with a `belongs_to :organization` on child models. So `scope_to_entity Organization` produces routes like `/organization_scoped/:organization_scoped_id/posts`. Override when you want a cleaner URL:
 
 ```ruby
 scope_to_entity Organization, strategy: :path, param_key: :org_id
+# → /org_id/:org_id/posts
+```
+
+Pair with `route_key:` to control the path segment as well:
+
+```ruby
+scope_to_entity Organization, strategy: :path, param_key: :org_id, route_key: :orgs
 # → /orgs/:org_id/posts
 ```
 

data/docs/reference/tenancy/index.md

@@ -20,7 +20,7 @@ Configure the portal once. The policy and model conventions then carry tenancy a
 
 ## 🚨 Critical (applies to all three sub-pages)
 
-- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins triggers `verify_default_relation_scope_applied!`. Always call `default_relation_scope(relation)` explicitly — not `super`.
+- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins triggers `verify_default_relation_scope_applied!`. Make sure `default_relation_scope(relation)` is called somewhere in the chain — explicitly here, or via `super` to a parent policy (e.g., a package base) that calls it.
 - **Always declare an association path from the model to the entity.** Direct `belongs_to`, `has_one :through`, or a custom `associated_with_<entity>` scope. If `associated_with` can't resolve, fix the **model**, not the policy.
 - **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.
 - **One level of nesting only.** Grandparent → parent → child nested routes are NOT supported. Use top-level routes for deeper relationships.

data/docs/reference/tenancy/invites.md

@@ -36,19 +36,21 @@ rails generate pu:invites:install
 | `--entity-model=NAME` | `Entity` | Entity model name |
 | `--user-model=NAME` | `User` | User model name |
 | `--invite-model=NAME` | `<EntityModel><UserModel>Invite` | Invite class name (omit for single-flow apps) |
-| `--membership-model=NAME` | `EntityUser` | Membership join model |
-| `--roles` | `member,admin` | Comma-separated roles |
+| `--membership-model=NAME` | `EntityUser` | Membership join model (must already exist) |
 | `--rodauth=NAME` | `user` | Rodauth configuration for signup |
 | `--enforce-domain` | `false` | Require invited email domain to match entity domain |
 
+::: info Roles come from the membership model
+The role list is read from the membership model's `enum :role` — there is no `--roles=` flag on `pu:invites:install`. Set roles when generating the membership model (`pu:saas:membership --roles=...`) or edit its enum directly. **Index 0 is the most privileged** (typically `owner`, which the invite UI excludes from selectable choices); new invitees default to the second role.
+:::
+
 Example with custom models:
 
 ```bash
 rails g pu:invites:install \
   --entity-model=Organization \
   --user-model=Customer \
-  --membership-model=OrganizationMember \
-  --roles=member,manager,admin
+  --membership-model=OrganizationMember
 ```
 
 After install:
@@ -317,10 +319,15 @@ Requires the invited email's domain to match the entity's domain.
 
 ### Custom roles
 
+Roles are defined on the membership model, not on the invites generator. Set them at membership generation time (ordering matters — **index 0 is the most privileged**, typically `owner`):
+
 ```bash
-rails g pu:invites:install --roles=viewer,editor,admin,owner
+rails g pu:saas:membership --user Customer --entity Organization --roles=admin,editor,viewer
+# → enum :role, { owner: 0, admin: 1, editor: 2, viewer: 3 }  (owner is auto-prepended)
 ```
 
+Or edit `enum :role` on the existing membership model directly. Then run `pu:invites:install`.
+
 ### Custom expiration
 
 Override on the model:

data/docs/reference/ui/tables.md

@@ -8,8 +8,9 @@ The index page's table rendering. Override the `Table` nested class in your defi
 class PostDefinition < ResourceDefinition
   class Table < Table
     def view_template
-      render_search_bar
-      render_scopes_bar
+      render_toolbar         # search + view toggle + filter buttons
+      render_scopes_pills    # scope chips (if any scopes defined)
+      render_filter_pills    # active-filter chips
 
       if collection.empty?
         render_empty_card
@@ -20,6 +21,7 @@ class PostDefinition < ResourceDefinition
         end
       end
 
+      render_bulk_actions_toolbar
       render_footer
     end
   end
@@ -30,8 +32,10 @@ end
 
 | Method | Purpose |
 |---|---|
-| `render_search_bar` | Toolbar search input |
-| `render_scopes_bar` | Quick-filter scope buttons |
+| `render_toolbar` | Search input + view toggle + filter button |
+| `render_scopes_pills` | Quick-filter scope chips (only renders if scopes defined) |
+| `render_filter_pills` | Active-filter chips |
+| `render_bulk_actions_toolbar` | Bulk action bar (only renders when rows selected) |
 | `render_table` | Default table rendering |
 | `render_empty_card` | Empty state |
 | `render_footer` | Pagination |