lcp 0.1.0 → 0.2.0

data/lib/lcp_ruby/cli/run_command.rb

@@ -13,10 +13,21 @@ module LcpRuby
     # installed gem dir is typically read-only), so this copies the source,
     # rewrites the Gemfile to depend on the installed `lcp`, then bundles,
     # prepares the DB, and starts the server. Rails-free at invocation.
+    #
+    # Idempotent: the first run drops a {MARKER} dotfile in the target. A second
+    # `lcp run` on the same dir detects that marker and re-boots the existing app
+    # (skipping materialize + Gemfile rewrite, and using `db:prepare` so existing
+    # data survives) instead of aborting. A non-empty dir WITHOUT the marker is
+    # still refused — it's likely the user's own files, not our example.
     class RunCommand
       MINIMUM_RUBY_VERSION  = "3.1"
       MINIMUM_RAILS_VERSION = "8.1"
 
+      # Dotfile written into a materialized app so a later `lcp run` recognizes
+      # it as ours and re-boots instead of refusing the non-empty dir. A dotfile
+      # so it never propagates via AssetCopier (its glob skips dotfiles).
+      MARKER = ".lcp-run"
+
       def initialize(name, dir, options, shell)
         @name    = name.to_s.strip.empty? ? "showcase" : name.to_s.strip
         @dir     = dir
@@ -26,8 +37,33 @@ module LcpRuby
 
       def run
         check_ruby_version!
-        source = resolve_source!
         target = File.expand_path(@dir || "./#{@name}")
+
+        if materialized?(target)
+          reuse!(target)
+        else
+          materialize!(target)
+        end
+      end
+
+      private
+
+      # A dir we previously materialized — re-boot it, keeping its data.
+      def reuse!(target)
+        existing = File.read(File.join(target, MARKER)).strip
+        unless existing.empty? || existing == @name
+          say "Note: #{target} holds example '#{existing}' — re-booting that " \
+              "(ignoring requested '#{@name}').", :yellow
+        end
+
+        say "Reusing existing app in #{target} ...", :green
+        warn_global_rails
+        boot!(target, fresh: false)
+      end
+
+      # A fresh target — copy the source in, rewire it to the installed gem, boot.
+      def materialize!(target)
+        source = resolve_source!
         refuse_non_empty!(target)
 
         say "Materializing example '#{@name}' into #{target} ...", :green
@@ -36,10 +72,16 @@ module LcpRuby
         remove_stale_lockfile!(target)
 
         warn_global_rails
-        boot!(target)
+        boot!(target, fresh: true)
       end
 
-      private
+      def materialized?(target)
+        File.exist?(File.join(target, MARKER))
+      end
+
+      def write_marker!(target)
+        File.write(File.join(target, MARKER), "#{@name}\n")
+      end
 
       def resolve_source!
         path = File.join(LcpRuby::GemPaths.examples, @name)
@@ -99,21 +141,63 @@ module LcpRuby
         File.delete(lock) if File.exist?(lock)
       end
 
-      def boot!(target)
+      def boot!(target, fresh:)
         Bundler.with_unbundled_env do
           run_step!("bundle install", target)
-          # `db:setup` (not `db:prepare`): the target dir is guaranteed empty, and
-          # db:setup invokes the `db:seed` Rake task *after* schema load — so LCP's
-          # `lcp_ruby:ensure_tables` prerequisite applies bind_to managed columns
-          # before seeding. `db:prepare` calls `load_seed` directly, bypassing that
-          # hook, and would crash seeds that touch boot-added managed columns.
-          run_step!("bundle exec rails db:setup", target)
+          run_step!(db_command(target, fresh), target)
+          # Drop the marker only now: a marker means a `db:setup` completed at
+          # least once, so a later run can trust the reuse path. (run_step! aborts
+          # on failure, so reaching here implies the DB step succeeded.) Reuse
+          # doesn't rewrite it — it already exists.
+          write_marker!(target) if fresh
           say ""
           say "Starting server (Ctrl-C to stop) ...", :green
           system("bundle", "exec", "rails", "server", chdir: target)
         end
       end
 
