plutonium 0.65.0 → 0.67.0

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

@@ -1,6 +1,6 @@
 ---
 name: plutonium-resource
-description: Use BEFORE creating, scaffolding, or editing any Plutonium resource — model, definition, field types, scaffold options, has_cents, SGID, search/filters/scopes/sorting, custom actions, bulk actions, hidden actions, index views, drag-to-reorder (positioned_on / position_on), page customization. The single source for "what is a resource and how do I configure one".
+description: 'Use BEFORE creating, scaffolding, or editing any Plutonium resource: model, definition, field types, scaffold options, has_cents, SGID, search/filters/scopes/sorting, custom actions, bulk actions, hidden actions, index views, drag-to-reorder (positioned_on / position_on), page customization. The single source for "what is a resource and how do I configure one".'
 ---
 
 # Plutonium Resources
@@ -14,29 +14,29 @@ For tenancy / `associated_with` / `relation_scope`, load [[plutonium-tenancy]].
 - **Always use generators.** `pu:res:scaffold` creates the resource; `pu:res:conn` connects it to a portal. Never hand-write the model, migration, policy, definition, or controller.
 - **Pass `--dest`** on every scaffold: `--dest=main_app` or `--dest=package_name`. Skips the interactive prompt.
 - **Quote field args with `?` or `{}`** to prevent shell expansion: `'field:type?'`, `'field:decimal{10,2}'`.
-- **Run `pu:res:conn` next** — without it the resource has no portal routes and is invisible.
+- **Migrate, then run `pu:res:conn`.** Without `conn` the resource has no portal routes and is invisible. When `conn` writes a policy with attribute lists (no base policy to inherit from), it reads them off the table's columns; on an unmigrated table it logs an error and writes empty lists.
 - **Let auto-detection work.** Plutonium reads your model. Only declare `field`/`input`/`display`/`column` when overriding the default.
 - **Authorization is in policies, not `condition:` procs.** Use `condition` for UI state ("show this when published"). Use the policy's `permitted_attributes_for_*` for "who can see this".
 - **Custom actions require a policy method.** `action :publish` needs `def publish?` on the policy.
-- **`has_cents` virtual accessor** — reference `:price`, NEVER `:price_cents`, in policies and definitions.
+- **`has_cents` virtual accessor**: reference `:price`, NEVER `:price_cents`, in policies and definitions.
 
 ---
 
-## 🛑 Before you scaffold or edit: confirm the shape (ASK — don't infer)
+## 🛑 Before you scaffold or edit: confirm the shape (ASK: don't infer)
 
-"Add a Product" / "add a status field" is underspecified. Guess wrong and you scaffold into the wrong package, churn migrations, store money as a lossy float, reference a model that doesn't exist, or **clobber files the user has customized**. Resolve each — **by inspecting (next section), not guessing** — then restate the resolved shape and confirm:
+"Add a Product" / "add a status field" is underspecified. Guess wrong and you scaffold into the wrong package, churn migrations, store money as a lossy float, reference a model that doesn't exist, or **clobber files the user has customized**. Resolve each, **by inspecting (next section), not guessing**, then restate the resolved shape and confirm:
 
 1. **New resource, or editing an existing one?** Existing ⇒ **NEVER re-run `pu:res:scaffold`** (it overwrites the customized model/definition/policy/controller). Add an incremental migration + hand-edit. Confirm by reading the files *first*.
 2. **Destination & portal.** `--dest=main_app` or a package? Which portal does `pu:res:conn` wire it to? Both are **required** and unguessable from the request.
-3. **Field types — and the money question.** A monetary field ⇒ `has_cents` (`price_cents:integer` + `has_cents :price_cents`, reference `:price`), **never a bare `decimal`**. Enums, attachments (`:attachment`/`:attachments`), rich text, references each have specific syntax (§ Field Type Syntax). Confirm types rather than inventing them.
-4. **Referenced associations must already exist.** `category:belongs_to` silently targets a `Category` — if that model isn't there, scaffold it first.
-5. **Beyond columns:** does it need search / filters / scopes / custom or bulk actions? Those live in the definition + policy, not the scaffold — name them now so you don't half-build.
+3. **Field types, and the money question.** A monetary field ⇒ `has_cents` (`price_cents:integer` + `has_cents :price_cents`, reference `:price`), **never a bare `decimal`**. Enums, attachments (`:attachment`/`:attachments`), rich text, references each have specific syntax (§ Field Type Syntax). Confirm types rather than inventing them.
+4. **Referenced associations must already exist.** `category:belongs_to` silently targets a `Category`; if that model isn't there, scaffold it first.
+5. **Beyond columns:** does it need search / filters / scopes / custom or bulk actions? Those live in the definition + policy, not the scaffold; name them now so you don't half-build.
 
 **Never emit applied scaffold commands from a guessed `--dest`, portal, or money-shape.** Confirm or read them first; fall back to `AskUserQuestion` only for product choices you can't read off the code (which portal, is `price` money). The decisions compound: *existing+customized ⇒ migration not scaffold*; *money ⇒ `has_cents` + `:price` in the policy*; *new reference ⇒ target model must exist*.
 
-## ✅ Before you touch files: verify the ground truth (CHECK — read it, don't ask for it)
+## ✅ Before you touch files: verify the ground truth (CHECK: read it, don't ask for it)
 
-You have file access — **use it.** "Paste me the model" is a fallback for when you genuinely can't read the repo, not the default.
+You have file access: **use it.** "Paste me the model" is a fallback for when you genuinely can't read the repo, not the default.
 
 | Check | How | Why it matters |
 |---|---|---|
@@ -49,7 +49,7 @@ You have file access — **use it.** "Paste me the model" is a fallback for when
 
 Inspect with your own tools **before** proposing commands or edits.
 
-## 🛠 Use the generator — and don't clobber
+## 🛠 Use the generator, and don't clobber
 
 Never hand-write the initial model, migration, policy, definition, or controller. Reach for the generator; quote args with `?`/`{}`; pass `--dest=`.
 
@@ -57,23 +57,32 @@ Never hand-write the initial model, migration, policy, definition, or controller
 |---|---|---|
 | New resource | `pu:res:scaffold Model field:type … --dest=` | `--dest` confirmed; referenced models exist |
 | Connect to a portal | `pu:res:conn Model --dest=portal` | Migrations are run |
-| Regenerate model from columns | `pu:res:scaffold Model --no-migration` | ⚠ **regenerates the model file** — review the diff; overwrites customizations |
-| Add a field to an **existing, customized** resource | `rails g migration AddXToYs …` + hand-edit model/definition/policy | This resource was already scaffolded — re-scaffolding clobbers it |
+| Portal-specific policy or definition | `pu:res:conn Model --dest=portal --policy` (and/or `--definition`) | Base policy/definition exists; the override subclasses it |
+| Regenerate model from columns | `pu:res:scaffold Model --no-migration` | ⚠ **regenerates the model file**: review the diff; overwrites customizations |
+| Add a field to an **existing, customized** resource | `rails g migration AddXToYs …` + hand-edit model/definition/policy | This resource was already scaffolded; re-scaffolding clobbers it |
 
 ---
 
-# Part 1 — Creating a Resource
+# Part 1: Creating a Resource
 
 ## Quick checklist
 
 1. Pick destination: `--dest=main_app` or `--dest=package_name`.
 2. Run `rails g pu:res:scaffold ResourceName field:type ... --dest=<dest>`.
-3. Review the generated migration — add cascade deletes, composite indexes, defaults.
+3. Review the generated migration: add cascade deletes, composite indexes, defaults.
 4. `rails db:prepare`.
 5. `rails g pu:res:conn ResourceName --dest=<portal_name>`.
 6. Customize the policy's `permitted_attributes_for_*` as needed.
 7. Open the portal route in the browser.
 
