lcp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15ce78e55a51f7b9192bd168c209459194465fe62de1f459d405d126e937accf
-  data.tar.gz: 550348550e26fc527d98d4090038f2919e2b1d866de92ecfaf885f75b2a597f1
+  metadata.gz: 9484b30d4253443cf9411e7e3bf6ae68446a092329b9f15b755db3fff166f0b0
+  data.tar.gz: 17e6a672a34b528006c55bf851e60f6ddf303df10acd15f4370067e3231240f7
 SHA512:
-  metadata.gz: 9e16d8a1b1d2804f52bd42483ddde70819511994465bcf68e58b27eee62234ad4f4e3155ae7b2478381cc4a3c004eeb3d04d68fe3c611ae9317198d64b5ae620
-  data.tar.gz: 75b0a589c1ee4e84c41c05fd78c356e79212d68f048d1d57e1c2857ce350ba36adf0701f7d9dc88ae29ff5867eb0eeccb33a3aee1d15a01e0ca10ff3ef6dc0cd
+  metadata.gz: bbf59bd655c458f3dbbb9ea01e6ac39e4389738fd38311851ffdf08eb02c19a045268acff0b4daca2da375a39dc197b1d029932771952d2b5bc52afaf2dd6dd8
+  data.tar.gz: 23f062bd96b24754437dae622770d8f73f26f344018488cbdb68b60e4734888fdc06bde98dab314dd684e6f277aa8cd1c22f36407b12dfdf42e563833c804ef4

data/.claude/skills/lcp-custom-field/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: lcp-custom-field
-description: Use when enabling or managing LCP Ruby custom fields — runtime user-defined fields stored in a model's `custom_data` JSON column. Triggers on phrases like "custom fields", "user-defined fields", "runtime fields", "extensible fields", "add fields without migration", "custom_data", "custom_field_definition", "field at runtime", "tenant-specific fields", "EAV", "show_in_table", "show_in_form", "field permissions for custom fields", `custom_fields: true` on a model. Also for editing the auto-generated `custom_field_definition` model/presenter/permissions or rolling out the `lcp_ruby:custom_fields` generator.
+description: >-
+  Use when enabling or managing LCP Ruby custom fields — runtime user-defined
+  fields stored in a model's `custom_data` JSON column. Triggers on phrases like
+  "custom fields", "user-defined fields", "runtime fields", "extensible fields",
+  "add fields without migration", "custom_data", "custom_field_definition",
+  "field at runtime", "tenant-specific fields", "EAV", "show_in_table",
+  "show_in_form", "field permissions for custom fields", `custom_fields: true`
+  on a model. Also for editing the auto-generated `custom_field_definition`
+  model/presenter/permissions or rolling out the `lcp_ruby:custom_fields`
+  generator.
 ---
 
 > **Reference docs base:** run `bundle exec rake lcp_ruby:docs` in an LCP app (version-matched), otherwise `lcp docs path`. Resolve any `docs/X` reference below under that base (or the project root if a `docs/` tree exists there).

data/.claude/skills/lcp-custom-field/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "LCP Custom Fields"
+  short_description: "Runtime custom fields for LCP models"
+  default_prompt: "Use $lcp-custom-field to add runtime custom fields to an LCP Ruby model."

data/.claude/skills/lcp-getting-started/SKILL.md

@@ -22,7 +22,7 @@ Pick the path based on whether the user has an app yet.
 
 ### Path A — greenfield (`lcp new`)
 
