plutonium 0.64.0 → 0.66.0

data/docs/reference/kanban/dsl.md

@@ -1,7 +1,7 @@
 # Kanban DSL Reference
 
 ::: 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.
 :::
 
 Complete reference for the `kanban do…end` block declared inside a resource Definition.
@@ -49,9 +49,9 @@ Default: `nil` (unlimited).
 
 Controls how card positions are persisted after a drag-and-drop. Three modes:
 
-**Inherited from the definition.** `position_on` is the same verb outside `kanban do…end`, where it makes the resource's [table and grid drag-reorderable](/reference/positioning). A board with no `position_on` of its own uses the **definition's**, falling back to the historic default (`:position`, Mode A). Declaring it inside the board overrides that. Resolution is lazy, so declaration order in the class body does not matter.
+**Inherited from the definition.** `position_on` is the same verb outside `kanban do…end`, where it makes the resource's [table and grid drag-reorderable](/reference/resource/positioning). A board with no `position_on` of its own uses the **definition's**, falling back to the historic default (`:position`, Mode A). Declaring it inside the board overrides that. Resolution is lazy, so declaration order in the class body does not matter.
 
-#### Mode A — delegate to `Plutonium::Positioning::Model` (default)
+#### Mode A: delegate to `Plutonium::Positioning::Model` (default)
 
 ```ruby
 # Default: uses :position attribute
@@ -64,30 +64,30 @@ position_on :sort_order
 Requires the model to:
 1. `include Plutonium::Positioning::Model`
 2. Call `positioned_on :position, scope: :grouping_attribute`
-3. Have a `decimal` column for the position attribute — add it with the `t.position` migration helper (a tuned `decimal(16,8)`) — see [Positioning › Migration](/reference/kanban/positioning#migration)
+3. Have a `decimal` column for the position attribute: add it with the `t.position` migration helper (a tuned `decimal(16,8)`); see [Positioning › Migration](/reference/kanban/positioning#migration)
 
 On drop, calls `record.reposition!(prev_record:, next_record:)` which computes the decimal midpoint and updates the record.
 
-#### Mode B — BYO block
+#### Mode B: BYO block
 
 ```ruby
 position_on :sort_order do |move|
   # move is a Plutonium::Positioning::Move value object
   # (also reachable as Plutonium::Kanban::Positioning::Move):
-  #   move.record  — the dropped ActiveRecord record
-  #   move.column  — destination column key (Symbol)
-  #   move.prev    — record immediately before the insertion slot, or nil
-  #   move.next    — record immediately after the insertion slot, or nil
-  #   move.index   — 0-based insertion index within the destination column
+  #   move.record  : the dropped ActiveRecord record
+  #   move.column  : destination column key (Symbol)
+  #   move.prev    : record immediately before the insertion slot, or nil
+  #   move.next    : record immediately after the insertion slot, or nil
+  #   move.index   : 0-based insertion index within the destination column
   move.record.update!(sort_order: compute_position(move.prev, move.next))
 end
 ```
 
-The block is evaluated via `call` (not `instance_exec`) — it is a plain Ruby proc/lambda.
+The block is evaluated via `call` (not `instance_exec`); it is a plain Ruby proc/lambda.
 
 Plutonium still orders column cards by `sort_order` (the first argument); your block is responsible only for persisting the new value.
 
-#### Mode C — disabled
+#### Mode C: disabled
 
 ```ruby
 position_on false
@@ -114,9 +114,9 @@ Enables ActionCable broadcasting after every successful move. After a drop, Plut
 - Tenant-scoped portals use the entity's Global ID parameter as the second segment.
 - Portals without entity scoping use the literal string `"global"`.
 
-Two viewers share a stream only if they have the same resource class **and** the same scoped entity — cross-tenant leakage is impossible by construction.
+Two viewers share a stream only if they have the same resource class **and** the same scoped entity; cross-tenant leakage is impossible by construction.
 
