lcp 0.1.0

data/docs/getting-started.md

@@ -0,0 +1,1187 @@
+# Getting Started
+
+This guide walks you through building a two-model TODO application with LCP Ruby — from installation to custom actions and event handlers. By the end, you'll have task lists and tasks with associations, search filters, a custom action, and an event handler.
+
+All examples use the **Ruby DSL** as the primary format. YAML equivalents are provided in collapsible blocks.
+
+## Prerequisites
+
+| Requirement | Version |
+|-------------|---------|
+| Ruby | >= 3.1 |
+| 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.
+
+## Quick Start with `lcp new`
+
+The fastest way to create a new LCP Ruby application:
+
+```bash
+lcp new my_app
+```
+
+This launches an interactive wizard that asks about:
+- **Database** — sqlite3, postgresql, or mysql2
+- **Metadata format** — Ruby DSL (default) or YAML
+- **Feature preset** — minimal, standard, full, or custom (choose individual features)
+
+Feature presets:
+| Preset | Includes |
+|--------|----------|
+| **minimal** | Core platform only (sample model + presenter + permissions) |
+| **standard** | Core + authentication + auditing + saved filters + export + import |
+| **full** | All 17 feature generators |
+| **custom** | Interactive selection of individual features |
+
+After the wizard, `lcp new` runs `rails new` with the right configuration, installs LCP Ruby, runs selected feature generators, and prepares the database. Then:
+
+```bash
+cd my_app
+rails s
+```
+
+Visit `http://localhost:3000/items` to see the sample application.
+
+To skip the interactive wizard and use defaults (sqlite3, DSL, minimal):
+
+```bash
+lcp new my_app --skip-interactive
+```
+
+CLI options: `--database=postgresql`, `--format=yaml`, `--preset=standard`, `--timezone=Europe/Prague`, `--locale=cs` (single-locale) or `--locale=cs,en,de` (multi-locale — first listed is `default_locale`), `--menu-layout=both|top|sidebar`, `--skip-action-text` (omits Trix WYSIWYG; `:rich_text` fields will render as plain textareas).
+
+For locale-specific guidance — engine UI translation, fallbacks, `available_locales` ↔ `Accept-Language` interaction, migration from pre-v1 generators — see [guides/adding-locale.md](guides/adding-locale.md).
+
+If `lcp new` reports that some feature generators failed (e.g. the
+preset asked for a feature whose prerequisites couldn't be installed),
+the command exits non-zero. Use `--allow-partial` to override and
+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.
+
+### Installing from a local checkout
+
+If `lcp_ruby` is not yet on RubyGems (pre-release, internal fork), point the generator at a local gem path:
+
+```bash
+lcp new my_app --gem-source=path:/abs/path/to/lcp-ruby
+```
+
+When you run `lcp` directly from a local clone (`bundle exec exe/lcp …`), the CLI auto-detects the checkout and uses `path:` automatically — you don't need the flag. The flag is only required when the binary is installed elsewhere (gem index, `gem install`, copied binary). The default when no checkout is detected is `rubygems`, which fails until the gem is published.
+
+## Manual Installation (existing Rails app)
+
+If you have an existing Rails application, use the install generator instead:
+
+```bash
+# Add to Gemfile
+gem "lcp"
+
+# Install
+bundle install
+rails generate lcp_ruby:install
+```
+
+The generator sets up everything: `require "lcp_ruby"` in `application.rb`, engine mount in routes, directory structure, sample model, initializer, and a `current_user` stub.
+
+### Scaffolding new entities
+
+```bash
+# Minimal scaffold — model + presenter + permissions + view group, top-level menu entry
+rails generate lcp_ruby:entity Customer name:string! email:email!:uniq phone:phone \
+  --label-method=name --menu=ROOT --menu-icon=users
+
+# Richer entity (v2/v3 grammar) — DB constraints, sections, renderers, link, search, color_map
+rails generate lcp_ruby:entity Order \
+  'number:string!:uniq' \
+  'customer:belongs_to{required}' \
+  'status:enum{draft|confirmed|shipped|delivered}!{default:draft}{color_map}' \
+  'total:decimal!{renderer:currency}' \
+  --label-method=number \
+  --display-template='Order {number}' \
+  --searchable-fields=number \
+  --menu=Sales        # auto-creates "Sales" dropdown if it doesn't yet exist
+```
+
+`lcp_ruby:entity` creates `models/<name>.rb`, `presenters/<plural>.rb`, `permissions/<name>.yml`, `views/<name>.yml` atomically and (when `--menu=...` is passed) inserts the matching `- view_group: <name>` line into `config/lcp_ruby/menu.yml` above the seeded `# lcp:menu <section>` marker. Field grammar covers all built-in types, inline enum values (`enum{a|b|c}`), DB modifiers (`!`, `:uniq`, `:index`, `{default:X}`), associations (`belongs_to`, `has_many`), and v3 presenter modifiers (`{section:NAME}`, `{renderer:NAME}`, `{color_map}`, `{link}`, `{polymorphic}`, `:hidden`, `:search`). Feature flags: `--soft-delete`, `--auditing`, `--custom-fields`, `--positioning`, `--tree`, `--form-layout=tabs`, `--index-fields=a,b,c`, `--menu=[<section>:]ROOT|<Label>[:bottom|:right]`, `--menu-icon=<lucide>`. **Bash users:** single-quote any field token whose braces contain a comma — bash brace-expands `{a,b}` patterns. See [the design spec](design/entity_generator.md) for full grammar and worked examples; the `--menu=...` placement grammar is documented in [`guides/menu.md`](guides/menu.md#adding-entities-to-the-menu).
+
+### Adding features
+
+Run any of the feature generators after install:
+
+```bash
+rails generate lcp_ruby:install_auth      # Devise authentication
+rails generate lcp_ruby:api_tokens        # Personal Access Tokens (bearer auth)
+rails generate lcp_ruby:auditing          # Audit trail
+rails generate lcp_ruby:export            # Data export
+rails generate lcp_ruby:import            # Data import
+rails generate lcp_ruby:custom_fields     # Runtime field definitions
+rails generate lcp_ruby:saved_filters     # Saved search filters
+rails generate lcp_ruby:monitoring        # Error dashboard
+rails generate lcp_ruby:batch_operations  # Bulk operations
+rails generate lcp_ruby:background_jobs   # Job tracking
+rails generate lcp_ruby:pages             # DB-backed pages
+rails generate lcp_ruby:groups            # User groups
+rails generate lcp_ruby:role_model        # DB-backed roles
+rails generate lcp_ruby:permission_source # Dynamic permissions
+rails generate lcp_ruby:workflow_definition   # Workflows
+rails generate lcp_ruby:workflow_approvals    # Approval processes
+rails generate lcp_ruby:workflow_audit_log    # Workflow audit
+rails generate lcp_ruby:gapfree_sequences     # Sequential numbering
+rails generate lcp_ruby:entity            # Scaffold a new entity (see "Scaffolding new entities" above)
+```
+
+All generators support `--format=dsl` (default) or `--format=yaml`.
+
+Each generator declares its prerequisites (e.g. `lcp_ruby:import`
+requires `lcp_ruby:background_jobs` for the FK target; `lcp_ruby:api_tokens`
+requires `lcp_ruby:install_auth` for the user model). If a prereq is
+missing, the generator aborts up-front with a structured
+`Missing prerequisite feature(s): …` message naming what to run first.
+Run `bundle exec rake lcp_ruby:doctor` to see the full feature
+dependency graph.
+
+## Claude Code 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.
+
+**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.
+
+**Manual install / refresh after gem upgrade:**
+
+```bash
+rails generate lcp_ruby:claude_skills
+```
+
+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.
+
+**Verify**: list installed skills via `/skills` inside Claude Code, or `ls .claude/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 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.
+
+## Installation (step-by-step)
+
+For full control over the setup, or if the generator doesn't suit your project structure, follow these manual steps.
+
+Add LCP Ruby to your Gemfile:
+
+```ruby
+gem "lcp"
+```
+
+### Asset Pipeline (Sprockets)
+
+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:
+
+```ruby
+gem "sprockets-rails"
+```
+
+Then create `app/assets/config/manifest.js` to link the engine assets:
+
+```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
+```
+
+> **Note:** If your host app already uses Sprockets, skip this step — the engine assets are picked up automatically.
+
+Run `bundle install`.
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount LcpRuby::Engine => "/"
+end
+```
+
+> **Tip:** If you want `http://localhost:3000/` to redirect to your first model's index, add a root route pointing to the engine's slug (e.g., `root to: redirect("/task_lists")`).
+
+## Configuration
+
+Create an initializer at `config/initializers/lcp_ruby.rb`:
+
+```ruby
+LcpRuby.configure do |config|
+  config.authentication = :none
+end
+```
+
+This is the minimal configuration for a quickstart. All other options have sensible defaults.
+
+### Authentication Modes
+
+| Mode | Use Case | `current_user` |
+|------|----------|----------------|
+| `:none` | Quickstart / prototyping | Not required |
+| `:external` | Existing app with its own auth (Devise, etc.) | Provided by host app |
+| `:built_in` | Standalone app without existing auth | Managed by LCP Ruby |
+
+The default is `:external`. This tutorial uses `:none` so you can skip authentication setup entirely. See [Authentication Setup](#authentication-setup) below when you're ready to add auth.
+
+See [Engine Configuration](reference/engine-configuration.md) for all available options.
+
+## Directory Structure
+
+Create the metadata directories:
+
+```
+config/lcp_ruby/
+  types/          # Custom business type definitions (optional)
+  models/         # Model definitions — .rb (DSL) or .yml (YAML)
+  presenters/     # UI definitions — .rb (DSL) or .yml (YAML)
+  permissions/    # Role-based access control — .yml only
+  views/          # View group definitions (optional — auto-created for single-presenter models)
+```
+
+Both `.rb` (DSL) and `.yml` (YAML) files are supported for models and presenters. Each model/presenter name must be unique across all files — defining the same name in both formats raises `MetadataError`.
+
+> **Note:** Permissions are YAML-only. There is no DSL loader for permission files.
+
+Metadata auto-loads on Rails boot via the `lcp_ruby.load_metadata` initializer.
+
+> **Note:** If you plan to use host app extensions (computed services, custom actions, event handlers, condition services), you must exclude their directories from Zeitwerk autoloading. See [Extensibility Guide — Auto-Discovery Setup](guides/extensibility.md#auto-discovery-setup) for details.
+
+## Authentication Setup
+
+> **Skip this section** if you're using `authentication: :none` (as in this tutorial).
+
+When using `authentication: :external`, your host app must provide a `current_user` object. The user model must implement the method configured by `role_method` (default: `lcp_role`), returning an **array of role name strings**:
+
+```ruby
+class User < ApplicationRecord
+  def lcp_role
+    roles.pluck(:name)  # => ["admin", "sales_rep"]
+  end
+end
+```
+
+Your `ApplicationController` must provide `current_user` (typically via Devise, Sorcery, or a custom session-based auth):
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :authenticate_user!
+
+  def current_user
+    @current_user ||= User.find_by(id: session[:user_id])
+  end
+  helper_method :current_user
+end
+```
+
+The role strings must match the role names defined in your [permissions YAML](reference/permissions.md).
+
+### Built-in Authentication
+
+When using `authentication: :built_in`, LCP Ruby manages users internally via `LcpRuby::User`. Run the generator to set up the auth tables and routes:
+
+```bash
+rails g lcp_ruby:install_auth
+```
+
+This adds Devise-based authentication with login/logout/password reset. The generator's post-install message lists the actual URLs.
+
+**Devise routes.** The engine mounts Devise under `path: "auth"` with custom path names — these are the URLs Devise users see, **not** the conventional `/users/sign_in`:
+
+| Path | What |
+|---|---|
+| `GET /auth/login` | Sign-in form |
+| `DELETE /auth/logout` (also `GET /auth/logout`) | Sign-out |
+| `GET /auth/register` | Sign-up (if Devise registrations are enabled) |
+| `GET /auth/password/new` | Password reset |
+
+When the engine is mounted at a non-root path (e.g. `mount LcpRuby::Engine => "/admin"`), prefix accordingly: `/admin/auth/login`.
+
+To create initial users, add them in `db/seeds.rb`:
+
+```ruby
+LcpRuby::User.find_or_create_by!(email: "admin@example.com") do |u|
+  u.name = "Admin User"
+  u.password = "password123"
+  u.lcp_role = ["admin"]
+  u.active = true
+end
+```
+
+Key attributes:
+- **`email`** (string, required) — login identifier
+- **`name`** (string) — display name
+- **`password`** (string) — minimum 6 characters; `password_confirmation` is optional in seeds
+- **`lcp_role`** (JSON array of strings) — role names matching your permissions YAML, e.g. `["admin"]`, `["viewer", "editor"]`
+- **`active`** (boolean) — must be `true` for the user to log in; inactive users are rejected at sign-in
+- **`profile_data`** (JSON hash, default `{}`) — extensible storage for custom per-user data (preferences, settings, app-specific fields). Access via `user.profile` which returns a hash with indifferent access
+
+#### Storing custom data in `profile_data`
+
+The `profile_data` JSON column is the recommended way to store per-user preferences or application-specific data without creating a separate model:
+
+```ruby
+# Writing
+user.update!(profile_data: { "locale" => "cs", "timezone" => "Europe/Prague", "theme" => "dark" })
+
+# Reading (returns HashWithIndifferentAccess)
+user.profile[:locale]    # => "cs"
+user.profile["timezone"] # => "Europe/Prague"
+
+# Merging new keys without overwriting existing ones
+user.update!(profile_data: user.profile.merge("items_per_page" => 50))
+```
+
+For external auth (`:external`), add a `profile_data` JSON column to your own user model if you want the same pattern, or implement custom accessors.
+
+The platform itself reads a small set of well-known keys from `profile_data` on every authenticated request (`theme`, `density`, `border_radius`, `locale`). Any writer — a presenter bound to the user model, the `PreferencesController`, a console `update!` — takes effect on the next render. See the [platform-read keys table](reference/engine-configuration.md#keys-the-platform-reads-from-profile_data) in the engine configuration reference, and the showcase `my_settings` presenter for a reference implementation built on `service: json_field` virtual fields.
+
+Then run `rails db:seed` to create the users.
+
+> **Note:** The `config.authentication = :built_in` line must appear in `config/initializers/lcp_ruby.rb`. If the generator inserts a duplicate line, remove the old one manually.
+
+### OIDC Single Sign-On
+
+For Microsoft Entra ID, Google Workspace, Okta, Keycloak, or any OIDC-compliant
+identity provider:
+
+```bash
+rails g lcp_ruby:install_auth --mode=oidc --provider=entra --with-built-in
+```
+
+This scaffolds `config/lcp_ruby/auth.yml` from a per-provider template
+(available: `entra`, `google`, `okta`, `keycloak`, `generic`), adds the
+required DB columns, and writes the host config (`host_url`, `mount_path`)
+into the initializer. `--with-built-in` keeps a Devise password form on the
+login page as a break-glass fallback.
+
+See [OIDC Setup](guides/oidc-setup.md) for the full walkthrough — IdP App
+registration, ENV variable options, role mapping, and troubleshooting — and
+[OIDC Reference](reference/oidc.md) for the complete `auth.yml` schema.
+
+## Your First Model: Task List
+
+Create `config/lcp_ruby/models/task_list.rb`:
+
+```ruby
+define_model :task_list do
+  label "Task List"
+  label_plural "Task Lists"
+
+  field :title, :string, label: "Title" do
+    validates :presence
+    validates :length, minimum: 3, maximum: 255
+  end
+
+  field :description, :text, label: "Description"
+
+  timestamps true
+  label_method :title
+end
+```
+
+This creates a `task_lists` database table with `title` and `description` columns, plus `created_at`/`updated_at` timestamps.
+
+Key concepts:
+- **`field`** — defines a database column with a name and type
+- **`validates`** — adds ActiveRecord validations (inside a field block, the field context is implicit)
+- **`timestamps`** — adds `created_at` and `updated_at` columns
+- **`label_method`** — the method called on records to generate display text (e.g., in association select dropdowns)
+
+<details>
+<summary>YAML equivalent</summary>
+
+```yaml
+# config/lcp_ruby/models/task_list.yml
+model:
+  name: task_list
+  label: "Task List"
+  label_plural: "Task Lists"
+
+  fields:
+    - name: title
+      type: string
+      label: "Title"
+      validations:
+        - type: presence
+        - type: length
+          options: { minimum: 3, maximum: 255 }
+
+    - name: description
+      type: text
+      label: "Description"
+
+  options:
+    timestamps: true
+    label_method: title
+```
+</details>
+
+See [Models Reference](reference/models.md) for all field types, validations, associations, and more. See [Model DSL Reference](reference/model-dsl.md) for the full DSL syntax.
+
+## Your First Presenter: Task List
+
+Create `config/lcp_ruby/presenters/task_list.rb`:
+
+```ruby
+define_presenter :task_list do
+  model :task_list
+  label "Task Lists"
+  slug "task_lists"
+  icon "list"
+
+  index do
+    default_sort :created_at, :desc
+    per_page 25
+    empty_message "No task lists yet. Create your first list to get started."
+    column :title, link_to: :show, sortable: true
+    column :description
+  end
+
+  show do
+    section "List Details" do
+      field :title, renderer: :heading
+      field :description
+    end
+  end
+
+  form do
+    section "List Details" do
+      field :title, placeholder: "My shopping list...", autofocus: true
+      field :description, input_type: :textarea, placeholder: "Optional description..."
+    end
+  end
+
+  search do
+    searchable_fields :title, :description
+    placeholder "Search lists..."
+  end
+
+  action :create, type: :built_in, on: :collection, label: "New List", icon: "plus"
+  action :show,   type: :built_in, on: :single, icon: "eye"
+  action :edit,   type: :built_in, on: :single, icon: "pencil"
+  action :destroy, type: :built_in, on: :single, icon: "trash", confirm: true, style: :danger
+end
+```
+
+Key concepts:
+- **`index`** — configures the list/table view (columns, sorting, pagination, empty state)
+- **`show`** — configures the detail view with sections and renderers
+- **`form`** — configures create/edit forms with input types and placeholders
+- **`search`** — enables text search across specified fields
+- **`action`** — defines UI buttons (built-in CRUD or custom business logic)
+
+<details>
+<summary>YAML equivalent</summary>
+
+```yaml
+# config/lcp_ruby/presenters/task_list.yml
+presenter:
+  name: task_list
+  model: task_list
+  label: "Task Lists"
+  slug: task_lists
+  icon: list
+
+  index:
+    default_sort: { field: created_at, direction: desc }
+    per_page: 25
+    empty_message: "No task lists yet. Create your first list to get started."
+    table_columns:
+      - { field: title, link_to: show, sortable: true }
+      - { field: description }
+
+  show:
+    layout:
+      - section: "List Details"
+        fields:
+          - { field: title, renderer: heading }
+          - { field: description }
+
+  form:
+    sections:
+      - title: "List Details"
+        fields:
+          - { field: title, placeholder: "My shopping list...", autofocus: true }
+          - { field: description, input_type: textarea, placeholder: "Optional description..." }
+
+  search:
+    enabled: true
+    searchable_fields: [title, description]
+    placeholder: "Search lists..."
+
+  actions:
+    collection:
+      - { name: create, type: built_in, label: "New List", icon: plus }
+    single:
+      - { name: show, type: built_in, icon: eye }
+      - { name: edit, type: built_in, icon: pencil }
+      - { name: destroy, type: built_in, icon: trash, confirm: true, style: danger }
+```
+</details>
+
+See [Presenters Reference](reference/presenters.md) for all options. See [Presenter DSL Reference](reference/presenter-dsl.md) for the full DSL syntax.
+
+## Your First Permissions: Task List
+
+Create `config/lcp_ruby/permissions/task_list.yml`:
+
+```yaml
+permissions:
+  model: task_list
+
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      fields: { readable: all, writable: all }
+      actions: all
+      scope: all
+      presenters: all
+
+    viewer:
+      crud: [index, show]
+      fields: { readable: all, writable: [] }
+      actions: { allowed: [] }
+      scope: all
+      presenters: all
+
+  default_role: admin
+```
+
+Key concepts:
+- **`roles`** — each key is a role name matched against `current_user.lcp_role`
+- **`crud`** — which operations the role can perform (`index`, `show`, `create`, `update`, `destroy`)
+- **`fields`** — which fields the role can read and write (`all` or an explicit list)
+- **`default_role`** — assigned when the user has no matching role (set to `admin` here since we're using `authentication: :none`)
+
+> **Warning:** We use `default_role: admin` only because this tutorial runs without authentication. When you switch to `authentication: :external` or `:built_in`, change `default_role` to a restrictive role like `viewer` so unauthenticated or unknown users don't get full access.
+
+> **Tip:** You can create `config/lcp_ruby/permissions/_default.yml` with `model: _default` to provide fallback permissions for all models that don't have their own permission file.
+
+See [Permissions Reference](reference/permissions.md) for field overrides, record rules, and scope types.
+
+## Run and Verify
+
+```bash
+bundle exec rails db:prepare
+bundle exec rails server
+```
+
+Visit `http://localhost:3000/task_lists`. You should see:
+
+1. **Empty state** — the message "No task lists yet. Create your first list to get started."
+2. **"New List" button** — click it to open the create form
+3. **Form** — `title` field with placeholder text and autofocus, `description` textarea
+4. **After saving** — redirects to the show page with your list details
+5. **Navigation menu** — "Task Lists" link in the top navigation
+
+Try creating a list, editing it, and searching for it by title.
+
+## Second Model with Association: Task
+
+Now add a `task` model that belongs to a task list.
+
+### Update the Task List Model
+
+First, update `config/lcp_ruby/models/task_list.rb` to add a `has_many` association:
+
+```ruby
+define_model :task_list do
+  label "Task List"
+  label_plural "Task Lists"
+
+  field :title, :string, label: "Title" do
+    validates :presence
+    validates :length, minimum: 3, maximum: 255
+  end
+
+  field :description, :text, label: "Description"
+
+  has_many :tasks, model: :task, dependent: :destroy
+
+  timestamps true
+  label_method :title
+end
+```
+
+### Update the Task List Presenter
+
+Now that task_list has tasks, update the show section in `config/lcp_ruby/presenters/task_list.rb` to display them:
+
+```ruby
+show do
+  section "List Details" do
+    field :title, renderer: :heading
+    field :description
+  end
+
+  association_list "Tasks", association: :tasks
+end
+```
+
+The `association_list` renders a list of associated records below the detail section. This is auto-detected for eager loading — no manual `includes` needed.
+
+<details>
+<summary>YAML equivalent — updated show section</summary>
+
+```yaml
+show:
+  layout:
+    - section: "List Details"
+      fields:
+        - { field: title, renderer: heading }
+        - { field: description }
+    - section: "Tasks"
+      type: association_list
+      association: tasks
+```
+</details>
+
+### Create the Task Model
+
+Create `config/lcp_ruby/models/task.rb`:
+
+```ruby
+define_model :task do
+  label "Task"
+  label_plural "Tasks"
+
+  field :title, :string, label: "Title" do
+    validates :presence
+  end
+
+  field :status, :enum, label: "Status", default: "pending",
+    values: { pending: "Pending", in_progress: "In Progress", completed: "Completed" }
+
+  field :due_date, :date, label: "Due Date"
+
+  field :notes, :text, label: "Notes"
+
+  belongs_to :task_list, model: :task_list, required: true
+
+  scope :active,    where_not: { status: "completed" }
+  scope :completed, where: { status: "completed" }
+
+  on_field_change :on_status_change, field: :status
+
+  timestamps true
+  label_method :title
+end
+```
+
+Key concepts:
+- **`belongs_to`** — creates a foreign key (`task_list_id`) linking each task to a task list
+- **`has_many`** — on the parent model, declares the inverse relationship (with `dependent: :destroy` to cascade deletes)
+- **`:enum`** with **`values:`** — a string field constrained to a set of labeled values, rendered as a `<select>` by default
+- **`scope`** — named query filters (used by presenter filter tabs)
+- **`on_field_change`** — declares a field change event that triggers when `status` changes (handler created [later](#adding-an-event-handler))
+
+<details>
+<summary>YAML equivalent — task_list.yml (updated)</summary>
+
+```yaml
+# config/lcp_ruby/models/task_list.yml
+model:
+  name: task_list
+  label: "Task List"
+  label_plural: "Task Lists"
+
+  fields:
+    - name: title
+      type: string
+      label: "Title"
+      validations:
+        - type: presence
+        - type: length
+          options: { minimum: 3, maximum: 255 }
+
+    - name: description
+      type: text
+      label: "Description"
+
+  associations:
+    - type: has_many
+      name: tasks
+      target_model: task
+      dependent: destroy
+
+  options:
+    timestamps: true
+    label_method: title
+```
+</details>
+
+<details>
+<summary>YAML equivalent — task.yml</summary>
+
+```yaml
+# config/lcp_ruby/models/task.yml
+model:
+  name: task
+  label: "Task"
+  label_plural: "Tasks"
+
+  fields:
+    - name: title
+      type: string
+      label: "Title"
+      validations:
+        - type: presence
+
+    - name: status
+      type: enum
+      label: "Status"
+      default: "pending"
+      enum_values:
+        - { value: pending, label: "Pending" }
+        - { value: in_progress, label: "In Progress" }
+        - { value: completed, label: "Completed" }
+
+    - name: due_date
+      type: date
+      label: "Due Date"
+
+    - name: notes
+      type: text
+      label: "Notes"
+
+  associations:
+    - type: belongs_to
+      name: task_list
+      target_model: task_list
+      required: true
+
+  scopes:
+    - name: active
+      where_not: { status: "completed" }
+    - name: completed
+      where: { status: "completed" }
+
+  events:
+    - name: on_status_change
+      type: field_change
+      field: status
+
+  options:
+    timestamps: true
+    label_method: title
+```
+</details>
+
+## Second Presenter: Task
+
+Create `config/lcp_ruby/presenters/task.rb`:
+
+```ruby
+define_presenter :task do
+  model :task
+  label "Tasks"
+  slug "tasks"
+  icon "check-square"
+
+  index do
+    default_sort :created_at, :desc
+    per_page 25
+    empty_message "No tasks yet. Create your first task to get started."
+    column :title, link_to: :show, sortable: true
+    column "task_list.title", label: "List", sortable: true
+    column :status, renderer: :badge, sortable: true
+    column :due_date, sortable: true
+  end
+
+  show do
+    section "Task Details", columns: 2 do
+      field :title, renderer: :heading
+      field :status, renderer: :badge
+      field "task_list.title", label: "List"
+      field :due_date
+      field :notes
+    end
+  end
+
+  form do
+    section "Task Details", columns: 2 do
+      field :title, placeholder: "What needs to be done?", autofocus: true
+      field :task_list_id, input_type: :association_select
+      field :status, input_type: :select
+      field :due_date, input_type: :date
+    end
+
+    section "Notes" do
+      field :notes, input_type: :textarea, placeholder: "Additional details..."
+    end
+  end
+
+  search do
+    searchable_fields :title
+    placeholder "Search tasks..."
+    filter :all, label: "All", default: true
+    filter :active, label: "Active", scope: :active
+    filter :completed, label: "Completed", scope: :completed
+  end
+
+  action :create,  type: :built_in, on: :collection, label: "New Task", icon: "plus"
+  action :show,    type: :built_in, on: :single, icon: "eye"
+  action :edit,    type: :built_in, on: :single, icon: "pencil"
+  action :destroy, type: :built_in, on: :single, icon: "trash", confirm: true, style: :danger
+end
+```
+
+Key concepts:
+- **`"task_list.title"`** — dot-notation traverses the `belongs_to` association to display the related list's title
+- **`label: "List"`** — overrides the auto-generated column header for dot-notation fields
+- **`input_type: :association_select`** — renders a `<select>` dropdown populated from the target model's records (uses `label_method` for display text)
+- **`renderer: :badge`** — renders enum values as colored badges
+- **`filter`** — creates tabbed filters that apply named scopes from the model
+
+<details>
+<summary>YAML equivalent</summary>
+
+```yaml
+# config/lcp_ruby/presenters/task.yml
+presenter:
+  name: task
+  model: task
+  label: "Tasks"
+  slug: tasks
+  icon: check-square
+
+  index:
+    default_sort: { field: created_at, direction: desc }
+    per_page: 25
+    empty_message: "No tasks yet. Create your first task to get started."
+    table_columns:
+      - { field: title, link_to: show, sortable: true }
+      - { field: "task_list.title", label: "List", sortable: true }
+      - { field: status, renderer: badge, sortable: true }
+      - { field: due_date, sortable: true }
+
+  show:
+    layout:
+      - section: "Task Details"
+        columns: 2
+        fields:
+          - { field: title, renderer: heading }
+          - { field: status, renderer: badge }
+          - { field: "task_list.title", label: "List" }
+          - { field: due_date }
+          - { field: notes }
+
+  form:
+    sections:
+      - title: "Task Details"
+        columns: 2
+        fields:
+          - { field: title, placeholder: "What needs to be done?", autofocus: true }
+          - { field: task_list_id, input_type: association_select }
+          - { field: status, input_type: select }
+          - { field: due_date, input_type: date }
+      - title: "Notes"
+        fields:
+          - { field: notes, input_type: textarea, placeholder: "Additional details..." }
+
+  search:
+    enabled: true
+    searchable_fields: [title]
+    placeholder: "Search tasks..."
+    predefined_filters:
+      - { name: all, label: "All", default: true }
+      - { name: active, label: "Active", scope: active }
+      - { name: completed, label: "Completed", scope: completed }
+
+  actions:
+    collection:
+      - { name: create, type: built_in, label: "New Task", icon: plus }
+    single:
+      - { name: show, type: built_in, icon: eye }
+      - { name: edit, type: built_in, icon: pencil }
+      - { name: destroy, type: built_in, icon: trash, confirm: true, style: danger }
+```
+</details>
+
+## Second Permissions: Task
+
+Create `config/lcp_ruby/permissions/task.yml`:
+
+```yaml
+permissions:
+  model: task
+
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      fields: { readable: all, writable: all }
+      actions: all
+      scope: all
+      presenters: all
+
+    viewer:
+      crud: [index, show]
+      fields: { readable: all, writable: [] }
+      actions: { allowed: [] }
+      scope: all
+      presenters: all
+
+  default_role: admin
+```
+
+## Run and Verify: Associations
+
+Restart the server (the database tables are created on boot when `auto_migrate` is enabled):
+
+```bash
+bundle exec rails server
+```
+
+Now you should see:
+
+1. **Navigation** — both "Task Lists" and "Tasks" in the top menu
+2. **Create a task list first** — go to Task Lists and create one (tasks need a list to belong to)
+3. **Create a task** — go to Tasks, click "New Task"; the "Task list" dropdown shows your lists
+4. **Dot-notation column** — the "List" column on the tasks index shows the related list's title
+5. **Association list** — the task list show page displays its tasks below the detail section
+6. **Filter tabs** — "All", "Active", and "Completed" tabs filter tasks by status scope
+
+## Adding a Custom Action
+
+Let's add a "Mark Completed" button that sets a task's status to `completed`.
+
+### Step 1: Create the Action Class
+
+Create `app/actions/task/mark_completed.rb`:
+
+```ruby
+module LcpRuby
+  module HostActions
+    module Task
+      class MarkCompleted < LcpRuby::Actions::BaseAction
+        def call
+          unless record
+            return failure(message: "No task specified")
+          end
+
+          if record.status == "completed"
+            return failure(message: "Task is already completed")
+          end
+
+          record.update!(status: "completed")
+          success(message: "Task '#{record.title}' marked as completed!")
+        end
+      end
+    end
+  end
+end
+```
+
+The class is resolved by naming convention: `LcpRuby::HostActions::<Model>::<ActionName>`.
+
+### Step 2: Add the Action to the Presenter
+
+Update `config/lcp_ruby/presenters/task.rb` — add this action alongside the existing ones:
+
+```ruby
+action :mark_completed, type: :custom, on: :single,
+  label: "Mark Completed", icon: "check",
+  confirm: true, confirm_message: "Mark this task as completed?",
+  visible_when: { field: :status, operator: :not_eq, value: "completed" }
+```
+
+The `visible_when` condition hides the button when the task is already completed.
+
+### Step 3: Add to Permissions
+
+Update `config/lcp_ruby/permissions/task.yml` — change `actions: all` to an explicit list that includes `mark_completed`:
+
+```yaml
+permissions:
+  model: task
+
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      fields: { readable: all, writable: all }
+      actions:
+        allowed: [mark_completed]
+      scope: all
+      presenters: all
+
+    viewer:
+      crud: [index, show]
+      fields: { readable: all, writable: [] }
+      actions: { allowed: [] }
+      scope: all
+      presenters: all
+
+  default_role: admin
+```
+
+### Step 4: Enable Auto-Discovery
+
+Update `config/initializers/lcp_ruby.rb` to discover action and event handler classes:
+
+```ruby
+LcpRuby.configure do |config|
+  config.authentication = :none
+end
+
+Rails.application.config.after_initialize do
+  app_path = Rails.root.join("app")
+  LcpRuby::Actions::ActionRegistry.discover!(app_path.to_s)
+  LcpRuby::Events::HandlerRegistry.discover!(app_path.to_s)
+end
+```
+
+Restart the server. Tasks that are not yet completed now show a "Mark Completed" button on the show page and in the index row actions.
+
+## Adding an Event Handler
+
+The task model already declares `on_field_change :on_status_change, field: :status`. Let's create the handler that responds when a task's status changes.
+
+Create `app/event_handlers/task/on_status_change.rb`:
+
+```ruby
+module LcpRuby
+  module HostEventHandlers
+    module Task
+      class OnStatusChange < LcpRuby::Events::HandlerBase
+        def self.handles_event
+          "on_status_change"
+        end
+
+        def call
+          old_status = old_value("status")
+          new_status = new_value("status")
+          Rails.logger.info(
+            "[TODO] Task '#{record.title}' status changed: #{old_status} -> #{new_status}"
+          )
+        end
+      end
+    end
+  end
+end
+```
+
+Key concepts:
+- **`self.handles_event`** — returns the event name string matching the model's `on_field_change` declaration
+- **`old_value` / `new_value`** — access the previous and current field values
+- **`record`** — the affected ActiveRecord instance
+- Auto-discovered via `HandlerRegistry.discover!` (added in the previous step)
+
+The class is resolved by convention: `LcpRuby::HostEventHandlers::<Model>::<HandlerName>`.
+
+Restart the server, then change a task's status. Check the Rails log to see the event handler output.
+
+## Dev Workflow
+
+LCP integrates with Rails' standard development reloader so most metadata edits take effect on the next request — no `pkill puma`, no restart. The exact "what reloads when" is:
+
+| You edit… | What happens on next request |
+|---|---|
+| YAML / DSL Ruby files under `config/lcp_ruby/` | Auto-reload via `Engine.reload!` (registries cleared, dynamic models rebuilt, `LcpRuby.on_models_loaded` callbacks re-fire) |
+| Ruby files under `app/` (controllers, host actions, host services, custom renderers) | Zeitwerk's standard reload (class redefinition) |
+| Locale files under `config/locales/` | Rails' i18n reloader |
+| Initializer files under `config/initializers/` | Requires server restart (Rails initializer chain runs once) |
+| Gem updates / `Gemfile.lock` changes | Requires server restart |
+| `LcpRuby.configuration.*` settings | Requires server restart (read once at boot) |
+
+**Important asymmetry.** Editing only an `app/`-side host file (e.g. a custom action class) reloads the **class** via Zeitwerk, but the LCP registry that holds a reference to the old class is not refreshed until the next YAML edit or manual `LcpRuby::Engine.reload!`. If you find a host action change isn't taking effect, touching any YAML file under `config/lcp_ruby/` (or simply restarting) forces the registry to rebuild.
+
+**Manual reload.** From the Rails console: `LcpRuby::Engine.reload!`. Useful when you've changed a `LcpRuby.configuration.*` field or want to force a refresh without editing a watched file.
+
+**Subscribing to reload events.** `ActiveSupport::Notifications` emits `boot.lcp_ruby` on every `load_metadata!` and `reload.lcp_ruby` on every successful reload. See [`docs/reference/boot_lifecycle.md`](reference/boot_lifecycle.md) § Instrumentation.
+
+The full lifecycle (boot phases, hook ordering, the watcher's glob form) is documented in [`docs/reference/boot_lifecycle.md`](reference/boot_lifecycle.md).
+
+## Resetting the Database
+
+LCP-managed tables are created by the platform's `SchemaManager` from your YAML/DSL model definitions — they do **not** live in `db/migrate/`. The standard Rails db lifecycle commands are wired to materialise these tables alongside Rails' own migrations:
+
+| Command | Behaviour |
+|---|---|
+| `rails db:prepare` | Creates DB if missing, runs Rails migrations, then runs `lcp_ruby:ensure_tables` (post-action) so platform tables exist |
+| `rails db:setup` | Same as `db:prepare` for a fresh DB; also seeds |
+| `rails db:reset` | Drops + recreates DB via `db:setup`; inherits the platform-table fix transitively |
+| `rails db:drop db:prepare db:seed` | Works in one process — `lcp_ruby:ensure_tables` recreates platform tables before seeds run |
+| `rake lcp_ruby:ensure_tables` | Standalone task; idempotent. Runs automatically as a post-action of `db:prepare` / `db:setup`, but you can invoke it directly when needed |
+
+**`db:reset` vs `db:prepare`.** Use either — both work after this change. Prior to v1 of the boot/reload lifecycle work, `db:reset` would silently leave platform tables un-created; this is no longer the case.
+
+**`db:migrate`.** Runs Rails migrations only. Does **not** touch platform tables — those are managed by `SchemaManager` at boot. If you need only platform tables refreshed (rare), invoke `rake lcp_ruby:ensure_tables` directly.
+
+**Adding a new model.** No migration required: define the YAML/DSL, save the file, and on the next request the dev watcher reloads metadata and `SchemaManager` adds the new table. The `auto_migrate: true` configuration default makes this work without explicit action.
+
+**Removing a model.** Drop the YAML/DSL file. The platform stops registering the model on the next reload, but the **table itself is not dropped automatically** (data preservation is the safer default). To drop the table manually:
+
+```ruby
+ActiveRecord::Base.connection.drop_table("legacy_things")
+```
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| `NoMethodError: undefined method 'lcp_role'` | User model missing role method | Add `lcp_role` method to your User model or use `authentication: :none` |
+| `MetadataError: Duplicate model` | Same model defined in both `.rb` and `.yml` | Use one format per model |
+| Action class not found | Not auto-discovered | Add `ActionRegistry.discover!` to your initializer |
+| Table not created (after `db:reset` or `db:drop db:prepare`) | Pre-v1 behaviour where Rails db tasks skipped `SchemaManager` | Fixed — `db:prepare` and `db:setup` now invoke `lcp_ruby:ensure_tables` automatically. If you've custom-overridden these tasks, ensure they still run the post-action |
+| Permission YAML edit not taking effect | Old: caches survived dev reload | Fixed — dev watcher reloads on any change under `config/lcp_ruby/`. If a change still doesn't apply, see [Dev Workflow](#dev-workflow) for what reloads vs. requires restart |
+| `Duplicate presenter '<name>'` after dev reload | Pre-v1 behaviour where reload re-ran loader on populated registries | Fixed — `Engine.reload!` now resets cleanly. Stop and restart the server once after upgrading; subsequent reloads work |
+| Host action / event handler change not visible | Zeitwerk reloaded the class but LCP registry holds old reference | Touch any YAML file under `config/lcp_ruby/` to force a reload, or run `LcpRuby::Engine.reload!` in the console |
+| Association select is empty | No records exist in the target model | Create target records first (e.g., create a task list before a task) |
+| `Pundit::NotAuthorizedError` | Missing permissions file for the model | Create a permissions YAML file or a `_default.yml` fallback |
+| Custom action button not visible | `visible_when` hides it or action not in `actions.allowed` | Check both presenter `visible_when` conditions and permissions `actions.allowed` |
+| Search returns no results | Field not included in `searchable_fields` | Add the field to the `search` block's `searchable_fields` |
+| Event handler not firing | Event not declared in model or handler not discovered | Verify `on_field_change` in model DSL, `handles_event` return value matches the event name, and `HandlerRegistry.discover!` in initializer |
+
+## Seed Data
+
+To populate the database with initial records in `db/seeds.rb`, you must load metadata first — otherwise the dynamic model classes do not exist yet:
+
+```ruby
+# db/seeds.rb
+
+# Required: load metadata before accessing dynamic models.
+# On normal boot this happens automatically, but seeds may run
+# before the initializer — call explicitly to be safe.
+LcpRuby::Engine.load_metadata!
+
+# Access dynamic model classes via registry:
+TaskList = LcpRuby.registry.model_for("task_list")
+Task = LcpRuby.registry.model_for("task")
+
+# Create records as usual:
+inbox = TaskList.create!(title: "Inbox")
+Task.create!(title: "Buy milk", task_list: inbox)
+```
+
+Key points:
+- `load_metadata!` is idempotent — safe to call even if already loaded
+- `model_for` returns the dynamic ActiveRecord class (e.g., `LcpRuby::Dynamic::TaskList`)
+- Assigning to a constant is optional but convenient for readability
+
+## Next Steps
+
+- [Host Application Guide](guides/host-application.md) — Full app bootstrap, optional dependencies (XLSX, charts, metrics), available feature generators
+- [Models Reference](reference/models.md) — All field types, validations, associations, scopes, and events
+- [Model DSL Reference](reference/model-dsl.md) — Full Ruby DSL syntax for models
+- [Presenters Reference](reference/presenters.md) — All index, show, form, search, and action options
+- [Presenter DSL Reference](reference/presenter-dsl.md) — Full Ruby DSL syntax for presenters (with inheritance)
+- [Permissions Reference](reference/permissions.md) — Field overrides, record rules, scope types
+- [Types Reference](reference/types.md) — Business types (email, phone, url, color) and custom types
+- [Custom Types Guide](guides/custom-types.md) — Practical custom type examples
+- [Attachments Guide](guides/attachments.md) — File upload with Active Storage
+- [Custom Actions](guides/custom-actions.md) — Advanced action patterns
+- [Event Handlers](guides/event-handlers.md) — Async handlers, lifecycle events
+- [Conditional Rendering](guides/conditional-rendering.md) — `visible_when` and `disable_when` on fields, sections, and actions
+- [Extensibility Guide](guides/extensibility.md) — Transforms, validators, defaults, computed fields, condition services
+- [View Groups Guide](guides/view-groups.md) — Multi-view navigation and view switcher
+- [i18n Reference](reference/i18n.md) — Translating model names, field labels, enums, menu items, and UI strings
+- [Menu Guide](guides/menu.md) — Custom navigation menus
+- [Custom Fields Guide](guides/custom-fields.md) — Runtime user-defined fields
+- [Developer Tools](guides/developer-tools.md) — Validate configuration, generate ERD diagrams, inspect permissions
+- [Engine Configuration](reference/engine-configuration.md) — All `LcpRuby.configure` options
+- [Example Apps](examples.md) — Complete TODO and CRM walkthroughs