lcp 0.1.0

data/docs/reference/models.md

@@ -0,0 +1,2972 @@
+# Models Reference
+
+File: `config/lcp_ruby/models/<name>.yml`
+
+Model YAML defines the data layer: database columns, validations, associations, scopes, and events. The engine reads these files at boot and dynamically creates ActiveRecord models under the `LcpRuby::Dynamic::` namespace.
+
+## Top-Level Attributes
+
+```yaml
+model:
+  name: <model_name>
+  label: "Display Name"
+  label_plural: "Display Names"
+  table_name: <custom_table_name>
+  slug_field: <field_name>
+  fields: []
+  validations: []
+  associations: []
+  scopes: []
+  events: []
+  display_templates: {}
+  virtual_columns: {}   # computed query-time columns (expressions, JOINs, aggregates)
+  aggregates: {}        # legacy alias for virtual_columns, still supported
+  positioning: true | { field: position, scope: parent_id }
+  options: {}
+```
+
+### `name`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string (snake_case) |
+
+Internal identifier for the model. Used to generate the AR class name (`LcpRuby::Dynamic::TodoItem` for `todo_item`), default table name, and cross-references from presenters and permissions.
+
+### `label`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `name.humanize` |
+| **Type** | string |
+
+Human-readable singular name displayed in the UI (page titles, flash messages).
+
+### `label_plural`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `label.pluralize` |
+| **Type** | string |
+
+Plural form of the label. Used in index page headings and navigation.
+
+### `abstract`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+When `true`, this model serves as a reusable template. Abstract models produce no AR class or DB table — their fields, associations, scopes, events, validations, options, virtual_columns, display_templates, and indexes are merged into child models that reference them via `inherits`. Abstract models must not define `table_name` or `options.sti`.
+
+**Convention:** Abstract model names start with `_` (underscore) to signal "not instantiable." This is a convention, not enforced — the `abstract: true` key is the authoritative flag.
+
+```yaml
+model:
+  name: _auditable
+  abstract: true
+  fields:
+    - name: created_by
+      type: string
+    - name: updated_by
+      type: string
+  options:
+    userstamps: true
+```
+
+### `inherits`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string |
+
+Name of a parent model whose fields, associations, scopes, events, validations, options, virtual_columns, display_templates, and indexes are merged into this model. The parent model must be either `abstract: true` or have `options.sti: true`.
+
+**Two inheritance modes:**
+
+1. **Abstract inheritance** — parent has `abstract: true`. Merged at metadata level; parent produces no AR class or DB table.
+2. **STI inheritance** — parent has `options.sti: true`. Child AR class inherits from parent AR class and shares the parent's table via [Single Table Inheritance](#single-table-inheritance-sti).
+
+**Merge rules:**
+
+| Section | Behavior |
+|---------|----------|
+| `fields` | Parent fields first, then child fields appended. Child field with same name **overrides** parent field entirely. |
+| `associations` | Parent first, child appended. Same-name override. |
+| `scopes` | Parent first, child appended. Same-name override. |
+| `events` | Parent first, child appended. Same-name override. |
+| `validations` | Additive — parent validations concatenated with child. No override. |
+| `options` | Deep merge — child options override parent where keys collide. |
+| `virtual_columns` | Merge by key — child overrides parent on collision. |
+| `display_templates` | Merge by key — child overrides parent on collision. |
+| `indexes` | Concatenated (all inherited + all child). |
+| `positioning` | Child wins if present, otherwise inherited. |
+| `data_source` | Child wins if present, otherwise inherited. |
+| `name`, `table_name`, `label`, `label_plural` | Never inherited — always the child's own identity. |
+
+**Chaining:** A model can inherit from a parent that itself inherits from another abstract model. An abstract → STI chain (abstract parent → STI parent → STI child) is supported. Circular inheritance is detected and raises `MetadataError` at load time.
+
+**Cross-format:** YAML models can inherit from DSL-defined abstract models and vice versa.
+
+```yaml
+model:
+  name: ticket
+  inherits: _auditable
+  fields:
+    - name: title
+      type: string
+```
+
+### `table_name`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `name.pluralize` |
+| **Type** | string |
+
+Override the database table name. Use this when integrating with an existing database that has a non-standard table naming convention.
+
+```yaml
+model:
+  name: todo_item
+  table_name: legacy_todo_items
+```
+
+#### Virtual Models
+
+Set `table_name: _virtual` to create a metadata-only model — no database table and no ActiveRecord class are created. Virtual models exist purely for field metadata (types, labels, validations, transforms, defaults) and are used as item definitions for JSON field nested editing.
+
+```yaml
+model:
+  name: address
+  table_name: _virtual
+  fields:
+    - name: street
+      type: string
+      validations: [{ type: presence }]
+    - name: city
+      type: string
+      validations: [{ type: presence }]
+    - name: zip
+      type: string
+    - name: country
+      type: string
+      default: "CZ"
+```
+
+Virtual models:
+- Are loaded by `Metadata::Loader` and available via `LcpRuby.loader.model_definitions`
+- Are **not** registered in `LcpRuby.registry` (no AR class to register)
+- Are **not** built by `ModelFactory::Builder` — `SchemaManager.ensure_table!` skips them
+- Should not have associations or scopes (these produce warnings in `ConfigurationValidator`)
+- Are referenced from presenter `nested_fields` sections via `target_model:` — see [JSON Field with Target Model](presenters.md#json-field-source-model-backed)
+
+When a `json_field:` + `target_model:` nested section is rendered, each hash item from the JSON array is wrapped in a `JsonItemWrapper` that uses the virtual model's field definitions for type coercion, getter/setter access, and per-item validation.
+
+#### API-Backed Models
+
+Add a `data_source` key to create a model backed by an external REST API or host-provided adapter instead of the database:
+
+```yaml
+model:
+  name: external_building
+  data_source:
+    type: rest_json                  # rest_json | host
+    base_url: "https://api.example.com"
+    resource: "/buildings"
+    auth:
+      type: bearer
+      token_env: "API_TOKEN"
+    cache:
+      enabled: true
+      ttl: 300
+  fields:
+    - name: name
+      type: string
+```
+
+API-backed models use `ActiveModel` instead of `ActiveRecord`. They support index and show views, cross-source associations (DB model → API model), permissions, and display renderers. Features requiring database access (soft_delete, auditing, userstamps, tree, positioning, custom_fields) are not available.
+
+See [API-Backed Models Reference](api-backed-models.md) and [API-Backed Models Guide](../guides/api-backed-models.md) for full documentation.
+
+### `positioning`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | boolean or hash |
+
+Enables automatic record positioning via the [`positioning`](https://github.com/brendon/positioning) gem. When present, records get automatic sequential position assignment on create, gap closing on destroy, and atomic reorder support.
+
+**Minimal form** — uses `position` field with no scope:
+
+```yaml
+positioning: true
+```
+
+**Hash form** — custom field and/or scoped positioning:
+
+```yaml
+positioning:
+  field: position          # optional, default: "position"
+  scope: pipeline_id       # optional, string or array of strings
+```
+
+**Multi-column scope:**
+
+```yaml
+positioning:
+  scope: [pipeline_id, category]
+```
+
+When `positioning` is set:
+- The `positioned` gem macro is applied to the dynamic model
+- The position column gets a `NOT NULL` constraint
+- A unique index on `[scope_columns..., position_column]` is added (except on SQLite)
+- The `positioning.field` must reference a declared field of type `integer`
+- Each `positioning.scope` entry must be a declared field or a belongs_to FK
+
+See [Record Positioning](../design/record_positioning.md) for the full design.
+
+### `indexes`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `[]` |
+| **Type** | array of index objects |
+
+Declares database indexes on the model's table. Each index specifies columns, optional uniqueness, and optional custom name.
+
+```yaml
+indexes:
+  - columns: [seq_model, seq_field, scope_key]
+    unique: true
+  - columns: [department_id, created_at]
+  - columns: [email]
+    unique: true
+    name: idx_users_email_uniq
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `columns` | array of strings | (required) | Column names to include in the index |
+| `unique` | boolean | `false` | Create a unique constraint index |
+| `name` | string | auto-generated | Custom index name |
+
+Indexes are created at boot by `SchemaManager` (idempotent — existing indexes are skipped). All referenced columns must be defined fields on the model.
+
+**DSL:**
+
+```ruby
+define_model :gapfree_sequence do
+  field :seq_model, :string
+  field :seq_field, :string
+  field :scope_key, :string
+  index %i[seq_model seq_field scope_key], unique: true
+end
+```
+
+### `slug_field`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none |
+| **Type** | string |
+
+Name of a string field to use as URL slug. When set, the controller resolves non-numeric `params[:id]` via `find_by!(slug_field => param)` before falling back to numeric ID lookup. The dynamic model class also overrides `to_param` to return the slug value (with fallback to `id` when slug is nil/blank), so Rails URL helpers automatically generate slug-based URLs.
+
+The field must be:
+- A declared field on the model (not a virtual column)
+- A string-compatible type (`string`, `email`, `url`, or a custom type resolving to a string column)
+- Not an attachment field
+
+The platform auto-adds an `exclusion` validation that prevents records from being saved with slug values that collide with reserved route segments (`new`, `edit`, `saved-filters`, etc.).
+
+```yaml
+model:
+  name: article
+  slug_field: slug
+  fields:
+    - { name: title, type: string }
+    - { name: slug, type: string }
+  validations:
+    - { field: slug, type: uniqueness }
+    - { field: slug, type: format, options: { with: "\\A[a-z0-9-]+\\z" } }
+  indexes:
+    - { columns: [slug], unique: true }
+```
+
+**Recommendations (validated as warnings at boot):**
+
+- Add a `uniqueness` validation on the slug field — without it, `find_by!` returns non-deterministic results when duplicates exist.
+- Use a format pattern that requires at least one non-numeric character — purely numeric slugs (e.g., `"123"`) are unreachable via URL because numeric params always resolve as record IDs.
+- Use a lowercase-only format pattern — `find_by!` is case-sensitive on PostgreSQL, so `/articles/My-Slug` and `/articles/my-slug` would be different URLs.
+- Avoid dots in slugs — Rails routing splits `params[:id]` on `.` into id and format (e.g., `/articles/v2.0` parses as `id: "v2", format: "0"`).
+- Add a database index on the slug field — `find_by!` runs on every non-numeric request.
+
+The recommended format pattern `\A[a-z0-9-]+\z` avoids all of the above pitfalls.
+
+**STI note:** `slug_field` is not inherited by STI child models. Each child that needs slug resolution must declare its own `slug_field`. The `to_param` override is inherited via Ruby class hierarchy (so outbound links work), but the inbound resolve chain checks the child's own `ModelDefinition`.
+
+**DSL:**
+
+```ruby
+define_model :article do
+  slug_field :slug
+
+  field :slug, :string
+  field :title, :string
+end
+```
+
+See [Record Aliases Guide](../guides/record-aliases.md) for full examples.
+
+## Fields
+
+Each field defines a database column and its metadata.
+
+```yaml
+fields:
+  - name: title
+    type: string
+    label: "Title"
+    default: "Untitled"
+    column_options:
+      limit: 255
+      "null": false
+    enum_values: []
+    validations: []
+```
+
+### Field Attributes
+
+#### `name`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string |
+
+Column name. Must be unique within the model. Used as the ActiveRecord attribute name.
+
+**Reserved names:** Some field names conflict with ActiveRecord/ActiveModel internals and must be avoided. Using a reserved name causes `ActiveModel::DangerousAttributeError` at runtime or silently overrides framework methods.
+
+Names that **must not** be used as field names:
+
+| Category | Names |
+|----------|-------|
+| Identity / lifecycle | `id`, `type`, `class`, `hash`, `object_id` |
+| Persistence | `save`, `save!`, `destroy`, `destroy!`, `delete`, `update`, `update!`, `create` |
+| State | `new_record?`, `persisted?`, `frozen?`, `valid?`, `invalid?`, `errors`, `changed?`, `changes` |
+| Introspection | `model_name`, `respond_to?`, `send`, `inspect`, `to_s`, `to_param`, `to_model` |
+| Attributes | `reload`, `assign_attributes`, `becomes`, `attributes`, `read_attribute`, `write_attribute`, `attribute_names`, `serializable_hash` |
+| Object | `dup`, `clone`, `freeze` |
+
+Additionally, these names are reserved by the platform: `custom_data` (used by custom fields), `discarded_at` (used by soft delete), `position` (used by positioning).
+
+> **Tip:** If you need a field conceptually named after a reserved word, add a prefix or suffix — e.g., use `ai_model` instead of `model_name`, or `record_type` instead of `type` (unless you intend STI).
+
+#### `type`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string (base type or registered business type) |
+
+Determines the database column type and default form input behavior. Accepts one of the 14 base types below, or any registered [business type](types.md) name (e.g., `email`, `phone`, `url`, `color`).
+
+**Base types:**
+
+| Type | DB Column | Description |
+|------|-----------|-------------|
+| `string` | `:string` | Short text (varchar). Default form input: text field. |
+| `text` | `:text` | Long text. Default form input: textarea. |
+| `integer` | `:integer` | Whole number. |
+| `float` | `:float` | Floating-point number. |
+| `decimal` | `:decimal` | Precise decimal. Use `column_options: { precision:, scale: }`. |
+| `boolean` | `:boolean` | True/false. Default form input: checkbox. |
+| `date` | `:date` | Date without time. |
+| `datetime` | `:datetime` | Date and time. |
+| `enum` | `:string` | Stored as string. Requires `enum_values`. Default form input: select. |
+| `file` | `:string` | File path/reference stored as string. |
+| `rich_text` | `:text` | Rich text content. Default form input: WYSIWYG editor (Trix). Requires Action Text — `lcp new` installs it by default; if you used `--skip-action-text` or added LCP to an existing app without Action Text, the field silently renders as a plain textarea. The boot logger prints a warning naming each affected field with recovery steps (`bin/rails action_text:install` → `db:migrate` → restart). |
+| `json` | `:jsonb` / `:json` | JSON data. Uses jsonb on PostgreSQL, json on other adapters. |
+| `uuid` | `:string` | UUID stored as string. |
+| `array` | PG: native array / SQLite: `:json` | Typed array of scalars. Requires `item_type`. Default form input: tag chips. |
+| `attachment` | none (uses Active Storage) | File attachment (single or multiple). Requires Active Storage. |
+
+**Built-in business types:**
+
+| Type | Base | Transforms | Input | Description |
+|------|------|------------|-------|-------------|
+| `email` | string | strip, downcase | `<input type="email">` | Email with format validation |
+| `phone` | string | strip, normalize_phone | `<input type="tel">` | Phone with format validation |
+| `url` | string | strip, normalize_url | `<input type="url">` | URL with format validation, auto-prepends `https://` |
+| `color` | string | strip, downcase | `<input type="color">` | Hex color (`#rrggbb`) with format validation |
+| `bigint` | integer | — | `<input type="number">` | 8-byte integer — use for FK columns that reference Rails' default `bigint` PK to avoid silent `INT`/`BIGINT` join mismatches. |
+
+Business types bundle transforms (normalization), validations, HTML input hints, and column options into a reusable definition. See [Types Reference](types.md) for defining custom types.
+
+##### Attachment Fields
+
+The `attachment` type uses Active Storage instead of a database column. It supports both single-file (`has_one_attached`) and multi-file (`has_many_attached`) attachments.
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `multiple` | boolean | `false` | Use `has_many_attached` instead of `has_one_attached` |
+| `accept` | string | none | HTML `accept` attribute hint for file input (e.g., `"image/*"`). Not validated server-side — use `content_types` for validation. |
+| `max_size` | string | global default | Maximum file size per file (e.g., `"10MB"`, `"512KB"`) |
+| `min_size` | string | none | Minimum file size per file |
+| `content_types` | array | global default | Allowed MIME types. Supports wildcards (e.g., `"image/*"`) |
+| `max_files` | integer | none | Maximum number of files (only for `multiple: true`) |
+| `variants` | hash | none | Named image variant configurations |
+
+```yaml
+fields:
+  # Single image attachment with variants
+  - name: photo
+    type: attachment
+    label: "Photo"
+    options:
+      accept: "image/*"
+      max_size: 5MB
+      content_types: ["image/jpeg", "image/png", "image/webp"]
+      variants:
+        thumbnail: { resize_to_limit: [100, 100] }
+        medium: { resize_to_limit: [300, 300] }
+
+  # Multiple file attachment
+  - name: files
+    type: attachment
+    label: "Documents"
+    options:
+      multiple: true
+      max_files: 10
+      max_size: 50MB
+      content_types: ["application/pdf", "image/*"]
+```
+
+Attachment fields require Active Storage to be set up in the host application. See the [Attachments Guide](../guides/attachments.md) for prerequisites and complete examples.
+
+##### Array Fields
+
+The `array` type stores a list of scalar values. It requires an `item_type` to specify the element type.
+
+**Supported item types:** `string`, `integer`, `float`
+
+**Storage:** On PostgreSQL, uses native array columns (`text[]`, `integer[]`, `float[]`). On SQLite and other adapters, uses a JSON column with transparent serialization.
+
+```yaml
+fields:
+  # String array (e.g., tags)
+  - name: tags
+    type: array
+    item_type: string
+    default: []
+
+  # Integer array (e.g., scores)
+  - name: scores
+    type: array
+    item_type: integer
+    default: []
+
+  # Float array (e.g., measurements)
+  - name: measurements
+    type: array
+    item_type: float
+```
+
+**Auto-generated scopes:** Each array field automatically creates two scopes:
+
+| Scope | Description | SQL (PostgreSQL) |
+|-------|-------------|------------------|
+| `with_<field>(values)` | Records whose array contains ALL given values | `@>` (array containment) |
+| `with_any_<field>(values)` | Records whose array contains ANY of the given values | `&&` (array overlap) |
+
+```ruby
+# Find records tagged with both "ruby" AND "rails"
+Article.with_tags(["ruby", "rails"])
+
+# Find records tagged with "ruby" OR "python"
+Article.with_any_tags(["ruby", "python"])
+```
+
+**Quick search:** Array fields with `item_type: string` are automatically included in quick search (`?qs=`). The search matches any element that contains the query text (case-insensitive on PostgreSQL, case-sensitive on SQLite).
+
+**Presenter defaults:** Array fields automatically use the `array_input` form input (tag-style chips) and the `collection` renderer. These can be overridden in the presenter.
+
+See also: [Array validations](#array_length), [Condition operators for arrays](condition-operators.md#array-operators).
+
+#### `label`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `name.humanize` |
+| **Type** | string |
+
+Display label for form inputs, table headers, and show fields.
+
+#### `default`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `nil` |
+| **Type** | scalar, string (built-in key), or hash (service) |
+
+Default value for new records. Supports exactly three forms — pick by the type of value you write:
+
+| Form | YAML shape | When applied | Use for |
+|------|-----------|--------------|---------|
+| Scalar | `default: false` / `default: "medium"` / `default: 0` | DB column default at table creation | Static literal values |
+| Built-in dynamic | `default: current_date` (string matching a built-in key) | Runtime `after_initialize` on new records | `current_date`, `current_datetime`, `current_year`, `current_user.id` |
+| Service dynamic | `default: { service: "my_service" }` | Runtime `after_initialize` on new records | Custom logic registered in `app/lcp_services/defaults/` |
+
+A bare string that does **not** match a built-in key is treated as a literal scalar (e.g. `default: "draft"`). The built-in dynamic keys follow the [Dynamic References](dynamic-references.md) grammar — boot-time validation catches typos against the configured `user_class`. For other dynamic computations expressible as field references see [`computed`](#computed) — distinct from `default` because it re-evaluates on every read.
+
+**Scalar default** — applied as a database column default:
+
+```yaml
+- name: completed
+  type: boolean
+  default: false
+
+- name: priority
+  type: string
+  default: "medium"
+```
+
+**Built-in dynamic default** — a string matching a built-in default key. Applied at runtime via `after_initialize` (only on new records, only when the field is blank):
+
+| Key | Value | Description |
+|-----|-------|-------------|
+| `current_date` | `Date.today` | Today's date |
+| `current_datetime` | `Time.current` | Current date and time |
+| `current_user.id` | `LcpRuby::Current.user&.id` | Current user's ID |
+
+```yaml
+- name: start_date
+  type: date
+  default: current_date
+```
+
+**Service dynamic default** — delegates to a registered default service. Applied at runtime via `after_initialize`:
+
+```yaml
+- name: expected_close_date
+  type: date
+  default:
+    service: thirty_days_out
+```
+
+```ruby
+# DSL
+field :start_date, :date, default: "current_date"
+field :expected_close_date, :date, default: { service: "thirty_days_out" }
+```
+
+**Defaults on service-accessor fields** — fields whose value lives behind an accessor service (most commonly `source: { service: json_field, ... }`) follow the same Rails-like default semantics as regular columns: the default is applied **on new-record creation** in the `after_initialize` callback, which calls the accessor's setter (e.g. `JsonField.set`) to write the value into the underlying store (JSON column) before `save`. Read-time fallback is NOT used — the accessor's getter returns the raw stored value.
+
+```yaml
+- name: theme
+  type: enum
+  default: "auto"
+  values: { light: "Light", dark: "Dark", auto: "System" }
+  source:
+    service: json_field
+    options: { column: profile_data, key: theme }
+```
+
+For `record = Preference.new`, `record.theme == "auto"` and after `record.save!` the column holds `profile_data == {"theme" => "auto"}`. All three default forms work identically to regular columns:
+
+- literal (`default: "auto"`)
+- built-in service key (`default: "current_date"`)
+- service hash (`default: { service: "thirty_days_out" }`)
+
+**Bind_to models** get the same behavior automatically — `DefaultApplicator` is in the `bind_to_auto_features` list when any field has a `default:`, so it registers the `after_initialize` callback on the host class. No `bind_to_apply:` declaration is needed.
+
+**Existing rows:** If you add a `default:` to a field that already has data in the database, **existing rows with a missing JSON key return `nil`** — the default is not retroactively applied, mirroring how DB column defaults behave in Rails. To backfill old rows, write a one-shot Rails migration:
+
+```ruby
+# db/migrate/20260521_backfill_theme_default.rb
+class BackfillThemeDefault < ActiveRecord::Migration[7.1]
+  def up
+    LcpRuby::Dynamic::Preference.where("profile_data->>'theme' IS NULL").find_each do |p|
+      p.update!(theme: "auto")
+    end
+  end
+end
+```
+
+The accessor's setter writes the value into the JSON column like any normal update.
+
+Service contract: `def self.call(record, field_name) -> value`. Register in `app/lcp_services/defaults/`. See [Extensibility Guide](../guides/extensibility.md).
+
+#### `column_options`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `{}` |
+| **Type** | hash |
+
+Options passed directly to the ActiveRecord migration column definition.
+
+| Option | Applicable Types | Description |
+|--------|-----------------|-------------|
+| `limit` | string | Maximum character length |
+| `precision` | decimal | Total number of digits |
+| `scale` | decimal | Digits after decimal point |
+| `null` | all | Allow NULL values (`true`/`false`) |
+
+```yaml
+column_options:
+  limit: 255
+  "null": false
+```
+
+> Note: Quote `null` as `"null"` in YAML to avoid it being parsed as a null value.
+
+#### `enum_values`
+
+| | |
+|---|---|
+| **Required** | yes (when type is `enum`) |
+| **Type** | array of strings or hashes |
+
+Defines the allowed values for an enum field. Two formats are supported:
+
+**Simple format** — value and label are the same:
+
+```yaml
+enum_values: [draft, published, archived]
+```
+
+**Hash format** — separate internal value and display label:
+
+```yaml
+enum_values:
+  - { value: draft, label: "Draft" }
+  - { value: published, label: "Published" }
+  - { value: archived, label: "Archived" }
+```
+
+Enum values are always stored and compared as strings internally. Even if you write `value: 0` (integer) in YAML, it is converted to `"0"` via `.to_s`.
+
+**Display label resolution** (in badges, table cells, show pages, and form selects):
+
+1. **i18n** — `I18n.t("lcp_ruby.enums.<model>.<field>.<value>")` (highest priority)
+2. **YAML label** — the `label` key from the hash format above
+3. **Humanize** — `value.humanize` as fallback
+
+**Form select ordering**: by default, form `<select>` and radio inputs render enum values in **declaration order** (the order in `enum_values`). To sort alphabetically by label or reverse declaration order, set `input_options: { sort: alphabetical }` (or `reverse`) on the form field — see [Presenters reference — Select (enum)](presenters.md#input-options).
+
+#### `item_type`
+
+| | |
+|---|---|
+| **Required** | yes (when type is `array`) |
+| **Type** | string |
+
+Specifies the scalar type of array elements. Must be one of: `string`, `integer`, `float`.
+
+```yaml
+- name: tags
+  type: array
+  item_type: string
+```
+
+```ruby
+# DSL
+field :tags, :array, item_type: :string
+```
+
+#### `transforms`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `[]` |
+| **Type** | array of strings |
+
+Field-level transforms applied via `ActiveRecord.normalizes`. Transforms run before validation on every assignment. Field-level transforms extend type-level transforms (defined via [custom types](types.md)) — the union is applied, with type-level transforms running first.
+
+```yaml
+# YAML
+- name: title
+  type: string
+  transforms: [strip]
+
+# With custom type that already has transforms
+- name: email
+  type: email  # email type has strip+downcase
+  transforms: [strip]  # deduplicated, won't strip twice
+```
+
+```ruby
+# DSL
+field :first_name, :string, transforms: [:strip, :titlecase]
+```
+
+Built-in transforms: `strip`, `downcase`, `normalize_url`, `normalize_phone`. Custom transforms can be registered in `app/lcp_services/transforms/`. See [Extensibility Guide](../guides/extensibility.md).
+
+#### `computed`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `nil` |
+| **Type** | string (template) or hash (service) |
+
+Computed fields are automatically calculated before save. They are rendered as readonly in forms.
+
+**Template syntax** — interpolates other field values:
+
+```yaml
+- name: full_name
+  type: string
+  computed: "{first_name} {last_name}"
+```
+
+The `{field}` micro-syntax (curly braces, dot-paths like `{company.name}`) is identical to the one used by [Display Templates](#display-templates) — the same parser handles both. Use `computed:` when the result is persisted on the record (read-write field, available to scopes and exports); use a display template when you only need it for rendering.
+
+**Service syntax** — delegates to a registered computed service:
+
+```yaml
+- name: weighted_value
+  type: decimal
+  computed:
+    service: weighted_deal_value
+```
+
+```ruby
+# DSL
+field :full_name, :string, computed: "{first_name} {last_name}"
+field :weighted_value, :decimal, computed: { service: "weighted_deal_value" }
+```
+
+Service contract: `def self.call(record) -> value`. Register in `app/lcp_services/computed/`. See [Extensibility Guide](../guides/extensibility.md).
+
+**Execution order:** Computed fields are recalculated in the order they appear in the `fields:` list. A computed field can read another computed field's value as long as the dependency is defined earlier. Circular dependencies are not detected — avoiding them is the implementor's responsibility.
+
+#### `sequence`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `nil` |
+| **Type** | boolean (`true`) or hash |
+
+Auto-numbering sequence field. Assigns a unique sequential value from a gap-free counter on record creation. Requires the `gapfree_sequence` model (run `rails generate lcp_ruby:gapfree_sequences`).
+
+**Shorthand** — all defaults (global scope, raw counter, start 1, step 1, readonly):
+
+```yaml
+- name: seq
+  type: integer
+  sequence: true
+```
+
+**Full form:**
+
+```yaml
+- name: invoice_number
+  type: string
+  sequence:
+    scope: [_year]
+    format: "INV-%{_year}-%{sequence:04d}"
+    start: 1
+    step: 1
+    readonly: true
+    assign_on: create
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `scope` | array of strings | `[]` (global) | Scope columns or virtual keys (`_year`, `_month`, `_day`). Counter resets per unique scope combination. |
+| `format` | string | none (raw integer) | Template with `%{sequence}`, `%{sequence:Nd}`, `%{_year}`, `%{_month}`, `%{_day}`, `%{field_name}`. |
+| `start` | integer | `1` | Initial counter value for a new scope. |
+| `step` | integer | `1` | Increment per record. |
+| `readonly` | boolean | `true` | Render as disabled input in forms. |
+| `assign_on` | string | `"create"` | `"create"` (before_create only) or `"always"` (also fills blank on update). |
+
+```ruby
+# DSL
+field :invoice_number, :string,
+  sequence: { scope: [:_year], format: "INV-%{_year}-%{sequence:04d}" }
+```
+
+A field cannot have both `sequence` and `computed` (or `source`) — these are mutually exclusive. See [Sequence Fields Guide](../guides/sequences.md) for scoping, format templates, and counter management.
+
+#### `validations`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `[]` |
+| **Type** | array of validation objects |
+
+Field-level validations. See [Validations](#validations) below.
+
+## Validations
+
+Validations can be defined at the field level (inside a field's `validations` array) or at the model level (in the top-level `validations` array). Model-level validations support the `custom` and `service` types.
+
+### Validation Types
+
+Each validation has a `type` and optional `options` hash.
+
+#### `presence`
+
+Validates that the field is not blank.
+
+```yaml
+validations:
+  - type: presence
+```
+
+> **Not for boolean fields.** `false.present? == false`, so `validates :presence` on a `:boolean` field rejects valid `false` values (a Rails footgun). `bundle exec rake lcp_ruby:validate` reports this as an error and offers three resolutions:
+>
+> - Drop the validator and declare `null: false` on the column. Phase 4b auto-applies `inclusion: { in: [true, false] }` at runtime.
+> - Replace with explicit `validates :inclusion, options: { in: [true, false] }`.
+> - If the field has three meaningful states (yes / no / pending), switch from nullable boolean to `enum` — `null:` boolean tri-state is a data-modeling antipattern (standard checkboxes don't preserve `nil`, `WHERE flag = false` doesn't catch `NULL` rows).
+
+With conditional options:
+
+```yaml
+validations:
+  - type: presence
+    options: { if: "requires_title?" }
+```
+
+#### `length`
+
+Validates string length.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `minimum` | integer | Minimum length |
+| `maximum` | integer | Maximum length |
+| `is` | integer | Exact length |
+| `in` | range | Length range (e.g., `3..100`) |
+
+```yaml
+validations:
+  - type: length
+    options: { minimum: 3, maximum: 100 }
+```
+
+#### `numericality`
+
+Validates numeric constraints.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `greater_than` | number | Must be > value |
+| `greater_than_or_equal_to` | number | Must be >= value |
+| `less_than` | number | Must be < value |
+| `less_than_or_equal_to` | number | Must be <= value |
+| `equal_to` | number | Must be exactly value |
+| `allow_nil` | boolean | Skip validation when nil |
+
+```yaml
+validations:
+  - type: numericality
+    options: { greater_than_or_equal_to: 0, allow_nil: true }
+```
+
+#### `format`
+
+Validates against a regular expression.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `with` | string | Regex pattern (converted to `Regexp` at runtime) |
+
+```yaml
+validations:
+  - type: format
+    options: { with: "\\A[a-zA-Z0-9]+\\z" }
+```
+
+#### `inclusion`
+
+Validates that the value is in a given set.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `in` | array | Allowed values |
+
+```yaml
+validations:
+  - type: inclusion
+    options: { in: [low, medium, high] }
+```
+
+#### `exclusion`
+
+Validates that the value is not in a given set.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `in` | array | Excluded values |
+
+```yaml
+validations:
+  - type: exclusion
+    options: { in: [banned, restricted] }
+```
+
+#### `uniqueness`
+
+Validates uniqueness of the value.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `scope` | string or array | Columns to scope uniqueness to |
+| `case_sensitive` | boolean | Case-sensitive comparison |
+
+```yaml
+validations:
+  - type: uniqueness
+    options: { scope: company_id, case_sensitive: false }
+```
+
+#### `confirmation`
+
+Validates that a `<field>_confirmation` attribute matches the field.
+
+```yaml
+validations:
+  - type: confirmation
+```
+
+#### `custom`
+
+Delegates to a custom validator class. The class must inherit from `ActiveModel::Validator`.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `validator_class` | string | Fully qualified class name |
+
+```yaml
+# Field-level custom validation
+fields:
+  - name: email
+    type: string
+    validations:
+      - type: custom
+        validator_class: "EmailFormatValidator"
+
+# Model-level custom validation
+validations:
+  - type: custom
+    validator_class: "BusinessRuleValidator"
+```
+
+#### `comparison`
+
+Compares the field value against another field on the same record. Skipped when either value is nil.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `operator` | string | Comparison operator: `gt`, `gte`, `lt`, `lte`, `eq`, `not_eq` |
+| `field_ref` | string | Name of the field to compare against |
+| `message` | string | Custom error message |
+
+```yaml
+fields:
+  - name: due_date
+    type: date
+    validations:
+      - type: comparison
+        operator: gte
+        field_ref: start_date
+        message: "must be on or after start date"
+```
+
+```ruby
+# DSL
+field :due_date, :date do
+  validates :comparison, operator: :gte, field_ref: :start_date,
+    message: "must be on or after start date"
+end
+```
+
+#### `service`
+
+Delegates validation to a registered service class. The service receives the record and can add errors.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `service` | string | Service key registered in `app/lcp_services/validators/` |
+
+```yaml
+# Model-level service validation
+validations:
+  - type: service
+    service: deal_credit_limit
+```
+
+```ruby
+# DSL
+validates_model :service, service: "deal_credit_limit"
+```
+
+Service contract: `def self.call(record, **opts) -> void` (adds errors directly to `record.errors`). Register in `app/lcp_services/validators/`. See [Extensibility Guide](../guides/extensibility.md).
+
+#### `array_length`
+
+Validates the number of items in an array field.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `minimum` | integer | Minimum number of items |
+| `maximum` | integer | Maximum number of items |
+
+```yaml
+fields:
+  - name: tags
+    type: array
+    item_type: string
+    validations:
+      - type: array_length
+        options: { minimum: 1, maximum: 10 }
+```
+
+```ruby
+# DSL
+field :tags, :array, item_type: :string do
+  validates :array_length, minimum: 1, maximum: 10
+end
+```
+
+#### `array_inclusion`
+
+Validates that all items in the array are within an allowed set.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `in` | array | Allowed values |
+
+```yaml
+fields:
+  - name: tags
+    type: array
+    item_type: string
+    validations:
+      - type: array_inclusion
+        options: { in: [ruby, python, java, go, rust] }
+```
+
+```ruby
+# DSL
+field :tags, :array, item_type: :string do
+  validates :array_inclusion, in: %w[ruby python java go rust]
+end
+```
+
+#### `array_uniqueness`
+
+Validates that all items in the array are unique (no duplicates).
+
+```yaml
+fields:
+  - name: tags
+    type: array
+    item_type: string
+    validations:
+      - type: array_uniqueness
+```
+
+```ruby
+# DSL
+field :tags, :array, item_type: :string do
+  validates :array_uniqueness
+end
+```
+
+### Conditional Validations (`when:`)
+
+Any validation can be made conditional using the `when:` key. When present, the validation only runs if the condition evaluates to true. The condition uses the same `{ field:, operator:, value: }` syntax as [`visible_when`](presenters.md#field-visibility) and [`condition`](condition-operators.md).
+
+```yaml
+fields:
+  - name: value
+    type: decimal
+    validations:
+      - type: presence
+        when:
+          field: stage
+          operator: not_in
+          value: [lead]
+      - type: numericality
+        options: { greater_than_or_equal_to: 0, allow_nil: true }
+```
+
+```ruby
+# DSL
+field :value, :decimal do
+  validates :presence, when: { field: :stage, operator: :not_in, value: %w[lead] }
+  validates :numericality, greater_than_or_equal_to: 0, allow_nil: true
+end
+```
+
+Service-based conditions are also supported:
+
+```yaml
+validations:
+  - type: presence
+    when:
+      service: requires_approval
+```
+
+### Common Validation Options
+
+These options can be added to any validation type:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `message` | string | Custom error message |
+| `allow_blank` | boolean | Skip validation when value is blank |
+| `if` | string | Method name; only validate when method returns true |
+| `unless` | string | Method name; skip validation when method returns true |
+
+```yaml
+validations:
+  - type: presence
+    options: { message: "must be provided", if: "active?" }
+  - type: numericality
+    options: { greater_than: 0, allow_blank: true, unless: "draft?" }
+```
+
+The `if` and `unless` options reference method names on the model instance. These methods must be defined in a model extension or custom validator.
+
+## Associations
+
+Associations define relationships between models.
+
+```yaml
+associations:
+  # Standard belongs_to
+  - type: belongs_to
+    name: company
+    target_model: company
+    foreign_key: company_id
+    required: true
+    inverse_of: employees
+
+  # Polymorphic belongs_to (creates _id + _type columns automatically)
+  - type: belongs_to
+    name: commentable
+    polymorphic: true
+    required: false
+
+  # has_many with polymorphic inverse
+  - type: has_many
+    name: comments
+    target_model: comment
+    as: commentable
+
+  # has_many through (join model)
+  - type: has_many
+    name: taggings
+    target_model: tagging
+  - type: has_many
+    name: tags
+    through: taggings
+    source: tag
+
+  # Join on a business key instead of the target's primary key.
+  # The owner's `division_code` matches `divisions.vema_code`.
+  - type: belongs_to
+    name: division
+    target_model: division
+    foreign_key: division_code
+    primary_key: vema_code
+    required: false
+```
+
+### Association Attributes
+
+#### `type`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Allowed** | `belongs_to`, `has_many`, `has_one` |
+
+The ActiveRecord association type.
+
+#### `name`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string |
+
+The association name. Used as the method name on the model (e.g., `record.company`).
+
+#### `target_model`
+
+| | |
+|---|---|
+| **Required** | conditionally (see below) |
+| **Type** | string |
+
+Name of another LCP model. The engine resolves this to `LcpRuby::Dynamic::<TargetModel>` at runtime. Use this for associations between LCP-managed models.
+
+At least one of `target_model`, `class_name`, `polymorphic`, `as`, or `through` must be present.
+
+```yaml
+- type: belongs_to
+  name: todo_list
+  target_model: todo_list
+  foreign_key: todo_list_id
+```
+
+#### `class_name`
+
+| | |
+|---|---|
+| **Required** | conditionally (see `target_model`) |
+| **Type** | string |
+
+Fully qualified class name for associations pointing to non-LCP models (e.g., your host app's `User` model). When `target_model` is set, `class_name` is ignored — the engine generates it automatically.
+
+```yaml
+- type: belongs_to
+  name: author
+  class_name: "User"
+  foreign_key: author_id
+```
+
+#### `foreign_key`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | Rails convention (`<name>_id` for `belongs_to`) |
+| **Type** | string |
+
+The foreign key column name. Specify this when the column name does not follow Rails naming conventions.
+
+#### `primary_key`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | target model's primary key column (usually `id`) |
+| **Type** | string |
+| **Applies to** | `belongs_to`, `has_many`, `has_one` (not `through:`, not `polymorphic:`) |
+
+Column on the PK side of the join that the `foreign_key` matches against. Mirrors Rails's native `primary_key:` option and lets associations join on a natural business key (`vema_code`, `iso_code`, `sku`, ...) instead of a surrogate `id`.
+
+**Semantics — the join pair depends on association type:**
+
+| Association type (declared on *owner*) | Effective join pair |
+|---|---|
+| `belongs_to` | `owner.foreign_key  =  target.primary_key` |
+| `has_many` (non-`through`) | `target.foreign_key  =  owner.primary_key` |
+| `has_one` (non-`through`) | `target.foreign_key  =  owner.primary_key` |
+
+```yaml
+# On employee — belongs_to joins to a non-PK column on the target
+- type: belongs_to
+  name: division
+  target_model: division
+  foreign_key: division_code
+  primary_key: vema_code    # employees.division_code = divisions.vema_code
+  required: false
+
+# On division — reverse side, same join pair
+- type: has_many
+  name: employees
+  target_model: employee
+  foreign_key: division_code
+  primary_key: vema_code    # employees.division_code = divisions.vema_code
+```
+
+**FK column type.** When `primary_key:` points at an LCP model's field, the auto-created FK column on the `belongs_to` side matches that field's type instead of the default `bigint`. For a `belongs_to :division, primary_key: :vema_code` where `divisions.vema_code` is `integer`, the engine creates `employees.division_code` as `integer`. For string business keys (`"EUR"`, `"0042"`), the FK is created as `string`.
+
+When `primary_key:` points at a non-LCP class (`class_name:` without `target_model:`), LCP cannot introspect the target column's type — the configurator **must** declare the FK column explicitly via `fields:`:
+
+```yaml
+fields:
+  - name: division_code
+    type: string              # must match the external column type
+
+associations:
+  - type: belongs_to
+    name: division
+    class_name: "::HostDivision"
+    foreign_key: division_code
+    primary_key: vema_code
+```
+
+Without the explicit field, `ConfigurationValidator` appends an error at boot.
+
+**Boot-time validation** (runs via `bundle exec rake lcp_ruby:validate`):
+
+- The referenced column must exist on the PK side (target for `belongs_to`, owner for `has_many`/`has_one`).
+- A warning fires when the column has no uniqueness constraint (unscoped `validates … uniqueness: true` or a single-column unique `indexes:` entry). Scoped uniqueness emits a softer warning pointing at `query_constraints:` as the proper fix for partition-scoped joins.
+- A warning fires when the FK and PK column types differ.
+- A warning fires when the FK is declared as an explicit `field:` but has no covering `indexes:` entry — auto-indexing does not cover explicit FK fields, so joins would silently degrade to table scans.
+- A warning fires when the forward and inverse associations declare different join pairs (reciprocity alignment).
+
+**Rejected configurations** (hard errors):
+
+- `primary_key:` together with `through:` — put it on the individual link associations instead.
+- `primary_key:` together with `polymorphic: true` — each polymorphic target can have a different PK column; there is no single column that makes sense.
+- `primary_key:` on tree-managed self-referencing associations (the recursive CTE hardcodes `id`-based joins — out of scope for v1).
+- `primary_key:` on cross-source (DB ↔ API) associations — the API applicator has its own `id`-based lookup paths that do not yet read the join column (out of scope for v1).
+
+**`bind_to:` models.** `primary_key:` is allowed on associations whose target is a `bind_to` model (LCP reads the YAML to render form selects, cascading selects, tree selects, [page filter form fields](page_filters.md), import/export metadata, and virtual-column SQL). The host AR class is responsible for declaring its own Rails macro-level `primary_key:`. Uniqueness and type-compat checks are skipped for `bind_to` targets because LCP cannot introspect the host schema — to opt back into the column-exists check, list the join column in the `bind_to` model's YAML `fields:`.
+
+**Migration note — redundant denormalized columns.** The common motivation for this feature is dropping denormalized columns (`division_code` + `division_name` + `bu_code` + `bu_name`) in favor of a single FK that joins on the business code. The migration steps are:
+
+1. Add `primary_key:` to the association in YAML.
+2. Remove the redundant field entries (`division_name`, `bu_code`, `bu_name`, ...) from the owner model.
+3. Update any host code that referenced the redundant fields to traverse via the association (`record.division.vema_name`, `record.division.business_unit.vema_name`, ...).
+
+LCP's auto-migration is additive — removing a YAML field leaves the column in the DB. A manual SQL migration to drop the column is optional and host-app-specific.
+
+See [design/association_primary_key.md](../design/association_primary_key.md) for the full feature specification, including every downstream consumer that was updated (form helpers, cascading selects, tree selects, page parameters [retired in PR 5; replaced by [filter forms](page_filters.md)], import/export field trees, virtual columns).
+
+#### `dependent`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none |
+| **Type** | string |
+| **Allowed** | `destroy`, `delete`, `delete_all`, `nullify`, `restrict_with_error`, `restrict_with_exception`, `discard` |
+
+What happens to associated records when the parent is destroyed (or discarded). Applicable to all association types.
+
+The `discard` value is special — it is **not** passed to ActiveRecord. Instead, when the parent record is discarded (soft-deleted), the `SoftDeleteApplicator` cascades the discard to child records with `dependent: :discard`. This requires:
+- The parent model must have `soft_delete` enabled
+- The target (child) model must also have `soft_delete` enabled
+- Only valid on `has_many` / `has_one` associations (not `belongs_to`)
+
+#### `required`
+
+| | |
+|---|---|
+| **Required** | no (but **strongly recommended on `belongs_to`** — see note) |
+| **Default** | `true` for `belongs_to` (AR Rails 5+), `false` for `has_many`/`has_one` |
+| **Type** | boolean |
+
+Whether the association is mandatory. For `belongs_to`, setting `required: false` allows the foreign key to be NULL.
+
+> **Always set `required:` explicitly on `belongs_to`.** Omitting it inherits the AR Rails 5+ default (`required: true`), which silently rejects nullable parents at save time. `bundle exec rake lcp_ruby:validate` warns whenever a `belongs_to` declaration lacks an explicit `required:` kwarg. The `lcp_ruby:entity` generator emits it for every generated association.
+
+#### `inverse_of`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none (Rails auto-detection) |
+| **Type** | string |
+| **Applies to** | all types |
+
+Specifies the inverse association on the target model. Rails usually infers this, but explicit setting avoids ambiguity and improves performance by preventing extra queries.
+
+```yaml
+associations:
+  - type: has_many
+    name: tasks
+    target_model: task
+    inverse_of: project
+```
+
+#### `counter_cache`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none |
+| **Type** | boolean or string |
+| **Applies to** | `belongs_to` |
+
+Maintains a count column on the parent model. Set to `true` to use the default column name (`<children>_count`), or a string for a custom column name.
+
+The counter column must be added as a field on the parent model.
+
+```yaml
+# On child model
+associations:
+  - type: belongs_to
+    name: project
+    target_model: project
+    counter_cache: true
+
+# Or with custom column name
+    counter_cache: tasks_count
+```
+
+#### `touch`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none |
+| **Type** | boolean or string |
+| **Applies to** | `belongs_to` |
+
+Updates the parent's `updated_at` timestamp when the child is saved. Set to `true` for `updated_at`, or a string for a custom timestamp column.
+
+```yaml
+associations:
+  - type: belongs_to
+    name: project
+    target_model: project
+    touch: true
+```
+
+#### `polymorphic`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+| **Applies to** | `belongs_to` |
+
+Creates a polymorphic association. When `true`, the engine automatically creates both `<name>_id` and `<name>_type` columns. No `target_model` or `class_name` is needed — the type is determined at runtime from the `_type` column.
+
+```yaml
+# On child model (e.g., comment)
+associations:
+  - type: belongs_to
+    name: commentable
+    polymorphic: true
+    required: false
+```
+
+#### `as`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none |
+| **Type** | string |
+| **Applies to** | `has_many`, `has_one` |
+
+The polymorphic interface name on the target model. Used with `polymorphic` belongs_to on the other side.
+
+```yaml
+# On parent model (e.g., post)
+associations:
+  - type: has_many
+    name: comments
+    target_model: comment
+    as: commentable
+```
+
+#### `through`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none |
+| **Type** | string |
+| **Applies to** | `has_many`, `has_one` |
+
+Creates a through association via a join model. The value is the name of another association on this model that serves as the join. No FK columns are created for through associations.
+
+```yaml
+associations:
+  - type: has_many
+    name: taggings
+    target_model: tagging
+  - type: has_many
+    name: tags
+    through: taggings
+```
+
+#### `source`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none (Rails infers from association name) |
+| **Type** | string |
+| **Applies to** | `has_many`, `has_one` (with `through`) |
+
+Specifies the source association on the join model. Only needed when the name cannot be inferred automatically.
+
+```yaml
+associations:
+  - type: has_many
+    name: authors
+    through: authorships
+    source: person
+```
+
+#### `autosave`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none (Rails default) |
+| **Type** | boolean |
+| **Applies to** | all types |
+
+When `true`, saves associated records whenever the parent is saved.
+
+```yaml
+associations:
+  - type: has_many
+    name: items
+    target_model: item
+    autosave: true
+```
+
+#### `validate`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none (Rails default) |
+| **Type** | boolean |
+| **Applies to** | all types |
+
+When `true`, validates associated records on save. Set to `false` to skip validation of associated records.
+
+```yaml
+associations:
+  - type: has_many
+    name: items
+    target_model: item
+    validate: false
+```
+
+#### `order`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none |
+| **Type** | hash |
+| **Applies to** | `has_many`, `has_one` |
+
+Default ordering for associated records. The engine passes this as a scope lambda to the ActiveRecord association. Keys are column names, values are `asc` or `desc`.
+
+```yaml
+associations:
+  - type: has_many
+    name: todo_items
+    target_model: todo_item
+    order:
+      position: asc
+```
+
+This generates: `has_many :todo_items, -> { order(position: :asc) }, ...`
+
+Useful for sortable nested forms where child records have a position field.
+
+#### `skip_inverse_check`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+| **Applies to** | `belongs_to` only |
+
+Suppresses the missing-inverse warning from `lcp_ruby:validate`. Use when a `belongs_to` is intentionally one-directional and you don't want a `has_many` on the parent side.
+
+**When to use:** audit/owner/author references where reverse traversal would be noise.
+
+```yaml
+associations:
+  - type: belongs_to
+    name: author
+    target_model: teacher
+    skip_inverse_check: true   # `teacher.has_many :authored_announcements` would be unused noise
+  - type: belongs_to
+    name: created_by
+    target_model: user
+    skip_inverse_check: true   # `user.has_many :created_things` × N tables: clutter
+```
+
+**When NOT to use:** the inverse would actually be queried (`teacher.school_classes`, `school_class.students`). Adding the `has_many` is the right move; this flag exists for the cases where it isn't.
+
+**Validation.** `skip_inverse_check: true` on `has_many` or `has_one` raises `MetadataError` at boot — that case (a parent declaring children with no `belongs_to` back) is a genuine bug because the FK has nowhere to go.
+
+## Nested Attributes
+
+Associations can declare `nested_attributes` to enable creating and updating associated records through the parent model's form and the import system. This uses Rails' `accepts_nested_attributes_for` under the hood.
+
+### Boolean Shorthand
+
+For `has_one` associations, the recommended form is the boolean shorthand:
+
+```yaml
+associations:
+  - type: has_one
+    name: employee_profile
+    target_model: employee_profile
+    dependent: destroy
+    inverse_of: employee
+    nested_attributes: true    # safe defaults: reject_if: all_blank, update_only: true
+```
+
+`nested_attributes: true` is equivalent to `{ reject_if: all_blank, update_only: true }`. These defaults are safe for both forms and import:
+- `reject_if: all_blank` prevents creating empty nested records when all fields are blank
+- `update_only: true` updates existing nested records in-place instead of destroying and recreating them (which would break foreign key references)
+
+### Explicit Hash Form
+
+For fine-grained control, use the explicit hash:
+
+```yaml
+associations:
+  - type: has_many
+    name: todo_items
+    target_model: todo_item
+    dependent: destroy
+    inverse_of: todo_list
+    nested_attributes:
+      allow_destroy: true
+      reject_if: all_blank
+      limit: 50
+      update_only: false
+```
+
+### Nested Attributes Keys
+
+#### `allow_destroy`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+When `true`, nested records can be marked for deletion by passing `_destroy: true` in the nested attributes hash. Without this option, nested records can only be created and updated, not removed through the parent form.
+
+```yaml
+nested_attributes:
+  allow_destroy: true
+```
+
+#### `reject_if`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none |
+| **Type** | string |
+
+Controls when nested records are silently rejected (not saved). The special value `"all_blank"` rejects any nested record where every attribute value is blank. This is useful for forms that render empty rows for new records — blank rows are ignored instead of causing validation errors.
+
+Can also be set to a symbol name referencing a custom method on the model that returns `true` to reject the record.
+
+```yaml
+nested_attributes:
+  reject_if: all_blank
+```
+
+#### `limit`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | none (unlimited) |
+| **Type** | integer |
+
+Maximum number of nested records that can be processed at once. If the incoming attributes hash contains more records than the limit, a `TooManyRecords` exception is raised. Use this to prevent abuse or accidental mass-creation of associated records.
+
+```yaml
+nested_attributes:
+  limit: 50
+```
+
+#### `update_only`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+When `true`, existing nested records are updated in-place instead of being destroyed and recreated. This preserves the nested record's ID, which is important when other records reference it via foreign keys.
+
+**Note:** Despite the name, `update_only: true` still allows **creating** new nested records when none exists. Rails' internal logic falls through to `build_<association>` when no existing record is found. The name only means "don't destroy+recreate existing records".
+
+```yaml
+nested_attributes:
+  update_only: true
+```
+
+### Requirements
+
+- The parent association **must** specify `inverse_of` for nested attributes to work correctly. Without `inverse_of`, Rails cannot properly link the parent and child records during validation, which can cause unexpected behavior or validation failures.
+- Nested attributes are used with `has_many` and `has_one` associations.
+- `has_one :through` associations are **not compatible** with `nested_attributes` (no direct FK). The `ConfigurationValidator` warns at boot if this is attempted.
+
+### Import Integration
+
+`has_one` associations with `nested_attributes` enabled are automatically available for import. See [Import Reference](import.md#nested-has_one-import) for details on:
+- Dot-notation column mapping (`hire_detail.starting_salary`)
+- `nested_associations` whitelist on the presenter
+- `nested_blank_strategy` for controlling blank value handling
+
+### Full Example
+
+```yaml
+model:
+  name: todo_list
+  label: "Todo List"
+
+  fields:
+    - name: name
+      type: string
+      validations:
+        - type: presence
+
+  associations:
+    - type: has_many
+      name: todo_items
+      target_model: todo_item
+      dependent: destroy
+      inverse_of: todo_list
+      nested_attributes:
+        allow_destroy: true
+        reject_if: all_blank
+        limit: 50
+```
+
+## Scopes
+
+Scopes define named query methods on the model.
+
+```yaml
+scopes:
+  - name: open_deals
+    where_not: { stage: [closed_won, closed_lost] }
+  - name: won
+    where: { stage: closed_won }
+  - name: recent           # order + limit only — no where
+    order: { created_at: desc }
+    limit: 10
+  - name: upcoming         # order-only sort helper
+    order: { due_at: asc }
+  - name: first_five       # limit-only cap
+    limit: 5
+```
+
+Only `name` is required — every other attribute (`where`, `where_not`, `order`, `limit`) is independently optional. Combine any subset, or use just one. Do not write `where: {}` to satisfy a perceived requirement; just omit it.
+
+### Scope Attributes
+
+#### `name`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string |
+
+The scope method name. Called as `ModelClass.scope_name` in queries and referenced from [predefined filters](presenters.md#search-configuration).
+
+#### `where`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | hash |
+
+Generates `scope :name, -> { where(...) }`. Keys are column names, values are the expected values (scalar or array).
+
+#### `where_not`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | hash |
+
+Generates `scope :name, -> { where.not(...) }`. Same syntax as `where` but negated.
+
+#### `order`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | hash |
+
+Generates ordering. Keys are column names, values are `asc` or `desc`.
+
+Valid column names are everything `SchemaManager` puts on the table: declared `field:` rows, `belongs_to` FK columns (incl. polymorphic `_type`), userstamps, timestamps when enabled, soft-delete column, positioning column, and `id`. The same set is accepted in `where:` / `where_not:`.
+
+#### `limit`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | integer |
+
+Limits the number of returned records. Combine with `order` for "top N" queries.
+
+#### `type`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Allowed** | `custom`, `parameterized` |
+
+- `custom` — the scope is not generated from YAML. Instead, it must be defined in Ruby code via a model extension. The scope entry in YAML serves as documentation and allows it to be referenced from predefined filters.
+- `parameterized` — the scope accepts typed parameters at runtime. The `parameters` attribute defines the parameter schema (see below). The actual scope must be defined in Ruby — either as a standard AR scope with keyword arguments, or as a `filter_*` interceptor method.
+
+#### `parameters`
+
+| | |
+|---|---|
+| **Required** | only when `type: parameterized` |
+| **Type** | array of parameter definitions |
+
+Each parameter has:
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `name` | string | yes | Parameter name (used as keyword argument) |
+| `type` | string | yes | One of: `boolean`, `string`, `integer`, `float`, `enum`, `date`, `datetime`, `model_select` |
+| `default` | any | no | Default value when the parameter is not provided |
+| `required` | boolean | no | Whether the parameter must be provided (default: `false`). If a required parameter is missing, the scope is skipped |
+| `min` | number | no | Minimum value (integer/float only). Values below this are clamped |
+| `max` | number | no | Maximum value (integer/float only). Values above this are clamped |
+| `values` | array | no | Allowed values (enum type only). Values not in the list are rejected |
+| `model` | string | no | Target model name (model_select only) |
+| `display_field` | string | no | Field to display in the select dropdown (model_select only) |
+
+### Parameterized Scopes
+
+Parameterized scopes let users configure scope arguments at runtime. Parameters are cast, validated, and clamped before being passed to the scope.
+
+```yaml
+scopes:
+  - name: created_recently
+    type: parameterized
+    parameters:
+      - name: days
+        type: integer
+        default: 30
+        min: 1
+        max: 365
+
+  - name: by_min_price
+    type: parameterized
+    parameters:
+      - name: min_price
+        type: float
+        default: 0.0
+        min: 0
+
+  - name: by_status_filter
+    type: parameterized
+    parameters:
+      - name: status
+        type: enum
+        values: [draft, published, archived]
+        required: true
+```
+
+The Ruby implementation can be either a standard scope or a `filter_*` interceptor:
+
+```ruby
+# Option A: AR scope with keyword arguments
+scope :created_recently, ->(days: 30) {
+  where("created_at >= ?", days.to_i.days.ago)
+}
+
+# Option B: filter_* interceptor (more flexible)
+def self.filter_by_min_price(scope, params, evaluator)
+  min = params[:min_price] || 0
+  scope.where("price >= ?", min)
+end
+```
+
+In the [query language](../design/advanced_search.md), parameterized scopes use `@` prefix syntax:
+
+```
+@created_recently(days: 7)
+@by_status_filter(status: 'published')
+```
+
+### Combined Scopes
+
+Scope attributes are additive — a single scope can combine `where`, `where_not`, `order`, and `limit`. They are also independent — any subset is valid (just `order:`, just `limit:`, `where:` + `order:` without `limit:`, etc.). Each attribute is applied only when present, so an order-only scope is `WHERE`-free SQL.
+
+```yaml
+scopes:
+  - name: top_open_deals
+    where_not: { stage: [closed_won, closed_lost] }
+    order: { value: desc }
+    limit: 5
+```
+
+This generates: `scope :top_open_deals, -> { where.not(stage: [...]).order(value: :desc).limit(5) }`
+
+### NULL / Empty Value Scopes
+
+YAML `null` maps to Ruby `nil`, which ActiveRecord translates to `WHERE column IS NULL`. This works in both `where` and `where_not` conditions.
+
+```yaml
+scopes:
+  # Records where phone is NULL
+  - name: without_phone
+    where:
+      phone: null
+
+  # Records where phone is NOT NULL
+  - name: with_phone
+    where_not:
+      phone: null
+
+  # Records where phone is NULL or empty string
+  - name: blank_phone
+    where:
+      phone: [null, ""]
+```
+
+Generated SQL:
+
+| Scope | SQL |
+|-------|-----|
+| `without_phone` | `WHERE phone IS NULL` |
+| `with_phone` | `WHERE phone IS NOT NULL` |
+| `blank_phone` | `WHERE phone IS NULL OR phone = ''` |
+
+## Events
+
+Events trigger [event handlers](../guides/event-handlers.md) in response to record changes.
+
+```yaml
+events:
+  - name: after_create
+    type: lifecycle
+  - name: on_stage_change
+    type: field_change
+    field: stage
+    condition:
+      field: stage
+      operator: not_in
+      value: [lead]
+```
+
+### Event Attributes
+
+#### `name`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string |
+
+Event identifier. Matched against `HandlerBase.handles_event` in registered handlers. For lifecycle events, use one of the predefined names.
+
+#### `type`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | inferred from `name` |
+| **Allowed** | `lifecycle`, `field_change` |
+
+- `lifecycle` — triggered by ActiveRecord callbacks
+- `field_change` — triggered when a specific field's value changes during an update
+
+If omitted, the type is inferred: names matching `after_create`, `after_update`, `before_destroy`, or `after_destroy` are treated as lifecycle; all others as field_change.
+
+#### `field`
+
+| | |
+|---|---|
+| **Required** | yes (for `field_change` type) |
+| **Type** | string |
+
+The field to monitor for changes. The event fires only when this field's value changes.
+
+#### `condition`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | hash (recommended) or string (deprecated) |
+
+Optional condition that must be met for the event to fire. Uses the same `{ field:, operator:, value: }` syntax as [condition operators](condition-operators.md). When a `field_change` event fires, the condition is evaluated against the record's current state — the event is only dispatched if the condition returns true.
+
+```yaml
+# Hash condition (recommended)
+events:
+  - name: on_stage_change
+    type: field_change
+    field: stage
+    condition:
+      field: stage
+      operator: not_eq
+      value: draft
+```
+
+```ruby
+# DSL
+on_field_change :on_stage_change, field: :stage,
+  condition: { field: :stage, operator: :not_in, value: %w[lead] }
+```
+
+> **Deprecated:** String conditions (evaluated via `instance_eval`) are deprecated and will be removed in a future version. Migrate to Hash conditions.
+
+### Lifecycle Events
+
+| Name | Trigger |
+|------|---------|
+| `after_create` | After a new record is created |
+| `after_update` | After an existing record is updated |
+| `before_destroy` | Before a record is destroyed |
+| `after_destroy` | After a record is destroyed |
+
+## Display Templates
+
+Display templates define rich HTML representations for records when displayed in contexts like `association_list`. Unlike `to_label` (which remains plain text), display templates support structured layouts with titles, subtitles, icons, and badges — or delegate to custom renderers/partials.
+
+Templates live on the **model** (not the presenter), so the same record can be rendered consistently across different presenters. The presenter selects which template to use by name.
+
+### YAML Syntax
+
+```yaml
+display_templates:
+  default:
+    template: "{first_name} {last_name}"
+    subtitle: "{position} at {company.name}"
+    icon: user
+    badge: "{status}"
+  compact:
+    template: "{last_name}, {first_name}"
+  card:
+    renderer: ContactCardRenderer
+  mini:
+    partial: "contacts/mini_label"
+```
+
+### Three Forms
+
+| Form | Detected by | Description |
+|------|-------------|-------------|
+| **Structured** | `template` key | Title, optional subtitle/icon/badge with `{field}` interpolation |
+| **Renderer** | `renderer` key | Delegates to a registered `Display::BaseRenderer` subclass |
+| **Partial** | `partial` key | Renders a Rails partial with `record` local |
+
+### Structured Template Keys
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `template` | string | **Required.** Main text with `{field}` placeholders |
+| `subtitle` | string | Secondary text below the title |
+| `icon` | string | Icon identifier (rendered as text; style via CSS) |
+| `badge` | string | Small label, supports `{field}` placeholders |
+
+Field placeholders use the same dot-path syntax as presenter fields: `{field_name}` for direct fields, `{association.field}` for related records. The exact same `{field}` micro-syntax is also accepted by the [`computed`](#computed) field attribute when used in template form — both go through the same parser.
+
+### Renderer Form
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `renderer` | string | Class name of a registered `Display::BaseRenderer` |
+| `options` | hash | Passed to the renderer's `render` method |
+
+### Partial Form
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `partial` | string | Rails partial path (e.g., `"contacts/mini_label"`) |
+
+### DSL Syntax
+
+```ruby
+define_model :contact do
+  display_template :default,
+    template: "{first_name} {last_name}",
+    subtitle: "{position} at {company.name}",
+    icon: "user"
+
+  display_template :card, renderer: "ContactCardRenderer"
+  display_template :mini, partial: "contacts/mini_label"
+end
+```
+
+### Permission Filtering
+
+Fields referenced in templates are resolved through `FieldValueResolver`, which respects the current user's `PermissionEvaluator`. If a field is not readable, it renders as blank rather than exposing unauthorized data.
+
+### Eager Loading
+
+The `IncludesResolver` automatically detects dot-path fields in display templates (e.g., `{company.name}`) and generates nested eager loading (e.g., `{ contacts: :company }`) to prevent N+1 queries.
+
+## Virtual Columns
+
+Virtual computed columns that are not stored in the database — they are calculated at query time and injected into SELECT statements. Virtual columns can be referenced in presenter table columns and show sections just like regular fields. They support sorting, conditional rendering (`visible_when`, `item_classes`), and type coercion.
+
+Virtual column names must not collide with field names on the same model.
+
+The `virtual_columns` key is the unified replacement for the older `aggregates` key. Both keys are accepted and merged — see [Backward Compatibility](#backward-compatibility) below.
+
+### YAML Syntax
+
+```yaml
+virtual_columns:
+  # Declarative aggregate (same as before)
+  issues_count:
+    function: count
+    association: issues
+
+  open_issues_count:
+    function: count
+    association: issues
+    where: { status: open }
+
+  total_revenue:
+    function: sum
+    association: orders
+    source_field: amount
+    default: 0
+
+  # Expression — inline SQL expression (replaces "sql" key)
+  is_overdue:
+    expression: "CASE WHEN %{table}.due_date < CURRENT_DATE THEN 1 ELSE 0 END"
+    type: boolean
+
+  # Expression with JOIN — pull data from another table
+  company_name:
+    expression: "companies.name"
+    join: "LEFT JOIN companies ON companies.id = %{table}.company_id"
+    type: string
+
+  # Expression with JOIN + GROUP BY — aggregate across a joined table
+  total_value:
+    expression: "COALESCE(SUM(line_items.quantity * line_items.unit_price), 0)"
+    join: "LEFT JOIN line_items ON line_items.order_id = %{table}.id"
+    group: true
+    type: decimal
+
+  # Auto-include — always loaded, even when not explicitly referenced
+  priority_score:
+    expression: "(%{table}.urgency * 10 + %{table}.impact * 5)"
+    type: integer
+    auto_include: true
+
+  # Service — Ruby service class
+  health_score:
+    service: project_health
+    type: integer
+```
+
+### DSL Syntax
+
+```ruby
+virtual_column :issues_count, function: :count, association: :issues
+virtual_column :open_issues_count, function: :count, association: :issues,
+  where: { status: "open" }
+virtual_column :total_revenue, function: :sum, association: :orders,
+  source_field: :amount, default: 0
+virtual_column :is_overdue,
+  expression: "CASE WHEN %{table}.due_date < CURRENT_DATE THEN 1 ELSE 0 END",
+  type: :boolean
+virtual_column :company_name,
+  expression: "companies.name",
+  join: "LEFT JOIN companies ON companies.id = %{table}.company_id",
+  type: :string
+virtual_column :total_value,
+  expression: "COALESCE(SUM(line_items.quantity * line_items.unit_price), 0)",
+  join: "LEFT JOIN line_items ON line_items.order_id = %{table}.id",
+  group: true,
+  type: :decimal
+
+# Legacy alias still works
+aggregate :contacts_count, function: :count, association: :contacts
+```
+
+### Four Virtual Column Types
+
+| Type | Detected by | Description |
+|------|-------------|-------------|
+| **Declarative** | `function` + `association` | SQL aggregate function over a has_many association (correlated subquery) |
+| **Expression** | `expression` key | Inline SQL expression injected into SELECT |
+| **Expression + JOIN** | `expression` + `join` | SQL expression that requires a JOIN clause |
+| **Service** | `service` key | Ruby service class from `app/lcp_services/virtual_columns/` (or `aggregates/`) |
+
+### Declarative Attributes
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `function` | string | yes | SQL aggregate function: `count`, `sum`, `min`, `max`, `avg` |
+| `association` | string | yes | Name of a `has_many` association on the model |
+| `source_field` | string | for sum/min/max/avg | Field on the target model to aggregate. Optional for `count` (defaults to `*`) |
+| `where` | hash | no | Equality conditions on the target model (see [Where Conditions](#where-conditions)) |
+| `distinct` | boolean | no | Use `DISTINCT` in the aggregate function (default: `false`) |
+| `default` | any | no | Default value via `COALESCE`. `count` always defaults to `0` even without this |
+| `include_discarded` | boolean | no | Include soft-deleted records (default: `false`). Only relevant when the target model uses `soft_delete` |
+
+### Expression Attributes
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `expression` | string | yes | SQL expression. Use `%{table}` for the parent model's quoted table name |
+| `type` | string | yes | Result type: `string`, `integer`, `float`, `decimal`, `boolean`, `date`, `datetime`, `json` |
+| `default` | any | no | Default value via `COALESCE` |
+| `join` | string | no | SQL JOIN clause to add. Use `%{table}` for the parent table name |
+| `group` | boolean | no | Whether this column requires `GROUP BY parent_table.id` (default: `false`) |
+| `auto_include` | boolean | no | Always include this column in queries, even when not referenced by the presenter (default: `false`) |
+
+**Notes:**
+- `auto_include: true` and `group: true` cannot be combined on the same column.
+- `auto_include: true` only affects controller queries. Direct model queries (`Model.find`, `Model.where`) from custom actions, event handlers, or other Ruby code do not include virtual columns — use `VirtualColumns::Builder.apply` explicitly.
+- The `join` attribute is a single string, not an array. Concatenate multiple JOINs in one string if needed.
+
+The legacy `sql` key is accepted as an alias for `expression`. You cannot specify both `sql` and `expression` on the same column.
+
+### Service Attributes
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `service` | string | yes | Service key looked up in `app/lcp_services/virtual_columns/` (falls back to `app/lcp_services/aggregates/`) |
+| `type` | string | yes | Result type |
+| `options` | hash | no | Options hash passed to the service's `call` method |
+
+The service class must implement `self.call(record, options:)`. Optionally implement `self.sql_expression(model_class, options:)` to return a SQL string — this enables sorting and avoids per-record evaluation.
+
+**Note:** Service virtual columns without `sql_expression` are only resolved on show/edit pages (per-record via `call`). On index pages, they return `nil` — if referenced in `table_columns` or `item_classes`, the display will be empty and conditions will evaluate incorrectly.
+
+### Expression Details
+
+#### `%{table}` Placeholder
+
+The `%{table}` placeholder is replaced with the parent model's quoted table name at query time. Always use it to reference the parent table:
+
+```yaml
+# Good — portable across table names
+expression: "CASE WHEN %{table}.due_date < CURRENT_DATE THEN 1 ELSE 0 END"
+
+# Bad — hardcoded table name
+expression: "CASE WHEN orders.due_date < CURRENT_DATE THEN 1 ELSE 0 END"
+```
+
+#### JOIN Clause
+
+The `join` attribute adds a SQL JOIN to the query. Multiple virtual columns can specify JOINs — duplicates are automatically deduplicated (compared case-insensitively after whitespace normalization):
+
+```yaml
+virtual_columns:
+  company_name:
+    expression: "companies.name"
+    join: "LEFT JOIN companies ON companies.id = %{table}.company_id"
+    type: string
+  company_country:
+    expression: "companies.country"
+    join: "LEFT JOIN companies ON companies.id = %{table}.company_id"
+    type: string
+```
+
+Both columns reference the same JOIN — it is applied only once.
+
+#### GROUP BY
+
+When `group: true` is set, the query adds `GROUP BY parent_table.id`. This is needed when the expression uses aggregate functions over joined rows:
+
+```yaml
+total_value:
+  expression: "COALESCE(SUM(line_items.quantity * line_items.unit_price), 0)"
+  join: "LEFT JOIN line_items ON line_items.order_id = %{table}.id"
+  group: true
+  type: decimal
+```
+
+**Caution:** Multiple JOINs combined with `group: true` can produce cartesian products (e.g., 3 line_items × 2 payments = 6 rows per order, inflating SUM results). When aggregating over multiple joined tables, prefer correlated subqueries in `expression:` instead of `join:` + `group:`:
+
+```yaml
+# Good — independent correlated subqueries, no cartesian product
+total_line_value:
+  expression: "(SELECT COALESCE(SUM(li.quantity * li.unit_price), 0) FROM line_items li WHERE li.order_id = %{table}.id)"
+  type: decimal
+total_payments:
+  expression: "(SELECT COALESCE(SUM(p.amount), 0) FROM payments p WHERE p.order_id = %{table}.id)"
+  type: decimal
+
+# Avoid — two joins with group = cartesian risk
+```
+
+Reserve `join:` + `group: true` for cases where a single JOIN + GROUP is genuinely needed.
+
+#### Auto-Include
+
+Columns with `auto_include: true` are always loaded in every query context (index, show, edit) regardless of whether the presenter references them. This is useful for columns needed by conditional rendering or business logic:
+
+```yaml
+priority_score:
+  expression: "(%{table}.urgency * 10 + %{table}.impact * 5)"
+  type: integer
+  auto_include: true
+```
+
+### Where Conditions
+
+The `where` hash applies equality conditions to **declarative** aggregate subqueries only. Expression columns embed their own WHERE conditions directly in the SQL string.
+
+```yaml
+where: { status: open }                         # WHERE status = 'open'
+where: { status: [open, in_progress] }           # WHERE status IN ('open', 'in_progress')
+where: { deleted_at: null }                      # WHERE deleted_at IS NULL
+where: { status: active, priority: high }        # WHERE status = 'active' AND priority = 'high'
+where: { assignee_id: :current_user }            # WHERE assignee_id = <current_user.id>
+```
+
+The `:current_user` placeholder resolves to `current_user.id` at query time. When no user is signed in, it resolves to `nil` (producing `IS NULL`). This enables per-user aggregates like "my open issues count".
+
+### Type Inference
+
+Declarative aggregates infer their result type automatically:
+
+| Function | Inferred type |
+|----------|---------------|
+| `count` | `integer` (always) |
+| `sum`, `min`, `max` | Same as `source_field` type |
+| `avg` | `float` (or `decimal` if source is `decimal`) |
+
+Expression and service virtual columns require an explicit `type` attribute.
+
+### Type Coercion
+
+Virtual columns register an ActiveRecord `attribute` declaration at boot time, ensuring consistent Ruby types regardless of database adapter. For example, SQLite returns `0`/`1` for booleans while PostgreSQL returns `true`/`false` — the `attribute :is_overdue, :boolean` declaration normalizes both to Ruby `true`/`false`.
+
+| Virtual column `type` | Ruby class |
+|----------------------|------------|
+| `string` | `String` |
+| `integer` | `Integer` |
+| `float` | `Float` |
+| `decimal` | `BigDecimal` |
+| `boolean` | `TrueClass`/`FalseClass` |
+| `date` | `Date` |
+| `datetime` | `Time` |
+| `text` | `String` |
+
+**NULL safety for booleans:** SQL boolean expressions like `(due_date < CURRENT_DATE AND status != 'done')` return NULL (not FALSE) when any operand is NULL (e.g., `due_date` is NULL). After type coercion, `nil` ≠ `false` — a condition `{ operator: eq, value: false }` would not match `nil`. Use `default: false` on boolean virtual columns that use arithmetic/comparison operators. Exception: `EXISTS(...)` always returns TRUE/FALSE (never NULL), so `default:` is not needed for EXISTS expressions.
+
+### Soft Delete Awareness
+
+When the target model uses `soft_delete`, **declarative** aggregates automatically exclude soft-deleted records (`WHERE discarded_at IS NULL`). Set `include_discarded: true` to include them.
+
+For **expression** columns with correlated subqueries or JOINs referencing a soft-deletable model, you must filter discarded records manually in the SQL (e.g., `AND discarded_at IS NULL`). The platform does not inject soft-delete conditions into raw SQL expressions.
+
+### Presenter Usage
+
+Virtual columns are referenced in presenters as regular fields:
+
+```yaml
+# Index — sortable virtual column
+table_columns:
+  - { field: issues_count, sortable: true }
+  - { field: total_revenue, renderer: currency, sortable: true }
+  - { field: is_overdue }
+  - { field: company_name }
+
+# Show — in a section
+layout:
+  - section: "Statistics"
+    fields:
+      - { field: issues_count }
+      - { field: total_revenue, renderer: currency }
+      - { field: company_name }
+```
+
+Virtual columns are visible to all roles regardless of field permissions — they are computed values, not stored data.
+
+#### Explicit Virtual Column Lists
+
+Presenters can explicitly list virtual columns to include, beyond what is auto-detected from field references:
+
+```yaml
+# In index config
+index:
+  table_columns:
+    - { field: title }
+  virtual_columns: [total_value, is_overdue]
+
+# In show config
+show:
+  virtual_columns: [total_value]
+  layout:
+    - section: "Details"
+      fields:
+        - { field: title }
+```
+
+### Auto-Detection (Collector)
+
+The system automatically detects which virtual columns are needed for each page context by scanning:
+
+| Source | Context |
+|--------|---------|
+| `table_columns` field names | `:index` |
+| `tile.fields` field names | `:index` |
+| `item_classes[].when` conditions (recursive through `all`/`any`/`not`) | `:index` |
+| Permission `record_rules[].when` conditions (all roles, recursive) | `:index` |
+| Action `visible_when` / `disable_when` conditions (single, collection, batch) | `:index`, `:show`, `:edit` |
+| Show `layout` field names | `:show` |
+| Form field/section `visible_when` / `disable_when` conditions | `:edit` |
+| Explicit `virtual_columns` lists | per context |
+| `auto_include: true` columns | all contexts |
+| Sort params at runtime (`?sort=field_name`) | `:index` (dynamic) |
+
+This means you don't need to manually list virtual columns in most cases — referencing a virtual column in a table column or condition is sufficient.
+
+**Note:** `record_rules` auto-detection scans all roles (not just the current user's role) to collect virtual column names. Including an unused virtual column in SELECT is harmless, while missing one would cause a runtime error.
+
+### Backward Compatibility
+
+The `aggregates` YAML key continues to work and is merged with `virtual_columns`:
+
+```yaml
+# Both keys accepted — merged into a single set
+aggregates:
+  issues_count:
+    function: count
+    association: issues
+
+virtual_columns:
+  is_overdue:
+    expression: "CASE WHEN %{table}.due_date < CURRENT_DATE THEN 1 ELSE 0 END"
+    type: boolean
+```
+
+A name collision between the two keys raises a `MetadataError`.
+
+The Ruby API also preserves backward compatibility:
+
+| Legacy method | Aliased to |
+|---------------|------------|
+| `model_def.aggregates` | `model_def.virtual_columns` |
+| `model_def.aggregate(name)` | `model_def.virtual_column(name)` |
+| `model_def.aggregate_names` | `model_def.virtual_column_names` |
+| DSL `aggregate(...)` | DSL `virtual_column(...)` |
+
+The legacy `sql` key in YAML is accepted as an alias for `expression`.
+
+### Limitations
+
+- **Not filterable via Ransack** — Virtual columns are SQL aliases, not real database columns. They are not added to `ransackable_attributes` and cannot be used in the advanced filter builder or saved filters. To filter by a virtual column value, use a custom scope.
+- **Not in summary bar / column summaries** — Both `summary_bar` and column-level `summary` operate on real database columns via `scope.sum(field)` etc. Virtual column names are silently skipped.
+- **Permission scopes cannot reference virtual columns** — `ScopeBuilder`'s `where` and `field_match` types use `.where()` which requires real columns. Use `type: custom` with a named scope that embeds the SQL expression.
+- **Read-only in forms** — Virtual columns are computed values and never appear in `permitted_params`. If referenced in a form layout, they render as read-only display fields.
+- **DB portability is the configurator's responsibility** — The platform does not abstract SQL differences between PostgreSQL and SQLite in `expression:` and `join:` strings. For DB-portable logic, use service virtual columns with Arel.
+- **Security** — `expression:` and `join:` values are defined in YAML/DSL by the platform configurator and are not user input. The `%{table}` placeholder is resolved to a properly quoted table name. No user-supplied values are interpolated into these strings.
+
+### Complete Example
+
+```yaml
+model:
+  name: order
+  fields:
+    - { name: title, type: string }
+    - { name: status, type: string }
+    - { name: due_date, type: date }
+  associations:
+    - { type: has_many, name: line_items, target_model: line_item, foreign_key: order_id }
+    - { type: belongs_to, name: company, target_model: company, foreign_key: company_id, required: false }
+  virtual_columns:
+    items_count:
+      function: count
+      association: line_items
+    total_value:
+      expression: "COALESCE(SUM(line_items.quantity * line_items.unit_price), 0)"
+      join: "LEFT JOIN line_items ON line_items.order_id = %{table}.id"
+      group: true
+      type: decimal
+    is_overdue:
+      expression: "CASE WHEN %{table}.due_date < CURRENT_DATE THEN 1 ELSE 0 END"
+      type: boolean
+    company_name:
+      expression: "companies.name"
+      join: "LEFT JOIN companies ON companies.id = %{table}.company_id"
+      type: string
+    priority_score:
+      expression: "(%{table}.urgency * 10 + %{table}.impact * 5)"
+      type: integer
+      auto_include: true
+```
+
+## Options
+
+```yaml
+options:
+  timestamps: true
+  label_method: title
+  sti: true                            # enable Single Table Inheritance on this model
+  soft_delete: true                    # or { column: deleted_at }
+  auditing: true                       # or { only: [title, status], ... }
+  userstamps: true                     # or { created_by: author_id, updated_by: editor_id, store_name: true }
+  tree: true                           # or { parent_field: parent_category_id, ... }
+```
+
+### `timestamps`
+
+| | |
+|---|---|
+| **Default** | `true` |
+| **Type** | boolean |
+
+Adds `created_at` and `updated_at` columns to the table.
+
+### `label_method`
+
+| | |
+|---|---|
+| **Default** | `"to_s"` |
+| **Type** | string |
+
+Method called on records to generate display text (e.g., in association select dropdowns). Should return a human-readable string.
+
+### `sti`
+
+| | |
+|---|---|
+| **Default** | `false` |
+| **Type** | boolean |
+
+Enables Single Table Inheritance (STI) on this model. See [Single Table Inheritance](#single-table-inheritance-sti) for details.
+
+### `custom_fields`
+
+| | |
+|---|---|
+| **Default** | `false` |
+| **Type** | boolean |
+
+Enables user-defined custom fields on this model. When `true`, the engine:
+- Adds a `custom_data` column (JSONB on PostgreSQL, JSON on SQLite) to the model's table
+- Creates a GIN index on the column (PostgreSQL only)
+- Installs dynamic accessor methods for each custom field definition
+- Validates custom field values based on their definition constraints
+- Auto-generates a management presenter at `/custom-fields-<model_name>`
+
+Custom field definitions are stored in the built-in `custom_field_definition` model. Access is controlled through the `custom_data` virtual field in permissions.
+
+```yaml
+options:
+  custom_fields: true
+```
+
+See [Custom Fields Reference](custom-fields.md) for the complete attribute reference and [Custom Fields Guide](../guides/custom-fields.md) for a step-by-step tutorial.
+
+### `soft_delete`
+
+| | |
+|---|---|
+| **Default** | `false` (disabled) |
+| **Type** | `true` or Hash |
+
+Enables soft delete (logical deletion) for this model. Instead of permanently deleting records, the engine sets a timestamp column to mark them as discarded.
+
+**Simple form** — uses default column `discarded_at`:
+
+```yaml
+options:
+  soft_delete: true
+```
+
+**Hash form** — custom column name:
+
+```yaml
+options:
+  soft_delete:
+    column: deleted_at
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `column` | string | `"discarded_at"` | Name of the datetime column that stores the discard timestamp |
+
+When `soft_delete` is enabled, the engine automatically:
+
+- Creates the timestamp column (`discarded_at` by default) plus tracking columns (`discarded_by_type`, `discarded_by_id`)
+- Adds scopes: `kept` (non-discarded), `discarded` (discarded only), `with_discarded` (all records)
+- Adds instance methods: `discard!`, `undiscard!`, `discarded?`, `kept?`, `cascade_discarded?`
+- Changes the controller `destroy` action to soft-delete (sets `discarded_at`) instead of hard-delete
+- Filters discarded records from the default index view (applies `kept` scope)
+- Supports `dependent: :discard` on `has_many` associations for automatic cascade discard/undiscard
+
+The `discard!(by:)` method accepts an optional `by:` parameter to track which record triggered the discard (used for cascade tracking). The `undiscard!` method only restores cascade-discarded children — manually discarded records are left as-is.
+
+#### Cascade behavior with `has_many dependent:`
+
+`discard!` is **not** the same call path as `destroy!`. ActiveRecord's `dependent:` rules only fire for actual destroys, so the parent's children are handled like this:
+
+| `dependent:` on `has_many` | Effect when parent is `discard!`-ed |
+|---|---|
+| `:discard` | Children are also soft-deleted (cascade tracked — `undiscard!` will restore them). **Both parent and child models must have `soft_delete` enabled.** |
+| `:destroy`, `:delete`, `:delete_all` | **Not cascaded.** Children remain untouched and become orphans (visible via the parent's `with_discarded` scope only). |
+| `:nullify` | Not cascaded — children keep their FK. |
+| `:restrict_with_exception`, `:restrict_with_error` | Not cascaded — children block the **destroy** path, but `discard!` bypasses the check. |
+| (omitted) | Not cascaded. |
+
+Mix `:destroy` and `soft_delete` only when you actually want to drop children permanently while keeping the parent recoverable; otherwise prefer `:discard` everywhere in a soft-delete graph for a coherent restore story.
+
+See [Soft Delete Guide](../guides/soft-delete.md) for setup and usage examples.
+
+### `auditing`
+
+| | |
+|---|---|
+| **Default** | `false` (disabled) |
+| **Type** | `true`, `false`, or Hash |
+
+Enables change auditing for this model. When enabled, all field changes are tracked and stored via the configured `audit_writer`. Set to `false` to explicitly disable (same as omitting the key).
+
+**Simple form** — tracks all fields:
+
+```yaml
+options:
+  auditing: true
+```
+
+**Hash form** — fine-grained control:
+
+```yaml
+options:
+  auditing:
+    only:
+      - title
+      - status
+    track_associations: true
+    track_attachments: true
+    expand_custom_fields: true
+    expand_json_fields:
+      - addresses
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `only` | array of strings | all fields | Track only these fields. Mutually exclusive with `ignore`. |
+| `ignore` | array of strings | none | Track all fields except these. Mutually exclusive with `only`. |
+| `track_associations` | boolean | `true` | Include nested_attributes child changes in parent audit entry |
+| `track_attachments` | boolean | `false` | Include attachment changes in audit trail (reserved, not yet implemented) |
+| `expand_custom_fields` | boolean | `true` | Expand `custom_data` JSON into individual `cf:` prefixed field changes |
+| `expand_json_fields` | array of strings | `[]` | JSON columns to expand into dot-path key changes |
+
+> **Note:** `only` and `ignore` are mutually exclusive — specifying both causes a validation error.
+
+See [Auditing Reference](auditing.md) for the audit log model contract, changes data format, and configuration options. See [Auditing Guide](../guides/auditing.md) for setup and usage examples.
+
+### `userstamps`
+
+| | |
+|---|---|
+| **Default** | `false` (disabled) |
+| **Type** | `true` or Hash |
+
+Enables automatic user tracking — stores the ID of the user who created and last updated each record via a `before_save` callback that reads from `LcpRuby::Current.user`.
+
+**Simple form** — uses default columns `created_by_id` and `updated_by_id`:
+
+```yaml
+options:
+  userstamps: true
+```
+
+**Hash form** — custom column names and name snapshots:
+
+```yaml
+options:
+  userstamps:
+    created_by: author_id
+    updated_by: editor_id
+    store_name: true
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `created_by` | string | `"created_by_id"` | Column name for the creating user's FK |
+| `updated_by` | string | `"updated_by_id"` | Column name for the last updating user's FK |
+| `store_name` | boolean | `false` | Add denormalized `_name` snapshot columns (e.g., `created_by_name`, `updated_by_name`) |
+
+The applicator automatically:
+- Adds `bigint` columns (nullable, indexed) for creator and updater FK
+- Adds `string` columns for name snapshots when `store_name: true`
+- Adds `belongs_to` associations pointing to `LcpRuby.configuration.user_class`
+- Sets `created_by_id` only on `new_record?`, `updated_by_id` on every save
+- Writes `nil` when `LcpRuby::Current.user` is not set (seeds, jobs, console)
+- `update_columns` bypasses the callback by design (same as Rails timestamps)
+
+### `tree`
+
+| | |
+|---|---|
+| **Default** | `false` (disabled) |
+| **Type** | `true` or Hash |
+
+Enables tree/hierarchy structure for this model. The model becomes self-referencing with parent-child relationships, enabling nested structures like categories, organizational units, or threaded comments.
+
+**Simple form** — uses defaults:
+
+```yaml
+options:
+  tree: true
+```
+
+**Hash form** — custom configuration:
+
+```yaml
+options:
+  tree:
+    parent_field: parent_category_id
+    parent_name: parent_category
+    children_name: subcategories
+    dependent: nullify
+    max_depth: 5
+    ordered: true
+    position_field: position
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `parent_field` | string | `"parent_id"` | Foreign key column for the parent record |
+| `parent_name` | string | `"parent"` | Name of the `belongs_to` parent association |
+| `children_name` | string | `"children"` | Name of the `has_many` children association |
+| `dependent` | string | `"destroy"` | What happens to children when parent is deleted. Values: `destroy`, `nullify`, `restrict_with_exception`, `restrict_with_error`, `discard` (requires soft_delete) |
+| `max_depth` | integer | `10` | Maximum allowed tree depth. Enforced by cycle detection validation |
+| `ordered` | boolean | `false` | Enable position-based ordering of siblings. Automatically configures `positioning` scoped to parent |
+| `position_field` | string | `"position"` | Column name for sibling ordering (only used when `ordered: true`) |
+
+The `TreeApplicator` automatically:
+- Creates `belongs_to` / `has_many` self-referential associations
+- Adds `roots` and `leaves` scopes
+- Adds traversal instance methods: `root?`, `leaf?`, `ancestors`, `descendants`, `subtree`, `subtree_ids`, `siblings`, `depth`, `path`, `root`
+- Adds cycle detection validation (prevents self-reference, circular chains, and max_depth violations)
+- Adds a database index on the parent field
+- When `ordered: true`, configures `positioning` scoped to the parent field (unless the model already has explicit positioning)
+
+See [Tree Structures Reference](tree-structures.md) for full details on scopes, methods, and presenter integration.
+
+## Complete Example
+
+### YAML (TODO App)
+
+```yaml
+model:
+  name: todo_item
+  label: "Todo Item"
+  label_plural: "Todo Items"
+
+  fields:
+    - name: title
+      type: string
+      label: "Title"
+      transforms: [strip]
+      column_options:
+        limit: 255
+        "null": false
+      validations:
+        - type: presence
+
+    - name: completed
+      type: boolean
+      label: "Completed"
+      default: false
+
+    - name: start_date
+      type: date
+      label: "Start Date"
+      default: current_date
+
+    - name: due_date
+      type: date
+      label: "Due Date"
+      default:
+        service: one_week_from_now
+      validations:
+        - type: comparison
+          operator: gte
+          field_ref: start_date
+          message: "must be on or after start date"
+        - type: presence
+          when:
+            field: completed
+            operator: eq
+            value: false
+
+  associations:
+    - type: belongs_to
+      name: todo_list
+      target_model: todo_list
+      foreign_key: todo_list_id
+      required: true
+
+  options:
+    timestamps: true
+    label_method: title
+```
+
+### Ruby DSL (CRM App)
+
+```ruby
+define_model :deal do
+  label "Deal"
+  label_plural "Deals"
+
+  field :title, :string, label: "Title", limit: 255, null: false do
+    validates :presence
+  end
+
+  field :stage, :enum, label: "Stage", default: "lead",
+    values: {
+      lead: "Lead", qualified: "Qualified", proposal: "Proposal",
+      negotiation: "Negotiation", closed_won: "Closed Won",
+      closed_lost: "Closed Lost"
+    }
+
+  field :value, :decimal, label: "Value", precision: 12, scale: 2 do
+    validates :numericality, greater_than_or_equal_to: 0, allow_nil: true
+    validates :presence, when: { field: :stage, operator: :not_in, value: %w[lead] }
+  end
+
+  field :weighted_value, :decimal, label: "Weighted Value", precision: 12, scale: 2,
+    computed: { service: "weighted_deal_value" }
+
+  field :expected_close_date, :date, label: "Expected Close",
+    default: { service: "thirty_days_out" } do
+    validates :comparison, operator: :gte, field_ref: :created_at,
+      message: "cannot be before deal creation"
+  end
+
+  belongs_to :company, model: :company, required: true
+  belongs_to :contact, model: :contact, required: false
+
+  validates :contact_id, :presence,
+    when: { field: :stage, operator: :in, value: %w[negotiation closed_won closed_lost] }
+
+  validates_model :service, service: "deal_credit_limit"
+
+  scope :open_deals, where_not: { stage: ["closed_won", "closed_lost"] }
+
+  on_field_change :on_stage_change, field: :stage,
+    condition: { field: :stage, operator: :not_in, value: %w[lead] }
+
+  timestamps true
+  label_method :title
+end
+```
+
+## Single Table Inheritance (STI)
+
+STI allows multiple models to share a single database table, with a `type` column distinguishing the AR class. Each child model gets its own presenter, permissions, workflow, and pages.
+
+### Enabling STI
+
+Set `options.sti: true` on the parent model:
+
+```yaml
+# models/document.yml
+model:
+  name: document
+  options:
+    sti: true
+  fields:
+    - name: title
+      type: string
+    - name: status
+      type: enum
+      enum_values: [draft, published]
+```
+
+Define child models with `inherits:` pointing to the STI parent:
+
+```yaml
+# models/invoice.yml
+model:
+  name: invoice
+  inherits: document
+  fields:
+    - name: amount
+      type: decimal
+    - name: due_date
+      type: date
+```
+
+```yaml
+# models/credit_note.yml
+model:
+  name: credit_note
+  inherits: document
+  fields:
+    - name: reason
+      type: text
+```
+
+### How it works
+
+- A single `documents` table is created with a `type` column, plus columns from all children (`amount`, `due_date`, `reason`).
+- `LcpRuby::Dynamic::Invoice` inherits from `LcpRuby::Dynamic::Document` at the Ruby level.
+- `Invoice.all` returns only invoices; `Document.all` returns all types.
+- Parent validations, enums, callbacks, and scopes are inherited via AR class hierarchy (not re-applied).
+- Each child can have its own presenter (with its own slug, columns, form) and its own permissions.
+
+### Restrictions
+
+- STI children must not define `table_name` (they inherit the parent's table).
+- STI children must not set `options.sti: true` (only the root parent can be STI).
+- Abstract models cannot be STI parents (use `abstract: true` or `options.sti: true`, not both).
+
+### Permission fallback
+
+When no permissions are defined for an STI child, the platform falls back to the parent model's permissions, then to `_default`. This applies to both YAML and DB permission sources.
+
+### Workflow fallback
+
+When no workflow is defined for an STI child, the platform falls back to the parent model's workflow.
+
+### Chaining with abstract inheritance
+
+An abstract → STI chain is supported: define common fields in an abstract base, then an STI parent that inherits from it, then STI children:
+
+```yaml
+# models/_auditable.yml
+model:
+  name: _auditable
+  abstract: true
+  fields:
+    - name: created_by
+      type: string
+
+# models/document.yml
+model:
+  name: document
+  inherits: _auditable
+  options:
+    sti: true
+  fields:
+    - name: title
+      type: string
+
+# models/invoice.yml
+model:
+  name: invoice
+  inherits: document
+  fields:
+    - name: amount
+      type: decimal
+```
+
+In this chain, `invoice` gets `created_by` (from `_auditable`), `title` (from `document`), and `amount` (its own).
+
+Source: `lib/lcp_ruby/metadata/model_definition.rb`, `lib/lcp_ruby/metadata/field_definition.rb`, `lib/lcp_ruby/metadata/validation_definition.rb`, `lib/lcp_ruby/metadata/association_definition.rb`, `lib/lcp_ruby/metadata/event_definition.rb`