plutonium 0.64.0 → 0.66.0

data/docs/reference/app/packages.md

@@ -1,6 +1,6 @@
 # Packages
 
-Plutonium apps are organized into **packages** — Rails engines with stricter conventions. Two flavors, hard split:
+Plutonium apps are organized into **packages**: Rails engines with stricter conventions. Two flavors, hard split:
 
 | Type | Purpose | Generator | Examples |
 |---|---|---|---|
@@ -60,7 +60,7 @@ Each feature package gets its own base classes:
 - `Blogging::ResourceDefinition`
 - `Blogging::ResourceInteraction`
 
-These inherit from the main app's base classes — extend them for package-wide defaults.
+These inherit from the main app's base classes; extend them for package-wide defaults.
 
 ### Creating resources inside a feature package
 
@@ -111,13 +111,13 @@ This is loaded from `config/application.rb`. Migrations from all packages are pi
 
 ## When to use which
 
-**Feature packages** — domain logic that:
+**Feature packages**: domain logic that:
 
 - Could be reused across multiple portals (admin and customer both edit `Blogging::Post`).
 - Has no inherent UI / auth (it's just behavior).
 - You want isolated from other domains (`billing` should not depend on `blogging`).
 
-**Portal packages** — user-facing surfaces that:
+**Portal packages**: user-facing surfaces that:
 
 - Have a specific auth flow (admin vs customer vs public).
 - Render different views of the same underlying resources.
@@ -137,10 +137,10 @@ packages/
     └── controllers, views, routes
 ```
 
-The portals expose the features. A single feature can be exposed by multiple portals — usually with different policies and definitions per portal.
+The portals expose the features. A single feature can be exposed by multiple portals, usually with different policies and definitions per portal.
 
 ## Related
 
-- [Portals](./portals) — portal-specific configuration (mounting, auth, route registration)
-- [Generators](./generators) — `pu:pkg:package` and `pu:pkg:portal` flags
-- [Guide: Creating Packages](/guides/creating-packages) — task-oriented walkthrough
+- [Portals](./portals): portal-specific configuration (mounting, auth, route registration)
+- [Generators](./generators): `pu:pkg:package` and `pu:pkg:portal` flags
+- [Guide: Creating Packages](/guides/creating-packages): task-oriented walkthrough

data/docs/reference/app/portals.md

@@ -5,7 +5,7 @@ A portal is a Rails engine mixing in `Plutonium::Portal::Engine`. It defines its
 ## 🚨 Critical
 
 - **Use `pu:pkg:portal` for everything.** Never hand-write the engine file, controller concern, or layout.
-- **Pass `--auth=<name>`, `--public`, or `--byo`** for unattended runs — without one of these flags, the generator prompts.
+- **Pass `--auth=<name>`, `--public`, or `--byo`** for unattended runs; without one of these flags, the generator prompts.
 - **Always connect resources with `pu:res:conn`.** Until connected, a resource has no portal routes and is invisible.
 - **For custom routes on a registered resource, pass `as:`.** Without it, `resource_url_for` can't build URLs.
 
@@ -20,7 +20,7 @@ rails g pu:pkg:portal <name>
 | Option | Description |
 |---|---|
 | `--auth=NAME` | Rodauth account to authenticate with (e.g. `--auth=user`) |
-| `--public` | Public access — no authentication |
+| `--public` | Public access, no authentication |
 | `--byo` | Bring your own authentication |
 | `--scope=CLASS` | Entity class for multi-tenancy (e.g. `--scope=Organization`) |
 
@@ -51,7 +51,9 @@ end
 
 ## Controller concern (auth)
 
-Every portal has a `Concerns::Controller` mixed into its `ResourceController`. The generator wires this up; you customize for auth flow and shared before_action hooks.
+Every portal has a `Concerns::Controller`, included by both its `ResourceController` (resource pages) and its `PlutoniumController` (dashboard and other non-resource pages). The generator wires this up; you customize for auth flow and shared before_action hooks.
+
+Portal-wide helpers the layout calls belong here, declared with `helper_method`, so they work on the dashboard as well as resource pages. The common case is `profile_url`: `Plutonium::Auth::Rodauth` defines it as `nil`, and the avatar menu only shows a Profile link when it returns a URL. `pu:profile:conn --dest=<portal>` writes the override into this concern (see [Auth › Profile](/reference/auth/profile)).
 
 ### Rodauth
 
@@ -89,19 +91,63 @@ end
 
 ## Mounting
 
+`pu:pkg:portal` writes the mount at the bottom of the portal's own `packages/<name>_portal/config/routes.rb`, at `/<name>`, wrapped in an auth constraint when `--auth` is given:
+
 ```ruby
-# config/routes.rb
+# packages/admin_portal/config/routes.rb (after the engine's routes.draw block)
 Rails.application.routes.draw do
-  # Authenticated mount
   constraints Rodauth::Rails.authenticate(:user) do
     mount AdminPortal::Engine, at: "/admin"
   end
+end
+```
+
+With `--public` or `--byo` the mount is unconstrained and the portal handles its own auth.
+
+To change the path, edit `at:` in place. Don't mount the engine again in `config/routes.rb`: the second `mount` reuses the route name (`admin_portal`) and Rails raises `ArgumentError: Invalid route name, already in use`.
 
-  # Unconstrained — the portal handles its own auth
-  mount PublicPortal::Engine, at: "/public"
+Route order matters: the app's `config/routes.rb` is drawn first, then each package's routes file, then gem engines (Active Storage, Turbo).
+
+### Mounting a portal at `/`
+
+Two things change when a portal is mounted at `"/"`.
+
+**Drop the `Rodauth::Rails.authenticate` constraint and authenticate in the controller concern instead.** The constraint does not fail the match for an anonymous visitor; it calls `rodauth.require_account`, which redirects to login. A constrained mount at `/` matches every path the app's own routes did not claim, so it redirects anonymous requests meant for routes drawn after it (other portals, Active Storage) and turns unknown URLs into login redirects.
+
+```ruby
+# packages/desk_portal/config/routes.rb
+Rails.application.routes.draw do
+  mount DeskPortal::Engine, at: "/"
+end
+
+# packages/desk_portal/app/controllers/desk_portal/concerns/controller.rb
+module DeskPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+      include Plutonium::Auth::Rodauth(:user)
+
+      included do
+        before_action { rodauth.require_account }
+      end
+    end
+  end
 end
 ```
 
+**Move the engine's root off `/` but keep the name.** The app's `root` is drawn first, so the generated `root to: "dashboard#index"` is unreachable and the portal's `root_path` points at the app's home page. Plutonium's header, icon rail, breadcrumbs and wizard exits all link to `root_path`, so the portal still needs a route named `root`:
+
+```ruby
+DeskPortal::Engine.routes.draw do
+  get "dashboard", to: "dashboard#index", as: :root
+  register_resource ::Comment
+  # register resources above.
+end
+```
+
+The same applies to `register_dashboard ..., at: "/"`. Confirm with `Rails.application.routes.recognize_path("/")` (still the app's home) and `recognize_path("/dashboard")`.
+
 ## Routes & `register_resource`
 
 Portal routes live in `packages/<name>_portal/config/routes.rb`:
@@ -126,7 +172,7 @@ For each call, Plutonium auto-generates:
 - Nested routes for every registered `has_many` / `has_one` parent (prefixed `nested_`)
 - Route names that `resource_url_for` can resolve
 
-You list every resource the portal exposes. If a resource isn't registered, it has no URLs in that portal — `resource_url_for` will fail.
+You list every resource the portal exposes. If a resource isn't registered, it has no URLs in that portal, so `resource_url_for` will fail.
 
 ### Choosing nested associations
 
@@ -136,11 +182,11 @@ Name the associations that get nested routes, and the rest are not drawn:
 register_resource ::Post, associations: %i[comments post_detail]
 ```
 
-`associations: []` draws none, and a name that is not a routable association fails the boot. Set `config.nested_association_routes = :declared` to make naming them the rule — see [Tenancy › Nested resources](../tenancy/nested-resources#declaring-which-associations-get-routes).
+`associations: []` draws none, and a name that is not a routable association fails the boot. Set `config.nested_association_routes = :declared` to make naming them the rule; see [Tenancy › Nested resources](../tenancy/nested-resources#declaring-which-associations-get-routes).
 
 ### Singular (singleton) resources
 
-For resources with no collection — a single per-user `Profile`, app-wide `Settings`, etc.:
+For resources with no collection: a single per-user `Profile`, app-wide `Settings`, etc.:
 
 ```ruby
 register_resource ::Profile, singular: true
@@ -178,12 +224,12 @@ end
 ```
 
 ::: warning Always pass `as:`
-Without `as:`, `resource_url_for(@post, action: :preview)` fails because there's no named route — especially critical for nested resources.
+Without `as:`, `resource_url_for(@post, action: :preview)` fails because there's no named route, which is especially critical for nested resources.
 :::
 
-For most operations with business logic, prefer **interactive actions** (definition + interaction — see [Resource › Actions](/reference/resource/actions)) over custom controller routes. Action routes wire automatically with no `register_resource` block needed.
+For most operations with business logic, prefer **interactive actions** (definition + interaction; see [Resource › Actions](/reference/resource/actions)) over custom controller routes. Action routes wire automatically with no `register_resource` block needed.
 
-## Connecting resources — `pu:res:conn`
+## Connecting resources: `pu:res:conn`
 
 A resource is invisible until connected to at least one portal. The generator wires up the portal-specific controller, policy, definition, and route registration.
 
@@ -191,7 +237,7 @@ A resource is invisible until connected to at least one portal. The generator wi
 rails g pu:res:conn RESOURCE [RESOURCE...] --dest=PORTAL_NAME [--singular]
 ```
 
-Pass resources directly — avoids interactive prompts. No `--src` needed.
+Pass resources directly to avoid interactive prompts. No `--src` needed.
 
 ```bash
 # Main app resources
@@ -286,13 +332,13 @@ end
 ## Per-portal overrides
 
 ```ruby
-# Definition — how fields render per portal
+# Definition: how fields render per portal
 class AdminPortal::PostDefinition < ::PostDefinition
   scope :pending_review
   input :internal_notes, hint: "Not shown to the author"
 end
 
-# Policy — which fields exist, and who may act
+# Policy: which fields exist, and who may act
 #          `internal_notes` appears for admins because THIS permits it,
 #          not because the definition above mentions it.
 class AdminPortal::PostPolicy < ::PostPolicy
@@ -302,7 +348,7 @@ class AdminPortal::PostPolicy < ::PostPolicy
   def permitted_attributes_for_create = %i[title content featured internal_notes]
 end
 
-# Controller — different redirect after submit
+# Controller: different redirect after submit
 module AdminPortal
   class PostsController < ResourceController
     private
@@ -321,20 +367,22 @@ config.after_initialize do
 end
 ```
 
-Strategies: `:path` (entity id in URL — default) or a custom method name on the portal controller concern.
+Strategies: `:path` (entity id in URL, the default) or a custom method name on the portal controller concern.
 
 For the full multi-tenancy story, see [Tenancy › Entity scoping](/reference/tenancy/entity-scoping).
 
 ## Dashboard / non-resource pages
 
+The generated `dashboard#index` is a plain page listing the registered resources. To replace it with a [dashboard](/guides/dashboards) of metric and chart cards, run `rails g pu:dashboard Home --dest=<portal> --at=/`, which swaps the `root to:` line for a `register_dashboard ... at: "/"` registration.
+
 ```ruby
-# config/routes.rb
+# packages/admin_portal/config/routes.rb
 AdminPortal::Engine.routes.draw do
   root to: "dashboard#index"
   get "settings", to: "settings#index"
 end
 
-# Controller — inherit from PlutoniumController, NOT ResourceController
+# Controller: inherit from PlutoniumController, NOT ResourceController
 module AdminPortal
   class DashboardController < PlutoniumController
     def index
@@ -349,7 +397,7 @@ See [UI › Pages](/reference/ui/pages) for custom Phlex page classes.
 ## Multiple portals
 
 ```ruby
-# Admin — full access, entity-scoped
+# Admin: full access, entity-scoped
 module AdminPortal
   class Engine < Rails::Engine
     include Plutonium::Portal::Engine
@@ -360,7 +408,7 @@ module AdminPortal
   end
 end
 
-# Customer dashboard — entity-scoped to the customer's organization
+# Customer dashboard: entity-scoped to the customer's organization
 module DashboardPortal
   class Engine < Rails::Engine
     include Plutonium::Portal::Engine
@@ -371,7 +419,7 @@ module DashboardPortal
   end
 end
 
-# Public — no auth, no entity scoping
+# Public: no auth, no entity scoping
 module PublicPortal
   class Engine < Rails::Engine
     include Plutonium::Portal::Engine
@@ -381,9 +429,9 @@ end
 
 ## Related
 
-- [Packages](./packages) — feature vs portal split, structure, namespacing
-- [Generators](./generators) — full `pu:pkg:portal` / `pu:res:conn` option reference
-- [Behavior › Controllers](/reference/behavior/controllers) — controller key methods, hooks, customizations
-- [Tenancy › Entity scoping](/reference/tenancy/entity-scoping) — multi-tenancy mechanics
-- [Auth](/reference/auth/) — Rodauth account types referenced by `--auth=`
-- [UI › Layouts](/reference/ui/layouts) — customizing portal chrome
+- [Packages](./packages): feature vs portal split, structure, namespacing
+- [Generators](./generators): full `pu:pkg:portal` / `pu:res:conn` option reference
+- [Behavior › Controllers](/reference/behavior/controllers): controller key methods, hooks, customizations
+- [Tenancy › Entity scoping](/reference/tenancy/entity-scoping): multi-tenancy mechanics
+- [Auth](/reference/auth/): Rodauth account types referenced by `--auth=`
+- [UI › Layouts](/reference/ui/layouts): customizing portal chrome

data/docs/reference/auth/accounts.md

@@ -1,8 +1,8 @@
 # Accounts
 
-Rodauth account types. Pick one (or several — apps can have multiple side-by-side).
+Rodauth account types. Pick one (or several; apps can have multiple side-by-side).
 
-## Basic account — `pu:rodauth:account`
+## Basic account: `pu:rodauth:account`
 
 ```bash
 rails generate pu:rodauth:account user [options]
@@ -59,7 +59,7 @@ rails g pu:rodauth:account api_user --api_only --jwt --jwt_refresh
 rails g pu:rodauth:account user --kitchen_sink
 ```
 
-## Admin account — `pu:rodauth:admin`
+## Admin account: `pu:rodauth:admin`
 
 Pre-configured secure admin with multi-phase login, **required** TOTP, recovery codes, lockout, active session tracking, audit logging, role-based access, invite interaction, and **no public signup**.
 
@@ -74,7 +74,7 @@ rails g pu:rodauth:admin admin --extra-attributes=name:string,department:string
 | `--roles` | `super_admin,admin` | Comma-separated roles (positional enum) |
 | `--extra_attributes` | | Additional model attributes (e.g. `name:string`) |
 
-**Role-ordering convention:** index 0 is the most privileged. Generated invite interaction defaults new invitees to `roles[1]` — the order in `--roles=` matters.
+**Role-ordering convention:** index 0 is the most privileged. Generated invite interaction defaults new invitees to `roles[1]`, so the order in `--roles=` matters.
 
 ```ruby
 enum :role, super_admin: 0, admin: 1
@@ -82,12 +82,12 @@ enum :role, super_admin: 0, admin: 1
 
 **Invite + resend.** The admin resource gets two actions:
 
-- **Invite** — invite a new admin by email; Rodauth sends a verification link and the invitee sets their own password through the verify flow.
-- **Resend invitation** — re-send the verification email. Only shown for admins who haven't verified yet.
+- **Invite**: invite a new admin by email; Rodauth sends a verification link and the invitee sets their own password through the verify flow.
+- **Resend invitation**: re-send the verification email. Only shown for admins who haven't verified yet.
 
 This uses Rodauth account verification, separate from the [Tenancy › Invites](/reference/tenancy/invites) system.
 
-Rake task for direct admin creation (generated alongside the account — namespace is `rodauth`, task name is the account name):
+Rake task for direct admin creation (generated alongside the account; namespace is `rodauth`, task name is the account name):
 
 ```bash
 EMAIL=admin@example.com rails rodauth:admin
@@ -96,7 +96,7 @@ EMAIL=admin@example.com rails rodauth:admin
 
 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) {#saas-setup}
+## SaaS setup: `pu:saas:setup` (meta-generator) {#saas-setup}
 
 Creates the User + Entity + Membership trio AND runs:
 
@@ -152,7 +152,7 @@ class OrganizationCustomer < ApplicationRecord
 end
 ```
 
-## API client — `pu:saas:api_client`
+## API client: `pu:saas:api_client`
 
 For machine-to-machine authentication. HTTP Basic Auth with auto-generated password.
 
@@ -233,12 +233,12 @@ end
 Emitted by the generators; both parts are required for concurrent portal logins.
 
 ```ruby
-# app/rodauth/rodauth_plugin.rb — the shared base, once
+# app/rodauth/rodauth_plugin.rb: the shared base, once
 enable :session_isolation
 ```
 
 ```ruby
-# app/rodauth/<name>_rodauth_plugin.rb — once per account type
+# app/rodauth/<name>_rodauth_plugin.rb: once per account type
 session_key_prefix "admin_"           # namespaces EVERY key, account id included
 remember_cookie_key "_admin_remember"
 ```
@@ -249,7 +249,7 @@ Do **not** also set `session_key`: explicit values bypass `convert_session_key`
 
 ## Related
 
-- [Profile](./profile) — profile resource + SecuritySection component
-- [App › Portals › Controller concern (auth)](/reference/app/portals#controller-concern-auth) — wiring accounts into portal controllers
-- [Tenancy › Invites](/reference/tenancy/invites) — invitation system on top of Rodauth signup
-- [App › Generators › Authentication generators](/reference/app/generators#authentication-generators) — full generator catalog
+- [Profile](./profile): profile resource + SecuritySection component
+- [App › Portals › Controller concern (auth)](/reference/app/portals#controller-concern-auth): wiring accounts into portal controllers
+- [Tenancy › Invites](/reference/tenancy/invites): invitation system on top of Rodauth signup
+- [App › Generators › Authentication generators](/reference/app/generators#authentication-generators): full generator catalog

data/docs/reference/auth/index.md

@@ -4,18 +4,18 @@ Plutonium uses [Rodauth](http://rodauth.jeremyevans.net/) via [rodauth-rails](ht
 
 ## Sub-pages
 
-- [Accounts](./accounts) — Rodauth install, basic accounts, admin accounts, SaaS setup, account customization
-- [Profile](./profile) — profile resource generator, the SecuritySection component
+- [Accounts](./accounts): Rodauth install, basic accounts, admin accounts, SaaS setup, account customization
+- [Profile](./profile): profile resource generator, the SecuritySection component
 
 ## 🚨 Critical
 
 - **Use the generators.** `pu:rodauth:install`, `pu:rodauth:account`, `pu:rodauth:admin`, `pu:saas:setup`, `pu:profile:install`, `pu:profile:conn`. Never hand-write Rodauth plugin files, account models, or profile resources.
-- **Role index 0 is the most privileged** (`owner`, `super_admin`). Invite interactions default new invitees to **index 1** — the order in `--roles=` matters.
+- **Role index 0 is the most privileged** (`owner`, `super_admin`). Invite interactions default new invitees to **index 1**, so the order in `--roles=` matters.
 - **`pu:saas:setup --roles=...` always prepends `owner` as index 0.** Don't include `owner` in the option.
 - **`pu:saas:setup` is a meta-generator.** It also runs `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, and `pu:invites:install`. Don't re-run those manually.
-- **Profile association is always `:profile`** regardless of the model class — `current_user.profile`, `build_profile`, `params.require(:profile)`.
-- **Profile needs `pu:profile:conn` to be visible** — without it, the singular `/profile` route and `profile_url` helper don't exist.
-- **Every user needs a profile row.** Add an `after_create` callback or `find_or_create_by` — otherwise `current_user.profile` is nil.
+- **Profile association is always `:profile`** regardless of the model class: `current_user.profile`, `build_profile`, `params.require(:profile)`. `pu:profile:conn` hardcodes `current_user.profile`.
+- **Profile needs `pu:profile:conn` to be visible.** Without it, there is no singular `/profile` route and `profile_url` stays `nil` (no menu link).
+- **Check an existing profile policy for `update?`.** Older `pu:profile:conn` output lacks `def update? = true`, so the profile can't be edited once it exists. See [Profile](./profile#what-pu-profile-conn-generates).
 
 ## Install Rodauth
 
@@ -34,7 +34,7 @@ class ResourceController < PlutoniumController
 end
 ```
 
-Multiple account types — include the matching `:name`:
+Multiple account types: include the matching `:name`:
 
 ```ruby
 class AdminController < PlutoniumController
@@ -80,9 +80,9 @@ Authorization: Bearer <access_token>
 
 ## Related
 
-- [Accounts](./accounts) — account types and feature flags
-- [Profile](./profile) — profile resource + SecuritySection
-- [Tenancy › Invites](/reference/tenancy/invites) — invitation system on top of Rodauth signup
-- [App › Portals › Controller concern (auth)](/reference/app/portals#controller-concern-auth) — portal-side wiring
-- [Guides › Authentication](/guides/authentication) — task-oriented walkthrough
+- [Accounts](./accounts): account types and feature flags
+- [Profile](./profile): profile resource + SecuritySection
+- [Tenancy › Invites](/reference/tenancy/invites): invitation system on top of Rodauth signup
+- [App › Portals › Controller concern (auth)](/reference/app/portals#controller-concern-auth): portal-side wiring
+- [Guides › Authentication](/guides/authentication): task-oriented walkthrough
 - [Guides › User profile](/guides/user-profile)

data/docs/reference/auth/profile.md

@@ -1,12 +1,12 @@
 # Profile
 
-Manages Rodauth account settings as a Plutonium resource — users view/edit personal fields and access Rodauth security features (change password, 2FA, etc.) on one page.
+Manages Rodauth account settings as a Plutonium resource: users view/edit personal fields and access Rodauth security features (change password, 2FA, etc.) on one page.
 
 ## 🚨 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`** — without it, no route, no `profile_url` helper, no user-menu link.
-- **Every user needs a profile row** — add an `after_create` callback (or `find_or_create_by`). Without it, `current_user.profile` is nil and the profile route errors.
+- **Profile association is always `:profile`** regardless of the model class: `current_user.profile`, `build_profile`, `params.require(:profile)` always work. `pu:profile:conn` hardcodes `current_user.profile` in the code it generates.
+- **Profile needs `pu:profile:conn`.** Without it: no route, no `profile_url` override, no user-menu link.
+- **Check an existing profile policy for `update?`.** Policies generated by older versions lack `def update? = true`, which leaves the profile read-only once it exists. See [What `pu:profile:conn` generates](#what-pu-profile-conn-generates).
 
 ## Quick setup
 
@@ -42,7 +42,7 @@ rails g pu:profile:install AccountSettings bio:text --dest=main_app
 
 ## What gets created
 
-By default the model is `{UserModel}Profile` — `UserProfile`, `StaffUserProfile`, etc. — derived from `--user-model`.
+By default the model is `{UserModel}Profile` (`UserProfile`, `StaffUserProfile`, etc.), derived from `--user-model`.
 
 ```
 app/models/[package/]user_profile.rb
@@ -59,10 +59,10 @@ has_one :profile, class_name: "UserProfile", dependent: :destroy
 ```
 
 ::: warning Association name is fixed
-Even when the class is `StaffUserProfile`, the association is `:profile`. Don't rename it — `current_user.profile`, `build_profile`, `params.require(:profile)` all assume this.
+Even when the class is `StaffUserProfile`, the association is `:profile`. Don't rename it: `current_user.profile`, `build_profile`, `params.require(:profile)` all assume this.
 :::
 
-The generated definition injects a custom `ShowPage` that renders the `SecuritySection` component.
+If you reuse a profile model whose user association has a different name (e.g. `has_one :user_profile`), add `has_one :profile, class_name: "UserProfile"` to the user model rather than editing `current_user.profile` out of the generated policy and `profile_url`. Then connect it with `pu:profile:conn UserProfile --dest=<portal>`.
 
 ## The `SecuritySection` component
 
@@ -78,7 +78,7 @@ Dynamically lists Rodauth security links based on which features are enabled on
 | `active_sessions` | Active Sessions |
 | `close_account` | Close Account |
 
-If a feature isn't enabled on the account, its link doesn't render — no configuration needed.
+If a feature isn't enabled on the account, its link doesn't render; no configuration needed.
 
 To customize (e.g. add chrome, reorder), override `ShowPage#render_after_content`:
 
@@ -96,40 +96,77 @@ end
 
 See [UI › Pages](/reference/ui/pages) for page-class customization.
 
-## Required: every user gets a profile
+## Connecting to a portal
+
+`pu:profile:conn` registers the profile as a **singular** resource: `/profile` (no `:id`), and overrides the `profile_url` helper:
+
+```bash
+rails g pu:profile:conn --dest=customer_portal
+```
+
+This is what makes the profile visible. Without it, the model exists but has no route in any portal.
+
+### What `pu:profile:conn` generates
+
+It runs `pu:res:conn` with `--singular --policy --definition`, then injects:
+
+- **Policy:** `relation_scope { skip_default_relation_scope!; relation.where(user: user) }` (a profile belongs to the user, not the portal's entity), `create? = user.profile.nil?`, `update? = true`, `destroy? = false`, and `permitted_attributes_for_create` minus `:user`.
+- **Controller:** `resource_params` merged with `user: current_user`, so the owner is set server-side.
+- **Definition:** a `ShowPage` whose `render_after_content` renders `Plutonium::Profile::SecuritySection`.
+- **Portal controller concern:** `profile_url`, which points at the profile or, when the user has none yet, at the new-profile form.
+
+The explicit `update?` matters: the base policy's `update?` delegates to `create?`, which is false once the profile exists. Policies generated by older versions lack it and leave the profile read-only, so add it if it's missing:
 
 ```ruby
-class User < ApplicationRecord
-  after_create :create_profile!
+def update?
+  true
+end
+```
 
-  private
-  def create_profile! = create_profile
+## Users without a profile row
+
+The generated `profile_url` sends a user with no profile to the new-profile form, and `create?` allows exactly one, so a missing row does not break the route. It does mean the first visit is a "create profile" form, and the `SecuritySection` only appears after it is saved. If you want the show page from the first click, create the row up front:
+
+```ruby
+class User < ApplicationRecord
+  after_create :create_profile
 end
 ```
 
-Without this, `current_user.profile` returns nil and the profile route errors. For existing users at migration time, run a one-off backfill:
+and backfill existing users:
 
 ```bash
-rails runner "User.find_each(&:create_profile)"
+rails runner "User.find_each { |u| u.profile || u.create_profile }"
 ```
 
-## Connecting to a portal
+Skip this when the profile has required fields the user must fill in, or when existing code creates profiles itself (the unique `user_id` index makes a second insert fail).
 
-`pu:profile:conn` registers the profile as a **singular** resource — `/profile` (no `:id`), and exposes the `profile_url` helper:
+## Linking to the profile
 
-```bash
-rails g pu:profile:conn --dest=customer_portal
+Nothing to add. `Plutonium::Auth::Rodauth` defines `profile_url` returning `nil`, and the topbar avatar menu renders a "Profile" entry whenever it returns a URL. `pu:profile:conn` overrides it in the portal's controller concern, which is what makes the link appear. Elsewhere:
+
+```ruby
+link_to("Profile", profile_url) if profile_url
 ```
 
-This is what makes the profile visible. Without it, the model exists but has no route in any portal.
+## Account features on the profile page
 
-## Linking to the profile
+Per-user settings that aren't part of the profile row (API tokens, connected accounts, notification preferences) are discovered from the profile page. Link them from the same `ShowPage` hook that renders `SecuritySection`, instead of adding custom items to the sidebar or overriding the topbar partial:
 
 ```ruby
-link_to("Profile", profile_url) if respond_to?(:profile_url)
+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.
+A resource like `ApiToken` belongs to the user, not the portal's entity, so connect it with `pu:res:conn ApiToken --dest=<portal> --policy` and give it the same shape the profile has: `skip_default_relation_scope!` plus `relation.where(user: user)` in the policy, and `resource_params` merged with `user: current_user` in the controller.
 
 ## Customizing the definition
 
@@ -173,13 +210,14 @@ rails g pu:profile:conn StaffUserProfile --dest=admin_portal
 
 ## Gotchas
 
-- **`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>`.
-- **Custom resource name** — pass it as the first positional argument to `pu:profile:install`. The association is still `:profile`.
-- **SecuritySection shows nothing** — none of the relevant Rodauth features are enabled on the account. Enable `change_password`, `otp`, etc. on the Rodauth plugin.
+- **Profile is read-only after creation.** The policy predates the generated `update?`, so `update?` falls back to `create?` (`user.profile.nil?`). Add `def update? = true`.
+- **First visit shows a "create profile" form.** The user has no profile row yet. Not an error; add `after_create :create_profile` plus a backfill if they should land on the show page.
+- **No Profile link in the user menu.** `profile_url` still returns the default `nil` because the profile isn't connected to this portal. Run `pu:profile:conn --dest=<portal>`.
+- **Custom resource name**: pass it as the first positional argument to `pu:profile:install`. The association is still `:profile`.
+- **SecuritySection shows nothing**: none of the relevant Rodauth features are enabled on the account. Enable `change_password`, `otp`, etc. on the Rodauth plugin.
 
 ## Related
 
-- [Accounts](./accounts) — Rodauth feature flags that gate SecuritySection links
-- [Resource › Definition](/reference/resource/definition) — customizing the profile definition
+- [Accounts](./accounts): Rodauth feature flags that gate SecuritySection links
+- [Resource › Definition](/reference/resource/definition): customizing the profile definition
 - [App › Generators › Profile generators](/reference/app/generators#profile-generators)