@retailcrm/embed-ui-v1-components 0.9.21 → 0.9.22-alpha.1

package/docs/AI.md

@@ -10,7 +10,6 @@ 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.18/`
 - Primary public entrypoints:
   - `@retailcrm/embed-ui-v1-components/remote`
   - `@retailcrm/embed-ui-v1-components/host`
@@ -31,12 +30,11 @@ When generating UI code, use this order:
 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
+4. read the relevant page profile from [`PROFILES.md`](./PROFILES.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.
+5. use [`FORMAT.md`](./FORMAT.md) as the schema for what information is considered reliable;
+6. read [`STYLING.md`](./STYLING.md) when the task is about classes, variables, typography, or visual zones;
+7. if no profile exists yet, fall back to public type declarations and state any inference explicitly.
 
 ## Runtime Embedding References
 
@@ -84,7 +82,7 @@ decorative landing page.
 
 Default screen rules:
 
-- use [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md) to choose between an entity list,
+- use [`PageComposition.yml`](./profiles/pages/PageComposition.yml) 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;
@@ -110,7 +108,8 @@ screen where users scan and refine datasets:
 - 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;
+- add local CSS for table footer layout and states; use [`UiTable.yml`](./profiles/components/UiTable.yml)
+  for the reference table footer example;
 - set `size="small"` on `UiLink` inside table cells so links match table body typography.
 
 Suggested query names:
@@ -165,17 +164,17 @@ The preferred styling signal is:
 
 ## Current High-Signal Profiles
 
-- [`UiField`](./profiles/UiField.yml)
-- [`UiTextbox`](./profiles/UiTextbox.yml)
-- [`UiButton`](./profiles/UiButton.yml)
-- [`UiPageHeader`](./profiles/UiPageHeader.yml)
-- [`UiSelect`](./profiles/UiSelect.yml)
-- [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml)
-- [`UiTabGroup`](./profiles/UiTabGroup.yml)
-- [`UiTab`](./profiles/UiTab.yml)
-- [`UiPopper`](./profiles/UiPopper.yml)
-- [`UiPopperConnector`](./profiles/UiPopperConnector.yml)
-- [`UiPopperTarget`](./profiles/UiPopperTarget.yml)
+- [`UiField`](./profiles/components/UiField.yml)
+- [`UiTextbox`](./profiles/components/UiTextbox.yml)
+- [`UiButton`](./profiles/components/UiButton.yml)
+- [`UiPageHeader`](./profiles/components/UiPageHeader.yml)
+- [`UiSelect`](./profiles/components/UiSelect.yml)
+- [`UiRadioSwitch`](./profiles/components/UiRadioSwitch.yml)
+- [`UiTabGroup`](./profiles/components/UiTabGroup.yml)
+- [`UiTab`](./profiles/components/UiTab.yml)
+- [`UiPopper`](./profiles/components/UiPopper.yml)
+- [`UiPopperConnector`](./profiles/components/UiPopperConnector.yml)
+- [`UiPopperTarget`](./profiles/components/UiPopperTarget.yml)
 
 ## Related Public Docs
 
@@ -185,5 +184,5 @@ The preferred styling signal is:
 - [`COMPONENTS.md`](./COMPONENTS.md)
 - [`FORMAT.md`](./FORMAT.md)
 - [`STYLING.md`](./STYLING.md)
-- [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md)
+- [`PROFILES.md`](./PROFILES.md)
 - [`../AGENTS.md`](../AGENTS.md)

package/docs/COMPONENTS.md

@@ -10,80 +10,79 @@ Detailed AI-friendly profiles are collected in [`PROFILES.md`](./PROFILES.md).
 
 ## Form And Input
 
-- [`UiField`](./profiles/UiField.yml): field wrapper with label, hint, validation state, and slot props for ARIA wiring
-- [`UiTextbox`](./profiles/UiTextbox.yml): text or numeric input with prefix, suffix, clear action, and multiline mode
-- [`UiCheckbox`](./profiles/UiCheckbox.yml): boolean choice
-- [`UiRadio`](./profiles/UiRadio.yml): single choice
-- [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml): segmented single-choice switch with inline or section-card appearance
-- [`UiRadioSwitchOption`](./profiles/UiRadioSwitchOption.yml): rich option child for UiRadioSwitch
-- [`UiToggleGroup`](./profiles/UiToggleGroup.yml): segmented multi-select group built from toggle buttons
-- [`UiToggleGroupOption`](./profiles/UiToggleGroupOption.yml): rich option child for UiToggleGroup
-- [`UiSwitch`](./profiles/UiSwitch.yml): state toggle
-- [`UiSlider`](./profiles/UiSlider.yml): ranged value selection
-- [`UiSelect`](./profiles/UiSelect.yml): select container for single or multiple choice
-- [`UiSelectOption`](./profiles/UiSelectOption.yml): select option
-- [`UiSelectOptionGroup`](./profiles/UiSelectOptionGroup.yml): grouped options
-- [`UiDatePicker`](./profiles/UiDatePicker.yml): date or date-range selection
-- [`UiTimePicker`](./profiles/UiTimePicker.yml): time selection
-- [`UiCalendar`](./profiles/UiCalendar.yml): calendar primitive
-- [`UiNumberStepper`](./profiles/UiNumberStepper.yml): numeric input with increment and decrement controls
+- [`UiField`](./profiles/components/UiField.yml): field wrapper with label, hint, validation state, and slot props for ARIA wiring
+- [`UiTextbox`](./profiles/components/UiTextbox.yml): text or numeric input with prefix, suffix, clear action, and multiline mode
+- [`UiCheckbox`](./profiles/components/UiCheckbox.yml): boolean choice
+- [`UiRadio`](./profiles/components/UiRadio.yml): single choice
+- [`UiRadioSwitch`](./profiles/components/UiRadioSwitch.yml): segmented single-choice switch with inline or section-card appearance
+- [`UiRadioSwitchOption`](./profiles/components/UiRadioSwitchOption.yml): rich option child for UiRadioSwitch
+- [`UiToggleGroup`](./profiles/components/UiToggleGroup.yml): segmented multi-select group built from toggle buttons
+- [`UiToggleGroupOption`](./profiles/components/UiToggleGroupOption.yml): rich option child for UiToggleGroup
+- [`UiSwitch`](./profiles/components/UiSwitch.yml): state toggle
+- [`UiSlider`](./profiles/components/UiSlider.yml): ranged value selection
+- [`UiSelect`](./profiles/components/UiSelect.yml): select container for single or multiple choice
+- [`UiSelectOption`](./profiles/components/UiSelectOption.yml): select option
+- [`UiSelectOptionGroup`](./profiles/components/UiSelectOptionGroup.yml): grouped options
+- [`UiDatePicker`](./profiles/components/UiDatePicker.yml): date or date-range selection
+- [`UiTimePicker`](./profiles/components/UiTimePicker.yml): time selection
+- [`UiCalendar`](./profiles/components/UiCalendar.yml): calendar primitive
+- [`UiNumberStepper`](./profiles/components/UiNumberStepper.yml): numeric input with increment and decrement controls
 
 ## Actions And Navigation
 
-- [`UiButton`](./profiles/UiButton.yml): main action button that can render as a button or anchor
-- [`UiToggleButton`](./profiles/UiToggleButton.yml): stateful toggle button primitive for standalone or grouped use
-- [`UiAddButton`](./profiles/UiAddButton.yml): add action button
-- [`UiCopyButton`](./profiles/UiCopyButton.yml): copy value action
-- [`UiToolbarButton`](./profiles/UiToolbarButton.yml): toolbar button
-- [`UiToolbarLink`](./profiles/UiToolbarLink.yml): toolbar link
-- [`UiLink`](./profiles/UiLink.yml): text link
-- [`UiMenuItem`](./profiles/UiMenuItem.yml): menu item
-- [`UiMenuItemGroup`](./profiles/UiMenuItemGroup.yml): menu item group
-- [`UiTabGroup`](./profiles/UiTabGroup.yml): tab navigation group with overflow handling and optional active panel
-- [`UiTab`](./profiles/UiTab.yml): declarative tab child for UiTabGroup
+- [`UiButton`](./profiles/components/UiButton.yml): main action button that can render as a button or anchor
+- [`UiToggleButton`](./profiles/components/UiToggleButton.yml): stateful toggle button primitive for standalone or grouped use
+- [`UiAddButton`](./profiles/components/UiAddButton.yml): add action button
+- [`UiCopyButton`](./profiles/components/UiCopyButton.yml): copy value action
+- [`UiToolbarButton`](./profiles/components/UiToolbarButton.yml): toolbar button
+- [`UiToolbarLink`](./profiles/components/UiToolbarLink.yml): toolbar link
+- [`UiLink`](./profiles/components/UiLink.yml): text link
+- [`UiMenuItem`](./profiles/components/UiMenuItem.yml): menu item
+- [`UiMenuItemGroup`](./profiles/components/UiMenuItemGroup.yml): menu item group
+- [`UiTabGroup`](./profiles/components/UiTabGroup.yml): tab navigation group with overflow handling and optional active panel
+- [`UiTab`](./profiles/components/UiTab.yml): declarative tab child for UiTabGroup
 
 ## Layout And Structure
 
-- [`UiPageHeader`](./profiles/UiPageHeader.yml): page or section header with an editable title and action zone
-- [`UiCollapse`](./profiles/UiCollapse.yml): collapsible section
-- [`UiCollapseBox`](./profiles/UiCollapseBox.yml): collapsible container
-- [`UiCollapseGroup`](./profiles/UiCollapseGroup.yml): multiple collapse coordination
-- [`UiScrollBox`](./profiles/UiScrollBox.yml): scrollable container
-- [`UiTransition`](./profiles/UiTransition.yml): transition wrapper
+- [`UiPageHeader`](./profiles/components/UiPageHeader.yml): page or section header with an editable title and action zone
+- [`UiCollapse`](./profiles/components/UiCollapse.yml): collapsible section
+- [`UiCollapseBox`](./profiles/components/UiCollapseBox.yml): collapsible container
+- [`UiCollapseGroup`](./profiles/components/UiCollapseGroup.yml): multiple collapse coordination
+- [`UiScrollBox`](./profiles/components/UiScrollBox.yml): scrollable container
+- [`UiTransition`](./profiles/components/UiTransition.yml): transition wrapper
 
 ## Feedback And Status
 
-- [`UiAlert`](./profiles/UiAlert.yml): contextual alert or notification
-- [`UiInfobox`](./profiles/UiInfobox.yml): highlighted explanatory block
-- [`UiError`](./profiles/UiError.yml): compact error state
-- [`UiLoader`](./profiles/UiLoader.yml): loading indicator
-- [`UiSkeleton`](./profiles/UiSkeleton.yml): content placeholder for loading state
-- [`UiTag`](./profiles/UiTag.yml): labels and statuses
+- [`UiAlert`](./profiles/components/UiAlert.yml): contextual alert or notification
+- [`UiInfobox`](./profiles/components/UiInfobox.yml): highlighted explanatory block
+- [`UiError`](./profiles/components/UiError.yml): compact error state
+- [`UiLoader`](./profiles/components/UiLoader.yml): loading indicator
+- [`UiSkeleton`](./profiles/components/UiSkeleton.yml): content placeholder for loading state
+- [`UiTag`](./profiles/components/UiTag.yml): labels and statuses
 
 ## Overlays And Modal Patterns
 
-- [`UiModalWindow`](./profiles/UiModalWindow.yml): modal window
-- [`UiModalWindowSurface`](./profiles/UiModalWindowSurface.yml): modal surface
-- [`UiModalSidebar`](./profiles/UiModalSidebar.yml): sidebar modal
-- [`UiTooltip`](./profiles/UiTooltip.yml): tooltip
-- [`UiPopper`](./profiles/UiPopper.yml): floating layer
-- [`UiPopperTarget`](./profiles/UiPopperTarget.yml): popper target
-- [`UiPopperConnector`](./profiles/UiPopperConnector.yml): target-to-floating connector
+- [`UiModalWindow`](./profiles/components/UiModalWindow.yml): modal window
+- [`UiModalWindowSurface`](./profiles/components/UiModalWindowSurface.yml): modal surface
+- [`UiModalSidebar`](./profiles/components/UiModalSidebar.yml): sidebar modal
+- [`UiTooltip`](./profiles/components/UiTooltip.yml): tooltip
+- [`UiPopper`](./profiles/components/UiPopper.yml): floating layer
+- [`UiPopperTarget`](./profiles/components/UiPopperTarget.yml): popper target
+- [`UiPopperConnector`](./profiles/components/UiPopperConnector.yml): target-to-floating connector
 
 ## Content And Data Display
 
-- [`UiAvatar`](./profiles/UiAvatar.yml): avatar
-- [`UiAvatarList`](./profiles/UiAvatarList.yml): avatar list
-- [`UiDate`](./profiles/UiDate.yml): formatted date display
-- [`UiImage`](./profiles/UiImage.yml): image display
-- [`UiTable`](./profiles/UiTable.yml): table root
-- [`UiTableColumn`](./profiles/UiTableColumn.yml): table column declaration
-- [`UiTableHeadCell`](./profiles/UiTableHeadCell.yml): table head cell primitive
-- [`UiTableBodyCell`](./profiles/UiTableBodyCell.yml): table body cell primitive
-- [`UiTableFooterSection`](./profiles/UiTableFooterSection.yml): table footer section container
-- [`UiTableFooterButton`](./profiles/UiTableFooterButton.yml): table footer action button
-- [`UiTableSorter`](./profiles/UiTableSorter.yml): table sort control primitive
-- [`UiYandexMap`](./profiles/UiYandexMap.yml): Yandex map component
+- [`UiAvatar`](./profiles/components/UiAvatar.yml): avatar
+- [`UiAvatarList`](./profiles/components/UiAvatarList.yml): avatar list
+- [`UiDate`](./profiles/components/UiDate.yml): formatted date display
+- [`UiTable`](./profiles/components/UiTable.yml): table root
+- [`UiTableColumn`](./profiles/components/UiTableColumn.yml): table column declaration
+- [`UiTableHeadCell`](./profiles/components/UiTableHeadCell.yml): table head cell primitive
+- [`UiTableBodyCell`](./profiles/components/UiTableBodyCell.yml): table body cell primitive
+- [`UiTableFooterSection`](./profiles/components/UiTableFooterSection.yml): table footer section container
+- [`UiTableFooterButton`](./profiles/components/UiTableFooterButton.yml): table footer action button
+- [`UiTableSorter`](./profiles/components/UiTableSorter.yml): table sort control primitive
+- [`UiYandexMap`](./profiles/components/UiYandexMap.yml): Yandex map component
 
 ## Helpers
 

package/docs/FORMAT.md

@@ -19,9 +19,9 @@ 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`.
+Component profiles should live in `docs/profiles/components`.
+Page-composition profiles should live in `docs/profiles/pages`.
+Use `examples` for copyable snippets and cross-link related profiles with relative `profile` paths.
 
 Minimal shape:
 
