@retailcrm/embed-ui-v1-endpoint 0.9.23 → 0.9.25

package/README.md

@@ -41,6 +41,7 @@ runEndpoint(runner)
 - [`createEndpoint`](./docs/create-endpoint.md) — как вручную создать endpoint с transport и messenger.
 - [`runEndpoint`](./docs/run-endpoint.md) — как поднять endpoint в точке входа веб-воркера одной строкой.
 - [`targets` и `defineTarget`](./docs/targets.md) — как типизировать цели виджетов и маршрутизировать их по target.
+- `@retailcrm/embed-ui-v1-components` `docs/profiles/widgets/WidgetComposition.yml` — как оформлять inline UI виджетов и когда уносить сложность в modal/sidebar.
 - [`menu-placements`](./docs/menu-placements.md) — как описывать меню и пункты навигации для встраиваемых страниц.
 - [`page-routes`](./docs/page-routes.md) — как связывать page `code`, CRM-маршрут и `definePageRunner`.
 - [`layout`](./docs/layout.md) — как выбирать паттерны компоновки страниц, `modal sidebar` и `modal window`, и из каких `v1-components` их собирать.
@@ -84,6 +85,15 @@ npx @retailcrm/embed-ui-v1-endpoint init-agents
 такого блока там ещё нет. С `--force` можно обновить уже существующий блок
 пакета.
 
+Для project-level skills можно создать `.agents/skills/embed-ui-v1-endpoint-runtime/SKILL.md`:
+
+```bash
+npx @retailcrm/embed-ui-v1-endpoint init-skills
+```
+
+Skill описывает повторяемый workflow для pages/widgets, runner setup, target selection,
+menu hierarchy, page publishing payloads и публичных границ Host API.
+
 ## Инициализация MCP-конфига
 
 Пакет также может сам добавить project-level MCP-настройки в целевой проект:

package/bin/embed-ui-v1-endpoint.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { fileURLToPath } from 'node:url'
 import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
@@ -13,6 +14,8 @@ const README_MCP_SECTION_HEADER = '## MCP For AI Assistants: @retailcrm/embed-ui
 const LEGACY_README_MCP_SECTION_HEADER = '## MCP For AI Assistants'
 const README_MCP_MARKER = 'embed-ui-v1-endpoint://targets'
 const MCP_SERVER_NAME = 'retailcrm-embed-ui-v1-endpoint'
+const SKILL_NAME = 'embed-ui-v1-endpoint-runtime'
+const SKILL_TEMPLATE_PATH = `templates/skills/${SKILL_NAME}/SKILL.md.txt`
 const MCP_BIN_NAME = process.platform === 'win32' ? 'embed-ui-v1-endpoint-mcp.cmd' : 'embed-ui-v1-endpoint-mcp'
 const RELATIVE_MCP_BIN_PATH = `./node_modules/.bin/${MCP_BIN_NAME}`
 const CLAUDE_PROJECT_MCP_BIN_PATH = `\${CLAUDE_PROJECT_DIR:-.}/node_modules/.bin/${MCP_BIN_NAME}`