-Requires Ruby 3.1+ and Rails 8.1+ on the user's machine. The CLI runs `rails new`, installs the gem, runs the chosen generators, prepares the database, and copies `lcp-*` Claude skills into `.claude/skills/`.
+Requires Ruby 3.2+ and Rails 8.1+ on the user's machine. The CLI runs `rails new`, installs the gem, runs the chosen generators, prepares the database, and copies `lcp-*` Claude skills into `.claude/skills/`.
 
 ```bash
 lcp new my_app                                    # interactive wizard

data/.claude/skills/lcp-getting-started/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "LCP Getting Started"
+  short_description: "Bootstrap and orient LCP Ruby apps"
+  default_prompt: "Use $lcp-getting-started to bootstrap a new LCP Ruby app and pick the first authoring steps."

data/.claude/skills/lcp-host-binding/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "LCP Host Binding"
+  short_description: "Bind LCP metadata to Rails host apps"
+  default_prompt: "Use $lcp-host-binding to connect LCP metadata to existing Rails models or controllers."

data/.claude/skills/lcp-model/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "LCP Model Authoring"
+  short_description: "Create and edit LCP model metadata"
+  default_prompt: "Use $lcp-model to create or update LCP Ruby model metadata."

data/.claude/skills/lcp-permissions/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "LCP Permissions"
+  short_description: "Author LCP role and field access rules"
+  default_prompt: "Use $lcp-permissions to define LCP role, CRUD, field, and record access rules."

data/.claude/skills/lcp-presenter/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "LCP Presenter Authoring"
+  short_description: "Build LCP index, show, and form UIs"
+  default_prompt: "Use $lcp-presenter to build or refine an LCP presenter UI."

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

@@ -1,6 +1,14 @@
 ---
 name: lcp-workflow
-description: Use when creating or modifying LCP Ruby workflow definitions in `config/lcp_ruby/workflows/` (either YAML `*.yml` or DSL `*.rb`), including approval processes. Triggers on phrases like "add a workflow", "state machine", "transition", "approval process", "approver", "approve/reject task", "guard condition", "set_fields on transition", "audit log for state changes", "workflow timeline", "delegation", "rework policy", "bypass_when", "on_entry/on_exit", "trigger: system", "workflow_source", "host workflow provider".
+description: >-
+  Use when creating or modifying LCP Ruby workflow definitions in
+  `config/lcp_ruby/workflows/` (either YAML `*.yml` or DSL `*.rb`), including
+  approval processes. Triggers on phrases like "add a workflow", "state
+  machine", "transition", "approval process", "approver", "approve/reject task",
+  "guard condition", "set_fields on transition", "audit log for state changes",
+  "workflow timeline", "delegation", "rework policy", "bypass_when",
+  "on_entry/on_exit", "trigger: system", "workflow_source", "host workflow
+  provider".
 ---
 
 > **Reference docs base:** run `bundle exec rake lcp_ruby:docs` in an LCP app (version-matched), otherwise `lcp docs path`. Resolve any `docs/X` reference below under that base (or the project root if a `docs/` tree exists there).
@@ -207,7 +215,7 @@ end
 | Source | Behavior |
 |--------|----------|
 | `:static` | YAML/DSL files in `config/lcp_ruby/workflows/`. Always loaded if files exist. |
-| `:model` | DB-backed. Requires a model with `name`, `model_name`, `field_name`, `states` (json), `transitions` (json), `version`, `active`, `audit_log`. |
+| `:model` | DB-backed. Requires a model with `name`, `target_model`, `field_name`, `states` (json), `transitions` (json), `version`, `active`, `audit_log`. |
 | `:host` | Provider class implementing `StateMachineContract` (`workflows_for(model_name)`, `workflow_by_name(name)`). |
 
 **Static is always active.** The configured non-static source is additive. **On name conflicts: `static > model > host`.**

data/.claude/skills/lcp-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "LCP Workflow Authoring"
+  short_description: "Define LCP state machines and approvals"
+  default_prompt: "Use $lcp-workflow to define an LCP workflow state machine or approval process."

data/CHANGELOG.md

@@ -9,6 +9,63 @@ warnings until `1.0.0`.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-01
+
+### Added
+
+- **MySQL / MariaDB support.** The full non-system suite now passes on
+  MySQL/MariaDB and is gated in CI alongside PostgreSQL and SQLite. Adapter
+  -aware SQL throughout: date-grouping emits `DATE_FORMAT`/`CONCAT`+`QUARTER`
+  period keys, custom-field JSON queries wrap `JSON_EXTRACT` in `JSON_UNQUOTE`
+  with MySQL-valid `CAST` targets, `ArrayQuery` uses a `JSON_TABLE()` row source
+  (contains/overlaps/contained_by/text-search were previously broken on MySQL),
+  and `json`/`array` attribute types are auto-applied on `bind_to` models. New
+  `LcpRuby.mysql?` helper; MySQL-only default decimal precision (16,4) when a
+  field declares none.
+- **Windows support.** Example apps bundle `tzinfo-data` (locks made
+  Windows-installable via `--add-platform x64-mingw-ucrt`); Sprockets'
+  file-backed asset cache is disabled on Windows in non-production to dodge a
+  non-atomic `File.rename` EACCES race; the `rails --version` probe is portable
+  on cmd.exe so `lcp new` / `lcp run` work. New
+  [docs/guides/windows-setup.md](docs/guides/windows-setup.md).
+- **Asset-pipeline auto-wiring.** Sprockets/Propshaft engine assets are wired
+  up automatically with a boot-time check, opt-out via `--skip-asset-pipeline`
+  on both layouts. `rich_text` and `markdown` page widgets; generator
+  `DELETE ME` sample with `--skip-sample` opt-out.
+
+### Changed
+
+- **Minimum Ruby is now 3.2** (was 3.1). `lib/` already uses `Data.define`
+  (Ruby 3.2), so the gem would `NameError` on 3.1 — the declared floor was
+  wrong. Ruby 3.1 is also EOL (security support ended March 2025).
+- **AI authoring skills now install for Codex as well as Claude Code.**
+  `lcp new`, `rails generate lcp_ruby:agent_setup`, and
+  the skills-only `rails generate lcp_ruby:claude_skills` /
+  `lcp skills install` paths populate `.codex/skills/lcp-*` alongside
+  `.claude/skills/lcp-*`; shipped skills also include `agents/openai.yaml`
+  metadata for Codex/OpenAI clients.
+- Dropped the unused `view_component` dependency; bumped the CSRF-protection
+  gem and declared `csv` + `ostruct` explicitly (silences Ruby 3.4 default-gem
+  deprecation warnings).
+- Enum resolver returns raw keys and humanizes at display time, consistently
+  across all surfaces.
+
+### Fixed
+
+- `lcp run` is now idempotent on a re-used directory: a `.lcp-run` marker lets a
+  second invocation re-boot the already-materialized example instead of aborting
+  with "already exists and is not empty". A non-empty directory without the
+  marker is still refused, and the marker is written only after `db:setup`
+  succeeds so an interrupted first run can't downgrade the next.
+- `bind_to` models on MariaDB serialized `json`/`array` columns via `Hash#to_s`
+  (the bind_to path skips the Builder, so AR attribute types were never applied),
+  tripping `json_valid()`. Built-in auth + OIDC also fixed (`LcpRuby::User` now
+  declares explicit `:json` attributes for `lcp_role`/`profile_data`).
+- Usage-audit hardening (from building a real host app): menu key validation and
+  empty-menu guards, export `Array` handling for `has_many` dot-paths,
+  render-time `rich_text` sanitization on DB-backed pages, manifest
+  failure-mode detection, and `i18n_check` rake fixes.
+
 ## [0.1.0] - 2026-05-28
 
 Initial public release.
