plutonium 0.60.5 → 0.62.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 004004c1342357f78b64e9ebc65c138438f3f84bad76c4f4af5c6875d7200821
-  data.tar.gz: 2e4fa5789c30c0bb39227b7ce9577f95eaf6166d116ec9670f23735a269c9a9d
+  metadata.gz: 62c3179e6fc69beaae9e39a5892a478bd41c546fcf0fb580dea6a4aa9680e296
+  data.tar.gz: 94c2ce8570a323536961196170f8cb7187efe724834485edfd210a783147cbe8
 SHA512:
-  metadata.gz: 36909e8c72456b74db2d941331b8bfb54dba04925ab53365bf188978dad45a9d699aabb6c16892951dfe5000aa40cc97fd1df2102e8e07026456e65de0af2b3d
-  data.tar.gz: 1962eab914ff635d489a75f9bb7c06a69c0ac382128f79e6a5caeac368010d9af84b834a568e61597b1279297a7438ca79408f32f2116a09064b2f8b3a31a0dd
+  metadata.gz: 0b9dc172a16b74c0f313606cefe964a661842aacd63c21df3ed3cb9ca20179439d2f302b53658305a375ee2b752aacf056244eb0a6875e2a31e20276b8055a2c
+  data.tar.gz: e1f47b1429392d82253f27e8268309e129d33e5d62716b04c669c13e24cc4e3b34d74728d154189c116124319c7155911e49000be008ea72a2bbdd64fecc3dbd

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

@@ -18,8 +18,22 @@ Entry point for all Plutonium work. Does three things:
 - **For targeted edits** — use the **router table** to jump to the right skill.
 - **For anything touching tenant scoping** — load `plutonium-tenancy`. Don't reach for `where(organization: ...)` in a policy; fix the model instead.
 - **Unattended execution:** always pass `--dest=`, `--force` (when re-running meta-generators), `--auth=`, `--skip-bundle`, `--quiet` so generators don't block on prompts. See [Unattended execution](#unattended-execution).
+- **Inspect before you act.** Every targeted skill now opens with a CHECK gate — read the relevant files yourself before scaffolding or editing. Don't ask the user to describe their app when you can read it.
 
-## The 8 skills
+## ✅ Orient before you route (CHECK — read the app, don't assume)
+
+A one-line request rarely says whether this is a new app, a half-built one, or a multi-tenant one — and those change which path you take. Spend 30 seconds reading the app **before** loading a bundle or running anything:
+
+| Read | Tells you |
+|---|---|
+| `git log --oneline \| head`; is there a populated `Gemfile` + `app/`? | Greenfield vs existing → install path (`plutonium-app`: `base.rb`, **never** `plutonium.rb` on an existing app) |
+| grep `Gemfile` for `plutonium`; `ls config/packages.rb` | Already installed? → skip install |
+| `ls packages/` | What portals / feature packages already exist |
+| Does any model `belongs_to` an org/team/tenant? | Multi-tenant → load `plutonium-tenancy` **before** declaring scoping |
+
+This is the global "look before you leap"; each targeted skill carries its own ASK/CHECK gate for the specifics. **Never run an installer or scaffold from a one-line request without first reading what's already there.**
+
+## The skills
 
 | Skill | Covers |
 |---|---|
@@ -27,9 +41,11 @@ Entry point for all Plutonium work. Does three things:
 | **[[plutonium-resource]]** | The resource itself — `pu:res:scaffold`, field types, model layer (`Plutonium::Resource::Record`, `has_cents`, SGID, routing), definition layer (fields/inputs/displays/columns, search/filters/scopes/sorting, custom actions, bulk actions, index views, page customization) |
 | **[[plutonium-behavior]]** | Controllers (hooks, key methods, presentation), policies (action methods, `permitted_attributes_for_*`, `permitted_associations`), interactions (structure, outcomes, chaining, URL generation) |
 | **[[plutonium-ui]]** | Page classes, forms, displays, tables, custom Phlex components, layouts, modals & tabs, Tailwind config, Stimulus, design tokens, `.pu-*` classes, Phlexi themes |
+| **[[plutonium-kanban]]** | `kanban do…end` DSL in a Definition — columns, `card_fields`, `position_on`, `realtime`, column actions, `kanban_move?` policy, quick-add, static vs dynamic boards |
 | **[[plutonium-auth]]** | Rodauth install, account types (basic / admin / SaaS), profile resource, security section |
 | **[[plutonium-tenancy]]** | Entity scoping (`associated_with`, `default_relation_scope`, three model shapes), nested resources, invites |
 | **[[plutonium-testing]]** | `pu:test:install`, `pu:test:scaffold`, `ResourceCrud`/`ResourcePolicy`/`ResourceDefinition`/`ResourceModel`/`NestedResource`/`PortalAccess`/`ResourceInteraction`, `AuthHelpers` |