@@ -49,6 +52,7 @@ const MCP_CLIENT_CONFIGS = {
 const HELP_TEXT = `Usage:
   npx ${PACKAGE_NAME} init-agents [target] [options]
   npx ${PACKAGE_NAME} init-config [target] [options]
+  npx ${PACKAGE_NAME} init-skills [target] [options]
 
 Options:
   -f, --force                  Replace existing managed sections and MCP server entries
@@ -58,6 +62,7 @@ Options:
 
 Examples:
   npx ${PACKAGE_NAME} init-agents
+  npx ${PACKAGE_NAME} init-skills
   npx ${PACKAGE_NAME} init-agents ./my-project
   npx ${PACKAGE_NAME} init-agents --force
   npx ${PACKAGE_NAME} init-config ./my-project
@@ -75,6 +80,10 @@ const printMcpNotice = (message) => {
   console.log(`MCP: ${message}`)
 }
 
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+const createSkill = () => fs.readFileSync(path.join(packageRoot, SKILL_TEMPLATE_PATH), 'utf8')
+
 const parseArgs = (argv) => {
   const options = {
     command: null,
@@ -157,9 +166,11 @@ When working with \`${PACKAGE_NAME}\` in this project:
 5. When the task involves widget targets, target placement, target contexts, target metadata, or choosing a target, use the package MCP server if it is available.
 6. First read \`embed-ui-v1-endpoint://targets\` to discover available target profiles.
 7. Then read the relevant \`embed-ui-v1-endpoint://targets/<encoded-target>\` resource before answering or changing code related to that target.
-8. A project \`.mcp.json\` may require restarting or reconnecting the AI client before MCP resources appear in the current session.
-9. If MCP resources are not available, use the generated YAML profiles from \`./node_modules/${PACKAGE_NAME}/docs/targets/*.yml\` as the fallback source.
-10. Prefer target profiles over guessing target placement, contexts, or semantic intent from names alone.
+8. For widget UI composition, keep inline target content compact: prefer \`UiToolbarButton\`, \`UiToolbarLink\`, short text, and icons; move complex UI into \`UiModalSidebar\` or \`UiModalWindow\`.
+9. If \`@retailcrm/embed-ui-v1-components\` is installed, read its widget composition docs before building widget UI.
+10. A project \`.mcp.json\` may require restarting or reconnecting the AI client before MCP resources appear in the current session.
+11. If MCP resources are not available, use the generated YAML profiles from \`./node_modules/${PACKAGE_NAME}/docs/targets/*.yml\` as the fallback source.
+12. Prefer target profiles over guessing target placement, contexts, or semantic intent from names alone.
 
 Suggested MCP stdio server configuration:
 
@@ -455,6 +466,35 @@ const initAgents = (target, force) => {
   console.log(`The ${PACKAGE_NAME} instructions were appended to the end of the file.`)
 }
 
+const initSkills = (target, options) => {
+  if (!fs.existsSync(target)) {
+    throw new Error(`Target path does not exist: ${target}`)
+  }
+
+  const stat = fs.statSync(target)
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Target path is not a directory: ${target}`)
+  }
+
+  const skillPath = path.join(target, '.agents', 'skills', SKILL_NAME, 'SKILL.md')
+  const fileExists = fs.existsSync(skillPath)
+
+  if (fileExists && !options.force) {
+    console.log(`${skillPath} already exists`)
+    console.log('Nothing was changed. Re-run with --force to refresh that skill.')
+    return
+  }
+
+  if (!options.dryRun) {
+    fs.mkdirSync(path.dirname(skillPath), { recursive: true })
+    fs.writeFileSync(skillPath, createSkill(), 'utf8')
+  }
+
+  const action = fileExists ? 'updated' : 'created'
+  console.log(`SKILL: ${options.dryRun ? `would ${action}` : action} ${skillPath}`)
+}
+
 const writeMcpServerConfig = (target, relativePath, rootField, options, serverConfig) => {
   const filePath = path.join(target, relativePath)
   const fileExists = fs.existsSync(filePath)
@@ -571,6 +611,11 @@ const main = () => {
       return
     }
 
+    if (options.command === 'init-skills') {
+      initSkills(options.target, options)
+      return
+    }
+
     throw new Error(`Unknown command: ${options.command}`)
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))

package/docs/README.md

@@ -14,6 +14,7 @@
 
 - [`targets` и `defineTarget`](./targets.md) — типизированные цели для виджетов.
 - [`targets/*.yml`](./targets/) — сгенерированные AI-friendly описания встроенных widget targets на английском.
+- `@retailcrm/embed-ui-v1-components` `docs/profiles/widgets/WidgetComposition.yml` — как оформлять inline UI виджетов и когда уносить сложность в modal/sidebar.
 - MCP-сервер `embed-ui-v1-endpoint-mcp` — поставляемый stdio server, который отдаёт `targets/*.yml` как MCP resources.
 - [`menu-placements`](./menu-placements.md) — как описывать меню и пункты навигации, из которых открываются встраиваемые страницы.
 - [`page-routes`](./page-routes.md) — как связывать page `code`, CRM-маршрут и `definePageRunner`.

package/docs/layout.md

@@ -31,6 +31,8 @@
 - Для контентных подложек базовое правило такое:
   - отступ от верхнего края подложки: `24px`;
   - отступы от левого, правого и нижнего края: `32px`.
