plutonium 0.60.5 → 0.61.0

data/docs/superpowers/specs/2026-06-15-wizard-dsl-examples.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+#
+# Sample wizards illustrating the Plutonium::Wizard DSL.
+# Companion to docs/superpowers/specs/2026-06-15-wizard-dsl-design.md.
+# Illustrative only — the subsystem isn't built yet, so this won't load/run.
+#
+# ── DSL cheatsheet ───────────────────────────────────────────────────────────
+#   presents label:/icon:        chrome (button label + icon), like interactions
+#   navigation :linear|:free     stepper navigation policy (default :linear)
+#   anchored with: Model         wizard runs against an existing record (URL :id); read via `anchor`
+#   anchored via: :method        context anchor resolved by a controller method (portal-level)
+#   concurrency_key { … }        key a run (tenant folded in); keyed in_progress row is the lock
+#   one_time                     retain the completed row at the key → run once (needs concurrency_key)
+#   cleanup_after 7.days|:never   idle TTL before abandoned sessions are swept
+#   anonymous                    opt into guest (unauthenticated) access; mount public: true.
+#                                auth is REQUIRED by default; authed lookups are owner-scoped.
+#                                a guest wizard may authenticate ONLY at its terminal execute.
+#   def authorize?              entry gate for portal-level wizards (no resource policy)
+#   step :key, label:, condition:, using:  do ... end   one screen (block declares its
+#                                fields/hooks); condition: gates it (branching). The block
+#                                is optional only when `using:` supplies everything.
+#     attribute/input/validates/structured_input/form_layout  the existing field DSL (in the block)
+#     on_submit { ... }          OPTIONAL per-step write hook (save-as-you-go)
+#       persist record           inside on_submit: register record(s) → persisted[:key]
+#       fail!("msg")             abort the step with an error (sugar over StepError)
+#     on_rollback { ... }        OPTIONAL extra cleanup of untracked side effects on cancel/abandon
+#                                (persist'd records are ALWAYS destroyed by the engine regardless)
+#   review label:                terminal step: auto-summary + gated Finish
+#   def execute                  at-end hook; returns succeed(...) / failed(...) (an Outcome)
+#   data.<step>.<field>          step-keyed, typed snapshot (e.g. data.company.name);
+#                                two steps may share a field name without colliding
+#   anchor / persisted[:key]     the launched-against record / records created via persist
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 1. Create flow — execute-only, multi-model, branching.
+#    Nothing is written until the end; `execute` does all writes in one
+#    transaction. Branching is subtractive via `condition:` (nil-safe).
+# ─────────────────────────────────────────────────────────────────────────────
+class CompanyOnboardingWizard < Plutonium::Wizard::Base
+  # `presents` sets the launch button's label + icon (same as interactions).
+  presents label: "Onboard a company", icon: Phlex::TablerIcons::BuildingSkyscraper
+
+  # Stepper behaviour. :linear = forward + back to visited steps (default).
+  navigation :linear
+
+  # A `step` is one screen. The block declares its fields with the existing
+  # field DSL (attribute = typed data, input = how it renders, validates = rules).
+  step :company, label: "Company details" do
+    attribute :name, :string
+    attribute :subdomain, :string
+    input :name
+    input :subdomain
+    validates :name, :subdomain, presence: true
+
+    # Optional: section THIS step's fields (reuses form_layout, scoped to the step).
+    form_layout do
+      section :identity, :name, :subdomain, label: "Identity", columns: 2
+    end
+  end
+
+  step :plan, label: "Plan" do
+    attribute :plan, :string
+    input :plan, as: :radio_buttons, choices: %w[free pro]
+    validates :plan, presence: true
+  end
+
+  # `condition:` decides whether this step is included (subtractive branching).
+  # It runs against the step-keyed `data` snapshot; `data.plan.plan` is nil until
+  # the plan step is filled, and `nil == "pro"` is false — so it must be nil-safe.
+  step :billing, label: "Billing", condition: -> { data.plan.plan == "pro" } do
+    attribute :card_token, :string
+    input :card_token
+    validates :card_token, presence: true
+  end
+
+  step :team, label: "Invite your team" do
+    # `structured_input ..., repeat:` = a repeatable group of sub-fields.
+    # Reachable later as data.team.invites (an array of typed sub-objects).
+    structured_input :invites, repeat: 5 do |f|
+      f.input :email, as: :email
+      f.input :role, as: :select, choices: %w[admin member]
+    end
+  end
+
+  # `review` is a built-in terminal step: auto-summarises everything entered and
+  # gates the Finish button until all visible steps are valid. Must be last.
+  review label: "Review & submit"
+
+  # `execute` runs once at the end, in one transaction. Use bang methods so a
+  # failure raises → the engine rolls back and re-renders with the error.
+  # Return an Outcome: succeed(value) / failed(errors).
+  def execute
+    company = Company.create!(name: data.company.name, subdomain: data.company.subdomain, plan: data.plan.plan)
+    Billing.create!(company:, token: data.billing.card_token) if data.plan.plan == "pro"
+    data.team.invites.each { |i| company.invites.create!(email: i.email, role: i.role) }
+    succeed(company).with_message("You're all set!")   # with_message → flash
+  end
+end
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 2. Anchored, save-as-you-go flow with field reuse + cleanup.
+#    Launched against an existing Company (the `anchor`). Uses `using:` to import
+#    a definition's fields/validations/layout instead of re-declaring them, and
+#    per-step `on_submit`/`persist`/`on_rollback` to write as it goes.
+# ─────────────────────────────────────────────────────────────────────────────
+class ConfigureCompanyWizard < Plutonium::Wizard::Base
+  presents label: "Configure", icon: Phlex::TablerIcons::Settings
+
+  # `anchored with:` binds the wizard to an existing record; `anchor` returns it.
+  # (Calling `anchor` on a non-anchored wizard raises NotAnchoredError.)
+  anchored with: Company
+
+  # Idle sessions are swept after this long (records created so far are rolled
+  # back). Use :never to keep partial records indefinitely.
+  cleanup_after 7.days
+
+  # `using:` imports a field surface from a model (types + validations from the
+  # model; input styling from its auto-resolved CompanyDefinition) — no need to
+  # re-declare. `fields:` selects a subset. Persistence stays wizard-side; only
+  # the declarations are reused.
+  step :branding, label: "Branding", using: Company, fields: %i[logo brand_color]
+
+  step :billing, label: "Billing", condition: -> { anchor.paid_plan? } do
+    attribute :card_token, :string
+    input :card_token
+    validates :card_token, presence: true
+
+    # `on_submit` runs when THIS step completes (opt-in save-as-you-go).
+    on_submit do
+      charge = PaymentApi.authorize!(anchor, data.billing.card_token)
+      fail!("Card was declined") unless charge.ok?            # abort with a base error
+      # `persist` registers the record for resume + cleanup → persisted[:billing]
+      persist Billing.create!(company: anchor, token: data.billing.card_token, charge_id: charge.id)
+    end
+
+    # ADDITIONAL cleanup if the wizard is cancelled/abandoned. The engine ALWAYS
+    # destroys the persisted Billing record on rollback — on_rollback is only for
+    # side effects the engine 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) }
+  end
+
+  def execute
+    anchor.update!(configured_at: Time.current)
+    succeed(anchor).with_message("Company configured.")
+  end
+end
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 3. One-time, standalone onboarding (no anchor).
+#    Mounted on its own route; gated so a user only sees it until completed.
+# ─────────────────────────────────────────────────────────────────────────────
+class WelcomeWizard < Plutonium::Wizard::Base
+  presents label: "Welcome"
+
+  # Keyed per user (tenant folded in); `one_time` retains the completed row as a
+  # durable "done" marker the gate (below) checks — so it never re-runs.
+  concurrency_key { current_user }
+  one_time
+
+  # Portal-level wizards have no resource policy, so gate entry with `authorize?`.
+  def authorize? = current_user.present?
+
+  step :profile, label: "Your profile" do
+    attribute :full_name, :string
+    attribute :timezone, :string
+    input :full_name
+    input :timezone, as: :select, choices: ActiveSupport::TimeZone.all.map(&:name)
+    validates :full_name, presence: true
+  end
+
+  step :preferences, label: "Preferences" do
+    attribute :newsletter, :boolean, default: true
+    input :newsletter, as: :toggle
+  end
+
+  review label: "All set?"
+
+  def execute
+    current_user.update!(
+      full_name: data.profile.full_name, timezone: data.profile.timezone,
+      newsletter: data.preferences.newsletter, onboarded_at: Time.current
+    )
+    succeed.with_message("Welcome aboard!")
+  end
+end
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 4. Guest (anonymous) signup — runs PRE-LOGIN, mounted on a public route.
+#    Auth is required by default; `anonymous` opts out. A guest run's identity is
+#    a server-minted, unguessable cookie (httponly/secure/same_site, cleared on
+#    completion). The wizard NEVER crosses the auth boundary mid-flow — the only
+#    boundary it may cross is its terminal `execute` (here: create + sign in).
+# ─────────────────────────────────────────────────────────────────────────────
+class GuestSignupWizard < Plutonium::Wizard::Base
+  presents label: "Sign up"
+
+  anonymous # may run without a current_user
+
+  step :account do
+    attribute :email, :string
+    attribute :password, :string
+    input :email, as: :email
+    input :password, as: :password
+    validates :email, :password, presence: true
+  end
+
+  review label: "Review"
+
+  def execute
+    account = Account.create!(email: data.account.email, password: data.account.password)
+    # A real signup would sign the account in here (the host calls Rodauth, which
+    # rotates the Rails session) — no special framework handling is needed.
+    succeed(account).with_message("Welcome!")
+  end
+end
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Registration
+# ─────────────────────────────────────────────────────────────────────────────
+
+# (a) On a resource definition — the `wizard` macro synthesizes the launch
+#     action. Placement mirrors interactions: anchored → record action (per row);
+#     no anchor → resource/collection action (index header).
+class CompanyDefinition < Plutonium::Resource::Definition
+  wizard :configure, ConfigureCompanyWizard          # anchored → record action
+  wizard :onboard, CompanyOnboardingWizard           # no anchor → collection action
+end
+
+# (b) Portal-level — inside a portal engine's routes (alongside register_resource).
+#     Runs within the portal (auth/scoping/layout inherited). Portal-relative path.
+#   register_wizard WelcomeWizard, at: "welcome"
+#
+#     A guest (anonymous) wizard mounts on a PUBLIC route (drawn on the main app,
+#     outside the portal's auth constraint, so it's reachable pre-login).
+#     public: true is the default for an anonymous wizard.
+#   register_wizard GuestSignupWizard, at: "signup", public: true
+
+# (c) Gating the one-time wizard — in a portal/ApplicationController. Redirects
+#     the user into the wizard until completed, then bounces them back.
+#   class DashboardController < PlutoniumController
+#     ensure_wizard_completed WelcomeWizard
+#   end