+| **[[plutonium-wizard]]** | Multi-step flows — the wizard DSL (`step`/`review`/`using:`/`condition:`, per-step `on_submit`/`persist`/`on_rollback`, `execute`), anchoring & resume, one-time wizards + gate, registration (`wizard` macro + `register_wizard`), storage/config + SweepJob |
 
 ## Greenfield bootstrap bundle
 
@@ -61,10 +77,12 @@ Add when relevant:
 | Scope a model to a tenant, write `associated_with`, set portal entity strategy | **[[plutonium-tenancy]]** |
 | Configure parent/child nested routes, custom parent resolution | **[[plutonium-tenancy]]** |
 | Set up user invitations or entity membership | **[[plutonium-tenancy]]** |
+| Build or customize a kanban board view — `kanban do…end`, columns, `card_fields`, `position_on`, `realtime`, column actions, `kanban_move?` policy | **[[plutonium-kanban]]** |
 | Build a custom page (override `ShowPage`/`IndexPage`/`NewPage`/`EditPage`), custom form, custom display, custom table, custom Phlex component | **[[plutonium-ui]]** |
 | Configure Tailwind, register Stimulus controllers, edit design tokens, theme forms/displays/tables, write a custom layout | **[[plutonium-ui]]** |
 | Install Rodauth, set up accounts, configure login flow, add the profile resource | **[[plutonium-auth]]** |
 | Write tests for a resource, run `pu:test:scaffold`, include `Plutonium::Testing::*` concerns | **[[plutonium-testing]]** |
+| Build a multi-step flow — onboarding, checkout, branching create — register a `wizard` / `register_wizard`, gate a one-time wizard | **[[plutonium-wizard]]** |
 
 ## Resource architecture at a glance
 

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

