plutonium 0.65.0 → 0.66.0

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

data/docs/guides/wizards.md

@@ -1,18 +1,18 @@
 # Wizards
 
 ::: warning Experimental
-Wizards are experimental — the DSL and behavior may change in a future release.
+Wizards are experimental. The DSL and behavior may change in a future release.
 :::
 
-Build multi-step flows — onboarding, checkout, "create several related records across screens", branching questionnaires — as a single declarative Ruby class.
+Build multi-step flows (onboarding, checkout, "create several related records across screens", branching questionnaires) as a single declarative Ruby class.
 
-A wizard collects typed `data` across ordered `step`s, optionally branches with `condition:`, and commits at the end via `execute`. It reuses Plutonium's existing field DSL (`attribute`/`input`/`validates`/`structured_input`/`form_layout`), form rendering, actions, and policies — it does **not** invent a parallel stack.
+A wizard collects typed `data` across ordered `step`s, optionally branches with `condition:`, and commits at the end via `execute`. It reuses Plutonium's existing field DSL (`attribute`/`input`/`validates`/`structured_input`/`form_layout`), form rendering, actions, and policies, it does **not** invent a parallel stack.
 
 ## Goal
 
-The user lands on the first step, fills it in, clicks Next, and walks through the flow. Branching steps appear or disappear based on earlier answers. A built-in review step recaps everything and gates a Finish button. On finish, `execute` writes the records — atomically by default.
+The user lands on the first step, fills it in, clicks Next, and walks through the flow. Branching steps appear or disappear based on earlier answers. A built-in review step recaps everything and gates a Finish button. On finish, `execute` writes the records, atomically by default.
 
-## Prerequisites — enable the subsystem
+## Prerequisites: enable the subsystem
 
 Wizards are core code, but the storage table is **opt-in** so apps that don't use wizards stay schema-clean. Enable it in your Plutonium initializer:
 
@@ -24,7 +24,7 @@ Plutonium.configure do |config|
 end
 ```
 
-Then run the migration (it ships in the gem and runs in place — no copy step):
+Then run the migration (it ships in the gem and runs in place, no copy step):
 
 ```bash
 rails db:migrate
@@ -68,28 +68,28 @@ class CompanyOnboardingWizard < Plutonium::Wizard::Base
 end
 ```
 
-- A wizard is a plain class — `< Plutonium::Wizard::Base`. There is no generator (just like interactions); author it by hand.
+- A wizard is a plain class, `< Plutonium::Wizard::Base`. There is no generator (just like interactions); author it by hand.
 - `presents label:/icon:` sets the launch button's label and icon, exactly like interactions; an optional `description:` renders as the wizard's header subheading.
 - Each `step :key, label: do ... end` is one screen. Inside the block, declare its fields with the same DSL you use on a definition or interaction.
 - `data` is **step-keyed**: `data.company.name` reads the **typed** value entered on the `:company` step (cast to the declared type), available from any step and from `execute`. Each step has its own sub-object, so two steps may use the same field name without colliding.
 - `review` is a built-in terminal step (auto-summary + gated Finish). It must be **last**.
-- `execute` runs once at the end and returns an `Outcome` (`succeed(...)` / `failed(...)`). **Use bang methods** (`create!`/`update!`) — failure is signalled by a raised exception, never a return value.
+- `execute` runs once at the end and returns an `Outcome` (`succeed(...)` / `failed(...)`). **Use bang methods** (`create!`/`update!`); failure is signalled by a raised exception, never a return value.
 
 ::: warning Use bang methods in `execute`
-The engine detects failure by a **raised exception**. Non-bang `create`/`save`/`update` return `false` on failure without raising — the engine can't see that, treats the step as successful, and advances, silently losing the data. Always use `create!`/`update!`/`save!`, or call `fail!("message")`.
+The engine detects failure by a **raised exception**. Non-bang `create`/`save`/`update` return `false` on failure without raising; the engine can't see that, treats the step as successful, and advances, silently losing the data. Always use `create!`/`update!`/`save!`, or call `fail!("message")`.
 :::
 
 ::: tip `execute` is a presentation boundary, same as an interaction's
-A wizard is built with `view_context:` too, so everything reachable only through `execute` is reachable only from a wizard run. Steps and `execute` own the *flow* — which screens, in what order, writing what. What the write **means** belongs on the model as soon as a second caller wants it: the API signup that skips onboarding, the admin backfill, the importer. `Company.create!(...)` inline is fine for a one-off; `Company.onboard!(...)` is what you reach for when it isn't. See [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for) — the rule is identical.
+A wizard is built with `view_context:` too, so everything reachable only through `execute` is reachable only from a wizard run. Steps and `execute` own the *flow*: which screens, in what order, writing what. What the write **means** belongs on the model as soon as a second caller wants it: the API signup that skips onboarding, the admin backfill, the importer. `Company.create!(...)` inline is fine for a one-off; `Company.onboard!(...)` is what you reach for when it isn't. See [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for), the rule is identical.
 :::
 
 Each step renders as a focused card with a numbered stepper rail (the terminal `review` shows a finish flag, not a number) and a Back / Next / Cancel strip:
 
-![A wizard step page — numbered stepper rail, a focused step card with typed inputs, and Back/Next/Cancel navigation](/images/guides/wizards-step.png)
+![A wizard step page: numbered stepper rail, a focused step card with typed inputs, and Back/Next/Cancel navigation](/images/guides/wizards-step.png)
 
 ## Branching with `condition:`
 
-A step's `condition:` lambda decides whether the step is included. Branching is **subtractive** — a falsy `condition:` removes the step from the visible path.
+A step's `condition:` lambda decides whether the step is included. Branching is **subtractive**: a falsy `condition:` removes the step from the visible path.
 
 ```ruby
 step :plan, label: "Plan" do
