lcp 0.1.0 → 0.2.0

data/docs/getting-started.md

@@ -8,12 +8,16 @@ All examples use the **Ruby DSL** as the primary format. YAML equivalents are pr
 
 | Requirement | Version |
 |-------------|---------|
-| Ruby | >= 3.1 |
+| Ruby | >= 3.2 |
 | Rails | >= 8.1 (for `lcp new`) or >= 7.1 (manual setup) |
 | Database | SQLite (development), PostgreSQL (production recommended) |
 
 LCP Ruby works with any Rails-supported database. SQLite is fine for development and this tutorial.
 
+> **On Windows?** A clean Windows box needs a working native-compilation
+> toolchain before `gem install lcp` and `lcp run` succeed. See the
+> [Windows Setup guide](guides/windows-setup.md) for the seven-step path.
+
 ## Quick Start with `lcp new`
 
 The fastest way to create a new LCP Ruby application:
@@ -30,7 +34,7 @@ This launches an interactive wizard that asks about:
 Feature presets:
 | Preset | Includes |
 |--------|----------|
-| **minimal** | Core platform only (sample model + presenter + permissions) |
+| **minimal** | Core platform only (sample `item` model + presenter + permissions) |
 | **standard** | Core + authentication + auditing + saved filters + export + import |
 | **full** | All 17 feature generators |
 | **custom** | Interactive selection of individual features |
@@ -44,6 +48,14 @@ rails s
 
 Visit `http://localhost:3000/items` to see the sample application.
 
+The sample `item` entity is generated by default so a fresh install has something to click. Each generated file (`models/item`, `presenters/items`, `permissions/item`, `views/items`) carries a `DELETE ME` header pointing at all four siblings; delete them once you've added your own entities via `rails g lcp_ruby:entity`. To skip the sample entirely:
+
+```bash
+lcp new my_app --skip-sample
+# or in an existing Rails app:
+rails generate lcp_ruby:install --skip-sample
+```
+
 To skip the interactive wizard and use defaults (sqlite3, DSL, minimal):
 
 ```bash
@@ -61,7 +73,7 @@ continue, then run `bundle exec rake lcp_ruby:doctor` from the new
 app to see exactly what is broken and how to fix it. See
 [reference/doctor.md](reference/doctor.md) for the full diagnostic.
 
-`lcp new` also installs [Claude Code skills](#claude-code-skills-ai-assisted-development) into `.claude/skills/` automatically — see the dedicated section below.
+`lcp new` also installs [AI agent skills](#ai-agent-skills-ai-assisted-development) into `.claude/skills/` and `.codex/skills/` automatically — see the dedicated section below.
 
 ### Installing from a local checkout
 
@@ -145,25 +157,25 @@ missing, the generator aborts up-front with a structured
 Run `bundle exec rake lcp_ruby:doctor` to see the full feature
 dependency graph.
 
-## Claude Code Skills (AI-Assisted Development)
+## AI Agent Skills (AI-Assisted Development)
 
-LCP Ruby ships a set of [Claude Code](https://claude.ai/code) skills (`lcp-model`, `lcp-presenter`, `lcp-permissions`, `lcp-workflow`, `lcp-custom-field`, `lcp-host-binding`) that auto-trigger when you're authoring the corresponding YAML/DSL configuration. Each skill briefs Claude on the 80/20 syntax + decision points + pitfalls and points at the relevant reference doc for the rest. The result: less time grepping for "how do I declare a `belongs_to` with a business-key join?" and fewer round-trips on common authoring tasks.
+LCP Ruby ships a set of AI authoring skills (`lcp-getting-started`, `lcp-model`, `lcp-presenter`, `lcp-permissions`, `lcp-workflow`, `lcp-custom-field`, `lcp-host-binding`) that auto-trigger in Claude Code and Codex when you're authoring the corresponding YAML/DSL configuration. Each skill briefs the agent on the 80/20 syntax + decision points + pitfalls and points at the relevant reference doc for the rest. The result: less time grepping for "how do I declare a `belongs_to` with a business-key join?" and fewer round-trips on common authoring tasks.
 
-**Auto-installed by `lcp new`** — you don't need to do anything. The skills land in `.claude/skills/` of the new app. Open the project in Claude Code (CLI, VS Code, or any other client) and skills activate automatically based on context.
+**Auto-installed by `lcp new`** — you don't need to do anything. The skills land in `.claude/skills/` and `.codex/skills/` of the new app. Open the project in Claude Code or Codex and skills activate automatically based on context.
 
 **Manual install / refresh after gem upgrade:**
 
 ```bash
