plutonium 0.62.2 → 0.63.0

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

@@ -220,9 +220,11 @@ end
 
 ## Custom layouts
 
-### Sectioned — prefer the `form_layout` DSL
+### Sectioned — prefer the `form_layout` / `display_layout` DSL
 
-**For grouping fields into sections, don't hand-roll a `Form` subclass — declare `form_layout` in the definition.** It handles headings, descriptions, collapsible `<details>`, per-section `columns:`, `condition:`-based visibility, and **auto-drops sections that resolve to zero fields** (so `+ New` doesn't sprout empty headings). See [[plutonium-resource]] › Form Layout.
+**For grouping fields into sections, don't hand-roll a `Form` or `Display` subclass — declare `form_layout` (forms) or `display_layout` (show page) in the definition.** They handle headings, descriptions, collapsible `<details>`, `condition:`-based visibility, and **auto-drop sections that resolve to zero fields** (so `+ New` doesn't sprout empty headings). `columns:` is form-only — `display_layout` raises on it. See [[plutonium-resource]] › Form Layout / Display Layout.
+
+**Each section renders as its own card** (`Plutonium::UI::Block`), so a sectioned form or show page has **no single outer card** — the form drops its own `pu-card` and the sections supply it. Don't add a card wrapper of your own around them.
 
 ```ruby
 class PostDefinition < ResourceDefinition
@@ -387,13 +389,15 @@ class PostDefinition < ResourceDefinition
         p(class: "mt-2 opacity-90") { object.excerpt }
       end
 
-      Block do
-        fields_wrapper do
-          render_resource_field :author
-          render_resource_field :published_at
-        end
+      # `fields_wrapper` is ALREADY a card (it renders a Block internally),
+      # so do not wrap it in another one — that stacks two cards and doubles
+      # the border and shadow.
+      fields_wrapper do
+        render_resource_field :author
+        render_resource_field :published_at
       end
 
+      # `Block` is the card primitive: use it for your own content.
       Block do
         div(class: "prose max-w-none") { raw object.content }
       end
@@ -409,9 +413,28 @@ end
 | `render_fields` | All permitted fields |
 | `render_resource_field(name)` | One field |
 | `render_associations` | Association tabs (driven by `permitted_associations` — see [[plutonium-behavior]]) |
+| `render_before_fields` / `render_after_fields` | Hooks around the fields — **Details tab only** |
 | `object` | The record |
 | `resource_fields`, `resource_associations` | Permitted lists |
 
+### Details-tab-only content
+
+To add a banner or extra section that shows on the **Details** tab and not the association tabs, override `render_before_fields` / `render_after_fields` on the **Display** — not the ShowPage. The page-level `render_before_content` / `render_after_content` hooks wrap the whole content block, and the tablist lives inside it, so anything added there shows on every tab.
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Display < Display
+    private
+
+    def render_before_fields
+      div(class: "pu-card pu-card-body mb-4") { plain "Only on the Details tab" }
+    end
+  end
+end
+```
+
+Both hooks are no-ops by default. `render_fields` is the Details tab body when the record has associations and the entire display when it doesn't, so the hooks fire in the Details context either way.
+
 ## Custom Table
 
 ```ruby
@@ -447,6 +470,40 @@ end
 
 ---
 
+## Drag-to-Reorder Affordance (`position_on`)
+
+When a definition declares `position_on` (see [[plutonium-resource]]) the index **table**, the **card grid**, and **nested association tables** render a drag grip. Configuration is entirely in the definition — there is no UI-layer switch.
+
+**What renders where:**
+
+| Surface | Draggable element | Grip placement | Axis |
+|---|---|---|---|
+| Index / nested table | the **grip only**, never the `<tr>` | inside the first cell's existing left padding (content does not shift) | vertical |
+| Card grid | the **grip only** | floated over the card's top-left corner | horizontal, wrap-aware |
+| Kanban board | the **whole card** | — | both (cross-column) |
+
+🚨 **Never make a `<tr>` draggable.** Two silent regressions: `draggable="true"` disables text selection inside the element in every major browser (you lose copy-a-cell-value), and it fights `row_click_controller` — a drag that starts and ends in place still fires a click and navigates the user away. Kanban keeps whole-card dragging because neither applies to a kanban card; a **grid** card gets a grip because it *does* carry a row-click show affordance.
+
+**Enabled state.** The grip is live only while the collection is sorted **ascending, by the position attribute, and nothing else**. Otherwise "drop me between these two rows" describes nothing. Under a foreign sort the Stimulus controller isn't attached at all and the grip renders as a **link that applies the position sort** — the disabled state is the way out of the disabled state, which is why `position_on` registers `sort <attr>`. Per record, the grip also requires `reposition?`.
+
+**DOM contract** (relevant if you eject a table/grid or write a custom collection component):
+
+```
+wrapper  data-controller="positioned"
+         data-positioned-url-template-value="/things/__ID__/reposition"
+         data-positioned-axis-value="horizontal"   # grid only
+row/card data-positioned-row-id="<id>"             # single source of truth for the record id
+grip     data-positioned-grip                      # a real <button> — tabbable
+```
+
+The URL template is built off `current_page_path` (not `request.path`) so a post-rebalance re-render doesn't wire subsequent drops to `/things/5/reposition`. The controller POSTs `{prev_id, next_id, to_index}` plus `window.location.search` — the query string is load-bearing, since the endpoint re-renders through the ordinary index pipeline.
+
+**Accessibility.** Focus the grip and use <kbd>↑</kbd>/<kbd>↓</kbd> — deliberately linear even on a wrapped grid, since one position attribute stores a 1-D order. Focus is restored onto the same record's grip after a stream replaces the collection. ⚠️ Native HTML5 drag does **not** fire on touch devices (inherited from kanban); there is no automatic fallback.
+
+Components: `lib/plutonium/ui/table/components/drag_handle.rb`, `lib/plutonium/ui/component/positionable.rb`, `src/js/controllers/positioned_controller.js`. Reference: `docs/reference/positioning.md`.
+
+---
+
 # Part 4 — Component Kit & Custom Components
 
 ## Built-in shorthand kit
@@ -509,17 +566,47 @@ class PostCardComponent < Plutonium::UI::Component::Base
 end
 ```
 