@@ -21,6 +21,47 @@ For the resources themselves (model + definition + scaffold options), see [[plut
 
 ---
 
+## 🛑 Before you install or scaffold structure: confirm the shape (ASK — don't infer)
+
+"Set up Plutonium" / "make an admin area" / "create a billing package" each hide a high-blast-radius decision. Get one wrong and you **clobber a year of git history**, build the wrong kind of package, or ship a portal nobody can log into. Resolve each — confirming by inspection (next section), not assumption:
+
+1. **Fresh app or existing one?** Existing ⇒ `bundle add plutonium` + `pu:core:install` (the `base.rb` path). **NEVER the `plutonium.rb` fresh-app template on an existing app** — it re-bootstraps (dotenv/annotate/solid_*/assets) and drops "initial commit" commits that clobber history. This is the single most dangerous mistake in this skill — confirm it's greenfield *before* reaching for `plutonium.rb`.
+2. **Feature package or portal package?** Business logic (models/policies/definitions/interactions) ⇒ `pu:pkg:package` (feature, no UI). A web surface (controllers/views/routes/auth) ⇒ `pu:pkg:portal`. Hard split — "billing" is a *feature*; "admin area" is a *portal*. A feature package is invisible until its resources are `pu:res:conn`'d into a portal.
+3. **Auth per portal.** `--auth=<account>` / `--public` / `--byo` / `--scope=<Entity>` (multi-tenant). Unguessable from "admin area" — decide, don't default silently.
+4. **Don't stop half-wired.** A resource reaches the browser only after: scaffold → migrate → `pu:res:conn --dest=portal` → portal engine `mount`ed in `config/routes.rb` → registered (conn does the last). Name the whole chain before you start.
+
+**Never ship a guessed schema, portal name, or auth flag as applied commands** — read them off the app first; fall back to `AskUserQuestion` only for genuine product choices (separate staff accounts vs shared, which payment backend). The decisions compound: *existing app ⇒ base.rb path*; *feature package ⇒ needs a portal to be visible*; *new portal ⇒ pick auth + mount it*.
+
+## ✅ Before you run a generator: verify the ground truth (CHECK — read it, don't ask for it)
+
+You have file access — **inspect**; don't ask the user to describe their app.
+
+| Check | How | Why it matters |
+|---|---|---|
+| Greenfield vs existing | `git log --oneline \| head`; is there a populated `Gemfile`/`app/`? | An existing app must use the `base.rb` path — **never** `plutonium.rb` |
+| Plutonium already installed | grep `Gemfile` for `plutonium`; `ls config/packages.rb app/controllers/resource_controller.rb` | Avoid re-installing / double bootstrap |
+| Package/portal already exists | `ls packages/<name>` | Don't duplicate — connect to / extend the existing one |
+| Existing auth | grep `Gemfile`/`app/models` for `rodauth`/`devise`/`has_secure_password` | Drives `--auth` vs `--byo` |
+| Portal engine mounted | grep `config/routes.rb` for `mount <Portal>::Engine` | An unmounted portal 404s |
+| Resource registered | grep the portal's `config/routes.rb` for `register_resource ::<X>` | Unregistered ⇒ no URLs (`resource_url_for` fails) |
+| Migrations applied | `rails db:migrate:status` before `pu:res:conn` | `conn` seeds the policy from columns |
+
+Inspect with your own tools **before** running any generator.
+
+## 🛠 Use the generator — pick the right install path
+
+Never hand-write base controllers, engine files, layouts, or route registration. Pass `--dest`/`--auth`/`--force`/`--skip-bundle` for unattended runs.
+
+| Task | Generator | Verify first |
+|---|---|---|
+| Install — **existing** app | `bundle add plutonium` + `pu:core:install` | It's an existing app (use `base.rb`, **not** `plutonium.rb`) |
+| Install — **fresh** app | `rails new … -m …/plutonium.rb` | Brand-new app **only** |
+| Feature package | `pu:pkg:package <name>` | Not already present |
+| Portal package | `pu:pkg:portal <name> --auth=…/--public/--byo/--scope=…` | Auth strategy decided; then `mount` the engine by hand |
+| Connect a resource | `pu:res:conn <Res> --dest=portal` | Migrated; target portal exists |
+
+---
+
 # Part 1 — Installation
 
 ## Fresh Rails app (recommended)

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

@@ -21,6 +21,46 @@ For multi-tenant invitations and membership, see [[plutonium-tenancy]] › Invit
 
 ---
 
+## 🛑 Before you set up auth: confirm the shape (ASK — don't infer)
+
+"Set up login" hides the one decision that determines everything: **is this multi-tenant SaaS or a single auth surface?** Pick wrong and you either hand-assemble what a meta-generator does in one shot, or scaffold a SaaS spine an app doesn't need. Resolve each — confirming by inspection (next section):
+
+1. **Single auth or multi-tenant SaaS?** "Each user belongs to / manages an org/team" ⇒ SaaS ⇒ **`pu:saas:setup`** (the meta-generator: user + entity + membership + portal + profile + welcome + invites in one). A plain login with no tenant ⇒ `pu:rodauth:install` + `pu:rodauth:account`.
+2. **Account type.** Basic user, **hardened admin** (`pu:rodauth:admin` — 2FA/lockout/audit, no public signup), or **API** (`--api_only --jwt`)? They're different generators.
+3. **Public signup allowed?** Default yes for `account`; admin accounts are invite-only.
+4. **Profile / account-settings page?** Needs `pu:profile:install` **and** `pu:profile:conn` (without conn there's no `/profile` route).
+5. **Roles.** Index 0 is most privileged (`owner`/`super_admin`); invites default new members to `roles[1]`. `pu:saas:setup` prepends `owner` — don't list it.
+
+**Never ship a guessed account-type, model name, or `--roles` as applied commands.** Read them off the app first; fall back to `AskUserQuestion` only for product choices (separate staff accounts vs shared, is signup open).
+
+## ✅ Before you run a generator: verify the ground truth (CHECK — read it, don't ask for it)
+
+You have file access — **inspect**; don't ask the user to describe their app.
+
+| Check | How | Why it matters |
+|---|---|---|
+| Rodauth already installed | `ls app/rodauth/rodauth_app.rb`; grep `Gemfile` for `rodauth` | Re-running `pu:rodauth:install` clobbers config |
+| Existing account models | grep `app/models` for `Rodauth::Rails.model` | Which account type exists / don't duplicate |
+| SaaS spine already run | `ls` for the entity portal + membership model | **`pu:saas:setup` chains 4 generators — don't re-run them separately** |
+| Profile wired | grep the user model for `has_one :profile` + `after_create`; is `profile_url` defined? | Else `current_user.profile` is nil / no route (`pu:profile:conn` missing) |
+| Role ordering | Read the membership `enum :role` | Index 0 = most privileged; invites default to `roles[1]` |
+
+Inspect with your own tools **before** running any generator.
+
+## 🛠 Use the generator — never hand-write Rodauth
+
+Never hand-write Rodauth plugin files, account models, or profile resources.
+
+| Task | Generator | Verify first |
+|---|---|---|
+| Multi-tenant SaaS spine | `pu:saas:setup --user U --entity E --roles=…` | Not already run (don't re-run the 4 sub-generators it chains) |
+| Rodauth base | `pu:rodauth:install` | Not already installed |
+| Basic account | `pu:rodauth:account NAME --defaults` | Rodauth installed |
+| Hardened admin | `pu:rodauth:admin NAME --roles=…` | Rodauth installed |
+| Profile page | `pu:profile:install …` + `pu:profile:conn --dest=portal` | Migrated; portal exists |
+
+---
+
 ## Install
 
 ```bash

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

@@ -25,6 +25,52 @@ For tenant-scoped `relation_scope` and entity scoping, load [[plutonium-tenancy]
 
 ---
 
+## 🛑 Before you write behavior: place it in the right layer (ASK — don't infer)
+
+"Make X happen" doesn't say **where** X lives. Put it in the wrong layer and you get authorization that doesn't authorize, a 500 on the happy path, or a CRUD override that breaks params/auth. First place the requirement, then confirm names against the real code (next section):
+
+| The requirement (in plain words) | Goes in | **NOT** in |
+|---|---|---|
+| "only \<role/owner\> may do X" — *who is allowed* | **Policy** `def x?` | a `condition:` proc — that only hides the button; the route stays live and callable |
+| "doing X changes state / sends mail / charges a card" — *the work* | **Interaction** `execute`, registered as an action | a hand-written controller action; an override of `create`/`update` |
+| "after create/update go to Y" · "munge a param" · "reshape the index query" | **Controller hook** (`redirect_url_after_submit`, `resource_params`, `filtered_resource_collection`) | overriding `create`/`update`/`index` |
+| "which fields are visible / editable" | **Policy** `permitted_attributes_for_*` | the definition — that only controls *how* a field renders |
+
+Then resolve the specifics:
+
+1. **A custom action needs BOTH:** an interaction (the work) **and** a policy `def <action>?` (the authorization). Miss the policy method ⇒ the action silently returns `false` (dead button). Put the role check in `condition:` ⇒ it isn't enforced — a direct POST still runs.
+2. **`create?`/`read?` default to `false`** — override explicitly; derived methods (`update?`/`show?`/…) inherit.
+3. **Any `create!`/`update!`/`save!` in `execute`** ⇒ rescue `ActiveRecord::RecordInvalid` → `failed(e.record.errors)`. Not auto-rescued — otherwise a validation failure 500s.
+4. **`has_cents`** ⇒ permit `:price`, never `:price_cents`.
+5. **New vs editing** — never re-scaffold a controller/policy/interaction that's been customized.
+
+**Never ship a guessed role method, column, enum value, or association as applied code.** `user.finance?`, `record.status_approved?`, `expense.submitted_by` either exist in the app or they don't — confirm them before writing, don't assume. Fall back to `AskUserQuestion` only for genuine product choices (what the rule *should* be), never for facts you can read.
+
+## ✅ Before you edit: verify the ground truth (CHECK — read it, don't ask for it)
+
+You have file access — **inspect**; don't ask the user to describe their own app.
+
+| Check | How | Why it matters |
+|---|---|---|
+| File already customized | Read `app/policies/<x>_policy.rb`, the controller, `app/interactions/*` | Edit incrementally — re-scaffolding clobbers customizations |
+| The role/method you authorize on exists | grep the user model for `def finance?` / `enum :role` / `has_role?` | `user.finance?` 500s (or is silently `false`) if absent |
+| The columns/enum your interaction writes | Read the model + `db/schema.rb` for the enum value, `approved_by`/`approved_at`, the submitter assoc | `update!(status: :approved)` raises if the value/column is missing |
+| Action not already wired | grep the definition for `action :<x>`; grep the policy for `def <x>?` | Avoids duplicate or dead actions |
+| Cross-resource access | Use `authorized_resource_scope` / `allowed_to?`, never raw `where`/`find` | Raw queries bypass the other resource's tenancy + visibility |
+
+Inspect with your own tools **before** proposing code.
+
+## 🛠 Use the generator — and know what's hand-authored
+
+| Task | How | Verify first |
+|---|---|---|
+| Base trio (controller + policy + interaction-base) | `pu:res:scaffold` | New resource |
+| Portal-specific controller/policy | `pu:res:conn … --dest=portal` | Resource exists |
+| **A custom-action interaction** | **Hand-author** in `app/interactions/<name>_interaction.rb` (subclass `ResourceInteraction`) — **there is NO `pu:res:interaction` generator; don't invent one** | — |
+| Edit an existing customized policy/controller/interaction | Hand-edit the file | It was already generated — re-scaffolding clobbers it |
+
+---
+
 # Part 1 — Controllers
 
 Plutonium controllers ship full CRUD out of the box; nearly all customization lives in definitions / policies / interactions. The controller stays thin.
@@ -494,7 +540,7 @@ def permitted_associations
 end
 ```
 
-Declares which associations get their own **tab on the show page**. When `permitted_associations` is non-empty, the show page renders a tablist: a "Details" tab (the main field card + metadata aside) plus one tab per association — each lazy-loaded via a frame navigator panel pointing at the associated `has_many` collection, `has_one` record, or `belongs_to` target. When empty, the show page renders without tabs.
+Declares which associations get their own **tab on the show page**. When `permitted_associations` is non-empty, the show page renders a tablist: a "Details" tab (the main field card + metadata aside) plus one tab per association — each lazy-loaded via a frame navigator panel pointing at the associated `has_many` collection, `has_one` record, or `belongs_to` target. When empty, the show page renders without tabs. If `permitted_attributes_for_show` resolves to **no fields**, the empty Details tab is omitted and the first association tab leads instead.
 
 Each named association must:
 

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

@@ -0,0 +1,378 @@
+---
+name: plutonium-kanban
+description: Use BEFORE building or customizing a kanban board view for any Plutonium resource — the kanban do…end DSL, column declarations, card_fields, position_on modes, realtime, column actions, kanban_move? policy, and quick-add. The single source for "how do I add a kanban board to a resource".
+---
+
+# Plutonium Kanban
+
+Turn any resource index into a drag-and-drop kanban board with a single `kanban do…end` block in the resource Definition. This skill covers the full DSL surface, model setup, authorization, and the caveats.
+
+For field-level rendering on cards (card_fields slots), see [[plutonium-resource]] › Index Views. For policy structure, see [[plutonium-behavior]]. For custom Phlex components on cards, see [[plutonium-ui]].
+
+## 🚨 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.
+- **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.
+- **Same-column drops = positioning only** — a reorder within a column fires neither `on_exit`, `on_enter`, nor an `enter_interaction`; they represent *leaving*/*entering* a column, so only cross-column drops trigger them.
+- **`on_exit:` is the source-side hook** — fired when a card LEAVES a column (before the destination's `on_enter`, in the same transaction). Use it for source-tied side effects (stop a timer, release a slot) the destination can't own. It fires only on drag-moves via `kanban_move`, NOT on destroy/programmatic changes/quick-add — for those, use an ActiveRecord callback.
+- **Use `on_enter:` / `enter_interaction:`, NOT `on_drop:` / `drop_interaction:`.** The old names were renamed. They still exist as deprecated aliases but **raise in development/test** (and only warn-and-map in production), so a definition using them fails your test suite. Always write the new names.
+
+---
+
+## Model setup
+
+```ruby
+class Task < ApplicationRecord
+  include Plutonium::Positioning
+
+  # position_on :position (default attr) scoped to the grouping column
+  positioned_on :position, scope: :status
+
+  def mark_done!
+    update!(status: "done")
+  end
+end
+```
+
+Migration — add the position column with the `t.position` helper (a tuned `decimal(16,8)`; works in `create_table` and `change_table`). Don't hand-roll a small scale — `scale: 6` exactly matches the `1e-6` rebalance threshold and can round to a duplicate. Use `t.position` (scale 8) or ≥ 8 if hand-written:
+
+```ruby
+create_table :tasks do |t|
+  t.string :title,  null: false
+  t.string :status, null: false, default: "todo"
+  t.position        # decimal :position, precision: 16, scale: 8
+  t.timestamps
+
+  t.index [:status, :position]
+end
+```
+
+---
+
+## Minimal definition
+
+```ruby
+class TaskDefinition < ResourceDefinition
+  kanban do
+    column :todo,
+      scope:   -> { where(status: "todo") },
+      on_enter: ->(r) { r.update!(status: "todo") }
+
+    column :doing,
+      scope:   -> { where(status: "doing") },
+      on_enter: ->(r) { r.update!(status: "doing") }
+
+    column :done,
+      scope:   -> { where(status: "done") },
+      on_enter: :mark_done!     # Symbol → record.mark_done!
+  end
+end
+```
+
+Set it as the default or only view:
+
+```ruby
+default_index_view :kanban   # still shows view switcher with :table
+index_views :kanban           # remove table; kanban is the only view
+```
+
+---
+
+## Board-level options
+
+| DSL call | Purpose | Default |
+|---|---|---|
+| `per_column N` | Cap cards rendered per column; `+N more` footer when exceeded | unlimited |
+| `position_on :attr` | Custom attribute name for ordering (Mode A) | `:position` |
+| `position_on :attr do \|move\| … end` | BYO positioning block (Mode B) | — |
+| `position_on false` | No ordering or repositioning (Mode C) | — |
+| `card_fields(**slots)` | Override grid slot layout for cards; same slot keys as `grid_fields` | inherits `grid_fields` |
+| `realtime true` | ActionCable broadcast after every move | false |
+| `lazy false` | Eager-load all column frames on the initial request | `true` (lazy) |
+| `show_in :modal` / `:page` | Open a card's show page in a centered modal (`:modal`) or full-page (`:page`). Overrides the definition's `show_in` for this board | inherits definition (`:page`) |
+| `columns do … end` | Dynamic columns evaluated at request time with view context | — |
+
+### `card_fields`
+
+Overrides the grid card layout for kanban cards. Uses the same slot keys as `grid_fields`:
+
+```ruby
+card_fields header: :title, meta: [:status, :priority], footer: :due_at
+```
+
+### `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 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.
+
+### `realtime`
+
+Broadcasts refreshed column turbo-frames to all board subscribers after every successful move. Requires ActionCable. Opt in per-board:
+
+```ruby
+realtime true
+```
+
+### `show_in`
+
+Where a card click opens the record's show page. `:modal` renders the show page in a **centered** dialog; `:page` is a full-page navigation. The show modal is always centered — deliberately NOT the definition's `modal_mode` (which styles `new`/`edit`). No per-card wiring: the `Show` page detects the modal frame (`in_modal?`) and wraps its details in the centered modal chrome.
+
+`show_in` also exists **on the definition** (`show_in :modal` / `:page`, default `:page`), where it governs the table and grid show links too. The kanban board inherits the definition's value unless it sets its own — so set it once on the definition for everywhere, or on the board to override just the board.
+
+From inside the show modal, an expand icon (or ⌘/Ctrl/middle-click on the card) opens the full page in a new tab.
+
+```ruby
+class TaskDefinition < ResourceDefinition
+  show_in :modal      # table + grid + board open show in a centered modal
+  kanban do
+    # show_in :page   # override: this board navigates full-page
+  end
+end
+```
+
+### Dynamic columns
+
+Evaluates the block at request time with the view context as `self` (`current_user`, `params`, `current_scoped_entity`, helpers all available). The block must return an Array of `Plutonium::Kanban::Column` objects — `column` is a DSL method only available outside the `columns` block. Declare any column-action interactions as top-level definition `action` calls — the block is not introspectable at class-load time.
+
+> **`enter_interaction:` is NOT supported on dynamic boards.** Its hidden action is registered from the static column list at class-load time, which a `columns do…end` board doesn't have, and the key is column-scoped/internal so there's no manual-registration escape hatch (unlike column actions). A drop into such a column is rejected with a snap-back — it does not crash. Use a static board if you need `enter_interaction:`.
+
+```ruby
+kanban do
+  columns do
+    # `self` is the view context here — use Plutonium::Kanban::Column.new, NOT `column`.
+    current_user.teams.map do |team|
+      Plutonium::Kanban::Column.new(
+        :"team_#{team.id}",
+        label:   team.name,
+        scope:   -> { where(team_id: team.id) },
+        on_enter: ->(r) { r.update!(team_id: team.id) }
+      )
+    end
+  end
+end
+```
+
+---
+
+## Column options
+
+```ruby
+column :key,
+  label:     "Custom Label",   # defaults to key.to_s.titleize
+  color:     :green,           # Tailwind-mapped color hint
+  wip:       3,                # max cross-column moves into this column
+  scope:     -> { where(…) },  # 0-arg lambda or Symbol (sent to relation)
+  on_enter:   ->(r) { … },      # 1-arg lambda or Symbol → record.method! (card ENTERS)
+  on_exit:    ->(r) { … },      # 1-arg lambda or Symbol → runs when a card LEAVES this column
+  enter_interaction: MarkLostInteraction, # record-scoped interaction run on cross-column drop (see below)
+  collapsed: true,             # starts collapsed (Stimulus persists toggle to localStorage)
+  add:       true,             # show "+ Add" button (requires create?)
+  accepts:   true,             # true (default), false, or Array of source keys (Proc raises)
+  locked:    false,            # reject all incoming drops (server-enforced)
+  role:      :backlog          # :backlog, :done or :lost (see presets below)
+```
+
+### Column role presets
+
+| Role | Preset behaviour |
+|---|---|
+| `:backlog` | `add: true` |
+| `:done` | `color: :green`, `collapsed: true` |
+| `:lost` | `color: :red`, `collapsed: true` |
+
+`:done` and `:lost` are the two terminal roles — collapsed by default, colour
+signalling the outcome (`:done` = positive close, `:lost` = negative close). The
+natural pair for won/lost pipelines (leads, deals, tickets).
+
+Explicit options override the preset (e.g. `role: :done, collapsed: false`).
+
+### `accepts:`
+
+Structural drop topology — which **source columns** may drop cards here:
+
+- `true` (default) — any source allowed
+- `false` — column is a drop target but refuses everything (snap-back)
+- `Array` — list of source column keys allowed: `accepts: [:doing]`
+
+Checked server-side; client-side visual hints read `data-kanban-accepts` (so the drag UI can grey out disallowed sources). **No Proc form** — a `Proc` raises `ArgumentError`. Record- or user-conditional rules belong in `kanban_move?`, which sees the record and the `from`/`to` columns (see Authorization below).
+
+### `on_enter:`
+
+Runs inside a transaction after authorization and before repositioning. Receives the record for lambda form:
+
+```ruby
+on_enter: ->(r) { r.update!(status: "done") }   # update! directly
+on_enter: ->(r) { r.status = "done" }            # attribute assignment — saved automatically
+on_enter: :mark_done!                            # dispatched as record.mark_done!
+```
+
+If `on_enter` only assigns attributes without calling `save!`/`update!`, the controller calls `record.save!` automatically when the record has unsaved changes after `on_enter` returns.
+
+### `on_exit:`
+
+The source-side counterpart to `on_enter:`. Runs on the column a card **leaves** during a cross-column move, **before** the destination's `on_enter`, in the same transaction (so it sees the pre-move state and rolls back if the move fails). Same Symbol/Proc dispatch and auto-save behaviour as `on_enter`.
+
+```ruby
+column :doing,
+  scope:    -> { where(status: "doing") },
+  on_enter: ->(r) { r.start_timer! },   # entering Doing
+  on_exit:  ->(r) { r.stop_timer! }     # leaving Doing (wherever it goes)
+```
+
+Use it for side effects tied to the column being **left** — the destination's `on_enter` doesn't know where a card came from, so source concerns (stop a timer, release a WIP/lock, un-assign) belong here.
+
+⚠️ It fires **only** on a drag-move through `kanban_move` — not on `destroy`, a programmatic `status` change elsewhere, or quick-add. For "whenever this leaves, no matter how", use an ActiveRecord callback. Skipped on same-column reorders.
+
+### `enter_interaction:`
+
+Run an input-collecting interaction when a card is dropped **into** this column from another column — for entries that need more than a membership flip (a reason, a mail, an audit entry).
+
+```ruby
+column :lost, scope: -> { where(status: "lost") }, enter_interaction: MarkLostInteraction
+
+class MarkLostInteraction < ResourceInteraction
+  attribute :resource                       # MUST be record-scoped (singular), not :resources
+  attribute :reason, :string
+  input :reason
+  validates :reason, presence: true
+  def execute
+    resource.update!(status: "lost", lost_reason: reason)
+    succeed(resource).with_message("Marked as lost")   # message → toast
+  end
+end
+```
+
+- **Auto-registered as a HIDDEN record action** under a column-scoped key (`:lost` → `:lost_enter_interaction`) — unique by construction, so two columns can reuse the same interaction class. No button on show/table/grid; reachable only by dropping. **No policy method of its own** — authorized by `kanban_move?` (see Authorization).
+- **Move flow:** cross-column drop opens the interaction's form as a modal; on submit `on_enter` + interaction + repositioning commit in **one atomic transaction**. Validation failure rolls it all back (membership write included) and re-renders the modal with errors — nothing persists. Put side-effects on `deliver_later` so a rollback sends no stray mail.
+- **Same-column reorder = positioning only** — neither `on_enter` nor the interaction fires (both = *entering* a column).
+- **Quick-add (`+ Add`)** applies `on_enter` + positioning post-create; the interaction is not involved.
+- **Author contract:** with both present, `on_enter` owns the membership attribute (`status`) and the interaction owns extras. If the interaction also writes membership it must set the **same** value (idempotent). With no `on_enter`, the interaction owns everything (like `:lost`).
+- **Limitation:** custom success *responses* (`with_redirect_response`, `with_file_response`, …) are NOT honored on the drop path — board re-renders + modal closes. Use `.with_message` for feedback.
+
+### Column actions
+
+Declared inside the column block. Auto-registered as interactive resource actions:
+
+```ruby
+column :done, … do
+  action :archive_all,
+    interaction: ArchiveTasksInteraction,
+    on:          :all,          # :all or :visible
+    label:       "Archive all",
+    icon:        Phlex::TablerIcons::Archive,
+    confirmation: "Archive all done tasks?"
+end
+```
+
+`on: :all` — passes every record in the column scope. `on: :visible` — passes only the currently rendered subset (respects `per_column`).
+
+---
+
+## Authorization
+
+### `kanban_move?` → `update?`
+
+Every drag-and-drop is authorized via `kanban_move?` in the policy. Default:
+
+```ruby
+def kanban_move?
+  update?
+end
+```
+
+Override for finer control:
+
+```ruby
+class TaskPolicy < ResourcePolicy
+  def kanban_move? = user.member?   # members can drag; only admins edit
+end
+```
+
+When `kanban_move?` returns `false`, the board renders read-only — no drag handles, no drop zones.
+
+**`kanban_move?` is the ONLY move authorization** — plain moves and `enter_interaction:` columns alike (the interaction has no policy method of its own). To gate a *specific* transition, read the destination (and source) column from the authorization context via the optional `kanban_to` / `kanban_from` policy readers (the `Column` objects; `nil` for every non-move check):
+
+```ruby
+def kanban_move?
+  return user.manager? if kanban_to&.key == :closed_won
+  super
+end
+```
+
+Rules take no positional args in ActionPolicy — the columns arrive as declared optional context (`authorize :kanban_from/:kanban_to, optional: true` on the base policy), supplied by the controller on the move check.
+
+### Move authorization flow
+
+1. Record loaded via current `relation_scope` (same as index).
+2. `kanban_move?` checked (with `kanban_from`/`kanban_to` in context) — HTTP 403 on failure. This is the sole authorization; an `enter_interaction` rides on it.
+3. Column `accepts:` / `locked:` checked — HTTP 422 + card snap-back on failure.
+4. `wip:` limit checked for cross-column moves — HTTP 422 on failure.
+5. `on_enter` fires + record repositioned, all in a transaction.
+
+On a 422 rejection (steps 3–4) the response re-renders the source column (snap-back) **and** appends a dismissable warning toast naming the reason (e.g. `“Pending” is at its WIP limit (5).`) to the board's `#kanban-flash` region — so the snap-back is never silent. The toast renders the shared `plutonium/toast` partial directly (not via `flash`), so a stale undisplayed flash can't leak into the turbo-stream response.
+
+### No permitted-attributes gate
+
+Moves do not pass through `permitted_attributes_for_update`. `on_enter` is trusted author code; it is responsible for assigning only the appropriate attributes.
+
+### Quick-add
+
+The `+ Add` button (column `add: true`) only renders when the policy's `create?` is true. The opened form is the standard new-resource form.
+
+The record is created normally, **then** the column's `on_enter` + positioning are applied to the **saved** record (it lands in the clicked column, appended to the bottom) — `on_enter` runs against a real record, exactly as on a drag. **Your grouping column must have a default** (DB or model), because `on_enter` runs after save; a `NOT NULL` grouping column with no default fails quick-add create. A raising `on_enter` keeps the created record in its default column and toasts the error (the create is not rolled back).
+
+---
+
+## Worked example (full)
+
+```ruby
+class TaskDefinition < ResourceDefinition
+  kanban do
+    per_column 25
+    card_fields header: :title, meta: [:status]
+
+    column :todo,
+      scope:   -> { where(status: "todo") },
+      on_enter: ->(r) { r.update!(status: "todo") },
+      role: :backlog                    # add: true
+
+    column :doing,
+      scope:   -> { where(status: "doing") },
+      on_enter: ->(r) { r.update!(status: "doing") },
+      wip: 3
+
+    column :done,
+      scope:   -> { where(status: "done") },
+      on_enter: :mark_done!,
+      accepts: [:doing],                # only cards coming from :doing
+      role:    :done do                 # color: :green, collapsed: true
+      action :archive_all,
+        interaction: ArchiveTasksInteraction,
+        on:    :all,
+        label: "Archive all"
+    end
+  end
+end
+```
+
+---
+
+## Full docs
+
+- Guide: `docs/guides/kanban.md`
+- DSL reference: `docs/reference/kanban/dsl.md`
+- Positioning reference: `docs/reference/kanban/positioning.md`
+- Authorization reference: `docs/reference/kanban/authorization.md`
+- Working example: `test/dummy/app/definitions/task_definition.rb`
+
+---
+
+## Related skills
+
+- [[plutonium-resource]] — Definition layer, `grid_fields`, index views, actions
+- [[plutonium-behavior]] — Policy methods, `kanban_move?`, interactions
+- [[plutonium-ui]] — Custom Phlex components for card rendering

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

@@ -22,6 +22,46 @@ For tenancy / `associated_with` / `relation_scope`, load [[plutonium-tenancy]].
 
 ---
 
+## 🛑 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:
+
+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.
+
+**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)
+
+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 |
+|---|---|---|
+| Resource already exists | Read `app/models/<x>.rb` + `app/**/definitions/<x>_definition.rb`; `ls` the policy/controller | Existing + customized ⇒ **incremental edit, never re-scaffold** |
+| Model is a resource record | grep `Plutonium::Resource::Record` / `< ResourceRecord` | Auto-detection + the field DSL depend on it |
+| Name collision | Read `db/schema.rb` for the column; grep the model for an existing method/enum/assoc of that name | A clashing `status` silently breaks the enum |
+| Referenced association target | `ls app/models` for the `belongs_to` target class | `x:belongs_to` to a missing model fails the scaffold |
+| `has_cents` policy leak | grep the policy/definition for `_cents` | Generator emits `:price_cents`; fix to the virtual `:price` |
+| Migrations applied | `rails db:migrate:status` before `pu:res:conn` | Unmigrated / unconnected ⇒ the resource is invisible |
+
+Inspect with your own tools **before** proposing commands or edits.
+
+## 🛠 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=`.
+
+| Task | Generator | Verify first |
+|---|---|---|
+| 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 |
+
+---
+
 # Part 1 — Creating a Resource
 
 ## Quick checklist