data/docs/superpowers/specs/2026-06-17-wizard-relaunch-prompt-design.md

@@ -0,0 +1,86 @@
+# Wizard relaunch prompt — "resume or start new" on bare launch
+
+## Problem
+
+Tokened (repeatable) wizards — those with **no `concurrency_key`** — mint a fresh
+run on every bare launch (`GET /onboarding`). A user with one or more pending
+(in-progress) runs has no way to resume from the launch URL; each visit forks a
+new run. Keyed wizards (incl. one-time and anchored) already auto-resume their
+single keyed run, so this gap is specific to tokened wizards.
+
+## Goal
+
+Let a tokened wizard **opt in** so that a bare launch with ≥1 pending run shows a
+chooser page — list the pending runs (resume any) or start a new one — instead of
+silently forking. `/onboarding` becomes a chooser in that case.
+
+## Decisions (settled in brainstorming)
+
+- **Opt-in**, not default. A macro turns it on; default behaviour (fresh run) is
+  unchanged, so existing wizards and "run repeatedly" flows don't nag.
+- **Chooser whenever ≥1 pending** (owner- and tenant-scoped). Even a single
+  pending run shows the page, so "Start new" stays reachable.
+- **0 pending → fresh run**, exactly as today.
+- **No-op unless it matters**: ignored for keyed wizards (already auto-resume) and
+  `anonymous`/guest wizards (session-keyed single run, no owner).
+
+## Design
+
+### 1. DSL — `on_relaunch`
+
+```ruby
+on_relaunch :prompt   # show the chooser when pending runs exist
+# omit → :new (default) → always a fresh run
+```
+
+`dsl.rb`: store `@on_relaunch` (default `:new`), inherit it, expose
+`relaunch_prompt?` (`@on_relaunch == :prompt`).
+
+### 2. Launch branch — `driving.rb#wizard_launch`
+
+Before building the runner (which mints a token), decide:
+
+```
+require auth
+if relaunch_prompt? && !anonymous? && !concurrency_key?
+   && params[:new].blank? && pending_entries.any?
+     → render the chooser page (no token minted)
+else
+     → (today) build runner → mint token → PRG to first step
+```
+
+- `pending_entries` = `Plutonium::Wizard::Resume.entries_for(owner, scope:)`
+  filtered to `current_wizard_class` — reuses the existing listing module, which
+  already resolves owner/tenant scoping and per-run `resume_url`s.
+- `params[:new]` present → skip the chooser (the "Start new" path).
+
+### 3. Chooser page — `Plutonium::UI::Page::WizardChooser`
+
+Same card aesthetic as `WizardCompleted`. Renders the wizard label/description,
+then a list of pending runs — each row: current-step label + relative
+`updated_at` + a **Resume** link (`entry.resume_url`) — and a primary **Start
+new** button (→ bare launch URL with `?new=1`). No per-row discard in v1 (YAGNI;
+`cancel` makes it easy to add later).
+
+### 4. "Start new" path
+
+The Start-new button links to the bare launch URL + `?new=1`. Re-enters
+`wizard_launch`; the `params[:new]` guard skips the chooser; mints a fresh token
+and redirects to the first step — identical to today's launch. GET, like the
+existing launch (no DB row until the first step is submitted → no orphans).
+
+## Testing
+
+A tokened dummy wizard with `on_relaunch :prompt`:
+
+- 0 pending → fresh redirect (unchanged).
+- ≥1 pending → chooser lists them with resume links + a Start-new control.
+- `?new=1` → fresh redirect even with pending.
+- opt-out wizard → always fresh (no chooser).
+- keyed / anonymous wizard declaring `on_relaunch` → no-op (still auto-resume / fork).
+
+## Out of scope
+
+- Per-row discard/cancel from the chooser (v2).
+- Changing keyed/one-time/anchored behaviour (already auto-resume).
+- A standalone dashboard widget (the `Resume` module already covers that).

