@retailcrm/embed-ui-v1-components 0.9.18 → 0.9.21

package/docs/AGENT-DESIGN-GUIDELINES.md

@@ -0,0 +1,463 @@
+# Agent Design Guidelines
+
+These guidelines describe page construction rules for AI assistants that generate RetailCRM
+extension screens with `@retailcrm/embed-ui-v1-components`.
+
+## How Agents Should Use This File
+
+- Use this file after `README.md`, `AGENTS.md`, `AI.md`, and the relevant component profiles.
+- Treat it as page-composition guidance, not as a replacement for component API docs.
+- Prefer public components from `@retailcrm/embed-ui-v1-components/remote`.
+- Use Storybook and YAML profiles for exact component props and examples.
+- Do not invent new chrome for pages, forms, tables, tabs, buttons, modals, or sidebars when a documented component exists.
+
+## Shared Page Rules
+
+- Page title uses the large accent text style: `Text large Accent 24`.
+- Page-level actions sit to the right of the title.
+- A page can have only one `Default Primary` button and one `Success Primary` button.
+- Additional page actions can use secondary or tertiary variants in unlimited quantity when the task needs them.
+- When a group has multiple buttons, the primary action should represent the main flow. Secondary actions should support or cancel that flow.
+- Components inside pages and blocks should be spaced by values divisible by 4px: `4`, `8`, `12`, `16`, `20`, `24`, `28`, `32`, and so on.
+- Content blocks commonly use 32px left, right, and bottom padding and 24px top padding.
+
+## Entity List Page
+
+Use this pattern for separate pages that list entities and allow filtering or creating a new entity.
+
+![Entity list page mockup](./assets/page-guidelines/entity-list-page.png)
+
+Examples from the design:
+
+- order list;
+- customer list;
+- mailing list;
+- task list.
+
+Expected structure:
+
+- `UiPageHeader` with a page title.
+- One or more 48px page buttons on the right side of the header.
+- If there are multiple header buttons, one should be primary and the rest can be secondary or tertiary.
+- The main primary button usually creates a new entity for the list.
+- Filters above the table, built from controls such as select, textbox, and combobox-like selection components.
+- Filter controls should run in rows of roughly 4-5 fields, then wrap to the next row.
+- Filters can be collapsible.
+- Filter apply action uses a default secondary 36px text button.
+- Filter reset action uses a danger secondary 36px icon button.
+- The entity data is shown in a table.
+- The table may scroll and may support export.
+
+Recommended components:
+
+- `UiPageHeader`
+- `UiButton`
+- `UiField`
+- `UiTextbox`
+- `UiSelect`
+- `UiTable`
+- `UiTableColumn`
+- `UiTableSorter`
+- `UiTableFooterSection`
+- `UiTableFooterButton`
+
+Canonical table footer pattern:
+
+```vue
+<script lang="ts" setup>
+import IconChevronLeft from '@retailcrm/embed-ui-v1-components/assets/sprites/arrows/chevron-left.svg'
+import IconChevronRight from '@retailcrm/embed-ui-v1-components/assets/sprites/arrows/chevron-right.svg'
+import {
+  UiTable,
+  UiTableColumn,
+  UiTableFooterButton,
+  UiTableFooterSection,
+} from '@retailcrm/embed-ui-v1-components/remote'
+</script>
+
+<template>
+  <UiTable
+    class="entity-list-table"
+    bordered
+    :rows="rows"
+    row-key="id"
+  >
+    <UiTableColumn label="Название">
+      <template #cell="{ row }">
+        {{ row.title }}
+      </template>
+    </UiTableColumn>
+
+    <template #footer-summary="{ rowsCount }">
+      <span>{{ rowsCount }} элементов</span>
+    </template>
+
+    <template #footer-page-size>
+      <UiTableFooterSection class="entity-list-table__page-size">
+        <span class="entity-list-table__footer-caption">Показывать:</span>
+        <UiTableFooterButton class="entity-list-table__footer-button entity-list-table__footer-button_passive">
+          по 20
+        </UiTableFooterButton>
+        <span class="entity-list-table__footer-delimiter">/</span>
+        <UiTableFooterButton class="entity-list-table__footer-button">
+          по 50
+        </UiTableFooterButton>
+        <span class="entity-list-table__footer-delimiter">/</span>
+        <UiTableFooterButton class="entity-list-table__footer-button">
+          по 100
+        </UiTableFooterButton>
+      </UiTableFooterSection>
+    </template>
+
+    <template #footer-pagination>
+      <UiTableFooterSection class="entity-list-table__pagination-section">
+        <div class="entity-list-table__pagination">
+          <UiTableFooterButton class="entity-list-table__pagination-button">
+            1
+          </UiTableFooterButton>
+          <UiTableFooterButton class="entity-list-table__pagination-button">
+            2
+          </UiTableFooterButton>
+          <UiTableFooterButton class="entity-list-table__pagination-button entity-list-table__pagination-button_current">
+            3
+          </UiTableFooterButton>
+          <span class="entity-list-table__pagination-divider" />
+          <UiTableFooterButton
+            aria-label="Предыдущая страница"
+            class="entity-list-table__pagination-arrow"
+          >
+            <IconChevronLeft
+              aria-hidden="true"
+              class="entity-list-table__pagination-arrow-icon"
+            />
+          </UiTableFooterButton>
+          <span class="entity-list-table__pagination-divider" />
+          <UiTableFooterButton
+            aria-label="Следующая страница"
+            class="entity-list-table__pagination-arrow"
+          >
+            <IconChevronRight
+              aria-hidden="true"
+              class="entity-list-table__pagination-arrow-icon"
+            />
+          </UiTableFooterButton>
+        </div>
+      </UiTableFooterSection>
+    </template>
+  </UiTable>
+</template>
+```
+
+Footer CSS contract:
+
+```css
+.entity-list-table {
+  --ui-v1-table-cell-padding-x: 12px;
+  --ui-v1-table-cell-padding-y: 12px;
+  --ui-v1-table-padding-start: 16px;
+  --ui-v1-table-padding-end: 16px;
+  --ui-v1-table-rounding: 4px;
+  --ui-v1-table-head-cell-padding-block-start: 14px;
+  --ui-v1-table-head-cell-padding-block-end: 14px;
+  --ui-v1-table-body-cell-padding-block-start: 15px;
+  --ui-v1-table-body-cell-padding-block-end: 15px;
+}
+
+.entity-list-table .ui-v1-table__head-cell {
+  height: 42px;
+}
+
+.entity-list-table .ui-v1-table__footer-meta {
+  min-height: 40px;
+  font-weight: 400;
+}
+
+.entity-list-table .ui-v1-table__footer-controls {
+  min-height: 52px;
+  background: #f9fafb;
+}
+
+.entity-list-table .ui-v1-table__footer-section {
+  font-size: 14px;
+  line-height: 20px;
+}
+
+.entity-list-table__page-size,
+.entity-list-table__pagination-section {
+  color: #1e2248;
+}
+
+.entity-list-table__footer-caption {
+  display: inline-block;
+  margin-right: 4px;
+  vertical-align: baseline;
+  line-height: inherit;
+}
+
+.entity-list-table__footer-button {
+  color: #005eeb;
+}
+
+.entity-list-table__footer-button_passive {
+  color: #1e2248;
+}
+
+.entity-list-table__footer-delimiter {
+  display: inline-block;
+  padding: 0 5px;
+  color: #8a96a6;
+  vertical-align: baseline;
+  line-height: inherit;
+}
+
+.entity-list-table .ui-v1-table__footer-side > .entity-list-table__pagination-section {
+  padding-block: 8px;
+}
+
+.entity-list-table__pagination {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 36px;
+}
+
+.entity-list-table__pagination-button,
+.entity-list-table__pagination-arrow {
+  width: 36px;
+  height: 36px;
+  border-radius: 4px;
+}
+
+.entity-list-table .ui-v1-table__footer-button.entity-list-table__pagination-button {
+  color: #1e2248;
+  font-size: 14px;
+  line-height: 20px;
+}
+
+.entity-list-table .ui-v1-table__footer-button.entity-list-table__pagination-button_current {
+  color: #fff;
+  background: #005eeb;
+}
+
+.entity-list-table .ui-v1-table__footer-button.entity-list-table__pagination-arrow {
+  color: #afb9c3;
+}
+
+.entity-list-table__pagination-arrow-icon {
+  display: block;
+  width: 24px;
+  height: 24px;
+}
+
+.entity-list-table__pagination-divider {
+  width: 1px;
+  height: 52px;
+  margin-block: -8px;
+  background: #dee2e6;
+}
+```
+
+Use `UiTableFooterSection` and `UiTableFooterButton` for table footer pagination. Do not replace them
+with regular `UiButton`. Use chevron icon assets for arrow controls, not text glyphs. Keep footer
+styling scoped to a local table root class, and override the internal footer button class together
+with the local class when changing pagination text, active page, or arrow colors.
+
+## Card Or Settings Page
+
+Use this pattern for settings pages or entity cards made mostly from forms.
+
+![Card or settings page mockup](./assets/page-guidelines/card-settings-page.png)
+
+Examples from the design:
+
+- tracked event page;
+- sending limit settings;
+- email template settings;
+- trigger page.
+
+Expected structure:
+
+- `UiPageHeader` with a page title.
+- The title can be editable via an inline-edit pattern when the product flow requires it.
+- One or more 48px header buttons on the right.
+- Header actions can be accompanied by text information or status labels.
+- Optional top tabs.
+- Main content sits on a white content surface.
+- The content can include text, buttons, fields, checkboxes, radio groups, switches, and other form controls.
+- A bottom save panel is optional.
+
+Recommended components:
+
+- `UiPageHeader`
+- `UiButton`
+- `UiField`
+- `UiTextbox`
+- `UiSelect`
+- `UiCheckbox`
+- `UiRadio`
+- `UiRadioSwitch`
+- `UiSwitch`
+- `UiTabGroup`
+- `UiTab`
+- `UiTag`
+
+## Multi-Column Page
+
+Use this pattern when an entity card or detail page contains several semantic blocks that should be visible in parallel.
+
+![Multi-column page mockup](./assets/page-guidelines/multi-column-page.png)
+
+Examples from the design:
+
+- order page;
+- customer page;
+- product view page.
+
+Layout rules:
+
+- Content is placed on surfaces.
+- The most common surface spans the full screen width.
+- Semantic blocks can be arranged vertically and horizontally.
+- Distance between blocks is 24px.
+- Allowed width distributions are:
+  - `100%`;
+  - `50% / 50%`;
+  - `30% / 70%`.
+
+Keep the visual hierarchy operational and dense. Do not turn internal CRM work screens into marketing-style layouts.
+
+## Collapse-Block Page
+
+Use this pattern for settings split into semantic groups.
+
+![Collapse-block page mockup](./assets/page-guidelines/collapse-block-page.png)
+
+Examples from the design:
+
+- product editing;
+- mailing editing;
+- Double Opt-In settings.
+
+Expected structure:
+
+- Multiple collapsible blocks with their own content and local actions.
+- If the page contains only collapse blocks, the white page surface is not needed.
+- If every collapse block has its own save action, the bottom save panel is not needed.
+- Collapse blocks can contain text, buttons, fields, controls, and small tables.
+
+Avoid inside collapse blocks:
+
+- complex tables;
+- nested collapse blocks;
+- two-column content split across separate surfaces.
+
+Recommended components:
+
+- `UiCollapse`
+- `UiCollapseBox`
+- `UiCollapseGroup`
+- `UiButton`
+- `UiField`
+- `UiTable` only for small, simple tables
+
+## Modal Sidebar
+
+Use this pattern for a small contextual form, local additional information, or a compact entity card with a limited number of fields and settings.
+
+![Modal sidebar mockup](./assets/page-guidelines/modal-sidebar.png)
+
+Examples from the design:
+
+- task card;
+- notifications;
+- new ticket;
+- scenario step editing.
+
+Size rules:
+
+- Sidebar can use two widths: `720px` and `416px`.
+
+Expected structure:
+
+- Fixed header at the top with title and close button.
+- Header can also contain extra text, icon, button, or tag.
+- If a sidebar opens from another sidebar, show a back arrow to return to the previous sidebar.
+- Fixed footer at the bottom.
+- Footer usually contains save, cancel/close, and delete actions.
+- Footer can also contain a copy button or auxiliary text.
+- Content can be flexible, but should stay compact.
+- Small tables can be placed in sidebars.
+
+Avoid in sidebars:
+
+- collapse blocks;
+- two-column content on separate surfaces;
+- bulky or complex interfaces.
+
+For bulky flows, use a full page or modal window instead.
+
+Recommended components:
+
+- `UiModalSidebar`
+- `UiButton`
+- `UiTag`
+- `UiField`
+- `UiTextbox`
+- `UiSelect`
+- `UiTable` only for small, simple tables
+
+## Modal Window
+
+Use this pattern for large contextual tables or additional local settings when a sidebar is not enough.
+
+![Modal window mockup](./assets/page-guidelines/modal-window.png)
+
+Examples from the design:
+
+- adding products to an order;
+- marking products in an order;
+- viewing an email from the communication list;
+- merging duplicates in the database cleanliness section.
+
+Size rules:
+
+- Modal can use two sizes:
+  - `960px`;
+  - full screen with side margins.
+
+Expected structure:
+
+- Fixed header at the top with title and close button.
+- Header can include extra text, icon, button, or tag.
+- Fixed footer at the bottom.
+- Footer usually contains save, cancel/close, and delete actions.
+- Footer can also contain a copy button or auxiliary text.
+- Content can be flexible; tables are a common modal use case.
+- If a modal contains a table, the table stretches across the modal width.
+- If a modal is split into sections, use large tabs instead of a regular modal header.
+
+Spacing rules:
+
+- Left, right, and bottom margins: 32px.
+- Top margin: 24px.
+
+Recommended components:
+
+- `UiModalWindow`
+- `UiButton`
+- `UiTabGroup`
+- `UiTab`
+- `UiTable`
+- `UiTableColumn`
+- `UiTableFooterSection`
+
+## Quick Decision Guide
+
+- Need a searchable, filterable registry: use an entity list page.
+- Need to edit an entity or settings form: use a card/settings page.
+- Need several semantic blocks visible together: use a multi-column page.
+- Need grouped settings with independent sections: use a collapse-block page.
+- Need a small contextual form or compact entity card: use a modal sidebar.
+- Need a large local workflow, auxiliary table, or dense settings flow: use a modal window.
+
+When uncertain between sidebar and modal, choose sidebar only if the flow is compact. If the content needs wide tables, several sections, or complex controls, choose modal or full page.

