lcp 0.1.0

data/.claude/skills/lcp-host-binding/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: lcp-host-binding
+description: Use when integrating LCP Ruby with an existing Rails host application — binding metadata to existing AR models (`bind_to:`), routing CRUD to host controllers (`controller:` / `action_controllers:`), or scaffolding a host controller that includes LCP concerns. Triggers on phrases like "bind_to existing model", "wrap an existing AR model", "use existing User model", "host controller", "delegate CRUD to host", "custom controller for presenter", "lcp_ruby:host_controller generator", "LcpRuby::Controller concerns", "PresenterSetup", "CrudHelpers", "skip ResourcesController", "wizard controller for new/create", "include LCP search in my controller".
+---
+
+> **Reference docs base:** run `bundle exec rake lcp_ruby:docs` in an LCP app (version-matched), otherwise `lcp docs path`. Resolve any `docs/X` reference below under that base (or the project root if a `docs/` tree exists there).
+
+# LCP Ruby — Host Application Integration
+
+LCP usually generates ActiveRecord classes and routes them through `LcpRuby::ResourcesController`. The host-integration patterns let you escape that:
+
+1. **`bind_to:`** on a model — point metadata at an existing host AR class; no LCP-generated class, no table created.
+2. **`controller:`** on a presenter — route all CRUD for this presenter to a host controller.
+3. **`action_controllers:`** on a presenter — route specific actions only.
+4. **`LcpRuby::Controller::*` concerns** — include in your host controller to reuse LCP's auth, search, path helpers, and views.
+5. **`lcp_ruby:host_controller` generator** — scaffold a host controller with the right concerns + actions + permitted_params.
+
+## Before you write anything
+
+1. **Read the canonical reference**: `docs/reference/host-controller-integration.md` (~300 lines).
+2. **Guide**: `docs/guides/host-controller-integration.md`, `docs/guides/host-application.md`.
+3. **Model binding details** also covered in: `docs/reference/models.md` (search for `bind_to`).
+
+## Pattern 1 — `bind_to:` an existing AR model
+
+Use when the host app already has a real AR class with its own associations, callbacks, validations, etc., and you want LCP to drive its UI without re-generating the class.
+
+```yaml
+model:
+  name: employee
+  bind_to: "::Employee"            # constantize'd at boot
+  bind_to_apply: [ransack, scopes] # opt-in applicators (see table)
+  fields:                          # REQUIRED non-empty (security)
+    - { name: name, type: string }
+    - { name: email, type: email }
+    - { name: department_id, type: integer }
+  associations:                    # metadata-only — never applied as AR macros
+    - { type: belongs_to, name: department }
+  options:
+    label_method: name
+```
+
+DSL: `define_model(:employee) do bind_to "::Employee"; bind_to_apply :ransack, :scopes; field :name, :string; … end`.
+
+### What `bind_to:` does (and skips)
+
+- **Skipped:** `SchemaManager` (no table created/altered), `ModelFactory::Builder` (no `LcpRuby::Dynamic::Employee` — the existing class is used as-is), all applicators **by default**.
+- **Always applied:** `label_method` → `to_label`; registered `model_extensions` (`config.model_extensions`).
+- **`table_name` is auto-synced** from the resolved class.
+
+### `bind_to_apply` — opt-in applicators
+
+| Value | Effect |
+|-------|--------|
+| `ransack` | `ransackable_attributes` from readable fields + `ransackable_associations` from YAML |
+| `scopes` | LCP-defined scopes from YAML |
+| `validations` | YAML validations (host's own AR validations always apply) |
+| `virtual_columns` | Aggregate / virtual column class methods |
+| `transforms` | Field value transforms |
+| `computed_fields` | Before-save hooks for computed fields |
+| `custom_fields` | Runtime custom fields (REQUIRES `custom_data` JSON column on host table) |
+| `workflow` | Workflow state machine |
+| `userstamps` | `created_by`/`updated_by` callbacks |
+| `soft_delete` | Includes `Discard::Model` |
+| `auditing` | Audit trail callbacks |
+| `tree` | Tree structure (REQUIRES `parent_id` column) |
+| `sequences` | Sequence counters |
+| `positioning` | Record positioning |
+| `attachments` | Active Storage macros |
+
+`associations` and `schema` are **NOT** valid `bind_to_apply` values — both are rejected at boot with a hint pointing at `lcp_managed: true`. Use the per-item flag (next section) for selective application.
+
+Idempotent: applied features tracked in `@lcp_applied_features` Set on the class, so metadata reload won't double-register validators/callbacks.
+
+### `lcp_managed: true` — per-item selective additive behavior
+
+Default for `bind_to:` is metadata-only (column expected on host, AR macros declared by host). When you need LCP to *add* a column or AR macro to the host class, set `lcp_managed: true` on the individual `fields:` / `associations:` row:
+
+```yaml
+# YAML form
+model:
+  name: user
+  bind_to: "::LcpRuby::User"
+  fields:
+    - { name: name,       type: string }                          # host (metadata-only)
+    - { name: email,      type: string }                          # host
+    - { name: parent_id,  type: integer, lcp_managed: true }      # LCP adds column
+  associations:
+    - { type: belongs_to, name: parent, target_model: parent, lcp_managed: true, required: false }  # LCP declares AR macro
+```
+
+```ruby
+# DSL form (config/lcp_ruby/models/user.rb) — `lcp_managed: true` is a kwarg on `field` / `belongs_to` / `has_many` / `has_one`
+define_model :user do
+  bind_to "::LcpRuby::User"
+  field :name,      :string                              # host
+  field :email,     :string                              # host
+  field :parent_id, :integer, lcp_managed: true          # LCP adds column
+
+  belongs_to :parent, target_model: :parent, lcp_managed: true, required: false
+end
+```
+
+**YAML style conventions** (recommended for readability when mixing managed and host-owned rows):
+1. Place `lcp_managed: true` immediately after `type:` (or `name:` for assocs) so the runtime-significant flag lives in the first three keys, not buried at the row's end.
+2. Group managed rows together and prefix with a comment header: `# === LCP-managed ===` so a `grep` for the marker surfaces the platform-added items.
+
+Behavior:
+- **Field rows:** `add_column` to the bound table at boot when missing (idempotent, additive only — never `change_column`/`remove_column`).
+- **`belongs_to` rows:** declare AR macro on the host class + auto-add FK column (and `*_type` for polymorphic) with index.
+- **`has_many` / `has_one` rows:** declare AR macro on the host class. No schema change on this side. `accepts_nested_attributes_for` is suppressed (host opts in by writing it themselves).
+- Gated on `auto_migrate: true`. When `auto_migrate: false`, LCP emits a clear warning and skips both schema and association steps unless the host has pre-migrated all required FK columns by hand.
+
+Validator catches at boot: type mismatch with existing host column, AR reflection collision (with reload carve-out for LCP-self-added), method-shadow with HARD ERRORS for ActiveStorage attachments / Action Text rich text / encrypted attributes (silently overriding these breaks file uploads / encrypted reads / rich rendering), NOT NULL without default on populated tables, `nested_attributes` ignored warning, `counter_cache` against non-LCP target, `dependent: :delete/:delete_all` over `soft_delete` target, and managed associations targeting `api_model` (incompatible).
+
+Day-2 ops (full recipes in [bind_to Managed Fields and Associations](../../../docs/design/bind_to_managed_fields_and_associations.md) → "Day-2 lifecycle"):
+- **Remove a managed column:** host migration `remove_column`, then drop YAML row. LCP never destructively touches host tables.
+- **Rename:** host migration `rename_column` + update YAML row name; old reflection clears on next process restart.
+- **Graduate to a real Rails migration:** `bin/rails db:schema:dump` writes the column to `schema.rb`; commit. Optionally drop `lcp_managed: true` to demote to metadata-only.
+
+See [docs/design/bind_to_managed_fields_and_associations.md](../../../docs/design/bind_to_managed_fields_and_associations.md) for the full feature spec, behavior matrix, edge cases (multi-DB, polymorphic, reload safety, etc.), and validator rules.
+
+### `fields:` MUST be non-empty (security gate)
+
+`PermissionEvaluator#all_field_names` builds the `readable: all` / `writable: all` allowlist from `model_def.fields.map(&:name)`. Auto-inferring from AR columns would expose sensitive columns (`encrypted_password`, `reset_password_token`, etc.). Empty `fields:` → boot error.
+
+### Constraints
+
+| | |
+|---|---|
+| Mutually exclusive with | `table_name:`, `data_source:`, `inherits:` (STI), `table_name: _virtual` |
+| Class must inherit from | `ActiveRecord::Base` |
+| Boot errors | Class missing (with Zeitwerk hint), non-AR class, presenter declares search/advanced_filter but `ransack` not in `bind_to_apply` and host doesn't define `ransackable_attributes` |
+| Boot warnings | YAML field doesn't match a host column/method; `type: enum` field doesn't match host's `defined_enums` |
+
+## Pattern 2 — `controller:` on a presenter
+
+Route ALL 7 CRUD actions to a host controller (`index`, `show`, `new`, `create`, `edit`, `update`, `destroy`). Ancillary routes (saved filters, custom fields, custom actions, workflow transitions, approval tasks) still go to LCP controllers.
+
+```yaml
+presenter:
+  name: checkout
+  model: order
+  slug: checkout                # REQUIRED with controller:
+  controller: "checkouts"       # → ::CheckoutsController
+                                # "admin/reports" → ::Admin::ReportsController
+```
+
+- Both `PUT` and `PATCH` accepted for `update`.
+- `read_only: true` reduces to `index` + `show` only.
+- Mutually exclusive with `action_controllers:`.
+
+## Pattern 3 — `action_controllers:` per-action override
+
+Route SPECIFIC actions to a host controller; others fall through to LCP's `ResourcesController`.
+
+```yaml
+presenter:
+  name: orders
+  model: order
+  slug: orders                  # REQUIRED
+  action_controllers:
+    new:    "orders/wizard#new"
+    create: "orders/wizard#create"
+    # index, show, edit, update, destroy → LCP
+```
+
+- Format: `"<lowercase/path>#<lowercase_action>"` (regex-validated).
+- Valid action keys: `index`, `show`, `new`, `create`, `edit`, `update`, `destroy`.
+- Mutually exclusive with `controller:`.
+
+### Routing internals
+
+LCP's `config/routes.rb` has a static catch-all `scope ":lcp_slug"` that handles all "normal" presenters. `LcpRuby::Routing::PresenterRoutes.draw_custom_controller_routes` generates **explicit literal-slug routes** for `controller:` / `action_controllers:` presenters BEFORE the catch-all, so they win Rails' top-down match. Each custom route sets `defaults: { lcp_slug: <slug>, lcp_presenter: <name> }` so `set_presenter_and_model` (which reads `params[:lcp_slug]`) keeps working.
+
+## Pattern 4 — Including `LcpRuby::Controller::*` concerns in a host controller
+
+Pick the concerns you need. Each has dependencies — include in this order:
+
+```
+ErrorHandling → Authentication → PresenterSetup →
+Impersonation → Authorization → PathHelpers →
+ViewHelpers → Search → CrudHelpers
+```
+
+(`Impersonation` MUST come before `Authorization` because it overrides `effective_user`.)
+
+| Concern | Provides | Depends on |
+|---------|----------|-----------|
+| `ErrorHandling` | rescue_from `MetadataError`, `RecordNotFound` + handlers | — |
+| `Authentication` | `authenticate_user!`, `current_user`, `effective_user`, `warden`, `LcpRuby::Current.user` setup, three modes (`:none`/`:built_in`/`:external`) | — |
+| `PresenterSetup` | `set_presenter_and_model`, `current_presenter`/`current_page`/`current_model_definition`, all LCP view helpers, includes `LcpRuby::Engine.routes.url_helpers` (so `resources_path` etc. work without prefix) | — |
+| `Impersonation` | `impersonating?`, overrides `effective_user` | Auth + Setup |
+| `Authorization` | `current_evaluator`, `policy`, `policy_scope`, `authorize` (Pundit-compatible API via `PolicyFactory` — does NOT include `Pundit::Authorization`), `before_action :authorize_presenter_access`, `rescue_from Pundit::NotAuthorizedError` | Setup + Auth |
+| `PathHelpers` | `resource_path`, `resources_path`, `new_resource_path`, `edit_resource_path` | Setup |
+| `ViewHelpers` | sort, breadcrumbs, view group methods | Setup |
+| `Search` | `apply_advanced_search`, `apply_sort`, filter helpers | Setup + Auth |
+| `CrudHelpers` | `permitted_params`, `set_record`, `setup_show_view_objects`, `setup_index_view_objects`, `setup_form_view_objects`; auto-includes `LcpRuby::FormActionExecution` | Setup + Auth |
+
+Each concern checks `method_defined?` for its dependencies in `included do` and raises a descriptive error at class load time → catches misconfiguration early.
+
+### View instance variable contract
+
+When rendering LCP view templates (e.g. `render "lcp_ruby/resources/show"`), set the right ivars — most are populated by helpers from `CrudHelpers`:
+
+| View | Required ivars (helper that sets them) |
+|------|---------------------------------------|
+| `…/index` | `@records` (you), `@column_set`/`@action_set` (`setup_index_view_objects`), `@ransack_search` (Search) |
+| `…/show` | `@record` (you), `@layout_builder`/`@column_set`/`@field_resolver`/`@action_set` (`setup_show_view_objects(presenter)`) |
+| `…/new`, `…/edit` | `@record` (you), `@layout_builder`/`@form_actions` (`setup_form_view_objects(record)`) |
+
+`@presenter_definition`/`@model_definition`/`@page_definition` are set automatically by `PresenterSetup`'s `before_action`.
+
+## Pattern 5 — `lcp_ruby:host_controller` generator
+
+```bash
+rails generate lcp_ruby:host_controller PRESENTER_NAME [options]
+```
+
+| Option | Default | Values |
+|--------|---------|--------|
+| `--concerns` | `all` | comma-sep short names: `setup`, `auth`, `search`, `crud`, `paths`, `views`, `errors`, `all` |
+| `--actions` | `all` | comma-sep: `index`, `show`, `new`, `create`, `edit`, `update`, `destroy`, `all` |
+| `--views` | `lcp` | `lcp` (render LCP templates) or `custom` (generate empty view stubs) |
+
+Concern aliases: `errors`→ErrorHandling, `setup`→PresenterSetup, `auth`→Authentication+Impersonation+Authorization, `paths`→PathHelpers, `views`→ViewHelpers, `search`→Search, `crud`→CrudHelpers.
+
+Auto-resolves dependencies and orders includes topologically. Examples:
+
+```bash
+rails generate lcp_ruby:host_controller orders                         # full
+rails generate lcp_ruby:host_controller reports --concerns=setup,paths --actions=index,show
+rails generate lcp_ruby:host_controller wizard  --views=custom --actions=new,create
+rails generate lcp_ruby:host_controller listings --concerns=search     # auto-pulls setup+auth
+```
+
+Generated: `app/controllers/<plural>_controller.rb` + (for `--views=custom`) `app/views/<plural>/*.html.erb` stubs. `permitted_params` is derived from the presenter's writable fields when metadata is loadable, else a TODO comment.
+
+## Pitfalls & guidance
+
+- **`bind_to:` `fields:` empty → boot error.** Always declare what LCP needs to know about (it's the security allowlist, not a column list).
+- **`bind_to:` `associations:` are metadata-only.** Don't expect AR `belongs_to`/`has_many` to be installed — declare them on the host class. The YAML associations are used by presenters for display, FK permitting, and association select widgets.
+- **Always-applied features run regardless** of `bind_to_apply`: `label_method` and `model_extensions`.
+- **Adding a new applicator?** It must respect the bind_to + bind_to_apply contract — only run when explicitly listed (or document why it's always-applied).
+- **`controller:` / `action_controllers:` REQUIRE `slug:`.** Without it, the route generator can't draw the explicit slug-scoped route.
+- **Don't skip the include order** for concerns — `Impersonation` before `Authorization` is critical (overrides `effective_user`); other concerns will load-time-error if their deps are missing.
+- **Custom controller can render LCP views** — set the right ivars (table above) and `render "lcp_ruby/resources/index"` etc. Or use `--views=custom` to start from blank stubs.
+- **The leading `/` on `controller:` paths** is added internally by the router to break out of the engine module scope into the host namespace. Don't add it yourself in YAML.
+- **Ransack for bind_to models:** if a presenter declares `search_parameters` or `advanced_filter` on a `bind_to:` model, either include `ransack` in `bind_to_apply` OR define `ransackable_attributes` on the host class. Otherwise: boot error.
+- **Custom fields on bind_to:** requires `bind_to_apply: [custom_fields]` AND a `custom_data` JSON/JSONB column on the host table. Without the column, dynamic accessors will fail at runtime.
+
+## Advanced (one-line pointers)
+
+Stuff with its own dedicated reference / guide. **Browse `docs/feature-catalog.md`** — sections `## Bind To`, `## Host Controller`, `## Authentication`, `## API Backed Models`. Don't inline syntax; just open the relevant doc.
+
+- **Engine configuration full surface** — `LcpRuby.configure do |c| ... end` knobs: authentication mode, mount paths, model_extensions hooks (`on_model_ready`), service registry discovery, hierarchy_resolver, group_source, role_source, permission_source, workflow_source, audit model names. → `docs/reference/engine-configuration.md`.
+- **Authentication tri-mode** — `:none` (anonymous), `:built_in` (Devise via `lcp_ruby:install_auth` generator: lockable, recoverable, timeoutable, registration toggle, account locking), `:external` (host app provides `current_user`). → `docs/guides/host-application.md` `## Step 5: Set Up current_user`, feature-catalog `## Authentication`.
+- **Concern dependency guards** — each concern's `included do` block calls `method_defined?` for required methods and raises descriptive error at class-load time → catches misconfigured include order before first request. → host-controller-integration.md `## Concern dependency guards`.
+- **View instance variable contract** — full table of which ivars LCP templates expect for index/show/new/edit, mapped to which helper sets them (`setup_show_view_objects`, `setup_index_view_objects`, `setup_form_view_objects`). Critical when hand-crafting a host action that renders LCP templates. → host-controller-integration.md `## View instance variable contract`.
+- **Hybrid routing internals** — explicit literal-slug routes drawn BEFORE the `scope ":lcp_slug"` catch-all by `LcpRuby::Routing::PresenterRoutes.draw_custom_controller_routes`; each sets `defaults: { lcp_slug:, lcp_presenter: }` so `set_presenter_and_model` keeps working unchanged. `rails routes | grep <slug>` to verify precedence. → host-controller-integration.md `## Routing architecture`.
+- **Impersonation under host integration** — include `LcpRuby::Controller::Impersonation` BEFORE Authorization (overrides `effective_user`). Inherits target user's groups. → `docs/guides/impersonation.md`, feature-catalog `## Groups → Groups with Impersonation`.
+- **Workflow on bind_to models** — `bind_to_apply: [workflow]` then define workflow in `config/lcp_ruby/workflows/` referencing the LCP model name; `before_save` guard installed on the host AR class. → `lcp-workflow` skill.
+- **Custom fields on bind_to models** — `bind_to_apply: [custom_fields]` AND host table needs `custom_data` JSON/JSONB column. → `lcp-custom-field` skill.
+- **Three-source principle for Groups / Roles / Permissions / Workflow / Pages** — same pattern as `bind_to:`: YAML/DSL static + DB-backed model + host provider class. Each has `*_source` config knob and a contract validator. → `docs/reference/groups.md`, `role-source.md`, `permission-source.md`, `workflow.md` (Three Definition Sources), `pages.md` (Page Source).
+- **API-backed models as alternative to `bind_to`** — when the data lives in an external HTTP API rather than a host AR table, use `data_source: type: rest_json` or `:host` (host provides ActiveModel data source). Cross-source associations supported. → `docs/reference/api-backed-models.md`, feature-catalog `## API Backed Models`.
+- **Generator concern auto-resolution** — `--concerns=search` auto-pulls `PresenterSetup`, `Authentication`, `Authorization` in correct topological order. `--concerns=all` includes all 9. Aliases: `errors`/`setup`/`auth`/`paths`/`views`/`search`/`crud`. → host-controller-integration.md `## Concern aliases`.
+- **`PresenterSetup` magic** — auto-registers all 11 LCP view helpers (Display, Form, Layout, Tree, Search, …) AND includes `LcpRuby::Engine.routes.url_helpers`, so host controllers get `resources_path`, `landing_path`, `new_resource_path` etc. without `lcp_ruby.` prefix. `url_for` in LCP partials resolves against the engine's route table. → host-controller-integration.md.
+- **Authorization concern is NOT Pundit** — provides Pundit-compatible API (`authorize`, `policy`, `policy_scope`) backed by `LcpRuby::Authorization::PolicyFactory`. Does NOT include `Pundit::Authorization`. Avoids version conflicts. → host-controller-integration.md.
+- **`bind_to` always-applied features** — `label_method` → `to_label`, plus any `on_model_ready` blocks from `config.model_extensions`. Run regardless of `bind_to_apply`. → host-controller-integration.md `## Always-applied features`.
+- **Boot-time validation** — class resolution (Zeitwerk hint), AR check, field-column matching (warning), enum value matching (warning), Ransack requirement enforcement. → host-controller-integration.md `## Boot-time validation`.
+
+When in doubt about whether a capability exists at all → grep `docs/feature-catalog.md`.
+
+## After editing
+
+1. Restart the dev server (model bindings + custom routes draw at boot).
+2. `bundle exec rake lcp_ruby:validate` (auto-fired by the `lcp-validate` hook for `examples/*/config/lcp_ruby/`).
+3. For a new host controller: hit each routed action in the browser to confirm the right controller handles it. `rails routes | grep <slug>` to verify route precedence.
+
+## Related skills / docs
+
+- Defining the LCP model first → `lcp-model` skill (then add `bind_to:`).
+- Custom field bind_to gotchas → `lcp-custom-field` skill.
+- Workflow on a bind_to model → `lcp-workflow` skill (`bind_to_apply: [workflow]` + workflow definition referencing the host model).
+- Permissions for host-bound models work normally → `lcp-permissions` skill.
+- Full host-app setup walkthrough (initial `rails new` → first model+presenter+menu) → `docs/guides/host-application.md`.
+- Three-source principle this fits into → see CLAUDE.md "Configuration Source Principle" table.

data/.claude/skills/lcp-model/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: lcp-model
+description: Use when creating or modifying LCP Ruby model definitions in `config/lcp_ruby/models/` (either YAML `*.yml` or DSL `*.rb`). Triggers on phrases like "add a model", "model field", "model validation", "belongs_to", "has_many", "scope", "soft_delete", "auditing", "userstamps", "tree", "positioning", "STI", "abstract model", "aggregate", "display_template", "data_source", "API-backed", "bind_to". Also for editing existing model files under `config/lcp_ruby/models/`.
+---
+
+> **Reference docs base:** run `bundle exec rake lcp_ruby:docs` in an LCP app (version-matched), otherwise `lcp docs path`. Resolve any `docs/X` reference below under that base (or the project root if a `docs/` tree exists there).
+
+# LCP Ruby — Model Authoring
+
+Models define data structure: tables, columns, validations, associations, scopes, lifecycle events. Defined per-file in `config/lcp_ruby/models/<name>.{rb,yml}`. The engine builds `ActiveRecord` classes under `LcpRuby::Dynamic::*` at boot.
+
+> **New entity from scratch?** If the user is creating a brand-new model **and** also needs a presenter + permissions + view group (the typical case for a fresh CRUD entity), prefer `rails generate lcp_ruby:entity NAME field:type ...` — one command produces all four files atomically. Hand-writing is for **editing** existing models or for cases the CLI grammar can't express. See `lcp-getting-started` skill, "Fast path" subsection, or `docs/design/entity_generator.md` for the full grammar.
+
+## Before you write anything
+
+1. **Read the canonical reference** — pick one based on chosen format:
+   - DSL (`.rb`): `docs/reference/model-dsl.md` (full, ~1100 lines)
+   - YAML (`.yml`): `docs/reference/models.md` (full, ~2200 lines)
+   - JSON Schema: `lib/lcp_ruby/schemas/model.json` (authoritative for valid YAML keys)
+2. **Mirror the project's chosen format.** Look at neighbouring files in `config/lcp_ruby/models/` — do not introduce a new format if all existing files use one. A given model name must be unique across `.yml` and `.rb`.
+3. **Check the host project's CLAUDE.md** for any model conventions (e.g., naming, prefixes for abstract models like `_auditable`).
+
+## File location
+
+```
+config/lcp_ruby/models/<name>.rb         # DSL
+config/lcp_ruby/models/<name>.yml        # YAML
+```
+
+`<name>` is the model name in `snake_case` and becomes the table name (auto-pluralised). Files starting with `_` (e.g. `_auditable.rb`) are conventionally abstract templates.
+
+## Minimal model
+
+DSL:
+```ruby
+define_model :task do
+  field :title, :string do
+    validates :presence
+    validates :length, minimum: 3, maximum: 255
+  end
+  field :completed, :boolean, default: false
+  timestamps true
+  label_method :title
+end
+```
+
+YAML:
+```yaml
+model:
+  name: task
+  fields:
+    - name: title
+      type: string
+      validations:
+        - { type: presence }
+        - { type: length, minimum: 3, maximum: 255 }
+    - name: completed
+      type: boolean
+      default: false
+  options:
+    timestamps: true
+  label_method: title
+```
+
+## Field types
+
+**Base types** (15): `string`, `text`, `integer`, `float`, `decimal` (use `precision:`/`scale:`), `boolean`, `date`, `datetime`, `enum` (requires `values:`), `file`, `rich_text`, `json` (jsonb on PG), `uuid`, `attachment` (Active Storage, no DB column), `array` (requires `item_type:`).
+
+**Built-in business types**: `email`, `phone`, `url`, `color`, `bigint` — these bundle transforms + validations + input hints. See `docs/reference/types.md`.
+
+**Custom types** can be defined in `config/lcp_ruby/types/` — see `docs/reference/types.md`.
+
+## Common per-model options
+
+| Option | Purpose | Doc section |
+|--------|---------|-------------|
+| `timestamps true` | Adds `created_at`/`updated_at` | `models.md` |
+| `soft_delete` | Logical deletion (`discarded_at`) | `models.md#soft_delete` |
+| `auditing` | Change audit log | `models.md#auditing` |
+| `userstamps` | `created_by_id`/`updated_by_id` | `models.md#userstamps` |
+| `tree` | Self-referential hierarchy | `models.md#tree` + `docs/reference/tree-structures.md` |
+| `positioning` | Drag-and-drop ordering | `models.md#positioning` |
+| `custom_fields true` | Runtime user-defined fields | `docs/reference/custom-fields.md` |
+| `slug_field :slug` | Slug-based routing (also add unique index + format validation) | `models.md#slug_field` |
+| `data_source` | API-backed model (no DB table) | `docs/reference/api-backed-models.md` |
+| `bind_to: "::HostClass"` | Use existing host AR model instead of generating one | `docs/reference/models.md` |
+| `abstract` + `inherits:` | Template / STI parent | `models.md#abstract`, `models.md#inherits` |
+
+## Associations
+
+Both `belongs_to` and `has_many`/`has_one` require **either** `model:` (LCP-managed model) **or** `class_name:` (host AR class). Polymorphic, `through:`, `nested_attributes:`, `primary_key:` (business-key joins) are all supported. See `docs/reference/model-dsl.md#associations` (or `models.md#associations`).
+
+`nested_attributes` requires `inverse_of:`. For sortable nested rows on a `has_many`, set `order: { position: :asc }` and use `sortable: true` in the presenter's `nested_fields`.
+
+For intentionally one-directional `belongs_to` (audit/owner/author refs where reverse traversal would be noise), set `skip_inverse_check: true` to silence the missing-`has_many` warning from `lcp_ruby:validate`. Only valid on `belongs_to` — has_many/has_one without inverse is a real bug. See `models.md#skip_inverse_check`.
+
+## Scopes
+
+Declarative only — `where`, `where_not`, `order`, `limit`. No raw SQL or lambdas in YAML/DSL config. For runtime parameters, use `type: :parameterized` with typed `parameters:`. See `models.md#scopes`. Scopes are referenced from `presenter.search.filter` blocks.
+
+## Validations
+
+Built-in types: `presence`, `length`, `numericality`, `format` (use **string** patterns, not regex literals — for portability), `inclusion`, `exclusion`, `uniqueness`, `confirmation`, `comparison`, `array_length`, `array_inclusion`, `array_uniqueness`, `service` (named service), `custom` (full class). All accept `message:`, `allow_blank:`, `if:`, `unless:` (method-name strings only). See `model-dsl.md#validations`.
+
+For cross-field validators: `validates_model :custom, validator_class: "DateRangeValidator"`.
+
+## Lifecycle events & display templates & aggregates
+
+These are advanced — read the relevant section before adding:
+- **Events**: `after_create`, `after_update`, `before_destroy`, `after_destroy`, `on_field_change` → wired to event handlers (`docs/guides/event-handlers.md`).
+- **Display templates**: rich record labels with `{field}` interpolation, custom renderers, or partials. `models.md#display-templates`.
+- **Aggregates**: virtual SQL-derived columns (count/sum/min/max/avg over an association, or full custom SQL, or service). Useful for index columns and dashboards. `models.md#aggregates`.
+
+## Pitfalls & guidance
+
+- **Inheritance.** `inherits:` works in two modes: abstract template (fields merge into child, no parent table) and STI (`options.sti: true` on parent, single shared table). They behave differently — read `models.md#inherits`.
+- **Indexes** are declared on the model (`index :col, unique: true`); the engine creates them at boot. Don't write ad-hoc `add_index` migrations.
+- **Tables** must come from the YAML/DSL — `SchemaManager` creates them at boot. Never write `create_table` in Ruby code (see project CLAUDE.md "Table creation rule").
+- **Format validation regexes** must be strings (e.g. `'\A[a-z0-9-]+\z'`), not Ruby regex literals. The string is converted to a `Regexp` at runtime.
+- **`bind_to:`** — when integrating an existing host AR model, the table already exists. Don't duplicate columns; just declare what LCP needs to know about.
+- **Field-level vs model-level validations:** both styles produce identical output. Prefer field-block style for readability when the validation belongs to one field.
+
+## Advanced (one-line pointers)
+
+Stuff with its own dedicated reference / guide. **Browse `docs/feature-catalog.md` first** — section names below match it 1:1. Don't inline syntax for these unless asked; just open the relevant doc.
+
+- **Virtual columns** — query-time SQL-derived columns: declarative aggregates (function/association/where/distinct/default), expression columns (raw SQL with `%{table}` placeholder, `auto_include:`), JOIN-based columns (deduplicated), window functions, service columns. → `docs/guides/virtual-columns.md`, `docs/design/virtual_columns.md`, feature-catalog `## Virtual Fields`. (YAML alias `aggregates` → `virtual_columns`, `sql` → `expression`.)
+- **Computed fields** (`computed: { service: ClassName }`) — read-only fields populated by a Ruby service on save. Different from virtual columns: stored in DB, computed before-save vs computed at query time. → `docs/guides/computed-fields.md`, `docs/reference/models.md#computed`.
+- **Field accessors / virtual fields with `source:`** (beta) — no-column fields backed by `json_field` service or `:external` accessor; expose JSON column keys as typed first-class fields, support default values + inclusion validation. → `docs/design/fields_accessors.md`, `docs/guides/virtual-columns.md` (Virtual Field sub-section). Useful pattern: user preferences as `user.profile_data` keys.
+- **Sequences** — auto-numbering on field via `sequence:` on a `field`. Format strings, scope, padding. → `docs/guides/sequences.md`, `docs/reference/models.md#sequence`.
+- **Transforms** (`transforms: [strip, downcase, parameterize]`) — auto value transforms on save. Custom transforms via `app/lcp_services/`. → `docs/reference/models.md#transforms`.
+- **Default services** (`default: { service: ClassName }`) — computed defaults beyond literals. → `docs/reference/models.md#default`.
+- **Attachments** — image variants (`resize_to_limit`), multi-file (`mode: multiple`, `max_files`), validation (`max_size`, `content_types`, MIME wildcards). → `docs/guides/attachments.md`, feature-catalog `## Attachments`.
+- **Association `primary_key:` (business-key joins)** — join on a non-id column (e.g. `division.vema_code`). Boot validations: column exists, type-compat, uniqueness, reciprocity. Rejected with `through:`/polymorphic/tree/cross-source. Importer write-back uses business key. → `docs/design/association_primary_key.md`, feature-catalog `## Association Primary Key`.
+- **Model inheritance details** — abstract+STI combined chains, additive validation inheritance, deep-merged options, multi-level chained inheritance, scope inheritance, STI permission fallback (child → parent → `_default`). → `docs/design/model_inheritance.md`, feature-catalog `## Model Inheritance`.
+- **Tree structures** — closure tables, depth column, counter cache, recursive scopes (`descendants`, `ancestors`). → `docs/reference/tree-structures.md`, `docs/guides/tree-structures.md`.
+- **Soft delete** — `discarded_at`, custom column, `with_discarded` / `kept` scopes, controller-level `restore`/`permanently_destroy` actions. → `docs/guides/soft-delete.md`.
+- **Userstamps** — `created_by_id`/`updated_by_id` + `store_name: true` denormalized snapshots, custom column names. → `docs/guides/userstamps.md`.
+- **Auditing** — `lcp_audit_logs` model contract, expand_custom_fields/expand_json_fields, audit history section in presenters. → `docs/reference/auditing.md`, `docs/guides/auditing.md`.
+- **Eager loading** — `includes` vs `eager_load` semantics, auto-detection for nested fields, N+1 patterns. → `docs/guides/eager-loading.md`.
+- **API-backed models** (`data_source: type: rest_json` or `:host`) — REST adapter with auth/pagination/cache, host-provided ActiveModel data sources, cross-source associations (DB↔API), caching & resilience (stale-on-error). → `docs/reference/api-backed-models.md`, `docs/guides/api-backed-models.md`, feature-catalog `## API Backed Models`.
+- **Display templates with renderer/partial** — beyond `template:` interpolation, you can plug a `BaseRenderer` subclass or a Rails partial. → `docs/reference/models.md#display-templates`.
+- **Slug field reserved-segment validation** — auto-added exclusion validation prevents slug values colliding with routing segments (`new`, `edit`, `actions`, …). → `docs/design/record_aliases.md`.
+
+When in doubt about whether a capability exists at all → grep `docs/feature-catalog.md` (auto-generated inventory of every shipped capability with category + doc/source links).
+
+## After editing
+
+1. Run validation from the host app directory: `bundle exec rake lcp_ruby:validate`
+   (Picked up automatically by the project's `lcp-validate` PostToolUse hook for files under `examples/*/config/lcp_ruby/`.)
+2. If you changed schema (added/removed fields or changed types), restart the dev server — schema rebuilds at boot.
+3. Run tests if any exist for this model: `bundle exec rspec spec/integration/<model>_spec.rb`.
+4. Look at `examples/showcase/config/lcp_ruby/models/` for working patterns of every option.
+
+## i18n principle
+
+**No user-visible literals in YAML / DSL.** Model `label`, `label_plural`, field `label:`, and enum value labels all resolve through `I18n.t` with humanize as fallback. The translation lives in `config/locales/<locale>.yml`, not in the model definition.
+
+Authoring pattern:
+
+```ruby
+# config/lcp_ruby/models/grade.rb
+field :recorded_on, :date  # NO `label: "Recorded on"` — humanize default + translation
+```
+
+```yaml
+# config/locales/cs.yml
+cs:
+  lcp_ruby:
+    models:
+      grade:
+        one: "Známka"
+        other: "Známky"
+        fields:
+          recorded_on: "Zaznamenáno"
+```
+
+Verify with `bundle exec rake lcp_ruby:i18n_check` (boots Rails, asserts every Tier 1 key has a translation in every configured locale). See `docs/reference/i18n_check.md`.
+
+## Related skills / docs
+
+- Adding/changing UI for a model → use `lcp-presenter` skill.
+- Locking down access → use `lcp-permissions` skill.
+- Custom field types → `docs/reference/types.md` and `docs/guides/custom-types.md`.
+- DB-backed models → see `docs/reference/api-backed-models.md` for the host-API pattern.