plutonium 0.64.0 → 0.66.0

data/docs/guides/search-filtering.md

@@ -28,7 +28,7 @@ All declared in the definition.
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  # Search box — searches title and body
+  # Search box: searches title and body
   search do |scope, query|
     scope.where("title ILIKE :q OR body ILIKE :q", q: "%#{query}%")
   end
@@ -81,7 +81,7 @@ end
 
 When an association input targets this resource, the dropdown's autocomplete calls the resource's `search` block. Same code, two surfaces.
 
-### Without a `search` block — typeahead fallback
+### Without a `search` block: typeahead fallback
 
 The framework falls back to a case-insensitive `LIKE` on the first column it finds, in priority order:
 
@@ -89,7 +89,7 @@ The framework falls back to a case-insensitive `LIKE` on the first column it fin
 2. Otherwise the first match from `[name, title, label, slug, display_name, email]`.
 3. Otherwise the relation is returned unfiltered (capped).
 
-For large tables, write an explicit `search` block — the leading-wildcard `LIKE` can't use a b-tree index. See [Reference › Resource › Query › Search](/reference/resource/query#search).
+For large tables, write an explicit `search` block: the leading-wildcard `LIKE` can't use a b-tree index. See [Reference › Resource › Query › Search](/reference/resource/query#search).
 
 ## Filters
 
@@ -154,7 +154,7 @@ class PostDefinition < ResourceDefinition
   scope :published    # uses Post.published
   scope :draft        # uses Post.draft
 
-  # Inline scope — block runs with scope as argument
+  # Inline scope: block runs with scope as argument
   scope(:recent) { |s| s.where('created_at > ?', 1.week.ago) }
 
   # Scope with controller context
@@ -206,9 +206,9 @@ Query params are namespaced under `q`:
 ## Performance tips
 
 - **Add indexes** for filtered and sorted columns.
-- **Use `.distinct`** when joining associations in search — duplicate rows otherwise.
+- **Use `.distinct`** when joining associations in search: duplicate rows otherwise.
 - **Prefer scopes over filters** for queries used often (no input parsing).
-- **`LIKE '%q%'` can't use a b-tree index** — for large tables, use `pg_search` or a trigram/GIN/full-text index.
+- **`LIKE '%q%'` can't use a b-tree index**: for large tables, use `pg_search` or a trigram/GIN/full-text index.
 
 ## Full-text search with `pg_search`
 
@@ -227,13 +227,13 @@ end
 
 ## Common issues
 
-- **Filter not showing up** — make sure the attribute is in `permitted_attributes_for_index` on the policy.
-- **Slow search on large tables** — `LIKE '%q%'` can't be indexed by a b-tree. Switch to FTS or trigram.
-- **Duplicate rows in results** — add `.distinct` when joining associations.
-- **Typeahead works on small dev tables but slows in production** — same b-tree issue. Write an explicit `search` block backed by a proper index.
+- **Filter not showing up**: make sure the attribute is in `permitted_attributes_for_index` on the policy.
+- **Slow search on large tables**: `LIKE '%q%'` can't be indexed by a b-tree. Switch to FTS or trigram.
+- **Duplicate rows in results**: add `.distinct` when joining associations.
+- **Typeahead works on small dev tables but slows in production**: same b-tree issue. Write an explicit `search` block backed by a proper index.
 
 ## Related
 
-- [Reference › Resource › Query](/reference/resource/query) — full surface
-- [Adding resources](./adding-resources) — basic resource setup
-- [Authorization](./authorization) — `permitted_attributes_for_index` gates which fields can be filtered
+- [Reference › Resource › Query](/reference/resource/query): full surface
+- [Adding resources](./adding-resources): basic resource setup
+- [Authorization](./authorization): `permitted_attributes_for_index` gates which fields can be filtered

data/docs/guides/testing.md

@@ -1,6 +1,6 @@
 # Testing
 
