From 2fd4e1da41bf6d7a1a874428e358087738698ab4 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Fri, 29 May 2026 18:55:33 +0400
Subject: [PATCH 1/2] docs(v1-components): Component guidance refined

---
 packages/v1-components/docs/AI.md             | 19 ++++++++++++++-
 packages/v1-components/docs/STYLING.md        | 22 +++++++++++++++++
 .../docs/profiles/components/UiAvatar.yml     | 13 +++++++++-
 .../docs/profiles/components/UiButton.yml     |  6 ++++-
 .../docs/profiles/components/UiCheckbox.yml   | 24 ++++++++++++-------
 .../docs/profiles/components/UiField.yml      |  7 ++++--
 .../profiles/components/UiNumberStepper.yml   |  3 +++
 .../docs/profiles/components/UiSwitch.yml     |  3 +++
 .../docs/profiles/components/UiTextbox.yml    |  2 ++
 .../docs/profiles/pages/CardSettingsPage.yml  |  9 ++++++-
 .../docs/profiles/pages/EntityListPage.yml    |  3 +++
 .../docs/profiles/pages/PageComposition.yml   |  4 ++++
 .../embed-ui-v1-components-ui/SKILL.md.txt    |  7 ++++++
 13 files changed, 108 insertions(+), 14 deletions(-)

diff --git a/packages/v1-components/docs/AI.md b/packages/v1-components/docs/AI.md
index a046b7ef..8deafb08 100644
--- a/packages/v1-components/docs/AI.md
+++ b/packages/v1-components/docs/AI.md
@@ -63,10 +63,13 @@ When building a basic form or settings screen, start from patterns like:
 ```ts
 import {
   UiButton,
+  UiCheckbox,
   UiField,
+  UiNumberStepper,
   UiPageFooter,
   UiPageHeader,
   UiSelect,
+  UiSwitch,
   UiTextbox,
 } from '@retailcrm/embed-ui-v1-components/remote'
 ```
@@ -75,6 +78,9 @@ Typical compositions:
 
 - `UiField` + `UiTextbox`
 - `UiField` + `UiSelect`
+- `UiField` + `UiNumberStepper`
+- `UiSwitch` + visible label + hint row
+- `UiCheckbox` + visible label row or checkbox group
 - `UiPageHeader` + `UiButton`
 - `UiSelect` + `UiSelectOption`
 
@@ -91,15 +97,20 @@ Default screen rules:
 - use `UiPageFooter` for page-level save/cancel/delete actions instead of recreating a local footer;
 - use one `Success Primary` button for the strongest save/apply/create action that commits a result; use `Default Primary`
   only for another important action with a different meaning;
+- use `Secondary` buttons for real neighboring commands that should still look like buttons;
+- use `Tertiary` buttons for lower-emphasis edit, open, configure, cancel, close, and optional commands near headers,
+  cards, tables, and inline content;
 - apply the 24px top and 32px side/bottom padding rule to white content surfaces, not to the page root wrapper;
 - keep filters and controls near the content they affect;
-- use `UiField` around labeled form controls;
+- use `UiField` around labeled textbox, select, number, date, and time 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`;
 - when a component uses only the default slot, prefer `v-slot` on the component instead of `<template #default>`;
 - avoid custom markup that recreates textbox, select, button, link, or table chrome.
+- before passing enum-like prop values, check the component profile or public type; omit optional props instead of
+  inventing neutral values such as `"none"` when they are not listed.
 
 ## Default Recommendation For Table Screens
 
@@ -142,10 +153,16 @@ When building forms with remote controls:
 - use `UiField` for labeled text, select, date, and number controls;
 - forward `UiField` slot props into the actual child control when it accepts `id`, especially
   `UiTextbox`, `UiSelect`, and `UiNumberStepper`;
+- put validation errors inside the relevant field composition, not as unrelated sibling blocks;
 - when a component uses only the default slot, prefer `v-slot` on the component instead of
   `<template #default>`;
 - do not wrap `UiSwitch` in `UiField`; place the switch next to a visible label and optional hint,
   and connect `UiSwitch :id` with `label :for`.