-rails generate lcp_ruby:claude_skills
+rails generate lcp_ruby:agent_setup
 ```
 
-This copies `.claude/skills/lcp-*/` from the gem path into the host application, overwriting the existing copies (use `--force=false` to skip existing files). Re-run after `bundle update lcp_ruby` to pick up skills updated for the new gem version — keeps Claude's instructions in sync with the DSL/schema changes you just bundled.
+This copies `.claude/skills/lcp-*/` from the gem path into both `.claude/skills/` and `.codex/skills/`, overwriting existing `lcp-*` copies and pruning removed ones. Re-run after `bundle update lcp_ruby` to pick up skills updated for the new gem version — keeps agent instructions in sync with the DSL/schema changes you just bundled.
 
-**Verify**: list installed skills via `/skills` inside Claude Code, or `ls .claude/skills/` on disk.
+**Verify**: list installed skills via `/skills` inside Claude Code, or inspect `.claude/skills/` and `.codex/skills/` on disk.
 
-**For host-app developers**: commit `.claude/skills/lcp-*` to git so the whole team benefits. (`.claude/settings.local.json` is per-user and stays gitignored.)
+**For host-app developers**: commit `.claude/skills/lcp-*` and `.codex/skills/lcp-*` to git so the whole team benefits. (`.claude/settings.local.json` is per-user and stays gitignored.)
 
-**For platform contributors** (working on `lcp_ruby` itself): the canonical skill files live in `.claude/skills/` of the gem repo and are loaded automatically when you open the gem in Claude Code. The generator copies these same files — single source of truth.
+**For platform contributors** (working on `lcp_ruby` itself): the canonical skill files live in `.claude/skills/` of the gem repo; `.codex/skills/lcp-*` is a symlink mirror for Codex. The generator copies the canonical files — single source of truth.
 
 ## Installation (step-by-step)
 
@@ -175,24 +187,28 @@ Add LCP Ruby to your Gemfile:
 gem "lcp"
 ```
 
-### Asset Pipeline (Sprockets)
+### Asset Pipeline (handled automatically)
 
-LCP Ruby bundles its JavaScript and CSS via Sprockets. If your host app uses **Propshaft** (the Rails 8 default), you must also add `sprockets-rails` — otherwise the engine's JS (Stimulus controllers, row-click navigation, advanced filters, form handling) will not load:
+LCP Ruby bundles its JavaScript and CSS via Sprockets. On Rails 8 (Propshaft default), the engine needs `sprockets-rails` as a compatibility shim — otherwise the engine's JS (Stimulus controllers, row-click, advanced filters, form widgets) silently fails to load.
 
-```ruby
-gem "sprockets-rails"
+**You don't need to do anything**: `lcp new` and `rails generate lcp_ruby:install` both add `sprockets-rails` to your Gemfile and create `app/assets/config/manifest.js` with the right link directives automatically. The engine also has a boot-time check that raises `LcpRuby::AssetPipelineError` with a fix recipe if the shim is missing, so silent failure mode is impossible.
+
+If you've wired your own ESM bundler (esbuild, importmap with custom pins, etc.) and don't want the shim, opt out:
+
+```bash
+lcp new my_app --skip-asset-pipeline
+# or for an existing app:
+rails generate lcp_ruby:install --skip-asset-pipeline
 ```
 
-Then create `app/assets/config/manifest.js` to link the engine assets:
+…and silence the boot check:
 
-```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
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure { |c| c.skip_asset_pipeline_check = true }
 ```
 
-> **Note:** If your host app already uses Sprockets, skip this step — the engine assets are picked up automatically.
+See [Asset pipeline reference](reference/asset-pipeline.md) for the full background and the future ESM-native roadmap.
 
 Run `bundle install`.
 

data/docs/guides/dashboards.md

@@ -128,7 +128,7 @@ Displays an aggregate value (count, sum, avg, min, max) from a model.
 
 ### Text
 
-Displays static i18n content.
+Displays static i18n content as plain text (HTML-escaped).
 
 ```yaml
 - name: welcome