+- Эти отступы относятся к белой контентной подложке, а не к корневому wrapper страницы.
+- Корневой wrapper страницы не должен дублировать padding подложки; внешнюю рамку страницы задаёт CRM host layout.
 - Между смысловыми блоками оставляйте заметную дистанцию, а не склеивайте их.
 
 ### Заголовок страницы
@@ -47,10 +49,14 @@
 
 ### Кнопки
 
-- На странице допускается одна основная `Default Primary` кнопка.
-- Отдельно может быть одна `Success Primary`, если сценарий этого требует.
-- Остальные действия рекомендуется оформлять через `Default Secondary`, `Default Tertiary`, `Success Secondary` и похожие менее доминирующие варианты.
-- Если действий много, одно оставляют главным, а остальные уводят во вторичный слой или dropdown.
+- В рамках всей страницы допускается максимум по одной page-level `primary`-кнопке каждого варианта: `Success Primary`, `Default Primary` и `Danger Primary`.
+- `Success Primary` — главное call-to-action страницы: действие, которое создаёт или фиксирует результат, например `Сохранить`, `Применить`, `Создать`. Обычно оно находится в `UiPageFooter`.
+- Если важное действие не является главным commit-действием, используйте `Default Primary`.
+- `Danger Primary` допустим только для одного критичного деструктивного действия.
+- Если важных действий несколько, выберите главное и оформите его как `Success Primary`; остальные переводите в `Default Primary`, `Default Secondary`, `Default Tertiary`, `Success Secondary` или другой менее доминирующий вариант по смыслу.
+- `UiPageHeader` и `UiPageFooter` относятся к одному page-level scope: `UiPageFooter` не сбрасывает лимит сам по себе.
+- Только `UiCollapseBox` с собственным footer создаёт локальный scope: внутри каждого блока может быть одна `Default Primary` для главного действия этой секции.
+- Если действий много, оставьте видимыми только действительно важные, а остальные уводите во вторичный слой или dropdown.
 
 Типичная компонентная основа:
 
@@ -61,6 +67,7 @@
 
 - Основной контент страницы обычно расположен на белых подложках.
 - Подложка должна собирать один смысловой блок, а не случайный набор элементов.
+- Padding `24px 32px 32px` ставится на саму подложку с контентом, а не на общий wrapper страницы.
 - Если на экране есть несколько независимых смысловых секций, предпочтительнее использовать несколько подложек, чем одну перегруженную.
 
 ## 1. Страница со списком сущностей
@@ -99,6 +106,8 @@
 
 - Таблица является главным содержимым списка.
 - Она может листаться, пагинироваться и поддерживать выгрузку.
+- `UiTable` не нужно заворачивать в дополнительную белую подложку: таблица сама задаёт табличную поверхность, границы и внутренние отступы.
+- Wrapper вокруг таблицы допустим только как layout/scroll/width container без собственной белой карточки и без padding подложки.
 - Не следует смешивать в одном списочном экране слишком много “карточной” логики; список должен оставаться в первую очередь инструментом поиска и просмотра.
 
 Типичная компонентная основа:
@@ -207,6 +216,7 @@
 - Если на странице используются `Collapse`-блоки, дополнительная общая белая подложка вокруг них обычно не нужна.
 - Если подложка видна только ради пары collapse-блоков, от неё следует отказаться.
 - Обычно и общая нижняя панель сохранения не нужна, потому что каждый блок сохраняется отдельно.
+- Каждый `UiCollapseBox` с footer работает как локальная “мини-страница”: в его footer можно использовать одну `Default Primary` кнопку для главного действия секции, а остальные действия оформлять менее доминирующе.
 
 ### Типичный состав
 
@@ -247,6 +257,7 @@
 - `UiModalSidebar` как контейнер `modal sidebar`.
 - Внутри: обычные form/content primitives из `v1-components`.
 - В `footer`: `UiButton` для сохранения, закрытия и удаления.
+- Главное действие сохранения или применения в `footer` обычно оформляется как `Success Primary`; соседние действия должны быть менее доминирующими, если они не являются самостоятельным `Default Primary` или `Danger Primary` по смыслу.
 
 ### Типичный состав
 
