plutonium 0.62.2 → 0.64.0

data/docs/superpowers/plans/2026-08-17-async-interactions.md.tasks.json

@@ -0,0 +1,66 @@
+{
+  "planPath": "docs/superpowers/plans/2026-08-17-async-interactions.md",
+  "tasks": [
+    {
+      "id": 0,
+      "subject": "Task 1: Config, migration and registration",
+      "status": "completed",
+      "description": "**Goal:** The plutonium_interaction_runs table exists in a host app when the feature is enabled, following the wizard subsystem's pattern.\n\n**Verify:** bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/runs/configuration_test.rb\n\n```json:metadata\n{\"files\": [\"lib/plutonium/interaction/runs/configuration.rb\", \"db/migrate/interaction_runs/20260817000001_create_plutonium_interaction_runs.rb\", \"lib/plutonium/railtie.rb\", \"lib/plutonium/configuration.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/runs/configuration_test.rb\", \"acceptanceCriteria\": [\"enabled defaults to false\", \"migration path surfaced only when enabled\", \"polymorphic *_id columns are string\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 1,
+      "subject": "Task 2: The Run model",
+      "status": "completed",
+      "blockedBy": [
+        0
+      ],
+      "description": "**Goal:** STI base with state transitions, progress accounting and typed options.\n\n**Verify:** bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/run_test.rb\n\n```json:metadata\n{\"files\": [\"lib/plutonium/interaction/run.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/run_test.rb\", \"acceptanceCriteria\": [\"start!/finish!/fail! move state\", \"progress_fraction nil for opaque work\", \"record_target_failure! accumulates\", \"targeted? reflects perform_on\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 2,
+      "subject": "Task 3: Authorization context and target resolution",
+      "status": "completed",
+      "blockedBy": [
+        1
+      ],
+      "description": "**Goal:** Rebuild (initiator, scoped_entity) in the job and resolve targets through the policy scope. SECURITY CORE \u2014 both failure modes fail open.\n\n**Verify:** bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/runs/context_test.rb\n\n```json:metadata\n{\"files\": [\"lib/plutonium/interaction/runs/context.rb\", \"test/dummy/app/runs/test_post_run.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/runs/context_test.rb\", \"acceptanceCriteria\": [\"targets resolve through the policy scope\", \"cross-tenant target not returned\", \"vanished target reported not dropped\", \"single query\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 3,
+      "subject": "Task 4: Executor and failure policies",
+      "status": "completed",
+      "blockedBy": [
+        2
+      ],
+      "description": "**Goal:** Run the work, honour on_failure (continue/halt/transactional), keep progress current.\n\n**Verify:** bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/runs/executor_test.rb\n\n```json:metadata\n{\"files\": [\"lib/plutonium/interaction/runs/executor.rb\", \"lib/plutonium/interaction/runs/job.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/runs/executor_test.rb\", \"acceptanceCriteria\": [\"continue records and proceeds\", \"halt stops at first error\", \"transactional rolls back\", \"missing targets recorded\", \"opaque run performs once\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 4,
+      "subject": "Task 5: Interactions dispatch",
+      "status": "completed",
+      "blockedBy": [
+        3
+      ],
+      "description": "**Goal:** dispatches_to creates and enqueues a run, then redirects. Outcome stays synchronous.\n\n**Verify:** bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/dispatchable_test.rb\n\n```json:metadata\n{\"files\": [\"lib/plutonium/interaction/concerns/dispatchable.rb\", \"lib/plutonium/interaction/base.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/dispatchable_test.rb\", \"acceptanceCriteria\": [\"run created with validated options\", \"initiator and scoped_entity persisted\", \"success outcome redirects to run\", \"invalid interaction enqueues nothing\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 5,
+      "subject": "Task 6: The run as a resource, and its progress page",
+      "status": "completed",
+      "blockedBy": [
+        4
+      ],
+      "description": "**Goal:** Portal-registerable run resource whose show page is the progress page and refreshes itself while in progress.\n\n**Verify:** bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/runs/policy_test.rb test/integration/admin_portal/interaction_run_progress_test.rb\n\n```json:metadata\n{\"files\": [\"lib/plutonium/interaction/runs/definition.rb\", \"lib/plutonium/interaction/runs/policy.rb\", \"lib/plutonium/ui/interaction/run_progress.rb\", \"test/dummy/packages/admin_portal/config/routes.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/runs/policy_test.rb test/integration/admin_portal/interaction_run_progress_test.rb\", \"acceptanceCriteria\": [\"relation_scope limits to entity scope\", \"cross-tenant run not visible\", \"in-progress page polls, finished does not\", \"indeterminate progress renders a spinner\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 6,
+      "subject": "Task 7: In-progress runs on the target index",
+      "status": "completed",
+      "blockedBy": [
+        5
+      ],
+      "description": "**Goal:** A resource's index lists runs currently working on it, above the collection.\n\n**Verify:** bundle exec appraisal rails-8.1 ruby -Itest test/integration/admin_portal/interaction_run_banner_test.rb\n\n```json:metadata\n{\"files\": [\"lib/plutonium/ui/interaction/running_banner.rb\", \"lib/plutonium/ui/page/index.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/integration/admin_portal/interaction_run_banner_test.rb\", \"acceptanceCriteria\": [\"lists in-progress runs for this resource\", \"excludes completed and other-resource runs\", \"excludes other tenants\", \"no banner when none running\"], \"requiresUserVerification\": false}\n```"
+    }
+  ],
+  "lastUpdated": "2026-08-17T13:42:04.578647"
+}

