plutonium 0.45.3 → 0.47.0

data/docs/guides/testing.md

@@ -0,0 +1,154 @@
+# Testing
+
+Plutonium ships `Plutonium::Testing` — opt-in Minitest concerns that give your app default test coverage for resources, policies, definitions, interactions, models, nested scoping, portal access, and authentication.
+
+## Quick start
+
+```bash
+# Once per app
+rails g pu:test:install
+
+# Per resource × portal pairing
+rails g pu:test:scaffold Blogging::Post --portals=admin,org
+
+# Run
+bin/rails test
+```
+
+`pu:test:install` adds `require "plutonium/testing"` to `test/test_helper.rb` and creates `test/support/plutonium_testing.rb` (a stub for non-Rodauth auth overrides).
+
+`pu:test:scaffold` produces one test file per (resource × portal) pairing with concerns pre-included and stub method bodies pre-filled with `TODO` markers.
+
+## Anatomy of a test file
+
+```ruby
+# test/integration/admin_portal/blogging_post_test.rb
+require "test_helper"
+
+class AdminPortal::BloggingPostTest < 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!
+    @org = create_organization!
+    @user = create_user!
+    login_as(@admin)
+  end
+
+  # --- ResourceCrud stubs ---
+  def create_resource!; create_post!(user: @user, organization: @org); end
+  def valid_create_params
+    {title: "x", body: "y", status: :draft,
+     user: @user.to_sgid.to_s, organization: @org.to_sgid.to_s}
+  end
+  def valid_update_params; {title: "Updated"}; end
+
+  # --- ResourcePolicy stubs ---
+  def policy_roles; {admin: -> { @admin }}; end
+  def policy_record; create_post!(user: @user, organization: @org); end
+  def policy_matrix
+    {index: %i[admin], show: %i[admin], create: %i[admin],
+     update: %i[admin], destroy: %i[admin]}
+  end
+end
+```
+
+Running this produces 15+ test cases: 7 CRUD + 2 policy + 3 definition + any `skip:` exclusions.
+
+## The DSL
+
+Every concern uses the same class-level method:
+
+```ruby
+resource_tests_for ResourceClass,
+  portal:           :admin,                                # required
+  path_prefix:      "/admin",                              # optional override
+  parent:           :organization,                         # for nested resources
+  actions:          %i[index show new create edit update destroy],
+  skip:             %i[destroy],
+  associated_with:  :organization,                         # ResourceModel only
+  sgid_routing:     true,                                  # ResourceModel only
+  has_cents:        %i[price]                              # ResourceModel only
+```
+
+The **portal symbol** drives path prefix, default auth strategy, and scoping expectations. The resolver walks `Rails.application.routes.routes` for the engine mount — no manual configuration.
+
+## Concerns
+
+| Concern | What it generates | Stubs required |
+|---|---|---|
+| `ResourceCrud` | index/show/new/create/edit/update/destroy | `create_resource!`, `valid_create_params`, `valid_update_params` |
+| `ResourcePolicy` | permit? × role × action matrix + relation_scope smoke | `policy_roles`, `policy_record`, `policy_matrix` |
+| `ResourceDefinition` | definition class + defineable prop smoke | none |
+| `ResourceInteraction` | `assert_interaction_success/failure` helpers | `interaction_class`, `valid_interaction_input` |
+| `ResourceModel` | `associated_with`, SGID, `has_cents` | `model_test_record` |
+| `NestedResource` | nested CRUD + sibling-tenant boundaries | `parent_record!`, `other_parent_record!`, `create_resource!(parent:)` |
+| `PortalAccess` | cross-portal access matrix | `login_as_role`, `portal_root_path` |
+
+Mix and match — `include` only what you want.
+
+## Auth helpers
+
+```ruby
+login_as(account)                    # uses portal from DSL
+login_as(account, portal: :admin)    # explicit override
+sign_out                              # uses portal from DSL
+current_account                       # uses portal from DSL
+with_portal(:org) { ... }            # scoped portal switch
+```
+
+### Non-Rodauth auth
+
+Define `sign_in_for_tests(account, portal:)` in your test class (or in `test/support/plutonium_testing.rb` for project-wide use):
+
+```ruby
+def sign_in_for_tests(account, portal:)
+  # your custom auth flow here
+  post "/your-login", params: {token: account.auth_token}
+end
+```
+
+`AuthHelpers` detects it and defers automatically.
+
+## Generators
+
+### `pu:test:install`
+
+Idempotent. Adds the require line and creates the override stub.
+
+### `pu:test:scaffold`
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--portals=admin,org` | required | Emit one file per portal |
+| `--concerns=...` | `crud,policy,definition` | Subset of concerns to include |
+| `--parent=organization` | none | Wires `NestedResource` parent |
+| `--dest=main_app\|<package>` | `main_app` | Output destination |
+
+Output: `test/integration/<portal>_portal/<resource>_test.rb`.
+
+## Customization
+
+- **Skip individual tests:** `resource_tests_for Klass, portal: :admin, skip: %i[destroy]`
+- **Restrict action set:** `resource_tests_for Klass, portal: :admin, actions: %i[index show]`
+- **Add custom tests:** regular `test "..."` blocks coexist with the generated matrix.
+- **Custom path prefix:** `path_prefix: "/v2/admin"` overrides portal resolution.
+
+## Common pitfalls
+
+- **Forgotten stubs raise `NotImplementedError`** with the stub name — look for the missing method.
+- **Portal mismatch:** `:admin` expects `AdminPortal::Engine`. Pass `path_prefix:` if your engine is named differently.
+- **Tenant leakage in stubs:** for an org portal, `create_resource!` must return a record bound to the test's `@org`.
+- **`policy_record` for tenant-scoped resources** must belong to a tenant the role can access — otherwise even allowed roles see `false`.
+- **Nested resources need `parent:` in the DSL AND a parent record** from `parent_record!`. Both are required for path interpolation.
+- **`PortalAccess` uses `portal_access_for`**, not `resource_tests_for`. Don't mix them on the same class.
+
+## See also
+
+- [Authorization](/guides/authorization) — write the policy this concern verifies
+- [Multi-tenancy](/guides/multi-tenancy) — entity scoping that drives nested-resource tests
+- [Authentication](/guides/authentication) — Rodauth setup behind the default login flow

data/docs/reference/controller/index.md

@@ -93,10 +93,15 @@ build_collection        # Build table component
 ### URL Generation
 
 ```ruby