@@ -329,8 +340,9 @@
 2. Это список, карточка, карточка с колонками или collapse-настройки?
 3. Нужны ли tabs, или блоки следует оставить на одном полотне?
 4. Нужна ли общая панель сохранения, или каждый блок должен сохраняться отдельно?
-5. Не перегружен ли экран количеством primary-действий?
+5. Есть ли на странице не больше одного page-level `primary`-действия каждого варианта, а дополнительные `Default Primary` находятся только внутри отдельных `UiCollapseBox`?
 6. Держатся ли отступы и расстояния сетки `4px`?
+7. Не продублирован ли padding контентной подложки на корневом wrapper страницы?
 
 ---
 

package/docs/menu-placements.md

@@ -29,6 +29,76 @@
 | `route` | Имя или путь CRM-маршрута, если пункт открывается через маршрутизацию host-части. |
 | `visibility` | Условия показа: права, настройки, тариф, доступность фичи. |
 
+## Manifest `pages`
+
+В `extensionrc.json` и payload для RetailCRM API страницы нужно описывать объектами `ConfigurationPage`,
+а не строками. Строковый список page codes достаточен только для runtime runner map на фронтенде; backend API
+и меню страницы ожидают метаданные пункта меню.
+
+Минимальная рабочая форма:
+
+```json
+{
+  "pages": [
+    {
+      "code": "orders-dashboard",
+      "menu": "activity_main_menu",
+      "parentMenuItemCode": "orders",
+      "menuItemOrdering": 100,
+      "menuItemTitle": {
+        "ru": "Заказы",
+        "en": "Orders",
+        "es": "Pedidos"
+      },
+      "pageHelpLink": null
+    }
+  ]
+}
+```
+
+`menu` обязателен для опубликованной страницы: без него backend не сможет открыть route вида
+`/modules/<module-code>/<page-code>`. Для страниц в разделе настроек обычно используется
+`menu: "private_main_menu"` и `parentMenuItemCode: "settings"`. Для страниц в разделе продаж используйте
+`menu: "activity_main_menu"` и соответствующий parent menu item, например `orders`.
+
+## Payload публикации
+
+При обновлении уже установленного расширения синхронизируйте существующий integration module через
+`/api/v5/integration-modules/{code}/edit`, а не создавайте новый инстанс регистрации. В payload страницы
+должны находиться внутри `integrationModule.integrations.embedJs.pages`:
+
+```json
+{
+  "integrationModule": {
+    "clientId": "client-id-xxx",
+    "integrations": {
+      "embedJs": {
+        "entrypoint": "https://example.test/extension/demo/script",
+        "stylesheet": "https://example.test/extension/demo/stylesheet",
+        "runner": "demo",
+        "pages": [
+          {
+            "code": "orders-dashboard",
+            "menu": "activity_main_menu",
+            "parentMenuItemCode": "orders",
+            "menuItemOrdering": 100,
+            "menuItemTitle": {
+              "ru": "Заказы",
+              "en": "Orders",
+              "es": "Pedidos"
+            },
+            "pageHelpLink": null
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Если локальный API client не знает DTO для расширенного payload, используйте поддержанный custom/request
+method с обычным JSON-объектом вместо добавления локального DTO, который serializer не умеет обрабатывать.
+
 ## Пример справочника меню
 
 Конкретные `placement`, `item code` и `route` нужно брать из host/manifest расширения.
@@ -66,4 +136,4 @@ const pageRunner = definePageRunner({
 - [`definePageRunner`](./define-page-runner.md) — как встраиваемая страница получает `code`.
 - [`targets`](./targets.md) — точки встраивания виджетов, не пунктов меню.
 - [`layout`](./layout.md) — когда делать полноценную страницу, а когда `modal sidebar` или `modal window`.
-- [`UiMenuItem`](../../v1-components/docs/profiles/UiMenuItem.yml) — компонент строки меню внутри UI расширения.
+- `@retailcrm/embed-ui-v1-components` `docs/profiles/components/UiMenuItem.yml` — компонент строки меню внутри UI расширения.

package/docs/page-routes.md

@@ -7,6 +7,11 @@
 host/manifest конкретного расширения, поэтому его нужно хранить в справочнике проекта рядом с кодом
 расширения.
 
+В runtime-коде `definePageRunner` сопоставляет page `code` с Vue-компонентом. В `extensionrc.json` этот же
+page `code` нужно описывать объектом manifest `pages[]` с `menu` и, обычно, `menuItemTitle`. Не используйте
+строковую форму `pages: ["orders-dashboard"]` для публикации через RetailCRM API: backend ожидает
+`ConfigurationPage` object, а страница без `menu` не откроется по route `/modules/<module-code>/<page-code>`.
+
 ## Что такое `page code`
 
 `page code` — стабильный идентификатор встраиваемой страницы внутри расширения.
@@ -59,6 +64,23 @@ console.log(settings['system.routing'].routes)
 | `integration-settings` | `embed.page.integration_settings` | `{}` | `settings / integration-settings` | `IntegrationSettingsPage.vue` |
 | `customer-tools` | `embed.page.customer_tools` | `{ customerId }` | `customer/card:actions / customer-tools` | `CustomerToolsPage.vue` |
 
+Пример manifest-записи для страницы:
+
+```json
+{
+  "code": "orders-dashboard",
+  "menu": "activity_main_menu",
+  "parentMenuItemCode": "orders",
+  "menuItemOrdering": 100,
+  "menuItemTitle": {
+    "ru": "Заказы",
+    "en": "Orders",
+    "es": "Pedidos"
+  },
+  "pageHelpLink": null
+}
+```
+
 ## Переход на CRM-маршрут
 
 Если странице нужен переход на другой CRM-маршрут, используйте host API, а не прямую сборку URL.
@@ -76,5 +98,5 @@ const openSettings = (host: HostApi) => {
 
 - [`menu-placements`](./menu-placements.md) — как связать пункт меню, page `code` и маршрут.
 - [`definePageRunner`](./define-page-runner.md) — как page `code` попадает в компонент.
-- [`settings context`](../../v1-contexts/docs/ru/CONCEPT.md) — общий принцип работы контекстов.
-- [`HostApi`](../../v1-types/host.d.ts) — публичный тип host API с `goTo`.
+- `@retailcrm/embed-ui-v1-contexts` `docs/ru/CONCEPT.md` — общий принцип работы контекстов.
+- `@retailcrm/embed-ui-v1-types` `host.d.ts` — публичный тип host API с `goTo`.

package/docs/targets/customer-card-communications-after.yml

@@ -56,6 +56,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/customer-card-inwork-after.yml

@@ -56,6 +56,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/customer-card-inwork-before.yml

@@ -56,6 +56,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/customer-card-phone.yml

@@ -59,6 +59,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-comment-manager-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-common-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-common-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-customer-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-customer-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-customer-email.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-customer-phone.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-delivery-address.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-delivery-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-delivery-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-dimensions-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-list-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-list-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-payment-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-store-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-delivery-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-delivery-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-list-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-list-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-payment-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-payment-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets.md

@@ -24,6 +24,19 @@
 `target` не является данными заказа, клиента или пользователя. Это только место встраивания.
 Данные нужно брать из контекстов, которые привязаны к этому `target`.
 
+## Оформление виджета в target
+
+Виджет должен добавлять в target простой и предсказуемый inline UI: обычно `UiToolbarButton`,
+`UiToolbarLink`, короткий текст или компактное действие с иконкой. Это сохраняет страницу CRM
+стабильной и не раздувает место встраивания.
+
+Если сценарий требует сложной формы, таблицы, карты, фильтров, summary-блоков или многошагового UI,
+оставьте в target только компактный вход в сценарий, а основную логику перенесите в `UiModalSidebar`
+или `UiModalWindow`.
+
+Подробные правила композиции описаны в `@retailcrm/embed-ui-v1-components`
+`docs/profiles/widgets/WidgetComposition.yml`.
+
 ## Проверка контекстов для `target`
 
 ```ts
