lcp 0.1.0

data/config/routes.rb

@@ -0,0 +1,119 @@
+LcpRuby::Engine.routes.draw do
+  # Devise routes are always mounted so URL helpers stay available regardless
+  # of mode; controllers gate access via require_session_based_auth!.
+  devise_for :users,
+    class_name: "LcpRuby::User",
+    module: "lcp_ruby/auth",
+    path: "auth",
+    router_name: :lcp_ruby,
+    path_names: {
+      sign_in: "login",
+      sign_out: "logout",
+      sign_up: "register",
+      password: "password"
+    }
+
+  # OIDC endpoints — only drawn when at least one :oidc provider is configured
+  # in config/lcp_ruby/auth.yml. OmniAuth 2.0 requires POST on the request phase
+  # for CSRF protection; the login view initiates provider sign-in via button_to.
+  if LcpRuby::Authentication::ProviderRegistry.oidc_enabled?
+    scope "auth", controller: "auth/callbacks" do
+      provider_constraint = { provider: /[a-z0-9_]+/ }
+      post  ":provider",          action: :passthru, as: :oidc_start,    constraints: provider_constraint
+      match ":provider/callback", action: :callback, as: :oidc_callback, constraints: provider_constraint, via: %i[get post]
+      get   "failure",            action: :failure,  as: :oidc_failure
+    end
+  end
+
+  get "lcp_health", to: "health#show", as: :health_check if LcpRuby.configuration.health_check
+  get "metrics", to: "metrics#show", as: :metrics if LcpRuby.configuration.metrics_endpoint
+
+  get    "/_dev/metadata",    to: "dev_toolbar#metadata",  as: :dev_toolbar_metadata
+
+  get    "/",                 to: "landing#show",          as: :landing
+
+  post   "impersonate",      to: "impersonation#create",  as: :impersonate
+  delete "impersonate",      to: "impersonation#destroy", as: :stop_impersonate
+
+  scope "lcp_dialog/:page_name" do
+    get  "/new",       to: "dialogs#new",    as: :dialog_new
+    post "/",          to: "dialogs#create",  as: :dialog_create
+    get  "/:id/edit",  to: "dialogs#edit",    as: :dialog_edit
+    patch "/:id",      to: "dialogs#update",  as: :dialog_update
+  end
+
+  # Per-presenter routes for presenters with controller: or action_controllers:.
+  # Drawn before the catch-all so explicit slug routes take precedence.
+  LcpRuby::Routing::PresenterRoutes.draw_custom_controller_routes(self)
+
+  # Slug constraint rejects asset paths (`favicon.ico`, …) at the routing layer.
+  # Format whitelist accepts REST-style suffixes for data formats only.
+  # NOTE: do NOT add `\A…\z` anchors to the format regex — Rails embeds it into
+  # a larger pattern and the anchors break format extraction. Rails anchors
+  # implicitly; the `.jsonp`-style partial-match guard test in
+  # spec/integration/asset_route_passthrough_spec.rb keeps that invariant.
+  # Asset paths that slip through (e.g. `manifest.json`, slug=manifest) are
+  # caught downstream by `rescue_from MetadataError` in ErrorHandling.
+  scope ":lcp_slug",
+        constraints: { lcp_slug: %r{[^/.]+} },
+        format: /(?:json|csv|xml)/ do
+    # Saved filters API (must precede /:id to avoid matching "saved-filters" as id)
+    scope "saved-filters", as: :saved_filters do
+      get    "/",     to: "saved_filters#index"
+      post   "/",     to: "saved_filters#create"
+      patch  "/:id",  to: "saved_filters#update",  as: :update
+      delete "/:id",  to: "saved_filters#destroy", as: :destroy
+    end
+
+    # Custom fields management (must precede /:id to avoid matching "custom-fields" as id)
+    scope "custom-fields", as: :custom_fields do
+      get    "/",          to: "custom_fields#index"
+      get    "/manage",    to: "custom_fields#manage",       as: :manage
+      patch  "/manage",    to: "custom_fields#bulk_update",  as: :bulk_update
+      get    "/new",       to: "custom_fields#new",     as: :new
+      post   "/",          to: "custom_fields#create"
+      get    "/:id",       to: "custom_fields#show",    as: :show
+      get    "/:id/edit",  to: "custom_fields#edit",    as: :edit
+      patch  "/:id",       to: "custom_fields#update",  as: :update
+      put    "/:id",       to: "custom_fields#update"
+      delete "/:id",       to: "custom_fields#destroy", as: :destroy
+    end
+
+    post   "/parse_ql",      to: "resources#parse_ql",      as: :parse_ql
+    get    "/filter_fields", to: "resources#filter_fields", as: :filter_fields
+    get    "/batch_count",   to: "resources#batch_count",   as: :batch_count
+    get    "/export_fields", to: "resources#export_fields", as: :export_fields
+    get    "/export_profiles", to: "resources#export_profiles", as: :export_profiles
+    get    "/import_fields",    to: "resources#import_fields",    as: :import_fields
+    get    "/import_profiles",  to: "resources#import_profiles",  as: :import_profiles
+    post   "/batch_selection", to: "resources#batch_selection", as: :batch_selection
+    get    "/",              to: "resources#index",         as: :resources
+    get    "/select_options",      to: "resources#select_options",      as: :select_options
+    get    "/inline_create_form",  to: "resources#inline_create_form",  as: :inline_create_form
+    post   "/inline_create",       to: "resources#inline_create",       as: :inline_create
+    get    "/new",       to: "resources#new",     as: :new_resource
+    post   "/",          to: "resources#create",  as: :create_resource
+    post   "/evaluate_conditions",     to: "resources#evaluate_conditions_new", as: :evaluate_conditions_new
+    post   "/actions/:action_name",       to: "actions#execute_collection", as: :collection_action
+    post   "/batch_actions/:action_name", to: "actions#execute_batch",      as: :batch_action
+    post   "/:id/transitions/:transition_name", to: "resources#execute_transition", as: :execute_transition
+    post   "/:id/approval_tasks/:task_id/approve",     to: "approval_tasks#approve",     as: :approve_approval_task
+    post   "/:id/approval_tasks/:task_id/reject",      to: "approval_tasks#reject",      as: :reject_approval_task
+    post   "/:id/approval_tasks/:task_id/return_task",  to: "approval_tasks#return_task",  as: :return_task_approval_task
+    post   "/:id/approval_tasks/:task_id/claim",       to: "approval_tasks#claim",       as: :claim_approval_task
+    post   "/:id/approval_tasks/:task_id/delegate",    to: "approval_tasks#delegate",    as: :delegate_approval_task
+    get    "/:id",       to: "resources#show",    as: :resource
+    get    "/:id/zones/:zone_name", to: "resources#zone", as: :zone_resource
+    get    "/:id/edit",  to: "resources#edit",    as: :edit_resource
+    patch  "/:id",       to: "resources#update",  as: :update_resource
+    put    "/:id",       to: "resources#update"
+    delete "/:id",       to: "resources#destroy", as: :destroy_resource
+    post   "/:id/restore",             to: "resources#restore",                 as: :restore_resource
+    delete "/:id/permanently_destroy", to: "resources#permanently_destroy",     as: :permanently_destroy_resource
+    patch  "/:id/reorder",             to: "resources#reorder",                 as: :reorder_resource
+    patch  "/:id/reparent",            to: "resources#reparent",                as: :reparent_resource
+    patch  "/:id/kanban_move",         to: "resources#kanban_move",             as: :kanban_move_resource
+    post   "/:id/evaluate_conditions", to: "resources#evaluate_conditions",     as: :evaluate_conditions
+    post   "/:id/actions/:action_name",   to: "actions#execute_single",     as: :single_action
+  end
+end

data/docs/README.md

