lcp 0.1.0

data/docs/reference/pages.md

@@ -0,0 +1,1375 @@
+# Pages Reference
+
+Pages are the top-level layout unit in LCP Ruby. Every routable URL maps to a page, which contains one or more **zones** — regions that display either a presenter or a widget.
+
+Pages are defined in `config/lcp_ruby/pages/` as YAML files with the root key `page:`.
+
+## Page Attributes
+
+| Attribute | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `name` | string | yes | — | Unique page identifier. Used in view group references and dialog targets. |
+| `slug` | string | no | — | URL slug for routing. Pages without a slug are only accessible as dialog targets. |
+| `model` | string | no | — | Associated model name. Standalone dashboard pages may omit this. |
+| `layout` | string | no | `semantic` | `semantic` (named areas) or `grid` (CSS grid with explicit positions). |
+| `title_key` | string | no | — | i18n key for page title. Falls back to humanized name. |
+| `index_presenter` | string | no | — | Presenter to use for the index action. Useful for composite pages where the main zone presenter (show-only) differs from the index presenter. Must have index columns defined and use the same model. |
+| `dialog` | object | no | — | Dialog rendering config. When present, the page can be rendered in a modal. |
+| `zones` | array | yes | — | One or more zone definitions (min 1). |
+
+## Dialog Configuration
+
+The `dialog:` key controls how the page renders as a modal.
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `size` | string | `medium` | `small`, `medium`, `large`, or `fullscreen`. |
+| `closable` | boolean | `true` | Whether clicking outside or pressing Escape closes the dialog. |
+| `title_key` | string | — | i18n key for the dialog title bar. |
+
+```yaml
+page:
+  name: quick_create_order
+  dialog:
+    size: large
+    closable: false
+    title_key: lcp_ruby.dialogs.quick_create
+  zones:
+    - name: main
+      presenter: order_create_form
+```
+
+## Zone Attributes
+
+Each zone represents a content region within the page.
+
+| Attribute | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `name` | string | yes | — | Unique identifier within the page. |
+| `type` | string | no | `presenter` | `presenter`, `widget`, or `custom`. |
+| `presenter` | string | conditional | — | Presenter name. Required for presenter zones. |
+| `area` | string | no | `main` | Named area for semantic layout (`main`, `tabs`, `sidebar`, `below`). |
+| `widget` | object | conditional | — | Widget config. Required for widget zones. |
+| `position` | object | no | — | Grid positioning (`row`, `col`, `width`, `height`). |
+| `scope` | string | no | — | Named scope to apply to the zone's data query. |
+| `default_scope` | string | no | — | Named scope applied before `scope`. Both are cumulative. |
+| `limit` | integer | no | — | Maximum records to display (min 1). |
+| `visible_when` | object | no | — | Conditional visibility (role shortcut or condition object). |
+| `width` | integer | no | — | CSS grid column ratio for semantic layout (1-12 scale). Controls main/sidebar proportions. |
+| `filters` | string | no | `quick` for tabs, `none` otherwise | Filter mode: `full`, `quick`, or `none`. Widget zones must use `none`. |
+| `record_click` | string | no | `navigate` | Row click behavior: `navigate` (full-page), `dialog` (opens in dialog), `none` (no click). |
+| `submit_redirect` | string | no | — | After form submit, redirect target. Only `self` supported (stay on composite page). Must be `main` area, presenter zone only. |
+| `record_source` | object/string | no | — | Load a single record by ID from a URL parameter. Use `selection` (string) for master-detail. Mutually exclusive with `scope_context`. |
+| `selection` | string | no | — | Enables row selection in sidebar. Only `single` is supported. Marks the zone as the selection zone for master-detail layouts. Only valid on presenter zones in `sidebar` area. |
+
+### Presenter Zones
+
+Render a full presenter (index table, show page, form). The presenter must exist in `config/lcp_ruby/presenters/`.
+
+```yaml
+zones:
+  - name: recent_tasks
+    presenter: dashboard_tasks
+    scope: recent
+    limit: 5
+```
+
+### Widget Zones
+
+Render a standalone widget. Set `type: widget` and provide the `widget:` config.
+
+### Custom Zones
+
+Render a host-app partial inside a zone. Set `type: custom` and provide the `partial:` path. Custom zones delegate rendering entirely to the host app while participating in the composite page layout (areas, tabs, visibility).
+
+| Attribute | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `partial` | string | yes | — | Host-app partial path (e.g., `"employees/gantt_chart"`). |
+| `model` | string | no | page's primary model | Model name for `scoped_records`. Enables cross-model zones. |
+| `eager` | boolean | no | `false` | When `true`, rendered inline (no Turbo Frame). Solves inline `<script>` issues. |
+| `apply_scope_context` | boolean | no | `true` | When `true`, builds `scoped_records` from `scope_context`. When `false`, only `scope_context_values` hash is passed. |
+| `scope_context` | object | no | — | Dynamic references resolved before render (e.g., `employee_id: ":record.id"`). |
+
+**Supported attributes:** `area`, `label_key`, `visible_when`, `width`, `scope_context`, `depends_on` — work as for other zone types.
+
+**Not applicable (rejected at boot):** `scope`, `default_scope`, `filters`, `record_click`, `selection`, `record_source`, `submit_redirect`.
+
+**Authorization:** Custom zones have no presenter, so only `visible_when` controls visibility. For fine-grained auth, check `evaluator.can?` inside the partial.
+
+**Turbo Frames:** Lazy-loaded custom zones (default) are rendered inside Turbo Frames. Turbo does not execute inline `<script>` tags in frame payloads. Use Stimulus controllers (`data-controller`) for JS initialization, or set `eager: true` for inline rendering.
+
+```yaml
+zones:
+  - name: project_timeline
+    type: custom
+    partial: "employees/gantt_chart"
+    area: tabs
+    label_key: lcp_ruby.pages.employee_detail.tabs.timeline
+    scope_context:
+      employee_id: ":record.id"
+```
+
+The partial receives: `record`, `presenter`, `evaluator`, `zone`, `scope_context_values`, `scoped_records`, `selection_id`, `current_user`, `page_definition`, `params`.
+
+See also [Rendering Extension Points](../guides/rendering-extension-points.md).
+
+## Widget Types
+
+### kpi_card
+
+Displays an aggregate value (count, sum, avg, min, max) over a model's records, or a Prometheus metric value via `value_source`. Two mutually exclusive modes: **model-based** (`model` + `aggregate`) or **metric-based** (`value_source`).
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | yes | Must be `kpi_card`. |
+| `model` | string | yes* | Model to aggregate over. *Required for model-based KPI; must be omitted when `value_source` is used. |
+| `aggregate` | string | yes* | `count`, `sum`, `avg`, `min`, or `max`. *Required for model-based KPI; must be omitted when `value_source` is used. |
+| `aggregate_field` | string | no | Field to aggregate. Required for `sum`/`avg`/`min`/`max`. Defaults to `id` for `count`. |
+| `value_source` | object | yes* | Read value from Prometheus metric. *Required for metric-based KPI; mutually exclusive with `model`+`aggregate`. |
+| `format` | string | no | Display format (e.g., `currency`, `number`, `percent`). |
+| `icon` | string | no | [Lucide](https://lucide.dev/icons/) icon name (kebab-case, e.g. `dollar-sign`, `activity`). The engine swaps it for an inline SVG client-side. |
+| `link_to` | string | no | Page slug to navigate to on click. |
+| `label_key` | string | no | i18n key for the card label. |
+| `compare_scope` | string | no | Named scope for the comparison period. When set, displays a trend indicator (percentage change) next to the KPI value. |
+
+**`value_source` object:**
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | yes | Must be `metric`. |
+| `name` | string | yes | Prometheus metric name (e.g., `lcp_ruby_requests_total`). |
+| `labels` | object | no | Label filter to select a specific time series. |
+
+```yaml
+# Model-based KPI card
+- name: total_revenue
+  type: widget
+  widget:
+    type: kpi_card
+    model: order
+    aggregate: sum
+    aggregate_field: total_amount
+    format: currency
+    icon: dollar-sign
+    link_to: orders
+    label_key: lcp_ruby.dashboard.revenue
+  position: { row: 1, col: 1, width: 4, height: 1 }
+```
+
+```yaml
+# Metric-based KPI card (reads from Prometheus)
+- name: total_requests
+  type: widget
+  widget:
+    type: kpi_card
+    value_source:
+      type: metric
+      name: lcp_ruby_requests_total
+    icon: activity
+    label_key: lcp_ruby.monitoring.total_requests
+  position: { row: 1, col: 5, width: 4, height: 1 }
+```
+
+### text
+
+Displays translated static content.
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | yes | Must be `text`. |
+| `content_key` | string | yes | i18n key for the text content. |
+
+```yaml
+- name: welcome
+  type: widget
+  widget:
+    type: text
+    content_key: lcp_ruby.dashboard.welcome
+  position: { row: 2, col: 1, width: 12, height: 1 }
+```
+
+### list
+
+Displays recent records from a model.
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | yes | Must be `list`. |
+| `model` | string | yes | Model to list records from. |
+| `link_to` | string | no | Page slug for the "view all" link. |
+| `label_key` | string | no | i18n key for the list header. |
+
+```yaml
+- name: recent_orders
+  type: widget
+  widget:
+    type: list
+    model: order
+    link_to: orders
+    label_key: lcp_ruby.dashboard.recent_orders
+  scope: recent
+  limit: 5
+```
+
+### chart
+
+Displays a chart visualization. Requires the `chartkick` gem (optional dependency). Add `gem "chartkick"` to the host app Gemfile and declare the JS assets in `app/assets/config/manifest.js` (`//= link Chart.bundle.js` and `//= link chartkick.js`). See the [Dashboards Guide](../guides/dashboards.md#chart) for full setup instructions.
+
+Charts support a single series (inline `aggregate`/`group_by`) or an explicit `series:` array for multi-series comparisons. The default color palette is the Okabe-Ito colorblind-safe 8-color set (Wong, 2011); per-series and chart-level overrides are supported.
+
+#### Chart-level attributes
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | yes | Must be `chart`. |
+| `chart_type` | string | yes | `line`, `bar` (horizontal), `column` (vertical), `pie`, `donut`, or `area`. |
+| `model` | string | yes | Model to query. |
+| `group_by` | string | yes | Field to group by. Inherited default for each series unless overridden. |
+| `group_period` | string | no | Time grouping period for date/datetime `group_by`: `day`, `week`, `month`, `quarter`, `year`. |
+| `aggregate` | string | yes | `count`, `sum`, `avg`, `min`, `max`. Inherited default for each series. |
+| `aggregate_field` | string | no | Field for `sum`/`avg`/`min`/`max`. Required when at least one effective series ends up with aggregate ≠ count. |
+| `scope` | string | no | Named scope on the model. Applied cumulatively with each series' own `scope:`. |
+| `series` | array | no | Multi-series array (see [Series attributes](#series-attributes) below). When absent, top-level keys define an implicit single series. |
+| `stacked` | boolean | no | Stack series on the Y axis. Legal for `column`/`bar`/`line`/`area`; hard error for `pie`/`donut`. |
+| `legend` | boolean / string | no | `auto` (default), `true`, `false`, `top`, `bottom`, `left`, or `right`. `auto` shows the legend for multi-series and all pie/donut, hides it for single-series non-pie. |
+| `colors` | array of strings | no | Chart-level color list. For `column`/`bar`/`line`/`area`, indexes by series; per-series `color:` wins on collision. For `pie`/`donut`, colors slices by category position. |
+| `min`, `max` | number | no | Y axis bounds. Not used for `pie`/`donut`. |
+| `xtitle` | string | no | X axis title (literal). |
+| `xtitle_key` | string | no | i18n key for X axis title. |
+| `ytitle` | string | no | Y axis title (literal). |
+| `ytitle_key` | string | no | i18n key for Y axis title. |
+| `empty` | string | no | Message shown when ALL series have zero rows (literal). |
+| `empty_key` | string | no | i18n key for empty-state message. Falls back to `lcp_ruby.charts.no_data`. |
+| `prefix`, `suffix` | string | no | Value prefix/suffix (e.g. `prefix: "€"`, `suffix: "%"`). |
+| `precision` | integer | no | Decimal places for values. |
+| `thousands` | string | no | Thousands separator (e.g. `" "` for cs-CZ). |
+| `points` | boolean | no | Line/area dot markers. |
+| `curve` | boolean | no | Line smoothing for line/area (default `true`). |
+| `discrete` | boolean | no | Treat X axis as categorical (not numeric). |
+| `sort` | string | no | `asc` (default for date `group_period`), `desc`, `none`, `value_asc`, `value_desc`. For multi-series, `value_*` sorts by per-category sum across all series. |
+| `download` | boolean | no | Render Chartkick's PNG download button. |
+| `height` | string | no | CSS height (e.g. `"320px"`). |
+| `library` | object | no | Raw Chart.js options deep-merged over platform defaults. Escape hatch — has last word. |
+| `label` | string | no | Chart title (literal). |
+| `label_key` | string | no | i18n key for the chart title. |
+| `link_to` | string | no | Page slug for the "view all" link. |
+
+#### Series attributes
+
+Each element of the chart-level `series:` array supports:
+
+| Attribute | Type | Required | Inherited | Description |
+|-----------|------|----------|-----------|-------------|
+| `name` | string | no | — | Legend label (literal). Defaults to `Series N` (1-indexed) when both `name` and `name_key` are absent. |
+| `name_key` | string | no | — | i18n key for the legend label. |
+| `color` | string | no | from `colors[index]` or palette | CSS color string (`#hex`, named, `rgb()`, `hsl()`, `var(--…)`). |
+| `aggregate` | string | no | chart-level | Per-series aggregate. |
+| `aggregate_field` | string | no | chart-level | Required when the effective aggregate is not `count`. |
+| `group_by` | string | no | chart-level | Per-series group field (own-table columns only in v1). |
+| `group_period` | string | no | chart-level | Per-series date period. |
+| `scope` | string | no | — | Named scope on the model. Applied on top of the chart-level `scope:`. |
+
+#### Examples
+
+Single-series line chart (existing form, unchanged):
+
+```yaml
+- name: orders_by_month
+  type: widget
+  widget:
+    type: chart
+    chart_type: line
+    model: order
+    group_by: created_at
+    group_period: month
+    aggregate: count
+    label_key: lcp_ruby.dashboard.orders_by_month
+  position: { row: 2, col: 1, width: 8, height: 2 }
+```
+
+Multi-series column chart with different group fields:
+
+```yaml
+- name: hires_vs_departures
+  type: widget
+  widget:
+    type: chart
+    chart_type: column
+    model: employee
+    group_by: hire_date
+    group_period: year
+    aggregate: count
+    legend: bottom
+    min: 0
+    ytitle: "Number of employees"
+    series:
+      - name: Hires
+        color: "#0072B2"
+        scope: hired_in_year
+      - name: Departures
+        color: "#999999"
+        scope: departed_in_year
+        group_by: departure_date
+  position: { row: 1, col: 1, width: 8, height: 2 }
+```
+
+Stacked column chart with localized series names:
+
+```yaml
+- name: turnover_stacked
+  type: widget
+  widget:
+    type: chart
+    chart_type: column
+    model: employee
+    group_by: departure_date
+    group_period: month
+    aggregate: count
+    stacked: true
+    legend: bottom
+    min: 0
+    ytitle_key: lcp_ruby.hr.charts.departures_per_month
+    series:
+      - name_key: lcp_ruby.hr.charts.series.managed
+        color: "#56B4E9"
+        scope: managed_departures
+      - name_key: lcp_ruby.hr.charts.series.unmanaged
+        color: "#E69F00"
+        scope: unmanaged_departures
+```
+
+Single-series area chart with value formatting:
+
+```yaml
+- name: monthly_revenue
+  type: widget
+  widget:
+    type: chart
+    chart_type: area
+    model: invoice
+    group_by: issued_at
+    group_period: month
+    aggregate: sum
+    aggregate_field: amount
+    prefix: "€"
+    thousands: " "
+    precision: 0
+    min: 0
+    ytitle_key: lcp_ruby.finance.charts.revenue
+    label_key: lcp_ruby.finance.charts.monthly_revenue
+```
+
+For the full feature specification including scope composition, payload shapes, validation rules, and the `library:` escape hatch, see [docs/design/chart_widget_multi_series.md](../design/chart_widget_multi_series.md).
+
+### workflow_graph
+
+Renders a Mermaid.js `stateDiagram-v2` diagram from the model's workflow definition. Shows all states and transitions including branches, with the current record's state highlighted.
+
+| Attribute | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `type` | string | yes | — | Must be `workflow_graph`. |
+| `model` | string | no | page model | Model name to resolve the workflow. Defaults to the page's model. |
+| `direction` | string | no | `LR` | Mermaid direction: `LR` (left-right) or `TD` (top-down). |
+| `show_transition_labels` | boolean | no | `true` | Show transition names on edges. |
+| `show_roles` | boolean | no | `false` | Show allowed roles on transition edges. |
+| `show_guards` | boolean | no | `false` | Show lock indicator on guarded transitions. |
+| `show_audit_trail` | boolean | no | `false` | Highlight the path this record took (requires `audit_log: true` on the workflow). |
+| `highlight_available` | boolean | no | `false` | Highlight transitions available to the current user from the current state. |
+| `collapse_universal` | boolean | no | `true` | Collapse transitions that originate from all states into a note on the target state instead of drawing individual edges. Reduces clutter from "reset" style transitions. |
+| `label_key` | string | no | — | i18n key for the widget label. |
+
+```yaml
+# Composite page with workflow graph in sidebar
+page:
+  name: purchase_order_show
+  model: purchase_order
+  layout: composite
+
+  zones:
+    - name: details
+      area: main
+      type: presenter
+      presenter: purchase_order
+
+    - name: workflow
+      area: sidebar
+      type: widget
+      widget:
+        type: workflow_graph
+        show_audit_trail: true
+        highlight_available: true
+        direction: LR
+        label_key: lcp_ruby.widgets.workflow_graph.title
+```
+
+**Mermaid.js dependency:** The widget loads Mermaid.js via a `<script>` tag. Configure the source with `config.mermaid_source` — see [Engine Configuration](engine-configuration.md#mermaid_source).
+
+**Audit trail overlay:** When `show_audit_trail: true`, traversed edges are annotated with step numbers (e.g., `#1`, `#2`), showing the actual path the record took through the workflow. Requires the workflow audit log model to be set up.
+
+## Grid Positioning
+
+Grid layout pages use a 12-column CSS grid. Each zone specifies its position:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `row` | integer | Starting grid row (1-based). |
+| `col` | integer | Starting grid column (1-12). |
+| `width` | integer | Number of columns to span. |
+| `height` | integer | Number of rows to span. |
+
+All values must be positive integers (>= 1).
+
+```yaml
+page:
+  name: main_dashboard
+  layout: grid
+  zones:
+    - name: kpi_1
+      type: widget
+      widget: { type: kpi_card, model: order, aggregate: count }
+      position: { row: 1, col: 1, width: 4, height: 1 }
+    - name: kpi_2
+      type: widget
+      widget: { type: kpi_card, model: order, aggregate: sum, aggregate_field: total }
+      position: { row: 1, col: 5, width: 4, height: 1 }
+    - name: main_content
+      presenter: orders
+      position: { row: 2, col: 1, width: 12, height: 3 }
+```
+
+## Auto-Page Creation
+
+Presenters that are not explicitly claimed by any page zone automatically get a simple page created at boot:
+
+- Page name = presenter name
+- Single presenter zone with `area: main`
+- Slug inherited from the presenter
+- `auto_generated: true` flag (skipped by schema validation)
+
+This means every presenter is accessible without explicit page YAML. Explicit pages override auto-generated ones by claiming the presenter in a zone.
+
+## Slug Ownership
+
+- Explicit pages with a `slug:` take priority.
+- Auto-generated pages inherit the presenter's slug.
+- Duplicate slugs across pages produce a validation error.
+
+## Standalone Pages
+
+Pages without a `model:` are standalone — they are not tied to any single model. Standalone dashboard pages can contain widget zones referencing multiple different models.
+
+```yaml
+page:
+  name: main_dashboard
+  slug: dashboard
+  layout: grid
+  zones:
+    - name: orders_count
+      type: widget
+      widget: { type: kpi_card, model: order, aggregate: count }
+      position: { row: 1, col: 1, width: 6, height: 1 }
+    - name: tasks_count
+      type: widget
+      widget: { type: kpi_card, model: task, aggregate: count }
+      position: { row: 1, col: 7, width: 6, height: 1 }
+```
+
+## Dialog-Only Pages
+
+Pages with `dialog:` config but no `slug:` are dialog-only — they cannot be navigated to directly but can be opened as modal dialogs by actions.
+
+```yaml
+page:
+  name: feedback_form
+  dialog:
+    size: medium
+    closable: true
+    title_key: lcp_ruby.dialogs.feedback
+  zones:
+    - name: main
+      presenter: feedback_create
+```
+
+## Composite Pages (Semantic Layout)
+
+Composite pages combine multiple zones into a record-bound layout with named areas: `main`, `tabs`, `sidebar`, and `below`. They use semantic layout (the default) to arrange zones into a structured detail page — for example, an employee detail page with a header, tabbed related records, and a sidebar.
+
+A page is composite when it:
+- Is explicitly defined (not auto-generated)
+- Has more than one zone
+- Is not standalone (has a `model:`)
+
+### Areas
+
+| Area | Description |
+|------|-------------|
+| `main` | Primary content area. Typically renders a show presenter with record details. |
+| `tabs` | Tabbed content below the main area. Each tab zone becomes a tab in the tab bar. Only the active tab's data is loaded. |
+| `sidebar` | Side panel alongside the main content. |
+| `below` | Full-width area below the tabs. |
+
+### Zone Attributes for Composite Pages
+
+In addition to the [standard zone attributes](#zone-attributes), composite page zones support:
+
+| Attribute | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `scope_context` | object | no | — | Maps column names on the zone's model to dynamic references resolved from the parent record or request context. |
+| `label_key` | string | no | — | i18n key for the zone's tab label. Recommended for tab zones. Falls back to humanized zone name. |
+
+**Note:** The `filters`, `default_scope`, `width`, and `record_click` attributes from the [standard zone attributes](#zone-attributes) are especially useful in composite pages. Tab zones default to `filters: quick` (quick search), and `record_click: dialog` is useful for opening related records in a dialog without leaving the composite page.
+
+### scope_context
+
+`scope_context` scopes a zone's data query to the parent record. Each key is a column name on the zone's model, and each value is either a static value or a dynamic reference prefixed with `:`.
+
+**Dynamic references:**
+
+| Reference | Resolves to |
+|-----------|-------------|
+| `:record` | The parent record |
+| `:record.<field>` | A field value from the parent record (e.g. `:record.id`, `:record.department_id`) |
+| `:current_user` | The full `current_user` object (useful with `filter_*` interceptors) |
+| `:current_user.<method>` | A method value on the user (e.g. `:current_user.id`, `:current_user.organization_id`) |
+| `:selection_id` | The selected record's `id` from `?selected=N` (master-detail only) |
+| `:current_year` | The current year (integer) |
+| `:current_date` | Today's date |
+
+Static values (without `:` prefix) pass through unchanged.
+
+This is the unified dotted grammar — see [Dynamic References](dynamic-references.md) for the runtime contract and boot-time validation guarantees.
+
+**Dot-path depth limit:** Only single-level dot-paths are supported (e.g. `:record.department_id`). Multi-level paths like `:record.department.company_id` raise a `MetadataError` at boot.
+
+```yaml
+# Scope leave requests to the current employee
+scope_context:
+  employee_id: ":record.id"
+
+# Scope by a field on the parent record
+scope_context:
+  department_id: ":record.department_id"
+
+# Scope to current user
+scope_context:
+  assigned_to_id: ":current_user.id"
+
+# Static value
+scope_context:
+  year: 2024
+```
+
+**Scope application:** Each `scope_context` key is applied to the zone's query in this order:
+
+1. If the zone's model defines a `filter_<key>` class method, that method is called. The method may accept 2 arguments `(scope, value)` or 3 arguments `(scope, value, evaluator)` — both signatures are supported.
+2. Otherwise, if the key is a column name on the model, a `where(key => value)` clause is applied.
+3. If neither exists, a warning is logged and the key is skipped.
+
+### Zone Filters
+
+The `filters` attribute controls the search/filtering UI rendered inside a zone.
+
+| Value | Behavior |
+|-------|----------|
+| `quick` | Quick search text input. Searches across string/text fields using `LIKE` queries. |
+| `full` | Quick search + advanced filter pipeline (Ransack, custom filter interception, custom field filters). |
+| `none` | No filtering UI. |
+
+**Defaults:** `quick` for tab zones, `none` for all other areas. Widget zones must always use `none`.
+
+The quick search form is rendered inside the zone's Turbo Frame, so searching does not cause a full page reload. The `qs` parameter is preserved across pagination.
+
+### Zone Record Click
+
+The `record_click` attribute controls what happens when a user clicks a row in a presenter zone's table.
+
+| Value | Behavior |
+|-------|----------|
+| `navigate` | Full-page navigation to the record's show page (default). |
+| `dialog` | Opens the record's show page in a modal dialog (via `?_dialog=1`). Keeps the user on the composite page. |
+| `none` | No click action. Rows are not clickable. |
+
+When `record_click` is `navigate` or `dialog`, rows get `data-href` attributes pointing to the record's show page (resolved from the zone presenter's slug). If the presenter has no routable slug, rows degrade to non-clickable regardless of the setting.
+
+### Zone Default Scope
+
+The `default_scope` attribute applies a named scope before the zone's `scope` attribute. Both are cumulative — if both are set, the query is narrowed by `default_scope` first, then further narrowed by `scope`.
+
+```yaml
+zones:
+  - name: active_employees
+    presenter: employees_index
+    area: tabs
+    default_scope: active    # applied first
+    scope: recent            # applied second (on top of active)
+```
+
+### Zone Width
+
+The `width` attribute (1–12) controls the CSS grid column ratio in semantic layouts. It is primarily used to adjust the main/sidebar proportions:
+
+```yaml
+zones:
+  - name: header
+    presenter: employee_show
+    area: main
+    width: 9         # 9 of 12 columns for main
+
+  - name: sidebar_info
+    presenter: employee_summary
+    area: sidebar
+    width: 3         # 3 of 12 columns for sidebar
+```
+
+When omitted, the default is 8 columns for main and 4 for sidebar. Width has no effect on tab or below zones (they always span the full width).
+
+### Main Zone Selection
+
+The main zone is selected automatically with this priority:
+
+1. First presenter zone with `area: main`
+2. First presenter zone (any area)
+3. First zone of any type
+
+### Tab Navigation
+
+Tab zones render as a tab bar with links. The first tab is active by default. Tab switching is handled via **Turbo Frames** — clicking a tab loads the zone content without a full page reload.
+
+Each tab link points to the zone endpoint (`GET /:slug/:id/zones/:zone_name`) and targets the shared `lcp-zone-tab-content` Turbo Frame. The URL is updated to `?tab=<zone_name>` via `history.replaceState` for bookmarkability.
+
+Tab content is always loaded from the zone endpoint (even for the initially active tab). This ensures that all links inside the frame (pagination, sort) resolve to the zone endpoint URL.
+
+### Zone Endpoint
+
+`GET /:slug/:id/zones/:zone_name` renders a single zone's content wrapped in a `<turbo-frame>`.
+
+**Response:** A `<turbo-frame>` fragment (no full page layout). The frame ID is:
+- `lcp-zone-tab-content` for tab zones
+- `lcp-zone-{zone_name}` for sidebar/below zones
+
+**Parameters:**
+- `page` — Kaminari pagination page number
+- `sort` — Sort column name (must be a valid column)
+- `direction` — `asc` or `desc` (default: `asc`)
+- `qs` — Quick search query string (only when zone has `filters: quick` or `filters: full`)
+- `f[...]` — Ransack filter parameters (only when zone has `filters: full`)
+- `cf[...]` — Custom field filter parameters (only when zone has `filters: full`)
+
+**Authorization:** The endpoint checks `show?` on the parent record, zone visibility (`visible_when`), and per-zone presenter access. Returns 404 for unknown or inaccessible zones.
+
+### Sidebar/Below Zones
+
+Sidebar and below zones are rendered eagerly (server-side) and wrapped in `<turbo-frame id="lcp-zone-{name}">` tags without a `src` attribute. This enables `reload_zone` support — after a dialog action with `on_success: reload_zone`, the frame's `src` is set to trigger a lazy reload via the zone endpoint.
+
+### Per-Zone Authorization
+
+Each presenter zone checks whether the current user has presenter access for that zone's presenter. If the user lacks access (via the `presenters` key in permissions YAML), the zone is completely hidden — no tab link appears in the tab bar and no data is loaded.
+
+This differs from `visible_when`, which also hides zones but is based on conditions (role, field values) rather than presenter permissions. Both mechanisms produce the same result: the zone is excluded from rendering.
+
+### Show in Dialog
+
+When a presenter zone has `record_click: dialog`, clicking a row opens the record's show page inside a modal dialog. The dialog renders a read-only view of the record's show sections (from the record's own presenter layout) in a dialog frame with a header and close button.
+
+The dialog is loaded via `GET /:slug/:id?_dialog=1`, which returns a `<turbo-frame>` fragment without the full page layout. This keeps the user on the composite page while viewing related record details.
+
+### Composite Page Example
+
+```yaml
+page:
+  name: employee_detail
+  model: employee
+  slug: employees
+  zones:
+    - name: header
+      presenter: employee_show
+      area: main
+      width: 8
+
+    - name: leave_requests
+      presenter: leave_requests_index
+      area: tabs
+      label_key: pages.employee_detail.tabs.leave_requests
+      scope_context:
+        employee_id: ":record.id"
+      default_scope: recent
+      filters: quick
+      record_click: dialog
+
+    - name: trainings
+      presenter: trainings_index
+      area: tabs
+      label_key: pages.employee_detail.tabs.trainings
+      scope_context:
+        employee_id: ":record.id"
+      filters: full
+      record_click: navigate
+
+    - name: notes
+      presenter: employee_notes
+      area: sidebar
+      width: 4
+      scope_context:
+        employee_id: ":record.id"
+      record_click: none
+
+    - name: activity_log
+      presenter: audit_entries
+      area: below
+      scope_context:
+        record_id: ":record.id"
+      visible_when:
+        role: admin
+```
+
+This renders:
+- **Main area** (8 columns): Employee detail (show presenter)
+- **Tab bar**: "Leave requests" (quick search, dialog click, recent records first) and "Trainings" (full search, navigates to record) tabs, each scoped to this employee
+- **Sidebar** (4 columns): Notes panel scoped to this employee, non-clickable rows
+- **Below**: Activity log visible only to admins
+
+### Widget Zones with scope_context
+
+Widget zones on composite pages can also use `scope_context` to scope their data to the parent record:
+
+```yaml
+zones:
+  - name: header
+    presenter: employee_show
+    area: main
+
+  - name: leave_count
+    type: widget
+    area: sidebar
+    widget:
+      type: kpi_card
+      model: leave_request
+      aggregate: count
+      label_key: pages.employee.sidebar.leave_count
+    scope_context:
+      employee_id: ":record.id"
+```
+
+### Index-Level Composite Pages
+
+A composite page where the main zone's presenter has `table_columns` is detected as an **index composite**. The main area renders a full index table (with search, filtering, sorting, pagination) while sidebar and below zones display contextual widgets.
+
+```yaml
+page:
+  name: orders_overview
+  model: order
+  slug: orders
+  zones:
+    - name: orders_table
+      presenter: orders_index       # must have table_columns
+      area: main
+
+    - name: total_orders
+      type: widget
+      area: sidebar
+      widget:
+        type: kpi_card
+        model: order
+        aggregate: count
+        label_key: lcp_ruby.orders.total
+
+    - name: help_text
+      type: widget
+      area: below
+      widget:
+        type: text
+        content_key: lcp_ruby.orders.help
+      visible_when:
+        role: admin
+```
+
+**Detection:** `PageDefinition#index_composite?` returns `true` when the page is `composite?` AND the main zone's presenter has `table_columns` defined.
+
+**Constraints specific to index composites:**
+- **No tab zones.** Tab zones are not allowed because they use query parameters (`page`, `sort`, `qs`) that collide with the index table's parameters.
+- **No `:record.*` in `scope_context`.** Index composites render a collection, not a single record. Use model-level scopes or `:current_user.id` instead.
+
+### Master-Detail Pages
+
+A master-detail page is a specialized index composite where the sidebar contains a **selection zone** (a clickable list or tree) and the main area shows the detail of the selected record. Tabs and below zones are scoped to the selection via `:selection_id`.
+
+```yaml
+page:
+  name: department_explorer
+  model: department
+  slug: department-explorer
+  zones:
+    # Sidebar: clickable selection list (rendered by the index pipeline)
+    - name: department_list
+      presenter: dept_list_zone       # index presenter with table_columns
+      area: sidebar
+      width: 3                        # sidebar proportion (1-12)
+      selection: single               # enables row selection
+      record_click: none              # prevents row navigation (selection handles clicks)
+
+    # Main: detail of the selected record
+    - name: department_detail
+      presenter: dept_detail_zone     # show presenter
+      area: main
+      width: 9                        # main proportion (1-12)
+      record_source: selection        # loads record from ?selected=N
+
+    # Tab: scoped to selected record
+    - name: employees
+      presenter: employees_zone
+      area: tabs
+      label_key: lcp_ruby.pages.dept_explorer.tabs.employees
+      scope_context:
+        department_id: ":selection_id"
+
+    # Widget: scoped to selected record
+    - name: employee_kpi
+      type: widget
+      area: below
+      widget:
+        type: kpi_card
+        model: employee
+        aggregate: count
+      scope_context:
+        department_id: ":selection_id"
+```
+
+**Key attributes:**
+
+| Attribute | Zone | Description |
+|-----------|------|-------------|
+| `selection: single` | sidebar | Marks the zone as the selection list. Rows get `click->lcp-selection#select` wiring. Only valid on `sidebar` presenter zones. |
+| `record_click: none` | sidebar | Prevents default row navigation — selection handles clicks instead. |
+| `record_source: selection` | main | Loads the record identified by `?selected=N` from the page's primary model. |
+| `:selection_id` | tabs/below | Dynamic reference in `scope_context` resolving to the selected record's ID. |
+
+**Layout:** In master-detail mode, the sidebar renders on the **left** and the main area on the **right** (reversed from standard composite pages). The `width` values on sidebar and main zones control the column ratio — e.g., `width: 3` + `width: 9` produces `3fr 9fr`.
+
+**Tree support:** If the selection zone's presenter uses `tree_view: true`, the sidebar renders as a collapsible tree instead of a flat table. The tree rows are clickable for selection just like table rows.
+
+**Empty state:** When no record is selected (`?selected` absent), the main area shows an empty state message ("Select a record to view details"), and tabs/below zones are hidden. The sidebar always renders regardless of selection.
+
+**Actions column:** The Actions column is automatically hidden in the selection zone sidebar to keep it compact.
+
+**Detection:** `PageDefinition#master_detail?` returns `true` when the page is `index_composite?` AND at least one zone has `selection: single`.
+
+**Constraints specific to master-detail:**
+- `selection: single` is only valid on presenter zones in `sidebar` area
+- `record_source: selection` is only valid when the page has a zone with `selection: single`
+- Page must have a model (standalone pages cannot use master-detail)
+
+### Composite Dialog Pages
+
+Dialog-only pages with multiple zones render all zones inline in a single response — no lazy loading or Turbo Frames inside the dialog.
+
+```yaml
+page:
+  name: transfer_dialog
+  model: inventory_transfer
+  dialog:
+    size: large
+  zones:
+    - name: transfer_form
+      presenter: transfer_form
+      area: main
+      width: 8
+
+    - name: source_item
+      presenter: item_show
+      area: sidebar
+      width: 4
+      record_source:
+        param: source_id
+```
+
+Tab zones in composite dialogs render as stacked sections (not switchable tabs). `scope_context` with `:record.*` is not allowed since dialog-only pages have no primary record.
+
+See the [Dialogs Guide](../guides/dialogs.md#composite-dialog-pages) for triggering and workflow details.
+
+### Constraints
+
+The configuration validator enforces these rules at boot time:
+
+- **Main zone must not be an index presenter when tabs are present.** Index presenters use `page`, `sort`, and `q[...]` query parameters that collide with tab parameters. Use a show presenter for the main zone.
+- **Index composites must not have tab zones.** Tabs are not supported on index composite pages (query parameter collisions).
+- **No `:record.*` in index composites or dialog-only pages.** These pages have no primary record. Use model-level scopes, `:current_user.id`, or `record_source` instead.
+- **Main zone model should match the page model.** A warning is produced if the main zone's presenter references a different model than the page's `model:` attribute.
+- **Tab zones should have `label_key`.** Tabs fall back to the humanized zone name, but explicit labels are recommended.
+- **Max zones per page.** Warning when a page has more than 10 zones, error above 20 (auto-generated pages are exempt).
+- **Zone `width` must be 1–12** when specified.
+- **Zone `default_scope` must exist** as a named scope on the zone's model.
+- **Widget zones cannot have `filters`** other than `none`.
+- **Record click without slug warns.** A warning is produced when `record_click` is not `none` but the zone's presenter has no routable slug.
+- **Unreachable presenters.** A boot-time warning is logged when a presenter's auto-page has no slug, the presenter is not used in any explicit page zone, and is not dialog-only.
+
+### Claimed Presenters
+
+Presenters used as zones in a composite page are "claimed" and do not get auto-generated pages. This prevents duplicate routes — the composite page owns the rendering for those presenters.
+
+## Form Zones
+
+A form zone renders an edit form in the main area of a composite page instead of a read-only show view. After a successful save, the user stays on the composite page.
+
+```yaml
+page:
+  name: order_detail
+  model: order
+  slug: orders
+  zones:
+    - name: order_form
+      presenter: order_edit       # must have form sections defined
+      area: main
+      submit_redirect: self       # redirect back to this composite page after save
+
+    - name: order_lines
+      presenter: order_lines_index
+      area: below
+      scope_context:
+        order_id: ":record.id"
+```
+
+**Constraints:**
+- `submit_redirect` must be `self` (the only supported value)
+- Must be on a presenter zone in the `main` area
+- At most one form zone per page
+- The presenter must have `form.sections` defined
+- Users need both `show` and `update` permissions to access the page
+
+On validation error, the composite page re-renders with the form errors and all other zones (sidebar, tabs, below) preserved.
+
+## Record Source Zones
+
+A `record_source` zone loads a **single record** by ID from a URL parameter, instead of loading a collection. The zone renders a show view of that record.
+
+```yaml
+page:
+  name: transfer_dialog
+  model: inventory_transfer
+  dialog:
+    size: large
+  zones:
+    - name: source_item
+      presenter: inventory_item_show
+      area: sidebar
+      width: 4
+      record_source:
+        param: source_id           # loads from ?source_id=N
+
+    - name: transfer_form
+      presenter: transfer_form
+      area: main
+      width: 8
+```
+
+**Behavior:**
+- The zone renders the presenter's show sections (reusing the standard `_show_sections` partial with all features: conditional visibility, section types, renderers, copyable fields, etc.)
+- Eager loading is applied automatically based on the presenter's association dependencies
+- Authorization checks: user must have `show` permission on the zone's model and access to the zone's presenter
+
+**Constraints:**
+- `record_source` requires a `param` key specifying the URL parameter name
+- Must be on a presenter zone
+- Mutually exclusive with `scope_context` (a zone either loads one record OR filters a collection)
+- When the parameter is missing or the record is not found, the zone is hidden
+
+## Conditional Zone Visibility
+
+Use `visible_when` to show zones only to specific users.
+
+### Role Shortcut
+
+```yaml
+visible_when:
+  role: admin
+
+# or multiple roles
+visible_when:
+  role: [admin, manager]
+```
+
+### Condition Object
+
+Full condition expressions (same syntax as presenter `visible_when`):
+
+```yaml
+visible_when:
+  field: status
+  operator: eq
+  value: active
+```
+
+## Complete Example
+
+```yaml
+page:
+  name: main_dashboard
+  slug: dashboard
+  layout: grid
+  title_key: lcp_ruby.dashboard.title
+  zones:
+    - name: order_count
+      type: widget
+      widget:
+        type: kpi_card
+        model: order
+        aggregate: count
+        icon: shopping-cart
+        link_to: orders
+      position: { row: 1, col: 1, width: 4, height: 1 }
+
+    - name: total_revenue
+      type: widget
+      widget:
+        type: kpi_card
+        model: order
+        aggregate: sum
+        aggregate_field: total_amount
+        format: currency
+        icon: dollar-sign
+      position: { row: 1, col: 5, width: 4, height: 1 }
+
+    - name: open_tasks
+      type: widget
+      widget:
+        type: kpi_card
+        model: task
+        aggregate: count
+        icon: check-square
+      scope: open
+      position: { row: 1, col: 9, width: 4, height: 1 }
+      visible_when:
+        role: [admin, manager]
+
+    - name: welcome_text
+      type: widget
+      widget:
+        type: text
+        content_key: lcp_ruby.dashboard.welcome
+      position: { row: 2, col: 1, width: 12, height: 1 }
+
+    - name: recent_tasks
+      presenter: dashboard_tasks
+      scope: recent
+      limit: 5
+      position: { row: 3, col: 1, width: 6, height: 2 }
+
+    - name: recent_orders
+      presenter: dashboard_orders
+      scope: recent
+      limit: 5
+      position: { row: 3, col: 7, width: 6, height: 2 }
+```
+
+## Page Filters
+
+Two parallel YAML blocks define user-facing filter controls at the top
+of a dashboard or index composite page:
+
+- **`filter_form:`** — value-based filters (text, select, multi-select,
+  date range, association select with cascading dropdowns). Each entry
+  is a form-syntax field that renders through the same `form_helper`
+  pipeline as presenter forms.
+- **`scope_filters:`** — predefined AR-scope toggles (e.g. `active` vs.
+  `archived`).
+
+**See the dedicated [Page Filters reference](page_filters.md) for full
+syntax, the `auto_submit:` derivation table, cascading associations,
+and the `/select_options` fallback chain.**
+
+> **How this relates to presenter search:** Presenter-level
+> [search parameters](presenters.md#search-parameters) add typed filter
+> controls (dropdowns, toggles, ranges) directly in a single presenter's
+> toolbar. **Page filters** apply to **all zones** on the page at
+> once. Use presenter search parameters for single-presenter index
+> pages; use page filters for composite pages or dashboards where
+> multiple zones share the same filter.
+
+### Minimal example
+
+```yaml
+page:
+  name: workforce_overview
+  model: employee
+  slug: workforce
+  filter_form:
+    - field: department_id
+      input_type: association_select
+      model: department
+      label_key: lcp_ruby.pages.workforce.filters.department
+    - field: hired_at
+      input_type: date_range
+  scope_filters:
+    - name: status
+      scopes:
+        active: Active
+        inactive: Inactive
+      default: active
+
+  zones:
+    - { name: employees_table, presenter: employees_index, area: main }
+    - { name: headcount, type: widget, area: sidebar,
+        widget: { type: kpi_card, model: employee, aggregate: count } }
+```
+
+The legacy `parameters:` block was retired — the platform boots with
+`MetadataError` if it encounters one, pointing at the migration
+target. See [Page Filters § Migration](page_filters.md#migration-from-parameters).
+
+## Embed Widget
+
+The `embed` widget type renders external content inside an iframe. It delegates URL generation to a registered **embed provider**, keeping the page YAML declarative while the provider handles authentication, URL signing, or any provider-specific logic.
+
+### Widget Attributes
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | yes | Must be `embed`. |
+| `provider` | string | yes | Name of the registered embed provider (e.g., `metabase`, `grafana`). |
+| `resource_type` | string | yes | Provider-specific resource type (e.g., `dashboard`, `question`, `panel`). |
+| `resource_id` | string/integer | yes | Provider-specific resource identifier. |
+| `params` | object | no | Key-value pairs passed to the provider's `embed_url` method. Used for filtering, theming, or other provider-specific options. |
+| `height` | string | no | CSS height for the iframe (e.g., `400px`, `60vh`). Defaults to the provider's default or `400px`. |
+
+### Provider Setup
+
+Register embed providers in the application initializer:
+
+```ruby
+LcpRuby.configure do |config|
+  config.register_embed_provider("metabase", MetabaseEmbedProvider.new(
+    site_url: ENV["METABASE_SITE_URL"],
+    secret_key: ENV["METABASE_SECRET_KEY"]
+  ))
+end
+```
+
+### Provider Interface
+
+Every provider class must extend `LcpRuby::EmbedProviders::Base` and implement the `embed_url` method:
+
+```ruby
+class MetabaseEmbedProvider < LcpRuby::EmbedProviders::Base
+  def initialize(site_url:, secret_key:)
+    @site_url = site_url
+    @secret_key = secret_key
+  end
+
+  # @param resource_type [String] e.g., "dashboard", "question"
+  # @param resource_id [String, Integer] provider-specific ID
+  # @param params [Hash] additional parameters from the widget YAML
+  # @return [String] fully qualified URL for the iframe src
+  def embed_url(resource_type:, resource_id:, params: {})
+    token = sign_token(resource_type, resource_id, params)
+    "#{@site_url}/embed/#{resource_type}/#{token}#bordered=false&titled=false"
+  end
+end
+```
+
+### Security
+
+The embed iframe is rendered with a `sandbox` attribute to restrict the embedded content's capabilities. By default, the sandbox allows `allow-scripts` and `allow-same-origin` (required by most BI tools), but does not permit navigation or form submission in the parent frame.
+
+For Content Security Policy (CSP) compliance, use the `LcpRuby.embed_csp_sources` helper to retrieve the list of registered provider origins. Add these to the `frame-src` directive in your CSP configuration:
+
+```ruby
+# config/initializers/content_security_policy.rb
+Rails.application.config.content_security_policy do |policy|
+  policy.frame_src :self, *LcpRuby.embed_csp_sources
+end
+```
+
+### Example
+
+```yaml
+page:
+  name: analytics_dashboard
+  slug: analytics
+  layout: grid
+  zones:
+    - name: revenue_dashboard
+      type: widget
+      widget:
+        type: embed
+        provider: metabase
+        resource_type: dashboard
+        resource_id: 42
+        params:
+          date_filter: this_month
+          theme: transparent
+        height: 600px
+      position: { row: 1, col: 1, width: 12, height: 4 }
+
+    - name: recent_orders
+      presenter: dashboard_orders
+      scope: recent
+      limit: 10
+      position: { row: 5, col: 1, width: 12, height: 2 }
+```
+
+### approval_status
+
+Displays the approval workflow status for the current record: step progress, task details with approver snapshots, and action buttons (approve/reject/return/claim/delegate) for the current user's pending tasks. No extra required fields — the widget reads the record's active approval request automatically.
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | yes | Must be `approval_status`. |
+
+```yaml
+- name: approval
+  type: widget
+  area: below
+  widget:
+    type: approval_status
+```
+
+This widget requires the approval engine to be configured (see [Workflow Approvals Reference](workflow-approvals.md)). If no active approval request exists on the record, the widget is hidden.
+
+**Note:** Even without an explicit widget zone, the approval status is automatically rendered on show pages via the `approval_status` [view slot](view-slots.md) when a record has an active approval request.
+
+## DB-Stored Page Definitions
+
+Page definitions can be stored in the database at runtime, following the platform's Configuration Source Principle. This enables non-technical users to create and manage pages (dashboards, composite layouts) without editing YAML files.
+
+### Generator
+
+Run the generator to create the required database tables, model YAML, presenter, and permissions:
+
+```bash
+rails generate lcp_ruby:pages
+```
+
+### Configuration
+
+Enable DB-stored pages in the initializer:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.page_source = :model
+end
+```
+
+### Model Contract
+
+The generator creates a `page_config` model with the following contract:
+
+| Column | Type | Required | Description |
+|--------|------|----------|-------------|
+| `name` | string | yes | Unique page identifier. Must not collide with YAML page names unless overriding intentionally. |
+| `definition` | json | yes | Page definition in JSON format. Uses the same structure as the `page:` root in YAML files. |
+| `active` | boolean | no | When `false`, the page definition is ignored at boot. Defaults to `true`. |
+
+### Definition JSON Format
+
+The `definition` column stores the page structure as JSON, mirroring the YAML `page:` format:
+
+```json
+{
+  "name": "sales_dashboard",
+  "slug": "sales",
+  "layout": "grid",
+  "title_key": "lcp_ruby.pages.sales.title",
+  "zones": [
+    {
+      "name": "revenue",
+      "type": "widget",
+      "widget": {
+        "type": "kpi_card",
+        "model": "order",
+        "aggregate": "sum",
+        "aggregate_field": "total_amount",
+        "format": "currency"
+      },
+      "position": { "row": 1, "col": 1, "width": 6, "height": 1 }
+    },
+    {
+      "name": "recent_orders",
+      "presenter": "dashboard_orders",
+      "scope": "recent",
+      "limit": 5,
+      "position": { "row": 2, "col": 1, "width": 12, "height": 2 }
+    }
+  ]
+}
+```
+
+All page attributes (`model`, `dialog`, `filter_form`, `scope_filters`, `index_presenter`, etc.) and zone attributes (`scope_context`, `visible_when`, `filters`, `record_click`, `depends_on`, etc.) are supported in the JSON format. The structure is identical to YAML — only the serialization format differs.
+
+### Override Priority
+
+Page definitions are resolved in this priority order (highest wins):
+
+1. **DB-stored pages** — runtime definitions from the `page_config` table (only active records)
+2. **YAML pages** — static definitions from `config/lcp_ruby/pages/*.yml`
+3. **Auto-generated pages** — created automatically for unclaimed presenters
+
+When a DB page and a YAML page share the same `name`, the DB version takes precedence. This allows runtime overrides of static page definitions without modifying YAML files.
+
+### Management UI
+
+The generator creates a presenter for the `page_config` model, accessible at `/page-configs`. This provides a standard CRUD interface for creating, editing, and deactivating page definitions through the platform's own UI.
+
+### Validation
+
+DB-stored pages are validated with the same rules as YAML pages (zone constraints, scope_context references, widget configuration, etc.). Invalid definitions are logged as warnings at boot and skipped — they do not prevent the application from starting.
+
+## Auto-Refresh (depends_on)
+
+The `depends_on` zone attribute enables automatic zone refresh when records of a specified model are created, updated, or destroyed. This keeps dashboard widgets and related-record lists up to date without manual page reloads.
+
+### Zone Attribute
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `depends_on` | array of strings | no | List of model names. When a CRUD operation occurs on any listed model, the zone's Turbo Frame is replaced via a Turbo Stream broadcast. |
+
+### Behavior
+
+When a record of a model listed in `depends_on` is created, updated, or destroyed, the platform broadcasts a Turbo Stream `replace` action targeting the zone's Turbo Frame. The zone content is re-rendered server-side with fresh data and pushed to all connected clients viewing the page.
+
+The broadcast is triggered by `after_commit` callbacks on the dependent models. Only zones currently visible to the user (i.e., not hidden by `visible_when` or authorization) receive the update.
+
+### ActionCable Requirement
+
+`depends_on` requires ActionCable to be available in the host application. If ActionCable is not configured:
+
+- The `depends_on` attribute is silently ignored at runtime (no errors, zones simply do not auto-refresh).
+- A warning is logged at boot time: `[LcpRuby] depends_on requires ActionCable but it is not available. Auto-refresh will be disabled.`
+
+This ensures graceful degradation — pages render and function normally, but without live updates.
+
+### Example
+
+```yaml
+page:
+  name: order_detail
+  model: order
+  slug: orders
+  zones:
+    - name: header
+      presenter: order_show
+      area: main
+
+    - name: order_lines
+      presenter: order_lines_index
+      area: tabs
+      label_key: lcp_ruby.pages.order_detail.tabs.lines
+      scope_context:
+        order_id: ":record.id"
+      depends_on: [order_line]
+
+    - name: total_amount
+      type: widget
+      area: sidebar
+      widget:
+        type: kpi_card
+        model: order_line
+        aggregate: sum
+        aggregate_field: amount
+        label_key: lcp_ruby.pages.order_detail.sidebar.total
+      scope_context:
+        order_id: ":record.id"
+      depends_on: [order_line]
+```
+
+In this example, both the order lines tab and the total amount KPI widget automatically refresh whenever an `order_line` record is created, updated, or destroyed. If a user adds a line item via a dialog, both zones update in real time without a page reload.