@@ -139,6 +139,49 @@ Displays static i18n content.
   position: { row: 2, col: 1, width: 12, height: 1 }
 ```
 
+For formatted blurbs (headings, links, lists, emphasis) pick `rich_text` or `markdown` instead. All three share the same `content_key:` API.
+
+### Rich Text
+
+i18n content emitted as raw HTML — locale string can carry `<h2>`, `<a>`, `<strong>`, etc.
+
+```yaml
+- name: announcement
+  type: widget
+  widget:
+    type: rich_text
+    content_key: lcp_ruby.dashboard.announcement_html  # i18n key holds HTML
+  position: { row: 2, col: 1, width: 12, height: 1 }
+```
+
+Trust model: same level as any engine view that uses `raw`. Use when translations live alongside code and go through code review.
+
+### Markdown
+
+i18n source is parsed as CommonMark (via Commonmarker, with table / tasklist / strikethrough / autolink extensions) and the rendered HTML is sanitized against an explicit tag allow-list. Raw HTML in the markdown source is stripped (`unsafe:` is deliberately omitted from Commonmarker options).
+
+```yaml
+- name: welcome
+  type: widget
+  widget:
+    type: markdown
+    content_key: lcp_ruby.dashboard.welcome_md  # i18n key holds Markdown
+  position: { row: 2, col: 1, width: 12, height: 1 }
+```
+
+```yaml
+# en.yml
+en:
+  lcp_ruby:
+    dashboard:
+      welcome_md: |
+        ## Welcome
+
+        Mix **KPIs**, lists, charts, and text widgets on one page.
+```
+
+Markdown is the friendlier authoring path for hand-written blurbs and the safer trust posture when translations come from an external pipeline. Mirrors the model-level `:markdown` renderer (`display/renderers/markdown.rb`) so on-page and in-table content render identically.
+
 ### List
 
 Displays a limited list of records from a model.

data/docs/guides/display-types.md

@@ -195,6 +195,12 @@ end
 
 **Appearance:** A rounded pill with a colored background and white or dark text. Values not present in `color_map` fall back to a neutral gray badge.
 
+> **`color_map` keys are raw enum keys**, e.g. `draft` / `active` /
+> `paused` — not their humanized labels (`Draft`, `Active`, …) and not
+> localized translations. The badge's display text is humanized
+> automatically from the enum's `label:` / i18n entry; `color_map`
+> operates on the raw stored value.
+
 ---
 
 ### `workflow_badge`

data/docs/guides/host-application.md

@@ -4,7 +4,7 @@ This guide walks through creating a new Rails application powered by the LCP Rub
 
 ## Prerequisites
 
-- Ruby >= 3.1
+- Ruby >= 3.2
 - Rails >= 7.1
 - The `lcp_ruby` gem (local path or published)
 

data/docs/guides/windows-setup.md

@@ -0,0 +1,211 @@
+# Windows Setup
+
+LCP Ruby runs on Windows, but a clean Windows box needs a working Ruby
+native-compilation toolchain before `gem install lcp`, `lcp skills install`,
+and `lcp run <example>` succeed. Most of the friction is **environment-level**
+(how RubyInstaller / rbenv-for-windows ship MSYS2), not LCP itself — but it
+trips up new users, so this page documents the known-good path end to end.
+
+> **Reality check.** On a clean Windows 11 box, budget ~1 hour the first time,
+> mostly toolchain troubleshooting. Once the toolchain is fixed, it stays
+> fixed — subsequent `lcp new` / `lcp run` runs are normal.
+
+This recipe was field-verified on:
+
+| | |
+|---|---|
+| OS | Windows 11 Enterprise (26200) |
+| Ruby | 3.3.5 (RubyInstaller via rbenv-for-windows) |
+| Shell | PowerShell 5.1, non-elevated |
+
+Other Ruby/RubyInstaller versions follow the same shape; exact paths and which
+MSYS2 libs you need may differ.
+
+## TL;DR — the seven steps
+
+1. **Install rbenv-for-windows + Ruby 3.3.5.**
+
+   ```powershell
+   iwr -useb https://github.com/RubyMetric/rbenv-for-windows/raw/main/tool/install.ps1 | iex
+   rbenv install 3.3.5
+   rbenv global 3.3.5
+   ```
+
+2. **Fix PATH and environment** (user-level env vars). Add to user `PATH`:
+
+   ```
+   C:\Ruby-on-Windows\msys64\ucrt64\bin
+   C:\Ruby-on-Windows\rbenv\bin
+   C:\Ruby-on-Windows\shims
+   ```
+
+   and set `RBENV_ROOT=C:\Ruby-on-Windows`. (Adjust the drive/folder to wherever
+   rbenv-for-windows installed; `RBENV_ROOT` is the root of that tree.) See
+   [gotcha C](#c-ucrt64bin-missing-from-path) for why the `ucrt64\bin` entry
+   matters.
+
+3. **Enable rbenv in your PowerShell profile** (`$PROFILE`):
+
+   ```powershell
+   & "$env:RBENV_ROOT\rbenv\bin\rbenv.ps1" init | Out-Null
+   ```
+
+4. **Patch `rbconfig.rb` so native gems compile** — append
+   `-Wno-error=incompatible-pointer-types` to `CONFIG["CFLAGS"]`. See
+   [gotcha A](#a-gcc-14-treats-incompatible-pointer-types-as-an-error).
+
+5. **Overwrite the stale bundled `libwinpthread-1.dll`** with the MSYS2 ucrt64
+   copy. See [gotcha D](#d-stale-bundled-libwinpthread-1dll-breaks-require-date).
+
+6. **Install the one MSYS2 system library LCP needs that isn't bundled** —
+   `libyaml` (required by `psych`). See [gotcha B](#b-msys2-keyring-uninitialized)
+   for the keyring workaround.
+
+   ```powershell
+   # after the SigLevel workaround in gotcha B:
+   ridk exec pacman -Sy --noconfirm
+   ridk exec pacman -S --noconfirm mingw-w64-ucrt-x86_64-libyaml
+   ```
+
+7. **Install LCP and run an example.**
+
+   ```powershell
+   gem install lcp
+   lcp skills install --global
+   lcp run showcase
+   ```
+
+## Environment gotchas (not LCP bugs)
+
+These stem from how rbenv-for-windows ships MSYS2 + GCC, not from LCP. They
+affect **every** Ruby project with native-extension gems
+(`websocket-driver`, `bcrypt`, `puma`, `psych`, `io-console`, `stringio`,
+`date`, …) — LCP just happens to depend on several of them.
+
+### A. GCC 14+ treats `incompatible-pointer-types` as an error
+
+MSYS2's GCC 14 defaults `-Wincompatible-pointer-types` to **error**, which
+breaks the native compile of many common gems on Ruby 3.3.5.
+
+A `.gemrc` `:build_args:` workaround fixes `gem install` but **does not
+propagate through Bundler** — so `bundle install` inside an example app still
+fails. The reliable fix is to relax the flag at the compiler-config level:
+
+Edit `<RBENV_ROOT>\rubies\<version>\lib\ruby\3.3.0\<arch>\rbconfig.rb` and
+append to `CONFIG["CFLAGS"]`:
+
+```
+-Wno-error=incompatible-pointer-types
+```
+
+> Patch **`CFLAGS`**, not `warnflags` — the Makefile template the gems use
+> doesn't reference `warnflags`, so a change there has no effect.
+
+### B. MSYS2 keyring uninitialized
+
+After an rbenv-for-windows install, `pacman -S` fails with
+`key "..." is unknown` / `keyring is not writable`, and the usual
+`pacman-key --init && --populate msys2` repair isn't available on the
+`ridk exec` PATH.
+
+**Workaround** — temporarily disable signature checking, install, then restore:
+
+1. Edit `<RBENV_ROOT>\msys64\etc\pacman.conf` and set:
+
+   ```ini
+   SigLevel = Never
+   LocalFileSigLevel = Never
+   ```
+
+2. Sync and install the package(s) you need:
+
+   ```powershell
+   ridk exec pacman -Sy --noconfirm
+   ridk exec pacman -S --noconfirm mingw-w64-ucrt-x86_64-libyaml
+   ```
+
+3. **Restore** the original `SigLevel` / `LocalFileSigLevel` lines in
+   `pacman.conf`.
+
+`libyaml` is the one library LCP indirectly needs (via `psych`) that MSYS2
+doesn't bundle. Other native gems may pull in other MSYS2 libs — install them
+the same way.
+
+### C. `ucrt64\bin` missing from PATH
+
+Runtime DLLs (`libgmp`, `libssl`, `libwinpthread`, `libyaml`, …) live in
+`<RBENV_ROOT>\msys64\ucrt64\bin`, but the installer doesn't add it to user
+`PATH`. Without it, even `require 'date'` fails with
+`127: procedure could not be found` once a native extension is built. Adding
+the directory in [step 2](#tldr--the-seven-steps) fixes this.
+
+### D. Stale bundled `libwinpthread-1.dll` breaks `require 'date'`
+
+The biggest gotcha. The `date` gem's native extension imports
+`clock_gettime64` from `libwinpthread-1.dll`. The copy Ruby ships in
+`<RBENV_ROOT>\rubies\<version>\bin\ruby_builtin_dlls\` is too old — it only
+exports `clock_gettime`, no `_64` variant. Worse, Ruby's `AddDllDirectory`
+loads `ruby_builtin_dlls\` **ahead** of `ucrt64\bin`, so fixing PATH
+([gotcha C](#c-ucrt64bin-missing-from-path)) alone isn't enough — the wrong
+DLL still wins.
+
+**Fix** — overwrite the bundled copy with the MSYS2 ucrt64 one:
+
+```powershell
+Copy-Item "$env:RBENV_ROOT\msys64\ucrt64\bin\libwinpthread-1.dll" `
+          "$env:RBENV_ROOT\rubies\<version>\bin\ruby_builtin_dlls\libwinpthread-1.dll" -Force
+```
+
+> This is an upstream packaging mismatch (RubyInstaller ships an older
+> `libwinpthread` than the MSYS2 it bundles); the overwrite is a local
+> workaround until the toolchain ships a matched pair.
+
+## LCP-specific notes on Windows
+
+The toolchain gotchas above aside, two Windows concerns are handled by LCP
+itself:
+
+- **Timezone data is bundled.** Windows has no system `zoneinfo` database, so
+  TZInfo needs the pure-Ruby fallback or Rails boot fails with
+  `TZInfo::DataSources::ZoneinfoDirectoryNotFound`. The bundled example apps
+  (`crm`, `hr`, `showcase`, `todo`) include
+  `gem "tzinfo-data", platforms: %i[ windows jruby ]`, and apps generated by
+  `lcp new` get it from the Rails 8 generator automatically. No action needed.
+
+- **The asset pipeline is wired automatically.** On a Rails 8 (Propshaft-only)
+  host, LCP's Sprockets-based JS bundle won't load without a compatibility
+  shim. Both `lcp new` and `rails generate lcp_ruby:install` add
+  `gem "sprockets-rails"` and create `app/assets/config/manifest.js` by default,
+  and the engine fails loudly at boot if the shim is missing — see the
+  [Asset Pipeline reference](../reference/asset-pipeline.md). No Windows-specific
+  action needed.
+
+- **The first-request `Errno::EACCES` is handled.** Sprockets' asset-cache
+  write uses a non-atomic `File.rename` that races with Windows file locking,
+  and LCP's 12+ precompile entries all hit that cache in parallel on the first
+  request — so a fresh `rails server` used to crash its very first page with
+  `Permission denied @ rb_file_s_rename` (reload always worked). LCP now swaps
+  the file-backed assets cache for a `null_store` on Windows in
+  **non-production** (development and test both live-compile assets and race the
+  same way; production precompiles at deploy, and Unix is untouched), removing
+  the rename race. No action needed; if you ever want the cache back, re-set
+  `env.cache` in your own `config.assets.configure` block.
+
+## Re-running an example
+
+`lcp run <name>` is idempotent: the first run materializes the bundled example
+into a fresh directory and boots it (`bundle install` → `db:setup` → server);
+running the same command again detects the already-materialized directory (via
+the `.lcp-run` marker it dropped after the first successful setup) and just
+re-boots it — `bundle install` → `db:prepare` → server — so your data from the
+previous session survives. (If you dropped the database in the meantime, the
+re-run falls back to `db:setup` and re-seeds.) No flag, no second command:
+
+```powershell
+lcp run showcase   # first time: materialize + boot
+lcp run showcase   # again: re-boot the same app, data preserved
+```
+
+Pointing `lcp run` at a non-empty directory that LCP did **not** create (no
+`.lcp-run` marker) still aborts with `already exists and is not empty`, so it
+never clobbers your own files. In that case pass a different `DIR`.

