plutonium 0.45.3 → 0.47.0

data/docs/superpowers/plans/2026-04-14-plutonium-testing.md.tasks.json

@@ -0,0 +1,21 @@
+{
+  "planPath": "docs/superpowers/plans/2026-04-14-plutonium-testing.md",
+  "tasks": [
+    {"id": 1, "subject": "Create Plutonium::Testing module skeleton and autoload entry", "status": "pending", "planTaskNumber": 1},
+    {"id": 2, "subject": "Implement shared DSL and portal resolution", "status": "pending", "blockedBy": [1], "planTaskNumber": 2},
+    {"id": 10, "subject": "Implement portal-scoped AuthHelpers", "status": "pending", "blockedBy": [2], "planTaskNumber": 3},
+    {"id": 3, "subject": "Implement ResourceCrud concern", "status": "pending", "blockedBy": [2, 10], "planTaskNumber": 4},
+    {"id": 4, "subject": "Implement ResourcePolicy concern", "status": "pending", "blockedBy": [2], "planTaskNumber": 5},
+    {"id": 5, "subject": "Implement ResourceDefinition concern", "status": "pending", "blockedBy": [2, 3], "planTaskNumber": 6},
+    {"id": 6, "subject": "Implement ResourceInteraction concern", "status": "pending", "blockedBy": [1], "planTaskNumber": 7},
+    {"id": 7, "subject": "Implement ResourceModel concern", "status": "pending", "blockedBy": [2], "planTaskNumber": 8},
+    {"id": 8, "subject": "Implement NestedResource concern", "status": "pending", "blockedBy": [2, 10], "planTaskNumber": 9},
+    {"id": 9, "subject": "Implement PortalAccess concern", "status": "pending", "blockedBy": [10], "planTaskNumber": 10},
+    {"id": 11, "subject": "Implement pu:test:install generator", "status": "pending", "blockedBy": [1], "planTaskNumber": 11},
+    {"id": 12, "subject": "Implement pu:test:scaffold generator", "status": "pending", "blockedBy": [1], "planTaskNumber": 12},
+    {"id": 14, "subject": "Write plutonium-testing skill documentation", "status": "pending", "blockedBy": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], "planTaskNumber": 13},
+    {"id": 15, "subject": "Add VitePress docs guide for testing", "status": "pending", "blockedBy": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], "planTaskNumber": 14},
+    {"id": 13, "subject": "Migrate in-repo shared_tests to use Plutonium::Testing concerns", "status": "pending", "blockedBy": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], "planTaskNumber": 15}
+  ],
+  "lastUpdated": "2026-04-14T00:00:00Z"
+}

data/docs/superpowers/specs/2026-04-08-plutonium-skills-overhaul-design.md

