plutonium 0.58.1 → 0.60.0

data/docs/superpowers/plans/2026-06-14-form-sectioning.md.tasks.json

@@ -0,0 +1,40 @@
+{
+  "planPath": "docs/superpowers/plans/2026-06-14-form-sectioning.md",
+  "tasks": [
+    {
+      "id": 1,
+      "subject": "Task 1: FormLayout DSL module + registry",
+      "status": "completed",
+      "description": "Add form_layout/section/ungrouped DSL + ordered inheritable registry + validations; include in Definition::Base and Interaction::Base.\n\n```json:metadata\n{\"files\": [\"lib/plutonium/definition/form_layout.rb\", \"lib/plutonium/definition/base.rb\", \"lib/plutonium/interaction/base.rb\", \"test/plutonium/definition/form_layout_test.rb\", \"test/plutonium/interaction/form_layout_test.rb\"], \"verifyCommand\": \"bin/rails test test/plutonium/definition/form_layout_test.rb test/plutonium/interaction/form_layout_test.rb\", \"acceptanceCriteria\": [\"form_layout records sections in order\", \"section :ungrouped and duplicate ungrouped raise\", \"default label humanizes key\", \"subclasses inherit; redeclare replaces\", \"instance + interaction expose registry\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 2,
+      "subject": "Task 2: Resolve field list into ordered sections",
+      "status": "completed",
+      "blockedBy": [1],
+      "description": "Add resolve_form_sections(resource_fields): assign fields (first-section-wins, order preserved), leftovers to ungrouped (default first / declared position), raise on unknown keys, keep empty sections.\n\n```json:metadata\n{\"files\": [\"lib/plutonium/definition/form_layout.rb\", \"test/plutonium/definition/form_layout_resolution_test.rb\"], \"verifyCommand\": \"bin/rails test test/plutonium/definition/form_layout_resolution_test.rb\", \"acceptanceCriteria\": [\"nil without layout\", \"fields assigned in order; leftovers to ungrouped\", \"ungrouped default-first / explicit-position\", \"unknown field raises\", \"empty sections kept (first-section-wins)\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 3,
+      "subject": "Task 3: Section chrome component + columns helper",
+      "status": "completed",
+      "blockedBy": [1],
+      "description": "Add Components::Section (heading/description, native <details> collapsible, grid by columns), yields field rendering to the form.\n\n```json:metadata\n{\"files\": [\"lib/plutonium/ui/form/components/section.rb\", \"test/plutonium/ui/form/components/section_test.rb\"], \"verifyCommand\": \"bin/rails test test/plutonium/ui/form/components/section_test.rb\", \"acceptanceCriteria\": [\"heading + description render\", \"collapsible emits <details> with open/collapsed\", \"non-collapsible has no <details>\", \"grid_class applied and block content rendered\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 4,
+      "subject": "Task 4: Render sections in resource forms + integration",
+      "status": "completed",
+      "blockedBy": [2, 3],
+      "description": "Form::Resource#render_fields groups via resolver + Section component, evaluates condition in form context, falls back to single grid. Register KitchenSink in admin + add form_layout to KitchenSinkDefinition; integration test.\n\n```json:metadata\n{\"files\": [\"lib/plutonium/ui/form/resource.rb\", \"test/dummy/app/definitions/kitchen_sink_definition.rb\", \"test/dummy/packages/admin_portal/config/routes.rb\", \"test/integration/admin_portal/form_layout_rendering_test.rb\"], \"verifyCommand\": \"bin/rails test test/integration/admin_portal/form_layout_rendering_test.rb test/integration/admin_portal\", \"acceptanceCriteria\": [\"sections + headings render and group fields\", \"collapsible emits <details>\", \"no layout -> single grid unchanged\", \"falsey condition hides section\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 5,
+      "subject": "Task 5: Interaction forms render sections",
+      "status": "completed",
+      "blockedBy": [4],
+      "description": "Confirm interaction forms render form_layout sections (shared render_fields path). Add form_layout to a dummy interaction exercised by an org_portal test; assert grouped render.\n\n```json:metadata\n{\"files\": [\"test/integration/org_portal/form_layout_interaction_test.rb\"], \"verifyCommand\": \"bin/rails test test/integration/org_portal/form_layout_interaction_test.rb\", \"acceptanceCriteria\": [\"interaction form renders section headings\", \"interaction attribute input names unchanged\"], \"requiresUserVerification\": false}\n```"
+    }
+  ],
+  "lastUpdated": "2026-06-14T12:55:00Z"
+}