data/docs/superpowers/specs/2026-06-18-wizard-attachments-design.md

@@ -0,0 +1,101 @@
+# Wizard attachments: token → attachment bridge
+
+Status: **design / implementing**
+Date: 2026-06-18
+
+## Problem
+
+A wizard step can render a file input — the real-world pattern (a colleague's):
+
+```ruby
+step :photo, label: "Photo" do
+  attribute :photo, :string
+  input :photo, as: :uppy, direct_upload: true, hint: "Optional — …"
+end
+```
+
+— but attachments don't display end to end:
+
+- The `Uppy` input and `Display::Components::Attachment` expect a value that
+  **quacks like an attachment** (`.url`, `.filename`, `.content_type`, …).
+- A wizard stages **plain typed scalars**. A direct-upload field submits its
+  backend's upload **token** (an ActiveStorage signed_id, or Shrine cached-file
+  JSON), so `data.photo` is a `String`.
+- `SummaryDisplay` (the review auto-summary) hardcodes `f.string_tag` for every
+  field — an attachment shows as a raw token, never a preview.
+- On Back/resume, the `Uppy` input calls `.url` on the staged `String` — wrong.
+
+## Backends — there is more than ActiveStorage
+
+Plutonium attachment fields can be backed by **ActiveStorage** *or* **active_shrine**
+(Shrine) — see `Plutonium::UI::Avatar.resolve_image_src`, which branches (AS resolves
+its URL via Rails routing; Shrine via its own `#url`). They carry different upload
+tokens, and active_shrine is **not a core-gem dependency** (generator-installed), so
+it isn't exercised by this repo's suite. The bridge must therefore be
+backend-agnostic by construction; the dummy covers the AS path.
+
+## Key decision — model-free resolution by token SHAPE
+
+The field is bare (`attribute :photo, :string`, no `using:` model), so there is **no
+model to resolve against** — and we don't need one. The staged token is one of two
+shapes, and they're distinguishable:
+
+- **Shrine** cached-file data is **JSON** (`{"id":…,"storage":"cache",…}`) →
+  `Shrine.uploaded_file(data)` revives it from the globally-registered storages.
+- An **ActiveStorage** signed_id is **not** JSON → `ActiveStorage::Blob.find_signed`.
+
+```ruby
+Plutonium::Wizard::Attachments.resolve(token) # → [Shrine::UploadedFile | ActiveStorage::Blob]
+#   JSON.parse succeeds → Shrine ; else → ActiveStorage ; blank/tampered → dropped
+```
+
+`data` stays plain strings (no custom ActiveModel type; `encrypt_data`, merge, sweep
+untouched). Resolution is **display-only** — staging and `execute` never call it.
+
+Why token-shape over a source model: the actual usage is a **modelless** `as: :uppy`
+field, so there's no `using:` model to assign to; and the two token shapes are
+unambiguous, so a model would be ceremony, not information. (A custom Shrine uploader
+with derivative-specific URLs would want its own attacher, but a cached file's `.url`
+from the base `Shrine` is correct for the in-flight preview/review.)
+
+## The four boundaries
+
+1. **Declaration.** `attribute :photo, :string` + `input :photo, as: :uppy`
+   (`/:file`/`:attachment`), `direct_upload: true`. Multiple → an array attribute +
+   `multiple: true`. An attachment field = a step input whose `as:` is a file alias
+   (`Attachments.field?`).
+2. **Staging.** The submitted token(s) extract through the step form like any other
+   field and stage as the string/array — no special handling (verify in a request
+   test).
+3. **Input rehydration (Back/resume).** The wizard step form wraps its data object so
+   an attachment field READS as the resolved attachment object(s) (for the `Uppy`
+   preview) while every other field reads normally. Render-only: the submitted value
+   is still the token the hidden preview field posts, so staging is unaffected.
+4. **Review.** `SummaryDisplay` detects attachment fields (`field?`) and renders the
+   resolved attachment via `Display::Components::Attachment` instead of `string_tag`.
+
+## Execute
+
+Author code, unchanged shape: `succeed(Member.create!(photo: data.photo.photo))`.
+The staged token round-trips into the model's attachment natively (AS or Shrine).
+
+## Risks / dependencies
+
+- **Direct-upload endpoint.** `Uppy` posts to `/upload` (AS DirectUploads, or Shrine's
+  `upload_endpoint`). A shell-less / main-app wizard must have it reachable. Host
+  concern; document it.
+- **Orphaned uploads.** A token staged then abandoned (cancel/sweep) leaves an
+  unattached blob / cached Shrine file; each backend's own cleanup handles it. Note it.
+- **Bad/expired token** → resolution drops the entry (no raise), so a tampered token
+  never 500s the review or the form.
+- **active_shrine untestable in-repo** (not a dep) — the dummy proves the AS path; the
+  Shrine branch is unit-stubbed and rides the same `.url`/`.filename` contract
+  (confirmed for display by `Avatar.resolve_image_src`).
+
+## Build order
+
+1. `Plutonium::Wizard::Attachments` — `field?` + token-shape `resolve`. ✅ done
+2. `SummaryDisplay`: attachment-aware rendering + a dummy `as: :uppy` step + review test.
+3. Input rehydration wrapper + a Back/resume request test.
+4. Full dummy flow (upload token → review → execute assigns the attachment) +
+   integration test. Requires AS tables provisioned in the dummy.