@@ -0,0 +1,236 @@
+# Plutonium Skills Overhaul — Design
+
+**Date:** 2026-04-08
+**Status:** Approved (pending user review of this doc)
+
+## Problem
+
+The current Plutonium skills (`.claude/skills/plutonium-*`) are content-correct but
+fail to trigger at the right moments. Concrete failure modes observed in real
+sessions:
+
+1. Agents write `relation_scope` overrides without ever loading `plutonium-policy`,
+   bypassing `default_relation_scope` and breaking entity scoping.
+2. Agents hand-write resource files instead of using `pu:res:scaffold`.
+3. Agents miss cross-cutting concerns (multi-tenancy spans 4 skills; nobody reads 4).
+4. Greenfield onboarding is one-skill-at-a-time as the agent stumbles into mistakes.
+5. The definition concept is split across 3 skills — agents read one and miss the others.
+
+Root cause: skill `description:` fields list **topics** ("authorization, attribute
+visibility, relation scoping..."). Agents triage descriptions against **moments**
+("I am about to write `relation_scope`"). Topic-based descriptions don't fire.
+
+## Goals
+
+1. Skills get invoked at the *moment* an agent is about to make a relevant decision.
+2. The most expensive mistakes live in a fixed 🚨 block at the top of the relevant skill.
+3. Cross-cutting concerns (entity scoping especially) are consolidated and discoverable.
+4. **Generators are the default path.** Every skill that touches a generator-backed
+   concern leads with "use `pu:...`, do not hand-write."
+5. **Greenfield onboarding works.** When an agent starts new work, it loads a bundle
+   of foundational skills upfront via the index skill.
+6. The index skill (`plutonium`) acts as a router AND a greenfield bootstrapper.
+7. Critical workflows are checklists; explanation is prose.
+
+## Non-goals
+
+- Not rewriting prose content wholesale — content is mostly correct.
+- No telemetry/measurement infrastructure.
+- No new code examples beyond what's needed for the 🚨 blocks.
+- No skill renames beyond `plutonium-rodauth → plutonium-auth`.
+
+## Final skill set (20 → 17)
+
+### Merges
+
+| New skill | Absorbs | Rationale |
+|---|---|---|
+| `plutonium-definition` | + `plutonium-definition-actions`, `plutonium-definition-query` | Agents writing a definition need all three; today's split causes "read one, miss two" |
+| `plutonium-auth` (renamed from `plutonium-rodauth`) | + `plutonium-profile` | Profile is a thin layer over rodauth, almost never edited independently |
+| `plutonium-assets` | + `plutonium-theming` | Both are "configure the frontend toolchain" — Tailwind + Stimulus + tokens are one mental model |
+
+### New skill
+
+| Skill | Purpose |
+|---|---|
+| `plutonium-entity-scoping` | Consolidates the entity-scoping/multi-tenancy-specific content currently fragmented across `plutonium-model`, `plutonium-policy`, `plutonium-portal`, and `plutonium-invites`. The single source of truth for: `associated_with` resolution, `default_relation_scope` rules, `relation_scope` override safety, entity strategies (path/custom), and the join-table/grandchild model shapes. |
+
+The four source skills retain their general content but defer to
+`plutonium-entity-scoping` for tenancy specifics via cross-reference.
+
+### Stays separate
+
+`plutonium`, `plutonium-installation`, `plutonium-create-resource`, `plutonium-model`,
+`plutonium-policy`, `plutonium-controller`, `plutonium-interaction`, `plutonium-portal`,
+`plutonium-package`, `plutonium-nested-resources`, `plutonium-invites`,
+`plutonium-forms`, `plutonium-views`.
+
+**Final count: 17 skills** (20 − 3 merges + 1 new − 1 rename effect = 17).
+
+## Skill template
+
+Every skill follows this fixed shape so agents always know where to look:
+
+```markdown
+---
+name: plutonium-<topic>
+description: Use BEFORE <specific verb/construct>. Also when <secondary trigger>. <one-line scope>.
+---
+
+# plutonium-<topic>
+
+## 🚨 Critical (read first)
+- **Use generators, not hand-written files.** `pu:<gen>` — never create <X> manually.
+- **<Top anti-pattern #1>** — one-liner + why.
+- **<Top anti-pattern #2>** — one-liner + why.
+- **Related skills you may also need:** [list with one-line reasons]
+
+## When to use this skill
+Checklist of decision points / code constructs that should trigger loading this skill.
+
+## Quick checklist  (bootstrap + high-traffic skills only)
+Numbered checklist for the most common workflow. Agent can TaskCreate from this.
+
+## <Sections — scaled to topic>
+Prose + code examples.
+
+## Gotchas
+The full anti-pattern list with explanations.
+
+## See also
+Cross-references to related skills.
+```
+
+### Template rules
+
+- **Description starts with `Use BEFORE <verb/construct>`** — verbs and code names,
+  not topic nouns. This is the single biggest triggering fix.
+- **🚨 Critical block is fixed-position** (always right after the H1) and capped at
+  ~5 bullets.
+- **Generator-first** is in the 🚨 block of every skill where a generator exists.
+- **Cross-references in 🚨 are mandatory** — the "Related skills" bullet replaces
+  most of the multi-tenancy discoverability problem.
+- **TOC at top of merged skills** so agents can jump to a section without reading
+  the whole file.
+
+## The index skill (`plutonium`) as router + bootstrapper
+
+```markdown
+---
+name: plutonium
+description: Use BEFORE starting any Plutonium work — new app, new feature, or first edit in an unfamiliar area. Routes you to the right skills and bootstraps greenfield work.
+---
+
+# plutonium
+
+## 🚨 Read this first
+- Plutonium is generator-driven. Almost every file you'd hand-write has a `pu:*`
+  generator. Use it. Hand-written files drift from conventions.
+- For greenfield (new app or substantial new feature), load the **bootstrap bundle**
+  below before writing any code.
+- For targeted edits, use the **router table**.
+- For anything touching tenant scoping, load `plutonium-entity-scoping`.
+
+## Greenfield bootstrap bundle
+Triggers: installing Plutonium, adding the first resource of a new domain, building
+a new portal/package, "set up X from scratch", "build me a Y app".
+
+Load ALL of these before writing code:
+1. `plutonium-installation`
+2. `plutonium-create-resource`
+3. `plutonium-model`
+4. `plutonium-policy`
+5. `plutonium-entity-scoping`   ← new
+6. `plutonium-portal`
+7. `plutonium-definition`
+
+## Router (targeted edits)
+| About to... | Load |
+|---|---|
+| Write/edit a model, add associations | `plutonium-model` |
+| Scope a model to a tenant, write `associated_with`, deal with multi-tenancy | `plutonium-entity-scoping` |
+| Write `relation_scope`, `permitted_attributes`, override a policy | `plutonium-policy` (+ `plutonium-entity-scoping` if scoping) |
+| Add fields, search, filters, custom actions to a resource | `plutonium-definition` |
+| Customize a controller action, hook, redirect | `plutonium-controller` |
+| Encapsulate business logic, multi-step ops | `plutonium-interaction` |
+| Build a custom page, panel, table, layout | `plutonium-views` |
+| Customize forms, field builders, inputs | `plutonium-forms` |
+| Configure Tailwind, Stimulus, design tokens | `plutonium-assets` |
+| Set up Rodauth, accounts, profile pages | `plutonium-auth` |
+| Set up user invitations / membership | `plutonium-invites` (+ `plutonium-entity-scoping`) |
+| Configure parent/child resources, nested routes | `plutonium-nested-resources` |
+| Create a portal or feature package | `plutonium-portal` / `plutonium-package` |
+
+## Generator catalog
+[Table of `pu:*` generators with one-line purpose + which skill covers it.]
+```
+
+## Execution phases
+
+### Phase A — Restructure (mechanical)
+1. Merge `plutonium-definition-actions` + `plutonium-definition-query` into
+   `plutonium-definition` with TOC + sections.
+2. Rename `plutonium-rodauth` → `plutonium-auth`; merge `plutonium-profile` into it.
+3. Merge `plutonium-theming` into `plutonium-assets` with TOC + sections.
+4. Delete merged source skills.
+5. Grep the codebase for references to deleted/renamed skill names; update.
+
+### Phase B — Create `plutonium-entity-scoping`
+- Extract entity-scoping content from `plutonium-model`, `plutonium-policy`,
+  `plutonium-portal`, `plutonium-invites`.
+- Single source of truth for: `associated_with`, `default_relation_scope`,
+  `relation_scope` override safety, entity strategies, and the three model shapes
+  (direct child, join-table, grandchild) with worked examples.
+- Source skills keep general content but link here for tenancy specifics.
+
+### Phase C — Rewrite descriptions (every skill)
+- Format: `Use BEFORE <verb/construct>. Also when <secondary>. <scope>.`
+- Each calls out specific code constructs.
+
+### Phase D — Add 🚨 Critical block to every skill
+- Fixed position (right after H1).
+- ~5 bullets max.
+- Pull existing anti-patterns from gotchas to the top.
+
+### Phase E — Rewrite `plutonium` index skill
+- Bootstrap bundle.
+- Router table.
+- Generator catalog.
+
+### Phase F — Quick checklists
+Add to bootstrap-bundle skills + `plutonium-definition` + `plutonium-entity-scoping`.
+Skip for low-traffic skills.
+
+### Phase G — Cross-references
+- Every tenancy-touching skill links to `plutonium-entity-scoping`.
+- Definition / policy / model get mutual cross-refs.
+- Verify bidirectionality.
+
+## Risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Merged skills are bigger → more tokens per load | TOC at top, section anchors, router tells agent which section to jump to |
+| Renaming `plutonium-rodauth → plutonium-auth` breaks references | Grep + update in Phase A step 5; also update CLAUDE.md if mentioned |
+| Description rewrites are subjective | Same pattern for all (`Use BEFORE <verb>`), reviewed for consistency |
+| `plutonium-entity-scoping` could become a dumping ground | Strict scope: only entity scoping itself. General model/policy stuff stays in source skills. |
+| Source skills' tenancy sections become stubs that drift | Rule: source skill has a 🚨 bullet "for entity scoping, see `plutonium-entity-scoping`" and a one-paragraph teaser, nothing more |
+
+## Out of scope
+
+- New code examples beyond 🚨 blocks and the three model-shape examples in
+  `plutonium-entity-scoping`.
+- Telemetry / measurement.
+- Skill content rewrites beyond what's needed for the new structure.
+- Consolidating below 17 skills.
+
+## Success criteria
+
+1. An agent about to write `relation_scope` loads `plutonium-policy` AND
+   `plutonium-entity-scoping` from description triggering alone.
+2. An agent doing greenfield work loads the bootstrap bundle from a single read of
+   `plutonium`.
+3. Every skill that has a generator mentions "use the generator" in its 🚨 block.
+4. The three model shapes (direct child / join table / grandchild) have worked
+   examples in `plutonium-entity-scoping`.
+5. No skill description starts with a topic noun list; all start with `Use BEFORE`.

data/docs/superpowers/specs/2026-04-14-plutonium-testing-design.md

@@ -0,0 +1,364 @@
+# Plutonium::Testing — Design Spec
+
+**Date:** 2026-04-14
+**Status:** Approved (pre-implementation)
+**Audience:** End-app developers using Plutonium
+
+---
+
+## Goal
+
+Ship `Plutonium::Testing` — a public, opt-in collection of Minitest concerns that give Plutonium app developers default test coverage for resources, policies, definitions, interactions, models, nested scoping, portal access, and authentication. Pair the module with a `plutonium-testing` skill and a Rails generator (`pu:test:scaffold`) that produces ready-to-run test files per (resource × portal) pairing.
+
+## Non-Goals
+
+- RSpec support (Minitest only for first cut).
+- A test data builder / factory layer (out of scope; callers wire their own factories or fixtures).
+- Replacing Plutonium's own internal `test/support/shared_tests/` ahead of the public API landing — the migration is the *last* implementation step and serves as dogfooding.
+
+## Approach
+
+- **Loading model:** opt-in `require "plutonium/testing"` in the consumer's `test/test_helper.rb`. No autoload, no production cost. Mirrors `ActiveSupport::Testing::*` conventions.
+- **Granularity:** one concern per category. Callers `include` exactly what they need. No umbrella module.
+- **DSL + stub methods:** declarative config (`resource_tests_for Post, portal: :admin`) for shape; abstract stub methods (raising `NotImplementedError`) for test data the caller must provide.
+- **Portal-centric:** the `portal:` symbol is the single unit of configuration. It resolves to path prefix, default sign-in helper, expected scoping, and allowed action set by introspecting the mounted portal engine. Same resource × different portal = different test file.
+
+---
+
+## Architecture
+
+### File Layout
+
+```
+lib/plutonium/
+  testing.rb                           # top-level require; loads submodules
+  testing/
+    dsl.rb                             # shared `resource_tests_for` + portal resolution
+    auth_helpers.rb                    # login_as / sign_out / with_portal (portal-aware)
+    resource_crud.rb                   # integration CRUD matrix
+    resource_policy.rb                 # permit? × action × role; relation_scope filtering
+    resource_definition.rb             # fields/inputs/displays/columns/scopes smoke
+    resource_interaction.rb            # interaction outcome assertions
+    resource_model.rb                  # associated_with, SGID, has_cents
+    nested_resource.rb                 # tenant-scoped CRUD + boundary assertions
+    portal_access.rb                   # cross-portal access boundaries
+
+lib/generators/pu/test/
+  install/install_generator.rb         # one-time setup
+  install/templates/plutonium_testing.rb.tt
+  scaffold/scaffold_generator.rb       # per-resource × portal scaffold
+  scaffold/templates/integration_test.rb.tt
+  scaffold/templates/policy_test.rb.tt
+  scaffold/templates/definition_test.rb.tt
+
+test/plutonium/testing/                # tests for the testing module itself
+  dsl_test.rb
+  auth_helpers_test.rb
+  resource_crud_test.rb
+  resource_policy_test.rb
+  resource_definition_test.rb
+  resource_interaction_test.rb
+  resource_model_test.rb
+  nested_resource_test.rb
+  portal_access_test.rb
+
+test/generators/pu/test/
+  install_generator_test.rb
+  scaffold_generator_test.rb
+
+.claude/skills/plutonium-testing/
+  SKILL.md
+
+docs/guides/testing.md
+```
+
+### Loading
+
+`lib/plutonium/testing.rb` is the entry point:
+
+```ruby
+require "plutonium/testing/dsl"
+require "plutonium/testing/auth_helpers"
+require "plutonium/testing/resource_crud"
+require "plutonium/testing/resource_policy"
+require "plutonium/testing/resource_definition"
+require "plutonium/testing/resource_interaction"
+require "plutonium/testing/resource_model"
+require "plutonium/testing/nested_resource"
+require "plutonium/testing/portal_access"
+```
+
+Consumers add `require "plutonium/testing"` to `test/test_helper.rb` (the `pu:test:install` generator does this for them).
+
+---
+
+## DSL
+
+`Plutonium::Testing::DSL` is included by every concern. Provides one class-level method:
+
+```ruby
+resource_tests_for ResourceClass,
+  portal:      :admin,                           # required: portal symbol
+  path_prefix: "/admin",                         # optional: explicit override
+  parent:      :organization,                    # optional: nested-resource parent
+  actions:     %i[index show new create edit update destroy],  # optional: opt-in set
+  skip:        %i[destroy]                       # optional: opt-out individual tests
+```
+
+The portal symbol drives:
+
+| Derived from portal | Example for `:admin` | Example for `:org` |
+|---|---|---|
+| `path_prefix` | `/admin` | `/org/:organization_id` |
+| Default sign-in | admin Rodauth strategy | org-member Rodauth strategy |
+| Expected entity scoping | unscoped | scoped to `@organization` |
+| Allowed action set | from definition | from definition |
+
+DSL stores the current portal in a test-class-local attr; `AuthHelpers` reads it as default when no `portal:` kwarg is given.
+
+### Cross-portal tests
+
+For tests that touch multiple portals (`PortalAccess` concern), `portal:` is an explicit kwarg on helper calls:
+
+```ruby
+login_as(@admin, portal: :admin)
+login_as(@user,  portal: :org)
+with_portal(:org) { get "/org/posts" }    # block form
+```
+
+---
+
+## Concerns
+
+### `Plutonium::Testing::ResourceCrud`
+
+Generates index / show / new / create / edit / update / destroy integration tests against the portal-mounted resource.
+
+**Stubs (caller must implement):**
+```ruby
+def create_resource!         # -> persisted record
+def valid_create_params      # -> Hash for POST
+def valid_update_params      # -> Hash for PATCH
+```
+
+Sign-in is automatic from the portal's auth strategy unless the caller overrides `sign_in_for_tests(account, portal:)`.
+
+### `Plutonium::Testing::ResourcePolicy`
+
+Asserts the `permit?` matrix across action × role and `relation_scope` filtering.
+
+**Stubs:**
+```ruby
+def policy_roles             # -> { admin: -> { @admin }, member: -> { @user } }
+def policy_record            # -> record instance under test
+def policy_matrix            # -> { index: %i[admin member], destroy: %i[admin] }
+```
+
+### `Plutonium::Testing::ResourceDefinition`
+
+Smoke-tests that all registered fields/inputs/displays/columns/scopes/filters render without error against a persisted record. Introspects the definition class via `Plutonium::Definition::DefineableProps`. **No caller stubs required** for the happy path.
+
+### `Plutonium::Testing::ResourceInteraction`
+
+Outcome-assertion helpers for `Plutonium::Resource::Interaction` subclasses.
+
+**Helpers:**
+- `assert_interaction_success(interaction_class, **input)`
+- `assert_interaction_failure(interaction_class, **input)`
+- `assert_interaction_redirect(interaction_class, to:, **input)`
+- `assert_interaction_renders(interaction_class, view:, **input)`
+
+**Stubs:**
+```ruby
+def interaction_class
+def valid_interaction_input
+```
+
+### `Plutonium::Testing::ResourceModel`
+
+Covers `associated_with` scope behavior, SGID routing, and `has_cents` money helpers. DSL flags select which features to test:
+
+```ruby
+resource_tests_for Post, portal: :admin,
+  associated_with: :organization,
+  sgid_routing:    true,
+  has_cents:       %i[price]
+```
+
+Only generates test methods for enabled features.
+
+### `Plutonium::Testing::NestedResource`
+
+Same CRUD matrix as `ResourceCrud` but asserts scope boundaries: index excludes records from sibling tenants; show on a sibling-tenant record returns 404.
+
+**Stubs:**
+```ruby
+def parent_record!           # -> persisted parent/tenant
+def other_parent_record!     # -> a different tenant for boundary tests
+```
+
+### `Plutonium::Testing::PortalAccess`
+
+Cross-portal access boundaries.
+
+**DSL:**
+```ruby
+portal_access_matrix \
+  admin:  %i[admin_portal],
+  member: %i[org_portal storefront_portal]
+```
+
+Asserts unauthorized portals return 403 or redirect to login.
+
+---
+
+## Auth Helpers
+
+`Plutonium::Testing::AuthHelpers` is included transitively by every concern.
+
+**Public API:**
+```ruby
+login_as(account)                    # uses portal from DSL
+login_as(account, portal: :admin)    # explicit override
+sign_out                              # uses portal from DSL
+sign_out(portal: :admin)
+current_account                       # uses portal from DSL
+current_account(portal: :admin)
+with_portal(:org) { ... }            # scoped portal switch
+```
+
+**Implementation:**
+- Looks up the portal's declared auth strategy from the mounted portal engine config.
+- For Rodauth (stock Plutonium): fakes the session cookie directly; no full login round-trip.
+- **Override hook** for non-Rodauth apps: caller defines `sign_in_for_tests(account, portal:)` and `AuthHelpers` defers to it.
+
+The `pu:test:install` generator scaffolds a commented-out override in `test/support/plutonium_testing.rb`.
+
+---
+
+## Generators
+
+### `pu:test:install`
+
+One-time project setup. Idempotent.
+
+- Adds `require "plutonium/testing"` to `test/test_helper.rb` (no-op if present).
+- Creates `test/support/plutonium_testing.rb` with commented-out override stubs for non-Rodauth auth.
+
+### `pu:test:scaffold`
+
+Per-resource scaffold. Produces one file per (resource × portal).
+
+```bash
+rails g pu:test:scaffold Blogging::Post --portals=admin,org
+rails g pu:test:scaffold Blogging::Post --portals=admin --concerns=crud,policy,definition
+rails g pu:test:scaffold Blogging::Post --portals=org --parent=organization --dest=blogging
+```
+
+**Flags:**
+- `--portals=admin,org` (required) — emits one file per portal.
+- `--concerns=crud,policy,definition,nested,model,interaction,portal_access` (default: `crud,policy,definition`).
+- `--parent=organization` — wires `NestedResource` parent stub.
+- `--dest=main_app|package_name` — output destination (matches `pu:res:scaffold` convention).
+
+**Example output** (`test/integration/admin_portal/blogging_posts_test.rb`):
+
+```ruby
+require "test_helper"
+
+class AdminPortal::BloggingPostsTest < ActionDispatch::IntegrationTest
+  include Plutonium::Testing::ResourceCrud
+  include Plutonium::Testing::ResourcePolicy
+  include Plutonium::Testing::ResourceDefinition
+
+  resource_tests_for Blogging::Post, portal: :admin
+
+  setup do
+    @admin = create_admin!       # TODO: replace with your factory
+    login_as(@admin)
+  end
+
+  def create_resource!
+    Blogging::Post.create!(title: "X", body: "...")    # TODO: adjust
+  end
+
+  def valid_create_params
+    { title: "New", body: "..." }                       # TODO: adjust
+  end
+
+  def valid_update_params
+    { title: "Updated" }                                # TODO: adjust
+  end
+
+  def policy_roles
+    { admin: -> { @admin } }                            # TODO: add other roles
+  end
+
+  def policy_record
+    create_resource!
+  end
+
+  def policy_matrix
+    { index: %i[admin], show: %i[admin], create: %i[admin],
+      update: %i[admin], destroy: %i[admin] }           # TODO: tighten
+  end
+end
+```
+
+Stub method bodies are pre-filled with best-guess values from model introspection (column types, associations).
+
+---
+
+## Skill
+
+`.claude/skills/plutonium-testing/SKILL.md` follows the existing skill conventions in `.claude/skills/`.
+
+**Frontmatter `description`:**
+> Use BEFORE writing tests for a Plutonium resource, running `pu:test:scaffold`, or including `Plutonium::Testing::*` concerns. Covers the full testing toolkit: CRUD, policy, definition, interaction, model, nested, portal access, and auth helpers.
+
+**Sections:**
+1. When to use
+2. Quick start (install + scaffold + first run)
+3. DSL reference (`resource_tests_for` keywords + portal resolution table)
+4. Concerns catalog (one section per concern with stub contract + example)
+5. Auth helpers
+6. Generator reference (`pu:test:install`, `pu:test:scaffold` flags)
+7. Customization & escape hatches (non-Rodauth auth, skipping defaults, custom assertions)
+8. Common pitfalls (forgotten stubs, portal mismatch, tenant leakage)
+
+The top-level `plutonium` router skill gets one new entry pointing to `plutonium-testing`.
+
+---
+
+## Docs
+
+`docs/guides/testing.md` mirrors the skill content for human-facing documentation. Linked from the guides section in `docs/.vitepress/config.ts`.
+
+---
+
+## In-Repo Adoption (Dogfooding)
+
+After all concerns and generators land, port the dummy app's tests:
+
+- `test/integration/admin_portal/resources_test.rb` and the other portal test files migrate to `Plutonium::Testing::*` concerns.
+- `test/support/shared_tests/blogging_post_tests.rb` and `catalog_product_tests.rb` are deleted or shrunk to anything that doesn't fit the generic concerns.
+
+Acceptance: zero coverage loss (compare test method counts before/after) and the entire suite still passes across `rails-7`, `rails-8.0`, `rails-8.1` appraisals.
+
+---
+
+## Implementation Sequence
+
+1. Module skeleton + entry point (`lib/plutonium/testing.rb`).
+2. Shared DSL + portal resolution.
+3. Auth helpers.
+4. Each concern (parallelizable after #2 and #3): ResourceCrud, ResourcePolicy, ResourceDefinition, ResourceInteraction, ResourceModel, NestedResource, PortalAccess.
+5. Generators: `pu:test:install`, then `pu:test:scaffold`.
+6. Skill + docs.
+7. In-repo migration (last — dogfoods the public API).
+
+---
+
+## Open Questions
+
+None at design time. Implementation may surface portal-resolution edge cases (engines mounted at non-standard paths, multiple engines per account type) that warrant follow-up.

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.45.0)
+    plutonium (0.45.3)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.45.0)
+    plutonium (0.45.3)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.45.0)
+    plutonium (0.46.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/lib/generators/pu/core/update/update_generator.rb

@@ -12,12 +12,20 @@ module Pu
       def start
         update_gem
         update_npm_package
+        sync_skills_if_present
       rescue => e
         exception "#{self.class} failed:", e
       end
 
       private
 
+      def sync_skills_if_present
+        return unless File.file?(Rails.root.join(".claude", "skills", "plutonium", "SKILL.md"))
+
+        say_status :update, "Syncing Plutonium Claude skills...", :green
+        Rails::Generators.invoke("pu:skills:sync", [], destination_root: Rails.root)
+      end
+
       def update_gem
         say_status :update, "Updating plutonium gem...", :green
         run "bundle update plutonium"