@@ -65,5 +122,6 @@ Initial public release.
 - Minimum **Ruby 3.1**, **Rails ≥ 7.1, < 9.0**.
 - The CLI binary is `lcp`; the Ruby module is `LcpRuby`.
 
-[Unreleased]: https://github.com/lksv/lcp/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/lksv/lcp/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/lksv/lcp/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/lksv/lcp/releases/tag/v0.1.0

data/app/assets/javascripts/lcp_ruby/dev_toolbar.js

@@ -5,12 +5,11 @@
   var BUTTON_CLASS = "lcp-dev-button";
   var SELECTOR = "[data-lcp-dev-presenter], [data-lcp-dev-zone]";
 
-  // Defensive i18n shim: window.LcpI18n is populated by lcp_i18n_payload_tag
-  // + i18n.js (bundled into application.js). Both live behind
-  // `if Rails.application.config.respond_to?(:assets)` in the layout, while
-  // dev_toolbar.js loads unconditionally whenever DevToolbar is enabled.
-  // In hosts without Sprockets (Propshaft-only, no-asset setups) LcpI18n.t
-  // is undefined, so we fall back to the caller-provided fallback string.
+  // Defensive i18n shim: window.LcpI18n.t comes from i18n.js (bundled into
+  // application.js). application.js and this dev_toolbar.js now load together
+  // behind `lcp_emit_engine_assets?` in the layout, so LcpI18n.t is normally
+  // present when this runs. The shim stays as defense-in-depth: if LcpI18n.t
+  // is ever undefined we fall back to the caller-provided fallback string.
   function t(key, fallback) {
     var i18n = window.LcpI18n;
     if (i18n && typeof i18n.t === "function") return i18n.t(key, fallback);

data/app/controllers/concerns/lcp_ruby/zone_resolution.rb

@@ -11,7 +11,8 @@ module LcpRuby
 
       if zone.widget?
         resolved_context = resolve_zone_scope_context(zone)
-        Widgets::DataResolver.new(zone, user: effective_user, scope_context: resolved_context, record: @record, **page_params_opts).resolve
+        Widgets::DataResolver.new(zone, user: effective_user, scope_context: resolved_context,
+          record: @record, trusted: page_allows_raw_html?, **page_params_opts).resolve
       elsif zone.custom?
         resolve_custom_zone_data(zone)
       elsif zone.record_source?
@@ -29,6 +30,18 @@ module LcpRuby
       end
     end
 
+    # Whether the page being rendered may emit raw (unsanitized) HTML widgets
+    # (rich_text). True unless the page is database-defined — DB pages are
+    # end-user-editable through the platform UI, so their rich_text content is
+    # sanitized at render. Defense-in-depth behind the save-time
+    # Pages::DefinitionValidator, which bypass paths (seeds, update_column,
+    # save(validate: false), records persisted before that validator shipped)
+    # can skip.
+    def page_allows_raw_html?
+      page = @page_definition || current_page
+      page.nil? || page.source_type != "database"
+    end
+
     def resolve_zone_scope_context(zone)
       return {} if zone.scope_context.blank?
 

data/app/helpers/lcp_ruby/display/card_helper.rb

@@ -28,7 +28,13 @@ module LcpRuby
         return "" if field.blank?
 
         value = resolve_title_value(record, field)
-        rendered = empty_value_placeholder(value, current_presenter)
+        # Humanize when title_field points to an enum (issue #18 — resolver
+        # now returns raw enum keys). Non-enum fields pass through unchanged;
+        # a has_many dot-path Array renders comma-joined via the collection
+        # renderer (card_display_value), same as subtitle/description — a bare
+        # format_enum_display would print the Ruby array literal.
+        fd, model_name = card_field_meta(field)
+        rendered = empty_value_placeholder(card_display_value(value, fd, model_name || current_model_name), current_presenter)
 
         # Blank/unauthorized title is the placeholder "—" — never a nav target.
         return rendered if value.blank?
@@ -55,14 +61,16 @@ module LcpRuby
         return "" unless @column_set.readable_named_slot?(field)
 
         value = @field_resolver.resolve(record, field, fk_map: @fk_map)
-        field_def = card_field_def(field)
+        field_def, fd_model = card_field_meta(field)
+        fd_model ||= current_model_name
 
         rendered =
           if (renderer_key = card_config["subtitle_renderer"]).present?
-            render_display_value(value, renderer_key, card_config["subtitle_options"] || {}, field_def, record: record)
+            render_display_value(value, renderer_key, card_config["subtitle_options"] || {}, field_def, record: record, model_name: fd_model)
           else
-            # Parity with table column rendering — humanize enum values before placeholder fallback.
-            empty_value_placeholder(format_enum_display(value, field_def, current_model_name), current_presenter)
+            # Parity with table column rendering — humanize enum values
+            # (scalar or has_many Array) before placeholder fallback.
+            empty_value_placeholder(card_display_value(value, field_def, fd_model), current_presenter)
           end
 
         content_tag(:div, rendered, class: "lcp-card-subtitle")
@@ -77,10 +85,16 @@ module LcpRuby
         value = @field_resolver.resolve(record, field, fk_map: @fk_map)
         return "" if value.blank?
 
+        # Humanize when description_field points to an enum (uncommon but
+        # supported). Non-enum fields pass through unchanged; has_many Arrays
+        # render comma-joined via the collection renderer.
+        fd, fd_model = card_field_meta(field)
+        display = card_display_value(value, fd, fd_model || current_model_name)
+
         max_lines = card_config["description_max_lines"]
         style = ("--lcp-card-desc-lines: #{max_lines.to_i}" if max_lines)
 
-        content_tag(:div, value, class: "lcp-card-description", style: style)
+        content_tag(:div, display, class: "lcp-card-description", style: style)
       end
 
       # Returns: <div class="lcp-card-image"><img .../></div> or "".
@@ -140,8 +154,9 @@ module LcpRuby
 
         items = fields.map do |fc|
           value = @field_resolver.resolve(record, fc["field"], fk_map: @fk_map)
-          field_def = card_field_def(fc["field"])
-          label = field_label_for(fc, field_def: field_def, model_name: current_model_name)
+          field_def, fd_model = card_field_meta(fc["field"])
+          fd_model ||= current_model_name
+          label = field_label_for(fc, field_def: field_def, model_name: fd_model)
 
           rendered_value =
             if fc["partial"].present?
@@ -151,9 +166,9 @@ module LcpRuby
                 context: "card.fields[].partial '#{fc['partial']}' for record_id=#{record.id}"
               )
             elsif fc["renderer"].present?
