lcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15ce78e55a51f7b9192bd168c209459194465fe62de1f459d405d126e937accf
+  data.tar.gz: 550348550e26fc527d98d4090038f2919e2b1d866de92ecfaf885f75b2a597f1
+SHA512:
+  metadata.gz: 9e16d8a1b1d2804f52bd42483ddde70819511994465bcf68e58b27eee62234ad4f4e3155ae7b2478381cc4a3c004eeb3d04d68fe3c611ae9317198d64b5ae620
+  data.tar.gz: 75b0a589c1ee4e84c41c05fd78c356e79212d68f048d1d57e1c2857ce350ba36adf0701f7d9dc88ae29ff5867eb0eeccb33a3aee1d15a01e0ca10ff3ef6dc0cd

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

@@ -0,0 +1,205 @@
+---
+name: lcp-custom-field
+description: Use when enabling or managing LCP Ruby custom fields — runtime user-defined fields stored in a model's `custom_data` JSON column. Triggers on phrases like "custom fields", "user-defined fields", "runtime fields", "extensible fields", "add fields without migration", "custom_data", "custom_field_definition", "field at runtime", "tenant-specific fields", "EAV", "show_in_table", "show_in_form", "field permissions for custom fields", `custom_fields: true` on a model. Also for editing the auto-generated `custom_field_definition` model/presenter/permissions or rolling out the `lcp_ruby:custom_fields` generator.
+---
+
+> **Reference docs base:** run `bundle exec rake lcp_ruby:docs` in an LCP app (version-matched), otherwise `lcp docs path`. Resolve any `docs/X` reference below under that base (or the project root if a `docs/` tree exists there).
+
+# LCP Ruby — Custom Fields
+
+Custom fields let end-users add new fields to a model **at runtime** — no code change, no DB migration. Definitions live as records in the `custom_field_definitions` table; values live in a `custom_data` JSON/JSONB column on the target model. Dynamic accessors (`record.<field_name>`) are generated from the definitions at boot and after any change (cached, invalidated on commit).
+
+## Before you write anything
+
+1. **Read the canonical reference**: `docs/reference/custom-fields.md` (~480 lines).
+2. **Guide**: `docs/guides/custom-fields.md` for end-user-facing behavior.
+3. **Permissions interplay**: `docs/reference/permissions.md#custom-field-permissions`.
+
+## Two-step setup
+
+### 1. Generate the management UI (one-time per host app)
+
+```bash
+rails generate lcp_ruby:custom_fields                   # DSL format (default)
+rails generate lcp_ruby:custom_fields --format=yaml     # YAML format
+```
+
+This generates:
+- `models/custom_field_definition.{rb,yml}` — definition table model
+- `presenters/custom_field_definition.{rb,yml}` — admin UI (incl. bulk "Manage All" editor, fully presenter-driven)
+- `permissions/custom_field_definition.yml`
+- `views/custom_fields.yml` — view group (optional)
+
+Customize the management UI by editing the generated **presenter** — its `form` sections drive both the per-field edit form AND the bulk "Manage All" page (per-row, with row-scoped `visible_when` like "Text Constraints visible when type ∈ {string, text}").
+
+### 2. Opt models in
+
+YAML:
+```yaml
+model:
+  name: project
+  options:
+    custom_fields: true
+  fields:
+    - { name: name, type: string }
+```
+
+DSL:
+```ruby
+define_model :project do
+  custom_fields true
+  field :name, :string
+end
+```
+
+When `custom_fields: true` is set, the engine:
+- Adds a `custom_data` column (JSONB on PostgreSQL with GIN index, JSON on SQLite — no native index)
+- Installs `read_custom_field` / `write_custom_field` instance methods
+- Installs `apply_custom_field_accessors!` — generates dynamic getters/setters from the live DB definitions and removes stale ones
+- Adds validation logic enforcing `required`, `min_length`, `max_length`, `min_value`, `max_value`, `enum_values`, etc.
+- Auto-applies `default_value` from definitions on `after_initialize` (only if the field is unset)
+
+## Definition attributes (the columns of `custom_field_definitions`)
+
+These are the fields users fill in via the management UI. Cite section names for searchability.
+
+### Core (required)
+
+| Attr | Notes |
+|------|-------|
+| `target_model` | model name with `custom_fields: true` |
+| `field_name` | `[a-z][a-z0-9_]*`, unique per `target_model`; **cannot collide** with model columns or reserved names (`id`, `type`, `created_at`, `updated_at`, `custom_data`) |
+| `custom_type` | one of `string`, `text`, `integer`, `float`, `decimal`, `boolean`, `date`, `datetime`, `enum` |
+| `label` | human-readable |
+
+### Display
+
+`description`, `section` (default `"Custom Fields"` — fields with same section group together in form/show), `position` (sort within section, lower first), `active` (default `true` — inactive = hidden from UI + skipped in validation).
+
+### Validation
+
+`required`, `min_length`/`max_length` (string/text), `min_value`/`max_value` (numeric), `precision` (decimal — informational), `default_value` (string, applied to new records only), `placeholder`, `enum_values` (when `custom_type: enum`; array of strings or `[{value, label}]` objects).
+
+### Visibility
+
+`show_in_table` (default `false`), `show_in_form` (default `true`), `show_in_show` (default `true`), `sortable`, `searchable` (combined with regular searchable fields via OR).
+
+### Rendering
+
+`input_type`, `renderer`, `renderer_options` (json), `column_width` (CSS like `"120px"` or `"15%"`).
+
+### Reserved (future / unused)
+
+`extra_validations`, `readable_by_roles`, `writable_by_roles` — declared but not yet wired. **Use the standard `permissions.fields.readable/writable` and `field_overrides`** for per-field access (see below).
+
+## Permissions interplay
+
+Two granularity levels — both work on the same model:
+
+```yaml
+permissions:
+  model: project
+  roles:
+    admin:
+      fields: { readable: all, writable: all }       # includes custom_data → ALL custom fields
+    editor:
+      fields:
+        readable: [name, status, website, phone]     # specific custom fields by name
+        writable: [name, website]                     # only website is writable
+    support:
+      fields:
+        readable: [name, custom_data]                 # name + ALL custom fields
+        writable: [custom_data]
+    restricted:
+      fields:
+        readable: [name, status]                      # NO custom_data → no custom fields visible
+  field_overrides:
+    internal_notes:                                    # per-custom-field override
+      readable_by: [admin, manager]
+      writable_by: [admin]
+```
+
+Resolution rules (verbatim from reference):
+
+| Permission Config | Result |
+|-------------------|--------|
+| `readable: all` | All custom fields readable |
+| `readable: [title, custom_data]` | title + ALL custom fields |
+| `readable: [title, website]` | title + only "website" custom field |
+| `readable: [title]` | No custom fields visible |
+
+## Programmatic API
+
+```ruby
+project = LcpRuby.registry.model_for("project")
+record  = project.find(1)
+
+# Low-level (always available)
+record.read_custom_field("website")
+record.write_custom_field("website", "https://new.com")
+record.save!
+
+# Dynamic accessors (after apply_custom_field_accessors!, which runs at boot + on definition changes)
+record.website                    # => "https://new.com"
+record.website = "https://x.com"
+record.save!
+```
+
+Querying:
+
+```ruby
+q = LcpRuby::CustomFields::Query
+q.text_search(scope, "projects", "website", "example")
+q.exact_match(scope, "projects", "status", "active")
+scope.order(q.sort_expression("projects", "website", "asc"))
+scope.order(q.sort_expression("projects", "score", "desc", cast: :integer))
+```
+
+Registry: `LcpRuby::CustomFields::Registry.for_model("project")` → array of definition records. `.reload!("project")` or `.reload!` to clear cache.
+
+## Pitfalls & guidance
+
+- **`field_name` collisions** with model columns (or reserved names) raise validation errors at definition save. Pick distinct names.
+- **`default_value` is stored as string** — converted at read time per `custom_type`. New records get it via `after_initialize` ONLY if unset; **existing records are not retroactively populated**.
+- **SQLite has no JSON indexing** — searchable/sortable custom fields work but are slow on large tables. Production deployments should use PostgreSQL.
+- **Cache invalidation is automatic** via an `after_commit` callback on `custom_field_definition` — definition changes take effect immediately without a server restart. Both the cached definition list AND the dynamic accessors on the model class are updated (stale getters/setters removed).
+- **Permissions: `custom_data` is a virtual catch-all.** Granting it grants all active custom fields. To restrict, list specific custom field names in `readable`/`writable`.
+- **`field_overrides` work with custom field names** — same `readable_by`/`writable_by`/`masked_for` semantics as regular fields.
+- **Management routes are nested** under the parent model's slug: `/<presenter_slug>/custom-fields`. The `target_model` is resolved from the URL — record lookups are scoped to prevent cross-model edits. Authorization is the **separate** `permissions/custom_field_definition.yml` (not the parent model's permissions).
+- **Don't use `custom_fields: true`** on `bind_to:` models without `bind_to_apply: [custom_fields]` AND a `custom_data` JSON column on the host table. See `lcp-host-binding` skill.
+- **Don't use the reserved attrs** `extra_validations`, `readable_by_roles`, `writable_by_roles` — they exist on the schema but are not enforced. Use real permissions for access control.
+- **Bulk "Manage All" page is presenter-driven.** To change the bulk editor's columns/sections, edit the **presenter's `form` sections** — the page reads them via `LayoutBuilder.form_sections` and applies row-scoped `visible_when`. No template overrides needed.
+
+## Advanced (one-line pointers)
+
+Stuff with its own dedicated reference / guide. **Browse `docs/feature-catalog.md ## Custom Fields`** for the full inventory of custom-field shipped capabilities. Don't inline syntax; just open the relevant doc.
+
+- **Bulk "Manage All" page is presenter-driven** — the page reads `form` sections from the generated `custom_fields` presenter and applies row-scoped `visible_when` per row (e.g. "Text Constraints" only when `custom_type ∈ {string, text}`). To customize the bulk editor, edit the presenter — no template overrides needed. → custom-fields.md `## Management Routes`, `docs/guides/conditional-rendering.md#row-scoped-conditions-in-nested-fields`.
+- **Cache invalidation flow** — `after_commit` callback on `custom_field_definition`: clears cached definitions for `target_model` AND re-applies dynamic accessors on the model class (adding new ones, removing stale ones). No restart needed for definition CRUD. → custom-fields.md `## Cache Invalidation`.
+- **Programmatic API for seeds & migrations** — `LcpRuby::CustomFields::Registry.for_model("project")`, `record.read_custom_field`/`write_custom_field`, dynamic `record.<field_name>` accessors. Query helpers: `LcpRuby::CustomFields::Query.text_search`, `.exact_match`, `.sort_expression(model, field, dir, cast: :integer)`. → custom-fields.md `## Programmatic API`.
+- **DB portability** — PostgreSQL: JSONB column with GIN index, `->>`, `ILIKE`. SQLite: JSON column without indexing, `JSON_EXTRACT`, `LIKE`. **SQLite is functional but slow at scale** — production custom fields → PostgreSQL. → custom-fields.md `## Database Portability`.
+- **Permission interplay full surface** — `custom_data` virtual catch-all, per-custom-field-name `readable`/`writable`, `field_overrides` with custom field names, full resolution table. → custom-fields.md `## Permissions`, `lcp-permissions` skill.
+- **Custom field hints, descriptions, placeholders** — `description:`, `hint:`-style propagation via `LayoutBuilder` to form inputs. → custom-fields.md `## description`, `## placeholder`.
+- **Conditional custom-field form sections** — Text/Numeric/Enum constraints groups shown conditionally by `custom_type`. → guides/custom-fields.md `## Working with Sections`.
+- **Custom fields on multiple models** — many models can have `custom_fields: true`; everything is scoped by `target_model`; nested management routes per-model. → custom-fields.md `## Enabling Custom Fields`.
+- **Bind_to + custom fields** — requires `bind_to_apply: [custom_fields]` AND `custom_data` JSON column on the host table. Without the column, dynamic accessors fail at runtime. → `lcp-host-binding` skill.
+- **Import respect for custom fields** — importer honors permission filtering on custom fields (writable check); custom fields appear in mapping UI when configured. → `docs/reference/import.md` `## permission-filtering`.
+- **Reserved-future attrs** — `extra_validations`, `readable_by_roles`, `writable_by_roles` are present on the schema but **not enforced** today. Use real permissions config for access control.
+- **Field-name reserved list** — `id`, `type`, `created_at`, `updated_at`, `custom_data`, plus any column on the model. Validation rejects collisions at definition save.
+
+When in doubt about whether a capability exists at all → grep `docs/feature-catalog.md`.
+
+## After editing
+
+1. If you added/changed a model's `custom_fields: true` flag, restart the dev server (schema is rebuilt at boot — `custom_data` column is added).
+2. If you changed the **management presenter** (`presenters/custom_field_definition.{rb,yml}`), restart so it reloads.
+3. If you changed actual **custom field definitions** (records in DB via UI or seeds), no restart needed — the `after_commit` cache invalidation handles it.
+4. Run validation: `bundle exec rake lcp_ruby:validate` (auto-fired by the `lcp-validate` hook for `examples/*/config/lcp_ruby/`).
+
+## Related skills / docs
+
+- Enabling on a model → `lcp-model` skill (`custom_fields true` / `options: { custom_fields: true }`).
+- Permissions for custom fields → `lcp-permissions` skill (`custom_data` virtual + per-field-name + `field_overrides`).
+- UI placement (which sections, ordering) → `lcp-presenter` skill (custom fields auto-merge by `section:`; explicit positioning works through that grouping).
+- Binding `custom_fields` onto an existing host AR model → `lcp-host-binding` skill (`bind_to_apply: [custom_fields]`).
+- DB-backed permissions for custom fields → `docs/reference/permission-source.md`.

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