+- do not wrap simple `UiCheckbox` rows in `UiField`; place the checkbox next to a visible label and optional hint.
+- use `UiSwitch` for compact immediate boolean settings, feature toggles, and enable/disable flags.
+- use `UiCheckbox` for checkbox groups, table row selection, "select all", acknowledgements, and checkbox-shaped choices.
+- use `UiNumberStepper` for bounded numeric settings, quantities, durations, limits, and values with meaningful increments.
+- use `UiTextbox` for numeric-looking text such as phone numbers, codes, identifiers, and free-form numeric strings.
 
 ## Default Recommendation For Widgets
 
diff --git a/packages/v1-components/docs/STYLING.md b/packages/v1-components/docs/STYLING.md
index 5c2d46d1..a7377ba5 100644
--- a/packages/v1-components/docs/STYLING.md
+++ b/packages/v1-components/docs/STYLING.md
@@ -157,6 +157,28 @@ For style-sensitive generation:
 4. avoid relying on internal descendant selectors unless the profile says that is safe;
 5. state which styling source is being followed when the change was requested by design feedback.
 
+## Remote Page Styles
+
+For Vue remote pages and page-like components, prefer local CSS Modules:
+
+```vue
+<style module lang="less">
+```
+
+Apply classes through `$style[...]` in the template. Use `@import (reference)` from
+`@retailcrm/embed-ui-v1-components/assets/stylesheets/*` for shared LESS tokens and typography
+mixins.
+
+Remote page styles should normally:
+
+- use package spacing, palette, geometry, and typography tokens instead of local hardcoded colors,
+  font sizes, weights, and spacing;
+- keep styles local to the page or component through CSS Modules;
+- avoid shared global files such as `admin.less` as the default strategy;
+- avoid duplicating CRM host layout padding on the page root;
+- put documented 24px top and 32px side/bottom padding on white content surfaces when such a
+  surface exists.
+
 ## Design Feedback Triage
 
 When design feedback does not match the current implementation, resolve the source before editing:
diff --git a/packages/v1-components/docs/profiles/components/UiAvatar.yml b/packages/v1-components/docs/profiles/components/UiAvatar.yml
index 0f7e04f4..d9f31f0e 100644
--- a/packages/v1-components/docs/profiles/components/UiAvatar.yml
+++ b/packages/v1-components/docs/profiles/components/UiAvatar.yml
@@ -16,7 +16,6 @@ examples:
           name="Anna Smith"
           src="https://example.com/avatar.jpg"
           size="sm"
-          status="none"
         />
       </template>
 
@@ -37,7 +36,17 @@ api:
     - name: src
     - name: name
     - name: status
+      values:
+        - busy
+        - break
+        - dinner
+        - free
+      notes: Omit status when no indicator should be shown; do not pass "none".
     - name: size
+      values:
+        - xs
+        - sm
+        - lg
     - name: href
 
 rendered_structure:
@@ -61,8 +70,10 @@ ai_notes:
   do:
     - Use UiAvatar for identity display, not for general media.
     - Provide name whenever possible so fallback identity stays meaningful.
+    - Omit optional enum-like props when no listed value applies.
   avoid:
     - Do not use it for generic content images or large media blocks.
+    - Do not pass unsupported neutral values such as status="none"; check listed values first.
 
 composition:
   works_well_with:
diff --git a/packages/v1-components/docs/profiles/components/UiButton.yml b/packages/v1-components/docs/profiles/components/UiButton.yml
index 4fd729f0..27bdceb1 100644
--- a/packages/v1-components/docs/profiles/components/UiButton.yml
+++ b/packages/v1-components/docs/profiles/components/UiButton.yml
@@ -211,6 +211,8 @@ behavior:
       notes: Enables the separate locked state.
   notes:
     - If href is present, the component becomes a link-shaped action.