data/docs/superpowers/specs/2026-06-18-wizard-hosting-design.md

@@ -0,0 +1,220 @@
+# Wizard hosting: controller resolution, identity, and chrome
+
+Status: **design / agreed direction** (no code yet)
+Date: 2026-06-18
+Supersedes the "wizards are portal-hosted only (v1)" framing.
+
+## Problem
+
+A wizard renders through the Plutonium controller stack (rendering, view-path
+prefix, layout). Today the host controller is **synthesized** at route-draw time,
+and the synthesis assumes a portal context. That leaves three things
+under-specified once wizards run outside a single portal:
+
+1. **Controller resolution** — which controller serves a wizard, and how an app
+   customizes it without a generator.
+2. **Identity / auth** — where `current_user` comes from, and how a pre-login
+   (guest) wizard avoids requiring it.
+3. **Chrome** — whether a wizard renders in the app shell, shell-less full page,
+   or embedded as a modal.
+
+The guiding facts (verified against the code):
+
+- **Authentication is enforced at the route constraint**, not the controller:
+  `constraints Rodauth::Rails.authenticate(:acct) { mount Engine }`. The gem adds
+  **no** `require_authentication` before_action; controller auth concerns
+  (`Plutonium::Auth::Rodauth(:acct)`) only *provide* `current_user`
+  (= `rodauth.rails_account`, `nil` when unauthenticated).
+- **`Plutonium::Auth::Public` is just a `current_user => "Guest"` stub.**
+- **The shell lives entirely in the layout** (`resource.html.erb` →
+  `ResourceLayout`: sidebar/header/topbar), not in the wizard page. The wizard
+  `Page` renders `header → stepper → body` and is layout-agnostic.
+  `Plutonium::Core::Controller` sets `layout -> { turbo_frame_request? ? false : "resource" }`.
+
+## Catalogue of supported cases
+
+| Surface | Enforcement | Identity (wizard) | Controller (else synthesize) | Chrome |
+|---|---|---|---|---|
+| **Portal standalone** (`register_wizard` in a portal) | portal constraint | authed (owner) | `<Portal>::PlutoniumController` | `:shell` (default) / `:standalone` |
+| **Main-app standalone, authenticated** (`register_wizard` on the app) | route constraint or `require_wizard_authentication!` | authed (owner) | **app-defined** `::WizardsController` | `:shell`* / `:standalone` |
+| **Main-app standalone, public** (`register_wizard public:`/`anonymous`) | none (outside constraints) | `anonymous` (guest token) | bare synthesized | `:standalone` (no shell to embed in) |
+| **Resource-anchored** (`wizard` macro on a definition) | inherits the resource controller | authed (owner) | the **resource controller** (WizardActions concern) | **always embedded** (modal) |
+
+\* a bare main-app base has no shell; "in-shell" only applies if the app's
+`::WizardsController` provides one.
+
+Two structural truths:
+
+- **Portals are "auth or nothing."** You can't carve a public hole inside an
+  engine that's wholly behind a constraint, so a *public* wizard is **main-app
+  only**. (A portal *may* be mounted without its constraint — a "public portal" —
+  in which case `current_user` is still *available*, just possibly `nil`.)
+- **Anchored wizards are not a wizard controller.** They are a concern
+  (`WizardActions`) mixed into the resource controller, inheriting its
+  auth/scope/layout. They stay out of the wizard-controller hierarchy entirely.
+
+## 1. Controller resolution — override-first, no inheritance chain
+
+There is **no single gem "global wizard controller" in the lineage.** A single
+base class can't span portal and main-app contexts: the concrete controller's
+superclass is *reserved* for the auth/context base (the portal's
+`PlutoniumController`, the app's authenticated base, or a bare
+`ActionController::Base`), so wizard behavior must compose via a **module**, not a
+superclass.
+
+Resolution per surface:
+
+1. **Use the app's controller if it exists** (const check — works today):
+   - Portal: `<Portal>::WizardsController`
+   - Main app: `::WizardsController`
+2. **Else synthesize:**
+   ```ruby
+   Class.new(context_base) { include Plutonium::Wizard::Controller }
+   ```
+   where `context_base` is:
+   - Portal → `<Portal>::PlutoniumController` (portal auth/scope/layout)
+   - Main-app → a **bare** base (`ActionController::Base`), **no auth** — an
+     authenticated main-app wizard therefore requires an app-defined
+     `::WizardsController` (same contract as `register_resource` controllers).
+
+### The module is the contract
+
+`Plutonium::Wizard::Controller` becomes the complete include surface. Including it
+must yield a fully renderable wizard controller, so it pulls in
+`Plutonium::Core::Controller` itself (asset/layout machinery) instead of the
+synthesizer bolting Core on separately. Re-including Core on a portal parent that
+already has it is a harmless no-op, so one module works everywhere.
+
+**View-prefix note.** The gem's shared partials (`plutonium/_flash`, …) are looked
+up by a `"plutonium"` view *prefix*, which normally comes from inheriting a
+controller whose `controller_path` is `"plutonium"` (the app's
+`PlutoniumController`) — *not* from `Core`'s `append_view_path` (that adds the
+directory, not the prefix). A truly bare host lacks the ancestor, so the **module
+contributes the `"plutonium"` prefix itself** (overriding `_prefixes`). This is
+what makes "main-app can be bare" actually render.
+
+- **Synthesizer:** `Class.new(context_base) { include Plutonium::Wizard::Controller }`
+- **User override:** `class WizardsController < MyAuthBase; include Plutonium::Wizard::Controller; end`
+
+### Convenience base class (sugar only)
+
+For apps that need no custom auth base, ship a ready-made class:
+
+```ruby
+# Plutonium-provided
+class Plutonium::Wizard::BaseController < ActionController::Base
+  include Plutonium::Wizard::Controller
+end
+
+# app
+class WizardsController < Plutonium::Wizard::BaseController; end
+```
+
+The class is convenience; the **module is the mechanism**.
+
+## 2. Identity / auth — guest-ness belongs to the wizard
+
+`current_user` has two distinct meanings:
+
+- **Available** = a *controller* property: present wherever a `Rodauth(acct)`
+  concern is mixed in (returns `nil` when unauthenticated).
+- **Expected** = a *wizard* property: a non-`anonymous` wizard owner-scopes off
+  `current_user`; an `anonymous` wizard *ignores it* and keys identity off the
+  session token (owner `nil`).
+
+Therefore:
+
+- Guest-ness is enforced **in the driving layer**: an `anonymous` wizard never
+  consults `current_user` for identity (it's session-token keyed, owner `nil`).
+- A normal wizard with no `current_user` is rejected by the route constraint
+  (authenticated mounts) or by `require_wizard_authentication!` (the fallback that
+  also covers public mounts hosting a non-anonymous wizard).
+- The wizard module supplies a **default `current_user`** that defers to the
+  host's auth concern when present (`defined?(super) ? super : nil`) and is `nil`
+  on a bare host — so a bare main-app/public controller has the method without
+  shadowing a real auth concern.
+
+> **CORRECTION (was: "retire `Auth::Public`").** `Plutonium::Auth::Public` is
+> **kept** — it is not wizard-specific: public *portals* (e.g. a storefront) use
+> it, and a wizard can run inside one (a resource-anchored wizard on a public
+> portal), where `current_user` is the `"Guest"` sentinel. So the driving layer's
+> `current_user_present_for_wizard?` **keeps** its `!= "Guest"` check. What changed
+> is only that the public *wizard* synthesis no longer *needs* `Auth::Public` for
+> correctness (an `anonymous` wizard never reads `current_user`); it's retained
+> there for a defined `current_user` and consistency with public portals.
+
+## 3. Chrome — a `register_wizard` option, three modes
+
+> **NAMING (as-built):** the option shipped as **`layout:` — a Rails layout NAME**,
+> exactly like the controller `layout` macro (not a closed enum). It went `chrome:`
+> → `shell:` → `layout:`: `chrome:` was disliked; `shell:` collided with the
+> framework's `shell` chrome-variant enum (`:modern`/`:plain`/`:classic`), a
+> different axis (*which* chrome vs *whether*); `layout:` names what it controls and
+> the value *is* the layout (`:basic` ↔ `basic.html.erb`/`BasicLayout`, like
+> `resource` ↔ `ResourceLayout`). The three "modes" below are: embedded (automatic,
+> turbo-frame), `layout: :basic` (bare), and the host default / `:resource` (shell).
+> Read "chrome" as the layout choice and `chrome: :standalone` as `layout: :basic`
+> throughout this section.
+
+The shell is a layout concern, so chrome = layout selection, made by the **driving
+layer at render time** (works regardless of which controller serves the wizard,
+and without touching the `Page` component):
+
+| Mode | Appearance | `layout:` |
+|---|---|---|
+| **Embedded** | overlays the current page (launched from a button) | `false` (turbo-frame) — already automatic |
+| **In-shell** | sidebar + topbar + wizard | `:resource` (or omit on a portal) — the `resource` layout |
+| **Bare** | no sidebar/topbar — e.g. "set up your organization" | `:basic` — `BasicLayout` |
+
+Rules:
+
+- **Chrome is toggled only on `register_wizard`** (`chrome: :shell | :standalone`).
+  It travels with the mount, not the wizard class.
+- **Resource-defined wizards (`wizard` macro) are always embedded** — launched
+  from a record/collection action, overlaying the page. No chrome option.
+- **Turbo-frame requests are always layout-less** regardless of the setting (the
+  embedded path).
+- **Default by mount context:** portal standalone → `:shell`; bare main-app
+  standalone → `:standalone` (no shell available). Both overridable.
+
+## Resolved decisions
+
+1. **Chrome surface:** `register_wizard` option only; resource wizards always
+   embedded. ✔
+2. **Default full-page chrome:** portal → `:shell`, main-app → `:standalone`. ✔
+3. **Retire `Auth::Public`:** yes — guest-ness moves to the `anonymous` wizard +
+   driving layer; guest = `current_user.nil?`. ✔
+
+## Migration / current state
+
+Already on the branch (keep — steps toward this design):
+
+- `PublicWizardsController` split from `::WizardsController` (the const collision
+  fix). Under this design the public path is "a bare synthesized controller +
+  `anonymous` wizard," but the distinct const remains correct.
+- The synthesized controller including `Plutonium::Core::Controller` itself — this
+  becomes "the module pulls in Core," i.e. moved into
+  `Plutonium::Wizard::Controller`.
+
+To revert before implementing:
+
+- The `Rodauth(:user)` added to the dummy's `::PlutoniumController` (wrong layer —
+  leaks auth into every portal base). Replace the dummy demo with an app-defined
+  `::WizardsController` that includes the wizard module + its own auth — which also
+  exercises the override hook.
+
+## Implementation outline (for the follow-up, not this doc)
+
+1. Fold `Core::Controller` into `Plutonium::Wizard::Controller`; ship
+   `Plutonium::Wizard::BaseController` convenience class.
+2. Main-app synthesis: bare `ActionController::Base` base (drop the
+   `::PlutoniumController` parent); keep the const-check override.
+3. `register_wizard … chrome:`; driving layer selects the layout
+   (`false` / `basic` / inherited) at render.
+4. Remove `Auth::Public`; route guest identity through `anonymous` + the driving
+   layer; treat `current_user.nil?` as guest.
+5. Dummy: app-defined `::WizardsController` (auth) for the authenticated main-app
+   demo; a separate `anonymous` public wizard for the guest demo; revert the
+   `::PlutoniumController` change.
+6. Tests: override-hook is honored; bare main-app wizard is guest; chrome toggles
+   pick the right layout; anchored wizard stays embedded.