@@ -0,0 +1,332 @@
+---
+name: lcp-getting-started
+description: Use when the user is starting a new LCP Ruby project or has just bootstrapped one and needs orientation — running `lcp new`, adding LCP to an existing Rails app via `lcp_ruby:install`, understanding the `config/lcp_ruby/` directory layout, picking DSL vs YAML format, or wiring up the first model + presenter + permissions trio. Triggers on phrases like "new LCP project", "set up LCP", "lcp new", "lcp_ruby:install", "where do I start", "first model", "first presenter", "scaffold a CRUD", "bootstrap an LCP app", "add LCP to existing Rails app", "directory structure", "DSL or YAML", "minimum viable LCP app".
+---
+
+> **Reference docs base:** run `bundle exec rake lcp_ruby:docs` in an LCP app (version-matched), otherwise `lcp docs path`. Resolve any `docs/X` reference below under that base (or the project root if a `docs/` tree exists there).
+
+# LCP Ruby — Getting Started
+
+This skill is an **orientation map**, not a feature reference. Use it when the user is at the "I just got here, where do I start?" moment — picking a bootstrap path, learning the project layout, or producing their first working CRUD page. Send the user to a deeper `lcp-*` skill as soon as the question turns into a real authoring task.
+
+## Before you do anything
+
+1. **Long-form tutorial**: `docs/getting-started.md` (~1100 lines). The example used in this skill (`task_list`) mirrors that tutorial — keep them consistent.
+2. **Host-application walkthrough**: `docs/guides/host-application.md` (end-to-end setup for an existing Rails app, including the trickier integration patterns).
+3. **Capability inventory**: `docs/feature-catalog.md` (auto-generated catalog of everything LCP can do — useful for "does LCP support X?" questions).
+4. **Doc index**: `docs/README.md` (the full index of YAML/DSL references and guides — start here whenever you want to know if something is already documented before answering from memory).
+
+## Two bootstrap paths
+
+Pick the path based on whether the user has an app yet.
+
+### Path A — greenfield (`lcp new`)
+
+Requires Ruby 3.1+ and Rails 8.1+ on the user's machine. The CLI runs `rails new`, installs the gem, runs the chosen generators, prepares the database, and copies `lcp-*` Claude skills into `.claude/skills/`.
+
+```bash
+lcp new my_app                                    # interactive wizard
+lcp new my_app --skip-interactive                 # defaults: sqlite3, DSL, minimal
+lcp new my_app --database=postgresql --format=yaml --preset=standard
+lcp new my_app --locale=cs --timezone=Europe/Prague           # single non-en locale
+lcp new my_app --locale=cs,en,de                              # multi-locale; first wins as default
+lcp new my_app --gem-source=path:/abs/path/to/lcp-ruby   # local checkout
+```
+
+**Locale flag:** `--locale=cs` writes `available_locales = [:cs]` (NOT `[:en, :cs]`) — listing `:en` would let the browser's en-US flip the UI to English via Accept-Language matching. `--locale=cs,en,de` makes all three first-class. Fallback to engine's English baseline is wired automatically via `config.i18n.fallbacks`. Full locale guide at `docs/guides/adding-locale.md` in the generated app.
+
+Presets:
+
+| Preset | Includes |
+|--------|----------|
+| `minimal` | Core only — sample model + presenter + permissions. Fastest path. |
+| `standard` | Core + auth + auditing + saved filters + export + import. Good default for real apps. |
+| `full` | All ~18 feature generators. Use only when the user wants to explore everything. |
+| `custom` | Interactive checklist of individual generators. |
+
+After bootstrap:
+
+```bash
+cd my_app
+bundle exec rails s
+# visit http://localhost:3000/items   (the sample model shipped by lcp_ruby:install)
+```
+
+### Path B — existing Rails app (`lcp_ruby:install`)
+
+```ruby
+# Gemfile
+gem "lcp"
+```
+
+```bash
+bundle install
+bundle exec rails generate lcp_ruby:install
+bundle exec rails generate lcp_ruby:claude_skills   # copy lcp-* skills into .claude/skills/
+```
+
+The install generator wires `require "lcp_ruby"` into `application.rb`, mounts the engine in `config/routes.rb`, creates `config/lcp_ruby/`, drops a sample model + presenter + permissions, adds the initializer, and creates a `current_user` stub.
+
+Most-used follow-up generators (run from the host app root):
+
+| Generator | Purpose |
+|-----------|---------|
+| `lcp_ruby:install_auth` | Devise-based authentication (`LcpRuby::User` + login flows) |
+| `lcp_ruby:api_tokens` | Personal Access Tokens for bearer-auth API access |
+| `lcp_ruby:auditing` | Per-record audit trail with field diffs |
+| `lcp_ruby:export` | CSV/XLSX export with field picker + saved profiles |
+| `lcp_ruby:import` | CSV/XLSX import with column mapping + strategies |
+| `lcp_ruby:custom_fields` | Runtime user-defined fields (`custom_data` JSON column) — see `lcp-custom-field` |
+| `lcp_ruby:saved_filters` | Per-user saved search filters |
+| `lcp_ruby:role_model` | DB-backed roles (replaces YAML-only roles) |
+| `lcp_ruby:permission_source` | DB-backed permissions (edit at runtime) |
+| `lcp_ruby:groups` | Organizational grouping for access control |
+| `lcp_ruby:workflow_definition` | State machine: states, transitions, guards — see `lcp-workflow` |
+| `lcp_ruby:workflow_approvals` | Sequential/parallel approval processes |
+| `lcp_ruby:workflow_audit_log` | Workflow state-change audit trail |
+| `lcp_ruby:pages` | DB-backed dashboards / landing pages |
+| `lcp_ruby:background_jobs` | Job-queue tracking and visibility |
+| `lcp_ruby:batch_operations` | Bulk create/update/delete in background jobs |
+| `lcp_ruby:monitoring` | Error dashboard + Prometheus metrics |
+| `lcp_ruby:gapfree_sequences` | Gap-free auto-numbering |
+| `lcp_ruby:host_controller` | Scaffold a host controller that includes LCP concerns — see `lcp-host-binding` |
+| `lcp_ruby:entity` | One-shot scaffold of a new entity — model + presenter + permissions + view group from a CLI field grammar (covers v1 types/associations, v2 DB constraints + feature flags, v3 sections/renderers/color_map/link/polymorphic). See "Fast path" below. |
+
+All format-aware generators take `--format=dsl` (default) or `--format=yaml`. The complete list lives in `docs/getting-started.md`.
+
+## Project anatomy
+
+LCP metadata lives entirely under `config/lcp_ruby/`:
+
+```
+config/lcp_ruby/
+├── models/              # Data definitions  → builds AR classes + tables  → see lcp-model
+│   ├── task_list.rb     # DSL  (or .yml — pick one per concept name)
+│   └── _auditable.rb    # Files starting with "_" are abstract templates
+├── presenters/          # UI definitions    → index/show/form/search    → see lcp-presenter
+│   └── task_list.rb
+├── permissions/         # Role-based access → CRUD/fields/scope        → see lcp-permissions
+│   ├── task_list.yml
+│   └── _default.yml     # Fallback for any model without its own file
+├── types/               # Custom field types (e.g., money, ssn)
+├── views/               # View groups / shared layout fragments
+├── pages/               # Custom static or composite pages
+├── workflows/           # State machines + approval flows               → see lcp-workflow
+├── menu.yml             # Top navigation
+└── theme.yml            # Color tokens, typography, density
+```
+
+The engine boots, reads everything in this tree, builds dynamic AR classes under `LcpRuby::Dynamic::*`, runs `SchemaManager` to create/alter tables to match, and mounts CRUD routes by presenter `slug`. **Restart the Rails server after editing any of these files** — they are loaded at boot.
+
+## Choosing DSL vs YAML
+
+| Aspect | DSL (`.rb`) | YAML (`.yml`) |
+|--------|-------------|----------------|
+| Style | Programmatic, method-call based | Declarative, data-only |
+| IDE help | Yes (Ruby methods) | Schema-validated via `lib/lcp_ruby/schemas/*.json` |
+| Diffs | Slightly noisier | Very clean |
+| Validation | Runtime errors at boot | `bundle exec rake lcp_ruby:validate` reads JSON schemas |
+| Mixing | A given concept name (`task_list`) must be either `.rb` or `.yml`, never both |
+
+**Mirror what the host project already uses.** Look at neighbouring files in `config/lcp_ruby/models/` (or wherever you're authoring) and match — don't introduce a second format. The host repo's `CLAUDE.md` may also state a preference.
+
+## Your first resource — `task_list` (model + presenter + permissions trio)
+
+Three files = a fully working CRUD page at `/task_lists`. Mirrors the example in `docs/getting-started.md`.
+
+### Fast path — `lcp_ruby:entity`
+
+If the user is creating a brand-new entity from scratch and just wants the four files (model + presenter + permissions + view group) atomically, prefer the entity generator over hand-writing them. Hand-writing is for **editing** existing files or for cases the grammar can't express; the generator covers the 80% case.
+
+```bash
+# Equivalent of the full task_list trio + view group, in one command
+bundle exec rails generate lcp_ruby:entity TaskList \
+  title:string!:uniq \
+  description:text \
+  --label-method=title
+
+# Richer entity (v3 grammar: sections, renderers, color_map, link, search, tabs)
+bundle exec 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
+```
+
+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`), v3 presenter modifiers (`{section:NAME}`, `{renderer:NAME}`, `{color_map}`, `{link}` (no-op since v3.1 — auto-link is the default for non-polymorphic belongs_to), `{polymorphic}`, `:hidden`, `:search`). Feature flags: `--soft-delete`, `--auditing` (requires `audit_log` model), `--custom-fields` (requires `custom_field_definition` model), `--positioning`, `--tree`, `--form-layout=tabs`, `--index-fields=a,b,c`, `--default-sort=field[,asc|desc]` (when omitted, no `default_sort` is emitted — runtime falls back to `id`), `--display-template`, `--validate`. Full grammar + worked examples in `docs/design/entity_generator.md`.
+
+**Bash users:** single-quote any field token whose braces contain a comma (e.g. `'belongs_to{required,model:user}'`) — bash brace-expands `{a,b}` patterns silently; zsh does not.
+
+The generator is **idempotent on file conflict** — Thor's standard `[Ynaqdh]` prompt; `--force` bypasses, `--skip` preserves. Generated permissions copy role keys from `_default.yml`. Generated view group is **not** auto-wired into `menu.yml` — the post-install message tells the configurator to add `- view_group: <plural>` to the desired menu branch.
+
+### Hand-written reference (for the cases the generator doesn't cover)
+
+### 1. Model — `config/lcp_ruby/models/task_list.rb`
+
+```ruby
+define_model :task_list do
+  field :title, :string do
+    validates :presence
+    validates :length, minimum: 3, maximum: 255
+  end
+  field :description, :text
+  timestamps true
+  label_method :title
+end
+```
+
+YAML equivalent — `config/lcp_ruby/models/task_list.yml`:
+
+```yaml
+model:
+  name: task_list
+  fields:
+    - name: title
+      type: string
+      validations:
+        - { type: presence }
+        - { type: length, options: { minimum: 3, maximum: 255 } }
+    - { name: description, type: text }
+  options:
+    timestamps: true
+    label_method: title
+```
+
+### 2. Presenter — `config/lcp_ruby/presenters/task_list.rb`
+
+```ruby
+define_presenter :task_list do
+  model :task_list
+  slug "task_lists"
+  icon "list"
+
+  index do
+    default_sort :created_at, :desc
+    per_page 25
+    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, autofocus: true
+      field :description, input_type: :textarea
+    end
+  end
+
+  search do
+    searchable_fields :title, :description
+  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
+```
+
+YAML equivalent lives at `config/lcp_ruby/presenters/task_list.yml` — see `docs/getting-started.md:407-453` for the side-by-side, or `docs/reference/presenters.md` for the full schema.
+
+### 3. Permissions — `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
+```
+
+`default_role: admin` is fine for an `authentication: :none` dev setup. **Switch it to `viewer` (or another restrictive role) the moment auth is added** — otherwise unauthenticated users get full access.
+
+For a fallback that applies to any model without its own file, create `config/lcp_ruby/permissions/_default.yml` with `model: _default`.
+
+## Validate, migrate, run
+
+From the host app's root:
+
+```bash
+bundle exec rake lcp_ruby:validate          # schema-checks all YAML, surfaces typos before boot
+bundle exec rails db:prepare                 # SchemaManager creates/alters tables from the metadata
+bundle exec rails s
+# visit http://localhost:3000/task_lists
+```
+
+Verify the user sees:
+- empty state on the index,
+- "New List" button → form with autofocused title,
+- after save, redirect to show page,
+- search box filters by title/description,
+- a "Task Lists" link in the top navigation.
+
+## Day-2 polish (after CRUD works)
+
+Two recurring questions once a few entities exist — both have built-in answers, no code needed:
+
+| Symptom | Fix | Docs |
+|---|---|---|
+| Menu items in alphabetical order, want custom order | Write `config/lcp_ruby/menu.yml` — quickest path is to pass `--menu=[<section>:]ROOT|<DropdownLabel>` when generating the entity (writes to menu.yml above the seeded `# lcp:menu` marker). For existing entities, edit menu.yml directly. `presenter.menu_position` still works but is deprecated. | `docs/guides/menu.md#adding-entities-to-the-menu`, `docs/reference/menu.md` |
+| After login redirects to wrong page (alphabetical first view group) | Set `config.landing_page = "<presenter-or-page-slug>"` in `config/initializers/lcp_ruby.rb` — supports a per-role hash form too | `docs/reference/engine-configuration.md#landing_page` |
+| Reset development data without writing destroy chains by hand | `bundle exec rake lcp_ruby:reset_data CONFIRM=yes` — topologically sorted destroy_all, refuses production unless forced | `docs/guides/developer-tools.md#lcp_rubyreset_data` |
+
+If the host app has 5+ entities and no `menu.yml`, the engine logs a one-time hint at boot pointing here. Don't suppress it without addressing one of the two options above.
+
+## Common first-day pitfalls
+
+- **Server not restarting after metadata changes.** Models/presenters/permissions are loaded at boot. The user's edit isn't taking effect until they restart `rails s`.
+- **`create_table` in a regular migration.** Don't. All LCP-managed tables come from `SchemaManager` reading the model metadata. If a feature wants its own internal tables (audit log, workflow log, etc.), add them via the relevant generator or as a normal LCP YAML/DSL model — see CLAUDE.md "Table creation rule".
+- **Hardcoded labels in YAML.** Per CLAUDE.md "i18n Principle", user-visible text goes in locale files. YAML/DSL define structure only. The lookup convention is `I18n.t("lcp_ruby.<namespace>.<key>", default: "Humanized fallback")`.
+- **Mixing DSL and YAML for the same concept name.** A model named `task_list` is either `task_list.rb` or `task_list.yml`, never both. Mirror the host project's chosen format.
+- **`default_role: admin` left in place after enabling auth.** It opens the app to anonymous full-access. Tighten it before switching `authentication:` away from `:none`.
+- **Re-defining an existing host AR model in `config/lcp_ruby/models/`.** If the host already has `app/models/user.rb`, don't redeclare it — use `bind_to: "::User"` (see `lcp-host-binding`). LCP will drive the UI without re-generating the class or creating a table.
+- **Running generators from the gem root instead of the host app.** `lcp_ruby:*` generators must run inside the host application directory.
+- **Bundler picks the wrong Gemfile when your shell is locked to another project (e.g. you're an agent operating from the LCP gem checkout).** `bundle` walks up from cwd and finds the nearest Gemfile, so `bundle exec rails s` will boot the LCP gem instead of the host app. Either `cd` into the host app first, or prefix every command with `BUNDLE_GEMFILE=/abs/path/to/host_app/Gemfile` to force the right context.
+- **Sprockets vs Propshaft.** On Rails 8 (Propshaft default), the host app must also `gem "sprockets-rails"` — without it, LCP's JS (row-click, advanced filters) won't load. See `docs/getting-started.md:139` "Asset Pipeline (Sprockets)".
+
+## Where to go next — skill cross-links
+
+Once the user moves past orientation, hand off to the skill that owns the topic:
+
+| Topic | Skill |
+|-------|-------|
+| Fields, validations, associations, scopes, lifecycle, soft-delete, auditing, tree, STI, aggregates, API-backed, `bind_to` | **`lcp-model`** |
+| Index/show/form layouts, tabs, steps, search, saved filters, custom actions, renderers, conditional rendering | **`lcp-presenter`** |
+| Roles, CRUD/field/action permissions, `record_rules`, `field_overrides`, `default_role`, DB-backed permission/role sources | **`lcp-permissions`** |
+| Wrapping an existing AR model, routing CRUD to a host controller, including `LcpRuby::Controller::*` concerns | **`lcp-host-binding`** |
+| Runtime user-defined fields stored in `custom_data` | **`lcp-custom-field`** |
+| State machines, transitions, guards, approval processes | **`lcp-workflow`** |
+
+## Reference docs the user will hit on day one
+
+The full index is `docs/README.md`. The entry points most relevant to a fresh project:
+
+- `docs/reference/models.md` (YAML) / `docs/reference/model-dsl.md` (DSL)
+- `docs/reference/presenters.md` (YAML) / `docs/reference/presenter-dsl.md` (DSL)
+- `docs/reference/permissions.md`
+- `docs/reference/types.md` — built-in field types and how to define custom ones
+- `docs/reference/menu.md` — top-nav configuration
+- `docs/reference/host-controller-integration.md` — when LCP needs to defer to host code
+- `docs/reference/engine-configuration.md` — initializer options (authentication mode, etc.)
+
+JSON schemas in `lib/lcp_ruby/schemas/` are authoritative for valid YAML keys when references and code disagree.