plutonium 0.60.5 → 0.61.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 004004c1342357f78b64e9ebc65c138438f3f84bad76c4f4af5c6875d7200821
-  data.tar.gz: 2e4fa5789c30c0bb39227b7ce9577f95eaf6166d116ec9670f23735a269c9a9d
+  metadata.gz: 8f8adf3a1153ed95a357bf90ab145279c7f7b72540c6f160c8f52f859ed14e4e
+  data.tar.gz: 96f58112aff1ffd9a21311c169169c31efe61c16470c65f1805b9860e987baca
 SHA512:
-  metadata.gz: 36909e8c72456b74db2d941331b8bfb54dba04925ab53365bf188978dad45a9d699aabb6c16892951dfe5000aa40cc97fd1df2102e8e07026456e65de0af2b3d
-  data.tar.gz: 1962eab914ff635d489a75f9bb7c06a69c0ac382128f79e6a5caeac368010d9af84b834a568e61597b1279297a7438ca79408f32f2116a09064b2f8b3a31a0dd
+  metadata.gz: 3cec89b62845ecb9177e21bb7307c18f182056ce01164f657b07b2dd5e165c041aa0172b7f22b967061170b3a39398834b2966c8d62ba333e279ce0ff8ee0f8d
+  data.tar.gz: d8369fec9bd3e3ce5951248e03ee065c6dd9e31fa05bccd9ab7bc49abb69a0586a1b94adbcf5c0bec11b0dc8269927daa8ca41ad62ef7d6f20d045cc02004ca8

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,313 @@
+---
+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_drop` 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.
+
+---
+
+## 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_drop: ->(r) { r.update!(status: "todo") }
+
+    column :doing,
+      scope:   -> { where(status: "doing") },
+      on_drop: ->(r) { r.update!(status: "doing") }
+
+    column :done,
+      scope:   -> { where(status: "done") },
+      on_drop: :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_drop` 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.
+
+```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_drop: ->(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_drop:   ->(r) { … },      # 1-arg lambda or Symbol → record.method!
+  collapsed: true,             # starts collapsed (Stimulus persists toggle to localStorage)
+  add:       true,             # show "+ Add" button (requires create?)
+  accepts:   true,             # true (default), false, Array of source keys, or 1-arg Proc
+  locked:    false,            # reject all incoming drops (server-enforced)
+  role:      :backlog          # :backlog or :done (see presets below)
+```
+
+### Column role presets
+
+| Role | Preset behaviour |
+|---|---|
+| `:backlog` | `add: true` |
+| `:done` | `color: :green`, `collapsed: true` |
+
+Explicit options override the preset (e.g. `role: :done, collapsed: false`).
+
+### `accepts:`
+
+Controls 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]`
+- `Proc` (1-arg) — per-card predicate: `accepts: ->(record) { record.state == "doing" }`
+
+Checked server-side. Client-side visual hints read `data-kanban-accepts`.
+
+### `on_drop:`
+
+Runs inside a transaction after authorization and before repositioning. Receives the record for lambda form:
+
+```ruby
+on_drop: ->(r) { r.update!(status: "done") }   # update! directly
+on_drop: ->(r) { r.status = "done" }            # attribute assignment — saved automatically
+on_drop: :mark_done!                            # dispatched as record.mark_done!
+```
+
+If `on_drop` only assigns attributes without calling `save!`/`update!`, the controller calls `record.save!` automatically when the record has unsaved changes after `on_drop` returns.
+
+### 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.
+
+### Move authorization flow
+
+1. Record loaded via current `relation_scope` (same as index).
+2. `kanban_move?` checked — HTTP 403 on failure.
+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_drop` 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_drop` 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.
+
+---
+
+## 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_drop: ->(r) { r.update!(status: "todo") },
+      role: :backlog                    # add: true
+
+    column :doing,
+      scope:   -> { where(status: "doing") },
+      on_drop: ->(r) { r.update!(status: "doing") },
+      wip: 3
+
+    column :done,
+      scope:   -> { where(status: "done") },
+      on_drop: :mark_done!,
+      accepts: ->(task) { task.status == "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

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

@@ -25,6 +25,49 @@ Cross-references back to [[plutonium-resource]] (models, definitions) and [[plut
 
 ---
 
+## 🛑 Before you scope anything: confirm the shape (ASK — don't infer)
+
+Tenancy decisions are **underspecified by a one-line request and have high blast radius**: guess the entity, the strategy, or the association path and you ship a model that *compiles but leaks across tenants*, *raises at runtime*, or *produces the wrong URL*. "Scope X to the tenant" does **not** determine any of the below.
+
+Resolve each decision — **by inspecting the app (next section), not by guessing** — then restate the resolved shape in a sentence and confirm:
+
+1. **Is this portal even entity-scoped?** A model is only tenant-filtered inside a portal that declares `scope_to_entity`. No `scope_to_entity` ⇒ your model change does nothing. (Verify it exists *before* touching the model.)
+2. **Which entity model, and which strategy?** `Organization` / `Account` / `Tenant` / `Company`? `:path` (most common) or custom (subdomain/session)? **Never default to `Organization` + `:path`** — read it.
+3. **What is the association PATH from this model to the entity?** Direct `belongs_to`, multi-hop `has_one :through`, a membership/join, or polymorphic needing a custom `associated_with_<entity>` scope (§ Three model shapes). This is the #1 thing to confirm against the **actual model** — wrong path ⇒ leak *or* raise.
+4. **Nested (parent-scoped) or entity-scoped?** Reached through a parent ⇒ parent scoping wins, don't double-scope. And **nesting is ONE level only** — a three-level URL request can't be met with `register_resource` nesting; say so before wiring it.
+5. **Uniqueness scoped to the tenant FK?** Any `validates … uniqueness` must scope to the tenant FK (`scope: :organization_id`) or it leaks across tenants.
+
+**Never emit applied scoping code from a *guessed* association path.** Confirm the path against the real model first; fall back to `AskUserQuestion` only for genuinely product-level choices you can't read off the code (which entity, which strategy). The decisions compound: *no scoped portal ⇒ nothing filters*; *nested ⇒ parent-scoped, not entity-scoped*; *multi-hop ⇒ needs `has_one :through` or a custom scope*.
+
+## ✅ Before you edit: 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. Inspect first, then act:
+
+| Check | How | Why it matters |
+|---|---|---|
+| Portal is scoped | `rg "scope_to_entity" -n` in the portal engine(s) | Confirms entity class + strategy; absent ⇒ scoping is a no-op |
+| Model is a resource | Read the model — `include Plutonium::Resource::Record` / `< ResourceRecord` | `associated_with` only exists on resource records |
+| Association path resolves | Read the model's `belongs_to`/`has_one :through` chain to the entity (or a `associated_with_<entity>` scope) | This is the real fix site; missing path ⇒ raise |
+| Denormalized FK already present | Read the schema/migration for an existing `<entity>_id` column | Collapses a multi-hop chain to a one-line `belongs_to` |
+| No leaky override | `rg "relation_scope" -n` in the policy | A manual `where(<entity>:…)` is the leak — **remove it**, don't patch it |
+| (Invites) prerequisites | Membership model exists with `enum :role`; AR encryption keys set (`bin/rails db:encryption:init`) | `pu:invites:install` fails loudly without both |
+
+Do this inspection with your own tools **before** proposing code. Surfacing a concrete edit you haven't grounded in the real files is how the "looks right, leaks anyway" bug ships.
+
+## 🛠 Use the generator — and verify its precondition first
+
+Hand-wiring tenancy (invite models, membership tables, join records) is how leaks happen. Reach for the generator, run it with `--dest=` to avoid prompts, and **confirm the precondition before running**:
+
+| Task | Generator | Verify first |
+|---|---|---|
+| New SaaS spine (user + entity + membership + join) | `pu:saas:setup --user U --entity E` | None — this is the bootstrap |
+| Scope a portal to an entity | `pu:pkg:portal --scope=Entity` | Entity model exists |
+| New tenant-scoped model | `pu:res:scaffold Model entity:belongs_to …` then `pu:res:conn` | Migrations from prior scaffolds are run |
+| Invite flow | `pu:invites:install` | Membership model exists (`enum :role`) **and** AR encryption keys configured |
+| App model notified on accept | `pu:invites:invitable Model` | Invites already installed |
+
+---
+
 # Part 1 — Entity Scoping
 
 Built on three cooperating pieces: