plutonium 0.65.0 → 0.66.0

data/.claude/skills/plutonium-async-interactions/SKILL.md

@@ -1,25 +1,25 @@
 ---
 name: plutonium-async-interactions
-description: Use BEFORE building any bulk operation or long-running interaction. Covers async, the Run STI model, failure policies (halt/continue/transactional), authorization re-derivation at perform time, registering AsyncRun as a resource (progress page + running banner), and scheduling ReapJob for stalled runs. The single source for "how do I make an interaction async".
+description: 'Use BEFORE building any bulk operation or long-running interaction. Covers async, the Run STI model, failure policies (halt/continue/transactional), authorization re-derivation at perform time, registering AsyncRun as a resource (progress page + running banner), and scheduling ReapJob for stalled runs. The single source for "how do I make an interaction async".'
 ---
 
 # Plutonium Async Interactions
 
-`async` turns an interaction from "does the work inline" into "persists a run, enqueues it, and redirects to it." Reach for it once the work is too slow to hold a request open — thousands of records, report generation, a third-party call.
+`async` turns an interaction from "does the work inline" into "persists a run, enqueues it, and redirects to it." Reach for it once the work is too slow to hold a request open: thousands of records, report generation, a third-party call.
 
 For everything about the interaction itself (inputs, validation, outcomes, `execute`), load [[plutonium-behavior]] first. `async` only replaces what `execute` does, not the rest of the interaction's shape.
 
 ## 🚨 Critical (read first)
 
-- **Experimental.** The DSL and behavior may change in a future release — same status as [[plutonium-wizard]] and [[plutonium-kanban]]. Fine to build on; expect to revisit it on upgrade.
+- **Experimental.** The DSL and behavior may change in a future release, same status as [[plutonium-wizard]] and [[plutonium-kanban]]. Fine to build on; expect to revisit it on upgrade.
 - **Enable the subsystem first.** `rails g pu:async_interactions:install --dest=<portal>` flips `config.async_interactions.enabled = true`, schedules `ReapJob`, and connects the run resource to that portal; then `rails db:migrate`. Pass `--skip-portal` to enable it before any portal exists. Off by default, so no `plutonium_async_runs` table otherwise.
-- **`async` fully replaces `#execute`.** An interaction either executes inline or runs async — declaring both raises `ArgumentError` at load.
+- **`async` fully replaces `#execute`.** An interaction either executes inline or runs async; declaring both raises `ArgumentError` at load.
 - **Define `perform_on(record)` for targeted work, `perform` for opaque work.** A run class implementing neither fails loudly (naming the class) the first time it's performed, rather than a bare `NoMethodError`.
-- **A nested dispatch records its parent.** `parent_type`/`parent_id`/`parent_association` join initiator and tenant on the row, because `Policy#default_relation_scope` picks parent scoping **or** entity scoping, not both — a nested run missing its parent re-derives targets under the wider tenant scope, and any predicate reading `parent` silently answers false. A parent deleted mid-run refuses the run, exactly like a deleted tenant.
+- **A nested dispatch records its parent.** `parent_type`/`parent_id`/`parent_association` join initiator and tenant on the row, because `Policy#default_relation_scope` picks parent scoping **or** entity scoping, not both. A nested run missing its parent re-derives targets under the wider tenant scope, and any predicate reading `parent` silently answers false. A parent deleted mid-run refuses the run, exactly like a deleted tenant.
 - **Permissions are re-derived at perform time, never replayed from dispatch.** The job rebuilds `(initiator, tenant)` from the row and re-checks the policy scope and predicate per target, immediately before each `perform_on`. A permission revoked mid-run stops applying to what's left. Both failure directions (scope, predicate) fail closed (refuse/report), never open.
 - **Register `Run` as a resource per portal.** Its show page IS the progress page, and other resources' index pages get a "runs in progress" banner for free. Nothing renders without registration.
 - **Read `outcome`, never bare `state`, when displaying a run's result.** A `:continue` run that under-applied still has `state == "completed"`; only `outcome` says `"completed_with_errors"`.