data/docs/superpowers/specs/2026-06-12-export-csv-default-action-design.md

@@ -0,0 +1,306 @@
+# Built-in CSV Export — Design
+
+**Date:** 2026-06-12
+**Status:** Implemented
+
+> **Revision (two exports, toolbar split button).** The shipped feature is a **split
+> button** with two behaviours, not a single export:
+> - **Export** (primary) — the current view (selected scope + filters + search via
+>   `?q`). Source: `filtered_resource_collection`. Filename `…_<date>.csv`.
+> - **Export all** (dropdown) — the entire authorized scope, bypassing the query object
+>   (`?all=1`). Source: `current_authorized_scope`. Filename `…_all_<date>.csv`.
+>
+> The controller selects the source via `export_csv_collection` (keyed on `params[:all]`).
+> The split button (`Plutonium::UI::ExportButton`, reusing the `resource-drop-down`
+> Stimulus controller) is rendered in the **index table toolbar, just after the Filter
+> button** — `Plutonium::UI::Table::Components::Toolbar` receives an `export:` config
+> built by `Table::Resource#export_toolbar_config` (policy-gated; carries the current
+> `?q`). It is styled with `pu-btn-outline pu-btn-sm` to match the Filter button, with
+> the two halves joined via inline corner styles. A page-limited "export current page"
+> variant and a scope-named primary label were both considered and dropped.
+
+## Goal
+
+Ship CSV export as a **built-in, auto-mounted, policy-gated capability** on every Plutonium
+resource — disabled by default, enabled by a one-line policy override, surfaced through a
+**custom export button** on the index page (not the action DSL — exports are special: they stream
+and open in a new tab). This generalizes the `AdminPortal::Concerns::ExportCsv` pattern from the
+achieve-api app into the framework, following Plutonium's existing `typeahead` design
+(auto-mounted route + default policy method + controller concern).
+
+The achieve app wired export per-resource by hand (a definition action, a controller concern,
+manual `collection { get :export_csv }` per resource, raw `attribute_names` as columns). Here the
+route auto-mounts, the column set comes from the policy/definition, the per-field output is
+customizable via an `export` DSL, and the export **streams** so it's safe on large tables — the
+only thing a user does to turn it on is enable the policy.
+
+## How users enable it
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  def export_csv? = true            # or `index?`
+end
+```
+
+That's it. The route already exists, the button appears on the index page once permitted, the
+column set defaults to the index columns. Optionally:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # customize a single field's output + header (column set still comes from the policy)
+  export :author, label: "Author email", &->(post) { post.author.email }
+  export :total, &->(post) { post.total.format }
+end
+```
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  def export_csv? = true
+  # override the exported column set (defaults to permitted_attributes_for_index)
+  def permitted_attributes_for_export = [:title, :author, :total, :created_at]
+end
+```
+
+## Behavior
+
+- The export button is a plain `<a target="_blank">` to `GET /<resources>/export_csv`, carrying
+  the **current query string** (`?q[...]`). So it exports **all records matching the current
+  filters/search/scope** — not just the visible page (the index is paginated; export is not).
+- `target="_blank"` opens the download in a new tab **and** naturally bypasses Turbo (Turbo
+  ignores links with a `target`), so the streamed file download isn't intercepted/rendered.
+- The response **streams** (`send_stream`) — rows are written as they're read in batches, so
+  memory stays flat regardless of row count. No row cap.
+
+## Design (5 touch-points)
+
+### 1. Routing — auto-mount (parallels `define_collection_typeahead_actions`)
+
+`lib/plutonium/routing/mapper_extensions.rb`. Add `define_collection_export_actions`, invoked
+inside the `interactive_resource_actions` concern:
+
+```ruby
+def define_collection_export_actions
+  collection do
+    get "export_csv", action: :export_csv, as: :export_csv
+  end
+end
+```
+
+Every resource registered via `register_resource` gets `GET /<resources>/export_csv`. No
+per-resource route edits. Path helper: `export_csv_<resources>_path`.
+
+### 2. Controller concern (parallels `Typeahead`)
+
+`lib/plutonium/resource/controllers/export_csv.rb`, included in `controller.rb` after
+`CrudActions` (so it can reuse the private `filtered_resource_collection`).
+
+```ruby
+require "csv"
+
+module Plutonium::Resource::Controllers::ExportCsv
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :authorize_export_csv!, only: :export_csv
+    skip_verify_current_authorized_scope only: :export_csv
+  end
+
+  # GET /<resources>/export_csv
+  # Streams via a lazy Enumerator response body (NOT send_stream — that
+  # lives in ActionController::Live, which would turn every resource
+  # action into a threaded streaming response). The primary key is always
+  # the first column. Rows are the index's filtered collection.
+  def export_csv
+    response.headers["Content-Type"] = "text/csv; charset=utf-8"
+    response.headers["Content-Disposition"] =
+      ActionDispatch::Http::ContentDisposition.format(disposition: "attachment", filename: export_csv_filename)
+    response.headers["X-Accel-Buffering"] = "no"
+    response.headers["Cache-Control"] = "no-cache"
+    self.response_body = export_csv_lines
+  end
+
+  def export_csv_lines
+    columns = export_columns   # [primary_key] + (exportable_attributes - [primary_key])
+    Enumerator.new do |yielder|
+      yielder << CSV.generate_line(columns.map { |c| export_csv_header(c) })
+      filtered_resource_collection.find_each do |record|
+        yielder << CSV.generate_line(columns.map { |c| export_csv_value(record, c) })
+      end
+    end
+  end
+
+  private
+
+  def authorize_export_csv!
+    authorize_current! resource_class, to: :export_csv?
+  end
+
+  def exportable_attributes
+    @exportable_attributes ||= current_policy.send_with_report(:permitted_attributes_for_export)
+  end
+
+  def export_csv_value(record, name)
+    defn = current_definition.defined_exports[name]
+    (defn && defn[:block]) ? defn[:block].call(record) : record.public_send(name)
+  end
+
+  def export_csv_header(name)
+    defn = current_definition.defined_exports[name]
+    defn&.dig(:options, :label) || name.to_s.humanize
+  end
+end
+```
+
+**Streaming + ordering tradeoff:** `find_each` bounds memory (loads ~1k rows at a time, GC'd per
+batch) but **forces primary-key order** — the file does *not* preserve the index's current sort.
+Filters, search, and scope from `filtered_resource_collection` *are* applied. This is the
+deliberate cost of unbounded streaming; CSV consumers re-sort downstream. (Sort-fidelity would
+require keyset pagination — out of scope.)
+
+`send_stream` is available on the framework's Rails floor (Appraisal `rails-7` pins `~> 7.2`;
+`send_stream` landed in 7.2).
+
+**Known N+1:** an `export` block that walks an association will N+1 across batches. Acceptable for
+v1 (document it); a preload hook can come later.
+
+### 3. Policy (parallels `permitted_attributes_for_index`)
+
+`lib/plutonium/resource/policy.rb`, in the action-methods section:
+
+```ruby
+# Checks if CSV export is permitted.
+# @return [Boolean] false by default — enable per-resource by overriding.
+def export_csv?
+  false
+end
+
+# Returns the attributes included in an export.
+# @return [Array<Symbol>] defaults to the index columns.
+def permitted_attributes_for_export
+  permitted_attributes_for_index
+end
+```
+
+`export_csv?` defaults to `false` — the explicit opt-in gate. `permitted_attributes_for_export`
+is format-agnostic (named `_export`, not `_export_csv`, so a future XLSX/JSON export reuses the
+same column set) and defaults to the index columns: "index columns by default, policy-overridable."
+The controller always prepends `resource_class.primary_key` as the first column (de-duplicated),
+so the id is exported even when the policy's attribute list omits it.
+
+`csv` is declared as a gemspec dependency — it is no longer a default gem on Ruby 3.4+.
+
+### 4. Custom export button (NOT a definition action)
+
+A dedicated Phlex component, `lib/plutonium/ui/export_button.rb`:
+
+```ruby
+class Plutonium::UI::ExportButton < Plutonium::UI::Component::Base
+  def initialize(url:)
+    @url = url
+  end
+
+  def view_template
+    a(href: @url, target: "_blank", rel: "noopener", class: "pu-btn pu-btn-outline pu-btn-sm") do
+      render Phlex::TablerIcons::Download.new(class: "w-4 h-4 shrink-0")
+      span { "Export" }
+    end
+  end
+end
+```
+
+Rendered by `Plutonium::UI::Page::Index` via the existing `render_after_page_header` hook, gated on
+the policy:
+
+```ruby
+def render_after_page_header
+  return unless current_policy.allowed_to?(:export_csv?)
+  url = resource_url_for(resource_class, action: :export_csv, **export_query_params)
+  div(class: "flex justify-end mb-2") { render Plutonium::UI::ExportButton.new(url:) }
+end
+```
+
+`export_query_params` forwards the current `q` (filters/search/scope/sort params) so the export
+matches what the user is looking at. The exact `resource_url_for` signature for appending `action:`
++ query params is verified against the existing `route_options_to_url`/`resource_url_for` usage
+during implementation; the button URL is the only routing detail to confirm.
+
+A custom button (rather than a definition action) is the right call because export is not a normal
+navigable action: it streams a file, must open in a new tab, must not be Turbo-driven, and is
+inherently collection-level. Keeping it out of the action DSL avoids bending that DSL around those
+quirks.
+
+### 5. Definition DSL — `export` (parallels `display`/`column`)
+
+`lib/plutonium/definition/base.rb`: add `:export` to the `defineable_props` list (alongside
+`:field, :input, :display, :column`). Generates `export :name, **options, &block` and
+`defined_exports`, exactly like `display`/`column`.
+
+- `&block` — receives the record, returns the cell value (overrides the raw `public_send`).
+- `label:` — overrides the column header (default `name.to_s.humanize`).
+
+The `export` DSL **customizes output of columns**; the column *set* is driven by
+`permitted_attributes_for_export`. An `export` entry for a name not in that set is simply unused;
+conversely the policy method may list virtual/method names (like index columns can), with `export`
+supplying their formatting.
+
+## Data flow
+
+```
+[Export button on index] --target=_blank, ?q=current--> GET /posts/export_csv?q[...]
+  → authorize_export_csv!        (export_csv? — 403 if false)
+  → exportable_attributes        (policy.permitted_attributes_for_export)
+  → filtered_resource_collection (current_authorized_scope + search/filter/scope; NOT paginated)
+  → send_stream: header line, then find_each → one CSV line per record (PK order)
+  → text/csv attachment "<plural>_<date>.csv", streamed, opens in new tab
+```
+
+Row-level authorization is the scope itself (`current_authorized_scope`), so
+`skip_verify_current_authorized_scope` is correct here — same as `typeahead`. Tenant/parent scoping
+applies because `filtered_resource_collection` is reused unchanged.
+
+## Error handling
+
+- `export_csv?` false → `ActionPolicy::Unauthorized` (403); button is also hidden.
+- Unknown column name in `permitted_attributes_for_export` with no `export` block →
+  `NoMethodError` from `public_send` — a definition/policy authoring error that should surface
+  loudly (same as an unknown index column).
+- An error raised mid-stream (after headers are sent) cannot un-send the 200/headers — the
+  download ends up truncated. Acceptable for v1; the column-resolution paths above are simple.
+
+## Out of scope (YAGNI)
+
+- Background-job / email export for very large tables — explicitly deferred (not designed now). The
+  `permitted_attributes_for_export` naming leaves the door open for an async path and other formats
+  later.
+- A split "export current view / export all" button — there is one export: all rows matching the
+  current query.
+- Preserving the index sort in the file (PK order; see tradeoff above).
+- Per-row authorization beyond the scope filter; preload/N+1 handling for `export` blocks.
+
+## Testing
+
+Use a dummy-app resource (created via generators per project convention) with the policy enabled:
+
+- Route exists: `GET /<resources>/export_csv` resolves.
+- Disabled by default: with default policy, the button is hidden and the route 403s.
+- Enabled: returns a streamed `text/csv` attachment with the right filename.
+- Header row = humanized column names; `export :x, label:` overrides a header.
+- Body rows = one per matching record; `export :x, &block` formats that cell.
+- Respects query: `?q[...]` search/filter narrows the exported rows; pagination does NOT limit them.
+- `permitted_attributes_for_export` override changes the column set.
+- Tenant/parent scoping: export never leaks rows outside `current_authorized_scope`.
+
+## Files
+
+| Action | Path |
+|---|---|
+| Modify | `plutonium.gemspec` (add `csv` dependency) |
+| Modify | `lib/plutonium/routing/mapper_extensions.rb` (add `define_collection_export_actions`, call it in concern) |
+| Create | `lib/plutonium/resource/controllers/export_csv.rb` |
+| Modify | `lib/plutonium/resource/controller.rb` (include the concern) |
+| Modify | `lib/plutonium/resource/policy.rb` (`export_csv?`, `permitted_attributes_for_export`) |
+| Create | `lib/plutonium/ui/export_button.rb` |
+| Modify | `lib/plutonium/ui/page/index.rb` (`render_after_page_header` → policy-gated button) |
+| Modify | `lib/plutonium/definition/base.rb` (add `:export` defineable prop) |
+| Create | tests under `test/` + dummy-app resource |
+| Modify | docs (`docs/reference/...`) + relevant `.claude/skills/` skill |

data/docs/superpowers/specs/2026-06-14-form-sectioning-design.md

@@ -0,0 +1,237 @@
+# Form Sectioning — Design
+
+**Date:** 2026-06-14
+**Status:** Approved (pending spec review)
+
+## Problem
+
+Plutonium forms render every field in a single responsive grid
+(`Form::Resource#render_fields` walks a flat `resource_fields` list inside one
+`fields_wrapper`). There is no way to group fields under headings ("Personal
+details", "Address", …). We want a clean DSL for *sectioning* forms that works
+for both resource definitions and interactions, without disturbing per-field
+configuration.
+
+## Constraints discovered in the codebase
+
+- **Field config lives in the definition** (`input :x, ...` via
+  `DefineableProps`, stored as ordered hashes), but the **set and order of
+  fields actually rendered come from the policy** (`permitted_attributes_for(action)`,
+  via `submittable_attributes_for`). The form receives that flat list as
+  `resource_fields`.
+- **Interactions reuse the resource form.** `Form::Interaction < Form::Resource`
+  and only swaps in `resource_fields` (from `interaction.attribute_names`) and
+  `resource_definition` (the interaction instance). So sectioning added to
+  `Form::Resource#render_fields` is inherited by interactions for free.
+- The shared definition DSL is composed from `Plutonium::Definition::*` concern
+  modules. `StructuredInputs` is the precedent for a module mixed into **both**
+  `Definition::Base` and `Interaction::Base`.
+
+Therefore: sectioning is a **presentation concern declared in the definition**
+that must group a **policy-driven** field list — skipping fields the policy
+filtered out and hiding sections that end up empty.
+
+## DSL
+
+A new shared module `Plutonium::Definition::FormLayout` provides `form_layout`.
+
+```ruby
+form_layout do
+  section :identity, :name, :date_of_birth, :grade,
+    label: "Your identification", description: "Basic info"
+
+  section :address, :street, :city, :country,
+    collapsible: true, columns: 2,
+    condition: -> { object.requires_address? }
+
+  ungrouped label: "Other", collapsible: true
+end
+```
+
+### `section(key, *fields, **opts)`
+
+- `key` — Symbol, the section's identity. Heading defaults to `key.to_s.humanize`.
+  `:ungrouped` is **reserved** for the macro below — `section :ungrouped, …`
+  raises `ArgumentError`.
+- `*fields` — ordered field keys placed in this section.
+- `**opts`:
+  - `label:` — overrides the humanized heading.
+  - `description:` — optional help line under the heading.
+  - `collapsible:` — Boolean (default `false`). Renders as a native
+    `<details>/<summary>` disclosure (no JS).
+  - `collapsed:` — Boolean (default `false`). Initial state when collapsible;
+    `false` ⇒ the `<details>` is `open`.
+  - `columns:` — Integer overriding the section's grid column count. Default
+    inherits the form's responsive grid.
+  - `condition:` — lambda evaluated in the **form instance context** (same
+    semantics as `input ..., condition:`; `object` and helpers available). A
+    falsey result renders nothing for the section.
+
+### `ungrouped(**opts)`
+
+- Configures the implicit bucket that auto-collects every permitted field not
+  claimed by a `section`. Takes **no field list**.
+- Accepts the same options as `section` (`label:`, `description:`,
+  `collapsible:`, `collapsed:`, `columns:`, `condition:`).
+- **Position:** where the macro is called sets where leftovers render. If the
+  macro is omitted, leftovers render **last** (appended after all declared
+  sections), with **no heading**. _(Amended — was "first"; see Amendments.)_
+- Calling `ungrouped` more than once in a single `form_layout` raises
+  `ArgumentError`.
+
+### Field configuration stays on `input`
+
+`form_layout`/`section` only reference field **keys** and carry **section-level**
+options. All per-field rendering config (`as:`, the field's own `label:`,
+`choices:`, per-field `condition:`, `pre_submit:`, blocks) remains on the `input`
+declaration. Layout never duplicates field config.
+
+### Inheritance / override
+
+- Re-declaring `form_layout` in a subclass **replaces** the parent layout as a
+  unit. Field-level `input` config continues to inherit normally.
+- The section registry is duplicated to subclasses on `inherited` (mirrors
+  `StructuredInputs`).
+
+### Backwards compatibility
+
+No `form_layout` declared ⇒ the current single-grid behavior is used unchanged.
+This is equivalent to one implicit, heading-less `ungrouped` region.
+
+## Rendering
+
+`Plutonium::Definition::FormLayout` exposes an ordered, frozen registry of
+section specs (and the `ungrouped` spec + its position) on definition and
+interaction instances.
+
+`Form::Resource#render_fields` becomes:
+
+1. **No layout** → existing path: one `fields_wrapper` over all `resource_fields`.
+2. **Layout present**:
+   - Assign each `section` its `fields ∩ resource_fields`, preserving the
+     section's declared field order.
+   - The `ungrouped` bucket gets `resource_fields` minus all claimed fields,
+     preserving `resource_fields` order.
+   - Build the ordered render list: sections in declared order with the
+     `ungrouped` bucket inserted at its declared position (default: **last**).
+   - For each entry: evaluate `condition` (skip if falsey); render a Section
+     component with its renderable fields. Empty sections are **not**
+     special-cased — they render with defaults (see Edge cases).
+
+Field rendering itself still goes through the existing `render_resource_field`,
+so all input types/components are unaffected.
+
+### Section component
+
+New `Plutonium::UI::Form::Components::Section` (Phlex). Responsibilities:
+
+- Wrapper + heading (`label`) + optional `description`.
+- When `collapsible`, wrap in native `<details>`/`<summary>` (`open` unless
+  `collapsed`), styled with Tailwind/`--pu-*` tokens.
+- A grid (`fields_wrapper`-style) whose column count comes from `columns:` when
+  given, else the existing responsive default
+  (`grid-cols-1 md:grid-cols-2 2xl:grid-cols-4`).
+- Yields to render the section's fields via `render_resource_field`.
+
+A small helper maps `columns:` → grid classes (e.g. `1 → "grid grid-cols-1 gap-6"`,
+`2 → "grid grid-cols-1 md:grid-cols-2 gap-6"`). Theme entries added for section
+heading/description/wrapper so they're themeable like the rest of the form.
+
+## Edge cases
+
+- **Field permitted but in no section** → falls into `ungrouped`.
+- **Section references a policy-filtered field** → that individual field is
+  skipped (no input is rendered for an unpermitted attribute).
+- **Empty section** (all fields filtered out, or none assigned) → **not
+  hidden**. It renders through the normal path with defaults (its default/declared
+  chrome). There is no automatic empty-hiding; to hide a section conditionally,
+  use `condition:`.
+- **Unknown field key in a `section`** (not an attribute at all) → raise at
+  render with a clear message (catches typos), consistent with how the form
+  already errors on unknown fields.
+- **`condition` falsey** → section renders nothing; its fields do **not** spill
+  into `ungrouped` (they remain owned by the suppressed section).
+- **No leftovers** → `ungrouped` renders with defaults (with no fields and no
+  configured heading, that is simply nothing visible; a configured `label:`
+  still renders).
+
+## Files
+
+- **New** `lib/plutonium/definition/form_layout.rb` — DSL module: `form_layout`
+  block builder, ordered + inheritable section registry, `section` / `ungrouped`,
+  instance readers, validation (duplicate `ungrouped`, etc.).
+- **Modify** `lib/plutonium/definition/base.rb` — `include FormLayout`.
+- **Modify** `lib/plutonium/interaction/base.rb` — `include FormLayout`.
+- **New** `lib/plutonium/ui/form/components/section.rb` — section component.
+- **Modify** `lib/plutonium/ui/form/resource.rb` — `render_fields` grouping; columns→grid helper.
+- **Modify** `lib/plutonium/ui/form/theme.rb` — section heading/description/wrapper tokens.
+
+## Testing (RSpec)
+
+- **DSL/registry:** sections recorded in order with options; `ungrouped` spec +
+  position; humanized default label; `label:` override; duplicate `ungrouped`
+  raises; `section :ungrouped` raises; inheritance duplicates registry;
+  re-declaring `form_layout` replaces.
+- **Assignment:** fields land in the right section in declared order; leftovers
+  collect into `ungrouped`; `ungrouped` default position is last; explicit
+  position honored.
+- **Filtering:** policy-filtered field is skipped; an empty section still renders
+  with defaults (is **not** hidden); unknown field key raises.
+- **Conditions:** falsey `condition` hides the section and withholds its fields.
+- **Rendering:** headings/descriptions present; collapsible emits
+  `<details>`/`<summary>` with correct `open`; `columns:` changes grid classes.
+- **Interactions:** an interaction with `form_layout` sections renders grouped
+  via `Form::Interaction`.
+- **Backwards-compat:** a definition with no `form_layout` renders the single
+  grid exactly as before.
+
+## Out of scope (YAGNI)
+
+- Applying sections to show/display pages or the index grid (forms only for now;
+  the same registry could later be reused by `Display::Resource`).
+- Nested sections / tabs.
+- Per-field layout hints (e.g. `field :notes, span: 2`) — Style 1 keeps fields
+  positional; this can be added later via the nested-block form if needed.
+- Stimulus-driven animated collapse (native `<details>` chosen for leanness).
+
+## Amendments (post-implementation)
+
+Changes made after the original plan landed:
+
+- **Implicit `ungrouped` placement: first → last.** When no `ungrouped` macro is
+  declared, leftover fields are now appended **after** all declared sections
+  (was: prepended). This matches the convention of the explicit macro ("the
+  rest" trails the sections you care about) and makes "omit it" equivalent to
+  "declare it last." To float leftovers above your sections, declare `ungrouped`
+  explicitly at the top.
+
+- **`columns:` actually lays out in a grid.** Previously every field wrapper got
+  `col-span-full`, so a section's `columns: N` had no visible effect. Fields in a
+  multi-column section now flow into single grid cells. A field that declares its
+  own span (`input :x, wrapper: {class: "col-span-..."}`) **always wins** — in any
+  section — so authors can opt a field back to full width (or wider) inside a
+  multi-column section.
+
+- **Dynamic section options.** Every section option except `columns:`
+  (`collapsed`, `collapsible`, `label`, `description`, plus the existing
+  `condition`) may be a **proc**, resolved at render time in the form instance
+  context — the same context as input/section `condition:` (so `object`,
+  `current_user`, `params`, helpers are available). The whole layout is resolved
+  once per render in `Form::Resource#resolve_form_layout` (visibility + option
+  evaluation in one pass); `render_form_section` is pure presentation. `columns:`
+  stays a validated literal (it feeds the grid class).
+
+- **Interactions: verified + exercised.** `Form::Interaction < Form::Resource`
+  already inherited the layout path; this is now covered by a dummy interaction
+  (`ReconfigureKitchenSink`, a record action on `KitchenSink`) and an integration
+  test. In an interaction form `object` is the interaction instance and
+  `object.resource` is the record, so record-aware dynamic options work there too
+  (e.g. `collapsed: -> { object.resource.archived? }`).
+
+- **Unrelated fix surfaced while driving the dummy in `development`:** the package
+  engine system (`Plutonium::Package::Engine`) called `Rails.application.initializers`
+  from a `before_configuration` hook, prematurely memoizing `Rails.application.railties`
+  and dropping package engines from the autoload paths when a second
+  `Rails::Application` (combustion, in dev) was instantiated before the packages
+  glob ran — surfacing as `uninitialized constant Blogging::Post`. The view-path
+  neutralization was moved to a real initializer (`before: :add_view_paths`).

data/gemfiles/rails_7.gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.57.0)
+    plutonium (0.59.0)
       action_policy (~> 0.7.0)
+      csv
       listen (~> 3.8)
       pagy (~> 43.0)
       phlex (~> 2.0)
@@ -138,6 +139,7 @@ GEM
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     crass (1.0.6)
+    csv (3.3.5)
     date (3.5.1)
     drb (2.2.3)
     erb (6.0.2)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.57.0)