data/docs/guides/workflow.md

@@ -518,7 +518,7 @@ LcpRuby.configure do |config|
 end
 ```
 
-Create the model with required fields (name, model_name, field_name, states, transitions, version, active). The `states` and `transitions` fields should be JSON columns containing the same structure as the YAML.
+Create the model with required fields (name, target_model, field_name, states, transitions, version, active). The `states` and `transitions` fields should be JSON columns containing the same structure as the YAML.
 
 Static (YAML/DSL) workflows are always loaded if files exist. DB workflows are additive. On name conflicts, static wins.
 

data/docs/reference/asset-pipeline.md

@@ -0,0 +1,79 @@
+# Asset pipeline
+
+LCP Ruby ships its UI as ~50 JavaScript files (45 Stimulus controllers plus helpers, vendored Stimulus 3.2 UMD bundle, and a few utility scripts) and a single 1900-line CSS file. The JS is glued together by Sprockets `//= require` directives in `app/assets/javascripts/lcp_ruby/application.js`.
+
+## Why a Sprockets compatibility shim is required
+
+Rails 8 ships **Propshaft** as the default asset pipeline. Propshaft is intentionally simple — it serves static assets and does not understand Sprockets' `//= require` directive syntax. Without `sprockets-rails`, two failure modes both produce a silently-broken UI:
+
+| Failure mode | Cause | Symptom in browser |
+|---|---|---|
+| **A — no sprockets-rails at all** | The `<script>` tag renders (the old `respond_to?(:assets)` gate is true on Propshaft too, so it never actually suppressed it), but Propshaft has no compiled bundle to serve at that logical path | `<script>` tag present, request for LCP JS 404s; Stimulus never loads; top nav stays hidden behind the FOUC mask |
+| **B — sprockets-rails present, manifest.js missing** | Propshaft serves `application.js` as the raw 58-line manifest with `//= require` comments instead of the 11000-line compiled bundle | `<script>` tag present, file fetched 200 OK, body is comments only, no Stimulus loads, top nav stays hidden |
+
+Both modes ship no console errors and no server-side warnings. Audit #16 cost ~hours of debugging before identifying the cause — these are the worst kind of failures.
+
+## The fix (Phase 1, current)
+
+`lcp new` and `rails generate lcp_ruby:install` both:
+
+1. Add `gem "sprockets-rails"` to the host's `Gemfile` (idempotent — re-runs don't duplicate)
+2. Create `app/assets/config/manifest.js` with the load-bearing link directives:
+
+   ```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
+   ```
+
+   If the file already exists (e.g. host added their own `Chart.bundle.js` link), only the missing LCP lines are appended — host entries are preserved.
+
+The engine adds a **boot-time check** (`lcp_ruby.asset_pipeline_check` initializer → `LcpRuby::Engine.check_asset_pipeline_compat!`) that raises `LcpRuby::AssetPipelineError` if Propshaft is loaded without sprockets-rails. The check skips:
+
+- during `rails generate lcp_ruby:install` (chicken-and-egg — the generator is what adds the shim)
+- when `LcpRuby.configuration.skip_asset_pipeline_check = true` (explicit opt-out)
+
+So the silent failure mode is impossible — you either get the working UI or a loud actionable error.
+
+## Opting out (advanced)
+
+If you've wired your own ESM bundler (esbuild, importmap-rails with custom pins, etc.) and serve the engine's JS your own way:
+
+```bash
+# Skip the shim during install
+lcp new my_app --skip-asset-pipeline
+# or for an existing app:
+rails generate lcp_ruby:install --skip-asset-pipeline
+```
+
+Silence the boot check:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.skip_asset_pipeline_check = true
+end
+```
+
+You take responsibility for compiling and serving the engine's JS bundle yourself. The 50 controllers register as `window.StimulusApp.register("lcp-foo", class extends Stimulus.Controller {...})` globals; your bundler needs to load them in the right order (Stimulus core first, then `stimulus_bootstrap.js`, then controllers — see `app/assets/javascripts/lcp_ruby/application.js` for the canonical order).
+
+## Phase 2 — ESM-native roadmap (not yet built)
+
+The current architecture predates Rails 8's pivot to Propshaft. Long-term the engine should ship a pre-bundled ESM artifact that works on Propshaft natively, without the Sprockets shim. Sketch of the plan:
+
+1. Convert all 45 Stimulus controllers from `window.StimulusApp.register(...)` globals to ESM `export default class Foo extends Controller {}`
+2. Add a `package.json` + esbuild build step to the engine repo
+3. Commit the pre-bundled output (or distribute via `gemspec.files` so `bundle install` lays it down)
+4. Layout dual-mode: if the pre-bundled file exists, use it; else fall back to the Sprockets path
+
+This is a substantial change (~2000 LOC) with breaking-change implications for hosts that have custom Stimulus controllers reading from `window.StimulusApp`. It is intentionally **not** in scope for the current fix — Phase 1 unblocks every new user today without forcing the bigger migration.
+
+## Files
+
+- `lib/lcp_ruby/engine.rb` — `check_asset_pipeline_compat!` class method + `lcp_ruby.asset_pipeline_check` initializer
+- `lib/generators/lcp_ruby/install_generator.rb` — `install_asset_pipeline_compat` step + `add_sprockets_rails_to_gemfile!` / `ensure_sprockets_manifest!` helpers
+- `lib/lcp_ruby/app_template.rb` — top-level `gem "sprockets-rails"` so `lcp new` bundles it before the install generator boots Rails
+- `lib/lcp_ruby/configuration.rb` — `skip_asset_pipeline_check` reader/writer (default false)
+- `app/views/layouts/lcp_ruby/application.html.erb` (and `auth.html.erb`) — engine asset includes are gated on the `lcp_emit_engine_assets?` helper (= `!skip_asset_pipeline_check`). The old `respond_to?(:assets)` gate was removed; the new gate suppresses the pipeline-dependent tags only when the host opted out (own bundler), so it doesn't 500 on Propshaft
+- `script/smoke_e2e.sh` — CI smoke test that probes `/assets/lcp_ruby/application.js` and verifies it's the compiled bundle, not the manifest stub

data/docs/reference/pages.md

@@ -172,7 +172,7 @@ Displays an aggregate value (count, sum, avg, min, max) over a model's records,
 
 ### text
 
-Displays translated static content.
+Displays translated static content as plain (HTML-escaped) text.
 
 | Attribute | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -188,6 +188,55 @@ Displays translated static content.
   position: { row: 2, col: 1, width: 12, height: 1 }
 ```
 