@@ -132,5 +145,5 @@ const testTarget = defineTarget('customer/card:test.after', [
 - [`defineWidgetRunner`](./define-widget-runner.md) — как `target` попадает в компонент встраиваемого виджета.
 - [`menu-placements`](./menu-placements.md) — чем пункты меню для страниц отличаются от widget `target`.
 - [`page-routes`](./page-routes.md) — как описывать page `code` и CRM-маршрут.
-- [`CONCEPT`](../../v1-contexts/docs/ru/CONCEPT.md) — общий принцип работы контекстов.
-- [`CUSTOM`](../../v1-contexts/docs/ru/CUSTOM.md) — пользовательский контекст для custom fields.
+- `@retailcrm/embed-ui-v1-contexts` `docs/ru/CONCEPT.md` — общий принцип работы контекстов.
+- `@retailcrm/embed-ui-v1-contexts` `docs/ru/CUSTOM.md` — пользовательский контекст для custom fields.

package/package.json

@@ -5,7 +5,7 @@
     "embed-ui-v1-endpoint-mcp": "bin/embed-ui-v1-endpoint-mcp.mjs"
   },
   "type": "module",
-  "version": "0.9.23",
+  "version": "0.9.25",
   "description": "Endpoint API for integrations in RetailCRM",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
@@ -85,7 +85,8 @@
     "bin",
     "dist",
     "docs",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "scripts": {
     "build": "yarn build:docs && yarn build:code && yarn build:mcp && yarn build:meta",
@@ -100,17 +101,17 @@
   "peerDependencies": {
     "@omnicajs/vue-remote": "^0.2.24",
     "@remote-ui/rpc": "^1.4",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.23",
-    "@retailcrm/embed-ui-v1-types": "^0.9.23",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.25",
+    "@retailcrm/embed-ui-v1-types": "^0.9.25",
     "pinia": "^2.2",
     "vue": "^3.5"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@remote-ui/rpc": "^1.4.7",
-    "@retailcrm/embed-ui-v1-components": "^0.9.23",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.23",
-    "@retailcrm/embed-ui-v1-types": "^0.9.23"
+    "@retailcrm/embed-ui-v1-components": "^0.9.25",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.25",
+    "@retailcrm/embed-ui-v1-types": "^0.9.25"
   },
   "devDependencies": {
     "@retailcrm/image-preview": "^1.0.2",

package/templates/skills/embed-ui-v1-endpoint-runtime/SKILL.md.txt

@@ -0,0 +1,45 @@
+---
+name: embed-ui-v1-endpoint-runtime
+description: Use when building, editing, or reviewing RetailCRM JS module endpoint wiring with @retailcrm/embed-ui-v1-endpoint. Covers pages, widgets, runners, targets, menu hierarchy, page publishing payloads, and public Host API boundaries.
+---
+
+# Embed UI v1 Endpoint Runtime
+
+Use this skill before changing JS module endpoint wiring, page registration, widget targets, or Host API navigation.
+
+## Reading order
+
+1. Read project `AGENTS.md` if it exists.
+2. Read `./node_modules/@retailcrm/embed-ui-v1-endpoint/README.md`.
+3. Read `./node_modules/@retailcrm/embed-ui-v1-endpoint/docs/README.md`.
+4. Read the relevant endpoint docs:
+   - `docs/define-runner.md`
+   - `docs/define-page-runner.md`
+   - `docs/define-widget-runner.md`
+   - `docs/page-routes.md`
+   - `docs/menu-placements.md`
+   - `docs/targets.md`
+5. If MCP resources are available, read `embed-ui-v1-endpoint://targets` and then the target profile for the target being changed.
+6. If MCP is not available, use `./node_modules/@retailcrm/embed-ui-v1-endpoint/docs/targets/*.yml` as fallback.
+
+## Workflow
+
+1. Identify whether the task is a page, widget, or shared endpoint runner change.
+2. For pages, keep the runtime runner map and extension config page descriptors aligned by page `code`.
+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.
+
+## Page and menu checks
+
+- Published page descriptors must be objects, not string page codes.
+- Page descriptors need `code`, `menu`, and usually `menuItemTitle`.
+- 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`.
+
+## Host API checks
+
+- Use public Host API for location, query state, and navigation.
+- Do not depend on internal endpoint runtime stores or private channel state.
+- Keep route names, page codes, and extension descriptor values documented in the project.