+    - appearance="secondary" is for neighboring commands that should still read as real buttons.
+    - appearance="tertiary" is for lower-emphasis actions near headers, cards, tables, and inline content.
 
 accessibility:
   notes:
@@ -231,7 +233,9 @@ ai_notes:
     - Start with appearance=primary for the main CTA, then choose variant by meaning.
     - Use variant="success" for the strongest create/save/apply action when it commits a result, and keep only one Success Primary on a page.
     - Use the default variant for an important primary action that is not the strongest commit action.
-    - Use secondary or tertiary for neighboring actions near titles.
+    - Use secondary for a real neighboring command that should still look like a button.
+    - Use tertiary for lower-emphasis edit, open, configure, cancel, close, and optional commands that should not compete with the main flow.
   avoid:
     - Do not replace UiButton with UiLink when the action should read as a button.
     - Do not use UiButton for regular inline text navigation.
+    - Do not default every non-primary action to secondary; choose tertiary when the action is only supportive.
diff --git a/packages/v1-components/docs/profiles/components/UiCheckbox.yml b/packages/v1-components/docs/profiles/components/UiCheckbox.yml
index b18c085c..15356b9d 100644
--- a/packages/v1-components/docs/profiles/components/UiCheckbox.yml
+++ b/packages/v1-components/docs/profiles/components/UiCheckbox.yml
@@ -1,7 +1,7 @@
 component: UiCheckbox
 summary: >
-  UiCheckbox is a boolean or set-membership control. It supports single boolean-like usage
-  as well as model-plus-value patterns for checkbox groups.
+  UiCheckbox is a checkbox or set-membership control. It supports single acknowledgement-like
+  choices, table row selection, "select all" states, and model-plus-value patterns for checkbox groups.
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -37,12 +37,14 @@ examples:
       const channels = ref<string[]>([])
       </script>
 use_when:
-  - You need a yes or no control.
+  - You need a checkbox-shaped boolean choice such as an acknowledgement or confirmation.
   - You need one value inside a checkbox group model.
+  - You need row selection, mass selection, or an indeterminate "select all" control.
 
 avoid_when:
   - You need exclusive single choice, use UiRadio instead.
-  - You need a more compact toggle-like control, use UiSwitch instead.
+  - You need a compact immediate on or off setting, use UiSwitch instead.
+  - You need a settings toggle row where a switch better communicates enable or disable state.
 
 api:
   key_props:
@@ -73,26 +75,32 @@ behavior:
   notes:
     - model plus value supports group-style selection.
     - indeterminate is useful for partial selection states.
+    - For ordinary settings toggles, UiSwitch is usually the better control even when the value is boolean.
 
 ai_notes:
   do:
-    - Use for boolean choice or checkbox-group membership.
+    - Use for checkbox-group membership, acknowledgement-like boolean choices, and table row selection.
     - Use indeterminate for parent selection such as "select all visible rows".
   avoid:
     - Do not use for mutually exclusive options.
+    - Do not replace UiSwitch settings toggles with UiCheckbox just because the value is boolean.
 
 composition:
   works_well_with:
-    - UiField
+    - visible label
+    - hint text
     - UiTable
     - UiTableColumn
   patterns:
-    - title: Form boolean
-      notes: Wrap in UiField when the checkbox needs a persistent label, hint, or validation text.
+    - title: Checkbox row
+      notes: Place UiCheckbox on the left, label and optional hint on the right, similar to a UiSwitch settings row.
+    - title: Checkbox group
+      notes: Use several UiCheckbox controls with one array model and visible labels for multi-selection.
     - title: Table row selection
       notes: Use in the first narrow UiTableColumn for row selection; use indeterminate in the header checkbox for partial selection.
   avoid:
     - Do not use as a visual switch replacement when the action is an immediate on or off setting.
+    - Do not wrap simple checkbox rows in UiField; use an explicit row with visible label and optional hint.
 
 accessibility:
   notes:
diff --git a/packages/v1-components/docs/profiles/components/UiField.yml b/packages/v1-components/docs/profiles/components/UiField.yml
index 5e30dad5..aaea2ddc 100644
--- a/packages/v1-components/docs/profiles/components/UiField.yml
+++ b/packages/v1-components/docs/profiles/components/UiField.yml
@@ -12,7 +12,6 @@ public_import:
 related_components:
   - UiTextbox
   - UiSelect
-  - UiCheckbox
   - UiNumberStepper
   - UiDatePicker
 
@@ -162,6 +161,8 @@ api:
           - UiDatePicker
         avoid:
           - several unrelated controls
+          - UiSwitch setting rows
+          - UiCheckbox setting rows
           - decorative layout only
           - raw content without using slot props
       layout_effect: The control sits below the headline and inherits field-level semantics through slot props.
@@ -311,8 +312,10 @@ ai_notes:
     - Forward slot props into the actual control in most form scenarios.
     - Pass field.id to child controls that accept id, including UiTextbox, UiSelect, and UiNumberStepper.
     - Use v-slot on UiField when the field uses only the default slot.
-    - Use UiField as a semantic wrapper for a single control.
+    - Use UiField as a semantic wrapper for a single textbox, select, number, date, or time control.
+    - Place validation errors inside the relevant field composition instead of rendering them as unrelated sibling blocks.
   avoid:
     - Do not use UiField as a generic visual container without control semantics.
     - Do not use UiField for UiSwitch settings rows; pair UiSwitch with a visible label and hint text instead.
+    - Do not use UiField for simple UiCheckbox rows; pair UiCheckbox with a visible label and optional hint instead.
     - Do not ignore id and ariaLabelledby when accessibility matters.
diff --git a/packages/v1-components/docs/profiles/components/UiNumberStepper.yml b/packages/v1-components/docs/profiles/components/UiNumberStepper.yml
index ff7f3136..e1652b01 100644
--- a/packages/v1-components/docs/profiles/components/UiNumberStepper.yml
+++ b/packages/v1-components/docs/profiles/components/UiNumberStepper.yml
@@ -28,9 +28,11 @@ examples:
 use_when:
   - You need numeric input with explicit step controls.
   - You need range constraints and nullable numeric state.
+  - You need bounded numeric settings, quantities, durations, limits, delays, or values with meaningful increments.
 
 avoid_when:
   - You need plain text or decimal input without stepper controls.
+  - You need numeric-looking text such as phone numbers, codes, identifiers, or free-form strings.
 
 api:
   key_props:
@@ -82,6 +84,7 @@ ai_notes:
     - Prefer nullable when clearing the value is a valid state.
   avoid:
     - Do not use when the value is an identifier, phone, code, or other numeric-looking text.
+    - Do not replace with UiTextbox for bounded numeric settings unless a runtime limitation is documented.
 
 accessibility:
   notes:
diff --git a/packages/v1-components/docs/profiles/components/UiSwitch.yml b/packages/v1-components/docs/profiles/components/UiSwitch.yml
index bde5fa24..233631b9 100644
--- a/packages/v1-components/docs/profiles/components/UiSwitch.yml
+++ b/packages/v1-components/docs/profiles/components/UiSwitch.yml
@@ -120,10 +120,12 @@ examples:
       </style>
 use_when:
   - You need a compact on or off toggle.
+  - You need an immediate boolean setting, feature flag, enable or disable control, or settings row.
 
 avoid_when:
   - You need checkbox-group semantics.
   - You need a UiField-style labeled wrapper; pair UiSwitch with a visible label and hint text instead.
+  - You need an acknowledgement, legal confirmation, table selection, or multi-select choice; use UiCheckbox instead.
 
 api:
   key_props:
@@ -170,6 +172,7 @@ ai_notes:
     - Put helper text below the label in the settings row, not in UiField hint.
   avoid:
     - Do not use for multi-select lists or legal acknowledgements; use UiCheckbox.
+    - Do not replace compact settings toggles with UiCheckbox just because the value is boolean.
     - Do not use UiField around UiSwitch.
 
 accessibility:
