plutonium 0.65.0 → 0.66.0

data/docs/guides/customizing-ui.md

@@ -1,6 +1,6 @@
 # Customizing the UI
 
-Plutonium's UI is built on Phlex, Tailwind 4, and Stimulus. Almost everything you see — pages, forms, displays, tables, components, layouts, even the design tokens — is open for override. This guide is the map. Each section shows the smallest useful example for one kind of customization, then points to the reference for the full surface.
+Plutonium's UI is built on Phlex, Tailwind 4, and Stimulus. Almost everything you see (pages, forms, displays, tables, components, layouts, even the design tokens) is open for override. This guide is the map. Each section shows the smallest useful example for one kind of customization, then points to the reference for the full surface.
 
 When you're not sure where to start, read this top to bottom. When you know what you need, jump to the right section and follow the link to reference.
 
@@ -17,7 +17,7 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-Each nested class inherits from Plutonium's defaults and lets you override only the methods you care about. Don't reimplement the whole layer — use the render hooks below.
+Each nested class inherits from Plutonium's defaults and lets you override only the methods you care about. Don't reimplement the whole layer; use the render hooks below.
 
 → See [Reference › UI › Pages](/reference/ui/pages) for the full hook list.
 
@@ -29,15 +29,17 @@ Most page customization is "I want to add something before/after this section."
 class PostDefinition < ResourceDefinition
   class ShowPage < ShowPage
     def render_before_content
-      div(class: "pu-card pu-card-body") do
-        plain "This post has #{object.comments.count} comments"
+      div(class: "pu-alert pu-alert-info", role: "status") do
+        div(class: "pu-alert-message") { t("blog.posts.show.comment_count", count: object.comments.count) }
       end
     end
   end
 end
 ```
 
-Hooks exist around the header, breadcrumbs, page header, toolbar, content, and footer — pick the one closest to where you want the thing to appear.
+`pu-alert pu-alert-<success|warning|danger|info>` is the same banner the flash messages use, so it already has its dark-mode colors. The text comes from a locale key; see [i18n](/reference/i18n#your-own-components-and-pages).
+
+Hooks exist around the header, breadcrumbs, page header, toolbar, content, and footer: pick the one closest to where you want the thing to appear.
 
 → See [Reference › UI › Pages](/reference/ui/pages) › Page hooks.
 
@@ -56,7 +58,7 @@ class Form < Form
       render_resource_field :published_at
       render_resource_field :category
     end
-    render_actions   # REQUIRED — without this, no submit button
+    render_actions   # REQUIRED: without this, no submit button
   end
 
   private
@@ -126,14 +128,14 @@ class PostCardComponent < Plutonium::UI::Component::Base
     div(class: "pu-card pu-card-body") do
       h3(class: "font-bold text-[var(--pu-text)]") { @post.title }
       p(class: "text-[var(--pu-text-muted)] mt-2") { @post.excerpt }
-      a(href: resource_url_for(@post), class: "pu-btn pu-btn-sm pu-btn-ghost") { "Read more" }
+      a(href: resource_url_for(@post), class: "pu-btn pu-btn-sm pu-btn-ghost") { t("blog.posts.card.read_more") }
     end
   end
 end
 ```
 
 Use it directly in a page, or wire it as a field in the definition. A component
-with its own constructor takes the block form — you build it, so you decide what
+with its own constructor takes the block form: you build it, so you decide what
 it receives:
 
 ```ruby
@@ -143,13 +145,13 @@ end
 ```
 
 `as: SomeComponent` is for a *field* component, which Plutonium constructs with
-the field builder (`Phlexi::Form::Components::Base` / `Phlexi::Display::Components::Base`) — see the reference below.
+the field builder (`Phlexi::Form::Components::Base` / `Phlexi::Display::Components::Base`); see the reference below.
 
 → See [Reference › UI › Components](/reference/ui/components).
 
 ## Phlexi themes (recolor without rewriting)
 
-If all you want is to recolor or restyle the form/display/table, write a `Theme` class instead of overriding the template. Always `super.merge(...)` — never replace wholesale:
+If all you want is to recolor or restyle the form/display/table, write a `Theme` class instead of overriding the template. Always `super.merge(...)`; never replace wholesale:
 
 ```ruby
 class Form < Form
@@ -173,7 +175,7 @@ By default `:new`, `:edit`, and every interactive action render in a slideover p
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  modal :slideover               # default — slide-in from the right
+  modal :slideover               # default: slide-in from the right
   # modal :centered              # centered dialog
   # modal :centered, size: :lg   # centered, wider container
   # modal false                  # full standalone page
@@ -184,7 +186,7 @@ end
 
 ## Layouts and the shell
 
-The layout is the chrome around every resource page — topbar, sidebar, flash region, scripts. Two ways to customize it:
+The layout is the chrome around every resource page: topbar, sidebar, flash region, scripts. Two ways to customize it:
 
 ```bash
 # Per-portal: eject the shell partials and edit them directly