-Use in a definition:
+Use in a definition. A component with its **own constructor** (like the one above)
+must use the **block form** — you build it:
 
 ```ruby
-display :card, as: PostCardComponent     # custom display component
-input   :color, as: ColorPickerComponent # custom input component
+display :card do |field|
+  PostCardComponent.new(post: field.object)
+end
 
 display :metrics do |field|
   MetricsChartComponent.new(data: field.value)
 end
 ```
 
+🚨 `as: SomeComponent` takes a **field component**, NOT a keyword-argument
+component: Plutonium constructs it as `SomeComponent.new(field, **attributes)`, so
+`display :card, as: PostCardComponent` raises `ArgumentError: wrong number of
+arguments`. A field component subclasses the Phlexi base for its surface and reads
+`field` (`field.value`, `field.object`, `field.dom`, `attributes`):
+
+```ruby
+class ColorPickerComponent < Phlexi::Form::Components::Base
+  include Phlexi::Form::Components::Concerns::HandlesInput  # name/id/value plumbing
+  include Plutonium::UI::Component::Behaviour               # optional: kit + resource helpers
+
+  def view_template
+    input(**attributes, type: "color", value: field.value)
+  end
+end
+
+class ChartComponent < Phlexi::Display::Components::Base
+  def view_template
+    div(class: "h-40", data: {controller: "chart", chart_series_value: field.value.to_json})
+  end
+end
+```
+
+```ruby
+input   :color, as: ColorPickerComponent  # every surface: form + filter panel
+display :chart, as: ChartComponent        # every surface: show + index column
+```
+
 ## `DynaFrameContent` pattern
 
 Enables frame-aware rendering: regular requests get the full page (header + content + footer); turbo-frame requests get only the content inside the frame.
@@ -747,7 +834,7 @@ import CustomController from "./custom_controller"
 application.register("custom", CustomController)
 ```
 
-Bundled controllers: `color-mode`, `form` (pre-submit), `nested-resource-form-fields`, `slim-select`, `flatpickr`, `easymde`, plus various internal UI controllers.
+Bundled controllers: `color-mode`, `form` (pre-submit), `nested-resource-form-fields`, `slim-select`, `flatpickr`, `easymde`, `kanban`, `positioned` (drag-to-reorder), `row-click`, plus various internal UI controllers.
 
 Custom controller — standard Stimulus:
 
@@ -815,6 +902,8 @@ Plutonium uses CSS custom properties for surfaces, text, borders, forms, cards,
 }
 ```
 
+🚨 **Mirror every `:root` override in `.dark`.** The app stylesheet loads after Plutonium's and `:root`/`.dark` have equal specificity, so a `:root`-only override beats Plutonium's `.dark` value even in dark mode — your light color ships into dark mode, often unreadably (e.g. translucent navy `--pu-text-subtle` is invisible on a dark surface). Every color token customized in `:root` MUST be re-asserted with a dark value in `.dark`.
+
 ## `.pu-*` component classes
 
 Ready-to-use styled components in `src/css/components.css`. **Prefer these over hardcoded `gray-X/dark:gray-Y` pairs.**
@@ -928,7 +1017,11 @@ end
 
 ### Form theme keys
 
-`base`, `fields_wrapper`, `actions_wrapper`, `wrapper`, `inner_wrapper`, `label`, `invalid_label`, `valid_label`, `neutral_label`, `input`, `invalid_input`, `valid_input`, `neutral_input`, `hint`, `error`, `button`, `checkbox`, `select`.
+`base`, `sectioned_base`, `fields_wrapper`, `sections_wrapper`, `actions_wrapper`, `wrapper`, `inner_wrapper`, `label`, `invalid_label`, `valid_label`, `neutral_label`, `input`, `invalid_input`, `valid_input`, `neutral_input`, `hint`, `error`, `button`, `checkbox`, `select`, plus the shared section keys below.
+
+`sectioned_base` replaces `base` when the definition declares a `form_layout` — the sections are cards, so the form itself stops being one.
+
+⚠️ **Width is NOT a theme key.** It's configuration (`page_width` / `form_width` on the definition, `Plutonium.configuration.default_page_width` globally) and is appended by `Form::Resource`/`Page::Show`, so overriding `base` or `fields_wrapper` restyles a surface without silently pinning its width. See [[plutonium-resource]] › Page Width.
 
 ## Display theme
 