@@ -107,17 +107,17 @@ end
 ```
 
 ::: warning `condition:` lambdas must be nil-safe
-A `condition:` runs against the typed `data` snapshot at **every** transition — including before its deciding step has been filled, when the value is still `nil`. `-> { data.plan.plan == "pro" }` is fine (`nil == "pro"` is `false`); `-> { data.plan.plan.upcase == "PRO" }` raises on `nil`. Always write conditions that tolerate `nil`.
+A `condition:` runs against the typed `data` snapshot at **every** transition, including before its deciding step has been filled, when the value is still `nil`. `-> { data.plan.plan == "pro" }` is fine (`nil == "pro"` is `false`); `-> { data.plan.plan.upcase == "PRO" }` raises on `nil`. Always write conditions that tolerate `nil`.
 :::
 
 The condition can also read `anchor` (for [anchored wizards](#anchored-wizards)). Data belonging to branch-hidden steps is pruned before `execute`, so `execute` only ever sees data for steps that actually applied.
 
-## Reusing a model's fields — `using:`
+## Reusing a model's fields: `using:`
 
 Instead of re-declaring fields a model already defines, import them with `using:`. It is a **step option** (not a block method), and it targets a **model (record class) only**.
 
 ```ruby
-# Whole-step import — no block needed.
+# Whole-step import, no block needed.
 step :branding, label: "Branding", using: Company, fields: %i[logo brand_color]
 
 # Mix imported + wizard-local fields: using: plus a block for the extras.
@@ -130,13 +130,13 @@ end
 What `using:` imports from the model:
 
 - **Field universe + types** from `Model.attribute_names` / `Model.attribute_types`. Selectors `fields:` (alias `only:`) and `except:` pick a subset.
-- **Input styling** overlaid from the auto-resolved `<Model>Definition` (its `as:`, options, labels) — best-effort; no definition found is fine.
+- **Input styling** overlaid from the auto-resolved `<Model>Definition` (its `as:`, options, labels), best-effort; no definition found is fine.
 - **Validations** run via a transient `Model.new(slice).valid?`, keeping errors on the imported fields plus `:base`. Pass `validate: false` to skip and write your own inline `validates`.
 - **`form_layout`** inherited from the `<Model>Definition` (filtered to imported fields). Pass `layout: false` to opt out.
 
-`using:` is **declaration reuse only** — it never pulls in the model's persistence or callbacks. Data still stages into `data`; your `execute` does the writes. Full detail: [DSL reference › `using:`](/reference/wizard/dsl#using-a-model).
+`using:` is **declaration reuse only**: it never pulls in the model's persistence or callbacks. Data still stages into `data`; your `execute` does the writes. Full detail: [DSL reference › `using:`](/reference/wizard/dsl#using-a-model).
 
-## Sectioning a step — `form_layout`
+## Sectioning a step: `form_layout`
 
 A step is its own form, so you can group its fields with the same `form_layout` DSL you use on a definition, scoped to that step:
 
@@ -175,11 +175,11 @@ end
 
 Repeater rows rehydrate from staged `data` on GET, so navigating back (or resuming) re-renders the rows you already filled.
 
-![A structured/repeater step — multiple invite rows with Add/Remove, inside the wizard step card](/images/guides/wizards-repeater.png)
+![A structured/repeater step: multiple invite rows with Add/Remove, inside the wizard step card](/images/guides/wizards-repeater.png)
 
 ## File uploads (attachments)
 
