plutonium 0.49.1 → 0.51.0

data/docs/superpowers/specs/2026-05-12-skill-compaction-design.md

@@ -0,0 +1,99 @@
+# Skill Compaction & Consolidation Design
+
+**Date:** 2026-05-12
+**Status:** Approved (pending implementation)
+
+## Problem
+
+The `.claude/skills/` directory currently holds 19 Plutonium skills totaling ~7,846 lines. Several issues:
+
+- Skills are too verbose for a stable-API framework. Plutonium rarely changes shape, so re-explaining concepts has little ROI.
+- Several skills are read together for any non-trivial task (e.g. create-resource + model + definition). Loading them separately wastes context.
+- Some skills duplicate content (Rails-isms, philosophy preambles, repeated DSL explanations).
+
+Skills are written for **developers using the framework**, not for first-time Rails users. They should read like reference + decision rules, not tutorials.
+
+## Goals
+
+1. Reduce total skill volume by ~45% (target: ~4,150 lines from 7,846).
+2. Merge skills that are almost always loaded together.
+3. Keep skills self-contained with inline code examples (chosen over linking to `test/dummy`).
+4. Preserve high-value reference material (option/DSL/field tables).
+
+## Non-Goals
+
+- Restructuring user-facing `docs/` site.
+- Changing the framework API.
+- Splitting examples into separate files outside the skill.
+
+## Target Skill Map
+
+From 19 skills to 8:
+
+| New skill | Merges | Est. lines |
+|---|---|---|
+| `plutonium` | (router, kept) | ~150 |
+| `plutonium-app` | installation + portal + package | ~600 |
+| `plutonium-resource` | create-resource + model + definition | ~800 |
+| `plutonium-behavior` | controller + policy + interaction | ~700 |
+| `plutonium-ui` | views + forms + assets | ~700 |
+| `plutonium-auth` | (kept, compacted) | ~350 |
+| `plutonium-tenancy` | entity-scoping + nested-resources + invites | ~600 |
+| `plutonium-testing` | (kept, compacted) | ~250 |
+
+**Total: ~4,150 lines.**
+
+### Rationale per merge
+
+- **plutonium-app** — installation, portal creation, and package creation are the setup arc. Always done together on a new app.
+- **plutonium-resource** — model declarations, scaffold options, and definition DSL are the core "build a resource" workflow.
+- **plutonium-behavior** — controllers, policies, and interactions form the request/authorization/business-logic layer.
+- **plutonium-ui** — views, forms, and assets all touch presentation. Assets covers the toolchain backing both views and forms.
+- **plutonium-tenancy** — entity-scoping is the core mechanic; nested-resources and invites are both consumers of that mechanic.
+- **plutonium-auth** stays solo at the user's request (rodauth/profile is distinct enough from tenancy/invites).
+- **plutonium-testing** stays solo (orthogonal concern, loaded only for test work).
+
+## Compaction Rules
+
+Applied to every skill during merge.
+
+**Cut:**
+- Rails/Ruby basics — assume reader knows Rails.
+- Philosophy/motivation preambles.
+- Duplicated content across merged skills (one canonical location per concept).
+- Verbose prose where a 10-line snippet shows the same thing.
+- Marketing copy ("Plutonium gives you...").
+
+**Keep:**
+- Decision rules ("use X when…, Y when…").
+- Non-obvious gotchas and constraints.
+- Short canonical inline snippets.
+- **Option/field/DSL tables** — high-value reference, kept verbatim.
+- Cross-references to other skills via `[[plutonium-resource]]` style links.
+
+## Format per merged skill
+
+1. **Header paragraph** — what this covers + when to load.
+2. **Sub-sections per merged topic** — each with: decision rules → minimal inline example → gotchas → tables (where applicable).
+3. **Cross-references** at bottom.
+
+## Rollout
+
+1. **Pilot:** `plutonium-resource` first (largest, hardest — biggest signal on whether the template works).
+2. **Review pilot together** — adjust template if needed.
+3. **Apply pattern** to the remaining merges. One PR per merged skill OR all-in-one (TBD with user).
+4. **Update `plutonium` router skill** last — it references the new names.
+5. **Delete old skill directories** only after the new one lands.
+
+Skills require a gem release to take effect for users (per `CLAUDE.md`), so this ships as a single release regardless of how PRs are split.
+
+## Risks
+
+- **Loss of granularity for context loading** — a single merged skill loads more tokens even when only one sub-topic is needed. Mitigated by aggressive compaction (loose budget but still much smaller than today's biggest individual skills).
+- **Cross-references breaking** — the `plutonium` router skill and any external references must update at the same time as the merge.
+- **Drift from `docs/`** — the user-facing docs site may still reference old skill structure; out of scope for this spec but worth noting.
+
+## Open Questions
+
+- Should the merge land as one PR or eight? (Deferred to rollout time.)
+- Are there external references to the old skill names (other repos, marketplace listings) that need updating?

data/docs/superpowers/specs/2026-05-13-docs-restructure-design.md

@@ -0,0 +1,186 @@
+# Docs Restructure & Compaction Design
+
+**Date:** 2026-05-13
+**Status:** Draft — awaiting approval
+
+## Problem
+
+Following the skill consolidation (19 → 8 skills, ~37% volume cut), the `docs/` site is misaligned in two ways:
+
+1. **Reference structure** mirrors the OLD skill structure (separate `model/`, `definition/`, `policy/`, `controller/`, `interaction/`, `views/`, `assets/`, `portal/`, `generators/`). It should mirror the new 7 functional areas.
+2. **Concept/task split is muddled.** Some "guides" are really concept explanations (e.g. `guides/authorization.md` overlaps `reference/policy/`). Some concepts have NO reference home (auth, tenancy, testing — they live in `guides/` only).
+
+## Goals
+
+**Primary goal: quality.** Volume reduction is incidental.
+
+1. Restructure `reference/` to mirror the 7 functional areas from the skill consolidation — so readers can predict where to look.
+2. Establish a clean role split: **guides = task recipes ("how do I X")**, **reference = concept lookup ("what does X do")**. Some duplication is fine when framed as different entry points; tables of options live in ONE place.
+3. Improve every page on these axes:
+   - **Right place** — concepts in reference, recipes in guides.
+   - **Right structure** — 🚨 callouts at top for "you'll regret this" rules; option/decision tables for scannability; decision rules over generic exhortations.
+   - **Right content** — keep WHY explanations that help reason about edge cases; cut marketing copy and empty "best practices" exhortations; verify technical accuracy as we go (the skill work caught real bugs — same energy).
+4. Light pass on the tutorial — preserve narrative flow; improve clarity where prose is unclear.
+
+## Non-Goals
+
+- Restructuring `getting-started/` navigation (the tutorial arc stays).
+- Changing VitePress theme, search provider, or build pipeline.
+- Adding new content beyond reorganizing what exists.
+
+## Current state
+
+40 markdown files, ~13,222 lines.
+
+| Area | Files | Notes |
+|---|---|---|
+| `getting-started/` | 11 | Index + installation + 8-step tutorial. Narrative learning arc. |
+| `guides/` | 14 | Task-oriented but inconsistent — some concept-heavy. |
+| `reference/` | 16 | Concept-by-concept, mirrors the OLD skill structure. |
+
+## Target reference structure (mirrors 7 skill areas)
+
+```
+reference/
+├── index.md          ← rewritten overview, links to the 7 areas
+├── app/
+│   ├── index.md      ← installation, configuration
+│   ├── packages.md   ← feature + portal packages
+│   ├── portals.md    ← portal engines, mounting, route registration
+│   └── generators.md ← full generator catalog
+├── resource/
+│   ├── index.md      ← overview, the 4 layers
+│   ├── model.md      ← `Plutonium::Resource::Record`, has_cents, SGID, routing (merges current model/)
+│   ├── definition.md ← field/input/display/column, page chrome (merges current definition/index + fields)
+│   ├── query.md      ← search, filters, scopes, sort
+│   └── actions.md    ← custom + bulk actions
+├── behavior/
+│   ├── index.md      ← overview, the controller/policy/interaction trio
+│   ├── controllers.md ← hooks, key methods, presentation
+│   ├── policies.md   ← actions, permitted attributes, associations, relation_scope
+│   └── interactions.md ← structure, outcomes, chaining, URL generation
+├── ui/
+│   ├── index.md      ← overview
+│   ├── pages.md      ← IndexPage/ShowPage/NewPage/EditPage, hooks
+│   ├── forms.md      ← field builder, layouts, theming, association inputs (current views/forms.md)
+│   ├── displays.md   ← Display class, custom rendering
+│   ├── tables.md     ← Table class, customization
+│   ├── components.md ← component kit, custom Phlex components
+│   ├── layouts.md    ← shell, eject, ResourceLayout
+│   └── assets.md     ← Tailwind config, Stimulus, design tokens, .pu-* classes (current assets/)
+├── auth/             ← NEW (currently only in guides/)
+│   ├── index.md      ← Rodauth overview
+│   ├── accounts.md   ← basic, admin, SaaS account types
+│   └── profile.md    ← profile resource, SecuritySection
+├── tenancy/          ← NEW (currently spread across guides/)
+│   ├── index.md      ← overview, three pieces (portal/policy/model)
+│   ├── entity-scoping.md ← associated_with, three model shapes
+│   ├── nested-resources.md ← parent/child routes, scoping
+│   └── invites.md    ← invitation system
+└── testing/          ← NEW (currently only in guides/)
+    ├── index.md
+    ├── crud.md
+    ├── policy.md
+    ├── nested.md
+    ├── portal-access.md
+    └── auth-helpers.md
+```
+
+### Content migrations
+
+| Current file | Goes to |
+|---|---|
+| `reference/model/index.md` + `features.md` | `reference/resource/model.md` |
+| `reference/definition/index.md` + `fields.md` | `reference/resource/definition.md` |
+| `reference/definition/query.md` | `reference/resource/query.md` |
+| `reference/definition/actions.md` | `reference/resource/actions.md` |
+| `reference/controller/index.md` | `reference/behavior/controllers.md` |
+| `reference/policy/index.md` | `reference/behavior/policies.md` |
+| `reference/interaction/index.md` | `reference/behavior/interactions.md` |
+| `reference/views/index.md` | split → `pages.md`, `displays.md`, `tables.md`, `components.md`, `layouts.md` |
+| `reference/views/forms.md` | `reference/ui/forms.md` |
+| `reference/assets/index.md` | `reference/ui/assets.md` |
+| `reference/portal/index.md` | `reference/app/portals.md` |
+| `reference/generators/index.md` | `reference/app/generators.md` |
+| `getting-started/installation.md` | concept part → `reference/app/index.md`; task part stays |
+| `guides/authentication.md` | concept part → `reference/auth/index.md` + `accounts.md`; recipe stays |
+| `guides/user-profile.md` | concept part → `reference/auth/profile.md`; recipe stays |
+| `guides/multi-tenancy.md` | concept part → `reference/tenancy/entity-scoping.md`; recipe stays |
+| `guides/nested-resources.md` | concept part → `reference/tenancy/nested-resources.md`; recipe stays |
+| `guides/user-invites.md` | concept part → `reference/tenancy/invites.md`; recipe stays |
+| `guides/testing.md` | concept part → `reference/testing/*`; recipe stays |
+| `guides/creating-packages.md` | concept part → `reference/app/packages.md`; recipe stays |
+
+## Guides restructure
+
+Each guide becomes a clean **task recipe**:
+
+- Single goal stated at the top ("Add authentication to your app")
+- Numbered step-by-step
+- Each step links to the relevant reference page for "why" and "what else"
+- No exhaustive option tables (those live in reference)
+- ~50-150 lines each, down from ~300-600
+
+Keep the 14 guides at their current paths so external links don't break.
+
+## Editing principles (quality-first)
+
+Not "cut everything"; cut what doesn't earn its keep. Specifically:
+
+**Cut:**
+- Marketing copy ("Plutonium is awesome because…").
+- Empty "best practices" exhortations ("write clean code", "test your code").
+- Content duplicated across pages — one canonical home + cross-link.
+- Verbose prose where a 10-line snippet shows the same thing.
+- Rails-101 explanations that don't set up a Plutonium twist.
+
+**Keep — and add more of:**
+- **WHY explanations** that help readers reason about edge cases.
+- **Non-obvious gotchas** — the dangerous-default stuff that bites people.
+- **Decision rules** ("use X when you need Y") over generic exhortations.
+- **Option / field / DSL tables** — readers scan them, they don't read prose.
+- **Inline code examples** that work — copy-pasteable, no `...` stand-ins.
+- **🚨 callouts at top of each page** for the "you'll regret this" rules.
+
+**Verify as we go.** The skill work caught real bugs (auto-detection rules, association input behavior, action visibility flags, `views` DSL naming). Same energy here — when prose claims X, check the source.
+
+## Tutorial compaction pass
+
+Same cuts as above, but preserve:
+
+- Step structure (1-8 stays)
+- Narrative flow (one step builds on the next)
+- Frequent "expected output" / "verify" callouts
+- Screenshots and visuals (keep all references)
+
+Target: 10-20% volume reduction without losing pedagogical value.
+
+## VitePress sidebar rewrite
+
+`.vitepress/config.ts` sidebar rewritten for the new structure. Three sidebars:
+
+- `/getting-started/` — unchanged
+- `/guides/` — same 14 entries, reorganized into the 7 functional groups
+- `/reference/` — new 7-area structure
+
+## Rollout
+
+1. **Pilot one reference area** — pick `reference/resource/` (largest, most-read). Build it from scratch using the merged skills as the template. Get user feedback on shape.
+2. **Build out the other 6 areas** — one at a time or in parallel, your call.
+3. **Move concept content** from guides into reference. Hollow guides become recipes.
+4. **Tutorial compaction pass** — minimal, last.
+5. **Rewrite VitePress sidebar** — once all paths exist.
+6. **Delete old reference directories** — `model/`, `definition/`, `policy/`, etc. — in one sweep after everything's in place.
+7. **Build the site locally** — verify no dead links, search index regenerates cleanly.
+
+## Risks
+
+- **External links break.** GitHub PRs, blog posts, Stack Overflow answers may link to `reference/model/`, `reference/definition/actions`, etc. Mitigation: VitePress supports redirects, OR keep stub pages that redirect via meta refresh. Cheap to add.
+- **Guides ↔ reference duplication drifts.** If a recipe and its reference page describe the same option differently, readers get confused. Mitigation: linting (no duplicate DSL/option tables across guide + reference).
+- **Volume isn't the metric.** Some pages will get longer (currently underdeveloped topics: tenancy, testing, profile). Some will get shorter. The win is navigability and clarity, not line count.
+
+## Open questions
+
+- Add `.vitepress` redirect configuration for old reference paths? (Recommended: yes, low cost.)
+- Should `reference/app/generators.md` be the full catalog or a per-area split? (Recommended: full catalog — it's reference, scannability matters.)
+- Are there guides that should be **deleted entirely** because they're 100% concept overlap with reference? (Decide after pilot.)

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.49.0)
+    plutonium (0.50.0)
       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.49.0)
