lcp 0.1.0

data/lib/lcp_ruby/schemas/presenter.json

@@ -0,0 +1,2274 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lcp-ruby.dev/schemas/presenter.json",
+  "title": "LCP Ruby Presenter Definition",
+  "description": "Schema for presenter metadata that defines UI configuration for a model — index table, show page, form, search, and actions. Presenters are defined in config/lcp_ruby/presenters/ as YAML files or via Ruby DSL.",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Unique presenter identifier. Multiple presenters can reference the same model (e.g., 'employees' and 'employees_archived').",
+      "examples": ["employees", "deal_pipeline"]
+    },
+    "model": {
+      "type": "string",
+      "description": "The model this presenter displays. Must match a model name from config/lcp_ruby/models/.",
+      "examples": ["employee", "deal"]
+    },
+    "label": {
+      "type": "string",
+      "description": "Human-readable title shown in navigation and page headers.",
+      "examples": ["Employees", "Deal Pipeline"]
+    },
+    "slug": {
+      "type": "string",
+      "description": "URL slug for routing. Defaults to presenter name. Must be unique across all presenters.",
+      "examples": ["employees", "deals", "pipeline"]
+    },
+    "icon": {
+      "type": "string",
+      "description": "Icon name shown in navigation and page headers (Lucide icon names).",
+      "examples": ["users", "briefcase", "folder-tree"]
+    },
+    "menu_position": {
+      "type": "integer",
+      "description": "Position hint for the auto-created view group when this is the only presenter on the model. Lifts the auto-VG entry out of the alphabetical 900+index tier into a configurator-controlled position. Ignored when an explicit view group YAML covers the model. Convention: user-defined positions in 0–899 range, auto-generated start at 900.",
+      "examples": [10, 20, 100]
+    },
+    "default": {
+      "type": "boolean",
+      "default": false,
+      "description": "Marks this presenter as the canonical link target for its model. When the model has multiple presenters, `link: true` / `link_to: :show` resolves to the one marked default. Per-link override via `link_presenter:` on a column/field bypasses this default. Exactly one presenter per model may be marked default; the validator rejects ambiguous configurations at boot."
+    },
+    "read_only": {
+      "type": "boolean",
+      "description": "When true, hides create/edit/destroy actions regardless of permissions. Useful for archive or report views."
+    },
+    "embeddable": {
+      "type": "boolean",
+      "description": "When true, allows this presenter to be embedded in other pages (e.g., as an association list)."
+    },
+    "redirect_after": {
+      "type": "object",
+      "description": "Override where the user is redirected after create/update actions.",
+      "properties": {
+        "create": {
+          "type": "string",
+          "description": "Redirect target after successful create.",
+          "enum": ["index", "show", "edit", "new"],
+          "default": "show"
+        },
+        "update": {
+          "type": "string",
+          "description": "Redirect target after successful update.",
+          "enum": ["index", "show", "edit", "new"],
+          "default": "show"
+        }
+      },
+      "additionalProperties": false,
+      "examples": [{ "create": "index", "update": "show" }]
+    },
+    "empty_value": {
+      "type": "string",
+      "description": "Text displayed for nil/empty field values on show and index pages. Overrides the engine-level default.",
+      "examples": ["—", "N/A", "(empty)"]
+    },
+    "max_inline_actions": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Maximum number of form action buttons rendered inline before excess overflow into a dropdown. Default: 3.",
+      "default": 3
+    },
+    "scope": {
+      "type": "string",
+      "description": "Base query scope applied to all records in this presenter. 'discarded' shows only soft-deleted records; 'with_discarded' includes both.",
+      "enum": ["discarded", "with_discarded"]
+    },
+    "record_aliases": {
+      "type": "object",
+      "description": "Named URL segments that resolve to a specific record dynamically. Keys are alias names (e.g., 'me', 'last'). Aliases are presenter-level — the same model may have different aliases in different presenters.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "resolve": {
+            "type": "string",
+            "enum": ["current_user", "field_on_user", "scope"],
+            "description": "Resolution strategy. current_user: match belongs_to FK against current_user.id. field_on_user: read a scalar PK value from current_user. scope: call a named scope and take first result."
+          },
+          "field": {
+            "type": "string",
+            "description": "For current_user strategy: belongs_to association name to match against current_user.id."
+          },
+          "user_field": {
+            "type": "string",
+            "description": "For field_on_user strategy: method or column on current_user that returns target record PK."
+          },
+          "scope": {
+            "type": "string",
+            "description": "For scope strategy: zero-arity named scope on the model. The first result is returned via .first!."
+          }
+        },
+        "required": ["resolve"],
+        "additionalProperties": false
+      }
+    },
+    "dialog": {
+      "type": "object",
+      "description": "Dialog rendering configuration. When present, the presenter can be opened as a modal dialog. Presenters without a slug are dialog-only.",
+      "properties": {
+        "size": {
+          "type": "string",
+          "description": "Dialog size.",
+          "enum": ["small", "medium", "large", "fullscreen"],
+          "default": "medium"
+        },
+        "title_key": {
+          "type": "string",
+          "description": "I18n key for the dialog title.",
+          "examples": ["lcp_ruby.dialogs.quick_edit_title"]
+        },
+        "closable": {
+          "type": "boolean",
+          "description": "Whether the dialog shows a close button and can be dismissed.",
+          "default": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "index": { "$ref": "#/$defs/index_config" },
+    "show": { "$ref": "#/$defs/show_config" },
+    "form": { "$ref": "#/$defs/form_config" },
+    "search": { "$ref": "#/$defs/search_config" },
+    "actions": { "$ref": "#/$defs/actions_config" },
+    "controller": {
+      "type": "string",
+      "description": "Route all CRUD actions for this presenter to a host app controller instead of LCP's ResourcesController. Value is the controller path (e.g., 'checkouts' or 'admin/reports'). Mutually exclusive with action_controllers.",
+      "examples": ["checkouts", "admin/reports"]
+    },
+    "action_controllers": {
+      "type": "object",
+      "description": "Route specific actions to host app controllers while keeping the rest in LCP's ResourcesController. Keys must be one of the 7 CRUD actions; values are 'controller#action' strings (lowercase, snake_case). Mutually exclusive with controller.",
+      "propertyNames": {
+        "enum": ["index", "show", "new", "create", "edit", "update", "destroy"]
+      },
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_/]*#[a-z][a-z0-9_]*$"
+      },
+      "examples": [
+        { "new": "orders/wizard#new", "create": "orders/wizard#create" }
+      ]
+    },
+    "export": { "$ref": "#/$defs/export_config" },
+    "import": { "$ref": "#/$defs/import_config" }
+  },
+  "required": ["name", "model"],
+  "additionalProperties": false,
+
+  "$defs": {
+    "condition": {
+      "description": "Condition for visible_when/disable_when. Accepts: a field-based condition ({field, operator, value}), a service condition ({service: <name>, params: { ... }} where params are passed as kwargs to the service — see built-in `current_user_role`), a compound (`all`/`any`/`not`), a collection condition ({collection, quantifier, condition}), or a method name string invoked on the record. See docs/reference/condition-operators.md for the full surface.",
+      "type": ["object", "string"],
+      "examples": [
+        { "field": "status", "operator": "eq", "value": "active" },
+        { "service": "current_user_role", "params": { "in": ["admin", "manager"] } },
+        { "all": [{ "field": "status", "operator": "eq", "value": "draft" }, { "service": "current_user_role", "params": { "in": ["admin"] } }] },
+        "can_archive?"
+      ]
+    },
+
+    "hidden_on": {
+      "description": "Hide the element on specific device sizes. Accepts a single value or array.",
+      "oneOf": [
+        { "type": "string", "enum": ["mobile", "tablet"] },
+        { "type": "array", "items": { "type": "string", "enum": ["mobile", "tablet"] } }
+      ],
+      "examples": ["mobile", ["mobile", "tablet"]]
+    },
+
+    "item_class_rule": {
+      "type": "object",
+      "description": "A conditional CSS class rule for index rows/cards. When the condition matches, the CSS class is applied to the element.",
+      "properties": {
+        "class": {
+          "type": "string",
+          "description": "One or more CSS class names (space-separated) to apply when the condition matches.",
+          "examples": ["lcp-row-danger", "lcp-row-muted lcp-row-strikethrough"]
+        },
+        "when": {
+          "$ref": "#/$defs/condition",
+          "description": "Condition evaluated against each record to determine if the class should be applied."
+        }
+      },
+      "required": ["class", "when"],
+      "additionalProperties": false
+    },
+
+    "table_column": {
+      "type": "object",
+      "description": "A column in the index table view.",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Field name to display. Supports dot-path for associations (e.g., 'department.name') and template syntax (e.g., '{first_name} {last_name}').",
+          "examples": ["name", "department.name", "{first_name} {last_name}"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Column header text. Falls back to humanized field name."
+        },
+        "width": {
+          "type": "string",
+          "description": "Column width as CSS value.",
+          "examples": ["30%", "200px", "auto"]
+        },
+        "link_to": {
+          "type": "string",
+          "description": "Make the cell value a link to this action (typically 'show'). Legacy option — always links to the current row. For linking through a belongs_to association (e.g. 'manager.display_name' → manager's show page), use 'link: true' or 'link_through:' instead.",
+          "examples": ["show", "edit"]
+        },
+        "link": {
+          "type": "boolean",
+          "description": "Render the cell value as a link. Auto-detects the link target from the field: dot-path ('manager.display_name') links to the last belongs_to record in the chain; a plain belongs_to field name ('manager') links to that record; a scalar field links to the current row (equivalent to legacy link_to: show). Use 'link_through:' to override auto-detection."
+        },
+        "link_through": {
+          "type": "string",
+          "description": "Name of a belongs_to association on this model to follow for the link target. Implies 'link: true'. Use to override auto-detection when the displayed field's name doesn't correspond to the linked entity (e.g. a precomputed label)."
+        },
+        "link_presenter": {
+          "type": "string",
+          "description": "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 index, full detail elsewhere). Falls back to the model's `default: true` presenter when absent.",
+          "examples": ["contact_short", "employee_compact"]
+        },
+        "sortable": {
+          "type": "boolean",
+          "description": "Allow sorting by this column via clickable header."
+        },
+        "renderer": {
+          "type": "string",
+          "description": "Display renderer name from the RendererRegistry (e.g., badge, date, currency, email_link).",
+          "examples": ["badge", "date", "currency", "boolean_icon", "email_link"]
+        },
+        "options": {
+          "type": "object",
+          "description": "Options passed to the renderer (e.g., color_map for badge renderer).",
+          "examples": [{ "color_map": { "active": "green", "inactive": "gray" } }]
+        },
+        "partial": {
+          "type": "string",
+          "description": "ERB partial path for fully custom cell rendering. Receives the record as a local.",
+          "examples": ["employees/status_cell"]
+        },
+        "hidden_on": { "$ref": "#/$defs/hidden_on" },
+        "pinned": {
+          "type": "string",
+          "description": "Pin the column to the left or right edge of the table (stays visible during horizontal scroll).",
+          "enum": ["left", "right"]
+        },
+        "summary": {
+          "type": "string",
+          "description": "Show a summary row at the bottom of the table with the specified aggregation.",
+          "enum": ["sum", "avg", "count"]
+        },
+        "copyable": {
+          "type": "boolean",
+          "description": "Show a copy-to-clipboard button next to the cell value."
+        },
+        "visible_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally show this column based on a field condition or service."
+        },
+        "disable_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally disable (gray out) this column."
+        },
+        "aggregate": {
+          "type": "string",
+          "description": "Aggregate function for grouped query columns (e.g., count, sum, avg, min, max).",
+          "enum": ["count", "sum", "avg", "min", "max"]
+        },
+        "aggregate_field": {
+          "type": "string",
+          "description": "Field to aggregate over. Defaults to the column field. Required for sum/avg/min/max when different from field."
+        },
+        "distinct": {
+          "type": "boolean",
+          "description": "Apply DISTINCT to the aggregate function."
+        },
+        "display_in_index": {
+          "type": "boolean",
+          "description": "Per-column opt-in for fields whose type has default_index_visible: false (e.g. :text, :rich_text, :attachment, :json, :array, :file). Without this kwarg, the validator emits a row-unfriendly-column warning suggesting either an explicit renderer or this opt-in. Has no runtime effect — purely a validator-silencer. Default: false.",
+          "default": false,
+          "examples": [true]
+        }
+      },
+      "required": ["field"],
+      "additionalProperties": false
+    },
+
+    "show_field": {
+      "description": "Field in show section. Regular field (has 'field' key), divider (type: divider), or info box (type: info).",
+      "type": "object",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Field name to display. Supports dot-path and template syntax.",
+          "examples": ["name", "department.name", "{first_name} {last_name}"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Override the field label."
+        },
+        "renderer": {
+          "type": "string",
+          "description": "Display renderer name.",
+          "examples": ["badge", "date", "currency", "rich_text", "attachment_gallery"]
+        },
+        "options": {
+          "type": "object",
+          "description": "Options passed to the renderer."
+        },
+        "partial": {
+          "type": "string",
+          "description": "ERB partial for custom field rendering."
+        },
+        "col_span": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of grid columns this field spans (for multi-column section layouts).",
+          "examples": [2, 3]
+        },
+        "copyable": {
+          "type": "boolean",
+          "description": "Show a copy-to-clipboard button next to the value."
+        },
+        "link": {
+          "type": "boolean",
+          "description": "Render the field value as a link. Auto-detects the target from a dot-path ('manager.display_name' → manager's show page, 'manager.organizational_unit.name' → org unit's show page) or from a plain belongs_to field name. Use 'link_through:' to override auto-detection."
+        },
+        "link_through": {
+          "type": "string",
+          "description": "Name of a belongs_to association on this model to follow for the link target. Implies 'link: true'. Use to override auto-detection when the displayed field's name doesn't correspond to the linked entity."
+        },
+        "link_presenter": {
+          "type": "string",
+          "description": "Override the target presenter slug for this link. Use when the linked model has multiple presenters and you want a non-default one. Falls back to the model's `default: true` presenter when absent.",
+          "examples": ["contact_short", "employee_compact"]
+        },
+        "hint": {
+          "type": "string",
+          "description": "Help text displayed below the field value.",
+          "examples": ["This value is calculated from the employee's base salary and bonus."]
+        },
+        "hidden_on": { "$ref": "#/$defs/hidden_on" },
+        "visible_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally show this field based on a record condition."
+        },
+        "disable_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally disable (gray out) this field."
+        },
+        "type": {
+          "type": "string",
+          "description": "Special field types: 'divider' renders a horizontal line, 'info' renders a text box. In nested_fields context, also accepts data types (string, integer, etc.).",
+          "enum": ["divider", "info", "string", "text", "integer", "float", "decimal", "boolean", "date", "datetime", "enum"]
+        },
+        "text": {
+          "type": "string",
+          "description": "Text content for type: info fields."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "form_field": {
+      "description": "Field in form section. Regular input (has 'field' key), divider (type: divider), or info box (type: info).",
+      "type": "object",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Field name matching a model field or association FK.",
+          "examples": ["name", "department_id", "status"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Override the input label."
+        },
+        "input_type": {
+          "type": "string",
+          "description": "Input widget type. Inferred from field type if omitted (e.g., text for string, select for enum, association_select for FK).",
+          "examples": ["text", "textarea", "select", "date", "color", "association_select", "rich_text", "file"]
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "Placeholder text shown in empty inputs.",
+          "examples": ["Enter employee name..."]
+        },
+        "autofocus": {
+          "type": "boolean",
+          "description": "Automatically focus this input when the form loads. Only one field per form should have this."
+        },
+        "prefix": {
+          "type": "string",
+          "description": "Text or symbol shown before the input (e.g., currency symbol).",
+          "examples": ["$", "EUR"]
+        },
+        "suffix": {
+          "type": "string",
+          "description": "Text or symbol shown after the input (e.g., unit).",
+          "examples": ["%", "kg", "hours"]
+        },
+        "col_span": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of grid columns this field spans."
+        },
+        "hint": {
+          "type": "string",
+          "description": "Help text displayed below the input.",
+          "examples": ["Use format: +1-234-567-8900"]
+        },
+        "readonly": {
+          "type": "boolean",
+          "description": "Render the field as read-only (displayed but not editable)."
+        },
+        "visible_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally show this field based on other form field values. Evaluated client-side for instant reactivity."
+        },
+        "disable_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally disable this field based on other form field values."
+        },
+        "default": {
+          "description": "Default value pre-filled in the form for new records. Overrides the model-level default."
+        },
+        "input_options": {
+          "type": "object",
+          "description": "HTML attributes and widget-specific options for the input element.",
+          "examples": [{ "rows": 6 }, { "min": 0, "step": 0.01 }]
+        },
+        "options": {
+          "type": "object",
+          "description": "Options passed to the renderer when the field uses a custom renderer instead of the default input."
+        },
+        "renderer": {
+          "type": "string",
+          "description": "Use a display renderer instead of an input widget (makes the field read-only in the form)."
+        },
+        "partial": {
+          "type": "string",
+          "description": "ERB partial for fully custom input rendering."
+        },
+        "hidden_on": { "$ref": "#/$defs/hidden_on" },
+        "type": {
+          "type": "string",
+          "description": "Special types: 'divider' renders a horizontal line, 'info' renders a text box. In nested_fields context, also accepts data types (string, integer, etc.).",
+          "enum": ["divider", "info", "string", "text", "integer", "float", "decimal", "boolean", "date", "datetime", "enum"]
+        },
+        "text": {
+          "type": "string",
+          "description": "Text content for type: info fields."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "show_section": {
+      "description": "Section in show page layout. Regular field section, association_list (embedded table of related records), json_items_list (items from a JSON column), or audit_history (change log).",
+      "type": "object",
+      "properties": {
+        "section": {
+          "type": "string",
+          "description": "Section title displayed as the heading. When `section_key` is not set, the title is parameterized and used as the i18n lookup key: lcp_ruby.presenters.<presenter>.sections.<parameterized_title>.",
+          "examples": ["Overview", "Contact Details", "Employment History"]
+        },
+        "section_key": {
+          "type": "string",
+          "description": "Explicit i18n lookup key for the section heading. Decouples the i18n key from the human-readable label, so non-English literals don't leak into the en locale as fallback values. Lookup: lcp_ruby.presenters.<presenter>.sections.<section_key>. Falls back to the `section` value (or humanized key) when the i18n entry is missing.",
+          "examples": ["details", "list_overview", "contact"]
+        },
+        "type": {
+          "type": "string",
+          "description": "Section type. Omit for regular field sections. 'custom' delegates rendering to a host-app partial.",
+          "enum": ["association_list", "json_items_list", "audit_history", "custom"]
+        },
+        "partial": {
+          "type": "string",
+          "description": "For type: custom — host-app partial path to render inside the section wrapper.",
+          "examples": ["employees/location_map", "products/custom_gallery"]
+        },
+        "columns": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of grid columns for field layout within this section.",
+          "examples": [2, 3]
+        },
+        "description": {
+          "type": "string",
+          "description": "Explanatory text shown below the section title."
+        },
+        "responsive": {
+          "type": "object",
+          "description": "Responsive column overrides per breakpoint (e.g., {mobile: 1, tablet: 2})."
+        },
+        "visible_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally show this entire section based on the record's field values."
+        },
+        "disable_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally disable (gray out) this section."
+        },
+        "fields": {
+          "type": "array",
+          "description": "Fields displayed in this section (for regular and json_items_list sections).",
+          "items": { "$ref": "#/$defs/show_field" }
+        },
+        "sub_sections": {
+          "type": "array",
+          "description": "Sub-sections for organizing fields into groups within a json_items_list or nested section.",
+          "items": { "$ref": "#/$defs/sub_section" }
+        },
+        "association": {
+          "type": "string",
+          "description": "For type: association_list — the association name on the model.",
+          "examples": ["employees", "skills", "comments"]
+        },
+        "json_field": {
+          "type": "string",
+          "description": "For type: json_items_list — the JSON column name containing the array of items.",
+          "examples": ["addresses", "work_history"]
+        },
+        "target_model": {
+          "type": "string",
+          "description": "For type: json_items_list — virtual model defining the field schema for each JSON item.",
+          "examples": ["address", "work_history_entry"]
+        },
+        "display_template": {
+          "type": "string",
+          "description": "For type: association_list — template for rendering each item. Uses {field} interpolation.",
+          "examples": ["{name}", "{first_name} {last_name} ({role})"]
+        },
+        "link": {
+          "type": "boolean",
+          "description": "For type: association_list — make each item a link to its show page."
+        },
+        "link_through": {
+          "type": "string",
+          "description": "For type: association_list — follow this belongs_to association on the target model to resolve the link target."
+        },
+        "link_presenter": {
+          "type": "string",
+          "description": "For type: association_list — override the target presenter slug for the link. Use when the linked model has multiple presenters. Falls back to the model's `default: true` presenter when absent.",
+          "examples": ["contact_short", "employee_compact"]
+        },
+        "sort": {
+          "type": "object",
+          "description": "For type: association_list — default ordering of items.",
+          "examples": [{ "created_at": "desc" }]
+        },
+        "limit": {
+          "type": "integer",
+          "description": "For type: association_list — maximum number of items to display.",
+          "examples": [5, 10]
+        },
+        "empty_message": {
+          "type": "string",
+          "description": "Message shown when no items exist.",
+          "examples": ["No employees found.", "No history entries yet."]
+        },
+        "scope": {
+          "type": "string",
+          "description": "For type: association_list — named scope to apply when loading items.",
+          "examples": ["active", "recent"]
+        }
+      },
+      "required": ["section"],
+      "additionalProperties": false
+    },
+
+    "form_section": {
+      "description": "Section in form layout. Regular section (title + fields) or nested_fields (editable association or JSON items).",
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "Section heading. When `section_key` is not set, the title is parameterized and used as the i18n lookup key: lcp_ruby.presenters.<presenter>.sections.<parameterized_title>.",
+          "examples": ["Basic Information", "Address", "Skills"]
+        },
+        "section_key": {
+          "type": "string",
+          "description": "Explicit i18n lookup key for the section heading. Decouples the i18n key from the human-readable label. Lookup: lcp_ruby.presenters.<presenter>.sections.<section_key>. Falls back to the `title` value (or humanized key) when the i18n entry is missing.",
+          "examples": ["basic_info", "address", "skills"]
+        },
+        "type": {
+          "type": "string",
+          "description": "Set to 'nested_fields' for inline editing of associated records or JSON array items. 'custom' delegates rendering to a host-app partial.",
+          "enum": ["nested_fields", "custom"]
+        },
+        "partial": {
+          "type": "string",
+          "description": "For type: custom — host-app partial path to render inside the form fieldset wrapper.",
+          "examples": ["products/variants_editor", "employees/custom_form_section"]
+        },
+        "additional_permitted_params": {
+          "type": "array",
+          "description": "For type: custom — extra param names permitted from the custom section's inputs. Supports scalar strings and single-key hash specs for nested params.",
+          "items": {
+            "oneOf": [
+              { "type": "string" },
+              { "type": "object" }
+            ]
+          },
+          "examples": [["variants_json"], [{ "address": ["street", "city", "zip"] }]]
+        },
+        "columns": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of grid columns for field layout.",
+          "examples": [2, 3]
+        },
+        "description": {
+          "type": "string",
+          "description": "Explanatory text shown below the section title."
+        },
+        "responsive": {
+          "type": "object",
+          "description": "Responsive column overrides per breakpoint."
+        },
+        "collapsible": {
+          "type": "boolean",
+          "description": "Allow the section to be collapsed/expanded by clicking the title."
+        },
+        "collapsed": {
+          "type": "boolean",
+          "description": "Start the section in collapsed state. Only effective when collapsible: true."
+        },
+        "visible_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally show this section based on form field values."
+        },
+        "disable_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally disable all inputs in this section."
+        },
+        "fields": {
+          "type": "array",
+          "description": "Input fields in this section.",
+          "items": { "$ref": "#/$defs/form_field" }
+        },
+        "sub_sections": {
+          "type": "array",
+          "description": "Sub-sections for organizing fields into titled groups within nested_fields.",
+          "items": { "$ref": "#/$defs/sub_section" }
+        },
+        "association": {
+          "type": "string",
+          "description": "For type: nested_fields with AR associations — the association name. Requires nested_attributes on the model.",
+          "examples": ["addresses", "phone_numbers"]
+        },
+        "json_field": {
+          "type": "string",
+          "description": "For type: nested_fields with JSON columns — the JSON column name storing the array of items.",
+          "examples": ["addresses", "work_history"]
+        },
+        "target_model": {
+          "type": "string",
+          "description": "For type: nested_fields with JSON — virtual model defining field schema and validations for each item.",
+          "examples": ["address", "work_history_entry"]
+        },
+        "allow_add": {
+          "type": "boolean",
+          "description": "For type: nested_fields — show an 'Add' button to create new items."
+        },
+        "allow_remove": {
+          "type": "boolean",
+          "description": "For type: nested_fields — show a 'Remove' button on each item."
+        },
+        "min": {
+          "type": "integer",
+          "description": "For type: nested_fields — minimum number of items required."
+        },
+        "max": {
+          "type": "integer",
+          "description": "For type: nested_fields — maximum number of items allowed."
+        },
+        "add_label": {
+          "type": "string",
+          "description": "For type: nested_fields — custom label for the 'Add' button.",
+          "examples": ["Add Address", "Add Skill"]
+        },
+        "empty_message": {
+          "type": "string",
+          "description": "For type: nested_fields — message shown when no items exist."
+        },
+        "sortable": {
+          "description": "For type: nested_fields — enable drag-and-drop reordering of items. Boolean true or a config object."
+        }
+      },
+      "required": ["title"],
+      "additionalProperties": false
+    },
+
+    "sub_section": {
+      "description": "Sub-section within nested_fields or json_items_list, grouping fields under a titled sub-heading.",
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "Sub-section heading.",
+          "examples": ["Street Address", "Emergency Contact"]
+        },
+        "columns": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of grid columns for field layout within this sub-section."
+        },
+        "collapsible": { "type": "boolean", "description": "Allow collapsing." },
+        "collapsed": { "type": "boolean", "description": "Start collapsed." },
+        "visible_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally show this sub-section."
+        },
+        "disable_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally disable all inputs in this sub-section."
+        },
+        "fields": {
+          "type": "array",
+          "description": "Input fields in this sub-section.",
+          "items": { "$ref": "#/$defs/form_field" }
+        }
+      },
+      "required": ["title"],
+      "additionalProperties": false
+    },
+
+    "action": {
+      "type": "object",
+      "description": "A UI action button shown on index or show pages.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Action identifier. Built-in names: show, edit, destroy, create, update, restore, permanently_destroy.",
+          "examples": ["show", "edit", "destroy", "archive", "export_pdf"]
+        },
+        "type": {
+          "type": "string",
+          "description": "'built_in' for standard CRUD actions; 'custom' for host-app actions; 'dialog' for actions that open a modal dialog; 'transition' for workflow transition overrides.",
+          "enum": ["built_in", "custom", "dialog", "transition"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Button label text. Falls back to i18n lookup: lcp_ruby.actions.<name>."
+        },
+        "icon": {
+          "type": "string",
+          "description": "Lucide icon name for the action button.",
+          "examples": ["plus", "pencil", "trash-2", "archive"]
+        },
+        "confirm": {
+          "description": "Confirmation before executing. true uses browser confirm, string provides custom message, object for page-based or styled confirmation dialogs.",
+          "oneOf": [
+            { "type": "boolean" },
+            { "type": "string" },
+            {
+              "type": "object",
+              "description": "Page-based confirmation dialog. Opens a presenter-driven dialog form; on success, executes the original action with form data forwarded as confirmation_data params.",
+              "properties": {
+                "page": {
+                  "type": "string",
+                  "description": "Page name referencing a dialog-only presenter (e.g., 'delete_reason_dialog')."
+                },
+                "size": {
+                  "type": "string",
+                  "description": "Override the dialog size from page config.",
+                  "enum": ["small", "medium", "large", "fullscreen"]
+                }
+              },
+              "required": ["page"],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "description": "Styled confirmation dialog with custom title and message via i18n keys.",
+              "properties": {
+                "title_key": {
+                  "type": "string",
+                  "description": "I18n key for the confirmation dialog title."
+                },
+                "message_key": {
+                  "type": "string",
+                  "description": "I18n key for the confirmation dialog message."
+                },
+                "style": {
+                  "type": "string",
+                  "description": "Visual style of the confirmation dialog (e.g., 'danger')."
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "description": "Role-scoped confirmation.",
+              "properties": {
+                "except": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Skip confirmation for these roles."
+                },
+                "only": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Only require confirmation for these roles."
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "examples": [true, "Are you sure?", { "page": "delete_reason_dialog" }, { "title_key": "lcp_ruby.dialogs.confirm_delete_title", "message_key": "lcp_ruby.dialogs.confirm_delete_message", "style": "danger" }]
+        },
+        "confirm_message": {
+          "type": "string",
+          "description": "Custom confirmation dialog message (alternative to confirm: 'message')."
+        },
+        "style": {
+          "type": "string",
+          "description": "Visual style of the button.",
+          "examples": ["danger", "primary", "secondary", "warning"]
+        },
+        "dialog": {
+          "type": "object",
+          "description": "Dialog configuration for type: dialog actions.",
+          "properties": {
+            "page": {
+              "type": "string",
+              "description": "Page name referencing a dialog-only presenter."
+            },
+            "record": {
+              "type": "string",
+              "description": "'current' to open the dialog with the current record for editing.",
+              "enum": ["current"]
+            },
+            "on_success": {
+              "type": "string",
+              "description": "Action after successful dialog submission.",
+              "enum": ["reload", "close", "redirect", "confirm_action", "reload_zone", "reload_zones"]
+            },
+            "size": {
+              "type": "string",
+              "description": "Override the dialog size from page config.",
+              "enum": ["small", "medium", "large", "fullscreen"]
+            },
+            "defaults": {
+              "type": "object",
+              "description": "Default field values to pre-fill in the dialog form.",
+              "additionalProperties": { "type": "string" }
+            },
+            "reload_zone": {
+              "type": "string",
+              "description": "Zone name to refresh when on_success is reload_zone."
+            },
+            "reload_zones": {
+              "type": "array",
+              "description": "Zone names to refresh when on_success is reload_zones.",
+              "items": { "type": "string" },
+              "minItems": 1
+            }
+          },
+          "required": ["page"],
+          "additionalProperties": false
+        },
+        "record": {
+          "type": "string",
+          "description": "Record context for dialog actions. 'current' passes the current record.",
+          "enum": ["current"]
+        },
+        "visible": {
+          "type": "boolean",
+          "description": "Explicitly show or hide this action. For transition overrides, set to false to suppress a workflow transition button in this presenter."
+        },
+        "visible_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally show this action based on the record's field values."
+        },
+        "disable_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditionally disable (gray out) this action."
+        },
+        "min_selection": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Batch actions: minimum records that must be selected (default: 1)."
+        },
+        "max_selection": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Batch actions: maximum records that can be selected."
+        },
+        "max_batch_records": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Batch actions: server-side limit on records affected."
+        },
+        "result_log": {
+          "type": "boolean",
+          "description": "Batch actions: enable per-record result tracking in batch operation log."
+        },
+        "select_all_filter": {
+          "type": "boolean",
+          "description": "Batch actions: allow 'select all matching filter' mode (default: true)."
+        },
+        "execution": {
+          "type": "string",
+          "enum": ["inline", "background", "auto"],
+          "description": "Batch actions: execution mode (default: inline)."
+        },
+        "background_threshold": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Batch actions: for execution: auto, record count above which action runs as background job (default: 100)."
+        },
+        "fields": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Batch update: which fields can be bulk-updated."
+        },
+        "strategy": {
+          "type": "string",
+          "enum": ["per_record", "bulk"],
+          "description": "Batch update: execution strategy (default: per_record)."
+        },
+        "pipeline": {
+          "type": "array",
+          "description": "Single actions: ordered list of operations to execute in a single transaction. On show pages there is no save step. Steps: { transition: <name> }, { action: <name> }.",
+          "items": {
+            "oneOf": [
+              { "type": "string", "const": "save" },
+              {
+                "type": "object",
+                "properties": {
+                  "transition": { "type": "string", "description": "Workflow transition name to fire." }
+                },
+                "required": ["transition"],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "action": { "type": "string", "description": "Custom action name. Resolved as <model>/<name>." }
+                },
+                "required": ["action"],
+                "additionalProperties": false
+              }
+            ]
+          },
+          "examples": [[{ "transition": "approve" }], [{ "transition": "reject" }, { "action": "notify_rejection" }]]
+        },
+        "transition": {
+          "type": "string",
+          "description": "Single actions: sugar for pipeline: [{ transition: <name> }]. Cannot be combined with pipeline or action.",
+          "examples": ["approve", "reject"]
+        },
+        "action": {
+          "type": "string",
+          "description": "Single actions: sugar for pipeline: [{ action: <name> }]. Cannot be combined with pipeline or transition.",
+          "examples": ["generate_report", "send_notification"]
+        },
+        "batch": {
+          "description": "Auto-derive a batch action from this single action. true: inherit name, type, icon, confirm, confirm_message, style, label, action_class. Hash: inherit and override with specified batch-specific options. Ignored on dialog and transition actions.",
+          "oneOf": [
+            { "type": "boolean" },
+            {
+              "type": "object",
+              "description": "Batch-specific overrides merged on top of inherited single action attributes.",
+              "properties": {
+                "execution": {
+                  "type": "string",
+                  "enum": ["inline", "background", "auto"],
+                  "description": "Execution mode. Default: inline."
+                },
+                "background_threshold": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "For execution: auto — record count above which action runs as background job. Default: 100."
+                },
+                "min_selection": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Minimum records that must be selected. Default: 1."
+                },
+                "max_selection": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Maximum records that can be selected."
+                },
+                "max_batch_records": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Server-side limit on records affected."
+                },
+                "result_log": {
+                  "type": "boolean",
+                  "description": "Enable per-record result tracking. Requires lcp_ruby:batch_operations generator."
+                },
+                "select_all_filter": {
+                  "type": "boolean",
+                  "description": "Allow 'select all matching filter' mode."
+                },
+                "confirm": {
+                  "type": "boolean",
+                  "description": "Override confirm behavior for the batch action."
+                },
+                "confirm_message": {
+                  "type": "string",
+                  "description": "Override confirmation message for the batch action."
+                },
+                "icon": {
+                  "type": "string",
+                  "description": "Override icon for the batch action."
+                },
+                "label": {
+                  "type": "string",
+                  "description": "Override label for the batch action."
+                },
+                "style": {
+                  "type": "string",
+                  "description": "Override button style for the batch action."
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "examples": [true, { "min_selection": 2, "result_log": true }, { "execution": "auto", "background_threshold": 50 }]
+        }
+      },
+      "required": ["name", "type"],
+      "additionalProperties": false
+    },
+
+    "form_action": {
+      "type": "object",
+      "description": "A submit button rendered in the form footer. Each form action defines what happens when the user clicks it — save, redirect, set fields, fire a workflow transition, or execute a custom action.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Unique identifier. Sent as `_form_action` param to the controller.",
+          "examples": ["save", "save_and_new", "save_and_submit", "cancel"]
+        },
+        "type": {
+          "type": "string",
+          "description": "'built_in' for platform-provided actions (save, cancel). Omit for custom form actions.",
+          "enum": ["built_in"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Button label text. Falls back to i18n lookup chain: presenter-specific -> global -> humanized name.",
+          "examples": ["Save & New", "Save & Submit for Approval"]
+        },
+        "submitting_label": {
+          "type": "string",
+          "description": "In-progress label shown while the form is submitting. Overrides the i18n fallback chain (lcp_ruby.form.submitting.<name>).",
+          "examples": ["Saving…", "Enqueuing import job…"]
+        },
+        "icon": {
+          "type": "string",
+          "description": "Lucide icon name rendered before the label.",
+          "examples": ["send", "globe", "check", "file-text"]
+        },
+        "style": {
+          "type": "string",
+          "description": "Button visual style.",
+          "enum": ["primary", "secondary", "success", "danger", "warning", "outline"],
+          "default": "secondary"
+        },
+        "redirect": {
+          "description": "Where to go after pipeline completes. String for simple targets, hash for cross-presenter navigation. Ignored in dialog context.",
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": ["show", "edit", "new", "index"]
+            },
+            {
+              "type": "object",
+              "description": "Follow an association to a related record's presenter.",
+              "properties": {
+                "association": {
+                  "type": "string",
+                  "description": "Association name on the model to follow."
+                },
+                "action": {
+                  "type": "string",
+                  "description": "Target action on the related presenter.",
+                  "enum": ["show", "edit", "new", "index"]
+                }
+              },
+              "required": ["association"],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "description": "Navigate to a specific presenter by slug, optionally passing query parameters.",
+              "properties": {
+                "presenter": {
+                  "type": "string",
+                  "description": "Target presenter slug."
+                },
+                "action": {
+                  "type": "string",
+                  "description": "Target action.",
+                  "enum": ["show", "edit", "new", "index"]
+                },
+                "defaults": {
+                  "type": "object",
+                  "description": "Query parameters passed to the target. Values use the same expression syntax as set_fields — static values, { field_ref: <field> }, { current_user: id }, etc."
+                }
+              },
+              "required": ["presenter"],
+              "additionalProperties": false
+            }
+          ],
+          "examples": ["show", "edit", "new", { "association": "order", "action": "show" }, { "presenter": "line_items", "action": "new", "defaults": { "order_id": { "field_ref": "id" } } }]
+        },
+        "set_fields": {
+          "type": "object",
+          "description": "Fields to set before the pipeline runs. Same syntax as workflow transition set_fields. Bypasses field-level write permissions (configurator-controlled).",
+          "examples": [{ "status": "published", "published_at": { "date": "now" } }]
+        },
+        "pipeline": {
+          "type": "array",
+          "description": "Ordered list of operations to execute in a single transaction. Steps: 'save', { transition: <name> }, { action: <name> }. Default: [save].",
+          "items": {
+            "oneOf": [
+              { "type": "string", "const": "save" },
+              {
+                "type": "object",
+                "properties": {
+                  "transition": { "type": "string", "description": "Workflow transition name to fire." }
+                },
+                "required": ["transition"],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "action": { "type": "string", "description": "Custom action name. Resolved as <model>/<name>." }
+                },
+                "required": ["action"],
+                "additionalProperties": false
+              }
+            ]
+          },
+          "examples": [["save"], ["save", { "transition": "submit" }], ["save", { "transition": "submit" }, { "action": "notify_approvers" }]]
+        },
+        "transition": {
+          "type": "string",
+          "description": "Sugar for pipeline: [save, { transition: <name> }]. Cannot be combined with pipeline or action.",
+          "examples": ["submit", "approve"]
+        },
+        "action": {
+          "type": "string",
+          "description": "Sugar for pipeline: [save, { action: <name> }]. Cannot be combined with pipeline or transition.",
+          "examples": ["generate_invoice", "notify_manager"]
+        },
+        "confirm": {
+          "description": "Confirmation before executing. Same syntax as record action confirm — boolean, string message, or object for styled/role-scoped confirmation.",
+          "oneOf": [
+            { "type": "boolean" },
+            { "type": "string" },
+            {
+              "type": "object",
+              "description": "Styled confirmation dialog.",
+              "properties": {
+                "title_key": { "type": "string" },
+                "message_key": { "type": "string" },
+                "style": { "type": "string" }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "description": "Role-scoped confirmation.",
+              "properties": {
+                "except": { "type": "array", "items": { "type": "string" } },
+                "only": { "type": "array", "items": { "type": "string" } }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "examples": [true, "Submit this PO for approval?"]
+        },
+        "confirm_message": {
+          "type": "string",
+          "description": "Custom confirmation dialog message text.",
+          "examples": ["Submit for approval? You won't be able to edit after this."]
+        },
+        "visible_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Field-value or service condition for visibility."
+        },
+        "disable_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Condition for disabled state."
+        },
+        "only_on": {
+          "type": "string",
+          "description": "Restrict to create or update context. Omit to show on both.",
+          "enum": ["create", "update"]
+        },
+        "only_roles": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Only these roles see this button.",
+          "examples": [["admin", "manager"]]
+        },
+        "except_roles": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "These roles do not see this button.",
+          "examples": [["viewer"]]
+        },
+        "dialog_behavior": {
+          "type": "string",
+          "description": "Dialog-only: what happens after successful save. 'close' closes the dialog, 'reset' clears the form and keeps it open, 'reload' reloads the parent page, 'show_result' renders a result partial (one-time secret display, etc.) — requires a 'result' config. Ignored outside dialog context.",
+          "enum": ["close", "reset", "reload", "show_result"]
+        },
+        "result": {
+          "type": "object",
+          "description": "Configuration for dialog_behavior: show_result. Selects a platform-shipped partial via 'style' (currently: 'single_secret'), or renders a host partial via 'partial'. When 'style' is given, 'field' names the in-memory record attribute to display.",
+          "properties": {
+            "style": {
+              "type": "string",
+              "enum": ["single_secret"],
+              "description": "Platform-shipped result style. Maps to app/views/lcp_ruby/dialogs/_<style>.html.erb."
+            },
+            "partial": {
+              "type": "string",
+              "description": "Host-owned partial path (escape hatch). Mutually exclusive with 'style'."
+            },
+            "field": {
+              "type": "string",
+              "description": "Required when 'style' is set: the model attribute to display."
+            },
+            "title_key": {
+              "type": "string",
+              "description": "I18n key for the dialog heading."
+            },
+            "warning_key": {
+              "type": "string",
+              "description": "I18n key for the warning paragraph (e.g., 'this will not be shown again')."
+            }
+          },
+          "additionalProperties": false
+        },
+        "position": {
+          "type": "string",
+          "description": "'inline' renders the button in the row, 'dropdown' forces it into the overflow menu.",
+          "enum": ["inline", "dropdown"],
+          "default": "inline"
+        }
+      },
+      "required": ["name"],
+      "additionalProperties": false
+    },
+
+    "search_filter": {
+      "type": "object",
+      "description": "A predefined filter shown as a tab/chip above the index table. Activates a named scope on the model.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Filter identifier, usually matching a scope name.",
+          "examples": ["active", "overdue", "my_records"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Display label for the filter tab."
+        },
+        "default": {
+          "type": "boolean",
+          "description": "If true, this filter is active by default when the page loads."
+        },
+        "scope": {
+          "type": "string",
+          "description": "Scope name to activate. Defaults to the filter name if omitted.",
+          "examples": ["active", "with_discarded"]
+        }
+      },
+      "required": ["name", "label"],
+      "additionalProperties": false,
+      "examples": [{ "name": "active", "label": "Active", "default": true }]
+    },
+
+    "search_parameter": {
+      "type": "object",
+      "description": "A typed filter control rendered in the search toolbar (dropdown, toggle, or range input).",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Parameter identifier."
+        },
+        "type": {
+          "type": "string",
+          "description": "Control type.",
+          "enum": ["enum_select", "association_select", "boolean_select", "number_range", "date_range"]
+        },
+        "field": {
+          "type": "string",
+          "description": "Model field name to filter by."
+        },
+        "model": {
+          "type": "string",
+          "description": "Target model name for association_select. Auto-derived from field's belongs_to if omitted."
+        },
+        "options": {
+          "type": "array",
+          "description": "Explicit options for enum_select. Auto-derived from model enum definition if omitted.",
+          "items": { "type": "string" }
+        },
+        "label_key": {
+          "type": "string",
+          "description": "I18n key for the parameter label."
+        },
+        "label_method": {
+          "type": "string",
+          "description": "Method name for display label on association records."
+        },
+        "visible_when": {
+          "type": "object",
+          "description": "Role-based visibility. Only the 'role' key is supported (no condition-based evaluation on index pages).",
+          "properties": {
+            "role": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Role name or array of role names that can see this parameter."
+            }
+          },
+          "additionalProperties": false
+        },
+        "search": {
+          "type": "boolean",
+          "description": "Enable server-side search for association_select (remote Tom Select mode)."
+        },
+        "min_query_length": {
+          "type": "integer",
+          "description": "Minimum characters before remote search triggers.",
+          "minimum": 0
+        },
+        "per_page": {
+          "type": "integer",
+          "description": "Results per page for remote search.",
+          "minimum": 1
+        },
+        "include_blank": {
+          "oneOf": [
+            { "type": "boolean" },
+            { "type": "string" }
+          ],
+          "description": "Label for the blank 'All' option. Set to false to omit, or a string to customize the label."
+        },
+        "col_span": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of grid columns this parameter spans. Range types default to 2 when search columns >= 2."
+        }
+      },
+      "required": ["name", "type", "field"],
+      "additionalProperties": false
+    },
+
+    "default_sort": {
+      "type": "object",
+      "description": "Default sorting applied to the index table on initial load.",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Field name to sort by.",
+          "examples": ["name", "created_at", "status"]
+        },
+        "direction": {
+          "type": "string",
+          "description": "Sort direction.",
+          "enum": ["asc", "desc"],
+          "default": "asc"
+        }
+      },
+      "required": ["field"],
+      "additionalProperties": false,
+      "examples": [{ "field": "created_at", "direction": "desc" }]
+    },
+
+    "card_field": {
+      "type": "object",
+      "description": "A field displayed in a card field list.",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Field name to display. Supports dot-path for associations."
+        },
+        "label": {
+          "type": "string",
+          "description": "Label shown next to the field value."
+        },
+        "renderer": {
+          "type": "string",
+          "description": "Display renderer name. Mutually exclusive with 'partial' (partial wins)."
+        },
+        "options": {
+          "type": "object",
+          "description": "Options passed to the renderer or partial."
+        },
+        "partial": {
+          "type": "string",
+          "description": "Host-app partial path for fully custom cell rendering. Receives locals { value, record, options }. Mutually exclusive with 'renderer' (partial wins)."
+        }
+      },
+      "required": ["field"],
+      "additionalProperties": false
+    },
+
+    "card_config": {
+      "type": "object",
+      "description": "Per-record card interior shared across card-based layouts (tiles, kanban, future). Zone resolution lives in LcpRuby::Display::CardHelper; per-layout body partials compose these zones in their own order.",
+      "properties": {
+        "title_field": {
+          "type": "string",
+          "description": "Field to display as the card title. Required for any card-based layout."
+        },
+        "subtitle_field": {
+          "type": "string",
+          "description": "Field to display as the card subtitle."
+        },
+        "subtitle_renderer": {
+          "type": "string",
+          "description": "Renderer for the subtitle field (e.g., 'badge')."
+        },
+        "subtitle_options": {
+          "type": "object",
+          "description": "Options passed to the subtitle renderer."
+        },
+        "description_field": {
+          "type": "string",
+          "description": "Field for card description text, shown with line clamping."
+        },
+        "description_max_lines": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum lines for description text before truncation.",
+          "default": 3
+        },
+        "image_field": {
+          "type": "string",
+          "description": "Field containing image URL or Active Storage attachment for the banner image zone."
+        },
+        "image_alt_field": {
+          "type": "string",
+          "description": "Field providing alt text for the banner image. Falls back to title_field value when unset."
+        },
+        "avatar_field": {
+          "type": "string",
+          "description": "Field containing image URL or Active Storage attachment for the small circular avatar zone."
+        },
+        "avatar_alt_field": {
+          "type": "string",
+          "description": "Field providing alt text for the avatar. Defaults to '' (decorative) when unset."
+        },
+        "color_field": {
+          "type": "string",
+          "description": "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": {
+          "type": "object",
+          "description": "Maps field values to whitelisted palette tokens.",
+          "additionalProperties": {
+            "type": "string",
+            "enum": ["success", "danger", "warning", "info", "muted", "primary"]
+          }
+        },
+        "actions": {
+          "type": "string",
+          "description": "How to render per-card actions.",
+          "enum": ["dropdown", "inline", "none"],
+          "default": "dropdown"
+        },
+        "render_with": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_/]*$",
+          "description": "Host-app partial path rendering the full card body. Lowercase, slash-separated (e.g., 'my_app/cards/deal'). File must exist at app/views/<path>/_<basename>.html.erb. Validated for shape at boot; existence checked at first render.",
+          "examples": ["my_app/cards/deal", "admin/cards/company"]
+        },
+        "fields": {
+          "type": "array",
+          "description": "Additional fields displayed as label-value pairs in the card.",
+          "items": { "$ref": "#/$defs/card_field" }
+        }
+      },
+      "required": ["title_field"],
+      "additionalProperties": false
+    },
+
+    "tile_config": {
+      "type": "object",
+      "description": "Tile-layout-specific grid configuration. Card zone rendering lives in card_config (sibling 'card:' block).",
+      "properties": {
+        "columns": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of tile columns in the grid.",
+          "default": 3,
+          "examples": [2, 3, 4]
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "kanban_config": {
+      "type": "object",
+      "description": "Kanban-layout-specific configuration. Card zone rendering lives in card_config (sibling 'card:' block). See docs/design/kanban_view.md for the full Phase 1 contract.",
+      "properties": {
+        "provider": {
+          "type": "string",
+          "description": "Custom provider class name (must inherit from LcpRuby::Kanban::HostProvider). When unset, DefaultProvider is used.",
+          "examples": ["TaskUrgencyProvider", "MyApp::CustomKanbanProvider"]
+        },
+        "group_by": {
+          "type": "string",
+          "description": "Field used to bucket records into columns. Required for DefaultProvider (workflow field, enum field, or belongs_to association). Treated as a hint by custom providers.",
+          "examples": ["status", "stage", "assignee"]
+        },
+        "column_order": {
+          "type": "array",
+          "description": "Explicit column ordering. Required when group_by is a belongs_to association (FK list). For workflow/enum, overrides default declared order.",
+          "items": { "type": ["string", "integer"] }
+        },
+        "cards_per_column": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 20,
+          "description": "Maximum cards loaded per column on initial render; remaining loaded via 'Load more' (Turbo Frame)."
+        },
+        "within_column_order": {
+          "type": "string",
+          "description": "ORDER BY expression for cards within a column (e.g., 'created_at DESC'). Defaults: position ASC when model is positioned and scope matches; else created_at DESC; else id DESC."
+        },
+        "show_null_column": {
+          "type": "boolean",
+          "default": false,
+          "description": "Show a leading 'Uncategorized' column for records whose group_by value is NULL."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "sort_field_entry": {
+      "type": "object",
+      "description": "A field available in the sort dropdown.",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Field name to sort by."
+        },
+        "label": {
+          "type": "string",
+          "description": "Display label in the sort dropdown."
+        }
+      },
+      "required": ["field"],
+      "additionalProperties": false
+    },
+
+    "summary_field": {
+      "type": "object",
+      "description": "A field in the summary bar with an aggregate function.",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Field name to aggregate."
+        },
+        "function": {
+          "type": "string",
+          "description": "SQL aggregate function to apply.",
+          "enum": ["sum", "avg", "count", "min", "max"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Label displayed in the summary bar."
+        },
+        "renderer": {
+          "type": "string",
+          "description": "Display renderer for the aggregate value."
+        },
+        "options": {
+          "type": "object",
+          "description": "Options passed to the renderer."
+        }
+      },
+      "required": ["field", "function"],
+      "additionalProperties": false
+    },
+
+    "summary_config": {
+      "type": "object",
+      "description": "Configuration for the summary bar displayed below the index content.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable the summary bar."
+        },
+        "fields": {
+          "type": "array",
+          "description": "Fields with aggregate functions to display in the summary bar.",
+          "items": { "$ref": "#/$defs/summary_field" }
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "index_config": {
+      "type": "object",
+      "description": "Configuration for the index (list) page.",
+      "properties": {
+        "render_with": {
+          "type": "string",
+          "description": "Replace the entire index content area with a custom host-app partial. When set, 'layout' is ignored. The search/sort/scope pipeline still runs.",
+          "examples": ["analytics/dashboard", "reports/custom_index"]
+        },
+        "layout": {
+          "type": "string",
+          "description": "Index page layout mode. 'table' (default), 'tiles' for card grid, 'tree' for tree hierarchy, 'kanban' for column-based pipeline view. Ignored when 'render_with' is set.",
+          "enum": ["table", "tiles", "tree", "kanban"]
+        },
+        "reorderable": {
+          "type": "boolean",
+          "description": "Enable drag-and-drop row reordering. Requires positioning on the model."
+        },
+        "description": {
+          "type": "string",
+          "description": "Explanatory text shown above the table."
+        },
+        "default_view": {
+          "type": "string",
+          "description": "Deprecated: use view groups instead.",
+          "default": "table",
+          "examples": ["table", "card", "tree"]
+        },
+        "views_available": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Deprecated: use view groups instead.",
+          "examples": [["table", "card"]]
+        },
+        "default_sort": { "$ref": "#/$defs/default_sort" },
+        "per_page": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of records per page (Kaminari pagination).",
+          "default": 25,
+          "examples": [10, 25, 50, 100]
+        },
+        "per_page_options": {
+          "type": "array",
+          "items": { "type": "integer", "minimum": 1 },
+          "description": "Selectable page sizes shown in a dropdown near pagination.",
+          "examples": [[10, 25, 50, 100]]
+        },
+        "show_record_count": {
+          "type": "boolean",
+          "description": "Show record count text in pagination footer (default: true)."
+        },
+        "pagination_ends": {
+          "type": "boolean",
+          "description": "Show First/Last page links in pagination (default: from global config, false)."
+        },
+        "table_columns": {
+          "type": "array",
+          "description": "Columns displayed in the index table.",
+          "items": { "$ref": "#/$defs/table_column" }
+        },
+        "tile": { "$ref": "#/$defs/tile_config" },
+        "card": { "$ref": "#/$defs/card_config" },
+        "kanban": { "$ref": "#/$defs/kanban_config" },
+        "sort_fields": {
+          "type": "array",
+          "description": "Fields available in the sort dropdown (auto-derived for tiles if omitted).",
+          "items": { "$ref": "#/$defs/sort_field_entry" }
+        },
+        "summary": { "$ref": "#/$defs/summary_config" },
+        "query_mode": {
+          "type": "string",
+          "description": "Query mode for the index. 'grouped' enables GROUP BY aggregation.",
+          "enum": ["grouped"]
+        },
+        "group_by": {
+          "type": "array",
+          "description": "Fields to GROUP BY in grouped query mode. Each item is a field name or an object with field and period (for date truncation).",
+          "items": {
+            "oneOf": [
+              { "type": "string" },
+              {
+                "type": "object",
+                "properties": {
+                  "field": { "type": "string" },
+                  "period": { "type": "string", "enum": ["day", "week", "month", "quarter", "year"] }
+                },
+                "required": ["field"],
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "having": {
+          "type": "array",
+          "description": "HAVING conditions for grouped queries.",
+          "items": { "type": "object" }
+        },
+        "limit": {
+          "type": "integer",
+          "description": "Maximum number of group rows to return.",
+          "minimum": 1
+        },
+        "row_click": {
+          "description": "Action triggered when clicking a table row. String for simple actions, object for grouped query filter navigation.",
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "object",
+              "properties": {
+                "mode": { "type": "string", "enum": ["filter"] },
+                "target": { "type": "string", "description": "Target presenter slug to navigate to with group filters applied." }
+              },
+              "required": ["mode", "target"],
+              "additionalProperties": false
+            }
+          ],
+          "examples": ["show", "edit", { "mode": "filter", "target": "features" }]
+        },
+        "empty_message": {
+          "type": "string",
+          "description": "Message shown when no records match the current filters.",
+          "examples": ["No employees found."]
+        },
+        "actions_position": {
+          "type": "string",
+          "description": "Position of action buttons in table rows.",
+          "examples": ["right", "left", "dropdown"]
+        },
+        "includes": {
+          "type": "array",
+          "description": "Manual eager loading hints (AR includes). Auto-detected from presenter fields if omitted.",
+          "examples": [["department", "manager"]]
+        },
+        "eager_load": {
+          "type": "array",
+          "description": "Manual eager_load hints (uses LEFT OUTER JOIN). Use for associations that must always be loaded.",
+          "examples": [["company"]]
+        },
+        "tree_view": {
+          "type": "boolean",
+          "description": "Deprecated: use layout: tree instead. Enable tree-structured index view."
+        },
+        "default_expanded": {
+          "description": "For tree layout: how many levels to expand by default. 0 means all collapsed, 'all' means fully expanded.",
+          "oneOf": [
+            { "type": "integer", "minimum": 0 },
+            { "type": "string", "const": "all" }
+          ],
+          "default": 0,
+          "examples": [0, 2, "all"]
+        },
+        "reparentable": {
+          "type": "boolean",
+          "description": "For tree layout: allow drag-and-drop reparenting of tree nodes."
+        },
+        "item_classes": {
+          "type": "array",
+          "description": "Conditional CSS classes applied to each row/card element based on record field values. All matching rules accumulate.",
+          "items": { "$ref": "#/$defs/item_class_rule" }
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "show_config": {
+      "type": "object",
+      "description": "Configuration for the show (detail) page.",
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Explanatory text shown at the top of the show page."
+        },
+        "render_with": {
+          "type": "string",
+          "description": "Replace the entire show content area with a custom host-app partial. Ignored in dialog and composite page contexts.",
+          "examples": ["products/custom_show", "reports/detail_view"]
+        },
+        "copy_url": {
+          "type": "boolean",
+          "description": "Show a 'Copy URL' button in the toolbar for sharing direct links to this record."
+        },
+        "layout": {
+          "type": "array",
+          "description": "Ordered list of sections displayed on the show page.",
+          "items": { "$ref": "#/$defs/show_section" }
+        },
+        "includes": {
+          "type": "array",
+          "description": "Manual eager loading hints for the show page."
+        },
+        "eager_load": {
+          "type": "array",
+          "description": "Manual eager_load hints for the show page."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "form_config": {
+      "type": "object",
+      "description": "Configuration for the new/edit form.",
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Explanatory text shown above the form."
+        },
+        "layout": {
+          "type": "string",
+          "description": "Form layout mode.",
+          "examples": ["stacked", "inline"]
+        },
+        "sections": {
+          "type": "array",
+          "description": "Ordered list of form sections, each containing input fields.",
+          "items": { "$ref": "#/$defs/form_section" }
+        },
+        "includes": {
+          "type": "array",
+          "description": "Manual eager loading hints for the edit form (e.g., for association selects)."
+        },
+        "eager_load": {
+          "type": "array",
+          "description": "Manual eager_load hints for the edit form."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "search_config": {
+      "type": "object",
+      "description": "Configuration for quick search, predefined filters, and advanced filter builder.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable the search box on the index page."
+        },
+        "searchable_fields": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Fields included in quick search (text search across multiple fields).",
+          "examples": [["name", "email", "department.name"]]
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "Placeholder text in the search input.",
+          "examples": ["Search employees..."]
+        },
+        "auto_search": {
+          "type": "boolean",
+          "description": "Trigger search automatically as the user types (with debounce) instead of requiring Enter."
+        },
+        "debounce_ms": {
+          "type": "integer",
+          "description": "Debounce delay in milliseconds for auto_search.",
+          "examples": [300, 500]
+        },
+        "min_query_length": {
+          "type": "integer",
+          "description": "Minimum number of characters before auto_search triggers.",
+          "examples": [2, 3]
+        },
+        "default_scope": {
+          "type": "string",
+          "description": "Named scope applied to all search queries as a base filter.",
+          "examples": ["active", "visible"]
+        },
+        "predefined_filters": {
+          "type": "array",
+          "description": "Filter tabs shown above the search results.",
+          "items": { "$ref": "#/$defs/search_filter" }
+        },
+        "columns": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of grid columns for search parameter layout. Default: 1 (stacked)."
+        },
+        "responsive": {
+          "type": "object",
+          "description": "Responsive column overrides per breakpoint.",
+          "properties": {
+            "mobile": {
+              "type": "object",
+              "properties": { "columns": { "type": "integer", "minimum": 1 } },
+              "additionalProperties": false
+            },
+            "tablet": {
+              "type": "object",
+              "properties": { "columns": { "type": "integer", "minimum": 1 } },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "parameters": {
+          "type": "array",
+          "description": "Typed filter controls rendered in the search toolbar (dropdowns, toggles, ranges).",
+          "items": { "$ref": "#/$defs/search_parameter" }
+        },
+        "advanced_filter": { "$ref": "#/$defs/advanced_filter_config" }
+      },
+      "additionalProperties": false
+    },
+
+    "advanced_filter_config": {
+      "type": "object",
+      "description": "Configuration for the visual filter builder UI that lets users construct complex queries with multiple conditions.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Show the advanced filter builder button on the index page."
+        },
+        "max_conditions": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of filter conditions a user can add.",
+          "default": 10
+        },
+        "max_association_depth": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 5,
+          "description": "Maximum depth for filtering on associated model fields (e.g., 1 = direct associations only).",
+          "default": 1
+        },
+        "default_combinator": {
+          "type": "string",
+          "description": "Default logical operator between conditions.",
+          "enum": ["and", "or"],
+          "default": "and"
+        },
+        "allow_or_groups": {
+          "type": "boolean",
+          "description": "Allow users to create OR groups within the filter builder.",
+          "default": true
+        },
+        "query_language": {
+          "type": "boolean",
+          "description": "Enable the text-based query language input alongside the visual builder.",
+          "default": false
+        },
+        "max_nesting_depth": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10,
+          "description": "Maximum nesting depth for condition groups.",
+          "default": 2
+        },
+        "filterable_fields": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Whitelist of fields available in the filter builder. If omitted, all readable fields are available.",
+          "examples": [["name", "status", "department_id", "hire_date"]]
+        },
+        "filterable_fields_except": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Blacklist of fields excluded from the filter builder.",
+          "examples": [["internal_notes", "password_digest"]]
+        },
+        "field_options": {
+          "type": "object",
+          "description": "Per-field customization of available filter operators. Keys are field names.",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "operators": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "List of operators available for this field.",
+                "examples": [["eq", "not_eq", "in", "not_in"]]
+              }
+            },
+            "additionalProperties": false
+          },
+          "examples": [{ "status": { "operators": ["eq", "not_eq", "in"] } }]
+        },
+        "presets": {
+          "type": "array",
+          "description": "Pre-defined filter combinations that users can apply with one click.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Preset identifier."
+              },
+              "label": {
+                "type": "string",
+                "description": "Display label for the preset button."
+              },
+              "conditions": {
+                "type": "array",
+                "items": { "type": "object" },
+                "description": "Array of condition objects ({field, operator, value}) applied by this preset."
+              }
+            },
+            "required": ["name"]
+          },
+          "examples": [[{ "name": "active_this_month", "label": "Active This Month", "conditions": [{ "field": "status", "operator": "eq", "value": "active" }] }]]
+        },
+        "custom_filters": {
+          "type": "array",
+          "description": "Custom filter widgets implemented as filter_* methods on the model.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Filter name matching a filter_<name> method on the model."
+              },
+              "label": {
+                "type": "string",
+                "description": "Display label in the filter UI."
+              },
+              "type": {
+                "type": "string",
+                "description": "Input type for the custom filter widget.",
+                "examples": ["text", "select", "date_range"]
+              }
+            },
+            "required": ["name"]
+          }
+        },
+        "saved_filters": { "$ref": "#/$defs/saved_filters_config" }
+      },
+      "additionalProperties": false
+    },
+
+    "saved_filters_config": {
+      "type": "object",
+      "description": "Configuration for user-saveable filter presets. Requires the saved_filters generator to create the backing model.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable the saved filters feature for this presenter."
+        },
+        "display": {
+          "type": "string",
+          "description": "How saved filters are displayed in the UI.",
+          "enum": ["inline", "dropdown", "sidebar"],
+          "default": "inline"
+        },
+        "max_per_user": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of personal saved filters per user.",
+          "default": 50
+        },
+        "max_per_role": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of role-shared saved filters.",
+          "default": 20
+        },
+        "max_global": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of globally visible saved filters.",
+          "default": 30
+        },
+        "max_visible_pinned": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of pinned filters shown inline (overflow goes to dropdown).",
+          "default": 5
+        },
+        "allow_pinning": {
+          "type": "boolean",
+          "description": "Allow users to pin saved filters for quick access.",
+          "default": true
+        },
+        "allow_default": {
+          "type": "boolean",
+          "description": "Allow users to set a saved filter as their personal default.",
+          "default": true
+        },
+        "visibility_options": {
+          "type": "array",
+          "description": "Which visibility levels are available when saving a filter.",
+          "items": { "type": "string", "enum": ["personal", "role", "global", "group"] },
+          "default": ["personal", "role", "global"],
+          "examples": [["personal", "role", "global"], ["personal", "group"]]
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "actions_config": {
+      "type": "object",
+      "description": "Action buttons grouped by context: collection (index page toolbar), single (per-record row actions), batch (multi-select actions), form (form submit buttons).",
+      "properties": {
+        "collection": {
+          "type": "array",
+          "description": "Actions shown in the index page toolbar (e.g., 'Create New').",
+          "items": { "$ref": "#/$defs/action" }
+        },
+        "single": {
+          "type": "array",
+          "description": "Actions shown per record row on the index page and on the show page (e.g., 'Show', 'Edit', 'Delete').",
+          "items": { "$ref": "#/$defs/action" }
+        },
+        "batch": {
+          "type": "array",
+          "description": "Actions available when multiple records are selected (e.g., 'Delete Selected', 'Export').",
+          "items": { "$ref": "#/$defs/action" }
+        },
+        "form": {
+          "type": "array",
+          "description": "Submit buttons rendered in the form footer. When absent, defaults to [save (primary), cancel (secondary)]. When present, only the listed actions appear.",
+          "items": { "$ref": "#/$defs/form_action" }
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "export_config": {
+      "type": "object",
+      "description": "Export configuration. When present, enables CSV/XLSX export for this presenter.",
+      "properties": {
+        "formats": {
+          "type": "array",
+          "description": "Allowed export formats.",
+          "items": { "type": "string", "enum": ["csv", "xlsx"] },
+          "default": ["csv"],
+          "examples": [["csv", "xlsx"]]
+        },
+        "max_records": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum records per export. Default: 10000.",
+          "default": 10000
+        },
+        "save_history": {
+          "type": "boolean",
+          "description": "Persist each export in the export_log model. Requires the lcp_ruby:export generator.",
+          "default": false
+        },
+        "fields": {
+          "type": "array",
+          "description": "Field whitelist (ceiling). Only these fields can be selected for export. When omitted, all readable fields are available.",
+          "items": { "type": "string" },
+          "examples": [["name", "email", "department_id"]]
+        },
+        "csv_delimiter": {
+          "type": "string",
+          "description": "CSV column delimiter.",
+          "default": ","
+        }
+      },
+      "additionalProperties": false,
+      "examples": [{ "formats": ["csv", "xlsx"], "max_records": 5000 }]
+    },
+
+    "import_config": {
+      "type": "object",
+      "description": "Import configuration. When present, enables CSV/XLSX import for this presenter.",
+      "properties": {
+        "formats": {
+          "type": "array",
+          "description": "Allowed import formats.",
+          "items": { "type": "string", "enum": ["csv", "xlsx"] },
+          "default": ["csv"],
+          "examples": [["csv", "xlsx"]]
+        },
+        "max_rows": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum rows per import. Default: 10000.",
+          "default": 10000
+        },
+        "max_file_size": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum file size in bytes. Default: 10485760 (10 MiB).",
+          "default": 10485760
+        },
+        "csv_delimiter": {
+          "type": "string",
+          "description": "CSV column delimiter.",
+          "default": ","
+        },
+        "csv_encoding": {
+          "type": "string",
+          "description": "Expected file encoding. 'auto' detects encoding automatically.",
+          "default": "auto"
+        },
+        "parsing": {
+          "type": "object",
+          "description": "Type coercion rules for imported values.",
+          "properties": {
+            "date_format": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Date parsing format(s). Tried in order.",
+              "examples": ["%d.%m.%Y", ["%d.%m.%Y", "%Y-%m-%d"]]
+            },
+            "datetime_format": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Datetime parsing format(s)."
+            },
+            "decimal_separator": {
+              "type": "string",
+              "description": "Decimal separator for number parsing.",
+              "examples": [",", "."]
+            },
+            "boolean_true": {
+              "type": "array",
+              "description": "Values recognized as true.",
+              "items": {},
+              "examples": [["true", "yes", "1", "ano"]]
+            },
+            "boolean_false": {
+              "type": "array",
+              "description": "Values recognized as false.",
+              "items": {},
+              "examples": [["false", "no", "0", "ne"]]
+            }
+          },
+          "additionalProperties": false
+        },
+        "nested_associations": {
+          "type": "array",
+          "description": "Whitelist of has_one association names that can be imported via column prefixes (e.g., hire_detail.start_date).",
+          "items": { "type": "string" },
+          "examples": [["hire_detail", "departure_detail"]]
+        },
+        "nested_blank_strategy": {
+          "type": "string",
+          "description": "How to handle blank nested association columns. 'null' sets fields to nil, 'skip' leaves them unchanged.",
+          "enum": ["null", "skip"],
+          "default": "null"
+        }
+      },
+      "additionalProperties": false,
+      "examples": [{ "formats": ["csv", "xlsx"], "max_rows": 1000, "nested_associations": ["hire_detail"] }]
+    }
+  }
+}