-              render_display_value(value, fc["renderer"], fc["options"] || {}, field_def, record: record)
+              render_display_value(value, fc["renderer"], fc["options"] || {}, field_def, record: record, model_name: fd_model)
             else
-              empty_value_placeholder(format_enum_display(value, field_def, current_model_name), current_presenter)
+              empty_value_placeholder(card_display_value(value, field_def, fd_model), current_presenter)
             end
 
           content_tag(:div, label, class: "lcp-card-field-label") +
@@ -241,20 +256,58 @@ module LcpRuby
 
       private
 
+      # Returns [FieldDefinition, model_name] tuple for any field reference
+      # (direct field or dot-path). Used to humanize enum values against the
+      # correct i18n namespace — the dot-path target model, not the page's
+      # current_model_name. Returns [nil, nil] for template fields, blanks,
+      # or unresolvable paths.
+      def card_field_meta(field_name)
+        return [ nil, nil ] if field_name.blank?
+        return [ nil, nil ] if Presenter::FieldValueResolver.template_field?(field_name)
+
+        # through_collections: has_many dot-path enum terminals (e.g.
+        # `tasks.status`) must resolve their field def so the Array of values
+        # humanizes element-wise (issue #18).
+        Metadata::FieldPath.terminal(current_model_definition, field_name, through_collections: true)
+      end
+
       def card_field_def(field_name)