diff --git a/packages/v1-components/docs/profiles/components/UiTextbox.yml b/packages/v1-components/docs/profiles/components/UiTextbox.yml
index 0a8a02e9..f865ca73 100644
--- a/packages/v1-components/docs/profiles/components/UiTextbox.yml
+++ b/packages/v1-components/docs/profiles/components/UiTextbox.yml
@@ -37,12 +37,14 @@ use_when:
   - You need a standard text input.
   - You need search, email, phone, url, or password input.
   - You need decimal or numeric input without a separate stepper.
+  - You need numeric-looking text such as a phone, code, identifier, article, external id, or free-form numeric string.
   - You need a multiline control in the same visual language.
   - You need an input that composes well with UiField and inline editing.
 
 avoid_when:
   - You need value selection, not free-form input.
   - You need explicit increment and decrement UX.
+  - You need bounded numeric settings, quantities, durations, limits, or values with meaningful increments; use UiNumberStepper instead.
   - You need advanced formatting beyond the prefix or suffix model.
 
 api:
diff --git a/packages/v1-components/docs/profiles/pages/CardSettingsPage.yml b/packages/v1-components/docs/profiles/pages/CardSettingsPage.yml
index 81f0b644..81cdbf03 100644
--- a/packages/v1-components/docs/profiles/pages/CardSettingsPage.yml
+++ b/packages/v1-components/docs/profiles/pages/CardSettingsPage.yml
@@ -23,6 +23,8 @@ expected_structure:
   - The white content surface owns the 24px top and 32px side/bottom padding.
   - The page root wrapper should not repeat that padding.
   - Content can include text, buttons, fields, checkboxes, radio groups, switches, and other form controls.
+  - Textbox, select, number, date, and time controls usually live inside UiField.
+  - UiSwitch and simple UiCheckbox rows should use their own row layout with a visible label and optional hint, not UiField.
   - A bottom save panel is optional.
   - If a bottom save panel is used, its main save or apply action should be Success Primary.
 
@@ -55,9 +57,14 @@ recommended_components:
 ai_notes:
   do:
     - Keep form controls grouped by task or semantic section.
-    - Use UiField around labelled form controls.
+    - Use UiField around labeled textbox, select, number, date, and time controls.
+    - Use UiSwitch for compact enable or disable settings.
+    - Use UiCheckbox for checkbox groups, table selection, acknowledgements, and checkbox-shaped boolean choices.
     - Use tabs only when they reduce visible complexity without hiding required work.
     - Keep save/apply as the strongest footer action and move neighboring actions to secondary or tertiary appearances unless their variant has a distinct page-level meaning.
+    - Prefer tertiary for low-emphasis local actions that should not compete with the settings save flow.
   avoid:
     - Do not create a decorative landing page for operational settings.
     - Do not put content-surface padding on the root page wrapper.
+    - Do not use UiCheckbox as the default replacement for UiSwitch just because a setting is boolean.
+    - Do not wrap UiSwitch or simple UiCheckbox rows in UiField.
diff --git a/packages/v1-components/docs/profiles/pages/EntityListPage.yml b/packages/v1-components/docs/profiles/pages/EntityListPage.yml
index 7ab60baf..580c13bd 100644
--- a/packages/v1-components/docs/profiles/pages/EntityListPage.yml
+++ b/packages/v1-components/docs/profiles/pages/EntityListPage.yml
@@ -18,6 +18,7 @@ expected_structure:
   - 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 Default Primary button usually creates a new entity for the list when there is no stronger Success Primary action on the page.
+  - Supporting header actions that should not compete with the create action are usually tertiary rather than secondary.
   - 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.
@@ -65,8 +66,10 @@ ai_notes:
     - Persist filters, sorting, page, and page size in query parameters when routing is available.
     - Reset page to 1 when filters or sorting change.
     - Use narrow icon-only row action columns with matching aria-label and UiTooltip text.