+    plutonium (0.59.0)
       action_policy (~> 0.7.0)
+      csv
       listen (~> 3.8)
       pagy (~> 43.0)
       phlex (~> 2.0)
@@ -135,6 +136,7 @@ GEM
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     crass (1.0.6)
+    csv (3.3.5)
     date (3.5.1)
     drb (2.2.3)
     erb (6.0.2)

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.57.0)
+    plutonium (0.59.0)
       action_policy (~> 0.7.0)
+      csv
       listen (~> 3.8)
       pagy (~> 43.0)
       phlex (~> 2.0)
@@ -137,6 +138,7 @@ GEM
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     crass (1.0.6)
+    csv (3.3.5)
     date (3.5.1)
     drb (2.2.3)
     erb (6.0.2)

data/lib/generators/pu/lite/solid_errors/solid_errors_generator.rb

@@ -43,7 +43,7 @@ module Pu
           # frozen_string_literal: true
 
           Rails.application.configure do
-            config.solid_errors.connects_to = {database: {writing: :#{@db_name}}}
+            config.solid_errors.connects_to = {database: {writing: :#{@db_name}, reading: :#{@db_name}}}
             config.solid_errors.email_from = ENV["SOLID_ERRORS_EMAIL_FROM"].presence
             config.solid_errors.email_to = ENV["SOLID_ERRORS_EMAIL_TO"].presence
             # Only deliver notifications when explicitly opted in AND both addresses are
@@ -51,8 +51,8 @@ module Pu
             # attempt to deliver malformed mail.
             config.solid_errors.send_emails = ENV["SOLID_ERRORS_SEND_EMAILS"].present? &&
               config.solid_errors.email_from.present? && config.solid_errors.email_to.present?
-            config.solid_errors.username = ENV.fetch("SOLID_ERRORS_USERNAME", nil)
-            config.solid_errors.password = ENV.fetch("SOLID_ERRORS_PASSWORD", nil)
+            config.solid_errors.username = ENV["SOLID_ERRORS_USERNAME"]
+            config.solid_errors.password = ENV["SOLID_ERRORS_PASSWORD"]
           end
         RUBY
       end