+      # Picks the Rails DB task, keeping the seed path `ensure_tables`-safe:
+      #
+      # * `db:setup` (not `db:prepare`) seeds via the `db:seed` *Rake task*, whose
+      #   `lcp_ruby:ensure_tables` prerequisite applies bind_to managed columns
+      #   before seeding. `db:prepare` seeds via `DatabaseTasks.load_seed`
+      #   directly (see Rails' `prepare_all`), bypassing that hook — it would
+      #   crash seeds that touch boot-added managed columns.
+      #
+      # So `db:prepare` is only safe when the DB already exists (it then just
+      # migrates and does NOT seed, preserving the user's data). We use it on
+      # reuse only when a DB is present; otherwise (fresh run, or a reuse whose
+      # DB was dropped/deleted) we fall back to the seed-safe `db:setup`.
+      def db_command(target, fresh)
+        return "bundle exec rails db:setup" if fresh || !database_present?(target)
+
+        "bundle exec rails db:prepare"
+      end
+
+      # Bundled examples (all the `lcp run` materializes) use sqlite3 under `db/`
+      # (crm/showcase/todo) or `storage/` (hr), and AssetCopier strips
+      # `*.sqlite3` on copy — so a DB file exists here only once `db:setup` has
+      # run. Its absence means "no DB yet / it was dropped", which routes reuse
+      # back to the seed-safe `db:setup`. Rails-free probe; no app boot (which
+      # would itself create tables).
+      #
+      # Scope to `db/`+`storage/` (not a whole-tree `**`): a bare `**/*.sqlite3`
+      # also matches stray DBs that don't mean "the app DB is here" — a gem's
+      # fixture under `vendor/bundle`, for instance — which would falsely report
+      # "present" and route a dropped-DB reuse to `db:prepare` (whose fresh-DB
+      # seed path crashes on bind_to managed columns). It also avoids walking a
+      # vendored bundle on every reuse.
+      #
+      # `base:` (not `File.join` into the pattern): `target` is an absolute path
+      # that may contain glob metacharacters (`[`, `{`, `*`) — e.g. a parent dir
+      # like `projects[old]`. Interpolating it into the pattern would make the
+      # glob silently match nothing, falsely report "no DB", and route a populated
+      # app to `db:setup`, which `schema:load`-purges the user's data. `base:`
+      # treats the directory literally.
+      def database_present?(target)
+        Dir.glob("{db,storage}/**/*.sqlite3", base: target).any?
+      end
+
       def run_step!(cmd, target)
         say ""
         say "  → #{cmd}"
@@ -131,7 +215,10 @@ module LcpRuby
       # Non-fatal: the app bundles its own Rails, so a missing/old global `rails`
       # only warrants a heads-up, not a hard stop.
       def warn_global_rails
-        version_output = `rails --version 2>/dev/null`.strip
+        # File::NULL (not a literal /dev/null) so the stderr redirect is valid
+        # on Windows cmd.exe too — a /dev/null redirect fails there and would
+        # garble this version probe.
+        version_output = `rails --version 2>#{File::NULL}`.strip
         return if version_output.empty?
 
         version = version_output.sub(/^Rails\s+/, "")

data/lib/lcp_ruby/cli/skills_command.rb

@@ -5,9 +5,9 @@ require_relative "../skills_installer"
 
 module LcpRuby
   module CLI
-    # `lcp skills install --global|--local` — install the bundled `lcp-*` Claude
-    # Code skills without a Rails app. The Rails-free sibling of the in-app
-    # `lcp_ruby:claude_skills` generator. Refresh prunes removed `lcp-*` skills.
+    # `lcp skills install --global|--local` — install the bundled `lcp-*` AI
+    # authoring skills without a Rails app. Refresh prunes removed `lcp-*`
+    # skills per target.
     class SkillsCommand < Thor
       def self.exit_on_failure?
         true