+    - Use tertiary for low-emphasis header or row-adjacent commands when a secondary button would be too visually heavy.
   avoid:
     - Do not hide filters in page header actions.
     - Do not put pagination only in local state when the result set is routable.
     - Do not place UiTable inside an additional white card or padded content surface.
     - Do not use visible text buttons for dense table row actions.
+    - Do not make every header action secondary when only one action should draw attention.
diff --git a/packages/v1-components/docs/profiles/pages/PageComposition.yml b/packages/v1-components/docs/profiles/pages/PageComposition.yml
index 5db8a133..77094db8 100644
--- a/packages/v1-components/docs/profiles/pages/PageComposition.yml
+++ b/packages/v1-components/docs/profiles/pages/PageComposition.yml
@@ -22,6 +22,8 @@ shared_rules:
   - Use Default Primary for an important action that is secondary to the Success Primary or does not commit a result.
   - Use Danger Primary only for one critical destructive action when the page needs it.
   - If several actions compete for attention, choose the main one for Success Primary and move the rest to Default Primary, secondary, tertiary, or dropdown actions by meaning.
+  - Use secondary for a real neighboring command that should still read as a button.
+  - Use tertiary for lower-emphasis header, card, inline, configure, edit, open, cancel, and close actions that should not compete with the main flow.
   - UiPageHeader actions and UiPageFooter actions belong to the same page-level action scope.
   - Treat each UiCollapseBox footer as a separate local action scope with the same rules scoped to that section.
   - A page can have several Default Primary buttons when each one belongs to a different UiCollapseBox footer.
@@ -60,8 +62,10 @@ ai_notes:
     - Choose ModalWindow or a full page when content needs wide tables, several sections, or complex controls.
     - Keep operational CRM screens dense, scannable, and work-focused.
     - Prefer variant="success" for the main save/apply/create action and keep it visually dominant.
+    - Prefer appearance="tertiary" for supportive actions that sit near content but should stay visually quiet.
   avoid:
     - Do not turn internal CRM work screens into marketing-style layouts.
     - Do not hide filters or primary workflow controls away from the content they affect.
     - Do not place multiple Success Primary, Default Primary, or Danger Primary actions with the same variant in the page-level scope or inside one collapse-box scope.
+    - Do not default every non-primary action to appearance="secondary"; choose by local action importance.
     - Do not add page-surface padding to both the page root and the white content surface.