package/docs/AI.md

@@ -10,7 +10,7 @@ Only the public package contract is described below, without depending on the re
 - Package name: `@retailcrm/embed-ui-v1-components`
 - Purpose: UI components and UI helpers for RetailCRM JS extensions
 - Framework: Vue 3
-- Published Storybook: `https://retailcrm.github.io/embed-ui/v1-components/0.9.14/`
+- Published Storybook: `https://retailcrm.github.io/embed-ui/v1-components/0.9.18/`
 - Primary public entrypoints:
   - `@retailcrm/embed-ui-v1-components/remote`
   - `@retailcrm/embed-ui-v1-components/host`
@@ -28,11 +28,33 @@ Only the public package contract is described below, without depending on the re
 
 When generating UI code, use this order:
 
-1. read [`COMPONENTS.md`](./COMPONENTS.md) to identify candidate components;
-2. open a detailed profile from [`PROFILES.md`](./PROFILES.md) if one exists;
-3. use [`FORMAT.md`](./FORMAT.md) as the schema for what information is considered reliable;
-4. read [`STYLING.md`](./STYLING.md) when the task is about classes, variables, typography, or visual zones;
-5. if no profile exists yet, fall back to [Storybook](https://retailcrm.github.io/embed-ui/v1-components/0.9.14/) docs and public type declarations, and state any inference explicitly.
+1. read [`../README.md`](../README.md) and [`../AGENTS.md`](../AGENTS.md) for package-level usage rules;
+2. read [`COMPONENTS.md`](./COMPONENTS.md) to identify candidate components;
+3. open a detailed profile from [`PROFILES.md`](./PROFILES.md) if one exists;
+4. use the profile `usage` link for published Storybook examples and visual behavior;
+5. read [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md) when the task is about complete
+   pages, modals, sidebars, filters, tables, or settings layouts;
+6. use [`FORMAT.md`](./FORMAT.md) as the schema for what information is considered reliable;
+7. read [`STYLING.md`](./STYLING.md) when the task is about classes, variables, typography, or visual zones;
+8. if no profile exists yet, fall back to [Storybook](https://retailcrm.github.io/embed-ui/v1-components/0.9.18/) docs and public type declarations, and state any inference explicitly.
+
+## Runtime Embedding References
+
+When generating code for a CRM extension, separate UI component choice from runtime placement:
+
+- [`targets` and contexts](../../v1-endpoint/docs/targets.md): explains that `target` is the CRM
+  embedding point, while `context` is the reactive CRM data available at that point.
+- [`menu placements`](../../v1-endpoint/docs/menu-placements.md): explains how host/manifest menu
+  items map to remote page codes.
+- [`page routes`](../../v1-endpoint/docs/page-routes.md): explains how page `code`, CRM route names,
+  and `definePageRunner` are connected.
+- [`defineWidgetRunner`](../../v1-endpoint/docs/define-widget-runner.md): shows how a widget receives
+  the current `target` prop.
+- [`definePageRunner`](../../v1-endpoint/docs/define-page-runner.md): shows how a page receives the
+  current `code` prop.
+- [`context concept`](../../v1-contexts/docs/ru/CONCEPT.md): explains predefined CRM contexts such as
+  `order/card`, `customer/card`, `user/current`, and `settings`.
+- [`custom context`](../../v1-contexts/docs/ru/CUSTOM.md): explains custom-field contexts.
 
 ## Default Recommendation For Common Forms
 
@@ -55,6 +77,64 @@ Typical compositions:
 - `UiPageHeader` + `UiButton`
 - `UiSelect` + `UiSelectOption`
 
+## Default Recommendation For Full Screens
+
+When building a complete extension screen, prioritize a working operational interface over a
+decorative landing page.
+
+Default screen rules:
+
+- use [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md) to choose between an entity list,
+  card/settings page, multi-column page, collapse-block page, modal sidebar, or modal window;
+- use `UiPageHeader` for page identity and top-level actions;
+- keep filters and controls near the content they affect;
+- use `UiField` around labeled form controls;
+- use `UiTable` for structured result lists;
+- use `UiLink` for navigation and inline links, `UiButton` for commands;
+- use `UiLoader` with `overlay: true` when loading should dim the covered page or module content;
+- keep public imports on `@retailcrm/embed-ui-v1-components/remote`;
+- avoid custom markup that recreates textbox, select, button, link, or table chrome.
+
+## Default Recommendation For Table Screens
+
+When building a registry, catalog, journal, search result, order list, customer list, or any
+screen where users scan and refine datasets:
+
+- put search and filters directly above `UiTable`;
+- use `UiTextbox` for free-text search and `UiSelect` or compact toggle controls for finite filters;
+- keep filters, sorting, page, and page size in GET query parameters when the host app has routing;
+- hydrate initial filter and pagination state from the current query;
+- reset `page` to `1` when filters or sorting change;
+- debounce free-text search before writing query or fetching data;
+- use `UiTableSorter` for sortable headers;
+- use `UiTable` footer slots for summary, page-size controls, export, and pagination;
+- compose table footer controls with `UiTableFooterSection` and `UiTableFooterButton`, not regular `UiButton`;
+- use chevron icon assets for table footer previous/next controls instead of text glyphs;
+- add local CSS for table footer layout and states; use `AGENT-DESIGN-GUIDELINES.md` for the canonical footer CSS contract;
+- set `size="small"` on `UiLink` inside table cells so links match table body typography.
+
+Suggested query names:
+
+- `q` for text search;
+- `status`, `managerId`, `dateFrom`, `dateTo` for filters;
+- `sort` and `direction` for sorting;
+- `page` and `pageSize` for pagination.
+
+## External Documentation Patterns
+
+These references are useful when extending the profiles and examples in this package:
+
+- [shadcn/ui Data Table source](https://github.com/shadcn-ui/ui/blob/main/apps/v4/content/docs/components/radix/data-table.mdx)
+  documents a scenario-first table build: base table, row actions, pagination, sorting,
+  filtering, visibility, row selection, and reusable table pieces.
+- [Nuxt UI v4 Table source](https://github.com/nuxt/ui/blob/v4/docs/content/docs/2.components/table.md)
+  documents table state, sorting, pagination, loading, empty state, slots, and advanced flows.
+- [Nuxt UI v2 Table source](https://github.com/nuxt/ui/blob/v2/docs/content/2.components/table.md)
+  is useful for explicit searchable, paginable, manual sorting, and reactive query examples.
+- [PrimeVue DataTable docs](https://primevue.org/datatable/)
+  are useful for Vue table patterns around filtering, pagination, selection, lazy loading, empty,
+  loading, and accessibility.
+
 ## What AI Needs In A Good Component Profile
 
 The most useful format for AI is a component profile that explicitly answers:
@@ -100,7 +180,10 @@ The preferred styling signal is:
 ## Related Public Docs
 
 - [`README.md`](./README.md)
+- [`../README.md`](../README.md)
+- [`../AGENTS.md`](../AGENTS.md)
 - [`COMPONENTS.md`](./COMPONENTS.md)
 - [`FORMAT.md`](./FORMAT.md)
 - [`STYLING.md`](./STYLING.md)
+- [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md)
 - [`../AGENTS.md`](../AGENTS.md)

package/docs/FORMAT.md

@@ -19,12 +19,17 @@ A good profile should let an agent answer these questions without opening the so
 
 Recommended filename: `<ComponentName>.yml`
 
+Top-level `usage` should point to the published Storybook docs page for version `0.9.18`.
+If the component is a subcomponent without its own Storybook page, point `usage` to the nearest
+parent or composition page that demonstrates it, for example table parts point to `UiTable`.
+
 Minimal shape:
 
 ```yml
 component: UiComponent
 summary: >
   A short description of the component.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/intro--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -77,12 +82,6 @@ styling:
       line_height: 24px
       weight: 400
 
-examples:
-  - title: Basic example
-    goal: What the user or the agent is trying to build.
-    code: |
-      <UiComponent />
-
 ai_notes:
   do:
     - rule
@@ -220,15 +219,17 @@ Capture:
 - what happens to `aria-invalid`, `aria-labelledby`, `role`, `aria-expanded`, and similar attributes;
 - which keys affect behavior, if that behavior is documented.
 
-## 11. `examples` and `composition`
+## 11. `composition`
 
 List:
 
 - common combinations;
 - required neighboring components;
 - safe defaults for typical screens;
-- goal-oriented examples such as "build a table", "build an editable header", or "build a field with a select";
-- examples of correct and incorrect composition.
+- correct and incorrect composition patterns.
+
+Do not duplicate Storybook examples in YAML profiles. The top-level `usage` link is the source for runnable
+examples and visual behavior.
 
 ## 12. `ai_notes`
 
@@ -244,6 +245,7 @@ A short list of rules specifically for code generation:
 - Use the exact names of props, emits, and slots.
 - For slots, describe not only the name, but also what the slot does and which content restrictions exist.
 - For styling, distinguish between safe CSS variables and descriptive class names.
+- Keep runnable examples in Storybook; YAML profiles should link to Storybook through `usage`.
 - Do not mix "how the component looks right now" with "what is publicly guaranteed".
 - If behavior is inferred from implementation rather than public API, say that explicitly.
 - If information is missing, state the limitation rather than inventing details.

package/docs/PROFILES.md

@@ -6,7 +6,7 @@ The current profile layer is structured like this:
 
 - the index stays in markdown so both humans and agents can navigate it easily;
 - the actual profiles live in `docs/profiles/*.yml`;
-- YAML is the source of truth for structure, props, slots, emits, examples, and AI rules.
+- YAML is the source of truth for structure, props, slots, emits, composition, and AI rules.
 
 ## Table Of Contents
 
@@ -18,9 +18,11 @@ The current profile layer is structured like this:
 
 ## Reading Order
 
-1. [`AI.md`](./AI.md)
-2. this index
-3. the relevant `.yml` profile
+1. [`../README.md`](../README.md)
+2. [`../AGENTS.md`](../AGENTS.md)
+3. [`AI.md`](./AI.md)
+4. this index
+5. the relevant `.yml` profile
 
 ## Current Coverage
 
@@ -30,6 +32,7 @@ Use these entrypoints:
 
 - [`COMPONENTS.md`](./COMPONENTS.md) for the full linked component index
 - `docs/profiles/*.yml` for per-component machine-readable profiles
+- each profile `usage` field for published Storybook 0.9.18 examples and visual behavior
 
 Current high-signal core profiles:
 
@@ -53,7 +56,7 @@ Current high-signal core profiles:
 - `props` if you need a broader practical API view.
 - `slots` if the task is about markup, zones, and allowed content.
 - `emits` if the component must be wired into screen logic.
-- `examples` if you need a working usage pattern quickly.
+- `usage` if you need Storybook examples or visual behavior.
 - `ai_notes` if the agent needs safe defaults and anti-patterns.
 
 ## Styling Reads
@@ -64,3 +67,4 @@ Current high-signal core profiles:
 ## Notes
 
 - All new updates should be made in YAML profiles.
+- Keep profile `usage` links on the Storybook 0.9.18 URL unless another version is required explicitly.