@@ -15,36 +15,48 @@ module LcpRuby
 
       desc "install", "Install bundled lcp-* skills (requires --global or --local)"
       option :global, type: :boolean, default: false,
-        desc: "Install into ~/.claude/skills/ (auto-triggers in every project)"
+        desc: "Install into per-agent global skills dirs (~/.claude/skills/, ~/.codex/skills/)"
       option :local, type: :boolean, default: false,
-        desc: "Install into ./.claude/skills/ (this project only)"
+        desc: "Install into per-agent local skills dirs (./.claude/skills/, ./.codex/skills/)"
+      option :agent, type: :string, default: "all",
+        desc: "Target agent: all, claude, or codex"
       def install
-        target = resolve_target
-        result = LcpRuby::SkillsInstaller.new(target: target).call
-        report(result, target)
+        resolve_targets.each do |agent, target|
+          result = LcpRuby::SkillsInstaller.new(target: target).call
+          report(result, agent, target)
+        end
       end
 
       private
 
       # Require an explicit, unambiguous destination — guessing would risk
       # writing to the wrong place (home vs project).
-      def resolve_target
+      def resolve_targets
         if options[:global] == options[:local]
           raise Thor::Error,
-            "Specify exactly one of --global (~/.claude/skills/) or --local (./.claude/skills/)."
+            "Specify exactly one of --global or --local."
         end
 
-        base = options[:global] ? File.expand_path("~/.claude") : File.expand_path(".claude")
-        File.join(base, "skills")
+        root = options[:global] ? File.expand_path("~") : File.expand_path(".")
+        LcpRuby::SkillsInstaller.agent_skill_targets(root: root, agents: selected_agents)
+      end
+
+      def selected_agents
+        raw = options[:agent].to_s.downcase
+        return LcpRuby::SkillsInstaller::DEFAULT_AGENTS if raw == "all"
+        return [ raw ] if LcpRuby::SkillsInstaller::AGENT_DIRECTORIES.key?(raw)
+
+        valid = LcpRuby::SkillsInstaller::DEFAULT_AGENTS.join(", ")
+        raise Thor::Error, "Unknown --agent=#{options[:agent].inspect}. Expected one of: all, #{valid}."
       end
 
-      def report(result, target)
+      def report(result, agent, target)
         unless result.any_changes?
-          say "No lcp-* skills found to install (checked #{LcpRuby::GemPaths.skills}).", :yellow
+          say "No #{agent} lcp-* skill changes for #{target} (checked #{LcpRuby::GemPaths.skills}).", :yellow
           return
         end
 
-        say "Installed lcp-* skills into #{target}:", :green
+        say "Installed #{agent} lcp-* skills into #{target}:", :green
         result.created.each { |n| say "  create  #{n}" }
         result.updated.each { |n| say "  update  #{n}" }
         result.removed.each { |n| say "  remove  #{n} (no longer shipped)", :yellow }

data/lib/lcp_ruby/cli.rb

@@ -33,6 +33,10 @@ module LcpRuby
         desc: "Skip interactive wizard, use defaults"
       option :skip_action_text, type: :boolean, default: false,
         desc: "Skip Action Text install (no WYSIWYG editor for :rich_text fields). Default: install."
+      option :skip_sample, type: :boolean, default: false,
+        desc: "Skip the Hello-World `item` model + presenter + permissions + view group. Default: create them (visible at /items). Generated files include DELETE ME headers."
+      option :skip_asset_pipeline, type: :boolean, default: false,
+        desc: "Skip the Sprockets compatibility shim (don't add `sprockets-rails` or create app/assets/config/manifest.js). Default: install. Only opt out if you've wired your own ESM bundler — LCP's JS won't load without one or the other."
       option :gem_source, type: :string,
         desc: "Gem source: 'rubygems' or 'path:/abs/path'"
       option :allow_partial, type: :boolean, default: false,
@@ -54,7 +58,7 @@ module LcpRuby
       end
       map "run" => :run_example
 
