lcp 0.1.0

data/docs/reference/engine-configuration.md

@@ -0,0 +1,989 @@
+# Engine Configuration Reference
+
+Configure LCP Ruby in `config/initializers/lcp_ruby.rb`:
+
+```ruby
+LcpRuby.configure do |config|
+  config.metadata_path = Rails.root.join("config", "lcp_ruby")
+  config.role_method = :lcp_role
+  config.user_class = "User"
+  config.mount_path = "/"
+  config.auto_migrate = true
+  config.label_method_default = :to_s
+  config.parent_controller = "::ApplicationController"
+end
+```
+
+## Options
+
+### `authentication`
+
+| | |
+|---|---|
+| **Type** | `Symbol` |
+| **Default** | `:external` |
+| **Allowed values** | `:none`, `:built_in`, `:external` |
+
+Controls how user authentication is handled.
+
+| Value | Behavior |
+|-------|----------|
+| `:external` | The host application handles authentication (default). LCP Ruby expects `current_user` to be set by the host. |
+| `:built_in` | LCP Ruby provides Devise-based authentication with login, registration, and session management. |
+| `:none` | No authentication. All users are anonymous. Useful for public-facing or development setups. |
+
+```ruby
+LcpRuby.configure do |config|
+  config.authentication = :built_in
+end
+```
+
+When `authentication` is `:built_in`, additional authentication options are available:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `auth_allow_registration` | `Boolean` | `false` | Allow new user self-registration |
+| `auth_password_min_length` | `Integer` | `8` | Minimum password length |
+| `auth_session_timeout` | `Duration` | `nil` | Session timeout (e.g., `30.minutes`). `nil` means no timeout. |
+| `auth_lock_after_attempts` | `Integer` | `0` | Lock account after N failed login attempts. `0` disables locking. |
+| `auth_lock_duration` | `Duration` | `30.minutes` | How long accounts remain locked |
+| `auth_mailer_sender` | `String` | `"noreply@example.com"` | From address for authentication emails |
+| `auth_after_login_path` | `String` | `"/"` | Redirect path after successful login |
+| `auth_after_logout_path` | `String` | `nil` | Redirect path after logout. `nil` uses the default. |
+
+```ruby
+LcpRuby.configure do |config|
+  config.authentication = :built_in
+  config.auth_allow_registration = true
+  config.auth_session_timeout = 30.minutes
+  config.auth_lock_after_attempts = 5
+  config.auth_after_login_path = "/dashboard"
+end
+```
+
+#### Built-in auth URLs
+
+When `authentication: :built_in` is enabled, Devise mounts under `/auth` (not the Devise default `/users`). The slug-based catchall `/:lcp_slug/...` would otherwise intercept the default URLs, so the engine renames them up-front:
+
+| Action | URL | HTTP method |
+|--------|-----|-------------|
+| Login form | `GET /auth/login` | — |
+| Submit login | `POST /auth/login` | — |
+| Logout | `DELETE /auth/logout` (also `GET` for direct visits / plain links) | — |
+| Registration | `GET /auth/register`, `POST /auth/register` | only when `auth_allow_registration: true` |
+| Password reset | `GET /auth/password/new`, `POST /auth/password` | — |
+
+The Devise default URLs (`/users/sign_in`, `/users/sign_out`) are **not** routed — they would fall through to the catchall and produce a 404. Use `/auth/login` etc. in links, redirects, and tests.
+
+### `metadata_path`
+
+| | |
+|---|---|
+| **Type** | `Pathname` or `String` |
+| **Default** | `Rails.root.join("config", "lcp_ruby")` |
+
+Directory containing `models/`, `presenters/`, and `permissions/` YAML subdirectories. Change this when you want metadata in a non-standard location (e.g., a shared gem or a monorepo subdirectory).
+
+### `role_method`
+
+| | |
+|---|---|
+| **Type** | `Symbol` |
+| **Default** | `:lcp_role` |
+
+Method called on the current user object to determine their roles. Must return an **array of role name strings** (e.g., `["admin", "sales_rep"]`). The values are matched against role names in [permissions YAML](permissions.md). Your User model must implement this method.
+
+```ruby
+class User < ApplicationRecord
+  def lcp_role
+    roles.pluck(:name)  # => ["admin", "sales_rep"]
+  end
+end
+```
+
+See [Multiple Roles](permissions.md#multiple-roles) for merge semantics when a user has more than one role.
+
+### `user_class`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"User"` |
+
+Class name of your application's user model. Used by:
+- **Authorization** — resolving the user class for permission evaluation
+- **Userstamps** — `belongs_to` associations on `created_by` / `updated_by` FK columns point to this class
+
+The user model must respond to `id` and `name` (the latter is used for `store_name` snapshots).
+
+#### Built-in user model attributes
+
+When using `authentication: :built_in`, `LcpRuby::User` provides these extension points beyond the standard Devise fields:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `lcp_role` | JSON array | Role names for permission evaluation. Always returned as `Array` via the `lcp_role` accessor. |
+| `profile_data` | JSON hash | Extensible key-value storage for per-user data (preferences, settings, app-specific fields). Default: `{}`. |
+| `active` | boolean | When `false`, the user cannot sign in. |
+
+Access `profile_data` via the `profile` method which returns a `HashWithIndifferentAccess`:
+
+```ruby
+user.profile[:locale]    # => "cs"
+user.profile["theme"]    # => "dark"
+```
+
+For **external auth**, if you want to use `profile_data`, add a JSON column to your user model and implement a `profile` method with the same contract, or use `on_model_ready` to extend behavior.
+
+##### Keys the platform reads from `profile_data`
+
+The engine consumes a small set of well-known keys on every authenticated (and, for `locale`, every) request. Any writer that sets them — the "My Settings" presenter, a seed, a console `update!`, a host-app endpoint — takes effect on the next render. There is no presenter DSL or callback involved: the contract is between the platform and the JSON keys, not between the platform and any particular presenter.
+
+| Key | Used by | Allowed values |
+|---|---|---|
+| `theme` | `LayoutHelper#current_theme_default` | `light`, `dark`, `auto` |
+| `density` | `LayoutHelper#current_density_default` | `comfortable`, `compact` |
+| `border_radius` | `LayoutHelper#current_radius_default` | `rounded`, `sharp` |
+| `locale` | `LcpRuby::Controller::LocaleBinding#apply_user_locale` | any symbol in `I18n.available_locales` |
+
+Unknown values fall through to the engine config default (for theme/density/border_radius) or `I18n.default_locale` (for locale).
+
+**Programmatic writers:**
+- Presenter-backed forms — expose preferences as `service: json_field` virtual fields (see the showcase `my_settings` presenter for a reference implementation).
+- Direct `user.update!(profile_data: ...)` — works from console/seeds/custom controllers; merges per-key so unrelated keys are not clobbered.
+
+Concurrent writes to the same key use last-write-wins semantics (standard AR update); writes to different keys never collide.
+
+### `mount_path`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"/"` |
+
+The path prefix where the engine is mounted. Must match the path in your `config/routes.rb` mount statement. Used by internal path helpers.
+
+### `auto_migrate`
+
+| | |
+|---|---|
+| **Type** | `Boolean` |
+| **Default** | `true` |
+
+When `true`, the engine automatically creates and updates database tables on boot to match model definitions. Set to `false` in production if you manage migrations manually or want to prevent schema changes at startup.
+
+**Schema change behavior:**
+
+| Action | Result |
+|--------|--------|
+| New model YAML added | Table created on boot |
+| Field added to YAML | Column added on boot |
+| Field removed from YAML | Column remains in DB (migrations are additive only) |
+| Field type changed | No effect — existing column type is unchanged |
+| `auto_migrate: false` | No schema changes on boot |
+
+**Removing a column after dropping a field from YAML**
+
+Because `auto_migrate` is additive, orphan columns stay in the database when you delete a field from a YAML model. Use a standard Rails migration to remove them:
+
+```bash
+bundle exec rails generate migration DropOldField
+```
+
+```ruby
+# db/migrate/<timestamp>_drop_old_field.rb
+class DropOldField < ActiveRecord::Migration[8.1]
+  def change
+    remove_column :service_orders, :model_name, :string
+  end
+end
+```
+
+```bash
+bundle exec rails db:migrate
+```
+
+**Renaming a field** (`model_name` → `vehicle_model` in YAML) creates **both** columns on next boot. Pick one:
+
+1. **Preserve data** — `rename_column :service_orders, :model_name, :vehicle_model` instead of letting `auto_migrate` add the new one.
+2. **Drop and recreate** — `remove_column :service_orders, :model_name, :string` and let `auto_migrate` add `:vehicle_model` (empty) on next boot.
+
+If the orphan column collides with an `ActiveRecord::Base` method (`type`, `model_name`, `changes`, `destroy`, …), the application boots into `ActiveRecord::DangerousAttributeError` until the column is removed from the database. `ConfigurationValidator` flags these names when the field is in YAML, but cannot detect orphans — manual cleanup is required.
+
+A `rake lcp_ruby:sync_schema` task that lists/drops orphan columns is on the roadmap (see [aggregated improvement tasks](../improve-tasks/aggregated.md), item C6).
+
+> **Production note:** Consider setting `auto_migrate: false` in production so that schema changes go through a controlled migration/review process rather than running automatically at startup.
+
+### `label_method_default`
+
+| | |
+|---|---|
+| **Type** | `Symbol` |
+| **Default** | `:to_s` |
+
+Default method called on records to generate display labels (e.g., in association selects). Overridden per-model via the `options.label_method` attribute in [model YAML](models.md#options).
+
+### `parent_controller`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"::ApplicationController"` |
+
+The host application controller that LCP Ruby's controllers inherit from. Change this to inherit authentication, locale settings, or other before-filters from a different base controller.
+
+### `dev_toolbar`
+
+| | |
+|---|---|
+| **Type** | `Boolean` |
+| **Default** | `nil` (disabled) |
+
+Enables a developer toolbar overlay in the browser. The toolbar displays metadata about the current page — presenter name, model, page definition, zone names, widget types, and record IDs. Only active when **both** `dev_toolbar` is `true` and `Rails.env.development?` is true, so it is never accidentally exposed in production.
+
+```ruby
+LcpRuby.configure do |config|
+  config.dev_toolbar = true
+end
+```
+
+The toolbar injects `data-lcp-dev-*` attributes into page elements and renders a floating panel via `dev_toolbar.js` and `dev_toolbar.css`.
+
+### `theme`
+
+| | |
+|---|---|
+| **Type** | `Hash` |
+| **Default** | `{ default: :auto, allow_user_switch: true, density: { default: :comfortable }, border_radius: { default: :rounded }, overrides: {}, palettes: {} }` |
+
+Controls the platform's theming system. Can also be configured via `config/lcp_ruby/theme.yml`.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `default` | Symbol | `:auto` | Default color theme (`:auto`, `:light`, `:dark`) |
+| `allow_user_switch` | Boolean | `true` | Whether the `my_settings` presenter renders the user-facing theme picker |
+| `density.default` | Symbol | `:comfortable` | Default UI density (`:comfortable`, `:compact`) |
+| `border_radius.default` | Symbol | `:rounded` | Default border radius (`:rounded`, `:sharp`) |
+| `overrides` | Hash | `{}` | Override specific CSS variables (e.g., `{ "--lcp-primary" => "#1a73e8" }`) |
+| `palettes` | Hash | `{}` | Per-theme palette overrides (`{ light: { ... }, dark: { ... } }`) |
+
+```ruby
+LcpRuby.configure do |config|
+  config.theme = {
+    default: :dark,
+    allow_user_switch: true,
+    palettes: {
+      light: { "--lcp-primary" => "#e91e63" },
+      dark:  { "--lcp-primary" => "#f48fb1" }
+    }
+  }
+end
+```
+
+See [Theming Guide](../guides/theming.md) and [Theme Variables Reference](theme-variables.md) for details.
+
+### `strict_loading`
+
+| | |
+|---|---|
+| **Type** | `Symbol` |
+| **Default** | `:never` |
+
+Controls whether ActiveRecord `strict_loading` is applied to records in index, show, and edit views. When enabled, accessing a lazy-loaded association raises `ActiveRecord::StrictLoadingViolationError`, helping catch N+1 queries during development.
+
+| Value | Behavior |
+|-------|----------|
+| `:never` | Disabled (default) |
+| `:development` | Enabled in `development` and `test` environments |
+| `:always` | Enabled in all environments |
+
+```ruby
+LcpRuby.configure do |config|
+  config.strict_loading = :development
+end
+```
+
+See [Eager Loading](eager-loading.md) for details on the auto-detection system.
+
+### `role_source`
+
+| | |
+|---|---|
+| **Type** | `Symbol` |
+| **Default** | `:implicit` |
+| **Allowed values** | `:implicit`, `:model` |
+
+Controls where role definitions come from. When set to `:model`, roles are validated against a DB-backed model at authorization time. Unknown role names are filtered out and logged as warnings.
+
+```ruby
+LcpRuby.configure do |config|
+  config.role_source = :model
+end
+```
+
+See [Role Source Reference](role-source.md) for the model contract, registry API, and setup details.
+
+### `role_model`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"role"` |
+
+Name of the LCP Ruby model that stores role definitions. Only used when `role_source` is `:model`. The model must satisfy the [role model contract](role-source.md#model-contract).
+
+### `role_model_fields`
+
+| | |
+|---|---|
+| **Type** | `Hash` |
+| **Default** | `{ name: "name", active: "active" }` |
+
+Maps the role model contract's logical fields to actual field names on your model. Only used when `role_source` is `:model`.
+
+```ruby
+LcpRuby.configure do |config|
+  config.role_model_fields = { name: "role_key", active: "enabled" }
+end
+```
+
+### `impersonator_roles`
+
+| | |
+|---|---|
+| **Type** | `Array` |
+| **Default** | `[]` |
+
+List of role names **allowed to impersonate** other roles (the gate). When empty (default), impersonation is disabled. Only users whose real role is in this list can activate impersonation.
+
+```ruby
+LcpRuby.configure do |config|
+  config.impersonator_roles = ["admin"]
+end
+```
+
+### `impersonatable_roles`
+
+| | |
+|---|---|
+| **Type** | `Array` or `nil` |
+| **Default** | `nil` (= "all roles defined in permissions") |
+
+Optional whitelist that **narrows the impersonation dropdown** to a subset of roles. When `nil`, the dropdown shows every role found across YAML and DB-backed permission definitions. Set this when you have internal roles (e.g. `service_account`, `audit_bot`) that should never appear as impersonation targets.
+
+```ruby
+LcpRuby.configure do |config|
+  config.impersonator_roles    = ["admin"]                    # who can impersonate
+  config.impersonatable_roles  = ["viewer", "editor", "manager"]  # who they can become
+end
+```
+
+> **Deprecated:** `impersonation_roles` is a backwards-compatible alias for `impersonator_roles` and emits a deprecation warning. New code should use the explicit `impersonator_roles` / `impersonatable_roles` pair.
+
+See the [Impersonation Guide](../guides/impersonation.md) for setup and usage details.
+
+### `menu_mode`
+
+| | |
+|---|---|
+| **Type** | `Symbol` |
+| **Default** | `:auto` |
+
+Controls how the navigation menu is built.
+
+| Value | Behavior |
+|-------|----------|
+| `:auto` | Auto-generate from view groups if no `menu.yml`; use `menu.yml` + auto-append unreferenced view groups if it exists |
+| `:strict` | `menu.yml` is required and is the sole source of truth; no auto-append |
+
+```ruby
+LcpRuby.configure do |config|
+  config.menu_mode = :strict
+end
+```
+
+See [Menu Reference](menu.md) for the full `menu.yml` YAML schema and [Menu Guide](../guides/menu.md) for setup examples.
+
+### `attachment_max_size`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"50MB"` |
+
+Global default maximum file size for attachment fields. Individual fields can override this with their own `max_size` option. Supports `KB`, `MB`, and `GB` suffixes.
+
+```ruby
+LcpRuby.configure do |config|
+  config.attachment_max_size = "50MB"
+end
+```
+
+### `landing_page`
+
+| | |
+|---|---|
+| **Type** | `String`, `Hash`, or `nil` |
+| **Default** | `nil` |
+
+Determines which page a user is redirected to after they hit the engine root (`GET /`) — i.e. the **post-login redirect**, **after-sign-in landing**, **default page**, or **home page** for the engine. Without this option, root requests fall back to the first navigable view group (alphabetical for ties). Three forms are accepted:
+
+**1. Single page for everyone (string):**
+
+```ruby
+LcpRuby.configure do |config|
+  config.landing_page = "dashboard"
+end
+```
+
+The value is a [presenter slug](presenters.md#slug) or a [page slug](pages.md). The user is redirected to `/<slug>` regardless of role.
+
+**2. Per-role mapping (hash):**
+
+```ruby
+LcpRuby.configure do |config|
+  config.landing_page = {
+    "admin"   => "admin-dashboard",
+    "manager" => "team-overview",
+    "default" => "showcase-dashboard"
+  }
+end
+```
+
+The engine resolves the user's roles via `LcpRuby.user_roles(current_user)` and returns the slug for the **first matching role** (in role-list order). Unmatched users get the `"default"` slug if present.
+
+**3. Not configured (nil):**
+
+When `landing_page` is `nil` (default), the engine falls back to the **first navigable view group's primary page** — i.e. whatever appears at the top of the navigation menu. This is the right default for small apps where you don't yet have a dashboard.
+
+If neither a configured slug nor a fallback navigable page resolves, the request raises `LcpRuby::MetadataError` (handled by `not_found_handler`).
+
+> **Distinction from `breadcrumb_home_path`:** `landing_page` controls **where** the engine sends users when they hit `/`; `breadcrumb_home_path` controls where the "Home" link in breadcrumbs points (often the same value but configured separately).
+
+See also: [Dashboards guide](../guides/dashboards.md) for end-to-end dashboard setup.
+
+### `breadcrumb_home_path`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"/"` |
+
+Path for the "Home" breadcrumb link. Useful when the engine is mounted at a sub-path and you want the Home crumb to point to the host application's root or a custom dashboard.
+
+```ruby
+LcpRuby.configure do |config|
+  config.breadcrumb_home_path = "/dashboard"
+end
+```
+
+> **Relationship to Rails `root to: …`:** these two settings are independent.
+>
+> - `root to: …` (in `config/routes.rb`) — defines what the host serves at `GET /`.
+> - `breadcrumb_home_path` — defines where the "Home" crumb in LCP breadcrumbs links.
+>
+> **Engine mounted at `/`:** typically leave `breadcrumb_home_path` at the default `"/"` and let Rails route `/` to your dashboard.
+>
+> **Engine mounted at a sub-path (e.g. `/app`):** keep your host's `root to: "home#index"` (marketing/landing) and set `breadcrumb_home_path = "/app"` so breadcrumbs return to the LCP dashboard, not to the public landing.
+
+### `not_found_handler`
+
+| | |
+|---|---|
+| **Type** | `Symbol` |
+| **Default** | `:default` |
+| **Allowed values** | `:default`, `:raise` |
+
+Controls how the engine handles unknown slugs (`MetadataError`) and missing records (`ActiveRecord::RecordNotFound`).
+
+| Value | Behavior |
+|-------|----------|
+| `:default` | Renders a styled 404 error page with a "Back to home" link (default) |
+| `:raise` | Re-raises the exception so the host application's error handling takes over |
+
+When set to `:default`, the engine renders `lcp_ruby/errors/not_found` with appropriate i18n messages. JSON requests receive a JSON error response with a 404 status.
+
+```ruby
+LcpRuby.configure do |config|
+  config.not_found_handler = :raise  # Let the host app handle 404s
+end
+```
+
+### `pagination_ends`
+
+| | |
+|---|---|
+| **Type** | `Boolean` |
+| **Default** | `false` |
+
+Global default for showing "First" and "Last" page links in the pagination footer. When `false`, only Prev/Next and page numbers are shown. Individual presenters can override this with [`index.pagination_ends`](presenters.md#pagination_ends).
+
+```ruby
+LcpRuby.configure do |config|
+  config.pagination_ends = true  # show First/Last links on all presenters
+end
+```
+
+### `max_explicit_ids`
+
+| | |
+|---|---|
+| **Type** | `Integer` |
+| **Default** | `500` |
+
+Maximum number of individual record IDs that can be sent in a batch action request using ID selection mode. This limits client-side explicit selection to prevent oversized form submissions. For bulk operations beyond this limit, users should use "select all matching filter" mode.
+
+The JS controller stops adding new IDs when the limit is reached (checkboxes won't check). The server also rejects ID lists exceeding this limit.
+
+```ruby
+LcpRuby.configure do |config|
+  config.max_explicit_ids = 1000
+end
+```
+
+### `empty_value`
+
+| | |
+|---|---|
+| **Type** | `String` or `nil` |
+| **Default** | `nil` (uses i18n key `lcp_ruby.empty_value`, which defaults to `"—"`) |
+
+Text to display when a field value is nil, empty string, whitespace-only, or empty array on index and show pages. The placeholder is rendered as a `<span class="lcp-empty-value">` element.
+
+**Important:** `false` and `0` are **not** considered empty and are rendered as-is.
+
+The resolution order is:
+1. Per-presenter `empty_value` in the presenter YAML
+2. Global `config.empty_value`
+3. `I18n.t("lcp_ruby.empty_value", default: "—")`
+
+```ruby
+LcpRuby.configure do |config|
+  config.empty_value = "N/A"
+end
+```
+
+Per-presenter override in YAML:
+
+```yaml
+presenter:
+  name: deals
+  model: deal
+  slug: deals
+  empty_value: "-"
+```
+
+### `mermaid_source`
+
+| | |
+|---|---|
+| **Type** | `Symbol` or `String` |
+| **Default** | `:cdn` |
+| **Allowed values** | `:cdn`, `:vendored`, or a URL string |
+
+Controls how Mermaid.js is loaded for the `workflow_graph` widget.
+
+| Value | Behavior |
+|-------|----------|
+| `:cdn` | Loads from jsDelivr CDN (default). Requires internet access. |
+| `:vendored` | Loads from the engine's vendored assets. Works offline. |
+| Custom URL | Any string URL (e.g., `"https://cdn.example.com/mermaid.min.js"`) for custom CDN policies. |
+
+```ruby
+LcpRuby.configure do |config|
+  config.mermaid_source = :vendored  # offline-capable
+end
+```
+
+See [Pages Reference — workflow_graph](pages.md#workflow_graph) for the widget configuration.
+
+### `job_source`
+
+| | |
+|---|---|
+| **Type** | `Symbol` |
+| **Default** | `:static` |
+| **Allowed values** | `:static`, `:model`, `:host` |
+
+Controls where background job definitions come from. Follows the three-source configuration principle.
+
+| Value | Behavior |
+|-------|----------|
+| `:static` | Job definitions loaded from YAML/DSL files in `config/lcp_ruby/jobs/` (default) |
+| `:model` | Job definitions stored in a DB model, editable at runtime |
+| `:host` | Job definitions provided by the host application via a provider adapter |
+
+```ruby
+LcpRuby.configure do |config|
+  config.job_source = :model
+end
+```
+
+### `job_execution_model`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"job_execution"` |
+
+Name of the LCP Ruby model that stores job execution records. The model must satisfy the JobExecution contract (required fields: `job_type`, `status`, `progress`; recommended fields: `error_message`, `log`, `params`, `target_model`, `target_id`, `started_at`, `completed_at`, etc.). Use the `lcp_ruby:background_jobs` generator to create a conforming model.
+
+### `job_definition_model`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"job_definition"` |
+
+Name of the LCP Ruby model that stores job definitions. Only used when `job_source` is `:model`.
+
+### `job_definition_model_fields`
+
+| | |
+|---|---|
+| **Type** | `Hash` |
+| **Default** | `{ name: "name", handler_type: "handler_type", handler_class: "handler_class", handler_config: "handler_config", queue: "queue", retry_count: "retry_count", retry_interval: "retry_interval", timeout: "timeout", unique_by: "unique_by", schedule: "schedule", active: "active" }` |
+
+Maps the job definition model contract's logical fields to actual field names on your model. Only used when `job_source` is `:model`.
+
+### `job_provider`
+
+| | |
+|---|---|
+| **Type** | Object or `nil` |
+| **Default** | `nil` |
+
+Host application adapter for job definitions. Only used when `job_source` is `:host`. The object must respond to `job_definitions` (returns array of hashes) and `job_definition_by_name(name)` (returns hash or nil).
+
+### `job_base_class`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"ApplicationJob"` |
+
+Base class name for the ExecutorJob ActiveJob class. Change this if your host application uses a different base job class.
+
+### `schedule_adapter`
+
+| | |
+|---|---|
+| **Type** | Object or `nil` |
+| **Default** | `nil` |
+
+Adapter for synchronizing scheduled job definitions with a scheduling backend (e.g., `solid_queue`, `sidekiq-cron`). Must respond to `sync_schedules!(definitions)`. When `nil`, scheduled jobs are defined but not automatically enqueued on a cron schedule.
+
+### `audit_writer`
+
+| | |
+|---|---|
+| **Type** | Object responding to `#log` or `nil` |
+| **Default** | `nil` |
+
+Custom audit writer for models with `auditing: true`. When set, the auditing system delegates change persistence to this object instead of writing to the built-in audit log model.
+
+The object must respond to `#log(action:, record:, changes:, user:, metadata:)`:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `action` | Symbol | `:create`, `:update`, `:destroy`, `:discard`, `:undiscard` |
+| `record` | ActiveRecord::Base | The changed record instance |
+| `changes` | Hash | Field-level diffs: `{ "field" => [old, new] }` |
+| `user` | Object or nil | Current user from `LcpRuby::Current.user` |
+| `metadata` | Hash or nil | `{ "request_id" => "..." }` when available |
+
+```ruby
+LcpRuby.configure do |config|
+  config.audit_writer = MyCustomAuditWriter.new
+end
+```
+
+See [Auditing Guide](../guides/auditing.md) for setup and usage examples.
+
+### `audit_model`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"audit_log"` |
+
+Name of the LCP Ruby model that stores audit entries. Only used with the built-in audit writer (when `audit_writer` is `nil`). The model must satisfy the [audit model contract](auditing.md#audit-log-model-contract).
+
+### `audit_model_fields`
+
+| | |
+|---|---|
+| **Type** | `Hash` |
+| **Default** | `{ auditable_type: "auditable_type", auditable_id: "auditable_id", action: "action", changes_data: "changes_data", user_id: "user_id", user_snapshot: "user_snapshot", metadata: "metadata" }` |
+
+Maps the audit model contract's logical fields to actual field names on your audit log model. Use this when your audit model has different column names than the defaults.
+
+```ruby
+LcpRuby.configure do |config|
+  config.audit_model_fields = {
+    auditable_type: "entity_type",
+    auditable_id: "entity_id",
+    action: "operation",
+    changes_data: "diff",
+    user_id: "actor_id",
+    user_snapshot: "actor_snapshot",
+    metadata: "meta"
+  }
+end
+```
+
+### `attachment_allowed_content_types`
+
+| | |
+|---|---|
+| **Type** | `Array` or `nil` |
+| **Default** | `nil` (allow all) |
+
+Global default list of allowed MIME types for attachment fields. When `nil`, all content types are accepted. Individual fields can override this with their own `content_types` option. Supports wildcards like `"image/*"`.
+
+```ruby
+LcpRuby.configure do |config|
+  config.attachment_allowed_content_types = %w[
+    image/jpeg image/png image/webp image/gif
+    application/pdf
+    application/msword
+    application/vnd.openxmlformats-officedocument.wordprocessingml.document
+  ]
+end
+```
+
+### `page_source`
+
+| | |
+|---|---|
+| **Type** | `Symbol` |
+| **Default** | `:yaml` |
+| **Allowed values** | `:yaml`, `:model` |
+
+Controls where page definitions come from. When `:yaml` (default), pages are loaded only from YAML files and auto-generated from presenters. When `:model`, page definitions are also loaded from a DB-backed model, allowing runtime creation and editing. DB pages override YAML pages with the same name.
+
+```ruby
+LcpRuby.configure do |config|
+  config.page_source = :model
+end
+```
+
+Run `rails generate lcp_ruby:pages` to create the required model, presenter, permissions, and view group. See [Pages Reference](pages.md#db-stored-page-definitions) for details.
+
+### `page_model`
+
+| | |
+|---|---|
+| **Type** | `String` |
+| **Default** | `"page_config"` |
+
+Name of the LCP Ruby model that stores page definitions. Only used when `page_source` is `:model`. The model must have a `name` (string), `definition` (json), and optionally `active` (boolean) field.
+
+### `page_model_fields`
+
+| | |
+|---|---|
+| **Type** | `Hash` |
+| **Default** | `{ name: "name", definition: "definition", active: "active" }` |
+
+Maps the page model contract's logical fields to actual field names on your model. Only used when `page_source` is `:model`.
+
+```ruby
+LcpRuby.configure do |config|
+  config.page_model_fields = { name: "page_name", definition: "page_json", active: "enabled" }
+end
+```
+
+## Bundled Front-End Assets
+
+The engine layout (`app/views/layouts/lcp_ruby/application.html.erb`) loads a small set of vendored JavaScript and CSS bundles automatically. Hosts that mount the engine inherit them; hosts that override the layout need to re-include them.
+
+| Asset | Purpose | Source | Loaded |
+|---|---|---|---|
+| `lcp_ruby/application.css` | Engine styling (nav, sidebar, forms, dialogs, …) | engine `app/assets/stylesheets` | always |
+| `lcp_ruby/application.js` | Stimulus controllers + helpers (Sprockets manifest) | engine `app/assets/javascripts` | always |
+| `lcp_ruby/tom-select.complete.min.js` + `tom-select.css` | Selectbox component | vendored | always |
+| `lcp_ruby/activestorage.min.js` | Direct upload | vendored | always |
+| `lcp_ruby/lucide.min.js` + `lucide_init.js` | Icon library | vendored | always |
+| `lcp_ruby/highlight.min.js` + `highlight-github.min.css` | Code highlighting | vendored | when [dev toolbar](#dev-toolbar) is enabled |
+| `lcp_ruby/dev_toolbar.{js,css}` | Dev toolbar | engine | when [dev toolbar](#dev-toolbar) is enabled |
+
+### Icons (Lucide)
+
+`menu_item_icon_html`, the boolean icon renderer, KPI card widget, and any host markup that emits `<i data-lucide="…">` are replaced with inline SVGs by [Lucide](https://lucide.dev). The init script (`lucide_init.js`) calls `lucide.createIcons({ icons: lucide.icons })` on `DOMContentLoaded`, `turbo:load`, `turbo:render`, and `turbo:frame-render`, so icons appear after both full-page loads and SPA-style navigations.
+
+Icon names are kebab-case Lucide identifiers (`bell`, `life-buoy`, `chart-bar`, `dollar-sign`, …). The bundled v0.499.0 ships ~1,800 icons; see [`lucide.dev/icons`](https://lucide.dev/icons/) for the catalog.
+
+> **Note on the pinned version.** The bundle is pinned to a `0.x` release rather than tracking `lucide@latest` because npm's `latest` tag for the `lucide` package still points at the legacy v1.14.0 line (frozen since 2022). The active development line uses `0.x` versions; we vendor a recent `0.x` UMD release. The same convention applies if you upgrade — pin a specific `0.x` version, do not chase `@latest`.
+
+To swap in a different icon library, override `LcpRuby::LayoutHelper#menu_item_icon_html` in your host application and replace `lcp_ruby/lucide.min.js` with your library's bundle.
+
+## Service Auto-Discovery
+
+The engine automatically discovers and registers custom services from `app/lcp_services/` in your host application. Services are organized by category:
+
+```
+app/
+  lcp_services/
+    transforms/          # Value normalization (strip, titlecase, etc.)
+      titlecase.rb       # LcpRuby::HostServices::Transforms::Titlecase
+    validators/          # Service validators (cross-record business rules)
+      deal_credit_limit.rb  # LcpRuby::HostServices::Validators::DealCreditLimit
+    defaults/            # Dynamic default value providers
+      thirty_days_out.rb    # LcpRuby::HostServices::Defaults::ThirtyDaysOut
+    computed/            # Computed field calculators
+      weighted_deal_value.rb  # LcpRuby::HostServices::Computed::WeightedDealValue
+    conditions/          # Custom condition evaluators
+      credit_check.rb       # LcpRuby::HostServices::Conditions::CreditCheck
+```
+
+### Namespace Convention
+
+Service classes must be namespaced under `LcpRuby::HostServices::{Category}::{ClassName}`. The file path relative to the category directory determines the class name. For example, `app/lcp_services/transforms/titlecase.rb` maps to `LcpRuby::HostServices::Transforms::Titlecase`.
+
+### Service Contracts
+
+| Category | Contract | Used In |
+|----------|----------|---------|
+| `transforms` | `def call(value) -> value` | Field `transforms:`, type `transforms:` |
+| `validators` | `def self.call(record, **opts) -> void` | Validation `type: service` |
+| `defaults` | `def self.call(record, field_name) -> value` | Field `default: { service: }` |
+| `computed` | `def self.call(record) -> value` | Field `computed: { service: }` |
+| `conditions` | `def self.call(record) -> boolean` | `visible_when: { service: }`, `when: { service: }` |
+
+### Discovery in Initializer
+
+For the engine to discover services, add `Services::Registry.discover!` to your initializer:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+Rails.application.config.after_initialize do
+  LcpRuby::Services::Registry.discover!(Rails.root.join("app").to_s)
+end
+```
+
+See the [Extensibility Guide](../guides/extensibility.md) for detailed examples of each service category.
+
+## Dedicated Registries
+
+In addition to `Services::Registry`, LCP Ruby has four dedicated registries with their own auto-discovery. These use separate directory paths and namespaces:
+
+```
+app/
+  actions/                # Custom actions
+    deal/
+      close_won.rb        # LcpRuby::HostActions::Deal::CloseWon
+  event_handlers/         # Event handlers
+    deal/
+      on_stage_change.rb  # LcpRuby::HostEventHandlers::Deal::OnStageChange
+  condition_services/     # Condition services for visible_when/disable_when
+    credit_check.rb       # LcpRuby::HostConditionServices::CreditCheck
+  renderers/              # Custom display renderers
+    conditional_badge.rb  # LcpRuby::HostRenderers::ConditionalBadge
+```
+
+These directories use `LcpRuby::Host*` namespaces which conflict with Zeitwerk autoloading. You must exclude them — see [Extensibility Guide — Auto-Discovery Setup](../guides/extensibility.md#auto-discovery-setup) for the required `config/application.rb` initializer.
+
+Each registry requires its own `discover!` call in the initializer:
+
+```ruby
+Rails.application.config.after_initialize do
+  app_path = Rails.root.join("app").to_s
+
+  LcpRuby::Actions::ActionRegistry.discover!(app_path)
+  LcpRuby::Events::HandlerRegistry.discover!(app_path)
+  LcpRuby::ConditionServiceRegistry.discover!(app_path)
+  LcpRuby::Display::RendererRegistry.discover!(app_path)
+  LcpRuby::Services::Registry.discover!(app_path)
+end
+```
+
+> **Note:** The `conditions` category under `Services::Registry` (`app/lcp_services/conditions/`) and the dedicated `ConditionServiceRegistry` (`app/condition_services/`) are separate registries. Both can serve condition services for `visible_when: { service: }`. See the [Extensibility Guide](../guides/extensibility.md) for details on choosing between them.
+
+Source: `lib/lcp_ruby/configuration.rb`, `lib/lcp_ruby/services/registry.rb`
+
+## Monitoring
+
+### `health_check`
+
+| | |
+|---|---|
+| **Type** | `Boolean` |
+| **Default** | `true` |
+
+Enables the `GET /lcp_health` endpoint. Returns 200 when database is connected and metadata is loaded, 503 otherwise. No authentication required.
+
+### `metrics_endpoint`
+
+| | |
+|---|---|
+| **Type** | `Boolean` |
+| **Default** | `true` |
+
+Enables the `GET /metrics` endpoint for Prometheus scraping. Requires the `prometheus-client` gem; returns 404 if not installed. No authentication required.
+
+### `metrics_histogram_buckets`
+
+| | |
+|---|---|
+| **Type** | `Array<Float>` |
+| **Default** | `[0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]` |
+
+Bucket boundaries (in seconds) for histogram metrics like `lcp_ruby_request_duration_seconds`.
+
+### `error_log_enabled`
+
+| | |
+|---|---|
+| **Type** | `:auto`, `true`, `false` |
+| **Default** | `:auto` |
+
+Controls error log persistence to the `lcp_error_log` model. `:auto` checks at boot whether the model exists and enables accordingly.
+
+### `error_log_rate_limit`
+
+| | |
+|---|---|
+| **Type** | `Integer` |
+| **Default** | `1` |
+
+Minimum seconds between database writes for the same error fingerprint. Occurrences between writes are accumulated in memory.
+
+### `error_log_capture_request_context`
+
+| | |
+|---|---|
+| **Type** | `Boolean` |
+| **Default** | `false` |
+
+When true, includes request context (IP address, path) in the error log context JSON.
+
+See also: [Monitoring Reference](monitoring.md), [Monitoring Guide](../guides/monitoring.md)
+
+### `runtime_type_renderers`
+
+| | |
+|---|---|
+| **Type** | `Boolean` |
+| **Default** | `false` (existing apps); `true` for new apps via `lcp new` install generator |
+
+When true, presenter columns whose `renderer:` is **absent** get a type-driven default at column-set build time. So `column :flag` on a `:boolean` field auto-renders as `boolean_icon` (✓/✗) and `column :status` on an `:enum` field auto-renders as a `badge` — without writing `renderer:` explicitly. The defaults come from each type's `TypeDefinition#renderer` (see [Types Reference](types.md#renderer)).
+
+The flag is gated for one release after Phase 4 of the type-system defaults lands (Decision 14 in `docs/design/type_system_defaults.md`) so existing apps keep their current rendering. To opt in:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.runtime_type_renderers = true
+end
+```
+
+Behavior changes when on:
+
+- `column :flag` (where `flag` is `:boolean`) — was raw `"true"`/`"false"` text, becomes `boolean_icon`.
+- `column :status` (where `status` is `:enum`) — was the humanized enum label via `format_enum_display`, becomes a `badge` (same label, wrapped in a badge box).
+- `column :body` (where `body` is `:text`) and similar row-unfriendly types are dropped from the auto-generated index entirely (Phase 2 generator behavior, independent of this flag); show pages keep them with renderer auto-applied (`:truncate` for `:text`, `:code` for `:json`, etc.).
+
+Explicit `renderer:` always wins (idempotent skip), so columns that already specify a renderer are unaffected. **Independent of**: the runtime renderer-name resolution path (Phase 4 fallback in `Display::RendererRegistry.renderer_for`), which always accepts type names as renderer synonyms regardless of this flag.
+
+See also: [Presenters Reference — Type-driven renderer defaults](presenters.md#type-driven-renderer-defaults-runtime_type_renderers).