@@ -0,0 +1,225 @@
+# LCP Ruby Documentation
+
+LCP Ruby is a Rails mountable engine that generates full CRUD information systems from YAML metadata.
+
+## Quick Start
+
+- [Getting Started](getting-started.md) — Install, configure, create your first model/presenter/permission
+  - **`lcp new my_app`** — interactive CLI to create a new LCP application (database, format, feature preset)
+  - **`rails generate lcp_ruby:install`** — add LCP to an existing Rails app
+  - **`rails generate lcp_ruby:entity NAME field:type ...`** — scaffold a complete CRUD entity (model + presenter + permissions + view group). See [Getting Started → Scaffolding new entities](getting-started.md#scaffolding-new-entities) and the [design spec](design/entity_generator.md) for the field grammar and worked examples.
+- [Host Application Guide](guides/host-application.md) — Full app bootstrap, optional dependencies (XLSX, charts, metrics), feature generators
+
+## YAML Reference
+
+Complete attribute reference for every YAML configuration file:
+
+- [Models](reference/models.md) — Fields, validations, associations, scopes, events, display templates, virtual columns, abstract models, inheritance
+- [Types](reference/types.md) — Custom business types (email, phone, url, color, and user-defined)
+- [Presenters](reference/presenters.md) — Index, show, form, search, actions, navigation
+- [Pages](reference/pages.md) — Page YAML format, zones, widget types (kpi_card, text, list, workflow_graph), grid positioning, auto-pages, dialog-only pages, composite pages (semantic layout, tabs, scope_context)
+- [Virtual Forms](reference/virtual_forms.md) — Shared infrastructure for synthetic per-request form-like objects (filter forms, wizards, virtual show, PaaS config UI): VirtualField + VirtualForm + Type::ArrayOf, dispatcher contract, security invariants, GC lifecycle
+- [Page Filters](reference/page_filters.md) — `filter_form:` (value-based, form-syntax fields with cascade + multi) and `scope_filters:` (AR-scope toggles) on dashboards and index composite pages; auto_submit derivation, dirty-state Apply button, `/select_options` fallback chain
+- [Cascading Selects](reference/cascading_selects.md) — `data-lcp-depends-on` contract for child selects, form-level data attributes, forward + reverse cascade, multi-parent UNION, accessibility (aria-busy, polite live region, focus restoration), race semantics
+- [Forms](reference/forms.md) — Form-input renderers shared between presenter forms and synthetic forms: `date_range` paired-date input, `multi_select` cascade activation, i18n keys, cross-links
+- [Dialogs](reference/dialogs.md) — Dialog actions, confirm variants (boolean, role, styled, page-based), routing, virtual model flow
+- [View Groups](reference/view-groups.md) — Navigation menu, view switching, auto-creation
+- [Menu](reference/menu.md) — Configurable navigation: top bar, sidebar, dropdowns, nested submenus, badges, role visibility, responsive modes (overflow_more / hamburger / rail / off-canvas), per-item priority/pin/hide_below, sidebar_toggle marker, mobile header, rail-collapsed flyouts
+- [Custom Fields](reference/custom-fields.md) — Runtime user-defined fields: definitions, types, permissions, querying
+- [Role Source](reference/role-source.md) — DB-backed role model: contract, registry, cache invalidation, generator
+- [Permission Source](reference/permission-source.md) — DB-backed permissions: JSON definitions, registry, cache invalidation, generator
+- [OIDC Authentication](reference/oidc.md) — `auth.yml` provider registry, claim mapping, role source, provisioning, logout modes, redirect_uri override, boot validation rules
+- [Groups](reference/groups.md) — Organizational groups: YAML, DB, host adapter, role mapping, resolution strategies
+- [i18n](reference/i18n.md) — Internationalization: key hierarchy, model/field/enum/menu/action labels, UI framework keys, date formatting
+- [i18n_check](reference/i18n_check.md) — Static-analysis lint for the i18n principle: three passes (DSL AST, YAML schema-driven, boot-time registry), configuration, severity / CI integration, exemption marker
+- [invariant_check](reference/invariant_check.md) — Boot-time validator for permission/page metadata behavioral invariants (AUTH-001..009): custom-scope methods on klass, field_match column, inherits parent resolution, page visible_when shape; severity / CI integration
+- [Permissions](reference/permissions.md) — Roles, CRUD, field access, scopes, record rules
+- [Condition Operators](reference/condition-operators.md) — Shared operator reference for `visible_when`, `record_rules`, `item_classes`, etc. Plus invocation forms (`service:`, `lookup:`)
+- [Dynamic References](reference/dynamic-references.md) — Single source of truth for dotted-string tokens (`current_user.<method>`, `record.<field>`, `current_date`, …) used in scopes, conditions, page `scope_context`, workflow `set_fields`, and field defaults
+- [Auditing](reference/auditing.md) — Change tracking: audit log model, field diffs, JSON/custom field expansion, configuration
+- [Workflow](reference/workflow.md) — State machine: states, transitions, guards, set_fields, readonly_fields, trigger modes, audit log, timeline_states, three definition sources
+- [Workflow Approvals](reference/workflow-approvals.md) — Multi-step approval engine: sequential/parallel strategies, approver types, delegation, bypass, rework
+- [Eager Loading](reference/eager-loading.md) — Auto-detection, manual overrides, strategy resolution, strict_loading
+- [Tree Structures](reference/tree-structures.md) — Declarative tree hierarchies: model options, traversal, reparenting, tree index view
+- [View Slots](reference/view-slots.md) — Extensible page layout injection points: registry, slot names, SlotContext, position ordering
+- [API-Backed Models](reference/api-backed-models.md) — External data sources: REST JSON adapter, host providers, cross-source associations, caching, error handling
+- [Host Controller Integration](reference/host-controller-integration.md) — `bind_to:` connecting LCP metadata to existing AR models, `controller:` / `action_controllers:` per-presenter routing to host controllers, includable `LcpRuby::Controller::*` concerns including `AuthorizedController` (Pundit `verify_authorized` framework guarantee), multi-model authorize helper pattern, `lcp_ruby:host_controller` generator
+- [Monitoring](reference/monitoring.md) — Health check, Prometheus metrics, error log, AS::Notifications events, custom collectors
+- [Export](reference/export.md) — Data export: CSV/XLSX formats, field picker, formatting options, profiles, history, generator
+- [Import](reference/import.md) — Data import: CSV/XLSX upload, column mapping, strategies, nested has_one, profiles, background execution, generator
+- [Theme Variables](reference/theme-variables.md) — All `--lcp-*` CSS custom properties with light/dark values
+- [Engine Configuration](reference/engine-configuration.md) — `LcpRuby.configure` options
+- [Boot / Reload Lifecycle](reference/boot_lifecycle.md) — Engine boot phases, extension hook timing (`on_model_ready`, `on_models_loaded`), dev-mode metadata watcher, `lcp_ruby:ensure_tables` rake + `db:prepare` / `db:setup` / `db:reset` integration, `boot.lcp_ruby` and `reload.lcp_ruby` AS::Notifications events
+- [`lcp_ruby:doctor`](reference/doctor.md) — Health check rake task: install manifest replay, feature state vs. prereqs, environment leaks (`BUNDLE_GEMFILE`, `.envrc`), seeds hygiene; `FORMAT=text|json|summary` and `EXIT_ON=error|warning`; install manifest format and JSON schema for CI consumption
+
+## DSL Reference
+
+- [Model DSL](reference/model-dsl.md) — Ruby DSL alternative to YAML for model definitions
+- [Presenter DSL](reference/presenter-dsl.md) — Ruby DSL alternative to YAML for presenter definitions (with inheritance)
+- [Types](reference/types.md#dsl-type-definition) — Ruby DSL for defining custom business types
+
+## Guides
+
+- [Presenters](guides/presenters.md) — Step-by-step guide to building presenters (index, show, form, search, actions) with YAML and DSL examples
+- [Selectbox](guides/selectbox.md) — Association select, cascading selects, remote search, multi-select, tree select, scoping, disabled options, legacy records, codelists
+- [Virtual Columns](guides/virtual-columns.md) — Query-time computed columns: declarative aggregates, SQL expressions, JOINs, GROUP BY, services, auto-include, conditional rendering
+- [Computed Fields](guides/computed-fields.md) — Auto-calculated persisted fields: template interpolation, service logic, arithmetic, comparison with virtual columns
+- [Sequence Fields](guides/sequences.md) — Gap-free auto-numbering: scoped counters, format templates, counter management, rake tasks
+- [Extensibility](guides/extensibility.md) — All extension mechanisms: actions, events, transforms, validators, defaults, computed fields, condition services, scopes, model extensions
+- [Conditional Rendering](guides/conditional-rendering.md) — `visible_when`, `disable_when`, `item_classes`: simple, compound (all/any/not), dot-path, dynamic references, collection conditions, lookup value references, DSL builder
+- [Custom Actions](guides/custom-actions.md) — Writing domain-specific operations beyond CRUD
+- [Event Handlers](guides/event-handlers.md) — Responding to lifecycle events and field changes
+- [Custom Types](guides/custom-types.md) — Defining custom business types (percentage, postal_code, slug, hex_color)
+- [View Groups](guides/view-groups.md) — Multi-view navigation and view switcher setup
+- [Menu](guides/menu.md) — Custom navigation menus: dropdowns, nested submenus, sidebar, combined layouts, badges
+- [Renderers](guides/display-types.md) — Visual guide to all built-in renderers (including workflow_timeline, workflow_badge, dot-notation, templates, and collections)
+- [Custom Renderers](guides/custom-renderers.md) — Creating custom renderers for host applications
+- [Attachments](guides/attachments.md) — File upload with Active Storage
+- [Userstamps](guides/userstamps.md) — Automatic created_by / updated_by tracking: setup, name snapshots, presenter display, seeds
+- [Record Aliases & Slug Fields](guides/record-aliases.md) — Human-readable URLs (`/articles/my-slug`), user-context aliases (`/preferences/me`), dynamic shortcuts (`/issues/last`)
+- [Soft Delete](guides/soft-delete.md) — Discard/restore, cascade, archive presenters, permissions
+- [Action Buttons & Pipelines](guides/action-buttons.md) — All button contexts (collection, single, batch, form), form submit buttons, save + transition + action pipelines, show page pipelines
+- [Batch Actions](guides/batch-actions.md) — Multiselect, batch delete/restore, custom batch actions, selection modes
+- [Auditing](guides/auditing.md) — Change tracking: setup, field filtering, JSON expansion, custom writer, show page integration
+- [Workflow](guides/workflow.md) — State machine setup: transitions, guards, readonly fields, events, system triggers, audit logging, workflow renderers, testing
+- [Eager Loading](guides/eager-loading.md) — N+1 prevention, strict_loading, manual overrides
+- [Tree Structures](guides/tree-structures.md) — Declarative tree hierarchies: setup, tree index view, drag-and-drop reparenting, search
+- [Custom Fields](guides/custom-fields.md) — Runtime user-defined fields: enabling, defining, sections, permissions, programmatic access
+- [Role Source](guides/role-source.md) — DB-backed role management: setup, validation, cache, testing
+- [Permission Source](guides/permission-source.md) — DB-backed permission management: runtime editing, JSON definitions, testing
+- [OIDC Setup](guides/oidc-setup.md) — IdP App registration walkthrough, generator, ENV setup options (export / dotenv / encrypted credentials), role mapping, troubleshooting (CSRF, cookie overflow, redirect URI mismatch, hostname consistency)
+- [Groups](guides/groups.md) — Organizational groups: YAML, DB, host adapter, testing
+- [Hierarchical Authorization](guides/hierarchical-authorization.md) — Multi-level parent-child access control (factory → production line → machine → sensor reading)
+- [Permissions](guides/permissions.md) — `extends:` keyword and coverage merge with `_default`: pattern catalog, anti-patterns, decision tree, validator output reference
+- [Inherited Permissions](guides/inherited-permissions.md) — Declarative `inherits_from:` cascade for visibility (read time) and create-time FK validation; bind_to host classes; soft-delete and transitive chains
+- [Impersonation](guides/impersonation.md) — "View as Role X" for testing permissions
+- [Tiles View](guides/tiles.md) — Card grid layout for index pages: tile configuration, sort dropdown, per-page selector, summary bar
+- [Dashboards](guides/dashboards.md) — Standalone grid pages: KPI cards, text widgets, list widgets, presenter zones, landing page
+- [Composite Pages](guides/composite-pages.md) — Record-bound multi-zone pages: semantic layout, tabs, scope_context, per-zone authorization, index composites, composite dialogs, dialog nesting
+- [Dialogs](guides/dialogs.md) — Quick create/edit dialogs, virtual model dialogs, styled/page-based confirms, composite dialogs, dialog nesting
+- [Rendering Extension Points](guides/rendering-extension-points.md) — Custom render blocks vs. view slots: when to use which, available locals, worked examples
+- [View Slots](guides/view-slots.md) — Extending page layouts: custom toolbar buttons, widgets, conditional components, overriding built-ins
+- [API-Backed Models](guides/api-backed-models.md) — Integrating external REST APIs and host-provided data sources: setup, cross-source associations, caching, error handling, testing
+- [Host Controller Integration](guides/host-controller-integration.md) — Connecting LCP to existing host AR models with `bind_to:`, routing presenter slugs to host controllers (`controller:` / `action_controllers:`), includable controller concerns, `lcp_ruby:host_controller` generator
+- [Monitoring](guides/monitoring.md) — Health check, Prometheus + Grafana, error log, custom collectors, testing
+- [Export](guides/export.md) — Data export setup: CSV/XLSX, field selection, profiles, history, permissions
+- [Import](guides/import.md) — Data import setup: CSV/XLSX upload, strategies, nested has_one associations, profiles, permissions
+- [Theming](guides/theming.md) — Dark mode, UI density, border radius, CSS variables, theme persistence
+- [Developer Tools](guides/developer-tools.md) — `lcp_ruby:validate`, `lcp_ruby:erd`, `lcp_ruby:permissions`, `lcp_ruby:create_admin`, `lcp_ruby:i18n_lint` rake tasks + `LcpRuby/NoHardcodedI18nString` RuboCop cop
+- [Adding a Locale](guides/adding-locale.md) — Workflow for adding a new language: engine UI vs host-app domain layers, step-by-step checklist, plural forms, devise, tooling, troubleshooting
+
+## Debugging
+
+Practical `rails runner` recipes for inspecting LCP internals at runtime:
+
+- [Overview](guides/debugging/README.md) — Entry points, general tips
+- [Models](guides/debugging/models.md) — Columns, validations, scopes, associations, inheritance, schema comparison
+- [Controllers](guides/debugging/controllers.md) — Routing, callbacks, auth chain, Warden vs controller, layout
+- [Permissions](guides/debugging/permissions.md) — Role checks, field access, record rules, condition evaluation
+- [Presenters](guides/debugging/presenters.md) — Columns, layout, actions, search, view groups, tiles
+- [Metadata](guides/debugging/metadata.md) — Loader, registry, boot validation, configuration, workflows, types
+- [Data](guides/debugging/data.md) — DB state, duplicates, custom fields, workflow state, audit logs, seeds verification
+
+## Design Documents
+
+Implemented:
+
+- [Record Positioning](design/record_positioning.md) — Drag-and-drop reordering of top-level records with the `positioning` gem
+- [External Field Accessors](design/fields_accessors.md) — Virtual fields with `source: external` and `source: { service: }` accessor delegation
+- [Unified Condition Operators](design/unified_condition_operators.md) — Strict condition evaluation, shared 12-operator set across all contexts
+- [Record Rules Action Visibility](design/record_rules_action_visibility.md) — Automatic hiding of edit/destroy buttons based on record_rules
+- [Inline Collection Editor](design/inline_collection_editor.md) — Unified editing for nested associations, JSON arrays, and bulk records: row-scoped conditions, JSON field source, virtual models, sub-sections, presenter-driven manage page
+- [Groups, Roles & Org Structure](design/groups_roles_and_org_structure.md) — Enterprise organizational units, groups, and group-to-role mapping
+- [Model Options Infrastructure](design/model_options_infrastructure.md) — Shared patterns for model-level feature flags (soft_delete, auditing, userstamps, tree)
+- [Userstamps](design/userstamps.md) — Automatic `created_by_id` / `updated_by_id` tracking
+- [Soft Delete](design/soft_delete.md) — Discard/restore support with `discarded_at` timestamp, cascade discard/undiscard, archive presenters
+- [Auditing](design/auditing.md) — Native change tracking and audit trail
+- [Tree Structures](design/tree_structures.md) — Declarative parent-child hierarchies with traversal, cycle detection, and tree index view
+- [Saved Filters & Parameterized Scopes](design/saved_filters.md) — User-persistent named filters with visibility levels, parameterized scopes with typed parameters, generator, CRUD API
+- [Aggregate Columns](design/aggregate_columns.md) — Virtual computed columns (COUNT, SUM, MIN, MAX, AVG) from associated records, custom SQL, service-based aggregates
+- [Virtual Columns](design/virtual_columns.md) — Generalized query extensions: expressions, JOINs, GROUP BY, auto-include, backward-compatible with aggregates
+- [Tiles View](design/tiles_view.md) — Card grid layout for index pages with sort dropdown, per-page selector, and summary bar
+- [Row Styling](design/row_styling.md) — Conditional CSS classes on index rows (tables, trees, tiles) based on field conditions or services
+- [Array Field Type](design/array_field_type.md) — Native array fields with typed items, array-specific operators, and auto-generated scopes
+- [API-Backed Models](design/api_backed_models.md) — External data sources (REST JSON, host adapters): read-only access, cross-source associations, caching, graceful degradation
+- [Pages — Unified Rendering Abstraction](design/composite_pages_v2.md) — Tier 1 + Tier 1b + Tier 2 Phase A: pages, zones, auto-pages, grid layout, widget zones, dashboard convergence, composite pages with semantic layout and tabs
+- [Modal Dialogs](design/modal_dialogs.md) — Dialog actions, virtual model flow, confirm variants, routing, authorization
+- [Dashboards](design/dashboards.md) — Tier 1b: standalone grid pages with KPI cards, text, list widgets, presenter zones
+- [Chart Widget — Multi-Series and Configuration Options](design/chart_widget_multi_series.md) — Multi-series `series:` array, `column` chart type, declarative Chartkick options (legend, stacked, axis titles, value formatting, colors, sort, library escape hatch), Okabe-Ito default palette, empty-state banner, defensive payload guards
+- [Workflow State Machine](design/workflow_state_machine.md) — Metadata-driven state machine: states, transitions, guards, audit log, three definition sources
+- [Background Jobs](design/background_jobs.md) — Async job execution: declarative/class handlers, multi-step jobs, retry, cancellation, triggers, scheduling, three definition sources
+- [Grouped Query Presenter](design/grouped_query_presenter.md) — GROUP BY queries with aggregates, date period grouping, HAVING, row_click drill-through
+- [Nested Menu Dropdowns](design/nested_menu_dropdowns.md) — Sub-groups in top menu and sidebar dropdowns
+- [Responsive Menu](design/responsive-menu.md) — Phase 0–2 implementation: lcp-dropdown primitive (touch/keyboard), top-nav modes (none/wrap/overflow_more/hamburger), sidebar rail + off-canvas, cookie persistence, auto-injected sidebar_toggle, mobile header, rail-collapsed flyouts
+- [Dev Toolbar](design/dev_toolbar.md) — Developer tools overlay for metadata inspection
+- [HR Demo App](design/demo-app-hr.md) — HR management system demo application design
+- [Workflow Renderers](design/workflow_renderers.md) — Built-in workflow visualization: `workflow_timeline` (linear progress), `workflow_badge` (colored status badge), `workflow_graph` (Mermaid.js state diagram), auto-detection
+- [Model Inheritance](design/model_inheritance.md) — Abstract base models and Single Table Inheritance (STI)
+- [Sequence Fields](design/sequences.md) — Gap-free auto-numbering with scoped counters, format templates, and counter management
+- [Deep Filter Enhancements](design/recursive_association_field_picker.md) — Recursive association field picker and recursive condition nesting (AND/OR tree)
+- [Advanced Conditions](design/advanced_conditions.md) — Compound conditions (all/any/not), dynamic value references, dot-path fields, collection quantifiers, value services, lookup value references
+- [Workflow Approvals](design/workflow_approvals.md) — Multi-step approval engine on top of the state machine: steps, strategies, delegation, rework
+- [Context-Aware View Switcher](design/view_switcher_context.md) — View switcher integration with context-aware presenters
+- [Custom Render Blocks](design/custom_render_blocks.md) — Host-app partial delegation: custom sections, custom zones, page-level render_with
+- [Monitoring & Metrics](design/monitoring.md) — Health check, Prometheus metrics, error log, AS::Notifications instrumentation
+- [Export](design/export.md) — Data export: collection/batch export, field picker, formatting, profiles, history
+- [Pagination Footer](design/pagination_footer.md) — Unified pagination bar: per-page selector, record count, styled page links, First/Last toggle
+- [Import](design/import.md) — Server-side data import with file upload, column mapping, strategy selection, association lookup, profiles, background execution
+- [Import Nested has_one](design/import_nested_has_one.md) — Import flat CSV rows into parent + has_one associations: dot-notation mapping, nested_blank_strategy, auto-mapping, permission filtering
+- [Search Parameter Controls](design/search_parameter_controls.md) — Typed filter controls (dropdowns, toggles, ranges) in the presenter search toolbar, generating Ransack `?f[...]` params
+- [Theming](design/theming.md) — Dark mode, CSS custom property system, UI density, border radius, theme persistence, vendor CSS dark variants
+- [Host App Controller Integration](design/host_app_controller_integration.md) — `bind_to:` for existing host AR models (Phase A), controller concern extraction (Phase B1), `controller:` / `action_controllers:` per-presenter routing (Phase B2), `lcp_ruby:host_controller` generator (Phase B3)
+- [bind_to Managed Fields and Associations](design/bind_to_managed_fields_and_associations.md) — Per-item `lcp_managed: true` flag on `fields:` and `associations:` of `bind_to:` models so LCP can additively add columns and declare AR macros on host classes (resolves school audit issue #22 and the deferred `bind_to_associations:` future from the original `bind_to` design)
+- [Association `primary_key`](design/association_primary_key.md) — Per-association override of the target join column so `belongs_to` / `has_many` / `has_one` can join on a business key (`vema_code`, `iso_code`, `sku`) instead of the surrogate `id`; FK column type inferred from the referenced column; Layer B consumers (form selects, cascading selects, tree selects, page parameters [retired in PR 5; replaced by [page filters](reference/page_filters.md)], import/export field trees, virtual columns) updated end-to-end for string business keys
+- [Record Aliases](design/record_aliases.md) — Presenter-level alias resolution (`/preferences/me`, `/issues/last`) and model-level slug fields (`/articles/quarterly-report`): resolve chain, strategies, URL preservation, validation pipeline
+- [Permission `_default` Coverage Merge](design/permissions_default_role_coverage.md) — `extends:` keyword and coverage-merge default for per-model permission YAML files (roles, field_overrides, record_rules inherit from `_default`); pre/post-merge validators; `lcp_ruby:permissions:resolve` rake task
+- [`lcp_ruby:entity` Generator](design/entity_generator.md) — Single-command scaffold of model + presenter + permissions + view group from a CLI field grammar (v1: types/associations, v2: DB constraints + feature flags, v3: sections/renderers/color_map/link/polymorphic). Includes auto-link of belongs_to in index/show, synthetic `position`/`parent_id` fields for `--positioning`/`--tree`, polymorphic skip from index/show, reverse-association post-install hints (and optional `--auto-add-inverses` for DSL targets), and bash-brace-expansion guidance.
+- [Entity Generator `--menu` Flag](design/entity_generator_menu_flag.md) — `rails g lcp_ruby:entity … --menu=[<section>:]ROOT|<DropdownLabel>[:bottom|:right] --menu-icon=<lucide>` writes a `- view_group: <name>` entry into `config/lcp_ruby/menu.yml` at scaffold time above the seeded `# lcp:menu` marker. Pairs with `lcp_ruby:install --menu-layout=top|sidebar|both` (and `lcp new`'s wizard prompt) for marker seeding.
+- [Menu Modes + Auto-Append Polish](design/menu_modes_and_skeleton.md) — `:auto` (default) vs `:strict` mode semantics, auto-append transparency log surfacing every auto-appended view group at boot, B59 cross-presenter dedup, `presenter.menu_position` deprecation info-warning.
+- [Boot / Reload Lifecycle](design/boot_reload_lifecycle.md) — Dev-mode metadata watcher (closes school-audit B1 + B2: permission YAML reload + Duplicate-presenter), `db:prepare` / `db:setup` enhanced with `lcp_ruby:ensure_tables` post-action that idempotently materialises platform tables in topological order (closes B4 — `db:drop && db:prepare && db:seed` works in one process), `reload.lcp_ruby` AS::Notifications event symmetric to `boot.lcp_ruby`. Builds on the `LcpRuby.on_models_loaded` hook and `RELOAD_MUTEX` from authorization hardening v1.
+- [Generator Prerequisites Registry & `lcp_ruby:doctor`](design/generator_prerequisites_registry.md) — Declarative `FeatureRegistry` + `Prerequisites` Thor concern collapse three ad-hoc prereq checks (import/entity/api_tokens) into one source of truth. `lcp new` writes an install manifest; the `lcp_ruby:doctor` rake task replays it and reports feature state, environment leaks, and seed hygiene. `install_auth` now ships the `user.rb` metadata model directly (replacing `api_tokens`' buggy fallback).
+
+In Progress:
+
+- [Advanced Search & Filter Builder](design/advanced_search.md) — Type-aware quick search, Ransack-based filter builder, custom filter methods, query language (Phase 0–4 implemented)
+- [Page Layouts & View Slots](design/page_layout_and_slots.md) — Extensible page layout system: slot registry (Phase 1 implemented), layout variants (planned)
+- [Multiselect and Batch Actions](design/multiselect_and_batch_infrastructure.md) — Checkbox selection, batch delete/restore/permanently_destroy, selection modes, result logging (infrastructure + batch delete implemented; background execution deferred)
+
+Partially Implemented:
+- [Form Submit Actions](design/form_submit_actions.md) — Configurable form submit buttons with redirect, set_fields, pipeline execution, cross-presenter redirect, overflow dropdown (Phase 1–3 implemented)
+- [AJAX Error Handling](design/ajax_error_handling.md) — Graceful error handling for Turbo/fetch requests
+- [~~Workflow & Approvals~~](design/workflow_and_approvals.md) — Outdated, superseded by the two documents above
+
+Proposed:
+
+- [Agent Affordances](design/agent_affordances.md) — *(Draft)* Make skills + curated docs + an AGENTS.md/CLAUDE.md entrypoint available to AI agents in installed-gem host apps (not just inside this repo)
+- [Cached Aggregates](design/cached_aggregates.md) — Materialized aggregate values with automatic invalidation
+- [Context-Aware Presenters](design/context_aware_presenters.md) — Parent-context-dependent presenter resolution for polymorphic sub-resources
+- [Data Retention](design/data_retention.md) — Automatic purge policies for audit logs, soft-deleted records, and attachments
+- [Derived Associations](design/derived_associations.md) — Computed associations derived from aggregate/virtual columns
+- [Document Management](design/document_management.md) — File-centric document management (versioning, preview, metadata, workflows)
+- [Dynamic Presenters](design/dynamic_presenters.md) — DB-backed presenter overrides (user/role/system personalization layer)
+- [Hub Pages](design/hub_pages.md) — Hero banner + navigation cards landing pages
+- [Import & Export](design/import_export.md) — Data import and export (CSV, Excel, JSON)
+- [Multi-Step Forms](design/multi_step_forms.md) — Wizard-style forms with step navigation
+- [PaaS — AI-Powered App Builder](design/paas.md) — AI agent builds LCP apps from natural language; container management, chat UI, code-server
+- [Workflow Async Completion](design/workflow_async_completion.md) — Declarative `async_completion` on transitions for long-running operations
+- [Scoped Permissions](design/scoped_permissions.md) — Context-dependent permission definitions for polymorphic sub-resources
+- [Timeline View](design/timeline_view.md) — Timeline index layout for chronological data
+- [User Menu](design/user-menu.md) — User menu dropdown (profile, settings, logout)
+- [Chess Demo App](design/demo-app-chess.md) — Chess training academy demo application design
+- [E-Shop Demo App](design/demo-app-eshop.md) — E-shop demo application design
+- [External Database Models](design/external_database_models.md) — External DB tables (read-only and writable), local overlay extensions, cross-DB filtering, feature compatibility, unified presenter
+
+
+Research:
+
+- [Basepack Search Lessons](design/basepack_lessons.md) — Lessons learned from Basepack search system for advanced search design
+
+## Internals
+
+- [Architecture](architecture.md) — Module structure, data flow, controllers, views
+
+## Examples
+
+- [Example Apps](examples.md) — TODO and CRM app walkthroughs

data/docs/architecture.md

@@ -0,0 +1,212 @@
+# Architecture
+
+## Overview
+
+LCP Ruby is a Rails mountable engine that generates full CRUD information systems from YAML metadata. Models, presenters (UI config), and permissions are defined in YAML files. The engine dynamically builds ActiveRecord models, database tables, controllers, and views at runtime.
+
+## Data Flow
+
+```
+YAML metadata (config/lcp_ruby/)
+  ├── types/*.yml        → Metadata::Loader → TypeDefinition → TypeRegistry
+  ├── models/*.yml       → Metadata::Loader → ModelInheritanceResolver → ModelDefinition
+  ├── presenters/*.yml   → Metadata::Loader → PresenterDefinition
+  ├── permissions/*.yml  → Metadata::Loader → PermissionDefinition
+  ├── jobs/*.yml         → Metadata::Loader → BackgroundJobs::Definition
+  └── menu.yml           → Metadata::Loader → MenuDefinition → MenuItem (with badges)
+                                ↓
+              ModelFactory::Builder.build → LcpRuby::Dynamic::<Name>
+              (creates AR class + DB table + validations + transforms + associations + scopes)
+              (virtual models with table_name: _virtual are skipped — metadata only, no AR class)
+              (API models → ApiBuilder creates ActiveModel class, skips DB/AR-specific applicators)
+                                ↓
+              LcpRuby.registry.register(name, model_class)
+                                ↓
+              DataSource::Setup.apply!(loader) → instantiate adapters, wrap with cache/resilient,
+              attach to API model classes, apply cross-source associations
+                                ↓
+              CustomFields::Setup.apply!(loader) → contract validation, registry, handlers, accessors, scopes
+                                ↓
+              Roles::Setup.apply!(loader) → contract validation, registry, change handler (if role_source == :model)
+                                ↓
+              Permissions::Setup.apply!(loader) → contract validation, registry, change handler, definition validator (if permission_source == :model)
+                                ↓
+              Groups::Setup.apply!(loader) → YAML/DB/host loader, registry, change handler (if group_source != :none)
+                                ↓
+              Auditing::Setup.apply!(loader) → contract validation, registry mark_available! (if any model has auditing: true)
+                                ↓
+              Pages::Setup.apply!(loader) → contract validation, registry, change handler, definition validator (if page_source == :model)
+              loader.merge_db_pages! → loads DB page definitions, overrides YAML/auto pages, recreates auto-pages
+                                ↓
+              BackgroundJobs::Setup.apply!(loader) → contract validation, sources, resolver,
+              triggers, schedule sync (if job definitions exist)
+                                ↓
+              Export::Setup.apply!(loader) → register export_config virtual model,
+              export_dialog page/presenter, ExportHandler event handler
+                                ↓
+              Metrics::Setup.apply!(loader) → resolve :auto error_log_enabled, register Prometheus metrics,
+              activate AS::Notifications subscriber, discover custom collectors from app/lcp_metrics/
+                                ↓
+              ConditionServiceRegistry.discover! → condition services from app/condition_services/
+              Services::Registry.discover! → data providers from app/lcp_services/data_providers/
+              Display::RendererRegistry.register_built_ins! → 28 built-in renderers + badge renderers
+              Display::RendererRegistry.discover! → custom renderers from app/renderers/
+              ViewSlots::Registry.register_built_ins! → 11 built-in slot components (toolbar, filters, pagination)
+                                ↓
+              Pages::Resolver → slug/name lookup → PageDefinition → zones → presenters
+                                ↓
+              Engine routes (/:lcp_slug/*) → ResourcesController
+              Dialog routes (/lcp_dialog/:page_name/*) → DialogsController
+              (CRUD with Pundit authorization, presenter-driven UI, conditional rendering,
+               composite pages with semantic layout, tabs, scope_context scoping)
+```
+
+## Key Modules
+
+| Module | Location | Purpose |
+|--------|----------|---------|
+| `Metadata` | `lib/lcp_ruby/metadata/` | Parses YAML into definition objects (ModelDefinition, PresenterDefinition, etc.). ModelHashMerger + ModelInheritanceResolver handle abstract model inheritance (two-pass load, topological sort, hash merge, abstract exclusion) |
+| `Types` | `lib/lcp_ruby/types/` | TypeRegistry, TypeDefinition, ServiceRegistry, built-in types (email, phone, url, color), transforms (strip, downcase, normalize_url, normalize_phone) |
+| `ModelFactory` | `lib/lcp_ruby/model_factory/` | Builds dynamic AR models: Builder orchestrates SchemaManager, ValidationApplicator, TransformApplicator, AssociationApplicator, VirtualColumnApplicator, ScopeApplicator, PositioningApplicator, UserstampsApplicator, SoftDeleteApplicator, AuditingApplicator, TreeApplicator, SequenceApplicator (gap-free auto-numbering with scoped counters). ApiBuilder builds ActiveModel classes for API-backed models. ApiAssociationApplicator creates cross-source association accessors |
+| `Sequences` | `lib/lcp_ruby/sequences/` | SequenceManager (admin API: set/current/list counter values), `build_scope_key` (scope hash to string key). Counter table via generator (`lcp_ruby:gapfree_sequences`) |
+| `DataSource` | `lib/lcp_ruby/data_source/` | API-backed model infrastructure: Base (contract), RestJson (HTTP adapter), Host (provider delegation), CachedWrapper (Rails.cache TTL), ResilientWrapper (error handling), ApiModelConcern (ActiveModel mixin), ApiFilterTranslator (Ransack→portable filter translation), ApiPreloader (batch N+1 prevention), ApiErrorPlaceholder (graceful degradation), Registry, Setup (boot orchestration) |
+| `VirtualColumns` | `lib/lcp_ruby/virtual_columns/` | Builder: injects SQL subqueries, expressions, JOINs, and GROUP BY into ActiveRecord scopes. Collector: auto-detects needed VCs from presenter metadata per context. Supports declarative aggregates, expression columns, JOIN-based columns, service-based VCs with `:current_user` placeholder, soft-delete filtering, and COALESCE defaults. `Aggregates::QueryBuilder` is a backward-compat alias |
+| `Presenter` | `lib/lcp_ruby/presenter/` | UI layer: Resolver (find by slug), LayoutBuilder (form/show sections + normalize_json_field_section for json_field: sources + sub-section enrichment), ColumnSet (visible columns), ActionSet (visible actions with record_rules integration via action_permitted_for_record?), IncludesResolver (auto-detects and applies eager loading from presenter metadata), FieldValueResolver (dot-path, template, FK, and simple field resolution with permission checks) |
+| `CustomFields` | `lib/lcp_ruby/custom_fields/` | Registry (per-model definition cache), Applicator (dynamic accessors + validations + defaults + stale cleanup), ContractValidator (boot-time model contract checks), Query (DB-portable JSON queries with field name validation), DefinitionChangeHandler (cache invalidation), Setup (shared boot logic with contract validation), Utils (env-aware JSON/numeric parsing) |
+| `Roles` | `lib/lcp_ruby/roles/` | Registry (thread-safe role name cache), ContractValidator (boot-time model contract checks), ChangeHandler (after_commit cache invalidation), Setup (boot orchestration). Only active when `role_source == :model` |
+| `Permissions` | `lib/lcp_ruby/permissions/` | Registry (per-model PermissionDefinition cache), ContractValidator (boot-time model contract checks), ChangeHandler (after_commit cache invalidation + PolicyFactory clear), DefinitionValidator (JSON validation on save), SourceResolver (DB → YAML priority chain), Setup (boot orchestration). Only active when `permission_source == :model` |
+| `Groups` | `lib/lcp_ruby/groups/` | Contract (interface), Registry (thread-safe, delegates to loader), YamlLoader (static groups from YAML), ModelLoader (DB queries), HostLoader (adapter delegation), ContractValidator (group/membership/mapping models), ChangeHandler (after_commit cache invalidation), Setup (boot orchestration by group_source). Integrates with PermissionEvaluator via role_resolution_strategy |
+| `Display` | `lib/lcp_ruby/display/` | BaseRenderer (base class), 28 built-in renderer classes in `renderers/` (incl. WorkflowBadge, WorkflowTimeline), badge renderers (CountBadge, TextBadge, IconBadge), RendererRegistry (registers built-ins + auto-discovers host renderers from `app/renderers/`) |
+| `Authorization` | `lib/lcp_ruby/authorization/` | PolicyFactory (dynamic Pundit policies), PermissionEvaluator (can?, can_for_record? with alias resolution, readable_fields, writable_fields, with optional role validation via Roles::Registry), ScopeBuilder |
+| `Events` | `lib/lcp_ruby/events/` | Dispatcher + HandlerRegistry. Host apps define handlers in `app/event_handlers/` |
+| `Actions` | `lib/lcp_ruby/actions/` | ActionExecutor + ActionRegistry. Host apps define custom actions in `app/actions/` |
+| `Conditions` | `lib/lcp_ruby/condition_evaluator.rb`, `lib/lcp_ruby/condition_service_registry.rb`, `lib/lcp_ruby/dsl/condition_builder.rb` | ConditionEvaluator (strict: 15 operators, raises ConditionError on unknown operator/missing field), ConditionServiceRegistry. Supports compound (all/any/not), dot-path fields, collection quantifiers, dynamic value references (field_ref, current_user, date, service, lookup). DSL via `ConditionBuilder.build` block and `ConditionBuilder.lookup` helper. All condition callers (PermissionEvaluator, ActionSet, views) delegate to ConditionEvaluator. Host apps define condition services in `app/condition_services/` |
+| `Search` | `lib/lcp_ruby/search/` | QuickSearch (type-aware text search), ParamSanitizer (filter param cleanup), FilterParamBuilder (LCP operators to Ransack predicates), OperatorRegistry (type-to-operator mapping), CustomFilterInterceptor (filter_* method detection and interception), CustomFieldFilter (JSON column queries with type casting), FilterMetadataBuilder (permission-aware JSON metadata for the visual filter builder), QueryLanguageParser (recursive descent QL parser), QueryLanguageSerializer (condition tree to QL text), ParameterizedScopeApplicator (typed parameter casting, min/max clamping, filter_*/scope dispatch). Ransack model setup (`ransackable_attributes`, `ransackable_associations`) handled by `ModelFactory::RansackApplicator` at boot |
+| `SavedFilters` | `lib/lcp_ruby/saved_filters/` | Generator-based saved filter model (not hardcoded). SavedFiltersGenerator creates model/presenter/permissions YAML. Presenter config via `saved_filters` block inside `advanced_filter` (enabled, display mode, max_visible_pinned). Visibility: personal/role/group/global with ownership record_rules |
+| `Attachments` | `lib/lcp_ruby/model_factory/attachment_applicator.rb` | Applies Active Storage macros (has_one_attached/has_many_attached), validations (size, content_type, max_files), and variant config to dynamic models |
+| `Positioning` | `lib/lcp_ruby/model_factory/positioning_applicator.rb` | Applies `positioning` gem macro to positioned models; SchemaManager creates unique indices on scope + position columns (except SQLite) |
+| `Auditing` | `lib/lcp_ruby/auditing/` | Registry (available? flag), ContractValidator (audit model contract checks), AuditWriter (field diffs, JSON/custom field expansion, nested changes), Setup (boot orchestration). AuditingApplicator installs AR callbacks on audited models |
+| `UserSnapshot` | `lib/lcp_ruby/user_snapshot.rb` | Captures `{id, email, name, role}` from user objects; used by auditing and userstamps |
+| `BulkUpdater` | `lib/lcp_ruby/bulk_updater.rb` | `tracked_update_all` wrapper with yield hook for post-update callbacks (auditing, events) |
+| `Pages` | `lib/lcp_ruby/pages/` | Resolver (slug/name lookup), ScopeContextResolver (delegates to `LcpRuby::DynamicReferences::Resolver` — see [Dynamic References](reference/dynamic-references.md) for the dotted-string gramatika and depth limits), auto-page creation from presenters, PageDefinition (name, slug, model, layout, dialog_config, zones; composite helpers: `composite?`, `semantic?`, `zones_for_area`, `tab_zones`, `has_tabs?`, `has_sidebar?`, `has_below?`, `grid_template_columns`, `form_zone`, `main_zone`), ZoneDefinition (presenter/widget zones, grid positioning, visible_when, scope_context, label_key, `default_scope`, `width` (1-12), `filters` (`:full`/`:quick`/`:none`), `record_click` (`:navigate`/`:dialog`/`:none`), `submit_redirect` (`:self`), `record_source` (`param` key); predicates: `filterable?`, `filters_quick?`, `filters_full?`, `record_click_navigate?`, `record_click_dialog?`, `record_click_none?`, `form_zone?`, `submit_redirect_self?`, `record_source?`, `record_source_param`). DB-backed pages: ContractValidator (page_config model contract), Registry (thread-safe cache), ChangeHandler (after_commit invalidation), DefinitionValidator (JSON validation on save), Setup (boot orchestration when `page_source == :model`) |
+| `Widgets` | `lib/lcp_ruby/widgets/` | DataResolver (kpi_card aggregate, text i18n, list records, workflow_graph Mermaid diagram, approval_status; accepts scope_context and record; applies default_scope before zone scope), PresenterZoneResolver (scope pipeline: policy_scope → soft_delete → default_scope → zone_scope → scope_context → zone_filters → eager_loading → sort → paginate; returns zone, zone_record_slug in result), RecordSourceResolver (loads single record by ID from URL param; scope pipeline: policy_scope → soft_delete → eager_loading → find_by; returns record, presenter, layout_builder, column_set, field_value_resolver), ScopeApplicator (shared scope/model resolution, policy scope, soft delete filtering, `apply_default_scope`, scope_context WHERE/filter_* application) |
+| `ViewSlots` | `lib/lcp_ruby/view_slots/` | Registry (page+slot component store with position ordering), SlotComponent (immutable value object: name, partial, position, enabled callback), SlotContext (immutable data bag for slot partials: presenter, evaluator, params, records, record, locals). ViewSlotHelper provides `render_slot` for ERB templates. 11 built-in components registered at boot + `approval_status` slot registered dynamically by `Workflow::Approval::Setup` |
+| `BackgroundJobs` | `lib/lcp_ruby/background_jobs/` | Registry (thread-safe, resolver-backed), Definition (value object from YAML/DSL/DB), Setup (boot orchestration with contract validation), ExecutorJob (ActiveJob wrapper with retry/cancellation/timeout), BaseHandler (progress, logging, cancellation API), HandlerFactory (class/declarative/steps routing), StepsExecutor (multi-step sequential), Enqueue (public API with unique key dedup), 4 declarative actions (run_scope, fire_event, call_webhook, send_notification), event triggers, schedule adapter interface. Three sources: StaticSource, ModelSource, HostSource with Resolver priority merge |
+| `GroupedQuery` | `lib/lcp_ruby/grouped_query/` | Builder (GROUP BY + aggregate SELECT + HAVING from presenter config), Row (value object for group rows), ResultWrapper (enum labels, null display). Supports count/sum/avg/min/max, DISTINCT, date period truncation, dot-path JOINs, row_click filter URL generation |
+| `Sort` | `lib/lcp_ruby/sort/` | EnumSortOrder: CASE WHEN SQL for enum definition-order sorting, strategy resolution (definition_order/value). Used by both `apply_sort` (non-grouped) and `apply_grouped_sort` (grouped) |
+| `Export` | `lib/lcp_ruby/export/` | Setup (virtual model + dialog page registration + event handler), ExportHandler (builds query, generates CSV/XLSX, saves profile/history), FieldTreeBuilder (permission-aware field picker tree with association traversal), DataGenerator (CSV with BOM + XLSX via caxlsx), ValueFormatter (enum/date/boolean/decimal formatting options) |
+| `BatchActions` | `lib/lcp_ruby/batch_actions/` | BaseService (shared constructor, `each_record`, `log_item`, `finalize_batch_operation`, message builder), DestroyService (soft/hard delete with per-record permission), RestoreService (undiscard), PermanentlyDestroyService (hard delete discarded), CustomActionDispatcher (per-record iteration vs bulk execution based on `batch_capable?`, with auth checks, error handling, progress callbacks, result log). All services accept `records:, evaluator:, model_definition:, current_user:, batch_operation: nil, &progress` |
+| `JsonItemWrapper` | `lib/lcp_ruby/json_item_wrapper.rb` | ActiveModel wrapper for JSON hash items; dynamic getter/setter per field from ModelDefinition; type coercion (integer, float, boolean); `validate_with_model_rules!` (presence, length, numericality, format); `to_hash` for persistence. Used by `json_field:` + `target_model:` nested sections |
+| `Metrics` | `lib/lcp_ruby/metrics/` | PrometheusCheck (soft dependency), MetricDefinitions (metric constants incl. boot gauges: models/presenters/pages, request metrics with model label, permission_checks_total), Subscriber (AS::Notifications → Prometheus, view_group+model labels on requests, permission.lcp_ruby events, exception excluded from error log context), Collector (base class for host collectors with `subscribe` DSL for AS::Notifications), CollectorRegistry (auto-discovery from `app/lcp_metrics/`, subscription lifecycle), Fingerprint (error normalization), RateLimiter (in-memory throttle), ErrorRecorder (atomic upsert to error log), JsonQuery (portable JSON column queries), Setup (boot orchestration, `:auto` resolution) |
+
+## Controller Stack
+
+`ApplicationController` (`app/controllers/lcp_ruby/application_controller.rb`):
+- Inherits from host app's controller (configurable via `parent_controller`)
+- Thin assembler that includes 9 modular concerns from `LcpRuby::Controller::*` (see below)
+- Cross-cutting `instrument_request` around_action for AS::Notifications
+
+Includable concerns (`lib/lcp_ruby/controller/`):
+- `ErrorHandling` — `rescue_from MetadataError`, `RecordNotFound`
+- `Authentication` — `current_user`, `effective_user` base impl, Warden integration
+- `PresenterSetup` — resolves presenter + model from `:lcp_slug`, auto-registers ~11 LCP view helpers
+- `Impersonation` — overrides `effective_user` when impersonating
+- `Authorization` — Pundit integration, `current_evaluator`, `policy`, `policy_scope`
+- `PathHelpers` — `resource_path`, `resources_path`, `edit_resource_path`, etc.
+- `ViewHelpers` — sort, breadcrumbs, view group methods
+- `Search` — `apply_advanced_search`, `apply_sort`, filter helpers
+- `CrudHelpers` — `permitted_params`, `set_record`, `setup_show_view_objects`, `setup_index_view_objects`
+
+Each concern has dependency guards via `method_defined?` checks in its `included do` block — including in wrong order raises a descriptive error at class load time. Host app controllers can include any subset of these concerns via the `lcp_ruby:host_controller` generator or manually.
+
+`ResourcesController` (`app/controllers/lcp_ruby/resources_controller.rb`):
+- Standard CRUD (index/show/new/create/edit/update/destroy)
+- Composite pages: `show` branches on `current_page.composite?` → `load_composite_page` resolves main zone (show or form via `form_zone?`) + delegates to `load_secondary_zones` for sidebar/below/tabs; tab zones are loaded lazily via `zone` action (Turbo Frames). `zone` action at `/:slug/:id/zones/:zone_name` calls `resolve_zone_data` for unified zone dispatch (widget/record_source/presenter). `zone_params(zone)` conditionally permits `qs` (when `zone.filterable?`), `f`/`cf` (when `zone.filters_full?`). Form zones: `update` uses `submit_redirect_self?` to redirect back to show page; on validation error, `load_composite_page_for_form_error` re-renders with dirty VCs. Show-in-dialog: `show` renders `_dialog_show_frame` when `dialog_context?` (`?_dialog=1`)
+- `permitted_params` filters by writable fields + association FK fields
+- `apply_advanced_search` 7-step pipeline: default scope, predefined filter scope, param sanitization, custom filter interception, Ransack query, quick search (`?qs=`), custom field filters (`?cf[...]`)
+- Authorization via Pundit on every action
+
+`CustomFieldsController` (`app/controllers/lcp_ruby/custom_fields_controller.rb`):
+- Nested under `/:lcp_slug/custom-fields` for managing custom field definitions
+- Dual context: parent model from `:lcp_slug`, CFD model + generated presenter for views
+- Records scoped by `target_model` from parent URL context (prevents cross-model access)
+- Reuses `lcp_ruby/resources` views via `controller_path` override
+- Separate authorization via `custom_field_definition` permissions
+
+`ApprovalTasksController` (`app/controllers/lcp_ruby/approval_tasks_controller.rb`):
+- 5 POST actions: `approve`, `reject`, `return_task`, `claim`, `delegate`
+- Nested under `/:lcp_slug/:id/approval_tasks/:task_id/<action>`
+- Authorizes via `show?` on the record (task-level auth handled by `TaskManager`)
+- Validates task belongs to record's active approval request
+- Rescues `TaskActionError`, `DelegationError` → redirect with alert flash
+
+`DialogsController` (`app/controllers/lcp_ruby/dialogs_controller.rb`):
+- Handles dialog-only pages (no slug) at `/lcp_dialog/:page_name/*`
+- Resolves presenter and model from the page definition
+- Supports both persistent models (AR create/update) and virtual models (JsonItemWrapper validation + `dialog_submit` event)
+- Uses `DialogRendering` concern for dialog frame rendering and success responses
+- `DialogRendering` concern also mixed into `ResourcesController` for `?_dialog=1` context detection
+
+## Routing
+
+Engine mounts at a configurable path (default `/`). All resources use a slug-based pattern:
+```
+/:lcp_slug                     → resources#index
+/:lcp_slug/new                 → resources#new
+/:lcp_slug/:id                 → resources#show
+/:lcp_slug/:id/zones/:zone_name → resources#zone (GET, Turbo Frame zone content)
+/:lcp_slug/:id/edit            → resources#edit
+/:lcp_slug/filter_fields           → resources#filter_fields (GET, JSON filter metadata)
+/:lcp_slug/batch_count             → resources#batch_count (GET, JSON count for "select all matching")
+/:lcp_slug/export_fields              → resources#export_fields (GET, JSON field tree for picker)
+/:lcp_slug/batch_selection             → resources#batch_selection (POST, session token for large ID sets)
+/:lcp_slug/batch_actions/:action_name → actions#execute_batch (POST, batch action dispatch)
+/:lcp_slug/parse_ql                → resources#parse_ql (POST, QL text → condition tree)
+/:lcp_slug/:id/approval_tasks/:task_id/<action> → approval_tasks#<action> (POST, 5 actions)
+/:lcp_slug/custom-fields           → custom_fields#index
+/:lcp_slug/custom-fields/manage    → custom_fields#manage (bulk editor)
+/:lcp_slug/custom-fields/:id       → custom_fields#show
+/lcp_dialog/:page_name/new        → dialogs#new (dialog-only page)
+/lcp_dialog/:page_name            → dialogs#create (POST)
+/lcp_dialog/:page_name/:id/edit   → dialogs#edit
+/lcp_dialog/:page_name/:id        → dialogs#update (PATCH)
+```
+
+The slug comes from the presenter YAML (e.g., `slug: deals` → `/deals`). Dialog routes use page names instead of slugs.
+
+**Custom controller routing.** Presenters can declare `controller: "checkouts"` (full override) or `action_controllers: { new: "wizard#new" }` (per-action override) to route to host app controllers instead of LCP's `ResourcesController`. `LcpRuby::Routing::PresenterRoutes.draw_custom_controller_routes` generates explicit slug-scoped routes for these presenters and is called **before** the catch-all `scope ":lcp_slug"` block. Rails matches top-down so explicit literal-slug routes win. All custom routes set `defaults: { lcp_slug, lcp_presenter }` so existing `set_presenter_and_model` works unchanged. Ancillary routes (saved filters, custom fields, actions, transitions, approval tasks) always remain on LCP controllers. See the [Host Controller Integration reference](reference/host-controller-integration.md).
+
+**Connecting to existing host AR models.** A model YAML can declare `bind_to: "::Employee"` to use an existing ActiveRecord class instead of creating a new dynamic model. For `bind_to:` models, both `SchemaManager` and `ModelFactory::Builder` are skipped — the existing class is registered in `LcpRuby.registry` as-is. Optional features can be opt-in via `bind_to_apply: [ransack, scopes, validations, ...]`. See the [Host Controller Integration reference](reference/host-controller-integration.md#bind_to--connecting-to-an-existing-ar-model).
+
+## How Association Selects Work
+
+When a form field has `input_type: association_select` (e.g., `todo_list_id`):
+1. `LayoutBuilder.normalize_section` matches the FK field name against `association.foreign_key` metadata
+2. Creates a synthetic `FieldDefinition` (type: integer) and attaches the `AssociationDefinition`
+3. `_form.html.erb` renders a `<select>` populated from the target model's records via `LcpRuby.registry.model_for(assoc.target_model)`
+4. FK fields bypass the `field_writable?` check (they're permitted separately in the controller)
+
+## Permission System
+
+Permissions YAML defines roles with: `crud` list, `fields` (readable/writable), `actions`, `scope`, `presenters`. The `PermissionEvaluator.can?` method maps action aliases (`edit` → `update`, `new` → `create`) before checking the CRUD list. Record-level rules (`record_rules`) can deny specific CRUD operations based on field conditions with role exceptions. `can_for_record?` resolves action aliases and delegates condition evaluation to `ConditionEvaluator.evaluate_any` (all 15 operators, compound/collection/dot-path/lookup). Record rules automatically hide built-in `edit`/`destroy` action buttons on index pages via `ActionSet#action_permitted_for_record?`.
+
+## Test Structure
+
+- **Unit tests**: `spec/lib/lcp_ruby/` — test individual subsystems against YAML fixtures in `spec/fixtures/metadata/`
+- **Integration tests**: `spec/integration/` — test full HTTP request cycle using fixtures in `spec/fixtures/integration/{todo,crm}/`
+- **Dummy app**: `spec/dummy/` — minimal Rails app that mounts the engine at `/`
+- **Integration helper**: `spec/support/integration_helper.rb` — provides `load_integration_metadata!` and `stub_current_user` for request specs
+- Each test resets `LcpRuby.reset!` and clears Dynamic constants before running (see `spec_helper.rb`)
+
+### Generator regression coverage
+
+Every platform generator's output must pass `ConfigurationValidator` clean (the same validator that `rake lcp_ruby:validate` runs in production). The harness:
+
+- **Test harness**: `spec/support/generator_fixture.rb` — `build_minimal_app(tier:)`, `run_generator`, `validate_metadata`. Two tiers: `:tier1` (bare `config/lcp_ruby/` directories) and `:tier2` (tier1 + minimal Rails skeleton for generators that patch host files).
+- **Shared example**: `spec/support/shared_examples/generator_validates_clean.rb` — runs DSL + YAML, supports `prerequisites:`, `args:`, `stub_active_storage:`.
+- **Per-generator coverage**: `spec/lib/generators/lcp_ruby/all_generators_validate_spec.rb` — registry of every shipped generator. Adding a new generator means adding one entry to the `GENERATORS` array.
+- **Preset stack coverage**: `preset_minimal_validate_spec.rb`, `preset_standard_validate_spec.rb`, `preset_full_validate_spec.rb` — run the full generator chain that `lcp new --preset=<name>` would invoke, on a single destination. These catch cross-generator collisions (view group positions, duplicate permission rules) that single-generator specs miss.
+- **Service reference coverage**: `services_coverage_spec.rb` — static-analysis sweep that ensures every `service: <name>` reference in any template resolves to a registered built-in.
+- **CI gate**: `.github/workflows/ci.yml` runs `bundle exec rspec spec/lib/generators spec/lib/lcp_ruby/metadata` on every push and pull request — new specs under `spec/lib/generators/lcp_ruby/` are picked up automatically.
+
+Background: see `docs/improve-tasks/aggregated.md` cross-cutting theme #1 ("generator regression") and item C10.