-- **Long work must call `heartbeat!`.** `stall_after` measures SILENCE, and the executor only writes per target — so opaque `perform` writes nothing at all between claim and finish. An opaque run longer than `stall_after` is reaped and, having no `handled_target_ids`, re-run from scratch. Call `heartbeat!` inside the loop. It also raises `StaleObjectError` if another worker took the run over, which for opaque work is the only way to find out.
+- **Long work must call `heartbeat!`.** `stall_after` measures SILENCE, and the executor only writes per target, so opaque `perform` writes nothing at all between claim and finish. An opaque run longer than `stall_after` is reaped and, having no `handled_target_ids`, re-run from scratch. Call `heartbeat!` inside the loop. It also raises `StaleObjectError` if another worker took the run over, which for opaque work is the only way to find out.
 - **A crashed/stalled run does not auto-heal.** Nothing revisits a `"running"` row on its own. `pu:async_interactions:install` schedules `Plutonium::Interaction::Async::ReapJob` for you when Solid Queue is in the bundle; otherwise (or on another scheduler) you must schedule it yourself. Unscheduled, a crash mid-batch leaves that row stuck forever.
 
 ---
@@ -37,7 +37,7 @@ For everything about the interaction itself (inputs, validation, outcomes, `exec
 
 ## Declaring the work
 
-`async` with a block. One file — the run is declared inline and needs no name:
+`async` with a block. One file: the run is declared inline and needs no name:
 
 ```ruby
 class Blogging::ArchivePosts < ResourceInteraction
@@ -64,9 +64,9 @@ class Reports::GenerateMonthly < ResourceInteraction
 end
 ```
 
-**The block is the run's class body, not the body of `#execute`.** The work happens later, in a process with no controller and no `view_context`, so it cannot close over anything in the interaction — which is why it declares `perform_on`/`perform` rather than executing directly. Validated attributes arrive through `options`, and `def` opens a fresh scope, so those bodies can't accidentally capture the interaction's locals.
+**The block is the run's class body, not the body of `#execute`.** The work happens later, in a process with no controller and no `view_context`, so it cannot close over anything in the interaction, which is why it declares `perform_on`/`perform` rather than executing directly. Validated attributes arrive through `options`, and `def` opens a fresh scope, so those bodies can't accidentally capture the interaction's locals.
 
-The block defines `<Interaction>::Run` — a real, named constant, because the class name is persisted in `type` and constantized in the job process.
+The block defines `<Interaction>::Run`, a real, named constant, because the class name is persisted in `type` and constantized in the job process.
 
 **Pass a class instead** to share one run across several interactions that do the same kind of work:
 
@@ -96,7 +96,7 @@ An opaque run records none of the target/policy columns. Nothing to re-verify wi
 
 ## Attributes and files
 
-Validated attributes reach the run through `options`, a JSON column written via `ActiveJob::Arguments` — primitives verbatim, `Date`/`BigDecimal`/`Time` round-tripped with their types. An attribute that can't be carried is refused at dispatch.
+Validated attributes reach the run through `options`, a JSON column written via `ActiveJob::Arguments`: primitives verbatim, `Date`/`BigDecimal`/`Time` round-tripped with their types. An attribute that can't be carried is refused at dispatch.
 
 Files can't ride a JSON column, and the request's tempfile is gone by the time the job runs, so an uploaded file is staged to its backend's cache and carried as a token. Read it back with `attachment`:
 
@@ -112,7 +112,7 @@ end
 
 `attachment(:key)` / `attachments(:key)` give `filename`, `content_type`, `url`, `open`, `download`.
 
-`backend:` and `uploader:` come off the attribute's `input` declaration, exactly as in a wizard step — `input :import_file, as: :uppy, uploader: Catalog::ImportUploader`. The uploader's `Attacher.validate` rules run when the interaction validates, so a bad file **fails the form** rather than surfacing as a run failure the submitter never sees. Where no `backend:` is declared: `config.async_interactions.attachment_backend` → `config.attachment_backend` → auto-detect.
+`backend:` and `uploader:` come off the attribute's `input` declaration, exactly as in a wizard step: `input :import_file, as: :uppy, uploader: Catalog::ImportUploader`. The uploader's `Attacher.validate` rules run when the interaction validates, so a bad file **fails the form** rather than surfacing as a run failure the submitter never sees. Where no `backend:` is declared: `config.async_interactions.attachment_backend` → `config.attachment_backend` → auto-detect.
 
 ## Registering the Run resource
 
@@ -136,9 +136,9 @@ class AdminPortal::AsyncRunsController < AdminPortal::ResourceController
 end
 ```
 
-`controller_for` is required — the controller's name doesn't match `Run`'s real, namespaced class, so inference can't find it on its own. No policy/definition files are generated: `Plutonium::Interaction::Async::RunPolicy`/`Async::RunDefinition` already resolve automatically (exact class-name match for the definition, ActionPolicy's own lookup for the policy).
+`controller_for` is required: the controller's name doesn't match `Run`'s real, namespaced class, so inference can't find it on its own. No policy/definition files are generated: `Plutonium::Interaction::Async::RunPolicy`/`Async::RunDefinition` already resolve automatically (exact class-name match for the definition, ActionPolicy's own lookup for the policy).
 
-If Solid Queue is in the bundle, this also schedules `Async::ReapJob` in `config/recurring.yml` — see [Scheduling ReapJob](#scheduling-reapjob-stalled-runs). `--schedule` overrides the default `every 15 minutes`. Idempotent, so running it against a second portal doesn't duplicate the entry.
+If Solid Queue is in the bundle, this also schedules `Async::ReapJob` in `config/recurring.yml`: see [Scheduling ReapJob](#scheduling-reapjob-stalled-runs). `--schedule` overrides the default `every 15 minutes`. Idempotent, so running it against a second portal doesn't duplicate the entry.
 
 Registering gets you, for free:
 
@@ -166,7 +166,7 @@ production:
     schedule: every 15 minutes
 ```
 
-Without Solid Queue — or for another scheduler like `whenever` — add it yourself:
+Without Solid Queue, or for another scheduler like `whenever`, add it yourself:
 
 ```ruby
 # whenever gem
@@ -175,7 +175,7 @@ every 15.minutes do
 end
 ```
 
-15 to 30 minutes is a reasonable cadence against the default 1-hour `stall_after`. This is a time heuristic, not a true lease: a merely-slow (not dead) run that crosses `stall_after` gets resumed too. `lock_version` bounds what that costs — the resumed row's version no longer matches the still-live worker's, so that worker stops at its next write instead of racing the new one. It does **not** interrupt an in-flight `perform_on` (one target can be applied twice, once by each side), and it does not roll back what the superseded worker already committed. Set `stall_after` well above the app's slowest legitimate run.
+15 to 30 minutes is a reasonable cadence against the default 1-hour `stall_after`. This is a time heuristic, not a true lease: a merely-slow (not dead) run that crosses `stall_after` gets resumed too. `lock_version` bounds what that costs: the resumed row's version no longer matches the still-live worker's, so that worker stops at its next write instead of racing the new one. It does **not** interrupt an in-flight `perform_on` (one target can be applied twice, once by each side), and it does not roll back what the superseded worker already committed. Set `stall_after` well above the app's slowest legitimate run.
 
 On Solid Queue (or any queue providing ActiveJob concurrency controls) this is tightened further, automatically and with no configuration: `Async::Job` declares a semaphore of 1 keyed on the run id, held for `stall_after`, and `ReapJob` one global sweep at a time. A second delivery of the same run then waits rather than racing, so the one target the fence cannot save from a double apply is not applied twice either. Nothing declares it when the queue does not support it.
 
@@ -185,7 +185,7 @@ On Solid Queue (or any queue providing ActiveJob concurrency controls) this is t
 
 ## Related Skills
 
-- [[plutonium-behavior]] — the interaction itself: inputs, validation, `succeed`/`failed`, policies.
-- [[plutonium-resource]] — Actions (inferred bulk/record/resource shape), Definition (`field`/`display`/`column`).
-- [[plutonium-tenancy]] — entity scoping, `associated_with`, portal tenant strategies.
-- [[plutonium-wizard]] — the other long-lived, persisted flow primitive (multi-step, not async execution). `Wizard::SweepJob` is `ReapJob`'s sibling for abandoned wizard sessions.
+- [[plutonium-behavior]]: the interaction itself: inputs, validation, `succeed`/`failed`, policies.
+- [[plutonium-resource]]: Actions (inferred bulk/record/resource shape), Definition (`field`/`display`/`column`).
+- [[plutonium-tenancy]]: entity scoping, `associated_with`, portal tenant strategies.
+- [[plutonium-wizard]]: the other long-lived, persisted flow primitive (multi-step, not async execution). `Wizard::SweepJob` is `ReapJob`'s sibling for abandoned wizard sessions.

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

@@ -1,9 +1,9 @@
 ---
 name: plutonium-auth
-description: Use BEFORE installing Rodauth, configuring account types, building login/password flows, or wiring a profile / account-settings page. Covers the full auth surface — Rodauth installation, accounts, admin accounts, SaaS setup, profile resource, security section.
+description: 'Use BEFORE installing Rodauth, configuring account types, building login/password flows, or wiring a profile / account-settings page. Covers the full auth surface: Rodauth installation, accounts, admin accounts, SaaS setup, profile resource, security section.'
 ---
 
-# Plutonium Auth — Rodauth + Profile
+# Plutonium Auth: Rodauth + Profile
 
 Plutonium integrates [Rodauth](http://rodauth.jeremyevans.net/) via [rodauth-rails](https://github.com/janko/rodauth-rails). This skill covers installing Rodauth, generating account types (basic / admin / SaaS), wiring auth into controllers and portals, and the profile / account-settings resource.
 
@@ -15,39 +15,40 @@ For multi-tenant invitations and membership, see [[plutonium-tenancy]] › Invit
 - **Role index 0 is the most privileged** (`owner`, `super_admin`). Invite interactions default new invitees to **index 1**.
 - **`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` in the code it generates. If an existing user model names it differently (e.g. `has_one :user_profile`), add `has_one :profile, class_name: "UserProfile"` to the model; don't rewrite the generated code to the other name.
+- **Profile needs `pu:profile:conn` to be visible.** Without it, the singular `/profile` route and `profile_url` helper don't exist. A profile that exists but isn't wired is something to fix with `pu:profile:conn`, not something to route around.
+- **Check an existing profile policy for `update?`.** Conn generates `create? = user.profile.nil?`, and the base `update?`/`edit?` delegate to `create?`. Current conn also generates `def update? = true`; a policy generated by an older version lacks it, so the profile can't be edited once it exists. Add it (the `relation_scope` already limits it to the user's own row).
+- **Per-user account features hang off the profile page.** API tokens, connected accounts, notification settings: link them from the profile `ShowPage#render_after_content` next to `SecuritySection` (see Account features on the profile page).
 
 ---
 
-## 🛑 Before you set up auth: confirm the shape (ASK — don't infer)
+## 🛑 Before you set up auth: confirm the shape (ASK: don't infer)
 
-"Set up login" hides the one decision that determines everything: **is this multi-tenant SaaS or a single auth surface?** Pick wrong and you either hand-assemble what a meta-generator does in one shot, or scaffold a SaaS spine an app doesn't need. Resolve each — confirming by inspection (next section):
+"Set up login" hides the one decision that determines everything: **is this multi-tenant SaaS or a single auth surface?** Pick wrong and you either hand-assemble what a meta-generator does in one shot, or scaffold a SaaS spine an app doesn't need. Resolve each, confirming by inspection (next section):
 
 1. **Single auth or multi-tenant SaaS?** "Each user belongs to / manages an org/team" ⇒ SaaS ⇒ **`pu:saas:setup`** (the meta-generator: user + entity + membership + portal + profile + welcome + invites in one). A plain login with no tenant ⇒ `pu:rodauth:install` + `pu:rodauth:account`.
-2. **Account type.** Basic user, **hardened admin** (`pu:rodauth:admin` — 2FA/lockout/audit, no public signup), or **API** (`--api_only --jwt`)? They're different generators.
+2. **Account type.** Basic user, **hardened admin** (`pu:rodauth:admin`, 2FA/lockout/audit, no public signup), or **API** (`--api_only --jwt`)? They're different generators.
 3. **Public signup allowed?** Default yes for `account`; admin accounts are invite-only.
 4. **Profile / account-settings page?** Needs `pu:profile:install` **and** `pu:profile:conn` (without conn there's no `/profile` route).
-5. **Roles.** Index 0 is most privileged (`owner`/`super_admin`); invites default new members to `roles[1]`. `pu:saas:setup` prepends `owner` — don't list it.
+5. **Roles.** Index 0 is most privileged (`owner`/`super_admin`); invites default new members to `roles[1]`. `pu:saas:setup` prepends `owner`; don't list it.
 
 **Never ship a guessed account-type, model name, or `--roles` as applied commands.** Read them off the app first; fall back to `AskUserQuestion` only for product choices (separate staff accounts vs shared, is signup open).
 
-## ✅ Before you run a generator: verify the ground truth (CHECK — read it, don't ask for it)
+## ✅ Before you run a generator: verify the ground truth (CHECK: read it, don't ask for it)
 
-You have file access — **inspect**; don't ask the user to describe their app.
+You have file access, **inspect**; don't ask the user to describe their app.
 
 | Check | How | Why it matters |
 |---|---|---|
 | Rodauth already installed | `ls app/rodauth/rodauth_app.rb`; grep `Gemfile` for `rodauth` | Re-running `pu:rodauth:install` clobbers config |
 | Existing account models | grep `app/models` for `Rodauth::Rails.model` | Which account type exists / don't duplicate |
-| SaaS spine already run | `ls` for the entity portal + membership model | **`pu:saas:setup` chains 4 generators — don't re-run them separately** |
-| Profile wired | grep the user model for `has_one :profile` + `after_create`; is `profile_url` defined? | Else `current_user.profile` is nil / no route (`pu:profile:conn` missing) |
+| SaaS spine already run | `ls` for the entity portal + membership model | **`pu:saas:setup` chains 4 generators; don't re-run them separately** |
+| Profile wired | grep the user model for `has_one :profile`; grep the portal's `concerns/controller.rb` for `def profile_url` | No `:profile` association ⇒ add it. No `profile_url` ⇒ the profile isn't connected: run `pu:profile:conn` (even if the model and a `register_resource` line already exist) |
 | Role ordering | Read the membership `enum :role` | Index 0 = most privileged; invites default to `roles[1]` |
 
 Inspect with your own tools **before** running any generator.
 
-## 🛠 Use the generator — never hand-write Rodauth
+## 🛠 Use the generator: never hand-write Rodauth
 
 Never hand-write Rodauth plugin files, account models, or profile resources.
 
@@ -58,6 +59,7 @@ Never hand-write Rodauth plugin files, account models, or profile resources.
 | Basic account | `pu:rodauth:account NAME --defaults` | Rodauth installed |
 | Hardened admin | `pu:rodauth:admin NAME --roles=…` | Rodauth installed |
 | Profile page | `pu:profile:install …` + `pu:profile:conn --dest=portal` | Migrated; portal exists |
+| Profile page for an existing profile model | `pu:profile:conn UserProfile --dest=portal` | User model has `has_one :profile, class_name: "UserProfile"` |
 
 ---
 
@@ -73,9 +75,9 @@ Installs gems (`rodauth-rails`, `bcrypt`, `sequel-activerecord_connection`), the
 
 ## Account types
 
-Pick one (or several — apps can have multiple account types side-by-side).
+Pick one (or several; apps can have multiple account types side-by-side).
 
-### Basic account — `pu:rodauth:account`
+### Basic account: `pu:rodauth:account`
 
 ```bash
 rails generate pu:rodauth:account user [options]
@@ -108,7 +110,7 @@ rails generate pu:rodauth:account user [options]
 | `--sms_codes` | | SMS 2FA |
 | `--jwt`, `--jwt_refresh` | | JWT for API auth |
 
-### 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 + resend-invite interactions, and **no public signup**.
 
@@ -123,17 +125,17 @@ rails generate pu:rodauth:admin admin --extra-attributes=name:string,department:
 | `--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
 ```
 
 **Invite + resend actions.** The admin resource gets two actions:
-- **Invite** — invite a new admin by email; they set their password via the verification link.
-- **Resend invitation** — re-send that verification email, shown only for admins who haven't verified yet.
+- **Invite**: invite a new admin by email; they set their password via the verification link.
+- **Resend invitation**: re-send that verification email, shown only for admins who haven't verified yet.
 
-This is Rodauth account verification — distinct from the tenancy invitation system (see [[plutonium-tenancy]]).
+This is Rodauth account verification, distinct from the tenancy invitation system (see [[plutonium-tenancy]]).
 
 Rake task for direct admin creation (namespace is `rodauth`, task name is the account name):
 
@@ -144,7 +146,7 @@ EMAIL=admin@example.com rails rodauth:admin
 
 Creates the account and sends a verification email; the admin sets their own password through the flow. No password is passed on the command line.
 
-### SaaS setup — `pu:saas:setup` (meta-generator)
+### SaaS setup: `pu:saas:setup` (meta-generator)
 
 Creates the User + Entity + Membership trio AND runs:
 
@@ -207,7 +209,7 @@ class ResourceController < PlutoniumController
 end
 ```
 
-Multiple account types — include the matching `:name`:
+Multiple account types: include the matching `:name`:
 
 ```ruby
 class AdminController < PlutoniumController
@@ -216,7 +218,7 @@ class AdminController < PlutoniumController
 end
 ```
 
-`Plutonium::Auth::Rodauth(:name)` exposes `current_user`, `logout_url`, and `rodauth` in the controller. It also adds a named accessor `current_<name>` aliased to `current_user` — e.g. `Rodauth(:admin)` gives `current_admin`. Read the signed-in account with `current_user` or its named alias (e.g. `current_admin`).
+`Plutonium::Auth::Rodauth(:name)` exposes `current_user`, `logout_url`, and `rodauth` in the controller. It also adds a named accessor `current_<name>` aliased to `current_user`, e.g. `Rodauth(:admin)` gives `current_admin`. Read the signed-in account with `current_user` or its named alias (e.g. `current_admin`).
 
 For portal wiring (`AdminPortal::Concerns::Controller`), see [[plutonium-app]] › Portal controller concern.
 
@@ -224,34 +226,34 @@ For portal wiring (`AdminPortal::Concerns::Controller`), see [[plutonium-app]]
 
 ## Multiple portals in one browser
 
-Each portal authenticates through its own Rodauth configuration, and a person can hold a session in several at once — sign into the admin portal and the customer portal in the same browser without either evicting the other.
+Each portal authenticates through its own Rodauth configuration, and a person can hold a session in several at once: sign into the admin portal and the customer portal in the same browser without either evicting the other.
 
 Two settings make that work, and the generators emit both:
 
 ```ruby
-# app/rodauth/rodauth_plugin.rb — the shared base
+# app/rodauth/rodauth_plugin.rb: the shared base
 configure do
   enable :session_isolation
 end
 
-# app/rodauth/<name>_rodauth_plugin.rb — once per account type
+# app/rodauth/<name>_rodauth_plugin.rb: once per account type
 configure do
   session_key_prefix "admin_"
   remember_cookie_key "_admin_remember"
 end
 ```
 
-🚨 **Both are required.** `session_key_prefix` namespaces every session key a configuration touches — the account id plus `authenticated_by`, `login_redirect`, `two_factor_auth_setup`, … `session_isolation` uses that prefix to decide ownership and stops a login from clearing the other configurations' keys.
+🚨 **Both are required.** `session_key_prefix` namespaces every session key a configuration touches: the account id plus `authenticated_by`, `login_redirect`, `two_factor_auth_setup`, … `session_isolation` uses that prefix to decide ownership and stops a login from clearing the other configurations' keys.
 
-🚨 **Never set `session_key` alongside it.** Explicit values bypass `convert_session_key` (`rodauth/features/base.rb:686`) so they are NOT prefixed — the account id then rotates separately from every other key. A session holding an account id with no `authenticated_by` makes Rodauth raise on every request (`logged_in_via_remember_key?` → `nil.include?`, `remember.rb:175`). A config with no prefix at all is simply not isolated: its keys are the unprefixed defaults, so nothing is carried for it.
+🚨 **Never set `session_key` alongside it.** Explicit values bypass `convert_session_key` (`rodauth/features/base.rb:686`) so they are NOT prefixed, and the account id then rotates separately from every other key. A session holding an account id with no `authenticated_by` makes Rodauth raise on every request (`logged_in_via_remember_key?` → `nil.include?`, `remember.rb:175`). A config with no prefix at all is simply not isolated: its keys are the unprefixed defaults, so nothing is carried for it.
 
-**Why:** Rodauth resets the session on every login — including the `remember` feature's `load_memory` autologin — to defend against session fixation, and rodauth-rails implements that as a full `reset_session`. Without `session_isolation`, signing into one portal wipes every other portal's session; and because `RodauthApp#route` calls `load_memory` for *every* configuration on *every* request, the evicted configuration autologins from its remember cookie on the next request and evicts the new one right back. The last `load_memory` in the route block wins permanently, so the other portal can never hold a session at all.
+**Why:** Rodauth resets the session on every login, including the `remember` feature's `load_memory` autologin, to defend against session fixation, and rodauth-rails implements that as a full `reset_session`. Without `session_isolation`, signing into one portal wipes every other portal's session; and because `RodauthApp#route` calls `load_memory` for *every* configuration on *every* request, the evicted configuration autologins from its remember cookie on the next request and evicts the new one right back. The last `load_memory` in the route block wins permanently, so the other portal can never hold a session at all.
 
 `session_isolation` carries only the *other configurations'* session entries across the reset. The session id is still rotated and application session data is still cleared, so session fixation is still defeated.
 
-**Reading a raw Rodauth session key?** Go through its accessor, never the literal — `session.delete(login_redirect_session_key)`, not `session.delete(:login_redirect)`. With a prefix set, the literal is the wrong key.
+**Reading a raw Rodauth session key?** Go through its accessor, never the literal: `session.delete(login_redirect_session_key)`, not `session.delete(:login_redirect)`. With a prefix set, the literal is the wrong key.
 
-**Upgrading an app generated before this existed:** add `enable :session_isolation` once in the base plugin, add `session_key_prefix` to each account plugin, and **delete any existing `session_key "_x_session"` line**. Every key name changes together, so stale session cookies are simply ignored — the safe outcome. Keeping the old `session_key` to preserve logins is exactly what produces the crashing half-migrated session. Only *unremembered* sessions actually drop: `remember_cookie_key` is a cookie name and is not prefixed, so anyone holding a valid `_x_remember` cookie is restored by `load_memory` on their next request.
+**Upgrading an app generated before this existed:** add `enable :session_isolation` once in the base plugin, add `session_key_prefix` to each account plugin, and **delete any existing `session_key "_x_session"` line**. Every key name changes together, so stale session cookies are simply ignored (the safe outcome). Keeping the old `session_key` to preserve logins is exactly what produces the crashing half-migrated session. Only *unremembered* sessions actually drop: `remember_cookie_key` is a cookie name and is not prefixed, so anyone holding a valid `_x_remember` cookie is restored by `load_memory` on their next request.
 
 ---
 
@@ -376,7 +378,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
@@ -392,9 +394,28 @@ The generator modifies the user model:
 has_one :profile, class_name: "UserProfile", dependent: :destroy
 ```
 
-🚨 The association is **always `:profile`**, regardless of class — `current_user.profile`, `build_profile`, `params.require(:profile)` always work.
+🚨 The association is **always `:profile`**, regardless of class, so `current_user.profile`, `build_profile`, `params.require(:profile)` always work.
 
-The generated definition injects a custom `ShowPage` that renders the `SecuritySection` component.
+If you are reusing a profile model that predates the generator and the user model has a different association name, add the `:profile` one rather than editing `current_user.profile` out of the generated policy and `profile_url`. Keeping the convention means the next `pu:profile:conn` (another portal, a re-run) works unedited. The dummy app's `has_one :user_profile` is a test fixture, not a pattern to copy.
+
+### What `pu:profile:conn` generates in the portal
+
+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 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
+def update?
+  true
+end
+```
+
+Narrowing the editable fields is `permitted_attributes_for_create` / `_for_update` in this portal policy; leave `:user` out.
 
 ### The `SecuritySection` component
 
@@ -412,26 +433,69 @@ Dynamically lists Rodauth security links based on which features are enabled:
 
 To customize the show page (e.g. wrap, reorder), override `ShowPage#render_after_content` (see [[plutonium-ui]] › Page hooks).
 
-### Required: every user gets a 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` (change email / password) 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!
+  after_create :create_profile
+end
+```
+
+and backfill existing users with `User.find_each { |u| u.profile || u.create_profile }`. 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).
+
+### Linking to the profile
 
+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, `link_to("Profile", profile_url) if profile_url`.
+
+### Account features on the profile page
+
+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
+# packages/org_portal/app/definitions/org_portal/user_profile_definition.rb
+class ShowPage < ShowPage
   private
-  def create_profile! = create_profile
+
+  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
 ```
 
-Without this, `current_user.profile` is `nil` and the profile route errors. For existing users at migration time, run a one-off `User.find_each(&:create_profile)`.
+If the profile isn't wired in that portal yet (no `profile_url`), wire it with `pu:profile:conn` first; that is the page users are sent to from the avatar menu.
 
-### Linking to the profile
+The feature resource itself belongs to the user, not the portal's entity, so it follows the same shape `pu:profile:conn` generates for the profile:
+
+```bash
+rails g pu:res:scaffold ApiToken user:belongs_to name:string token_digest:string:uniq 'last_used_at:datetime?' --dest=main_app
+rails g pu:res:conn ApiToken --dest=org_portal --policy
+```
 
 ```ruby
-link_to("Profile", profile_url) if respond_to?(:profile_url)
+# packages/org_portal/app/policies/org_portal/api_token_policy.rb
+relation_scope do |relation|
+  skip_default_relation_scope!
+  relation.where(user: user)
+end
+
+def permitted_attributes_for_create
+  %i[name]
+end
+
+# packages/org_portal/app/controllers/org_portal/api_tokens_controller.rb
+private
+
+def resource_params
+  super.merge(user: current_user)
+end
 ```
 
-`profile_url` only exists when the profile resource is connected via `pu:profile:conn` (which registers it as a singular resource — see [[plutonium-app]] › Routes).
+Use `--policy` so the user-only scope lives in this portal's policy. In an entity-scoped portal the default scope calls `associated_with(entity)`, which raises for a model with no path to the entity; skipping it and filtering by `user` is the intended pattern here, as in the profile policy. Don't invent an `associated_with_<entity>` scope through the user's memberships to satisfy it. Gate per-record actions such as revoke in the policy (see [[plutonium-behavior]]).
 
 ---
 
@@ -439,20 +503,22 @@ link_to("Profile", profile_url) if respond_to?(:profile_url)
 
 - **Role index 0 is the most privileged.** For admin/SaaS roles, index 0 is `owner`/`super_admin`. Generated invite interactions default invitees to index 1.
 - **`owner` is always prepended** by `pu:saas:setup --roles`. Don't include it manually.
-- **Profile association is always `:profile`** — even when the class is `StaffUserProfile`.
-- **`pu:saas:setup` runs four other generators** — don't re-run portal, profile, welcome, or invites separately.
-- **Profile requires `pu:profile:conn`** — without it, no route, no `profile_url`, no menu link.
-- **Users need a profile row.** Add an `after_create` callback (or `find_or_create_by`) — `current_user.profile` is otherwise nil.
-- **Concurrent portal logins need `enable :session_isolation` + `session_key_prefix`.** Missing either and signing into one portal silently evicts the others — see Multiple portals in one browser.
+- **Profile association is always `:profile`**: even when the class is `StaffUserProfile`.
+- **`pu:saas:setup` runs four other generators**: don't re-run portal, profile, welcome, or invites separately.
+- **Profile requires `pu:profile:conn`**: without it, no route, no `profile_url`, no menu link.
+- **Profile is read-only after creation.** The policy predates the generated `update?`; `update?` falls back to the injected `create?` (`user.profile.nil?`). Add `def update? = true`.
+- **Users without a profile row land on the new-profile form.** Not an error; add `after_create :create_profile` plus a backfill if they should land on the show page.
+- **User-owned resources in an entity-scoped portal** use `pu:res:conn --policy` with `skip_default_relation_scope!` + `where(user: user)`, and are linked from the profile show page.
+- **Concurrent portal logins need `enable :session_isolation` + `session_key_prefix`.** Missing either and signing into one portal silently evicts the others; see Multiple portals in one browser.
 - **Never hardcode a Rodauth session key.** Use the accessor (`login_redirect_session_key`), since `session_key_prefix` changes the literal.
-- **"Remember me" is opt-in.** Configs use `after_login { remember_login if param_or_nil(remember_param) == remember_remember_param_value }` and the login form renders the checkbox. Compare against the value, not just presence — a bare truthiness check means `remember=disable` would remember you. Plutonium's form also passes `include_hidden: false` so an unticked box sends nothing — belt-and-braces next to the value comparison, not the thing holding it up.
+- **"Remember me" is opt-in.** Configs use `after_login { remember_login if param_or_nil(remember_param) == remember_remember_param_value }` and the login form renders the checkbox. Compare against the value, not just presence: a bare truthiness check means `remember=disable` would remember you. Plutonium's form also passes `include_hidden: false` so an unticked box sends nothing, which is belt-and-braces next to the value comparison, not the thing holding it up.
 
 ---
 
 ## Related skills
 
-- [[plutonium-app]] — initial install, portal wiring, mounting auth-constrained routes
-- [[plutonium-tenancy]] — invites + memberships for multi-tenant onboarding
-- [[plutonium-behavior]] — policies (auth runs first, policy checks the authenticated user)
-- [[plutonium-resource]] — customizing the profile definition (fields, inputs, displays)
-- [[plutonium-ui]] — overriding the profile's `ShowPage`, theming the security section
+- [[plutonium-app]]: initial install, portal wiring, mounting auth-constrained routes
+- [[plutonium-tenancy]]: invites + memberships for multi-tenant onboarding
+- [[plutonium-behavior]]: policies (auth runs first, policy checks the authenticated user)
+- [[plutonium-resource]]: customizing the profile definition (fields, inputs, displays)
+- [[plutonium-ui]]: overriding the profile's `ShowPage`, theming the security section