-        return nil if field_name.blank?
-        return nil if Presenter::FieldValueResolver.dot_path?(field_name) || Presenter::FieldValueResolver.template_field?(field_name)
+        card_field_meta(field_name).first
+      end
+
+      # Humanize + render a card field value that may be a scalar or an Array
+      # (has_many dot-path terminal). Arrays render comma-joined through the
+      # collection renderer so enum elements show labels, not raw keys
+      # (issue #18 — `format_enum_display` returns an Array for Array input,
+      # which a bare `content_tag` would print as a Ruby literal). Scalars
+      # humanize via `format_enum_display`. Mirrors the table/tree surfaces.
+      def card_display_value(value, field_def, model_name)
+        return render_display_value(value, "collection", {}, field_def, model_name: model_name) if value.is_a?(Array)
+
+        format_enum_display(value, field_def, model_name)
+      end
 
-        current_model_definition&.field(field_name)
+      # Plain-text humanized value for alt attributes. Unlike card_display_value
+      # (which emits HTML through the collection renderer), a has_many dot-path
+      # Array of enum labels is comma-joined as plain text — alt is an attribute,
+      # not markup, so HTML would leak into it. Issue #18 / card surface: a bare
+      # `format_enum_display(...).to_s` printed the Ruby array literal instead.
+      def card_alt_text(value, field_def, model_name)
+        humanized = format_enum_display(value, field_def, model_name)
+        humanized.is_a?(Array) ? humanized.join(", ") : humanized.to_s
       end
 
       def card_image_alt(record, card_config)
         if (alt_field = card_config["image_alt_field"]).present?
-          return @field_resolver.resolve(record, alt_field, fk_map: @fk_map).to_s
+          value = @field_resolver.resolve(record, alt_field, fk_map: @fk_map)
+          fd, fd_model = card_field_meta(alt_field)
+          return card_alt_text(value, fd, fd_model || current_model_name)
         end
 
         if (title_field = card_config["title_field"]).present?
-          return resolve_title_value(record, title_field).to_s
+          value = resolve_title_value(record, title_field)
+          fd, fd_model = card_field_meta(title_field)
+          return card_alt_text(value, fd, fd_model || current_model_name)
         end
 
         ""
