lcp 0.1.0

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

@@ -0,0 +1,176 @@
+---
+name: lcp-permissions
+description: Use when creating or modifying LCP Ruby permission YAML files in `config/lcp_ruby/permissions/`. Triggers on phrases like "add permissions", "role", "CRUD permissions", "field-level permissions", "record_rules", "field_overrides", "scope by user", "row-level security", "default_role", "permission for", "can/cannot edit", "deny", "_default permissions", "extends:", "coverage merge", "DB-backed permissions", "permission_source", "role_source", "lcp_role", "menu hidden".
+---
+
+> **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 — Permissions Authoring
+
+Permissions are role-based access control: who can perform CRUD, read/write which fields, execute which actions, see which records, access which presenters. One file per model: `config/lcp_ruby/permissions/<model>.yml`. Use `_default.yml` for fallback.
+
+> **First permissions file for a brand-new entity?** If the user is creating model + presenter + permissions + view group together for a new CRUD entity, prefer `rails generate lcp_ruby:entity NAME field:type ...` — it scaffolds a permissions file with all role keys copied from `_default.yml` (admin/owner roles get full CRUD, the rest get read-only). This skill is for **editing** that file afterwards (adding `record_rules`, `field_overrides`, narrowing scope per role, etc.). See `lcp-getting-started` "Fast path" or `docs/design/entity_generator.md`.
+
+## Before you write anything
+
+1. **Read the canonical reference**: `docs/reference/permissions.md` (~540 lines).
+2. For DB-backed (runtime-editable) permissions: `docs/reference/permission-source.md`.
+3. For DB-backed roles (validated at boot): `docs/reference/role-source.md`.
+4. For record_rule conditions: `docs/reference/condition-operators.md`.
+5. **JSON Schema**: `lib/lcp_ruby/schemas/permission.json`.
+
+## Critical: file structure
+
+Every permissions file **must** start with `permissions:` as the top-level key — omitting it raises `MetadataError` at boot.
+
+```yaml
+# WRONG — will fail
+model: deal
+roles:
+  default: { crud: [index, show] }
+
+# CORRECT
+permissions:
+  model: deal
+  roles:
+    default:
+      crud: [index, show]
+```
+
+`permissions.model` is either the model name, or `_default` for the global fallback. Resolution chain: model-specific → STI parent → `_default`.
+
+> **Per-model files coverage-merge with `_default` by default.** Missing entries in `roles:`, `field_overrides:`, and `record_rules:` are filled in from the `_default` permission entry automatically. Whole-entry replacement on collision (per-model `viewer` replaces `_default`'s `viewer` entirely; no key-by-key blending). To opt out and use full-shadow semantics, declare `extends: "none"` on the per-model file — appropriate for security boundaries (vault entries) and verticals with their own role taxonomy. `extends: "_default"` is the documentary-explicit form of the merge default; absence is identical. The validator forbids `extends:` and `inherits_from:` on the `_default` entry itself, and runs post-merge `default_role`/field/rule existence checks. See `docs/guides/permissions.md` for the full pattern catalog and `bundle exec rake lcp_ruby:permissions:resolve[<model>]` for diagnostic output with per-entry source attribution.
+
+## Minimal permission file
+
+```yaml
+permissions:
+  model: deal
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      fields: { readable: all, writable: all }
+      actions: all
+      scope: all
+    viewer:
+      crud: [index, show]
+      fields: { readable: all, writable: [] }
+      actions: { allowed: [] }
+      scope: all
+  default_role: viewer
+```
+
+## Role configuration
+
+| Key | Required | Notes |
+|-----|----------|-------|
+| `crud` | yes | Subset of `[index, show, create, update, destroy, restore, permanently_destroy]`. `edit→update`, `new→create` are auto-resolved. `restore` / `permanently_destroy` are for `soft_delete` models. |
+| `fields.readable` | no | `"all"` or array. `"all"` includes `custom_data` for custom-fields models. |
+| `fields.writable` | no | `"all"` or array. `[]` = read-only. |
+| `actions` | no | `"all"`, or `{ allowed: …, denied: … }`. `denied` wins. Built-in non-CRUD actions like `export` are gated here. |
+| `scope` | no | `"all"` (default) or one of 4 hash types — see below. |
+| `presenters` | no | Omit (or `"all"`) to allow all; array to restrict. Hides menu items too. |
+
+### Scope types (row-level security)
+
+```yaml
+# 1. Field equals value derived from current user
+scope: { type: field_match, field: owner_id, value: current_user.id }
+# value can be: current_user.id, current_user.<method>, or a literal
+
+# 2. Field IN array returned by a user method
+scope: { type: association, field: department_id, method: department_ids }
+
+# 3. Static WHERE
+scope: { type: where, conditions: { active: true } }
+
+# 4. Custom named scope on the model — receives current user
+scope: { type: custom, method: visible_to_user }
+# model defines: scope :visible_to_user, ->(user) { … }
+```
+
+## Field overrides
+
+Per-field overrides that **take precedence** over role `fields.readable`/`writable`:
+
+```yaml
+field_overrides:
+  salary:
+    readable_by: [admin, hr]
+    writable_by: [hr]
+  ssn:
+    readable_by: [admin]
+    masked_for: [sales_rep, viewer]   # display-level — UI shows ***
+```
+
+## Record rules
+
+Conditional CRUD denial per record. Condition uses any of the [12 condition operators](`docs/reference/condition-operators.md`).
+
+```yaml
+record_rules:
+  - name: closed_deals_readonly
+    condition: { field: stage, operator: in, value: [closed_won, closed_lost] }
+    effect:
+      deny_crud: [update, destroy]
+      except_roles: [admin]
+```
+
+Record rules also **automatically hide the corresponding action buttons** on index pages — no need to repeat the condition in `presenter.action.visible_when`.
+
+## Pitfalls & guidance
+
+- **`permissions:` wrapper is non-optional** — most-common mistake.
+- **Positioning + reorderable index** — for drag-and-drop reordering you need BOTH `update` in `crud` AND the position field in `fields.writable`. See `permissions.md` note for the editor-vs-manager pattern.
+- **Custom fields permissions** — for models with `custom_fields: true`, the virtual key `custom_data` toggles all custom fields at once. Individual custom field names also work (`fields.readable: [name, internal_notes]`). See `docs/reference/custom-fields.md#permissions`.
+- **`presenters:` controls both URL access AND menu visibility.** Restrict only when a model has multiple presenters and roles diverge — otherwise omit.
+- **Multiple roles** are unioned (most-permissive wins for crud/fields/actions/presenters; `actions.denied` is intersected). **Scope merging is fragile**: when multiple roles have non-`"all"` scopes only the first wins (warning logged) — use a `custom` scope to combine deliberately.
+- **`role_method` returns an array of strings** (default method: `lcp_role`). Single-role users return `["admin"]`, not `"admin"`.
+- **Action aliases**: a record rule with `deny_crud: [update]` also denies `edit`. Don't list both.
+- **`new`/`edit` need not be listed** in `crud` — only `create`/`update`. They're inferred.
+- **`format` regex strings** (in record_rules conditions) follow the same string-only rule as model validations.
+- **Audit:** every denial publishes an `ActiveSupport::Notifications` event `authorization.lcp_ruby` and writes a logger line — useful for host-app audit pipelines.
+
+## Three permission sources (per project's three-source principle)
+
+| Source | How |
+|--------|-----|
+| **YAML (default)** | Files in `config/lcp_ruby/permissions/`. |
+| **DB-backed** | `config.permission_source = :model` + a model conforming to the `target_model`/`definition`/`active` contract. Lookup: DB row by `target_model` → DB row `_default` → YAML fallback. See `permission-source.md`. |
+| **Host-provided roles** | `config.role_source = :model` validates role names against a DB registry; unknown roles in YAML are filtered + logged. See `role-source.md`. |
+
+## Advanced (one-line pointers)
+
+Stuff with its own dedicated reference / guide. **Browse `docs/feature-catalog.md` first** — sections `## Permissions`, `## Permission Source`, `## Role Source`, `## Groups`. Don't inline syntax; just open the relevant doc.
+
+- **Coverage merge with `_default` (`extends:`)** — per-model files merge missing roles / field_overrides / record_rules from the `_default` entry by default; `extends: "none"` opts out (security boundaries, separate role taxonomies); `extends: "_default"` is the explicit form. Whole-entry replacement on collision (per-model `viewer` replaces `_default.viewer` entirely). Decision tree, A1–A12 patterns, anti-patterns, and validator output reference are in the guide. → `docs/guides/permissions.md`, `docs/reference/permissions.md#extends`, `docs/design/permissions_default_role_coverage.md`.
+- **Compound conditions in `record_rules`** — `all:` / `any:` / `not:` for boolean logic on record-level conditions. → `docs/reference/condition-operators.md#compound-conditions`, `docs/design/advanced_conditions.md`.
+- **Collection conditions (has_many quantifiers)** — `quantifier: any/all/none` over an association in record_rules (e.g. "deny update if ANY child task is locked"). → `docs/reference/condition-operators.md#collection-conditions`.
+- **All 15 condition operators** — `eq`, `not_eq`, `present`, `blank`, `in`, `not_in`, `gt/gte/lt/lte`, `between`, `contains`, `starts_with`, `ends_with`, `matches` (regex, 1s timeout), `not_matches`. Same engine as `visible_when`, `item_classes`, workflow guards. → `docs/reference/condition-operators.md`.
+- **Groups** (organization layer over roles) — three sources: YAML (`config/lcp_ruby/groups.yml`), DB-backed (`group_source: :model`, generator: `lcp_ruby:groups`), host adapter (AD/LDAP). Group memberships + group-role mappings. Role resolution strategies: `direct_only`, `groups_only`, `merged` (default = union of direct + group-assigned). → `docs/reference/groups.md`, `docs/guides/groups.md`, feature-catalog `## Groups`.
+- **DB-backed roles (`role_source`)** — runtime role registry with `name`/`slug`/`active` contract, generator `lcp_ruby:role_model`, validates role names from permission YAML against the registry at boot (unknown roles filtered + logged). → `docs/reference/role-source.md`, `docs/guides/role-source.md`.
+- **DB-backed permissions (`permission_source: :model`)** — JSON definitions per `target_model` (with `_default` fallback), runtime editing through generated UI, validation on save (roles hash, crud array, fields all/array, etc.), cache invalidation. Lookup priority: DB row by model → DB row `_default` → YAML fallback. Permissions::Registry API. → `docs/reference/permission-source.md`, `docs/guides/permission-source.md`.
+- **Hierarchical authorization** — chain of org units, scope filtering by org unit ID, "see records of users I supervise"-style patterns. → `docs/guides/hierarchical-authorization.md`.
+- **Impersonation** — "view as role X" / "view as user Y" for support/debugging; `LcpRuby::Controller::Impersonation` overrides `effective_user` (must include before Authorization concern); inherits target user's groups. → `docs/guides/impersonation.md`, feature-catalog `## Groups → Groups with Impersonation`.
+- **Audit notifications** — every denial publishes `authorization.lcp_ruby` ActiveSupport::Notification with `{user_id, roles, action, resource, detail, ip}`. Subscribe in host app for custom audit pipelines. → permissions.md `## Audit Logging`.
+- **STI permission fallback chain** — model-specific → STI parent → `_default`. Same chain for DB-backed (DB rows checked first at each tier). → permissions.md `## model`.
+- **Positioning + reorderable interplay** — drag-and-drop reordering needs BOTH `update` in `crud` AND the position field in `fields.writable`. Lets you split editor (can edit + reorder) from manager (can edit only). → permissions.md `## fields` note.
+
+When in doubt about whether a capability exists at all → grep `docs/feature-catalog.md`.
+
+## After editing
+
+1. Run validation from the host app directory: `bundle exec rake lcp_ruby:validate`.
+   (Picked up automatically by the `lcp-validate` PostToolUse hook for files under `examples/*/config/lcp_ruby/`.)
+2. Useful inspection:
+   - `bundle exec rake lcp_ruby:permissions` — prints a permission matrix table for all models/roles, plus a `[merge]` / `[shadow]` coverage report against `_default`.
+   - `bundle exec rake "lcp_ruby:permissions:resolve[<model>]"` — prints the merged definition for one model with per-entry source attribution (`(per-model)` vs `(inherited from _default)`). Use when debugging "why does this role have these perms" — shows exactly which file each role/override/rule came from. Add a second arg for a role-narrowed `can?` matrix; pass `FORMAT=yaml`/`json` for tooling.
+3. Restart the dev server (permissions reload at boot — except DB-backed which auto-invalidate).
+4. Manually verify with a non-admin user that the right buttons / menu items are hidden.
+
+## Related skills / docs
+
+- Defining a model first → `lcp-model` skill.
+- Hiding/showing UI based on conditions → presenter `visible_when` (see `lcp-presenter` skill + `docs/guides/conditional-rendering.md`).
+- Hierarchical / org-unit authorization → `docs/guides/hierarchical-authorization.md`.
+- Groups (DSL/DB/host) → `docs/reference/groups.md`.

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

@@ -0,0 +1,194 @@
+---
+name: lcp-presenter
+description: Use when creating or modifying LCP Ruby presenter (UI) definitions in `config/lcp_ruby/presenters/` (either YAML `*.yml` or DSL `*.rb`). Triggers on phrases like "add a presenter", "form layout", "tabs", "steps wizard", "index column", "show page", "search filter", "saved filter", "custom action", "renderer", "input_type", "association_select", "nested_fields", "tree view", "tile view", "row_click", "visible_when", "disable_when", "record_alias", "dialog presenter".
+---
+
+> **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 — Presenter Authoring
+
+Presenters define the UI for a model: index (list), show (detail), form (create/edit), search (filters), and custom actions. One model can have multiple presenters (e.g. `deal` index, `deal_pipeline` kanban). Defined in `config/lcp_ruby/presenters/<name>.{rb,yml}`.
+
+> **First presenter for a brand-new entity?** If the user is creating the model + presenter + permissions + view group together for a new CRUD entity, prefer `rails generate lcp_ruby:entity NAME field:type ...` — it scaffolds a working starter presenter (index/show/form/search/sections/actions) along with the model, permissions, and view group atomically. The CLI grammar covers index/show columns, form sections, renderers, color_map, link, polymorphic, search blocks, and `--form-layout=tabs`. Editing the presenter afterwards is what this skill is for; bootstrapping it from nothing is what the generator is for. See `lcp-getting-started` "Fast path" or `docs/design/entity_generator.md`.
+
+## Before you write anything
+
+1. **Read the canonical reference** — pick one based on chosen format:
+   - DSL (`.rb`): `docs/reference/presenter-dsl.md` (~2200 lines)
+   - YAML (`.yml`): `docs/reference/presenters.md` (~3300 lines)
+   - JSON Schema: `lib/lcp_ruby/schemas/presenter.json`
+2. **Mirror the project's chosen format** — check neighbours in `config/lcp_ruby/presenters/`.
+3. **Read the model file first** — every field referenced in a presenter must exist on the model (or be an aggregate/association). The presenter's `model:` must match an existing model name.
+
+## Required structure
+
+Every presenter has a `model:` and a unique `name`/file. The four main blocks are optional but typical:
+
+```ruby
+define_presenter :deals do
+  model :deal
+  label "Deals"
+  slug "deals"          # URL slug; defaults to file name
+  icon "briefcase"      # navigation icon
+
+  index do … end        # list page
+  show  do … end        # detail page
+  form  do … end        # create + edit
+  search do … end       # search & filter sidebar
+
+  action :create,  type: :built_in, on: :collection
+  action :show,    type: :built_in, on: :single
+  action :edit,    type: :built_in, on: :single
+  action :destroy, type: :built_in, on: :single, confirm: true, style: :danger
+end
+```
+
+## Index (list page)
+
+Most-used methods: `column`, `default_view`, `views_available`, `default_sort`, `per_page`, `row_click`, `reorderable` (drag-handle ordering — needs model `positioning` + writable `position` field), `tree_view`, `tile`, `summary`, `item_classes` (conditional row classes), `includes`/`eager_load`.
+
+Column options: `link_to:`, `renderer:`, `options:`, `sort_field:`, `width:`, `sticky:`, `class:`, plus all the renderer options. Renderers include `:heading`, `:badge`, `:truncate`, `:boolean_icon`, `:progress_bar`, `:image`, `:avatar`, `:currency`, `:percentage`, `:number`, `:date`, `:datetime`, `:relative_date`, `:email_link`, `:phone_link`, `:color_swatch`, `:link`, `:tag_list`, `:collection` (sub-list), `:html` (Markdown), and custom renderers (`docs/guides/custom-renderers.md`).
+
+**Grouped query mode** (analytics / pivot): set `query_mode :grouped`, then `group_by [...]`, optional `having`, optional `limit`, and define columns referencing aggregates. See `presenter-dsl.md#grouped-query-mode`.
+
+## Show (detail page)
+
+Wraps fields in `section "Title", columns: 1..4 do … end`. Special section types:
+- `custom_section "Title", partial: "..."` — host-app partial.
+- `association_list "Title", association: :tasks, …` — list of related records with optional `link_through:` (jump through join models).
+- `nested_fields` — same as in `form`, render-only on show.
+
+Sections support `visible_when:`/`disable_when:` (condition hash, see `docs/guides/conditional-rendering.md`).
+
+**i18n keys for sections:** all section-creating methods accept `key:` to decouple the i18n lookup key from the human-readable label — `section "Detaily", key: "details"` looks up `lcp_ruby.presenters.<presenter>.sections.details` instead of parameterizing the literal. See `presenter-dsl.md` §"Section titles & i18n".
+
+## Form (create/edit)
+
+Layout modes via `layout :flat` (default), `layout :tabs`, or `layout :steps` (client-side wizard). For server-side multi-step processes, use a separate `stepper:` block (DB-backed `current_step`, per-step save). See showcase examples.
+
+Each `section` accepts `columns:`, `responsive:`, `collapsible:`, `collapsed:`, `description:`, plus conditional rendering. Inside, use `field`, `divider label: ...`, `info "..."`, or `nested_fields` (rows of structured items, sourced from `association:` or `json_field:` ± `target_model:` for inline JSON sub-records).
+
+Field options: `input_type:` (`:select`, `:number`, `:text`, `:textarea`, `:date_picker`, `:association_select`, `:multi_select`, `:file_upload`, `:checkbox`, `:rich_text`, …), `placeholder:`, `autofocus:`, `prefix:`/`suffix:`, `col_span:`, `hint:`, `readonly:`, `default:`, `visible_when:`/`disable_when:`, `input_options:` (widget-specific — see DSL §`input_options`), `options:` (renderer formatting), `hidden_on:` (responsive).
+
+Common `input_options` patterns (read DSL §888 for the full menu):
+- Enum select with role filtering: `exclude_values:` / `include_values:`
+- Association select: `scope:`, `sort:`, `label_method:`, `include_blank:`, `group_by:`, `scope_by_role:`
+- Cascading selects: `depends_on: { field:, foreign_key: }`
+- Multi-select for `has_many :through`: `input_type: :multi_select, input_options: { association: :tags, max: 5 }`
+- Attachments: `preview:`, `drag_drop:`, `direct_upload:`
+
+## Search
+
+`searchable_fields :a, :b, …` (full-text fields), `placeholder`, `auto_search`, `debounce_ms`, then **filters** (saved-filter chips) and **predefined_filters** (parameterised filters mapped to model scopes). See `presenter-dsl.md#search-configuration`.
+
+## Actions
+
+Two kinds:
+- `type: :built_in` — `:show`, `:edit`, `:create`, `:destroy`, `:export`. Permission via `PermissionEvaluator.can?`.
+- `type: :custom` — points to an action class (`action_class: "MyAction"`) or `dialog:`. Permission via `can_execute_action?`. See `docs/guides/custom-actions.md` and `docs/guides/batch-actions.md`.
+
+Actions can be `on: :single` (per-record button), `on: :collection` (toolbar), or `on: :batch` (multi-select toolbar). Options include `confirm:`, `style:` (`:default` / `:primary` / `:danger`), `icon:`, `label:`, `visible_when:`, `position:` (`:left`/`:right` for top toolbar).
+
+## Other top-level options
+
+- `record_alias` — friendly URL aliases (`/preferences/me`, `/issues/last`). Resolution strategies: `current_user`, `field_on_user`, `scope`. See `presenter-dsl.md#record_alias`.
+- `dialog true` — marks the presenter as embeddable in a modal (used by other presenters' actions). See `docs/guides/dialogs.md`.
+- `embeddable true` — allow embedding inside other pages / view groups.
+- `read_only true` — disables all create/update/destroy UI regardless of permissions.
+- `redirect_after :index` / `:show` — where to land after a successful save.
+- `menu_position 10` — **deprecated.** Order hint for the auto-created view group (single-presenter models without explicit view-group YAML). Still works in v1 but boot emits a one-time info log when used. Prefer writing `config/lcp_ruby/menu.yml` (or generating the entity with `--menu=...`) for explicit placement. See `presenters.md#menu_position`.
+- **Multi-presenter models — `default true` + `link_presenter:`.** When a model has multiple presenters (e.g. `contact_full`, `contact_short`, `contact_tiles`), `link: true` / `link_to: :show` from another presenter must pick one. Mark the canonical with `default true` (per-model) — exactly one default per model. Override per-link with `column :name, link: true, link_presenter: "contacts-short"`. The validator rejects ambiguous configurations (multiple presenters + no `default` + no `link_presenter:`) at boot with both options spelled out. See `presenters.md#multiple-presenters-per-model`.
+
+## Pitfalls & guidance
+
+- **Field references must exist on the model.** Typos surface only at runtime/validate. Always run `lcp_ruby:validate` after changes.
+- **`reorderable true`** on the index requires model `positioning` AND `position` in the role's `fields.writable` (see `permissions.md`). Without both, no drag handles.
+- **Eager loading.** Add `includes :company, :tags` (or `eager_load`) when columns reference associations — otherwise N+1. The form auto-detects `nested_fields`. See `docs/guides/eager-loading.md`.
+- **Conditional rendering.** Both `visible_when` and `disable_when` accept either field-value hashes (`{ field: :status, operator: :eq, value: "active" }`) or service hashes (`{ service: :persisted_check }`). Server evaluates initial state; client re-evaluates on field change.
+- **`nested_fields` data source** — exactly one of `association:` or `json_field:`. With `json_field:` + `target_model:`, field metadata comes from a virtual model (`abstract: true`, `data_source: :virtual`).
+- **`column` vs `field`** — `column` is for index tables (compact, sortable). `field` is for show/form sections (wider, with widgets).
+- **Tabs vs Steps**: `layout :tabs` is for grouping fields visually; `layout :steps` is a client-only wizard (no server state between steps). For real multi-step processes use a `stepper:` block (DB-backed). See user memory `multi_step_forms.md`.
+- **Sections in show vs form** share the same partial — features available in one are usually available in the other.
+
+## Advanced (one-line pointers)
+
+Stuff with its own dedicated reference / guide. **Browse `docs/feature-catalog.md` first** — most of these have a dedicated section there. Don't inline syntax; just open the relevant doc.
+
+- **Composite pages** (semantic multi-zone layouts) — `area: main|tabs|sidebar|below`, master-detail (`selection: single`), `record_source` for one-record zones, `scope_context` for record-scoped widgets, conditional zone visibility, dialog reload (one or many zones), Turbo-frame lazy tab loading, URL bookmarkability `?tab=`, zone endpoints, zone filters (none/quick/full), zone width grid (1–12). → `docs/reference/pages.md`, `docs/guides/composite-pages.md`, feature-catalog `## Composite Pages` + `## Master Detail`. Index-level composite (`index_presenter:` override) too.
+- **View groups** (`config/lcp_ruby/views/`) — multiple presenters for the same model, switcher UI, primary view, per-role view filtering. → `docs/reference/view-groups.md`, `docs/guides/view-groups.md`.
+- **View slots** — render-anywhere extension points (e.g. auto `approval_status` slot under show sections). → `docs/reference/view-slots.md`, `docs/guides/view-slots.md`.
+- **Dialogs** — `dialog: true` on presenter + `?_dialog=1`, dialog routing, success behavior (`close`/`reset`/`reload_zone`/`reload_zones`), confirm-then-action pattern. → `docs/reference/dialogs.md`, `docs/guides/dialogs.md`.
+- **Custom actions / batch actions** — `type: custom` with `action_class:` or `dialog:`, `on: :batch` for multi-select toolbars, action visibility/style/confirm. → `docs/guides/custom-actions.md`, `docs/guides/batch-actions.md`.
+- **Form-submit actions (pipeline)** — multiple submit buttons, ordered pipeline (e.g. `[:save, { transition: :submit }]`), `set_fields` injection, per-button `redirect:`, `only_on: :create/:update`, role-restricted buttons, dialog `dialog_behavior`, deferred event dispatch, double-submit protection, form action i18n (4-level lookup), overflow-to-dropdown. → `docs/guides/action-buttons.md`, `docs/design/form_submit_actions.md`, feature-catalog `## Form Submit Actions`.
+- **Grouped query mode** (`query_mode: :grouped`) — GROUP BY with aggregate columns (count/sum/avg/min/max), date-period grouping, HAVING, multi-column group_by, association dot-path JOINs, row_click drill-down (`:filter`, `target:`), tree-of-grouped-and-flat in view groups. → `docs/reference/presenter-dsl.md#grouped-query-mode`, feature-catalog `## Grouped Query`.
+- **Tiles layout** (`layout: :tiles` + `tile do … end`) — card grid, columns/responsive, title/subtitle/description fields, summary bar, sort dropdown, per-card action style, dot-paths, view group integration, inheritance. → `docs/guides/tiles.md`, `docs/design/tiles_view.md`.
+- **Tree view** (`tree_view: true`, `default_expanded`, `reparentable`) — for models with `tree`. → presenters.md, `docs/guides/tree-structures.md`.
+- **Dashboards** — KPI cards, multi-zone widgets (`type: widget`, `aggregate: count/sum/avg`), Mermaid `workflow_graph`, error log widget. → `docs/guides/dashboards.md`, `docs/reference/pages.md`.
+- **Selectbox advanced** — Tom Select (search, allow_create, multi), tree_select for hierarchy, cascading (depends_on, 2/3-level), role-based scope (`scope_by_role:`), inline create. → `docs/guides/selectbox.md`, feature-catalog `## Input Types`.
+- **Input types** (full list) — `array_input` (chip), `radio_group`, `rich_text_editor` (Trix), `slider`, `toggle`, `tree_select`, `number` w/ prefix/suffix, JSON inline editor (`json_editor`). → `docs/reference/presenters.md#input-types`, feature-catalog `## Input Types`.
+- **Custom renderers** — host-app classes in `app/lcp_renderers/` registered via service registry; full `display-types` inventory. → `docs/guides/custom-renderers.md`, `docs/guides/display-types.md`.
+- **Rendering extension points** — places where host-app partials/renderers plug in (custom_section, partial-based field, view slots). → `docs/guides/rendering-extension-points.md`.
+- **Item classes (row styling)** — conditional CSS classes per row using all 15 condition operators (`eq`, `gt`, `in`, `present`, `matches` regex with 1s safety, `service:` …); cross-layout (table/tiles/tree); 7 built-in utility classes (`lcp-row-danger/warning/success/info/muted/bold/strikethrough`). → presenters.md `## item_classes`, `docs/design/row_styling.md`.
+- **Predefined filters / saved filters** — scope-based filter tabs above index (presenter); user-saved filter presets (DB-backed, optional generator). → presenters.md, `docs/design/saved_filters.md`.
+- **Pagination footer** — `per_page_options`, `show_record_count`, `pagination_ends`, grouped/tree counts, sticky footer. → presenters.md, `docs/design/pagination_footer.md`.
+- **Presenter inheritance (DSL)** — `inherits: :other_presenter` then override specific blocks. Useful for tiles vs index variants. → `docs/reference/presenter-dsl.md#inheritance`.
+- **Record aliases** (`record_alias`) — friendly URLs (`/preferences/me`, `/issues/last`); resolution strategies `current_user`, `current_user-on-self` (no `field:` on user model), `field_on_user`, `scope`. URL preserved across edit/zones. → `docs/guides/record-aliases.md`, `docs/design/record_aliases.md`.
+- **Export / Import** — `export` action + export profiles (`docs/reference/export.md`); two-phase import dialog with mapping, profiles, strategies (create_only/update_only/upsert/skip_existing), nested has_one, undo, error CSV (`docs/reference/import.md`, `docs/guides/import.md`).
+- **Field/Column link through join models** — `link_through: true` on association lists or columns lets you jump through a join model to the real entity. → `docs/design/show_field_link_through.md`.
+- **Conditional rendering details** — operator reference, compound `all`/`any`/`not`, service conditions, collection (has_many quantifier) conditions. → `docs/reference/condition-operators.md`, `docs/guides/conditional-rendering.md`.
+- **`empty_value`, `copyable: true`, sticky table header, info blocks, dividers, section descriptions, view descriptions** — presenters.md (search the keyword).
+
+When in doubt about whether a capability exists at all → grep `docs/feature-catalog.md`.
+
+## After editing
+
+1. Run validation from the host app directory: `bundle exec rake lcp_ruby:validate`.
+   (Picked up automatically by the `lcp-validate` PostToolUse hook for files under `examples/*/config/lcp_ruby/`.)
+2. Restart the dev server (presenters reload at boot only).
+3. For UI-changing edits, open the page in the browser. Per project CLAUDE.md, type-checking ≠ feature correctness — actually click through happy path + 1-2 edge cases.
+4. Showcase app → `http://127.0.0.1:3000/showcase/`, login `admin@example.com` / `password123`.
+
+## i18n principle
+
+**No user-visible literals in DSL / YAML.** Presenter `label`, `description`, `section "X"`, custom action `label:`, and form-submit `submitting_label:` all resolve through `I18n.t` with humanize as fallback. The translation lives in `config/locales/<locale>.yml`, not in the presenter definition.
+
+Authoring pattern:
+
+```ruby
+# config/lcp_ruby/presenters/grades.rb
+define_presenter :grades do
+  model :grade
+  show do
+    section "Grade Details", columns: 2 do  # locale key:
+      field :value                          # lcp_ruby.presenters.grades.sections.grade_details
+    end
+  end
+  action :archive, type: :custom, label: "Archive"  # lcp_ruby.actions.form.archive
+end
+```
+
+```yaml
+# config/locales/cs.yml
+cs:
+  lcp_ruby:
+    presenters:
+      grades:
+        sections:
+          grade_details: "Detail známky"
+    actions:
+      form:
+        archive: "Archivovat"
+```
+
+Tier 2 surfaces (column / filter / view-group labels) have no Tier 1 i18n key today and are flagged separately (`direct_render_label`, default `:warning`). Cleanup: remove the literal so the underlying field's translation applies, or accept the warning.
+
+Verify with `bundle exec rake lcp_ruby:i18n_check`. See `docs/reference/i18n_check.md`.
+
+## Related skills / docs
+
+- Model not yet defined → `lcp-model` skill.
+- Permission for who sees what → `lcp-permissions` skill.
+- Custom renderers → `docs/guides/custom-renderers.md`.
+- Dashboards / tiles → `docs/guides/dashboards.md`, `docs/guides/tiles.md`.
+- Composite pages (multiple presenters on one page) → `docs/guides/composite-pages.md`.
+- Dialogs → `docs/guides/dialogs.md`.