@@ -199,24 +201,24 @@ For programmatic overrides, subclass `Plutonium::UI::Layout::ResourceLayout` and
 
 ## Tailwind, Stimulus, and assets
 
-Plutonium ships with a Tailwind config, design tokens, and a set of Stimulus controllers. To plug into them in your app:
+Plutonium ships with a Tailwind config, design tokens, and a set of Stimulus controllers. Out of the box the app serves the gem's prebuilt `plutonium.css` and `plutonium.min.js`, so app-side Tailwind classes, a new brand palette, token overrides and your own Stimulus controllers need your own bundles first. Run the generator rather than wiring the pipeline by hand:
 
 ```bash
 rails generate pu:core:assets
 ```
 
-This installs the npm packages, creates a `tailwind.config.js` that extends Plutonium's defaults via `plutoniumTailwindConfig.merge`, imports Plutonium's CSS, and registers its Stimulus controllers. After that, you can:
+This installs the npm packages, creates a `tailwind.config.js` that extends Plutonium's defaults via `plutoniumTailwindConfig.merge`, imports Plutonium's CSS, registers its Stimulus controllers, and points `config.assets.stylesheet` / `config.assets.script` at your `application` bundles. It needs `app/assets/stylesheets/application.tailwind.css` and `app/javascript/controllers/index.js` to exist (an app created with `-j esbuild -c tailwind` plus Stimulus). After that, you can:
 