-A step can collect a file. You declare it like any other field — a **`:string`** attribute (it holds the upload **token**, not the bytes) plus a file input:
+A step can collect a file. You declare it like any other field: a **`:string`** attribute (it holds the upload **token**, not the bytes) plus a file input:
 
 ```ruby
 step :photo, label: "Photo" do
@@ -188,7 +188,7 @@ step :photo, label: "Photo" do
 end
 ```
 
-A wizard stages its `data` as JSON across several requests, so a file can't ride along — only a **token** does. The field stages the backend's upload token (an ActiveStorage signed_id, or active_shrine/Shrine cached-file data); your `execute` assigns that token to the model's attachment, which both backends accept natively:
+A wizard stages its `data` as JSON across several requests, so a file can't ride along, only a **token** does. The field stages the backend's upload token (an ActiveStorage signed_id, or active_shrine/Shrine cached-file data); your `execute` assigns that token to the model's attachment, which both backends accept natively:
 
 ```ruby
 def execute
@@ -199,19 +199,19 @@ def execute
 end
 ```
 
-The review summary and the step's preview (when you go Back or resume) render the file for you — reading `data.photo.photo` resolves the token to a displayable attachment automatically.
+The review summary and the step's preview (when you go Back or resume) render the file for you; reading `data.photo.photo` resolves the token to a displayable attachment automatically.
 
 ### Server-side vs direct upload
 
 The same field works two ways:
 
-- **Server-side (default)** — `input :photo, as: :file`. The file is submitted with the step (a plain file input) and the wizard uploads it to the backend's cache while staging. Nothing else to wire up; works for both ActiveStorage and active_shrine.
-- **Direct upload** — `input :photo, as: :uppy, direct_upload: true, endpoint: "/upload"`. The browser uploads straight to the endpoint (with a progress UI) and posts back a token. Use this for large files or an async UX; it needs the backend's direct-upload endpoint reachable (ActiveStorage's direct uploads, or Shrine's `upload_endpoint`).
+- **Server-side (default)**: `input :photo, as: :file`. The file is submitted with the step (a plain file input) and the wizard uploads it to the backend's cache while staging. Nothing else to wire up; works for both ActiveStorage and active_shrine.
+- **Direct upload**: `input :photo, as: :uppy, direct_upload: true, endpoint: "/upload"`. The browser uploads straight to the endpoint (with a progress UI) and posts back a token. Use this for large files or an async UX; it needs the backend's direct-upload endpoint reachable (ActiveStorage's direct uploads, or Shrine's `upload_endpoint`).
 
 ::: tip Match the backend to the model
-In server-side mode the backend defaults to `config.wizards.attachment_backend` — auto-detected as Shrine when active_shrine is installed, else ActiveStorage. Override per field with `backend:` (`input :photo, as: :file, backend: :active_storage`). It must match the model your `execute` assigns to: an ActiveStorage model can't accept a Shrine token, and vice-versa.
+In server-side mode the backend defaults to `config.wizards.attachment_backend`, auto-detected as Shrine when active_shrine is installed, else ActiveStorage. Override per field with `backend:` (`input :photo, as: :file, backend: :active_storage`). It must match the model your `execute` assigns to: an ActiveStorage model can't accept a Shrine token, and vice-versa.
 