@@ -279,7 +332,9 @@ module LcpRuby
         alt_field = card_config["avatar_alt_field"]
         return "" if alt_field.blank?
 
-        @field_resolver.resolve(record, alt_field, fk_map: @fk_map).to_s
+        value = @field_resolver.resolve(record, alt_field, fk_map: @fk_map)
+        fd, fd_model = card_field_meta(alt_field)
+        card_alt_text(value, fd, fd_model || current_model_name)
       end
 
       def image_renderable?(value)

data/app/helpers/lcp_ruby/display_helper.rb

@@ -1,24 +1,51 @@
 module LcpRuby
   module DisplayHelper
-    def render_display_value(value, renderer_key, options = {}, field_def = nil, record: nil)
+    def render_display_value(value, renderer_key, options = {}, field_def = nil, record: nil, model_name: nil)
       return value if renderer_key.blank?
 
       renderer = LcpRuby::Display::RendererRegistry.renderer_for(renderer_key.to_s)
       return value unless renderer
 
       effective_options = options || {}
-      if field_def&.enum? && !effective_options.key?("label")
-        effective_options = effective_options.merge("label" => field_def.enum_label_for(value, model_name: current_model_name))
+      if field_def&.enum?
+        # For dot-path columns the i18n namespace is the target model, not the
+        # presenter's current model. Caller passes model_name: explicitly when
+        # the field def comes from a different model than the page is showing.
+        enum_model = model_name || current_model_name
+        if value.is_a?(Array)
+          # has_many → terminal enum dot-path (e.g. `tasks.status`) resolves to
+          # an Array of raw keys; humanize each element so list renderers
+          # (`collection`) emit labels, not raw keys (issue #18). The scalar
+          # `label` injection below can't help here — list renderers render
+          # each element, not a single pre-labeled value.
+          value = humanize_enum_array(value, field_def, enum_model)
+        elsif !effective_options.key?("label")
+          effective_options = effective_options.merge("label" => field_def.enum_label_for(value, model_name: enum_model))
+        end
       end
 
       renderer.render(value, effective_options, record: record, view_context: self)
     end
 
+    # Humanize an enum value for display. Scalars route through
+    # `enum_label_for`; Arrays (has_many → terminal enum dot-path) humanize
+    # each element so the collection renderer / clipboard copy show labels,
+    # not raw keys (issue #18). Non-enum field defs and blank values pass
+    # through unchanged.
     def format_enum_display(value, field_def, model_name = nil)
       return value unless field_def&.enum? && value.present?
+      return humanize_enum_array(value, field_def, model_name) if value.is_a?(Array)
       field_def.enum_label_for(value, model_name: model_name)
     end
 
+    # Map each element of an enum-valued Array through `enum_label_for`,
+    # leaving blanks untouched. Shared by `render_display_value` and
+    # `format_enum_display` so on-table, in-card, and clipboard rendering
+    # of has_many enum dot-paths stay consistent.
+    def humanize_enum_array(values, field_def, model_name)
+      values.map { |v| v.blank? ? v : field_def.enum_label_for(v, model_name: model_name) }
+    end
+
     def compute_item_classes(record, presenter)
       rules = presenter.item_classes
       return "" if rules.empty?

data/app/helpers/lcp_ruby/display_template_helper.rb

@@ -40,7 +40,7 @@ module LcpRuby
                                    link_to_record, presenter_slug)
       resolver = build_template_field_resolver(model_definition, permission_evaluator)
 
-      title_text = resolver ? resolver.resolve(record, template_def.template) : template_def.template
+      title_text = resolver ? resolver.resolve(record, template_def.template, humanize_enums: true) : template_def.template
       title_html = ERB::Util.html_escape(title_text.to_s)
       title_html = wrap_in_link(title_html, record, presenter_slug, model_definition) if link_to_record
 
@@ -53,13 +53,13 @@ module LcpRuby
       parts << content_tag(:span, title_html, class: "lcp-display-template__title")
 
       if template_def.subtitle.present?
-        subtitle_text = resolver ? resolver.resolve(record, template_def.subtitle) : template_def.subtitle
+        subtitle_text = resolver ? resolver.resolve(record, template_def.subtitle, humanize_enums: true) : template_def.subtitle
         parts << content_tag(:span, ERB::Util.html_escape(subtitle_text.to_s),
                              class: "lcp-display-template__subtitle")
       end
 
       if template_def.badge.present?