-resource_url_for(@post)                    # URL for record
-resource_url_for(@post, action: :edit)     # Edit URL
-resource_url_for(Post)                     # Index URL
-resource_url_for(Post, parent: @user)      # Nested index URL
+resource_url_for(@post)                                # URL for record
+resource_url_for(@post, action: :edit)                 # Edit URL
+resource_url_for(Post)                                 # Index URL
+resource_url_for(Post, parent: @user)                  # Nested index URL
+
+# Interactions (sugar over `action: :interactive_*_action, interactive_action: ...`)
+resource_url_for(@post, interaction: :publish)         # Record action
+resource_url_for(Post, interaction: :import)           # Resource (class-level) action
+resource_url_for(Post, interaction: :archive, ids: [1, 2])  # Bulk action
 ```
 
 ## Customization Hooks

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

@@ -0,0 +1,481 @@
+# Plutonium Skills Overhaul Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:subagent-driven-development (recommended) or superpowers-extended-cc:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Restructure all Plutonium skills so they trigger at the right moments, surface critical anti-patterns first, consolidate cross-cutting concerns (especially entity scoping), and enable greenfield bootstrap loading.
+
+**Architecture:** Apply a uniform skill template (description rewrite + 🚨 Critical block + checklist + cross-refs) across all 17 final skills. Merge 3 sets of overlapping skills, create one new `plutonium-entity-scoping` skill, and rewrite the `plutonium` index skill as a router + greenfield bootstrapper.
+
+**Tech Stack:** Markdown skill files in `.claude/skills/<name>/SKILL.md`, plus `CLAUDE.md` updates for any references to renamed skills.
+
+**User Verification:** NO — this is a documentation/skill refactor. The user requested the overhaul and approved the design; no human-in-the-loop validation is required by the spec. Final review happens via normal git diff.
+
+**Spec:** `docs/superpowers/specs/2026-04-08-plutonium-skills-overhaul-design.md`
+
+---
+
+## File map
+
+**Skills to delete (after merge):**
+- `.claude/skills/plutonium-definition-actions/`
+- `.claude/skills/plutonium-definition-query/`
+- `.claude/skills/plutonium-profile/`
+- `.claude/skills/plutonium-theming/`
+
+**Skills to rename:**
+- `.claude/skills/plutonium-rodauth/` → `.claude/skills/plutonium-auth/`
+
+**Skills to create:**
+- `.claude/skills/plutonium-entity-scoping/SKILL.md`
+
+**Skills to modify (every remaining skill):**
+- All 17 final skills get description rewrite + 🚨 Critical block + cross-refs.
+
+**Other files to check:**
+- `CLAUDE.md` (project root) for references to renamed/deleted skills.
+- `.claude/skills/*/SKILL.md` for cross-references to renamed/deleted skills.
+
+---
+
+## Conventions used by every task
+
+**Description format (Phase C):**
+```
+description: Use BEFORE <verb/construct>. Also when <secondary trigger>. <one-line scope>.
+```
+
+**🚨 Critical block format (Phase D), inserted directly after the H1:**
+```markdown
+## 🚨 Critical (read first)
+- **Use the generator.** `pu:<gen>` — never hand-write <X>. <one-line why>.
+- **<Top anti-pattern #1>** — one-line + why.
+- **<Top anti-pattern #2>** — one-line + why.
+- **Related skills:** `plutonium-X` (when Y), `plutonium-Z` (when W).
+```
+
+Cap at ~5 bullets. Pull anti-patterns from existing Gotchas section.
+
+**Commit cadence:** one commit per task. Commit message format:
+`docs(skills): <task summary>`
+
+---
+
+## Task 0: Baseline audit
+
+**Goal:** Capture the current state so later tasks can verify nothing was lost.
+
+**Files:**
+- Read: every `.claude/skills/plutonium-*/SKILL.md`
+- Create: `/tmp/skills-baseline.txt` (line counts + headers index)
+
+**Acceptance Criteria:**
+- [ ] Line count for every current skill recorded
+- [ ] List of all H2 headings per skill recorded
+- [ ] List of all `## Gotchas` / anti-pattern bullets per skill recorded
+- [ ] Identified which skills currently mention entity scoping / `associated_with` / `default_relation_scope` / `relation_scope`
+
+**Verify:** `wc -l /tmp/skills-baseline.txt` → non-zero
+
+**Steps:**
+
+- [ ] **Step 1:** Run `wc -l .claude/skills/plutonium-*/SKILL.md` and save.
+- [ ] **Step 2:** For each skill, extract `^## ` headings via Grep.
+- [ ] **Step 3:** Grep `.claude/skills/` for `associated_with|default_relation_scope|relation_scope|entity scoping|entity_scope` to find every mention. This list seeds Task 5 (entity-scoping extraction).
+- [ ] **Step 4:** Grep `.claude/skills/` and `CLAUDE.md` for `plutonium-rodauth|plutonium-profile|plutonium-theming|plutonium-definition-actions|plutonium-definition-query` to find every cross-reference that will need updating.
+- [ ] **Step 5:** Save all findings to `/tmp/skills-baseline.txt`.
+- [ ] **Step 6:** No commit (audit only).
+
+---
+
+## Task 1: Merge plutonium-definition trio
+
+**Goal:** Fold `plutonium-definition-actions` and `plutonium-definition-query` into `plutonium-definition` as sections, then delete the source skills.
+
+**Files:**
+- Modify: `.claude/skills/plutonium-definition/SKILL.md`
+- Delete: `.claude/skills/plutonium-definition-actions/` (whole directory)
+- Delete: `.claude/skills/plutonium-definition-query/` (whole directory)
+
+**Acceptance Criteria:**
+- [ ] `plutonium-definition/SKILL.md` contains all original content from the three skills, organized into sections: §Fields/Inputs/Displays, §Query (search/filters/scopes), §Actions (custom + bulk).
+- [ ] A TOC at the top with anchor links to each section.
+- [ ] No content from the deleted skills is lost (verify by H2-heading diff against baseline).
+- [ ] `plutonium-definition-actions/` and `plutonium-definition-query/` directories no longer exist.
+
+**Verify:** `ls .claude/skills/ | grep definition` → only `plutonium-definition`
+
+**Steps:**
+
+- [ ] **Step 1:** Read all three current skill files in full.
+- [ ] **Step 2:** Plan the new section order. Use this structure:
+  ```
+  ---
+  name: plutonium-definition
+  description: <will be rewritten in Phase C — leave existing for now>
+  ---
+
+  # Plutonium Definitions
+
+  ## Contents
+  - [Fields, Inputs, Displays](#fields-inputs-displays)
+  - [Query: Search, Filters, Scopes](#query)
+  - [Actions: Custom and Bulk](#actions)
+  - [Gotchas](#gotchas)
+
+  <existing plutonium-definition body, retitled as ## Fields, Inputs, Displays>
+
+  ## Query
+  <full body of plutonium-definition-query, with H2s demoted to H3>
+
+  ## Actions
+  <full body of plutonium-definition-actions, with H2s demoted to H3>
+
+  ## Gotchas
+  <merged gotchas from all three>
+  ```
+- [ ] **Step 3:** Write the merged file via Write.
+- [ ] **Step 4:** Delete the two source directories: `rm -rf .claude/skills/plutonium-definition-actions .claude/skills/plutonium-definition-query`
+- [ ] **Step 5:** Verify with `ls .claude/skills/ | grep definition`.
+- [ ] **Step 6:** Commit: `docs(skills): merge definition-actions and definition-query into plutonium-definition`
+
+---
+
+## Task 2: Merge plutonium-profile into plutonium-rodauth, rename to plutonium-auth
+
+**Goal:** Combine rodauth and profile content into a single `plutonium-auth` skill.
+
+**Files:**
+- Modify: `.claude/skills/plutonium-rodauth/SKILL.md` (will be moved)
+- Delete: `.claude/skills/plutonium-profile/` (whole directory)
+- Rename: `.claude/skills/plutonium-rodauth/` → `.claude/skills/plutonium-auth/`
+
+**Acceptance Criteria:**
+- [ ] All content from `plutonium-rodauth` and `plutonium-profile` lives in `.claude/skills/plutonium-auth/SKILL.md`.
+- [ ] Sectioned: §Rodauth setup · §Account types · §Profile page.
+- [ ] `name:` frontmatter updated to `plutonium-auth`.
+- [ ] TOC at top.
+- [ ] Old directories no longer exist.
+
+**Verify:** `ls .claude/skills/ | grep -E 'auth|rodauth|profile'` → only `plutonium-auth`
+
+**Steps:**
+
+- [ ] **Step 1:** Read both current skill files.
+- [ ] **Step 2:** Construct merged file body with TOC + 3 sections + merged gotchas.
+- [ ] **Step 3:** `mv .claude/skills/plutonium-rodauth .claude/skills/plutonium-auth`
+- [ ] **Step 4:** Write merged content to `.claude/skills/plutonium-auth/SKILL.md`, updating `name: plutonium-auth` in frontmatter.
+- [ ] **Step 5:** `rm -rf .claude/skills/plutonium-profile`
+- [ ] **Step 6:** Verify with `ls .claude/skills/`.
+- [ ] **Step 7:** Commit: `docs(skills): merge plutonium-profile into plutonium-rodauth, rename to plutonium-auth`
+
+---
+
+## Task 3: Merge plutonium-theming into plutonium-assets
+
+**Goal:** Fold theming content into assets as a section.
+
+**Files:**
+- Modify: `.claude/skills/plutonium-assets/SKILL.md`
+- Delete: `.claude/skills/plutonium-theming/`
+
+**Acceptance Criteria:**
+- [ ] `plutonium-assets/SKILL.md` contains all theming content as §Design tokens / theming.
+- [ ] Sectioned: §Tailwind/CSS · §Stimulus registration · §Design tokens & theming.
+- [ ] TOC at top.
+- [ ] `plutonium-theming/` no longer exists.
+
+**Verify:** `ls .claude/skills/ | grep -E 'assets|theming'` → only `plutonium-assets`
+
+**Steps:**
+
+- [ ] **Step 1:** Read both source files.
+- [ ] **Step 2:** Build merged structure with TOC.
+- [ ] **Step 3:** Write merged file.
+- [ ] **Step 4:** `rm -rf .claude/skills/plutonium-theming`
+- [ ] **Step 5:** Verify.
+- [ ] **Step 6:** Commit: `docs(skills): merge plutonium-theming into plutonium-assets`
+
+---
+
+## Task 4: Update cross-references to merged/renamed skills
+
+**Goal:** Find and update every reference to the deleted/renamed skills throughout the repo.
+
+**Files:**
+- Modify: any file matching the grep results from Task 0 step 4.
+- Likely candidates: `CLAUDE.md`, other `.claude/skills/*/SKILL.md`, `docs/`.
+
+**Acceptance Criteria:**
+- [ ] No references remain to `plutonium-rodauth`, `plutonium-profile`, `plutonium-theming`, `plutonium-definition-actions`, `plutonium-definition-query`.
+- [ ] References point to the new names (`plutonium-auth`, `plutonium-definition`, `plutonium-assets`).
+
+**Verify:**
+```bash
+grep -r 'plutonium-rodauth\|plutonium-profile\|plutonium-theming\|plutonium-definition-actions\|plutonium-definition-query' .claude/ CLAUDE.md docs/ 2>/dev/null
+```
+Expected: no output.
+
+**Steps:**
+
+- [ ] **Step 1:** Run the verify grep above.
+- [ ] **Step 2:** For each match, Edit the file to update the reference.
+- [ ] **Step 3:** Re-run grep until empty.
+- [ ] **Step 4:** Commit: `docs(skills): update cross-references after skill merges/renames`
+
+---
+
+## Task 5: Create plutonium-entity-scoping skill
+
+**Goal:** Single source of truth for entity scoping. Extract scoping content from `plutonium-model`, `plutonium-policy`, `plutonium-portal`, `plutonium-invites` and consolidate here. Add worked examples for the three model shapes.
+
+**Files:**
+- Create: `.claude/skills/plutonium-entity-scoping/SKILL.md`
+- Modify (in Task 8 cross-ref pass, not here): the four source skills get a teaser + link.
+
+**Acceptance Criteria:**
+- [ ] Skill exists with the standard template structure.
+- [ ] Description: `Use BEFORE writing relation_scope, associated_with, scoping a model to a tenant, or any multi-tenancy work. Also when configuring entity strategies on a portal. The single source of truth for Plutonium entity scoping.`
+- [ ] 🚨 Critical block lists: never bypass `default_relation_scope`, always declare `associated_with`, use a generator to scaffold scoped resources.
+- [ ] Quick checklist for "scope a new model to a tenant".
+- [ ] Sections: §How entity scoping works · §`associated_with` resolution · §`default_relation_scope` and safe `relation_scope` overrides · §Entity strategies (path, custom) · §Three model shapes (worked examples).
+- [ ] Three model-shape worked examples: (a) direct child `Comment belongs_to :post belongs_to :tenant`, (b) join table `Membership` linking user/tenant, (c) grandchild `Comment` → `Post` → `Tenant`.
+- [ ] Cross-refs to `plutonium-model`, `plutonium-policy`, `plutonium-portal`, `plutonium-invites`.
+
+**Verify:** `cat .claude/skills/plutonium-entity-scoping/SKILL.md | wc -l` → > 100
+
+**Steps:**
+
+- [ ] **Step 1:** Re-read the entity-scoping bits from `plutonium-model`, `plutonium-policy`, `plutonium-portal`, `plutonium-invites` (use the seed list from Task 0 step 3).
+- [ ] **Step 2:** Draft the file using the standard skill template.
+- [ ] **Step 3:** Write the three model-shape examples. Direct child is the existing `Comment/Post` example; for join-table show a `Membership` model with `belongs_to :user, belongs_to :tenant` and `has_one :tenant, through: :membership` on `User`; for grandchild show `Comment.has_one :tenant, through: :post` and how `associated_with` resolves it.
+- [ ] **Step 4:** Write the file.
+- [ ] **Step 5:** Verify line count.
+- [ ] **Step 6:** Commit: `docs(skills): add plutonium-entity-scoping skill`
+
+---
+
+## Task 6: Rewrite descriptions for all 17 skills
+
+**Goal:** Every skill's `description:` frontmatter follows `Use BEFORE <verb/construct>. Also when <secondary>. <scope>.`
+
+**Files:**
+- Modify: frontmatter in all 17 `.claude/skills/plutonium-*/SKILL.md` files.
+
+**Acceptance Criteria:**
+- [ ] Every description starts with "Use BEFORE".
+- [ ] Each description names at least one specific code construct, generator, or file the agent might be about to touch.
+- [ ] No description is a topic-noun list.
+
+**Verify:**
+```bash
+grep -h '^description:' .claude/skills/plutonium-*/SKILL.md | grep -v 'Use BEFORE\|Use when starting\|Use when'
+```
+Expected: empty (or only the index skill, which has its own format).
+
+**Steps:**
+
+- [ ] **Step 1:** For each skill, draft new description using this table as a starting point. **The drafts below are starting points — adjust if reading the skill reveals a more specific trigger.**
+
+| Skill | Draft description |
+|---|---|
+| `plutonium` | `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-installation` | `Use BEFORE installing Plutonium in a Rails app or running pu:install. Also when configuring initial Plutonium setup. Covers generators, gemfile, and initial config.` |
+| `plutonium-create-resource` | `Use BEFORE running pu:res:scaffold or creating any new resource. Also when picking field types for a generator. Covers field syntax and scaffold options.` |
+| `plutonium-model` | `Use BEFORE editing a Plutonium resource model, adding associations, has_cents, SGID, or routing helpers. For tenancy, see plutonium-entity-scoping.` |
+| `plutonium-policy` | `Use BEFORE writing relation_scope, permitted_attributes, permitted_associations, or any policy override. For tenant-scoped relation_scope, also load plutonium-entity-scoping.` |
+| `plutonium-entity-scoping` | (already set in Task 5) |
+| `plutonium-controller` | `Use BEFORE overriding a controller action, adding a hook, or changing redirect logic in a Plutonium controller.` |
+| `plutonium-interaction` | `Use BEFORE writing an interaction class, encapsulating business logic, or building multi-step operations beyond basic CRUD.` |
+| `plutonium-definition` | `Use BEFORE editing a resource definition — adding fields, inputs, displays, search, filters, scopes, custom actions, or bulk actions.` |
+| `plutonium-views` | `Use BEFORE building a custom page, panel, table, layout, or Phlex component in Plutonium.` |
+| `plutonium-forms` | `Use BEFORE customizing a form template, field builder, or input component in Plutonium.` |
+| `plutonium-assets` | `Use BEFORE configuring Tailwind, registering a Stimulus controller, or editing design tokens / theming in a Plutonium app.` |
+| `plutonium-auth` | `Use BEFORE configuring Rodauth, account types, login flows, or building a profile / account settings page.` |
+| `plutonium-invites` | `Use BEFORE setting up user invitations or entity membership in a multi-tenant Plutonium app. Also load plutonium-entity-scoping.` |
+| `plutonium-portal` | `Use BEFORE creating a portal, mounting a portal engine, configuring entity strategies, or routing portal-specific resources.` |
+| `plutonium-package` | `Use BEFORE creating a feature package or portal package, or organizing a Plutonium app into modular engines.` |
+| `plutonium-nested-resources` | `Use BEFORE configuring parent/child resource relationships, nested routes, or scoped URL generation.` |
+
+- [ ] **Step 2:** For each skill, Edit the `description:` line in the frontmatter.
+- [ ] **Step 3:** Run the verify grep.
+- [ ] **Step 4:** Commit: `docs(skills): rewrite descriptions to trigger on verbs and constructs`
+
+---
+
+## Task 7: Add 🚨 Critical block to all 17 skills
+
+**Goal:** Every skill gets a fixed-position 🚨 Critical block right after the H1.
+
+**Files:**
+- Modify: all 17 `.claude/skills/plutonium-*/SKILL.md` files.
+
+**Acceptance Criteria:**
+- [ ] Every skill has `## 🚨 Critical (read first)` as the first H2 after the H1.
+- [ ] Each block contains: generator-first bullet (where applicable), 1-2 top anti-patterns pulled from gotchas, and a "Related skills" bullet with 1-3 cross-refs.
+- [ ] Cap: ~5 bullets per block.
+- [ ] Existing Gotchas sections are kept (not deleted) — top items are duplicated to the 🚨 block.
+
+**Verify:**
+```bash
+for f in .claude/skills/plutonium-*/SKILL.md; do
+  head -30 "$f" | grep -q '🚨 Critical' || echo "MISSING: $f"
+done
+```
+Expected: no output.
+
+**Steps:**
+
+- [ ] **Step 1:** For each skill, read the file and identify (a) does it have a generator? (b) what are the top 1-2 anti-patterns from existing gotchas? (c) which other skills does it relate to?
+- [ ] **Step 2:** Write a 🚨 block following the convention. Example for `plutonium-policy`:
+  ```markdown
+  ## 🚨 Critical (read first)
+  - **Use generators.** `pu:res:scaffold` and `pu:res:conn` create policies — never hand-write policy files.
+  - **Never bypass `default_relation_scope`.** Overriding `relation_scope` with a raw `where(...)` skips entity scoping and leaks tenant data. Always compose with `super` or use `associated_with`.
+  - **Derived actions inherit.** `update?` falls back to `create?` unless overridden — don't duplicate.
+  - **Related skills:** `plutonium-entity-scoping` (for tenant-scoped overrides), `plutonium-model` (for `associated_with`), `plutonium-definition` (for `permitted_attributes` location).
+  ```
+- [ ] **Step 3:** Edit each skill to insert the block after the H1 (before the first existing H2).
+- [ ] **Step 4:** Run the verify loop.
+- [ ] **Step 5:** Commit: `docs(skills): add 🚨 Critical block to every skill`
+
+---
+
+## Task 8: Add cross-references back to source skills (entity-scoping teasers)
+
+**Goal:** Every skill that previously held entity-scoping content now has a one-paragraph teaser + link to `plutonium-entity-scoping`. Prevents drift and content duplication.
+
+**Files:**
+- Modify: `.claude/skills/plutonium-model/SKILL.md`
+- Modify: `.claude/skills/plutonium-policy/SKILL.md`
+- Modify: `.claude/skills/plutonium-portal/SKILL.md`
+- Modify: `.claude/skills/plutonium-invites/SKILL.md`
+
+**Acceptance Criteria:**
+- [ ] Each of the four skills has a "## Entity scoping" section (or similar) that contains: a one-paragraph summary of how that skill relates to entity scoping, and an explicit link to `plutonium-entity-scoping` as the authoritative source.
+- [ ] The 🚨 block of each of these four skills mentions `plutonium-entity-scoping` in the Related bullet.
+- [ ] Long-form scoping content in the source skills is replaced by the teaser + link, OR retained but explicitly marked "see plutonium-entity-scoping for the canonical version".
+
+**Verify:**
+```bash
+for f in plutonium-model plutonium-policy plutonium-portal plutonium-invites; do
+  grep -q 'plutonium-entity-scoping' .claude/skills/$f/SKILL.md || echo "MISSING: $f"
+done
+```
+Expected: no output.
+
+**Steps:**
+
+- [ ] **Step 1:** For each of the four files, find the existing entity-scoping section (using the seed list from Task 0).
+- [ ] **Step 2:** Replace it with a teaser paragraph ending in: `> **For entity scoping details, see the [plutonium-entity-scoping](../plutonium-entity-scoping/SKILL.md) skill — it is the single source of truth.**`
+- [ ] **Step 3:** Verify the 🚨 block (added in Task 7) already lists `plutonium-entity-scoping` as related; if not, add it.
+- [ ] **Step 4:** Run the verify loop.
+- [ ] **Step 5:** Commit: `docs(skills): defer entity-scoping content to plutonium-entity-scoping`
+
+---
+
+## Task 9: Add Quick checklist sections to bootstrap + high-traffic skills
+
+**Goal:** The 7 highest-traffic skills get a "## Quick checklist" section so agents can convert them to tasks via TaskCreate.
+
+**Files (7 skills):**
+- Modify: `.claude/skills/plutonium-installation/SKILL.md`
+- Modify: `.claude/skills/plutonium-create-resource/SKILL.md`
+- Modify: `.claude/skills/plutonium-model/SKILL.md`
+- Modify: `.claude/skills/plutonium-policy/SKILL.md`
+- Modify: `.claude/skills/plutonium-portal/SKILL.md`
+- Modify: `.claude/skills/plutonium-definition/SKILL.md`
+- Modify: `.claude/skills/plutonium-entity-scoping/SKILL.md`
+
+**Acceptance Criteria:**
+- [ ] Each of the 7 skills has a `## Quick checklist` section with a numbered list (5-10 items) describing the most common workflow for that skill.
+- [ ] Checklist items are imperative and concrete (e.g., "Run `pu:res:scaffold` with the appropriate field types"), not vague ("Set up the model").
+- [ ] Section is placed after 🚨 Critical and before the long-form sections.
+
+**Verify:**
+```bash
+for f in plutonium-installation plutonium-create-resource plutonium-model plutonium-policy plutonium-portal plutonium-definition plutonium-entity-scoping; do
+  grep -q '## Quick checklist' .claude/skills/$f/SKILL.md || echo "MISSING: $f"
+done
+```
+Expected: no output.
+
+**Steps:**
+
+- [ ] **Step 1:** For each of the 7 skills, draft a 5-10 item checklist for "the most common workflow." For example, `plutonium-create-resource`'s checklist would be: 1) Pick a portal/dest, 2) Identify field types, 3) Run `pu:res:scaffold ResourceName field:type ...`, 4) Run migrations, 5) Connect to a portal via `pu:res:conn`, 6) Verify with `bin/rails routes | grep <resource>`, 7) Open the portal route in the browser.
+- [ ] **Step 2:** Edit each file to insert the section.
+- [ ] **Step 3:** Run the verify loop.
+- [ ] **Step 4:** Commit: `docs(skills): add Quick checklist sections to bootstrap and high-traffic skills`
+
+---
+
+## Task 10: Rewrite the `plutonium` index skill as router + bootstrapper
+
+**Goal:** The index skill becomes a router table, a greenfield bootstrap bundle, and a generator catalog.
+
+**Files:**
+- Modify: `.claude/skills/plutonium/SKILL.md` (full rewrite)
+
+**Acceptance Criteria:**
+- [ ] Description set per Task 6 table.
+- [ ] 🚨 block at top with generator-first message and bootstrap pointer.
+- [ ] Greenfield bootstrap bundle section listing the 7 foundational skills (installation, create-resource, model, policy, entity-scoping, portal, definition) with explicit triggers.
+- [ ] Router table mapping "About to..." actions to the right skill(s).
+- [ ] Generator catalog: table of `pu:*` generators with one-line purpose + which skill covers it.
+- [ ] Multi-tenancy entries in the router table cross-reference `plutonium-entity-scoping`.
+
+**Verify:**
+```bash
+grep -c 'plutonium-' .claude/skills/plutonium/SKILL.md
+```
+Expected: at least 17 (one mention per other skill).
+
+**Steps:**
+
+- [ ] **Step 1:** Read the spec's full `plutonium` index template (Section 4 in the design doc).
+- [ ] **Step 2:** Run `bin/rails generate --help 2>&1 | grep '^  pu:'` from `test/dummy/` to enumerate generators. If that fails, list them by reading `lib/generators/pu/`.
+- [ ] **Step 3:** Build the generator catalog table.
+- [ ] **Step 4:** Write the full new file body following the template in the spec.
+- [ ] **Step 5:** Verify with the grep.
+- [ ] **Step 6:** Commit: `docs(skills): rewrite plutonium index as router and greenfield bootstrapper`
+
+---
+
+## Task 11: Final verification sweep
+
+**Goal:** Catch any drift, missing pieces, or broken cross-references introduced during the overhaul.
+
+**Files:**
+- Read-only checks across `.claude/skills/`.
+
+**Acceptance Criteria:**
+- [ ] All 17 expected skills exist; no extras.
+- [ ] All 17 skills have a 🚨 block.
+- [ ] All 17 skills have a description starting with "Use BEFORE" (or the index's variant).
+- [ ] No references to deleted/renamed skills anywhere in `.claude/`, `CLAUDE.md`, or `docs/`.
+- [ ] `plutonium-entity-scoping` exists and has the three model-shape examples.
+- [ ] `plutonium` index lists all 17 skills somewhere (router table + bootstrap bundle).
+
+**Verify:**
+```bash
+ls .claude/skills/ | grep -c '^plutonium'      # → 17
+grep -L '🚨 Critical' .claude/skills/plutonium-*/SKILL.md   # → empty
+grep -L '^description: Use BEFORE\|^description: Use when starting' .claude/skills/plutonium-*/SKILL.md   # → empty
+grep -r 'plutonium-rodauth\|plutonium-profile\|plutonium-theming\|plutonium-definition-actions\|plutonium-definition-query' .claude/ CLAUDE.md docs/ 2>/dev/null   # → empty
+```
+
+**Steps:**
+
+- [ ] **Step 1:** Run all four verify commands.
+- [ ] **Step 2:** Fix any failures inline.
+- [ ] **Step 3:** Re-run until all pass.
+- [ ] **Step 4:** Commit (only if fixes were made): `docs(skills): final verification fixes for skills overhaul`
+
+---
+
+## Self-review
+
+- Spec coverage: ✓ all 7 phases (A-G) of the spec map to tasks 1-10; Task 0 is the audit; Task 11 is the final sweep.
+- Placeholder scan: ✓ no TBDs; descriptions table provides starting points but instructs the implementer to adjust based on reading.
+- Type consistency: N/A (no code).
+- Verification requirement scan: NO — no user verification required.
+