diff --git a/packages/v1-components/templates/skills/embed-ui-v1-components-ui/SKILL.md.txt b/packages/v1-components/templates/skills/embed-ui-v1-components-ui/SKILL.md.txt
index b4f1329f..68c08b76 100644
--- a/packages/v1-components/templates/skills/embed-ui-v1-components-ui/SKILL.md.txt
+++ b/packages/v1-components/templates/skills/embed-ui-v1-components-ui/SKILL.md.txt
@@ -26,13 +26,20 @@ Use this skill before changing frontend UI built with `@retailcrm/embed-ui-v1-co
 5. Do not hand-roll buttons, inputs, selects, tables, or links when a documented Embed UI component exists.
 6. Do not set arbitrary `font-family`; inherit the host/component stack unless a project-specific design requirement says otherwise.
 7. Do not style internal `.ui-v1-*` selectors unless the profile or `STYLING.md` explicitly documents that override pattern.
+8. For Vue remote pages, prefer `<style module lang="less">` with `$style[...]` and package LESS tokens/mixins.
+9. Before passing enum-like prop values, check the profile or public type; omit optional props instead of inventing neutral values.
 
 ## High-signal checks
 
 - For entity lists, use `UiTable`, `UiTableColumn`, and table footer slots.
 - For table pagination, follow the reference example in `UiTable.yml`: button sizes, active state, dividers, arrow assets, and scoped selector pattern.
 - For form fields, use `UiField` with the matching control and forward slot props such as `id` when the control accepts them.
+- Put validation errors inside the relevant field composition, not as unrelated sibling blocks.
 - For `UiSwitch`, use the documented switch + visible label + hint row instead of wrapping it in `UiField`.
+- For simple `UiCheckbox` rows, use checkbox + visible label + optional hint instead of wrapping it in `UiField`.
+- Use `UiSwitch` for compact boolean settings and `UiCheckbox` for checkbox groups, table row selection, select-all, and acknowledgements.
+- Use `UiNumberStepper` for bounded numeric settings and `UiTextbox` for numeric-looking text such as phones, codes, and identifiers.
+- Use `Secondary` buttons for real neighboring commands and `Tertiary` buttons for lower-emphasis edit/open/configure/cancel/close actions.
 - For widgets mounted into CRM targets, keep inline UI compact; move complex UI into `UiModalSidebar` or `UiModalWindow`.
 - For sidebar footers, group related actions, use 12px or 16px gaps inside groups, and confirm destructive icon-only actions with `UiPopconfirm okVariant="danger"`.
 

From 5656ed161f0429a2e00d82223e493ca07b28e940 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Fri, 29 May 2026 18:56:50 +0400
Subject: [PATCH 2/2] docs(v1-endpoint): Runtime page checks documented

---
 packages/v1-endpoint/docs/define-page-runner.md  | 16 ++++++++++++++++
 packages/v1-endpoint/docs/menu-placements.md     |  9 +++++++++
 packages/v1-endpoint/docs/page-routes.md         |  8 ++++++++
 .../embed-ui-v1-endpoint-runtime/SKILL.md.txt    |  3 +++
 4 files changed, 36 insertions(+)

diff --git a/packages/v1-endpoint/docs/define-page-runner.md b/packages/v1-endpoint/docs/define-page-runner.md
index 23bc7496..26bca90c 100644
--- a/packages/v1-endpoint/docs/define-page-runner.md
+++ b/packages/v1-endpoint/docs/define-page-runner.md
@@ -45,6 +45,22 @@ const pageRunner = definePageRunner({
 
 Если для `code` нет раннера, будет warning в консоль и noop-destroy.
 
+## Runtime-проверка страницы
+
+После первого минимального vertical slice проверяйте страницу внутри CRM host, а не только через build/lint.
+
+Минимальный чек:
+
+- manifest или publish payload содержит page descriptor object с `code`, `menu`, `menuItemTitle` и нужной
+  hierarchy metadata;
+- `code` в `pages[]` совпадает с ключом runner map в `definePageRunner`;
+- локальный dev server отдает `entrypoint` и `stylesheet` URL, которые указаны в extension config;
+- пункт меню появился в CRM и открывает route `/modules/<module-code>/<page-code>`;
+- frontend реально смонтировался в CRM host.
+
+Если ошибка видна только в minified bundle, соберите или отдайте dev bundle без минификации до изменения кода
+по догадке.
+
 ## `beforeMount`
 
 `beforeMount` вызывается после `app.use(pinia)` и до `app.mount(...)`.
diff --git a/packages/v1-endpoint/docs/menu-placements.md b/packages/v1-endpoint/docs/menu-placements.md
index d7f2d7b4..ea9130c1 100644
--- a/packages/v1-endpoint/docs/menu-placements.md
+++ b/packages/v1-endpoint/docs/menu-placements.md
@@ -61,6 +61,10 @@
 `menu: "private_main_menu"` и `parentMenuItemCode: "settings"`. Для страниц в разделе продаж используйте
 `menu: "activity_main_menu"` и соответствующий parent menu item, например `orders`.
 
+CRM также использует hierarchy из `pages[]` для видимой навигации и breadcrumb-like поведения. Сначала
+моделируйте нужную иерархию через `menu`, `parentMenuItemCode` и `menuItemOrdering`; локальные ссылки внутри
+страницы добавляйте только для дополнительной in-page navigation.
+
 ## Payload публикации
 
 При обновлении уже установленного расширения синхронизируйте существующий integration module через
@@ -130,6 +134,11 @@ const pageRunner = definePageRunner({
 Если host откроет страницу с `code`, которого нет в runner map, `definePageRunner` запишет warning
 в консоль и не смонтирует страницу.
 
+После изменения меню или pages manifest проверьте локальную CRM установку: пункт меню должен появиться,
+route `/modules/<module-code>/<page-code>` должен открываться, а `entrypoint` и `stylesheet` из extension
+config должны отдаваться локальным dev server. При runtime-ошибках в minified bundle сначала включите dev
+bundle или sourcemaps.
+
 Читайте также:
 
 - [`page-routes`](./page-routes.md) — как описывать page `code` и CRM-маршрут.
diff --git a/packages/v1-endpoint/docs/page-routes.md b/packages/v1-endpoint/docs/page-routes.md
index 9d0051ad..fb0efa6d 100644
--- a/packages/v1-endpoint/docs/page-routes.md
+++ b/packages/v1-endpoint/docs/page-routes.md
@@ -12,6 +12,10 @@ page `code` нужно описывать объектом manifest `pages[]` с
 строковую форму `pages: ["orders-dashboard"]` для публикации через RetailCRM API: backend ожидает
 `ConfigurationPage` object, а страница без `menu` не откроется по route `/modules/<module-code>/<page-code>`.
 
+Build/lint успех не доказывает, что страница откроется в CRM. После добавления новой страницы проверьте
+runtime lifecycle в host: page descriptor, menu item, route `/modules/<module-code>/<page-code>`,
+доступность `entrypoint` и `stylesheet`, и фактический mount frontend-кода.
+
 ## Что такое `page code`
 
 `page code` — стабильный идентификатор встраиваемой страницы внутри расширения.
@@ -94,6 +98,10 @@ const openSettings = (host: HostApi) => {
 }
 ```
 