data/docs/superpowers/specs/2026-07-16-homepage-depth-upgrade-design.md

@@ -0,0 +1,111 @@
+# Homepage Depth & Proof Upgrade — Design
+
+**Date:** 2026-07-16
+**Status:** Approved
+**Scope:** VitePress docs homepage (`docs/index.md` + `docs/.vitepress/theme/components/Home*.vue`)
+
+## Problem
+
+The homepage looks good but undersells the product. Two confirmed weaknesses
+(vs Avo/ActiveAdmin/Administrate, Filament/Refine/AdminJS, and Jumpstart/Bullet Train):
+
+1. **Feature depth is hidden.** Wizards, kanban boards, custom/bulk actions, and
+   multi-tenancy/nesting barely appear. The surface area reads smaller than it is.
+2. **Not enough proof.** Claims outnumber evidence — three CRUD screenshots and one
+   asciinema cast carry the whole page.
+
+Constraint: the overall look (design system, section rhythm, dark-terminal aesthetic)
+stays. No hosted demo. No new screenshot production — reuse existing guide assets.
+
+## Approved changes
+
+New page order:
+
+```
+Hero → Stop writing → Walkthrough → Feature tour (NEW) → Why Plutonium (NEW, merged) → In the box → CTA
+```
+
+### 1. `HomeFeatureTour.vue` (new section)
+
+Slots between `HomeWalkthrough` and the merged band.
+
+- **Heading:** "More than CRUD." Sub: "Four features other frameworks make you
+  build yourself. All declarative. All policy-aware."
+- **Desktop (>768px):** left vertical rail listing the four features, each with a
+  one-line hook; right panel shows the selected feature. Selected rail item gets the
+  accent left-border treatment (matches `--pu-accent`).
+- **Mobile (≤768px):** the rail reflows into an accordion — all four heads always
+  visible, one open at a time, same panel content inside.
+- **Panel anatomy (each feature):**
+  1. File-path caption bar (e.g. `app/definitions/task_definition.rb`)
+  2. DSL code snippet, dark terminal styling (`--pu-bg-dark`), syntax-highlighted
+  3. Real screenshot below the code, reused from `docs/public/images/guides/`
+  4. A one-line "policy-aware" callout: the button/column/step disappears when the
+     policy says no
+  5. "Read the guide →" link to the relevant guide page
+
+| Rail item | Hook | Snippet | Screenshot | Guide link |
+|---|---|---|---|---|
+| Kanban boards | drag-drop from one block | `kanban do … end` column DSL (todo/doing/done, `wip:`, `role:`) | `guides/kanban-board.png` | `/guides/kanban` |
+| Wizards | multi-step flows, branching | trimmed `CompanyOnboardingWizard` (2 steps + `review` + `execute`) | `guides/wizards-step.png` | `/guides/wizards` |
+| Actions & interactions | business logic + auto UI | `action :publish, interaction: PublishPostInteraction` + `def publish? = update? && record.draft?` | `guides/custom-actions-bulk.png` | `/guides/custom-actions` |
+| Multi-tenancy & nesting | scoping, invites, nesting | entity-scoping snippet (`scoped_to_entity` / portal strategy) | `guides/multi-tenancy-dashboard.png` | `/guides/multi-tenancy` |
+
+- Interactivity via a small Vue `ref` for the selected feature (desktop rail and
+  mobile accordion share state). No new dependencies.
+- Note: the wizards guide labels the feature experimental; the tour panel copy should
+  not contradict that (avoid "stable", fine to omit the caveat).
+
+### 2. `HomeWhyPlutonium.vue` (new, replaces `HomePillars` + `HomeAudienceSplit`)
+
+One `pu-section--band` section that merges both messages, cutting a full section of
+page height:
+
+- **Top:** the four pillar cards in compact form — Convention over configuration /
+  It's just Rails / Multi-tenant ready / AI-readable — same icons and card styling
+  as today, tighter padding.
+- **Bottom:** a two-column footer row inside the same section:
+  - "For Rails developers" — existing lede + 2 bullets: "Convention extended to
+    CRUD, policies, and portals" and "Generated code lives in your repo — edit anything"
+  - "For founders & teams" — existing lede + 2 bullets: "Admin panel, signup, and
+    invites on day one" and "Multi-tenant scoping when you need it"
+- `HomePillars.vue` and `HomeAudienceSplit.vue` are deleted; `docs/index.md` updated.
+
+### 3. Copy-only weaves (existing components)
+
+- **`HomeHero.vue`:** pillars line gains **Wizards.** and **Kanban.** in the bold list.
+- **`HomeStopWriting.vue`:** Plutonium win column gains `+ Actions` (accurate — the
+  scaffold ships action wiring).
+- **`HomeInTheBox.vue`:** new fourth category row **Workflows** with three links:
+  Wizards (`/guides/wizards`), Kanban (`/guides/kanban`), Interactions
+  (`/guides/custom-actions` — there is no separate interactions guide).
+
+### 4. Out of scope
+
+- Hosted live demo
+- New screenshot/asset production
+- Full-spine restructure (each feature as a full-width alternating panel) —
+  considered and superseded by the rail-tour + tightened-middle structure
+- Credibility signals (testimonials, star counts) and quantified-value claims —
+  explicitly not the weak spots being addressed
+
+## Error handling / edge cases
+
+- Screenshots must be referenced with `withBase(...)` like existing components.
+- Rail/accordion is progressive: SSR renders the first feature expanded so the
+  section is meaningful without JS.
+- Accordion heads are `<button>`s with `aria-expanded`; rail follows the existing
+  `role="tablist"` pattern used by `HomeCta.vue` pills.
+
+## Testing / verification
+
+- `yarn docs:dev` visual pass at desktop and ≤768px widths (rail ↔ accordion reflow).
+- `yarn docs:build` must pass (dead-link check catches wrong guide paths).
+- Verify all four screenshots resolve under the site base path in the built output.
+
+## Decisions log
+
+- Tour layout: feature rail (chosen over tabbed showcase) — breadth visible at a glance
+- Mobile: accordion (chosen over horizontal pill strip) — same breadth rationale
+- Phase 2 pulled forward, resolved as structure A: rail tour + merged middle band
+  (chosen over full-spine panels)