-      desc "skills SUBCOMMAND", "Manage bundled lcp-* Claude Code skills"
+      desc "skills SUBCOMMAND", "Manage bundled lcp-* AI agent skills"
       subcommand "skills", SkillsCommand
 
       desc "docs SUBCOMMAND", "Locate or copy the bundled LCP reference docs"

data/lib/lcp_ruby/configuration.rb

@@ -16,7 +16,8 @@ module LcpRuby
                   :theme,
                   :i18n_check,
                   :max_inheritance_depth,
-                  :runtime_type_renderers
+                  :runtime_type_renderers,
+                  :skip_asset_pipeline_check
 
     attr_reader :tenant_association_name
 
@@ -237,6 +238,16 @@ module LcpRuby
       # unflagged because their delta is strictly additive.
       @runtime_type_renderers = false
 
+      # Boot-time asset-pipeline compatibility check (see audit #16 and
+      # docs/reference/asset-pipeline.md). When false (default), boot
+      # raises `LcpRuby::AssetPipelineError` if Propshaft is loaded but
+      # sprockets-rails is not — the silent-failure mode that turned a
+      # broken nav-bar into hours of debugging. Set to true to opt out
+      # when you've manually wired an alternative bundler (esbuild,
+      # importmap-rails with custom pin map, etc.) and don't want the
+      # check to fire.
+      @skip_asset_pipeline_check = false
+
       # Role source defaults
       @role_source = :implicit
       @role_model = "role"
