lcp 0.1.0

data/docs/reference/menu.md

@@ -0,0 +1,985 @@
+# Menu Reference
+
+The menu system controls the navigation layout of your LCP Ruby application. It supports top bar, sidebar, or combined layouts with dropdown grouping, custom links, separators, and role-based visibility.
+
+## Configuration
+
+```ruby
+LcpRuby.configure do |config|
+  config.menu_mode = :auto    # :auto (default) or :strict
+end
+```
+
+| Mode | No menu.yml | menu.yml exists |
+|------|------------|-----------------|
+| `:auto` | Auto-generate nav from view groups | Use menu + auto-append unreferenced view groups |
+| `:strict` | Raises `MetadataError` | Use menu only (sole source of truth) |
+
+### Auto-append transparency log
+
+In `:auto` mode, when the loader auto-appends view groups that aren't explicitly referenced in `menu.yml`, it emits a single info-level log line at boot:
+
+```
+[LcpRuby] Auto-appended 4 view groups to top_menu: alpha, bravo, charlie, delta.
+Add them to config/lcp_ruby/menu.yml for custom ordering or dropdown placement,
+or set `navigation: { auto_append: false }` on the view group to hide it from the menu.
+```
+
+The log fires only when at least one view group was auto-appended. It is silent when `menu.yml` already references every navigable view group, and never fires in `:strict` mode (no auto-append runs).
+
+The opt-out is per view group: set `navigation: { auto_append: false }` (in `config/lcp_ruby/views/<name>.rb`/`.yml`) on infrastructure view groups (e.g. `audit_logs`, `job_executions`) that should stay accessible via URL but invisible in navigation.
+
+## File Location
+
+```
+config/lcp_ruby/menu.yml
+```
+
+### Entity Generator Markers
+
+Files seeded by `rails generate lcp_ruby:install` (or `lcp new`) include single-line **insertion markers** for the entity generator's `--menu=...` flag:
+
+```yaml
+menu:
+  top_menu:
+    - view_group: items
+    # lcp:menu top  # entity generator marker - do not edit/delete
+  sidebar_menu:
+    # lcp:menu sidebar  # entity generator marker - do not edit/delete
+```
+
+`rails generate lcp_ruby:entity Student … --menu=ROOT` inserts the new `- view_group: student` entry **immediately above** the matching marker. Dropdown markers (`# lcp:menu top > "School"`) are added automatically when `--menu=NewLabel` auto-creates a dropdown.
+
+**Don't delete markers.** Editing other lines (reordering, adding labels, restructuring) is fine — only the marker comment lines themselves need to stay intact for future generator runs. Apps generated before this feature can opt in by pasting the marker manually (see [`docs/guides/menu.md`](../guides/menu.md) for the `--menu` walkthrough).
+
+The install generator's `--menu-layout=top|sidebar|both` (default `both`) seeds the corresponding section blocks + markers. `lcp new` exposes the same flag and asks during the interactive wizard.
+
+## YAML Schema
+
+The file **must** use `menu:` as the top-level YAML key, and **at least one** of `top_menu` or `sidebar_menu` must be present. Omitting both raises `MetadataError` at boot. Other key names (e.g., `items`, `nav_menu`) are not recognized.
+
+```yaml
+menu:
+  top_menu:        # Top bar navigation items
+    - ...
+  sidebar_menu:    # Sidebar navigation items
+    - ...
+```
+
+> **Minimal valid menu file:**
+> ```yaml
+> menu:
+>   top_menu: []
+> ```
+
+**Layout mode** is determined by which keys are present:
+
+| Keys present | Layout |
+|-------------|--------|
+| Only `top_menu` | Top bar |
+| Only `sidebar_menu` | Sidebar |
+| Both | Top bar + sidebar |
+
+## Menu Item Types
+
+Each item in the menu arrays must be one of four types, determined by which key is present:
+
+### View Group Reference
+
+References an existing view group. Label, icon, and slug are resolved from the view group's primary presenter.
+
+```yaml
+- view_group: deals
+```
+
+Optional overrides:
+
+```yaml
+- view_group: deals
+  label: "My Deals"          # Override resolved label
+  icon: dollar               # Override resolved icon
+  visible_when:
+    role: [admin, manager]
+  position: bottom            # Pin to sidebar bottom
+```
+
+### Group (Dropdown / Collapsible Section)
+
+Container for nested items. Renders as a dropdown in top bar, collapsible section in sidebar.
+
+```yaml
+- label: "CRM"
+  icon: briefcase
+  children:
+    - view_group: deals
+    - view_group: companies
+    - separator: true
+    - label: "Reports"
+      url: /crm/reports
+```
+
+**Required:** `label`
+
+### Custom Link
+
+Link to an external or host app URL.
+
+```yaml
+- label: "Dashboard"
+  icon: home
+  url: /dashboard
+```
+
+**Required:** `label`, `url`
+
+**HTTP method.** GET-style URLs render as `<a>` and integrate with Turbo Drive (SPA-style navigation). For non-GET destinations (sign-out via DELETE, host actions via POST/PUT/PATCH) add `method:` and the framework renders a `button_to` form with CSRF token + Rails `_method` override:
+
+```yaml
+- url: "/users/sign_out"
+  method: delete
+  label: "Sign out"
+  icon: log-out
+```
+
+`method:` accepts `get`, `post`, `put`, `patch`, `delete` (case-insensitive). Invalid on `view_group:`, `children:` (groups always GET-equivalent), and `separator:`. See [Method-Aware Rendering](#method-aware-rendering).
+
+### Presenter Link (slug-rename-resilient)
+
+Resolve the URL through an LCP presenter's `record_alias` and action contract instead of hardcoding it. When the host renames the presenter slug, the link still works.
+
+```yaml
+- presenter: my_settings
+  alias: me                    # resolved via record_aliases on the presenter
+  action: edit                 # built-in CRUD or a custom action name
+  label: "My Settings"
+  icon: settings
+```
+
+**Keys:**
+
+| Key | Required | Notes |
+|---|---|---|
+| `presenter` | yes | Presenter slug as declared in `config/lcp_ruby/presenters/`. |
+| `action` | yes | Built-in (`show` / `edit` / `new` / `destroy` / `index`) or a custom action name declared on the presenter under `actions: collection:` / `actions: single:` / `actions: batch:` / `actions: form:`. |
+| `alias` | for `show` / `edit` / `destroy` and single-record custom actions | Record alias declared under the presenter's `record_aliases:`. Omit for `index` / `new` / collection-context custom actions. |
+| `defaults` | no | Extra query parameters forwarded to the resolved URL (see [Path Templating](#path-templating)). |
+
+**Default HTTP method:** `:get` for show/edit/new/index, `:delete` for destroy, `:post` for custom actions. Override with `method:`.
+
+**Permission gating.** `presenter:` items run the same `can_access_presenter?` check as the presenter toolbar plus `can?(action)` for built-ins or `can_execute_action?(action)` for custom actions. Items the current user cannot execute are hidden.
+
+See [Presenter Resolver](#presenter-resolver) for URL shape per action type.
+
+### Computed Item (`provider:`)
+
+Compute the whole item (or a sibling array of items) at render time. Use for "Current organization" links, multi-tenant switchers, "recently visited" lists, or anything that depends on runtime data.
+
+```yaml
+- provider: current_org_link
+  options: { variant: compact }
+```
+
+The provider class is registered under the `menu_items` services category at `app/lcp_services/menu_items/<name>.rb` (namespaced `LcpRuby::HostServices::MenuItems::<Name>`). It implements `.call(options:, current_user:, request_context:)` and returns:
+
+| Return | Behaviour |
+|---|---|
+| Hash | Single item — replaces the YAML position. |
+| Array of hashes | Sibling expansion at the YAML position. |
+| `nil` or `[]` | Item silently collapses (no rendering). |
+
+The returned hash uses standard MenuItem keys (`url`, `label`, `icon`, `method`, `badge`, …); `provider:` and `panel_provider:` chains are forbidden inside the return.
+
+See [Computed Items](#computed-items-provider).
+
+### Custom Renderers (`render:` / `render_panel:` / `widget:`)
+
+Three escape hatches for items whose visible content cannot be expressed by the standard `<icon> <label>` shape.
+
+| Key | Replaces | Wrapper element |
+|---|---|---|
+| `render:` | the inner HTML of the link/button **trigger** | framework keeps `<a>` / `<button_to>` / dropdown-toggle wrapper |
+| `render_panel:` | the inner HTML of a `:group`'s **dropdown panel** | framework keeps the `<div class="lcp-nav-dropdown-menu">` wrapper |
+| `widget: true` | the entire item — drops the `<a>` / `<button_to>` wrapper | bare `<li class="lcp-menu-widget">` |
+
+Path is `<namespace>/<name>` and resolves to `app/views/<namespace>/menu_renderers/_<name>.html.erb`. The framework ships two renderers:
+
+- `lcp_ruby/user_menu` — avatar + display name + caret (corner user-menu trigger).
+- `lcp_ruby/user_menu_panel` — profile-card header + items list (corner user-menu panel).
+
+```yaml
+# Combined: custom trigger + custom panel
+- render: lcp_ruby/user_menu
+  render_panel: lcp_ruby/user_menu_panel
+  position: right
+  aria_label: "User menu"
+  children:
+    - presenter: my_settings
+      alias: me
+      action: edit
+    - url: "{lcp_ruby.destroy_user_session_path}"
+      method: delete
+      label: "Sign out"
+
+# Widget: search box that needs to drop the wrapper to receive clicks
+- widget: true
+  render: my_app/quick_search
+  aria_label: "Search the app"
+  position: right
+```
+
+Provided locals to render partials:
+
+| Partial | Locals |
+|---|---|
+| `render:` (trigger) | `item:` (the MenuItem), `disabled:` (boolean) |
+| `render_panel:` | `item:` (the parent group), `items:` (already filtered children — call `panel_items_for(item)` from inside) |
+| `widget:` | `item:`, `disabled:`, `bare:` (boolean — true when nested inside a panel via `render_menu_item`) |
+
+See [Custom Renderers](#custom-renderers).
+
+### Separator
+
+Visual divider between items.
+
+```yaml
+- separator: true
+```
+
+### Icon-Only Items
+
+Render an item with only an icon (no visible label) — typical for a notifications bell, help link, or compact secondary entry. Boot validation requires every item to render either a label or an icon, and icon-only items must carry an `aria_label` for screen-reader access:
+
+```yaml
+# Notifications bell — view_group keeps slug-based active state and the
+# usual presenter permission check.
+- view_group: notifications
+  icon: bell
+  label: false                  # opt out of the presenter's label fallback
+  aria_label: "Notifications"
+  position: right
+  badge:
+    provider: unread_notifications
+    renderer: count_badge
+
+# Plain icon-only link to a host route.
+- url: /help
+  icon: life-buoy
+  aria_label: "Help"
+  position: right
+```
+
+**Required:** `icon` (or a view_group whose presenter supplies one) and `aria_label` (or `aria_label_key`).
+
+For `view_group` items, omit `label:` to keep the presenter's label as the fallback; set `label: false` to suppress that fallback and go icon-only. For `link`/`group` items, just omit `label:`.
+
+The `aria_label` value goes through i18n auto-lookup at `lcp_ruby.menu.aria.<slug>` (sub-namespace prevents collisions with `lcp_ruby.menu.<slug>` for the same literal). Use `aria_label_key:` for an explicit key.
+
+The icon placeholder is always emitted with `aria-hidden="true"` so the icon never leaks into the accessible name. The link/button takes its accessible name from either the visible label or `aria_label` — never from the icon.
+
+#### Icon rendering
+
+The `icon:` value is a [Lucide](https://lucide.dev/icons/) icon name (kebab-case: `bell`, `life-buoy`, `chart-bar`, …). The platform layout ships Lucide as a vendored asset and replaces every `<i data-lucide="…">` placeholder with an inline SVG on first paint and on every Turbo navigation.
+
+Markup the helper emits:
+
+```html
+<i data-lucide="bell" class="lcp-menu-icon" aria-hidden="true"></i>
+```
+
+After Lucide replacement:
+
+```html
+<svg class="lucide lucide-bell lcp-menu-icon" aria-hidden="true">…</svg>
+```
+
+The SVG inherits the link's text colour via `currentColor` and is sized via the `.lcp-menu-icon` CSS hook (defaults: `1rem` in top nav, `0.9rem` in dropdowns, `1.05rem` in sidebar). Hosts override the icon size by re-declaring `.lcp-menu-icon` width/height in their own stylesheet.
+
+To use a different icon set (Heroicons, FontAwesome, Material Symbols, …), override the `menu_item_icon_html` helper in your host application — its single responsibility is to map a string identifier to the icon library's preferred markup.
+
+See [`docs/design/menu_icon_only_items.md`](../design/menu_icon_only_items.md) for the full design.
+
+## Optional Keys
+
+These keys can be added to any item (except separators):
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `label` | string \| `false` | Display text. Omit for `link`/`group` to render icon-only. `false` is an explicit opt-out from the view_group presenter fallback (see [Icon-Only Items](#icon-only-items)). |
+| `label_key` | string | Explicit i18n key for the label (highest priority, see [Label Resolution](#label-resolution)) |
+| `icon` | string | Icon name (resolved from presenter for view groups). Always rendered with `aria-hidden="true"`. |
+| `aria_label` | string | Accessible name. Required when no visible label renders. Auto-looks up `lcp_ruby.menu.aria.<slug>`. |
+| `aria_label_key` | string | Explicit i18n key for `aria_label`. Mirrors `label_key` for `label`. |
+| `method` | string | HTTP method — `get`/`post`/`put`/`patch`/`delete`. Non-GET renders as `button_to`. Invalid on view_group/group/separator. See [Method-Aware Rendering](#method-aware-rendering). |
+| `defaults` | object | Extra query params forwarded to the resolved URL. String values support [path-template tokens](#path-templating). |
+| `visible_when` | object | Conditional visibility — full ConditionEvaluator surface (see [Conditional Visibility](#conditional-visibility)) |
+| `disable_when` | object | Renders the item visible but in a disabled (greyed-out, non-clickable) state. Same shape as `visible_when:`. See [Disabled State](#disabled-state). |
+| `position` | string | `"bottom"` pins item to sidebar bottom; `"right"` right-aligns item in top bar (see [Position](#position)) |
+| `badge` | object | Dynamic badge display (see [Badges](#badges) section) |
+| `options` | object | Free-form options hash forwarded to a `provider:` or `panel_provider:` (kwarg `options:`). Use to parameterize one provider with different configurations. |
+
+### Label Resolution
+
+Menu item labels are resolved in this order (first match wins):
+
+1. **`label_key`** — explicit i18n key: `I18n.t(label_key, default: label)`
+2. **`label`** — auto-lookup via `I18n.t("lcp_ruby.menu.<parameterized_label>", default: label)`. E.g., label `"HR Turnover"` looks up key `lcp_ruby.menu.hr_turnover`.
+3. **View group fallback** — for view group items without a label, the primary presenter's `resolved_label` is used (which itself resolves via `lcp_ruby.models.<model>.other`).
+
+See [i18n Reference](i18n.md#menu-labels) for locale file examples.
+
+### Position
+
+The `position: bottom` key pins menu items to the bottom of the sidebar. Multiple items with `position: bottom` stack in definition order. This is typically used for settings and logout links:
+
+```yaml
+- label: "Settings"
+  icon: settings
+  url: /settings
+  position: bottom
+- label: "Log out"
+  icon: log-out
+  url: /logout
+  position: bottom
+```
+
+In top bar layout, `position: bottom` has no effect — items render in definition order.
+
+**Top bar right alignment.** In `top_menu`, `position: right` moves a top-level item to a right-aligned zone after a flex spacer. Multiple right-aligned items render in YAML definition order. Use for profile, settings, log out, notifications, and similar secondary entries:
+
+```yaml
+top_menu:
+  - view_group: dashboard
+  - view_group: reports
+  - url: /profile/me
+    label: "Profile"
+    icon: user
+    position: right
+  - label: "Log out"
+    icon: log-out
+    url: /logout
+    position: right
+```
+
+**Semantics per menu layout:**
+
+| Layout | `position: "bottom"` | `position: "right"` |
+|--------|----------------------|---------------------|
+| `top_menu` | ignored | **right-aligned** |
+| `sidebar_menu` | pinned to footer | ignored |
+
+Only the diagonal combinations (`sidebar + bottom`, `top + right`) are meaningful; the other two are silently ignored. `position` applies only to **top-level** items — dropdown children ignore it. Separators support `position: right` and join the right-aligned zone.
+
+## Nested Sub-Groups
+
+Groups can contain sub-groups (one additional level of `children:`) for organizing large menus. Maximum nesting depth is **2 levels** of `children:`. Deeper nesting raises a `MetadataError` at boot.
+
+```yaml
+- label: "Features"
+  children:
+    - view_group: basic_fields
+    - separator: true
+    - label: "Search & Filters"       # Sub-group (level 2)
+      children:
+        - view_group: advanced_search
+        - view_group: saved_filters
+    - label: "Workflow"                # Sub-group (level 2)
+      children:
+        - view_group: workflows
+        - view_group: approval_tasks
+```
+
+**Top menu:** Sub-groups render as flyout submenus that open to the right on hover. If the flyout would overflow the viewport, it flips horizontally (opens left) or vertically (aligns bottom). Keyboard users can Tab into submenus via `:focus-within`. Sub-group labels have `aria-haspopup="true"`.
+
+**Sidebar:** Sub-groups render as nested collapsible sections with additional indentation. Click to expand/collapse (same interaction as top-level groups).
+
+**Active state:** propagates through nested sub-groups — if any item inside a sub-group matches the current slug, both the sub-group and its parent group are highlighted.
+
+**Empty sub-group hiding:** if all children of a sub-group are filtered out by `visible_when` constraints, the sub-group itself is hidden (same as top-level groups).
+
+Sub-groups support all the same features as top-level groups: `visible_when`, `badge`, and child types (`view_group`, `link`, `separator`).
+
+## Conditional Visibility
+
+Use `visible_when` to gate menu items. The condition is evaluated through `LcpRuby::ConditionEvaluator` with **no record context** — menu items are global navigation, so only conditions that don't need a record are supported:
+
+| Shape | Supported? | Notes |
+|-------|-----------|-------|
+| `service:` (+ optional `params:`) | ✅ | Full kwargs via `params:`. Built-in: `current_user_role`. |
+| `all:` / `any:` / `not:` (compound) | ✅ | Recurses into children with the same restrictions. |
+| `field:` | ❌ | Rejected by validator — needs a record (menu has none). |
+| `collection:` | ❌ | Rejected by validator — needs a record. |
+| `role: [...]` (legacy shorthand) | ❌ | Rejected by validator with migration hint. |
+
+### Built-in: `current_user_role`
+
+Restrict by role using the canonical service form:
+
+```yaml
+- label: "Admin"
+  visible_when:
+    service: current_user_role
+    params:
+      in: [admin]
+  children:
+    - view_group: users
+    - view_group: settings
+```
+
+The user's role is read via `LcpRuby.user_roles(user)`, which honours `Configuration#role_method` (default: `:lcp_role`). The user model contract is "respond to `role_method` returning a string or array of strings" — works with Devise, host User models, and `:none`/`:built_in`/`:external` auth modes.
+
+`params:` accepts:
+- `in:` — list of allowed roles (visible if user has *any*).
+- `not_in:` — list of denied roles (visible if user has *none*).
+
+### Compound conditions
+
+Combine multiple checks with `all:`/`any:`/`not:`:
+
+```yaml
+- label: "Reports"
+  visible_when:
+    any:
+      - service: current_user_role
+        params: { in: [admin] }
+      - service: feature_flag           # host-registered service
+        params: { flag: reports_beta }
+```
+
+```yaml
+- label: "Public"
+  visible_when:
+    not:
+      service: current_user_role
+      params: { in: [guest] }
+```
+
+### Other access checks
+
+View group items additionally check **presenter accessibility** via the permission system, regardless of `visible_when`. A user without `index` CRUD on the model never sees the item, even if the role gate would pass.
+
+### Migration from legacy `role:` shorthand
+
+If you used the pre-upgrade form:
+
+```yaml
+# old (rejected by validator)
+visible_when:
+  role: [admin]
+```
+
+Rewrite as:
+
+```yaml
+visible_when:
+  service: current_user_role
+  params:
+    in: [admin]
+```
+
+See [`condition-operators.md`](condition-operators.md) for the full condition syntax reference, and [`engine-configuration.md#role_method`](engine-configuration.md#role_method) for the user-role contract.
+
+## Path Templating
+
+`url:`, `label:`, `aria_label:`, and any string value inside `defaults:` may contain `{namespace.member[.member2[.member3]]}` placeholders that resolve at render time:
+
+| Namespace | Hops | Resolves to |
+|---|---|---|
+| `current_user.<a>[.<b>[.<c>]]` | 1–3 | `public_send` chain on `LcpRuby::Current.user`. e.g. `{current_user.id}`, `{current_user.organization.slug}`. |
+| `lcp_ruby.<helper>` | 1 | Engine route helper from `LcpRuby::Engine.routes.url_helpers`. e.g. `{lcp_ruby.destroy_user_session_path}`. |
+| `application.<helper>` | 1 | Host-app route helper from `Rails.application.routes.url_helpers`. e.g. `{application.root_path}`. |
+
+```yaml
+- url: "/orgs/{current_user.organization.slug}/members/{current_user.id}"
+  label: "Profile of {current_user.name}"
+- url: "{lcp_ruby.destroy_user_session_path}"
+  method: delete
+  label: "Sign out"
+- defaults: { scope: "user-{current_user.id}" }
+```
+
+**Validation.** Tokens are validated structurally at config-load time (grammar, namespace allowlist, hop count) and again at boot/`to_prepare` time for route-helper existence + arity (helpers requiring required arguments are rejected — only argument-less helpers work in templates). Malformed tokens, unknown namespaces, or 4+ hops fail validation at boot.
+
+**Runtime errors.** A `current_user.<chain>` that hits `nil` mid-chain or calls a method the receiver doesn't respond to raises `LcpRuby::MenuRenderError`. In development/test the error surfaces; in production the error is recorded via `LcpRuby.record_error` and the affected item silently drops.
+
+## Method-Aware Rendering
+
+The `method:` key controls which Rails helper is used to render the item:
+
+| `method:` | Renders | Notes |
+|---|---|---|
+| omitted, `get` | `<a href>` (with `link_to`) | Default. Integrates with Turbo Drive. |
+| `post`, `put`, `patch`, `delete` | `<form><button>` (with `button_to`) | Includes CSRF authenticity token + Rails `_method` hidden field for non-POST. |
+
+Default per destination:
+
+| Destination | Default method |
+|---|---|
+| `url:` | `:get` |
+| `view_group:` | `:get` (always — index pages are GET) |
+| `presenter: ... action: show/edit/index/new` | `:get` |
+| `presenter: ... action: destroy` | `:delete` |
+| `presenter: ... action: <custom>` | `:post` |
+
+`disable_when:` works for both shapes — the disabled `<button>` is natively non-activatable; the disabled `<a>` is gated by a Stimulus `lcp-menu` controller that prevents click activation client-side.
+
+## Presenter Resolver
+
+The `presenter:` + `alias:` + `action:` triple resolves to a URL via the engine's resourceful routing scope (`/:lcp_slug/...`). URL shapes:
+
+| Action | URL shape | Helper used |
+|---|---|---|
+| `index` | `/<slug>` | `resources_path(lcp_slug:)` |
+| `new` | `/<slug>/new` | `new_resource_path(lcp_slug:)` |
+| `show` | `/<slug>/<alias>` | `resource_path(lcp_slug:, id:)` |
+| `edit` | `/<slug>/<alias>/edit` | `edit_resource_path(lcp_slug:, id:)` |
+| `destroy` | `/<slug>/<alias>` (DELETE) | `destroy_resource_path(lcp_slug:, id:)` |
+| custom + `alias:` | `/<slug>/<alias>/actions/<action_name>` | `single_action_path(lcp_slug:, id:, action_name:)` |
+| custom (no alias) | `/<slug>/actions/<action_name>` | `collection_action_path(lcp_slug:, action_name:)` |
+
+`alias:` values are presenter-level — declared under `record_aliases:` on the presenter (e.g. `me: { resolve: current_user }` resolves the segment to the current user's id at request time). The same model can have different aliases in different presenters.
+
+`defaults:` forwards extra query parameters to the helper. String values pass through path templating, so `defaults: { scope: "user-{current_user.id}" }` works.
+
+## Disabled State
+
+`disable_when:` mirrors `visible_when:` — same condition shapes (`service:` + `params:`, compound `all`/`any`/`not`) — but instead of hiding the item, the platform renders it visible with the disabled affordance:
+
+```yaml
+- presenter: notifications
+  action: mark_all_read
+  label: "Mark all as read"
+  icon: check
+  disable_when:
+    service: notifications_unread_count
+    params: { eq: 0 }
+```
+
+Effects when the condition evaluates true:
+
+- Visual: `lcp-menu-item--disabled` class on the link/button.
+- A11y: `aria-disabled="true"` on `<a>` items, native `disabled` on `<button>` items.
+- Click activation: Stimulus `lcp-menu` controller's `prevent` action blocks click + keyboard activation on `<a>` items (native `<button disabled>` already blocks both).
+- Dropdown trigger: the `lcp-nav-dropdown--disabled` modifier on the `<li>` also suppresses the hover-open behaviour, so a disabled group-trigger does not reveal its panel.
+
+`disable_when:` is a **UI affordance, not a security boundary**. The endpoint behind the URL must enforce its own authorization — a determined user can copy the disabled URL out of the DOM. Use `visible_when:` (or server-side authorization) for security gating.
+
+In production, errors from a `disable_when:` service are swallowed and the item renders enabled (failure-bias toward usability — prevents a service outage from locking users out of working buttons). In dev/test the error is raised. See `MenuItem#meets_enabled?`.
+
+## Computed Items (`provider:`)
+
+A `provider:` item delegates the entire item construction to a Ruby class:
+
+```ruby
+# app/lcp_services/menu_items/current_org_link.rb
+module LcpRuby::HostServices::MenuItems
+  class CurrentOrgLink
+    def self.call(options:, current_user:, request_context:)
+      org = current_user&.current_organization
+      return nil unless org
+
+      {
+        url: "/orgs/#{org.slug}",
+        label: org.name,
+        icon: "building",
+        badge: { provider: "org_unread_count", renderer: "count_badge" }
+      }
+    end
+  end
+end
+```
+
+Wired via `provider:` in YAML:
+
+```yaml
+- provider: current_org_link
+- provider: recent_records
+  options: { limit: 5 }
+```
+
+**Return shapes:**
+
+| Return | Walker behaviour |
+|---|---|
+| Hash | One MenuItem replaces the YAML position. |
+| Array of hashes | `flat_map` — each hash becomes a sibling. |
+| `nil` / `[]` | Silent collapse (no item rendered, no warning). |
+
+**Constraints on returns:**
+
+- The hash's keys are validated against the standard MenuItem allowlist; `provider:` and `panel_provider:` chains are forbidden (each YAML position resolves to one source — chains would invite recursion bugs).
+- Returned `:group` items are recursed for visibility filtering before being rendered.
+- Depth is threaded through the walker so providers cannot bypass the `MAX_NESTING_DEPTH` (currently 2) limit by returning deeply nested structures.
+
+**Modifier inheritance.** Static modifier keys on the YAML provider item (`label`, `icon`, `position`, `badge`, `visible_when`, `disable_when`, `aria_label`, `render`) are inherited by each returned hash unless the provider overrides them. Destination keys are stripped on the YAML side (the provider supplies the destination).
+
+**Performance.** Providers fire on every render. The platform does **not** cache by default — provider authors are responsible for fragment caching by `[name, current_user.id, options.hash]`. Consider wrapping the body in `Rails.cache.fetch` for expensive computations.
+
+## Custom Renderers
+
+The three render slots (`render:`, `render_panel:`, `widget:`) compose with destinations (`presenter:`, `url:`, `provider:`, `children:`) and modifiers (`disable_when:`, `visible_when:`, `position:`).
+
+### `render:` — custom trigger HTML
+
+Replaces the inner content of the link/button wrapper. Use for items where the visible content is more than `<icon> <label>` — e.g. avatar + display name + caret on the user menu trigger.
+
+The framework still owns:
+
+- The wrapping element (`<a>`, `<button_to>` form, or `<button class="lcp-nav-dropdown-toggle">` for groups).
+- ARIA attributes (`role`, `aria-label`, `aria-disabled`).
+- Active-state class.
+- Badge placement (rendered after the partial output, unless badge is suppressed via no-badge YAML).
+
+The partial output is constrained to phrasing/inline content (HTML forbids block-level inside `<a>`/`<button>`). To emit block content, combine with `widget: true`.
+
+### `render_panel:` — custom dropdown panel HTML
+
+Replaces the inner content of a `:group`'s dropdown panel. The framework keeps the `<div class="lcp-nav-dropdown-menu lcp-nav-dropdown-menu--custom">` wrapper.
+
+Locals: `item:` (parent group MenuItem) and `items:` (already filtered children — equivalent to `panel_items_for(item)`). Block-level HTML allowed (panel is `<div>`-wrapped).
+
+Pair with `panel_provider:` to pull panel children from a Ruby class:
+
+```yaml
+- render_panel: my_app/tenant_switcher_panel
+  panel_provider: user_tenants
+  children: []                    # explicit "no static children"
+  options: { current_only: false }
+  aria_label: "Switch tenant"
+```
+
+### `widget: true` — drop the wrapper
+
+Lifts the inline-content constraint by removing the wrapping `<a>`/`<button_to>` entirely. The framework keeps `<li class="lcp-menu-widget">` for layout consistency; the `render:` partial owns everything inside.
+
+Use for menu items whose inner HTML is itself interactive — search inputs, theme switchers, language pickers — where a wrapping link/button would swallow events.
+
+```yaml
+- widget: true
+  render: my_app/quick_search
+  aria_label: "Search the app"
+  position: right
+```
+
+**Required** with `widget: true`: `render:`. **Forbidden** with `widget: true`: `url:`, `presenter:`, `view_group:`, `children:`, `separator:` (no destination URL — there's no wrapper to attach it to). `provider:` is allowed (provider returns widget data, render: produces the markup).
+
+## Detection Priority
+
+When parsing a menu item hash, keys are checked in this order:
+
+1. `separator` — separator item
+2. `view_group` — view group reference
+3. `children` — group with nested items
+4. `url`, `presenter`, `provider`, or `widget` — link-typed item
+
+## Auto Mode Behavior
+
+In `:auto` mode (the default):
+
+1. If no `menu.yml` exists, navigation is auto-generated from view groups (same as before)
+2. If `menu.yml` exists, it is used as the menu definition
+3. Any navigable view groups not referenced in `menu.yml` are automatically appended to `top_menu`
+4. View groups with `navigation: false` are excluded from auto-generation and auto-append
+
+## Strict Mode Behavior
+
+In `:strict` mode:
+
+1. `menu.yml` is required — raises `MetadataError` if missing
+2. The menu is the sole source of truth — no auto-append
+3. View groups must not have `navigation` config (only `navigation: false` is allowed)
+
+## Badges
+
+Menu items can display dynamic badges — counts, text labels, or icons — populated by data providers.
+
+### Badge YAML Schema
+
+```yaml
+- view_group: tasks
+  badge:
+    provider: open_tasks        # Required: data provider name
+    renderer: count_badge       # One of: renderer, template, or partial
+    options:                    # Optional: passed to renderer
+      color: "#dc3545"
+```
+
+Exactly one rendering form must be specified:
+
+| Key | Description |
+|-----|-------------|
+| `renderer` | A `Display::BaseRenderer` subclass from `Display::RendererRegistry` |
+| `template` | String with `{key}` interpolation, wrapped in a badge `<span>` |
+| `partial` | Rails partial path, receives `data` local variable |
+
+### Data Providers
+
+Data providers are registered in `Services::Registry` under the `data_providers` category. They are auto-discovered from `app/lcp_services/data_providers/`.
+
+**Contract:** `call(user:)` → data (any shape) or `nil` (nil = hide badge).
+
+```ruby
+# app/lcp_services/data_providers/open_tasks.rb
+module LcpRuby::HostServices::DataProviders
+  class OpenTasks
+    def self.call(user:)
+      LcpRuby::Dynamic::Task.where(status: "open").count
+    end
+  end
+end
+```
+
+### Built-in Badge Renderers
+
+| Renderer | Input | Output |
+|----------|-------|--------|
+| `count_badge` | Positive `Integer` | Red pill with count (nil for 0 or non-integer) |
+| `text_badge` | `String` or `Hash` with `"text"`, optional `"color"` | Uppercase text badge with optional background color |
+| `icon_badge` | `String` or `Hash` with `"icon"`, optional `"color"` | Icon element with optional color |
+
+### Template Form
+
+For the `template` form, `{key}` placeholders are interpolated from the provider data:
+
+- If provider returns a **Hash**, keys are available directly: `{count}`, `{label}`
+- If provider returns a **simple value** (Integer, String), use `{value}`
+
+```yaml
+- view_group: inbox
+  badge:
+    provider: unread_messages
+    template: "{count} new"
+```
+
+### Partial Form
+
+The partial receives a `data` local variable with the provider's return value:
+
+```yaml
+- view_group: system_health
+  badge:
+    provider: health_status
+    partial: "badges/health_indicator"
+```
+
+### Badge Examples
+
+```yaml
+menu:
+  sidebar_menu:
+    # Count badge on tasks
+    - view_group: tasks
+      badge:
+        provider: open_tasks
+        renderer: count_badge
+
+    # Text badge with color
+    - view_group: inbox
+      badge:
+        provider: unread_messages
+        template: "{count} new"
+
+    # Badge on a group
+    - label: "CRM"
+      badge:
+        provider: crm_alerts
+        renderer: text_badge
+        options:
+          color: "#dc3545"
+      children:
+        - view_group: deals
+```
+
+## Complete Example
+
+```yaml
+menu:
+  top_menu:
+    - view_group: deals
+    - label: "CRM"
+      icon: briefcase
+      children:
+        - view_group: companies
+        - view_group: contacts
+        - separator: true
+        - label: "Reports"                   # Nested sub-group (flyout)
+          children:
+            - view_group: monthly_reports
+            - view_group: annual_reports
+        - label: "External"
+          url: /crm/reports
+
+  sidebar_menu:
+    - view_group: deals
+    - label: "CRM"
+      icon: briefcase
+      children:
+        - view_group: companies
+        - view_group: contacts
+        - label: "Reports"                   # Nested sub-group (collapsible)
+          children:
+            - view_group: monthly_reports
+            - view_group: annual_reports
+    - label: "Settings"
+      icon: settings
+      position: bottom
+      visible_when:
+        role: [admin]
+      children:
+        - view_group: users
+        - view_group: audit_log
+```
+
+## Responsive Behavior
+
+The top nav and sidebar adapt to viewport size via the `responsive:`
+block in `menu.yml`. When the block is omitted, sensible defaults apply
+out of the box — every LCP app gets responsive navigation with zero
+configuration. See [docs/design/responsive-menu.md](../design/responsive-menu.md)
+for the full design rationale.
+
+### Top-nav modes
+
+```yaml
+menu:
+  responsive:
+    top_menu:
+      mode: overflow_more     # none | wrap | overflow_more | hamburger
+      breakpoint: 768         # px
+      more:
+        label_key: lcp_ruby.nav.more
+        icon: more-horizontal
+```
+
+| Mode | Behavior |
+|---|---|
+| `none` | No responsive adaptation. Use only if your host stylesheet owns layout. |
+| `wrap` | Items that don't fit wrap onto subsequent rows. CSS-only. |
+| `overflow_more` *(default)* | Items that don't fit collapse into a synthesized *More* dropdown. Items with `pin: always` or `position: right` never collapse. |
+| `hamburger` | Below `breakpoint`, the entire left zone hides behind a hamburger drawer. |
+
+### Sidebar modes
+
+```yaml
+menu:
+  responsive:
+    sidebar_menu:
+      above_breakpoint: rail         # none | rail
+      below_breakpoint: off_canvas   # none | off_canvas
+      breakpoint: 1024
+      user_toggle: true
+      persist: cookie                # cookie | local_storage | none
+      initial: expanded              # expanded | collapsed | auto
+      auto_inject_toggle: true
+```
+
+| State | Behavior |
+|---|---|
+| `above_breakpoint: rail` | Viewport >= breakpoint: sidebar can collapse to icon-only rail. User toggle is sticky at top. State persists via cookie (1y, path-scoped to engine mount). |
+| `above_breakpoint: none` | Viewport >= breakpoint: sidebar always full width. |
+| `below_breakpoint: off_canvas` | Viewport < breakpoint: sidebar hides off-screen and opens via an auto-injected `sidebar_toggle` button in `top_menu` (suppressed by `auto_inject_toggle: false` or an explicit `- sidebar_toggle: true` item). |
+| `below_breakpoint: none` | Viewport < breakpoint: sidebar stays inline (may overflow horizontally). |
+
+### Per-item responsive keys
+
+Apply to any `top_menu` item (most keys also accepted on children for
+forward compat, but only the `overflow_more` measurement loop reads
+`responsive_priority` / `pin`):
+
+| Key | Type | Effect |
+|---|---|---|
+| `responsive_priority` | integer | Higher = collapse later. `position: right` and `pin: always` implicitly priority infinity. |
+| `pin` | `always` | Never collapses into *More*. |
+| `hide_below` | px integer | Hide on viewports narrower than this value (presentational only, not a permission boundary). |
+| `show_below` | px integer | Show ONLY on viewports narrower than this value. Mutex with `hide_below`. |
+| `collapse_label_below` | px integer | (Sidebar) Drop the visible label and show icon only when viewport is narrower than this value. |
+
+### Escape hatch
+
+To disable all responsive behavior (e.g. a host with custom responsive
+CSS):
+
+```yaml
+menu:
+  responsive:
+    top_menu:    { mode: none }
+    sidebar_menu: { above_breakpoint: none, below_breakpoint: none }
+```
+
+### sidebar_toggle marker
+
+```yaml
+top_menu:
+  - sidebar_toggle: true
+    label_key: lcp_ruby.nav.menu
+    icon: menu
+    position: left
+```
+
+Renders a button that opens the sidebar's off-canvas drawer.
+Platform-owned UI chrome — carries no destination URL. The framework
+auto-injects one of these when `below_breakpoint: off_canvas` is active
+and no explicit one is authored; opt out with
+`auto_inject_toggle: false`.
+
+### Mobile header (sidebar-only layouts)
+
+When a host app has `sidebar_menu` only (no `top_menu`) and the policy
+keeps `below_breakpoint: off_canvas` + `auto_inject_toggle: true`
+(both defaults), the platform renders a thin sticky `_mobile_header.html.erb`
+strip above the layout. Below the sidebar breakpoint the strip becomes
+visible with a hamburger button that opens the sidebar drawer; above
+breakpoint it's hidden via CSS (`body.lcp-sidebar-off-canvas-active`
+class toggled by `lcp-responsive-sidebar` from its `matchMedia`
+listener).
+
+The off-canvas drawer overrides the rail-collapsed width — even if the
+user persisted `lcp_sidebar=collapsed` in the rail-mode cookie, opening
+the drawer on a narrow viewport shows full-width labels
+(`min(80vw, 280px)`).
+
+Suppress the mobile header by either (a) authoring an explicit
+`sidebar_toggle:` somewhere in `top_menu` (only works if you also add a
+`top_menu`; sidebar-only layouts don't have one), or (b) setting
+`responsive.sidebar_menu.auto_inject_toggle: false` (sidebar drawer
+then has no built-in trigger — author your own).
+
+### Rail-collapsed flyouts
+
+When the sidebar is in `above_breakpoint: rail` mode AND the user has
+collapsed it (`data-rail="collapsed"`), group items show only their
+icons. Clicking a group icon opens its `children` as an
+absolute-positioned flyout panel to the right of the rail:
+
+- Only one flyout open at a time per page.
+- ESC closes the open flyout.
+- Outside-click closes (single shared capture-phase document listener).
+- Leaf items (`view_group:`, `url:`, `presenter:`) inside the flyout
+  are standard `<a>` links — click navigates.
+
+CSS uses `overflow: visible` on the rail (`.lcp-sidebar[data-rail=
+"collapsed"]`) instead of the default `overflow-y: auto`, so the
+flyout can escape the rail's right edge. Trade-off: the rail loses
+vertical scroll. Hosts with 20+ groups can set
+`responsive.sidebar_menu.above_breakpoint: none` to keep the sidebar
+full-width and skip rail mode entirely.
+
+### Custom trigger renderers in sidebar (`render:`)
+
+`render: lcp_ruby/user_menu` (or any custom trigger partial) works in
+both top-nav and sidebar contexts. In the sidebar:
+
+- The trigger renders in the configured group's `.lcp-sidebar-group-toggle`
+  button — full content control via the partial.
+- Framework drops its native badge + arrow when `render:` is set,
+  matching top-nav behavior.
+- The item is **not** treated as icon-only even if no `label:` is
+  authored — the renderer is presumed to supply its own visible label.
+  This keeps `Demo User (admin)`-style triggers aligned at the icon
+  column (~16 px) like other group headers, instead of being centered
+  like the notifications bell / help link / other intentionally-icon-only
+  items.
+
+In rail-collapsed mode, the avatar (`.lcp-user-menu__avatar`) remains
+visible as the rail icon, while the label / caret hide along with other
+labels.
+