-Plutonium ships `Plutonium::Testing` — opt-in Minitest concerns that give your app default test coverage for resources, policies, definitions, interactions, models, nested scoping, portal access, and authentication.
+Plutonium ships `Plutonium::Testing`, opt-in Minitest concerns that give your app default test coverage for resources, policies, definitions, interactions, models, nested scoping, portal access, and authentication.
 
 ## Quick start
 
@@ -75,7 +75,7 @@ resource_tests_for ResourceClass,
   has_cents:        %i[price]                              # ResourceModel only
 ```
 
-The **portal symbol** drives path prefix, default auth strategy, and scoping expectations. The resolver walks `Rails.application.routes.routes` for the engine mount — no manual configuration.
+The **portal symbol** drives path prefix, default auth strategy, and scoping expectations. The resolver walks `Rails.application.routes.routes` for the engine mount, with no manual configuration.
 
 ## Concerns
 
@@ -84,15 +84,17 @@ The **portal symbol** drives path prefix, default auth strategy, and scoping exp
 | `ResourceCrud` | index/show/new/create/edit/update/destroy | `create_resource!`, `valid_create_params`, `valid_update_params` |
 | `ResourcePolicy` | permit? × role × action matrix + relation_scope smoke | `policy_roles`, `policy_record`, `policy_matrix` |
 | `ResourceDefinition` | definition class + defineable prop smoke | none |
-| `ResourceInteraction` | `assert_interaction_success/failure` helpers | `interaction_class`, `valid_interaction_input` |
+| `ResourceInteraction` | `assert_interaction_success/failure` helpers | none |
 | `ResourceModel` | `associated_with`, SGID, `has_cents` | `model_test_record` |
 | `NestedResource` | nested CRUD + sibling-tenant boundaries | `parent_record!`, `other_parent_record!`, `create_resource!(parent:)` |
 | `PortalAccess` | cross-portal access matrix | `login_as_role`, `portal_root_path` |
 
-Mix and match — `include` only what you want.
+Mix and match: `include` only what you want.
 
 ## Auth helpers
 
+`login_as` and friends come from `Plutonium::Testing::AuthHelpers`. Only `ResourceCrud`, `NestedResource` and `PortalAccess` include it; the policy, definition, model and interaction concerns don't. A bare `login_as(account)` takes its portal from `resource_tests_for`, so in a `PortalAccess` class (or a hand-written test that adds `include Plutonium::Testing::AuthHelpers` itself) pass `portal:` every time.
+
 ```ruby
 login_as(account)                    # uses portal from DSL
 login_as(account, portal: :admin)    # explicit override
@@ -130,7 +132,7 @@ Idempotent. Adds the require line and creates the override stub.
 |---|---|---|
 | `--portals=admin,org` | required | Emit one file per portal |
 | `--concerns=...` | `crud,policy,definition` | Subset of concerns to include |
-| `--parent=organization` | none | Wires `NestedResource` parent |
+| `--parent=organization` | none | Adds `parent:` to `resource_tests_for`; the `NestedResource` include and stubs also need `nested` in `--concerns` (`--concerns=crud,nested --parent=organization`) |
 | `--dest=main_app\|<package>` | `main_app` | Output destination |
 
 Output: `test/integration/<portal>_portal/<resource>_test.rb`.
@@ -144,16 +146,18 @@ Output: `test/integration/<portal>_portal/<resource>_test.rb`.
 
 ## Common pitfalls
 
-- **Forgotten stubs raise `NotImplementedError`** with the stub name — look for the missing method.
+- **Forgotten stubs raise `NotImplementedError`** with the stub name: look for the missing method.
 - **Portal mismatch:** `:admin` expects `AdminPortal::Engine`. Pass `path_prefix:` if your engine is named differently.
 - **Tenant leakage in stubs:** for an org portal, `create_resource!` must return a record bound to the test's `@org`.