-        badge_text = resolver ? resolver.resolve(record, template_def.badge) : template_def.badge
+        badge_text = resolver ? resolver.resolve(record, template_def.badge, humanize_enums: true) : template_def.badge
         parts << content_tag(:span, ERB::Util.html_escape(badge_text.to_s),
                              class: "lcp-display-template__badge")
       end

data/app/helpers/lcp_ruby/layout_helper.rb

@@ -1,5 +1,17 @@
 module LcpRuby
   module LayoutHelper
+    # Whether the engine should emit its own pipeline-dependent asset tags
+    # (`javascript_include_tag`/`stylesheet_link_tag`/`asset_path` for
+    # `lcp_ruby/*`). False when the host opted out via
+    # `config.skip_asset_pipeline_check = true` — that host runs its own JS
+    # bundler and owns including the LCP assets, so emitting the tags would
+    # raise Propshaft::MissingAssetError → 500. Single source of truth so the
+    # layout's several engine-asset blocks (core bundle, dev toolbar, vendored
+    # mermaid) can't drift — adding a new one just calls this.
+    def lcp_emit_engine_assets?
+      !LcpRuby.configuration.skip_asset_pipeline_check
+    end
+
     # Resolves a column or field label using the same fallback chain as
     # FieldDefinition#resolved_label, with one extra step for synthetic
     # fields (timestamps, FK columns, dotted association paths) that don't
@@ -200,11 +212,22 @@ module LcpRuby
       true
     end
 
-    # MenuItem-shaped keys allowed in provider returns. `provider:`
-    # and `panel_provider:` are stripped (chains are banned — each
-    # YAML position resolves to one source, never a chain).
+    # Internal/derived keys silently dropped from provider returns. `type`
+    # is always re-derived from the destination keys, so a provider that
+    # echoes it (e.g. from a stored to_kwargs snapshot) must not trip the
+    # forbidden-key check below — nor reach MenuItem.from_hash_at_depth,
+    # which rejects `type` to stay consistent with the JSON schema.
+    PROVIDER_STRIP_KEYS = %w[type].freeze
+
+    # MenuItem-shaped keys allowed in provider returns. `provider:` and
+    # `panel_provider:` are NOT listed (chains are banned — each YAML position
+    # resolves to one source, never a chain), so a provider return carrying
+    # them hits the forbidden-key branch and raises (record_error in prod) —
+    # they are rejected, not silently dropped (that is PROVIDER_STRIP_KEYS).
+    # MUST stay a subset of MenuItem::KNOWN_KEYS — every key here is fed
+    # straight into MenuItem.from_hash_at_depth, which rejects unknown keys.
     PROVIDER_RETURN_ALLOWED_KEYS = %w[
-      type label label_key icon url method aria_label aria_label_key
+      label label_key icon url method aria_label aria_label_key
       badge children visible_when disable_when presenter alias action
       defaults render render_panel widget position options
     ].freeze
@@ -277,11 +300,12 @@ module LcpRuby
     end
 
     # Filters a provider-returned hash to the whitelisted MenuItem keys.
-    # Drops `provider:` and `panel_provider:` (chains are banned).
-    # Drops anything else with the canonical idiom — raise in dev/test,
-    # record_error in production.
+    # PROVIDER_STRIP_KEYS (e.g. `type`) are dropped silently at EVERY depth
+    # first (so a `children: [{type:…}]` echo doesn't trip reject_unknown_keys!
+    # during the nested build), then top-level keys outside
+    # PROVIDER_RETURN_ALLOWED_KEYS raise — record_error in production.
     def filter_provider_keys(hash, provider_name)
-      stringified = hash.transform_keys(&:to_s)
+      stringified = deep_strip_provider_keys(hash).transform_keys(&:to_s)
       sanitized = {}
 
       stringified.each do |k, v|
@@ -302,6 +326,23 @@ module LcpRuby
       sanitized
     end
 
