plutonium 0.62.2 → 0.64.0

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

@@ -12,7 +12,7 @@ For field-level rendering on cards (card_fields slots), see [[plutonium-resource
 ## 🚨 Critical (read first)
 
 - **`kanban do…end` in the Definition auto-enables `:kanban`** in `defined_index_views` — exactly like `grid_fields` enables `:grid`. You do not need to call `index_views :kanban` separately unless you want to remove the table view.
-- **The model needs `include Plutonium::Positioning`** (and a decimal `position` column + `positioned_on` call) for drag ordering to work. Without it, cards render unordered and moves raise an error. Use `position_on false` to explicitly opt out.
+- **The model needs `include Plutonium::Positioning::Model`** (and a decimal `position` column + `positioned_on` call) for drag ordering to work. Without it, cards render unordered and moves raise an error. Use `position_on false` to explicitly opt out.
 - **Static column actions are auto-registered** as interactive resource actions at class-load time. Dynamic boards (`columns do…end`) cannot introspect their columns at load time — declare any column-action interactions separately with top-level `action` calls.
 - **Moves bypass `permitted_attributes_for_update`** — the `on_enter` callback runs with full model access. Gate the move itself with `kanban_move?` in the policy.
 - **Quick-add (`add: true`) only appears when `create?` is true** in the policy.
@@ -26,7 +26,7 @@ For field-level rendering on cards (card_fields slots), see [[plutonium-resource
 
 ```ruby
 class Task < ApplicationRecord
-  include Plutonium::Positioning
+  include Plutonium::Positioning::Model
 
   # position_on :position (default attr) scoped to the grouping column
   positioned_on :position, scope: :status
@@ -103,9 +103,23 @@ Overrides the grid card layout for kanban cards. Uses the same slot keys as `gri
 card_fields header: :title, meta: [:status, :priority], footer: :due_at
 ```
 
+Every slot is optional and omitting it drops that line — **except `footer`, which
+falls back to `:created_at`**. To render no footer at all, opt out explicitly:
+
+```ruby
+card_fields header: :title, meta: [:status], footer: false
+```
+
+Omitting `footer:` is the common cause of a card ending in a stray `—`: the
+fallback lands on `:created_at`, and if that isn't in the policy's
+`permitted_attributes_for_index` the value resolves to nil and renders as the
+blank placeholder. Either permit `created_at`, point `footer:` at a permitted
+field, or pass `footer: false`. (A *declared* slot that's merely blank still
+shows `—` by design, so cards keep an even height.)
+
 ### `position_on` modes
 
-- **Mode A (default)** — delegates to `record.reposition!(prev_record:, next_record:)` from `Plutonium::Positioning`. Requires the model concern and a decimal column.
+- **Mode A (default)** — delegates to `record.reposition!(prev_record:, next_record:)` from `Plutonium::Positioning::Model`. Requires the model concern and a decimal column.
 - **Mode B (block)** — you write the persistence. Plutonium still orders by the attribute; the block only persists the new value. Block receives a `Plutonium::Kanban::Positioning::Move` (fields: `record`, `column`, `prev`, `next`, `index`).
 - **Mode C (`false`)** — no ordering, no repositioning. `on_enter` still fires.
 

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, index views, 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
@@ -484,8 +484,8 @@ end
 
 # Portal override (per-portal customization)
 class AdminPortal::PostDefinition < ::PostDefinition
-  input :internal_notes, as: :text
   scope :pending_review
+  input :internal_notes, hint: "Not shown to the author"
 end
 ```
 
@@ -602,6 +602,30 @@ field :debug_info, condition: -> { Rails.env.development? }
 
 Use `condition` for UI state; use the policy for authorization.
 
+## 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**:
+
+```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.
+
+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:
+
+```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
+```
+
+It cannot take a `form` argument the way an option does: for a `column`/`display`, a step, or an action there is no form.
+
 ## Dynamic Forms (`pre_submit`)
 
 A `pre_submit: true` field triggers a server re-render on change, re-evaluating `condition:` procs. Use for cascading or context-dependent forms.
@@ -660,14 +684,14 @@ input :birth_date do |f|
 end
 ```
 
-**`phlexi_tag` for declarative custom display.** The `with:` option takes either a Phlex component class, or a proc whose body is **rendered inside a Phlex context** — so HTML tags (`span`, `div`, `a`, …) and Tailwind classes are first-class. The proc receives `(value, attrs)` where `value` is the field value and `attrs` are wrapper attributes.
+**`phlexi_render` for declarative custom display.** The `with:` option takes either a Phlex component class, or a proc whose body is **rendered inside a Phlex context** — so HTML tags (`span`, `div`, `a`, …) and Tailwind classes are first-class. The proc receives `(value, attrs)` where `value` is the field value and `attrs` are wrapper attributes.
 
 ```ruby
 # Component class — preferred for anything reusable
-display :status, as: :phlexi_tag, with: StatusBadgeComponent
+display :status, as: :phlexi_render, with: StatusBadgeComponent
 
 # Inline Phlex proc — `span` here is a Phlex tag method, not Ruby/Rails
-display :priority, as: :phlexi_tag, with: ->(value, attrs) {
+display :priority, as: :phlexi_render, with: ->(value, attrs) {
   case value
   when 'high'   then span(class: "badge badge-danger")  { "High" }
   when 'medium' then span(class: "badge badge-warning") { "Medium" }
@@ -678,13 +702,21 @@ display :priority, as: :phlexi_tag, with: ->(value, attrs) {
 
 See [[plutonium-ui]] for writing custom Phlex components.
 
-**Custom component classes** (Phlex components — see [[plutonium-ui]]):
+**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:
+
+```ruby
+display :card do |field|
+  PostCardComponent.new(post: field.object)
+end
+```
+
 ## Column Options
 
 ```ruby
@@ -883,7 +915,7 @@ class PostDefinition < ResourceDefinition
   form_layout do
     section :identity, :name, :email, label: "Identity", description: "Who this is"
     section :address, :street, :city,
-      collapsible: true, collapsed: -> { object.persisted? }, columns: 2,
+      collapsible: true, collapsed: ->(form) { form.object.persisted? }, columns: 2,
       condition: -> { object.requires_address? }   # hide the whole section as a unit
     ungrouped label: "Other"                        # bucket for unlisted fields; position = where it renders
   end
@@ -891,13 +923,55 @@ 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 in the form context (`object`, `current_user`, `params`, helpers).
+- **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. This checks *field presence only*; per-field `condition:` runs later, so to hide a whole section by state, gate it with the **section's own `condition:`**, not by hiding every field inside it.
 - **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 sections dropped) — applied to the show page's fields instead of the form's.
+
+```ruby
+class PostDefinition < ResourceDefinition
+  display_layout do
+    section :profile, :name, :author, label: "Profile", description: "Identity and owner"
+    section :presentation, :cover, :body, collapsible: true
+    ungrouped label: "Other details"
+  end
+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.
+
+## 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.
+
+```ruby
+Plutonium.configure { |c| c.default_page_width = :md }   # global default (:md)
+
+class PostDefinition < ResourceDefinition
+  page_width    :lg      # form AND show page
+  display_width :full    # ...but the show page opts out
+  form_width    :sm      # ...and the form goes narrow
+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).
+- **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`).
+- **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.
+
 ## Metadata Panel (show page)
 
 Declares fields rendered in the show page's right-side aside as label/value rows.
@@ -908,8 +982,10 @@ 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.
+- **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.
 
 Use for chrome (timestamps, ownership, system flags), keeping the main card focused on substance.
 
@@ -926,7 +1002,7 @@ class UserDefinition < ResourceDefinition
     subheader: :email,
     body:      :bio,
     meta:      [:role, :status],  # rendered as small pills
-    footer:    :last_seen_at      # falls back to :created_at
+    footer:    :last_seen_at      # falls back to :created_at; `false` to omit
   )
 
   default_index_view :grid        # optional — initial view when no cookie
@@ -949,6 +1025,123 @@ 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:
+
+```ruby
+# 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
+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.
+class TaskDefinition < ResourceDefinition
+  position_on
+end
+
+# Existing rows need positions:
+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.
+
+### `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 :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 |
+
+**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 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.
+
+### 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`.
+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.
+
+```ruby
+# 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
+  acts_as_list scope: [:status]
+end
+
+class TaskDefinition < ResourceDefinition
+  position_on :position do |move|
+    record = move.record
+
+    target =
+      if move.prev
+        # 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
+        # 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
+        1 # the only row in the list
+      end
+
+    record.insert_at(target)
+  end
+end
+```
+
+`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
+
+```ruby
+sort <attr>                      # load-bearing: the only way back to position order
+default_sort <attr>, :asc        # ⚠ ONLY when default_sort is still the framework default
+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.
+
+### 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.
+- 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/positioning.md`. Kanban specifics: `docs/reference/kanban/positioning.md`.
+
+---
+
 # Part 4 — Query: Search, Filters, Scopes, Sorting
 
 ```ruby
@@ -1090,6 +1283,7 @@ default_sort { |scope| scope.order(featured: :desc, created_at: :desc) }
 | `record_action: true` | Show page | Edit, Delete, Archive |
 | `collection_record_action: true` | Table rows | Quick per-row actions |
 | `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:**
 
@@ -1132,6 +1326,10 @@ action :name,
   # `-> { 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
+  # a gesture rather than a button (see Hidden Actions below). NOT authorization.
+  hidden: true,
+
   # Grouping
   category: :primary,               # :primary, :secondary, :danger
   position: 50,
@@ -1141,9 +1339,26 @@ action :name,
   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
+  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
+  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`.
+
+```ruby
+action :documentation,
+  route_options: {url: "https://docs.example.com"},
+  resource_action: true,
+  link: {target: "_blank", rel: "noopener noreferrer"}   # open in a new tab
+```
+
+Both bags round-trip through `with(...)`: `defined_actions[:edit].with(link: {target: "_blank"})`.
+
 ### 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.
@@ -1174,6 +1389,23 @@ def wipe? = current_user.admin?
 
 The two compose: an action's button shows only when the policy permits **and** the condition is truthy; execution is gated by the policy alone. Use `object` in `condition:` for per-record *display*; use the policy for per-record *authorization*.
 
+### Hidden Actions (`hidden: true`)
+
+```ruby
+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.
+
+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.
+
 `Action#with(...)` — actions are frozen value objects; clone with overrides:
 
 ```ruby
@@ -1222,6 +1454,8 @@ 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.
+
 ### Single-record interaction
 
 ```ruby
@@ -1260,7 +1494,9 @@ class Company::InviteUserInteraction < Plutonium::Resource::Interaction
   validates :role,  presence: true, inclusion: {in: %w[admin member viewer]}
 
   def execute
-    UserInvite.create!(company: resource, email: email, role: role, invited_by: current_user)
+    # 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}.")
   rescue ActiveRecord::RecordInvalid => e
     failed(e.record.errors)
@@ -1296,6 +1532,17 @@ end
 
 The UI only shows bulk action buttons that ALL selected records support. Records are fetched via `current_authorized_scope`.
 
+**Bulk over more than a screenful runs in the request and will time out.** Swap `execute` for `async` and the same interaction dispatches a background run instead, with its declaration and policy unchanged:
+
+```ruby
+async do
+  on_failure :continue   # :halt (default) | :continue | :transactional
+  def perform_on(record) = record.archived!
+end
+```
+
+The block is the run's class body, not `execute`: it runs later in a job with no controller, so its inputs arrive through `options`. Load [[plutonium-async-interactions]] before building one.
+
 ### Resource action (no record)
 
 ```ruby

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

@@ -323,26 +323,55 @@ Plutonium prefixes nested routes with `nested_` to avoid conflicts with the top-
 
 For `has_one`: index redirects to show (or new if no record exists); only one record per parent.
 
+### Choosing which associations get routes
+
+Every routable association gets a nested route unless the registration narrows it:
+
+```ruby
+register_resource ::Company, associations: %i[properties company_profile]
+```
+
+`associations: []` draws none. A name that is not a `has_many`/`has_one`, or whose
+child is not registered in that portal, raises at boot.
+
+`config.nested_association_routes = :declared` (default `:detected`) makes a resource
+that names none get none. The mode only changes what silence means; `associations:`
+behaves the same either way, and top-level routes are unaffected.
+
+**Before turning `:declared` on:** it is global, so every resource naming nothing
+loses its nested routes, and a policy's `permitted_associations` panel links to the
+nested route — permit an association there without declaring it here and the panel
+points nowhere.
+
 ## Automatic behavior in nested routes
 
 When the controller is hit through a nested route:
 
 1. **Resolves the parent** via `current_parent`, authorized for `:read?`.
 2. **Scopes queries** via parent association (e.g. `parent.properties` for `has_many`, `where(foreign_key => parent.id)` for `has_one`).
-3. **Assigns parent** on create (injected into `resource_params`).
+3. **Assigns parent** on create (injected into `resource_params`). The record is built
+   on the parent's association (`parent.properties.new`), so a scoped association
+   contributes its equality conditions as defaults.
 4. **Hides parent field** in forms (already determined by URL).
 
 You don't need to add hidden parent fields in forms or filter queries manually.
 
+Expose a scoped association as a nested route only when its scope is equality-based
+(`-> { where(published: true) }`). Rails derives create attributes from equality
+conditions alone, so `-> { where("expires_at > ?", Time.current) }` creates records
+that its own index, which honours the scope, will not list.
+
 ## Controller methods
 
 ```ruby
 current_parent              # Parent record
+current_parent_class        # Company
 current_nested_association  # :properties
-parent_route_param          # :company_id
 parent_input_param          # :company
 ```
 
+The parent class and association are read from the **route** (each nested route carries its registration key), not inferred from the URL — which is why a `singular: true` parent works as a parent despite contributing no id segment. There is no `parent_route_param`.
+
 ## Parent vs entity scoping
 
 When a parent is present, **parent scoping wins**: `default_relation_scope` scopes via the parent association, not `entity_scope`. The parent was already authorized and entity-scoped during its own authorization — double-scoping isn't needed.
@@ -613,7 +642,7 @@ configure do
   login_redirect "/welcome"
 
   after_login do
-    session[:after_welcome_redirect] = session.delete(:login_redirect)
+    session[:after_welcome_redirect] = session.delete(login_redirect_session_key)
   end
 end
 ```