-Requires `turbo-rails` + ActionCable (gems), a cable adapter in `config/cable.yml` (Redis/Solid Cable in multi-process production), ActionCable mounted at `/cable`, **and** an ActionCable client loaded in your app's JavaScript. Plutonium's bundle ships `@hotwired/turbo` only — without `@hotwired/turbo-rails` (or `@rails/actioncable`) in your pack, the `<turbo-cable-stream-source>` never connects and other viewers won't update. Server-side broadcasting works regardless; this is purely the client subscription. See the [guide's Realtime setup](/guides/kanban#setup-required-for-realtime-to-actually-update-other-viewers).
+Requires `turbo-rails` + ActionCable (gems), a cable adapter in `config/cable.yml` (Redis/Solid Cable in multi-process production), ActionCable mounted at `/cable`, **and** an ActionCable client loaded in your app's JavaScript. Plutonium's bundle ships `@hotwired/turbo` only; without `@hotwired/turbo-rails` (or `@rails/actioncable`) in your pack, the `<turbo-cable-stream-source>` never connects and other viewers won't update. Server-side broadcasting works regardless; this is purely the client subscription. See the [guide's Realtime setup](/guides/kanban#setup-required-for-realtime-to-actually-update-other-viewers).
 
 Default: `false`.
 
@@ -141,14 +141,14 @@ show_in :modal   # open a card's show page in a centered modal dialog
 show_in :page    # navigate the whole page to the show route
 ```
 
-Overrides — **for this board** — where clicking a card opens the record's show page:
+Overrides, **for this board**, where clicking a card opens the record's show page:
 
-- `:modal` — the card's show link targets the layout's `remote_modal` frame, so the show page renders in a **centered** dialog. (Show is always centered — deliberately not the definition's `modal_mode`, which styles `new`/`edit`.)
-- `:page` — the card's show link targets `_top`, navigating the whole page to the show route.
+- `:modal`: the card's show link targets the layout's `remote_modal` frame, so the show page renders in a **centered** dialog. (Show is always centered, deliberately not the definition's `modal_mode`, which styles `new`/`edit`.)
+- `:page`: the card's show link targets `_top`, navigating the whole page to the show route.
 
 When `show_in` is **not** set on the board, the board inherits the definition's [`show_in`](/reference/resource/definition#show_in) (which itself defaults to `:page`). So to open cards in a modal you can set it on the board, or once on the definition (which also covers the table and grid views).
 
-Either mode escapes the column's lazy turbo-frame — `:page` replaces the whole page, and the `remote_modal` frame lives in the layout (resolved document-wide), so it opens outside the column. No per-card configuration is needed; the show page detects the modal frame (`in_modal?`) and wraps its details in the centered modal chrome. From inside the modal, an expand icon (or ⌘/Ctrl-click on the card) opens the full page in a new tab.
+Either mode escapes the column's lazy turbo-frame: `:page` replaces the whole page, and the `remote_modal` frame lives in the layout (resolved document-wide), so it opens outside the column. No per-card configuration is needed; the show page detects the modal frame (`in_modal?`) and wraps its details in the centered modal chrome. From inside the modal, an expand icon (or ⌘/Ctrl-click on the card) opens the full page in a new tab.
 
 An unknown mode raises `ArgumentError`.
 
@@ -168,7 +168,7 @@ Overrides the slot layout for every kanban card on this board, using the same sl
 
 When `card_fields` is not set, cards fall back to the resource definition's `grid_fields`. If neither is declared, the card renders the default header-only layout.
 
-The `meta` slot renders each field as a colored badge, and formats values by type before badging: a `has_cents` field renders as currency, a `belongs_to` association renders as its label (not an object inspect), and everything else is humanized — with status-like enums (`active`, `pending`, `published`…) resolving to a semantic color. The badge color is deterministic per value, so a given status is the same color on every card.
+The `meta` slot renders each field as a colored badge, and formats values by type before badging: a `has_cents` field renders as currency, a `belongs_to` association renders as its label (not an object inspect), and everything else is humanized, with status-like enums (`active`, `pending`, `published`…) resolving to a semantic color. The badge color is deterministic per value, so a given status is the same color on every card.
 
 ---
 
@@ -203,12 +203,12 @@ end
 | `color:` | Symbol or String | `nil` | Header color dot. Named colors: `:red`, `:orange`, `:amber`, `:yellow`, `:green`, `:blue`, `:purple`, `:pink`, `:gray`. Raw CSS string also accepted |
 | `scope:` | Symbol or Proc | `nil` | Relation filter for this column. **Symbol** → `relation.public_send(sym)` (named AR scope). **Proc** → 0-arg lambda called via `instance_exec` on the relation, e.g. `-> { where(status: "todo") }` |
 | `on_enter:` | Symbol or Proc | `nil` | Fired when a card is dropped into this column. **Symbol** → `record.public_send(sym)`. **Proc** → 1-arg lambda `->(record) { … }` where `self` inside the block is the view context (giving access to `current_user`, helpers, etc.). The callback may assign attributes in memory (`r.status = :done`) or call `update!` directly; if the record has unsaved changes after `on_enter` returns the controller saves it automatically. |
-| `on_exit:` | Symbol or Proc | `nil` | The source-side counterpart to `on_enter:`, fired when a card **leaves** this column on a cross-column move. Same dispatch (**Symbol** → `record.public_send`; **Proc** → 1-arg lambda, `self` = view context). Runs **before** the destination's `on_enter`, inside the same move transaction, so it sees the pre-move state and rolls back if the move fails. Use it for source-tied side effects the destination can't own (stop a timer, release a slot). Fires only on a drag-move through `kanban_move` — not on destroy, a programmatic status change, or quick-add. Skipped on same-column reorders. |
+| `on_exit:` | Symbol or Proc | `nil` | The source-side counterpart to `on_enter:`, fired when a card **leaves** this column on a cross-column move. Same dispatch (**Symbol** → `record.public_send`; **Proc** → 1-arg lambda, `self` = view context). Runs **before** the destination's `on_enter`, inside the same move transaction, so it sees the pre-move state and rolls back if the move fails. Use it for source-tied side effects the destination can't own (stop a timer, release a slot). Fires only on a drag-move through `kanban_move`, not on destroy, a programmatic status change, or 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` | A **record-scoped** interaction class (declares `attribute :resource`) run when a card is dropped **into** this column from another column. Opens the interaction's form as a modal to collect input, then commits `on_enter` + the interaction + repositioning atomically. Auto-registered as a hidden record action under a column-scoped key (`:<column>_enter_interaction`), authorized by `kanban_move?` (no policy method of its own). See [enter_interaction](#drop-interaction) below |
 | `role:` | `:backlog`, `:done`, `:lost` | `nil` | Applies a preset (see below) |
 | `collapsed:` | Boolean | `false` | Column starts collapsed (a thin strip with the label rotated). The Stimulus controller persists the toggled state to `localStorage` (key: `pu-kanban:<path>:<column-key>:collapsed`) so the user preference survives page reloads; this DSL value sets the server-rendered initial state only. |
 | `add:` | Boolean | `false` | Show a `+ Add` quick-add button |
-| `accepts:` | `true`, `false`, or Array | `true` | Drop policy — **structural topology only**. `true` accepts any source column. `false` rejects all drops (display-only column). An Array of column key symbols accepts only those sources. This is client-hintable: the value is emitted as `data-kanban-accepts` so the drag UI greys out disallowed source columns before the drop. **Record- or user-conditional rules do not belong here** — put them in `kanban_move?`, which sees the record and the `from`/`to` columns (see [Authorization](./authorization)). Passing a `Proc` raises `ArgumentError`. |
+| `accepts:` | `true`, `false`, or Array | `true` | Drop policy: **structural topology only**. `true` accepts any source column. `false` rejects all drops (display-only column). An Array of column key symbols accepts only those sources. This is client-hintable: the value is emitted as `data-kanban-accepts` so the drag UI greys out disallowed source columns before the drop. **Record- or user-conditional rules do not belong here**. Put them in `kanban_move?`, which sees the record and the `from`/`to` columns (see [Authorization](./authorization)). Passing a `Proc` raises `ArgumentError`. |
 | `locked:` | Boolean | `false` | Prevent dragging cards **out of** this column |
 | `wip:` | Integer | `nil` | WIP limit. Reject cross-column drops when `dest_count + 1 > wip`. Has no effect on same-column reordering |
 
@@ -219,7 +219,7 @@ The old names are **deprecated aliases**:
 - In **development and test** they raise an `ArgumentError` so the rename is caught before release.
 - In **deployed environments** (production, staging) they log a deprecation warning and map onto the new option, so an in-flight deployment keeps working across the upgrade.
 
-If both the old and new name are given, the new one wins. Update your definitions to `on_enter:` / `enter_interaction:` at your earliest convenience — a future release will drop the aliases entirely.
+If both the old and new name are given, the new one wins. Update your definitions to `on_enter:` / `enter_interaction:` at your earliest convenience; a future release will drop the aliases entirely.
 :::
 
 ### Role presets
@@ -230,7 +230,7 @@ If both the old and new name are given, the new one wins. Update your definition
 | `: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
 colour signalling the outcome (`:done` = positive close, `:lost` = negative
 close). Use them as the won/lost pair in pipelines (leads, deals, tickets).
 
@@ -246,13 +246,13 @@ column :lost,
 
 Runs an authorization-aware, input-collecting interaction when a card is dropped **into** this column from another column.
 
-- **Must be a record-scoped interaction** — the class declares `attribute :resource` (singular) and acts on the one dropped card. A `resources`-plural (bulk) interaction is not valid here; that shape is for [column actions](#column-actions).
-- **Auto-registered as a hidden record action** under a column-scoped key (`:lost` → `:lost_enter_interaction`) — unique by construction, so two columns can reuse the same interaction class without colliding. Hidden = it does not render as an action button on the show page, table rows, or grid cards; it is reachable only by a drop.
-- **Authorized by `kanban_move?` alone** — the interaction has **no policy method of its own**. The move (and therefore the interaction) is gated by the single `kanban_move?` predicate, which can gate this specific transition via its `to` column context (e.g. `def kanban_move? = kanban_to&.key == :lost ? user.manager? : super`). See [Authorization](./authorization).
-- **Move flow only.** Dropping cross-column opens the interaction's form as a modal; on submit `on_enter` + the interaction + repositioning commit in **one atomic transaction**. Validation failure rolls the whole transaction back (membership write included) and re-renders the modal with errors — nothing persists. Same-column reorders run positioning only (neither `on_enter` nor the interaction fires).
-- **Quick-add (`+ Add`)** applies `on_enter` + positioning **post-create** — the record is created first (needs a grouping-column default), then `on_enter` places it in the column; the `enter_interaction` is not involved.
-- **Author contract** — when a column declares both, `on_enter` owns the membership attribute (e.g. `status`) and the interaction owns the extras (reason, mail, audit). If the interaction also writes the membership attribute it must set the same value `on_enter` does (idempotent). With no `on_enter`, the interaction owns everything.
-- **Success response limitation** — the interaction's success **message** (`.with_message`) surfaces as a toast, but a custom success *response* (`with_redirect_response`, `with_file_response`, …) is **not** honored on the drop path; the board just re-renders and closes the modal.
+- **Must be a record-scoped interaction.** The class declares `attribute :resource` (singular) and acts on the one dropped card. A `resources`-plural (bulk) interaction is not valid here; that shape is for [column actions](#column-actions).
+- **Auto-registered as a hidden record action** under a column-scoped key (`:lost` → `:lost_enter_interaction`), unique by construction, so two columns can reuse the same interaction class without colliding. Hidden = it does not render as an action button on the show page, table rows, or grid cards; it is reachable only by a drop.
+- **Authorized by `kanban_move?` alone.** The interaction has **no policy method of its own**. The move (and therefore the interaction) is gated by the single `kanban_move?` predicate, which can gate this specific transition via its `to` column context (e.g. `def kanban_move? = kanban_to&.key == :lost ? user.manager? : super`). See [Authorization](./authorization).
+- **Move flow only.** Dropping cross-column opens the interaction's form as a modal; on submit `on_enter` + the interaction + repositioning commit in **one atomic transaction**. Validation failure rolls the whole transaction back (membership write included) and re-renders the modal with errors; nothing persists. Same-column reorders run positioning only (neither `on_enter` nor the interaction fires).
+- **Quick-add (`+ Add`)** applies `on_enter` + positioning **post-create**: the record is created first (needs a grouping-column default), then `on_enter` places it in the column; the `enter_interaction` is not involved.
+- **Author contract.** When a column declares both, `on_enter` owns the membership attribute (e.g. `status`) and the interaction owns the extras (reason, mail, audit). If the interaction also writes the membership attribute it must set the same value `on_enter` does (idempotent). With no `on_enter`, the interaction owns everything.
+- **Success response limitation.** The interaction's success **message** (`.with_message`) surfaces as a toast, but a custom success *response* (`with_redirect_response`, `with_file_response`, …) is **not** honored on the drop path; the board just re-renders and closes the modal.
 
 See the [guide's Interaction on drop section](/guides/kanban#interaction-on-drop) for a full worked example.
 
@@ -265,7 +265,7 @@ Use `columns do…end` when the column list depends on the current request:
 ```ruby
 kanban do
   columns do
-    # `self` is the view context — current_user, params, and helpers all work.
+    # `self` is the view context: current_user, params, and helpers all work.
     current_user.visible_statuses.map do |status|
       Plutonium::Kanban::Column.new(
         :"status_#{status.id}",
@@ -299,7 +299,7 @@ class TaskDefinition < ResourceDefinition
 end
 ```
 
-**`enter_interaction:` is not supported on dynamic boards.** Unlike a column action, its hidden action can't be registered manually — the key is column-scoped and internal — and the static registration pass has no columns to see. A drop into a dynamic column that declares `enter_interaction:` is rejected with a snap-back (it does not crash). Use a static board when a column needs an `enter_interaction:`.
+**`enter_interaction:` is not supported on dynamic boards.** Unlike a column action, its hidden action can't be registered manually: the key is column-scoped and internal, and the static registration pass has no columns to see. A drop into a dynamic column that declares `enter_interaction:` is rejected with a snap-back (it does not crash). Use a static board when a column needs an `enter_interaction:`.
 :::
 
 ---
@@ -326,7 +326,7 @@ end
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
-| `interaction:` | Class | Yes | An interaction class. Must have `attribute :resources` (plural) — it runs as a bulk action |
+| `interaction:` | Class | Yes | An interaction class. Must have `attribute :resources` (plural); it runs as a bulk action |
 | `on:` | `:all` or `:visible` | No (default `:all`) | `:all` passes IDs of all column cards (ignoring `per_column`). `:visible` passes only the rendered, capped subset |
 | `label:` | String | No | Button text. Defaults to `key.to_s.humanize` |
 | `icon:` | Phlex icon class | No | Icon rendered before the label |

data/docs/reference/kanban/index.md

@@ -6,7 +6,7 @@ Reference documentation for the Plutonium kanban board feature.
 
 | Page | What it covers |
 |------|---------------|
-| [DSL](/reference/kanban/dsl) | Complete `kanban do…end` DSL — board options, columns, column actions, static vs. dynamic, lazy loading, realtime |
+| [DSL](/reference/kanban/dsl) | Complete `kanban do…end` DSL: board options, columns, column actions, static vs. dynamic, lazy loading, realtime |
 | [Positioning](/reference/kanban/positioning) | `Plutonium::Positioning::Model` concern, `positioned_on`, `position_on` modes, `reposition!`, rebalancing |
 | [Authorization](/reference/kanban/authorization) | `kanban_move?` policy predicate, read-only fallback, separating move rights from edit rights |
 

data/docs/reference/kanban/positioning.md

@@ -1,10 +1,10 @@
 # Kanban Positioning
 
 ::: tip Positioning is not kanban-only
-The model concern, the arithmetic and the `position_on` modes on this page are shared with **table and grid drag-to-reorder** — see [Positioning & drag-to-reorder](/reference/positioning) for the index-surface half of the feature (the grip, the `reposition` endpoint, `reposition?`, and board inheritance).
+The model concern, the arithmetic and the `position_on` modes on this page are shared with **table and grid drag-to-reorder**; see [Positioning & drag-to-reorder](/reference/resource/positioning) for the index-surface half of the feature (the grip, the `reposition` endpoint, `reposition?`, and board inheritance).
 :::
 
-Plutonium uses **decimal fractional positioning** for kanban card ordering. A drop writes a single decimal position (the midpoint between its neighbors), so the common case touches exactly one row — no bulk renumbering. The one exception is rare **rebalancing**: when the same slot has been subdivided ~20 times and the gap between two neighbors shrinks below `1e-6`, Plutonium renumbers that one scope group back to clean integers before inserting (see [Gap exhaustion](#rebalancing)).
+Plutonium uses **decimal fractional positioning** for kanban card ordering. A drop writes a single decimal position (the midpoint between its neighbors), so the common case touches exactly one row, with no bulk renumbering. The one exception is rare **rebalancing**: when the same slot has been subdivided ~20 times and the gap between two neighbors shrinks below `1e-6`, Plutonium renumbers that one scope group back to clean integers before inserting (see [Gap exhaustion](#rebalancing)).
 
 ## `Plutonium::Positioning::Model` concern
 
@@ -34,7 +34,7 @@ After calling `positioned_on`, the model gets:
 
 ### Migration
 
-Use the **`t.position`** helper — it adds a `decimal` column already tuned for fractional ordering (`precision: 16, scale: 8`), so you can't get the scale wrong:
+Use the **`t.position`** helper: it adds a `decimal` column already tuned for fractional ordering (`precision: 16, scale: 8`), so you can't get the scale wrong:
 
 ```ruby
 create_table :tasks do |t|
@@ -56,6 +56,8 @@ class AddPositionToTasks < ActiveRecord::Migration[8.1]
 end
 ```
 
+For a model owned by a feature package (e.g. `Catalog::Product`), put this migration in `packages/<package>/db/migrate/`, next to the table's create migration. Each package's `db/migrate` is appended to the app's migration paths, so `rails db:migrate` picks it up. Plain `rails g migration` always writes to the main app's `db/migrate`, so move the file into the package afterwards.
+
 `t.position` accepts a custom column name and any `column` options:
 
 ```ruby
@@ -65,7 +67,7 @@ t.position :position, scale: 10      # override precision/scale
 ```
 
 ::: tip Why the helper picks `scale: 8`
-If you write the column by hand, give it at least **two more decimal places than `EPSILON` (`1e-6`)** — i.e. `scale: 8` or higher. Rebalancing triggers when a gap drops below `1e-6`, so a column that can store smaller values still has room to write the final midpoint cleanly. A `scale: 6` column has no headroom: the last subdivision before a rebalance can round to a neighbor and momentarily collide. `t.position` defaults to `scale: 8`, which is safe.
+If you write the column by hand, give it at least **two more decimal places than `EPSILON` (`1e-6`)**, i.e. `scale: 8` or higher. Rebalancing triggers when a gap drops below `1e-6`, so a column that can store smaller values still has room to write the final midpoint cleanly. A `scale: 6` column has no headroom: the last subdivision before a rebalance can round to a neighbor and momentarily collide. `t.position` defaults to `scale: 8`, which is safe.
 :::
 
 ---
@@ -88,7 +90,7 @@ task.reposition!(prev_record: last_card, next_record: nil)   # append
 
 ### Gap exhaustion (rebalancing) {#rebalancing}
 
-Each midpoint insert into the *same* slot halves the gap (`1.0 → 0.5 → 0.25 → …`), so after roughly 20 consecutive insertions the gap drops below `EPSILON` (`1e-6`). At that point `reposition!` rebalances **only that scope group** — renumbering every row in the group to fresh integers (`1.0, 2.0, 3.0, …`) in current-position order, inside a transaction — then reloads the two neighbors and writes the new midpoint. Other scope groups are untouched. End moves (a `nil` neighbor) never rebalance: they always have integer room via `prev ± 1`.
+Each midpoint insert into the *same* slot halves the gap (`1.0 → 0.5 → 0.25 → …`), so after roughly 20 consecutive insertions the gap drops below `EPSILON` (`1e-6`). At that point `reposition!` rebalances **only that scope group**, renumbering every row in the group to fresh integers (`1.0, 2.0, 3.0, …`) in current-position order, inside a transaction, then reloads the two neighbors and writes the new midpoint. Other scope groups are untouched. End moves (a `nil` neighbor) never rebalance: they always have integer room via `prev ± 1`.
 
 ---
 
@@ -108,7 +110,7 @@ Task.backfill_positions!(order: :created_at)
 The `position_on` call inside `kanban do…end` controls how Plutonium persists positions after a drag-and-drop. Three modes are available:
 
 ::: tip A board inherits the definition's `position_on`
-`position_on` is the **same verb** at both levels. A board resolves its strategy as: its own `position_on`, else the **definition's**, else the historic default (`:position`, Mode A). So a resource whose definition already declares `position_on` for its table and grid needs nothing inside `kanban do…end` — the board picks up the same attribute and the same mode.
+`position_on` is the **same verb** at both levels. A board resolves its strategy as: its own `position_on`, else the **definition's**, else the historic default (`:position`, Mode A). So a resource whose definition already declares `position_on` for its table and grid needs nothing inside `kanban do…end`; the board picks up the same attribute and the same mode.
 
 Resolution is lazy, so a `kanban do…end` written **above** `position_on` in the class body still sees it.
 
@@ -123,7 +125,7 @@ end
 ```
 :::
 
-### Mode A — delegate (default)
+### Mode A: delegate (default)
 
 ```ruby
 kanban do
@@ -135,26 +137,26 @@ end
 
 On drop, Plutonium calls `record.reposition!(prev_record:, next_record:)`. Requires the model to include `Plutonium::Positioning::Model` and call `positioned_on`.
 
-### Mode B — BYO block
+### Mode B: BYO block
 
 ```ruby
 kanban do
   position_on :sort_order do |move|
-    # move.record — the dropped record
-    # move.column — destination column key (Symbol)
-    # move.prev   — record immediately before the slot (or nil)
-    # move.next   — record immediately after the slot (or nil)
-    # move.index  — 0-based insertion index within the destination column
+    # move.record: the dropped record
+    # move.column: destination column key (Symbol)
+    # move.prev:   record immediately before the slot (or nil)
+    # move.next:   record immediately after the slot (or nil)
+    # move.index:  0-based insertion index within the destination column
     move.record.update!(sort_order: my_position(move.prev, move.next))
   end
 end
 ```
 
-Plutonium orders the column by `sort_order` for display; your block is responsible only for persisting the new value. The block is called with a single `Plutonium::Positioning::Move` argument (still reachable under its original name, `Plutonium::Kanban::Positioning::Move`) — it is NOT `instance_exec`'d, so `self` is the proc's original binding.
+Plutonium orders the column by `sort_order` for display; your block is responsible only for persisting the new value. The block is called with a single `Plutonium::Positioning::Move` argument (still reachable under its original name, `Plutonium::Kanban::Positioning::Move`); it is NOT `instance_exec`'d, so `self` is the proc's original binding.
 
-On a table or grid the same block runs with `move.column` set to `nil`, since those surfaces have no columns. See [Mode B](/reference/positioning#mode-b) for a worked `acts_as_list` example.
+On a table or grid the same block runs with `move.column` set to `nil`, since those surfaces have no columns. See [Mode B](/reference/resource/positioning#mode-b) for a worked `acts_as_list` example.
 
-### Mode C — disabled
+### Mode C: disabled
 
 ```ruby
 kanban do

data/docs/reference/resource/actions.md

@@ -1,32 +1,32 @@
 # Actions
 
-Custom buttons that go beyond standard CRUD — publish, archive, import, send invitation, etc. Two flavors:
+Custom buttons that go beyond standard CRUD: publish, archive, import, send invitation, etc. Two flavors:
 
-- **Simple actions** — navigate to an existing URL.
-- **Interactive actions** — run an [Interaction](/reference/behavior/interactions), optionally collecting input via a modal form.
+- **Simple actions**: navigate to an existing URL.
+- **Interactive actions**: run an [Interaction](/reference/behavior/interactions), optionally collecting input via a modal form.
 
 ## 🚨 Critical
 
 - **Every custom action needs a policy method.** `action :publish` requires `def publish?` on the policy. Undefined methods return `false`, so the action silently disappears.
 - **For interactive actions, visibility is inferred from the interaction's attributes.** Don't declare `record_action: true` / `bulk_action: true` etc. by hand unless you're opting OUT.
 - **Bulk action authorization is per-record.** If any selected record fails the policy check, the entire request is rejected.
-- **Always pass `as:`** on custom routes — without it, `resource_url_for` can't generate URLs (critical for nested resources).
+- **Always pass `as:`** on custom routes: without it, `resource_url_for` can't generate URLs (critical for nested resources).
 - **Prefer interactive actions over hand-written controller routes.** Anything a user triggers from a page belongs behind an interaction.
-- **An interaction is the button, not the operation.** Logic may start in `execute`; once a job or an API also needs it, it moves to the model — see [Behavior › Interactions](/reference/behavior/interactions#what-an-interaction-is-for).
+- **An interaction is the button, not the operation.** Logic may start in `execute`; once a job or an API also needs it, it moves to the model, see [Behavior › Interactions](/reference/behavior/interactions#what-an-interaction-is-for).
 
 ## Action visibility flags
 
 | Flag | Where the button appears |
 |---|---|
-| `resource_action: true` | Index page (top toolbar) — for actions that operate on the collection (Import, Export, Create) |
-| `record_action: true` | Show page — for actions on a single record (Edit, Archive, Delete) |
-| `collection_record_action: true` | Per-row in the index table — for quick actions (Edit, Show) |
+| `resource_action: true` | Index page (top toolbar): for actions that operate on the collection (Import, Export, Create) |
+| `record_action: true` | Show page: for actions on a single record (Edit, Archive, Delete) |
+| `collection_record_action: true` | Per-row in the index table: for quick actions (Edit, Show) |
 | `bulk_action: true` | Bulk-actions toolbar (shown when records are selected) |
-| `hidden: true` | **Nowhere.** Suppresses all four surfaces at once, while keeping the route and policy live — see [Hidden actions](#hidden-actions) |
+| `hidden: true` | **Nowhere.** Suppresses all four surfaces at once, while keeping the route and policy live, see [Hidden actions](#hidden-actions) |
 
 ### Inferred visibility (interactive actions)
 
-For `interaction:`-based actions, all four flags are **inferred from the interaction's attributes** — don't declare them by hand:
+For `interaction:`-based actions, all four flags are **inferred from the interaction's attributes**; don't declare them by hand:
 
 | Interaction declares | Inferred flags |
 |---|---|
@@ -34,7 +34,7 @@ For `interaction:`-based actions, all four flags are **inferred from the interac
 | `attribute :resources` (plural) | `bulk_action: true` |
 | neither | `resource_action: true` |
 
-User-supplied flags override the inferred ones, but only **opt-out** makes sense — the interaction's `attribute :resource` / `attribute :resources` already fixes its semantic shape:
+User-supplied flags override the inferred ones, but only **opt-out** makes sense: the interaction's `attribute :resource` / `attribute :resources` already fixes its semantic shape:
 
 ```ruby
 # :resource interaction → defaults to record_action + collection_record_action.
@@ -63,10 +63,10 @@ action :name,
   collection_record_action: true,
   bulk_action:              true,
 
-  # Conditional visibility — display-only proc, NOT authorization (see below)
+  # Conditional visibility: display-only proc, NOT authorization (see below)
   condition: -> { params[:beta] == "1" },
 
-  # Never render, anywhere — route + policy stay live (see below)
+  # Never render, anywhere: route + policy stay live (see below)
   hidden: true,
 
   # Grouping
@@ -78,19 +78,19 @@ action :name,
   turbo_frame:  "_top",
   return_to:    "/custom/path",
   route_options: {action: :foo},
-  modal: :slideover,                     # :slideover / :centered — overrides the definition's modal mode
-  size:  :lg,                            # :sm / :md / :lg / :xl / :auto / :full — overrides the definition's modal size
+  modal: :slideover,                     # :slideover / :centered; overrides the definition's modal mode
+  size:  :lg,                            # :sm / :md / :lg / :xl / :auto / :full; overrides the definition's modal size
 
   # HTML attributes (see below)
   link:   {target: "_blank", rel: "noopener"},  # merged onto the action's <a> renderings
   button: {data: {analytics: "archive"}}        # merged onto the button_to <form> (non-GET)
 ```
 
-### HTML attributes — `link:` / `button:`
+### HTML attributes: `link:` / `button:`
 
-Two per-element attribute bags, deep-merged over the framework's own attributes at render time — **the author wins on every key**, recursively through nested `data`:
+Two per-element attribute bags, deep-merged over the framework's own attributes at render time; **the author wins on every key**, recursively through nested `data`:
 
-- **`link:`** applies to every `<a>` rendered for the action: the toolbar link (GET), dropdown items (**any** HTTP method — dropdown items are always anchors, submitting via `data-turbo-method`), bulk-action links, kanban column action links, and the grid/kanban card's hidden show link (for `:show`).
+- **`link:`** applies to every `<a>` rendered for the action: the toolbar link (GET), dropdown items (**any** HTTP method, dropdown items are always anchors, submitting via `data-turbo-method`), bulk-action links, kanban column action links, and the grid/kanban card's hidden show link (for `:show`).
 - **`button:`** applies to the `button_to` **`<form>`** element of the non-GET toolbar rendering (the form wrapper, not the inner `<button>`).
 
 ```ruby
@@ -100,14 +100,14 @@ action :documentation,
   link: {target: "_blank", rel: "noopener noreferrer", data: {analytics: "docs"}}
 ```
 
-Because the author wins, you can override anything — `turbo_frame`, `class`, `data-*` — at your own risk. Two things to know:
+Because the author wins, you can override anything (`turbo_frame`, `class`, `data-*`) at your own risk. Two things to know:
 
-- `class:` **replaces** the framework's classes (no token append) — a bare `link: {class: "mt-2"}` removes the button styling entirely.
+- `class:` **replaces** the framework's classes (no token append): a bare `link: {class: "mt-2"}` removes the button styling entirely.
 - Pass `data:` as a **hash**. The merge only recurses when both sides are hashes, so a scalar `data:` replaces the framework's data wholesale (dropping `turbo_confirm`/`turbo_frame`).
 
 Both bags round-trip through [`with(...)`](#deriving-variants-action-with), so `defined_actions[:edit].with(link: {target: "_blank"})` works in `customize_actions`.
 
-### Deriving variants — `Action#with(...)`
+### Deriving variants: `Action#with(...)`
 
 Action records are frozen value objects. Inside `customize_actions`, derive a copy with overrides:
 
@@ -117,11 +117,11 @@ def customize_actions
 end
 ```
 
-## Conditional visibility — `condition:` {#conditional-visibility}
+## Conditional visibility: `condition:` {#conditional-visibility}
 
-Like the `condition:` proc on [inputs/displays/columns](/reference/resource/definition), an action can be **defined but only rendered when a runtime proc is truthy**. It's purely a toggle on whether the **button is shown** — the action (and its route) stays fully live either way.
+Like the `condition:` proc on [inputs/displays/columns](/reference/resource/definition), an action can be **defined but only rendered when a runtime proc is truthy**. It's purely a toggle on whether the **button is shown**; the action (and its route) stays fully live either way.
 
-The headline use case: **expose an action's endpoint without surfacing it in the UI** — e.g. one you call from the API, a webhook, or another service. Hide the button with an always-falsy condition; the route still works:
+The headline use case: **expose an action's endpoint without surfacing it in the UI**, e.g. one you call from the API, a webhook, or another service. Hide the button with an always-falsy condition; the route still works:
 
 ```ruby
 # Defined and callable (API / programmatic), but no button anywhere in the UI:
@@ -133,7 +133,7 @@ It also works as a dynamic toggle driven by the **record** or the **view/request
 ```ruby
 # object → the row/shown record (record & collection-record actions):
 action :reopen,  interaction: ReopenInteraction,  condition: -> { object.closed? }
-# view/request state — feature flag, preview/beta mode:
+# view/request state: feature flag, preview/beta mode:
 action :preview, interaction: PreviewInteraction, condition: -> { params[:beta] == "1" }
 ```
 
@@ -144,34 +144,34 @@ Inside the proc, `object`/`record` is the contextual record, and every other cal
 | `object` / `record` | The row/shown record for **record** and **collection-record** actions; **`nil`** for resource and bulk actions (no single record). Guard with `object&.…` if a condition is shared across action kinds. |
 | `params`, `request` | Current request. |
 | `current_user`, `current_parent` | The signed-in user and (nested) parent. |
-| `resource_record!` | The shown record on the show page; raises on index/table — prefer `object`. |
+| `resource_record!` | The shown record on the show page; raises on index/table: prefer `object`. |
 | `allowed_to?`, `policy_for`, other helpers | The usual view helpers. |
 
 `object` is evaluated **per row** in tables and grids, so per-record show/hide works there too.
 
-::: danger `condition:` is NOT authorization — it only hides the button
+::: danger `condition:` is NOT authorization: it only hides the button
 A hidden action still has a **live route**: anyone who knows the URL can still trigger it. `condition:` decides whether the *button renders*, never whether the *request is allowed*.
 
 ```ruby
-# 🚫 WRONG — this does NOT stop non-admins. The route is live; they can POST to it.
+# 🚫 WRONG: this does NOT stop non-admins. The route is live; they can POST to it.
 action :wipe, interaction: WipeInteraction, condition: -> { current_user.admin? }
 
-# ✅ RIGHT — authorization belongs in the policy. The action only runs if this returns true.
+# ✅ RIGHT: authorization belongs in the policy. The action only runs if this returns true.
 class WidgetPolicy < ResourcePolicy
   def wipe? = current_user.admin?
 end
 ```
 
-**Rule of thumb:** "who may run this" → **policy** (`def action_name?`). "is this UI relevant right now" → `condition:`. Authorization is enforced regardless of `condition:`; the two compose — an action appears only when the policy permits **and** the condition is truthy.
+**Rule of thumb:** "who may run this" → **policy** (`def action_name?`). "is this UI relevant right now" → `condition:`. Authorization is enforced regardless of `condition:`; the two compose: an action appears only when the policy permits **and** the condition is truthy.
 :::
 
 ::: tip Per-record display vs. per-record authorization
-`condition: -> { object.draft? }` is fine for **showing/hiding** a per-record button. But if the rule is about **who may run it** ("only while draft *and* nobody else has it locked"), put it in the policy — `def publish? = record.draft?` is also evaluated per record (per row), and unlike `condition:` it actually gates execution.
+`condition: -> { object.draft? }` is fine for **showing/hiding** a per-record button. But if the rule is about **who may run it** ("only while draft *and* nobody else has it locked"), put it in the policy: `def publish? = record.draft?` is also evaluated per record (per row), and unlike `condition:` it actually gates execution.
 :::
 
-## Hidden actions — `hidden: true` {#hidden-actions}
+## Hidden actions: `hidden: true` {#hidden-actions}
 
-An action declared `hidden: true` renders in **no** toolbar, row dropdown, card, or bulk bar — regardless of its visibility flags, the policy, or `condition:`. Everything else about it stays live:
+An action declared `hidden: true` renders in **no** toolbar, row dropdown, card, or bulk bar, regardless of its visibility flags, the policy, or `condition:`. Everything else about it stays live:
 
 - the **route** is mounted;
 - the **policy predicate** (`def name?`) is defined and enforced;
@@ -181,7 +181,7 @@ An action declared `hidden: true` renders in **no** toolbar, row dropdown, card,
 action :reposition, hidden: true
 ```
 
-The use case is an endpoint reached by **something other than a button** — a drag gesture, a custom Stimulus controller, a client-side widget you wrote yourself. The framework uses it for exactly that: [`position_on`](/reference/positioning) expands to `action :reposition, hidden: true`, and the kanban board's drop endpoint is declared the same way.
+The use case is an endpoint reached by **something other than a button**: a drag gesture, a custom Stimulus controller, a client-side widget you wrote yourself. The framework uses it for exactly that: [`position_on`](/reference/resource/positioning) expands to `action :reposition, hidden: true`, and the kanban board's drop endpoint is declared the same way.
 
 ### `hidden:` vs `condition: -> { false }`
 
@@ -190,7 +190,7 @@ Both suppress the button, so pick by intent:
 | | `hidden: true` | `condition: -> { false }` |
 |---|---|---|
 | Decided | at **class-load**, once | at **render time**, per row/request |
-| Costs | nothing — the surfaces filter it out before any policy or condition runs | a proc evaluation per rendering |
+| Costs | nothing: the surfaces filter it out before any policy or condition runs | a proc evaluation per rendering |
 | Says | "this is never a button" | "this is a button, just not right now" |
 
 Use `hidden:` for an action that is *structurally* not a button. Use `condition:` when visibility genuinely depends on the record, the user, or the request.
@@ -199,10 +199,10 @@ Use `hidden:` for an action that is *structurally* not a button. Use `condition:
 This is the same trap as [`condition:`](#conditional-visibility), and it bears repeating because "hidden" reads more absolute than it is. A hidden action has a **live route**: anyone who can construct the URL can call it.
 
 ```ruby
-# 🚫 WRONG — hiding the button does not stop the request.
+# 🚫 WRONG: hiding the button does not stop the request.
 action :purge_all, interaction: PurgeInteraction, hidden: true
 
-# ✅ RIGHT — authorization belongs in the policy.
+# ✅ RIGHT: authorization belongs in the policy.
 class WidgetPolicy < ResourcePolicy
   def purge_all? = current_user.admin?
 end
@@ -239,16 +239,16 @@ resources :posts do
 end
 ```
 
-Without it, `resource_url_for` can't build the URL — particularly critical for nested resources.
+Without it, `resource_url_for` can't build the URL, particularly critical for nested resources.
 :::
 
 For anything with business logic, use an **interactive action** instead.
 
 ## Interactive actions
 
-Run an [Interaction](/reference/behavior/interactions) — automatically renders a form if the interaction declares attributes beyond `:resource`/`:resources`, otherwise executes immediately with a confirmation.
+Run an [Interaction](/reference/behavior/interactions): automatically renders a form if the interaction declares attributes beyond `:resource`/`:resources`, otherwise executes immediately with a confirmation.
 
-The interactions below call named model methods (`archive!`, `invite!`) rather than doing the work inline. That's not mandatory for a one-off — the trigger to extract is the second caller, since an interaction can only be built with a `view_context`. See [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
+The interactions below call named model methods (`archive!`, `invite!`) rather than doing the work inline. That's not mandatory for a one-off; the trigger to extract is the second caller, since an interaction can only be built with a `view_context`. See [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
 
 ```ruby
 class PostDefinition < Plutonium::Resource::Definition
@@ -341,7 +341,7 @@ action :bulk_archive, interaction: BulkArchiveInteraction
 # bulk_action: true inferred from `attribute :resources`
 ```
 
-Policy — checked per record; fails the whole request if ANY record is unauthorized:
+Policy: checked per record; fails the whole request if ANY record is unauthorized:
 
 ```ruby
 def bulk_archive?
@@ -349,7 +349,7 @@ def bulk_archive?
 end
 ```
 
-The UI only shows bulk actions that ALL selected records support. Records are fetched via `current_authorized_scope` — users can only select records they can access.
+The UI only shows bulk actions that ALL selected records support. Records are fetched via `current_authorized_scope`; users can only select records they can access.
 
 ### Resource action (no record)
 
@@ -375,7 +375,7 @@ action :import, interaction: ImportInteraction
 
 ## Running the work in the background
 
-An interactive action executes inside the request. When that is too slow — a bulk action over thousands of records, or a single call to something slow — replace `execute` with `async` and the interaction dispatches a persisted, resumable run instead:
+An interactive action executes inside the request. When that is too slow (a bulk action over thousands of records, or a single call to something slow), replace `execute` with `async` and the interaction dispatches a persisted, resumable run instead:
 
 ```ruby
 class BulkArchiveInteraction < ResourceInteraction
@@ -396,8 +396,8 @@ See [Async Interactions](/reference/behavior/async-interactions) for failure pol
 
 | Interaction shape | Behavior |
 |---|---|
-| Only `:resource` / `:resources` (no extra inputs) | **Immediate** — browser confirmation (`"#{label}?"`, e.g. `"Archive?"`), then runs. Override with `confirmation: "Custom"` or `confirmation: false`. |
-| Additional `attribute` / `input` declared | **Form** — renders the action's form in a modal first; no auto-confirmation (the form is the confirmation). |
+| Only `:resource` / `:resources` (no extra inputs) | **Immediate**: browser confirmation (`"#{label}?"`, e.g. `"Archive?"`), then runs. Override with `confirmation: "Custom"` or `confirmation: false`. |
+| Additional `attribute` / `input` declared | **Form**: renders the action's form in a modal first; no auto-confirmation (the form is the confirmation). |
 
 ## Built-in CRUD actions
 
@@ -454,13 +454,13 @@ end
 ```
 
 > **CSV export is not an action.** It's a built-in, policy-gated capability with its own
-> button — see [CSV Export](./export.md). Don't declare it with `action :export_csv`.
+> button; see [CSV Export](./export.md). Don't declare it with `action :export_csv`.
 
 ## Interaction responses
 
 ```ruby
 def execute
-  # Success — redirects to resource automatically
+  # Success: redirects to resource automatically
   succeed(resource).with_message("Done!")
 
   # Different redirect destination
@@ -569,7 +569,7 @@ action :export,
 
 ## Related
 
-- [Definition](./definition) — fields, page chrome
-- [Query](./query) — search, filters, scopes
-- [Behavior › Interactions](/reference/behavior/interactions) — writing interaction classes
-- [Behavior › Policy](/reference/behavior/policies) — authorizing custom actions
+- [Definition](./definition): fields, page chrome
+- [Query](./query): search, filters, scopes
+- [Behavior › Interactions](/reference/behavior/interactions): writing interaction classes
+- [Behavior › Policy](/reference/behavior/policies): authorizing custom actions