@@ -29,7 +29,6 @@ Minimal shape:
 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'
@@ -228,8 +227,7 @@ List:
 - safe defaults for typical screens;
 - 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.
+Keep examples in YAML profiles focused, copyable, and aligned with the public package entrypoints.
 
 ## 12. `ai_notes`
 
@@ -245,7 +243,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`.
+- Keep runnable examples in YAML profiles when they clarify safe public 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.
@@ -256,7 +254,7 @@ The following data can usually be obtained automatically or semi-automatically:
 
 - the list of public exports;
 - prop, emit, method, and enum names;
-- whether Storybook stories and examples exist;
+- whether profile examples exist;
 - the current root classes and layout zones from templates.
 
 These sections almost always need manual writing:

package/docs/PROFILES.md

@@ -1,12 +1,13 @@
-# Component Profiles
+# AI Profiles
 
-`PROFILES.md` is the entry point for machine-readable AI-friendly component profiles.
+`PROFILES.md` is the entry point for machine-readable AI-friendly profiles.
 
 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, composition, and AI rules.
+- component profiles live in `docs/profiles/components/*.yml`;
+- page-composition profiles live in `docs/profiles/pages/*.yml`;
+- YAML is the source of truth for structure, props, slots, emits, composition, page patterns, and AI rules.
 
 ## Table Of Contents
 
@@ -31,24 +32,34 @@ Coverage is now expanding across the public component catalog.
 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
+- `docs/profiles/components/*.yml` for per-component machine-readable profiles
+- `docs/profiles/pages/*.yml` for page, modal, sidebar, filter, table, and settings-layout profiles
 
 Current high-signal core profiles:
 
-- [`UiField`](./profiles/UiField.yml)
-- [`UiTextbox`](./profiles/UiTextbox.yml)
-- [`UiButton`](./profiles/UiButton.yml)
-- [`UiToggleButton`](./profiles/UiToggleButton.yml)
-- [`UiToggleGroup`](./profiles/UiToggleGroup.yml)
-- [`UiPageHeader`](./profiles/UiPageHeader.yml)
-- [`UiSelect`](./profiles/UiSelect.yml)
-- [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml)
-- [`UiTabGroup`](./profiles/UiTabGroup.yml)
-- [`UiTab`](./profiles/UiTab.yml)
-- [`UiPopper`](./profiles/UiPopper.yml)
-- [`UiPopperConnector`](./profiles/UiPopperConnector.yml)
-- [`UiPopperTarget`](./profiles/UiPopperTarget.yml)
+- [`UiField`](./profiles/components/UiField.yml)
+- [`UiTextbox`](./profiles/components/UiTextbox.yml)
+- [`UiButton`](./profiles/components/UiButton.yml)
+- [`UiToggleButton`](./profiles/components/UiToggleButton.yml)
+- [`UiToggleGroup`](./profiles/components/UiToggleGroup.yml)
+- [`UiPageHeader`](./profiles/components/UiPageHeader.yml)
+- [`UiSelect`](./profiles/components/UiSelect.yml)
+- [`UiRadioSwitch`](./profiles/components/UiRadioSwitch.yml)
+- [`UiTabGroup`](./profiles/components/UiTabGroup.yml)
+- [`UiTab`](./profiles/components/UiTab.yml)
+- [`UiPopper`](./profiles/components/UiPopper.yml)
+- [`UiPopperConnector`](./profiles/components/UiPopperConnector.yml)
+- [`UiPopperTarget`](./profiles/components/UiPopperTarget.yml)
+
+Current page profiles:
+
+- [`PageComposition`](./profiles/pages/PageComposition.yml)
+- [`EntityListPage`](./profiles/pages/EntityListPage.yml)
+- [`CardSettingsPage`](./profiles/pages/CardSettingsPage.yml)
+- [`MultiColumnPage`](./profiles/pages/MultiColumnPage.yml)
+- [`CollapseBlockPage`](./profiles/pages/CollapseBlockPage.yml)
+- [`ModalSidebar`](./profiles/pages/ModalSidebar.yml)
+- [`ModalWindow`](./profiles/pages/ModalWindow.yml)
 
 ## What To Read First
 
@@ -56,8 +67,9 @@ 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.
-- `usage` if you need Storybook examples or visual behavior.
+- `examples` if you need copyable usage snippets.
 - `ai_notes` if the agent needs safe defaults and anti-patterns.
+- `profiles/pages/*.yml` if the task is about a full page, modal, sidebar, filter, table, or settings layout.
 
 ## Styling Reads
 
@@ -67,4 +79,5 @@ 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.
+- Keep component-level details in `profiles/components`.
+- Keep page-composition details in `profiles/pages`.

package/docs/README.md

@@ -21,10 +21,8 @@ These docs are optimized for two main scenarios:
   the target component profile format for AI assistants.
 - [`STYLING.md`](./STYLING.md)
   shared guidance for reading classes, CSS variables, and typography in profiles.
-- [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md)
-  page composition rules for agents generating full RetailCRM extension screens.
 - [`PROFILES.md`](./PROFILES.md)
-  the index of YAML component profiles.
+  the index of YAML component and page profiles.
 
 ## Public Entrypoints
 
@@ -62,7 +60,7 @@ If you need to generate UI quickly:
 3. [`AI.md`](./AI.md)
 4. [`COMPONENTS.md`](./COMPONENTS.md)
 5. the relevant profile from [`PROFILES.md`](./PROFILES.md)
-6. [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md) if the task is about complete pages,
+6. the relevant page profile from [`PROFILES.md`](./PROFILES.md) if the task is about complete pages,
    modals, sidebars, filters, tables, or settings layouts
 7. [`STYLING.md`](./STYLING.md) if the task is about classes, variables, typography, or layout tuning
 
@@ -70,5 +68,4 @@ If you are extending the docs:
 
 1. [`FORMAT.md`](./FORMAT.md)
 2. [`STYLING.md`](./STYLING.md)
-3. [`AGENT-DESIGN-GUIDELINES.md`](./AGENT-DESIGN-GUIDELINES.md)
-4. the existing profiles in [`PROFILES.md`](./PROFILES.md)
+3. the existing profiles in [`PROFILES.md`](./PROFILES.md)

package/docs/profiles/{UiAddButton.yml → components/UiAddButton.yml}

@@ -2,7 +2,6 @@ component: UiAddButton
 summary: >
   UiAddButton is an action-first button for add or create flows. It is close to UiButton,
   but tuned for "create another item" scenarios and supports small descriptive additions.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiaddbutton--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -13,6 +12,55 @@ related_components:
   - UiButton
   - UiToolbarButton
 
+examples:
+  - title: Basic add button
+    code: |
+      <template>
+        <UiAddButton>
+          Add Button
+        </UiAddButton>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAddButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Small add button (`small`)
+    code: |
+      <template>
+        <UiAddButton small>
+          Add Button
+        </UiAddButton>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAddButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Description slot
+    code: |
+      <template>
+        <UiAddButton color="blue">
+          Add Button
+
+          <template #description>
+            Description
+          </template>
+        </UiAddButton>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAddButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Custom height
+    code: |
+      <template>
+        <UiAddButton :height="120">Add Button</UiAddButton>
+        <UiAddButton height="50%">Add Button</UiAddButton>
+
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAddButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
 use_when:
   - You need a dedicated create or add action.
   - You need a compact add CTA with optional extra description.
@@ -82,6 +130,5 @@ styling:
   notes:
     - Use documented props and slots as the primary styling API.
     - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-add-button

package/docs/profiles/{UiAlert.yml → components/UiAlert.yml}

@@ -2,13 +2,44 @@ component: UiAlert
 summary: >
   UiAlert is a compact contextual message block for status, warning, success, and danger feedback.
   It can be shown inline in normal page flow and can be closable.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uialert--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
   named:
     - UiAlert
 
+examples:
+  - title: Basic alert
+    code: |
+      <template>
+        <UiAlert text="Basic alert" />
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAlert } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Warning alert
+    code: |
+      <template>
+        <UiAlert variant="warning" text="Warning alert" />
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAlert } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Closable alert
+    code: |
+      <template>
+        <UiAlert
+          closable
+          text="You can close this alert manually"
+        />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAlert } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
 use_when:
   - You need inline status feedback.
   - You need dismissible page-level or section-level notice content.
@@ -70,6 +101,5 @@ styling:
   notes:
     - Use documented props and slots as the primary styling API.
     - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-alert

package/docs/profiles/{UiAvatar.yml → components/UiAvatar.yml}

@@ -2,13 +2,28 @@ component: UiAvatar
 summary: >
   UiAvatar renders a user or entity avatar with optional name, status, and link semantics.
   It is meant for compact identity display rather than generic image rendering.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiavatar--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
   named:
     - UiAvatar
 
+examples:
+  - title: Basic avatar
+    code: |
+      <template>
+        <UiAvatar
+          name="Anna Smith"
+          src="https://example.com/avatar.jpg"
+          size="sm"
+          status="none"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAvatar } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
 use_when:
   - You need a compact identity marker for a user or contact.
   - You need avatar display with optional status.
@@ -47,7 +62,7 @@ ai_notes:
     - Use UiAvatar for identity display, not for general media.
     - Provide name whenever possible so fallback identity stays meaningful.
   avoid:
-    - Do not use it where UiImage is the better semantic fit.
+    - Do not use it for generic content images or large media blocks.
 
 composition:
   works_well_with:
@@ -69,6 +84,5 @@ styling:
   notes:
     - Use documented props and slots as the primary styling API.
     - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-avatar

package/docs/profiles/{UiAvatarList.yml → components/UiAvatarList.yml}

@@ -2,7 +2,6 @@ component: UiAvatarList
 summary: >
   UiAvatarList renders a compact list of avatars with consistent sizing. It is useful for showing
   several users or actors in a narrow area.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiavatar--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -65,6 +64,5 @@ styling:
   notes:
     - Use documented props and slots as the primary styling API.
     - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-avatar-list

package/docs/profiles/{UiButton.yml → components/UiButton.yml}

@@ -3,13 +3,26 @@ summary: >
   UiButton is the main action component in the library. It covers primary, secondary,
   tertiary, and outlined use cases, can render as either a button or an anchor,
   and adapts well to text-plus-icon and icon-only content.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uibutton--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
   named:
     - UiButton
 
+examples:
+  - title: States
+    code: |
+      <template>
+          <UiButton variant="danger">
+              <IconDelete /> Delete
+          </UiButton>
+      </template>
+
+      <script lang="ts" setup>
+      import IconDelete from '@retailcrm/embed-ui-v1-components/assets/sprites/ui/delete-outlined.svg'
+      import { UiButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
 use_when:
   - You need a primary or secondary action in a form or screen.
   - You need an inline action in a header, modal, infobox, or toolbar-like area.