+    # Removes PROVIDER_STRIP_KEYS (internal/derived keys a provider may echo,
+    # e.g. `type`) from a provider-returned item AND recursively from its
+    # nested `children:`. These keys are re-derived by MenuItem, so stripping
+    # them at every depth keeps reject_unknown_keys! from raising on an echoed
+    # `type:` in a nested child. Key type (String/Symbol) is preserved.
+    def deep_strip_provider_keys(hash)
+      hash.each_with_object({}) do |(k, v), out|
+        next if PROVIDER_STRIP_KEYS.include?(k.to_s)
+
+        out[k] = if k.to_s == "children" && v.is_a?(Array)
+          v.map { |child| child.is_a?(Hash) ? deep_strip_provider_keys(child) : child }
+        else
+          v
+        end
+      end
+    end
+
     # Builds the `request_context:` hash passed to provider classes.
     # Provider may run outside a controller-driven request (cache
     # warm-up, mailer, background job that builds an HTML preview);

data/app/helpers/lcp_ruby/tree_helper.rb

@@ -4,6 +4,21 @@ module LcpRuby
                          reparentable: false, search_active: false)
       return "".html_safe if roots.blank?
 
+      # Pre-compute terminal field_def + owning model_name per column once,
+      # then pass through recursive calls. Avoids O(rows × cols × fields)
+      # linear scans on deep trees (the inline lookup in render_tree_row used
+      # to do this per (row × column) without memoization).
+      @_tree_col_field_defs ||= {}
+      @_tree_col_model_names ||= {}
+      columns.each do |col|
+        path = col["field"]
+        next unless path
+        next if @_tree_col_field_defs.key?(path)
+        fd, mn = LcpRuby::Metadata::FieldPath.terminal(current_model_definition, path, through_collections: true)
+        @_tree_col_field_defs[path] = fd
+        @_tree_col_model_names[path] = mn || current_model_name
+      end
+
       roots.each_with_index.map { |record, idx|
         render_tree_row(record, children_map, columns, depth: depth,
           default_expanded: default_expanded, match_ids: match_ids,
@@ -83,17 +98,23 @@ module LcpRuby
           end
 
           value = @field_resolver.resolve(record, col["field"], fk_map: @fk_map)
+          fd = @_tree_col_field_defs[col["field"]]
+          fd_model = @_tree_col_model_names[col["field"]] || current_model_name
 
           rendered_value = if col["partial"]
             render(partial: col["partial"], locals: { value: value, record: record, options: col["options"] || {} })
           elsif col["renderer"]
-            render_display_value(value, col["renderer"], col["options"], nil, record: record).to_s
+            render_display_value(value, col["renderer"], col["options"], fd, record: record, model_name: fd_model).to_s
           elsif value.is_a?(Array)
-            render_display_value(value, "collection", {}).to_s
+            # Pass fd + model so enum elements humanize (issue #18) — the
+            # collection renderer itself only does item.to_s.
+            render_display_value(value, "collection", {}, fd, record: record, model_name: fd_model).to_s
           elsif value.is_a?(ActiveRecord::Base)
             empty_value_placeholder(display_association_value(value), current_presenter).to_s
           else
-            empty_value_placeholder(value, current_presenter).to_s
+            # Resolver returns raw enum keys (issue #18); humanize via field's
+            # owning model namespace.
+            empty_value_placeholder(format_enum_display(value, fd, fd_model), current_presenter).to_s
           end
           cell_content << wrap_link_through(value, rendered_value, record, col)
 

data/app/models/lcp_ruby/user.rb

@@ -9,6 +9,16 @@ module LcpRuby
   class User < ActiveRecord::Base
     self.table_name = "lcp_ruby_users"
 
+    # Declare the AR :json attribute type for the JSON columns explicitly.
+    # PostgreSQL (jsonb) and SQLite reflect these correctly, but MariaDB reports
+    # JSON columns as `longtext`, so without this AR serializes a Hash via
+    # Hash#to_s (`{"k"=>"v"}`) — invalid JSON that trips MariaDB's implicit
+    # json_valid() CHECK on insert, and returns a raw String on read. The proc
+    # defaults mirror the create_lcp_ruby_users migration and hand each new
+    # record its own object.
+    attribute :lcp_role, :json, default: -> { [ "viewer" ] }
+    attribute :profile_data, :json, default: -> { {} }
+
     # Devise modules — lockable and timeoutable are always declared but
     # their behavior depends on configuration (lock_after_attempts, session_timeout).
     devise :database_authenticatable, :registerable, :recoverable,