+**`permitted_associations` is checked per portal.** Each association listed there becomes a show-page tab, and the child model must be a registered resource in the portal rendering the page (`registered_resources` is the current engine's register). A base policy shared by several portals that names a child only one of them registers breaks the show page in the others:
+
+```
+ArgumentError: Catalog::Product#reviews defined in #permitted_associations, but Catalog::Review is not a registered resource
+```
+
+Register the child in every portal that uses the policy, or move the association into a portal-specific policy (`pu:res:conn Model --dest=portal --policy`, then `def permitted_associations = [*super, :reviews]`). See [[plutonium-behavior]].
+
 ## Command Syntax
 
 ```bash
@@ -194,9 +203,9 @@ price_cents:integer    # use with has_cents in model
 
 ## Generator Options
 
-- `--dest=DESTINATION` — `main_app` or `package_name` (**required**)
-- `--no-model` — skip model file
-- `--no-migration` — skip migration
+- `--dest=DESTINATION`: `main_app` or `package_name` (**required**)
+- `--no-model`: skip model file
+- `--no-migration`: skip migration
 
 For existing models that already include `Plutonium::Resource::Record`:
 
@@ -204,7 +213,7 @@ For existing models that already include `Plutonium::Resource::Record`:
 rails g pu:res:scaffold Post --no-migration --dest=main_app
 ```
 
-Run with no fields to auto-import from `model.content_columns` (regenerates the model file — review the diff).
+Run with no fields to auto-import from `model.content_columns` (regenerates the model file; review the diff).
 
 ## What Gets Generated
 
@@ -239,6 +248,8 @@ For non-trivial defaults, edit the migration directly:
 t.datetime :published_at, default: -> { "CURRENT_TIMESTAMP" }
 ```
 
+**Migration version: copy the app's form.** The generators (and `rails g migration`) stamp `ActiveRecord::Migration[<current version>]`, the Rails version that ran them. When you hand-write or edit a migration, open a neighbouring one and match its superclass rather than typing a version. An engine or gem whose test app runs under several Rails versions (Appraisal) often uses `ActiveRecord::Migration[[Rails::VERSION::MAJOR, Rails::VERSION::MINOR].join(".").to_f]` or a pinned older version, and a hard-coded `[8.1]` raises on load under Rails 7.x or 8.0.
+
 ## Examples
 
 ```bash
@@ -268,7 +279,7 @@ rails g pu:res:scaffold Comment \
 
 ---
 
-# Part 2 — The Model Layer
+# Part 2: The Model Layer
 
 ## What `Plutonium::Resource::Record` provides
 
@@ -296,7 +307,7 @@ end
 
 ## Section Order
 
-The scaffold lays out resource models in a strict order — keep new code in the right section so files stay scannable:
+The scaffold lays out resource models in a strict order: keep new code in the right section so files stay scannable:
 
 1. Concerns (`include`)
 2. Constants (`TYPES = {...}.freeze`)
@@ -370,7 +381,7 @@ product.price = 10.999
 product.price_cents  # => 1099
 ```
 
-**Critical: in policies and definitions, reference the virtual accessor (`:price`), NOT the column (`:price_cents`).** Generators sometimes emit `_cents` in the policy — fix by hand:
+**Critical: in policies and definitions, reference the virtual accessor (`:price`), NOT the column (`:price_cents`).** Generators sometimes emit `_cents` in the policy, so fix by hand:
 
 ```ruby
 # Policy
@@ -409,7 +420,7 @@ post.remove_tag_sgid("...")   # collection: remove
 
 ## URL Routing
 
-`path_parameter` and `dynamic_path_parameter` are **class-level macros** (private class methods) — call them in the class body, not as instance methods.
+`path_parameter` and `dynamic_path_parameter` are **class-level macros** (private class methods): call them in the class body, not as instance methods.
 
 ```ruby
 # Default: numeric id
@@ -457,11 +468,11 @@ User.has_many_attached_field_names
 
 ---
 
-# Part 3 — The Definition Layer
+# Part 3: The Definition Layer
 
 Definitions configure **how** a resource is rendered and interacted with.
 
-🚨 **Do NOT declare a `field` / `input` / `display` / `column` unless you are overriding an auto-detected default.** Plutonium reads the model and renders every attribute automatically — type, label, form widget, display formatter, column. Declaring it again with no new options is dead code; declaring it with the same `as:` Plutonium already inferred is dead code; listing every field "for completeness" is dead code. If the only reason you're adding a line is "so the field shows up", delete it — it already shows up. Declare ONLY when you need: a different type (`as: :markdown`), a custom option (`hint:`, `placeholder:`, `wrapper:`), a `condition:`, a custom block, or a custom component.
+🚨 **Do NOT declare a `field` / `input` / `display` / `column` unless you are overriding an auto-detected default.** Plutonium reads the model and renders every attribute automatically: type, label, form widget, display formatter, column. Declaring it again with no new options is dead code; declaring it with the same `as:` Plutonium already inferred is dead code; listing every field "for completeness" is dead code. If the only reason you're adding a line is "so the field shows up", delete it; it already shows up. Declare ONLY when you need: a different type (`as: :markdown`), a custom option (`hint:`, `placeholder:`, `wrapper:`), a `condition:`, a custom block, or a custom component.
 
 File locations:
 
@@ -532,29 +543,33 @@ The field-level help keys (`:label`, `:description`, `:hint`, `:placeholder`) ar
 
 | Category | Types |
 |----------|-------|
-| Text | `:string`, `:text`, `:email`, `:url`, `:tel`, `:password` |
-| Rich Text | `:markdown` (EasyMDE) |
-| Numeric | `:number`, `:integer`, `:decimal`, `:range` |
-| Boolean | `:toggle` / `:switch` (switch — **default** for boolean columns), `:boolean` (plain checkbox) |
+| Text | `:string`, `:text`, `:email`, `:url`, `:phone`, `:password` (alias `:secret`) |
+| Rich Text | `:rich_text` (Action Text editor: Trix, or Lexxy once installed; **default** for `has_rich_text`), `:markdown` (EasyMDE) |
+| Numeric | `:number`, `:integer`, `:decimal`, `:range`, `:rating` (star picker, `max:`) |
+| Boolean | `:toggle` / `:switch` (switch, **default** for boolean columns), `:boolean` (plain checkbox) |
 | Date/Time | `:date`, `:time`, `:datetime` |
-| Selection | `:select`, `:slim_select`, `:radio_buttons`, `:check_boxes` |
-| Files | `:file`, `:uppy`, `:attachment` |
+| Selection | `:select`, `:slim_select`, `:collection_radio_buttons`, `:collection_checkboxes` |
+| Lists | `:list` (chip input for array values; `suggestions:`, `addable:`, `limit:`), `:tags` (no_fly_list `has_tags` contexts, **auto-detected**) |
+| Files | `:file`, `:uppy`, `:attachment` (Active Storage), `:binary` (bytes in a `binary` column) |
 | Associations | `:association`, `:secure_association`, `:belongs_to`, `:has_many`, `:has_one` |
-| Special | `:hidden`, `:color`, `:phone` |
+| Special | `:hidden`, `:color`, `:json`, `:key_value` |
 
 ### Display Types (show / index)
 
-`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:badge`, `:currency`, `:color`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`
+`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:badge`, `:currency`, `:color`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`, `:key_value`, `:binary`, `:list`, `:tags`, `:rich_text`, `:relative_time`, `:code`, `:duration`, `:file_size`, `:progress`, `:rating`
 
 #### Auto-inferred display formatting
 
-These render automatically — declare an `as:` only to override or pass options:
+These render automatically: declare an `as:` only to override or pass options:
 
 | Column | Renders as | Notes |
 |--------|-----------|-------|
 | `boolean` | Yes/No pill (`:boolean`) | green "Yes" / neutral "No". Override labels: `true_label:`, `false_label:` |
 | `enum` | colored status badge (`:badge`) | known statuses (active, pending, failed…) auto-colored; unknown values get a stable decorative color |
-| `has_cents` decimal | currency (`:currency`) | delimited, 2 decimals, **no symbol** unless you add `unit:` |
+| `binary` | size (`:binary`) | `Binary data (12 KB)`, never the bytes |
+| `has_rich_text` | HTML (`:rich_text`) | rendered and sanitized by Action Text |
+| no_fly_list `has_tags` | chips (`:tags`) | declare by context name (`:labels`), not `labels_list` |
+| `has_cents` decimal | currency (`:currency`) | delimited, 2 decimals; symbol from `unit:` (display or `has_cents`), else `config.default_currency_unit` / i18n. `unit: false` drops it |
 
 ```ruby
 display :status, as: :badge, colors: {archived: :neutral, vip: :accent}  # override per-value color
@@ -592,7 +607,7 @@ input :title,
 input :category, as: :select, choices: %w[Tech Business Lifestyle]
 input :status, as: :select, choices: Post.statuses.keys
 
-# Dynamic — must use a block
+# Dynamic: must use a block
 input :author do |f|
   f.select_tag choices: User.active.pluck(:name, :id)
 end
@@ -624,24 +639,24 @@ A surface's own `condition:` wins; otherwise the surface falls back to the `fiel
 
 ## Options That Vary Per Render
 
-Any option may be a **proc**, resolved on every render rather than frozen at class load. Holds across the whole form DSL — `field`, `input`, `section`/`ungrouped`, `structured_input`, nested inputs. Arity says **whether you want the form**:
+Any option may be a **proc**, resolved on every render rather than frozen at class load. Holds across the whole form DSL: `field`, `input`, `section`/`ungrouped`, `structured_input`, nested inputs. Arity says **whether you want the form**:
 
 ```ruby
 input :tier,  as: :select, choices: ->(form) { form.object.account.available_tiers }
 input :notes, placeholder: -> { "Updated #{Time.current.year}" }
 ```
 
-- `-> { … }` is called as-is, keeping its own binding — it means what it reads like where you wrote it; nothing rebinds `self`. That is what makes `choices: -> { reviewer_choices }` work inside an interaction's `customize_inputs` (private helpers included).
-- `->(form) { … }` gets the form — `object` (the record), `params`, view helpers.
+- `-> { … }` is called as-is, keeping its own binding: it means what it reads like where you wrote it; nothing rebinds `self`. That is what makes `choices: -> { reviewer_choices }` work inside an interaction's `customize_inputs` (private helpers included).
+- `->(form) { … }` gets the form: `object` (the record), `params`, view helpers.
 
-Same rule on wizard steps — but a step block closes over an internal field recorder, so options there must take the form: `->(form) { form.wizard.anchor.tiers }`. See [[plutonium-wizard]].
+Same rule on wizard steps, but a step block closes over an internal field recorder, so options there must take the form: `->(form) { form.wizard.anchor.tiers }`. See [[plutonium-wizard]].
 
-**`condition:` is not an option — it follows a different rule, for a reason.** An option asks "what value should this have?", so it may not care about the render and defaults to meaning what it reads like. `condition:` asks "should this render *here, now*?" — a question about the render context by definition. So it always runs **against** that context and reads it with no argument, where "context" is whatever is rendering:
+**`condition:` is not an option: it follows a different rule, for a reason.** An option asks "what value should this have?", so it may not care about the render and defaults to meaning what it reads like. `condition:` asks "should this render *here, now*?", a question about the render context by definition. So it always runs **against** that context and reads it with no argument, where "context" is whatever is rendering:
 
 ```ruby
 input   :notes,     condition: -> { object.published? }        # the form
 display :audit_log, condition: -> { current_user.admin? }      # the display component
-step    :billing,   condition: -> { data.plan.tier == "pro" }  # the wizard — no form exists yet
+step    :billing,   condition: -> { data.plan.tier == "pro" }  # the wizard, no form exists yet
 ```
 
 It cannot take a `form` argument the way an option does: for a `column`/`display`, a step, or an action there is no form.
@@ -689,7 +704,7 @@ class QuestionDefinition < ResourceDefinition
     choices: %w[text choice scale],
     pre_submit: true
 
-  # No `as:` — types are auto-detected from the model. We only declare to add `condition:`.
+  # No `as:`: types are auto-detected from the model. We only declare to add `condition:`.
   input :max_length, condition: -> { object.question_type == "text" }
   input :choices,    condition: -> { object.question_type == "choice" }
   input :min_value,  condition: -> { object.question_type == "scale" }
@@ -716,7 +731,7 @@ Tips:
 
 ## Custom Rendering
 
-**Display block — return any component:**
+**Display block: return any component:**
 
 ```ruby
 display :status do |field|
@@ -724,7 +739,7 @@ display :status do |field|
 end
 ```
 
-**Input block — must use form builder methods:**
+**Input block: must use form builder methods:**
 
 ```ruby
 input :birth_date do |f|
@@ -762,14 +777,14 @@ end
 
 See [[plutonium-ui]] for writing custom Phlex components.
 
-**Custom component classes** (Phlex components — see [[plutonium-ui]]). `as:` takes a **field component**, constructed as `YourComponent.new(field, **attributes)` — subclass `Phlexi::Form::Components::Base` (inputs) or `Phlexi::Display::Components::Base` (displays) and read the value off `field`:
+**Custom component classes** (Phlex components, see [[plutonium-ui]]). `as:` takes a **field component**, constructed as `YourComponent.new(field, **attributes)`: subclass `Phlexi::Form::Components::Base` (inputs) or `Phlexi::Display::Components::Base` (displays) and read the value off `field`:
 
 ```ruby
 input :color_picker, as: ColorPickerComponent
 display :chart, as: ChartComponent
 ```
 
-🚨 A component with its own constructor (`PostCardComponent.new(post:)`) is NOT an `as:` candidate — it raises `ArgumentError`. Build it in a block instead:
+🚨 A component with its own constructor (`PostCardComponent.new(post:)`) is NOT an `as:` candidate; it raises `ArgumentError`. Build it in a block instead:
 
 ```ruby
 display :card do |field|
@@ -783,10 +798,10 @@ end
 column :title, align: :start     # :start (default), :center, :end
 column :amount, align: :end
 
-# formatter — receives just the value
+# formatter: receives just the value
 column :price, formatter: ->(v) { "$%.2f" % v if v }
 
-# block — receives the full record
+# block: receives the full record
 column :full_name do |record|
   "#{record.first_name} #{record.last_name}"
 end
@@ -841,7 +856,7 @@ end
 |--------|-------------|
 | `limit` | Max records (auto-detected from model, default 10) |
 | `allow_destroy` | Show delete checkbox (auto-detected) |
-| `update_only` | Hide "Add" button — only edit existing |
+| `update_only` | Hide "Add" button, only edit existing |
 | `description` | Help text above section |
 | `condition` | Proc to show/hide |
 | `using` | Another Definition class |
@@ -857,7 +872,7 @@ end
 
 ## Structured Inputs
 
-`structured_input` collects a **classless** group of fields — a single hash, or
+`structured_input` collects a **classless** group of fields: a single hash, or
 (with `repeat:`) an array of hashes. No association or model class is involved.
 On resources the value is stored in a **JSON/jsonb column**; use it when you
 want structured data in a JSON column rather than a real association (which is
@@ -901,14 +916,14 @@ blank rows are dropped, `_destroy` stripped).
 
 ### Gotchas
 
-- The column must be `json`/`jsonb` (or otherwise hold a hash/array). No model macro is needed — the value assigns directly.
+- The column must be `json`/`jsonb` (or otherwise hold a hash/array). No model macro is needed; the value assigns directly.
 - **Unlike `nested_input`, you DO permit the column name** in `permitted_attributes_for_*` (it's a regular attribute on a JSON column).
-- `repeat: 1` is "array, max one row" — **not** the single form. Presence of `repeat:` always means an array.
-- Rows are positional plain hashes — **no ids, no per-row class, no type coercion**.
+- `repeat: 1` is "array, max one row", **not** the single form. Presence of `repeat:` always means an array.
+- Rows are positional plain hashes: **no ids, no per-row class, no type coercion**.
 - **No automatic validation.** Classless ⇒ nothing to attach `validates` to. `required:` and a select's `choices:` are **client-side only**, not enforced on the server. To enforce, add a model `validate` (resource) or a `validate` on the interaction (ActiveModel, checked before `execute`).
 - **`as: :select` drops unknown values.** If a stored value isn't in `choices:`, the `<select>` renders blank and **saving overwrites it with `nil`** (standard `<select>` behaviour). Keep `choices:` a stable superset or use free text when values can drift.
-- Inside repeater rows, prefer **native** field types (string, number, text, native `select`, checkbox). JS-enhanced inputs (slim-select, flatpickr, easymde, uppy, intl-tel) transform the DOM and may not survive the repeater's clone-by-innerHTML — verify before relying on them.
-- Same DSL works on **interactions** (see [[plutonium-behavior]] › Interactions) — there it backs an ActiveModel attribute reaching `execute`.
+- Inside repeater rows, prefer **native** field types (string, number, text, native `select`, checkbox). JS-enhanced inputs (slim-select, flatpickr, easymde, uppy, intl-tel) transform the DOM and may not survive the repeater's clone-by-innerHTML; verify before relying on them.
+- Same DSL works on **interactions** (see [[plutonium-behavior]] › Interactions); there it backs an ActiveModel attribute reaching `execute`.
 
 ## File Uploads
 
@@ -925,9 +940,9 @@ input :documents, as: :uppy,
 
 Inside `condition` procs and block-form `input`/`display`:
 
-- `object` — the record
+- `object`: the record
 - `current_user`
-- `current_parent` — for nested resources
+- `current_parent`: for nested resources
 - `request`, `params`
 - All helper methods
 
@@ -964,7 +979,7 @@ class PostDefinition < ResourceDefinition
   breadcrumbs true
   show_page_breadcrumbs false
 
-  # Custom page classes — inherit from the parent's nested class
+  # Custom page classes: inherit from the parent's nested class
   class IndexPage < IndexPage
     def view_template(&block)
       div(class: "custom-header") { h1 { "Custom" } }
@@ -988,7 +1003,7 @@ end
 
 ## Form Layout (`form_layout`)
 
-Group form fields into sections **declaratively in the definition** — no `Form` subclass, no view code. Prefer this over hand-rolling a `section` helper in a custom `form_template`.
+Group form fields into sections **declaratively in the definition**, no `Form` subclass, no view code. Prefer this over hand-rolling a `section` helper in a custom `form_template`.
 
 ```ruby
 class PostDefinition < ResourceDefinition
@@ -1002,18 +1017,18 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-- **Layout references field KEYS only** — all per-field config (`as:`, `hint:`, blocks, per-field `condition:`) stays on `input`. Never duplicated here.
-- **Options**: `label:`, `description:`, `collapsible:`, `collapsed:`, `columns:` (positive Integer, literal only), `condition:`. Every option except `columns:` may be a **proc**, resolved at render under the same arity rule as any other option — take a `form` argument to read the render context.
+- **Layout references field KEYS only**: all per-field config (`as:`, `hint:`, blocks, per-field `condition:`) stays on `input`. Never duplicated here.
+- **Options**: `label:`, `description:`, `collapsible:`, `collapsed:`, `columns:` (positive Integer, literal only), `condition:`. Every option except `columns:` may be a **proc**, resolved at render under the same arity rule as any other option: take a `form` argument to read the render context.
 - ⚠️ **Breaking in 0.63**: section options used to take a zero-arg proc run *against* the form. They now follow the shared rule, and a `form_layout` block is evaluated against the layout builder, so a bare `object` is a `NameError`. Migrate `collapsed: -> { object.persisted? }` → `collapsed: ->(form) { form.object.persisted? }`. `condition:` is unchanged (still form-evaluated, still reads `object` with no argument).
-- **Absent fields are skipped.** A key the section lists that isn't in the permitted set (policy, per-action, scoping, nesting, or a typo) is silently dropped — never an error. The same layout serves a richly-permitted `edit` and a minimal `new`.
-- **🚨 Zero-field sections drop entirely** — no heading, no grid. So `+ New` (fewer permitted attributes) won't sprout empty headings. A section whose fields are **all** hidden by their own `condition:` on this render drops too (the hidden fields are still recorded on the form). A section's own `condition:` hides it as a unit regardless of its fields.
-- **Works on interactions too** (`Plutonium::Interaction::Base`) — groups `attribute` declarations. There `object` is the interaction instance; for record actions the record is `object.resource`.
+- **Absent fields are skipped.** A key the section lists that isn't in the permitted set (policy, per-action, scoping, nesting, or a typo) is silently dropped, never an error. The same layout serves a richly-permitted `edit` and a minimal `new`.
+- **🚨 Zero-field sections drop entirely**: no heading, no grid. So `+ New` (fewer permitted attributes) won't sprout empty headings. A section whose fields are **all** hidden by their own `condition:` on this render drops too (the hidden fields are still recorded on the form). A section's own `condition:` hides it as a unit regardless of its fields.
+- **Works on interactions too** (`Plutonium::Interaction::Base`): groups `attribute` declarations. There `object` is the interaction instance; for record actions the record is `object.resource`.
 
 Full DSL reference: [Resource › Definition › Form layout](/reference/resource/definition#form-layout).
 
 ## Display Layout (`display_layout`)
 
-The show page's counterpart to `form_layout`. Same DSL, same resolution (first-section-wins, unlisted permitted fields fall into `ungrouped`, absent fields skipped, zero-field and all-condition-hidden sections dropped) — applied to the show page's fields instead of the form's.
+The show page's counterpart to `form_layout`. Same DSL, same resolution (first-section-wins, unlisted permitted fields fall into `ungrouped`, absent fields skipped, zero-field and all-condition-hidden sections dropped), applied to the show page's fields instead of the form's.
 
 ```ruby
 class PostDefinition < ResourceDefinition
@@ -1025,14 +1040,14 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-- **Declare both independently.** `form_layout` and `display_layout` are separate registries — a resource can group its form one way and its show page another, or declare only one. Neither inherits from the other.
-- **🚨 No `columns:`** — unlike `form_layout`, it **raises**. Every display section shares one responsive grid; field width is a per-field concern: `display :x, wrapper: {class: "col-span-2"}` (works identically inside a section and outside one). Raising rather than ignoring means a copied `form_layout` block fails loudly instead of silently doing nothing.
-- **Options**: `label:`, `description:`, `collapsible:`, `collapsed:`, `condition:` — the same set as `form_layout` minus `columns:`. `collapsible: true, collapsed: true` works exactly as it does on forms. Every option except `condition:` may be a **proc**, resolved at render under the same arity rule as the form: take a `display` argument to read `object`.
-- **Each section renders as its own card**, so the sectioned show page has no single outer card. Fields declared in `metadata` are excluded (they render in the metadata panel) — see below.
+- **Declare both independently.** `form_layout` and `display_layout` are separate registries: a resource can group its form one way and its show page another, or declare only one. Neither inherits from the other.
+- **🚨 No `columns:`.** Unlike `form_layout`, it **raises**. Every display section shares one responsive grid; field width is a per-field concern: `display :x, wrapper: {class: "col-span-2"}` (works identically inside a section and outside one). Raising rather than ignoring means a copied `form_layout` block fails loudly instead of silently doing nothing.
+- **Options**: `label:`, `description:`, `collapsible:`, `collapsed:`, `condition:`, the same set as `form_layout` minus `columns:`. `collapsible: true, collapsed: true` works exactly as it does on forms. Every option except `condition:` may be a **proc**, resolved at render under the same arity rule as the form: take a `display` argument to read `object`.
+- **Each section renders as its own card**, so the sectioned show page has no single outer card. Fields declared in `metadata` are excluded (they render in the metadata panel); see below.
 
 ## Page Width (`page_width`)
 
-Detail-style pages — the show page and resource forms — are width-constrained by default. Inputs and values stretch to their container, so at full content width you get ~1200px-long lines. Index/table pages are NOT affected.
+Detail-style pages (the show page and resource forms) are width-constrained by default. Inputs and values stretch to their container, so at full content width you get ~1200px-long lines. Index/table pages are NOT affected.
 
 ```ruby
 Plutonium.configure { |c| c.default_page_width = :md }   # global default (:md)
@@ -1045,12 +1060,12 @@ end
 ```
 
 - **Sizes**: `:sm` `:md` `:lg` `:xl` `:full`. `:full` means no constraint. An unknown value **raises** at declaration.
-- **🚨 Tokens are relative to their surface** — the same *names* modals use, but NOT the same widths. Page `:md` is 896px; a centered modal's `:md` is 576px and a slideover's is 480px. A "small page" is deliberately larger than a "small dialog". Modals also have `:auto`; pages don't (nothing to hug).
+- **🚨 Tokens are relative to their surface**: the same *names* modals use, but NOT the same widths. Page `:md` is 896px; a centered modal's `:md` is 576px and a slideover's is 480px. A "small page" is deliberately larger than a "small dialog". Modals also have `:auto`; pages don't (nothing to hug).
 - **Resolution**: surface-specific (`form_width` / `display_width`) → `page_width` → `Plutonium.configuration.default_page_width`. An explicit `:full` is honoured, not treated as unset.
 - **Inherits** to subclasses, so a portal-specific definition keeps the parent's width unless it overrides.
-- **Modals are unaffected** — the dialog sets its own width (`modal_size`).
+- **Modals are unaffected**: the dialog sets its own width (`modal_size`).
 - **Interactions support it too** (`Plutonium::Interaction::Base`), for interactive actions rendered as standalone pages.
-- **Wizards are on their own axis** — `Plutonium.configuration.wizards.width` (default `:md`), overridden per wizard with `width`. It does NOT follow `default_page_width`, so changing resource page width leaves wizards untouched.
+- **Wizards are on their own axis**: `Plutonium.configuration.wizards.width` (default `:md`), overridden per wizard with `width`. It does NOT follow `default_page_width`, so changing resource page width leaves wizards untouched.
 
 ## Metadata Panel (show page)
 
@@ -1060,12 +1075,12 @@ Declares fields rendered in the show page's right-side aside as label/value rows
 metadata :author, :state, :created_at, :updated_at
 ```
 
-- **Opt-in** — no call → show page is full-width with no aside.
-- **Policy-aware** — fields the user can't see disappear; panel auto-hides if nothing's permitted.
-- **Deduplicated** — listed fields are removed from the main details card (and from any `display_layout` section).
-- **Responsive** — side-by-side at `lg+`, stacked below.
+- **Opt-in**: no call → show page is full-width with no aside.
+- **Policy-aware**: fields the user can't see disappear; panel auto-hides if nothing's permitted.
+- **Deduplicated**: listed fields are removed from the main details card (and from any `display_layout` section).
+- **Responsive**: side-by-side at `lg+`, stacked below.
 - **In a modal it stacks below the details**, not beside them: the rail is a fixed-width column on a *viewport* breakpoint, so in a dialog it would split regardless of how narrow the dialog is and crush the main column.
-- **A kanban card's modal drops metadata entirely** — the fields are hidden, not folded into the main card.
+- **A kanban card's modal drops metadata entirely**: the fields are hidden, not folded into the main card.
 
 Use for chrome (timestamps, ownership, system flags), keeping the main card focused on substance.
 
@@ -1075,7 +1090,7 @@ Resources can offer both Table and Grid views; user choice persists per-resource
 
 ```ruby
 class UserDefinition < ResourceDefinition
-  # No `index_views :table, :grid` needed — `grid_fields` auto-enables :grid alongside the default :table.
+  # No `index_views :table, :grid` needed, `grid_fields` auto-enables :grid alongside the default :table.
   grid_fields(
     image:     :avatar,           # ActiveStorage, Shrine, or URL
     header:    :name,             # falls back to to_label
@@ -1085,7 +1100,7 @@ class UserDefinition < ResourceDefinition
     footer:    :last_seen_at      # falls back to :created_at; `false` to omit
   )
 
-  default_index_view :grid        # optional — initial view when no cookie
+  default_index_view :grid        # optional: initial view when no cookie
   grid_layout :media              # :compact (default) or :media
   grid_columns 3                  # pin lg+ cols; default is 1/2/3/4 responsive
 end
@@ -1107,23 +1122,23 @@ All grid slots are optional; slots pointing at unpermitted fields collapse silen
 
 ## Drag-to-Reorder (`positioned_on` + `position_on`)
 
-Manual ordering on the index table, the card grid, and nested association tables. **Two verbs, never three** — the model says how positions are stored, the definition (and a kanban board) says the UI is orderable:
+Manual ordering on the index table, the card grid, and nested association tables. **Two verbs, never three**: the model says how positions are stored, the definition (and a kanban board) says the UI is orderable:
 
 ```ruby
-# Migration — t.position emits decimal(16,8), tuned for fractional ordering.
+# Migration: t.position emits decimal(16,8), tuned for fractional ordering.
 create_table :tasks do |t|
   t.string :status, null: false, default: "todo"
   t.position
   t.index [:status, :position]     # match the scope attribute
 end
 
-# Model — storage
+# Model: storage
 class Task < ApplicationRecord
   include Plutonium::Positioning::Model    # NOT Plutonium::Positioning
   positioned_on :position, scope: :status  # scope: nil = one global ordering
 end
 
-# Definition — "this UI can be reordered". Never restates the column or the scope.
+# Definition: "this UI can be reordered". Never restates the column or the scope.
 class TaskDefinition < ResourceDefinition
   position_on
 end
@@ -1132,45 +1147,45 @@ end
 Task.backfill_positions!(order: :created_at)
 ```
 
-- **`include Plutonium::Positioning::Model`** — the concern used to be `Plutonium::Positioning` itself. A bare `include Plutonium::Positioning` is now wrong (it's a pure namespace). Constants nested in an included concern join the model's constant lookup, so the old form let `Plutonium::Positioning::Config` shadow an app's own `::Config`.
-- **`positioned_on` is required**, not just the include — without it there's no `before_create`, so every row is created with a `NULL` position. `position_on` raises at class-load if you forget.
+- **`include Plutonium::Positioning::Model`**: the concern used to be `Plutonium::Positioning` itself. A bare `include Plutonium::Positioning` is now wrong (it's a pure namespace). Constants nested in an included concern join the model's constant lookup, so the old form let `Plutonium::Positioning::Config` shadow an app's own `::Config`.
+- **`positioned_on` is required**, not just the include; without it there's no `before_create`, so every row is created with a `NULL` position. `position_on` raises at class-load if you forget.
 
 ### `position_on` forms and modes
 
 | Form | Mode | Notes |
 |---|---|---|
-| `position_on` | A (delegate) | Follows the model's `positioning_column`. **Prefer this** — it cannot disagree with the model. |
+| `position_on` | A (delegate) | Follows the model's `positioning_column`. **Prefer this**: it cannot disagree with the model. |
 | `position_on :sort_order` | A | Must **match** the model's column, else `ArgumentError` at class-load |
-| `position_on(:rank) { \|move\| … }` | B (block) | Escape hatch — another gem owns the write (`acts_as_list`). No model concern needed. **Prefer migrating to A.** |
-| `position_on false` | C (disabled) | No ordering, no route — the endpoint 404s |
+| `position_on(:rank) { \|move\| … }` | B (block) | Escape hatch: another gem owns the write (`acts_as_list`). No model concern needed. **Prefer migrating to A.** |
+| `position_on false` | C (disabled) | No ordering, no route, the endpoint 404s |
 
-**Default to Mode A.** It is one word in the definition. A *correct* Mode B block is ~15 lines of rank arithmetic, and getting it right requires knowing three non-obvious things: `move.index` is page-relative; removing a record shifts its neighbours' ranks by one, in a direction that depends on where it started; and a blank `move.prev` means "nothing above me *on screen*", not "top of the list". These docs got two of the three wrong until they were tested. Mode B is legitimate and tested — it just costs you semantics Mode A handles.
+**Default to Mode A.** It is one word in the definition. A *correct* Mode B block is ~15 lines of rank arithmetic, and getting it right requires knowing three non-obvious things: `move.index` is page-relative; removing a record shifts its neighbours' ranks by one, in a direction that depends on where it started; and a blank `move.prev` means "nothing above me *on screen*", not "top of the list". These docs got two of the three wrong until they were tested. Mode B is legitimate and tested; it just costs you semantics Mode A handles.
 
-### Mode B — what the framework stops doing
+### Mode B: what the framework stops doing
 
 Mode B block receives a `Plutonium::Positioning::Move`: `record`, `prev`, `next`, `index` (0-based, **relative to the visible page**), `column` (kanban only, `nil` on tables/grids). Called with `call`, not `instance_exec`.
 
 Because the write is opaque, three Mode A behaviours are **not** provided:
 
-- **No hidden boundary resolution** — `resolve_position_boundaries` returns early unless the config delegates, so the block gets the client's viewport verbatim, `nil`s and all.
-- **No server-side foreign-sort rejection** — Mode A rejects a drop under a foreign sort with 422 before writing; Mode B relies on the client-side gate only.
-- **Always a full repaint** — never 204. Gems like `acts_as_list` renumber the whole group on every move, so the client's optimistic DOM is stale by definition.
+- **No hidden boundary resolution**: `resolve_position_boundaries` returns early unless the config delegates, so the block gets the client's viewport verbatim, `nil`s and all.
+- **No server-side foreign-sort rejection**: Mode A rejects a drop under a foreign sort with 422 before writing; Mode B relies on the client-side gate only.
+- **Always a full repaint**: never 204. Gems like `acts_as_list` renumber the whole group on every move, so the client's optimistic DOM is stale by definition.
 
 ### Migrating off `acts_as_list` to Mode A
 
-1. **Change the column** — `acts_as_list` uses contiguous integers; Plutonium uses fractional decimals (`t.position` emits `decimal(16,8)`; an integer column would round every midpoint onto a neighbour). `t.position` *adds* a column, so an existing one needs `change_column :tasks, :position, :decimal, precision: 16, scale: 8`.
-2. **Swap the macro** — drop `acts_as_list scope: [:status]`, add `include Plutonium::Positioning::Model` + `positioned_on :position, scope: :status` (bare Symbol; the Array trap is gem-specific).
-3. **Backfill** — `Task.backfill_positions!(order: :position)` numbers each scope group `1.0, 2.0, …` in the gem's existing order. `update_column`, no callbacks/validations/`updated_at` — run it once from a migration or `rails runner`.
+1. **Change the column**: `acts_as_list` uses contiguous integers; Plutonium uses fractional decimals (`t.position` emits `decimal(16,8)`; an integer column would round every midpoint onto a neighbour). `t.position` *adds* a column, so an existing one needs `change_column :tasks, :position, :decimal, precision: 16, scale: 8`.
+2. **Swap the macro**: drop `acts_as_list scope: [:status]`, add `include Plutonium::Positioning::Model` + `positioned_on :position, scope: :status` (bare Symbol; the Array trap is gem-specific).
+3. **Backfill**: `Task.backfill_positions!(order: :position)` numbers each scope group `1.0, 2.0, …` in the gem's existing order. `update_column`, no callbacks/validations/`updated_at`; run it once from a migration or `rails runner`.
 4. Drop the block from the definition; a bare `position_on` is the whole of Mode A.
 
 ### Staying on `acts_as_list` (the harder road)
 
 For when the gem is not yours to remove. This recipe is correct and tested against the real gem (`test/plutonium/resource/controllers/position_actions_acts_as_list_test.rb`).
 
-🚨 **Anchor off `move.prev` / `move.next`, never off `move.index`.** `move.index` counts the visible page; a positioning gem's `insert_at` addresses the whole group. `insert_at(move.index + 1)` is wrong on any list past 20 rows (Plutonium's default page size) — measured: dragging rank 25 into the middle of page 2 lands it at **rank 2**, and a page-2 top drop lands at **rank 1**. Same failures on a filtered list.
+🚨 **Anchor off `move.prev` / `move.next`, never off `move.index`.** `move.index` counts the visible page; a positioning gem's `insert_at` addresses the whole group. `insert_at(move.index + 1)` is wrong on any list past 20 rows (Plutonium's default page size). Measured: dragging rank 25 into the middle of page 2 lands it at **rank 2**, and a page-2 top drop lands at **rank 1**. Same failures on a filtered list.
 
 ```ruby
-# Keeping acts_as_list. NOTE scope: [:status] — a bare Symbol scope is run
+# Keeping acts_as_list. NOTE scope: [:status], a bare Symbol scope is run
 # through acts_as_list's `idify`, which turns :status into :status_id and makes
 # every create raise NoMethodError.
 class Task < ApplicationRecord
@@ -1186,7 +1201,7 @@ class TaskDefinition < ResourceDefinition
         # Removing the record shifts prev up one when the record was above it.
         (record.position > move.prev.position) ? move.prev.position + 1 : move.prev.position
       elsif move.next
-        # Blank prev means "nothing above me ON MY SCREEN" — rows may still sit
+        # Blank prev means "nothing above me ON MY SCREEN"; rows may still sit
         # above off-page or behind a filter, so anchor off next rather than 1.
         (record.position < move.next.position) ? move.next.position - 1 : move.next.position
       else
@@ -1198,7 +1213,7 @@ class TaskDefinition < ResourceDefinition
 end
 ```
 
-`insert_at` calls `save`, not `save!` — a failed move silently no-ops. Use `insert_at!` to surface it as a 422.
+`insert_at` calls `save`, not `save!`; a failed move silently no-ops. Use `insert_at!` to surface it as a 422.
 
 ### 🚨 `position_on` expands to three things
 
@@ -1208,21 +1223,21 @@ default_sort <attr>, :asc        # ⚠ ONLY when default_sort is still the frame
 action :reposition, hidden: true # route + policy predicate, no button
 ```
 
-**The `default_sort` claim is implicit.** A resource that listed newest-first will list in position order after you add `position_on`. Declare your own `default_sort` (above OR below `position_on` — resolution is order-independent) to keep it; note the list then opens **not** draggable.
+**The `default_sort` claim is implicit.** A resource that listed newest-first will list in position order after you add `position_on`. Declare your own `default_sort` (above OR below `position_on`: resolution is order-independent) to keep it; note the list then opens **not** draggable.
 
 ### Behavior notes
 
 - **Dragging is offered only while the collection is sorted ascending by the position attribute** (and nothing else). Under any other sort the grip renders as a **link that applies that sort**, and the server rejects the drop with 422 before writing.
 - **`reposition?` policy predicate**, defaulting to `update?`. Gates both the drop and whether the grip renders per row. `index?` is also required (you must be able to see a list to reorder it).
 - **A kanban board inherits the definition's `position_on`** (lazily, so order in the class body doesn't matter); a `position_on` inside `kanban do…end` overrides it.
-- **`scope:` is the model author's job.** A globally positioned model rendered under a parent still reorders correctly per parent — but a rebalance renumbers every row in the table, not just that parent's.
+- **`scope:` is the model author's job.** A globally positioned model rendered under a parent still reorders correctly per parent, but a rebalance renumbers every row in the table, not just that parent's.
 - Native HTML5 drag doesn't fire on **touch** devices (same limitation as kanban). Keyboard works: focus the grip, <kbd>↑</kbd>/<kbd>↓</kbd>.
 
 Full reference: `docs/reference/resource/positioning.md`. Kanban specifics: `docs/reference/kanban/positioning.md`.
 
 ---
 
-# Part 4 — Query: Search, Filters, Scopes, Sorting
+# Part 4: Query: Search, Filters, Scopes, Sorting
 
 ```ruby
 class PostDefinition < ResourceDefinition
@@ -1266,6 +1281,7 @@ end
 | Date Range | `:date_range` | `from`, `to` | `from_label:`, `to_label:` |
 | Select | `:select` | `value` | `choices:`, `multiple:` |
 | Association | `:association` | `value` | `class_name:`, `multiple:` |
+| Tags | `:tags` | `value` | `match:` (`:any` default, `:all`); no_fly_list contexts, options limited to the policy scope |
 
 **Text predicates:** `:eq`, `:not_eq`, `:contains`, `:not_contains`, `:starts_with`, `:ends_with`, `:matches`, `:not_matches`
 **Date predicates:** `:eq`, `:not_eq`, `:lt`, `:lteq`, `:gt`, `:gteq`
@@ -1280,6 +1296,7 @@ filter :category,     with: :select,      choices: -> { Category.pluck(:name) }
 filter :tags,         with: :select,      choices: %w[ruby rails js], multiple: true
 filter :category,     with: :association
 filter :author,       with: :association, class_name: User
+filter :labels,       with: :tags                          # no_fly_list context
 ```
 
 **Custom filter class:**
@@ -1317,7 +1334,7 @@ default_scope :published   # applied on initial load; "All" button clears it
 
 ### Conditional scopes (`condition:`)
 
-Like `condition:` on actions and fields — define a scope but only **render its button** when a proc is truthy. The scope itself (and its URL) stays live; `condition:` only controls UI visibility.
+Like `condition:` on actions and fields: define a scope but only **render its button** when a proc is truthy. The scope itself (and its URL) stays live; `condition:` only controls UI visibility.
 
 ```ruby
 scope :admin_only,   condition: -> { current_user.admin? }
@@ -1325,7 +1342,7 @@ scope :beta_feature, condition: -> { params[:beta] == "1" }
 scope :never_shown,  condition: -> { false }  # hides button but URL still works
 ```
 
-The proc is evaluated against the view context — `current_user`, `params`, `request`, `allowed_to?` are all available directly. There is no `object`/`record` (scopes have no single-record context).
+The proc is evaluated against the view context: `current_user`, `params`, `request`, `allowed_to?` are all available directly. There is no `object`/`record` (scopes have no single-record context).
 
 🚨 **`condition:` is NOT authorization.** A hidden scope button still has a live URL. Use `condition:` for UI relevance ("show admins only this tab"). Use the policy's `relation_scope` for "who can see these records at all".
 
@@ -1353,7 +1370,7 @@ default_sort { |scope| scope.order(featured: :desc, created_at: :desc) }
 
 ---
 
-# Part 5 — Actions: Custom and Bulk
+# Part 5: Actions: Custom and Bulk
 
 ## Action Types
 
@@ -1365,7 +1382,7 @@ default_sort { |scope| scope.order(featured: :desc, created_at: :desc) }
 | `bulk_action: true` | Selected records | Bulk operations |
 | `hidden: true` | **Nowhere** | Suppresses all four; route + policy stay live (drag gestures, custom JS) |
 
-🚨 **For interactive actions (`interaction:`), all four flags are inferred from the interaction's attributes — don't declare them manually:**
+🚨 **For interactive actions (`interaction:`), all four flags are inferred from the interaction's attributes, so don't declare them manually:**
 
 | Interaction declares | Inferred flags |
 |---|---|
@@ -1373,7 +1390,7 @@ default_sort { |scope| scope.order(featured: :desc, created_at: :desc) }
 | `attribute :resources` (plural) | `bulk_action` |
 | neither | `resource_action` |
 
-User-supplied flags override the inferred ones, but only **opt-out** makes sense for interactive actions — the interaction's `attribute :resource` / `attribute :resources` already fixes the action's semantic shape. Use opt-out to narrow where the button appears:
+User-supplied flags override the inferred ones, but only **opt-out** makes sense for interactive actions: the interaction's `attribute :resource` / `attribute :resources` already fixes the action's semantic shape. Use opt-out to narrow where the button appears:
 
 ```ruby
 # :resource interaction defaults to record_action + collection_record_action.
@@ -1402,11 +1419,11 @@ action :name,
   collection_record_action: true,
   bulk_action: true,
 
-  # Conditional visibility — display-only toggle, NOT authorization (see below).
+  # Conditional visibility: display-only toggle, NOT authorization (see below).
   # `-> { false }` keeps the route live but hides the button (e.g. API-only).
   condition: -> { params[:beta] == "1" },
 
-  # Never renders anywhere — route + policy stay live. For endpoints reached by
+  # Never renders anywhere: route + policy stay live. For endpoints reached by
   # a gesture rather than a button (see Hidden Actions below). NOT authorization.
   hidden: true,
 
@@ -1418,17 +1435,17 @@ action :name,
   confirmation: "Are you sure?",
   turbo_frame: "_top",
   route_options: {action: :foo},
-  modal: :slideover,                # :slideover / :centered — overrides definition's modal mode
-  size:  :lg,                       # :sm / :md / :lg / :xl / :auto / :full — overrides definition's modal size
+  modal: :slideover,                # :slideover / :centered, overrides definition's modal mode
+  size:  :lg,                       # :sm / :md / :lg / :xl / :auto / :full, overrides definition's modal size
 
-  # HTML attributes — deep-merged over the framework's, author wins on every key
+  # HTML attributes: deep-merged over the framework's, author wins on every key
   link:   {target: "_blank", rel: "noopener"},  # every <a> rendering: toolbar GET link, dropdown items (any method), bulk links, card show link
   button: {data: {analytics: "x"}}              # the button_to <form> wrapper (non-GET toolbar rendering), NOT the inner <button>
 ```
 
 ### HTML Attributes (`link:` / `button:`)
 
-Per-element attribute bags for an action's rendered control. `link:` lands on every anchor the action renders as (dropdown items are anchors even for non-GET actions); `button:` lands on the `button_to` `<form>` element. The author wins on collisions — including `class:` (replaces, no token append) and `turbo_frame`. Pass `data:` as a hash: a scalar `data:` replaces the framework's data wholesale, dropping `turbo_confirm`/`turbo_frame`.
+Per-element attribute bags for an action's rendered control. `link:` lands on every anchor the action renders as (dropdown items are anchors even for non-GET actions); `button:` lands on the `button_to` `<form>` element. The author wins on collisions, including `class:` (replaces, no token append) and `turbo_frame`. Pass `data:` as a hash: a scalar `data:` replaces the framework's data wholesale, dropping `turbo_confirm`/`turbo_frame`.
 
 ```ruby
 action :documentation,
@@ -1441,29 +1458,29 @@ Both bags round-trip through `with(...)`: `defined_actions[:edit].with(link: {ta
 
 ### Conditional Actions (`condition:`)
 
-Like `condition:` on inputs/displays/columns — define an action but render its **button** only when a runtime proc is truthy. The action and its route stay live either way; `condition:` only toggles the UI.
+Like `condition:` on inputs/displays/columns: define an action but render its **button** only when a runtime proc is truthy. The action and its route stay live either way; `condition:` only toggles the UI.
 
-Headline use case: **expose an action's endpoint without a button** — one you call from the API, a webhook, or another service. Hide it with an always-falsy condition; the route still works:
+Headline use case: **expose an action's endpoint without a button**, one you call from the API, a webhook, or another service. Hide it with an always-falsy condition; the route still works:
 
 ```ruby
 # Defined and callable (API / programmatic), but no button anywhere:
 action :sync_inventory, interaction: SyncInventoryInteraction, condition: -> { false }
 
-# Per-record display state — object is the row/shown record:
+# Per-record display state: object is the row/shown record:
 action :reopen, interaction: ReopenInteraction, condition: -> { object.closed? }
 
 # View/request-level toggle (feature flag, beta mode):
 action :preview, interaction: PreviewInteraction, condition: -> { params[:beta] == "1" }
 ```
 
-Inside the proc, `object`/`record` is the contextual record — the row/shown record for **record** and **collection-record** actions, **nil** for **resource** and **bulk** actions (guard with `object&.…` if shared). Every other call delegates to the **view context**: `current_user`, `current_parent`, `params`, `request`, `allowed_to?`, `resource_record!`, etc. `object` is evaluated per row in tables/grids, so per-record show/hide works there.
+Inside the proc, `object`/`record` is the contextual record: the row/shown record for **record** and **collection-record** actions, **nil** for **resource** and **bulk** actions (guard with `object&.…` if shared). Every other call delegates to the **view context**: `current_user`, `current_parent`, `params`, `request`, `allowed_to?`, `resource_record!`, etc. `object` is evaluated per row in tables/grids, so per-record show/hide works there.
 
-🚨 **`condition:` is NOT authorization — it only hides the button.** A hidden action still has a live route; anyone with the URL can trigger it. "Who may run this" belongs in the policy:
+🚨 **`condition:` is NOT authorization: it only hides the button.** A hidden action still has a live route; anyone with the URL can trigger it. "Who may run this" belongs in the policy:
 
 ```ruby
-# 🚫 WRONG — does not stop non-admins; the route is live.
+# 🚫 WRONG: does not stop non-admins; the route is live.
 action :wipe, interaction: WipeInteraction, condition: -> { current_user.admin? }
-# ✅ RIGHT — authorization in the policy, enforced regardless of condition:
+# ✅ RIGHT: authorization in the policy, enforced regardless of condition:
 def wipe? = current_user.admin?
 ```
 
@@ -1475,18 +1492,18 @@ The two compose: an action's button shows only when the policy permits **and** t
 action :reposition, hidden: true
 ```
 
-Renders in **no** toolbar, row dropdown, card, or bulk bar — regardless of visibility flags, policy, or `condition:`. Everything else stays live: the route, the policy predicate (`def reposition?`), and (for `interaction:` actions) the form + permitted-params machinery.
+Renders in **no** toolbar, row dropdown, card, or bulk bar, regardless of visibility flags, policy, or `condition:`. Everything else stays live: the route, the policy predicate (`def reposition?`), and (for `interaction:` actions) the form + permitted-params machinery.
 
-Use it for an endpoint reached by **something other than a button** — a drag gesture, a custom Stimulus controller. The framework uses it for exactly that: `position_on` expands to `action :reposition, hidden: true`, and the kanban drop endpoint is declared the same way.
+Use it for an endpoint reached by **something other than a button**: a drag gesture, a custom Stimulus controller. The framework uses it for exactly that: `position_on` expands to `action :reposition, hidden: true`, and the kanban drop endpoint is declared the same way.
 
 | | `hidden: true` | `condition: -> { false }` |
 |---|---|---|
 | Decided | class-load, once | render time, per row/request |
 | Says | "never a button" | "a button, just not right now" |
 
-🚨 **`hidden:` is a display gate, NOT an authorization boundary** — same trap as `condition:`. The route is live; authorization belongs in the policy.
+🚨 **`hidden:` is a display gate, NOT an authorization boundary**: same trap as `condition:`. The route is live; authorization belongs in the policy.
 
-`Action#with(...)` — actions are frozen value objects; clone with overrides:
+`Action#with(...)`: actions are frozen value objects; clone with overrides:
 
 ```ruby
 def customize_actions
@@ -1534,7 +1551,7 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-⚠️ **An interaction is the button, not the operation.** It's a presentation object — it can only be built with a `view_context`, so anything reachable only through one is reachable only from a Plutonium page. Logic may *start* in `execute` (a one-off with a single caller is fine; don't pre-extract). The **second caller** — a job, an API controller, a rake task, the console — is the trigger to move it onto the **model**, in domain language (`publish!`, `archive!`, `register!`). Not a service layer. Full rule + the validation split: [[plutonium-behavior]] › Part 3 › Where the logic goes.
+⚠️ **An interaction is the button, not the operation.** It's a presentation object: it can only be built with a `view_context`, so anything reachable only through one is reachable only from a Plutonium page. Logic may *start* in `execute` (a one-off with a single caller is fine; don't pre-extract). The **second caller** (a job, an API controller, a rake task, the console) is the trigger to move it onto the **model**, in domain language (`publish!`, `archive!`, `register!`). Not a service layer. Full rule + the validation split: [[plutonium-behavior]] › Part 3 › Where the logic goes.
 
 ### Single-record interaction
 
@@ -1574,7 +1591,7 @@ class Company::InviteUserInteraction < Plutonium::Resource::Interaction
   validates :role,  presence: true, inclusion: {in: %w[admin member viewer]}
 
   def execute
-    # Company#invite! creates the row AND sends the mail — a seat-provisioning
+    # Company#invite! creates the row AND sends the mail, a seat-provisioning
     # job needs both, and has no view_context to build an interaction with.
     resource.invite!(email: email, role: role, by: current_user)
     succeed(resource).with_message("Invitation sent to #{email}.")
@@ -1604,7 +1621,7 @@ end
 action :bulk_archive, interaction: BulkArchiveInteraction
 # bulk_action: true inferred from `attribute :resources`
 
-# Policy — checked per record; fails the request if ANY record is unauthorized
+# Policy: checked per record; fails the request if ANY record is unauthorized
 class PostPolicy < ResourcePolicy
   def bulk_archive? = create?
 end
@@ -1678,13 +1695,13 @@ end
 
 ## Immediate vs Form
 
-- **Immediate** — interaction has only `:resource` (or `:resources`) and no other inputs. Shows an auto-generated browser confirmation (`"#{label}?"`, e.g. `"Archive?"`) on click, then runs. Pass `confirmation: "Custom message"` to override, or `confirmation: false` to skip.
-- **Form** — interaction declares extra `attribute`/`input` beyond `:resource`/`:resources`. Renders a modal form first; no auto-confirmation (the form itself is the confirmation step).
+- **Immediate**: interaction has only `:resource` (or `:resources`) and no other inputs. Shows an auto-generated browser confirmation (`"#{label}?"`, e.g. `"Archive?"`) on click, then runs. Pass `confirmation: "Custom message"` to override, or `confirmation: false` to skip.
+- **Form**: interaction declares extra `attribute`/`input` beyond `:resource`/`:resources`. Renders a modal form first; no auto-confirmation (the form itself is the confirmation step).
 
 ## CSV Export (built-in)
 
 Every resource has a streamed CSV export, **disabled by default**. It is not declared
-with `action :export_csv` — it's a policy-gated capability with its own split button.
+with `action :export_csv`: it's a policy-gated capability with its own split button.
 The route (`GET /<resources>/export_csv`) is auto-mounted; the button appears on the
 index page once the policy permits it. Enable it by overriding one policy method:
 
@@ -1695,9 +1712,9 @@ end
 ```
 
 **Two exports** (split button in the index toolbar, after Filter):
-- **Export** (primary) — the current view: selected scope + filters + search (the
+- **Export** (primary): the current view: selected scope + filters + search (the
   index's `?q`), all matching rows (not just the visible page). File: `posts_<date>.csv`.
-- **Export all** (dropdown) — the entire authorized scope, ignoring scope/filters/
+- **Export all** (dropdown): the entire authorized scope, ignoring scope/filters/
   search (`?all=1`). File: `posts_all_<date>.csv`.
 
 Both stream via `find_each` (memory-safe on large tables; primary-key order, so the
@@ -1710,7 +1727,7 @@ file does not preserve the index sort).
 def permitted_attributes_for_export = [:title, :author, :total, :created_at]
 ```
 
-- **Per-field output** — customize a cell's value and header in the definition with
+- **Per-field output**: customize a cell's value and header in the definition with
   the `export` DSL (parallels `display`/`column`):
 
 ```ruby
@@ -1723,7 +1740,7 @@ end
 - **Without** an `export` block a column is read off the record: scalars as-is,
   associations as their `display_name_of` label (e.g. `User #5`, not `#<User:…>`). A
   computed/virtual column with no real method **needs** an `export` block (a `label:`-only
-  `export` doesn't supply a value) — otherwise the cell renders `<<invalid column>>`.
+  `export` doesn't supply a value); otherwise the cell renders `<<invalid column>>`.
 - **CSV/formula injection** is neutralized automatically (cells starting with `= + - @` or
   tab/CR get a leading `'`).
 
@@ -1734,7 +1751,7 @@ The button opens in a new tab (so the streamed download bypasses Turbo). Full re
 
 ## Related Skills
 
-- [[plutonium-behavior]] — controllers, policies (`permitted_attributes_for_*`, action methods), interactions
-- [[plutonium-tenancy]] — `associated_with`, `relation_scope`, nested resources
-- [[plutonium-ui]] — custom Phlex pages, forms, displays, tables
-- [[plutonium-testing]] — testing resources, definitions, policies, interactions
+- [[plutonium-behavior]]: controllers, policies (`permitted_attributes_for_*`, action methods), interactions
+- [[plutonium-tenancy]]: `associated_with`, `relation_scope`, nested resources
+- [[plutonium-ui]]: custom Phlex pages, forms, displays, tables
+- [[plutonium-testing]]: testing resources, definitions, policies, interactions