lcp 0.1.0

data/docs/reference/presenters.md

@@ -0,0 +1,3627 @@
+# Presenters Reference
+
+File: `config/lcp_ruby/presenters/<name>.yml`
+
+Presenter YAML defines the UI layer: how records are listed, displayed, edited, searched, and what actions are available. Multiple presenters can reference the same model to provide different views (e.g., an admin view and a read-only pipeline view).
+
+## Top-Level Attributes
+
+```yaml
+presenter:
+  name: <presenter_name>
+  model: <model_name>
+  label: "Display Label"
+  slug: <url_slug>
+  icon: <icon_name>
+  read_only: false
+  embeddable: false
+  redirect_after: { create: show, update: show }
+  scope: <soft_delete_scope>
+  record_aliases: { me: { resolve: current_user, field: user } }
+  dialog: { size: medium, closable: true, title_key: <i18n_key> }
+  index: {}
+  show: {}
+  form: {}
+  search: {}
+  actions: {}
+```
+
+### `name`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string |
+
+Unique identifier for the presenter. Referenced from [permissions](permissions.md) (`presenters` attribute) and used internally for resolution.
+
+### `model`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string |
+
+Name of the [model](models.md) this presenter displays. Must match a model's `name` attribute.
+
+### `label`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `name.humanize` |
+| **Type** | string |
+
+Display label for the presenter, shown in navigation menus and page titles.
+
+### `slug`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string |
+
+URL path segment. When set, the presenter is routable at `/<slug>`. If omitted, the presenter is not directly accessible via URL (useful for embedded or programmatic-only presenters).
+
+### `icon`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string |
+
+Icon name displayed in navigation menus. The engine uses these as CSS class hints (e.g., `dollar-sign`, `check-square`, `users`).
+
+### `menu_position`
+
+> **Deprecated.** `menu_position` is a side-channel workaround that lives on the wrong primitive (the presenter rather than navigation) and creates a third ordering surface alongside view-group `navigation: { position: N }` and explicit `menu.yml` order. **Write `config/lcp_ruby/menu.yml`** for explicit menu placement — the entity generator's `--menu=[<section>:]ROOT|<DropdownLabel>[:bottom|:right]` flag makes this a one-line addition at scaffold time. The field still works in v1 (boot emits a one-time info-level log when a presenter actually uses it) and will be removed in a future release.
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | integer |
+
+Position hint for the auto-created view group when this is the only presenter on the model.
+
+When a model has exactly one presenter and no explicit view group YAML, the engine [auto-creates a view group](view-groups.md#auto-creation-behavior) with position `900 + alphabetical_index`. The result is alphabetical menu order, which scales poorly past ~5 entries.
+
+`menu_position` lifts the auto-VG out of that tier into a configurator-controlled position without forcing a full `config/lcp_ruby/views/<name>.yml`:
+
+```yaml
+# config/lcp_ruby/presenters/school_class.yml
+presenter:
+  name: school_class
+  model: school_class
+  slug: school-classes
+  menu_position: 10        # → auto-VG appears at position 10
+
+# config/lcp_ruby/presenters/student.yml
+presenter:
+  name: student
+  model: student
+  slug: students
+  menu_position: 20        # → auto-VG appears at position 20
+
+# Other presenters without menu_position keep the 900+alphabetical default.
+```
+
+**Conventions:**
+
+- User-defined positions: `0–899`. Mix `menu_position` on presenters with explicit view-group `navigation: { position: N }` freely; the engine merges both into the same tier.
+- Auto-generated default: `900–999`.
+
+**Ignored when:**
+
+- An explicit view group already covers the model — the explicit `navigation: { position: N }` wins, this hint is silently dropped.
+- The presenter is one of multiple presenters on the same model — auto-VG creation is skipped entirely (you must define an explicit view group anyway).
+- The presenter isn't routable (`slug:` blank) — no auto-VG is ever created.
+
+### `default`
+
+| | |
+|---|---|
+| **Required** | no (required when the model has multiple routable presenters and any column/field uses `link: true` / `link_to: :show` without a per-link `link_presenter:` override) |
+| **Default** | `false` |
+| **Type** | boolean |
+
+Marks this presenter as the **canonical link target** for its model. When a column or field elsewhere uses `link: true` / `link_to: :show` to a record of this model, the link resolves to the presenter marked `default: true`.
+
+```yaml
+presenter:
+  name: contact_full
+  model: contact
+  slug: contacts
+  default: true   # canonical detail view for `contact` records
+```
+
+```ruby
+define_presenter :contact_full do
+  model :contact
+  slug "contacts"
+  default true
+end
+```
+
+**Validator rules** (boot-time):
+
+- Exactly one presenter per model may be marked `default: true`. Two defaults on the same model raise an error with both presenter names.
+- When the model has multiple routable presenters and a column/field uses `link: true`, either a `default: true` presenter must exist or every link entry must override with `link_presenter:`. The validator surfaces the missing-resolution case with both options spelled out.
+
+**See also:** [Multiple presenters per model](#multiple-presenters-per-model) for the full pattern, and `link_presenter` on column/field entries (in `index` / `show` field reference) for per-link overrides.
+
+### `read_only`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+When `true`, disables create, edit, and destroy operations for this presenter. The model data is still writable through other presenters or direct code. Use this for dashboard or reporting views.
+
+### `embeddable`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+Marks this presenter as embeddable within other views (e.g., as an inline table within a parent record's show page). This is a metadata flag for the UI layer to decide rendering behavior.
+
+### `redirect_after`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | hash |
+
+Controls where the user is redirected after successful create or update operations. Each key maps a CRUD action to a target page. Destroy always redirects to index.
+
+| Key | Allowed values | Default |
+|-----|---------------|---------|
+| `create` | `index`, `show`, `edit`, `new` | `show` |
+| `update` | `index`, `show`, `edit`, `new` | `show` |
+
+```yaml
+presenter:
+  name: quick_entry
+  model: ticket
+  slug: tickets
+
+  # After creating a ticket, go back to the list.
+  # After updating, stay on the edit page.
+  redirect_after:
+    create: index
+    update: edit
+```
+
+### `scope`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none (uses `kept` scope when model has `soft_delete`) |
+| **Type** | string |
+| **Allowed values** | `discarded`, `with_discarded` |
+
+Controls the soft delete scope applied to the index query for this presenter. Only meaningful when the referenced model has `soft_delete` enabled.
+
+- **Not set (default)** — the index shows only kept (non-discarded) records
+- `"discarded"` — the index shows only discarded (archived) records
+- `"with_discarded"` — the index shows all records regardless of discard status
+
+Use this to create archive presenters that show discarded records with `restore` and `permanently_destroy` actions:
+
+```yaml
+presenter:
+  name: project_archive
+  model: project
+  label: "Archived Projects"
+  slug: projects-archive
+  scope: discarded
+
+  actions:
+    collection: []
+    single:
+      - { name: show, type: built_in }
+      - { name: restore, type: built_in }
+      - { name: permanently_destroy, type: built_in, confirm: true }
+```
+
+See [Soft Delete Guide](../guides/soft-delete.md) for a complete example.
+
+### `record_aliases`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `{}` (none) |
+| **Type** | object (alias name → config) |
+
+Named URL segments that resolve to a specific record dynamically. Keys are alias names (URL path segments like `me`, `last`, `my`), values are config objects specifying the resolution strategy.
+
+Aliases are presenter-level because the same model may have different aliases in different contexts (e.g., a user-facing presenter has `me`, an admin presenter doesn't).
+
+#### Resolve strategies
+
+| Strategy | Config keys | Behavior |
+|----------|------------|----------|
+| `current_user` | `field` (optional) | Guard `current_user` nil → 404. With `field:` → resolve belongs_to FK: `scope.find_by!(assoc.foreign_key => current_user.id)`. Without `field:` → self-referential: `scope.find(current_user.id)` (requires the presenter's model to share a table with the configured user class; verified at boot). |
+| `field_on_user` | `user_field` | Guard `current_user` nil → 404; `scope.find(current_user.public_send(user_field))` |
+| `scope` | `scope` | `scope.send(scope_name).first!` — must be a zero-arity scope |
+
+All strategies apply within the existing `policy_scope` and soft-delete scope — authorization is never bypassed.
+
+#### Resolve chain
+
+When `params[:id]` arrives, the controller resolves in this order:
+
+1. **Alias match** — if presenter defines `record_aliases` and `params[:id]` matches a key, use the alias strategy.
+2. **Slug field** — if model defines [`slug_field`](models.md#slug_field) and `params[:id]` is not purely numeric, try `find_by!(slug_field => param)`.
+3. **Numeric ID** — fallback `scope.find(params[:id])`.
+
+This means an alias named `me` always takes priority over a record with slug `me`. Numeric-looking params always use ID lookup.
+
+#### Alias name constraints
+
+- Must not be purely numeric (`42` would shadow that record's ID)
+- Must not collide with reserved route segments (`new`, `edit`, `saved-filters`, `actions`, etc.)
+
+#### URL preservation
+
+When a record is entered via alias (e.g., `GET /preferences/me`), all ResourcesController member URLs generated during that request preserve the alias — the user never sees a jarring switch from `/preferences/me` to `/preferences/42`. Cross-presenter links use `to_param` instead (slug or ID, not alias).
+
+#### Example: user preferences with `/preferences/me`
+
+```yaml
+presenter:
+  name: my_preferences
+  model: user_preference
+  slug: preferences
+  record_aliases:
+    me:
+      resolve: current_user
+      field: user            # belongs_to association name
+```
+
+#### Example: self-referential alias on the User model (no `field:`)
+
+When the presenter's model *is* the user model (same table), `field:` can be omitted — the alias resolves directly to the current user's own row.
+
+```yaml
+presenter:
+  name: my_settings
+  model: user              # same table as the configured user_class
+  slug: my-settings
+  record_aliases:
+    me:
+      resolve: current_user
+      # no field: — resolves to scope.find(current_user.id)
+```
+
+#### Example: last issue shortcut
+
+```yaml
+presenter:
+  name: issues
+  model: issue
+  slug: issues
+  record_aliases:
+    last:
+      resolve: scope
+      scope: latest          # model must define scope :latest
+```
+
+#### Example: my team
+
+```yaml
+presenter:
+  name: teams
+  model: team
+  slug: teams
+  record_aliases:
+    my:
+      resolve: field_on_user
+      user_field: team_id    # current_user.team_id → Team.find(value)
+```
+
+**DSL:**
+
+```ruby
+define_presenter :my_preferences do
+  model :user_preference
+  slug "preferences"
+
+  record_alias :me, resolve: :current_user, field: :user
+end
+```
+
+See [Record Aliases Guide](../guides/record-aliases.md) for full examples.
+
+### `dialog`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | object |
+
+Dialog rendering configuration for when this presenter's auto-generated page is opened as a modal. Properties: `size` (`small`/`medium`/`large`/`fullscreen`, default `medium`), `closable` (boolean, default `true`), `title_key` (i18n key). When present on a presenter, the auto-generated page inherits this dialog config.
+
+```yaml
+presenter:
+  name: task_quick_form
+  model: task
+  dialog:
+    size: large
+    closable: false
+    title_key: lcp_ruby.dialogs.quick_task
+```
+
+See [Dialogs Reference](dialogs.md) for details.
+
+## Multiple presenters per model
+
+A model may have any number of presenters that provide different views — full detail, compact card, kanban, archive, dialog-only, etc. When another presenter links to a record of this model with `link: true` or `link_to: :show`, LCP must pick which presenter the link resolves to.
+
+> **Migrating from earlier LCP**: existing host apps with multi-presenter models will boot-error after upgrade until exactly one presenter per model is marked `default: true` *or* every link entry uses `link_presenter:`. Before this rule existed, `link: true` resolved to whichever presenter happened to be alphabetically first — which was rarely what the configurator intended. Single-presenter models need no annotation; the change is opt-in by problem (multi-presenter + linking).
+
+**Resolution order** (`Presenter::Enrichment.resolve_presenter_slug`):
+
+1. **Per-link override** — if the column/field entry has `link_presenter: <slug>`, that wins.
+2. **Single presenter** — if the model has exactly one presenter, its slug is used (no decision needed; this is the most common case).
+3. **Per-model default** — among multiple presenters, the one marked `default: true` is canonical.
+
+If none of these resolves a slug, the link silently breaks. The validator catches this case at boot — see the rules under [`default`](#default).
+
+### Worked example: Contact with three views
+
+```yaml
+# contact_full.yml — full detail page (canonical)
+presenter:
+  name: contact_full
+  model: contact
+  slug: contacts
+  default: true
+
+# contact_short.yml — compact card embedded in dialogs / sidebars
+presenter:
+  name: contact_short
+  model: contact
+  slug: contacts-short
+
+# contact_tiles.yml — image-heavy tile grid for the directory
+presenter:
+  name: contact_tiles
+  model: contact
+  slug: contacts-tiles
+```
+
+```yaml
+# orders.yml — has columns that link to contact records
+presenter:
+  name: orders
+  model: order
+  slug: orders
+  index:
+    table_columns:
+      # Default link target — uses contact_full (canonical) at /contacts/:id
+      - { field: customer.name, link: true }
+      # Per-link override — opens compact card on this index column only
+      - { field: secondary_contact.name, link: true, link_presenter: contacts-short }
+```
+
+### Validator rules
+
+- **Exactly one default per model** — if two presenters mark `default: true`, the validator raises an error naming both.
+- **Multi-presenter resolution required** — if a column/field uses `link: true` to a model with two or more routable presenters and there's no `default: true` and no per-link `link_presenter:`, the validator emits an error with both resolution options spelled out:
+
+  ```
+  Presenter 'orders', column 'customer.name': link target model 'contact' has
+  multiple presenters (contacts, contacts-short, contacts-tiles) and no resolution
+  strategy. Either:
+    (a) Mark one presenter as canonical: `default true` (DSL) / `default: true` (YAML), or
+    (b) Override per-link: `link_presenter: <slug>` on this column/field
+  ```
+
+- **`link_presenter:` must reference an existing slug** for the target model. Typos surface a `Did you mean '<closest>'?` hint with the available list.
+
+### Single-presenter models
+
+A model with exactly one presenter never needs `default: true` — single presenter is unambiguous and used directly. Adding the flag is harmless but redundant; the validator only enforces it when the resolution is otherwise ambiguous.
+
+## Index Configuration
+
+Controls the record list view. When `render_with` is set, the entire content area is replaced by a custom host-app partial while preserving LCP's toolbar, search, nav, and layout. See also [Rendering Extension Points](../guides/rendering-extension-points.md).
+
+```yaml
+index:
+  render_with: "analytics/dashboard"  # optional: replace the entire index content area
+  layout: tiles          # table (default), tiles, or tree
+  description: "Browse and manage all records."
+  default_sort: { field: created_at, direction: desc }
+  per_page: 25
+  per_page_options: [10, 25, 50, 100]
+  show_record_count: true
+  pagination_ends: false
+  row_click: show
+  empty_message: "No records found."
+  actions_position: dropdown
+  reorderable: false
+  table_columns: []
+  tile:
+    columns: 3
+  card:
+    title_field: name
+    subtitle_field: status
+    description_field: description
+    image_field: cover_image
+    actions: dropdown
+    fields:
+      - field: price
+        label: Price
+  sort_fields:
+    - field: name
+      label: Name
+    - field: price
+      label: Price
+  summary:
+    enabled: true
+    fields:
+      - field: price
+        function: sum
+        label: Total Value
+```
+
+### `render_with`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string (partial path) |
+
+Replaces the entire index content area with a custom host-app partial. The search/sort/scope pipeline still runs — the partial receives the processed `records`. When set, `layout` is ignored. See also [Rendering Extension Points](../guides/rendering-extension-points.md).
+
+```yaml
+index:
+  render_with: "analytics/dashboard"
+```
+
+The partial receives: `records`, `presenter`, `evaluator`, `action_set`, `ransack_search`, `total_count`, `current_user`, `page_definition`, `params`.
+
+### `layout`
+
+| | |
+|---|---|
+| **Default** | `"table"` |
+| **Type** | string (`table`, `tiles`, `tree`) |
+
+Index page layout mode. `table` renders a standard data table, `tiles` renders a responsive card grid, `tree` renders a tree hierarchy. The `tree_view: true` flag is still supported for backward compatibility but `layout: tree` is preferred. Ignored when `render_with` is set.
+
+### `description`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string |
+
+Descriptive text displayed below the page heading. Available on `index`, `show`, and `form` views.
+
+```yaml
+index:
+  description: "Browse all deals in your pipeline."
+```
+
+### `default_view`
+
+| | |
+|---|---|
+| **Default** | `"table"` |
+| **Type** | string |
+
+The default display mode for the index page.
+
+### `views_available`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | not set |
+| **Type** | array of strings |
+
+List of available view modes the user can switch between (e.g., `[table, tiles]`). This is a metadata attribute for future UI support of multiple view modes.
+
+### `default_sort`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | hash |
+
+Default sorting for the index page.
+
+```yaml
+default_sort: { field: created_at, direction: desc }
+```
+
+- `field` — column name to sort by
+- `direction` — `asc` or `desc`
+
+### `per_page`
+
+| | |
+|---|---|
+| **Default** | `25` |
+| **Type** | integer |
+
+Number of records per page. Used by Kaminari pagination.
+
+### `row_click`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | not set |
+| **Type** | string |
+
+When set to `"show"`, clicking any table row navigates to the record's show page. This makes the entire row clickable, not just link columns. When omitted, rows are not clickable (users navigate via link columns or action buttons).
+
+```yaml
+index:
+  row_click: show
+```
+
+### `empty_message`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | not set |
+| **Type** | string |
+
+Custom message displayed when no records match the current search or filter. If omitted, a generic empty state is shown.
+
+```yaml
+index:
+  empty_message: "No deals match your criteria. Try adjusting your filters."
+```
+
+### `actions_position`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | inline |
+| **Type** | string |
+
+Controls how single-record actions are rendered in each table row. When set to `"dropdown"`, all single actions are grouped into a dropdown menu (useful when there are many actions). The default behavior renders each action as an inline button.
+
+```yaml
+index:
+  actions_position: dropdown
+```
+
+### `includes`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `[]` |
+| **Type** | array of strings or nested hashes |
+
+Manually specify associations to preload for display purposes. Auto-detection handles most cases, but this allows explicit overrides. See [Eager Loading](eager-loading.md).
+
+```yaml
+index:
+  includes: [company, contact]
+```
+
+### `eager_load`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `[]` |
+| **Type** | array of strings or nested hashes |
+
+Manually specify associations to eager load via LEFT JOIN. Use when associations are needed for sorting or filtering. See [Eager Loading](eager-loading.md).
+
+```yaml
+index:
+  eager_load: [company]
+```
+
+### `reorderable`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+Enables drag-and-drop reordering of records in the index table. Requires the model to have a [`positioning`](models.md#positioning) configuration.
+
+When `reorderable: true`:
+
+- Drag handles are rendered as the first column in each table row
+- `default_sort` is automatically set to `{ field: <position_field>, direction: asc }` unless explicitly overridden
+- A `PATCH /:slug/:id/reorder` endpoint is available for position updates
+- The table includes `data-reorder-url` and `data-list-version` attributes for the frontend
+- Drag handles are disabled when a search query is active or when sorting by a non-position column
+
+Reordering requires the user to have `update` CRUD permission and write access to the position field. See [Permissions — Positioning](#positioning-and-permissions) for details.
+
+```yaml
+index:
+  reorderable: true
+  table_columns:
+    - { field: name, link_to: show }
+    - { field: position, sortable: true }
+```
+
+See [Record Positioning](../design/record_positioning.md) for the full design.
+
+### `tree_view`
+
+| | |
+|---|---|
+| **Default** | `false` |
+| **Type** | boolean |
+
+Enables tree index rendering for models with `tree` enabled. Instead of a flat paginated table, records are displayed in a hierarchical tree with expand/collapse controls, connecting guide lines, and indentation. All records are loaded (no pagination).
+
+The model must have `options.tree` enabled, otherwise `ConfigurationValidator` raises an error.
+
+```yaml
+index:
+  tree_view: true
+  table_columns:
+    - { field: name, width: "40%", link_to: show }
+    - { field: "parent.name", label: "Parent" }
+```
+
+### `default_expanded`
+
+| | |
+|---|---|
+| **Default** | `0` |
+| **Type** | integer or `"all"` |
+
+Controls how many tree levels are expanded by default when the tree index loads. `0` collapses everything (only roots visible), `1` shows roots and their direct children, `"all"` expands the entire tree. Only meaningful when `tree_view: true`.
+
+During search/filter, all matched nodes and their ancestors are always expanded regardless of this setting.
+
+```yaml
+index:
+  tree_view: true
+  default_expanded: 1    # expand one level
+  # default_expanded: "all"  # expand everything
+```
+
+### `reparentable`
+
+| | |
+|---|---|
+| **Default** | `false` |
+| **Type** | boolean |
+
+Enables drag-and-drop reparenting on the tree index. Rows get a drag handle, and users can drag nodes to change their parent. Dropping on the root drop zone makes a node a root. Cycle detection prevents invalid drops (dropping a parent onto its descendant).
+
+Requires `tree_view: true` and model `tree` to be enabled. The user must have `update` CRUD permission and write access to the parent field. Uses optimistic locking via tree version hash to prevent conflicts.
+
+```yaml
+index:
+  tree_view: true
+  default_expanded: 1
+  reparentable: true
+```
+
+See [Tree Structures Reference](tree-structures.md) for full reparenting endpoint details.
+
+### `tile`
+
+| | |
+|---|---|
+| **Required** | no (only meaningful with `layout: tiles`) |
+| **Type** | hash |
+
+Tile-layout-specific grid configuration. Card zone rendering lives in the sibling [`card`](#card) block.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `columns` | integer | 3 | Grid columns (overridden by responsive breakpoints) |
+
+### `card`
+
+| | |
+|---|---|
+| **Required** | when using a card-based layout (`tiles`, `kanban`, future) |
+| **Type** | hash |
+
+Per-record card interior shared across card-based layouts. Zone resolution lives in `LcpRuby::Display::CardHelper`; per-layout body partials compose these zones in their own order. See the [Tiles View Guide](../guides/tiles.md) for layout-specific examples.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `title_field` | string | *required* | Field displayed as the card title. Title becomes a link when index-level `row_click` is set. |
+| `subtitle_field` | string | — | Field displayed below the title |
+| `subtitle_renderer` | string | — | Renderer for the subtitle |
+| `subtitle_options` | hash | — | Options passed to the subtitle renderer |
+| `description_field` | string | — | Field for card description (line-clamped) |
+| `description_max_lines` | integer | 3 | Max description lines |
+| `image_field` | string | — | Field containing image URL or Active Storage attachment for the banner zone |
+| `image_alt_field` | string | — | Field providing alt text for the banner image (falls back to `title_field` value) |
+| `avatar_field` | string | — | Field containing image URL or attachment for the small circular avatar |
+| `avatar_alt_field` | string | — | Field providing alt text for the avatar (defaults to "" — decorative) |
+| `color_field` | string | — | Field whose value drives the color accent. Mapped through `color_map` (or workflow state color) to a whitelisted palette token. Raw values never reach CSS. |
+| `color_map` | hash | — | Maps field values to whitelisted palette tokens (`success`, `danger`, `warning`, `info`, `muted`, `primary`) |
+| `actions` | string | `dropdown` | `dropdown`, `inline`, or `none` |
+| `render_with` | string | — | Host-app partial path (e.g., `my_app/cards/deal`) that overrides the entire card body |
+| `fields` | array | — | Additional label-value fields in the card body. Each entry: `{ field, label?, renderer?, options?, partial? }` (`partial` wins over `renderer` if both set) |
+
+> **Note:** the legacy `card_link:` key (placed inside `tile:` in earlier versions) is removed. Use index-level [`row_click`](#row_click) instead.
+
+### `sort_fields`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | array of `{ field, label }` objects |
+
+Fields available in the sort dropdown. Shows a `<select>` in the filter bar allowing users to pick a sort field and toggle direction.
+
+```yaml
+sort_fields:
+  - field: name
+    label: Name
+  - field: price
+    label: Price
+```
+
+### `per_page_options`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | array of positive integers |
+
+Selectable page sizes shown in a dropdown near pagination. When set, users can switch between page sizes.
+
+```yaml
+per_page: 25
+per_page_options: [10, 25, 50, 100]
+```
+
+### `show_record_count`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `true` |
+| **Type** | boolean |
+
+Shows a record count text in the pagination footer bar (e.g., "Showing 1-25 of 312 records"). When `false`, the count text is hidden but pagination links and per-page selector still render.
+
+On grouped layouts the text reads "groups" instead of "records" because the total reflects the number of groups, not individual records.
+
+```yaml
+index:
+  show_record_count: false   # hide record count
+```
+
+### `pagination_ends`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` (from `LcpRuby.configuration.pagination_ends`) |
+| **Type** | boolean |
+
+Shows "First" and "Last" page links alongside the Prev/Next navigation in the pagination footer. Per-presenter override of the global [engine configuration](engine-configuration.md#pagination_ends) setting.
+
+```yaml
+index:
+  pagination_ends: true   # show First/Last links for this presenter
+```
+
+### `summary`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | hash with `enabled` and `fields` |
+
+Horizontal bar below the index content displaying aggregate values computed on the filtered scope (before pagination).
+
+```yaml
+summary:
+  enabled: true
+  fields:
+    - field: price
+      function: sum
+      label: Total Revenue
+    - field: price
+      function: avg
+      label: Average Price
+```
+
+Each field requires `field` and `function` (`sum`, `avg`, `count`, `min`, `max`). Optional `label`, `renderer`, and `options` keys.
+
+### `item_classes`
+
+| | |
+|---|---|
+| **Default** | `[]` |
+| **Type** | array of rule objects |
+
+Conditional CSS classes applied to each row (`<tr>`) or card element based on record field values. All matching rules accumulate — a record matching multiple rules gets all their CSS classes.
+
+```yaml
+index:
+  item_classes:
+    - class: "lcp-row-muted lcp-row-strikethrough"
+      when: { field: status, operator: eq, value: "done" }
+    - class: "lcp-row-danger"
+      when: { field: status, operator: eq, value: "overdue" }
+    - class: "lcp-row-bold"
+      when: { field: priority, operator: eq, value: "critical" }
+```
+
+#### Rule Attributes
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `class` | string | yes | One or more CSS class names (space-separated) to apply when the condition matches |
+| `when` | hash | yes | A [condition](condition-operators.md) (`field`/`operator`/`value` or `service`) evaluated against each record |
+
+#### Cross-Layout Support
+
+`item_classes` applies across all index layouts:
+
+| Layout | Applied to |
+|--------|-----------|
+| `table` | `<tr>` element in the table body |
+| `tree` | `<tr>` element for each tree node |
+| `tiles` | `.lcp-tile-card` container element |
+
+#### Built-in Utility Classes
+
+| Class | Visual Effect |
+|-------|---------------|
+| `lcp-row-danger` | Light red background (`--lcp-row-danger-bg`) |
+| `lcp-row-warning` | Light amber background (`--lcp-row-warning-bg`) |
+| `lcp-row-success` | Light green background (`--lcp-row-success-bg`) |
+| `lcp-row-info` | Light blue background (`--lcp-row-info-bg`) |
+| `lcp-row-muted` | Reduced opacity (`--lcp-row-muted-opacity`) |
+| `lcp-row-bold` | Bold text |
+| `lcp-row-strikethrough` | Line-through text decoration |
+
+All background classes use CSS custom properties for host app theming. Custom CSS classes are also supported.
+
+#### Permissions
+
+Conditions are evaluated regardless of field read permissions. The styling is server-side and does not expose field values — it only adds CSS classes to the HTML element.
+
+#### Validation
+
+`ConfigurationValidator` validates `item_classes` at boot using the same rules as `visible_when`/`disable_when`: field existence, operator validity, and operator-type compatibility.
+
+### `table_columns`
+
+| | |
+|---|---|
+| **Default** | `[]` |
+| **Type** | array of column objects |
+
+Defines which columns appear in the index table and how they render.
+
+```yaml
+table_columns:
+  - field: title
+    width: "30%"
+    link_to: show
+    sortable: true
+    renderer: null
+```
+
+#### Column Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `field` | string | Model field name to display. Supports dot-notation (e.g., `"company.name"`) and template syntax (e.g., `"{first_name} {last_name}"`) |
+| `label` | string | Custom column header label. Defaults to humanized last segment of the field name. Useful for dot-path fields (e.g., `"company.name"` → label `"Company"`) |
+| `width` | string | CSS width (e.g., `"30%"`, `"200px"`) |
+| `link_to` | string | **Legacy.** Makes the cell a link to the **current row's** show page. Value `show`. Preserved for backward compatibility — prefer `link: true` below for new configurations |
+| `link` | boolean | Wrap the cell value in a link. Auto-detects the target: dot-path (`"manager.display_name"`) links to the last `belongs_to` record in the chain (including multi-level chains like `"manager.organizational_unit.name"`); a plain `belongs_to` field name links to that record; a scalar field links to the current row (same as legacy `link_to: :show`). Use `link_through:` to override |
+| `link_through` | string | Name of a `belongs_to` association on this model to follow for the link target. Implies `link: true`. Use when the displayed field's name doesn't correspond to the linked entity (e.g. a precomputed virtual column label). Incompatible with `link_to: :show` |
+| `link_presenter` | string | Override the target presenter slug for this link. Use when the linked model has multiple presenters and you want a non-default one (e.g. compact card on this column, full detail elsewhere). Falls back to the model's `default: true` presenter when absent. See [Multiple presenters per model](#multiple-presenters-per-model) |
+| `sortable` | boolean | Enables column header sorting |
+| `renderer` | string | Renderer for the field value (see [Renderers](#renderers)). Alternatively, use `partial: "path/to/partial"` to render with a custom view partial |
+| `options` | hash | Options passed to the renderer (see [Renderers](#renderers) for per-renderer options) |
+| `hidden_on` | array/string | Hide column at specific breakpoints. Values: `"mobile"`, `"tablet"`. Accepts a single string or an array |
+| `pinned` | string | Pin column to one side on horizontal scroll. Value: `"left"` |
+| `summary` | string | Adds a summary row at the bottom of the table for this column. Values: `"sum"`, `"avg"`, `"count"` |
+| `display_in_index` | boolean | Per-column opt-in for fields whose type carries `default_index_visible: false` (`:text`, `:rich_text`, `:attachment`, `:json`, `:array`, `:file`). Without this kwarg the configuration validator emits a row-unfriendly-column warning suggesting either an explicit `renderer:` or this opt-in. No runtime effect — purely a validator-silencer. See [Types Reference — `default_index_visible`](types.md#default_index_visible) |
+
+**Example with new column attributes:**
+
+```yaml
+table_columns:
+  - field: name
+    width: "25%"
+    link_to: show
+    sortable: true
+    pinned: left
+  - field: email
+    hidden_on: [mobile, tablet]
+  - field: status
+    renderer: badge
+    options:
+      color_map:
+        active: green
+        inactive: gray
+        pending: yellow
+  - field: revenue
+    renderer: currency
+    options:
+      currency: "$"
+      precision: 2
+    sortable: true
+    summary: sum
+  - field: deals_count
+    summary: count
+    hidden_on: mobile
+```
+
+## Grouped Query Mode
+
+Setting `query_mode: grouped` on the `index` block switches the presenter from a flat record list to a GROUP BY query. The index table shows one row per group (e.g., one row per category, one row per month), with aggregate columns computing COUNT, SUM, AVG, MIN, or MAX across the records in each group.
+
+Grouped presenters are read-only by design: show, edit, form, and CRUD actions are not available. Use them for reporting views, summary dashboards, and drill-through navigation.
+
+### Index-Level Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query_mode` | string | — | Set to `grouped` to enable grouped query mode |
+| `group_by` | array | (required when grouped) | Fields to GROUP BY. Each element is a field name (string) or a hash `{ field: name, period: year\|quarter\|month\|week\|day }` for date truncation |
+| `having` | array | `[]` | Post-aggregation filters applied after grouping. Each entry: `{ field: aggregate_column, operator: op, value: val }`. Operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte` |
+| `limit` | integer | — | Maximum number of group rows returned. When set, pagination is disabled |
+| `row_click` | hash | — | `{ mode: filter, target: presenter-slug }` — clicking a row navigates to the target presenter with Ransack filter params pre-filled from the group's values |
+
+### Column-Level Attributes
+
+When `query_mode: grouped`, `table_columns` entries support two additional attributes:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `aggregate` | string or hash | Aggregate function for this column. Short form: `count`. Full form: `{ function: sum, field: amount }` |
+| `aggregate.function` | string | `count`, `sum`, `avg`, `min`, `max` |
+| `aggregate.field` | string | Source field for sum/avg/min/max aggregates |
+| `aggregate.distinct` | boolean | When `true`, generates `AGG(DISTINCT field)` |
+| `group_field` | string | References the original `group_by` field when the column name differs from the grouped field (e.g., a period-truncated date) |
+| `sort_strategy` | string | Enum columns only. `definition_order` (default for enums) sorts by position in the model's enum values list using CASE WHEN SQL. `value` sorts alphabetically by raw value. Applies to both grouped and non-grouped index views |
+
+Columns without an `aggregate` key display the group-by value for that column. Columns with `aggregate` display the computed aggregate.
+
+### Basic Example
+
+```yaml
+presenter:
+  name: products_by_category
+  model: product
+  label: "Products by Category"
+  slug: products-by-category
+
+  index:
+    query_mode: grouped
+    group_by: [category]
+    row_click:
+      mode: filter
+      target: products
+    table_columns:
+      - { field: category, sortable: true }
+      - { field: product_count, aggregate: count, sortable: true }
+      - { field: total_price, aggregate: { function: sum, field: price }, sortable: true }
+```
+
+### HAVING Filters
+
+Use `having` to filter groups after aggregation — for example, to show only categories with at least 5 products:
+
+```yaml
+index:
+  query_mode: grouped
+  group_by: [category]
+  having:
+    - { field: product_count, operator: gte, value: 5 }
+  table_columns:
+    - { field: category, sortable: true }
+    - { field: product_count, aggregate: count, sortable: true }
+```
+
+### Date Period Grouping
+
+Group by a date field truncated to a period (year, quarter, month, week, or day):
+
+```yaml
+index:
+  query_mode: grouped
+  group_by:
+    - { field: created_at, period: month }
+  table_columns:
+    - { field: month, group_field: created_at, sortable: true }
+    - { field: order_count, aggregate: count, sortable: true }
+    - { field: revenue, aggregate: { function: sum, field: total }, sortable: true }
+```
+
+The `group_field` attribute on the column tells the presenter which `group_by` entry this column corresponds to when the column name (`month`) differs from the source field (`created_at`).
+
+### Constraints
+
+- `show`, `edit`, `form` sections are ignored in grouped mode
+- CRUD actions (`create`, `edit`, `destroy`) are not available
+- `row_click: show` has no effect (no individual record to show); use `{ mode: filter, target: ... }` for drill-through instead
+- Quick search and advanced filters apply to the base scope before grouping, not to the group rows themselves
+
+---
+
+## Field Path Syntax
+
+The `field` attribute in `table_columns` and show `fields` supports three syntaxes beyond simple field names:
+
+### Dot-Notation (Association Traversal)
+
+Use dot-notation to display fields from associated records:
+
+```yaml
+table_columns:
+  - { field: "company.name", sortable: true }        # belongs_to traversal
+  - { field: "company.industry", renderer: badge }     # with renderer
+  - { field: "contacts.full_name", renderer: collection }  # has_many traversal
+```
+
+For `belongs_to`/`has_one`, the resolved value is a scalar. For `has_many`, the resolved value is an array (use the `collection` renderer).
+
+Dot-paths can be nested: `company.industry.name` traverses `company` → `industry` → `name`.
+
+**Permissions:** Each segment in the dot-path is checked against `readable_fields` on the target model. If any segment is not readable, the column is hidden.
+
+**Eager loading:** Dot-path fields are automatically detected by the `IncludesResolver` and the required associations are preloaded to prevent N+1 queries.
+
+### Template Syntax (Multi-Field Interpolation)
+
+Use `{field}` syntax to combine multiple fields into a single display value:
+
+```yaml
+table_columns:
+  - { field: "{first_name} {last_name}" }
+  - { field: "{company.name}: {title}" }     # dot-paths inside templates
+```
+
+Template fields extract all `{ref}` references and resolve each one individually. Dot-paths inside templates work the same as standalone dot-paths.
+
+**Permissions:** All referenced fields must be readable for the template column to be visible.
+
+### Collection Renderer
+
+The `collection` renderer renders arrays (typically from `has_many` dot-paths) as formatted lists:
+
+```yaml
+table_columns:
+  - field: "contacts.full_name"
+    renderer: collection
+    options:
+      separator: ", "          # default: ", "
+      limit: 3                 # max items to show
+      overflow: "..."          # text appended when truncated (default: "...")
+      item_renderer: badge     # apply a renderer to each item
+      item_options:            # options for the per-item renderer
+        color_map: { ... }
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `separator` | string | `", "` | Separator between items |
+| `limit` | integer | all | Maximum number of items to display |
+| `overflow` | string | `"..."` | Text appended when items are truncated |
+| `item_renderer` | string | none | Renderer to apply to each item before joining |
+| `item_options` | hash | `{}` | Options for the per-item renderer |
+
+### Custom Renderers
+
+Custom renderers defined in `app/renderers/` can be referenced by name in the `renderer` attribute:
+
+```yaml
+table_columns:
+  - field: stage
+    renderer: conditional_badge
+    options:
+      rules:
+        - match: { in: [closed_won] }
+          renderer: badge
+          options: { color_map: { closed_won: green } }
+        - default:
+            renderer: badge
+```
+
+You can also use `partial:` to render a field with a custom view partial instead of a renderer class:
+
+```yaml
+table_columns:
+  - field: stage
+    partial: "shared/stage_indicator"
+```
+
+See [Custom Renderers Guide](../guides/custom-renderers.md) for creating custom renderers.
+
+## Renderers
+
+Renderers control how field values are rendered in index tables and show pages. Each renderer can accept `options` to customize its behavior. You can also use `partial: "path/to/partial"` instead of a renderer to render a field with a custom view partial.
+
+The renderer name is validated at boot — if you pass an unknown key (e.g. `renderer: extrnal_link`), `bundle exec rake lcp_ruby:validate` raises an error with a "Did you mean…" suggestion and the full list of available renderers. **Type names are accepted as renderer synonyms** when the type's `TypeDefinition#renderer` is set: `renderer: enum` resolves to `:badge` (the `:enum` type's default renderer), `renderer: text` keeps its existing alias to passthrough (the alias table wins over the type-registry fallback). See [Aliases](#aliases) below for the full precedence rules.
+
+### Row-unfriendly column warning
+
+`bundle exec rake lcp_ruby:validate` warns when an index `table_columns` entry references a field whose type is row-unfriendly (`:text`, `:rich_text`, `:attachment`, `:json`, `:array`, `:file` — types whose values don't render well in a row). Three escape hatches silence the warning:
+
+- **`renderer:`** — pick a row-friendly renderer (e.g. `:truncate` for `:text`, `:code` for `:json`).
+- **`partial:`** — supply a custom view partial that handles the cell content.
+- **`display_in_index: true`** — explicit opt-in; tells the validator the configurator knows the value is non-trivial in a row but wants it anyway. Has no runtime effect (purely a validator-silencer).
+
+Example:
+
+```yaml
+table_columns:
+  - field: title
+  - field: body                          # WARN: :text not row-friendly
+  - field: body                          # silenced — explicit renderer
+    renderer: truncate
+  - field: body                          # silenced — opt-in
+    display_in_index: true
+```
+
+The warning is suppressed for `bind_to:` models (host AR class owns its presenter authoring decisions).
+
+### Aliases
+
+Several renderer keys are aliases for canonical renderers. Use whichever name reads better in your presenter:
+
+| Alias | Canonical | Notes |
+|-------|-----------|-------|
+| `boolean` | `boolean_icon` | Renders ✓/✗ glyph (with Lucide SVG when available) |
+| `email` | `email_link` | `<a href="mailto:…">` |
+| `phone` | `phone_link` | `<a href="tel:…">` |
+| `url` / `external_link` | `url_link` | `<a target="_blank" rel="noopener">` for safe http(s) URLs |
+| `json` | `code` | Uses `code`'s JSON pretty-print path |
+| `text` | (passthrough) | Renders `value.to_s` — equivalent to omitting `renderer:` |
+| `enum` | `badge` | Implicit alias resolved via the type registry — `:enum` type's `TypeDefinition#renderer` is `"badge"`. See note below |
+
+**Type-name fallback (Phase 4 of type-system defaults).** Any registered type whose `TypeDefinition#renderer` is set is accepted as a renderer synonym. Resolution order:
+
+1. **Registered renderer table** (the explicit aliases above) — wins. E.g. `renderer: text` returns the passthrough Text renderer regardless of what `:text` type's default is.
+2. **Type registry fallback** — if the key isn't a registered renderer, runtime consults `Types::TypeRegistry.renderer_for(key)` and uses the resolved renderer if any. E.g. `renderer: enum` is NOT in the alias table but the `:enum` type's renderer is `"badge"`, so it resolves to the Badge renderer.
+3. **Returns nil** if neither layer resolves — view template falls through to the value-shape heuristic (Array → collection, AR::Base → display_association_value, etc.).
+
+`bundle exec rake lcp_ruby:validate` accepts type-name synonyms as valid renderer keys (Phase 4 alignment); the validator does not mutate the metadata, so `renderer: enum` stays as `"enum"` in the parsed metadata and runtime resolves it via the type registry on every render. See `docs/design/type_system_defaults.md` Decision 4 for the full rationale.
+
+### Type-driven renderer defaults (`runtime_type_renderers`)
+
+When `LcpRuby.configuration.runtime_type_renderers = true`, presenter columns whose `renderer:` is **absent** get a type-driven default at column-set build time. So `column :flag` on a `:boolean` field auto-renders as `boolean_icon` (✓/✗ glyph) and `column :status` on an `:enum` field auto-renders as a `badge` — without writing `renderer:` explicitly. The defaults come from each type's `TypeDefinition#renderer` (see [Types Reference — `renderer`](types.md#renderer)).
+
+The flag is `false` for one release after Phase 4 lands so existing apps keep their current rendering; `true` from the start in new apps via `lcp new`. To opt in:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.runtime_type_renderers = true
+end
+```
+
+Behavior changes when the flag is on:
+
+- `column :flag` (where `flag` is `:boolean`) — was raw `"true"`/`"false"` text, becomes `boolean_icon`.
+- `column :status` (where `status` is `:enum`) — was the humanized enum label via `format_enum_display`, becomes a `badge` (same label, wrapped in a badge box).
+
+Explicit `renderer:` always wins (idempotent skip), so columns that already specify a renderer are unaffected. See [Engine Configuration — `runtime_type_renderers`](engine-configuration.md#runtime_type_renderers).
+
+### `heading`
+
+Renders the value as `<strong>` text. Useful for primary identifiers.
+
+```yaml
+{ field: title, renderer: heading }
+```
+
+### `badge`
+
+Renders the value as a colored badge. Useful for enum and status fields.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `color_map` | hash | Maps field values to badge colors |
+
+Available colors: `green`, `red`, `blue`, `yellow`, `orange`, `purple`, `gray`, `teal`, `cyan`, `pink`.
+
+```yaml
+- field: status
+  renderer: badge
+  options:
+    color_map:
+      active: green
+      inactive: gray
+      pending: yellow
+      suspended: red
+```
+
+### `truncate`
+
+Truncates long text with an ellipsis.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `max` | integer | `50` | Maximum number of characters before truncation |
+
+```yaml
+- field: description
+  renderer: truncate
+  options:
+    max: 100
+```
+
+### `boolean_icon`
+
+Shows a colored glyph (✓ / ✗) for true / false values. The glyph is wrapped in `<i data-lucide="check|x">`; the engine layout ships Lucide and replaces it with an inline SVG on first paint and on every Turbo navigation. The Unicode glyph in the placeholder text stays visible as a graceful fallback if Lucide ever fails to load. The visible label is exposed via an `.sr-only` span for screen readers.
+
+Pass `true_icon` / `false_icon` to opt out of the Lucide / glyph default and render plain text content instead (useful when you want a custom icon character or a localized short text).
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `true_icon` | string | Plain-text content for true (disables Lucide + glyph) |
+| `false_icon` | string | Plain-text content for false (disables Lucide + glyph) |
+
+```yaml
+- field: verified
+  renderer: boolean_icon
+# legacy plain-text mode:
+- field: verified
+  renderer: boolean_icon
+  options:
+    true_icon: "✅"
+    false_icon: "❌"
+```
+
+### `progress_bar`
+
+Renders a horizontal progress bar.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `max` | integer | `100` | Maximum value (100% mark) |
+
+```yaml
+- field: completion
+  renderer: progress_bar
+  options:
+    max: 100
+```
+
+### `image`
+
+Renders the field value as an image URL.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `size` | string | Image size: `"small"`, `"medium"`, `"large"` |
+
+```yaml
+- field: photo_url
+  renderer: image
+  options:
+    size: medium
+```
+
+### `avatar`
+
+Renders a circular avatar image.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `size` | integer | `32` | Avatar diameter in pixels |
+
+```yaml
+- field: profile_image
+  renderer: avatar
+  options:
+    size: 48
+```
+
+### `currency`
+
+Formats a numeric value as currency. Uses `I18n.locale` for thousands separator, decimal mark, and unit positioning — your locale's `number.currency.format` (e.g., `cs.yml` ships `"%n %u"` with `,` decimal and ` ` thousands → `1 490,00 Kč`). Pass `currency:` to override the unit symbol; the format itself stays locale-driven.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `currency` | string | Currency unit override (e.g., `"USD"`, `"€"`). When omitted, the locale's default unit applies. |
+| `precision` | integer | Number of decimal places |
+
+```yaml
+- field: amount
+  renderer: currency
+  options:
+    currency: "USD"
+    precision: 2
+```
+
+### `percentage`
+
+Formats a numeric value as a percentage.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `precision` | integer | Number of decimal places |
+
+```yaml
+- field: margin
+  renderer: percentage
+  options:
+    precision: 1
+```
+
+### `number`
+
+Formats a numeric value with delimiters and precision.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `delimiter` | string | Thousands separator (e.g., `","`) |
+| `precision` | integer | Number of decimal places |
+
+```yaml
+- field: population
+  renderer: number
+  options:
+    delimiter: ","
+    precision: 0
+```
+
+### `date`
+
+Formats a date value.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `format` | string | `"%Y-%m-%d"` | strftime format string |
+
+```yaml
+- field: birth_date
+  renderer: date
+  options:
+    format: "%B %d, %Y"
+```
+
+### `datetime`
+
+Formats a datetime value. When `format` is omitted, the renderer calls `I18n.l(value, format: :default)` so the output respects your locale's `time.formats.default`. Pass an explicit `format` strftime string to bypass the locale lookup.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `format` | string | Optional strftime format. Omit to use locale-aware `I18n.l(:default)`. |
+
+```yaml
+# Locale-aware (recommended) — cs locale renders e.g. "Sat 25. April 2026, 14:30:00 +0200"
+- field: created_at
+  renderer: datetime
+
+# Explicit ISO format
+- field: created_at
+  renderer: datetime
+  options:
+    format: "%Y-%m-%d %H:%M"
+```
+
+### `relative_date`
+
+Shows a human-readable relative time (e.g., "3 days ago", "in 2 hours").
+
+```yaml
+{ field: updated_at, renderer: relative_date }
+```
+
+### `email_link`
+
+Renders the value as a `mailto:` link.
+
+```yaml
+{ field: email, renderer: email_link }
+```
+
+### `phone_link`
+
+Renders the value as a `tel:` link.
+
+```yaml
+{ field: phone, renderer: phone_link }
+```
+
+### `url_link`
+
+Renders the value as an external link that opens in a new tab.
+
+```yaml
+{ field: website, renderer: url_link }
+```
+
+### `color_swatch`
+
+Renders a color preview swatch alongside the color value.
+
+```yaml
+{ field: brand_color, renderer: color_swatch }
+```
+
+### `rating`
+
+Displays a numeric value as filled stars.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `max` | integer | `5` | Maximum number of stars |
+
+```yaml
+- field: score
+  renderer: rating
+  options:
+    max: 5
+```
+
+### `code`
+
+Renders the value in monospace code formatting.
+
+```yaml
+{ field: api_key, renderer: code }
+```
+
+### `file_size`
+
+Renders a numeric byte value as human-readable file size (e.g., "2.4 MB").
+
+```yaml
+{ field: attachment_size, renderer: file_size }
+```
+
+### `rich_text`
+
+Renders HTML content safely.
+
+```yaml
+{ field: body, renderer: rich_text }
+```
+
+### `link`
+
+Renders the value as a clickable link. Uses `to_label` (if defined on the model) or `to_s` for the display text.
+
+```yaml
+{ field: reference, renderer: link }
+```
+
+### `attachment_preview`
+
+Renders an image preview for attachment fields. For image files, displays the image (optionally using a named variant). For non-image files, falls back to a download link.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `variant` | string | Named variant to use for the image (e.g., `"thumbnail"`, `"medium"`) |
+
+```yaml
+- field: photo
+  renderer: attachment_preview
+  options:
+    variant: medium
+```
+
+### `attachment_list`
+
+Renders a list of download links with filenames and file sizes. Designed for multiple attachment fields.
+
+```yaml
+- field: files
+  renderer: attachment_list
+```
+
+### `attachment_link`
+
+Renders a single download link with the filename. Designed for single non-image attachment fields.
+
+```yaml
+- field: contract
+  renderer: attachment_link
+```
+
+### `empty_value`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string |
+
+Overrides the placeholder text displayed when a field value is `nil` or blank. Takes precedence over the global `LcpRuby.configure { |c| c.empty_value = "..." }` setting and the `lcp_ruby.empty_value` i18n key. The placeholder is rendered with CSS class `lcp-empty-value`.
+
+```yaml
+presenter:
+  name: showcase_fields
+  model: showcase_field
+  empty_value: "N/A"
+```
+
+## Show Configuration
+
+Controls the record detail view.
+
+```yaml
+show:
+  description: "View record details and related items."
+  copy_url: true
+  includes: [contacts, deals]
+  layout:
+    - section: "Section Title"
+      description: "Key information about this record."
+      columns: 2
+      fields:
+        - { field: title, renderer: heading }
+        - { field: stage, renderer: badge }
+        - { type: info, text: "This explains the fields above." }
+    - section: "Related Items"
+      type: association_list
+      association: contacts
+```
+
+### `copy_url`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `true` |
+| **Type** | boolean |
+
+Controls whether the "Copy link" toolbar button is shown on the show page. Set to `false` to hide it (e.g., for read-only summary views where the URL is not useful).
+
+```yaml
+show:
+  copy_url: false
+```
+
+### `includes` / `eager_load`
+
+Same as index configuration. Manually specify associations to preload for the show page. Auto-detection handles `association_list` sections automatically. See [Eager Loading](eager-loading.md).
+
+### `render_with`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string (partial path) |
+
+Replaces the entire show content area with a custom host-app partial while preserving LCP's layout, nav, toolbar, breadcrumbs, and flash messages. Ignored in dialog (`?_dialog=1`) and composite page contexts. See also [Rendering Extension Points](../guides/rendering-extension-points.md).
+
+```yaml
+show:
+  render_with: "products/custom_show"
+```
+
+The partial receives these locals: `record`, `presenter`, `evaluator`, `action_set`, `layout_builder`, `column_set`, `field_value_resolver`, `current_user`, `page_definition`, `params`.
+
+### `layout`
+
+Array of section objects. Each section is rendered as a card or panel.
+
+#### Section Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `section` | string | Section heading text. Used as the i18n fallback when no entry exists at `lcp_ruby.presenters.<presenter>.sections.<parameterized_section>`. |
+| `section_key` | string | Explicit i18n lookup key. Decouples the i18n key from the human-readable label so non-English literals don't leak into the en locale. Lookup: `lcp_ruby.presenters.<presenter>.sections.<section_key>`. Falls back to `section` (or humanized key) when missing. |
+| `description` | string | Explanatory text displayed below the section heading |
+| `columns` | integer | Number of columns in the field grid (default: 1) |
+| `fields` | array | Fields to display (see below) |
+| `type` | string | `association_list`, `json_items_list`, `audit_history`, or `custom` |
+| `association` | string | Association name (required when `type: association_list`) |
+| `partial` | string | Host-app partial path (required when `type: custom`) |
+| `responsive` | hash | Responsive overrides per breakpoint (see below) |
+| `visible_when` | hash | Condition object. When false, the section is not rendered. Same syntax as [field conditions](#conditional-visibility) |
+| `disable_when` | hash | Condition object. When true, the section has a disabled appearance. Same syntax as [field conditions](#conditional-disabling) |
+
+Show page conditions are evaluated **server-side only** — hidden sections are not rendered in the DOM (no client-side JavaScript toggling).
+
+#### Custom Sections (Show)
+
+Set `type: custom` to delegate rendering of a section to a host-app partial. The `fields:` key is ignored — the partial owns all content inside the section wrapper. `columns:` and `disable_when:` are also ignored.
+
+```yaml
+show:
+  layout:
+    - section: "Location"
+      type: custom
+      partial: "employees/location_map"
+```
+
+The partial receives: `record`, `presenter`, `evaluator`, `section_config`, `current_user`, `page_definition`, `params`.
+
+```yaml
+- section: "Metrics"
+  visible_when: { field: stage, operator: not_eq, value: lead }
+  fields:
+    - { field: priority }
+    - { field: progress }
+```
+
+#### Association List Sections
+
+Use `type: association_list` to render a list of associated records within the show page:
+
+```yaml
+- section: "Contacts"
+  type: association_list
+  association: contacts
+  display_template: default
+  link: true
+  sort: { last_name: asc }
+  limit: 5
+  empty_message: "No contacts yet."
+  scope: active
+```
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `association` | string | — | **Required.** Association name from the model |
+| `display_template` | string | `"default"` | Name of the display template defined on the target model |
+| `link` | boolean | `false` | Wrap each record in a link to its show page |
+| `link_through` | string | — | Follow this `belongs_to` association on the target model to resolve the link target (implies `link: true`) |
+| `link_presenter` | string | — | Override the target presenter slug. Use when the linked model has multiple presenters. Falls back to the model's `default: true` presenter. See [Multiple presenters per model](#multiple-presenters-per-model) |
+| `sort` | hash | — | Sort field and direction (e.g., `{ last_name: asc }`) |
+| `limit` | integer | — | Maximum number of records to display |
+| `empty_message` | string | `"No records."` | Message when no associated records exist |
+| `scope` | string | — | Named scope to apply on the association |
+| `visible_when` | hash | — | Condition object. When false, the section is not rendered |
+| `disable_when` | hash | — | Condition object. When true, the section has a disabled appearance |
+
+When `display_template` references a display template defined on the target model (see [Models Reference — Display Templates](models.md#display-templates)), records render with rich HTML including title, subtitle, icon, and badge. Without a display template, records fall back to `to_label`.
+
+When `link: true`, each record is wrapped in a link to the target model's show page (the first presenter for that model is used for routing).
+
+When `link_through` is set, each record links to the related record reached by following the named `belongs_to` association on the target model. For example, `link_through: employee` on a `group_memberships` association list links each membership to the employee's show page instead of the membership's own page. The `link_through` association must be a non-polymorphic `belongs_to`. If the related record is `nil` (orphaned FK) or soft-deleted, the item renders without a link. The user must have `show` permission on the link target model for links to appear.
+
+```yaml
+# Link through a join model to the real entity
+- section: "Members"
+  type: association_list
+  association: group_memberships
+  link_through: employee           # Links to employee show page
+  display_template: default
+```
+
+Sort and limit operate in-memory on preloaded records (unless `scope` is specified, which triggers a SQL query).
+
+#### Responsive Sections
+
+Use `responsive` to override the number of columns at different breakpoints:
+
+```yaml
+- section: "Deal Information"
+  columns: 3
+  responsive:
+    tablet:
+      columns: 2
+    mobile:
+      columns: 1
+  fields:
+    - { field: title, renderer: heading }
+    - { field: stage, renderer: badge }
+    - { field: value, renderer: currency }
+```
+
+#### Show Field Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `field` | string | Model field name. Supports dot-notation and template syntax |
+| `label` | string | Custom field label. Defaults to humanized last segment of the field name. Useful for dot-path fields (e.g., `"company.name"` → label `"Company"`) |
+| `renderer` | string | Renderer for the field value (see [Renderers](#renderers)). Alternatively, use `partial: "path/to/partial"` to render with a custom view partial |
+| `options` | hash | Options passed to the renderer (see [Renderers](#renderers) for per-renderer options) |
+| `copyable` | boolean | Adds a copy-to-clipboard icon next to the field value. When clicked, copies the displayed value to the clipboard with a "Copied!" tooltip. Coexists with `link:` — the link wraps the value and the copy button is rendered outside it |
+| `link` | boolean | Wrap the field value in a link to the associated record. Auto-detects the target from a dot-path (`"manager.display_name"` → manager; `"manager.organizational_unit.name"` → org unit) or from a plain `belongs_to` field name (`field: manager`). Nil / soft-deleted targets, blank values, and users without `:show` on the target render without a link. Incompatible with link-emitting renderers (`email_link`, `url_link`, `markdown`, `rich_text`, …) |
+| `link_through` | string | Name of a `belongs_to` association on this model to follow for the link target. Implies `link: true`. Use when the displayed field's name doesn't correspond to the linked entity (e.g. a precomputed virtual column) |
+| `link_presenter` | string | Override the target presenter slug for this link. Use when the linked model has multiple presenters. Falls back to the model's `default: true` presenter when absent. See [Multiple presenters per model](#multiple-presenters-per-model) |
+| `col_span` | integer | Number of grid columns this field spans (defaults to 1) |
+| `hidden_on` | array/string | Hide field at specific breakpoints. Values: `"mobile"`, `"tablet"` |
+
+**Example with new show field attributes:**
+
+```yaml
+show:
+  layout:
+    - section: "Overview"
+      columns: 3
+      responsive:
+        mobile:
+          columns: 1
+      fields:
+        - { field: title, renderer: heading, col_span: 3 }
+        - field: status
+          renderer: badge
+          options:
+            color_map:
+              active: green
+              inactive: red
+        - { field: email, renderer: email_link }
+        - { field: phone, renderer: phone_link, hidden_on: mobile }
+        - field: revenue
+          renderer: currency
+          options:
+            currency: "$"
+            precision: 2
+```
+
+**Example — link-through on show fields:**
+
+```yaml
+show:
+  layout:
+    - section: "Work Details"
+      columns: 2
+      fields:
+        - { field: "manager.display_name", label: "Manager", link: true }
+        - { field: "organizational_unit.name", label: "Org Unit", link: true }
+        - { field: position, link: true }                                  # plain belongs_to
+        - field: "manager.organizational_unit.name"
+          label: "Manager's Dept"
+          link: true                                                       # multi-level → org unit
+        - { field: manager_label, link_through: manager }                  # virtual/precomputed
+```
+
+Same auto-detection rules apply to index columns via `link:` / `link_through:` — see [Column Attributes](#column-attributes).
+
+## Form Configuration
+
+Controls the create and edit forms.
+
+```yaml
+form:
+  description: "Fill in the record details below."
+  layout: flat
+  includes: [todo_items]
+  sections:
+    - title: "Section Title"
+      description: "Basic information about the record."
+      columns: 2
+      fields:
+        - { type: info, text: "Prices are in USD." }
+        - { field: title, placeholder: "Enter title...", autofocus: true }
+        - { field: stage, input_type: select }
+        - { field: value, input_type: number, prefix: "$" }
+        - { field: company_id, input_type: association_select }
+```
+
+### `includes` / `eager_load`
+
+Same as index configuration. Manually specify associations to preload for the form. Auto-detection handles `nested_fields` sections automatically. See [Eager Loading](eager-loading.md).
+
+### `layout`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `"flat"` |
+| **Type** | string |
+
+Controls how form sections are rendered. When set to `"tabs"`, each section becomes a tab in a tabbed interface. The default `"flat"` layout renders sections as stacked cards.
+
+```yaml
+form:
+  layout: tabs
+  sections:
+    - title: "General"
+      fields:
+        - { field: title }
+        - { field: description, input_type: textarea }
+    - title: "Pricing"
+      fields:
+        - { field: price, input_type: number }
+        - { field: currency, input_type: select }
+    - title: "Advanced"
+      fields:
+        - { field: notes, input_type: rich_text_editor }
+```
+
+### `sections`
+
+Array of form section objects.
+
+#### Form Section Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `title` | string | Section heading text. Used as the i18n fallback when no entry exists at `lcp_ruby.presenters.<presenter>.sections.<parameterized_title>`. |
+| `section_key` | string | Explicit i18n lookup key. Decouples the i18n key from the human-readable label so non-English literals don't leak into the en locale. Lookup: `lcp_ruby.presenters.<presenter>.sections.<section_key>`. Falls back to `title` (or humanized key) when missing. |
+| `description` | string | Explanatory text displayed below the section heading |
+| `columns` | integer | Number of columns in the field grid (default: 1) |
+| `fields` | array | Form fields (see below) |
+| `type` | string | `nested_fields` or `custom`. Default: standard field section |
+| `partial` | string | Host-app partial path (required when `type: custom`) |
+| `additional_permitted_params` | array | Extra param names permitted from the custom section's inputs. Supports scalar strings and nested hash specs. Only for `type: custom` |
+| `collapsible` | boolean | When `true`, the section can be collapsed/expanded by clicking its header |
+| `collapsed` | boolean | When `true` (and `collapsible` is `true`), the section starts in the collapsed state |
+| `visible_when` | hash | Condition object. When the condition evaluates to false, the entire section (fieldset) is hidden. Same syntax as field conditions. See [Conditional Visibility](#conditional-visibility) |
+| `disable_when` | hash | Condition object. When the condition evaluates to true, the entire section is visually disabled. Same syntax as field conditions. See [Conditional Disabling](#conditional-disabling) |
+| `responsive` | hash | Responsive overrides per breakpoint (see below) |
+
+#### Custom Sections (Form)
+
+Set `type: custom` to delegate rendering of a form section to a host-app partial. The `fields:`, `columns:`, and `disable_when:` keys are ignored — the partial owns all content inside the fieldset wrapper.
+
+```yaml
+form:
+  sections:
+    - title: "Variants"
+      type: custom
+      partial: "products/variants_editor"
+      additional_permitted_params:
+        - variants_json
+        - address:
+            - street
+            - city
+            - zip
+```
+
+The partial receives: `record`, `presenter`, `evaluator`, `section_config`, `form` (ActionView form builder), `current_user`, `page_definition`, `params`. The `form` local is the same `FormBuilder` instance from the enclosing `form_with` block.
+
+**Example with conditional sections:**
+
+```yaml
+form:
+  sections:
+    - title: "Basic Information"
+      columns: 2
+      fields:
+        - { field: name }
+        - { field: stage, input_type: select }
+    - title: "Revenue Details"
+      columns: 2
+      visible_when: { field: stage, operator: not_eq, value: lead }
+      fields:
+        - { field: expected_revenue, input_type: number, prefix: "$" }
+        - { field: probability, input_type: slider }
+    - title: "Closed Deal Info"
+      disable_when: { field: stage, operator: not_in, value: [closed_won, closed_lost] }
+      fields:
+        - { field: close_date, input_type: date }
+        - { field: close_reason, input_type: textarea }
+```
+
+**Example with collapsible sections:**
+
+```yaml
+form:
+  sections:
+    - title: "Basic Information"
+      columns: 2
+      fields:
+        - { field: name }
+        - { field: email }
+    - title: "Advanced Options"
+      columns: 2
+      collapsible: true
+      collapsed: true
+      fields:
+        - { field: api_key }
+        - { field: webhook_url }
+```
+
+**Example with responsive sections:**
+
+```yaml
+form:
+  sections:
+    - title: "Contact Details"
+      columns: 3
+      responsive:
+        tablet:
+          columns: 2
+        mobile:
+          columns: 1
+      fields:
+        - { field: first_name }
+        - { field: last_name }
+        - { field: email }
+```
+
+#### Form Field Attributes
+
+> **Note — `required:` is not a form-field attribute.** Presence is enforced on the **model**, not on the form. Use one of:
+>
+> - `belongs_to :customer, required: true` (for FK associations) — adds `validates: { presence: true }` automatically
+> - `validates: { presence: true }` on a `field` declaration in the model YAML/DSL (see [Validations](models.md#validations))
+>
+> Adding `required: true` directly to a form field will be rejected by the validator. The HTML5 `required` attribute on form-only basis (without model validation) is tracked as a future feature — see [aggregated.md C25](../improve-tasks/aggregated.md).
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `field` | string | Model field name or FK column name |
+| `label` | string | Custom label for the field. Defaults to the model field's label. Also used as the text label on `type: divider` pseudo-fields |
+| `input_type` | string | Override the default input type (see below) |
+| `placeholder` | string | Placeholder text for the input |
+| `autofocus` | boolean | Auto-focus this field when the form loads |
+| `prefix` | string | Text prefix displayed before the input (e.g., `"$"` for currency) |
+| `suffix` | string | Text suffix displayed after the input (e.g., `"kg"`, `"%"`) |
+| `col_span` | integer | Number of grid columns this field spans (defaults to 1) |
+| `hint` | string | Help text displayed below the input |
+| `readonly` | boolean | Renders the field as read-only (visible but not editable) |
+| `visible_when` | hash | Condition object. When the condition evaluates to false, the field is hidden (`display:none`). Supports field-value conditions and service conditions. See [Conditional Visibility](#conditional-visibility) |
+| `disable_when` | hash | Condition object. When the condition evaluates to true, the field is visually disabled (opacity reduced, pointer-events disabled) but values are still submitted. Same syntax as `visible_when`. See [Conditional Disabling](#conditional-disabling) |
+| `default` | string | Default value for new records. Supports dynamic defaults (see below) |
+| `input_options` | hash | Type-specific input options (see below) |
+| `options` | hash | Options passed to the renderer when field is shown in read-only mode |
+| `hidden_on` | array/string | Hide field at specific breakpoints. Values: `"mobile"`, `"tablet"` |
+
+**Example with new field attributes:**
+
+```yaml
+fields:
+  - field: title
+    placeholder: "Enter title..."
+    autofocus: true
+    col_span: 2
+    hint: "A descriptive title for the deal"
+  - field: value
+    input_type: number
+    prefix: "$"
+    suffix: "USD"
+    input_options:
+      min: 0
+      step: 0.01
+    disable_when: { field: stage, operator: in, value: [closed_won, closed_lost] }
+  - field: internal_code
+    readonly: true
+    hint: "Auto-generated, cannot be changed"
+  - field: renewal_date
+    visible_when: { field: stage, operator: not_in, value: [lead] }
+  - field: created_at
+    default: current_date
+    hidden_on: mobile
+```
+
+#### Dynamic Defaults
+
+The `default` attribute supports dynamic values that are resolved at form render time:
+
+| Value | Description |
+|-------|-------------|
+| `"current_date"` | Sets the default to today's date |
+| `"current_user.id"` | Sets the default to the current user's ID |
+
+```yaml
+- { field: start_date, default: current_date }
+- { field: assigned_to_id, default: current_user.id }
+```
+
+#### Conditional Visibility
+
+The `visible_when` attribute on **form fields** and **form sections** accepts a condition object that controls whether the element is shown. When the condition evaluates to false, the element is hidden with `display:none` — values are preserved in the DOM and still submitted with the form.
+
+Two types of conditions are supported:
+
+**Field-value conditions** reference another field on the same record and are evaluated client-side with JavaScript for instant reactivity:
+
+```yaml
+# Show only when stage is not "lead"
+- field: expected_revenue
+  visible_when: { field: stage, operator: not_in, value: [lead] }
+
+# Show only when a boolean flag is true
+- field: discount_reason
+  visible_when: { field: discounted, operator: eq, value: true }
+```
+
+**Service conditions** are evaluated server-side (on initial render and via AJAX when field values change):
+
+```yaml
+# Show only when the record is persisted (has been saved)
+- field: internal_code
+  visible_when: { service: persisted_check }
+```
+
+> **Note — `role:` shortcut is page-zone only.** On presenter sections and fields, use a service condition with the `current_user_role` registered service:
+>
+> ```yaml
+> visible_when:
+>   service:
+>     name: current_user_role
+>     in: ["admin", "manager"]
+> ```
+>
+> The `role: [...]` top-level shortcut is recognized only by [page zone visible_when](pages.md#zone-visibility), not by section/field visible_when. The validator emits an explicit hint when this is used in the wrong place.
+
+See [Condition Operators](condition-operators.md) for the full list of supported operators.
+
+#### Conditional Disabling
+
+The `disable_when` attribute on **form fields** and **form sections** accepts a condition object with the same syntax as `visible_when`. When the condition evaluates to true, the element is visually disabled — rendered with reduced opacity (`opacity: 0.6`) and `pointer-events: none`. Unlike the HTML `disabled` attribute, this CSS-based approach means **values are still submitted** with the form.
+
+```yaml
+# Disable the value field when the deal is closed
+- field: value
+  input_type: number
+  prefix: "$"
+  disable_when: { field: stage, operator: in, value: [closed_won, closed_lost] }
+
+# Disable notes when stage is blank
+- field: notes
+  input_type: textarea
+  disable_when: { field: stage, operator: blank }
+```
+
+Field-value conditions use client-side JavaScript for instant reactivity. Service conditions are evaluated server-side.
+
+#### Input Types
+
+| Input Type | Description | Default For |
+|------------|-------------|-------------|
+| `text` | Single-line text input | `string` fields |
+| `textarea` | Multi-line text area | `text` fields |
+| `select` | Dropdown (populated from `enum_values`) | `enum` fields |
+| `number` | Numeric input | `integer`, `float`, `decimal` fields |
+| `date` / `date_picker` | Date picker | `date` fields |
+| `datetime` | Datetime picker | `datetime` fields |
+| `boolean` / `checkbox` | Checkbox (`<input type="checkbox">`) | `boolean` fields |
+| `association_select` | Dropdown populated from associated model's records | FK fields (e.g., `company_id`) |
+| `rich_text_editor` | Rich text editor | `rich_text` fields |
+| `slider` | Range slider input | - |
+| `toggle` | Toggle switch (on/off) | - |
+| `rating` | Star rating input | - |
+| `file_upload` | File upload input with optional preview, drag-and-drop, and direct upload | `attachment` fields |
+| `array_input` / `tags` | Tag-style chip input for multi-valued fields. Add items by typing and pressing Enter | `array` fields |
+
+#### Input Options
+
+Input options provide type-specific configuration for form inputs.
+
+**Text / Textarea:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `rows` | integer | Number of visible rows (textarea only) |
+| `max_length` | integer | Maximum character count |
+| `show_counter` | boolean | Show a character counter below the input |
+
+```yaml
+- field: description
+  input_type: textarea
+  input_options:
+    rows: 6
+    max_length: 500
+    show_counter: true
+```
+
+**Number:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `min` | number | Minimum allowed value |
+| `max` | number | Maximum allowed value |
+| `step` | number | Step increment for the input |
+
+```yaml
+- field: quantity
+  input_type: number
+  input_options:
+    min: 1
+    max: 1000
+    step: 1
+```
+
+**Slider:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `min` | number | Minimum slider value |
+| `max` | number | Maximum slider value |
+| `step` | number | Step increment |
+| `show_value` | boolean | Display the current value alongside the slider |
+
+```yaml
+- field: priority
+  input_type: slider
+  input_options:
+    min: 1
+    max: 10
+    step: 1
+    show_value: true
+```
+
+**Rating:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `max` | integer | Maximum number of stars |
+
+```yaml
+- field: satisfaction
+  input_type: rating
+  input_options:
+    max: 5
+```
+
+**File Upload:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `preview` | boolean | `false` | Show a preview of the current file (image thumbnail or filename) |
+| `drag_drop` | boolean | `false` | Enable drag-and-drop upload zone |
+| `direct_upload` | boolean | `false` | Use Active Storage direct upload (uploads before form submission) |
+
+```yaml
+- field: photo
+  input_type: file_upload
+  input_options:
+    preview: true
+    drag_drop: true
+    direct_upload: true
+```
+
+When `drag_drop` is enabled, the drop zone text adapts automatically: "Drop file here or click to browse" for single attachments, "Drop files here or click to browse" for multiple.
+
+Attachment fields with existing files display a "Remove" checkbox on edit forms. When checked, the attachment is purged on save. For multiple attachments, each file has its own remove checkbox.
+
+Attachment fields auto-resolve to `input_type: file_upload` — you only need to set `input_type` explicitly if you want to override the default.
+
+**Select (enum):**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `include_blank` | boolean/string | Show a blank option. `true` (default) adds an empty option, `false` removes it, a string uses custom text |
+| `include_values` | hash | Role-based whitelist. Keys are role names, values are arrays of allowed enum values |
+| `exclude_values` | hash | Role-based blacklist. Keys are role names, values are arrays of excluded enum values |
+| `sort` | string | Sort options. See ordering table below. Applies to both `select` and `radio` input types |
+
+**Enum option ordering** (`input_options: { sort: ... }`):
+
+| `sort` value | Behavior |
+|--------------|----------|
+| (omitted) | **Default** — declaration order from `enum_values` in the model YAML/DSL |
+| `"alphabetical"` | Sort by label (case-insensitive) |
+| `"reverse"` | Reverse declaration order |
+
+When both `include_values` and `exclude_values` are specified for the same role, `include_values` is applied first (whitelist), then `exclude_values` removes from the remaining set.
+
+```yaml
+# Viewers can only see active and archived statuses
+- field: status
+  input_type: select
+  input_options:
+    include_blank: false
+    include_values:
+      viewer: [active, archived]
+    exclude_values:
+      editor: [deleted]
+```
+
+```yaml
+# Sort enum options alphabetically
+- field: category
+  input_type: select
+  input_options:
+    sort: alphabetical
+```
+
+**Association Select:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `include_blank` | boolean/string | Blank option text. Default: `"-- Select --"`. Set to `false` to remove |
+| `scope` | string | Named scope to apply on the target model (e.g., `"active"`) |
+| `filter` | hash | Hash of field-value pairs passed to `.where()` |
+| `sort` | hash | Hash of field-direction pairs passed to `.order()` (e.g., `{ name: asc }`) |
+| `label_method` | string | Method to call on each record for display text. Default: `to_label` |
+| `group_by` | string | Group options by this field (renders `<optgroup>` tags) |
+| `depends_on` | hash | Cascading select configuration (see below) |
+| `scope_by_role` | hash | Role-based scope selection. Keys are role names, values are scope names or `"all"` |
+
+```yaml
+# Sorted, with custom label and blank text
+- field: company_id
+  input_type: association_select
+  input_options:
+    sort: { name: asc }
+    label_method: full_name
+    include_blank: "-- Choose company --"
+
+# Grouped by industry
+- field: company_id
+  input_type: association_select
+  input_options:
+    sort: { name: asc }
+    group_by: industry
+
+# Scoped to active records
+- field: contact_id
+  input_type: association_select
+  input_options:
+    scope: active_contacts
+    sort: { last_name: asc }
+    label_method: full_name
+```
+
+**Dependent (cascading) selects:**
+
+Use `depends_on` to create cascading select relationships. When the parent field changes, the dependent select options are refreshed via AJAX.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `field` | string | Parent field name that this select depends on |
+| `foreign_key` | string | FK column on the target model to filter by |
+| `reset_strategy` | string | What happens to the current value when parent changes: `"clear"` (default) or `"keep_if_valid"` |
+
+```yaml
+- field: company_id
+  input_type: association_select
+
+- field: contact_id
+  input_type: association_select
+  input_options:
+    depends_on:
+      field: company_id
+      foreign_key: company_id
+    sort: { last_name: asc }
+    label_method: full_name
+```
+
+**Role-based scope:**
+
+Use `scope_by_role` to apply different scopes depending on the current user's role. The special value `"all"` means no scope is applied (returns all records).
+
+```yaml
+- field: company_id
+  input_type: association_select
+  input_options:
+    scope_by_role:
+      admin: all
+      editor: active_companies
+      viewer: my_companies
+```
+
+When `scope_by_role` is present, the `scope` option is ignored.
+
+**Multi Select:**
+
+For `has_many :through` associations, use `input_type: multi_select` to render a `<select multiple>`.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `association` | string | Name of the `has_many :through` association |
+| `scope` | string | Named scope on the target model |
+| `sort` | hash | Ordering for the options |
+| `label_method` | string | Method for display text |
+| `min` | integer | Minimum required selections |
+| `max` | integer | Maximum allowed selections |
+
+```yaml
+- field: tag_ids
+  input_type: multi_select
+  input_options:
+    association: tags
+    scope: active
+    sort: { name: asc }
+    min: 1
+    max: 5
+```
+
+**Array Input:**
+
+Tag-style chip input for `type: array` fields. Values appear as removable chips. Type text and press Enter to add, click x to remove.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `placeholder` | string | `"Add item..."` | Placeholder text for the text input |
+| `max` | integer | - | Maximum number of items allowed |
+| `suggestions` | array | `[]` | Static suggestion list shown as a dropdown. Already-added values are filtered out |
+
+```ruby
+field :tags, input_type: :array_input, input_options: {
+  placeholder: "Add a tag...",
+  max: 10,
+  suggestions: %w[ruby rails javascript python]
+}
+```
+
+Array fields automatically default to `input_type: array_input` and `renderer: collection` when no explicit override is set.
+
+#### Divider Pseudo-Field
+
+Use a divider to visually separate groups of fields within a section:
+
+```yaml
+fields:
+  - { field: first_name }
+  - { field: last_name }
+  - { type: divider, label: "Contact Information" }
+  - { field: email }
+  - { field: phone }
+  - { type: divider }
+  - { field: notes, input_type: textarea }
+```
+
+A divider with a `label` renders a labeled horizontal rule. A divider without a `label` renders a plain separator line.
+
+#### Info Pseudo-Field
+
+Use an info pseudo-field to add contextual help text within a section. The info text spans the full width of the grid and renders as a styled callout.
+
+```yaml
+fields:
+  - { type: info, text: "Prices are in USD. Tax is calculated automatically." }
+  - { field: price, input_type: number }
+  - { field: tax_rate, input_type: number }
+```
+
+Info pseudo-fields work in both `form` and `show` sections.
+
+#### Nested Fields
+
+Use `type: nested_fields` to manage a list of structured items inline within the parent form. Items can come from three different data sources, all rendered through the same pipeline:
+
+| Source | Config Key | Data Origin | Persistence |
+|--------|-----------|-------------|-------------|
+| Association | `association:` | has_many child records | `accepts_nested_attributes_for` |
+| JSON field (inline) | `json_field:` | JSON column value | JSON array in single column |
+| JSON field (model-backed) | `json_field:` + `target_model:` | JSON column value | JSON array, virtual model field defs |
+
+##### Association Source
+
+The most common mode — edits `has_many` child records inline:
+
+```yaml
+form:
+  sections:
+    - title: "Line Items"
+      type: nested_fields
+      association: line_items
+      allow_add: true
+      allow_remove: true
+      add_label: "Add Line Item"
+      min: 1
+      max: 20
+      columns: 3
+      fields:
+        - { field: product_id, input_type: association_select }
+        - { field: quantity, input_type: number }
+        - { field: unit_price, input_type: number, prefix: "$" }
+```
+
+##### JSON Field Source (Inline)
+
+Stores items as a JSON array of hashes in a single column. Field types and labels are declared directly in the presenter — no separate model needed:
+
+```yaml
+form:
+  sections:
+    - title: "Workflow Steps"
+      type: nested_fields
+      json_field: steps
+      sortable: true
+      allow_add: true
+      allow_remove: true
+      columns: 2
+      fields:
+        - { field: name, type: string, label: "Step Name" }
+        - field: action_type
+          type: string
+          input_type: select
+          options: [review, approve, notify]
+        - field: timeout_days
+          type: integer
+          label: "Timeout (days)"
+          visible_when: { field: action_type, operator: eq, value: review }
+```
+
+The parent model must have a `json` type field (e.g., `steps: json`). Each item is stored as a hash in the array. Inline mode is best for simple, ad-hoc structures where creating a full model definition is unnecessary.
+
+##### JSON Field Source (Model-Backed)
+
+For complex, reusable structures that need validations, transforms, or custom types. The item structure is defined as a virtual model (`table_name: _virtual`):
+
+```yaml
+# config/lcp_ruby/models/address.yml
+model:
+  name: address
+  table_name: _virtual
+  fields:
+    - name: street
+      type: string
+      validations: [{ type: presence }]
+    - name: city
+      type: string
+      validations: [{ type: presence }]
+    - name: zip
+      type: string
+    - name: country
+      type: string
+      default: "CZ"
+```
+
+The presenter references the virtual model via `target_model:`:
+
+```yaml
+# Presenter section
+- title: "Addresses"
+  type: nested_fields
+  json_field: addresses
+  target_model: address
+  allow_add: true
+  allow_remove: true
+  columns: 2
+  fields:
+    - { field: street }
+    - { field: city }
+    - { field: zip }
+    - { field: country }
+```
+
+Field definitions (type, label, validations) come from the target model. Each item is wrapped in a `JsonItemWrapper` for form rendering and validated against the model's rules on save. See [Virtual Models](models.md#virtual-models) for details.
+
+##### Sub-Sections in Nested Rows
+
+For complex items with many fields, use `sub_sections` instead of `fields` to group fields within each row:
+
+```yaml
+- title: "Addresses"
+  type: nested_fields
+  json_field: addresses
+  target_model: address
+  allow_add: true
+  allow_remove: true
+  sub_sections:
+    - title: "Location"
+      columns: 2
+      fields:
+        - { field: street }
+        - { field: city }
+        - { field: zip }
+        - { field: country }
+    - title: "Additional"
+      columns: 1
+      collapsible: true
+      collapsed: true
+      fields:
+        - { field: notes }
+        - { field: is_primary, input_type: boolean }
+```
+
+Each sub-section renders as a `<fieldset>` inside the row. Sub-sections support `collapsible`/`collapsed`, `visible_when`, `disable_when`, and their own `columns` grid. You cannot mix `fields` and `sub_sections` in the same section — use one or the other.
+
+##### Field-Level Conditions in Nested Rows
+
+Fields inside nested rows support `visible_when` and `disable_when` conditions, evaluated against the **current row's data** (not the parent record). This works for both association and JSON field sources:
+
+```yaml
+fields:
+  - { field: item_type, input_type: select }
+  - field: discount_percent
+    input_type: number
+    visible_when: { field: item_type, operator: eq, value: discount }
+    hint: "Enter discount percentage"
+    col_span: 2
+  - field: notes
+    visible_when: { field: item_type, operator: in, value: "service,discount" }
+    prefix: "Note:"
+```
+
+Each row gets a `data-lcp-condition-scope` attribute that scopes the JavaScript field lookup to the current row container. This prevents cross-row interference when multiple rows have fields with the same name. See [Row-Scoped Conditions](../guides/conditional-rendering.md#row-scoped-conditions-in-nested-fields) for details.
+
+##### Nested Fields Section Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `type` | string | - | Must be `"nested_fields"` |
+| `association` | string | - | Name of the `has_many` association (mutually exclusive with `json_field`) |
+| `json_field` | string | - | JSON column name to store items as array of hashes (mutually exclusive with `association`) |
+| `target_model` | string | - | Virtual model name defining item structure and validations (only with `json_field`) |
+| `allow_add` | boolean | `true` | Show a button to add new items |
+| `allow_remove` | boolean | `true` | Show a remove button on each row |
+| `add_label` | string | `"Add"` | Label for the add button |
+| `min` | integer | - | Minimum number of items required |
+| `max` | integer | - | Maximum number of items allowed |
+| `empty_message` | string | - | Message displayed when there are no items |
+| `columns` | integer | - | Number of grid columns for each row's field layout |
+| `fields` | array | - | Field definitions for each row (mutually exclusive with `sub_sections`) |
+| `sub_sections` | array | - | Sub-section definitions for grouping fields within rows (mutually exclusive with `fields`) |
+| `sortable` | boolean or string | `false` | Enable drag-and-drop reordering. `true` uses `position` field, or a string for a custom field name |
+
+##### Sub-Section Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `title` | string | - | Sub-section heading (renders as `<legend>`) |
+| `columns` | integer | - | Number of grid columns for this sub-section's fields |
+| `collapsible` | boolean | `false` | Whether the sub-section can be collapsed/expanded |
+| `collapsed` | boolean | `false` | Whether the sub-section starts collapsed (requires `collapsible: true`) |
+| `visible_when` | hash | - | Condition for sub-section visibility (evaluated against the current row) |
+| `disable_when` | hash | - | Condition for sub-section disabling |
+| `fields` | array | - | Field definitions for this sub-section |
+
+##### Sortable Nested Forms
+
+When `sortable` is set, nested form rows get drag handles for reordering via HTML5 Drag and Drop. The position field is automatically hidden from the visible form fields and rendered as a hidden input that updates on drag. The position field is also auto-permitted in the controller.
+
+```yaml
+form:
+  sections:
+    - title: "Items"
+      type: nested_fields
+      association: line_items
+      sortable: true
+      fields:
+        - { field: name }
+        - { field: quantity, input_type: number }
+```
+
+The child model should have an integer position field, and the parent association should specify `order: { position: asc }` to load children in the correct order. For JSON field items, array order is the position — no position key needed.
+
+**Custom position field name:**
+
+```yaml
+sortable: "sort_order"
+```
+
+#### How Association Selects Work
+
+When a form field has `input_type: association_select` on a foreign key column (e.g., `company_id`):
+
+1. The `LayoutBuilder` matches the FK field name against `association.foreign_key` in model metadata
+2. Creates a synthetic `FieldDefinition` (type: integer) with the `AssociationDefinition` attached
+3. The form renders a `<select>` populated from the target model's records
+4. Display text uses `to_label` (if defined) or `to_s`
+5. Falls back to a number input if the target model is not registered in LCP
+6. FK fields bypass the `field_writable?` permission check — they are permitted separately in the controller
+
+## Search Configuration
+
+Controls quick search, predefined filters, and the advanced filter builder on the index page.
+
+> **Need persistent dropdown filters (selectboxes)?** Use [Search Parameters](#search-parameters) — configure `parameters` under `search` to add always-visible typed filter controls (dropdowns, toggles, ranges) directly in the toolbar. For filters that apply across **all zones** on a composite page, use [Page Parameters](../reference/pages.md#page-parameters) instead.
+
+The quick search parameter is `?qs=` (query string). Previous versions used `?q=`; the rename avoids collision with Ransack's internal `q` parameter.
+
+```yaml
+search:
+  enabled: true
+  searchable_fields: [title, description]
+  placeholder: "Search..."
+  auto_search: true
+  debounce_ms: 500
+  min_query_length: 3
+  predefined_filters:
+    - { name: all, label: "All", default: true }
+    - { name: open, label: "Open", scope: open_deals }
+    - { name: won, label: "Won", scope: won }
+
+  advanced_filter:
+    enabled: true
+    max_conditions: 20
+    max_association_depth: 3
+    default_combinator: and
+    allow_or_groups: true
+    query_language: false
+
+    filterable_fields:
+      - title
+      - stage
+      - value
+      - company.name
+      - contact.email
+
+    field_options:
+      stage:
+        operators: [eq, not_eq, in, not_in]
+      value:
+        operators: [eq, gt, gteq, lt, lteq, between]
+        step: 0.01
+
+    presets:
+      - name: high_value_open
+        label: "High-value open deals"
+        conditions:
+          - { field: stage, operator: not_in, value: [closed_won, closed_lost] }
+          - { field: value, operator: gteq, value: 10000 }
+
+    custom_filters:
+      - name: region
+        label: "Region"
+        type: string
+      - name: active
+        label: "Active Only"
+        type: boolean
+
+  advanced_filter:
+    enabled: true
+    saved_filters:
+      enabled: true
+      display: inline
+      max_visible_pinned: 5
+```
+
+### Search Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `enabled` | boolean | Enable/disable the search bar |
+| `searchable_fields` | array | Field names to search with quick search (`?qs=`). Type-aware: numeric fields skip non-numeric queries, date fields match by range, enum fields match by display label |
+| `placeholder` | string | Search input placeholder text |
+| `auto_search` | boolean | When `true`, the form auto-submits as the user types (default: `false`) |
+| `debounce_ms` | integer | Debounce delay in milliseconds before auto-submit (default: `300`) |
+| `min_query_length` | integer | Minimum query length to trigger auto-submit; empty input (length 0) always triggers to clear the search (default: `2`) |
+| `columns` | integer | Number of grid columns for the search parameter layout (default: `1`) |
+| `responsive` | object | Responsive column overrides: `{ mobile: { columns: 1 }, tablet: { columns: 2 } }` |
+| `parameters` | array | Typed filter controls in the toolbar (see [Search Parameters](#search-parameters) below) |
+| `predefined_filters` | array | Filter buttons (see below) |
+| `advanced_filter` | object | Advanced filter builder configuration (see below) |
+| `saved_filters` | object | Saved filter configuration (see below) |
+
+### Quick Search Behavior
+
+Quick search (`?qs=term`) is type-aware. Instead of applying a blanket `LIKE` to all `searchable_fields`, the search module checks each field's type:
+
+- **String/text fields** — `ILIKE '%term%'` (contains match)
+- **Numeric fields** (integer, float, decimal) — exact match when the term is numeric, skipped otherwise
+- **Date/datetime fields** — range match when the term parses as a date, skipped otherwise
+- **Enum fields** — matches against enum display labels (e.g., searching "won" matches `closed_won` if its label contains "won")
+
+Models can override quick search entirely with a `default_query` class method (escape hatch). The method receives the search term and must return a relation (which is merged with the current scope):
+
+```ruby
+# Model extension
+def self.default_query(term)
+  where("title ILIKE :q OR reference_number = :exact", q: "%#{term}%", exact: term)
+end
+```
+
+### Search Parameters
+
+The `parameters` key under `search` adds typed filter controls directly in the search toolbar — dropdowns, toggles, and range inputs. Each control generates standard Ransack `?f[...]` URL params, so they flow through the existing filter pipeline with no additional configuration.
+
+```yaml
+search:
+  enabled: true
+  columns: 2
+  searchable_fields: [name, email]
+  parameters:
+    - name: status
+      type: enum_select
+      field: status
+
+    - name: department
+      type: association_select
+      field: department_id
+      label_method: full_name
+      include_blank: "Any department"
+
+    - name: active
+      type: boolean_select
+      field: active
+
+    - name: salary_range
+      type: number_range
+      field: salary
+      # col_span auto-defaults to 2 for range types when columns >= 2
+
+    - name: hired
+      type: date_range
+      field: hired_at
+
+    - name: tenant
+      type: association_select
+      model: tenant
+      field: tenant_id
+      visible_when:
+        role: admin
+```
+
+#### Parameter Types
+
+| Type | UI Control | Generated URL params |
+|------|-----------|---------------------|
+| `enum_select` | Tom Select dropdown | `?f[status_eq]=active` |
+| `association_select` | Tom Select (local or remote) | `?f[department_id_eq]=42` |
+| `boolean_select` | Tom Select (All / Yes / No) | `?f[active_eq]=true` |
+| `number_range` | Two number inputs (min / max) | `?f[salary_gteq]=1000&f[salary_lteq]=5000` |
+| `date_range` | Two date inputs (from / to) | `?f[hired_at_gteq]=2025-01-01&f[hired_at_lteq]=2025-12-31` |
+
+#### Parameter Attributes
+
+| Attribute | Type | Applies to | Description |
+|-----------|------|-----------|-------------|
+| `name` | string | all | Parameter identifier (required) |
+| `type` | string | all | One of `enum_select`, `association_select`, `boolean_select`, `number_range`, `date_range` (required) |
+| `field` | string | all | Model field name to filter by (required) |
+| `model` | string | `association_select` | Target model name. Auto-derived from the field's `belongs_to` association if omitted |
+| `options` | array | `enum_select` | Explicit option values. Auto-derived from model enum definition if omitted |
+| `label_key` | string | all | i18n key for the parameter label. Falls back to `lcp_ruby.parameters.<name>`, then humanized name |
+| `label_method` | string | `association_select` | Method called on each record to produce the display label. Defaults to `to_s` |
+| `include_blank` | string/boolean | select types | Custom label for the blank "All" option. Set to `false` to omit the blank option entirely |
+| `visible_when` | object | all | Role-based visibility: `{ role: admin }` or `{ role: [admin, manager] }`. Only the `role` key is supported (no condition-based evaluation on index pages). Hidden parameters are not rendered AND their `?f[...]` params are stripped server-side |
+| `search` | boolean | `association_select` | Enable remote server-side search (Tom Select remote mode). Default: local mode with preloaded options |
+| `min_query_length` | integer | `association_select` | Minimum characters before remote search triggers (requires `search: true`) |
+| `per_page` | integer | `association_select` | Results per page for remote search (requires `search: true`) |
+| `col_span` | integer | all | Number of grid columns this parameter spans. Range types auto-default to 2 when `columns >= 2` |
+
+#### Grid Layout
+
+The search parameter bar uses CSS Grid, configured via `search.columns` (default: 1). Each grid cell displays the label inline beside the control. The quick search text input is also a grid item.
+
+- **`columns: 1`** (default) — single-column stack, one parameter per row.
+- **`columns: 2`** or more — multi-column grid. Range types auto-span 2 columns. Use `col_span` to override.
+- **`responsive`** — override columns per breakpoint: `responsive: { mobile: { columns: 1 } }`.
+
+#### Auto-Derivation
+
+- **`enum_select`** without `options`: options derived from the model's enum field definition.
+- **`association_select`** without `model`: model derived from the field's `belongs_to` association (e.g., `field: department_id` looks up `belongs_to :department`).
+- **`boolean_select`**: always renders All / Yes / No.
+
+#### Interaction with Other Features
+
+- **Quick search / predefined filters / advanced filter**: all combine with AND logic. Parameters and the advanced filter builder share the `?f[...]` namespace — they are two UI views over the same filter state.
+- **Saved filters**: parameter values are naturally captured when saving a filter (no special handling needed).
+- **Page filter form**: when a presenter is rendered inside a composite page that declares a `filter_form:` block, presenter search parameters whose `field` matches a `filter_form:` field are suppressed to avoid duplicate controls. (The legacy `parameters:` page block was retired in PR 5; see [Page Filters reference](page_filters.md).)
+- **Export**: works automatically — `QueryBuilder` already processes `?f[...]` params.
+
+### Predefined Filter Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Filter identifier |
+| `label` | string | Button text |
+| `default` | boolean | Whether this filter is active by default |
+| `scope` | string | Named [scope](models.md#scopes) to apply. Omit for the "all" filter |
+
+Predefined filters render as buttons above the table. Each filter (except the default "all") maps to a named scope defined in the model YAML.
+
+### Advanced Filter Attributes
+
+The `advanced_filter` key controls the visual filter builder that lets users construct field-level filter conditions.
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `enabled` | boolean | `false` | Show the filter builder. Requires both `search.enabled: true` and `advanced_filter.enabled: true` |
+| `max_conditions` | integer | `10` | Safety limit on filter rows |
+| `max_association_depth` | integer | `1` | Maximum levels of association traversal (e.g., `company.country.name` = depth 2) |
+| `default_combinator` | string | `"and"` | Top-level combinator: `"and"` or `"or"` |
+| `allow_or_groups` | boolean | `true` | Allow users to create OR groups within the filter |
+| `query_language` | boolean | `false` | Show "Edit as QL" toggle for text-based query input |
+| `max_nesting_depth` | integer | `2` | Maximum depth of AND/OR nesting. `1` = flat AND only, `2` = AND with OR groups (current default), `3+` = full recursive nesting |
+| `filterable_fields` | array | auto-detected | Fields available in the filter dropdown. Supports dot-path association syntax (e.g., `company.name`). If omitted, all readable fields are auto-detected from permissions. Mutually exclusive with `filterable_fields_except` |
+| `filterable_fields_except` | array | `[]` | Fields/associations to exclude from auto-detection. Supports direct field names, association names (excludes entire subtree), and dot-paths. Mutually exclusive with `filterable_fields` |
+| `field_options` | object | `{}` | Per-field operator overrides and input hints (see below) |
+| `presets` | array | `[]` | Predefined filter combinations that populate the builder with one click |
+| `custom_filters` | array | `[]` | Explicit declaration of `filter_*` methods for UI exposure (see [Custom Filter Methods](../guides/extensibility.md#custom-filter-methods)) |
+
+#### `filterable_fields`
+
+When omitted, the platform auto-detects filterable fields from the model definition, filtered by the current user's read permissions. When specified, only the listed fields appear in the filter dropdown. Association fields use dot notation:
+
+```yaml
+filterable_fields:
+  - title                    # Direct field
+  - stage                    # Enum — auto-detects values for dropdown
+  - value                    # Numeric — auto-detects numeric operators
+  - company.name             # belongs_to association (1 level)
+  - contact.company.country  # Association chain (2 levels)
+```
+
+#### `filterable_fields_except`
+
+When using auto-detection (no `filterable_fields`), exclude specific fields or entire association subtrees:
+
+```yaml
+filterable_fields_except:
+  - internal_notes            # Exclude a direct field
+  - audit_log                 # Exclude entire association subtree
+  - company.tax_id            # Exclude a specific association field
+  - company.audit_log         # Exclude a sub-association
+```
+
+Exclusion matching rules:
+- **Direct field name** (`internal_notes`) — excludes that field from the root model.
+- **Association name without dot** (`audit_log`) — excludes the entire association subtree.
+- **Dot-path to a field** (`company.tax_id`) — excludes that specific field on the associated model.
+- **Dot-path to an association** (`company.audit_log`) — excludes a sub-association within an association.
+
+Setting both `filterable_fields` and `filterable_fields_except` is a configuration error.
+
+#### `field_options`
+
+Override the default operators or input hints for specific fields:
+
+```yaml
+field_options:
+  stage:
+    operators: [eq, not_eq, in, not_in]   # Only these operators
+  value:
+    operators: [eq, gt, gteq, lt, lteq, between, present, blank]
+    step: 0.01                             # Numeric input step
+```
+
+See the [Advanced Search design document](../design/advanced_search.md) for the full operator-by-type matrix.
+
+#### `presets`
+
+Presets are predefined filter combinations that appear as one-click pill buttons at the top of the filter panel. Each preset has a `name`, `label`, and a list of `conditions`:
+
+```yaml
+presets:
+  - name: high_value_open
+    label: "High-value open deals"
+    conditions:
+      - { field: stage, operator: not_in, value: [closed_won, closed_lost] }
+      - { field: value, operator: gteq, value: 10000 }
+  - name: closing_soon
+    label: "Closing this month"
+    conditions:
+      - { field: expected_close_date, operator: this_month }
+```
+
+DSL equivalent:
+
+```ruby
+advanced_filter do
+  preset :high_value_open,
+    label: "High-value open deals",
+    conditions: [
+      { field: "stage", operator: "not_in", value: %w[closed_won closed_lost] },
+      { field: "value", operator: "gteq", value: "10000" }
+    ]
+end
+```
+
+**UI behavior:**
+
+- The preset bar renders inside the filter panel, above the condition rows, with a "Presets:" label followed by pill-shaped buttons.
+- The preset bar only appears when at least one preset is defined.
+- **Click** applies the preset immediately — fills conditions and navigates (page reload with filter URL params).
+- **Active highlighting** — if the current URL filters exactly match a preset's conditions, that preset button is highlighted in blue.
+- Presets work with all operator types including no-value operators (`true`, `present`, `this_month`, etc.) and multi-value operators (`in`, `not_in`).
+
+Each condition in a preset uses the same `field`, `operator`, and `value` format as the filter builder. The `field` supports dot-path association syntax (e.g., `company.name`). The `operator` must be one of the [supported operators](condition-operators.md). The `value` is optional for no-value operators (`present`, `blank`, `null`, `true`, `this_month`, etc.).
+
+#### `custom_filters`
+
+Declares `filter_*` class methods on the model so they appear in the filter dropdown UI. Each entry has a `name`, `label`, and `type` (for the value input):
+
+```yaml
+custom_filters:
+  - name: region
+    label: "Region"
+    type: string
+  - name: active
+    label: "Active Only"
+    type: boolean
+```
+
+See [Custom Filter Methods](../guides/extensibility.md#custom-filter-methods) for implementation details.
+
+### Saved Filter Attributes
+
+The `saved_filters` block (nested inside `advanced_filter`) enables user-persistent named filters. Users can save filter conditions, pin favorites, set defaults, and share with roles/groups.
+
+**Prerequisite:** The saved filter model must exist. Generate it with `rails generate lcp_ruby:saved_filters`.
+
+```yaml
+advanced_filter:
+  enabled: true
+  saved_filters:
+    enabled: true
+    display: inline
+    max_visible_pinned: 5
+```
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `enabled` | boolean | `false` | Allow users to save, load, and manage personal filters |
+| `display` | string | `"inline"` | UI display mode: `"inline"` (pill buttons above filter), `"dropdown"` (select menu), `"sidebar"` (side panel) |
+| `max_visible_pinned` | integer | `3` | Maximum number of pinned filters shown directly (overflow goes to "more" menu) |
+
+**Saved filter visibility levels:**
+
+| Level | Description |
+|-------|-------------|
+| `personal` | Only the owner can see and use the filter |
+| `role` | Visible to all users with the `target_role` |
+| `group` | Visible to members of the `target_group` |
+| `global` | Visible to all users |
+
+**Saved filter model fields:** `name`, `description`, `target_presenter`, `condition_tree` (JSON), `ql_text`, `visibility` (enum), `owner_id`, `target_role`, `target_group`, `position`, `icon`, `color`, `pinned` (boolean), `default_filter` (boolean).
+
+See the [Saved Filters design spec](../design/saved_filters.md) for the complete feature description.
+
+## Actions Configuration
+
+Controls CRUD buttons, custom actions, and form submit buttons.
+
+```yaml
+actions:
+  collection:
+    - { name: create, type: built_in, label: "New Deal", icon: plus }
+  single:
+    - { name: show, type: built_in, icon: eye }
+    - { name: edit, type: built_in, icon: pencil }
+    - name: close_won
+      type: custom
+      label: "Close as Won"
+      icon: check-circle
+      confirm: true
+      confirm_message: "Mark this deal as won?"
+      visible_when: { field: stage, operator: not_in, value: [closed_won, closed_lost] }
+    - { name: destroy, type: built_in, icon: trash, confirm: true, style: danger, batch: true }
+  batch: []
+  form:
+    - { name: save, type: built_in, style: primary, redirect: show }
+    - { name: save_and_new, label: "Save & New", redirect: new, only_on: create }
+    - { name: cancel, type: built_in, style: secondary }
+```
+
+### Action Categories
+
+| Category | Description |
+|----------|-------------|
+| `collection` | Actions on the collection (no specific record). Displayed above the table. |
+| `single` | Actions on a single record. Displayed in each table row. |
+| `batch` | Actions on multiple selected records. Renders checkboxes and a fixed toolbar at the bottom of the index page. See [Batch Actions Guide](../guides/batch-actions.md). |
+| `form` | Submit buttons on create/edit forms. Replaces the default Save/Cancel when configured. See [Form Actions](#form-actions). |
+
+### Auto-Derived Batch Actions
+
+Single actions can auto-derive a batch version using the `batch` attribute:
+
+```yaml
+single:
+  - { name: destroy, type: built_in, confirm: true, style: danger, batch: true }
+  - { name: archive, type: custom, icon: box, batch: { select_all_filter: false } }
+```
+
+When `batch: true`, the platform derives a batch action inheriting `name`, `type`, `icon`, `confirm`, `confirm_message`, `style`, `label`, and `action_class`. When `batch:` is a Hash, the hash values are merged as batch-specific overrides. Attributes like `visible_when`, `disable_when`, and `dialog` are not inherited. If an explicit batch action with the same name exists, it takes precedence over the derived one.
+
+`batch:` on `type: dialog` or `type: transition` actions is ignored. `batch:` on collection actions has no effect.
+
+See [Batch Actions Guide](../guides/batch-actions.md) for full details and examples.
+
+### Batch Action Attributes
+
+Batch actions (both explicit and auto-derived) support the same base attributes as other actions (`name`, `type`, `icon`, `confirm`, `style`) plus the following batch-specific attributes:
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `min_selection` | integer | 1 | Minimum records that must be selected for the action button to activate |
+| `max_selection` | integer | — | Maximum records that can be selected |
+| `max_batch_records` | integer | — | Server-side limit on records affected. If exceeded, the action returns an error without executing. Applied to both ID and filter selection modes. |
+| `result_log` | boolean | `false` | Enable per-record result tracking in the batch operation log. Requires the `lcp_ruby:batch_operations` generator to have been run. |
+| `select_all_filter` | boolean | `true` | Allow "select all matching filter" mode for this action |
+| `execution` | string | `inline` | Execution mode: `inline` (synchronous), `background` (always enqueue job), or `auto` (choose based on `background_threshold`). `background` and `auto` require the `lcp_ruby:background_jobs` generator. |
+| `background_threshold` | integer | 100 | For `execution: auto` only — record count above which the action runs as a background job |
+
+**Built-in batch action names:** `destroy`, `restore`, `permanently_destroy`, `update`, `export`. The `restore` and `permanently_destroy` actions require `soft_delete: true` on the model.
+
+### Action Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Action identifier. For built-in: `show`, `edit`, `destroy`, `create`, `restore`, `permanently_destroy`, `export` |
+| `type` | string | `built_in`, `custom`, or `dialog` |
+| `label` | string | Display text |
+| `icon` | string | Icon name |
+| `confirm` | boolean or hash | Show a confirmation dialog before executing (see [Confirm Per Role](#confirm-per-role) and [Styled Confirm](#styled-confirm)) |
+| `confirm_message` | string | Custom text for the confirmation dialog |
+| `style` | string | CSS style hint (e.g., `danger` for destructive actions) |
+| `visible_when` | object | Condition controlling visibility (see below) |
+| `disable_when` | object | Condition controlling disabled state. When true, the action button renders as a disabled span instead of a clickable link/button (see below) |
+| `dialog` | object | Dialog configuration (for `type: dialog` actions only). Keys: `page`, `on_success`, `record`, `defaults`. See [Dialogs Reference](dialogs.md). |
+| `batch` | boolean or object | Single actions only. `true` auto-derives a batch action; a Hash merges batch-specific overrides. See [Auto-Derived Batch Actions](#auto-derived-batch-actions). |
+
+### Action Types
+
+- **`built_in`** — standard CRUD actions (`show`, `edit`, `destroy`, `create`, `restore`, `permanently_destroy`) and non-CRUD built-in actions (`export`). CRUD actions are authorized via `PermissionEvaluator.can?`. Non-CRUD built-in actions (like `export`) are authorized via `can_execute_action?` against the `actions` permission config. The `restore` and `permanently_destroy` actions are used with [soft delete](models.md#soft_delete) archive presenters. The `export` action requires the [export configuration](export.md).
+- **`custom`** — user-defined actions. Authorization checked via `can_execute_action?`. Dispatched to registered action classes. See [Custom Actions](../guides/custom-actions.md).
+- **`dialog`** — opens a page in a modal dialog. Authorization checked against the dialog page's presenter. Config: `dialog: { page: <page_name>, on_success: reload|close|redirect|confirm_action, record: current, defaults: {...} }`. See [Dialogs Reference](dialogs.md).
+
+### Action Visibility
+
+Action buttons are filtered through three checks (in order):
+
+1. **Record rules** — built-in `edit`/`destroy` actions are automatically hidden when [record_rules](permissions.md#record-rules) deny the corresponding CRUD operation for that record. No `visible_when` configuration needed. The `show` action is not affected.
+2. **`visible_when`** — a [condition object](condition-operators.md) evaluated per-record via `ConditionEvaluator`. When omitted, the action is always visible.
+3. **`disable_when`** — same syntax, controls disabled state (see below).
+
+All three checks apply with AND semantics. Record rules and `visible_when` can be used independently or together.
+
+```yaml
+visible_when: { field: stage, operator: not_in, value: [closed_won, closed_lost] }
+```
+
+When `visible_when` is omitted and no record_rules apply, the action is always visible (subject to role-level permission checks).
+
+### Action Disabling
+
+The `disable_when` attribute uses the same [condition object](condition-operators.md) syntax as `visible_when`. When the condition evaluates to true, the action button is rendered as a disabled `<span>` instead of a clickable link or button:
+
+```yaml
+single:
+  - name: send_invoice
+    type: custom
+    label: "Send Invoice"
+    icon: mail
+    disable_when: { field: value, operator: blank }
+  - name: close_won
+    type: custom
+    label: "Close as Won"
+    icon: check-circle
+    visible_when: { field: stage, operator: not_in, value: [closed_won, closed_lost] }
+    disable_when: { field: value, operator: lte, value: 0 }
+```
+
+An action can use both `visible_when` and `disable_when` together. The visibility condition is evaluated first — if the action is hidden, `disable_when` has no effect.
+
+### Confirm Per Role
+
+The `confirm` attribute supports role-based resolution. Instead of a simple boolean, you can use a hash with `except` or `only` keys to control which roles see the confirmation dialog:
+
+```yaml
+actions:
+  single:
+    # Confirm for everyone (existing behavior):
+    - name: destroy
+      type: built_in
+      confirm: true
+
+    # Confirm for all EXCEPT these roles (admin skips confirm):
+    - name: archive
+      type: custom
+      confirm:
+        except: [admin]
+
+    # Confirm ONLY for these roles (others skip):
+    - name: force_delete
+      type: custom
+      confirm:
+        only: [viewer, sales_rep]
+```
+
+| Value | Behavior |
+|-------|----------|
+| `true` | Confirm for all roles (backward compatible) |
+| `false` or omitted | No confirm for any role (backward compatible) |
+| `{ except: [roles] }` | Confirm for all roles EXCEPT the listed ones |
+| `{ only: [roles] }` | Confirm ONLY for the listed roles |
+
+The resolved `confirm` value (true/false) is set on the action before rendering, so view templates work unchanged.
+
+### Styled Confirm
+
+For custom confirmation styling with title, message, and button style:
+
+```yaml
+- name: deactivate
+  type: custom
+  confirm:
+    title_key: lcp_ruby.confirm.deactivate_title
+    message_key: lcp_ruby.confirm.deactivate_message
+    style: danger
+```
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `title_key` | string | i18n key for the dialog title |
+| `message_key` | string | i18n key for the confirmation message |
+| `style` | string | Button style: `danger`, `warning`, `primary` |
+
+### Page-Based Confirm
+
+For complex confirmations requiring user input (e.g., a reason field), use a page reference:
+
+```yaml
+- name: delete_with_reason
+  type: custom
+  confirm:
+    page: delete_reason_form
+```
+
+The confirmation page is typically a virtual model (`table_name: _virtual`) with validation. On success, `on_success: confirm_action` submits the original action with `confirmation_data[...]` params. See [Dialogs Reference](dialogs.md) for details.
+
+## Form Actions
+
+Form actions define the submit buttons rendered in the form footer on create/edit pages. When `actions.form` is not configured, the platform renders default Save and Cancel buttons (backward compatible).
+
+When `actions.form` is explicitly configured, **only the listed actions appear** — the configurator has full control over which buttons render, in what order.
+
+### Form Action Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | string | required | Unique identifier. Sent as `_form_action` param to the controller. |
+| `type` | string | — | `built_in` for platform-provided actions (`save`, `cancel`). Omit for custom form actions. |
+| `label` | string | i18n lookup | Button label text. |
+| `icon` | string | — | Icon name (rendered before label). |
+| `style` | string | `secondary` | Button style: `primary`, `secondary`, `success`, `danger`, `warning`, `outline`. |
+| `redirect` | string or hash | presenter's `redirect_after` | Where to redirect after pipeline completes. String: `show`, `edit`, `new`, `index`. Hash: `{ association: <name>, action: <target> }` or `{ presenter: <slug>, action: <target>, defaults: {...} }` for cross-presenter navigation. Ignored in dialog context. |
+| `set_fields` | hash | — | Fields to set before save. Same value syntax as workflow `set_fields` (`{ date: now }`, `{ current_user: id }`, static values). Values are configurator-controlled and bypass field-level write permissions. |
+| `confirm` | boolean | `false` | Show confirmation dialog before submit. |
+| `confirm_message` | string | — | Custom confirmation text. |
+| `visible_when` | condition | — | Field-value condition for visibility. |
+| `disable_when` | condition | — | Condition for disabled state. |
+| `only_on` | string | both | `create`, `update`, or omit for both. |
+| `only_roles` | array | all | Roles that see this button. |
+| `except_roles` | array | none | Roles that don't see this button. |
+| `dialog_behavior` | string | `close` in dialog context | Dialog-only: `close` (save & close), `reset` (save & clear form), `reload` (save & reload parent). Ignored outside dialog context. |
+| `pipeline` | array | `[save]` | Ordered operations to execute in a single transaction. Steps: `save`, `{ transition: <name> }`, `{ action: <name> }`. See [Pipeline](#pipeline). |
+| `transition` | string | — | Sugar for `pipeline: [save, { transition: <name> }]`. Cannot combine with `pipeline` or `action`. |
+| `action` | string | — | Sugar for `pipeline: [save, { action: <name> }]`. Cannot combine with `pipeline` or `transition`. |
+| `position` | string | `inline` | `inline` (rendered in row), `dropdown` (forced into overflow menu). |
+
+### Built-In Form Actions
+
+| Name | Behavior |
+|------|----------|
+| `save` | Save the record and redirect per config. |
+| `cancel` | Does **not** submit the form. Renders as a link to index (or close button in dialog context). |
+
+### Default Form Actions
+
+When `actions.form` is absent, the platform injects:
+
+```yaml
+actions:
+  form:
+    - { name: save, type: built_in, style: primary }
+    - { name: cancel, type: built_in, style: secondary }
+```
+
+### Interaction with `redirect_after`
+
+When form actions are present, `redirect_after` serves as the **fallback** for any form action that does not specify its own `redirect`:
+
+```yaml
+redirect_after:
+  create: show
+  update: show
+
+actions:
+  form:
+    - name: save
+      type: built_in
+      style: primary
+      # redirect not set → falls back to redirect_after (show)
+    - name: save_and_new
+      redirect: new
+      only_on: create
+    - name: cancel
+      type: built_in
+```
+
+### Form Action i18n
+
+Button labels use the following lookup chain:
+
+1. Explicit `label` attribute on the form action (if set)
+2. `lcp_ruby.presenters.<presenter_name>.actions.form.<action_name>` (presenter-specific)
+3. `lcp_ruby.actions.form.<action_name>` (global)
+4. Humanized `name` as fallback (e.g., `save_and_new` → "Save and new")
+
+Built-in `save` uses `lcp_ruby.form.create` / `lcp_ruby.form.update` depending on context.
+
+### Authorization
+
+1. **Role-based filtering** — `only_roles` / `except_roles` filter buttons by the current user's roles at render time.
+2. **Pundit policy** — built-in `save` checks `create?` / `update?` policy. Non-built-in form actions check `can_execute_action?(name)`. Built-in `cancel` requires no authorization.
+3. **Submit-time whitelist** — the controller re-validates `_form_action` against the authorized form actions at submit time (re-checks `only_on`, roles, permissions). Unknown or unauthorized values fall back to `save` behavior.
+
+### `set_fields` Precedence
+
+`set_fields` values are applied **after** user input from the form. This means configurator values intentionally override anything the user submits for the same field:
+
+1. `record.assign_attributes(permitted_params)` — user input
+2. `apply_set_fields(record, form_action_config)` — configurator overrides
+3. `record.save!`
+
+### Examples
+
+**Quick data entry:**
+
+```yaml
+actions:
+  form:
+    - { name: save, type: built_in, style: primary, redirect: show }
+    - { name: save_and_new, label: "Save & New", redirect: new, only_on: create }
+    - { name: cancel, type: built_in }
+```
+
+**Content publishing with set_fields:**
+
+```yaml
+actions:
+  form:
+    - name: save_draft
+      label: "Save Draft"
+      redirect: edit
+    - name: save_and_publish
+      label: "Publish"
+      style: primary
+      icon: globe
+      set_fields:
+        status: published
+        published_at: { date: now }
+      confirm: true
+      redirect: show
+      visible_when: { field: status, operator: not_eq, value: published }
+    - { name: cancel, type: built_in }
+```
+
+**Dialog with "add another":**
+
+```yaml
+actions:
+  form:
+    - { name: save_close, label: "Save & Close", style: primary, dialog_behavior: close }
+    - { name: save_another, label: "Save & Add Another", dialog_behavior: reset, only_on: create }
+    - { name: cancel, type: built_in }
+```
+
+**Save + workflow transition (pipeline):**
+
+```yaml
+actions:
+  form:
+    - name: save_draft
+      label: "Save Draft"
+      style: secondary
+      redirect: edit
+
+    - name: save_and_submit
+      label: "Save & Submit"
+      style: primary
+      icon: send
+      transition: submit
+      confirm: true
+      confirm_message: "Submit for approval? You won't be able to edit after this."
+      visible_when: { field: status, operator: eq, value: draft }
+      redirect: show
+
+    - { name: cancel, type: built_in }
+```
+
+**Explicit pipeline (save + transition + custom action):**
+
+```yaml
+actions:
+  form:
+    - name: save_submit_and_notify
+      label: "Save, Submit & Notify"
+      style: primary
+      pipeline:
+        - save
+        - { transition: submit }
+        - { action: notify_approvers }
+      confirm: true
+      visible_when: { field: status, operator: eq, value: draft }
+      redirect: show
+
+    - { name: cancel, type: built_in }
+```
+
+**Cross-presenter redirect:**
+
+```yaml
+actions:
+  form:
+    - name: save_and_add_line_item
+      label: "Save & Add Line Item"
+      redirect:
+        presenter: line_items
+        action: new
+        defaults:
+          order_id: { field_ref: id }
+      only_on: update
+```
+
+### Pipeline
+
+Each form action executes a **pipeline** — an ordered list of operations that run within a single database transaction. The `pipeline` attribute makes the execution sequence explicit: `save` is a step you include (or omit), not an implicit behavior.
+
+#### Pipeline steps
+
+| Step | Syntax | Description |
+|------|--------|-------------|
+| **save** | `save` | Save the record (create or update). Applies `set_fields` before saving. |
+| **transition** | `{ transition: <name> }` | Fire a workflow transition via `TransitionExecutor`. |
+| **action** | `{ action: <name> }` | Execute a custom action class. Resolved as `<model>/<name>`. |
+
+#### Sugar attributes
+
+For simple cases, `transition:` and `action:` top-level attributes expand into a pipeline automatically:
+
+```yaml
+# This:
+- name: save_and_submit
+  transition: submit
+
+# Expands to:
+- name: save_and_submit
+  pipeline: [save, { transition: submit }]
+```
+
+When neither `pipeline`, `transition`, nor `action` is set, the default pipeline is `[save]`.
+
+#### Execution semantics
+
+1. The entire pipeline runs inside a single `ActiveRecord::Base.transaction`.
+2. Steps execute in order. If any step fails, the transaction rolls back.
+3. `set_fields` is applied before the `save` step.
+4. For custom action results: `result.redirect_to` takes precedence over the form action's `redirect`. `result.message` is displayed as flash. When multiple actions run, last non-nil values win.
+5. Workflow events are deferred until after the transaction commits.
+
+#### Pipeline on single actions
+
+The `pipeline` attribute also works on `single` actions (show page buttons). On show pages there is no `save` step — the pipeline operates on the existing record:
+
+```yaml
+actions:
+  single:
+    - name: approve
+      label: "Approve"
+      style: success
+      icon: check
+      pipeline:
+        - { transition: approve }
+      visible_when: { field: status, operator: eq, value: pending_approval }
+      only_roles: [admin, manager]
+
+    - name: reject_and_notify
+      label: "Reject & Notify"
+      style: danger
+      pipeline:
+        - { transition: reject }
+        - { action: notify_rejection }
+      confirm: true
+```
+
+Single actions also support `transition:` and `action:` sugar (without `save` step):
+
+```yaml
+# Sugar form — expands to pipeline: [{ transition: approve }]
+- name: approve
+  transition: approve
+```
+
+For the step-by-step walkthrough, see the [Action Buttons & Pipelines Guide](../guides/action-buttons.md). For the full design rationale, see the [Form Submit Actions design doc](../design/form_submit_actions.md).
+
+## Export Configuration
+
+Enables data export (CSV/XLSX) from the presenter. See [Export Reference](export.md) for full details.
+
+```yaml
+export:
+  formats: [csv, xlsx]
+  max_records: 5000
+  save_history: true
+  fields: [name, email, department_id, hire_date]
+  csv_delimiter: ","
+```
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `formats` | array | `["csv"]` | Available formats: `csv`, `xlsx` (XLSX requires the `caxlsx` gem) |
+| `max_records` | integer | `10000` | Safety limit — export fails with error if count exceeds this |
+| `save_history` | boolean | `false` | Log each export to `export_log` model (requires `lcp_ruby:export` generator) |
+| `fields` | array | all readable | Field ceiling — restricts which fields appear in the picker |
+| `csv_delimiter` | string | `","` | CSV separator character |
+
+The export action is a non-CRUD built-in action. Authorization is checked via the `actions` permission config (not the `crud` list). See [Permissions](permissions.md#actions).
+
+```yaml
+actions:
+  collection:
+    - { name: export, type: built_in, icon: download }
+  batch:
+    - { name: export, type: built_in, icon: download }
+```
+
+## Import Configuration
+
+Enables data import (CSV/XLSX) into the presenter's model. See [Import Reference](import.md) for full details.
+
+```yaml
+import:
+  formats: [csv, xlsx]
+  max_rows: 5000
+  max_file_size: 10485760
+  csv_delimiter: ","
+  csv_encoding: auto
+  nested_associations: [employee_profile]
+  nested_blank_strategy: skip
+  parsing:
+    date_format: ["%d.%m.%Y", "%Y-%m-%d"]
+    boolean_true: [true, yes, 1, ano]
+    boolean_false: [false, no, 0, ne]
+```
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `formats` | array | `["csv"]` | Accepted formats: `csv`, `xlsx` (XLSX requires the `roo` gem) |
+| `max_rows` | integer | `10000` | Safety limit — import fails if row count exceeds this |
+| `max_file_size` | integer | `10485760` | Maximum file size in bytes (default 10 MiB) |
+| `csv_delimiter` | string | `","` | CSV separator character |
+| `csv_encoding` | string | `"auto"` | CSV encoding. `"auto"` detects via BOM and UTF-8 validity check |
+| `parsing` | hash | `{}` | Type coercion options: `date_format`, `datetime_format`, `decimal_separator`, `boolean_true`, `boolean_false` |
+| `nested_associations` | array | all | Whitelist of `has_one` association names exposed in import. When omitted, all `has_one` with `nested_attributes` are exposed |
+| `nested_blank_strategy` | string | `"null"` | How to handle blank nested values: `"null"` sets to nil, `"skip"` preserves existing |
+
+The import action is a non-CRUD built-in action. Authorization is checked via the `actions` permission config (not the `crud` list). See [Permissions](permissions.md#actions).
+
+```yaml
+actions:
+  collection:
+    - { name: import, type: built_in, icon: upload }
+```
+
+## Navigation
+
+Navigation is configured through [view groups](view-groups.md), not directly on presenters. View groups control menu placement, ordering, and view switching between multiple presenters for the same model.
+
+## Complete Example
+
+```yaml
+presenter:
+  name: deal
+  model: deal
+  label: "Deals"
+  slug: deals
+  icon: dollar-sign
+
+  index:
+    default_view: table
+    default_sort: { field: created_at, direction: desc }
+    per_page: 25
+    row_click: show
+    empty_message: "No deals found. Create your first deal to get started."
+    actions_position: dropdown
+    table_columns:
+      - field: title
+        width: "30%"
+        link_to: show
+        sortable: true
+        pinned: left
+      - field: stage
+        width: "15%"
+        renderer: badge
+        options:
+          color_map:
+            open: blue
+            negotiation: yellow
+            closed_won: green
+            closed_lost: red
+        sortable: true
+      - field: value
+        width: "15%"
+        renderer: currency
+        options:
+          currency: "$"
+          precision: 2
+        sortable: true
+        summary: sum
+      - field: contact_name
+        hidden_on: [mobile, tablet]
+      - { field: updated_at, renderer: relative_date, hidden_on: mobile }
+
+  show:
+    layout:
+      - section: "Deal Information"
+        columns: 3
+        responsive:
+          tablet:
+            columns: 2
+          mobile:
+            columns: 1
+        fields:
+          - { field: title, renderer: heading, col_span: 3 }
+          - field: stage
+            renderer: badge
+            options:
+              color_map:
+                open: blue
+                negotiation: yellow
+                closed_won: green
+                closed_lost: red
+          - field: value
+            renderer: currency
+            options:
+              currency: "$"
+          - { field: email, renderer: email_link }
+          - { field: website, renderer: url_link, hidden_on: mobile }
+      - section: "Contacts"
+        type: association_list
+        association: contacts
+
+  form:
+    layout: tabs
+    sections:
+      - title: "Deal Details"
+        columns: 2
+        responsive:
+          mobile:
+            columns: 1
+        fields:
+          - field: title
+            placeholder: "Deal title..."
+            autofocus: true
+            col_span: 2
+            hint: "A short, descriptive name for the deal"
+          - { field: stage, input_type: select }
+          - field: value
+            input_type: number
+            prefix: "$"
+            input_options:
+              min: 0
+              step: 0.01
+            visible_when: { field: stage, operator: not_in, value: [lead] }
+            disable_when: { field: stage, operator: in, value: [closed_won, closed_lost] }
+          - { type: divider, label: "Relationships" }
+          - { field: company_id, input_type: association_select }
+          - { field: contact_id, input_type: association_select }
+      - title: "Additional"
+        collapsible: true
+        visible_when: { field: stage, operator: not_eq, value: lead }
+        fields:
+          - field: probability
+            input_type: slider
+            input_options:
+              min: 0
+              max: 100
+              step: 5
+              show_value: true
+            suffix: "%"
+          - field: notes
+            input_type: textarea
+            input_options:
+              rows: 4
+              max_length: 2000
+              show_counter: true
+          - field: close_date
+            input_type: date
+            default: current_date
+            visible_when: { service: persisted_check }
+
+  search:
+    enabled: true
+    searchable_fields: [title]
+    placeholder: "Search deals..."
+    predefined_filters:
+      - { name: all, label: "All", default: true }
+      - { name: open, label: "Open", scope: open_deals }
+      - { name: won, label: "Won", scope: won }
+      - { name: lost, label: "Lost", scope: lost }
+
+  actions:
+    collection:
+      - { name: create, type: built_in, label: "New Deal", icon: plus }
+    single:
+      - { name: show, type: built_in, icon: eye }
+      - { name: edit, type: built_in, icon: pencil }
+      - name: close_won
+        type: custom
+        label: "Close as Won"
+        icon: check-circle
+        confirm: true
+        confirm_message: "Mark this deal as won?"
+        visible_when: { field: stage, operator: not_in, value: [closed_won, closed_lost] }
+        disable_when: { field: value, operator: blank }
+      - { name: destroy, type: built_in, icon: trash, confirm: true, style: danger }
+```
+
+Source: `lib/lcp_ruby/metadata/presenter_definition.rb`, `lib/lcp_ruby/presenter/layout_builder.rb`, `lib/lcp_ruby/presenter/column_set.rb`, `lib/lcp_ruby/presenter/action_set.rb`