@@ -937,7 +1030,7 @@ class Display < Display
   class Theme < Plutonium::UI::Display::Theme
     def self.theme
       super.merge(
-        fields_wrapper: "grid grid-cols-3 gap-8",
+        fields_inner:   "pu-card-body grid grid-cols-3 gap-8",   # the GRID
         label:          "text-sm font-bold text-[var(--pu-text-muted)] mb-1",
         string:         "text-lg text-[var(--pu-text)]",
         markdown:       "prose dark:prose-invert max-w-none"
@@ -949,7 +1042,15 @@ end
 
 ### Display theme keys
 
-`fields_wrapper`, `label`, `description`, `string`, `text`, `link`, `email`, `phone`, `markdown`, `json`, `boolean`, `badge`, `currency`, `color`.
+`fields_wrapper`, `fields_inner`, `sections_wrapper`, `section_grid`, `label`, `description`, `string`, `text`, `link`, `email`, `phone`, `markdown`, `json`, `boolean`, `badge`, `currency`, `color`.
+
+⚠️ **`fields_wrapper` is the CARD, `fields_inner` is the grid.** `fields_wrapper` is merged into a `Plutonium::UI::Block` (which supplies `pu-card` itself), so putting grid classes there styles the card, not the fields. Override `fields_inner` to change the unsectioned grid, and `section_grid` to change the grid inside a `display_layout` section.
+
+### Section theme keys (forms *and* displays)
+
+Section chrome is shared: `Plutonium::UI::Component::Section::DEFAULT_THEME` is merged into **both** `Form::Theme` and `Display::Theme`, so the two read identically by default while staying independently overridable.
+
+`section_wrapper` (merged into the section's Block — Block already supplies `pu-card`), `section_header`, `section_summary` (the collapsible header row), `section_accent`, `section_heading`, `section_description`, `section_caret`, `section_body`, plus `sections_wrapper` (the container that stacks sections).
 
 ## Table theme
 

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

@@ -11,15 +11,16 @@ For the field/input vocabulary used inside a step, load [[plutonium-resource]].
 
 ## 🚨 Critical (read first)
 
-- **Enable the subsystem first.** `config.wizards.enabled = true` in `config/initializers/plutonium.rb`, then `rails db:migrate`. It's `false` by default — without it there's no `plutonium_wizard_sessions` table.
+- **Enable the subsystem first.** `rails g pu:wizards:install` flips `config.wizards.enabled = true` and schedules `SweepJob`; then `rails db:migrate`. (By hand: the flag in `config/initializers/plutonium.rb`.) It's `false` by default — without it there's no `plutonium_wizard_sessions` table.
 - **Use bang methods** (`create!`/`update!`/`save!`) in `on_submit` and `execute`. Failure is signalled by a **raised exception** — a non-bang `false` advances the wizard and silently loses data. Or call `fail!("msg")`.
 - **`data` is step-keyed:** `data.<step>.<field>` (e.g. `data.company.name`, `data.plan.plan`). Each step has its own typed sub-object, so two steps may share a field name without colliding. Read a field through its owning step everywhere (`condition:`/`on_submit`/`execute`).
 - **`condition:` lambdas must be nil-safe.** They run against `data` at every transition, including before their deciding step is filled (value is `nil`). `-> { data.plan.plan == "pro" }` ✓; `-> { data.plan.plan.upcase == "PRO" }` raises on nil ✗.
 - **`review` must be the LAST step.** A step declared after `review` raises at load.
 - **`using:` targets a MODEL only** — not an interaction, not a bare definition. Selectors `fields:`/`only:`/`except:`.
 - **No generator.** Author wizards by hand, like interactions. They live in `app/wizards/`.
+- **A wizard is a presentation object** — it's built with `view_context:`, so anything reachable only through `execute`/`on_submit` is reachable only from a wizard run. Logic may *start* there; the **second caller** (a job, an API, a rake task, the console) is the trigger to move it onto the **model**. See [[plutonium-behavior]] › Part 3 › Where the logic goes.
 - **Wizards are portal- *or* main-app-hosted.** A `register_wizard` mount inside a portal inherits the portal's auth/scoping/layout. A `register_wizard` mount on the **main app** runs standalone — for an **authenticated** main-app wizard you MUST define your own `::WizardsController` (include `Plutonium::Wizard::Controller` + your auth concern); the synthesized fallback is **bare (no auth)**. Resource-anchored (`wizard` macro) wizards always run embedded on the resource controller.
-- **Schedule `SweepJob`** (a periodic job/cron). It reaps abandoned/expired sessions — always good hygiene (stale `in_progress` rows pile up otherwise), and **load-bearing** for `on_submit`/`persist` wizards: it's the only thing that rolls back the partial domain records an abandoned save-as-you-go run leaves behind.
+- **Schedule `SweepJob`** — `pu:wizards:install` does it for you when Solid Queue is in the bundle; otherwise add a periodic job/cron yourself. It reaps abandoned/expired sessions — always good hygiene (stale `in_progress` rows pile up otherwise), and **load-bearing** for `on_submit`/`persist` wizards: it's the only thing that rolls back the partial domain records an abandoned save-as-you-go run leaves behind.
 
 ---
 
@@ -53,7 +54,7 @@ The ASK gate resolves the *design*; this confirms the app can actually *run* it.
 | Anchor model exists & reachable | Read the model an `anchored` wizard runs against | Missing/unreadable anchor ⇒ 404 / `NotAnchoredError` |
 | Host portal exists & its scoping | Read the portal engine (`scope_to_entity`?) + its real module name | Tenant folds into run identity; a guessed portal name breaks `register_wizard` |
 | Guest-flow prereqs | AR encryption keys if `encrypt_data`; no `concurrency_key`/`one_time` with `anonymous` | First write raises otherwise |
-| `on_submit` ⇒ SweepJob scheduled | The recurring-job config | Abandoned mid-flow records pile up forever |
+| `on_submit` ⇒ SweepJob scheduled | grep `config/recurring.yml` for `sweep_abandoned_wizards` | Abandoned mid-flow records pile up forever |
 
 **Don't author the class until `config.wizards.enabled` is confirmed and the anchor/target model + portal are read.** Until then, any class you show is provisional — say so; don't present a guessed field/column mapping as final.
 
@@ -97,6 +98,8 @@ end
 - `review` — built-in terminal step: auto-summary + gated Finish. Must be last.
 - `execute` — runs once at the end in one transaction; returns `succeed(...)` / `failed(...)`.
 
+⚠️ **`execute` is a presentation boundary, same as an interaction's.** A wizard is built with `view_context:` too, so anything 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, an admin backfill, an importer): `Company.create!(...)` inline is fine for a one-off; `Company.onboard!(...)` is what you reach for when it isn't. Same for `on_submit`/`on_rollback` — they're flow hooks, not a home for domain logic. Full rule: [[plutonium-behavior]] › Part 3 › Where the logic goes.
+
 ## Wizard-level macros
 
 | Macro | Meaning |
@@ -111,6 +114,7 @@ end
 | `one_time` | Retain the completed row at the `concurrency_key` → run once (gate-able). **Requires `concurrency_key`.** Omit → row deleted on complete (repeatable). |
 | `completed do \|wizard\| … end` | Custom body for the "already completed" page a finished **one-time** wizard shows when re-opened (replaces the default confirmation). |
 | `encrypt_data` | Encrypt the staged `data` column at rest via ActiveRecord's encryption keys (PII flows). Requires `active_record.encryption` keys — first write raises (naming the wizard) if unconfigured. Unset inherits `config.wizards.encrypt_data` (global default, off); `encrypt_data false` opts out when that default is on. |
+| `width <size>` | Width of this wizard's step pages: `:sm` `:md` `:lg` `:xl` `:full` (`:full` = unconstrained). Unset inherits `config.wizards.width` (default `:md`). Independent of `config.default_page_width` — resource page width does not move wizards. |
 | `anonymous` | Opt into **guest (unauthenticated) access.** Default = auth required. A guest wizard may authenticate only at its terminal `execute`; never mid-flow. Mount it `public: true` (the default for `anonymous`). **Mutually exclusive with `concurrency_key`/`one_time`** — a guest's identity is its session token (already session-keyed/repeatable); whichever macro is declared last raises. |
 
 ## Branching — `condition:`
@@ -127,6 +131,26 @@ end
 
 `condition:` can also read `anchor`. Branch-hidden steps' data is pruned before `execute`. **Must be nil-safe** (see Critical).
 
+Conditions are re-evaluated against the submission that was just staged, so a step (including `review`) may be gated on an answer from the step immediately before it — the revealed steps become reachable on that same POST. When a step's answer reveals nothing after it, that POST ends the flow and runs `execute`.
+
+### Revealing a field within a step — `pre_submit:`
+
+A step-level `condition:` branches whole steps against *stored* data. To show or hide a field as the user edits a **sibling field on the same step**, mark the deciding input `pre_submit: true` — changing it re-renders the step form from the **just-submitted** values (same mechanism as resource forms and interactive actions):
+
+```ruby
+step :details do
+  attribute :contact_pref, :string
+  input :contact_pref, as: :select, pre_submit: true,
+    choices: {none: "Don't contact me", email: "Email me"}
+
+  attribute :contact_email, :string
+  # `object` here is the step's data, seeded from what was just typed.
+  input :contact_email, condition: -> { object.contact_pref == "email" }
+end
+```
+
+A `pre_submit` is **render-only**: it never persists, never marks the step submitted, and never moves the cursor — abandon the page and nothing durable is left. **Attachment fields are exempt** from the re-render's seeding: a file input doesn't re-post on a sibling's `change`, so an already-staged upload survives untouched instead of being blanked out of the form. Uploads stage only on a real submit.
+
 ## Field reuse — `using:` a model
 
 `using:` is a **step option** (not a block method) and targets a **model only**.
@@ -179,6 +203,31 @@ Repeater rows rehydrate from staged `data` on GET (resume / back re-renders fill
 
 Validations drive the form's field affordances just like a resource form: `presence` → the required marker (`*`); `length`/`numericality`/`format`/`inclusion` → `maxlength`/`min`/`max`/`pattern`/auto-choices. This holds for validations imported via `using:` too. (Structured-input sub-fields are the exception — they carry no validators, so no markers there.)
 
+### Options that depend on the run
+
+The step block runs **once, when the class loads**, so a literal option is frozen for every run. A **proc-valued** field/input option is resolved on **every render**. It must **take the form**: `form.wizard` is the run (so `anchor`, `data`, `persisted`, `current_user` are all reachable) and `form.object` is that step's staged data.
+
+```ruby
+step :plan do
+  attribute :tier
+  input :tier, as: :select, choices: -> { anchor.available_tiers }
+end
+```
+
+It is also how a custom component receives per-run configuration:
+
+```ruby
+input :answers, as: MyManifestComponent, config: -> { anchor.manifest }
+```
+
+A one-argument proc still takes the form, as on any other form, for `object` (this step's staged data), `params` and helpers: `choices: ->(form) { form.object.region_tiers }`.
+
+Three limits worth knowing:
+
+- The **field set** is still fixed at class load — a proc varies an option, not which fields exist. To collect a shape known only at runtime, declare one `structured_input` and let a custom component render the inner controls. For bespoke markup pass a **block** to `input` instead; it renders in the form's context with the field yielded.
+- A **step's** `condition:` runs against the wizard; a **field's** `condition:` runs against the form (`object` = that step's staged data). Only the field-level one is excluded from the resolution above.
+- **Proc options resolve on every form** ([[plutonium-resource]]), by one rule with no wizard exception: a zero-argument proc keeps its own binding, a one-argument one gets the form. A step block is `instance_exec`'d against an internal field recorder, so `-> { anchor.x }` raises `NameError` — take the form and use `form.wizard`. Same trade a `form_layout` section option makes; an `input` line keeps its meaning when moved between a definition and a step.
+
 ## Attachment fields (file uploads)
 
 A step can collect a file. Declare it like any field — a **`:string`** attribute (it holds the upload **token**, not the bytes) + a file input:
@@ -241,6 +290,8 @@ Always lists invalid/unvisited steps as fix-this jump links; Finish disabled unt
 
 The custom block runs **in the Phlex view context** (`self` is the component), so it may return a String, emit Phlex (`div`, `render Component.new(...)`), and reach helpers via `helpers.*`; it's yielded the `wizard` (`data`/`anchor`/`persisted`/`current_user`). Don't both emit markup and return a String — Phlex renders the returned String too, double-rendering it.
 
+**The summary resolves choice labels.** A field declared with the `choices:` option summarises as the label its `<option>` carried, not the stored value — `42` reads as "Alice", `"cash"` as "Cash". Every collection shape the input accepts works (pair arrays, `{value => label}` hashes, ranges, sets, AR relations, procs returning any of those), because resolution goes through the same `Phlexi::Form::SimpleChoicesMapper` the input uses. **Caveat:** choices supplied inside a *block* (`input(:x) { |f| f.select_tag choices: … }`) are computed at render time and aren't visible to the summary — those fields still show the raw value. Use the declarative `choices:` option when you want the review page to read well.
+
 ## Per-step writes — `on_submit` / `persist` / `on_rollback`
 
 `execute` is the default (atomic). Use `on_submit` **only** when a real record must exist mid-flow (external handoff, reviewer sees partials, payload too large for the row).
@@ -268,6 +319,8 @@ end
 
 `on_submit` is not atomic across steps (HTTP), which is why `cleanup_after` + `SweepJob` exist.
 
+**Keep the hook to flow, not domain.** `on_submit`/`on_rollback` belong to one wizard step and can't be called from anywhere else, so they should say *when* and *what gets tracked* — one call to a model, as above. Once "authorize a card and record the billing row" is something the API does too, it becomes `Billing.authorize!(company:, token:)` and the hook shrinks to `persist Billing.authorize!(...)`.
+
 ## Accessors
 
 | Accessor | Returns |
@@ -278,6 +331,8 @@ end
 | `succeed(v)` / `failed(errs)` | Outcome helpers (alias `success`). `.with_message`, `.with_redirect_response` chainable. |
 | `fail!(msg)` / `fail!(:field, msg)` | Raise a `StepError` from `on_submit`/`execute`. |
 
+Available inside steps, `condition:`, `on_submit`, `on_rollback` and `execute` — and, via `form.wizard`, inside a step's **proc-valued field/input options** (see **Step internals → Options that depend on the run**).
+
 ## Anchoring
 
 ```ruby
@@ -419,7 +474,20 @@ The guest run-id lives in the **Rails session** (`session["plutonium_wizards"][<
 
 `Plutonium::Wizard.in_progress_for(view_context)` (→ `Resume.entries_for(view_context)`) takes the `view_context` (as interactions do) and derives the run owner (`current_user`), tenant scope, and **portal** from it — returning that user's in-progress runs **for the current portal**, newest-first, for a "continue where you left off" dashboard. A run is only ever listed (and linked) by the portal it was launched in: a non-scoped portal lists only unscoped runs, a scoped portal narrows to the current tenant. (Two portals can share an entity scope, so the launching portal — the `engine` — is recorded per-run; scope alone can't identify it.)
 
-Each entry exposes the wizard's `label`/`icon`, `current_step` (+ `current_step_label`), `updated_at`, the raw `session` row, and a `resume_url` built through the **current portal's** routes — `resource_url_for(record, wizard:, step:)` for a `wizard`-macro **anchored** mount, the named route for a `register_wizard` mount; `nil` + `resume_unresolved_reason` when the row can't be resolved here (e.g. a non-anchored `wizard`-macro run). **Narrowing.** For the per-record / per-wizard resume widget ("does this record have an unfinished draft of wizard X?"), pass the optional `anchor:`/`wizard:` filters — they narrow **in the query, before enrichment**, so discarded rows are never URL-resolved or anchor-loaded (cheaper than `select`-ing the array, which enriches every row first). They compose, and the `wizard + anchor` pair is index-covered: `…in_progress_for(vc, wizard: ConfigureCompanyWizard, anchor: company).first`. Don't reach into `e.session.anchor` to filter (a polymorphic load per row). For ad-hoc post-filtering the array still works — `e.wizard_class` is already on each entry.
+Each entry exposes the wizard's `label`/`icon`, `current_step` (+ `current_step_label`), `updated_at`, the raw `session` row, and a `resume_url` built through the **current portal's** routes — the named route for a `register_wizard` mount, `resource_url_for(record, wizard:, step:)` for a `wizard`-macro **anchored** mount, and for a **non-anchored** `wizard`-macro run the resource whose definition registers that wizard class; `nil` + `resume_unresolved_reason` when the row can't be resolved here.
+
+Each entry also exposes a **`cancel_url`** — the `DELETE` target that abandons the run — resolved from the *same* mount through its own named cancel route. Never derive it by string-munging `resume_url`: that drops query params and mis-resolves for a run with no `current_step` (whose resume URL is the bare launch path). The two resolve **independently**, so an unresumable row is still cancellable rather than stranded in the list. Render it as a **form**, not a link — cancelling runs every step's `on_rollback`, destroys its `persist`'d records, and deletes the row:
+
+```ruby
+form(action: entry.cancel_url, method: "post") do
+  input(type: "hidden", name: "_method", value: "delete")
+  input(type: "hidden", name: "authenticity_token", value: helpers.form_authenticity_token)
+  # `turbo_confirm`, NOT `confirm` — `data-confirm` is Rails UJS and never fires under Turbo.
+  button(type: "submit", data: {turbo_confirm: "Discard this draft? This can't be undone."}) { "Cancel" }
+end
+```
+
+**Narrowing.** For the per-record / per-wizard resume widget ("does this record have an unfinished draft of wizard X?"), pass the optional `anchor:`/`wizard:` filters — they narrow **in the query, before enrichment**, so discarded rows are never URL-resolved or anchor-loaded (cheaper than `select`-ing the array, which enriches every row first). They compose, and the `wizard + anchor` pair is index-covered: `…in_progress_for(vc, wizard: ConfigureCompanyWizard, anchor: company).first`. Don't reach into `e.session.anchor` to filter (a polymorphic load per row). For ad-hoc post-filtering the array still works — `e.wizard_class` is already on each entry.
 
 ## Storage & config
 
@@ -431,6 +499,7 @@ Plutonium.configure do |config|
   config.wizards.encrypt_data = false      # encrypt every wizard's data at rest (needs AR encryption keys)
   config.wizards.database = :primary       # reserved — v1 supports :primary only (else raises at boot)
   config.wizards.attachment_backend = nil  # server-side attachment staging backend (nil = auto-detect active_shrine/AS)
+  config.wizards.width = :md               # default step page width (:sm/:md/:lg/:xl/:full) — NOT tied to default_page_width
 end
 ```
 

data/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.63.0] - 2026-08-22
+
+### Bug Fixes
+
+- Normalize default_phone_country to lowercase ISO2
+- Stop formatter: leaking into typed display components
+- Stop copied input classes from restyling the slim select panel
+- Explain the draft-only Publish menu with both action policies
+- Show the PublishPost interaction and unclip long file captions
+- Drop the redundant is_a? guard from the tour policy snippet
+- Nest litestream and job roles under servers: in generated deploy.yml
+- Let action dropdowns size to their longest label ([#70](https://github.com/radioactive-labs/plutonium-core/issues/70))
+- [**breaking**] Isolate Rodauth session state per configuration ([#73](https://github.com/radioactive-labs/plutonium-core/issues/73))
+- Stop a nil entity_scope persisting in the policy context ([#74](https://github.com/radioactive-labs/plutonium-core/issues/74))
+- Stop a component-class `as:` crashing on `to_sym` ([#75](https://github.com/radioactive-labs/plutonium-core/issues/75))
+- Honour `as: :hidden` when declared on input ([#83](https://github.com/radioactive-labs/plutonium-core/issues/83))
+- Resolve the parent on routes nested under a singular resource ([#81](https://github.com/radioactive-labs/plutonium-core/issues/81))
+- [**breaking**] Decide wizard finalize after staging the submission ([#89](https://github.com/radioactive-labs/plutonium-core/issues/89))
+- Size layouts to the visible viewport, not 100vh ([#90](https://github.com/radioactive-labs/plutonium-core/issues/90))
+- Call to_s on attachment filename before Phlex title attribute ([#92](https://github.com/radioactive-labs/plutonium-core/issues/92))
+- Relation_scope written as an instance method silently does nothing ([#96](https://github.com/radioactive-labs/plutonium-core/issues/96))
+- Stop Turbo's cross-document node swap failing system tests ([#98](https://github.com/radioactive-labs/plutonium-core/issues/98))
+- Retry slim-select instead of waiting on it ([#105](https://github.com/radioactive-labs/plutonium-core/issues/105))
+- Apply an association's scope when creating through a nested route ([#106](https://github.com/radioactive-labs/plutonium-core/issues/106))
+
+### Documentation
+
+- Add homepage depth & proof upgrade design spec
+- Warn that :root token overrides must be mirrored in .dark
+
+### Features
+
+- Allow opting out of the grid card footer with `footer: false`
+- Add render_before_fields/render_after_fields display hooks
+- Hide show-page metadata rail in a kanban card's modal
+- Add link:/button: HTML attribute bags to actions
+- Homepage depth & proof upgrade ([#69](https://github.com/radioactive-labs/plutonium-core/issues/69))
+- Collapse overflowing breadcrumbs, fix singular-route segments ([#72](https://github.com/radioactive-labs/plutonium-core/issues/72))
+- Generate a Rodauth ManagementConstraint when an admin account exists
+- Resolve proc-valued input options on every form ([#87](https://github.com/radioactive-labs/plutonium-core/issues/87))
+- Eager-load what a collection is about to render ([#91](https://github.com/radioactive-labs/plutonium-core/issues/91))
+- Native drag-and-drop reordering for tables, nested tables and grids ([#77](https://github.com/radioactive-labs/plutonium-core/issues/77))
+- Add display_layout and render sections as cards ([#93](https://github.com/radioactive-labs/plutonium-core/issues/93))
+- Constrain standalone form width ([#94](https://github.com/radioactive-labs/plutonium-core/issues/94))
+- Per-wizard width override, independent of resource pages ([#97](https://github.com/radioactive-labs/plutonium-core/issues/97))
+- Resume/cancel flow, pre_submit, and Turbo Stream completion ([#68](https://github.com/radioactive-labs/plutonium-core/issues/68))
+- Run interactions out of band on a persisted, resumable run ([#99](https://github.com/radioactive-labs/plutonium-core/issues/99))
+- Carry files and typed attributes into the run ([#100](https://github.com/radioactive-labs/plutonium-core/issues/100))
+- Install generator, sweep concurrency, and an experimental template ([#101](https://github.com/radioactive-labs/plutonium-core/issues/101))
+- Add a blog with RSS and the Plutonium launch post ([#102](https://github.com/radioactive-labs/plutonium-core/issues/102))
+- Refresh the runs index while work is outstanding ([#104](https://github.com/radioactive-labs/plutonium-core/issues/104))
+- Declare which associations get nested routes ([#107](https://github.com/radioactive-labs/plutonium-core/issues/107))
+
+### Miscellaneous Tasks
+
+- Patch pagy CVE, five npm advisories, refresh appraisal locks ([#78](https://github.com/radioactive-labs/plutonium-core/issues/78))
+- Prune the 0.49.0 notice from post_install_message ([#80](https://github.com/radioactive-labs/plutonium-core/issues/80))
+- Clear 11 npm advisories via lockfile updates
+
+### Refactoring
+
+- Drop is_a? guards from record-action policy methods
+
+### Testing
+
+- Update the nested-association tests to the route-config lookup ([#88](https://github.com/radioactive-labs/plutonium-core/issues/88))
+
 ## [0.62.2] - 2026-07-09
 
 ### Bug Fixes

data/CLAUDE.md

@@ -159,6 +159,93 @@ yarn docs:build    # Build for production
 2. Add helper method in `Plutonium::Interaction::Outcome::Success`
 3. Document usage
 
+## Writing Docs and Blog Posts
+
+Docs and posts in this repo are read by two audiences: developers, and AI assistants
+(the skills in `.claude/skills/` are synced to `docs/public/skills/` and shipped).
+A wrong example does not just mislead a reader. It gets reproduced as code.
+
+### Verify every code sample
+
+**Never publish a snippet you have not checked against this codebase.** Reading the
+docs is not enough; the docs have been wrong. Two real cases:
+
+- `as: :phlexi_tag` was in three docs and a skill. `ResolvesTags#component_for`
+  dispatches via `send(:"#{tag}_tag")`, so it resolved to `phlexi_tag_tag` and
+  raised `NoMethodError`. The working values are `:phlexi_render` and `:phlexi`.
+- A per-portal override example declared `as: :text` on a text column (dead code)
+  and commented that the definition decides which fields admins see (it does not).
+
+When a claim is mechanical, prove it at runtime rather than by reading:
+
+```bash
+cd test/dummy && RAILS_ENV=test bin/rails runner 'puts SomeClass.instance_methods.grep(/x/)'
+```
+
+### Invariants a sample must not violate
+
+- **Don't declare what is auto-detected.** `field :title` matching the detected type
+  is dead code (`reference/resource/definition.md`).
+- **Definition = how a field renders. Policy = whether it appears.** "Only admins see
+  this" is `permitted_attributes_for_*`, never a definition line or a `condition:`.
+- **Pages expose the record as `object`**, not `resource`.
+- **Interactions:** `attribute :resource` (no `class:`); rescue
+  `ActiveRecord::RecordInvalid` around any `create!`/`update!`/`save!`.
+- **Policies:** never put `*_attributes` hashes in `permitted_attributes_for_*`.
+
+### Voice
+
+Match the reference docs: direct, concrete, no throat-clearing. Specifically avoid
+the tells that make writing read as machine-generated:
+
+- **No em dashes.** Use commas, colons, parentheses, or two sentences.
+- No "It's not X, it's Y" or "The pitch isn't… The pitch is…" constructions.
+- No tidy-summary line after every example ("That's the Rails bargain in miniature").
+- No stacked negation before the real claim, no "critically", no "genuinely".
+- Cut a sentence that restates the one before it.
+
+Deliberate parallelism and a stated opinion are fine. The tell is *unearned*
+rhetoric, not rhetoric itself.
+
+### Blog mechanics
+
+Posts are markdown in `docs/blog/`. Frontmatter:
+
+```yaml
+---
+title: "Introducing Plutonium: Rails conventions, past CRUD"   # must read cold
+titleTemplate: "Plutonium Blog"
+date: 2026-08-19
+description: One sentence. Becomes the RSS description and the index subtitle.
+author: Stefan Froelich
+tags: [announcement, rails]
+draft: true        # omit to publish
+---
+```
+
+- Put `<BlogMeta />` directly under the `# ` heading; it renders date, author and
+  the back link from frontmatter.
+- **A title must be legible with no context.** It travels via RSS, social and pasted
+  links, where the site name is absent, so include both "Plutonium" and "Rails".
+  "Plutonium" alone collides with the element and other projects.
+- **The slug must match the title.** Renaming the title means renaming the file;
+  URLs are permanent once published.
+- A post is distinguished from the section index by having a `date`. `draft: true`
+  hides it from the index and the feed.
+- `yarn docs:build` must pass. Dead internal links fail the build.
+
+### Screenshots
+
+Match the existing ones or they look foreign next to each other:
+
+- **2480px wide** (1240 CSS at `deviceScaleFactor: 2`); height varies with content.
+- **Light mode, icon rail collapsed.** In `test/dummy`, set
+  `localStorage.theme = 'light'` and `localStorage.pu_rail_pinned = 'false'`.
+- Capture from the running dummy app with realistic, **distinct** data. Generated
+  titles that repeat across rows read as broken data.
+- Crop dead space: `magick shot.png -crop 2480x1290+0+0 +repage shot.png`.
+- Live under `docs/public/images/<section>/`.
+
 ## Skills System
 
 The `.claude/skills/` directory contains documentation for AI assistants:

data/Rakefile

@@ -35,12 +35,46 @@ end
 task :test_generators do
   failures = []
 
+  # This task DESTROYS uncommitted work under test/dummy — `git checkout --` plus
+  # `git clean -fd`, unconditionally, after every file. That is required (see
+  # below) but it is not something to discover afterwards, so refuse to start on
+  # a dirty tree. Set FORCE=1 to run anyway; CI checkouts are clean and never
+  # trip this.
+  dirty = `git status --porcelain -- test/dummy`.strip
+  if !dirty.empty? && ENV["FORCE"] != "1"
+    abort <<~MSG
+      test/dummy has uncommitted changes:
+
+      #{dirty.lines.map { |l| "  #{l}" }.join}
+      This task git-restores and git-cleans test/dummy between generator test
+      files, which would discard them. Commit or stash first, or re-run with
+      FORCE=1 to accept the loss.
+    MSG
+  end
+
+  # Between files, not just inside them. A generator that shells out — e.g.
+  # `generate "pu:pkg:package"` — goes through Rails' `generate` action, which
+  # passes abort_on_failure: true, so Thor calls `abort` in the test process
+  # when the child fails. SystemExit skips minitest's teardown, so anything the
+  # test wrote into test/dummy survives; since every generator test file boots
+  # the dummy app at require time, one aborted file would take down every file
+  # after it. Cleaning here can't be skipped by an aborting child.
+  #
+  # An at_exit hook inside the tests cannot do this job: minitest runs the whole
+  # suite from its own at_exit, and handlers fire LIFO, so a hook registered
+  # later runs before any test does.
+  restore_dummy_app = lambda do
+    system("git", "checkout", "--", "test/dummy", out: File::NULL, err: File::NULL)
+    system("git", "clean", "-fd", "test/dummy", out: File::NULL, err: File::NULL)
+  end
+
   FileList["test/generators/**/*_test.rb"].sort.each do |test_file|
     puts "\n=== #{test_file} ==="
     # in: File::NULL — prevents a stray sub-generator prompt from hanging on the inherited TTY.
     unless system(Gem.ruby, "-w", "-Ilib:test", test_file, in: File::NULL)
       failures << test_file
     end
+    restore_dummy_app.call
   end
 
   if failures.any?

data/SECURITY.md

@@ -12,7 +12,7 @@ please upgrade before reporting an issue to confirm it still reproduces.
 
 | Version | Supported          |
 | ------- | ------------------ |
-| Latest release (`0.62.x`) | :white_check_mark: |
+| Latest release (`0.63.x`) | :white_check_mark: |
 | Older releases | :x: |
 
 ## Reporting a Vulnerability