@@ -276,7 +287,7 @@ module LcpRuby
       @workflow_model = "workflow_definition"
       @workflow_model_fields = {
         name: "name",
-        model_name: "model_name",
+        target_model: "target_model",
         field_name: "field_name",
         states: "states",
         transitions: "transitions",

data/lib/lcp_ruby/custom_fields/applicator.rb

@@ -23,6 +23,14 @@ module LcpRuby
       def install_custom_data_accessors!
         mn = model_definition.name
 
+        # MariaDB reflects JSON columns as `longtext`, so ActiveRecord never
+        # applies a JSON type to the dynamically-created custom_data column
+        # (PG `jsonb` and SQLite `json` are detected fine). Without an explicit
+        # type a Hash round-trips through Ruby's `Hash#to_s` (`{"k"=>"v"}`) and
+        # fails JSON.parse on read. Registering the type makes Hash<->JSON
+        # (de)serialization adapter-agnostic.
+        model_class.attribute :custom_data, :json, default: {}
+
         model_class.define_method(:read_custom_field) do |name|
           data = read_custom_data_hash
           data[name.to_s]

data/lib/lcp_ruby/custom_fields/query.rb

@@ -12,13 +12,9 @@ module LcpRuby
         def text_search_condition(table_name, field_name, query)
           validate_field_name!(field_name)
           conn = ActiveRecord::Base.connection
-          quoted_table = conn.quote_table_name(table_name)
-
-          if LcpRuby.postgresql?
-            "#{quoted_table}.custom_data ->> #{conn.quote(field_name)} ILIKE #{conn.quote("%#{query}%")}"
-          else
-            "JSON_EXTRACT(#{quoted_table}.custom_data, #{conn.quote("$.#{field_name}")}) LIKE #{conn.quote("%#{query}%")}"
-          end
+          expr = json_extract_expr(table_name, field_name)
+          op = LcpRuby.postgresql? ? "ILIKE" : "LIKE"
+          "#{expr} #{op} #{conn.quote("%#{query}%")}"
         end
 
         # Apply a text search on a scope for a custom field.
@@ -41,14 +37,7 @@ module LcpRuby
         def exact_match(scope, table_name, field_name, value)
           validate_field_name!(field_name)
           conn = ActiveRecord::Base.connection
-          quoted_table = conn.quote_table_name(table_name)
-
-          condition = if LcpRuby.postgresql?
-            "#{quoted_table}.custom_data ->> #{conn.quote(field_name)} = #{conn.quote(value.to_s)}"
-          else
-            "JSON_EXTRACT(#{quoted_table}.custom_data, #{conn.quote("$.#{field_name}")}) = #{conn.quote(value.to_s)}"
-          end
-
+          condition = "#{json_extract_expr(table_name, field_name)} = #{conn.quote(value.to_s)}"
           scope.where(Arel.sql(condition))
         end
 
@@ -74,12 +63,18 @@ module LcpRuby
         # @return [String] SQL expression fragment
         def json_extract_expr(table_name, field_name)
           conn = ActiveRecord::Base.connection
-          quoted_table = conn.quote_table_name(table_name)
+          col = "#{conn.quote_table_name(table_name)}.custom_data"
 
           if LcpRuby.postgresql?
-            "#{quoted_table}.custom_data ->> #{conn.quote(field_name)}"
+            "#{col} ->> #{conn.quote(field_name)}"
+          elsif LcpRuby.mysql?
+            # MySQL/MariaDB JSON_EXTRACT keeps the JSON quotes around scalars
+            # ("5", "text"), which breaks numeric CAST (-> 0) and LIKE matching.
+            # JSON_UNQUOTE strips them. SQLite's json_extract already returns the
+            # raw scalar and has no JSON_UNQUOTE function, so it keeps the bare form.
+            "JSON_UNQUOTE(JSON_EXTRACT(#{col}, #{conn.quote("$.#{field_name}")}))"
           else
-            "JSON_EXTRACT(#{quoted_table}.custom_data, #{conn.quote("$.#{field_name}")})"
+            "JSON_EXTRACT(#{col}, #{conn.quote("$.#{field_name}")})"
           end
         end
 
@@ -97,9 +92,22 @@ module LcpRuby
         def apply_cast(expr, cast)
           case cast
           when :integer
-            LcpRuby.postgresql? ? "(#{expr})::integer" : "CAST(#{expr} AS INTEGER)"
+            if LcpRuby.postgresql?
+              "(#{expr})::integer"
+            elsif LcpRuby.mysql?
+              # MySQL/MariaDB CAST has no INTEGER/REAL target — use SIGNED / DECIMAL.
+              "CAST(#{expr} AS SIGNED)"
+            else
+              "CAST(#{expr} AS INTEGER)"
+            end
           when :decimal, :float
-            LcpRuby.postgresql? ? "(#{expr})::numeric" : "CAST(#{expr} AS REAL)"
+            if LcpRuby.postgresql?
+              "(#{expr})::numeric"
+            elsif LcpRuby.mysql?
+              "CAST(#{expr} AS DECIMAL(65, 30))"
+            else
+              "CAST(#{expr} AS REAL)"
+            end
           when :date
             LcpRuby.postgresql? ? "(#{expr})::date" : "DATE(#{expr})"
           else

data/lib/lcp_ruby/display/markdown_sanitize.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module LcpRuby
+  module Display
+    # Sanitize allow-list shared between the model-level :markdown renderer
+    # (`Display::Renderers::Markdown`) and the page-level `markdown` widget
+    # partial (`app/views/lcp_ruby/widgets/_markdown.html.erb`). Both run
+    # the same Commonmarker → HTML pipeline and need the same downstream
+    # tag/attribute allow-list — defining the constants twice invited drift
+    # (a `<details>` tag added to one site but not the other would be a
+    # silent rendering inconsistency).
+    #
+    # `unsafe:` is deliberately *omitted* from the Commonmarker options
+    # below — raw HTML embedded in the markdown source is stripped at
+    # parse time before sanitize ever runs. This module is the
+    # second layer of defense; the parser is the first.
+    module MarkdownSanitize
+      TAGS = %w[
+        p br strong em del s a ul ol li blockquote pre code h1 h2 h3 h4 h5 h6
+        table thead tbody tfoot tr th td hr img input div span
+      ].freeze
+      # Note: `input` is kept for tasklist checkbox rendering (generated by
+      # the Commonmarker tasklist extension). Raw HTML `<input>` from user
+      # source is blocked by omitting `unsafe: true` from Commonmarker options.
+
+      ATTRIBUTES = %w[href src alt title class type checked disabled].freeze
+
+      # Commonmarker extension hash — same on both the renderer and the
+      # widget. Frozen so a host extension that wants to add e.g. footnotes
+      # creates a new hash rather than mutating the shared default.
+      COMMONMARKER_OPTIONS = {
+        extension: { table: true, tasklist: true, strikethrough: true, autolink: true }
+      }.freeze
+    end
+  end
+end

data/lib/lcp_ruby/display/renderers/markdown.rb

@@ -1,26 +1,19 @@
 require "commonmarker"
+require "lcp_ruby/display/markdown_sanitize"
 
 module LcpRuby
   module Display
     module Renderers
       class Markdown < BaseRenderer
-        ALLOWED_TAGS = %w[
-          p br strong em del s a ul ol li blockquote pre code h1 h2 h3 h4 h5 h6
-          table thead tbody tfoot tr th td hr img input div span
-        ].freeze
-        # Note: `input` is kept for tasklist checkbox rendering (generated by Commonmarker tasklist extension).
-        # Raw HTML `<input>` from user source is blocked by omitting `unsafe: true` from Commonmarker options.
-
-        ALLOWED_ATTRIBUTES = %w[href src alt title class type checked disabled].freeze
-
         def render(value, options = {}, record: nil, view_context: nil)
           return nil if value.blank?
 
-          html = Commonmarker.to_html(value.to_s, options: {
-            extension: { table: true, tasklist: true, strikethrough: true, autolink: true }
-          })
+          html = Commonmarker.to_html(value.to_s,
+            options: LcpRuby::Display::MarkdownSanitize::COMMONMARKER_OPTIONS)
           view_context.content_tag(:div,
-            view_context.sanitize(html, tags: ALLOWED_TAGS, attributes: ALLOWED_ATTRIBUTES),
+            view_context.sanitize(html,
+              tags: LcpRuby::Display::MarkdownSanitize::TAGS,
+              attributes: LcpRuby::Display::MarkdownSanitize::ATTRIBUTES),
             class: "lcp-markdown")
         end
 

data/lib/lcp_ruby/engine.rb

@@ -2,7 +2,6 @@ require "pundit"
 require "ransack"
 require "kaminari"
 require "positioning"
-require "view_component"
 require "turbo-rails"
 require "stimulus-rails"
 require "devise"
@@ -230,6 +229,189 @@ module LcpRuby
         app.config.assets.paths << root.join("vendor", "assets", "javascripts")
         app.config.assets.paths << root.join("vendor", "assets", "stylesheets")
       end
+
+      Engine.disable_sprockets_dev_cache_on_windows!(app)
+    end
+
+    # Windows-only dev-server immunisation against Sprockets' non-atomic
+    # cache write (from a 2026-05-29 Windows bug report). `Sprockets::PathUtils.
+    # atomic_write` writes the compiled-asset cache to a temp file then
+    # `File.rename`s it into place; on Windows that rename raises
+    # `Errno::EACCES` whenever the source/target handle is still held (the
+    # writer's own un-GC'd handle, Windows Search, antivirus, OneDrive).
+    # A stock app touches one or two assets on first load and rarely trips
+    # it; LCP declares 12+ precompile entries that all hit the cache in
+    # parallel on the very first request, so the rename race fires ~95% of
+    # the time — crashing the first page of every fresh `rails server`.
+    # Subsequent requests read the now-existing cache and skip the write,
+    # which is why "reload always fixes it".
+    #
+    # Swapping the file-backed assets cache for a null_store removes the
+    # rename entirely (slightly slower dev compilation, no race). Scoped
+    # as narrowly as the bug: Windows only (Unix keeps its cache),
+    # non-production only — development and test both live-compile assets
+    # on demand and race the same way; production precompiles once at
+    # deploy and never live-writes this cache, so it's skipped — and a
+    # no-op when Sprockets isn't loaded (a Propshaft-only host has no such
+    # cache). Hosts that want the cache back can re-set `env.cache` in
+    # their own `config.assets.configure`.
+    def self.disable_sprockets_dev_cache_on_windows!(app)
+      return unless sprockets_dev_cache_race_prone?
+      return unless app.config.respond_to?(:assets)
+
+      app.config.assets.configure do |env|
+        env.cache = ActiveSupport::Cache.lookup_store(:null_store)
+      end
+    end
+
+    # Extracted predicate so the platform/env gating is unit-testable
+    # without a Windows box — same pattern as `check_asset_pipeline_compat!`.
+    def self.sprockets_dev_cache_race_prone?
+      return false unless Gem.win_platform?
+      return false unless defined?(Rails) && Rails.respond_to?(:env)
+      return false if Rails.env.production?
+      return false unless defined?(Sprockets)
+
+      true
+    end
+
+    # Boot-time asset-pipeline compatibility check (audit #16). LCP's JS
+    # is glued together by Sprockets `//= require` directives in
+    # `app/assets/javascripts/lcp_ruby/application.js`. The layout's
+    # `<script>` tags render regardless of pipeline (the old
+    # `Rails.application.config.respond_to?(:assets)` gate is true on
+    # Propshaft too, so it never actually suppressed them); without
+    # sprockets-rails the bundle then 404s, and with sprockets-rails but
+    # no manifest.js it serves the raw `//= require` source — both present
+    # as "top nav invisible, no JS errors".
+    # Fail loud at boot instead. `after :load_config_initializers` so
+    # the host's `LcpRuby.configure { |c| c.skip_asset_pipeline_check = true }`
+    # opt-out is honored. `before "lcp_ruby.load_metadata"` so we fail
+    # before any expensive metadata work happens.
+    initializer "lcp_ruby.asset_pipeline_check",
+      after: :load_config_initializers,
+      before: "lcp_ruby.load_metadata" do
+      Engine.check_asset_pipeline_compat!
+    end
+
+    # Extracted as a class method so it can be unit-tested without
+    # booting Rails — same pattern as `register_oidc_bearer_resolver_if_enabled!`.
+    def self.check_asset_pipeline_compat!
+      # Skip during `rails generate lcp_ruby:install` (chicken-and-egg:
+      # the generator IS what adds sprockets-rails + manifest.js to the
+      # host). Any other generate context is also skipped — the user is
+      # likely in the middle of bootstrapping and the next `rails s` /
+      # `db:prepare` will catch it.
+      return if LcpRuby.generator_context?
+      return if LcpRuby.configuration.skip_asset_pipeline_check
+      # Failure mode A — sprockets-rails is NOT loaded: Propshaft alone can't
+      # serve the engine's `//= require` bundle.
+      raise asset_pipeline_error_no_sprockets unless defined?(Sprockets::Rails)
+
+      # Failure mode B — sprockets-rails IS loaded but app/assets/config/manifest.js
+      # doesn't link the engine bundle (or is missing): Sprockets serves the raw
+      # `//= require` stub instead of the compiled file, so the nav is silently
+      # inert. The error message already names this case — now we detect it
+      # instead of returning clean.
+      return if asset_manifest_links_engine_bundle?
+
+      raise asset_pipeline_error_no_manifest
+    end
+
+    # True when app/assets/config/manifest.js exists AND explicitly links the
+    # engine bundle (`//= link lcp_ruby/application...`, what `lcp_ruby:install`
+    # writes). A host's own `//= link_tree`/`link_directory` sweeps ITS asset
+    # dirs, never the gem's bundled assets — so a manifest that only sweeps
+    # `../images` or `../stylesheets` does NOT serve the engine JS. Requiring
+    # the explicit link is what actually catches failure mode B (sprockets-rails
+    # present, engine bundle unlinked → Sprockets serves the raw `//= require`
+    # stub, nav silently inert). Hosts that bundle the engine some other way set
+    # skip_asset_pipeline_check (short-circuited earlier). Missing manifest →
+    # false. A read error never blocks boot: degrade to "assume linked".
+    def self.asset_manifest_links_engine_bundle?
+      return true unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+      manifest = Rails.root.join("app/assets/config/manifest.js")
+      return false unless File.exist?(manifest)
+
+      # Match an actual `//= link … lcp_ruby/application` directive at line start,
+      # not a bare substring — a commented-out `# //= link lcp_ruby/application`
+      # must not count as linked.
+      File.read(manifest).match?(%r{^\s*//=\s*link\b.*lcp_ruby/application})
+    rescue SystemCallError => e
+      raise unless Rails.env.production?
+      LcpRuby.record_error(e, subsystem: "asset_pipeline")
+      true
+    end
+
+    def self.asset_pipeline_error_no_sprockets
+      LcpRuby::AssetPipelineError.new(<<~MSG)
+        LCP Ruby requires a Sprockets-compatible asset pipeline, but the host
+        app appears to use Propshaft alone (Rails 8 default) without
+        sprockets-rails. The engine's JavaScript (~50 files glued by
+        `//= require` directives) cannot be served — the top navigation
+        bar and every Stimulus controller will be silently inert.
+
+        Fix (recommended, takes 30 seconds):
+
+          bin/rails generate lcp_ruby:install
+
+        which adds `gem "sprockets-rails"` to your Gemfile and creates
+        `app/assets/config/manifest.js` with the right link directives.
+        Then `bundle install` and restart.
+
+        Manual fix (equivalent):
+
+          # Gemfile
+          gem "sprockets-rails"
+
+          # app/assets/config/manifest.js
+          //= link lcp_ruby/application.js
+          //= link lcp_ruby/application.css
+          //= link lcp_ruby/tom-select.css
+          //= link lcp_ruby/tom-select.complete.min.js
+
+        Then `bundle install` and restart.
+
+        Opt out (only if you've wired your own ESM bundler):
+
+          # config/initializers/lcp_ruby.rb
+          LcpRuby.configure { |c| c.skip_asset_pipeline_check = true }
+
+        Full background: docs/reference/asset-pipeline.md
+      MSG
+    end
+
+    def self.asset_pipeline_error_no_manifest
+      LcpRuby::AssetPipelineError.new(<<~MSG)
+        LCP Ruby's JavaScript bundle is not being served. `sprockets-rails`
+        is installed, but `app/assets/config/manifest.js` does not link the
+        engine bundle — Sprockets then serves the raw `//= require` source
+        instead of the compiled file, so the top navigation bar and every
+        Stimulus controller are silently inert (no console error, no log).
+
+        Fix (recommended):
+
+          bin/rails generate lcp_ruby:install
+
+        which creates/updates `app/assets/config/manifest.js` with:
+
+          //= link lcp_ruby/application.js
+          //= link lcp_ruby/application.css
+          //= link lcp_ruby/tom-select.css
+          //= link lcp_ruby/tom-select.complete.min.js
+
+        Then restart. The engine bundle must be linked explicitly — a
+        `//= link_tree`/`//= link_directory` sweep of your own asset dirs does
+        NOT reach the gem's bundled assets.
+
+        Opt out (only if you've wired your own ESM bundler):
+
+          # config/initializers/lcp_ruby.rb
+          LcpRuby.configure { |c| c.skip_asset_pipeline_check = true }
+
+        Full background: docs/reference/asset-pipeline.md
+      MSG
     end
 
     BIND_TO_APPLICATOR_MAP = {
@@ -250,6 +432,8 @@ module LcpRuby
       "attachments"      => ModelFactory::AttachmentApplicator,
       "enums"            => ModelFactory::EnumApplicator,
       "service_accessors" => ModelFactory::ServiceAccessorApplicator,
+      "json_types"       => ModelFactory::JsonTypeApplicator,
+      "array_types"      => ModelFactory::ArrayTypeApplicator,
       "defaults"         => ModelFactory::DefaultApplicator,
       "inherited_parent_validator" => ModelFactory::InheritedParentValidatorApplicator
     }.freeze