lcp 0.1.0

data/docs/reference/model-dsl.md

@@ -0,0 +1,1157 @@
+# Model DSL Reference
+
+File: `config/lcp_ruby/models/<name>.rb`
+
+The Model DSL is a Ruby alternative to [YAML model definitions](models.md). It produces the same internal representation (`ModelDefinition`, `FieldDefinition`, etc.) and feeds through the same pipeline — the DSL builder outputs a hash identical to parsed YAML, which is then processed by `ModelDefinition.from_hash`.
+
+DSL files live alongside YAML files in `config/lcp_ruby/models/`. A project can mix both formats, but each model name must be unique across all files (defining the same model in both `.yml` and `.rb` raises `MetadataError`).
+
+## Entry Point
+
+```ruby
+LcpRuby.define_model :model_name do
+  # DSL calls here
+end
+```
+
+The symbol argument becomes the model name. The block is evaluated on a builder context object that provides all the DSL methods documented below.
+
+In DSL files loaded by the engine, use `define_model` without the `LcpRuby.` prefix:
+
+```ruby
+# config/lcp_ruby/models/task.rb
+define_model :task do
+  label "Task"
+  field :title, :string
+  timestamps true
+end
+```
+
+## Model Metadata
+
+### `label`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `name.humanize` |
+| **Type** | string |
+
+Human-readable singular name displayed in the UI.
+
+```ruby
+label "Todo Item"
+```
+
+### `label_plural`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `label.pluralize` |
+| **Type** | string |
+
+Plural form used in index page headings and navigation.
+
+```ruby
+label_plural "Todo Items"
+```
+
+### `abstract`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+Marks this model as an abstract template. See [Models Reference — `abstract`](models.md#abstract) for merge rules and behavior.
+
+```ruby
+define_model :_auditable do
+  abstract
+
+  field :created_by, :string
+  field :updated_by, :string
+  option :userstamps, true
+end
+```
+
+### `inherits:` (keyword argument)
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | symbol |
+
+Passed as a keyword argument to `define_model`. The parent must be either an abstract model (`abstract: true`) or an STI parent (`options.sti: true`). See [Models Reference — `inherits`](models.md) for merge rules and both inheritance modes.
+
+```ruby
+define_model :ticket, inherits: :_auditable do
+  field :title, :string
+  field :due_date, :date
+end
+```
+
+### `option`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | `option(key, value)` |
+
+Sets a generic model option. Equivalent to setting a key in `options:` in YAML.
+
+```ruby
+option :soft_delete, true
+option :custom_fields, true
+```
+
+### `table_name`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `name.pluralize` |
+| **Type** | string |
+
+Override the database table name.
+
+```ruby
+table_name "legacy_todo_items"
+```
+
+### `timestamps`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `true` (when set via options) |
+| **Type** | boolean |
+
+Adds `created_at` and `updated_at` columns to the table.
+
+```ruby
+timestamps true
+```
+
+### `label_method`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `"to_s"` |
+| **Type** | symbol or string |
+
+Method called on records to generate display text (e.g., in association select dropdowns).
+
+```ruby
+label_method :title
+```
+
+### `custom_fields`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+Enables runtime user-defined custom fields on this model. See [Custom Fields Reference](custom-fields.md) for details.
+
+```ruby
+custom_fields true
+```
+
+### `data_source`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | keyword arguments |
+
+Configures the model as API-backed. See [API-Backed Models Reference](api-backed-models.md).
+
+```ruby
+data_source type: :rest_json,
+            base_url: "https://api.example.com",
+            resource: "/buildings",
+            auth: { type: "bearer", token_env: "API_TOKEN" },
+            cache: { enabled: true, ttl: 300 }
+
+# Host-provided data source
+data_source type: :host, provider: "Erp::ProductDataSource"
+```
+
+### `positioning`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | keyword arguments or no arguments |
+
+Enables automatic record positioning via the [`positioning`](https://github.com/brendon/positioning) gem. See [Models Reference — positioning](models.md#positioning) for semantics.
+
+```ruby
+# Minimal — uses "position" field, no scope
+positioning
+
+# With custom field
+positioning field: :position
+
+# With scope
+positioning scope: :pipeline_id
+
+# With field and multi-column scope
+positioning field: :sort_order, scope: [:pipeline_id, :category]
+```
+
+### `index`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | positional + keyword arguments |
+
+Declares a database index on one or more columns. See [Models Reference — `indexes`](models.md#indexes) for semantics.
+
+```ruby
+# Simple index
+index :email
+
+# Compound unique index
+index %i[seq_model seq_field scope_key], unique: true
+
+# With custom name
+index :email, unique: true, name: "idx_users_email_uniq"
+```
+
+### `soft_delete`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | boolean or keyword arguments |
+
+Enables soft delete (logical deletion). See [Models Reference — soft_delete](models.md#soft_delete) for semantics.
+
+```ruby
+# Simple — uses default column "discarded_at"
+soft_delete
+
+# Custom column name
+soft_delete column: :deleted_at
+```
+
+### `auditing`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | boolean or keyword arguments |
+
+Enables change auditing. See [Models Reference — auditing](models.md#auditing) for semantics.
+
+```ruby
+# Simple — tracks all fields
+auditing
+
+# Track only specific fields
+auditing only: [:title, :status]
+
+# Ignore specific fields
+auditing ignore: [:updated_at]
+
+# With boolean flags
+auditing track_associations: true, track_attachments: true
+
+# With JSON field expansion
+auditing expand_custom_fields: true, expand_json_fields: [:addresses]
+```
+
+| Keyword | Type | Description |
+|---------|------|-------------|
+| `only:` | array of symbols | Track only these fields |
+| `ignore:` | array of symbols | Track all fields except these |
+| `track_associations:` | boolean | Include association changes |
+| `track_attachments:` | boolean | Include attachment changes |
+| `expand_custom_fields:` | boolean | Expand `custom_data` JSON |
+| `expand_json_fields:` | array of symbols | JSON columns to expand |
+
+### `userstamps`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | boolean or keyword arguments |
+
+Enables automatic user tracking. See [Models Reference — userstamps](models.md#userstamps) for semantics.
+
+```ruby
+# Simple — uses default columns "created_by_id" and "updated_by_id"
+userstamps
+
+# With name snapshots
+userstamps store_name: true
+
+# Custom column names with name snapshots
+userstamps created_by: :author_id, updated_by: :editor_id, store_name: true
+```
+
+| Keyword | Type | Description |
+|---------|------|-------------|
+| `created_by:` | symbol | Custom creator FK column name |
+| `updated_by:` | symbol | Custom updater FK column name |
+| `store_name:` | boolean | Add denormalized `_name` snapshot columns |
+
+### `tree`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | boolean or keyword arguments |
+
+Enables tree/hierarchy structure. See [Models Reference — tree](models.md#tree) for semantics.
+
+> **⚠️ Required fields:** `tree` does **not** auto-create columns. Declare `field :parent_id, :integer` (and `field :position, :integer` when using `ordered: true`) yourself. See the [Tree Structures reference](tree-structures.md#tree) callout for details.
+
+```ruby
+# Simple — uses defaults
+tree
+
+# Custom configuration
+tree parent_field: :parent_category_id, children_name: :subcategories
+
+# Full configuration
+tree parent_field: :parent_category_id,
+     children_name: :subcategories,
+     depth_column: :depth,
+     counter_cache: true
+```
+
+| Keyword | Type | Description |
+|---------|------|-------------|
+| `parent_field:` | symbol | Foreign key column for parent record |
+| `children_name:` | symbol | Name of the children association |
+| `depth_column:` | symbol | Column for computed depth |
+| `counter_cache:` | boolean | Maintain child count |
+
+### `slug_field`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | symbol or string |
+
+Designates a string field as the URL slug for this model. See the [YAML reference](models.md#slug_field) for full semantics, validation rules, and recommendations.
+
+```ruby
+define_model :article do
+  slug_field :slug
+
+  field :title, :string
+  field :slug, :string
+
+  validates :slug, :uniqueness
+  validates :slug, :format, options: { with: "\\A[a-z0-9-]+\\z" }
+
+  index %i[slug], unique: true
+end
+```
+
+## Fields
+
+```ruby
+field :name, :type, **options do
+  # optional: field-level validations
+end
+```
+
+### Positional Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `name` | yes | Column name (symbol). Must be unique within the model. |
+| `type` | yes | Field type (symbol). One of the 14 base types or a registered [business type](types.md) name. |
+
+> **Reserved names.** Avoid `:type`, `:model_name`, `:class`, `:save`, `:destroy`, `:changes`, and other ActiveRecord/ActiveModel internals. The boot-time validator rejects them with `MetadataError`. See the full list and the platform-reserved additions (`:custom_data`, `:discarded_at`, `:position`) in [Models Reference — `name`](models.md#name).
+
+### 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 `precision:` and `scale:` options. |
+| `:boolean` | `:boolean` | True/false. Default form input: checkbox. |
+| `:date` | `:date` | Date without time. |
+| `:datetime` | `:datetime` | Date and time. |
+| `:enum` | `:string` | Stored as string. Requires `values:` option. Default form input: select. |
+| `:file` | `:string` | File path/reference stored as string. |
+| `:rich_text` | `:text` | Rich text content. Default form input: rich text editor. |
+| `: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:` option. Default form input: tag chips. |
+| `:attachment` | none (Active Storage) | File attachment (single or multiple). No DB column — uses Active Storage. |
+
+### Business Types
+
+In addition to base types, fields can use any registered business type:
+
+```ruby
+field :email, :email           # strip + downcase + email format validation + <input type="email">
+field :phone, :phone           # strip + normalize_phone + phone format validation + <input type="tel">
+field :website, :url           # strip + normalize_url + URL format validation + <input type="url">
+field :favorite_color, :color  # strip + downcase + hex color validation + <input type="color">
+field :user_id, :bigint        # 8-byte integer — matches Rails' default bigint PK (avoids INT/BIGINT join mismatches)
+```
+
+Business types bundle transforms, validations, and input hints. Additional field-level validations merge with the type defaults:
+
+```ruby
+field :email, :email do
+  validates :presence          # added on top of the email type's format validation
+end
+```
+
+See [Types Reference](types.md) for the full list of built-in types and how to define custom ones.
+
+### Keyword Options
+
+| Option | Maps to | Description |
+|--------|---------|-------------|
+| `label:` | `FieldDefinition.label` | Display label. Default: humanized name. |
+| `default:` | `FieldDefinition.default` | Default value for new records. |
+| `values:` | `FieldDefinition.enum_values` | Enum values — Hash or Array (see below). |
+| `limit:` | `column_options[:limit]` | Maximum character length (string). |
+| `precision:` | `column_options[:precision]` | Total number of digits (decimal). |
+| `scale:` | `column_options[:scale]` | Digits after decimal point (decimal). |
+| `null:` | `column_options[:null]` | Allow NULL values. |
+| `item_type:` | `FieldDefinition.item_type` | Element type for array fields (`:string`, `:integer`, `:float`). Required for `:array` type. |
+| `options:` | `FieldDefinition.options` | Additional type-specific options (used by `attachment` fields). |
+| `sequence:` | `FieldDefinition.sequence` | Auto-numbering config hash. See [Models Reference — `sequence`](models.md#sequence). |
+
+Column options (`limit`, `precision`, `scale`, `null`) are flattened to top-level keyword arguments for conciseness. The builder separates them back into a `column_options` hash internally.
+
+### Attachment Fields
+
+The `:attachment` type uses Active Storage instead of a database column. Pass configuration via the `options:` keyword:
+
+```ruby
+# Single image with variants
+field :avatar, :attachment, label: "Avatar", options: {
+  accept: "image/*",
+  max_size: "5MB",
+  content_types: %w[image/jpeg image/png image/webp],
+  variants: {
+    thumbnail: { resize_to_fill: [40, 40] },
+    medium: { resize_to_limit: [200, 200] }
+  }
+}
+
+# Multiple file attachment
+field :documents, :attachment, label: "Documents", options: {
+  multiple: true,
+  max_files: 10,
+  max_size: "15MB",
+  content_types: %w[application/pdf image/jpeg image/png]
+}
+```
+
+| 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 (not validated server-side) |
+| `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 (validated server-side). Supports wildcards (e.g., `"image/*"`) |
+| `max_files` | integer | none | Maximum number of files (only for `multiple: true`) |
+| `variants` | hash | none | Named image variant configurations (requires `image_processing` gem) |
+
+> **Note:** `accept` is an HTML hint that filters the file browser — it does **not** validate on the server. Use `content_types` for server-side validation.
+
+See the [Attachments Guide](../guides/attachments.md) for prerequisites and complete examples.
+
+### Array Fields
+
+The `:array` type stores a list of scalar values. Requires the `item_type:` keyword.
+
+```ruby
+# String array (e.g., tags)
+field :tags, :array, item_type: :string, default: []
+
+# Integer array (e.g., scores)
+field :scores, :array, item_type: :integer, default: []
+
+# Array with validations
+field :categories, :array, item_type: :string, default: [] do
+  validates :array_length, minimum: 1, maximum: 5
+  validates :array_inclusion, in: %w[tech finance health sports]
+  validates :array_uniqueness
+end
+```
+
+Auto-generated scopes: `with_<field>(values)` (contains ALL) and `with_any_<field>(values)` (contains ANY). See [Models Reference](models.md#array-fields) for details.
+
+### Examples
+
+```ruby
+# String with column constraints and validations
+field :title, :string, label: "Title", limit: 255, null: false do
+  validates :presence
+end
+
+# Decimal with precision
+field :price, :decimal, precision: 12, scale: 2
+
+# Boolean with default
+field :completed, :boolean, default: false
+
+# Date without options
+field :due_date, :date, label: "Due Date"
+```
+
+> **`null: false` auto-applies a runtime validator (Phase 4b of type-system defaults).**
+> A field declared `null: false` (whether via `column_options: { null: false }`, the `!` modifier in the entity generator, or directly as a field-level keyword in the DSL) gets the type's
+> `null_false_validation` rule applied at runtime — for `:boolean` it's
+> `inclusion: { in: [true, false] }`, for everything else it's `presence`. So
+> `field :enabled, :boolean, null: false` (no explicit validator block) produces
+> a Rails-shaped validation error on `enabled = nil`, not a SQL NOT NULL
+> violation. The runtime auto-application is silenced by any explicit
+> field-level validator of the same type — declare `validates :inclusion, in: [true, false]`
+> in the block to make the rule visible in source. **Do not** add
+> `validates :presence` to a `:boolean` field with `null: false` — that's the
+> C4 footgun (`false.present? == false`) and `bundle exec rake lcp_ruby:validate`
+> flags it as an error.
+
+### Enum Values
+
+The `values:` option accepts two formats:
+
+**Hash format** — explicit labels:
+
+```ruby
+field :status, :enum, default: "draft",
+  values: { draft: "Draft", published: "Published", archived: "Archived" }
+```
+
+**Array format** — labels auto-humanized from value names:
+
+```ruby
+field :priority, :enum, values: [:low, :medium, :high]
+# Produces: low → "Low", medium → "Medium", high → "High"
+```
+
+Both formats produce the same `enum_values` structure as the [YAML hash format](models.md#enum_values).
+
+## Validations
+
+Validations can be placed in two locations:
+
+### Style A — Inside a Field Block
+
+Preferred for field-specific validations. The field context is implicit — only the validation type and options are needed.
+
+```ruby
+field :title, :string do
+  validates :presence
+  validates :length, minimum: 3, maximum: 255
+end
+
+field :budget, :decimal do
+  validates :numericality, greater_than_or_equal_to: 0, allow_nil: true
+end
+```
+
+### Style B — At Model Level
+
+ActiveRecord-like style where the field name is the first argument. Useful when adding validations to fields defined elsewhere or when preferring the AR convention.
+
+```ruby
+field :email, :string
+field :title, :string
+
+validates :email, :format, with: '\A[^@\s]+@[^@\s]+\z', allow_blank: true
+validates :title, :presence
+validates :title, :length, minimum: 3, maximum: 255
+```
+
+Both styles produce the same result — a `ValidationDefinition` attached to the field's `validations` array. The referenced field must be defined in the same model; referencing an unknown field raises `MetadataError`.
+
+### Model-Level Validations
+
+For validations not attached to a specific field (e.g., cross-field validators), use `validates_model`:
+
+```ruby
+validates_model :custom, validator_class: "DateRangeValidator"
+```
+
+### Validation Types
+
+#### `presence`
+
+Validates that the field is not blank.
+
+```ruby
+validates :presence
+```
+
+#### `length`
+
+Validates string length.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `minimum` | integer | Minimum length |
+| `maximum` | integer | Maximum length |
+| `is` | integer | Exact length |
+| `in` | range | Length range |
+
+```ruby
+validates :length, 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 |
+
+```ruby
+validates :numericality, greater_than_or_equal_to: 0, allow_nil: true
+```
+
+#### `format`
+
+Validates against a regular expression pattern.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `with` | string | Regex pattern (converted to `Regexp` at runtime) |
+
+```ruby
+validates :format, with: '\A[a-zA-Z0-9]+\z'
+```
+
+> Note: Use string patterns instead of Ruby regex literals (`/.../`) for portability.
+
+#### `inclusion`
+
+Validates that the value is in a given set.
+
+```ruby
+validates :inclusion, in: ["low", "medium", "high"]
+```
+
+#### `exclusion`
+
+Validates that the value is not in a given set.
+
+```ruby
+validates :exclusion, in: ["banned", "restricted"]
+```
+
+#### `uniqueness`
+
+Validates uniqueness of the value.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `scope` | symbol or array | Columns to scope uniqueness to |
+| `case_sensitive` | boolean | Case-sensitive comparison |
+
+```ruby
+validates :uniqueness, scope: :company_id, case_sensitive: false
+```
+
+#### `confirmation`
+
+Validates that a `<field>_confirmation` attribute matches the field.
+
+```ruby
+validates :confirmation
+```
+
+#### `custom`
+
+Delegates to a custom validator class.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `validator_class` | string | Fully qualified class name (required) |
+
+```ruby
+validates :custom, validator_class: "EmailFormatValidator", strict: true
+```
+
+All additional keyword arguments are passed as validation options.
+
+#### `array_length`
+
+Validates the number of items in an array field.
+
+```ruby
+validates :array_length, minimum: 1, maximum: 10
+```
+
+#### `array_inclusion`
+
+Validates that all items are within an allowed set.
+
+```ruby
+validates :array_inclusion, in: %w[ruby python java go rust]
+```
+
+#### `array_uniqueness`
+
+Validates that all items are unique (no duplicates).
+
+```ruby
+validates :array_uniqueness
+```
+
+### 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 |
+
+```ruby
+validates :presence, message: "must be provided", if: "active?"
+validates :numericality, greater_than: 0, unless: "draft?"
+```
+
+The `if` and `unless` options accept method name strings (not procs) for portability.
+
+## Associations
+
+### `belongs_to`
+
+```ruby
+belongs_to :company, model: :company, required: true
+belongs_to :tag,     model: :tag,     required: false   # nullable parent
+belongs_to :author,  class_name: "User", foreign_key: :author_id, required: true
+```
+
+> **Always pass `required:` explicitly.** Without it, AR Rails 5+ defaults to
+> `required: true`, which silently rejects nullable parents at save time.
+> `bundle exec rake lcp_ruby:validate` warns when a `belongs_to` declaration
+> omits the kwarg. The `lcp_ruby:entity` generator emits it for you;
+> hand-written associations should mirror that.
+
+### `has_many`
+
+```ruby
+has_many :contacts, model: :contact, dependent: :destroy
+has_many :items, model: :item, foreign_key: :parent_id
+
+# With nested attributes
+has_many :todo_items, model: :todo_item, dependent: :destroy,
+  inverse_of: :todo_list,
+  nested_attributes: { allow_destroy: true, reject_if: :all_blank }
+```
+
+### `has_one`
+
+```ruby
+has_one :profile, model: :profile, dependent: :destroy
+
+# With nested attributes
+has_one :address, model: :address, dependent: :destroy,
+  inverse_of: :contact,
+  nested_attributes: { update_only: true }
+```
+
+### Association Options
+
+| Option | Maps to | Description |
+|--------|---------|-------------|
+| `model:` | `AssociationDefinition.target_model` | Target LCP model name. For associations between LCP-managed models. |
+| `class_name:` | `AssociationDefinition.class_name` | Target class name. For external (non-LCP) ActiveRecord models. |
+| `foreign_key:` | `AssociationDefinition.foreign_key` | Foreign key column. Auto-inferred for `belongs_to` (e.g., `:company` → `company_id`). |
+| `primary_key:` | `AssociationDefinition.primary_key` | Column on the PK side of the join (target for `belongs_to`, owner for `has_many`/`has_one`). Defaults to the target's primary key. Use this to join on a business key instead of a surrogate id. Not allowed with `through:` or `polymorphic:`. See [Models Reference — primary_key](models.md#primary_key). |
+| `required:` | `AssociationDefinition.required` | Whether association is mandatory. Default: `true` for `belongs_to` (AR Rails 5+), `false` otherwise. **Always pass explicitly on `belongs_to`** — the validator warns when omitted, since the implicit default is a frequent footgun for nullable parents. |
+| `dependent:` | `AssociationDefinition.dependent` | What happens on parent destroy: `:destroy`, `:nullify`, `:delete_all`, `:restrict_with_error`. |
+| `inverse_of:` | `AssociationDefinition.inverse_of` | Name of inverse association on target model. Avoids ambiguity and extra queries. |
+| `counter_cache:` | `AssociationDefinition.counter_cache` | `belongs_to` only. `true` or custom column name string. |
+| `touch:` | `AssociationDefinition.touch` | `belongs_to` only. Updates parent's `updated_at` on child save. |
+| `polymorphic:` | `AssociationDefinition.polymorphic` | `belongs_to` only. Creates polymorphic association with `_id` and `_type` columns. |
+| `as:` | `AssociationDefinition.as` | `has_many`/`has_one` only. Polymorphic interface name on target. |
+| `through:` | `AssociationDefinition.through` | `has_many`/`has_one` only. Join association name for through relationships. |
+| `source:` | `AssociationDefinition.source` | `has_many`/`has_one` with `through:` only. Source association on join model. |
+| `autosave:` | `AssociationDefinition.autosave` | Auto-save associated records when parent is saved. |
+| `validate:` | `AssociationDefinition.validate` | Validate associated records on save. Set `false` to skip. |
+| `nested_attributes:` | `AssociationDefinition.nested_attributes` | `has_many`/`has_one` only. Hash with nested attributes options: `allow_destroy:`, `reject_if:`, `limit:`, `update_only:`. Requires `inverse_of:`. See [Nested Attributes](models.md#nested-attributes). |
+| `order:` | `AssociationDefinition.order` | `has_many`/`has_one` only. Default ordering for associated records. Hash with column names as keys and `:asc`/`:desc` as values, or a single symbol for ascending order. |
+| `skip_inverse_check:` | `AssociationDefinition.skip_inverse_check` | `belongs_to` only. Suppresses the `lcp_ruby:validate` warning about a missing `has_many`/`has_one` inverse. Use for intentionally one-directional refs (audit/author/owner). See [`skip_inverse_check`](models.md#skip_inverse_check). |
+
+At least one of `model:`, `class_name:`, `polymorphic:`, `as:`, or `through:` is required. Use `model:` for LCP models; use `class_name:` for host app models.
+
+### Examples
+
+```ruby
+# Polymorphic belongs_to
+belongs_to :commentable, polymorphic: true
+
+# has_many with polymorphic interface
+has_many :comments, model: :comment, as: :commentable
+
+# has_many through (join model)
+has_many :taggings, model: :tagging
+has_many :tags, through: :taggings
+
+# has_many through with explicit source
+has_many :authors, through: :authorships, source: :person
+
+# Counter cache on belongs_to
+belongs_to :project, model: :project, counter_cache: true
+
+# Touch parent on save
+belongs_to :project, model: :project, touch: true
+
+# Inverse of
+has_many :tasks, model: :task, inverse_of: :project, dependent: :destroy
+
+# Ordered association (for sortable nested forms)
+has_many :items, model: :item, dependent: :destroy,
+  inverse_of: :list, order: { position: :asc }
+
+# Join on a business key instead of the target's primary key
+# (employees.division_code = divisions.vema_code)
+belongs_to :division, model: :division,
+  foreign_key: :division_code,
+  primary_key: :vema_code,
+  required: false
+
+# Reverse side — same join pair declared on the owner (division)
+has_many :employees, model: :employee,
+  foreign_key: :division_code,
+  primary_key: :vema_code
+```
+
+## Scopes
+
+```ruby
+scope :name, where: { ... }, where_not: { ... }, order: { ... }, limit: N
+```
+
+Purely declarative — no lambdas, no raw SQL. **Every option is independently optional** — only `name` is required. Combine any subset (`where` + `order`, `where_not` + `limit`, `order` alone as a sort helper, `limit` alone as a "top N" cap, etc.). Don't write `where: {}` to satisfy a perceived requirement; just omit it.
+
+### Scope Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `where:` | hash | `where(...)` conditions. Keys = columns, values = expected values. |
+| `where_not:` | hash | `where.not(...)` conditions. Same syntax, negated. |
+| `order:` | hash | Ordering. Keys = columns, values = `:asc` or `:desc`. |
+| `limit:` | integer | Maximum number of returned records. |
+| `type:` | symbol | `:custom` (Ruby-only) or `:parameterized` (accepts typed parameters). |
+| `parameters:` | array | Parameter definitions (only when `type: :parameterized`). |
+
+### Examples
+
+```ruby
+scope :active,       where: { status: "active" }
+scope :not_closed,   where_not: { stage: ["closed_won", "closed_lost"] }
+scope :recent,       order: { created_at: :desc }, limit: 10  # order + limit only — no where
+scope :upcoming,     order: { due_at: :asc }                  # order-only sort helper
+scope :first_five,   limit: 5                                 # limit-only cap (relies on default order)
+scope :top_active,   where: { status: "active" }, order: { value: :desc }, limit: 5
+```
+
+### Parameterized Scopes
+
+Parameterized scopes accept typed parameters at runtime. The actual scope logic must be defined in Ruby (AR scope or `filter_*` interceptor).
+
+```ruby
+scope :by_min_price, type: :parameterized, parameters: [
+  { name: :min_price, type: :float, default: 0.0, min: 0 }
+]
+
+scope :created_recently, type: :parameterized, parameters: [
+  { name: :days, type: :integer, default: 30, min: 1, max: 365 }
+]
+
+scope :by_status_filter, type: :parameterized, parameters: [
+  { name: :status, type: :enum, values: %w[draft published archived], required: true }
+]
+```
+
+Each parameter hash supports: `name`, `type` (boolean/string/integer/float/enum/date/datetime/model_select), `default`, `required`, `min`, `max`, `values`. See [Models Reference — Parameterized Scopes](models.md#parameterized-scopes) for full details.
+
+Scopes can be referenced from [predefined filters](presenters.md#search-configuration) in presenters.
+
+## Events
+
+Events trigger [event handlers](../guides/event-handlers.md) in response to record changes.
+
+### Lifecycle Events
+
+```ruby
+after_create                    # name defaults to "after_create"
+after_create :my_custom_name    # custom event name
+after_update
+before_destroy
+after_destroy
+```
+
+Each method accepts an optional symbol argument to set a custom event name. When omitted, the method name itself is used.
+
+| Method | 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 |
+
+### Field Change Events
+
+```ruby
+on_field_change :event_name, field: :field_name
+on_field_change :on_priority_change, field: :priority, condition: "priority_increased?"
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `name` | yes | Event identifier (symbol). |
+| `field:` | yes | Field to monitor for changes. |
+| `condition:` | no | Method name string for additional filtering. |
+
+## Display Templates
+
+Display templates define rich HTML representations for records. See [Models Reference — Display Templates](models.md#display-templates) for full documentation.
+
+```ruby
+display_template :name, template: nil, subtitle: nil, icon: nil,
+                        badge: nil, renderer: nil, partial: nil, options: nil
+```
+
+### Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `name` | yes | Template identifier (symbol). Use `:default` for the auto-selected template. |
+| `template:` | conditional | Main text with `{field}` placeholders. Required for structured form. |
+| `subtitle:` | no | Secondary text. Supports `{field}` and `{assoc.field}` placeholders. |
+| `icon:` | no | Icon identifier string. |
+| `badge:` | no | Badge text. Supports `{field}` placeholders. |
+| `renderer:` | conditional | Renderer key. Required for renderer form. Accepts a registered renderer name (`badge`, `truncate`, `email_link`, …) OR a type name whose `TypeDefinition#renderer` is set (e.g. `enum` → `:badge`, `markdown` → the type's declared renderer). Runtime resolves type-name synonyms via the type registry — see [Presenters Reference § Aliases](presenters.md#aliases) for the full precedence rules. |
+| `partial:` | conditional | Rails partial path. Required for partial form. |
+| `options:` | no | Hash passed to the renderer's `render` method (renderer form only). |
+
+Exactly one of `template:`, `renderer:`, or `partial:` must be provided.
+
+### Examples
+
+```ruby
+define_model :contact do
+  field :first_name, :string
+  field :last_name, :string
+  field :position, :string
+
+  belongs_to :company, model: :company
+
+  # Structured: title + subtitle + icon
+  display_template :default,
+    template: "{first_name} {last_name}",
+    subtitle: "{position} at {company.name}",
+    icon: "user"
+
+  # Structured: compact single-line
+  display_template :compact,
+    template: "{last_name}, {first_name}"
+
+  # Renderer: delegates to a registered BaseRenderer subclass
+  display_template :card, renderer: "ContactCardRenderer", options: { size: "large" }
+
+  # Partial: renders a Rails partial
+  display_template :mini, partial: "contacts/mini_label"
+end
+```
+
+## Aggregates
+
+Virtual computed columns derived from associated records. See [Models Reference — Aggregates](models.md#aggregates) for full semantics.
+
+```ruby
+aggregate :name, function: :func, association: :assoc, **options
+```
+
+### Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `name` | yes | Aggregate identifier (symbol). Must not collide with field names. |
+| `function:` | conditional | SQL function: `:count`, `:sum`, `:min`, `:max`, `:avg`. Required for declarative aggregates. |
+| `association:` | conditional | Target `has_many` association name. Required for declarative aggregates. |
+| `source_field:` | conditional | Field on the target model. Required for sum/min/max/avg. |
+| `where:` | no | Hash of equality conditions on the target model. Supports `:current_user` placeholder. |
+| `distinct:` | no | Use DISTINCT in the function (default: `false`). |
+| `default:` | no | Default value via COALESCE. Count defaults to 0 automatically. |
+| `include_discarded:` | no | Include soft-deleted records (default: `false`). |
+| `sql:` | conditional | Custom SQL subquery. Use `%{table}` for parent table name. Required for SQL-type aggregates. |
+| `service:` | conditional | Service key from `app/lcp_services/aggregates/`. Required for service-type aggregates. |
+| `type:` | conditional | Result type. Required for SQL and service aggregates; inferred for declarative. |
+| `options:` | no | Hash passed to service's `call` method. |
+
+### Examples
+
+```ruby
+define_model :company do
+  has_many :contacts, model: :contact, foreign_key: :company_id
+  has_many :deals, model: :deal, foreign_key: :company_id
+
+  # Count all contacts
+  aggregate :contacts_count, function: :count, association: :contacts
+
+  # Count deals with a filter
+  aggregate :open_deals_count, function: :count, association: :deals,
+    where: { stage: "open" }
+
+  # Sum with default
+  aggregate :total_deal_value, function: :sum, association: :deals,
+    source_field: :value, default: 0
+
+  # Filtered sum
+  aggregate :won_deals_value, function: :sum, association: :deals,
+    source_field: :value, where: { stage: "closed_won" }, default: 0
+
+  # Per-user aggregate
+  aggregate :my_deals_count, function: :count, association: :deals,
+    where: { assignee_id: :current_user }
+
+  # Custom SQL
+  aggregate :weighted_score, sql: "SELECT AVG(r.score) FROM ratings r WHERE r.company_id = %{table}.id",
+    type: :float
+
+  # Service-based
+  aggregate :health_score, service: :company_health, type: :integer
+end
+```
+
+## DSL vs YAML Equivalence
+
+The DSL produces the exact same hash structure as parsed YAML. Every DSL construct has a 1:1 YAML equivalent:
+
+| DSL | YAML Equivalent |
+|-----|----------------|
+| `label "Deal"` | `label: "Deal"` |
+| `field :title, :string` | `fields: [{ name: title, type: string }]` |
+| `field ... do validates :presence end` | `validations: [{ type: presence }]` inside field |
+| `values: { a: "A" }` | `enum_values: [{ value: a, label: "A" }]` |
+| `limit: 255, null: false` | `column_options: { limit: 255, "null": false }` |
+| `belongs_to :x, model: :x` | `associations: [{ type: belongs_to, name: x, target_model: x }]` |
+| `belongs_to :x, polymorphic: true` | `associations: [{ type: belongs_to, name: x, polymorphic: true }]` |
+| `has_many :x, through: :y` | `associations: [{ type: has_many, name: x, through: y }]` |
+| `has_many :x, ..., nested_attributes: { allow_destroy: true }` | `associations: [{ ..., nested_attributes: { allow_destroy: true } }]` |
+| `has_many :x, ..., order: { position: :asc }` | `associations: [{ ..., order: { position: asc } }]` |
+| `scope :a, where: { ... }` | `scopes: [{ name: a, where: { ... } }]` |
+| `after_create` | `events: [{ name: after_create }]` |
+| `on_field_change :e, field: :f` | `events: [{ name: e, type: field_change, field: f }]` |
+| `display_template :default, template: "{name}"` | `display_templates: { default: { template: "{name}" } }` |
+| `display_template :card, renderer: "X"` | `display_templates: { card: { renderer: X } }` |
+| `aggregate :x, function: :count, association: :y` | `aggregates: { x: { function: count, association: y } }` |
+| `positioning` | `positioning: true` |
+| `positioning scope: :pipeline_id` | `positioning: { scope: pipeline_id }` |
+| `soft_delete` | `options: { soft_delete: true }` |
+| `soft_delete column: :deleted_at` | `options: { soft_delete: { column: deleted_at } }` |
+| `auditing` | `options: { auditing: true }` |
+| `auditing only: [:title]` | `options: { auditing: { only: [title] } }` |
+| `userstamps` | `options: { userstamps: true }` |
+| `userstamps created_by: :author_id` | `options: { userstamps: { created_by: author_id } }` |
+| `userstamps store_name: true` | `options: { userstamps: { store_name: true } }` |
+| `tree` | `options: { tree: true }` |
+| `tree parent_field: :parent_id` | `options: { tree: { parent_field: parent_id } }` |
+| `timestamps true` | `options: { timestamps: true }` |
+
+For the full YAML attribute reference, see [Models Reference](models.md).
+
+## Debugging
+
+The builder exposes two methods for inspecting the generated output:
+
+### `to_hash`
+
+Returns the hash that would be passed to `ModelDefinition.from_hash`. Useful for verifying DSL output matches expected YAML structure.
+
+```ruby
+builder = LcpRuby::Dsl::ModelBuilder.new(:task)
+builder.instance_eval do
+  field :title, :string
+  timestamps true
+end
+puts builder.to_hash.inspect
+# => {"name"=>"task", "fields"=>[{"name"=>"title", "type"=>"string"}], "options"=>{"timestamps"=>true}}
+```
+
+### `to_yaml`
+
+Serializes the hash to a YAML string with the `model:` root key. Useful for migrating from DSL to YAML or comparing output.
+
+```ruby
+puts builder.to_yaml
+# => ---
+#    model:
+#      name: task
+#      fields:
+#      - name: title
+#        type: string
+#      options:
+#        timestamps: true
+```
+
+## Complete Example
+
+A deal-tracking model demonstrating all DSL features:
+
+```ruby
+# config/lcp_ruby/models/deal.rb
+define_model :deal do
+  label "Deal"
+  label_plural "Deals"
+
+  field :title, :string, label: "Title" do
+    validates :presence
+    validates :length, minimum: 3, maximum: 255
+  end
+
+  field :stage, :enum, default: "lead",
+    values: { lead: "Lead", closed_won: "Closed Won", closed_lost: "Closed Lost" }
+
+  field :value, :decimal, precision: 12, scale: 2 do
+    validates :numericality, greater_than_or_equal_to: 0, allow_nil: true
+  end
+
+  field :description, :text
+
+  belongs_to :company, model: :company, required: true
+  belongs_to :contact, model: :contact, required: false
+
+  scope :open_deals, where_not: { stage: ["closed_won", "closed_lost"] }
+  scope :won,        where: { stage: "closed_won" }
+
+  on_field_change :on_stage_change, field: :stage
+  after_create
+
+  timestamps true
+  label_method :title
+end
+```
+
+**YAML equivalent** — the same model in [YAML format](models.md#complete-example) would be approximately 50 lines.
+
+Source: `lib/lcp_ruby/dsl/model_builder.rb`, `lib/lcp_ruby/dsl/field_builder.rb`, `lib/lcp_ruby/dsl/dsl_loader.rb`