+For formatted content use the `rich_text` or `markdown` widget instead — both share the same `content_key:` API and differ only in how the resolved string is rendered.
+
+### rich_text
+
+Same `content_key:` lookup as `text`, but the resolved string is emitted via `raw` — so the translation can carry `<h2>`, `<a>`, `<strong>`, etc., and they render as tags. Trust model: locale files are author-controlled, the same level as any engine view that uses `raw`. When translations might originate outside code review (external translator pipeline), prefer `markdown` — its sanitize step makes the trust boundary explicit.
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | yes | Must be `rich_text`. |
+| `content_key` | string | yes | i18n key whose value is HTML. |
+
+```yaml
+- name: announcement
+  type: widget
+  widget:
+    type: rich_text
+    content_key: lcp_ruby.dashboard.announcement_html
+  position: { row: 2, col: 1, width: 12, height: 1 }
+```
+
+### markdown
+
+i18n source is parsed by [Commonmarker](https://github.com/gjtorikian/commonmarker) (CommonMark + GFM tables, tasklists, strikethrough, autolinks) and the rendered HTML is sanitized against the same tag/attribute allow-list as the model-level `:markdown` renderer. `unsafe:` is **deliberately omitted** from the Commonmarker options, so raw HTML embedded in the source is stripped at parse time.
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | yes | Must be `markdown`. |
+| `content_key` | string | yes | i18n key whose value is Markdown source. |
+
+```yaml
+- name: welcome
+  type: widget
+  widget:
+    type: markdown
+    content_key: lcp_ruby.dashboard.welcome_md
+  position: { row: 2, col: 1, width: 12, height: 1 }
+```
+
+```yaml
+# en.yml
+en:
+  lcp_ruby:
+    dashboard:
+      welcome_md: |
+        ## Welcome
+
+        Mix **KPIs**, lists, charts, and *text-style* widgets on one page.
+```
+
 ### list
 
 Displays recent records from a model.

data/docs/reference/presenters.md

@@ -1242,6 +1242,12 @@ Renders the value as a colored badge. Useful for enum and status fields.
 
 Available colors: `green`, `red`, `blue`, `yellow`, `orange`, `purple`, `gray`, `teal`, `cyan`, `pink`.
 
+**`color_map` keys are raw enum keys, not humanized labels.** For an enum
+field with values `active`, `pending`, `suspended`, write
+`active: green` — not `Active: green` and not the localized label. The
+displayed text comes from the enum's `label:` / i18n translation
+automatically; `color_map` operates on the underlying stored value.
+
 ```yaml
 - field: status
   renderer: badge

data/docs/reference/workflow.md

@@ -538,7 +538,7 @@ LcpRuby.configure do |config|
   # DB model source
   config.workflow_model = "workflow_definition"
   config.workflow_model_fields = {
-    name: "name", model_name: "model_name", field_name: "field_name",
+    name: "name", target_model: "target_model", field_name: "field_name",
     states: "states", transitions: "transitions",
     version: "version", active: "active", audit_log: "audit_log"
   }
@@ -575,7 +575,7 @@ The DB model must have these fields:
 | Logical Name | Type | Description |
 |---|---|---|
 | `name` | string | Unique workflow name |
-| `model_name` | string | Target model name |
+| `target_model` | string | Target model name |
 | `field_name` | string | Enum field name |
 | `states` | json | States hash |
 | `transitions` | json | Transitions hash |

data/examples/crm/Gemfile

@@ -4,6 +4,9 @@ gem "rails", "~> 7.1"
 gem "sqlite3", "~> 1.4"
 gem "puma", "~> 6.0"
 gem "sprockets-rails"
+
+# Windows has no system zoneinfo database; bundle the pure-Ruby fallback.
+gem "tzinfo-data", platforms: %i[ windows jruby ]
 gem "image_processing", "~> 1.2"
 gem "chartkick"
 gem "lcp", path: "../.."