plutonium 0.61.0 → 0.62.0

data/app/views/resource/_kanban_move_action_form.html.erb

@@ -0,0 +1 @@
+<%= render Plutonium::UI::Form::KanbanMove.new(@interaction) %>

data/app/views/resource/kanban_move_form.html.erb

@@ -0,0 +1 @@
+<%= render Plutonium::UI::Page::KanbanMove.new %>

data/config/brakeman.ignore

@@ -144,11 +144,11 @@
     {
       "warning_type": "Dangerous Eval",
       "warning_code": 13,
-      "fingerprint": "ac51d516bdbc88a0a624795dad1b3efc1d2744b3f2d7be7feb67e0b5cebab763",
+      "fingerprint": "bdacd028907815ba0db0cf99e069d1ea7e94a6e527b7746efd97886c52b2f928",
       "check_name": "Evaluation",
       "message": "Dynamic string evaluated as code",
       "file": "lib/plutonium/models/has_cents.rb",
-      "line": 134,
+      "line": 162,
       "link": "https://brakemanscanner.org/docs/warning_types/dangerous_eval/",
       "code": "class_eval(\"            # Getter method for the decimal representation of the cents value.\\n            #\\n            # @return [BigDecimal, nil] The decimal value or nil if cents_name is not present.\\n            def #{(:\"#{cents_name.to_sym}_#{suffix}\" or cents_name.to_sym.to_s.gsub(/_cents$/, \"\").to_sym)}\\n              #{cents_name.to_sym}.to_d / #{rate} if #{cents_name.to_sym}.present?\\n            end\\n\\n            # Setter method for the decimal representation of the cents value.\\n            #\\n            # @param value [Numeric, nil] The decimal value to be set.\\n            def #{(:\"#{cents_name.to_sym}_#{suffix}\" or cents_name.to_sym.to_s.gsub(/_cents$/, \"\").to_sym)}=(value)\\n              self.#{cents_name.to_sym} = begin\\n                (BigDecimal(value.to_s) * #{rate}).to_i if value.present?\\n              rescue ArgumentError\\n                nil\\n              end\\n            end\\n\\n            # Mark decimal field as invalid if cents field is not valid\\n            after_validation do\\n              next unless errors[#{cents_name.to_sym.inspect}].present?\\n\\n              errors.add(#{(:\"#{cents_name.to_sym}_#{suffix}\" or cents_name.to_sym.to_s.gsub(/_cents$/, \"\").to_sym).inspect}, :invalid)\\n            end\\n\", \"lib/plutonium/models/has_cents.rb\", 135)",
       "render_path": null,

data/docs/.vitepress/config.ts

@@ -1,5 +1,6 @@
 import { defineConfig } from "vitepress"
 import { withMermaid } from "vitepress-plugin-mermaid";
+import llmstxt from "vitepress-plugin-llms";
 
 const base = "/plutonium-core/"
 
@@ -22,6 +23,24 @@ export default defineConfig(withMermaid({
   ],
   ignoreDeadLinks: 'localhostLinks',
   srcExclude: ['superpowers/**'],
+  vite: {
+    plugins: [
+      // Generates llms.txt, llms-full.txt, and a raw .md twin for every page.
+      llmstxt({
+        // Site base (/plutonium-core/) is appended automatically — domain must not include it.
+        domain: "https://radioactive-labs.github.io",
+        // public/ is served verbatim (skills live there); superpowers/ is internal.
+        // Section landing pages are Vue components with no markdown content.
+        ignoreFiles: [
+          "superpowers/**",
+          "public/**",
+          "getting-started/index.md",
+          "guides/index.md",
+          "reference/index.md",
+        ],
+      }),
+    ],
+  },
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     logo: "/plutonium.png",
@@ -32,7 +51,8 @@ export default defineConfig(withMermaid({
       { text: "Home", link: "/" },
       { text: "Getting Started", link: "/getting-started/" },
       { text: "Guides", link: "/guides/" },
-      { text: "Reference", link: "/reference/" }
+      { text: "Reference", link: "/reference/" },
+      { text: "For AI Agents", link: "/ai" }
     ],
     sidebar: {
       '/getting-started/': [

data/docs/.vitepress/sync-skills.mjs

@@ -0,0 +1,45 @@
+// Syncs .claude/skills/*/SKILL.md into docs/public/skills/ so the docs site
+// serves them as raw, crawlable markdown at /skills/<name>.md.
+// Runs before `docs:dev` and `docs:build` (see package.json). Output is gitignored.
+import { readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..")
+const skillsDir = join(root, ".claude", "skills")
+const outDir = join(root, "docs", "public", "skills")
+
+rmSync(outDir, { recursive: true, force: true })
+mkdirSync(outDir, { recursive: true })
+
+const skills = []
+
+for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue
+  const source = join(skillsDir, entry.name, "SKILL.md")
+  if (!existsSync(source)) continue // skip dirs that aren't skills (no SKILL.md)
+  let content = readFileSync(source, "utf8")
+
+  const description = content.match(/^description:\s*(.+)$/m)?.[1] ?? ""
+
+  // Wiki-style [[skill-name]] cross-links become relative markdown links so
+  // crawlers can follow them between the published files.
+  content = content.replace(/\[\[([\w-]+)\]\]/g, "[$1]($1.md)")
+
+  writeFileSync(join(outDir, `${entry.name}.md`), content)
+  skills.push({ name: entry.name, description })
+}
+
+skills.sort((a, b) => (a.name === "plutonium" ? -1 : b.name === "plutonium" ? 1 : a.name.localeCompare(b.name)))
+
+const index = `# Plutonium Skills
+
+Task-focused guides for AI agents working with the [Plutonium](https://radioactive-labs.github.io/plutonium-core/) Rails RAD framework. Each file is self-contained markdown. Start with \`plutonium.md\` — it routes to the others.
+
+These are the same skills the gem installs into projects via \`rails g pu:skills:sync\` (Claude Code loads them automatically from \`.claude/skills/\`). Any agent can fetch them directly from the URLs below.
+
+${skills.map((s) => `- [${s.name}](${s.name}.md) — ${s.description}`).join("\n")}
+`
+
+writeFileSync(join(outDir, "index.md"), index)
+console.log(`Synced ${skills.length} skills to docs/public/skills/`)

data/docs/ai.md

@@ -0,0 +1,99 @@
+---
+title: Plutonium for AI Agents
+description: Machine-readable entry point for AI coding agents building Rails apps with Plutonium — install commands, conventions, generator catalog, and skill files.
+sidebar: false
+---
+
+# Plutonium for AI Agents
+
+You are reading the agent entry point for **Plutonium**, a Rails RAD framework (Ruby gem) that provides resource-oriented architecture: automatic CRUD, authorization policies, declarative UI definitions, authentication, and multi-tenancy. If a user asked you to build something with Plutonium, this page gives you the golden path and where to read next.
+
+## Machine-readable resources
+
+| Resource | URL |
+|---|---|
+| Docs index (llms.txt) | `https://radioactive-labs.github.io/plutonium-core/llms.txt` |
+| Full docs, one file | `https://radioactive-labs.github.io/plutonium-core/llms-full.txt` |
+| Agent skills index | `https://radioactive-labs.github.io/plutonium-core/skills/index.md` |
+| Router skill (start here) | `https://radioactive-labs.github.io/plutonium-core/skills/plutonium.md` |
+
+Every docs page also has a raw markdown twin: append `.md` to its URL (e.g. `/guides/multi-tenancy.md`).
+
+**Prefer the skills over the raw docs.** They are task-focused, deduplicated, and encode the mistakes agents actually make. The router skill maps "about to do X" to the right skill file. If you are Claude Code, run `rails g pu:skills:sync` after installing the gem to install them into `.claude/skills/` so they load automatically.
+
+## Rules that prevent expensive mistakes
+
+1. **Plutonium is generator-driven.** Nearly every file has a `pu:*` generator. Generate, then edit — never hand-write models, definitions, policies, or packages from scratch. Hand-written files drift from conventions and break future generator runs.
+2. **Inspect before you act.** Check `Gemfile` for `plutonium`, `ls config/packages.rb`, and `ls packages/` before installing or scaffolding anything.
+3. **New app → `plutonium.rb` template. Existing app → `base.rb` template.** Never run `plutonium.rb` on an existing app; it re-runs full bootstrap and clobbers git history.
+4. **Pass flags to avoid interactive prompts**: `--dest=main_app` (or `--dest=<package>`), `--force` when re-running meta-generators, `--auth=<account>` for portals, `--skip-bundle`, `--quiet`.
+5. **Quote field arguments with special characters**: `'title:string?'`, `'price:decimal{10,2}'`.
+6. **Multi-tenancy is structural, not filtered in policies.** The portal declares `scope_to_entity`; the model provides the association path that `associated_with` resolves. Never `where(organization: ...)` in a policy — read the tenancy skill first.
+
+## Golden path: new application
+
+```bash
+rails new myapp -a propshaft -j esbuild -c tailwind \
+  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+cd myapp
+rails db:prepare
+```
+
+Then for each resource:
+
+```bash
+rails g pu:res:scaffold Post 'title:string' 'body:text?' user:references --dest=main_app
+rails db:prepare
+rails g pu:res:conn Post --dest=<portal_package>
+```
+
+## Golden path: existing application
+
+```bash
+bin/rails app:template \
+  LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
+```
+
+Or manually: add `gem "plutonium"` to the Gemfile, `bundle install`, then `rails g pu:core:install`.
+
+## Architecture in one table
+
+A **resource** is four cooperating layers. Plutonium auto-fills defaults from the model; you only declare overrides.
+
+| Layer | File | Purpose |
+|---|---|---|
+| Model | `app/models/post.rb` | Data, validations, associations |
+| Definition | `app/definitions/post_definition.rb` | UI — fields, filters, actions |
+| Policy | `app/policies/post_policy.rb` | Authorization |
+| Controller | `app/controllers/posts_controller.rb` | Rarely edited — use hooks |
+| Interaction (optional) | `app/interactions/publish_post_interaction.rb` | Business logic for custom actions |
+
+Resources live in the main app or in **feature packages**; users access them through **portal packages** (Rails engines with their own auth and optional tenant scoping).
+
+## Generator catalog
+
+Discover all generators with `rails g --help | grep pu:`. The most used:
+
+| Generator | Purpose |
+|---|---|
+| `pu:core:install` | Initial Plutonium setup |
+| `pu:res:scaffold NAME field:type ... --dest=` | New resource (model, migration, policy, definition) |
+| `pu:res:conn RESOURCE --dest=PORTAL` | Connect a resource to a portal |
+| `pu:pkg:package NAME` | Feature package |
+| `pu:pkg:portal NAME --auth=...` | Portal package |
+| `pu:rodauth:install` / `pu:rodauth:account NAME` | Authentication |
+| `pu:saas:setup --user ... --entity ...` | Full SaaS bootstrap: user + tenant + membership + portal |
+| `pu:test:install` / `pu:test:scaffold NAME` | Testing scaffolds |
+| `pu:skills:sync` | Install the agent skill files into the project |
+
+## Verify your work
+
+```bash
+rails runner "puts Plutonium::VERSION"   # gem installed and loaded
+rails db:prepare                          # migrations applied
+bin/dev                                   # boot; visit the portal route
+```
+
+## For humans reading this
+
+This page exists so AI coding agents can bootstrap correctly on the first try. Point your agent at it, or just say: *"Read https://radioactive-labs.github.io/plutonium-core/ai.md before starting."* The [Getting Started guide](/getting-started/) covers the same ground for people.

data/docs/guides/kanban.md

@@ -12,7 +12,7 @@ Turn any resource index into a drag-and-drop kanban board — columns, WIP limit
 
 - Drag cards between columns; the server persists the column change and the position within the column.
 - Decimal fractional positioning — cards always land exactly where you drop them without renumbering.
-- Per-column `+ Add` button opens the resource's normal new form, pre-seeded for that column.
+- Per-column `+ Add` button opens the resource's normal new form; the new card is placed in that column (`on_enter` + positioning applied post-create).
 - Column actions run an interaction against all (or visible) cards in a column.
 - WIP limits, locked columns, and cross-column drop restrictions enforced server-side.
 - Opt-in realtime: every connected viewer sees the same board state after any move.
@@ -66,17 +66,17 @@ class TaskDefinition < ResourceDefinition
 
     column :todo,
       scope: -> { where(status: "todo") },
-      on_drop: ->(r) { r.update!(status: "todo") },
+      on_enter: ->(r) { r.update!(status: "todo") },
       role: :backlog          # shorthand for add: true
 
     column :doing,
       scope: -> { where(status: "doing") },
-      on_drop: ->(r) { r.update!(status: "doing") },
+      on_enter: ->(r) { r.update!(status: "doing") },
       wip: 3
 
     column :done,
       scope: -> { where(status: "done") },
-      on_drop: :mark_done!,   # Symbol → record.mark_done!
+      on_enter: :mark_done!,   # Symbol → record.mark_done!
       accepts: [:doing],      # only cards from :doing can land here
       role: :done do          # shorthand for color: :green, collapsed: true
       action :archive_all,
@@ -116,7 +116,7 @@ If a move is refused server-side — the destination is at its `wip:` limit, its
 
 ![A warning toast reading “Pending” is at its WIP limit (5) after a rejected drop](/images/guides/kanban-wip-toast.png)
 
-The toast is appended to a `#kanban-flash` region in the board shell (outside the per-column frames, so it survives the snap-back re-render). The client-side drag hints already grey out columns a card plainly can't enter, so the toast mainly surfaces the cases the browser can't pre-check — most commonly a WIP-full column or a per-card `accepts:` Proc.
+The toast is appended to a `#kanban-flash` region in the board shell (outside the per-column frames, so it survives the snap-back re-render). The client-side drag hints already grey out columns a card plainly can't enter, so the toast mainly surfaces the cases the browser can't pre-check — most commonly a WIP-full column or a `kanban_move?` denial.
 
 ### Opening a card
 
@@ -149,15 +149,15 @@ class KitchenSinkDefinition < ResourceDefinition
   kanban do
     column :active, label: "Active", role: :backlog,
       scope:   -> { where(status: :active) },
-      on_drop: ->(ks) { ks.status = :active }
+      on_enter: ->(ks) { ks.status = :active }
 
     column :pending, label: "Pending", color: :yellow, wip: 5,
       scope:   -> { where(status: :pending) },
-      on_drop: ->(ks) { ks.status = :pending }
+      on_enter: ->(ks) { ks.status = :pending }
 
     column :archived, label: "Archived", role: :done,
       scope:   -> { where(status: :archived) },
-      on_drop: ->(ks) { ks.status = :archived }
+      on_enter: ->(ks) { ks.status = :archived }
 
     per_column 10
   end
@@ -168,7 +168,7 @@ Key points:
 - `role: :backlog` enables the `+ Add` button (equivalent to `add: true`).
 - `wip: 5` caps the Pending column; a cross-column drop that would push it past 5 is rejected server-side.
 - `role: :done` collapses the Archived column by default and shows a green header dot.
-- `on_drop` here assigns the attribute in memory (`ks.status = :active`). The framework calls `record.save!` automatically when the record has unsaved changes after `on_drop` returns — you do not need to call `update!` explicitly.
+- `on_enter` here assigns the attribute in memory (`ks.status = :active`). The framework calls `record.save!` automatically when the record has unsaved changes after `on_enter` returns — you do not need to call `update!` explicitly.
 
 ---
 
@@ -184,7 +184,7 @@ kanban do
     label: "Product Backlog",      # default: key.to_s.titleize
     color: :blue,                  # dot color in the column header
     scope: -> { where(stage: 0) }, # 0-arg lambda evaluated on the relation
-    on_drop: ->(r) { r.update!(stage: 0) }
+    on_enter: ->(r) { r.update!(stage: 0) }
 end
 ```
 
@@ -201,7 +201,7 @@ kanban do
         :"project_#{project.id}",
         label: project.name,
         scope: -> { where(project_id: project.id) },
-        on_drop: ->(r) { r.update!(project_id: project.id) }
+        on_enter: ->(r) { r.update!(project_id: project.id) }
       )
     end
   end
@@ -227,6 +227,8 @@ class TaskDefinition < ResourceDefinition
   end
 end
 ```
+
+Note that **`enter_interaction:` is not supported on dynamic boards** — its hidden action is registered from the static column list at class-load time, and its key is internal (column-scoped) so it can't be registered manually the way a column action can. A drop into such a column snaps back rather than committing (it doesn't crash). Use a static board if a column needs an `enter_interaction:`.
 :::
 
 ### Column options
@@ -236,11 +238,13 @@ end
 | `label:` | String | `key.to_s.titleize` | Column header text |
 | `color:` | Symbol or String | `nil` | Dot color in the column header — `:red`, `:orange`, `:amber`, `:yellow`, `:green`, `:blue`, `:purple`, `:pink`, `:gray`, or a raw CSS value |
 | `scope:` | Symbol or Proc | `nil` | Filters the resource relation to this column's cards. Symbol → named scope; Proc → 0-arg lambda called with `instance_exec` on the relation (e.g. `-> { where(status: "todo") }`) |
-| `on_drop:` | Symbol or Proc | `nil` | Called when a card lands in this column. Symbol → `record.public_send(sym)`; Proc → 1-arg lambda `->(record) { … }` where `self` is the view context |
-| `role:` | `:backlog`, `:done` | `nil` | Preset shorthand (see below) |
+| `on_enter:` | Symbol or Proc | `nil` | Called when a card lands in this column. Symbol → `record.public_send(sym)`; Proc → 1-arg lambda `->(record) { … }` where `self` is the view context |
+| `on_exit:` | Symbol or Proc | `nil` | Source-side counterpart to `on_enter:` — called when a card **leaves** this column on a cross-column move, before the destination's `on_enter`, in the same transaction. For source-tied side effects (stop a timer, release a slot). Drag-moves only (not destroy/programmatic/quick-add); skipped on same-column reorders |
+| `enter_interaction:` | Class | `nil` | Record-scoped interaction run on a cross-column drop into this column — opens a modal to collect input, then commits atomically. See [Interaction on drop](#interaction-on-drop) |
+| `role:` | `:backlog`, `:done`, `:lost` | `nil` | Preset shorthand (see below) |
 | `collapsed:` | Boolean | `false` | Start collapsed |
 | `add:` | Boolean | `false` | Show `+ Add` quick-add button |
-| `accepts:` | `true`, `false`, Array of keys, or Proc | `true` | Which drops are accepted. `true` = all, `false` = none, `[:doing]` = only from `:doing`. A 1-arg Proc `->(record) { … }` is evaluated **per-card on the server** at drop time and returns a boolean (e.g. `->(task) { task.status == "doing" }`) |
+| `accepts:` | `true`, `false`, or Array of keys | `true` | Which source columns may drop here (structural, client-hintable). `true` = all, `false` = none, `[:doing]` = only from `:doing`. Record/user conditions go in `kanban_move?` instead (it sees the record and `from`/`to`); a `Proc` here raises |
 | `locked:` | Boolean | `false` | Prevent dragging cards **out of** this column |
 | `wip:` | Integer | `nil` | Work-in-progress limit. Cross-column drops that would exceed this count are rejected |
 
@@ -250,6 +254,11 @@ end
 |------|---------------|
 | `:backlog` | `add: true` |
 | `:done` | `color: :green, collapsed: true` |
+| `:lost` | `color: :red, collapsed: true` |
+
+`:done` and `:lost` are the two terminal roles (both collapsed by default) — the
+won/lost pair for pipelines like leads, deals, or tickets; the colour signals the
+outcome.
 
 Explicitly provided options override the preset.
 
@@ -264,7 +273,7 @@ Declare actions inside a column block to run an interaction against that column'
 ```ruby
 column :done,
   scope: -> { where(status: "done") },
-  on_drop: :mark_done! do
+  on_enter: :mark_done! do
 
   action :archive_all,
     interaction: ArchiveTasksInteraction,   # must be a bulk interaction (has `attribute :resources`)
@@ -282,6 +291,101 @@ Column actions are rendered as buttons in the column header. They open the norma
 
 ---
 
+## Interaction on drop
+
+A column can declare `enter_interaction:` to run an authorization-aware, input-collecting [Interaction](/reference/behavior/interactions) when a card is dropped **into** it from another column. Use it when entering a column needs more than a membership flip — a reason, a notification email, an audit entry.
+
+```ruby
+column :lost,
+  scope: -> { where(status: "lost") },
+  enter_interaction: MarkLostInteraction
+```
+
+`enter_interaction:` takes an **Interaction class**. It must be **record-scoped** — it declares `attribute :resource` and acts on the single dropped card. A bulk (`attribute :resources`) interaction is not valid here; that shape is for [column actions](#column-actions).
+
+The interaction is **auto-registered as a hidden record action** under a column-scoped key (`:lost` → `:lost_enter_interaction`), so two columns can reuse the same interaction class without colliding. "Hidden" means it does **not** appear as an action button on the show page, table rows, or grid cards — it is reachable only by dropping a card into the column.
+
+### The interaction
+
+A drop interaction is an ordinary record-scoped interaction — nothing kanban-specific in the class:
+
+```ruby
+class MarkLostInteraction < ResourceInteraction
+  presents label: "Mark Lost",
+    icon: Phlex::TablerIcons::X
+
+  attribute :resource
+  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")
+  end
+end
+```
+
+### Authorization
+
+The drop is authorized by the single **`kanban_move?`** predicate — the interaction has **no policy method of its own**. To gate this specific transition, branch on the destination column, which `kanban_move?` reads from its authorization context (`kanban_to`):
+
+```ruby
+class TaskPolicy < ResourcePolicy
+  def kanban_move?
+    return update? if kanban_to&.key == :lost   # who may mark a task lost
+    super
+  end
+end
+```
+
+This keeps authorization in one place: `kanban_move?` gates every move, and the `to` (and `from`) column context lets it gate a specific transition — no per-interaction predicate, no `condition:` proc. If the check fails the drop is refused and the card stays put. See [Authorization](../reference/kanban/authorization) for the full `from`/`to` context.
+
+### Two flows, split by intent
+
+- **Move flow (drag a card cross-column).** Dropping into the column opens the interaction's form as a **modal** to collect input (the `reason`). On submit, the membership write (`on_enter`, if any), the interaction, and the repositioning are committed in **one atomic transaction**.
+- **Quick-add (`+ Add`).** The `+ Add` button creates the record, then applies `on_enter` + positioning **post-create** (see [Quick-add](#quick-add)). The `enter_interaction` is **not** involved in quick-add.
+
+### Author contract: on_enter owns membership, the interaction owns extras
+
+A column can declare `on_enter:` and `enter_interaction:` together. When it does:
+
+- `on_enter` owns the **membership attribute** (the column's grouping value, e.g. `status`).
+- `enter_interaction` owns the **extras** — the reason, the mail, the audit trail.
+
+If the interaction also writes the membership attribute it **must set the same value** `on_enter` sets (idempotent). In this dummy-app example the `:blocked` column does exactly that — `on_enter` sets `status = "blocked"` and the interaction's `execute` re-asserts `status: "blocked"` while adding the reason:
+
+```ruby
+column :blocked,
+  scope: -> { where(status: "blocked") },
+  on_enter: ->(r) { r.status = "blocked" },
+  enter_interaction: BlockTaskInteraction
+```
+
+When a column declares **only** a `enter_interaction` (no `on_enter`, like `:lost` above), the interaction owns everything — including the membership write — because there is no `on_enter` to do it.
+
+### Same-column drops run positioning only
+
+Reordering a card **within** its current column runs positioning only. Neither `on_enter` nor the `enter_interaction` fires — both represent *entering* a column, and a same-column reorder is not an entry. Only cross-column drops trigger them.
+
+### Atomicity and failure
+
+Interaction validation failure rolls the **whole transaction back** — the membership write included — and re-renders the modal with errors. The move context is preserved, so the user can fix the input and resubmit. Nothing is persisted on failure. Keep side-effects on `deliver_later` (mailers, jobs): a rolled-back failure then sends no stray mail, because the enqueue never commits.
+
+### Success feedback and the response limitation
+
+On success the board's column frames re-render and the modal closes. The interaction's success **message** (`succeed(resource).with_message("Marked as lost")`) is surfaced as a toast.
+
+::: warning Custom success responses are not honored on the drop path
+A drop interaction's custom success *response* — `with_redirect_response`, `with_file_response`, etc. — is **not** honored when it runs from a drop: the board simply re-renders and closes the modal. Keep drop interactions to simple state + extras mutations, and use `.with_message` for feedback.
+:::
+
+There is no card "snap-back" to worry about on cancel — native drag never moves the card's DOM node, so canceling the modal just closes it and the card stays where it was.
+
+---
+
 ## Positioning
 
 By default Plutonium uses decimal fractional positioning: cards always slot exactly where you drop them without ever renumbering the whole column. You need:
@@ -337,11 +441,17 @@ Each column loads at most 25 cards. When the total exceeds the limit, a `+N more
 
 ## Quick-add
 
-When `add: true` (or `role: :backlog`) is set on a column, a `+ Add` button appears in the column header. Clicking it opens the resource's normal new form in a modal, pre-filled with the values that `on_drop` would set.
+When `add: true` (or `role: :backlog`) is set on a column, a `+ Add` button appears in the column header. Clicking it opens the resource's normal new form in a modal.
 
-Authorization: the button is only rendered when `create?` returns `true` in the current policy.
+The record is created normally, and **then** the column's `on_enter` and positioning are applied to the **saved** record — so the new card lands in the clicked column, appended to the bottom. `on_enter` runs against a real, persisted record (exactly as it does for a drag), so `update!`-style callbacks and any side effects behave identically and fire once, on the actual create.
 
-The pre-seeding works by doing a dry-run of `on_drop` against a sentinel record — it intercepts `save!`/`update!` to capture the attribute changes without writing to the database. Exotic `on_drop` callbacks with external side effects (API calls, background jobs) will fire on every `+ Add` click; keep `on_drop` to attribute assignment for clean quick-add behavior.
+::: warning Give your grouping column a default
+Because `on_enter` runs **after** the record is saved, the record must be creatable **without** a grouping value. Give your grouping column (e.g. `status`) a database or model default. If it is `NOT NULL` with no default, quick-add create fails validation before `on_enter` can set it.
+:::
+
+If `on_enter` (or positioning) raises after the record was created, the create is **not** rolled back: the record is kept in its default column (validly positioned there) and the failure is surfaced as a toast.
+
+Authorization: the button is only rendered when `create?` returns `true` in the current policy.
 
 ---
 

data/docs/reference/kanban/authorization.md

@@ -27,6 +27,25 @@ class TaskPolicy < ResourcePolicy
 end
 ```
 
+## Gating a specific transition (`from` / `to` context)
+
+`kanban_move?` is the **single** authorization for every move — plain moves and `enter_interaction:` columns alike. To gate a *specific* transition, read the source and destination columns from the authorization context. They are exposed as the optional `kanban_from` / `kanban_to` policy readers (the `Plutonium::Kanban::Column` objects), and are `nil` for every non-move authorization:
+
+```ruby
+class DealPolicy < ResourcePolicy
+  # Anyone on the team may shuffle cards, but only a manager may move one
+  # INTO "Closed Won".
+  def kanban_move?
+    return user.manager? if kanban_to&.key == :closed_won
+    super
+  end
+end
+```
+
+Rules take no positional arguments in ActionPolicy — the columns arrive via context, which the controller supplies on the `kanban_move?` check (`context: { kanban_from:, kanban_to: }`). This replaces per-column policy methods: an `enter_interaction:` column is authorized by `kanban_move?` too, so there is no separate `mark_lost?`-style predicate to define.
+
+Both `kanban_from` and `kanban_to` are **trustworthy** to authorize on. `to` is where the card ends up; and although `from_column` arrives from the client, the move handler **verifies the record actually resides in the claimed source column** before it proceeds (a mismatch snaps the drag back), so a spoofed or stale `from` can never drive a move past a `kanban_from`-based rule.
+
 ## Read-only board
 
 When `kanban_move?` returns `false` for the current user, the board is rendered read-only. Cards are displayed but dragging is disabled — no drag handles appear and the Stimulus controller does not register drop zones.
@@ -36,14 +55,15 @@ When `kanban_move?` returns `false` for the current user, the board is rendered
 When a card is dropped, the server:
 
 1. Finds the record within the current authorized scope (the same policy `relation_scope` used by the index action).
-2. Calls `authorize_current!(record, to: :kanban_move?)`. A `false` result halts the action with HTTP 403.
-3. Validates the drop against the destination column's `accepts:` policy and `locked:` flag. A rejected drop responds with HTTP 422 and re-renders the source column (the Stimulus controller snaps the card back).
-4. Enforces the destination column's `wip:` limit (cross-column moves only). Exceeding the WIP cap also responds 422.
-5. Calls `on_drop` and repositions the record inside a transaction.
+2. Calls `authorize_current!(record, to: :kanban_move?, context: { kanban_from:, kanban_to: })` — the single authorization for the move (an `enter_interaction:` column rides on this same check, with no policy method of its own). A `false` result halts the action with HTTP 403.
+3. Verifies the record actually resides in the claimed source column (`from_column` is client-supplied). A mismatch responds 422 and snaps the card back — this is what makes `kanban_from` safe to authorize on.
+4. Validates the drop against the destination column's `accepts:` policy and `locked:` flag. A rejected drop responds with HTTP 422 and re-renders the source column (the Stimulus controller snaps the card back).
+5. Enforces the destination column's `wip:` limit (cross-column moves only). Exceeding the WIP cap also responds 422.
+6. Calls `on_enter` and repositions the record inside a transaction.
 
 ## No permitted attributes for moves
 
-Kanban moves do **not** pass through `permitted_attributes_for_update` / `permitted_attributes_for_kanban_move`. The `on_drop` callback is author code that runs with full model access — it is the responsibility of the `on_drop` implementation to assign only the attributes appropriate for a column transition. This is intentional: the callback is trusted Ruby, not user-supplied form data.
+Kanban moves do **not** pass through `permitted_attributes_for_update` / `permitted_attributes_for_kanban_move`. The `on_enter` callback is author code that runs with full model access — it is the responsibility of the `on_enter` implementation to assign only the attributes appropriate for a column transition. This is intentional: the callback is trusted Ruby, not user-supplied form data.
 
 ## Column-level drop policies