data/docs/superpowers/specs/2026-07-17-action-html-attributes-design.md

@@ -0,0 +1,124 @@
+# Native `link:` / `button:` HTML attributes on actions
+
+**Date:** 2026-07-17
+**Status:** Approved (design)
+
+## Problem
+
+On released Plutonium (≤0.62.2) there is no native way to put `target`, `rel`, or
+arbitrary HTML attributes on an action's rendered control. `Action::Base` reads a
+fixed key set in `initialize`, so any extra option passed to an action is silently
+inert — not stored, never rendered. `ActionButton`'s three render paths
+(`render_link`, `render_button`, `render_dropdown_item`) hardcode their attributes.
+
+Concrete need: an action that opens an external link in a new tab
+(`target: "_blank" rel: "noopener noreferrer"`), or that carries custom
+`data-*` / `aria-*` attributes.
+
+## API
+
+Two target-named attribute bags on the action DSL, each naming the **element**
+it applies to. No merged/"always" bag — `link:` covers every anchor rendering
+and `button:` covers the button_to form, so per-element bags cover everything
+with no "which element?" ambiguity.
+
+The element rule, not HTTP method, decides which bag applies: dropdown items
+are anchors even for non-GET actions (they submit via `data-turbo-method`), so
+`link:` applies to them regardless of method, and `button:` applies only to the
+toolbar's button_to rendering. A non-GET action that needs attributes in both
+placements sets both bags.
+
+```ruby
+action :docs,
+  link:   { target: "_blank", rel: "noopener noreferrer", data: { analytics: "docs" } },
+  button: { data: { turbo_confirm: "Sure?" } }
+```
+
+- **`link:`** → every `<a>` rendered for the action: the GET toolbar link,
+  dropdown items (any method), bulk-actions toolbar links, kanban column
+  action links, and the grid/kanban card's hidden show anchor (for `:show`).
+- **`button:`** → the `button_to` **`<form>`** element, in `render_button` (non-GET),
+  via `button_to`'s `form:` option. The form wrapper, not the inner `<button>`.
+- Both default to `{}`. `target`/`rel` are just keys inside `link:` — no first-class
+  sugar, nothing special-cased.
+
+## Storage — `Action::Base`
+
+- New ivars `@link` / `@button` in `initialize`, each normalized on the way in:
+  the action stores its **own deep-symbolized copy** of the bag (never freezing
+  or sharing the caller's hash), structurally deep-frozen. Symbolizing is
+  load-bearing: the render-time `deep_merge` matches keys exactly, so a
+  string-keyed bag would sit *alongside* the framework's symbol keys and emit
+  duplicate attributes (browser keeps the first — the framework's) instead of
+  overriding. Any non-Hash value — including `false` — raises `ArgumentError`.
+- Matching `attr_reader :link, :button`, plus the merge points
+  `link_attributes(base)` / `button_attributes(base)`: rendering surfaces hand
+  the framework-built attribute hash to the action, which deep-merges its bag
+  over it (author wins). Surfaces never merge the raw bags themselves.
+- Both added to `to_options` so `with(**overrides)` round-trips them (miss this and
+  `.with` silently drops them — the one non-negotiable).
+- `Action::Interactive` already forwards `**options` to `super`, so the bags flow
+  through interactive actions automatically. No change needed there.
+- Verify during implementation that the definition-level `action` /
+  `interactive_action` DSL forwards unknown kwargs into the action constructor
+  (it splats `**options` into `Action::Simple.new` / `Interactive::Factory.create`,
+  so it should — confirm, don't assume).
+
+## Rendering
+
+Merge rule everywhere: build the framework's attribute hash as the base, then
+hand it to the action's merge point (`action.link_attributes(base)` /
+`action.button_attributes(base)`) — **the author wins on every key**,
+recursively through nested `data`. This gives authors full control (they can
+override `turbo_frame`, `class`, `data-*`, anything) at their own risk.
+
+Surfaces funnelling through the merge points:
+
+- **`ActionButton#render_link`** — base
+  `{ class: button_classes, data: { turbo_frame: … }.merge(@extra_data) }`
+  through `link_attributes`, passed to `link_to`.
+- **`ActionButton#render_dropdown_item`** — the existing `link_attrs` hash
+  through `link_attributes` before `a(**…)`. Applies to any method — dropdown
+  items are anchors; `button:` never applies here.
+- **`ActionButton#render_button`** — the `form:` option hash passed to
+  `button_to` through `button_attributes`. So `button: { target: "_top" }` sets
+  the form's target; `button: { data: { … } }` deep-merges into the form's data.
+- **`BulkActionsToolbar#render_action_button`** — the bulk-action anchor's
+  attrs through `link_attributes`.
+- **`Kanban::Column#column_action_link_attributes`** — the column-action
+  anchor's attrs through `link_attributes` (of the registered action).
+- **`Grid::Card#render_show_link`** — the hidden row-click show anchor's attrs
+  through the `:show` action's `link_attributes`.
+
+## Tests
+
+- `test/plutonium/action/base_test.rb`:
+  - `link` / `button` readers default to `{}` and return what was passed.
+  - `to_options` includes both bags; `with(link: …)` round-trips and overrides.
+- `ActionButton` rendering tests:
+  - `link:` attributes (`target`, `rel`, custom `data-*`) land on the `<a>` in the
+    GET-link and dropdown renderings.
+  - `button:` attributes land on the `<form>` in the non-GET rendering.
+  - Author wins on collision: an author `data.turbo_frame` overrides the
+    framework's.
+
+## Scope guard (out)
+
+- No third "always" / `html:` bag.
+- No attribute-name validation — authors own their HTML; a bad attribute is their
+  problem. (Container shape IS validated: a non-Hash bag raises; keys are
+  symbolized so string-keyed bags can't silently lose the merge.)
+- No per-element targeting *within* a rendering (e.g. the inner `<button>` vs the
+  `<form>`) — `button:` targets the form only. Can be extended later if needed.
+
+## Known footguns (documented, accepted)
+
+- `deep_merge` only recurses when **both** values are hashes: an author scalar
+  `data:` (`button: { data: "x" }`) wholesale-replaces the framework's data hash,
+  deleting `turbo_confirm`/`turbo_frame`. Pass `data:` as a hash. Same mechanics
+  mean `class:` **replaces** the framework's classes (no token append) — that's
+  the author-wins contract working as designed.
+- `button:` lands on the `<form>` wrapper, not the visible `<button>`: click-
+  element attributes (`aria-label`, `class` for the control) don't reach the
+  button element. Documented in the guide; per-element targeting is the
+  deferred extension above.