+    plutonium (0.50.0)
       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.49.0)
+    plutonium (0.50.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/lib/generators/pu/core/install/templates/config/initializers/plutonium.rb

@@ -3,5 +3,6 @@
 Plutonium.configure do |config|
   config.load_defaults 1.0
 
+  config.shell = :modern
   # Configure plutonium above.
 end

data/lib/generators/pu/invites/install_generator.rb

@@ -70,6 +70,7 @@ module Pu
       end
 
       def create_package
+        return if File.exist?(File.join(destination_root, "packages/invites"))
         generate "pu:pkg:package", "invites"
       end
 

data/lib/generators/pu/lite/rails_pulse/rails_pulse_generator.rb

@@ -70,21 +70,70 @@ module Pu
 
       def setup_recurring_tasks
         recurring_file = "config/recurring.yml"
-        return unless File.exist?(File.expand_path(recurring_file, destination_root))
+        full_path = File.expand_path(recurring_file, destination_root)
+        return unless File.exist?(full_path)
         return if file_includes?(recurring_file, "rails_pulse")
 
-        recurring_tasks = <<~YAML
+        content = File.read(full_path)
+        env_keys = %w[production development staging test]
+        env_scoped = content.lines.any? { |l| l.match?(/^(#{env_keys.join("|")}):\s*$/) }
 
+        if env_scoped
+          create_file recurring_file, inject_rails_pulse_under_envs(content, env_keys), force: true
+        else
+          append_to_file recurring_file, "\n" + rails_pulse_tasks_yaml(0)
+        end
+      end
+
+      def rails_pulse_tasks_yaml(indent)
+        pad = " " * indent
+        <<~YAML.gsub(/^(?=.)/, pad)
           rails_pulse_summary:
             class: RailsPulse::SummaryJob
-            schedule: "5 * * * *" # 5 minutes past every hour
+            queue: default
+            schedule: every hour at minute 5
+            description: "Roll up Rails Pulse raw records into summary tables"
 
           rails_pulse_cleanup:
             class: RailsPulse::CleanupJob
-            schedule: "0 1 * * *" # Daily at 1am
+            queue: default
+            schedule: every day at 1am
+            description: "Archive/purge old Rails Pulse data"
         YAML
+      end
+
+      def inject_rails_pulse_under_envs(content, env_keys)
+        lines = content.lines
+        env_re = /^(#{env_keys.join("|")}):\s*$/
+
+        env_starts = lines.each_with_index.select { |l, _| env_re.match?(l) }.map(&:last)
+
+        env_starts.reverse_each do |start|
+          end_idx = lines.length
+          ((start + 1)...lines.length).each do |i|
+            if lines[i].match?(/^[^\s#]/)
+              end_idx = i
+              break
+            end
+          end
+
+          indent = 2
+          ((start + 1)...end_idx).each do |i|
+            if (m = lines[i].match(/^(\s+)\S/))
+              indent = m[1].length
+              break
+            end
+          end
+
+          insert_at = end_idx
+          while insert_at > start + 1 && lines[insert_at - 1].strip.empty?
+            insert_at -= 1
+          end
+
+          lines.insert(insert_at, "\n", rails_pulse_tasks_yaml(indent))
+        end
 
-        append_to_file recurring_file, recurring_tasks
+        lines.join
       end
     end
   end

data/lib/plutonium/action/base.rb

@@ -16,7 +16,7 @@ module Plutonium
     # @attr_reader [Symbol, nil] category The category of the action.
     # @attr_reader [Integer] position The position of the action within its category.
     class Base
-      attr_reader :name, :label, :description, :icon, :route_options, :confirmation, :turbo, :turbo_frame, :color, :category, :position, :return_to
+      attr_reader :name, :label, :description, :icon, :route_options, :confirmation, :turbo, :turbo_frame, :color, :category, :position, :return_to, :modal
 
       # Initialize a new action.
       #
@@ -57,6 +57,8 @@ module Plutonium
         @resource_action = options[:resource_action] || false
         @category = ActiveSupport::StringInquirer.new((options[:category] || :secondary).to_s)
         @position = options[:position] || 50
+        @modal = options[:modal] || :centered
+        validate_modal!
 
         freeze
       end
@@ -85,8 +87,49 @@ module Plutonium
         policy.allowed_to?(:"#{name}?")
       end
 
+      # Returns a new Action with the given options merged over this one.
+      # Used by the resource definition to derive variants (e.g. dropping
+      # `turbo_frame` when `modal false` is configured) without mutating
+      # the frozen original.
+      def with(**overrides)
+        self.class.new(name, **to_options.merge(overrides))
+      end
+
+      protected
+
+      # Canonical representation for reconstruction via `with`. Every
+      # attribute set in `initialize` MUST appear here; otherwise
+      # `with(**overrides)` would silently drop it on round-trip.
+      # `category` is exposed as a Symbol since `initialize` re-wraps
+      # it in StringInquirer.
+      def to_options
+        {
+          label: @label,
+          description: @description,
+          icon: @icon,
+          color: @color,
+          confirmation: @confirmation,
+          route_options: @route_options,
+          turbo: @turbo,
+          turbo_frame: @turbo_frame,
+          return_to: @return_to,
+          bulk_action: @bulk_action,
+          collection_record_action: @collection_record_action,
+          record_action: @record_action,
+          resource_action: @resource_action,
+          category: @category.to_sym,
+          position: @position,
+          modal: @modal
+        }
+      end
+
       private
 
+      def validate_modal!
+        return if [:centered, :slideover].include?(@modal)
+        raise ArgumentError, "modal must be :centered or :slideover, got #{@modal.inspect}"
+      end
+
       # Build RouteOptions from the provided options
       #
       # @param [RouteOptions, Hash, nil] options The routing options

data/lib/plutonium/action/interactive.rb

@@ -22,7 +22,7 @@ module Plutonium
         options[:label] ||= interaction.label
         options[:description] ||= interaction.description
         options[:icon] ||= interaction.icon
-        options[:turbo_frame] = "remote_modal" unless options.key?(:turbo_frame)
+        options[:turbo_frame] = Plutonium::REMOTE_MODAL_FRAME unless options.key?(:turbo_frame)
 
         super(name, **options)
       end

data/lib/plutonium/configuration.rb

@@ -27,6 +27,9 @@ module Plutonium
     # @return [Float] the current defaults version
     attr_reader :defaults_version
 
+    # @return [Symbol] :classic (legacy Header/Sidebar) or :modern (Topbar/IconRail)
+    attr_accessor :shell
+
     # Map of version numbers to their default configurations
     VERSION_DEFAULTS = {
       1.0 => proc do |config|
@@ -48,6 +51,7 @@ module Plutonium
       @development = parse_boolean_env("PLUTONIUM_DEV")
       @cache_discovery = !Rails.env.development?
       @enable_hotreload = Rails.env.development?
+      @shell = :modern
     end
 
     # Load default configuration for a specific version

data/lib/plutonium/definition/actions.rb

@@ -32,6 +32,9 @@ module Plutonium
 
         # standard CRUD actions
 
+        # turbo_frame for :new and :edit is set by
+        # Resource::Definition.configure_crud_modal_targets! based on the
+        # `modal` config. Don't hard-code it here.
         action(:new, route_options: {action: :new},
           resource_action: true, category: :primary,
           icon: Phlex::TablerIcons::Plus, position: 10)

data/lib/plutonium/definition/base.rb

@@ -33,6 +33,8 @@ module Plutonium
       include Scoping
       include Search
       include NestedInputs
+      include IndexViews
+      include Metadata
 
       class IndexPage < Plutonium::UI::Page::Index; end
 
@@ -48,6 +50,8 @@ module Plutonium
 
       class Table < Plutonium::UI::Table::Resource; end
 
+      class Grid < Plutonium::UI::Grid::Resource; end
+
       class Display < Plutonium::UI::Display::Resource; end
 
       class QueryForm < Plutonium::UI::Form::Query; end
@@ -114,6 +118,10 @@ module Plutonium
         self.class::Table
       end
 
+      def grid_class
+        self.class::Grid
+      end
+
       def detail_class
         self.class::Display
       end

data/lib/plutonium/definition/index_views.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Definition
+    # DSL for declaring which index views a resource supports and how
+    # they're configured.
+    #
+    # @example Enable both views, default to Grid
+    #   class UserDefinition < Plutonium::Resource::Definition
+    #     grid_fields(
+    #       image:     :avatar,
+    #       header:    :name,
+    #       subheader: :email,
+    #       meta:      [:role, :status]
+    #     )
+    #     default_index_view :grid
+    #   end
+    module IndexViews
+      extend ActiveSupport::Concern
+
+      KNOWN_VIEWS = %i[table grid].freeze
+      GRID_SLOTS = %i[image header subheader body meta footer].freeze
+      GRID_LAYOUTS = %i[compact media].freeze
+
+      included do
+        class_attribute :defined_index_views, default: [:table], instance_accessor: false
+        class_attribute :defined_default_index_view, default: nil, instance_accessor: false
+        class_attribute :defined_grid_fields, default: {}, instance_accessor: false
+        class_attribute :defined_grid_layout, default: :compact, instance_accessor: false
+        class_attribute :defined_grid_columns, default: nil, instance_accessor: false
+      end
+
+      class_methods do
+        # Declares the index views this resource supports.
+        # Usually unnecessary — declaring `grid_fields` auto-enables :grid
+        # alongside the default :table. Use `index_views` only to disable
+        # one (e.g. `index_views :grid` to drop the table view).
+        # @param list [Array<Symbol>] one or more of {KNOWN_VIEWS}
+        def index_views(*list)
+          list = list.flatten.map(&:to_sym)
+          invalid = list - KNOWN_VIEWS
+          raise ArgumentError, "Unknown index_views: #{invalid.inspect}. Valid: #{KNOWN_VIEWS}" if invalid.any?
+          self.defined_index_views = list.empty? ? [:table] : list
+        end
+
+        # Declares the default index view. Must be one of {.index_views}.
+        # Falls back to the first declared view if unset.
+        def default_index_view(name = nil)
+          if name.nil?
+            defined_default_index_view || defined_index_views.first
+          else
+            name = name.to_sym
+            unless defined_index_views.include?(name)
+              raise ArgumentError, "default_index_view #{name.inspect} not in index_views #{defined_index_views.inspect}"
+            end
+            self.defined_default_index_view = name
+          end
+        end
+
+        # Maps grid slots to fields. Each slot is optional. Implicitly
+        # adds `:grid` to {.index_views} so a resource can opt into the
+        # Grid view simply by declaring its slots.
+        # @param slots [Hash{Symbol => Symbol, Array<Symbol>}]
+        def grid_fields(**slots)
+          invalid = slots.keys - GRID_SLOTS
+          raise ArgumentError, "Unknown grid slots: #{invalid.inspect}. Valid: #{GRID_SLOTS}" if invalid.any?
+          self.defined_grid_fields = slots
+          self.defined_index_views = defined_index_views + [:grid] unless defined_index_views.include?(:grid)
+        end
+
+        # Layout shape for grid cards. :compact (default) places the image
+        # left of the content; :media stacks the image full-width on top.
+        def grid_layout(value)
+          value = value.to_sym
+          unless GRID_LAYOUTS.include?(value)
+            raise ArgumentError, "grid_layout must be one of #{GRID_LAYOUTS}, got #{value.inspect}"
+          end
+          self.defined_grid_layout = value
+        end
+
+        # Override responsive column count. Default is 1 / 2 / 3 / 4 at
+        # sm / md / lg / xl.
+        def grid_columns(value)
+          self.defined_grid_columns = Integer(value)
+        end
+      end
+
+      def defined_index_views = self.class.defined_index_views
+      def default_index_view = self.class.default_index_view
+      def defined_grid_fields = self.class.defined_grid_fields
+      def defined_grid_layout = self.class.defined_grid_layout
+      def defined_grid_columns = self.class.defined_grid_columns
+    end
+  end
+end