-- Extend the palette under `theme.extend.colors` (always inside `plutoniumTailwindConfig.merge` — a plain spread drops Plutonium's defaults).
-- Use `.pu-btn`, `.pu-card`, `.pu-input`, `.pu-table`, etc. instead of hand-rolling Tailwind chains.
+- Extend the palette under `theme.extend.colors` (always inside `plutoniumTailwindConfig.merge`: a plain spread drops Plutonium's defaults), then rebuild the CSS.
+- Use `.pu-btn`, `.pu-card`, `.pu-input`, `.pu-table`, `.pu-alert`, `.pu-badge`, etc. instead of hand-rolling Tailwind chains.
 - Reference design tokens directly: `bg-[var(--pu-surface)]`, `text-[var(--pu-text-muted)]`, `border-[var(--pu-border)]`. These auto-switch with dark mode.
-- Register your own Stimulus controllers alongside Plutonium's — `registerControllers(application)` is mandatory or the entire interactive layer is dead.
+- Register your own Stimulus controllers alongside Plutonium's. Your `application.js` now replaces the gem's bundle, so `registerControllers(application)` (added by the generator) must stay, or the entire interactive layer is dead.
 
 → See [Reference › UI › Assets](/reference/ui/assets) for the full toolchain, the `.pu-*` class catalog, and design-token reference.
 
 ## ERB views (escape hatch)
 
-When the Phlex page class is the wrong tool — you want to keep an existing ERB layout, you're integrating with a designer's HTML, or you just want to surround the generated page with custom markup — drop an ERB view at the controller path:
+When the Phlex page class is the wrong tool (you want to keep an existing ERB layout, you're integrating with a designer's HTML, or you just want to surround the generated page with custom markup), drop an ERB view at the controller path:
 
 ```
 app/views/posts/show.html.erb
@@ -237,7 +239,7 @@ Keep that line and wrap it to add chrome without giving up the generated page:
 <%= render partial: "related" %>
 ```
 
-Or replace the line entirely for full control. ERB views always win over the Phlex page class when both exist for the same action — reach for this only when Phlex hooks + overrides genuinely can't do the job.
+Or replace the line entirely for full control. ERB views always win over the Phlex page class when both exist for the same action, so reach for this only when Phlex hooks + overrides genuinely can't do the job.
 
 ## When to reach for what
 
@@ -249,18 +251,19 @@ Or replace the line entirely for full control. ERB views always win over the Phl
 | Reuse a UI block across pages | Custom Phlex component |
 | Recolor without changing structure | Phlexi `Theme` class |
 | Swap the topbar or sidebar | `pu:eject:shell` or custom layout class |
-| Change brand color or radius | Design tokens — see [Theming](/guides/theming) |
+| Change brand color | Tailwind `primary` palette via `plutoniumTailwindConfig.merge`, then rebuild. See [Theming](/guides/theming) |
+| Change surfaces, borders or radius | Design tokens (mirrored in `.dark`). See [Theming](/guides/theming) |
 | Add a custom JS interaction | Stimulus controller registered alongside Plutonium's |
 
 ## Gotchas
 
-- **Don't override `view_template` in pages** when a render hook fits — you lose breadcrumbs, header, and DynaFrame (turbo-frame) behavior.
-- **`render_actions` is mandatory** when you write a custom `form_template` — otherwise the form has no submit button.
-- **Always `registerControllers(application)`** in `app/javascript/controllers/index.js`. Without it, every Plutonium-shipped Stimulus controller is dead (color mode, slim-select, flatpickr, easymde, form pre-submit).
+- **Don't override `view_template` in pages** when a render hook fits, or you lose breadcrumbs, header, and DynaFrame (turbo-frame) behavior.
+- **`render_actions` is mandatory** when you write a custom `form_template`, otherwise the form has no submit button.
+- **Once the app serves its own JS bundle, `registerControllers(application)`** must be in `app/javascript/controllers/index.js` (`pu:core:assets` adds it). Without it, every Plutonium-shipped Stimulus controller is dead (color mode, slim-select, flatpickr, easymde, form pre-submit).
 - **Use `plutoniumTailwindConfig.merge`** when extending the Tailwind theme. A plain object spread drops Plutonium's defaults.
-- **Prefer `.pu-*` classes and `var(--pu-*)` tokens** over hardcoded `gray-X/dark:gray-Y` pairs — they switch with dark mode automatically.
+- **Style with `.pu-*` classes first, `var(--pu-*)` tokens second, raw palette pairs last.** The classes and tokens switch with dark mode; a hand-written `gray-X/dark:gray-Y` pair needs its own dark twin and won't follow a rebrand.
 
 ## Related
 
-- [Theming](/guides/theming) — design tokens, brand colors.
-- [Reference › UI](/reference/ui/) — the full surface area for every override above.
+- [Theming](/guides/theming): design tokens, brand colors.
+- [Reference › UI](/reference/ui/): the full surface area for every override above.

data/docs/guides/dashboards.md

@@ -4,7 +4,7 @@
 Dashboards are experimental: the DSL and behavior may change in a future release.
 :::
 
-A dashboard is a page of cards: headline numbers, charts and free-form panels, declared in one Ruby class and mounted with a single routes line. Every card loads in its own lazy turbo frame, so the page paints immediately and each card's queries run in a separate request as it scrolls into view.
+A dashboard is a page of cards: headline numbers, charts and free-form panels, declared in one Ruby class and mounted with a single routes line. By default every card loads in its own lazy turbo frame, so the page paints immediately and each card's queries run in a separate request as it scrolls into view.
 
 ![A dashboard with four metric cards, an area chart of signups per day, a donut chart and a full-width welcome card](/images/guides/dashboard-overview.png)
 

data/docs/guides/index.md

@@ -25,12 +25,12 @@ aside: false
       { name: 'Nested resources', link: '/plutonium-core/guides/nested-resources' },
       { name: 'Multi-tenancy', link: '/plutonium-core/guides/multi-tenancy' },
       { name: 'Search & filtering', link: '/plutonium-core/guides/search-filtering' },
-      { name: 'Wizards', desc: 'Multi-step flows — onboarding, checkout, branching create.', link: '/plutonium-core/guides/wizards' },
-      { name: 'Kanban boards', desc: 'Drag-and-drop board view — columns, moves, positioning, WIP limits.', link: '/plutonium-core/guides/kanban' },
+      { name: 'Wizards', desc: 'Multi-step flows: onboarding, checkout, branching create.', link: '/plutonium-core/guides/wizards' },
+      { name: 'Kanban boards', desc: 'Drag-and-drop board view: columns, moves, positioning, WIP limits.', link: '/plutonium-core/guides/kanban' },
       { name: 'Dashboards', desc: 'Metric, chart and free-form cards, each loaded in its own lazy turbo frame.', link: '/plutonium-core/guides/dashboards' },
     ]},
     { group: 'Customization', items: [
-      { name: 'Customizing the UI', desc: 'A map of the override surface — pages, forms, displays, tables, components, layouts.', link: '/plutonium-core/guides/customizing-ui' },
+      { name: 'Customizing the UI', desc: 'A map of the override surface: pages, forms, displays, tables, components, layouts.', link: '/plutonium-core/guides/customizing-ui' },
       { name: 'Theming', desc: 'Design tokens and brand colors.', link: '/plutonium-core/guides/theming' },
     ]},
     { group: 'Quality', items: [

data/docs/guides/kanban.md

@@ -1,29 +1,29 @@
 # Kanban Boards
 
 ::: warning Experimental
-Kanban boards are experimental — the DSL and behavior may change in a future release.
+Kanban boards are experimental: the DSL and behavior may change in a future release.
 :::
 
-Turn any resource index into a drag-and-drop kanban board — columns, WIP limits, quick-add, column actions, and opt-in realtime — all from a single `kanban do…end` block in your definition.
+Turn any resource index into a drag-and-drop kanban board: columns, WIP limits, quick-add, column actions, and opt-in realtime, all from a single `kanban do…end` block in your definition.
 
-![A kanban board grouped by status — cards with badges, a WIP badge on Pending, a quick-add button, and collapsible columns](/images/guides/kanban-board.png)
+![A kanban board grouped by status: cards with badges, a WIP badge on Pending, a quick-add button, and collapsible columns](/images/guides/kanban-board.png)
 
 ## What you get
 
 - Drag cards between columns; the server persists the column change and the position within the column.
-- Decimal fractional positioning — cards always land exactly where you drop them without renumbering.
+- Decimal fractional positioning: cards always land exactly where you drop them without renumbering.
 - Per-column `+ Add` button opens the resource's normal new form; the new card is placed in that column (`on_enter` + positioning applied post-create).
 - Column actions run an interaction against all (or visible) cards in a column.
 - WIP limits, locked columns, and cross-column drop restrictions enforced server-side.
 - Opt-in realtime: every connected viewer sees the same board state after any move.
 
-## Worked example — Task board
+## Worked example: Task board
 
-A complete board for a `Task` model grouped by status — migration, model, definition, and policy.
+A complete board for a `Task` model grouped by status, migration, model, definition, and policy.
 
 ### 1. Migration
 
-The model needs a `decimal` position column. Use the **`t.position`** helper — it adds a `decimal` column already tuned for fractional ordering (`precision: 16, scale: 8`), so you can't pick a scale too small to rebalance cleanly (see [Positioning › Migration](/reference/kanban/positioning#migration)).
+The model needs a `decimal` position column. Use the **`t.position`** helper, it adds a `decimal` column already tuned for fractional ordering (`precision: 16, scale: 8`), so you can't pick a scale too small to rebalance cleanly (see [Positioning › Migration](/reference/kanban/positioning#migration)).
 
 ```ruby
 class CreateTasks < ActiveRecord::Migration[8.1]
@@ -102,25 +102,25 @@ class TaskPolicy < ResourcePolicy
 end
 ```
 
-### 5. Routes — no changes needed
+### 5. Routes: no changes needed
 
 The `kanban_move` member route is wired automatically when the controller includes `Plutonium::Resource::Controllers::KanbanActions` (included by default in all Plutonium resource controllers).
 
 Visit the resource index and use the view switcher to select the Kanban view.
 
-![After dragging a card from Doing to Done — both column frames re-render and the WIP badge on Doing updates in place](/images/guides/kanban-after-move.png)
+![After dragging a card from Doing to Done: both column frames re-render and the WIP badge on Doing updates in place](/images/guides/kanban-after-move.png)
 
 ### When a drop is rejected
 
-If a move is refused server-side — the destination is at its `wip:` limit, its `accepts:` policy rejects the card, or the source column is `locked:` — the card snaps back to where it started **and** a dismissable toast explains why:
+If a move is refused server-side: the destination is at its `wip:` limit, its `accepts:` policy rejects the card, or the source column is `locked:`, then the card snaps back to where it started **and** a dismissable toast explains why:
 
 ![A warning toast reading “Pending” is at its WIP limit (5) after a rejected drop](/images/guides/kanban-wip-toast.png)
 
-The toast is appended to a `#kanban-flash` region in the board shell (outside the per-column frames, so it survives the snap-back re-render). The client-side drag hints already grey out columns a card plainly can't enter, so the toast mainly surfaces the cases the browser can't pre-check — most commonly a WIP-full column or a `kanban_move?` denial.
+The toast is appended to a `#kanban-flash` region in the board shell (outside the per-column frames, so it survives the snap-back re-render). The client-side drag hints already grey out columns a card plainly can't enter, so the toast mainly surfaces the cases the browser can't pre-check, most commonly a WIP-full column or a `kanban_move?` denial.
 
 ### Opening a card
 
-Clicking a card opens its show page. Where it opens is controlled by [`show_in`](/reference/kanban/dsl#show_in) — full-page by default, or a **centered modal** that keeps the board visible behind it:
+Clicking a card opens its show page. Where it opens is controlled by [`show_in`](/reference/kanban/dsl#show_in), full-page by default, or a **centered modal** that keeps the board visible behind it:
 
 ![A card's show page open in a centered modal over the board, with an expand icon to open the full page](/images/guides/kanban-show-centered-modal.png)
 
@@ -135,14 +135,14 @@ end
 ```
 
 - Set `show_in :modal` on the **definition** to open show in a modal from the table, grid, and board alike. Set it on the **kanban block** to change only the board. An unset board inherits the definition (which defaults to `:page`).
-- The show modal is always **centered** — distinct from `new`/`edit`, which follow the definition's `modal_mode` (a slideover by default).
+- The show modal is always **centered**: distinct from `new`/`edit`, which follow the definition's `modal_mode` (a slideover by default).
 - From inside the modal, an expand icon opens the record's full page in a new tab. ⌘/Ctrl-click (or middle-click) on a card does the same directly.
 
 ---
 
-## Worked example — Status enum board
+## Worked example: Status enum board
 
-A shorter example that groups by a Rails enum for status. Cards reuse `grid_fields` for their slot layout — no explicit `card_fields` needed.
+A shorter example that groups by a Rails enum for status. Cards reuse `grid_fields` for their slot layout, so no explicit `card_fields` needed.
 
 ```ruby
 class KitchenSinkDefinition < ResourceDefinition
@@ -168,7 +168,7 @@ Key points:
 - `role: :backlog` enables the `+ Add` button (equivalent to `add: true`).
 - `wip: 5` caps the Pending column; a cross-column drop that would push it past 5 is rejected server-side.
 - `role: :done` collapses the Archived column by default and shows a green header dot.
-- `on_enter` here assigns the attribute in memory (`ks.status = :active`). The framework calls `record.save!` automatically when the record has unsaved changes after `on_enter` returns — you do not need to call `update!` explicitly.
+- `on_enter` here assigns the attribute in memory (`ks.status = :active`). The framework calls `record.save!` automatically when the record has unsaved changes after `on_enter` returns; you do not need to call `update!` explicitly.
 
 ---
 
@@ -195,7 +195,7 @@ Use `columns do…end` when the column list depends on request context (`current
 ```ruby
 kanban do
   columns do
-    # `self` is the view_context — current_user, params, helpers all work.
+    # `self` is the view_context: current_user, params, helpers all work.
     current_user.projects.map do |project|
       Plutonium::Kanban::Column.new(
         :"project_#{project.id}",
@@ -228,7 +228,7 @@ class TaskDefinition < ResourceDefinition
 end
 ```
 
-Note that **`enter_interaction:` is not supported on dynamic boards** — its hidden action is registered from the static column list at class-load time, and its key is internal (column-scoped) so it can't be registered manually the way a column action can. A drop into such a column snaps back rather than committing (it doesn't crash). Use a static board if a column needs an `enter_interaction:`.
+Note that **`enter_interaction:` is not supported on dynamic boards**: its hidden action is registered from the static column list at class-load time, and its key is internal (column-scoped) so it can't be registered manually the way a column action can. A drop into such a column snaps back rather than committing (it doesn't crash). Use a static board if a column needs an `enter_interaction:`.
 :::
 
 ### Column options
@@ -236,11 +236,11 @@ Note that **`enter_interaction:` is not supported on dynamic boards** — its hi
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `label:` | String | `key.to_s.titleize` | Column header text |
-| `color:` | Symbol or String | `nil` | Dot color in the column header — `:red`, `:orange`, `:amber`, `:yellow`, `:green`, `:blue`, `:purple`, `:pink`, `:gray`, or a raw CSS value |
+| `color:` | Symbol or String | `nil` | Dot color in the column header, `:red`, `:orange`, `:amber`, `:yellow`, `:green`, `:blue`, `:purple`, `:pink`, `:gray`, or a raw CSS value |
 | `scope:` | Symbol or Proc | `nil` | Filters the resource relation to this column's cards. Symbol → named scope; Proc → 0-arg lambda called with `instance_exec` on the relation (e.g. `-> { where(status: "todo") }`) |
 | `on_enter:` | Symbol or Proc | `nil` | Called when a card lands in this column. Symbol → `record.public_send(sym)`; Proc → 1-arg lambda `->(record) { … }` where `self` is the view context |
-| `on_exit:` | Symbol or Proc | `nil` | Source-side counterpart to `on_enter:` — called when a card **leaves** this column on a cross-column move, before the destination's `on_enter`, in the same transaction. For source-tied side effects (stop a timer, release a slot). Drag-moves only (not destroy/programmatic/quick-add); skipped on same-column reorders |
-| `enter_interaction:` | Class | `nil` | Record-scoped interaction run on a cross-column drop into this column — opens a modal to collect input, then commits atomically. See [Interaction on drop](#interaction-on-drop) |
+| `on_exit:` | Symbol or Proc | `nil` | Source-side counterpart to `on_enter:`: called when a card **leaves** this column on a cross-column move, before the destination's `on_enter`, in the same transaction. For source-tied side effects (stop a timer, release a slot). Drag-moves only (not destroy/programmatic/quick-add); skipped on same-column reorders. Use a model callback instead only when other save paths (edit form, API, import) must be covered too, and then drop the `on_exit:` so the work isn't done twice. |
+| `enter_interaction:` | Class | `nil` | Record-scoped interaction run on a cross-column drop into this column; opens a modal to collect input, then commits atomically. See [Interaction on drop](#interaction-on-drop) |
 | `role:` | `:backlog`, `:done`, `:lost` | `nil` | Preset shorthand (see below) |
 | `collapsed:` | Boolean | `false` | Start collapsed |
 | `add:` | Boolean | `false` | Show `+ Add` quick-add button |
@@ -256,7 +256,7 @@ Note that **`enter_interaction:` is not supported on dynamic boards** — its hi
 | `:done` | `color: :green, collapsed: true` |
 | `:lost` | `color: :red, collapsed: true` |
 
-`:done` and `:lost` are the two terminal roles (both collapsed by default) — the
+`:done` and `:lost` are the two terminal roles (both collapsed by default), the
 won/lost pair for pipelines like leads, deals, or tickets; the colour signals the
 outcome.
 
@@ -284,8 +284,8 @@ column :done,
 end
 ```
 
-- `on: :all` — passes IDs of **all** cards in the column (ignoring `per_column`).
-- `on: :visible` — passes IDs of only the rendered, `per_column`-capped cards.
+- `on: :all`: passes IDs of **all** cards in the column (ignoring `per_column`).
+- `on: :visible`: passes IDs of only the rendered, `per_column`-capped cards.
 
 Column actions are rendered as buttons in the column header. They open the normal interactive-action modal (with form, authorization, success/failure handling) pre-loaded with the column's card IDs.
 
@@ -293,7 +293,7 @@ Column actions are rendered as buttons in the column header. They open the norma
 
 ## Interaction on drop
 
-A column can declare `enter_interaction:` to run an authorization-aware, input-collecting [Interaction](/reference/behavior/interactions) when a card is dropped **into** it from another column. Use it when entering a column needs more than a membership flip — a reason, a notification email, an audit entry.
+A column can declare `enter_interaction:` to run an authorization-aware, input-collecting [Interaction](/reference/behavior/interactions) when a card is dropped **into** it from another column. Use it when entering a column needs more than a membership flip, a reason, a notification email, an audit entry.
 
 ```ruby
 column :lost,
@@ -301,13 +301,13 @@ column :lost,
   enter_interaction: MarkLostInteraction
 ```
 
-`enter_interaction:` takes an **Interaction class**. It must be **record-scoped** — it declares `attribute :resource` and acts on the single dropped card. A bulk (`attribute :resources`) interaction is not valid here; that shape is for [column actions](#column-actions).
+`enter_interaction:` takes an **Interaction class**. It must be **record-scoped**: it declares `attribute :resource` and acts on the single dropped card. A bulk (`attribute :resources`) interaction is not valid here; that shape is for [column actions](#column-actions).
 
-The interaction is **auto-registered as a hidden record action** under a column-scoped key (`:lost` → `:lost_enter_interaction`), so two columns can reuse the same interaction class without colliding. "Hidden" means it does **not** appear as an action button on the show page, table rows, or grid cards — it is reachable only by dropping a card into the column.
+The interaction is **auto-registered as a hidden record action** under a column-scoped key (`:lost` → `:lost_enter_interaction`), so two columns can reuse the same interaction class without colliding. "Hidden" means it does **not** appear as an action button on the show page, table rows, or grid cards, it is reachable only by dropping a card into the column.
 
 ### The interaction
 
-A drop interaction is an ordinary record-scoped interaction — nothing kanban-specific in the class:
+A drop interaction is an ordinary record-scoped interaction with nothing kanban-specific in the class:
 
 ```ruby
 class MarkLostInteraction < ResourceInteraction
@@ -330,7 +330,7 @@ end
 
 ### Authorization
 
-The drop is authorized by the single **`kanban_move?`** predicate — the interaction has **no policy method of its own**. To gate this specific transition, branch on the destination column, which `kanban_move?` reads from its authorization context (`kanban_to`):
+The drop is authorized by the single **`kanban_move?`** predicate, the interaction has **no policy method of its own**. To gate this specific transition, branch on the destination column, which `kanban_move?` reads from its authorization context (`kanban_to`):
 
 ```ruby
 class TaskPolicy < ResourcePolicy
@@ -341,7 +341,7 @@ class TaskPolicy < ResourcePolicy
 end
 ```
 
-This keeps authorization in one place: `kanban_move?` gates every move, and the `to` (and `from`) column context lets it gate a specific transition — no per-interaction predicate, no `condition:` proc. If the check fails the drop is refused and the card stays put. See [Authorization](../reference/kanban/authorization) for the full `from`/`to` context.
+This keeps authorization in one place: `kanban_move?` gates every move, and the `to` (and `from`) column context lets it gate a specific transition: no per-interaction predicate, no `condition:` proc. If the check fails the drop is refused and the card stays put. See [Authorization](../reference/kanban/authorization) for the full `from`/`to` context.
 
 ### Two flows, split by intent
 
@@ -353,9 +353,9 @@ This keeps authorization in one place: `kanban_move?` gates every move, and the
 A column can declare `on_enter:` and `enter_interaction:` together. When it does:
 
 - `on_enter` owns the **membership attribute** (the column's grouping value, e.g. `status`).
-- `enter_interaction` owns the **extras** — the reason, the mail, the audit trail.
+- `enter_interaction` owns the **extras**: the reason, the mail, the audit trail.
 
-If the interaction also writes the membership attribute it **must set the same value** `on_enter` sets (idempotent). In this dummy-app example the `:blocked` column does exactly that — `on_enter` sets `status = "blocked"` and the interaction's `execute` re-asserts `status: "blocked"` while adding the reason:
+If the interaction also writes the membership attribute it **must set the same value** `on_enter` sets (idempotent). In this dummy-app example the `:blocked` column does exactly that, `on_enter` sets `status = "blocked"` and the interaction's `execute` re-asserts `status: "blocked"` while adding the reason:
 
 ```ruby
 column :blocked,
@@ -364,25 +364,25 @@ column :blocked,
   enter_interaction: BlockTaskInteraction
 ```
 
-When a column declares **only** a `enter_interaction` (no `on_enter`, like `:lost` above), the interaction owns everything — including the membership write — because there is no `on_enter` to do it.
+When a column declares **only** a `enter_interaction` (no `on_enter`, like `:lost` above), the interaction owns everything, including the membership write, because there is no `on_enter` to do it.
 
 ### Same-column drops run positioning only
 
-Reordering a card **within** its current column runs positioning only. Neither `on_enter` nor the `enter_interaction` fires — both represent *entering* a column, and a same-column reorder is not an entry. Only cross-column drops trigger them.
+Reordering a card **within** its current column runs positioning only. Neither `on_enter` nor the `enter_interaction` fires; both represent *entering* a column, and a same-column reorder is not an entry. Only cross-column drops trigger them.
 
 ### Atomicity and failure
 
-Interaction validation failure rolls the **whole transaction back** — the membership write included — and re-renders the modal with errors. The move context is preserved, so the user can fix the input and resubmit. Nothing is persisted on failure. Keep side-effects on `deliver_later` (mailers, jobs): a rolled-back failure then sends no stray mail, because the enqueue never commits.
+Interaction validation failure rolls the **whole transaction back**, the membership write included, and re-renders the modal with errors. The move context is preserved, so the user can fix the input and resubmit. Nothing is persisted on failure. Keep side-effects on `deliver_later` (mailers, jobs): a rolled-back failure then sends no stray mail, because the enqueue never commits.
 
 ### Success feedback and the response limitation
 
 On success the board's column frames re-render and the modal closes. The interaction's success **message** (`succeed(resource).with_message("Marked as lost")`) is surfaced as a toast.
 
 ::: warning Custom success responses are not honored on the drop path
-A drop interaction's custom success *response* — `with_redirect_response`, `with_file_response`, etc. — is **not** honored when it runs from a drop: the board simply re-renders and closes the modal. Keep drop interactions to simple state + extras mutations, and use `.with_message` for feedback.
+A drop interaction's custom success *response*, `with_redirect_response`, `with_file_response`, etc., is **not** honored when it runs from a drop: the board simply re-renders and closes the modal. Keep drop interactions to simple state + extras mutations, and use `.with_message` for feedback.
 :::
 
-There is no card "snap-back" to worry about on cancel — native drag never moves the card's DOM node, so canceling the modal just closes it and the card stays where it was.
+There is no card "snap-back" to worry about on cancel: native drag never moves the card's DOM node, so canceling the modal just closes it and the card stays where it was.
 
 ---
 
@@ -390,35 +390,35 @@ There is no card "snap-back" to worry about on cancel — native drag never move
 
 By default Plutonium uses decimal fractional positioning: cards always slot exactly where you drop them without ever renumbering the whole column. You need:
 
-1. A `decimal` database column — use the `t.position` helper (`precision: 16, scale: 8`). Hand-rolling it, keep `scale` at **8 or more**: `scale: 6` exactly matches the `1e-6` rebalance threshold and the last subdivision can round into a neighbour.
+1. A `decimal` database column: use the `t.position` helper (`precision: 16, scale: 8`). Hand-rolling it, keep `scale` at **8 or more**: `scale: 6` exactly matches the `1e-6` rebalance threshold and the last subdivision can round into a neighbour.
 2. `include Plutonium::Positioning::Model` in the model.
-3. `positioned_on :position, scope: :status` — the `scope:` option groups positions by the grouping attribute so cards in different columns don't compete.
+3. `positioned_on :position, scope: :status`: the `scope:` option groups positions by the grouping attribute so cards in different columns don't compete.
 
 ### Position modes
 
-`position_on` is the same verb inside and outside `kanban do…end`. Declared on the **definition** it makes the resource's index table and card grid [drag-reorderable](/reference/resource/positioning); declared inside the board it configures the board. A board that declares none **inherits the definition's** (falling back to `:position`, Mode A), so a resource that already reorders in its table needs nothing extra here. Declaration order in the class body doesn't matter — the board resolves this lazily.
+`position_on` is the same verb inside and outside `kanban do…end`. Declared on the **definition** it makes the resource's index table and card grid [drag-reorderable](/reference/resource/positioning); declared inside the board it configures the board. A board that declares none **inherits the definition's** (falling back to `:position`, Mode A), so a resource that already reorders in its table needs nothing extra here. Declaration order in the class body doesn't matter; the board resolves this lazily.
 
 ```ruby
 kanban do
-  # Mode A (default) — delegate to Plutonium::Positioning::Model.
+  # Mode A (default): delegate to Plutonium::Positioning::Model.
   # Uses :position attribute, requires the model concern.
   position_on :position
 
   # Mode A with a custom attribute name:
   position_on :sort_order
 
-  # Mode B — BYO positioning. The block receives a Move struct.
+  # Mode B: BYO positioning. The block receives a Move struct.
   # Use when you want to call a custom service or use a different ordering scheme.
   position_on :sort_order do |move|
-    # move.record  — the dropped record
-    # move.column  — the destination column key (Symbol)
-    # move.prev    — the record immediately before the drop slot (or nil)
-    # move.next    — the record immediately after the drop slot (or nil)
-    # move.index   — 0-based insertion index within the destination column
+    # move.record : the dropped record
+    # move.column : the destination column key (Symbol)
+    # move.prev   : the record immediately before the drop slot (or nil)
+    # move.next   : the record immediately after the drop slot (or nil)
+    # move.index  : 0-based insertion index within the destination column
     MyPositioningService.call(move.record, prev: move.prev, next: move.next)
   end
 
-  # Mode C — no ordering. Cards render in the relation's default order.
+  # Mode C: no ordering. Cards render in the relation's default order.
   # On-drop still fires; position is just never updated.
   position_on false
 end
@@ -445,7 +445,7 @@ Each column loads at most 25 cards. When the total exceeds the limit, a `+N more
 
 When `add: true` (or `role: :backlog`) is set on a column, a `+ Add` button appears in the column header. Clicking it opens the resource's normal new form in a modal.
 
-The record is created normally, and **then** the column's `on_enter` and positioning are applied to the **saved** record — so the new card lands in the clicked column, appended to the bottom. `on_enter` runs against a real, persisted record (exactly as it does for a drag), so `update!`-style callbacks and any side effects behave identically and fire once, on the actual create.
+The record is created normally, and **then** the column's `on_enter` and positioning are applied to the **saved** record, so the new card lands in the clicked column, appended to the bottom. `on_enter` runs against a real, persisted record (exactly as it does for a drag), so `update!`-style callbacks and any side effects behave identically and fire once, on the actual create.
 
 ::: warning Give your grouping column a default
 Because `on_enter` runs **after** the record is saved, the record must be creatable **without** a grouping value. Give your grouping column (e.g. `status`) a database or model default. If it is `NOT NULL` with no default, quick-add create fails validation before `on_enter` can set it.
@@ -495,10 +495,10 @@ After a successful move, Plutonium broadcasts the updated column frames to all c
 
 Plutonium emits the `<turbo-cable-stream-source>` subscription element and broadcasts on the server, but the **client must have an ActionCable consumer** to receive it. Plutonium's bundled JavaScript ships `@hotwired/turbo` only (no cable client), so you must wire the rest up yourself:
 
-1. **Gems** — `turbo-rails` and `actioncable` (Rails includes ActionCable; `turbo-rails` provides `Turbo::StreamsChannel` and `turbo_stream_from`).
-2. **Cable adapter** (`config/cable.yml`) — `async` is fine for a single-process dev server; use **Redis** (or Solid Cable) for multi-process production, otherwise a broadcast from one worker won't reach clients connected to another.
-3. **Mount ActionCable** — `mount ActionCable.server => "/cable"` (Rails mounts it by default when `action_cable/engine` is loaded).
-4. **Load the cable client in your app's JavaScript** — this is the step most people miss. Add **one** of:
+1. **Gems**: `turbo-rails` and `actioncable` (Rails includes ActionCable; `turbo-rails` provides `Turbo::StreamsChannel` and `turbo_stream_from`).
+2. **Cable adapter** (`config/cable.yml`): `async` is fine for a single-process dev server; use **Redis** (or Solid Cable) for multi-process production, otherwise a broadcast from one worker won't reach clients connected to another.
+3. **Mount ActionCable**: `mount ActionCable.server => "/cable"` (Rails mounts it by default when `action_cable/engine` is loaded).
+4. **Load the cable client in your app's JavaScript**: this is the step most people miss. Add **one** of:
    ```js
    // app pack, alongside your other imports
    import "@hotwired/turbo-rails"   // registers <turbo-cable-stream-source> + a consumer
@@ -511,7 +511,7 @@ Plutonium emits the `<turbo-cable-stream-source>` subscription element and broad
    Without this, the server broadcasts but no browser is subscribed, so other viewers won't update until they reload.
 
 ::: tip Verify it
-With two browser tabs on the same board, move a card in one — the other should update without a reload. If it doesn't, check the browser console/network for a `/cable` WebSocket connection; a missing connection means the cable client (step 4) isn't loaded.
+With two browser tabs on the same board, move a card in one; the other should update without a reload. If it doesn't, check the browser console/network for a `/cable` WebSocket connection; a missing connection means the cable client (step 4) isn't loaded.
 :::
 
 ---
@@ -539,7 +539,7 @@ class TaskDefinition < ResourceDefinition
     # ...
   end
 
-  # Call AFTER the kanban block — :kanban isn't a valid default until
+  # Call AFTER the kanban block: :kanban isn't a valid default until
   # `kanban` has enabled the view. Reversing the order raises ArgumentError
   # at class load.
   default_index_view :kanban