+Breadcrumb-like navigation для module pages строится CRM из hierarchy в `pages[]`: `menu`,
+`parentMenuItemCode`, `menuItemOrdering` и связанных metadata. Не собирайте breadcrumbs вручную внутри
+страницы, если продуктовая задача явно не просит локальную in-page navigation.
+
 Читайте также:
 
 - [`menu-placements`](./menu-placements.md) — как связать пункт меню, page `code` и маршрут.
diff --git a/packages/v1-endpoint/templates/skills/embed-ui-v1-endpoint-runtime/SKILL.md.txt b/packages/v1-endpoint/templates/skills/embed-ui-v1-endpoint-runtime/SKILL.md.txt
index 68337458..43d55f08 100644
--- a/packages/v1-endpoint/templates/skills/embed-ui-v1-endpoint-runtime/SKILL.md.txt
+++ b/packages/v1-endpoint/templates/skills/embed-ui-v1-endpoint-runtime/SKILL.md.txt
@@ -29,6 +29,8 @@ Use this skill before changing JS module endpoint wiring, page registration, wid
 3. For widgets, choose the exact target from endpoint docs or MCP resources before writing UI.
 4. Use documented public entrypoints such as `@retailcrm/embed-ui-v1-endpoint/remote`; do not import from `dist/*`, source files, or repository-only paths.
 5. Keep widget inline UI compact; use component package widget composition guidance for UI mounted into CRM targets.
+6. After the first page vertical slice, verify it in the CRM host: menu item, `/modules/<moduleCode>/<pageCode>` route, entrypoint URL, stylesheet URL, and actual frontend mount.
+7. If a runtime error appears only in a minified bundle, switch to a dev bundle or sourcemaps before guessing.
 
 ## Page and menu checks
 
@@ -37,6 +39,7 @@ Use this skill before changing JS module endpoint wiring, page registration, wid
 - Use `parentMenuItemCode` and `menuItemOrdering` to model the intended CRM page/menu hierarchy.
 - Breadcrumb-like navigation is derived by CRM from the page/menu hierarchy passed in the extension config; do not hand-roll breadcrumbs in the page unless the product task explicitly asks for local in-page navigation.
 - For updating an already installed module, use the existing integration module edit/update flow and put pages under `integrationModule.integrations.embedJs.pages`.
+- Build/lint success does not prove page rendering; check the installed module in the CRM host when page routing or menu placement changed.
 
 ## Host API checks