-For Shrine, you can also cache through a specific uploader — `input :photo, as: :file, backend: :shrine, uploader: PhotoUploader` — so that uploader's cache-stage plugins (mime/dimension extraction, `generate_location`, processing) run while staging. The minted token stays uploader-agnostic, so display and `execute` promotion are unchanged. That uploader's **validations are enforced on the step** too: a file that violates them is rejected right there with a field error (validated against the field's effective uploader — its `uploader:`, or base `Shrine`), rather than slipping through to `execute`.
+For Shrine, you can also cache through a specific uploader, `input :photo, as: :file, backend: :shrine, uploader: PhotoUploader`, so that uploader's cache-stage plugins (mime/dimension extraction, `generate_location`, processing) run while staging. The minted token stays uploader-agnostic, so display and `execute` promotion are unchanged. That uploader's **validations are enforced on the step** too: a file that violates them is rejected right there with a field error (validated against the field's effective uploader, its `uploader:`, or base `Shrine`), rather than slipping through to `execute`.
 :::
 
 For **multiple** files, use an array attribute with `multiple: true`; the staged value is then an array of tokens. A staged-but-abandoned upload (cancel/sweep) is an unattached blob / cached file that each storage backend's own cleanup reaps.
@@ -224,7 +224,7 @@ For **multiple** files, use an array attribute with `multiple: true`; the staged
 - Lists invalid/unvisited visible steps as "fix this" jump links.
 - Disables Finish until all visible steps are valid; clicking it runs `execute`.
 
-![The review step — a grouped auto-summary of every step's data with per-step Edit links and a gated Finish](/images/guides/wizards-review.png)
+![The review step: a grouped auto-summary of every step's data with per-step Edit links and a gated Finish](/images/guides/wizards-review.png)
 
 ```ruby
 review label: "Review & submit"
@@ -245,9 +245,9 @@ review summary: false, header: false   # no header, no summary → "ready to com
 
 See the [DSL reference](/reference/wizard/dsl#review) for the complete state table.
 
-## Per-step writes — `on_submit` / `persist` / `on_rollback`
+## Per-step writes: `on_submit` / `persist` / `on_rollback`
 
-`execute` is the default — atomic, no orphans. Reach for per-step `on_submit` **only** when a real record must exist mid-flow (handing off to an external system that webhooks back, a reviewer who must see partial data, a payload too large for the session row).
+`execute` is the default: atomic, no orphans. Reach for per-step `on_submit` **only** when a real record must exist mid-flow (handing off to an external system that webhooks back, a reviewer who must see partial data, a payload too large for the session row).
 
 ```ruby
 class ConfigureCompanyWizard < Plutonium::Wizard::Base
@@ -268,7 +268,7 @@ class ConfigureCompanyWizard < Plutonium::Wizard::Base
     end
 
     # ADDITIONAL cleanup on Cancel/abandonment. The engine ALWAYS destroys the
-    # persist'd Billing record — on_rollback is only for side effects it can't see
+    # persist'd Billing record; on_rollback is only for side effects it can't see
     # (here, refunding the external charge). It runs BEFORE the destroy, so
     # persisted[:billing] is still alive to read.
     on_rollback { PaymentApi.refund!(persisted[:billing].charge_id) }
@@ -281,11 +281,11 @@ class ConfigureCompanyWizard < Plutonium::Wizard::Base
 end
 ```
 
-- `on_submit` runs in its own transaction when the step completes. Inside it, `persist record` registers record(s) the engine tracks for resume and cleanup — reachable later as `persisted[:step_key]`.
+- `on_submit` runs in its own transaction when the step completes. Inside it, `persist record` registers record(s) the engine tracks for resume and cleanup, reachable later as `persisted[:step_key]`.
 - `fail!("msg")` aborts the step with a base (form-level) error; `fail!(:field, "msg")` attaches it to a field. Both roll back the step's transaction and re-render with input intact.
 - The engine **always** destroys every `persist`'d record on rollback (Cancel, abandonment-sweep, branch-prune), in reverse order, via `destroy!` (which respects a model's own soft-delete override). `on_rollback` is an **optional, additive** compensating block for side effects the engine can't see (refund a charge, call an external API), and runs **before** the destroy, so `persisted[:key]` is still alive inside it. Don't destroy the tracked record yourself; the engine does.
-- Because `on_submit` writes mid-flow, it isn't atomic across steps — that's why `cleanup_after` + the SweepJob exist. See [Storage & config](/reference/wizard/storage-config) and the [DSL reference](/reference/wizard/dsl#per-step-hooks).
-- `on_submit` / `on_rollback` are **wizard-flow hooks**, not a home for domain logic. They belong to a single wizard step and can't be called from anywhere else, so keep them to *when* and *what gets tracked* — `persist Billing.create!(...)` above is one call to a model. Once "authorize a card and record the billing row" is something the API also does, it becomes `Billing.authorize!(company:, token:)` and the hook shrinks to `persist Billing.authorize!(...)`.
+- Because `on_submit` writes mid-flow, it isn't atomic across steps; that's why `cleanup_after` + the SweepJob exist. See [Storage & config](/reference/wizard/storage-config) and the [DSL reference](/reference/wizard/dsl#per-step-hooks).
+- `on_submit` / `on_rollback` are **wizard-flow hooks**, not a home for domain logic. They belong to a single wizard step and can't be called from anywhere else, so keep them to *when* and *what gets tracked*: `persist Billing.create!(...)` above is one call to a model. Once "authorize a card and record the billing row" is something the API also does, it becomes `Billing.authorize!(company:, token:)` and the hook shrinks to `persist Billing.authorize!(...)`.
 
 ## Anchored wizards
 
@@ -305,7 +305,7 @@ end
 ```
 
 - `anchored with: Company` → a single type. `anchored with: [Company, Organization]` → polymorphic. `anchored` (no `with:`) → generic, bound at registration.
-- `anchor` raises `Plutonium::Wizard::NotAnchoredError` if the wizard wasn't declared `anchored` — it never returns `nil`.
+- `anchor` raises `Plutonium::Wizard::NotAnchoredError` if the wizard wasn't declared `anchored`; it never returns `nil`.
 - Omit `anchored` for a pure create flow (the wizard creates the records it names itself).
 
 See [Anchoring & resume](/reference/wizard/anchoring-resume).
@@ -332,12 +332,12 @@ class WelcomeWizard < Plutonium::Wizard::Base
   def execute
     # User#complete_onboarding! sets the name and stamps onboarded_at. It lives on
     # the model because the gate below, an admin backfill, and the invite-accept
-    # flow all need to mark a user onboarded — and none of them is a wizard.
+    # flow all need to mark a user onboarded, and none of them is a wizard.
     current_user.complete_onboarding!(full_name: data.profile.full_name)
     succeed.with_message("Welcome aboard!")
   end
 
-  # Standalone wizards have no resource policy — gate entry with `authorize?`.
+  # Standalone wizards have no resource policy; gate entry with `authorize?`.
   def authorize?
     current_user.present?
   end
@@ -357,15 +357,15 @@ end
 
 An un-completed user hitting the gate is redirected into the wizard (their destination stashed); on completion they're bounced back (PRG). Completed users pass straight through. Re-opening a finished one-time wizard renders an "already completed" page (override its body with a `completed do |wizard| … end` block) rather than re-running it:
 
-![The "already completed" page for a re-opened one-time wizard — a success badge, the wizard's label, and a Continue button](/images/guides/wizards-completed.png)
+![The "already completed" page for a re-opened one-time wizard: a success badge, the wizard's label, and a Continue button](/images/guides/wizards-completed.png)
 
 See [One-time wizards](/reference/wizard/one-time).
 
 ## Registration & launch
 
-A wizard reaches a user as a **resource action** (the `wizard` macro) or a **route-mounted entry** (`register_wizard`) — inside a portal, or on the main app. A portal mount inherits the portal's auth, tenant scoping, layout, and rendering; a main-app mount runs standalone.
+A wizard reaches a user as a **resource action** (the `wizard` macro) or a **route-mounted entry** (`register_wizard`), inside a portal or on the main app. A portal mount inherits the portal's auth, tenant scoping, layout, and rendering; a main-app mount runs standalone.
 
-### On a resource — the `wizard` macro
+### On a resource: the `wizard` macro
 
 Register a wizard on a resource definition. Placement follows `anchored?` automatically: an anchored wizard becomes a **record** action (the show page *and* each index row, like `edit`/`destroy`); a non-anchored wizard becomes a collection-level **resource** action.
 
@@ -376,13 +376,13 @@ class CompanyDefinition < Plutonium::Resource::Definition
 end
 ```
 
-![A resource index — each row carries the anchored wizard's launch action (Show · Edit · Configure widget · ⋮)](/images/guides/wizards-index-action.png)
+![A resource index: each row carries the anchored wizard's launch action (Show · Edit · Configure widget · ⋮)](/images/guides/wizards-index-action.png)
 
-The anchor resolves through the resource controller's scoped, policy-gated `resource_record!` (IDOR-safe — an out-of-scope or missing id 404s), and the action is gated by a policy predicate named after the wizard key (`def configure? = update?`). For placement flags, routes, and the full option list see [Registration & launch › the `wizard` macro](/reference/wizard/registration-launch#on-a-resource-the-wizard-macro).
+The anchor resolves through the resource controller's scoped, policy-gated `resource_record!` (IDOR-safe: an out-of-scope or missing id 404s), and the action is gated by a policy predicate named after the wizard key (`def configure? = update?`). For placement flags, routes, and the full option list see [Registration & launch › the `wizard` macro](/reference/wizard/registration-launch#on-a-resource-the-wizard-macro).
 
-### Route-mounted — `register_wizard`
+### Route-mounted: `register_wizard`
 
-For a wizard not tied to a single resource (onboarding, welcome, set-up), mount it alongside `register_resource` — in a portal engine's routes or on the main app:
+For a wizard not tied to a single resource (onboarding, welcome, set-up), mount it alongside `register_resource`, in a portal engine's routes or on the main app:
 
 ```ruby
 # packages/admin_portal/config/routes.rb
@@ -394,17 +394,17 @@ end
 
 This draws the step routes within the host and gives you an `onboarding_wizard_path` helper. See [Registration & launch › `register_wizard`](/reference/wizard/registration-launch#route-mounted-register_wizard) for `at:`/`as:`/`public:`/`layout:`, the per-host layout defaults, and the controller override hook.
 
-::: danger Portal-level wizards are open to any authenticated user by default
-A `register_wizard` wizard has no resource policy and **defaults to allowed** — any authenticated portal user can run it. Always define `def authorize?` for anything privileged. (Resource-mounted wizards are gated by their action's policy predicate instead.)
+::: danger `register_wizard` wizards are open to any authenticated user by default
+A `register_wizard` wizard (portal or main-app) has no resource policy and its default is `def authorize? = true`, so any authenticated user of that host can run it. Define `def authorize?` on every `register_wizard` wizard, including a gated `one_time` one (the gate forces users into the wizard but doesn't decide who may run it). Resource-mounted wizards are also gated by their action's policy predicate.
 :::
 
 ::: tip Authenticated main-app wizards: define your own controller
-A portal mount inherits the portal's auth; a bare main-app mount has no `current_user`. An authenticated main-app wizard therefore needs you to define `::WizardsController` yourself (`include Plutonium::Wizard::Controller` + your auth concern) — the same "app owns the controller" contract as `register_resource`. See [Hosting & the controller override hook](/reference/wizard/registration-launch#hosting-the-controller-override-hook).
+A portal mount inherits the portal's auth; a bare main-app mount has no `current_user`. An authenticated main-app wizard therefore needs you to define `::WizardsController` yourself (`include Plutonium::Wizard::Controller` + your auth concern), the same "app owns the controller" contract as `register_resource`. See [Hosting & the controller override hook](/reference/wizard/registration-launch#hosting-the-controller-override-hook).
 :::
 
 ### Guest (unauthenticated) wizards
 
-Wizards require authentication by default — and every resume is **owner-scoped**, so a run id leaked in a URL can't be picked up by another user. Opt into pre-login access with the `anonymous` macro and mount it `public: true` (the default for `anonymous`). A guest run's identity is a server-minted id held in the **Rails session** (never a URL, no leak surface); it may authenticate only at its terminal `execute` (e.g. a signup that creates the account and logs in):
+Wizards require authentication by default, and every resume is **owner-scoped**, so a run id leaked in a URL can't be picked up by another user. Opt into pre-login access with the `anonymous` macro and mount it `public: true` (the default for `anonymous`). A guest run's identity is a server-minted id held in the **Rails session** (never a URL, no leak surface); it may authenticate only at its terminal `execute` (e.g. a signup that creates the account and logs in):
 
 ```ruby
 class GuestSignupWizard < Plutonium::Wizard::Base
@@ -429,7 +429,7 @@ Full detail (owner-scoping, session-keying, the synthesized public controller):
 
 ### Listing in-progress & resume-or-new
 
-Build a "continue where you left off" dashboard with `Plutonium::Wizard.in_progress_for(view_context)` — it derives the owner, tenant scope, and portal from the view context and returns that user's in-progress runs for the current portal, each carrying `label` / `icon` / `current_step` / `updated_at` / `resume_url`:
+Build a "continue where you left off" dashboard with `Plutonium::Wizard.in_progress_for(view_context)`, it derives the owner, tenant scope, and portal from the view context and returns that user's in-progress runs for the current portal, each carrying `label` / `icon` / `current_step` / `updated_at` / `resume_url`:
 
 ```ruby
 Plutonium::Wizard.in_progress_for(view_context).each do |entry|
@@ -440,16 +440,16 @@ end
 Plutonium::Wizard.in_progress_for(view_context, wizard: ConfigureCompanyWizard, anchor: @company).first
 ```
 
-A **tokened** wizard (no `concurrency_key`) doesn't silently fork on relaunch — by default it shows a resume-or-new chooser when a pending run exists (`on_relaunch :new` opts out). Keyed and guest wizards auto-resume their single run.
+A **tokened** wizard (no `concurrency_key`) doesn't silently fork on relaunch; by default it shows a resume-or-new chooser when a pending run exists (`on_relaunch :new` opts out). Keyed and guest wizards auto-resume their single run.
 
-![The resume-or-new chooser — pending runs with their current step and a Resume button, plus a Start new action](/images/guides/wizards-chooser.png)
+![The resume-or-new chooser: pending runs with their current step and a Resume button, plus a Start new action](/images/guides/wizards-chooser.png)
 
 See [Anchoring & resume › Listing](/reference/wizard/anchoring-resume#listing-in-progress-wizards) for the full entry fields, portal-scoping rules, `resume_unresolved_reason`, and the filter performance notes.
 
 ## Where to go next
 
-- [DSL reference](/reference/wizard/dsl) — every macro and accessor.
-- [Anchoring & resume](/reference/wizard/anchoring-resume) — anchors, instance keys, resume.
-- [Storage & config](/reference/wizard/storage-config) — the table, config, encryption, the sweep.
-- [Registration & launch](/reference/wizard/registration-launch) — the `wizard` macro, `register_wizard`, routes.
-- [One-time wizards](/reference/wizard/one-time) — completion markers + the gate.
+- [DSL reference](/reference/wizard/dsl): every macro and accessor.
+- [Anchoring & resume](/reference/wizard/anchoring-resume): anchors, instance keys, resume.
+- [Storage & config](/reference/wizard/storage-config): the table, config, encryption, the sweep.
+- [Registration & launch](/reference/wizard/registration-launch): the `wizard` macro, `register_wizard`, routes.
+- [One-time wizards](/reference/wizard/one-time): completion markers + the gate.

data/docs/reference/app/generators.md

@@ -15,7 +15,7 @@ Plutonium's `pu:*` CLI generators. Discoverable via `rails g pu:<tab>`. Always p
 | [`pu:rodauth:install`](#pu-rodauth-install) | Install Rodauth base |
 | [`pu:rodauth:account`](#pu-rodauth-account) | Basic Rodauth account |
 | [`pu:rodauth:admin`](#pu-rodauth-admin) | Hardened admin account (2FA, lockout, audit) |
-| [`pu:saas:setup`](#pu-saas-setup) | **Meta** — user + entity + membership + portal + profile + welcome + invites |
+| [`pu:saas:setup`](#pu-saas-setup) | **Meta**: user + entity + membership + portal + profile + welcome + invites |
 | [`pu:saas:user`](#individual-saas-generators) | Individual: SaaS user account |
 | [`pu:saas:entity`](#individual-saas-generators) | Individual: entity model |
 | [`pu:saas:membership`](#individual-saas-generators) | Individual: membership join model |
@@ -23,7 +23,7 @@ Plutonium's `pu:*` CLI generators. Discoverable via `rails g pu:<tab>`. Always p
 | [`pu:saas:welcome`](#individual-saas-generators) | Individual: onboarding / select-entity flow |
 | [`pu:saas:api_client`](#pu-saas-api-client) | API client for M2M auth |
 | [`pu:profile:install`](#pu-profile-install) | Profile resource + security section |
-| [`pu:profile:setup`](#pu-profile-setup) | Meta — `pu:profile:install` + `pu:profile:conn` |
+| [`pu:profile:setup`](#pu-profile-setup) | Meta: `pu:profile:install` + `pu:profile:conn` |
 | [`pu:profile:conn`](#pu-profile-conn) | Connect profile to a portal as a singular resource |
 | [`pu:invites:install`](#pu-invites-install) | User invitations package |
 | [`pu:invites:invitable`](#pu-invites-invitable) | Mark a model as invitable |
@@ -52,11 +52,11 @@ rails g pu:res:scaffold Post user:belongs_to title:string 'content:text?' --dest
 
 | Option | Description |
 |---|---|
-| `--dest=NAME` | Destination package (`main_app` or `<package>`) — required for unattended runs |
+| `--dest=NAME` | Destination package (`main_app` or `<package>`), required for unattended runs |
 | `--no-model` | Skip model file (for existing models) |
 | `--no-migration` | Skip migration (use with `--no-model` for existing schema) |
 
-Field type syntax — full reference in [Resource › Model](/reference/resource/model). Quick recap:
+Field type syntax: full reference in [Resource › Model](/reference/resource/model). Quick recap:
 
 ```bash
 'name:string'              # required string
@@ -98,7 +98,7 @@ See [Portals › Connecting resources](./portals#connecting-resources-pu-res-con
 
 ### `pu:pkg:package`
 
-Feature package — models, policies, definitions, interactions.
+Feature package: models, policies, definitions, interactions.
 
 ```bash
 rails g pu:pkg:package blogging
@@ -108,7 +108,7 @@ See [Packages › Feature packages](./packages#feature-packages).
 
 ### `pu:pkg:portal`
 
-Portal package — controllers, views, routes, auth.
+Portal package: controllers, views, routes, auth.
 
 ```bash
 rails g pu:pkg:portal admin --auth=user
@@ -122,7 +122,7 @@ rails g pu:pkg:portal admin --auth=admin --scope=Organization
 | `--byo` | Bring your own auth |
 | `--scope=CLASS` | Entity class for multi-tenancy |
 
-See [Portals › Creating a portal](./portals#creating-a-portal).
+The generator also mounts the engine at `/<name>` in `packages/<name>_portal/config/routes.rb`. Don't mount it again in `config/routes.rb`; edit `at:` there to change the path. See [Portals › Mounting](./portals#mounting).
 
 ---
 
@@ -130,7 +130,7 @@ See [Portals › Creating a portal](./portals#creating-a-portal).
 
 ### `pu:rodauth:install`
 
-Install the Rodauth base — Roda app, base plugin, controller, layout, PostgreSQL extension migration.
+Install the Rodauth base: Roda app, base plugin, controller, layout, PostgreSQL extension migration.
 
 ```bash
 rails g pu:rodauth:install
@@ -151,7 +151,7 @@ For full option tables (features, defaults, individual feature flags) see [Auth
 
 ### `pu:rodauth:admin`
 
-Hardened admin account — pre-configured with multi-phase login, required TOTP, recovery codes, lockout, active sessions, audit logging, role-based access, invite interaction, and **no public signup**.
+Hardened admin account: pre-configured with multi-phase login, required TOTP, recovery codes, lockout, active sessions, audit logging, role-based access, invite interaction, and **no public signup**.
 
 ```bash
 rails g pu:rodauth:admin admin
@@ -196,7 +196,7 @@ rails g pu:saas:setup --user Customer --entity Organization \
 | `--user=NAME` | (required) | User account model name |
 | `--entity=NAME` | (required) | Entity model name |
 | `--allow-signup` | `true` | Allow public registration |
-| `--roles` | `admin,member` | Additional roles — **`owner` always prepended as index 0** |
+| `--roles` | `admin,member` | Additional roles: **`owner` always prepended as index 0** |
 | `--skip-entity` | | Skip entity model generation |
 | `--skip-membership` | | Skip membership model generation |
 | `--user-attributes` | | Additional user model attributes |
@@ -271,7 +271,7 @@ rails g pu:profile:install AccountSettings bio:text --dest=main_app   # custom r
 
 ### `pu:profile:setup`
 
-Meta — runs `pu:profile:install` + `pu:profile:conn` in one shot.
+Meta: runs `pu:profile:install` + `pu:profile:conn` in one shot.
 
 ```bash
 rails g pu:profile:setup date_of_birth:date bio:text \
@@ -281,7 +281,7 @@ rails g pu:profile:setup date_of_birth:date bio:text \
 
 ### `pu:profile:conn`
 
-Connect the profile resource to a portal as a **singular** resource (registers `/profile` and the `profile_url` helper).
+Connect the profile resource to a portal as a **singular** resource (registers `/profile` and overrides the `profile_url` helper in the portal's controller concern). It also generates a user-scoped portal policy (`create? = user.profile.nil?`, `update? = true`, `destroy? = false`) and a `ShowPage` that renders the `SecuritySection`. See [Auth › Profile](/reference/auth/profile#what-pu-profile-conn-generates).
 
 ```bash
 rails g pu:profile:conn --dest=customer_portal
@@ -310,7 +310,7 @@ rails g pu:invites:install --entity-model=Organization --user-model=Customer --i
 | `--enforce-domain` | `false` | Require email domain to match entity |
 | `--dest=PACKAGE` | `main_app` | Package where the entity model lives (controls where `invite_user_interaction.rb` is generated) |
 
-Multiple invite flows are supported — run `pu:invites:install` once per flow.
+Multiple invite flows are supported; run `pu:invites:install` once per flow.
 
 ### `pu:invites:invitable`
 
@@ -398,7 +398,7 @@ rails g pu:test:install
 
 ### `pu:test:scaffold`
 
-Scaffold integration tests — one file per (resource × portal) pairing.
+Scaffold integration tests: one file per (resource × portal) pairing.
 
 ```bash
 rails g pu:test:scaffold Blogging::Post --portals=admin,org
@@ -432,7 +432,7 @@ rails g pu:skills:sync
 ### Full app setup
 
 ```bash
-# 1. Plutonium template (greenfield) — does all initial setup
+# 1. Plutonium template (greenfield): does all initial setup
 rails new myapp -a propshaft -j esbuild -c tailwind \
   -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
 
@@ -505,13 +505,13 @@ Generators run from Rails root. Package names are case-sensitive.
 
 ### Migration already exists
 
-If a migration with the same timestamp exists, wait a second and retry — Rails generates timestamps to one-second resolution.
+If a migration with the same timestamp exists, wait a second and retry; Rails generates timestamps to one-second resolution.
 
 ## Related
 
-- [Packages](./packages) — feature vs portal package structure
-- [Portals](./portals) — portal configuration and resource connection
-- [Resource › Model](/reference/resource/model) — field-type syntax for `pu:res:scaffold`
-- [Auth](/reference/auth/) — account type configuration
-- [Tenancy](/reference/tenancy/) — multi-tenancy and invitations
-- [Testing](/reference/testing/) — test scaffolding
+- [Packages](./packages): feature vs portal package structure
+- [Portals](./portals): portal configuration and resource connection
+- [Resource › Model](/reference/resource/model): field-type syntax for `pu:res:scaffold`
+- [Auth](/reference/auth/): account type configuration
+- [Tenancy](/reference/tenancy/): multi-tenancy and invitations
+- [Testing](/reference/testing/): test scaffolding