-- **`policy_record` for tenant-scoped resources** must belong to a tenant the role can access — otherwise even allowed roles see `false`.
-- **Nested resources need `parent:` in the DSL AND a parent record** from `parent_record!`. Both are required for path interpolation.
+- **`policy_record` for tenant-scoped resources** must belong to a tenant the role can access, otherwise even allowed roles see `false`.
+- **Nested paths come from `parent_record!.id`**, so it must return the same persisted tenant on every call (e.g. `@org`). `parent:` in the DSL documents the relationship; the concern doesn't read it.
+- **Entity-scoped (`:path`) portals need two classes** for CRUD and tenant isolation, since `ResourceCrud` needs the tenant in `current_path_prefix` and `NestedResource` adds it itself. See [Reference › Testing](/reference/testing/#entity-scoped-portals-crud-tenant-isolation).
+- **`valid_update_params` is compared literally** after the PATCH: use strings for enums and leave association SGIDs out.
 - **`PortalAccess` uses `portal_access_for`**, not `resource_tests_for`. Don't mix them on the same class.
 
 ## Related
 
-- [Reference › Testing](/reference/testing/) — full DSL reference, all concern stubs, override hooks
-- [Authorization](./authorization) — write the policy this concern verifies
-- [Multi-tenancy](./multi-tenancy) — entity scoping that drives nested-resource tests
-- [Authentication](./authentication) — Rodauth setup behind the default login flow
+- [Reference › Testing](/reference/testing/): full DSL reference, all concern stubs, override hooks
+- [Authorization](./authorization): write the policy this concern verifies
+- [Multi-tenancy](./multi-tenancy): entity scoping that drives nested-resource tests
+- [Authentication](./authentication): Rodauth setup behind the default login flow

data/docs/guides/theming.md

@@ -18,11 +18,12 @@ Adapt Plutonium's defaults to match your brand: primary color, fonts, logo, dark
 
 ## 🚨 Critical
 
-- **Always register Stimulus controllers** — `registerControllers(application)`. Without it, the entire interactive layer is dead.
-- **Use `plutoniumTailwindConfig.merge`** when overriding Tailwind theme — plain object spread drops Plutonium's defaults.
-- **Tokens are CSS variables, not Tailwind keys** — `bg-[var(--pu-surface)]`, NOT `bg-pu-surface`.
-- **Dark mode is `selector`, not `class`** — toggle by adding/removing `dark` on `<html>`.
-- **Prefer `.pu-*` classes and `var(--pu-*)` tokens** over hardcoded `gray-X/dark:gray-Y` pairs — they switch with dark mode automatically.
+- **Run `pu:core:assets` before any CSS or brand-color change.** Out of the box the app serves the gem's prebuilt `plutonium.css` / `plutonium.min.js`, so app-side Tailwind classes, palette changes and token overrides have nowhere to compile. Don't hand-write the Tailwind/PostCSS pipeline.
+- **Once the app owns its JS bundle, register Stimulus controllers** with `registerControllers(application)` (`pu:core:assets` adds it). Your bundle replaces the gem's, so without it the entire interactive layer is dead.
+- **Use `plutoniumTailwindConfig.merge`** when overriding Tailwind theme: plain object spread drops Plutonium's defaults.
+- **Tokens are CSS variables, not Tailwind keys**: `bg-[var(--pu-surface)]`, NOT `bg-pu-surface`.
+- **Dark mode is `selector`, not `class`**: toggle by adding/removing `dark` on `<html>`.
+- **Style with `.pu-*` classes first, `var(--pu-*)` tokens second, raw palette pairs last.** Banners, badges, cards and buttons all have a `.pu-*` class that carries its own `.dark` rule; a hand-written `bg-warning-50 dark:bg-warning-950/30` pair duplicates that and drifts from the theme.
 
 ## Step 1: Run the assets generator
 
@@ -30,7 +31,9 @@ Adapt Plutonium's defaults to match your brand: primary color, fonts, logo, dark
 rails generate pu:core:assets
 ```
 
-This installs npm packages, creates `tailwind.config.js`, imports Plutonium CSS, registers Stimulus controllers, and points `Plutonium.configure` at your asset files. Run once per app.
+This installs npm packages, creates `tailwind.config.js` and `postcss.config.js`, imports Plutonium CSS, registers Stimulus controllers, and points `Plutonium.configure` at your asset files. Run once per app.
+
+It aborts unless `app/assets/stylesheets/application.tailwind.css` and `app/javascript/controllers/index.js` exist (an app created with `-j esbuild -c tailwind` plus Stimulus). For an app without them, run `bin/rails javascript:install:esbuild`, `css:install:tailwind` and `stimulus:install` first. See [Reference › UI › Assets › Generator](/reference/ui/assets#generator).
 
 ## Step 2: Asset configuration
 
@@ -75,6 +78,8 @@ theme: plutoniumTailwindConfig.merge(plutoniumTailwindConfig.theme, {
 })
 ```
 
+These palettes are compiled into the CSS at build time (`.pu-btn-primary` is `@apply bg-primary-600 ...`), so a brand color change needs this `merge` plus a rebuild (the `build:css` script, or the running `bin/dev` watcher). A `--pu-*` override won't recolor `primary`.
+
 ### Default palette
 
 | Color | Use |
@@ -105,7 +110,15 @@ theme: plutoniumTailwindConfig.merge(plutoniumTailwindConfig.theme, {
 }
 ```
 
-Tokens auto-switch when the user toggles dark mode. See [Reference › UI › Assets › Design tokens](/reference/ui/assets#design-tokens) for the full token catalog.
+Tokens auto-switch when the user toggles dark mode.
+
+::: warning Mirror every `:root` override in `.dark`
+Your stylesheet loads after Plutonium's and `:root` / `.dark` have equal specificity, so a token overridden only in `:root` wins in dark mode too and ships your light value there. Re-assert every customized color token in `.dark`, shadows included: `--pu-shadow-sm/md/lg` have their own dark values in `src/css/tokens.css`.
+
+Put dark values in a `.dark { ... }` block, not `@media (prefers-color-scheme: dark)`. Dark mode is the `dark` class on `<html>`, so a media query ignores the user's toggle.
+:::
+
+See [Reference › UI › Assets › Design tokens](/reference/ui/assets#design-tokens) for the full token catalog.
 
 ## Using tokens in your code
 
@@ -145,6 +158,8 @@ Pre-styled ready-to-use components:
 | Buttons | `.pu-btn`, `.pu-btn-md/-sm/-xs`, `.pu-btn-primary/-secondary/-danger/-success/-warning/-info/-accent`, `.pu-btn-ghost/-outline`, `.pu-btn-soft-*` |
 | Inputs | `.pu-input/-invalid/-valid`, `.pu-label/-required`, `.pu-hint`, `.pu-error`, `.pu-checkbox` |
 | Cards | `.pu-card`, `.pu-card-body`, `.pu-panel-header`, `.pu-panel-title`, `.pu-panel-description` |
+| Badges | `.pu-badge`, `.pu-badge-neutral/-primary/-secondary/-success/-danger/-warning/-info/-accent` |
+| Alerts (inline banners) | `.pu-alert`, `.pu-alert-success/-warning/-danger/-info`, `.pu-alert-message`, `.pu-alert-close` |
 | Tables | `.pu-table-wrapper`, `.pu-table`, `-header`, `-header-cell`, `-body-row`, `-body-row-selected`, `-body-cell`, `.pu-selection-cell` |
 | Toolbars / empty states | `.pu-toolbar`, `-text`, `-actions`; `.pu-empty-state`, `-icon`, `-title`, `-description` |
 
@@ -184,7 +199,7 @@ end
 ```
 
 ::: warning Always `super.merge(...)`
-Don't replace the theme wholesale — Plutonium's defaults handle invalid states, focus rings, and dark mode. `super.merge` keeps them.
+Don't replace the theme wholesale (Plutonium's defaults handle invalid states, focus rings, and dark mode). `super.merge` keeps them.
 :::
 
 Full theme key catalog: [Reference › UI › Assets › Phlexi component themes](/reference/ui/assets#phlexi-component-themes).
@@ -225,7 +240,7 @@ document.documentElement.classList.toggle('dark')
 
 If you've overridden tokens via `:root` and `.dark`, both modes Just Work.
 
-## Per-portal chrome — eject the shell
+## Per-portal chrome: eject the shell
 
 For per-portal headers/sidebars:
 
@@ -245,7 +260,7 @@ Copies `layouts/resource.html.erb` for layout-level edits.
 
 ```ruby
 Plutonium.configure do |config|
-  config.shell = :modern     # default — topbar + icon rail
+  config.shell = :modern     # default: topbar + icon rail
   # config.shell = :classic  # legacy header + sidebar (only when upgrading)
 end
 ```
@@ -268,13 +283,13 @@ Bundled controllers: `color-mode`, `form` (pre-submit), `nested-resource-form-fi
 
 ## Common issues
 
-- **Stimulus controllers silently fail** — if `registerControllers(application)` isn't called, the entire UI's interactive layer is dead (color-mode toggle, slim-select, flatpickr, easymde, pre-submit). No error — just no behavior.
-- **`plutoniumTailwindConfig.merge` is mandatory** — plain spread drops defaults silently.
-- **Tokens not switching in dark mode** — you used `bg-pu-surface` instead of `bg-[var(--pu-surface)]`. Tokens are CSS variables, not Tailwind keys.
-- **`.pu-btn` styles not applying** — check that Plutonium CSS is imported BEFORE Tailwind: `@import "gem:plutonium/src/css/plutonium.css";` then `@import "tailwindcss";`.
+- **Stimulus controllers silently fail**: once the app serves its own JS bundle, if `registerControllers(application)` isn't called, the entire UI's interactive layer is dead (color-mode toggle, slim-select, flatpickr, easymde, pre-submit). No error: just no behavior.
+- **`plutoniumTailwindConfig.merge` is mandatory**: plain spread drops defaults silently.
+- **Tokens not switching in dark mode**: you used `bg-pu-surface` instead of `bg-[var(--pu-surface)]`. Tokens are CSS variables, not Tailwind keys.
+- **`.pu-btn` styles not applying**: check that Plutonium CSS is imported BEFORE Tailwind: `@import "gem:plutonium/src/css/plutonium.css";` then `@import "tailwindcss";`.
 
 ## Related
 
-- [Reference › UI › Assets](/reference/ui/assets) — full Tailwind / Stimulus / design tokens / component classes surface
-- [Reference › UI › Layouts](/reference/ui/layouts) — shell, eject, ResourceLayout
-- [Reference › UI › Forms › Theming](/reference/ui/forms#theming) — Form theme keys
+- [Reference › UI › Assets](/reference/ui/assets): full Tailwind / Stimulus / design tokens / component classes surface
+- [Reference › UI › Layouts](/reference/ui/layouts): shell, eject, ResourceLayout
+- [Reference › UI › Forms › Theming](/reference/ui/forms#theming): Form theme keys

data/docs/guides/troubleshooting.md

@@ -79,6 +79,6 @@ If you encounter an issue not covered here, please [open an issue](https://githu
 
 - [Nested resources](./nested-resources)
 - [Adding resources](./adding-resources)
-- [Reference › Behavior › Controllers](/reference/behavior/controllers) — `controller_for`, `resource_url_for`, `current_parent`
-- [Reference › Tenancy › Nested resources](/reference/tenancy/nested-resources) — nested URL generation
+- [Reference › Behavior › Controllers](/reference/behavior/controllers): `controller_for`, `resource_url_for`, `current_parent`
+- [Reference › Tenancy › Nested resources](/reference/tenancy/nested-resources): nested URL generation
 - [Rails Inflections](https://api.rubyonrails.org/classes/ActiveSupport/Inflector/Inflections.html)

data/docs/guides/user-invites.md

@@ -8,7 +8,7 @@ An admin enters an email, the user gets an invite link, clicks it, signs up (or
 
 ## Prerequisites
 
-You need a user model, an entity model, and a membership model. The fastest path is `pu:saas:setup` — it creates all three and runs `pu:invites:install` automatically:
+You need a user model, an entity model, and a membership model. The fastest path is `pu:saas:setup`: it creates all three and runs `pu:invites:install` automatically:
 
 ```bash
 rails g pu:saas:setup --user Customer --entity Organization
@@ -43,7 +43,7 @@ rails g pu:invites:install \
 | `--enforce-domain` | `false` | Require email domain to match entity |
 
 ::: info Roles come from the membership model
-`pu:invites:install` reads the role list from the membership model's `enum :role` — it does not accept a `--roles=` flag. Define roles when you generate the membership model (`pu:saas:membership --roles=...`), or edit the enum directly. **Index 0 is the most privileged** (typically `owner`); the invite interaction excludes `owner` from selectable choices and defaults new invitees to the second role.
+`pu:invites:install` reads the role list from the membership model's `enum :role`; it does not accept a `--roles=` flag. Define roles when you generate the membership model (`pu:saas:membership --roles=...`), or edit the enum directly. **Index 0 is the most privileged** (typically `owner`); the invite interaction excludes `owner` from selectable choices and defaults new invitees to the second role.
 :::
 
 ### 2. Migrate
@@ -112,7 +112,7 @@ Users land on `/welcome` where pending invites are shown. Including `Plutonium::
 include Plutonium::Invites::PendingInviteCheck
 ```
 
-## Invitables — app models notified on acceptance
+## Invitables: app models notified on acceptance
 
 An invitable is a model that gets notified when its invitation is accepted. Examples: `Tenant`, `TeamMember`, `ProjectCollaborator`.
 
@@ -137,7 +137,7 @@ end
 ```
 
 ::: warning Without `on_invite_accepted`
-The invitable never learns about the new user — the invite is consumed but your app doesn't update its state.
+The invitable never learns about the new user: the invite is consumed but your app doesn't update its state.
 :::
 
 ## Multiple invite flows in one app
@@ -158,7 +158,7 @@ rails g pu:invites:install \
 
 Each invocation creates an independent flow: model, controller, route, helper all named for the invite-model.
 
-The shared `Invites::WelcomeController` accumulates each new class into its `invite_classes` array — `pending_invite` checks all flows in priority order (first-match wins).
+The shared `Invites::WelcomeController` accumulates each new class into its `invite_classes` array; `pending_invite` checks all flows in priority order (first-match wins).
 
 See [Reference › Tenancy › Invites › Multiple invite flows](/reference/tenancy/invites#multiple-invite-flows).
 
@@ -222,27 +222,27 @@ entity.user_invites.pending    # list pending
 
 ## Security
 
-- **Token security** — `SecureRandom.urlsafe_base64(32)` — 256 bits, URL-safe. Stored hashed, raw token shown only at creation.
-- **Email validation** — `enforce_email?` is `true` by default. The accepting user's email must match the invited email — prevents account hijacking via invite forwarding.
-- **Rate limiting** — use Rack::Attack or similar to throttle invite creation per admin and acceptance attempts per IP.
+- **Token security**: `SecureRandom.urlsafe_base64(32)`, 256 bits, URL-safe. Stored hashed, raw token shown only at creation.
+- **Email validation**: `enforce_email?` is `true` by default. The accepting user's email must match the invited email; this prevents account hijacking via invite forwarding.
+- **Rate limiting**: use Rack::Attack or similar to throttle invite creation per admin and acceptance attempts per IP.
 
 ::: danger Don't disable enforce_email?
 ```ruby
 def enforce_email? = false   # ← only if you fully understand the trade-off
 ```
-Without this, anyone with the token can sign up — defeats the purpose of an invitation system.
+Without this, anyone with the token can sign up, which defeats the purpose of an invitation system.
 :::
 
 ## Common issues
 
-- **"Invitation not found or expired"** — token expired (default 1 week), invite cancelled, or no longer `pending`.
-- **Email mismatch error** — the accepting user's email doesn't match the invited email. This is by design (security).
-- **Rodauth redirect after login doesn't go to `/welcome`** — check `login_redirect "/welcome"` in the rodauth plugin's `configure` block.
-- **`on_invite_accepted` not called** — ensure the invitable model `include Plutonium::Invites::Concerns::Invitable` and defines `on_invite_accepted`.
+- **"Invitation not found or expired"**: token expired (default 1 week), invite cancelled, or no longer `pending`.
+- **Email mismatch error**: the accepting user's email doesn't match the invited email. This is by design (security).
+- **Rodauth redirect after login doesn't go to `/welcome`**: check `login_redirect "/welcome"` in the rodauth plugin's `configure` block.
+- **`on_invite_accepted` not called**: ensure the invitable model `include Plutonium::Invites::Concerns::Invitable` and defines `on_invite_accepted`.
 
 ## Related
 
-- [Reference › Tenancy › Invites](/reference/tenancy/invites) — full surface, multi-flow apps, customization
-- [Multi-tenancy](./multi-tenancy) — entity scoping (invites are entity-scoped automatically)
-- [Authentication](./authentication) — Rodauth setup
-- [User profile](./user-profile) — account-settings page
+- [Reference › Tenancy › Invites](/reference/tenancy/invites): full surface, multi-flow apps, customization
+- [Multi-tenancy](./multi-tenancy): entity scoping (invites are entity-scoped automatically)
+- [Authentication](./authentication): Rodauth setup
+- [User profile](./user-profile): account-settings page

data/docs/guides/user-profile.md

@@ -8,15 +8,15 @@ A `/profile` URL that shows the user's personal fields plus a "Security" section
 
 ## 🚨 Critical
 
-- **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.
+- **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 there is no `/profile` route, and `profile_url` stays `nil` so the user menu has no Profile link.
+- **A user without a profile row is fine.** `profile_url` sends them to the new-profile form. Creating the row up front is optional (see step 4).
 
 The show page renders the user's fields, then the **Security Settings** block with Rodauth-backed actions:
 
 ![User profile show page with SecuritySection](/images/guides/user-profile-show.png)
 
-Editing produces a regular Plutonium form — same form generator the rest of your resources use:
+Editing produces a regular Plutonium form, same form generator the rest of your resources use:
 
 ![User profile edit form](/images/guides/user-profile-edit.png)
 
@@ -28,7 +28,7 @@ rails g pu:profile:setup date_of_birth:date bio:text \
   --portal=competition_portal
 ```
 
-`pu:profile:setup` is a meta-generator — runs `pu:profile:install` + `pu:profile:conn` in one shot.
+`pu:profile:setup` is a meta-generator: runs `pu:profile:install` + `pu:profile:conn` in one shot.
 
 ## Step-by-step
 
@@ -64,31 +64,38 @@ rails db:prepare
 rails g pu:profile:conn --dest=customer_portal
 ```
 
-This registers the profile as a **singular** resource — exposes `/profile` (no `:id`) and the `profile_url` helper.
+This registers the profile as a **singular** resource: exposes `/profile` (no `:id`) and the `profile_url` helper.
 
-### 4. Add the auto-create callback
+It also generates a portal policy scoped to the current user: `create?` is `user.profile.nil?` (one profile per user), `update?` is `true`, and `destroy?` is `false`. The controller sets `user` from `current_user`, so `:user` is not a permitted attribute.
+
+::: tip Profile can't be edited?
+Policies generated by older versions of `pu:profile:conn` lack `update?`, so it falls back to `create?` and the profile becomes read-only once it exists. Add `def update? = true` to the portal's profile policy.
+:::
+
+### 4. (Optional) Create the row up front
+
+Without a profile row, the first visit to the profile is the "create profile" form, and the Security section appears once it is saved. To land users on the show page from the first click, create the row when the user is created:
 
 ```ruby
-# app/models/user.rb (modified by pu:profile:install)
+# app/models/user.rb (has_one added by pu:profile:install)
 class User < ApplicationRecord
   has_one :profile, class_name: "UserProfile", dependent: :destroy
 
-  after_create :create_profile!
-
-  private
-  def create_profile! = create_profile
+  after_create :create_profile
 end
 ```
 
-For existing users at migration time:
+and backfill existing users:
 
 ```bash
-rails runner "User.find_each(&:create_profile)"
+rails runner "User.find_each { |u| u.profile || u.create_profile }"
 ```
 
+Skip this when the profile has required fields the user must fill in, or when other code already creates profiles.
+
 ## What you get
 
-The generated definition injects a custom `ShowPage` that renders `SecuritySection` — dynamically lists Rodauth security links based on which features are enabled:
+The generated definition injects a custom `ShowPage` that renders `SecuritySection`: dynamically lists Rodauth security links based on which features are enabled:
 
 | Feature enabled | Link rendered |
 |---|---|
@@ -100,15 +107,34 @@ The generated definition injects a custom `ShowPage` that renders `SecuritySecti
 | `active_sessions` | Active Sessions |
 | `close_account` | Close Account |
 
-If a feature isn't enabled, its link doesn't render — no configuration needed.
+If a feature isn't enabled, its link doesn't render; no configuration needed.
 
 ## Linking to the profile
 
+The topbar avatar menu already shows a "Profile" entry once `pu:profile:conn` has run. `Plutonium::Auth::Rodauth` defines `profile_url` as `nil`, and the generator overrides it in the portal's controller concern. To link from your own views:
+
 ```ruby
-link_to("Profile", profile_url) if respond_to?(:profile_url)
+link_to("Profile", profile_url) if profile_url
+```
+
+## Account features on the profile page
+
+Per-user settings that aren't profile fields (API tokens, connected accounts, notification preferences) belong on the profile page. Link them from the same `ShowPage` hook, next to `SecuritySection`:
+
+```ruby
+class ShowPage < ShowPage
+  private
+
+  def render_after_content
+    render Plutonium::Profile::SecuritySection.new
+    div(class: "mt-8") do
+      a(href: resource_url_for(ApiToken), class: "font-medium text-[var(--pu-text)] hover:underline") { "API tokens" }
+    end
+  end
+end
 ```
 
-The `respond_to?` guard is defensive — only portals that ran `pu:profile:conn` have the helper.
+See [Reference › Auth › Profile](/reference/auth/profile#account-features-on-the-profile-page) for scoping such a resource to the user.
 
 ## Customizing the definition
 
@@ -152,12 +178,13 @@ rails g pu:profile:conn StaffUserProfile --dest=admin_portal
 
 ## Common issues
 
-- **`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.
+- **First visit shows a "create profile" form.** The user has no profile row yet. That's expected; see step 4 if they should land on the show page.
+- **Profile is read-only after creation.** The policy predates the generated `update?`. Add `def update? = true`.
+- **No Profile link in the user menu.** The profile isn't connected to this portal, so `profile_url` returns `nil`. 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.
 
 ## Related
 
-- [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
+- [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