snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ru/developers/extend/apps/config/application.mdx

@@ -0,0 +1,124 @@
+---
+title: Конфигурация приложения
+description: Определите идентификацию вашего приложения, роль по умолчанию, переменные и метаданные маркетплейса с помощью defineApplication.
+icon: rocket
+---
+
+В каждом приложении должен быть ровно один вызов `defineApplication`. Он объявляет:
+
+* **Идентификация** — универсальный идентификатор, отображаемое имя, описание.
+* **Разрешения** — от имени какой роли выполняются его логические функции и фронтенд-компоненты.
+* **Переменные** *(необязательно)* — пары ключ–значение, доступные вашему коду как переменные окружения.
+* **Хуки предустановки / постустановки / удаления** *(необязательно)* — см. [Логические функции](/l/ru/developers/extend/apps/logic/logic-functions).
+
+```ts src/application-config.ts
+import { defineApplication } from 'twenty-sdk/define';
+
+export default defineApplication({
+  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
+  displayName: 'My Twenty App',
+  description: 'My first Twenty app',
+  applicationVariables: {
+    DEFAULT_RECIPIENT_NAME: {
+      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
+      description: 'Default recipient name for postcards',
+      value: 'Jane Doe',
+      isSecret: false,
+    },
+  },
+});
+```
+
+Заметки:
+
+* Поля `universalIdentifier` — это детерминированные идентификаторы, которые принадлежат вам. Сгенерируйте их один раз и сохраняйте неизменными между синхронизациями.
+* `applicationVariables` становятся переменными окружения для ваших функций и фронтенд-компонентов. В логических функциях (на стороне сервера) они доступны как `process.env.VARIABLE_NAME`. Во фронтенд-компонентах используйте `getApplicationVariable('VARIABLE_NAME')` из `twenty-sdk/front-component`. Переменные, помеченные как `isSecret: true`, внедряются только в логические функции. Фронтенд-компоненты получают только несекретные переменные.
+* Роль по умолчанию автоматически определяется из файла роли, помеченного с помощью [`defineApplicationRole()`](/l/ru/developers/extend/apps/config/roles) — вам не нужно ссылаться на неё из `defineApplication()`.
+* Функции предустановки, постустановки и удаления обнаруживаются автоматически во время сборки манифеста — вам не нужно указывать их в `defineApplication()`.
+* Явная передача `defaultRoleUniversalIdentifier` по-прежнему поддерживается для обратной совместимости, но считается устаревшей и вместо неё рекомендуется использовать `defineApplicationRole()`.
+* `serverVariables` — это параметры конфигурации и секреты в области экземпляра (например, ключи API). В отличие от `applicationVariables`, значения для них не указываются в манифесте — оператор рабочего пространства заполняет их в настройках приложения, и они внедряются в логические функции только после того, как будут заданы.
+* Оба типа переменных принимают `isDeprecated: true`. Используйте это, чтобы вывести переменную из обращения вместо её удаления: сохранение объявленного ключа сохраняет хранимое значение (удаление уничтожает значение, введённое пользователем), а переменная по-прежнему внедряется, поэтому код сможет обратиться к ней — `process.env.NEW_API_KEY ?? process.env.API_KEY`. Устаревшая переменная исчезает из настроек приложения, как только у неё больше нет значения, и никогда не учитывается при проверке конфигурации приложения, поэтому `isDeprecated` имеет приоритет над `isRequired`.
+* Чтобы отобразить на вкладке **Settings** приложения пользовательский интерфейс настройки (вместо стандартного раздела настройки переменных), объявите фронтенд‑компонент с помощью [`defineSettingsFrontComponent()`](/l/ru/developers/extend/apps/layout/front-components#custom-settings-component) в отдельном файле. Для каждого приложения допускается только один такой компонент. Разделы, управляемые системой (автообновление, App URL, соединения), всегда остаются видимыми.
+
+## Типы переменных
+
+И `applicationVariables`, и `serverVariables` принимают необязательный `type` (а для `SELECT` / `MULTI_SELECT` — список `options`). Поддерживаемые типы: `TEXT` (по умолчанию), `BOOLEAN`, `NUMBER`, `NUMERIC`, `DATE`, `DATE_TIME`, `SELECT`, `MULTI_SELECT`, `ARRAY`, `RAW_JSON`, `RICH_TEXT`.
+
+```ts src/application-config.ts
+import { defineApplication, FieldType } from 'twenty-sdk/define';
+
+export default defineApplication({
+  // ...identity, role...
+  applicationVariables: {
+    MAX_POSTCARDS: {
+      universalIdentifier: '5f4497e4-9030-4085-85eb-2c48b8d53713',
+      description: 'Maximum postcards per batch',
+      type: FieldType.NUMBER,
+      value: 10,
+    },
+    DEFAULT_REGION: {
+      universalIdentifier: '76c5c321-b6b6-46eb-b4fc-f9f04bb04227',
+      description: 'Default shipping region',
+      type: FieldType.SELECT,
+      options: [
+        { label: 'Europe', value: 'eu' },
+        { label: 'United States', value: 'us' },
+      ],
+      value: 'eu',
+    },
+  },
+});
+```
+
+Свойство `type` влияет только на **отображение и валидацию** — оно выбирает соответствующий ввод в UI настроек рабочего пространства (переключатель, числовое поле, раскрывающийся список, выбор даты, JSON‑редактор, …) и позволяет сборке проверить вашу конфигурацию (например, `SELECT` / `MULTI_SELECT` должны объявить непустой список `options`). Оно **не** меняет то, как значение попадает в ваш код.
+
+Значения **всегда внедряются как строки** — это заложено в природу переменных окружения (`process.env.*` содержит только строки). Когда выполняется ваша логическая функция, исполнитель сериализует каждое значение в соответствии с объявленным `type` при построении `process.env`, так что строковый формат остается единым, независимо от того, как было задано значение (значение по умолчанию в манифесте, UI настроек или предыдущая версия):
+
+| Тип                                   | строка в `process.env`                              |
+| ------------------------------------- | --------------------------------------------------- |
+| `TEXT`, `SELECT`, `DATE`, `DATE_TIME` | непреобразованное значение (`"eu"`, `"2026-01-01"`) |
+| `BOOLEAN`                             | `"true"` / `"false"`                                |
+| `NUMBER`, `NUMERIC`                   | десятичная строка (`"10"`, `"2.5"`)                 |
+| `MULTI_SELECT`, `ARRAY`               | JSON‑массив (`'["email","postcard"]'`)              |
+| `RAW_JSON`, `RICH_TEXT`               | JSON‑объект (`'{"retries":3}'`)                     |
+
+Преобразуйте строку обратно в ожидаемый вами тип:
+
+```ts
+const maxCards = Number(process.env.MAX_POSTCARDS); // "10" -> 10
+const enabled = process.env.ENABLE_TRACKING === 'true'; // "true" -> true
+const channels = JSON.parse(process.env.ENABLED_CHANNELS ?? '[]'); // '["email"]' -> ["email"]
+const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3}' -> { retries: 3 }
+```
+
+Это же относится к фронтенд‑компонентам, читающим значения через `getApplicationVariable('VARIABLE_NAME')` — возвращаемое значение является строкой; при необходимости преобразуйте его.
+
+## Роль функции по умолчанию
+
+Роль, объявленная с помощью [`defineApplicationRole()`](/l/ru/developers/extend/apps/config/roles), определяет, к чему могут получать доступ логические функции и фронтенд‑компоненты приложения:
+
+* Токены времени выполнения, подставляемые в ваши функции логики, формируются из этой роли. Вызов, выполняемый от имени пользователя, дополнительно ограничен тем, что может делать этот пользователь, поэтому он никогда не может превышать ни один из них. См. [Чей доступ использует вызов](/l/ru/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
+* Типизированный клиент API ограничен правами, предоставленными этой роли.
+* Следуйте принципу наименьших привилегий: объявляйте только те разрешения, которые действительно нужны вашим функциям.
+
+Когда вы создаёте новое приложение с помощью шаблона, CLI создаёт стартовый файл роли по адресу `src/roles/default-role.ts`. Полную справочную информацию см. в разделе [Роли и разрешения](/l/ru/developers/extend/apps/config/roles).
+
+## Метаданные маркетплейса
+
+Если вы планируете [опубликовать приложение](/l/ru/developers/extend/apps/operations/publishing), эти необязательные поля определяют, как оно отображается в маркетплейсе:
+
+| Поле               | Описание                                                                                                            |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `author`           | Имя автора или название компании                                                                                    |
+| `category`         | Категория приложения для фильтрации в маркетплейсе                                                                  |
+| `logo`             | Путь к вашему логотипу приложения в `public/` (например, `public/logo.png`)                                         |
+| `galleryImages`    | Массив путей галереи изображений в комплекте `public/` (например, `public/screenshot-1.png`)                        |
+| `aboutDescription` | Расширенное описание в Markdown для вкладки "About". Если опущено, маркетплейс использует `README.md` пакета из npm |
+| `websiteUrl`       | Ссылка на ваш сайт                                                                                                  |
+| `termsUrl`         | Ссылка на условия предоставления услуг                                                                              |
+| `emailSupport`     | Адрес электронной почты поддержки                                                                                   |
+| `issueReportUrl`   | Ссылка на систему отслеживания проблем                                                                              |
+
+<Note>
+«logoUrl» и «screenshots» являются устаревшими псевдонимами «logo» и «galleryImages». Внешние абсолютные URL-адреса (`http://` или `https://`) не поддерживаются для этих полей: они удаляются с предупреждением на время сборки. Вместо этого объедините изображения в папку `public/` вашего приложения.
+</Note>

packages/twenty-docs/l/ru/developers/extend/apps/config/install-hooks.mdx

@@ -0,0 +1,188 @@
+---
+title: Установочные хуки
+description: Выполняйте логику во время жизненного цикла установки, обновления или удаления — выполняйте начальное заполнение данными, создавайте резервные копии записей, проверяйте корректность обновления, очищайте внешние ресурсы.
+icon: wrench
+---
+
+Установочные хуки — это специальные логические функции, которые выполняются во время жизненного цикла установки, обновления или удаления. Они используют то же окружение выполнения обработчика, что и обычные [logic functions](/l/ru/developers/extend/apps/logic/logic-functions), но объявляются с помощью собственных функций определения и существуют вне обычной модели триггеров (HTTP, cron, события базы данных). Установочные хуки получают `InstallPayload` (`{ previousVersion?: string; newVersion: string }` — `previousVersion` имеет значение `undefined` при новой установке); хук удаления получает `UninstallPayload` (`{ version?: string }` — версия, которая удаляется).
+
+Каждое приложение может определить **не более одного** хука каждого типа (предустановочный, постустановочный, хук удаления). Сборка манифеста завершится ошибкой, если будет обнаружено более одного хука любого типа.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ install flow                                                │
+│                                                             │
+│   upload package → [pre-install] → metadata migration →     │
+│   generate SDK → [post-install]                             │
+│                                                             │
+│                  old schema visible    new schema visible   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Краткий обзор
+
+|                        | `definePreInstallLogicFunction`                                                                                                            | `definePostInstallLogicFunction`                                                                                                                    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Запуски                | До миграции метаданных — **предыдущая** схема и данные остаются нетронутыми                                                                | После миграции и генерации SDK — **новая** схема уже применяется                                                                                    |
+| Выполнение             | Всегда синхронное; блокирует установку                                                                                                     | Асинхронно по умолчанию (постановка в очередь, 3 повторные попытки); синхронный режим по желанию через `shouldRunSynchronously: true`               |
+| При ошибке             | Установка **прерывается** до любых изменений схемы                                                                                         | Асинхронный режим: до 3 повторных попыток. Синхронный режим: вызывающая сторона получает `POST_INSTALL_ERROR` (изменения схемы **не** откатываются) |
+| Типичное использование | Создать резервную копию или исправить данные, которые были бы потеряны при миграции; отклонить рискованное обновление, выбросив исключение | Наполнить данными по умолчанию, настроить рабочее пространство, зарегистрировать внешние ресурсы                                                    |
+
+**Общее практическое правило:** по умолчанию используйте post-install. Обращайтесь к pre-install только тогда, когда сама миграция разрушительна и вам нужно перехватить предыдущее состояние, прежде чем оно исчезнет.
+
+| Вы хотите...                                                                                 | Использовать                                                                    |
+| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Инициализировать данные, настроить рабочее пространство, зарегистрировать внешние ресурсы    | `post-install`                                                                  |
+| Длительные операции, которые не должны блокировать ответ установки                           | `post-install` (асинхронный режим по умолчанию, с повторными попытками воркера) |
+| Быстрая настройка, на которую вызывающая сторона полагается сразу после завершения установки | `post-install` с `shouldRunSynchronously: true`                                 |
+| Прочитать или сохранить данные, которые предстоящая миграция может потерять                  | `pre-install`                                                                   |
+| Отклонить обновление, которое повредит существующие данные                                   | `pre-install` (бросьте исключение из обработчика)                               |
+| Согласование при каждом обновлении                                                           | Любой хук с `shouldRunOnVersionUpgrade: true`                                   |
+
+## Общее поведение для обоих хуков
+
+* Конфиг — это конфиг `defineLogicFunction` без настроек триггера, но с `shouldRunOnVersionUpgrade`.
+* **Когда запускается**: по умолчанию только при чистой установке. Установите `shouldRunOnVersionUpgrade: true`, чтобы также запускать его при обновлениях. Используйте `previousVersion` / `newVersion`, чтобы разветвлять логику в зависимости от пути обновления.
+* **Идемпотентность имеет значение**: асинхронный post-install может быть повторно выполнен, и любой хук будет запускаться повторно при обновлениях, если включён `shouldRunOnVersionUpgrade`.
+* Обычное окружение logic-функций (`APPLICATION_ID`, `APP_ACCESS_TOKEN`, `API_URL`) инъецируется, поэтому вы можете вызывать Twenty API с токеном своего приложения.
+* Хук автоматически прикрепляется к манифесту приложения на этапе сборки (`preInstallLogicFunction` / `postInstallLogicFunction`) — ничего не нужно указывать в [`defineApplication()`](/l/ru/developers/extend/apps/config/application).
+* Значение `timeoutSeconds` по умолчанию — 300, чтобы позволить выполнять более длительные задачи настройки, такие как инициализация данных.
+* **Не выполняется в dev-режиме**: `yarn twenty dev` пропускает процесс установки и синхронизирует файлы напрямую, поэтому хуки там никогда не запускаются. Вместо этого запускайте их вручную:
+
+```bash filename="Terminal"
+yarn twenty dev:function:exec --postInstall
+yarn twenty dev:function:exec --preInstall
+```
+
+<AccordionGroup>
+<Accordion title="definePostInstallLogicFunction" description="Выполняется после применения миграции метаданных рабочего пространства">
+
+Запускается после завершения установки приложения: метаданные синхронизированы, SDK-клиент сгенерирован, новая схема доступна для запросов. Пример — инициализировать запись по умолчанию при новой установке:
+
+```ts src/logic-functions/post-install.ts
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
+  if (previousVersion) return; // fresh installs only
+
+  const client = new CoreApiClient();
+  await client.mutation({
+    createPostCard: {
+      __args: { data: { name: 'Welcome to Postcard', content: 'Your first card!' } },
+      id: true,
+    },
+  });
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
+  name: 'post-install',
+  description: 'Seeds a welcome post card after install.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  shouldRunSynchronously: false,
+  handler,
+});
+```
+
+Флаг `shouldRunSynchronously` управляет моделью выполнения:
+
+* `false` *(по умолчанию)* — ставится в очередь сообщений (`retryLimit: 3`) и выполняется воркером. Ответ установки возвращается, как только задача поставлена в очередь. **Используйте для длительных операций** — инициализация больших наборов данных, медленные сторонние API.
+* `true` — выполняется непосредственно в процессе установки. Запрос на установку блокируется до завершения обработчика; выброшенная ошибка возвращается вызывающей стороне как `POST_INSTALL_ERROR` (без повторных попыток). **Используйте для быстрых операций, которые обязательно должны завершиться до ответа.** На этом этапе миграция уже применена, поэтому сбой не откатывает изменения схемы — он только сообщает об ошибке.
+
+</Accordion>
+<Accordion title="definePreInstallLogicFunction" description="Выполняется до применения миграции метаданных рабочего пространства">
+
+Запускается до миграции метаданных, в контексте **предыдущей** схемы — подходящее место, чтобы создать резервную копию данных, которые были бы потеряны при миграции, или отклонить рискованное обновление. Перед выполнением сервер запускает чисто добавочную «урезанную синхронизацию», которая регистрирует только pre-install функцию новой версии; всё остальное — объекты, поля и данные предыдущей версии — остаётся нетронутым во время выполнения вашего обработчика.
+
+Pre-install всегда **синхронный** и блокирует установку. Если обработчик генерирует исключение, установка прерывается до применения каких-либо изменений схемы — рабочее пространство остаётся на предыдущей версии в согласованном состоянии. Это сделано намеренно: pre-install — ваш последний шанс отказать в рискованном обновлении.
+
+Пример — скопировать значения устаревшего поля перед тем, как миграция его удалит:
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
+  // Only the 1.x → 2.x upgrade drops the legacy `notes` field.
+  if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
+    return;
+  }
+
+  const client = new CoreApiClient();
+  const { postCards } = await client.query({
+    postCards: {
+      __args: { filter: { notes: { isNot: null } } },
+      edges: { node: { id: true, notes: true } },
+    },
+  });
+
+  // Copy legacy `notes` into `description` before the migration drops the
+  // column. If this fails, the upgrade aborts and the workspace stays on v1.
+  for (const { node } of postCards.edges) {
+    await client.mutation({
+      updatePostCard: {
+        __args: { id: node.id, data: { description: node.notes } },
+        id: true,
+      },
+    });
+  }
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
+  name: 'pre-install',
+  description: 'Backs up legacy notes into description before the v2 migration.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: true,
+  handler,
+});
+```
+
+</Accordion>
+</AccordionGroup>
+
+## Хук удаления
+
+`defineUninstallLogicFunction` объявляет хук, который выполняется, когда пользователь удаляет ваше приложение. Он выполняется **до того**, как метаданные, данные и код приложения будут удалены — после запуска миграции удаления уже нечему будет выполняться — поэтому ваш обработчик все еще может запрашивать объекты и записи приложения. Используйте его для очистки внешних ресурсов: отмены выделения ресурсов API, удаления оставшихся ботов, отзыва вебхуков.
+
+Заметки:
+
+* Хук работает по принципу «по возможности»: он выполняется синхронно, но сбой только логируется и **никогда не блокирует удаление** — очистка не должна делать удаление приложения невозможным.
+* Он получает `UninstallPayload` (`{ version?: string }` — версия, которая удаляется).
+* Он **не** выполняется при откате неуспешной новой установки — приложение так и не было полностью установлено.
+* Хук не может выполниться после того, как приложение удалено, поэтому внешняя очистка, которая зависит от данных приложения (например, ID ботов, сохраненные в записях), должна выполняться здесь, а не во внешнем запланированном задании.
+* Как и установочные хуки, он **не выполняется в режиме разработки** — вместо этого запустите его вручную:
+
+```bash filename="Terminal"
+yarn twenty dev:function:exec --uninstall
+```
+
+```ts src/logic-functions/uninstall.ts
+import { defineUninstallLogicFunction, type UninstallPayload } from 'twenty-sdk/define';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const handler = async (_payload: UninstallPayload): Promise<void> => {
+  const client = new CoreApiClient();
+  const { meetingBots } = await client.query({
+    meetingBots: { edges: { node: { id: true, externalBotId: true } } },
+  });
+
+  // Delete the provider-side bots so nothing keeps recording after uninstall.
+  for (const { node } of meetingBots.edges) {
+    await fetch(`https://api.recorder.example/bots/${node.externalBotId}`, {
+      method: 'DELETE',
+      headers: { Authorization: `Bearer ${process.env.RECORDER_API_KEY}` },
+    });
+  }
+};
+
+export default defineUninstallLogicFunction({
+  universalIdentifier: 'b2c3d4e5-6789-01bc-def0-234567890abc',
+  name: 'uninstall',
+  description: 'Deletes remaining recorder bots when the app is uninstalled.',
+  timeoutSeconds: 300,
+  handler,
+});
+```

packages/twenty-docs/l/ru/developers/extend/apps/config/overview.mdx

@@ -0,0 +1,56 @@
+---
+title: Обзор
+description: Настройте само приложение — его идентичность, разрешения по умолчанию и то, что выполняется во время установки.
+icon: screwdriver-wrench
+---
+
+**Конфигурационный слой** приложения Twenty описывает приложение *для платформы* — его идентичность, разрешения, которыми оно обладает, и код, который выполняется при установке или обновлении. Эти декларации не добавляют новых структур данных или поведения во время выполнения; они сообщают Twenty, *что это за приложение* и *как его настроить*.
+
+```text
+┌────────────────────────────────────────────────────────┐
+│ Application — identity, default role, variables,       │
+│               marketplace metadata                     │
+│                                                        │
+│   ┌──────────────────────────────────────────────────┐ │
+│   │ Role — what the app's logic functions can read   │ │
+│   │ and write (referenced by Application)            │ │
+│   └──────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────┘
+                          │
+                          ▼  (at install / upgrade time)
+       ┌──────────────────────────────────┐
+       │ Pre-install hook                 │  before metadata migration
+       └──────────────────────────────────┘
+       ┌──────────────────────────────────┐
+       │ Post-install hook                │  after metadata migration
+       └──────────────────────────────────┘
+                          │
+                          ▼  (at uninstall time)
+       ┌──────────────────────────────────┐
+       │ Uninstall hook                   │  before app removal
+       └──────────────────────────────────┘
+```
+
+## В этом разделе
+
+<CardGroup cols={2}>
+  <Card title="Конфигурация приложения" icon="rocket" href="/l/ru/developers/extend/apps/config/application">
+    `defineApplication` — идентичность, роль по умолчанию, переменные, метаданные маркетплейса.
+  </Card>
+  <Card title="Роли и разрешения" icon="shield-halved" href="/l/ru/developers/extend/apps/config/roles">
+    `defineRole` — определите, что логические функции вашего приложения могут читать и записывать.
+  </Card>
+  <Card title="Установочные хуки" icon="wrench" href="/l/ru/developers/extend/apps/config/install-hooks">
+    `definePreInstallLogicFunction`, `definePostInstallLogicFunction` и `defineUninstallLogicFunction` — создавайте резервные копии данных, заполняйте значения по умолчанию, проверяйте обновления, выполняйте очистку при удалении.
+  </Card>
+</CardGroup>
+
+## Связь между частями
+
+* **Приложение** — это точка входа. У каждого приложения есть ровно один вызов `defineApplication()`, и он указывает на одну **роль** по умолчанию.
+* **Роль** управляет тем, что логические функции и фронтенд‑компоненты приложения могут читать и записывать. Следуйте принципу наименьших привилегий: выдавайте только те разрешения, которые вашему коду действительно нужны.
+* **Установочные хуки** запускаются при установке или обновлении — предустановочный до миграции метаданных (чтобы можно было отклонить рискованное обновление), постустановочный после миграции (чтобы можно было заполнить данные по умолчанию в соответствии с новой схемой). Хук удаления запускается непосредственно перед тем, как приложение будет удалено, поэтому он может очистить внешние ресурсы, пока данные приложения ещё доступны для чтения.
+
+<Note>
+Установочные хуки используют то же окружение выполнения, что и [логическая функция](/l/ru/developers/extend/apps/logic/logic-functions) — тот же формат обработчика, те же переменные окружения, тот же типизированный клиент API, — но объявляются через собственные функции `define` и находятся вне обычной модели триггеров (HTTP, cron, события базы данных).
+</Note>

packages/twenty-docs/l/ru/developers/extend/apps/config/public-assets.mdx

@@ -0,0 +1,67 @@
+---
+title: Публичные ресурсы
+description: Поставляйте статические файлы — изображения, значки, шрифты — вместе с приложением через папку `public/`.
+icon: folder-open
+---
+
+Папка `public/` в корне вашего приложения содержит статические файлы — изображения, значки, шрифты и любые другие ресурсы, необходимые вашему приложению во время выполнения. Эти файлы автоматически включаются в сборки, синхронизируются в режиме разработки и загружаются на сервер.
+
+Файлы, размещённые в `public/`, являются:
+
+* **Публично доступными** — после синхронизации с сервером ресурсы доступны по публичному URL. Для доступа к ним аутентификация не требуется.
+* **Доступными в компонентах фронтенда** — используйте URL ресурсов для отображения изображений, значков или любого медиа внутри ваших компонентов React.
+* **Доступными в логических функциях** — используйте URL ресурсов в письмах, ответах API или любой серверной логике.
+* \*\*Используется для метаданных на marketplace — поля `logo` и `galleryImages` в файле `defineApplication()` из этой папки (например, `public/logo.png`). Они отображаются в маркетплейсе при публикации вашего приложения. Внешние абсолютные URL-адреса игнорируются для этих полей — вместо этого объединяйте изображения в `public/`. Каждое изображение не должно превышать 10 МБ.
+* **Автосинхронизация в режиме разработки** — когда вы добавляете, обновляете или удаляете файл в `public/`, он автоматически синхронизируется с сервером. Перезапуск не требуется.
+* **Включены в сборки** — `yarn twenty dev:build` упаковывает все публичные ресурсы в выходной дистрибутив.
+
+## Доступ к публичным ресурсам с помощью `getPublicAssetUrl`
+
+Используйте хелпер `getPublicAssetUrl` из `twenty-sdk`, чтобы получить полный URL файла в каталоге `public/` вашего приложения. Он работает как в **логических функциях**, так и в **компонентах фронтенда**.
+
+**В логической функции:**
+
+```ts src/logic-functions/send-invoice.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { getPublicAssetUrl } from 'twenty-sdk/utils';
+
+const handler = async (): Promise<any> => {
+  const logoUrl = getPublicAssetUrl('logo.png');
+  const invoiceUrl = getPublicAssetUrl('templates/invoice.png');
+
+  // Fetch the file content (no auth required — public endpoint)
+  const response = await fetch(invoiceUrl);
+  const buffer = await response.arrayBuffer();
+
+  return { logoUrl, size: buffer.byteLength };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'a1b2c3d4-...',
+  name: 'send-invoice',
+  description: 'Sends an invoice with the app logo',
+  timeoutSeconds: 10,
+  handler,
+});
+```
+
+**В компоненте фронтенда:**
+
+```tsx src/front-components/company-card.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { getPublicAssetUrl } from 'twenty-sdk/utils';
+
+const CompanyCard = () => {
+  const logoUrl = getPublicAssetUrl('logo.png');
+
+  return <img src={logoUrl} alt="App logo" />;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'company-card',
+  component: CompanyCard,
+});
+```
+
+Аргумент `path` задаётся относительно папки `public/` вашего приложения. И `getPublicAssetUrl('logo.png')`, и `getPublicAssetUrl('public/logo.png')` приводят к одному и тому же URL — префикс `public/`, если он есть, удаляется автоматически.

packages/twenty-docs/l/ru/developers/extend/apps/config/roles.mdx

@@ -0,0 +1,205 @@
+---
+title: Роли и разрешения
+description: Укажите, к каким объектам и полям функции логики и фронтенд‑компоненты вашего приложения имеют доступ на чтение и запись.
+icon: shield-halved
+---
+
+**Роль** — это набор разрешений: какие объекты приложение может читать или изменять, какие поля оно может видеть и какие возможности платформенного уровня оно может использовать. Функции логики и фронтенд‑компоненты каждого приложения наследуют разрешения роли, помеченной с помощью `defineApplicationRole()` (см. раздел [Роль функции по умолчанию](#the-default-function-role) ниже).
+
+```ts src/roles/restricted-company-role.ts
+import {
+  defineRole,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+  SystemPermissionFlag,
+} from 'twenty-sdk/define';
+
+export default defineRole({
+  universalIdentifier: '2c80f640-2083-4803-bb49-003e38279de6',
+  label: 'My new role',
+  description: 'A role that can be used in your workspace',
+  canReadAllObjectRecords: false,
+  canUpdateAllObjectRecords: false,
+  canSoftDeleteAllObjectRecords: false,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: false,
+  canBeAssignedToAgents: false,
+  canBeAssignedToUsers: false,
+  canBeAssignedToApiKeys: false,
+  objectPermissions: [
+    {
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      canReadObjectRecords: true,
+      canUpdateObjectRecords: true,
+      canSoftDeleteObjectRecords: false,
+      canDestroyObjectRecords: false,
+    },
+  ],
+  fieldPermissions: [
+    {
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      fieldUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name
+          .universalIdentifier,
+      canReadFieldValue: false,
+      canUpdateFieldValue: false,
+    },
+  ],
+  permissionFlagUniversalIdentifiers: [SystemPermissionFlag.APPLICATIONS],
+});
+```
+
+## Безопасность на уровне строк
+
+Разрешения на объекты и поля определяют, *к каким объектам и полям* у роли есть доступ. **Предикаты прав доступа на уровне строк** заходят дальше и определяют, *какие записи* роль может видеть и с которыми может работать — например, для роли самообслуживания, где каждый внешний пользователь видит только свои собственные записи.
+
+Объявляйте предикаты с помощью `rowLevelPermissionPredicates` в роли. Как и остальная часть манифеста, каждый предикат имеет свой собственный `universalIdentifier` и ссылается на объект и поле по их `universalIdentifier`, `operand`, а также (необязательно) поле workspaceMember, значение которого подставляется во время выполнения запроса — чтобы вы могли выразить: "отношение владельца записи **является** текущим участником рабочей области":
+
+```ts src/roles/partner-role.ts
+import {
+  defineRole,
+  RowLevelPermissionPredicateOperand,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+
+import { ACCOUNT_OWNER_FIELD_UNIVERSAL_IDENTIFIER } from '../fields/account-owner.field';
+
+export default defineRole({
+  universalIdentifier: 'c3c1dc2e-1a08-4de5-abb7-2139b3d99343',
+  label: 'Partner',
+  description: 'External partner — sees only its own records',
+  canBeAssignedToUsers: true,
+  objectPermissions: [
+    {
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      canReadObjectRecords: true,
+      canUpdateObjectRecords: true,
+    },
+  ],
+  rowLevelPermissionPredicates: [
+    {
+      universalIdentifier: 'd0f0c1a2-3b4c-4d5e-8f60-111111111111',
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      fieldUniversalIdentifier: ACCOUNT_OWNER_FIELD_UNIVERSAL_IDENTIFIER,
+      operand: RowLevelPermissionPredicateOperand.IS,
+      workspaceMemberFieldUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.workspaceMember.fields.id
+          .universalIdentifier,
+    },
+  ],
+});
+```
+
+Поскольку предикаты поставляются в манифесте, они создаются, обновляются и удаляются вместе с ролью при каждой установке и обновлении — не требуется отдельный шаг после установки для поддержания синхронизации.
+
+### Комбинирование предикатов с группами
+
+По умолчанию предикаты роли комбинируются с помощью `AND`. Чтобы комбинировать некоторые из них с помощью `OR` (или
+вкладывать логику), объявите запись `rowLevelPermissionPredicateGroups` и укажите на неё каждый предикат через
+`predicateGroupUniversalIdentifier`. Эта роль позволяет партнёру видеть сделку, которая либо **принадлежит** ему,
+либо по которой он является **контактным лицом**:
+
+```ts src/roles/partner-opportunities-role.ts
+import {
+  defineRole,
+  RowLevelPermissionPredicateGroupLogicalOperator,
+  RowLevelPermissionPredicateOperand,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+
+const OPPORTUNITY = STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.opportunity;
+const CURRENT_MEMBER =
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.workspaceMember.fields.id
+    .universalIdentifier;
+
+export default defineRole({
+  universalIdentifier: 'b2a1c0d9-8e7f-4a6b-9c5d-222222222222',
+  label: 'Partner (opportunities)',
+  canBeAssignedToUsers: true,
+  objectPermissions: [
+    {
+      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
+      canReadObjectRecords: true,
+    },
+  ],
+  rowLevelPermissionPredicateGroups: [
+    {
+      universalIdentifier: 'c3b2a1d0-9f8e-4b7a-8d6c-333333333333',
+      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
+      logicalOperator: RowLevelPermissionPredicateGroupLogicalOperator.OR,
+    },
+  ],
+  rowLevelPermissionPredicates: [
+    {
+      universalIdentifier: 'd4c3b2a1-0e9f-4c8b-9e7d-444444444444',
+      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
+      fieldUniversalIdentifier: OPPORTUNITY.fields.owner.universalIdentifier,
+      operand: RowLevelPermissionPredicateOperand.IS,
+      workspaceMemberFieldUniversalIdentifier: CURRENT_MEMBER,
+      predicateGroupUniversalIdentifier: 'c3b2a1d0-9f8e-4b7a-8d6c-333333333333',
+    },
+    {
+      universalIdentifier: 'e5d4c3b2-1f0e-4d9c-8f8e-555555555555',
+      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
+      fieldUniversalIdentifier:
+        OPPORTUNITY.fields.pointOfContact.universalIdentifier,
+      operand: RowLevelPermissionPredicateOperand.IS,
+      workspaceMemberFieldUniversalIdentifier: CURRENT_MEMBER,
+      predicateGroupUniversalIdentifier: 'c3b2a1d0-9f8e-4b7a-8d6c-333333333333',
+    },
+  ],
+});
+```
+
+Заметки:
+
+* Присвойте каждому предикату и группе стабильный `universalIdentifier` (любой uuid) — он служит ключом сущности между обновлениями, а предикаты ссылаются на группы по нему.
+* Предикаты могут ссылаться на объекты и поля, принадлежащие вашему приложению, или на стандартные объекты и поля Twenty.
+* Безопасность на уровне строк (row-level security) применяется для рабочих пространств в тарифах, которые её включают; предикаты по-прежнему синхронизируются
+  в других тарифах, они просто не применяются.
+
+## Роль функции по умолчанию
+
+Когда вы создаёте новое приложение с помощью шаблона, CLI создаёт файл роли по умолчанию, объявленный с помощью `defineApplicationRole()`:
+
+```ts src/roles/default-role.ts
+import { defineApplicationRole } from 'twenty-sdk/define';
+
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
+  'b648f87b-1d26-4961-b974-0908fd991061';
+
+export default defineApplicationRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: 'Default function role',
+  description: 'Default role for function Twenty client',
+  canReadAllObjectRecords: true,
+  canUpdateAllObjectRecords: false,
+  canSoftDeleteAllObjectRecords: false,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: false,
+  canBeAssignedToAgents: false,
+  canBeAssignedToUsers: false,
+  canBeAssignedToApiKeys: false,
+  objectPermissions: [],
+  fieldPermissions: [],
+  permissionFlagUniversalIdentifiers: [],
+});
+```
+
+`defineApplicationRole()` — это тонкая обёртка вокруг `defineRole()`, которая помечает **ту** роль, которая используется как роль приложения по умолчанию во время установки. Проверка идентична `defineRole`, но конвейер сборки автоматически подключает его `universalIdentifier` к полю `defaultRoleUniversalIdentifier` манифеста приложения — поэтому вам не нужно ссылаться на него из [`defineApplication`](/l/ru/developers/extend/apps/config/application) самостоятельно.
+
+Заметки:
+
+* Допускается ровно **один** вызов `defineApplicationRole(...)` на приложение — сборка манифеста завершится с ошибкой, если будет найдено более одного.
+* Используйте `defineRole()` (а не `defineApplicationRole()`) для любых **дополнительных** ролей, которые ставятся вместе с вашим приложением.
+* Явная установка `defaultRoleUniversalIdentifier` в `defineApplication()` всё ещё поддерживается для обратной совместимости, но считается устаревшей по сравнению с `defineApplicationRole()`.
+
+## Лучшие практики
+
+* Начните с сгенерированной роли и постепенно ограничивайте её — роль по умолчанию предоставляет широкий доступ на чтение, что редко подходит для продакшена.
+* Замените `objectPermissions` и `fieldPermissions` на точные объекты и поля, которые действительно нужны вашим функциям.
+* `permissionFlagUniversalIdentifiers` управляют доступом к возможностям на уровне платформы. Сведите их к минимуму.
+* Смотрите рабочий пример: [`examples/hello-world/src/roles/default-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/hello-world/src/roles/default-role.ts).

packages/twenty-docs/l/ru/developers/extend/apps/data/extending-objects.mdx

@@ -0,0 +1,52 @@
+---
+title: Расширение объектов
+description: Добавляйте поля к стандартным объектам Twenty (Person, Company, …) или к объектам из других приложений с помощью `defineField`.
+icon: wand-magic-sparkles
+---
+
+Используйте `defineField()` для добавления поля к объекту, которым вы не владеете — стандартному объекту Twenty, такому как Person или Company, или объекту, поставляемому другим установленным приложением. В отличие от встроенных полей, объявленных внутри [`defineObject`](/l/ru/developers/extend/apps/data/objects), отдельные поля требуют `objectUniversalIdentifier`, чтобы указать, какой объект они расширяют.
+
+```ts src/fields/company-loyalty-tier.field.ts
+import { defineField, FieldType } from 'twenty-sdk/define';
+
+export default defineField({
+  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
+  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
+  name: 'loyaltyTier',
+  type: FieldType.SELECT,
+  label: 'Loyalty Tier',
+  icon: 'IconStar',
+  options: [
+    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
+    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
+    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
+  ],
+});
+```
+
+## Основные моменты
+
+* `objectUniversalIdentifier` определяет целевой объект. Для стандартных объектов Twenty импортируйте константу из `twenty-sdk`:
+
+  ```ts
+  import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
+
+  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier
+  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier
+  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.opportunity.universalIdentifier
+  // …
+  ```
+
+* При определении полей **непосредственно внутри `defineObject()`** вам **не** нужен `objectUniversalIdentifier` — он наследуется от родительского объекта.
+
+* `defineField()` — единственный способ добавить поля к объектам, которые вы не создавали с помощью `defineObject()`.
+
+* Расположение файла зависит от вас. Принятое соглашение — `src/fields/\<name>.field.ts`, но SDK обнаруживает поля в любом месте внутри `src/`.
+
+* `writability` также может задаваться для каждого поля: `MetadataWritability.APPLICATION` ограничивает запись логическими функциями только вашего приложения, `MetadataWritability.SYSTEM` зарезервирован для данных, управляемых платформой. Изменяемость поля может быть только более строгой, чем уровень его объекта, и чтение при этом не затрагивается. Смотрите раздел [Objects](/l/ru/developers/extend/apps/data/objects) для полного описания семантики.
+
+* Чтобы добавить вкладку в стандартную компоновку страницы (например, на страницу сведений о задаче или компании), используйте [`definePageLayoutTab`](/l/ru/developers/extend/apps/layout/page-layouts#definepagelayouttab) с `STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS` из `twenty-sdk/define`.
+
+## Добавление связи к существующему объекту
+
+Чтобы добавить поле связи (например, связать ваш пользовательский объект со стандартным `Person`), используйте `defineField()` с `FieldType.RELATION`. Шаблон тот же, что и для встроенных связей, но с явным указанием `objectUniversalIdentifier`. Смотрите раздел [Relations](/l/ru/developers/extend/apps/data/relations) для двунаправленного шаблона.

packages/twenty-docs/l/ru/developers/extend/apps/data/objects.mdx

@@ -0,0 +1,143 @@
+---
+title: Объекты
+description: Объявляйте новые типы записей — пользовательские таблицы с собственными полями — с помощью defineObject.
+icon: table
+---
+
+Пользовательские **объекты** — это новые типы записей, которые ваше приложение добавляет в рабочее пространство — открытка, счёт-фактура, подписка, что‑то специфичное для вашей предметной области. Каждый объект объявляет свою схему (поля, связи, значения по умолчанию) и стабильный универсальный идентификатор, который сохраняется между синхронизациями и развёртываниями.
+
+```ts src/objects/post-card.object.ts
+import { defineObject, FieldType } from 'twenty-sdk/define';
+
+enum PostCardStatus {
+  DRAFT = 'DRAFT',
+  SENT = 'SENT',
+  DELIVERED = 'DELIVERED',
+  RETURNED = 'RETURNED',
+}
+
+export default defineObject({
+  universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
+  nameSingular: 'postCard',
+  namePlural: 'postCards',
+  labelSingular: 'Post Card',
+  labelPlural: 'Post Cards',
+  description: 'A post card object',
+  icon: 'IconMail',
+  fields: [
+    {
+      universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
+      name: 'content',
+      type: FieldType.TEXT,
+      label: 'Content',
+      description: "Postcard's content",
+      icon: 'IconAbc',
+    },
+    {
+      universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
+      name: 'recipientName',
+      type: FieldType.FULL_NAME,
+      label: 'Recipient name',
+      icon: 'IconUser',
+    },
+    {
+      universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
+      name: 'recipientAddress',
+      type: FieldType.ADDRESS,
+      label: 'Recipient address',
+      icon: 'IconHome',
+    },
+    {
+      universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
+      name: 'status',
+      type: FieldType.SELECT,
+      label: 'Status',
+      icon: 'IconSend',
+      defaultValue: `'${PostCardStatus.DRAFT}'`,
+      options: [
+        { value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
+        { value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
+        { value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
+        { value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
+      ],
+    },
+    {
+      universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
+      name: 'deliveredAt',
+      type: FieldType.DATE_TIME,
+      label: 'Delivered at',
+      icon: 'IconCheck',
+      isNullable: true,
+      defaultValue: null,
+    },
+  ],
+});
+```
+
+## Основные моменты
+
+* `universalIdentifier` должен быть уникальным и стабильным между развёртываниями.
+* Каждому полю требуются `name`, `type`, `label` и собственный стабильный `universalIdentifier`.
+* Массив `fields` необязателен — вы можете определять объекты без пользовательских полей.
+* `openRecordIn` определяет, где открываются записи этого объекта при щелчке: `ObjectOpenRecordIn.USER_CHOICE` (по умолчанию, в соответствии с индивидуальными настройками каждого участника рабочего пространства в Settings → Experience), `ObjectOpenRecordIn.SIDE_PANEL` или `ObjectOpenRecordIn.RECORD_PAGE`. Закрепите его на `RECORD_PAGE` для записей, которым для полноценного использования нужна целая страница (как у рабочих процессов и дашбордов), или на `SIDE_PANEL` для записей, которые уместны только в виде быстрой боковой панели (как события календаря).
+* `writability` определяет, кто в принципе может выполнять операции записи с записями объекта — до того, как начнут действовать разрешения ролей: `MetadataWritability.OPEN` (значение по умолчанию — решают роли рабочего пространства), `MetadataWritability.APPLICATION` (создавать, обновлять и удалять записи могут только собственные логические функции вашего приложения; используйте это для «конфигурационных» объектов, чьи записи задают поведение, чтобы участники рабочего пространства с широким доступом к записям не могли редактировать их через API) или `MetadataWritability.SYSTEM` (зарезервировано для данных, управляемых платформой). Операции чтения не затрагиваются — это ограничение применяется на стороне сервера, в отличие от `isUIEditable`, который лишь скрывает элементы интерфейса. Оно также существует на уровне отдельного поля, где может быть только более строгим, чем на уровне объекта.
+* Встроенным полям, определённым здесь, **не** нужен `objectUniversalIdentifier` — он наследуется от родительского объекта. Используйте [`defineField()`](/l/ru/developers/extend/apps/data/extending-objects), чтобы добавить поля к объектам, которые вам не принадлежат.
+* Вы можете сгенерировать заготовки новых объектов с помощью `yarn twenty dev:add object`, который проведёт вас через настройку названий, полей и связей. См. [Architecture → Scaffolding entities](/l/ru/developers/extend/apps/getting-started/scaffolding).
+
+<Note>
+**Базовые поля добавляются автоматически.** Когда вы определяете пользовательский объект, Twenty создаёт для вас стандартные поля, такие как `id`, `name`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` и `deletedAt`. Вам не нужно объявлять их в массиве `fields` — только ваши пользовательские поля. Вы можете переопределить базовое поле, объявив поле с тем же именем, но это редко бывает хорошей идеей.
+</Note>
+
+## Типы полей
+
+Полный набор значений `FieldType`, экспортируемых из `twenty-sdk/define`:
+
+| Категория              | Типы                                                                                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Текст                  | `TEXT`, `RICH_TEXT`, `ARRAY` (строк), `RAW_JSON`                                                                                   |
+| Числовые               | `NUMBER` (`universalSettings.dataType`: `'float'` / `'int'` / `'bigint'`), `NUMERIC` (произвольная точность), `RATING`, `POSITION` |
+| Даты                   | `DATE`, `DATE_TIME`                                                                                                                |
+| Выбор                  | `BOOLEAN`, `SELECT`, `MULTI_SELECT`                                                                                                |
+| Составные              | `FULL_NAME`, `ADDRESS`, `EMAILS`, `PHONES`, `LINKS`, `CURRENCY`, `ACTOR`, `FILES`                                                  |
+| Идентификаторы и связи | `UUID`, `RELATION`, `MORPH_RELATION` (см. [Relations](/l/ru/developers/extend/apps/data/relations))                                     |
+| Система                | `TS_VECTOR` (вектор полнотекстового поиска, управляется сервером)                                                                  |
+
+Составные типы хранят несколько подполей (например, `FULL_NAME` = имя + фамилия; `CURRENCY` = `amountMicros` + `currencyCode`). `SELECT` и `MULTI_SELECT` требуют массива `options`, как в примере выше.
+
+## Значения по умолчанию
+
+Строковые значения по умолчанию должны быть заключены в одинарные кавычки **внутри** строки — `defaultValue: "'Draft'"`, а не `defaultValue: "Draft"`. Именно поэтому поле `status` выше использует `` `'${PostCardStatus.DRAFT}'` ``.
+
+Незаключённые в кавычки строки зарезервированы для вычисляемых значений по умолчанию, которые рассчитываются при создании записи:
+
+* `'uuid'` — генерирует UUID (для полей `UUID`)
+* `'now'` — текущая временная метка (для полей `DATE_TIME`)
+
+Та же конвенция применяется к строковым подполям составных значений по умолчанию (например, `{ source: "'MANUAL'" }` в поле `ACTOR`) и к значениям `SELECT`/`MULTI_SELECT`. Строковый литерал по умолчанию, оставленный без кавычек, вызывает предупреждение при сборке приложения.
+
+## Допустимость значения NULL
+
+`isNullable` определяет, допускает ли поле значение `NULL`. По умолчанию установлено значение `true` — опускайте этот параметр для необязательных полей. Установите `isNullable: false`, чтобы сделать поле обязательным на уровне базы данных.
+
+Изменения `isNullable` применяются при каждой синхронизации, включая синхронизации, которые обновляют существующее поле, — таким образом, вы можете изменить допустимость значения NULL для поля, отредактировав манифест и повторно выполнив синхронизацию.
+
+<Note>
+**Чтобы сделать существующее поле не допускающим значение NULL, требуется значение по умолчанию.** Когда вы изменяете поле на `isNullable: false`, вы также должны предоставить значение `defaultValue`, отличное от `NULL`. Значение по умолчанию заполняет все существующие строки с `NULL` перед применением ограничения `NOT NULL`; без него синхронизация завершится с ошибкой `Default value cannot be null for non-nullable fields`. Поля связей и поля `TS_VECTOR` всегда допускают значение NULL, поэтому параметр `isNullable` на них не влияет.
+</Note>
+
+```ts
+{
+  universalIdentifier: 'b1a7c0de-1234-4f00-9abc-000000000000',
+  name: 'reference',
+  type: FieldType.TEXT,
+  label: 'Reference',
+  isNullable: false,
+  defaultValue: "'N/A'",
+}
+```
+
+## Что дальше
+
+* **Свяжите этот объект с другими** — см. [Relations](/l/ru/developers/extend/apps/data/relations) для двунаправленного шаблона связей.
+* **Добавляйте поля к объектам из других приложений** — см. [Extending Objects](/l/ru/developers/extend/apps/data/extending-objects) о `defineField()`.
+* **Отображать этот объект в интерфейсе** — см. [пункты меню навигации](/l/ru/developers/extend/apps/layout/navigation-menu-items), чтобы добавить пункт бокового меню; см. [представления](/l/ru/developers/extend/apps/layout/views), чтобы добавить пользовательские настройки списков.

packages/twenty-docs/l/ru/developers/extend/apps/data/overview.mdx

@@ -0,0 +1,101 @@
+---
+title: Обзор
+description: Определяйте структуру данных, которые ваше приложение добавляет в рабочее пространство — объекты, поля и связи.
+icon: database
+---
+
+**Уровень данных** приложения Twenty — это данные, которые ваше приложение *добавляет* в рабочее пространство: новые типы записей, которые оно объявляет, столбцы, которые оно добавляет к существующим объектам, и то, как эти записи связываются друг с другом.
+
+```text
+┌──────────────────────────────────────────────────┐
+│ Object — a record type, e.g. PostCard            │
+│    ├─ Field     (name, type, label)              │
+│    ├─ Field                                      │
+│    └─ Relation  (link to another object)         │
+└──────────────────────────────────────────────────┘
+            │
+            ├── lives in your app, OR
+            │
+            ▼
+┌──────────────────────────────────────────────────┐
+│ Standard / other apps' objects                   │
+│    └─ Field added by your app via defineField    │
+└──────────────────────────────────────────────────┘
+```
+
+## В этом разделе
+
+<CardGroup cols={2}>
+  <Card title="Объекты" icon="table" href="/l/ru/developers/extend/apps/data/objects">
+    `defineObject` — объявляйте новые типы записей с их собственными полями.
+  </Card>
+  <Card title="Расширение объектов" icon="wand-magic-sparkles" href="/l/ru/developers/extend/apps/data/extending-objects">
+    `defineField` — добавляйте поля к стандартным объектам или объектам других приложений.
+  </Card>
+  <Card title="Связи" icon="diagram-project" href="/l/ru/developers/extend/apps/data/relations">
+    Двусторонние связи `MANY_TO_ONE` / `ONE_TO_MANY` между объектами.
+  </Card>
+  <Card title="Типы действий на временной шкале" icon="clock-rotate-left" href="/l/ru/developers/extend/apps/data/timeline-activity-types">
+    Определяйте автоматические события аудита и явные события приложения для временных шкал записей.
+  </Card>
+</CardGroup>
+
+## Сущности вкратце
+
+| Сущность                            | Назначение                                                                                                                              | Определяется с помощью                 |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| **Объект**                          | Новый пользовательский тип записей (например, PostCard, Invoice) с собственными полями                                                  | `defineObject()`                       |
+| **Поле**                            | Столбец в объекте. Отдельные поля могут расширять объекты, которые вы не создавали (например, добавьте `loyaltyTier` к объекту Company) | `defineField()`                        |
+| **Связь**                           | Двусторонняя связь между двумя объектами — обе стороны объявлены как поля                                                               | `defineField()` с `FieldType.RELATION` |
+| **Индекс**                          | Индекс базы данных для ускорения повторяющегося запроса к одному из ваших объектов                                                      | `defineIndex()`                        |
+| **Тип действия на временной шкале** | Автоматическое событие аудита или явное событие домена, отображаемое на временных шкалах записей                                        | `defineTimelineActivityType()`         |
+
+SDK обнаруживает их с помощью анализа AST во время сборки, поэтому организация файлов остается на ваше усмотрение — по соглашению используются `src/objects/`, `src/fields/`, `src/indexes/` и `src/timeline-activity-types/`. Стабильные UUID `universalIdentifier` связывают все воедино между развертываниями.
+
+## Индексы (необязательно)
+
+Приложения могут поставлять индексы вместе со своими объектами, чтобы повторяющиеся запросы выполнялись быстро. Наиболее распространенный случай — столбец статуса или внешнего ключа, к которому вы часто обращаетесь при чтении.
+
+```ts src/indexes/post-card-status.index.ts
+import { defineIndex } from 'twenty-sdk/define';
+
+import {
+  POST_CARD_UNIVERSAL_IDENTIFIER,
+  STATUS_FIELD_UNIVERSAL_IDENTIFIER,
+} from '../objects/post-card.object';
+
+export default defineIndex({
+  universalIdentifier: 'b6e9d2a1-5a4c-46ca-9d52-42c8f02d1ff0',
+  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+  fields: [
+    {
+      universalIdentifier: 'b6e9d2a1-5a4c-46ca-9d52-42c8f02d1ff1',
+      fieldUniversalIdentifier: STATUS_FIELD_UNIVERSAL_IDENTIFIER,
+    },
+  ],
+});
+```
+
+### Уникальные индексы
+
+`defineIndex` принимает `isUnique: true` как для уникальности по одному столбцу, так и по нескольким столбцам. Это рекомендуемый примитив — `defineField({ isUnique: true })` устарел и будет удален в одном из будущих релизов.
+
+```ts
+defineIndex({
+  universalIdentifier: '…',
+  objectUniversalIdentifier: PERSON_UNIVERSAL_IDENTIFIER,
+  isUnique: true,
+  fields: [{ universalIdentifier: '…', fieldUniversalIdentifier: EMAIL_FIELD_UNIVERSAL_IDENTIFIER }],
+});
+```
+
+### Другие ограничения
+
+* Частичные предложения `WHERE` остаются под контролем администратора — приложения не могут объявлять их.
+* Для каждого объекта допускается не более 10 пользовательских индексов (индексы самого фреймворка не учитываются).
+
+Упорядочьте массив `fields` в том порядке, в котором Postgres должен его использовать — сначала самый левый столбец, как в телефонной книге. Индексы не бесплатны: при каждой записи в таблицу они обновляются. Добавляйте индекс только тогда, когда у вас есть запрос, которому он действительно нужен.
+
+<Note>
+Ищете **Application Config** или **Roles & Permissions**? Они описывают само приложение, а не данные, которые оно добавляет, — их можно найти в разделе [Config](/l/ru/developers/extend/apps/config/overview). Ищете **Connections** (Linear, GitHub, Slack OAuth)? Они существуют для вызова *из* логических функций и находятся в разделе [Logic](/l/ru/developers/extend/apps/logic/connections).
+</Note>

packages/twenty-docs/l/ru/developers/extend/apps/data/relations.mdx

@@ -0,0 +1,184 @@
+---
+title: Связи
+description: Связывайте объекты между собой двунаправленными связями MANY_TO_ONE / ONE_TO_MANY.
+icon: diagram-project
+---
+
+Отношения связывают два объекта между собой. В Twenty отношения всегда **двунаправленные** — у каждого отношения есть две стороны, и каждая сторона объявляется как поле, ссылающееся на другую.
+
+| Тип отношения | Описание                                                              | Есть внешний ключ?     |
+| ------------- | --------------------------------------------------------------------- | ---------------------- |
+| `MANY_TO_ONE` | Многие записи этого объекта указывают на одну запись целевого объекта | Да (`joinColumnName`)  |
+| `ONE_TO_MANY` | Одна запись этого объекта имеет много записей целевого объекта        | Нет (обратная сторона) |
+
+## Как работают отношения
+
+Каждое отношение требует **двух полей**, которые ссылаются друг на друга:
+
+1. Сторона **MANY_TO_ONE** — находится в объекте, который содержит внешний ключ.
+2. Сторона **ONE_TO_MANY** — находится в объекте, которому принадлежит коллекция.
+
+Оба поля используют `FieldType.RELATION` и ссылаются друг на друга через `relationTargetFieldMetadataUniversalIdentifier`.
+
+## Пример: Почтовая открытка имеет много получателей
+
+`PostCard` может быть отправлен множеству записей `PostCardRecipient`. Каждый получатель относится ровно к одной открытке.
+
+**Шаг 1: Определите сторону ONE_TO_MANY на PostCard** (сторона "one"):
+
+```ts src/fields/post-card-recipients-on-post-card.field.ts
+import { defineField, FieldType, RelationType } from 'twenty-sdk/define';
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
+import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
+
+// Export so the other side can reference it
+export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
+// Import from the other side
+import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
+
+export default defineField({
+  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
+  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+  type: FieldType.RELATION,
+  name: 'postCardRecipients',
+  label: 'Post Card Recipients',
+  icon: 'IconUsers',
+  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
+  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
+  universalSettings: {
+    relationType: RelationType.ONE_TO_MANY,
+  },
+});
+```
+
+**Шаг 2: Определите сторону MANY_TO_ONE на PostCardRecipient** (сторона "many" — содержит внешний ключ):
+
+```ts src/fields/post-card-on-post-card-recipient.field.ts
+import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk/define';
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
+import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
+
+// Export so the other side can reference it
+export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
+// Import from the other side
+import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
+
+export default defineField({
+  universalIdentifier: POST_CARD_FIELD_ID,
+  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
+  type: FieldType.RELATION,
+  name: 'postCard',
+  label: 'Post Card',
+  icon: 'IconMail',
+  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
+  universalSettings: {
+    relationType: RelationType.MANY_TO_ONE,
+    onDelete: OnDeleteAction.CASCADE,
+    joinColumnName: 'postCardId',
+  },
+});
+```
+
+<Note>
+**Циклические импорты:** оба поля отношений ссылаются на `universalIdentifier` друг друга. Чтобы избежать проблем с циклическими импортами, экспортируйте идентификаторы полей как именованные константы из каждого файла и импортируйте их в другом. Система сборки разрешает это на этапе компиляции.
+</Note>
+
+## Связи через промежуточный объект
+
+Промежуточный объект связывает одну исходную запись с одной или несколькими целевыми записями. Например, `PostCardRecipient` может содержать связь `postCard` и связь `recipient`. В поле `ONE_TO_MANY` исходного объекта задайте для `junctionTargetFieldUniversalIdentifier` поле связи в промежуточном объекте, указывающее на цель:
+
+```ts
+export default defineField({
+  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
+  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+  type: FieldType.RELATION,
+  name: 'postCardRecipients',
+  label: 'Post Card Recipients',
+  relationTargetObjectMetadataUniversalIdentifier:
+    POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
+  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
+  universalSettings: {
+    relationType: RelationType.ONE_TO_MANY,
+    junctionTargetFieldUniversalIdentifier: RECIPIENT_FIELD_ID,
+  },
+});
+```
+
+`RECIPIENT_FIELD_ID` должен идентифицировать связь `MANY_TO_ONE` или морфную связь в промежуточном объекте. Это сообщает Twenty, какая связанная запись является целевой, когда функция, например [распределение действий временной шкалы](/l/ru/developers/extend/apps/data/timeline-activity-types#automatic-and-explicit-events), проходит через промежуточный объект.
+
+## Связывание со стандартными объектами
+
+Чтобы создать отношение со встроенным объектом Twenty (Person, Company и т. д.), используйте `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
+
+```ts src/fields/person-on-self-hosting-user.field.ts
+import {
+  defineField,
+  FieldType,
+  RelationType,
+  OnDeleteAction,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
+
+export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
+export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
+
+export default defineField({
+  universalIdentifier: PERSON_FIELD_ID,
+  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
+  type: FieldType.RELATION,
+  name: 'person',
+  label: 'Person',
+  description: 'Person matching with the self hosting user',
+  isNullable: true,
+  relationTargetObjectMetadataUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
+  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
+  universalSettings: {
+    relationType: RelationType.MANY_TO_ONE,
+    onDelete: OnDeleteAction.SET_NULL,
+    joinColumnName: 'personId',
+  },
+});
+```
+
+## Свойства поля отношения
+
+| Свойство                                                   | Обязательно                                   | Описание                                                                                        |
+| ---------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `type`                                                     | Да                                            | Должно быть `FieldType.RELATION`                                                                |
+| `relationTargetObjectMetadataUniversalIdentifier`          | Да                                            | `universalIdentifier` целевого объекта                                                          |
+| `relationTargetFieldMetadataUniversalIdentifier`           | Да                                            | `universalIdentifier` соответствующего поля на целевом объекте                                  |
+| `universalSettings.relationType`                           | Да                                            | `RelationType.MANY_TO_ONE` или `RelationType.ONE_TO_MANY`                                       |
+| `universalSettings.onDelete`                               | Только для MANY_TO_ONE                        | Что происходит при удалении связанной записи: `CASCADE`, `SET_NULL`, `RESTRICT` или `NO_ACTION` |
+| `universalSettings.joinColumnName`                         | Только для MANY_TO_ONE                        | Имя столбца базы данных для внешнего ключа (например, `postCardId`)                             |
+| `universalSettings.junctionTargetFieldUniversalIdentifier` | Только для промежуточного объекта ONE_TO_MANY | Поле связи в промежуточном объекте, указывающее на цель распределения                           |
+
+## Встроенные поля связей
+
+Вы также можете объявить связь напрямую внутри [`defineObject`](/l/ru/developers/extend/apps/data/objects). При встроенном объявлении опустите `objectUniversalIdentifier` — он наследуется от родительского объекта:
+
+```ts
+export default defineObject({
+  universalIdentifier: '...',
+  nameSingular: 'postCardRecipient',
+  // ...
+  fields: [
+    {
+      universalIdentifier: POST_CARD_FIELD_ID,
+      type: FieldType.RELATION,
+      name: 'postCard',
+      label: 'Post Card',
+      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
+      universalSettings: {
+        relationType: RelationType.MANY_TO_ONE,
+        onDelete: OnDeleteAction.CASCADE,
+        joinColumnName: 'postCardId',
+      },
+    },
+    // … other fields
+  ],
+});
+```

packages/twenty-docs/l/ru/developers/extend/apps/data/system-fields.mdx

@@ -0,0 +1,211 @@
+---
+title: Обращение к системным метаданным
+description: Определяйте детерминированные универсальные идентификаторы метаданных, которые Twenty автоматически подготавливает для каждого объекта, чтобы ваше приложение могло ссылаться на них без жёсткого кодирования.
+icon: gears
+---
+
+Каждый объект в Twenty содержит **системные метаданные**, которые вы сами никогда не объявляете, например набор полей и основное представление списка с его столбцами. Сервер создаёт всё это при подготовке объекта, и этот набор растёт по мере развития Twenty.
+
+Поскольку вы это не объявляете, у вас нет константы `universalIdentifier`, которую можно импортировать. Вместо этого сервер **выводит** каждый идентификатор детерминированным образом, а `twenty-sdk` предоставляет тот же механизм вывода, чтобы ваш манифест мог получить точное значение, которое использует сервер.
+
+## Системные поля
+
+Скалярные поля, присутствующие в каждом объекте, ни одно из которых вы не объявляете с помощью [`defineField()`](/l/ru/developers/extend/apps/data/extending-objects):
+
+`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector`
+
+Тогда как сослаться на `createdAt` как на столбец в [представлении](/l/ru/developers/extend/apps/layout/views)?
+
+### Проблема
+
+Начиная с Twenty 2.19, универсальный идентификатор системного поля **детерминированно выводится** сервером из трех входных данных: универсального идентификатора приложения, универсального идентификатора объекта и имени поля. Придумать id и захардкодить его не получится: он не соответствует ничему на сервере, и синхронизация отклоняет висящую ссылку:
+
+```
+Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found
+```
+
+### Решение
+
+<Note>
+  `getFieldUniversalIdentifier` доступен, начиная с `twenty-sdk` версии 2.21.
+</Note>
+
+Используйте `getFieldUniversalIdentifier`, чтобы получить в точности то же значение, которое использует сервер. Он принимает три входных параметра и возвращает универсальный идентификатор поля:
+
+```ts
+import { getFieldUniversalIdentifier } from 'twenty-sdk/define';
+
+const createdAtFieldId = getFieldUniversalIdentifier({
+  applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+  objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
+  name: 'createdAt',
+});
+```
+
+* `applicationUniversalIdentifier` — это идентификатор вашего приложения, тот, который вы передаете в [`defineApplication()`](/l/ru/developers/extend/apps/config/application).
+* `objectUniversalIdentifier` — это идентификатор объекта, к которому принадлежит поле.
+* `name` — это имя системного поля, одно из значений, перечисленных выше.
+
+### Пример: столбец createdAt в представлении
+
+Типичный случай — добавление столбца `createdAt` в представление одного из ваших пользовательских объектов. Разрешите id поля и ссылайтесь на него так же, как на любой другой `fieldMetadataUniversalIdentifier`:
+
+```ts src/views/example-view.ts
+import {
+  defineView,
+  getFieldUniversalIdentifier,
+} from 'twenty-sdk/define';
+
+const APPLICATION_UNIVERSAL_IDENTIFIER =
+  '0b04e15c-27b2-4741-9046-b32e07469072';
+const MY_OBJECT_UNIVERSAL_IDENTIFIER =
+  'c782b61c-70fd-4c88-9cd6-4e61ab8d7591';
+
+export default defineView({
+  universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0',
+  name: 'All records',
+  objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
+  icon: 'IconList',
+  position: 0,
+  fields: [
+    {
+      universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104',
+      fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({
+        applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+        objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
+        name: 'createdAt',
+      }),
+      position: 0,
+      isVisible: true,
+      size: 200,
+    },
+  ],
+});
+```
+
+Тот же разрешенный id работает везде, где ожидается `fieldMetadataUniversalIdentifier`: поля представления, фильтры, сортировки, группировки и виджеты макета страницы.
+
+<Note>
+  Разрешайте id, не хардкодьте его. Поскольку сервер выводит значение из
+  id приложения, id объекта и имени поля, вызов
+  `getFieldUniversalIdentifier` сохраняет вашу ссылку корректной, даже если эти
+  входные данные изменятся, и предотвращает расхождение, если способ вывода когда-нибудь изменится.
+</Note>
+
+### Системные поля связей
+
+<Note>
+  `getSystemRelationFieldUniversalIdentifier` доступен в `twenty-sdk`, начиная с версии 2.23, и требует сервер Twenty версии 2.23 или новее.
+</Note>
+
+Помимо перечисленных выше скалярных системных полей, сервер также подготавливает четыре **системных поля связей** для каждого объекта: `timelineActivities`, `attachments`, `noteTargets` и `taskTargets`, каждое из которых указывает на соответствующий стандартный объект связи.
+
+Таким образом, эти поля не разрешаются с помощью `getFieldUniversalIdentifier`: их идентификатор выводится **безотносительно имени** из объекта, содержащего поле, и объекта, на который поле указывает. Таким образом, переименование объекта никогда не изменяет идентификаторы его полей связей.
+
+Используйте `getSystemRelationFieldUniversalIdentifier`, чтобы разрешить их:
+
+```ts
+import {
+  getSystemRelationFieldUniversalIdentifier,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+
+// rocket.attachments — the relation field hosted on your custom object
+const rocketAttachmentsFieldId = getSystemRelationFieldUniversalIdentifier({
+  applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+  objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
+  relationTargetObjectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier,
+});
+```
+
+* `objectUniversalIdentifier` — это объект, **содержащий** поле.
+* `relationTargetObjectUniversalIdentifier` — это объект, на который **указывает** поле.
+
+Направление кодируется порядком аргументов. Чтобы получить обратную сторону (например, `attachment.targetRocket`, morph‑поле, которое сервер создаёт на стандартном объекте связи), поменяйте их местами:
+
+```ts
+// attachment.targetRocket — the reverse morph field on Attachment
+const attachmentTargetRocketFieldId =
+  getSystemRelationFieldUniversalIdentifier({
+    applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+    objectUniversalIdentifier:
+      STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier,
+    relationTargetObjectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
+  });
+```
+
+Как и в случае со скалярными системными полями, разрешённый id работает везде, где ожидается `fieldMetadataUniversalIdentifier`.
+
+## Системные представления
+
+<Note>
+  `getSystemViewUniversalIdentifier` и `getSystemViewFieldUniversalIdentifier`
+  доступны в `twenty-sdk`, начиная с версии 2.26, и требуют сервер Twenty
+  версии 2.26 или новее.
+</Note>
+
+Сервер также подготавливает **системное представление** для каждого объекта: основное представление списка (`All {objectLabelPlural}`, с ключом `ViewKey.INDEX` (полученным с помощью `SYSTEM_VIEW_KEYS.INDEX`)), с одним столбцом на каждое отображаемое поле. Как и у системных полей связей, их идентификаторы выводятся **без использования имён**, поэтому переименование объекта или поля никогда их не меняет.
+
+Используйте `getSystemViewUniversalIdentifier`, чтобы получить идентификатор представления:
+
+```ts
+import {
+  getSystemViewUniversalIdentifier,
+  SYSTEM_VIEW_KEYS,
+} from 'twenty-sdk/define';
+
+const rocketIndexViewId = getSystemViewUniversalIdentifier({
+  objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+  objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
+  viewKey: SYSTEM_VIEW_KEYS.INDEX,
+});
+```
+
+* `objectMetadataApplicationUniversalIdentifier` — это приложение, которому принадлежит **объект**, и именно по нему задаётся пространство имён представления.
+* `objectUniversalIdentifier` — это объект, который отображается в представлении.
+* `viewKey` — это дискриминатор системного представления: `SYSTEM_VIEW_KEYS.INDEX` для основного представления списка, `SYSTEM_VIEW_KEYS.FIELDS_WIDGET` для представления виджета полей на странице записи. Он определяет способ вычисления представления; только `INDEX` также сохраняется в строке представления.
+
+Полученный идентификатор подходит везде, где ожидается `viewUniversalIdentifier`, например для пункта боковой панели [`NavigationMenuItemType.VIEW`](/l/ru/developers/extend/apps/layout/navigation-menu-items). Чтобы просто открыть основной список объекта, предпочитайте `NavigationMenuItemType.OBJECT` с `targetObjectUniversalIdentifier`: здесь не нужен вывод идентификатора.
+
+`getSystemViewFieldUniversalIdentifier` определяет идентификатор одного **столбца** в системном представлении по самому представлению и отображаемому в нём полю:
+
+```ts
+import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define';
+
+const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({
+  fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+  viewUniversalIdentifier: rocketIndexViewId,
+  fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER,
+});
+```
+
+Обратите внимание на первый аргумент: пространство имён столбца задаётся приложением, которому принадлежит **поле, отображаемое в нём**, а не приложением, которому принадлежит представление. Поле, которое ваше приложение добавляет к стандартному объекту, получает свой столбец, выводимый в пространстве имён вашего приложения, на представлении, принадлежащем Twenty.
+
+<Warning>
+  Системные представления и их столбцы **принадлежат серверу**: разрешайте их идентификаторы, чтобы ссылаться на них, но никогда не объявляйте их сами. `key` в
+  [`defineView()`](/l/ru/developers/extend/apps/layout/views) устарел и
+  игнорируется, поэтому представление из манифеста никогда не может заявить ключ `INDEX`, а сервер уже подготавливает столбец для каждого добавленного вами поля, так что объявление собственного
+  `defineViewField()` для того же поля в системном представлении конфликтует с ним.
+</Warning>
+
+## Стандартные объекты Twenty
+
+Для **стандартного** объекта Twenty (Person, Company, Opportunity, …) вам не нужно ничего выводить: идентификаторы как полей, так и представлений — это заранее вычисленные константы, которые вы можете импортировать напрямую.
+
+```ts
+import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
+
+// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier
+// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier
+// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.universalIdentifier
+```
+
+Используйте указанные выше вспомогательные функции, когда объект — это объект, который **ваше приложение** определяет с помощью [`defineObject()`](/l/ru/developers/extend/apps/data/objects), где такой константы не существует.
+
+<Note>
+  `name` — это **поле по умолчанию**, а не системное поле. У него есть собственный захардкоженный
+  универсальный идентификатор, и он не разрешается через
+  `getFieldUniversalIdentifier`. В определяемых вами объектах ссылайтесь на поле
+  `name` по идентификатору, который вы задали ему в `defineObject()`.
+</Note>

packages/twenty-docs/l/ru/developers/extend/apps/data/timeline-activity-types.mdx

@@ -0,0 +1,184 @@
+---
+title: Типы активности хронологии
+description: Определяет автоматические события аудита и события приложения, отображающие время записи.
+icon: clock-rotate-left
+---
+
+Тип активности временной шкалы определяет стабильный словарь событий, отображаемых на временной шкале. Стандартные объекты и прикладные объекты используют тот же контракт: тип имеет метку и иконку, можно объявить при выдаче, и может при желании отображать один из [фронтальных компонентов](/l/ru/developers/extend/apps/layout/front-components).
+
+<Note>
+  Виды активностей на временной шкале находятся в бета-версии и скоро появятся в разделе Двадцать 2.34.
+  API может развиваться, пока мы учимся у разработчиков приложений.
+</Note>
+
+Создайте один с помощью лесника:
+
+```bash filename="Terminal"
+yarn twenty dev:add timelineActivityType
+```
+
+Или определите его напрямую:
+
+```ts filename="src/timeline-activity-types/post-card-created.ts"
+import { defineTimelineActivityType } from 'twenty-sdk/define';
+
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
+
+export default defineTimelineActivityType({
+  universalIdentifier: 'f4fa646c-6e11-4d8f-a6be-c3b7a2fc7500',
+  name: 'postCardCreated',
+  label: 'created a post card',
+  icon: 'IconMail',
+  emit: {
+    on: 'created',
+    objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+  },
+});
+```
+
+## Автоматические и явные события
+
+Добавьте `emit`, когда двадцать должен создать этот тип автоматически. `emit.on` поддерживает `created`, `updated`, `deleted`, `restored`, `linked`, и `unlinked`, а `emit.objectUniversalIdentifier` идентифицирует объект источника. Только один эффективный тип может справиться с тем же эмулируемым ключом - `on`, объектом и необязательным - в рабочей области.
+
+Без `emit.through` событие записывается на собственной временной шкале источника. Чтобы пообщаться с соответствующими записями, установите `emit.through. elationFieldUniversalIdentifier` в исходном объекте либо прямое отношение множества к одному или [отношение одного-много соединения](/l/ru/developers/extend/apps/data/relations#junction-relations). Morph отношения с каждым членом группы морфов, так что одно объявление может быть направлено на несколько типов объектов.
+
+Для прямой связи создание или восстановление записи источника производит `linked`, удаляя ее производит `unlinked`, и перенаправление отношения приводит к `unlinked` на предыдущей цели плюс `linked` на новую цель. Другие обновления источников не дают ссылки на события. Это контракт используется приложениями, целью которых является прямая связь.
+
+Для связи между перекрёстками 'universalSettings.junctionTargetFieldUniversalIdentifier' идентифицирует отношение объекта соединения к цели. Создание или удаление строки перекрёстка производит `linked` или `unlinked`. Переадресация на обе стороны строки перекрёсток также производит ссылку событие; обновления к несвязанным полям не делают.
+
+События `linked` и `unlinked` требуют `emit.through`, потому что их триггер-триггер является изменением настроенной связи или соединения.
+
+Например, это тот же общий контракт, который используется заметками, задачами, сообщениями и событиями в календаре:
+
+```ts filename="src/timeline-activity-types/post-card-linked.ts"
+import { defineTimelineActivityType } from 'twenty-sdk/define';
+
+import { POST_CARD_RECIPIENTS_FIELD_UNIVERSAL_IDENTIFIER } from '../fields/post-card-recipients-on-post-card.field';
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
+
+export default defineTimelineActivityType({
+  universalIdentifier: 'f4fa646c-6e11-4d8f-a6be-c3b7a2fc7502',
+  name: 'postCardLinked',
+  label: 'received a post card',
+  icon: 'IconMail',
+  emit: {
+    on: 'linked',
+    objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+    through: {
+      relationFieldUniversalIdentifier:
+        POST_CARD_RECIPIENTS_FIELD_UNIVERSAL_IDENTIFIER,
+    },
+  },
+});
+```
+
+По умолчанию для каждого обновления источника выдается параметр «updated» через событие. Установите `emit.through.triggerFieldUniversalIdentifiers`, когда изменяются только выбранные исходные поля должны отображаться в целевые сроки.
+
+Omit `emit` для явного события домена, которое создаёт ваша логическая функция. Это позволяет избежать автоматического аудита и явной строки для одной и той же операции.
+
+```ts filename="src/timeline-activity-types/post-card-sent.ts"
+import { defineTimelineActivityType } from 'twenty-sdk/define';
+
+export default defineTimelineActivityType({
+  universalIdentifier: 'f4fa646c-6e11-4d8f-a6be-c3b7a2fc7501',
+  name: 'postCardSent',
+  label: 'sent a post card',
+  icon: 'IconSend',
+});
+```
+
+Создать явные события с помощью [`createTimelineActivity()`](/l/ru/developers/extend/apps/logic/logic-functions#create-a-timeline-activity). Код приложения использует стабильные универсальные идентификаторы; двадцать разрешает идентификаторы метаданных, специфичные для установки.
+
+## Пользовательский рендеринг
+
+Без переднего компонента двадцать передает обычный общий ряд из метаданных типа, значка и связанных объектов. Это работает для стандартных и пользовательских объектов без объектно-специфичного визуализатора.
+
+Для пользовательских деталей установите `frontComponentUniversalIdentifier` на передний компонент, принадлежащий тому же приложению:
+
+```ts
+export default defineTimelineActivityType({
+  universalIdentifier: 'f4fa646c-6e11-4d8f-a6be-c3b7a2fc7501',
+  name: 'postCardSent',
+  label: 'sent a post card',
+  icon: 'IconSend',
+  frontComponentUniversalIdentifier: '88c15ae2-5f87-4a6b-b48f-1974bbe62eb7',
+});
+```
+
+Натуральная строка остается свернутой презентацией. Двадцать монтируют передний компонент только после того, как пользователь расширяет ряд, избегая песочницы и рабочих для каждого видимого события. Внутри компонента вызовите `useTimelineActivityId()` из `twenty-sdk/front-component` для чтения ID строки и получения любых данных, необходимых для презентации. Возвращает `null`, когда компонент отображается за пределами ленты времени.
+
+## Переопределение презентации другого приложения
+
+Приложение имеет автоматические контракты на временной шкале для собственных объектов. Чтобы настроить событие на объекте, принадлежащем другому приложению, явно объявить существующий тип заменой `reTimelineActivityTypeUniversalIdentifier`:
+
+```ts
+export default defineTimelineActivityType({
+  universalIdentifier: 'f4fa646c-6e11-4d8f-a6be-c3b7a2fc7503',
+  name: 'companyCreatedWithDeploymentContext',
+  label: 'was created from a deployment',
+  emit: {
+    on: 'created',
+    objectUniversalIdentifier: COMPANY_UNIVERSAL_IDENTIFIER,
+  },
+  replacesTimelineActivityTypeUniversalIdentifier:
+    RECORD_CREATED_TIMELINE_ACTIVITY_TYPE_UNIVERSAL_IDENTIFIER,
+  frontComponentUniversalIdentifier: '88c15ae2-5f87-4a6b-b48f-1974bbe62eb7',
+});
+```
+
+Переопределение должно включать `emit`, потому что оно заменяет существующую ячейку автоматического излучения вместо явного типа. Указанный тип должен принадлежать приложению целевого объекта и описывать одно и то же действие и маршрут. Удаление переопределения приложения возвращает базовый тип; удаление базового типа отключает переопределение.
+
+## Рабочая область переопределяет и отключает звук
+
+Администраторы рабочего пространства могут изменять презентацию типа или отключать автоматические и явные события без форсирования приложения. Используйте мутацию `updateTimelineActivityType` метаданных API с идентификатором определенного типа установки:
+
+```graphql
+mutation CustomizeTimelineActivityType(
+  $id: UUID!
+  $label: String
+  $icon: String
+  $isActive: Boolean
+) {
+  updateTimelineActivityType(
+    input: { id: $id, label: $label, icon: $icon, isActive: $isActive }
+  ) {
+    id
+    label
+    icon
+    isActive
+  }
+}
+```
+
+`label` и `icon` хранятся как переопределение рабочего пространства, поэтому последующие обновления приложения не перезаписывают выбор администратора. Установите `isActive` в `false`, чтобы остановить автоматическое излучение и отклонить новые явные события этого типа. Существующие строки остаются видимыми.
+
+Восстановить настройки по умолчанию, включая активное состояние, например:
+
+```graphql
+mutation ResetTimelineActivityType($id: UUID!) {
+  resetTimelineActivityType(id: $id) {
+    id
+    label
+    icon
+    isActive
+  }
+}
+```
+
+## Поля конфигурации
+
+| Поле                                               | Обязательно  | Описание                                                                      |
+| -------------------------------------------------- | ------------ | ----------------------------------------------------------------------------- |
+| `universalIdentifier`                              | Да           | Стабильный UUID для всех установок и обновлений                               |
+| `name`                                             | Да           | Локальное для приложения программное имя; должно быть уникальным в приложении |
+| `label`                                            | Да           | Текст действий для пользователя, используемый родным рендерером               |
+| `icon`                                             | Нет          | Двадцать иконок, отображаемое рядом с событием                                |
+| `emit`                                             | Нет          | Автоматическое заявление о выбросах; опущение только для явных типов          |
+| `emit.on`                                          | С излучением | Ревизия для записи этого типа                                                 |
+| `emit.objectUniversalIdentifier`                   | С излучением | Объект с записями излучающей этот тип                                         |
+| `emit.through.relationFieldUniversalIdentifier`    | Нет          | Прямое или перекрёстое, используемое для вентиляции в соответствующие сроки   |
+| `emit.through.triggerFieldUniversalIdentifiers`    | Нет          | Исходные поля, которые могут инициировать «обновление» через событие          |
+| `frontComponentUniversalIdentifier`                | Нет          | Собственный фронтальный компонент монтируется при расширении ряда             |
+| `заменяет TimelineActivityTypeUniversalIdentifier` | Нет          | Существующий тип излучения заменён, требует `emit`                            |
+
+Двадцать снимков семантическая идентичность и прочная презентация, когда событие создается. Исторические строки сохраняют исходное значение действия и объекта. Пока тип установлен, в live отображаются текущая метка перевода, иконка и передние компоненты; после удаления резервный снимок сохраняет строку читаемой. Резолюция использует универсальный идентификатор, поэтому презентация также выживает после переустановки приложения.

packages/twenty-docs/l/ru/developers/extend/apps/getting-started/concepts.mdx

@@ -0,0 +1,102 @@
+---
+title: Понятия
+description: Как работают приложения Twenty — модель сущностей, изоляция в песочнице и жизненный цикл установки.
+icon: sitemap
+---
+
+Приложения Twenty — это пакеты TypeScript, которые расширяют ваше рабочее пространство пользовательскими объектами, логикой, компонентами интерфейса и возможностями ИИ. Они работают на платформе Twenty с полной изоляцией в песочнице и контролем прав доступа.
+
+## Как работают приложения
+
+Приложение — это набор **сущностей**, объявленных с помощью функций `defineEntity()` из пакета `twenty-sdk`. SDK обнаруживает эти объявления посредством анализа AST на этапе сборки и формирует **манифест** — полное описание того, что ваше приложение добавляет в рабочее пространство. Эти функции проверяют вашу конфигурацию на этапе сборки и обеспечивают автодополнение в IDE и безопасность типов.
+
+```
+your-app/
+├── src/
+│   ├── application-config.ts    ← defineApplication (required, one per app)
+│   ├── roles/                   ← defineRole
+│   ├── objects/                 ← defineObject
+│   ├── fields/                  ← defineField
+│   ├── logic-functions/         ← defineLogicFunction
+│   ├── front-components/        ← defineFrontComponent
+│   ├── skills/                  ← defineSkill
+│   ├── agents/                  ← defineAgent
+│   ├── views/                   ← defineView
+│   ├── navigation-menu-items/   ← defineNavigationMenuItem
+│   └── page-layouts/            ← definePageLayout
+├── public/                      ← Static assets (images, icons)
+└── package.json
+```
+
+<Note>
+  **Организация файлов — на ваше усмотрение.** Обнаружение сущностей основано на AST — SDK находит вызовы `export default defineEntity(...)` независимо от расположения файла. Структура папок выше — это соглашение, а не требование.
+</Note>
+
+## Типы сущностей
+
+| Сущность                  | Назначение                                                                       | Документация                                                                                                      |
+| ------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| **Приложение**            | Идентификация приложения, роль по умолчанию, переменные                          | [Конфигурация приложения](/l/ru/developers/extend/apps/config/application)                                             |
+| **Роль**                  | Наборы прав для объектов и полей                                                 | [Роли и разрешения](/l/ru/developers/extend/apps/config/roles)                                                         |
+| **Объект**                | Пользовательские типы записей с полями                                           | [Объекты](/l/ru/developers/extend/apps/data/objects)                                                                   |
+| **Поле**                  | Добавляйте поля к объектам из других приложений                                  | [Расширение объектов](/l/ru/developers/extend/apps/data/extending-objects)                                             |
+| **Связь**                 | Двунаправленные связи между объектами                                            | [Связи](/l/ru/developers/extend/apps/data/relations)                                                                   |
+| **Логическая функция**    | Серверный TypeScript с триггерами                                                | [Логические функции](/l/ru/developers/extend/apps/logic/logic-functions)                                               |
+| **Навык**                 | Повторно используемые инструкции для ИИ-агента                                   | [Навыки и агенты](/l/ru/developers/extend/apps/logic/skills-and-agents)                                                |
+| **Агент**                 | ИИ-агенты с пользовательскими промптами                                          | [Навыки и агенты](/l/ru/developers/extend/apps/logic/skills-and-agents)                                                |
+| **Провайдер подключения** | Учётные данные OAuth для сторонних API                                           | [Подключения](/l/ru/developers/extend/apps/logic/connections)                                                          |
+| **Представление**         | Преднастроенные представления списков записей                                    | [Представления](/l/ru/developers/extend/apps/layout/views)                                                             |
+| **Пункт меню навигации**  | Пользовательские элементы боковой панели                                         | [Элементы меню навигации](/l/ru/developers/extend/apps/layout/navigation-menu-items)                                   |
+| **Макет страницы**        | Вкладки и виджеты на странице сведений о записи                                  | [Макеты страниц](/l/ru/developers/extend/apps/layout/page-layouts)                                                     |
+| **Компонент фронтенда**   | Изолированный в песочнице интерфейс React внутри Twenty                          | [Компоненты фронтенда](/l/ru/developers/extend/apps/layout/front-components)                                           |
+| **Общие зависимости**     | Зависимости, общие для фронтенд-компонентов приложения, указанные в package.json | [Общие зависимости](/l/ru/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
+| **Элемент меню команд**   | Быстрые действия и элементы Cmd+K                                                | [Элементы меню команд](/l/ru/developers/extend/apps/layout/command-menu-items)                                         |
+
+## Изоляция в песочнице
+
+* **Логические функции** выполняются в изолированных процессах Node.js на сервере. Они получают доступ к данным только через типизированный API-клиент, который действует либо от имени человека, запустившего выполнение, либо от имени самого приложения. См. [Чей доступ использует вызов](/l/ru/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
+* **Компоненты фронтенда** запускаются в Web Workers с использованием Remote DOM — изолированы от основной страницы, но при этом рендерят нативные элементы DOM (не iframes). Они взаимодействуют с Twenty через хостовый API обмена сообщениями.
+* **Права доступа** применяются на уровне API. Внедряются два токена времени выполнения, оба производные от роли, объявленной с помощью `defineApplicationRole()`; область действия токена по умолчанию дополнительно ограничивается тем, что может делать человек, запустивший выполнение, когда за выполнением стоит человек.
+
+## Жизненный цикл приложения
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Development                                             │
+│   npx create-twenty-app → yarn twenty dev (live sync)   │
+├─────────────────────────────────────────────────────────┤
+│ Build & Deploy                                          │
+│   yarn twenty dev:build → yarn twenty app:publish        │
+├─────────────────────────────────────────────────────────┤
+│ Install flow                                            │
+│   upload → [pre-install] → metadata migration →         │
+│   generate SDK → [post-install] → … → [uninstall]       │
+├─────────────────────────────────────────────────────────┤
+│ Publish                                                 │
+│   npm publish → appears in Twenty marketplace           │
+└─────────────────────────────────────────────────────────┘
+```
+
+* **`yarn twenty dev`** — следит за исходными файлами и синхронизирует изменения в реальном времени с подключённым сервером Twenty. Типизированный клиент API автоматически пересоздаётся при изменении схемы.
+* **`yarn twenty dev:build`** — компилирует TypeScript, упаковывает логические функции и фронтенд-компоненты с помощью esbuild и формирует манифест.
+* **Хуки до/после установки и удаления** — необязательные функции, которые выполняются во время установки или непосредственно перед удалением. См. раздел [Install Hooks](/l/ru/developers/extend/apps/config/install-hooks) для подробностей.
+
+## Следующие шаги
+
+<CardGroup cols={2}>
+  <Card title="Конфигурация" icon="screwdriver-wrench" href="/l/ru/developers/extend/apps/config/overview">
+    Идентификация приложения, роль по умолчанию, а также хуки установки и удаления.
+  </Card>
+  <Card title="Данные" icon="database" href="/l/ru/developers/extend/apps/data/overview">
+    Объекты, поля и двунаправленные связи.
+  </Card>
+  <Card title="Логика" icon="bolt" href="/l/ru/developers/extend/apps/logic/overview">
+    Логические функции, навыки, агенты и OAuth-подключения.
+  </Card>
+  <Card title="Макет" icon="table-columns" href="/l/ru/developers/extend/apps/layout/overview">
+    Представления, навигация, макеты страниц, фронтенд-компоненты.
+  </Card>
+  <Card title="Операции" icon="rocket" href="/l/ru/developers/extend/apps/operations/overview">
+    CLI, тестирование, удаленные окружения, CI и публикация вашего приложения.
+  </Card>
+</CardGroup>

packages/twenty-docs/l/ru/developers/extend/apps/getting-started/local-server.mdx

@@ -0,0 +1,87 @@
+---
+title: Локальный сервер
+description: Управление локальным Docker-сервером Twenty — запуск, остановка, обновление, параллельный тестовый экземпляр и ручная настройка SDK.
+icon: server
+---
+
+## Управление локальным сервером
+
+Используйте `yarn twenty docker:*` для управления локальным контейнером Twenty:
+
+| Команда                                | Что делает                                           |
+| -------------------------------------- | ---------------------------------------------------- |
+| `yarn twenty docker:start`             | Запустить сервер (при необходимости скачивает образ) |
+| `yarn twenty docker:start 2.2.0`       | Запустить конкретную версию сервера                  |
+| `yarn twenty docker:start --port 3030` | Запустить на пользовательском порту                  |
+| `yarn twenty docker:stop`              | Остановить сервер (данные сохраняются)               |
+| `yarn twenty docker:status`            | Показать URL, версию и учётные данные для входа      |
+| `yarn twenty docker:logs`              | Потоковый вывод журналов сервера                     |
+| `yarn twenty docker:reset`             | Стереть данные и начать заново                       |
+| `yarn twenty docker:upgrade`           | Скачать последний образ `twenty-app-dev`             |
+| `yarn twenty docker:upgrade 2.2.0`     | Обновить до конкретной версии                        |
+
+Данные сохраняются между перезапусками в двух томах Docker (`twenty-app-dev-data` для PostgreSQL, `twenty-app-dev-storage` для файлов). Используйте `reset`, чтобы стереть всё.
+
+## Фиксация версии сервера
+
+Когда версия не передана, `docker:start` определяет версию из диапазона `engines.twenty` вашего приложения в `package.json` — того же диапазона, по которому сервер выполняет проверку при установке вашего приложения. Он запускает самый новый опубликованный образ `twenty-app-dev`, который удовлетворяет диапазону, и использует `latest`, если поле отсутствует или ни одна опубликованная версия не совпадает:
+
+```json filename="package.json"
+{
+  "engines": {
+    "twenty": ">=2.2.0"
+  }
+}
+```
+
+Передайте версию явно, чтобы переопределить диапазон для одного запуска: `yarn twenty docker:start 2.3.0`. Если контейнер уже существует с другой версией, `docker:start` обновляет его на месте (пересоздаёт контейнер с сохранением томов данных).
+
+## Обновление образа сервера
+
+`yarn twenty docker:upgrade` скачивает последний образ, сравнивает дайджесты и пересоздаёт контейнер только если действительно что-то изменилось. Тома сохраняются — заменяется только контейнер. Если был скачан новый образ и контейнер работал, при обновлении автоматически запускается новый контейнер; затем выполните `yarn twenty docker:start`, чтобы дождаться его готовности.
+
+```bash filename="Terminal"
+yarn twenty docker:upgrade            # Latest
+yarn twenty docker:upgrade 2.2.0      # Specific version
+```
+
+Проверьте запущенную версию с помощью `yarn twenty docker:status` (эта команда показывает `APP_VERSION`, встроенную в контейнер).
+
+## Запуск параллельного тестового экземпляра
+
+Передайте `--test` любой команде `docker:*`, чтобы управлять вторым, полностью изолированным экземпляром — это полезно для запуска интеграционных тестов или экспериментов, не затрагивая ваши основные данные разработки:
+
+| Команда                             | Что делает                                              |
+| ----------------------------------- | ------------------------------------------------------- |
+| `yarn twenty docker:start --test`   | Запустить тестовый экземпляр (по умолчанию — порт 2021) |
+| `yarn twenty docker:stop --test`    | Остановить его                                          |
+| `yarn twenty docker:status --test`  | Показать его статус                                     |
+| `yarn twenty docker:logs --test`    | Транслировать его журналы                               |
+| `yarn twenty docker:reset --test`   | Стереть его данные                                      |
+| `yarn twenty docker:upgrade --test` | Обновить его образ                                      |
+
+Тестовый экземпляр запускается в собственном контейнере Docker (`twenty-app-dev-test`) с выделенными томами (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) и собственной конфигурацией, поэтому он может работать параллельно с вашим основным экземпляром без конфликтов. Совместите `--test` с `--port`, чтобы переопределить значение по умолчанию (2021).
+
+## Ручная настройка (без генератора каркаса)
+
+Пропустите генератор каркаса, если вы добавляете SDK в существующий проект:
+
+```bash filename="Terminal"
+yarn add twenty-sdk twenty-client-sdk
+```
+
+Добавьте скрипт в `package.json`:
+
+```json filename="package.json"
+{
+  "scripts": {
+    "twenty": "twenty"
+  }
+}
+```
+
+Теперь вы можете запускать `yarn twenty dev`, `yarn twenty docker:start` и остальные команды.
+
+<Note>
+Не устанавливайте `twenty-sdk` глобально — фиксируйте версию в каждом проекте, чтобы каждое приложение использовало свою собственную версию.
+</Note>

packages/twenty-docs/l/ru/developers/extend/apps/getting-started/project-structure.mdx

@@ -0,0 +1,79 @@
+---
+title: Структура проекта
+description: Что находится внутри сгенерированного приложения Twenty — файлы, папки и назначение каждого из них.
+icon: folder-tree
+---
+
+Новое приложение, сгенерированное с помощью `npx create-twenty-app`, выглядит так:
+
+```text filename="my-twenty-app/"
+my-twenty-app/
+  package.json
+  src/
+    application-config.ts                   # Required — your app's entry point
+    default-role.ts                         # Permissions for logic functions
+    constants/
+      universal-identifiers.ts              # Auto-generated UUIDs and metadata
+    front-components/
+      main-page.tsx                         # Welcome page component
+    navigation-menu-items/
+      main-page.navigation-menu-item.ts     # Sidebar entry for the welcome page
+    page-layouts/
+      main-page.page-layout.ts              # Standalone page hosting the component
+    __tests__/
+      application-config.test.ts            # Unit test
+      global-setup.ts                       # Integration test setup (sync + uninstall)
+      schema.integration-test.ts            # Integration test against a live server
+  .github/workflows/
+    ci.yml                                  # Lint, typecheck, unit + integration tests
+    cd.yml                                  # Deploy + install on push to main
+    publish.yml                             # Publish to npm on version tags (with provenance)
+  public/
+    logo.svg                                # Static assets
+  vitest.config.ts                          # Integration test runner config
+  vitest.unit.config.ts                     # Unit test runner config
+  tsconfig.json, tsconfig.spec.json
+  .nvmrc, .yarnrc.yml, .oxlintrc.json
+  README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md
+```
+
+## Ключевые файлы
+
+| Файл / Папка                                                               | Назначение                                                                                                                    |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `src/application-config.ts`                                                | **Обязательно.** Основной файл конфигурации для вашего приложения.                                                            |
+| `src/default-role.ts`                                                      | Роль по умолчанию, контролирующая, к чему имеют доступ ваши логические функции.                                               |
+| `src/constants/universal-identifiers.ts`                                   | Автоматически генерируемые UUID и метаданные (отображаемое имя, описание).                                                    |
+| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | Стартовая приветственная страница: фронтенд-компонент, отображаемый отдельным макетом страницы и доступный из боковой панели. |
+| `src/__tests__/`                                                           | Модульный тест плюс интеграционный тест (с его глобальной настройкой), которые синхронизируют приложение с реальным сервером. |
+| `public/`                                                                  | Статические ресурсы (изображения, шрифты), обслуживаемые вместе с вашим приложением.                                          |
+| `AGENTS.md` / `CLAUDE.md`                                                  | Руководство для ИИ-агентов, пишущих код для приложения.                                                                       |
+| `CHANGELOG.md` / `SETUP.md`                                                | Журнал значимых изменений и инструкции по настройке для локальной разработки.                                                 |
+
+<Note>
+**Организация файлов — на ваше усмотрение.** Приведенные выше папки являются соглашениями — SDK обнаруживает сущности с помощью AST-анализа вызовов `export default defineEntity(...)` независимо от того, где расположен файл.
+</Note>
+
+## Зависимости
+
+Оба пакета Twenty SDK должны находиться в `devDependencies`, а не в `dependencies`:
+
+```json filename="package.json"
+{
+  "dependencies": {},
+  "devDependencies": {
+    "twenty-client-sdk": "2.20.0",
+    "twenty-sdk": "2.20.0",
+    "twenty-ui": "1.0.0-alpha.1"
+  }
+}
+```
+
+Генератор заготовок фиксирует версии `twenty-sdk` и `twenty-client-sdk` на своей собственной версии — сохраняйте их синхронизацию при обновлении.
+
+* **`twenty-sdk`** поставляет `twenty` CLI и инструменты сборки/скэффолдинга. Он выполняется только на этапах разработки и сборки и никогда не импортируется во время выполнения опубликованного приложения.
+* **`twenty-client-sdk`** *действительно* импортируется кодом вашего приложения (`CoreApiClient`, `MetadataApiClient`, `RestApiClient`), но Twenty предоставляет его во время выполнения — функции логики получают его из сгенерированного слоя SDK, а фронтенд‑компоненты получают его из модулей, отдаваемых сервером. Установленная вами копия используется только для проверки типов и сборки на этапе деплоя, поэтому её не нужно включать в развертываемый бандл.
+
+Если любой из пакетов находится в `dependencies`, он попадает в бандл среды выполнения установленного приложения, где он является лишним грузом. `twenty dev:build` выдаёт предупреждение, если любой из них всё ещё указан в `dependencies`.
+
+Добавляйте собственные зависимости среды выполнения вашего приложения (библиотеки, которые ваши функции логики действительно импортируют во время выполнения) в `dependencies`, как обычно. Держите дерево лёгким: `dependencies` устанавливаются в слой выполнения с ограничением 250 МБ в распакованном виде, и операция синхронизации или установки завершается ошибкой размера зависимостей при превышении этого лимита — UI-библиотеки и инструменты разработки должны находиться в `devDependencies`.

packages/twenty-docs/l/ru/developers/extend/apps/getting-started/quick-start.mdx

@@ -0,0 +1,166 @@
+---
+title: Быстрый старт
+icon: rocket
+description: Создайте своё первое приложение Twenty за считанные минуты.
+---
+
+## Требования
+
+* **Node.js 24.5+** — [Скачать здесь](https://nodejs.org/)
+* **Yarn 4** — поставляется вместе с Node.js через Corepack. Включите его, выполнив `corepack enable`
+* **Docker** — [Скачать здесь](https://www.docker.com/products/docker-desktop/). Требуется для запуска локального экземпляра Twenty. Пропустите, если у вас уже запущен Twenty в другом месте.
+
+Создание приложения Twenty включает три фазы. Генератор каркаса объединяет их в одну команду для идеального сценария (happy path), но каждая фаза — отдельная концепция: когда что-то идёт не так, понимание того, на какой фазе вы находитесь, подскажет, что исправить.
+
+| Фаза                    | Что вы делаете                                    | Инструмент                          | Результат                              |
+| ----------------------- | ------------------------------------------------- | ----------------------------------- | -------------------------------------- |
+| **1. Создание каркаса** | Сгенерировать исходный код приложения             | `npx create-twenty-app`             | Проект TypeScript на диске             |
+| **2. Запустить сервер** | Запустить сервер Twenty для синхронизации         | Docker + `yarn twenty docker:start` | Запущенный экземпляр Twenty            |
+| **3. Синхронизация**    | Синхронизируйте код с сервером в реальном времени | `yarn twenty dev`                   | Ваши изменения появляются в интерфейсе |
+
+---
+
+## Фаза 1 — Сгенерируйте каркас проекта
+
+Создайте новое приложение из шаблона:
+
+```bash filename="Terminal"
+npx create-twenty-app@latest my-twenty-app
+```
+
+Генератор работает в неинтерактивном режиме: имя каталога становится именем приложения. Передайте `--display-name` и `--description`, чтобы настроить создаваемые метаданные (вы также можете отредактировать их позже в `src/constants/universal-identifiers.ts`). Это создаёт проект TypeScript в `my-twenty-app/` с начальным файлом `application-config.ts`, ролью по умолчанию, рабочими процессами CI/CD и интеграционным тестом.
+
+**После этой фазы:** у вас есть исходный код приложения на вашем компьютере. Он ещё не запущен — это фаза 2.
+
+---
+
+## Фаза 2 — Запустите локальный сервер Twenty
+
+Вашему приложению нужен сервер Twenty для синхронизации. Сервер — это полноценный экземпляр Twenty — UI, GraphQL API, PostgreSQL — работающий локально в Docker. Ваш локальный код загружает свои определения на этот сервер, благодаря чему они появляются в интерфейсе.
+
+Генератор запускает её за вас: при запущенном Docker он скачивает образ `twentycrm/twenty-app-dev`, запускает его на порту `2020` и аутентифицирует CLI в предварительно заполненном демо‑workspace (`tim@apple.dev`) — вход не требуется.
+
+Чтобы вместо этого подключиться к существующему серверу Twenty, передайте `--url \<your-server-url>`. Удалённые серверы аутентифицируются через OAuth: открывается браузер, чтобы вы могли войти в систему и нажать **Authorize**, после чего CLI получает доступ к вашему workspace. (Локально вы тоже можете включить OAuth с помощью `--authentication-method oauth` — войдите, используя `tim@apple.dev` / `tim@apple.dev`.)
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/login.png" alt="Экран входа в Twenty" />
+</div>
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Экран авторизации Twenty CLI" />
+</div>
+
+В вашем терминале появится подтверждение, что всё настроено.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="Каркас приложения успешно создан" />
+</div>
+
+**После этой фазы:** у вас запущен сервер Twenty на [http://localhost:2020](http://localhost:2020), а ваш CLI авторизован для синхронизации с ним.
+
+<Note>
+Если Docker не установлен или не запущен, генератор каркаса подскажет правильную команду запуска для вашей ОС. Когда Docker будет запущен, вы можете продолжить с `yarn twenty docker:start` — заново генерировать каркас не нужно.
+</Note>
+
+---
+
+## Фаза 3 — Синхронизируйте свои изменения
+
+Это внутренний цикл, в котором вы проведёте большую часть времени.
+
+```bash filename="Terminal"
+cd my-twenty-app
+yarn twenty dev
+```
+
+Эта команда отслеживает `src/`, пересобирает при каждом изменении и синхронизирует результат с сервером. Отредактируйте файл, сохраните — и через несколько секунд сервер отразит изменения. В терминале появится панель текущего статуса.
+
+Для более подробного вывода (журналы сборки, запросы синхронизации, трассировки ошибок) добавьте `--verbose`.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/dev.png" alt="Вывод терминала в режиме разработки" />
+</div>
+
+Откройте [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Вы должны увидеть своё приложение в разделе **Your Apps**.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Список Your Apps с приложением My twenty app" />
+</div>
+
+Нажмите **My twenty app**, чтобы открыть его регистрацию приложения — запись на уровне сервера, описывающую ваше приложение (имя, идентификатор, учётные данные OAuth, источник). Одну и ту же регистрацию можно установить в нескольких рабочих пространствах на одном сервере.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Сведения о регистрации приложения" />
+</div>
+
+Нажмите **View installed app**, чтобы посмотреть установку в рабочем пространстве. Вкладка **About** показывает версию и параметры управления.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Установленное приложение" />
+</div>
+
+**После этой фазы:** у вас есть интерактивный цикл разработки. Отредактируйте любой файл в `src/`, и он появится в интерфейсе.
+
+### Разовая синхронизация для CI и скриптов
+
+Используйте `plan` и `apply`, чтобы один раз запустить тот же конвейер без наблюдателя:
+
+```bash filename="Terminal"
+yarn twenty plan   # preview the metadata changes without applying them
+yarn twenty apply  # show the plan, then apply it
+```
+
+| Команда             | Поведение                                                                                                                                                                               | Когда использовать                                                                |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `yarn twenty dev`   | Отслеживает и повторно синхронизирует при каждом изменении. Продолжает работать, пока вы его не остановите.                                                                             | Интерактивная локальная разработка.                                               |
+| `yarn twenty apply` | Одна сборка и синхронизация, завершает работу с кодом `0` при успехе и `1` при ошибке. Запрашивает подтверждение при разрушительных изменениях (передайте `--force`, чтобы пропустить). | CI, хуки pre-commit, AI-агенты, скриптовые рабочие процессы.                      |
+| `yarn twenty plan`  | Создает и выводит изменения метаданных **без их применения**.                                                                                                                           | Проверка того, какие изменения внесет синхронизация, прежде чем зафиксировать их. |
+
+Все режимы требуют аутентифицированного удалённого сервера. Смотрите раздел [Syncing & recovery](/l/ru/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) для получения дополнительной информации о `plan`.
+
+<Note>
+`yarn twenty dev --once` и `yarn twenty dev --once --dry-run` являются устаревшими псевдонимами для `yarn twenty apply` и `yarn twenty plan`.
+</Note>
+
+### Параметры режима разработки
+
+| Флаг                                  | Описание                                                                              |
+| ------------------------------------- | ------------------------------------------------------------------------------------- |
+| `--force`                             | Применяет разрушительные изменения (удаления) без подтверждения.                      |
+| `--debounceMs \<ms>` | Установить задержку дебаунса изменений файлов в миллисекундах (по умолчанию: `1000`). |
+| `--verbose` / `--debug`               | Показывать подробные журналы сборки, запросы синхронизации и трассировки ошибок.      |
+
+## Что вы можете создать
+
+Приложения состоят из **сущностей** — каждая определена как файл TypeScript с одним `export default`:
+
+| Сущность                      | Что делает                                                                                                |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
+| **Объекты и поля**            | Пользовательские модели данных (почтовая открытка, счёт и т. д.) с типизированными полями                 |
+| **Логические функции**        | Серверный TypeScript, запускаемый HTTP-маршрутами, расписаниями cron или событиями базы данных            |
+| **Фронтенд-компоненты**       | React-компоненты, которые отображаются внутри интерфейса Twenty (боковая панель, виджеты, командное меню) |
+| **Навыки и агенты**           | Возможности ИИ — многократно используемые инструкции и автономные помощники                               |
+| **Представления и навигация** | Предварительно настроенные представления списков и элементы бокового меню                                 |
+| **Макеты страниц**            | Пользовательские страницы сведений о записи с вкладками и виджетами                                       |
+
+Полная справка: [Концепции](/l/ru/developers/extend/apps/getting-started/concepts).
+
+## Следующие шаги
+
+<CardGroup cols={2}>
+  <Card title="Конфигурация" icon="screwdriver-wrench" href="/l/ru/developers/extend/apps/config/overview">
+    Идентификация приложения, роль по умолчанию, хуки установки и удаления, публичные ресурсы.
+  </Card>
+  <Card title="Данные" icon="database" href="/l/ru/developers/extend/apps/data/overview">
+    Объекты, поля и двунаправленные связи.
+  </Card>
+  <Card title="Логика" icon="bolt" href="/l/ru/developers/extend/apps/logic/overview">
+    Логические функции, навыки, агенты и OAuth-подключения.
+  </Card>
+  <Card title="Макет" icon="table-columns" href="/l/ru/developers/extend/apps/layout/overview">
+    Представления, навигация, макеты страниц, фронтенд-компоненты.
+  </Card>
+  <Card title="Операции" icon="rocket" href="/l/ru/developers/extend/apps/operations/overview">
+    CLI, тестирование, удалённые серверы, CI и публикация вашего приложения.
+  </Card>
+</CardGroup>

packages/twenty-docs/l/ru/developers/extend/apps/getting-started/scaffolding.mdx

@@ -0,0 +1,63 @@
+---
+title: Создание каркаса
+description: Интерактивно генерируйте файлы сущностей с помощью yarn twenty dev:add — объекты, поля, представления, логические функции и многое другое.
+icon: wand-magic-sparkles
+---
+
+Вместо ручного создания файлов сущностей используйте интерактивный генератор:
+
+```bash filename="Terminal"
+yarn twenty dev:add
+```
+
+Он предлагает выбрать тип сущности и пошагово проводит через обязательные поля, а затем записывает готовый к использованию файл со стабильным `universalIdentifier` и корректным вызовом `defineEntity()`.
+
+Вы также можете передать тип сущности напрямую, чтобы пропустить первый запрос:
+
+```bash filename="Terminal"
+yarn twenty dev:add object
+yarn twenty dev:add logicFunction
+yarn twenty dev:add frontComponent
+```
+
+## Доступные типы сущностей
+
+| Тип сущности                    | Команда                                    | Сгенерированный файл                                      |
+| ------------------------------- | ------------------------------------------ | --------------------------------------------------------- |
+| Объект                          | `yarn twenty dev:add object`               | `src/objects/\<name>.ts`                 |
+| Поле                            | `yarn twenty dev:add field`                | `src/fields/\<name>.ts`                  |
+| Логическая функция              | `yarn twenty dev:add logicFunction`        | `src/logic-functions/\<name>.ts`         |
+| Компонент фронтенда             | `yarn twenty dev:add frontComponent`       | `src/front-components/\<name>.tsx`       |
+| Роль                            | `yarn twenty dev:add role`                 | `src/roles/\<name>.ts`                   |
+| Навык                           | `yarn twenty dev:add skill`                | `src/skills/\<name>.ts`                  |
+| Агент                           | `yarn twenty dev:add agent`                | `src/agents/\<name>.ts`                  |
+| Представление                   | `yarn twenty dev:add view`                 | `src/views/\<name>.ts`                   |
+| Пункт меню навигации            | `yarn twenty dev:add navigationMenuItem`   | `src/navigation-menu-items/\<name>.ts`   |
+| Макет страницы                  | `yarn twenty dev:add pageLayout`           | `src/page-layouts/\<name>.ts`            |
+| Вкладка компоновки страницы     | `yarn twenty dev:add pageLayoutTab`        | `src/page-layout-tabs/\<name>.ts`        |
+| Элемент меню команд             | `yarn twenty dev:add commandMenuItem`      | `src/command-menu-items/\<name>.ts`      |
+| Поле представления              | `yarn twenty dev:add viewField`            | `src/view-fields/\<name>.ts`             |
+| Провайдер подключения           | `yarn twenty dev:add connectionProvider`   | `src/connection-providers/\<name>.ts`    |
+| Тип действия на временной шкале | `yarn twenty dev:add timelineActivityType` | `src/timeline-activity-types/\<name>.ts` |
+
+## Что генерирует скэффолдер
+
+У каждого типа сущности есть свой шаблон. Например, `yarn twenty dev:add object` запрашивает:
+
+1. **Имя (единственное число)** — например, `invoice`
+2. **Имя (множественное число)** — например, `invoices`
+3. **Метка (единственное число)** — заполняется автоматически из имени (например, `Invoice`)
+4. **Метка (множественное число)** — заполняется автоматически (например, `Invoices`)
+5. **Создать представление и пункт навигации?** — если вы ответите «да», скэффолдер также сгенерирует соответствующее представление и ссылку в боковой панели для нового объекта.
+
+У других типов сущностей подсказки проще — в большинстве случаев запрашивается только имя.
+
+Тип сущности `field` более детализирован: он запрашивает имя поля, метку, тип (из списка всех доступных типов полей, таких как `TEXT`, `NUMBER`, `SELECT`, `RELATION` и т. д.), а также `universalIdentifier` целевого объекта.
+
+## Пользовательский путь вывода
+
+Используйте флаг `--path`, чтобы поместить сгенерированный файл в пользовательское расположение:
+
+```bash filename="Terminal"
+yarn twenty dev:add logicFunction --path src/custom-folder
+```

packages/twenty-docs/l/ru/developers/extend/apps/getting-started/troubleshooting.mdx

@@ -0,0 +1,14 @@
+---
+title: Устранение неполадок
+description: Распространенные проблемы при первом запуске — Docker, версия Node, Yarn, зависимости.
+icon: wrench
+---
+
+* **Ошибки Docker** — убедитесь, что Docker Desktop (или демон) запущен перед выполнением `yarn twenty docker:start`. Сообщение об ошибке укажет правильную команду запуска для вашей ОС.
+* **Неверная версия Node** — требуется 24.5+ (`engines.node: ^24.5.0`). Проверьте с помощью `node -v`.
+* **Отсутствует Yarn 4** — выполните `corepack enable`.
+* **Зависимости повреждены** — `rm -rf node_modules && yarn install`.
+* **Ошибки `twenty-sdk` после обновления до v2.8.0** — он был перенесен из `dependencies` в `devDependencies` в v2.8.0. См. [Структура проекта → Зависимости](/l/ru/developers/extend/apps/getting-started/project-structure#dependencies).
+* **`twenty dev:build` предупреждает о `twenty-client-sdk` в разделе `dependencies`** — он предоставляется Twenty во время выполнения, поэтому его следует перенести в `devDependencies` рядом с `twenty-sdk`. См. [Структура проекта → Зависимости](/l/ru/developers/extend/apps/getting-started/project-structure#dependencies).
+
+Застряли? Попросите помощи на [Discord-сервере Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).

packages/twenty-docs/l/ru/developers/extend/apps/layout/command-menu-items.mdx

@@ -0,0 +1,118 @@
+---
+title: Элементы меню команд
+description: Отображайте фронтенд-компоненты как быстрые действия и элементы командного меню (Cmd+K) с помощью `defineCommandMenuItem`.
+icon: terminal
+---
+
+**Элемент командного меню** — это мост между пользователем и [фронтенд-компонентом](/l/ru/developers/extend/apps/layout/front-components). Он регистрирует компонент в командном меню Twenty (Cmd+K) и, при необходимости, как закреплённую кнопку быстрого действия в правом верхнем углу страницы.
+
+```ts src/command-menu-items/open-dashboard.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  label: 'Open Dashboard',
+  shortLabel: 'Dashboard',
+  isPinned: true,
+  availabilityType: 'GLOBAL',
+  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+});
+```
+
+## Поля конфигурации
+
+| Поле                                    | Обязательно | Описание                                                                                                                                                                                                                                                                                               |
+| --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `universalIdentifier`                   | Да          | Стабильный уникальный идентификатор для команды                                                                                                                                                                                                                                                        |
+| `label`                                 | Да          | Полная метка, отображаемая в меню команд (Cmd+K)                                                                                                                                                                                                                                                       |
+| `frontComponentUniversalIdentifier`     | Да          | `universalIdentifier` фронтенд-компонента, который открывается этой командой                                                                                                                                                                                                                           |
+| `shortLabel`                            | Нет         | Короткая метка, отображаемая на закреплённой кнопке быстрого действия                                                                                                                                                                                                                                  |
+| `icon`                                  | Нет         | **Устарело** — игнорируется в пользу значка приложения; при установке этого параметра сборка выводит предупреждение                                                                                                                                                                                    |
+| `isPinned`                              | Нет         | При значении `true` показывает команду как кнопку быстрого действия в правом верхнем углу страницы                                                                                                                                                                                                     |
+| `availabilityType`                      | Нет         | Определяет, где отображается команда: `'GLOBAL'` (доступна всегда), `'GLOBAL_OBJECT_CONTEXT'` (только на страницах с объектным контекстом — индексные страницы и карточки записей), `'RECORD_SELECTION'` (только при выборе записей) или `'FALLBACK'` (показывается, когда другие команды не подходят) |
+| `availabilityObjectUniversalIdentifier` | Нет         | Ограничивает команду страницами определённого типа объектов (например, только для записей Company)                                                                                                                                                                                                     |
+| `conditionalAvailabilityExpression`     | Нет         | Логическое выражение, которое динамически управляет видимостью (см. ниже)                                                                                                                                                                                                                              |
+
+## Команды без интерфейса
+
+Элемент командного меню в паре с [фронтенд-компонентом без интерфейса](/l/ru/developers/extend/apps/layout/front-components#headless-vs-non-headless) — идиоматичный способ предоставить действие в один клик: выполнить код, перейти или подтвердить и выполнить. Страница Front Components описывает [SDK Command components](/l/ru/developers/extend/apps/layout/front-components#sdk-command-components) (`Command`, `CommandLink`, `CommandModal`, `CommandOpenSidePanelPage`), которые реализуют шаблон «действие и размонтирование».
+
+Типичный сценарий: headless-компонент рендерит `<Command execute={...} />` (см. [полный пример](/l/ru/developers/extend/apps/layout/front-components#sdk-command-components)), и пункт меню команды указывает на него:
+
+```ts src/command-menu-items/run-action.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
+  label: 'Run my action',
+  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
+});
+```
+
+## Выражения условной доступности
+
+Поле `conditionalAvailabilityExpression` позволяет управлять видимостью команды в зависимости от текущего контекста страницы. Импортируйте типизированные переменные и операторы из `twenty-sdk`, чтобы составлять выражения:
+
+```ts src/command-menu-items/bulk-update.command-menu-item.ts
+import {
+  defineCommandMenuItem,
+  objectPermissions,
+  everyEquals,
+} from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: '...',
+  label: 'Bulk Update',
+  availabilityType: 'RECORD_SELECTION',
+  frontComponentUniversalIdentifier: '...',
+  conditionalAvailabilityExpression: everyEquals(
+    objectPermissions,
+    'canUpdateObjectRecords',
+    true,
+  ),
+});
+```
+
+<Note>
+  `RECORD_SELECTION` уже подразумевает, что есть выбранные записи — используйте `numberOfSelectedRecords` только для конкретных количеств (например, `>= 2`).
+</Note>
+
+### Переменные контекста
+
+Они представляют текущее состояние страницы:
+
+| Переменная                     | Тип       | Описание                                                                 |
+| ------------------------------ | --------- | ------------------------------------------------------------------------ |
+| `pageType`                     | `string`  | Текущий тип страницы (например, `'RecordIndexPage'`, `'RecordShowPage'`) |
+| `isInSidePanel`                | `boolean` | Указывает, рендерится ли компонент в боковой панели                      |
+| `numberOfSelectedRecords`      | `number`  | Количество выбранных в данный момент записей                             |
+| `isSelectAll`                  | `boolean` | Активен ли режим "выбрать все"                                           |
+| `selectedRecords`              | `array`   | Объекты выбранных записей                                                |
+| `favoriteRecordIds`            | `array`   | ID избранных записей                                                     |
+| `objectPermissions`            | `object`  | Разрешения для текущего типа объекта                                     |
+| `targetObjectReadPermissions`  | `object`  | Права на чтение для целевого объекта                                     |
+| `targetObjectWritePermissions` | `object`  | Права на запись для целевого объекта                                     |
+| `featureFlags`                 | `object`  | Активные флаги функций                                                   |
+| `objectMetadataItem`           | `object`  | Метаданные текущего типа объекта                                         |
+| `hasAnySoftDeleteFilterOnView` | `boolean` | Есть ли у текущего представления фильтр мягкого удаления                 |
+
+### Операторы
+
+Комбинируйте переменные в логические выражения:
+
+| Оператор                            | Описание                                                                  |
+| ----------------------------------- | ------------------------------------------------------------------------- |
+| `isDefined(value)`                  | `true`, если значение не null/undefined                                   |
+| `isNonEmptyString(value)`           | `true`, если значение — непустая строка                                   |
+| `includes(array, value)`            | `true`, если массив содержит значение                                     |
+| `includesEvery(array, prop, value)` | `true`, если свойство каждого элемента включает значение                  |
+| `every(array, prop)`                | `true`, если свойство истинно для каждого элемента                        |
+| `everyDefined(array, prop)`         | `true`, если свойство определено у каждого элемента                       |
+| `everyEquals(array, prop, value)`   | `true`, если свойство равно значению у каждого элемента                   |
+| `some(array, prop)`                 | `true`, если свойство истинно хотя бы у одного элемента                   |
+| `someDefined(array, prop)`          | `true`, если свойство определено хотя бы у одного элемента                |
+| `someEquals(array, prop, value)`    | `true`, если свойство равно значению хотя бы у одного элемента            |
+| `someNonEmptyString(array, prop)`   | `true`, если свойство является непустой строкой хотя бы у одного элемента |
+| `none(array, prop)`                 | `true`, если свойство ложно для каждого элемента                          |
+| `noneDefined(array, prop)`          | `true`, если свойство не определено ни у одного элемента                  |
+| `noneEquals(array, prop, value)`    | `true`, если свойство не равно значению ни у одного элемента              |

packages/twenty-docs/l/ru/developers/extend/apps/layout/front-components.mdx

@@ -0,0 +1,849 @@
+---
+title: Компоненты фронтенда
+description: Создавайте компоненты React, которые отображаются внутри интерфейса Twenty в изолированной песочнице.
+icon: window-maximize
+---
+
+Фронтенд-компоненты — это компоненты React, которые отображаются непосредственно внутри интерфейса Twenty. Они выполняются в **изолированном Web Worker** с использованием Remote DOM — ваш код исполняется внутри изолированного iframe с непрозрачным источником (opaque-origin), но его UI всё равно нативно рендерится на странице, а не ограничивается этим iframe.
+
+<Warning>
+Конструкции передней части все еще активно развиваются. Ваш код запускается с частичным DOM, а не с реальной страницей браузера, так что использование расширенного кода может привести к ошибке, часто молчанию. См. [Текущие ограничения](#current-limitations).
+</Warning>
+
+## Где можно использовать фронт-компоненты
+
+Фронт-компоненты могут отображаться в трёх местах внутри Twenty:
+
+* **Боковая панель** — фронт-компоненты с интерфейсом открываются в правой боковой панели. Это поведение по умолчанию, когда фронт-компонент запускается из меню команд.
+* **Виджеты (дашборды и страницы записей)** — фронт-компоненты можно встраивать как виджеты в [макеты страниц](/l/ru/developers/extend/apps/layout/page-layouts). При настройке дашборда или макета страницы записи пользователи могут добавить виджет фронт-компонента.
+* **Настройки приложения (App settings)** — если определить фронт-компонент с помощью [`defineSettingsFrontComponent()`](#custom-settings-component), он будет отображаться как раздел на вкладке **Settings** приложения, заменяя стандартный интерфейс настройки переменных.
+
+Сам по себе фронт-компонент недоступен из интерфейса — его нужно *сделать доступным*. Сделать это можно тремя способами:
+
+* **Связать его с [элементом командного меню](/l/ru/developers/extend/apps/layout/command-menu-items)** — регистрирует его в командном меню (Cmd+K) и, при необходимости, как закреплённое быстрое действие.
+* **Встроить его как виджет в [макет страницы](/l/ru/developers/extend/apps/layout/page-layouts)** — размещает его на странице деталей записи или на дашборде.
+* **Определить его с помощью [`defineSettingsFrontComponent()`](#custom-settings-component)** — отображает его как раздел на вкладке **Settings** приложения, заменяя стандартный интерфейс настройки переменных.
+
+## Простой пример
+
+Самый быстрый способ увидеть фронт-компонент в действии — связать его с [`defineCommandMenuItem`](/l/ru/developers/extend/apps/layout/command-menu-items), чтобы он появился как кнопка быстрого действия в правом верхнем углу страницы:
+
+```tsx src/front-components/hello-world.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+
+const HelloWorld = () => {
+  return (
+    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
+      <h1>Hello from my app!</h1>
+      <p>This component renders inside Twenty.</p>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+  name: 'hello-world',
+  description: 'A simple front component',
+  component: HelloWorld,
+});
+```
+
+```ts src/command-menu-items/hello-world.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
+  shortLabel: 'Hello',
+  label: 'Hello World',
+  isPinned: true,
+  availabilityType: 'GLOBAL',
+  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+});
+```
+
+После синхронизации с помощью `yarn twenty dev` (или однократного запуска `yarn twenty apply`) быстрое действие появится в правом верхнем углу страницы:
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/quick-action.png" alt="Кнопка быстрого действия в правом верхнем углу" />
+</div>
+
+Нажмите её, чтобы отобразить компонент инлайн.
+
+## Поля конфигурации
+
+| Поле                  | Обязательно | Описание                                                                                           |
+| --------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
+| `universalIdentifier` | Да          | Стабильный уникальный идентификатор для этого компонента                                           |
+| `component`           | Да          | Функция компонента React                                                                           |
+| `name`                | Нет         | Отображаемое имя                                                                                   |
+| `description`         | Нет         | Описание того, что делает компонент                                                                |
+| `isHeadless`          | Нет         | Установите значение `true`, если у компонента нет видимого пользовательского интерфейса (см. ниже) |
+
+## Размещение фронт-компонента на странице
+
+Помимо команд, вы можете встроить фронт-компонент непосредственно на страницу записи, добавив его как виджет в **макет страницы**. См. [макеты страниц](/l/ru/developers/extend/apps/layout/page-layouts) для подробностей.
+
+## Пользовательский компонент настроек
+
+Чтобы заменить автоматически сгенерированный интерфейс настройки переменных на вкладке **Settings** вашего приложения собственным компонентом, определите его с помощью `defineSettingsFrontComponent` вместо `defineFrontComponent`. Он использует те же [поля конфигурации](#configuration-fields) (за исключением `isHeadless`, которое не принимается, поскольку компонент настроек всегда отрисовывает видимый интерфейс пользователя) и дополнительно помечает компонент как интерфейс настроек приложения.
+
+Компонент отрисовывается как раздел **внутри** вкладки Settings, а не как замена всей вкладки. Управляемые системой Twenty разделы — автообновление, App URL и подключения — всегда отрисовываются над ним и не могут быть переопределены приложением.
+
+```tsx src/front-components/app-settings.tsx
+import { defineSettingsFrontComponent } from 'twenty-sdk/define';
+
+const AppSettings = () => {
+  return (
+    <div style={{ padding: '20px' }}>
+      <h2>My app settings</h2>
+      {/* render your own configuration UI here */}
+    </div>
+  );
+};
+
+export default defineSettingsFrontComponent({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'app-settings',
+  description: "Custom UI for the app's Settings tab",
+  component: AppSettings,
+});
+```
+
+Для каждого приложения допускается только один фронт-компонент настроек; объявление более одного приведет к ошибке сборки. Если он присутствует, вкладка **Settings** приложения отрисовывает этот компонент вместо стандартного интерфейса конфигурации переменных.
+
+## Headless и non-headless
+
+Фронт-компоненты поддерживают два режима отображения, управляемых опцией `isHeadless`:
+
+**Non-headless (по умолчанию)** — компонент отображает видимый интерфейс. При запуске из меню команд он открывается в боковой панели. Это поведение по умолчанию, когда `isHeadless` имеет значение `false` или опущен.
+
+**Headless (`isHeadless: true`)** — компонент монтируется невидимо в фоновом режиме. Он не открывает боковую панель. Компоненты headless предназначены для действий, которые выполняют логику и затем размонтируются — например, запуск асинхронной задачи, переход на страницу или показ модального окна подтверждения. Они естественно сочетаются с компонентами SDK Command, описанными ниже.
+
+```tsx src/front-components/sync-tracker.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useSelectedRecordIds, enqueueSnackbar } from 'twenty-sdk/front-component';
+import { useEffect } from 'react';
+
+const SyncTracker = () => {
+  const [recordId] = useSelectedRecordIds();
+
+  useEffect(() => {
+    enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
+  }, [recordId]);
+
+  return null;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'sync-tracker',
+  description: 'Tracks record views silently',
+  isHeadless: true,
+  component: SyncTracker,
+});
+```
+
+Поскольку компонент возвращает `null`, Twenty пропускает рендеринг контейнера для него — в макете не появляется пустое место. Компонент по-прежнему имеет доступ ко всем хукам и API взаимодействия с хостом.
+
+## Компоненты SDK Command
+
+Пакет `twenty-sdk` предоставляет четыре вспомогательных компонента Command, предназначенных для headless фронт-компонентов. Каждый компонент выполняет действие при монтировании, обрабатывает ошибки, показывая уведомление snackbar, и автоматически размонтирует фронт-компонент по завершении.
+
+Импортируйте их из `twenty-sdk/front-component`:
+
+* **`Command`** — запускает асинхронный колбэк через проп `execute`.
+* **`CommandLink`** — переходит по пути внутри приложения. Пропы: `to`, `params`, `queryParams`, `options`.
+* **`CommandModal`** — открывает модальное окно подтверждения. Если пользователь подтвердит, выполняет колбэк `execute`. Пропы: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
+* **`CommandOpenSidePanelPage`** — открывает страницу боковой панели. Пропсы зависят от `page` — например, `ViewRecord` принимает `recordId` + `objectNameSingular` (а также необязательный id `tab`, чтобы открыть запись на определённой вкладке), другие страницы принимают `pageTitle` + `pageIcon`.
+
+Полный пример headless фронт-компонента, использующего `Command` для запуска действия из меню команд:
+
+```tsx src/front-components/run-action.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { Command } from 'twenty-sdk/front-component';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const RunAction = () => {
+  const execute = async () => {
+    const client = new CoreApiClient();
+
+    await client.mutation({
+      createTask: {
+        __args: { data: { title: 'Created by my app' } },
+        id: true,
+      },
+    });
+  };
+
+  return <Command execute={execute} />;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
+  name: 'run-action',
+  description: 'Creates a task from the command menu',
+  component: RunAction,
+  isHeadless: true,
+});
+```
+
+```ts src/command-menu-items/run-action.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
+  label: 'Run my action',
+  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
+});
+```
+
+А также пример с использованием `CommandModal` для запроса подтверждения перед выполнением:
+
+```tsx src/front-components/delete-draft.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { CommandModal } from 'twenty-sdk/front-component';
+
+const DeleteDraft = () => {
+  const execute = async () => {
+    // perform the deletion
+  };
+
+  return (
+    <CommandModal
+      title="Delete draft?"
+      subtitle="This action cannot be undone."
+      execute={execute}
+      confirmButtonText="Delete"
+      confirmButtonAccent="danger"
+    />
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'a7b8c9d0-e1f2-3456-abcd-567890123456',
+  name: 'delete-draft',
+  description: 'Deletes a draft with confirmation',
+  component: DeleteDraft,
+  isHeadless: true,
+});
+```
+
+И пример использования `CommandOpenSidePanelPage` для открытия текущей записи в боковой панели на определённой вкладке. `tab` — это id вкладки в макете страницы (в стандартных макетах используются id вроде `company-tab-emails` или `company-tab-timeline`; в пользовательских макетах используется собственный id вкладки). Если такого id нет в макете записи, откроется вкладка по умолчанию:
+
+```tsx src/front-components/open-company-emails.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import {
+  CommandOpenSidePanelPage,
+  SidePanelPages,
+  useSelectedRecordIds,
+} from 'twenty-sdk/front-component';
+
+const OpenCompanyEmails = () => {
+  const selectedRecordIds = useSelectedRecordIds();
+  const recordId = selectedRecordIds.length === 1 ? selectedRecordIds[0] : null;
+
+  if (!recordId) {
+    return null;
+  }
+
+  return (
+    <CommandOpenSidePanelPage
+      page={SidePanelPages.ViewRecord}
+      recordId={recordId}
+      objectNameSingular="company"
+      tab="company-tab-emails"
+      resetNavigationStack={false}
+    />
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'b8c9d0e1-f2a3-4567-bcde-678901234567',
+  name: 'open-company-emails',
+  description: 'Opens the current company on its Emails tab',
+  component: OpenCompanyEmails,
+  isHeadless: true,
+});
+```
+
+## Вызов логической функции
+
+Front-компоненты выполняются в браузере в Web Worker, изолированном внутри iframe с непрозрачным источником (opaque-origin), в то время как [логические функции](/l/ru/developers/extend/apps/logic/logic-functions) выполняются на стороне сервера. Между ними нет прямого внутрипроцессного вызова — вместо этого front-компонент обращается к логической функции по HTTP.
+
+Логическая функция, объявленная с `httpRouteTriggerSettings`, доступна по HTTP по своему пути маршрута. `RestApiClient` рассматривает пути, начинающиеся с `/s/`, как маршруты приложения, разрешает их в URL, по которому обслуживаются ваши функции, и аутентифицирует их с помощью `TWENTY_APP_ACCESS_TOKEN`.
+
+> **В Twenty Cloud логические функции с HTTP-триггером обслуживаются на выделенном домене для каждого рабочего пространства** по адресу `https://\<your-workspace-subdomain>.withtwenty.com\<path>`. Для внешних вызовов скопируйте точный URL из настроек **HTTP trigger** функции или на вкладке **Settings** приложения.
+
+Безголовый front-компонент может выполнить вызов при монтировании через компонент `Command`, а затем автоматически размонтироваться:
+
+```tsx src/front-components/sync-prs.tsx
+import { RestApiClient } from 'twenty-client-sdk/rest';
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { Command } from 'twenty-sdk/front-component';
+
+const SyncPrs = () => {
+  const execute = async () => {
+    await new RestApiClient().post('/s/github/fetch-prs', {
+      owner: 'twentyhq',
+      repo: 'twenty',
+    });
+  };
+
+  return <Command execute={execute} />;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'sync-prs',
+  description: 'Triggers the fetch-prs logic function',
+  isHeadless: true,
+  component: SyncPrs,
+});
+```
+
+Путь, передаваемый в `RestApiClient`, — это значение `httpRouteTriggerSettings.path` логической функции с префиксом `/s`. Сохраните `isAuthRequired: true`; `TWENTY_APP_ACCESS_TOKEN`, который Twenty выпускает для вашего компонента, аутентифицирует запрос:
+
+```ts src/logic-functions/fetch-prs.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import type { RoutePayload } from 'twenty-sdk/logic-function';
+
+const handler = async (event: RoutePayload) => {
+  const { owner, repo } = (event.body ?? {}) as { owner: string; repo: string };
+  // ...fetch from GitHub and persist records...
+  return { ok: true };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '...',
+  name: 'fetch-prs',
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/github/fetch-prs',
+    httpMethod: 'POST',
+    isAuthRequired: true,
+  },
+});
+```
+
+<Note>
+`TWENTY_APP_ACCESS_TOKEN` внедряется автоматически — см. [переменные приложения](#application-variables). Поскольку секретные переменные приложения никогда не раскрываются front-компонентам, храните ключи API и другую конфиденциальную логику в логической функции, а не во front-компоненте.
+</Note>
+
+### Вызов REST API Twenty
+
+Чтобы вызывать HTTP-маршруты приложения или читать и изменять записи Twenty из фронт-компонента, используйте `RestApiClient` из `twenty-client-sdk/rest`. Он отправляет пути вида `/s/...` на базовый URL функций вашего рабочего пространства, а все остальные пути, включая `/rest/...`, — на `TWENTY_API_URL`.
+
+Он всегда действует от имени человека, просматривающего страницу. `runAs: 'application'` — это параметр только для логической функции: компонент никогда не получает собственный токен вашего приложения, поэтому его запрос здесь вызывает ошибку. Поместите работу, требующую собственного доступа приложения, за логическую функцию и вызывайте вместо этого её.
+
+| Метод                             | Описание                                                          |
+| --------------------------------- | ----------------------------------------------------------------- |
+| `get(path, options?)`             | Отправляет запрос `GET`                                           |
+| `post(path, body?, options?)`     | Отправляет запрос `POST`                                          |
+| `put(path, body?, options?)`      | Отправляет запрос `PUT`                                           |
+| `patch(path, body?, options?)`    | Отправляет запрос `PATCH`                                         |
+| `delete(path, options?)`          | Отправляет запрос `DELETE`                                        |
+| `request(method, path, options?)` | Универсальный запрос с любым HTTP-методом                         |
+| `resolveUrl(path, options?)`      | Разрешает путь в его полный URL без отправки запроса (для ссылок) |
+
+В `options` принимаются `headers`, `query` (объект с параметрами строки запроса; значения, равные null или undefined, пропускаются) и `AbortSignal` через `signal`. Объект `body`, не являющийся `FormData`, автоматически сериализуется в JSON. При получении `401` клиент один раз обновляет токен доступа через хост и повторяет запрос.
+
+Базовый URL и токен по умолчанию берутся из окружения. При необходимости передавайте переопределения в конструктор — например, в тестах:
+
+```ts
+const client = new RestApiClient({
+  baseUrl: 'https://myworkspace.twenty.com',
+  token: 'my-token',
+});
+```
+
+Неудачные запросы выбрасывают `RestApiClientError`, который содержит `status`, `statusText`, `url` и распарсенное `body`:
+
+```tsx
+import { RestApiClient, RestApiClientError } from 'twenty-client-sdk/rest';
+
+const client = new RestApiClient();
+
+try {
+  const people = await client.get('/rest/people', {
+    query: { limit: 10 },
+  });
+} catch (error) {
+  if (error instanceof RestApiClientError) {
+    console.error(error.status, error.body);
+  }
+}
+```
+
+## Доступ к контексту времени выполнения
+
+Внутри вашего компонента используйте хуки SDK для доступа к текущему пользователю, записи и экземпляру компонента:
+
+```tsx src/front-components/record-info.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import {
+  useUserId,
+  useSelectedRecordIds,
+  useFrontComponentId,
+} from 'twenty-sdk/front-component';
+
+const RecordInfo = () => {
+  const userId = useUserId();
+  const [recordId] = useSelectedRecordIds();
+  const componentId = useFrontComponentId();
+
+  return (
+    <div>
+      <p>User: {userId}</p>
+      <p>Record: {recordId ?? 'No record context'}</p>
+      <p>Component: {componentId}</p>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
+  name: 'record-info',
+  component: RecordInfo,
+});
+```
+
+Доступные хуки:
+
+| Хук                                           | Возвращает             | Описание                                                                                                  |
+| --------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `useUserId()`                                 | `string` или `null`    | ID текущего пользователя                                                                                  |
+| `useSelectedRecordIds()`                      | `string[]`             | Все выбранные идентификаторы записей (пустой массив, если ничего не выбрано)                              |
+| `useRecordId()`                               | `string` или `null`    | **Устарело.** Используйте `useSelectedRecordIds()` вместо этого                                           |
+| `useFrontComponentId()`                       | `string`               | ID этого экземпляра компонента                                                                            |
+| `useTimelineActivityId()`                     | `string` или `null`    | Идентификатор текущего действия на временной шкале при рендеринге пользовательской строки временной шкалы |
+| `useColorScheme()`                            | `'light'` или `'dark'` | Активная цветовая схема интерфейса хоста (значение `System` уже определено)                               |
+| `useFrontComponentExecutionContext(selector)` | различается            | Доступ к полному контексту выполнения с помощью функции-селектора                                         |
+
+## Переменные приложения
+
+Переменные приложения, определенные в [`defineApplication()`](/l/ru/developers/extend/apps/config/application) с `isSecret: false`, доступны внутри фронтенд-компонентов через утилиту `getApplicationVariable`:
+
+```tsx src/front-components/greeting.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { getApplicationVariable } from 'twenty-sdk/front-component';
+
+const Greeting = () => {
+  const recipientName = getApplicationVariable('DEFAULT_RECIPIENT_NAME') ?? 'World';
+
+  return <p>Hello, {recipientName}!</p>;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'greeting',
+  component: Greeting,
+});
+```
+
+<Warning>
+Секретные переменные (`isSecret: true`) **не** доступны фронтенд-компонентам. Они доступны только в [логических функциях](/l/ru/developers/extend/apps/logic/logic-functions), которые выполняются на стороне сервера. Это предотвращает отправку в браузер конфиденциальных значений, таких как ключи API.
+</Warning>
+
+`getApplicationVariable` всегда возвращает **строку** (или `undefined`), независимо от объявленного для переменной `type`. Строка сериализуется единообразно в зависимости от типа (логические значения как `"true"` / `"false"`, числа как десятичные строки, массивы / объекты как JSON) в том же формате, который используется для логической функции `process.env` — разбирайте её самостоятельно (`Number(...)`, `JSON.parse(...)`, `=== 'true'`). См. [типы переменных](/l/ru/developers/extend/apps/config/application#variable-types).
+
+Следующие системные переменные всегда доступны через `process.env`:
+
+| Переменная                | Описание                                                                                                                                                                                                                            |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TWENTY_API_URL`          | Базовый URL основного API Twenty                                                                                                                                                                                                    |
+| `TWENTY_APP_ACCESS_TOKEN` | Кратковременный токен, область действия которого ограничена пересечением роли вошедшего в систему пользователя и роли вашего приложения, поэтому компонент никогда не сможет сделать больше, чем человек, который его просматривает |
+
+### `TWENTY_FUNCTIONS_URL`
+
+Twenty также внедряет `TWENTY_FUNCTIONS_URL` во фронт-компоненты и логические функции: это базовый URL, по которому обслуживаются HTTP-триггерные логические функции вашего приложения.
+
+Он существует, потому что этот URL не всегда совпадает с самим сервером Twenty. В Twenty Cloud маршруты приложения обслуживаются на выделенном домене для каждого рабочего пространства (`https://\<your-workspace-subdomain>.withtwenty.com` или основном общедоступном домене приложения, если он настроен), чтобы ответы, сформированные приложением, отдавались с изолированного источника, а не с источника приложения Twenty. Самостоятельно развёрнутые и локальные экземпляры обслуживают маршруты приложения с префиксом `/s` на самом сервере и могут вовсе не задавать эту переменную. Поскольку базовый URL различается для каждого рабочего пространства и экземпляра, ваш код не может жёстко прописать его — сервер внедряет правильное значение во время выполнения.
+
+Вам редко нужно читать его напрямую. Вызывайте свои маршруты через `RestApiClient` с путём, начинающимся с `/s/`, и клиент разрешит URL за вас: он убирает префикс `/s` и обращается к `TWENTY_FUNCTIONS_URL`, а если переменная не задана, использует `\<TWENTY_API_URL>/s`. Используйте `resolveUrl('/s/\<path>')`, чтобы получить абсолютный URL без отправки запроса, например для ссылки. Читайте переменную напрямую только при ручной сборке URL:
+
+```ts
+const routeUrl = `${process.env.TWENTY_FUNCTIONS_URL || `${process.env.TWENTY_API_URL}/s`}/documents/generate`;
+```
+
+## API взаимодействия с хостом
+
+Компоненты фронтенда могут вызывать навигацию, модальные окна и уведомления с помощью функций из `twenty-sdk`:
+
+| Функция                                            | Описание                                                                                                                                                                                |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `navigate(to, params?, queryParams?, options?)`    | Перейти на страницу в приложении                                                                                                                                                        |
+| `openSidePanelPage(params)`                        | Открыть боковую панель                                                                                                                                                                  |
+| `closeSidePanel()`                                 | Закрыть боковую панель                                                                                                                                                                  |
+| `openCommandConfirmationModal(params)`             | Показать диалог подтверждения                                                                                                                                                           |
+| `enqueueSnackbar(params)`                          | Показать всплывающее уведомление                                                                                                                                                        |
+| `unmountFrontComponent()`                          | Размонтировать компонент                                                                                                                                                                |
+| `updateProgress(progress)`                         | Обновить индикатор прогресса                                                                                                                                                            |
+| `uploadFile(file, { fieldMetadataId, fileName? })` | Загрузите `Blob` в поле FILES; возвращает `{ status: 'uploaded', file: { fileId, path, url, size, mimeType } }` или `{ status: 'failed', reason: 'invalid-params' \| 'upload-failed' }` |
+
+Пример, который использует API хоста для показа snackbar и закрытия боковой панели после завершения действия:
+
+```tsx src/front-components/archive-record.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { enqueueSnackbar, closeSidePanel, useSelectedRecordIds } from 'twenty-sdk/front-component';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const ArchiveRecord = () => {
+  const [recordId] = useSelectedRecordIds();
+
+  const handleArchive = async () => {
+    const client = new CoreApiClient();
+
+    await client.mutation({
+      updateTask: {
+        __args: { id: recordId, data: { status: 'ARCHIVED' } },
+        id: true,
+      },
+    });
+
+    await enqueueSnackbar({
+      message: 'Record archived',
+      variant: 'success',
+    });
+
+    await closeSidePanel();
+  };
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <p>Archive this record?</p>
+      <button onClick={handleArchive}>Archive</button>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
+  name: 'archive-record',
+  description: 'Archives the current record',
+  component: ArchiveRecord,
+});
+```
+
+### Хранилище
+
+`localStorage` и `sessionStorage` работают так же, как на обычной странице, с использованием стандартного синхронного API. Ваши ключи ограничены рамками установки приложения и учетной записью вошедшего пользователя: ни одно другое приложение не может их прочитать, а другой пользователь, вошедший в тот же браузер, начинает с пустого хранилища. Значения, записанные в `localStorage`, остаются на устройстве при перезагрузках; `sessionStorage` действует в течение браузерной сессии.
+
+```tsx src/front-components/note-draft.tsx
+import { useState } from 'react';
+import { defineFrontComponent } from 'twenty-sdk/define';
+
+const NoteDraft = () => {
+  const [draft, setDraft] = useState(() => localStorage.getItem('draft') ?? '');
+
+  const handleChange = (nextDraft: string) => {
+    setDraft(nextDraft);
+    localStorage.setItem('draft', nextDraft);
+  };
+
+  return (
+    <textarea value={draft} onChange={(event) => handleChange(event.target.value)} />
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'd0e1f2a3-b4c5-6789-def0-890123456789',
+  name: 'note-draft',
+  description: 'Keeps an unsaved note on this device',
+  component: NoteDraft,
+});
+```
+
+Twenty хранит значения от имени вашего приложения, поэтому запись применяется локально сразу же и сохраняется в фоновом режиме. Операции чтения никогда не блокируются ожиданием хоста. Ничто не синхронизируется: значения не следуют за пользователем в другой браузер или на другой компьютер, поэтому используйте [хранилище ключ-значение](/l/ru/developers/extend/apps/logic/key-value-store) логической функции для всего, что должно пережить смену устройства.
+
+Записи ограничены, и для каждого лимита считаются символы, а не байты: ключи могут содержать не более 512 символов, одно значение — не более 262144 символов, а каждое хранилище — не более 1048576 символов на приложение и пользователя. Запись, нарушающая лимит, выбрасывает `QuotaExceededError`, как и браузерный API.
+
+### Работа с несколькими записями
+
+Используйте `useSelectedRecordIds()` для обработки нескольких выбранных записей. Это полезно для массовых операций:
+
+```tsx src/front-components/bulk-export.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useSelectedRecordIds } from 'twenty-sdk/front-component';
+import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const BulkExport = () => {
+  const selectedRecordIds = useSelectedRecordIds();
+
+  const handleExport = async () => {
+    const client = new CoreApiClient();
+
+    for (const recordId of selectedRecordIds) {
+      await client.mutation({
+        updateTask: {
+          __args: { id: recordId, data: { exported: true } },
+          id: true,
+        },
+      });
+    }
+
+    await enqueueSnackbar({
+      message: `Exported ${selectedRecordIds.length} records`,
+      variant: 'success',
+    });
+
+    await closeSidePanel();
+  };
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <p>Export {selectedRecordIds.length} selected record(s)?</p>
+      <button onClick={handleExport}>Export</button>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
+  name: 'bulk-export',
+  description: 'Export selected records',
+  component: BulkExport,
+});
+```
+
+Сделайте его доступным через [элемент командного меню](/l/ru/developers/extend/apps/layout/command-menu-items), доступный только при выборе записей:
+
+```ts src/command-menu-items/bulk-export.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
+  label: 'Bulk Export',
+  availabilityType: 'RECORD_SELECTION',
+  frontComponentUniversalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
+});
+```
+
+## Публичные ресурсы
+
+Компоненты фронтенда могут получать доступ к файлам из каталога приложения `public/` с помощью `getPublicAssetUrl`:
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { getPublicAssetUrl } from 'twenty-sdk/utils';
+
+const Logo = () => <img src={getPublicAssetUrl('logo.png')} alt="Logo" />;
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'logo',
+  component: Logo,
+});
+```
+
+См. [раздел о публичных ресурсах](/l/ru/developers/extend/apps/config/public-assets) для подробностей.
+
+## Распространение зависимостей между фронт-компонентами
+
+По умолчанию, каждая передняя часть объединяет свою собственную копию импортируемых библиотек, так что приложение с пятью компонентами поставляет React пять раз. Объявление общих зависимостей в пакете вашего приложения. son\`, чтобы собрать эти библиотеки один раз и загрузить каждый компонент приложения из одного кэшированного файла:
+
+```json package.json
+{
+  "frontComponentSharedDependencies": ["react", "react-dom/client", "twenty-ui/input"]
+}
+```
+
+Затем каждый компонент импортирует его зависимости точно так же, как и раньше: ничего не изменяется в коде компонента:
+
+```tsx src/front-components/counter.tsx
+import { useState } from 'react';
+import { defineFrontComponent } from 'twenty-sdk/define';
+
+const Counter = () => {
+  const [count, setCount] = useState(0);
+
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'counter',
+  component: Counter,
+});
+```
+
+Несколько важных моментов:
+
+* **Один общий набор зависимостей для каждого приложения.** Пакет построен из зависимостей вашего приложения, так что вы сохраняете полный контроль над версиями, которые вы поставляете.
+* **Перечислите точные спецификаторы, которые вы импортируете.** `twenty-ui/input` и `twenty-ui/display` являются двумя записями; только имя пакета не содержит подпусков. Список `react` автоматически охватывает `react/jsx-runtime`.
+* **Поделиться `react-dom/client` вместе с `react`.** Каждый компонент проделывает `createRoot`, поэтому оставив его, значит каждый компонент всё ещё объединяет React DOM.
+* \*\*Набор кэширован. \* Он обслуживается под content-hash URL с длительным неизменяемым кэшем, так что загружается один раз и повторно используется всеми компонентами приложения до тех пор, пока одна из зависимостей не изменится.
+* **Компоненты, импортирующие ни один из общих пакетов никогда не загружают его.**
+
+## Стилизация
+
+Компоненты фронтенда поддерживают несколько подходов к стилизации. Вы можете использовать:
+
+* **Встроенные стили** — `style={{ color: 'red' }}`
+* **Twenty UI components** — собственная библиотека компонентов Twenty; см. раздел [Using Twenty UI components](#using-twenty-ui-components) ниже
+* **Emotion** — CSS-in-JS с `@emotion/react`
+* **Styled-components** — паттерны `styled.div`
+* **Tailwind CSS** — утилитарные классы
+* **Любая библиотека CSS-in-JS**, совместимая с React
+
+## Использование компонентов Twenty UI
+
+Twenty поставляет свою библиотеку компонентов как пакет [`twenty-ui`](https://www.npmjs.com/package/twenty-ui/v/1.0.0-alpha.1). Компоненты фронтенда могут использовать его для кнопок, тегов, статусных плашек, чипов, аватаров, иконок, типографики и токенов темы, которые автоматически соответствуют светлой и тёмной теме рабочего пространства.
+
+### Установка
+
+Добавьте пакет в своё приложение, зафиксировав его на версии, с которой поставляется ваш экземпляр Twenty:
+
+```bash
+yarn add twenty-ui@1.0.0-alpha.1
+```
+
+`twenty-ui` включается в ваш компонент фронтенда на этапе сборки, поэтому его достаточно иметь в зависимостях вашего приложения — во время выполнения ничего настраивать не нужно.
+
+### Импорт компонентов
+
+Импортируйте из соответствующего подпути, а не из корня пакета, чтобы в ваш бандл попали только те компоненты, которые вы используете:
+
+| Подпуть                     | Что экспортирует                                  |
+| --------------------------- | ------------------------------------------------- |
+| `twenty-ui/input`           | `Button` и элементы ввода формы                   |
+| `twenty-ui/data-display`    | `Tag`, `Status`, `Chip`, `Avatar` и другие        |
+| `twenty-ui/feedback`        | `Callout`, `Banner`, `Info` и другие              |
+| `twenty-ui/typography`      | `H1Title`, `H2Title`, `H3Title`, `Label` и другие |
+| `twenty-ui/icon`            | Компоненты `Icon*` (например, `IconCheck`)        |
+| `twenty-ui/theme-constants` | `ThemeProvider`, `themeCssVariables`              |
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { Status, Tag } from 'twenty-ui/data-display';
+import { Button } from 'twenty-ui/input';
+
+const StyledWidget = () => {
+  return (
+    <div style={{ padding: '16px', display: 'flex', gap: '8px' }}>
+      <Button title="Click me" onClick={() => alert('Clicked!')} />
+      <Tag text="Active" color="green" />
+      <Status color="green" text="Online" />
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
+  name: 'styled-widget',
+  component: StyledWidget,
+});
+```
+
+### Иконки
+
+Импортируйте отдельные иконки из `twenty-ui/icon`:
+
+```tsx
+import { IconBox, IconCheck } from 'twenty-ui/icon';
+```
+
+Каждая именованная иконка участвует в tree-shaking, поэтому импорт нескольких иконок почти не увеличит размер вашего бандла. Избегайте `IconsProvider`, `useIcons` и `iconsState` — они подключают весь набор иконок Tabler (несколько мегабайт).
+
+### Темизация и токены темы
+
+Компоненты Twenty UI автоматически подстраиваются под светлую и тёмную темы рабочего пространства — рендерер применяет активную цветовую схему на хосте, а компоненты вычисляют свои цвета относительно неё.
+
+Чтобы использовать те же дизайн‑токены в собственных встроенных стилях, вызовите хук `useTheme()`. Он возвращает токены темы Twenty (отступы, цвета, радиусы, шрифты), привязанные к активной теме, без необходимости настраивать `ThemeProvider` в вашем компоненте:
+
+```tsx
+import { useTheme } from 'twenty-ui/theme-constants';
+
+const Card = () => {
+  const theme = useTheme();
+
+  return (
+    <div
+      style={{
+        padding: theme.spacing[4],
+        background: theme.background.secondary,
+        color: theme.font.color.primary,
+      }}
+    >
+      Themed card
+    </div>
+  );
+};
+```
+
+Поскольку `useTheme()` — это хук, вы читаете токены внутри тела компонента, поэтому значения всегда соответствуют активной теме. Та же карта токенов также экспортируется как константа `themeCssVariables`, но в компонентах фронтенда предпочтительнее использовать `useTheme()` — модульная константа, разыменующая `themeCssVariables`, может быть `undefined`, пока извлекается манифест приложения.
+
+Чтобы явно разветвлять логику по активной цветовой схеме, считайте её с помощью `useColorScheme()` из `twenty-sdk/front-component`, который возвращает `'light'` или `'dark'`.
+
+## Нынешние ограничения
+
+Активно разрабатываются передние компоненты. Рендеринг, стилизация, обработка событий, измерение элементов и работа с хранилищем браузера работают хорошо. Все, что выходит *за рамки* этих возможностей (вызов DOM‑метода на ref, отслеживание изменения размеров элементов, порталирование за пределы вашего дерева), сегодня отсутствует или реализовано не полностью, и в большинстве случаев это тихо ломается: ни исключения, ни ошибки TypeScript, поскольку обвязка типизирована под полный DOM браузера.
+
+Если один из этих блоков вас, [откройте задачу](https://github.com/twentyhq/twenty/issues/new/choose), чтобы получить приоритет.
+
+### Макет и измерение
+
+Элементы могут измерять себя сами: хост отражает геометрию в песочницу, поэтому чтения выполняются локально, но могут отставать до одного кадра, а первое чтение никогда ранее не измеренного элемента возвращает нули. После записи выполните повторное чтение в колбэке `requestAnimationFrame` или в эффекте.
+
+| API                                                                                      | Что происходит                                                                                                                         |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `getBoundingClientRect()`, `offsetWidth`, `clientWidth`, `scrollWidth`, `offsetTop`, ... | Работают, из зеркала; присваивание `scrollTop` / `scrollLeft` не имеет эффекта                                                         |
+| `getClientRects()`, `window.matchMedia()`                                                | Бросает                                                                                                                                |
+| `window.innerWidth`, `innerHeight`, `devicePixelRatio`, `scrollX`, `scrollY`             | Работают, сообщая размеры области просмотра браузера; собственный размер вашего виджета — `document.body.clientWidth` / `clientHeight` |
+| `window.getComputedStyle()`                                                              | Возвращает только встроенные (inline) стили элемента и никогда не возвращает вычисленный хостом каскад                                 |
+| `ResizeObserver`, `IntersectionObserver`                                                 | `Справочная ошибка` (защита `typeof` делает работу)                                                                                    |
+| `MutationObserver`                                                                       | Работает, включая `subtree`, `attributeFilter`, старые значения и `takeRecords()`                                                      |
+
+Позиционирование с использованием `getBoundingClientRect` теперь работает, но всё, что отслеживает изменение размеров через `ResizeObserver` (recharts `ResponsiveContainer`, `autoUpdate` из Floating UI), по‑прежнему не работает. В любом случае отдавайте предпочтение CSS для верстки: ваша таблица стилей применяется к реальной странице, поэтому flexbox, grid, `aspect-ratio`, `clamp()` и `@container` работают как обычно, без задержки кадра.
+
+<Note>
+`requestAnimationFrame`, `fetch`, `setTimeout` и `queueMicrotask` работают без префикса `window.`. Только `window.requestAnimationFrame(...)` и брошенные друзья.
+</Note>
+
+### DOM access
+
+`ref` дает вам элемент песочницы, а не `HTMLElement`.
+
+| Что вы пишете                                                                                               | Что происходит                                                     | Использовать вместо                                                                                                                                                                  |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ref.current.focus()`, `.click()`, `.select()`, `.setSelectionRange()`, `.scrollIntoView()`, `video.play()` | Бросает                                                            | Контролируемые компоненты; читать значения из `event.target`                                                                                                                         |
+| `element.classList.add(...)`                                                                                | Броски (`classList` `undefined`)                                   | Создайте строку `className` самостоятельно                                                                                                                                           |
+| `document.createTreeWalker()`                                                                               | Бросает                                                            | `querySelector()` / `querySelectorAll()` и `getElementById()` работают; `getElementsByClassName()` тоже работает, но возвращает статическую коллекцию, а не «живой» `HTMLCollection` |
+| `document.activeElement`                                                                                    | Всегда `неопределённые`                                            | Отслеживать фокус с с помощью «onFocus» / «onBlur»                                                                                                                                   |
+| `canvas`                                                                                                    | Отображает ничего, без ошибок                                      | SVG или рисуйте вне экрана и показывайте результат в элементе `img`                                                                                                                  |
+| `createPortal(node, document.body)`                                                                         | Отображает ничего, в то время как «isConnected» сообщает об успехе | Наслоения в строке `position: absolute` или передайте библиотеке свой собственный элемент контейнера                                                                                 |
+
+Портал зазор поэтому всплывающие окна Radix, Headless UI, MUI и react-select не отображаются по умолчанию. Большинство из них принимают реквизиты контейнера; указывайте их на отображаемый элемент.
+
+### События
+
+События мыши, указателя, касания, перетаскивания, клавиатуры, фокуса, `input`/`change`/`submit`, `scroll`/`wheel`/`contextmenu` и `animationend`/`transitionend` передаются хосту, плюс несколько на элемент: `load`/`error` на `img`, буфер обмена и композиция на `input`/`textarea`, медиа на `video`/`audio`, `toggle` на `details`/`dialog`. Все остальное (`onAuxClick`, `onSelect`, `onInvalid`, `onReset`, `onAnimationStart`, захват указателя, `onLoad` у `img`) отбрасывается без предупреждения.
+
+`document.addEventListener()` и `window. ddEventListener()` регистрируется без ошибок и никогда не стреляет, поэтому перетаскивание останавливается, как только указатель покидает начатый элемент. `event.preventDefault()` тоже не пересекается; форма представления, `dragover`/`drop` и ссылки уже охраняются для вас.
+
+### Атрибуты и стиль
+
+Каждый элемент передает свои собственные свойства хостовому DOM (`href` на `a`, `src`/`alt` на `img`, `value`/`placeholder`/`disabled` на `input` и так далее), плюс общий набор на каждом элементе: `id`, `className`, `style`, `title`, `tabIndex`, `role`, `draggable` и любой атрибут `aria-*` / `data-*` (через дефис, поэтому `ariaLabel` отбрасывается). Всё, что за пределами тихо отбрасывается, поэтому выражать пользовательское состояние как `data-*`.
+
+CSS компонента, будь то из `import './styles.css'`, CSS-in-JS или элемента `style`, внедряется в `head` хостовой страницы **без области видимости**. Таким образом, имена классов конфликтуют с собственным Twenty's (префикс их), и никогда не пишут пустые `div { ... }` селекторы), а `@media` совпадает с вашим окном браузера вместо виджета (используйте `@container` с вашим собственным `container-type`). Встроенные свойства не затронуты.
+
+### Хранилище и сеть
+
+`localStorage` и `sessionStorage` предоставляются Twenty, а не браузером: компонент выполняется в воркере с непрозрачным источником (origin), поэтому хост хранит значения от имени вашего приложения. См. раздел [storage](#storage) для получения информации об области действия и ограничениях. IndexedDB, cookies, Cache API и `BroadcastChannel` по-прежнему недоступны. Чтобы сохранять состояние между устройствами, вызовите [логическую функцию](/l/ru/developers/extend/apps/logic/logic-functions) и используйте ее [хранилище ключ-значение](/l/ru/developers/extend/apps/logic/key-value-store).
+
+`fetch` работает с сохранениями:
+
+* Звонки к Twenty API и маршрутам вашего приложения проксируются узлом, поэтому предпочитайте [`RestApiClient`](#calling-the-twenty-rest-api). В случае проксируемых вызовов `AbortSignal` и другие опции `RequestInit` удаляются, и поддерживаются только тела `string` и `URLSearchParams`.
+* Другие источники оставляют песчаник с `Origin: null`, так что сторонний API отвечает, только если он посылает `Access-Control-Allow-Origin: *`. Вызовите его из логической функции.
+* `fetch('/rest/people')` никогда не совпадает с двадцать API, потому что песочница не имеет URL страницы для разрешения относительного пути.
+
+### Захват мультимедиа
+
+`navigator.mediaDevices.getUserMedia()` и `MediaRecorder` работают внутри фронт-компонентов благодаря полифиллам песочницы, поэтому стандартный код записи выполняется без изменений, а `MediaRecorder.isTypeSupported` возвращает true для распространенных комбинаций контейнер/кодек. Подробные объекты ограничений `getUserMedia` принимаются, но не передаются дальше — хост выполняет захват с настройками по умолчанию для запрошенных типов — и одновременно во всех приложениях может быть активен только один захват. Сохраните записанный `Blob` с помощью хост-функции `uploadFile`.
+
+### Другие пробелы
+
+* **Содержимое файла.** Элемент `input` с типом `file` предоставляет вашему обработчику только метаданные файла, а не байты, поэтому `FileReader` недоступен. Чтобы загрузить `Blob`, который уже есть в вашем коде (например, созданный `MediaRecorder`), используйте хост-функцию `uploadFile`.
+* **Перетащите приложения.** Перетаскивайте события, но `event.dataTransfer` `неопределённый`.
+* **Узел встроенный** `fs`, `path` и `node:crypto` не срабатывают сборки, так что переместитесь с помощью [logic функции](/l/ru/developers/extend/apps/logic/logic-functions). Веб-криптовалюты, `fetch`, `TextEncoder` и `URL`.
+* **`iframe`** всегда повторно изолируется без `allow-same-origin`, поэтому встраиваемый контент, зависящий от собственной сессии, отображается как неавторизованный. У него также нет `onLoad`.

packages/twenty-docs/l/ru/developers/extend/apps/layout/navigation-menu-items.mdx

@@ -0,0 +1,46 @@
+---
+title: Элементы навигационного меню
+description: Добавляйте на боковую панель рабочего пространства пользовательские элементы — ссылки на сохраненные представления или внешние URL-адреса.
+icon: bars
+---
+
+**Элемент навигационного меню** — это запись в левой боковой панели. Используйте `defineNavigationMenuItem()` для добавления пользовательских ссылок на боковую панель — обычно по одной на каждое [представление](/l/ru/developers/extend/apps/layout/views), которое вы поставляете, — или для указания на внешние URL-адреса.
+
+```ts src/navigation-menu-items/example-navigation-menu-item.ts
+import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';
+
+export default defineNavigationMenuItem({
+  universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
+  name: 'example-navigation-menu-item',
+  icon: 'IconList',
+  color: 'blue',
+  position: 0,
+  type: NavigationMenuItemType.VIEW,
+  viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
+});
+```
+
+## Основные моменты
+
+* `type` определяет, на что указывает элемент меню. Каждый тип сопоставляется с определенным полем идентификатора:
+
+  | Тип                                  | Что делает                                      | Обязательное поле                                                                 |
+  | ------------------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------- |
+  | `NavigationMenuItemType.VIEW`        | Открывает сохраненное представление             | `viewUniversalIdentifier`                                                         |
+  | `NavigationMenuItemType.LINK`        | Открывает внешний URL-адрес                     | `link`                                                                            |
+  | `NavigationMenuItemType.FOLDER`      | Группирует вложенные элементы под меткой        | `name` (а дочерние элементы ссылаются на папку через `folderUniversalIdentifier`) |
+  | `NavigationMenuItemType.OBJECT`      | Открывает страницу индекса по умолчанию объекта | `targetObjectUniversalIdentifier`                                                 |
+  | `NavigationMenuItemType.PAGE_LAYOUT` | Открывает отдельный макет страницы              | `pageLayoutUniversalIdentifier`                                                   |
+
+* `position` управляет порядком в боковой панели.
+
+* Перечисление также содержит `NavigationMenuItemType.RECORD`, используемый внутренне для добавляемых пользователем в «Избранное» записей — он не может использоваться из манифеста приложения (нет поля для ссылки на запись).
+
+* `icon` и `color` являются необязательными и настраивают внешний вид элемента.
+
+* `folderUniversalIdentifier` также доступен для любого элемента, чтобы поместить его внутрь родительского элемента типа `FOLDER`.
+
+<Note>
+**Распространенная ошибка:** создание объекта без связанного элемента навигационного меню делает этот объект недоступным через боковую панель. Если только это не технический/внутренний объект, у каждого настраиваемого объекта должен быть элемент боковой панели, указывающий на него.
+</Note>

packages/twenty-docs/l/ru/developers/extend/apps/layout/overview.mdx

@@ -0,0 +1,59 @@
+---
+title: Обзор
+description: Разместите своё приложение внутри интерфейса Twenty — элементы боковой панели, сохранённые представления, вкладки страницы записи и изолированные React‑компоненты.
+icon: table-columns
+---
+
+**Слой компоновки** приложения Twenty — это всё, что видит пользователь: где приложение отображается в боковой панели, какие списки представлений оно поставляет, как устроены его страницы деталей записей и какие пользовательские React‑компоненты отображаются внутри этих страниц.
+
+```text
+   Sidebar               Record list            Record detail page
+   ───────               ───────────            ──────────────────
+   [📋 My View]    ────▶ ┌──────────┐          ┌─────────────────────┐
+   [📋 Drafts ]          │ Companies│          │ Tabs: [Overview ]   │
+   [📋 Inbox  ]          │ ──────── │          │       [Notes    ]   │
+        ▲                │  Apple   │          │       [Hello    ]◀──── definePageLayoutTab
+        │                │  Acme    │          │                     │   adds a tab...
+        └ defineNavi-    │  …       │          │  ┌────────────────┐ │
+          gationMenu-    └────▲─────┘          │  │                │ │
+          Item points         │                │  │   React UI     │◀── …with a
+          to a defineView     │                │  │  (sandboxed in │ │   defineFrontComponent
+                              └ defineView     │  │   a Worker)    │ │   widget inside
+                                picks columns  │  └────────────────┘ │
+                                and filters    └─────────────────────┘
+```
+
+## В этом разделе
+
+<CardGroup cols={2}>
+  <Card title="Представления" icon="list" href="/l/ru/developers/extend/apps/layout/views">
+    `defineView` — сохранённые конфигурации списков: видимые столбцы, фильтры, группы.
+  </Card>
+  <Card title="Элементы меню навигации" icon="bars" href="/l/ru/developers/extend/apps/layout/navigation-menu-items">
+    `defineNavigationMenuItem` — элементы боковой панели, ссылающиеся на представления или внешние URL.
+  </Card>
+  <Card title="Макеты страниц" icon="table-columns" href="/l/ru/developers/extend/apps/layout/page-layouts">
+    `definePageLayout` и `definePageLayoutTab` — вкладки и виджеты на странице деталей записи.
+  </Card>
+  <Card title="Компоненты фронтенда" icon="window-maximize" href="/l/ru/developers/extend/apps/layout/front-components">
+    `defineFrontComponent` — изолированные React‑компоненты, которые отображаются внутри Twenty.
+  </Card>
+  <Card title="Элементы меню команд" icon="terminal" href="/l/ru/developers/extend/apps/layout/command-menu-items">
+    `defineCommandMenuItem` — регистрирует фронтенд‑компоненты как элементы Cmd+K и быстрые действия.
+  </Card>
+</CardGroup>
+
+## Где отображается приложение
+
+| Область отображения                      | Что определяет                                                                                                              | Сущность                                  |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| **Боковая панель**                       | Пользовательский элемент, который ссылается на сохранённое представление или внешний URL                                    | `defineNavigationMenuItem`                |
+| **Список записей**                       | Сохранённая конфигурация для объекта — видимые столбцы, порядок, фильтры, группы                                            | `defineView`                              |
+| **Страница деталей записи**              | Вкладки и виджеты на странице записи (вашего собственного объекта или стандартного)                                         | `definePageLayout`, `definePageLayoutTab` |
+| **Внутри любого из перечисленного выше** | Пользовательский React‑виджет — кнопки, формы, панели мониторинга, интеграции                                               | `defineFrontComponent`                    |
+| **Настройки приложения**                 | Настраиваемый раздел конфигурации на вкладке «Настройки» приложения, используемый вместо стандартного интерфейса переменных | `defineSettingsFrontComponent`            |
+| **Меню команд (Cmd+K)**                  | Закреплённое быстрое действие или скрытая команда                                                                           | `defineCommandMenuItem`                   |
+
+Фронтенд‑компоненты выполняются внутри изолированного Web Worker с использованием Remote DOM — они отображаются *нативно* на странице (не внутри iframe), но не могут напрямую обращаться к хостовой странице или DOM. Взаимодействие с Twenty происходит через хостовый API обмена сообщениями.
+
+Они все еще находятся в активной разработке: песочница реализует частичный DOM, поэтому сложные варианты использования могут завершаться сбоем. См. раздел [Текущие ограничения](/l/ru/developers/extend/apps/layout/front-components#current-limitations).

packages/twenty-docs/l/ru/developers/extend/apps/layout/page-layouts.mdx

@@ -0,0 +1,158 @@
+---
+title: Макеты страниц
+description: Настраивайте страницы деталей записей — вкладки, виджеты и места, где отображаются фронтенд-компоненты, — с помощью `definePageLayout` и `definePageLayoutTab`.
+icon: table-columns
+---
+
+**Макет страницы** управляет тем, как устроена страница деталей записи: какие вкладки отображаются и какие виджеты они содержат. Используйте `definePageLayout()` для объявления макета для объекта, которым вы владеете, или `definePageLayoutTab()` для добавления одной вкладки к макету, который уже существует (вашему или стандартному Twenty).
+
+| Сценарий использования                                                                        | Сущность              |
+| --------------------------------------------------------------------------------------------- | --------------------- |
+| Определите весь макет для страницы записи на объекте, которым вы владеете                     | `definePageLayout`    |
+| Добавьте одну вкладку в существующий макет (для вашего собственного объекта или стандартного) | `definePageLayoutTab` |
+
+## definePageLayout
+
+Используйте это, когда вы управляете всей страницей деталей — обычно для пользовательского объекта, который вы определили сами.
+
+```ts src/page-layouts/example-record-page-layout.ts
+import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';
+import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+export default definePageLayout({
+  universalIdentifier: '203aeb94-6701-46d6-9af1-be2bbcc9e134',
+  name: 'Example Record Page',
+  type: 'RECORD_PAGE',
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  tabs: [
+    {
+      universalIdentifier: '6ed26b60-a51d-4ad7-86dd-1c04c7f3cac5',
+      title: 'Hello World',
+      position: 50,
+      icon: 'IconWorld',
+      layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
+      widgets: [
+        {
+          universalIdentifier: 'aa4234e0-2e5f-4c02-a96a-573449e2351d',
+          title: 'Hello World',
+          type: 'FRONT_COMPONENT',
+          configuration: {
+            configurationType: 'FRONT_COMPONENT',
+            frontComponentUniversalIdentifier:
+              HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+          },
+        },
+      ],
+    },
+  ],
+});
+```
+
+### Основные моменты
+
+* `type` — одно из значений `'RECORD_INDEX'`, `'RECORD_PAGE'`, `'DASHBOARD'` или `'STANDALONE_PAGE'`. Используйте `'RECORD_PAGE'` для настройки детального представления конкретного объекта.
+* `objectUniversalIdentifier` указывает, к какому объекту применяется этот макет.
+* Каждая `tab` определяет раздел страницы с `title`, `position` и `layoutMode`: `VERTICAL_LIST` для страниц записей и автономных страниц, `GRID` для панелей мониторинга и `CANVAS` для одного виджета, который должен заполнять область просмотра вкладки. Во вкладке `VERTICAL_LIST` виджеты располагаются вертикально. Встроенные виджеты, которые самостоятельно управляют прокруткой, такие как временные шкалы, файлы, заметки, задачи и рабочие процессы, заполняют одну область просмотра; поля, фронтальные компоненты, графики и другие виджеты с подгонкой по содержимому отображаются с высотой по содержимому или заданной высотой. Во вкладке `GRID` виджеты всегда размещаются в виде карточек в 12-колоночной сетке. Виджет `CANVAS` не имеет явно заданного положения; если вкладка холста содержит несколько виджетов, они отображаются на высоте своего содержимого, а не заполняют область просмотра.
+* Явно задайте `layoutMode`. Если его не указывать, вы получите `VERTICAL_LIST` на `STANDALONE_PAGE` и `GRID` в остальных случаях, что редко бывает нужно на странице записи.
+* Каждый `widget` внутри вкладки может отображать [front component](/l/ru/developers/extend/apps/layout/front-components), список связей или другие встроенные типы виджетов.
+* Виджет `FRONT_COMPONENT` может задавать для `headerCommandMenuItemUniversalIdentifiers` упорядоченный массив универсальных идентификаторов элементов меню команд из того же приложения. Эти действия отображаются как кнопки со значками в заголовке карточки виджета и сохраняют доступность и проверки разрешений на уровне команд. Идентификаторы должны быть уникальными и разрешаться при установке приложения.
+* `position` у вкладок управляет их порядком. Используйте большие значения (например, 50), чтобы разместить пользовательские вкладки после встроенных.
+
+### Виджеты полей
+
+Виджет `FIELD` отображает одно поле записи. Для полей связи он также может встраивать список связанных записей:
+
+```ts
+{
+  universalIdentifier: 'c1c2c3c4-c5c6-4000-8000-000000000003',
+  title: 'People → Opportunities',
+  type: 'FIELD',
+  configuration: {
+    configurationType: 'FIELD',
+    fieldMetadataId: PEOPLE_FIELD_UNIVERSAL_IDENTIFIER,
+    fieldDisplayMode: 'TABLE',
+    nestedRelationFieldMetadataId: OPPORTUNITIES_FIELD_UNIVERSAL_IDENTIFIER,
+  },
+}
+```
+
+* `fieldMetadataId` принимает универсальный идентификатор поля в объекте макета.
+* `fieldDisplayMode` может иметь одно из следующих значений: `'FIELD'`, `'CARD'`, `'EDITOR'`, `'VIEW'` или `'TABLE'`. `TABLE` встраивает представление, отображающее записи поля связи «один‑ко‑многим».
+* `nestedRelationFieldMetadataId` является необязательным и принимает универсальный идентификатор поля связи «один‑ко‑многим» на целевом объекте связи, чтобы перечислять записи на два перехода связи дальше (например, страница Company, перечисляющая сделки людей этой компании, или страница Person, перечисляющая сделки компании этого человека). Первый переход может быть полем связи «один‑ко‑многим» или «многие‑к‑одному», второй обязан быть «один‑ко‑многим» (соединительные связи не поддерживаются), и это требует `fieldDisplayMode: 'TABLE'` — комбинирование его с любым другим режимом отображения является ошибкой валидации, поскольку вложенный виджет всегда отображается как встраиваемое представление.
+
+## definePageLayoutTab
+
+Используйте это, когда вы хотите только **добавить** вкладку к существующему макету — например, вкладку аналитики на стандартной странице Company или вкладку с AI-сводкой, прикреплённую к макету вашего собственного объекта.
+
+```ts src/page-layouts/example-extra-tab.ts
+import {
+  definePageLayoutTab,
+  PageLayoutTabLayoutMode,
+  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+export default definePageLayoutTab({
+  universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
+  pageLayoutUniversalIdentifier:
+    STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage
+      .universalIdentifier,
+  title: 'Hello World',
+  position: 1000,
+  icon: 'IconWorld',
+  layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
+  widgets: [
+    {
+      universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
+      title: 'Hello World',
+      type: 'FRONT_COMPONENT',
+      configuration: {
+        configurationType: 'FRONT_COMPONENT',
+        frontComponentUniversalIdentifier:
+          HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+      },
+    },
+  ],
+});
+```
+
+### Основные моменты
+
+* `pageLayoutUniversalIdentifier` является **обязательным** и должен указывать на макет страницы, который уже существует на момент установки — либо стандартный макет Twenty, либо определённый вашим собственным приложением. Кросс-приложенческие ссылки на макеты, которыми владеет другое установленное приложение, на данный момент не поддерживаются. Если родительский макет отсутствует, установка завершается с понятной ошибкой проверки.
+
+* Для стандартных макетов Twenty импортируйте идентификаторы из `twenty-sdk/define`:
+
+  ```ts
+  import { STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
+
+  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage.universalIdentifier
+  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.personRecordPage.universalIdentifier
+  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.universalIdentifier
+  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.opportunityRecordPage.universalIdentifier
+  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.noteRecordPage.universalIdentifier
+  // …
+  ```
+
+  Каждый элемент макета также предоставляет свои `tabs` и их `widgets`, поэтому вы можете ссылаться на любой уровень:
+
+  ```ts
+  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.tabs.home
+    .universalIdentifier;
+  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.tabs.home.widgets
+    .fields.universalIdentifier;
+  ```
+
+  Также доступен короткий псевдоним `STANDARD_PAGE_LAYOUT`:
+
+  ```ts
+  import { STANDARD_PAGE_LAYOUT } from 'twenty-sdk/define';
+
+  STANDARD_PAGE_LAYOUT.companyRecordPage.universalIdentifier;
+  ```
+
+* `widgets` ограничены только этой вкладкой — они ссылаются на [front components](/l/ru/developers/extend/apps/layout/front-components), представления и т. п. точно так же, как виджеты, определённые непосредственно в `definePageLayout`.
+
+* `position` управляет порядком относительно существующих вкладок в целевом макете. Выберите значение, которое поместит вашу вкладку в нужное место относительно встроенных вкладок.
+
+* Используйте это вместо `definePageLayout`, когда вы хотите только добавить к существующему макету. Используйте `definePageLayout`, когда вы управляете всем макетом.

packages/twenty-docs/l/ru/developers/extend/apps/layout/views.mdx

@@ -0,0 +1,113 @@
+---
+title: Представления
+description: Поставляйте предварительно настроенные сохранённые представления — порядок столбцов, фильтры, группы — для объектов в вашем приложении.
+icon: list
+---
+
+**Представление** — это сохранённая конфигурация того, как отображаются записи объекта: какие поля появляются, их порядок, видимость, а также применённые фильтры и группы. Используйте `defineView()` для поставки преднастроенных представлений вместе с вашим приложением.
+
+Каждый объект автоматически получает свое основное представление списка (таблицу "All ...", которую открывает пункт навигации `OBJECT`), подготавливаемое сервером — включая объекты, создаваемые вашим приложением, с одним столбцом для каждого поля, объявленного вашим приложением. Представления, которые вы определяете с помощью `defineView()`, всегда являются **дополнительными** представлениями поверх этого представления по умолчанию.
+
+```ts src/views/example-view.ts
+import { defineView } from 'twenty-sdk/define';
+import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
+import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
+
+export default defineView({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'All example items',
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  icon: 'IconList',
+  position: 0,
+  fields: [
+    {
+      universalIdentifier: 'f926bdb7-6af7-4683-9a09-adbca56c29f0',
+      fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
+      position: 0,
+      isVisible: true,
+      size: 200,
+    },
+  ],
+});
+```
+
+## Основные моменты
+
+* `objectUniversalIdentifier` указывает, к какому объекту применяется это представление. Это может быть пользовательский объект, который вы определили, или стандартный объект Twenty.
+* Основное представление списка объекта принадлежит серверу: `key` устарел и игнорируется, поэтому представление из манифеста никогда не сможет на него претендовать. Добавьте элемент навигации `VIEW`, если вы хотите, чтобы до вашего представления можно было добраться в один клик из боковой панели.
+* `fields` управляет тем, какие столбцы отображаются и в каком порядке. Каждое поле ссылается на `fieldMetadataUniversalIdentifier`. Чтобы сослаться на автоматически созданное системное поле, такое как `createdAt`, см. раздел [Targeting System Metadata](/l/ru/developers/extend/apps/data/system-fields).
+* Также вы можете определить `filters`, `filterGroups`, `sorts`, `groups` и `fieldGroups` для более продвинутых конфигураций.
+* `position` управляет порядком, когда для одного и того же объекта существует несколько представлений.
+
+## Необязательные свойства
+
+| Свойство                                                                                                    | Значения                                                                                 | Описание                                                                                                                                                                                                                              |
+| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`                                                                                                      | `ViewType.TABLE` (по умолчанию), `ViewType.LIST`, `ViewType.KANBAN`, `ViewType.CALENDAR` | Как записи располагаются на экране. (`FIELDS_WIDGET`, `TABLE_WIDGET`, `KANBAN_WIDGET`, `LIST_WIDGET` и `CALENDAR_WIDGET` также существуют, но используются внутри виджетов макета страницы.)                                          |
+| `visibility`                                                                                                | `ViewVisibility.WORKSPACE` (по умолчанию), `ViewVisibility.UNLISTED`                     | Отображается ли представление для всего рабочего пространства или скрыто из элементов выбора.                                                                                                                                         |
+| `openRecordIn`                                                                                              | устаревшие                                                                               | Больше не используется: место открытия записей теперь является свойством [объекта](/l/ru/developers/extend/apps/data/objects) (`openRecordIn` в `defineObject()`); при отсутствии значения используется предпочтение каждого пользователя. |
+| `sorts`                                                                                                     | `{ fieldMetadataUniversalIdentifier, direction: ViewSortDirection.ASC \| DESC }[]`       | Порядок сортировки по умолчанию.                                                                                                                                                                                                      |
+| `isCompact`                                                                                                 | `boolean`                                                                                | Компактное отображение строк.                                                                                                                                                                                                         |
+| `mainGroupByFieldMetadataUniversalIdentifier` + `shouldHideEmptyGroups`                                     | —                                                                                        | Группировать записи (например, столбцы канбана) по полю.                                                                                                                                                                              |
+| `kanbanAggregateOperation`, `kanbanAggregateOperationFieldMetadataUniversalIdentifier`, `kanbanColumnWidth` | `AggregateOperations.*`                                                                  | Агрегирование и ширина столбцов канбана.                                                                                                                                                                                              |
+| `calendarLayout`, `calendarFieldMetadataUniversalIdentifier`, `calendarEndFieldMetadataUniversalIdentifier` | `ViewCalendarLayout.DAY` / `WEEK` / `MONTH`                                              | Календарные представления: макет, поле даты, по которому размещаются записи, и необязательное поле даты окончания.                                                                                                                    |
+
+Все перечисления выше экспортируются из `twenty-sdk/define`.
+
+## Фильтры
+
+Представление может поставляться с заранее примененными фильтрами. У каждого фильтра есть три координаты: **поле**, по которому выполняется фильтрация, **операнд** (как сравнивать) и **значение** (с чем сравнивать). Все три должны совпадать — использование операнда, который не подходит для типа поля, будет отклонено во время синхронизации.
+
+```ts
+import { ViewFilterOperand } from 'twenty-sdk/define';
+
+filters: [
+  {
+    universalIdentifier: '...',
+    fieldMetadataUniversalIdentifier: STATUS_FIELD_UNIVERSAL_IDENTIFIER,
+    operand: ViewFilterOperand.IS,
+    value: ['ACTIVE'],
+  },
+],
+```
+
+### Поддерживаемые операнды по типу поля
+
+| Тип поля                                                                                           | Поддерживаемые операнды                                                                                            |
+| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `TEXT`, `EMAILS`, `FULL_NAME`, `ADDRESS`, `LINKS`, `PHONES`, `RAW_JSON`, `FILES`, `ACTOR`, `ARRAY` | `CONTAINS`, `DOES_NOT_CONTAIN`, `IS_EMPTY`, `IS_NOT_EMPTY`                                                         |
+| `ACTOR.source`, `ACTOR.workspaceMemberId`                                                          | `IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`                                                                         |
+| `SELECT`                                                                                           | `IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`                                                                         |
+| `MULTI_SELECT`                                                                                     | `CONTAINS`, `DOES_NOT_CONTAIN`, `IS_EMPTY`, `IS_NOT_EMPTY`                                                         |
+| `RELATION`                                                                                         | `IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`                                                                         |
+| `NUMBER`                                                                                           | `IS`, `IS_NOT`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS_EMPTY`, `IS_NOT_EMPTY`                          |
+| `RATING`                                                                                           | `IS`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS_EMPTY`, `IS_NOT_EMPTY`                                    |
+| `CURRENCY`, `CURRENCY.amountMicros`                                                                | `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`                          |
+| `CURRENCY.currencyCode`                                                                            | `IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`                                                                         |
+| `DATE`, `DATE_TIME`                                                                                | `IS`, `IS_RELATIVE`, `IS_IN_PAST`, `IS_IN_FUTURE`, `IS_TODAY`, `IS_BEFORE`, `IS_AFTER`, `IS_EMPTY`, `IS_NOT_EMPTY` |
+| `BOOLEAN`                                                                                          | `IS`                                                                                                               |
+| `UUID`                                                                                             | `IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`                                                                         |
+| `TS_VECTOR`                                                                                        | `VECTOR_SEARCH`                                                                                                    |
+
+> Типы полей с похожими названиями могут использовать совершенно разные операнды — типичный пример: `SELECT` и `MULTI_SELECT`.
+
+### Форма значения для каждого операнда
+
+Поле `value` всегда содержит значение, сериализуемое в JSON, но ожидаемая форма зависит от операнда:
+
+| Семейство операндов                                    | Форма значения                        | Пример                   |
+| ------------------------------------------------------ | ------------------------------------- | ------------------------ |
+| `IS`, `IS_NOT` для `SELECT`                            | массив ключей опций (строки)          | `['ACTIVE', 'PENDING']`  |
+| `CONTAINS`, `DOES_NOT_CONTAIN` для `MULTI_SELECT`      | массив ключей опций (строки)          | `['TAG_A']`              |
+| `IS`, `IS_NOT` для `RELATION`                          | массив идентификаторов записей (uuid) | `['c5a1...']`            |
+| `CONTAINS`, `DOES_NOT_CONTAIN` для текстовых полей     | строка                                | `'acme'`                 |
+| `IS`, `IS_NOT` для `NUMBER`                            | строка (значение)                     | `'5'`                    |
+| `IS` для `RATING` / `UUID`                             | строка (значение)                     | `'5'`                    |
+| `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`          | строка (граница)                      | `'10'`                   |
+| `IS`, `IS_BEFORE`, `IS_AFTER` для `DATE` / `DATE_TIME` | строка в формате ISO 8601             | `'2025-01-01T00:00:00Z'` |
+| `IS_EMPTY`, `IS_NOT_EMPTY`                             | пустая строка                         | `''`                     |
+| `IS` для `BOOLEAN`                                     | `'true'` или `'false'`                | `'true'`                 |
+
+## Как представления отображаются в интерфейсе
+
+Само по себе представление недоступно из боковой панели. Чтобы оно появилось там, свяжите его с [пунктом навигационного меню](/l/ru/developers/extend/apps/layout/navigation-menu-items) типа `VIEW`, который указывает на `universalIdentifier` представления. Это канонический шаблон: для каждого настраиваемого объекта при создании автоматически генерируется индексное представление по умолчанию, поэтому вам нужно только добавить элемент боковой панели, который его открывает.

packages/twenty-docs/l/ru/developers/extend/apps/logic/background-jobs.mdx

@@ -0,0 +1,197 @@
+---
+title: Фоновые задания
+description: Передавайте длительные или ограниченные по скорости задачи воркерам Twenty, помещая в очередь ещё один запуск логической функции вместо выполнения всего прямо в текущем процессе.
+icon: layer-group
+---
+
+Запуск логической функции ограничен значением `timeoutSeconds` (максимум 900 секунд). Любая задача, которая не может завершиться за это время — полная повторная синхронизация, разветвление по каждой записи, сторонний API, который ограничивает вас по скорости, — должна быть разделена на более мелкие запуски.
+
+`enqueueJobs` делает именно это: он просит воркеров Twenty позже запустить одну из логических функций вашего приложения, по одному разу для каждой полезной нагрузки, каждый запуск в отдельном процессе с собственным лимитом времени. Вызов возвращается немедленно.
+
+```text
+  ┌─────────────────┐  enqueueJobs(...)  ┌──────────────┐   ┌────────────────────┐
+  │ Logic function  │ ─────────────────▶ │ Job queue    │──▶│ Logic function     │
+  │ (returns now)   │                    │ (workers)    │   │ (fresh run/timeout)│
+  └─────────────────┘                    └──────────────┘   └────────────────────┘
+```
+
+## Постановка запусков в очередь
+
+Импортируйте `enqueueJobs` из `twenty-sdk/logic-function`, укажите `universalIdentifier` логической функции для запуска и передайте в очередь по одной полезной нагрузке для каждого запуска.
+
+```ts src/logic-functions/sync-all-contacts.ts
+import { enqueueJobs } from 'twenty-sdk/logic-function';
+
+await enqueueJobs({
+  logicFunctionUniversalIdentifier: '9f1c3d7e-51b8-4a29-8f0d-7c4e2a6b1d33',
+  payloads: [{ page: 1 }],
+});
+```
+
+Каждый запуск получает свою полезную нагрузку в качестве аргумента обработчика, точно так же, как любой другой триггер. Целевая функция должна принадлежать **тому же приложению**, что и вызывающая сторона — постановка в очередь функции другого приложения будет отклонена с ошибкой `Logic function not found`, и ничего не будет поставлено в очередь. Один вызов принимает до `200` полезных нагрузок.
+
+<Note>
+`enqueueJobs` возвращает управление, как только задания приняты, а не когда они выполнены. Он не возвращает результаты целевых функций — если вам нужно потом их прочитать, пусть каждая целевая функция запишет то, что она создаёт, в [key-value store](/l/ru/developers/extend/apps/logic/key-value-store) или в запись рабочего пространства.
+</Note>
+
+<Note>
+Старый помощник `enqueueJob`, который добавляет в очередь одно задание за вызов, устарел. Вместо этого используйте `enqueueJobs` со списком `payloads`, состоящим из одного элемента.
+</Note>
+
+## Параметры задания
+
+Параметры применяются к каждому запуску в пакете.
+
+| Вариант      | По умолчанию | Диапазон                 | Что делает                                                                                                                                                                                                                            |
+| ------------ | ------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `retryLimit` | `0`          | `0`–`10`                 | Общее количество дополнительных попыток постановки в очередь. Количество повторных попыток, запрошенных приложением, ограничено значением `3`. Увеличивайте это значение только для обработчиков, которые безопасно запускать дважды. |
+| `delayMs`    | `0`          | `0`–`604800000` (7 дней) | Сколько ждать, прежде чем запуски станут допустимыми к выполнению.                                                                                                                                                                    |
+
+```ts
+await enqueueJobs({
+  logicFunctionUniversalIdentifier: '9f1c3d7e-51b8-4a29-8f0d-7c4e2a6b1d33',
+  payloads: [{ page: 1 }],
+  retryLimit: 3,
+  delayMs: 60_000,
+});
+```
+
+<Note>
+**Приоритет пока нельзя настраивать.** Задания в очереди всегда выполняются с самым низким приоритетом, поэтому работа платформы никогда не откладывается из‑за заданий приложений. Возможность управлять приоритетом появится скоро.
+</Note>
+
+Запуск в очереди наследует действующего пользователя функции, которая его поставила в очередь, поэтому он работает с теми же правами.
+
+## Повторная попытка при временном сбое
+
+Twenty не выполняет повторную попытку при каждом исключении из кода приложения. Обычная вызванная ошибка считается постоянным сбоем. При временном сбое логическая функция в очереди может запросить до трёх повторных попыток, вызвав `RetryableLogicFunctionError`.
+
+```ts
+import {
+  type LogicFunctionExecutionContext,
+  RetryableLogicFunctionError,
+} from 'twenty-sdk/logic-function';
+
+export const handler = async (
+  _payload: unknown,
+  { retryCount, maxRetries }: LogicFunctionExecutionContext,
+) => {
+  const response = await fetch('https://api.example.com/contacts');
+
+  if (response.status === 429 || response.status >= 500) {
+    throw new RetryableLogicFunctionError(
+      `The contacts API is temporarily unavailable (${response.status}); retry ${retryCount} of ${maxRetries}`,
+    );
+  }
+};
+```
+
+По возможности вызывайте `RetryableLogicFunctionError` напрямую. Если вы расширяете его, не заменяйте его `name`: Twenty распознаёт сериализованное имя `RetryableLogicFunctionError` во всех средах выполнения.
+
+`retryCount` равен `0` при первоначальном выполнении и увеличивается, только когда код приложения запрашивает повторную попытку. `maxRetries` не превышает `3` и может быть меньше, если у задания в очереди меньше общий лимит повторных попыток. Сбои платформы не увеличивают `retryCount`, хотя всё равно расходуют общий резерв безопасности очереди.
+
+Очередь задерживает повторные попытки с экспоненциальной задержкой и случайным разбросом. Точная задержка намеренно не гарантируется, поэтому код приложения не должен зависеть от выполнения повторной попытки в точно определённое время. После достижения `maxRetries` ещё один `RetryableLogicFunctionError` фиксируется как окончательный сбой приложения без нового выполнения.
+
+<Warning>
+Повторные попытки заново выполняют весь обработчик и могут происходить после успешного выполнения некоторых побочных эффектов. Сделайте обработчик идемпотентным, прежде чем запрашивать повторные попытки.
+</Warning>
+
+## Использование: постраничный проход по длинной синхронизации
+
+Классический шаблон — функция, которая ставит *саму себя* в очередь со следующим курсором. Каждый запуск обрабатывает одну страницу работы, уверенно укладываясь в собственный таймаут, а цепочка останавливается, когда больше нечего делать.
+
+```ts src/logic-functions/sync-contacts-page.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { enqueueJobs } from 'twenty-sdk/logic-function';
+
+const SYNC_CONTACTS_PAGE = '9f1c3d7e-51b8-4a29-8f0d-7c4e2a6b1d33';
+
+const handler = async (params: { cursor?: string }) => {
+  const { contacts, nextCursor } = await fetchContactsPage(params.cursor);
+
+  await importContacts(contacts);
+
+  if (nextCursor) {
+    await enqueueJobs({
+      logicFunctionUniversalIdentifier: SYNC_CONTACTS_PAGE,
+      payloads: [{ cursor: nextCursor }],
+      delayMs: 2_000,
+    });
+  }
+
+  return { imported: contacts.length, done: !nextCursor };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: SYNC_CONTACTS_PAGE,
+  name: 'sync-contacts-page',
+  timeoutSeconds: 120,
+  handler,
+});
+```
+
+## Разветвление по каждой записи
+
+Когда работа естественным образом выполняется по отдельным элементам, добавляйте в очередь по одному заданию на элемент за один вызов и позвольте воркерам обрабатывать их параллельно, вместо того чтобы перебирать элементы в цикле непосредственно в коде.
+
+```ts
+const companies = await listCompaniesToEnrich();
+
+await enqueueJobs({
+  logicFunctionUniversalIdentifier: ENRICH_COMPANY,
+  payloads: companies.map((company) => ({ companyId: company.id })),
+  retryLimit: 2,
+});
+```
+
+## Рекомендации для длительной работы
+
+Два правила покрывают почти любое долгое задание: **рекурсивный вызов вместо цикла** и **обработка ограниченного блока за один запуск**.
+
+Запуск, который пытается сделать всё сразу, — это сценарий отказа: он упирается в таймаут и при повторной попытке начинает всё сначала с нуля. Вместо этого выберите размер блока так, чтобы он с запасом завершался в пределах `timeoutSeconds`, сохраните свою позицию и поставьте в очередь следующий запуск.
+
+```ts src/logic-functions/enrich-companies-batch.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { enqueueJobs, kv } from 'twenty-sdk/logic-function';
+
+const ENRICH_COMPANIES_BATCH = '3f9d1c02-8a44-4f0e-b1d7-9c2e5a7b4f10';
+const CHUNK_SIZE = 50;
+
+const handler = async (params: { offset?: number }) => {
+  const offset = params.offset ?? 0;
+  const companies = await listCompaniesToEnrich({
+    offset,
+    limit: CHUNK_SIZE,
+  });
+
+  for (const company of companies) {
+    await enrichCompany(company);
+  }
+
+  await kv.set('enrich:progress', { offset: offset + companies.length });
+
+  if (companies.length === CHUNK_SIZE) {
+    await enqueueJobs({
+      logicFunctionUniversalIdentifier: ENRICH_COMPANIES_BATCH,
+      payloads: [{ offset: offset + CHUNK_SIZE }],
+    });
+  }
+
+  return { processed: companies.length, done: companies.length < CHUNK_SIZE };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: ENRICH_COMPANIES_BATCH,
+  name: 'enrich-companies-batch',
+  timeoutSeconds: 300,
+  handler,
+});
+```
+
+Почему это работает:
+
+* **Размер блока выбирайте, исходя из самого медленного элемента, а не среднего.** `CHUNK_SIZE × время обработки в худшем случае` должно помещаться в `timeoutSeconds` с запасом, иначе хвост блока будет потерян, когда запуск обрежет таймаут.
+* **Сделайте условие завершения явным.** Вызывайте рекурсивно только пока вернулся полный блок. Цепочка, которая останавливается только на основе «нет результатов», будет продолжаться бесконечно, если источник когда‑либо вернёт укороченную страницу посередине.
+* **Сохраняйте прогресс перед постановкой в очередь следующего запуска**, чтобы при сбое звена цепочки она возобновлялась с последнего завершённого блока, а не с начала.
+* **Сделайте каждый блок идемпотентным.** Повторная обработка одного блока после повторной попытки не должна приводить к двойной записи — привязывайте операции записи к идентификатору обрабатываемой записи или к внешнему идентификатору.
+* **Отдавайте предпочтение цепочке из блоков перед одним гигантским разветвлением**, когда работа обращается к внешнему сервису с ограничением по скорости: цепочка с `delayMs` саморегулирует темп, тогда как тысячи заданий, поставленных в очередь одновременно, сразу становятся допустимыми к выполнению.

packages/twenty-docs/l/ru/developers/extend/apps/logic/connections.mdx

@@ -0,0 +1,269 @@
+---
+title: Подключения
+description: Разрешите вашему приложению действовать от имени пользователя в сторонних сервисах с помощью OAuth.
+icon: plug
+---
+
+Подключения — это учетные данные, которыми пользователь располагает для внешнего сервиса (Linear, GitHub, Slack, ...). Ваше приложение определяет, **как** получают эти учетные данные — через **провайдера подключения** — и использует их во время выполнения для выполнения аутентифицированных вызовов к стороннему API.
+
+На данный момент поддерживается только OAuth 2.0. Будущие типы учетных данных (персональные токены доступа, ключи API, базовая аутентификация) будут подключаться к тому же интерфейсу — приложения, уже использующие `defineConnectionProvider({ type: 'oauth', ... })` не потребуют миграции.
+
+<AccordionGroup>
+
+<Accordion title="defineConnectionProvider" description="Определите, как в вашем приложении получаются подключения">
+
+Провайдер подключения описывает процедуру OAuth-обмена, которая требуется вашему приложению. Пользователь нажимает "Добавить подключение" в настройках вашего приложения, подтверждает разрешения на экране согласия провайдера, и в его рабочем пространстве создается запись `ConnectedAccount`.
+
+Рабочей конфигурации нужны **два файла** — провайдер подключения и соответствующее объявление `serverVariables` в `defineApplication`, которое содержит учетные данные клиента OAuth.
+
+```ts src/connection-providers/linear-connection.ts
+import { defineConnectionProvider } from 'twenty-sdk/define';
+
+export default defineConnectionProvider({
+  universalIdentifier: '9c7d1f5e-6a0b-4d44-be0c-3f8b5a9d4e6f',
+  name: 'linear',
+  displayName: 'Linear',
+  icon: 'IconBrandLinear',
+  type: 'oauth',
+  oauth: {
+    authorizationEndpoint: 'https://linear.app/oauth/authorize',
+    tokenEndpoint: 'https://api.linear.app/oauth/token',
+    scopes: ['read', 'write'],
+    // These must match keys in `defineApplication.serverVariables` below.
+    clientIdVariable: 'LINEAR_CLIENT_ID',
+    clientSecretVariable: 'LINEAR_CLIENT_SECRET',
+    // Optional: defaults to 'json'. Some providers (Linear, Slack) want
+    // 'form-urlencoded' for the token request.
+    tokenRequestContentType: 'form-urlencoded',
+    // Optional: defaults to true. Disable only if the provider rejects PKCE.
+    usePkce: false,
+    // Optional: extra query params on the authorize URL.
+    // authorizationParams: { prompt: 'consent' },
+    // Optional: provider's RFC 7009 token revocation endpoint, called on disconnect.
+    // revokeEndpoint: 'https://example.com/oauth/revoke',
+  },
+  // Optional: a logic function in this app to run right after a connection is
+  // established. See "Run a logic function on connect".
+  // onConnectLogicFunction: { universalIdentifier: '3a2b1c0d-...-...' },
+  // Optional: a logic function in this app to run right after a connection is
+  // removed. See "Run a logic function on disconnect".
+  // onDisconnectLogicFunction: { universalIdentifier: '4d5e6f70-...-...' },
+});
+```
+
+```ts src/application.config.ts
+import { defineApplication } from 'twenty-sdk/define';
+
+export default defineApplication({
+  universalIdentifier: '...',
+  displayName: 'Linear',
+  description: 'Connect Linear to Twenty.',
+  // OAuth client credentials live on the app registration (one OAuth app per
+  // Twenty server, configured by the admin) — not per-workspace. Declare them
+  // as serverVariables so the admin can fill them in once for all installs.
+  serverVariables: {
+    LINEAR_CLIENT_ID: {
+      description: 'OAuth client ID from your Linear OAuth application.',
+      isSecret: false,
+      isRequired: true,
+    },
+    LINEAR_CLIENT_SECRET: {
+      description: 'OAuth client secret from your Linear OAuth application.',
+      isSecret: true,
+      isRequired: true,
+    },
+  },
+});
+```
+
+Основные моменты:
+
+* `name` — это уникальная строка-идентификатор, используемая в `listConnections({ providerName })` (kebab-case, должна соответствовать `^[a-z][a-z0-9-]*$`).
+* `displayName` отображается на вкладке настроек приложения и в списке инструментов ИИ.
+* `clientIdVariable` / `clientSecretVariable` — это **имена**, а не значения — они должны совпадать с ключами, объявленными в `defineApplication.serverVariables`. Фактические `client_id` и `client_secret` вводятся администратором сервера через интерфейс регистрации приложения и никогда не коммитятся в ваш репозиторий.
+* Используйте `serverVariables` (не `applicationVariables`) — учетные данные OAuth являются общими для сервера, и на каждом сервере Twenty используется одно приложение OAuth.
+* Пока оба `serverVariables` не заполнены, на вкладке настроек приложения показывается подсказка "нужен администратор сервера", а кнопка "Добавить подключение" отключена.
+* `type: 'oauth'` — единственное поддерживаемое сегодня значение. Дискриминатор совместим с будущими версиями: будущие типы (`'pat'`, `'api-key'`, ...) добавят новые блоки подконфигурации рядом с `oauth`.
+
+URL обратного вызова OAuth, который вашему провайдеру нужно добавить в список разрешенных:
+
+```
+https://<your-twenty-server>/auth/apps/callback
+```
+
+</Accordion>
+
+<Accordion title="Запускайте логическую функцию при подключении" description="Реагируйте в момент установления соединения">
+
+Некоторые провайдеры передают вам данные в момент подключения, которые нужно сохранить до того, как соединение станет пригодным к использованию — классический пример — Slack, где OAuth-ответ указывает `team_id` рабочей области, по которому будут определяться входящие события. Установите `onConnectLogicFunction`, чтобы сослаться на логическую функцию в том же приложении (по её `universalIdentifier`), и она будет выполнена сразу после создания `ConnectedAccount`.
+
+```ts src/connection-providers/slack-connection.ts
+export default defineConnectionProvider({
+  universalIdentifier: '...',
+  name: 'slack',
+  displayName: 'Slack',
+  type: 'oauth',
+  oauth: {
+    /* ... */
+  },
+  // Runs claimSlackTeam after every successful Slack connection.
+  onConnectLogicFunction: {
+    universalIdentifier: '3a2b1c0d-1111-4222-8333-444455556666',
+  },
+});
+```
+
+Хук выполняется **асинхронно в подключающейся рабочей области** (он ставится в очередь, а не ожидается), поэтому медленный или падающий хук никогда не блокирует и не ломает OAuth-callback — сделайте его идемпотентным и обеспечьте собственную обработку повторных попыток. Обработчик получает:
+
+```ts
+type OnConnectPayload = {
+  connectionProviderId: string;
+  connectionProviderName: string; // e.g. 'slack'
+  connectedAccountId: string;
+};
+```
+
+Оттуда используйте `getConnection(connectedAccountId)`, чтобы прочитать новый access token и вызвать API провайдера (например, Slack `auth.test`) или сохранить отображение с помощью [key-value store](/l/ru/developers/extend/apps/logic/key-value-store).
+
+</Accordion>
+
+<Accordion title="Запускайте логическую функцию при отключении" description="Выполняйте очистку при удалении подключения">
+
+Всё, на что приложение заявляет права при подключении, должно быть освобождено, когда подключение прекращается. Интеграция со Slack, которая, например, заявляет `team_id` при подключении, должна освободить это право, чтобы другое рабочее пространство могло подключить ту же Slack-команду. Установите `onDisconnectLogicFunction`, чтобы сослаться на логическую функцию в том же приложении, и она будет выполнена сразу после удаления `ConnectedAccount`.
+
+```ts src/connection-providers/slack-connection.ts
+export default defineConnectionProvider({
+  universalIdentifier: '...',
+  name: 'slack',
+  displayName: 'Slack',
+  type: 'oauth',
+  oauth: {
+    /* ... */
+  },
+  // Runs releaseSlackTeam after every Slack disconnection.
+  onDisconnectLogicFunction: {
+    universalIdentifier: '4470aba8-5ff5-4800-88db-2a427cd8677c',
+  },
+});
+```
+
+Как и hook on-connect, он запускается **асинхронно в отключаемом рабочем пространстве** и никогда не блокирует отключение. Обработчик получает тот же формат полезной нагрузки:
+
+```ts
+type OnDisconnectPayload = {
+  connectionProviderId: string;
+  connectionProviderName: string; // e.g. 'slack'
+  connectedAccountId: string;
+};
+```
+
+`ConnectedAccount` уже удалён к моменту запуска hook, поэтому `getConnection(connectedAccountId)` больше не возвращает результат. Всё, что требуется для очистки (например, `team_id`, внешний идентификатор подписки), должно быть записано в [key-value store](/l/ru/developers/extend/apps/logic/key-value-store) в момент подключения, с ключом `connectedAccountId`.
+
+Hook срабатывает, когда соединение удаляется само по себе. При удалении приложения его соединения удаляются каскадом на уровне базы данных, поэтому hook в этом случае не запускается. Объявите `uninstallLogicFunction` в `defineApplication` для этого сценария: она запускается до удаления метаданных приложения, поэтому всё ещё может вызвать `listConnections` и выполнить оставшуюся очистку.
+
+</Accordion>
+
+<Accordion title="listConnections / getConnection" description="Используйте подключения из логической функции">
+
+Внутри обработчика логической функции `listConnections({ providerName })` возвращает записи `ConnectedAccount` этого приложения для указанного провайдера с обновленными токенами доступа.
+
+```ts src/logic-functions/handlers/create-linear-issue-handler.ts
+import { listConnections } from 'twenty-sdk/logic-function';
+
+export const createLinearIssueHandler = async (input: {
+  teamId?: string;
+  title?: string;
+}) => {
+  if (!input.teamId || !input.title) {
+    return { success: false, error: 'teamId and title are required' };
+  }
+
+  const connections = await listConnections({ providerName: 'linear' });
+
+  // Workspace-shared credentials win when present; fall back to the first
+  // user-visibility one. For HTTP-route triggers you typically pick the
+  // request user's connection via event.userWorkspaceId instead.
+  const connection =
+    connections.find((c) => c.visibility === 'workspace') ?? connections[0];
+
+  if (!connection) {
+    return {
+      success: false,
+      error:
+        'Linear is not connected. Open the app settings and click "Add connection".',
+    };
+  }
+
+  // Use connection.accessToken to call the third-party API.
+  const response = await fetch('https://api.linear.app/graphql', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${connection.accessToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      query: `mutation { issueCreate(input: { teamId: "${input.teamId}", title: "${input.title}" }) { success } }`,
+    }),
+  });
+
+  return { success: response.ok };
+};
+```
+
+Каждое подключение имеет:
+
+| Поле              | Описание                                                                                                                                                                                                                                                    |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`              | Уникальный идентификатор записи; передайте его в `getConnection(id)`, чтобы повторно получить одну запись                                                                                                                                                   |
+| `visibility`      | `'user'` (приватно для одного участника рабочего пространства) или `'workspace'` (доступно всем участникам)                                                                                                                                                 |
+| `scopes`          | Разрешения OAuth, предоставленные внешним провайдером (отличаются от `visibility` — это несвязанные вещи)                                                                                                                                                   |
+| `userWorkspaceId` | Идентификатор userWorkspace владельца — полезно для выбора "подключения пользователя запроса" в триггерах HTTP-маршрутов                                                                                                                                    |
+| `accessToken`     | Актуальный токен доступа OAuth (обновляется автоматически при истечении срока действия)                                                                                                                                                                     |
+| `name`            | Отображаемое имя подключения (автоматически определяется при обратном вызове OAuth, может быть переименовано пользователем)                                                                                                                                 |
+| «Обработка»       | Подключенная почта учётной записи в потоке, обновляется при каждом переподключении; решил из OIDC `id_token` возвратился при обмене токенов, возвращаясь обратно к подключению электронной почты Twenty пользователей, когда провайдер не возвращает одного |
+| `authFailedAt`    | Устанавливается, если последняя попытка обновления не удалась; пользователю нужно переподключиться                                                                                                                                                          |
+
+Основные моменты:
+
+* Передайте `{ providerName }`, чтобы отфильтровать по провайдеру; опустите, чтобы получить все подключения этого приложения у всех провайдеров.
+* Сервер прозрачно обновляет токен доступа перед возвратом. Ваш обработчик всегда получает рабочий токен (или установлено `authFailedAt`).
+* `getConnection(id)` — эквивалент для одной записи.
+
+</Accordion>
+
+<Accordion title="Индивидуальная и общая для рабочего пространства видимость" description="Как пользователи выбирают между приватными и общими учетными данными">
+
+Когда пользователь нажимает "Добавить подключение", ему предлагается выбрать видимость:
+
+* **Только для меня** — учетные данные приватны для подключившегося пользователя. Любая логическая функция, вызываемая от его имени (триггер HTTP-маршрута с `isAuthRequired: true`), видит их; триггеры cron и события базы данных — нет.
+* **Общее для рабочего пространства** — любой участник рабочего пространства может использовать эти учетные данные. Триггеры cron/базы данных также видят их, поскольку у них нет пользователя запроса.
+
+Используйте подходящий вариант для каждого обработчика:
+
+```ts
+// HTTP-route trigger — prefer the request user's own connection.
+const conn =
+  connections.find((c) => c.userWorkspaceId === event.userWorkspaceId) ??
+  connections.find((c) => c.visibility === 'workspace');
+
+// Cron trigger — no request user; only shared credentials are sensible.
+const conn = connections.find((c) => c.visibility === 'workspace');
+```
+
+Допускается несколько подключений на пару (пользователь, провайдер), поэтому один и тот же пользователь может иметь "Personal Linear" и "Work Linear" одновременно.
+
+</Accordion>
+
+<Accordion title="Единоразовая настройка провайдера" description="Зарегистрируйте свое приложение OAuth у стороннего сервиса">
+
+Для каждого провайдера подключения администратору сервера сначала нужно зарегистрировать у стороннего сервиса приложение OAuth.
+
+1. Перейдите в настройки разработчика провайдера (например, https://linear.app/settings/api/applications/new).
+2. Установите **Redirect URI** в значение `\<SERVER_URL>/auth/apps/callback`.
+3. Скопируйте сгенерированные **Client ID** и **Client Secret**.
+4. Откройте установленное приложение в Twenty под учетной записью администратора сервера → задайте значения в соответствующих `serverVariables`.
+5. Затем участники рабочего пространства смогут добавлять подключения в разделе **Подключения** конкретного приложения.
+
+</Accordion>
+
+</AccordionGroup>

packages/twenty-docs/l/ru/developers/extend/apps/logic/key-value-store.mdx

@@ -0,0 +1,110 @@
+---
+title: Хранилище ключ-значение
+description: Сохраняйте промежуточные результаты, кэшируйте данные и разделяйте состояние между запусками логических функций с помощью встроенного в приложение хранилища ключ-значение.
+icon: database
+---
+
+Логические функции выполняются в изолированной среде во временных процессах Node.js — после завершения запуска в памяти ничего не сохраняется. Когда вам нужно **что-то запомнить между запусками** (кэшировать дорогой ответ API, сохранить курсор для инкрементальной синхронизации, «задебаунсить» работу или передать состояние от одной функции к другой), сохраняйте это во встроенном хранилище ключ-значение.
+
+Каждое приложение получает собственное изолированное пространство имён: записи привязаны к аутентифицированному приложению, поэтому ваши ключи никогда не могут конфликтовать с ключами другого приложения или быть прочитаны другим приложением.
+
+```text
+  ┌─────────────────┐   kv.set(key, value)   ┌──────────────────────────┐
+  │ Logic function  │ ─────────────────────▶ │ Application KV store     │
+  │ (your handler)  │ ◀───────────────────── │  key (unique)  │  value  │
+  └─────────────────┘   kv.get(key)          └──────────────────────────┘
+```
+
+## Получение, установка, удаление
+
+Импортируйте `kv` из `twenty-sdk/logic-function`. Значения могут быть любыми JSON-сериализуемыми данными.
+
+```ts src/logic-functions/sync-linear-issues.ts
+import { kv } from 'twenty-sdk/logic-function';
+
+// Read a value. Returns null when the key is missing.
+const cursor = await kv.get<string>('sync-cursor:linear');
+
+// Write a value. Creates the entry on first write, updates it afterwards.
+await kv.set('sync-cursor:linear', newCursor);
+
+// Delete an entry. Returns true when an entry was removed.
+await kv.delete('sync-cursor:linear');
+```
+
+## Области действия
+
+У каждой записи есть область видимости (scope), которая передаётся как опция при каждом вызове. По умолчанию используется `WORKSPACE`.
+
+* **`WORKSPACE`** (по умолчанию) — запись доступна только для текущей установки вашего приложения в рабочем пространстве. Каждое рабочее пространство, в которое устанавливается приложение, получает собственный независимый набор ключей. Это то, что вам нужно для кэшей, курсоров и состояния на уровне рабочего пространства.
+* **`SERVER`** — запись разделяется между **всеми установками** вашего приложения на сервере. Серверные записи ведут себя как механизм резервирования: сохраняемым значением всегда является workspaceId, зарезервировавший ключ (опустите `value` при вызове `set`, чтобы зарезервировать ключ для текущего рабочего пространства), и только это рабочее пространство может перезаписать или удалить запись. Любая установка может прочитать эту запись.
+
+Резервирования на сервере используются для маршрутизации между рабочими пространствами. [Резолвер серверного маршрута](/l/ru/developers/extend/apps/logic/logic-functions#server-route-trigger) выполняется в рабочем пространстве владельца регистрации приложения, но входящий вебхук обычно содержит только внешний идентификатор аккаунта, а не workspaceId в Twenty. Пусть каждое рабочее пространство зарезервирует свой внешний идентификатор в момент подключения, а затем разрешайте его в маршруте:
+
+```ts
+// In the connected workspace, when the external account is linked:
+await kv.set(`slack:team:${teamId}`, undefined, { scope: 'SERVER' });
+
+// In the server-route resolver (owner workspace), on each webhook:
+const workspaceId = await kv.get<string>(`slack:team:${teamId}`, {
+  scope: 'SERVER',
+});
+```
+
+Поскольку серверный ключ может быть занят только для собственного рабочего пространства вызывающего кода и никогда не может быть перезаписан другим, рабочее пространство не может перехватить сопоставление, принадлежащее кому-то ещё. `kv.set` выбрасывает ошибку, если ключ уже занят другим рабочим пространством.
+
+## Использование: кэширование дорогого вызова
+
+Типичный сценарий — кэширование медленного или ограниченного по частоте ответа стороннего сервиса, чтобы при повторных запусках переиспользовать его, а не нести затраты каждый раз.
+
+```ts src/logic-functions/getExchangeRate.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { kv } from 'twenty-sdk/logic-function';
+
+const ONE_HOUR_MS = 60 * 60 * 1000;
+
+type CachedRate = { rate: number; fetchedAt: number };
+
+const handler = async (params: { from: string; to: string }) => {
+  const cacheKey = `cache:exchange-rate:${params.from}:${params.to}`;
+  const cached = await kv.get<CachedRate>(cacheKey);
+
+  if (cached && Date.now() - cached.fetchedAt < ONE_HOUR_MS) {
+    return { rate: cached.rate, cached: true };
+  }
+
+  const response = await fetch(
+    `https://api.example.com/rate?from=${params.from}&to=${params.to}`,
+  );
+  const { rate } = (await response.json()) as { rate: number };
+
+  await kv.set(cacheKey, { rate, fetchedAt: Date.now() });
+
+  return { rate, cached: false };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'd9b2f4e6-1c83-4a07-9e52-6b1d3c8a0f47',
+  name: 'get-exchange-rate',
+  timeoutSeconds: 10,
+  handler,
+});
+```
+
+## Шаблоны и советы
+
+* **Пространства имён.** Добавляйте префиксы к ключам, чтобы разделять разные задачи — `sync-cursor:linear`, `cache:exchange-rate:USD:EUR`, `lock:nightly-report`.
+* **Срок жизни (TTL).** У хранилища нет встроенного механизма истечения срока действия. Сохраняйте метку времени внутри значения (как в примере с кэшем) и проверяйте её при чтении или очищайте устаревшие ключи из [функции, запускаемой по cron](/l/ru/developers/extend/apps/logic/logic-functions).
+* **Что хранить.** Любое JSON-сериализуемое значение — числа, строки, массивы, объекты. Держите записи небольшими; это для координации и кэширования, а не для больших блобов или файлов. Для файлов используйте поле `FILES` и [`uploadFile`](/l/ru/developers/extend/apps/logic/logic-functions#uploading-files).
+* **Видимость.** Записи хранятся в базе данных экземпляра, а не как записи рабочего пространства — они никогда не отображаются в интерфейсе рабочего пространства, не являются частью модели данных вашего приложения и не требуют ролей или прав доступа к объектам.
+
+## Альтернатива: объект-хранилище с возможностью запросов
+
+Встроенное хранилище намеренно сделано непрозрачным: записи не являются записями объектов, поэтому вы не можете просматривать их в интерфейсе, связывать их с другими объектами или фильтровать их с помощью запросов к записям. Когда вам нужно что-то из этого — например, видимый журнал синхронизаций или состояние на уровне записи, — вместо этого определите небольшой **технический объект** с уникальным полем `key` и полем `value` типа `RAW_JSON`, и выполняйте к нему запросы через [типизированный API-клиент](/l/ru/developers/extend/apps/logic/logic-functions#typed-api-clients-twenty-client-sdk). См. [Objects](/l/ru/developers/extend/apps/data/objects) для справки по `defineObject` и [Data → Unique indexes](/l/ru/developers/extend/apps/data/overview#unique-indexes) по обеспечению уникальности ключей.
+
+* **Привязка к записи.** Добавьте [relation](/l/ru/developers/extend/apps/data/relations) от объекта-хранилища к целевому объекту вместо кодирования идентификатора в ключе.
+* **Видимость и разрешения.** Строки живут в базе данных рабочего пространства как любые другие записи, поэтому к ним можно обращаться через API, и они подчиняются [ролям](/l/ru/developers/extend/apps/config/roles) вашего приложения. Чтобы скрыть хранилище из основного пользовательского интерфейса, не добавляйте его в [навигационное меню](/l/ru/developers/extend/apps/layout/navigation-menu-items).
+
+<Note>
+В отличие от встроенного хранилища, пользовательский объект всегда ограничен одним рабочим пространством — он не может разделять записи между установками так, как это делают ключи `SERVER`.
+</Note>

packages/twenty-docs/l/ru/developers/extend/apps/logic/logic-functions.mdx

@@ -0,0 +1,908 @@
+---
+title: Логические функции
+description: Определяйте серверные функции на TypeScript с триггерами HTTP, cron и событиями базы данных.
+icon: bolt
+---
+
+Функции логики — это серверные функции на TypeScript, которые выполняются на платформе Twenty. Их можно запускать HTTP-запросами, расписаниями cron или событиями базы данных — а также предоставлять как инструменты для ИИ-агентов.
+
+<AccordionGroup>
+<Accordion title="defineLogicFunction" description="Определяйте логические функции и их триггеры">
+
+Каждый файл функции использует `defineLogicFunction()` для экспорта конфигурации с обработчиком и необязательными триггерами.
+
+```ts src/logic-functions/createPostCard.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import type { RoutePayload } from 'twenty-sdk/logic-function';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const handler = async (params: RoutePayload) => {
+  const client = new CoreApiClient();
+  const body = (params.body ?? {}) as { name?: string };
+  const name = body.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world';
+
+  const result = await client.mutation({
+    createPostCard: {
+      __args: { data: { name } },
+      id: true,
+      name: true,
+    },
+  });
+  return result;
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
+  name: 'create-new-post-card',
+  timeoutSeconds: 2,
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/post-card/create',
+    httpMethod: 'POST',
+    isAuthRequired: true,
+  },
+  /*databaseEventTriggerSettings: {
+    eventName: 'people.created',
+  },*/
+  /*cronTriggerSettings: {
+    pattern: '0 0 1 1 *',
+  },*/
+});
+```
+
+Доступные типы триггеров:
+* **httpRoute**: Публикует вашу функцию по HTTP-пути и методу. В коде приложения добавляйте префикс `/s/` к пути маршрута при использовании `RestApiClient`; развернутый URL использует внедренную базовую часть `TWENTY_FUNCTIONS_URL` (или `\<server-url>/s`, если она не задана).
+
+<Note>
+Чтобы вызвать логическую функцию, запускаемую маршрутом, из фронтенд-компонента (без интерфейса), см. раздел [Вызов логической функции](/l/ru/developers/extend/apps/layout/front-components#calling-a-logic-function).
+</Note>
+* **cron**: Запускает вашу функцию по расписанию с использованием выражения CRON.
+* **databaseEvent**: Запускается при событиях жизненного цикла объектов рабочего пространства. Когда операция события — `updated`, можно указать конкретные поля для отслеживания в массиве `updatedFields`. Если оставить не заданным или пустым, любое обновление будет вызывать функцию.
+> например, `person.updated`, `*.created`, `company.*`
+* **serverRoute**: открывает один HTTP-маршрут в области регистрации. Функция-резолвер (объявленная с помощью `serverRouteTriggerSettings`) выполняется в рабочем пространстве-владельце и либо возвращает синхронный `Response`, либо целевое рабочее пространство И логическую функцию для постановки в очередь; в случае постановки в очередь платформа отправляет подтверждение с кодом `202` и запускает эту целевую функцию в очереди worker. См. [триггер серверного маршрута](#server-route-trigger).
+
+<Note>
+Вы также можете вручную выполнить функцию с помощью CLI:
+
+```bash filename="Terminal"
+yarn twenty dev:function:exec -n create-new-post-card -p '{"key": "value"}'
+```
+
+```bash filename="Terminal"
+yarn twenty dev:function:exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
+```
+
+Вы можете просматривать логи с помощью:
+
+```bash filename="Terminal"
+yarn twenty dev:function:logs
+```
+</Note>
+
+#### Полезная нагрузка триггера маршрута
+
+Когда триггер маршрута вызывает вашу логическую функцию, она получает объект `RoutePayload`, который соответствует [формату AWS HTTP API v2](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html).
+Импортируйте тип `RoutePayload` из `twenty-sdk/logic-function`:
+
+```ts
+import type { RoutePayload } from 'twenty-sdk/logic-function';
+
+const handler = async (event: RoutePayload) => {
+  const { headers, queryStringParameters, pathParameters, body } = event;
+  const { method, path } = event.requestContext.http;
+
+  return { message: 'Success' };
+};
+```
+
+Тип `RoutePayload` имеет следующую структуру:
+
+  | Свойство                     | Тип                                                     | Описание                                                                                                                                                                                                                | Пример                                                                     |
+  | ---------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+  | `headers`                    | `Record\<string, string \| undefined>` | HTTP-заголовки (только перечисленные в `forwardedRequestHeaders`)                                                                                                                                                       | см. раздел ниже                                                            |
+  | `queryStringParameters`      | `Record\<string, string \| undefined>` | Параметры строки запроса (несколько значений объединяются запятыми)                                                                                                                                                     | `/users?ids=1&ids=2&ids=3&name=Alice` -> `{ ids: '1,2,3', name: 'Alice' }` |
+  | `pathParameters`             | `Record\<string, string \| undefined>` | Параметры пути, извлечённые из шаблона маршрута                                                                                                                                                                         | `/users/:id`, `/users/123` -> `{ id: '123' }`                              |
+  | `body`                       | `object \| null`                                        | Разобранное тело запроса (JSON)                                                                                                                                                                                         | `{ id: 1 }` -> `{ id: 1 }`                                                 |
+  | `rawBody`                    | `string \| undefined`                                   | Исходное тело запроса в кодировке UTF-8, до разбора JSON. Полезно для проверки подписей вебхуков в стиле HMAC (например, `X-Hub-Signature-256` от GitHub, Stripe). `undefined`, если среда выполнения не сохранила его. |                                                                            |
+  | `isBase64Encoded`            | `boolean`                                               | Является ли тело закодированным в base64                                                                                                                                                                                |                                                                            |
+  | `requestContext.http.method` | `string`                                                | Метод HTTP (GET, POST, PUT, PATCH, DELETE)                                                                                                                                                                              |                                                                            |
+  | `requestContext.http.path`   | `string`                                                | Необработанный путь запроса                                                                                                                                                                                             |                                                                            |
+
+
+#### forwardedRequestHeaders
+
+По умолчанию HTTP-заголовки из входящих запросов **не** передаются в вашу логическую функцию по соображениям безопасности.
+Чтобы получить доступ к определённым заголовкам, перечислите их в массиве `forwardedRequestHeaders`:
+
+```ts
+export default defineLogicFunction({
+  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
+  name: 'webhook-handler',
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/webhook',
+    httpMethod: 'POST',
+    isAuthRequired: false,
+    forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
+  },
+});
+```
+
+В обработчике обращайтесь к переданным заголовкам следующим образом:
+
+```ts
+const handler = async (event: RoutePayload) => {
+  const signature = event.headers['x-webhook-signature'];
+  const contentType = event.headers['content-type'];
+
+  // Validate webhook signature...
+  return { received: true };
+};
+```
+
+<Note>
+Имена заголовков приводятся к нижнему регистру. Обращайтесь к ним, используя ключи в нижнем регистре (например, `event.headers['content-type']`).
+</Note>
+
+#### Пользовательский HTTP-ответ
+
+По умолчанию возврат простого значения из обработчика отправляет его обратно как ответ `200` (JSON для объектов, `text/plain` для строк). Чтобы управлять статус-кодом и заголовками ответа, верните `Response` из `twenty-sdk/logic-function`:
+
+```ts
+import { Response } from 'twenty-sdk/logic-function';
+
+const handler = async (event: RoutePayload) => {
+  return new Response('<h1>Hello</h1>', {
+    status: 201,
+    headers: { 'content-type': 'text/html' },
+  });
+};
+```
+
+По соображениям безопасности заголовки ответа ограничены списком разрешенных заголовков. Любой заголовок, которого нет в этом списке (например, `Set-Cookie`, CORS-заголовки, такие как `Access-Control-Allow-Origin`, или пользовательские заголовки `X-*`), молчаливо удаляется перед отправкой ответа. Разрешенные заголовки ответа:
+
+* `content-type`
+* `content-language`
+* `content-disposition`
+* `cache-control`
+* `retry-after`
+
+<Note>
+Код состояния должен быть допустимым кодом состояния HTTP (в диапазоне от 100 до 599). Имена заголовков ответа сравниваются без учета регистра.
+</Note>
+
+#### Ошибочные ответы платформы
+
+Помимо собственных ответов вашего обработчика, платформа в некоторых ситуациях отвечает на запросы к маршрутам напрямую: `404`, когда маршрут или функция не существует, `403`, когда приложение остановлено, `429`, когда достигнут предел частоты выполнения, и `422`, когда `dependencies` приложения для продакшена слишком велики для установки — см. раздел [ограничения на размер зависимостей](/l/ru/developers/extend/apps/getting-started/project-structure#dependencies).
+
+#### Триггер серверного маршрута
+
+`httpRouteTriggerSettings` предоставляет функцию по пути `/s/` и определяет рабочее пространство из хоста запроса — это работает, когда у каждого рабочего пространства свой домен. Поставщики сторонних сервисов, однако, отправляют события всех арендаторов на **один** URL. В этом случае используйте `serverRouteTriggerSettings`.
+
+Триггер состоит из двух частей:
+
+1. Логическая функция-**резолвер** — объявляется с помощью `serverRouteTriggerSettings` — выполняется в вашем **рабочем пространстве-владельце** (рабочем пространстве, которому принадлежит регистрация приложения). Она анализирует входящий запрос и возвращает либо:
+
+   * `{ workspaceId, targetLogicFunctionUniversalIdentifier, payload? }` — платформа ставит эту целевую функцию в очередь в определённом рабочем пространстве и отправляет подтверждение с кодом `202 { queued: true }`, или
+   * `Response` из `twenty-sdk/logic-function` — платформа возвращает этот HTTP‑ответ **синхронно** и **не** ставит целевую функцию в очередь (используйте это для challenge‑рукопожатий, таких как Slack `url_verification`).
+
+   Резолвер является единой точкой авторизации — URL содержит только идентификатор резолвера. **Это предпочтительное место для проверки подписей запросов**: резолвер выполняется до любых побочных эффектов, имеет доступ к исходным `rawBody` и переадресованным заголовкам и может отклонить запрос, не обращаясь к целевой функции.
+2. **Целевая** логическая функция — обычная логическая функция на рабочее пространство — затем выполняется в определенном рабочем пространстве с полезной нагрузкой, возвращенной резолвером (или с исходной полезной нагрузкой запроса, если резолвер ее не преобразовал). Его возвращаемое значение не видит HTTP‑клиент, когда резолвер выбрал путь постановки в очередь.
+
+```ts src/logic-functions/resolve-server-route.logic-function.ts
+import { createHmac, timingSafeEqual } from 'crypto';
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { Response, type RoutePayload } from 'twenty-sdk/logic-function';
+
+// Runs in the owner workspace. Verifies the request signature, picks
+// which target function should handle the event, and returns the
+// workspace + target the platform should dispatch to.
+const handler = async (event: RoutePayload) => {
+  // Fail closed if the secret isn't configured — never fall back to an
+  // empty key, which would let any caller forge a matching signature.
+  const secret = process.env.GITHUB_WEBHOOK_SECRET;
+
+  if (!secret) {
+    throw new Error('GITHUB_WEBHOOK_SECRET is not configured');
+  }
+
+  const signature = event.headers['x-hub-signature-256'] ?? '';
+  const expected =
+    'sha256=' +
+    createHmac('sha256', secret).update(event.rawBody ?? '').digest('hex');
+
+  const a = Buffer.from(signature);
+  const b = Buffer.from(expected);
+
+  if (a.length !== b.length || !timingSafeEqual(a, b)) {
+    throw new Error('invalid signature');
+  }
+
+  const body = (event.body ?? {}) as {
+    challenge?: string;
+    metadata?: { twentyWorkspaceId?: string };
+    type?: string;
+  };
+
+  // Handshakes must be answered on this same response, so reply from the
+  // resolver instead of returning a dispatch target.
+  if (body.type === 'url_verification') {
+    return new Response({ challenge: body.challenge });
+  }
+
+  const workspaceId = body.metadata?.twentyWorkspaceId;
+
+  if (!workspaceId) {
+    throw new Error('event is not linked to a workspace');
+  }
+
+  return {
+    workspaceId,
+    // Route different event types to different target functions.
+    targetLogicFunctionUniversalIdentifier:
+      body.type === 'invoice.paid'
+        ? 'c4e2a9b1-7d4e-4c9a-9f2b-2e1d6a4c8e10' // handle-invoice-paid
+        : 'd5f3b0c2-8e5f-5d0b-a0c3-3f2e7b5d9f21', // handle-other-event
+  };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'b3c2f0a1-7d4e-4c9a-9f2b-2e1d6a4c8e10',
+  name: 'resolve-server-route',
+  handler,
+  serverRouteTriggerSettings: {
+    forwardedRequestHeaders: ['x-hub-signature-256'],
+  },
+});
+```
+
+```ts src/logic-functions/handle-invoice-paid.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import type { RoutePayload } from 'twenty-sdk/logic-function';
+
+// Runs in the resolved workspace. The resolver has already authenticated
+// the request, so this handler can focus on the actual work.
+const handler = async (event: RoutePayload) => {
+  // ...handle the verified event
+  return { received: true };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'c4e2a9b1-7d4e-4c9a-9f2b-2e1d6a4c8e10',
+  name: 'handle-invoice-paid',
+  handler,
+});
+```
+
+Конечная точка доступна по адресу:
+
+```
+POST https://your-twenty-server.com/webhooks/server/:resolverLogicFunctionUniversalIdentifier
+```
+
+Идентификатор — это `universalIdentifier` резолвера из вашего манифеста. Зарегистрируйте этот URL у поставщика.
+
+**Ответ на проверочный `GET`.** Некоторые поставщики проверяют конечную точку перед отправкой данных на неё: они отправляют `GET` с проверочным запросом на тот же URL, на который позднее будут `POST` события. Meta's WhatsApp Cloud API — один из них. Маршрут сервера отвечает только на `POST`, если не указано иное, поэтому объявите оба метода:
+
+```ts
+serverRouteTriggerSettings: {
+  forwardedRequestHeaders: ['x-hub-signature-256'],
+  httpMethods: ['GET', 'POST'],
+}
+```
+
+Проверочный запрос поступает в `event.queryStringParameters`, а возврат `Response` отправляет его обратно поставщику в рамках того же запроса. Строковое тело отправляется как `text/plain`, что и ожидают эти поставщики:
+
+```ts
+const handler = async (event: RoutePayload) => {
+  if (event.requestContext.http.method === 'GET') {
+    return new Response(event.queryStringParameters['hub.challenge']);
+  }
+  // …handle the delivered event
+};
+```
+
+`httpMethods` заменяет значение по умолчанию, а не дополняет его, поэтому одного `['GET']` достаточно, чтобы маршрут отклонял `POST`. Поддерживаются только `GET` и `POST`. Не задавайте его, если провайдеру не требуется второй метод: резолвер маршрута, объявляющего `GET`, будет выполняться при обращении любого неаутентифицированного вызывающего клиента, включая поисковые роботы и средства предварительного просмотра ссылок, которые отправляют `GET` без запроса. На всё, для чего у платформы нет метода, возвращается `405`, при этом резолвер вообще не запускается.
+
+<Note>
+**Приложение должно быть закреплено и установлено в рабочем пространстве владельца.** Поскольку резолвер выполняется в **рабочем пространстве владельца** (рабочем пространстве, которому принадлежит регистрация приложения), триггер серверного маршрута будет работать только после того, как приложение будет *закреплено* — то есть у него появится рабочее пространство владельца — **и** это приложение будет **установлено в рабочем пространстве владельца**. Пока оба этих условия не выполнены, резолверу негде выполняться, поэтому маршрут не может быть отправлен на обработку. Приложение, которое предоставляет логическую функцию `serverRouteTriggerSettings`, соответственно, не может быть размещено в маркетплейсе, пока оно не будет закреплено и установлено в рабочем пространстве владельца.
+</Note>
+
+**Контракт резолвера.** Тип `LogicFunctionConfig` в SDK обеспечивает это на этапе компиляции: как только вы задаете `serverRouteTriggerSettings`, ваш обработчик обязан возвращать либо `Response`, либо `{ workspaceId: string; targetLogicFunctionUniversalIdentifier: string; payload?: object }` (или `Promise` одного из этих вариантов). На пути диспетчеризации `workspaceId` должен указывать на рабочее пространство, в котором установлена целевая функция, иначе запрос будет отклонен с кодом `404`. Результат, не соответствующий ни одному из этих форматов — включая случай, когда идентификаторы не являются UUID, — отклоняется с кодом `502`.
+
+| Поле                                     | Тип                       | Заметки                                                                                      |
+| ---------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------- |
+| `workspaceId`                            | `string`                  | UUID рабочего пространства, в котором будет выполняться целевая функция.                     |
+| `targetLogicFunctionUniversalIdentifier` | `string`                  | `universalIdentifier` логической функции, которую нужно вызвать в этом рабочем пространстве. |
+| `payload`                                | `object` (необязательный) | Если задан, заменяет тело запроса, отправляемое целевой функции.                             |
+
+<Warning>
+**Ответственность за проверку подписи лежит на вас — выполняйте проверку в резолвере.** Платформа не проверяет подписи запросов. Резолвер — рекомендуемое место для этого: он выполняется первым, имеет доступ к `event.rawBody` и заголовкам, которые вы указали в `forwardedRequestHeaders`, и выброшенная ошибка (или любой `workspaceId`, не соответствующий ожидаемому) останавливает диспетчеризацию до вызова целевой функции. Если вместо этого вы перенесете проверку в целевую функцию, целевая функция должна позаботиться о том, чтобы не потерять `rawBody` и заголовки — то есть резолвер не должен возвращать `payload`. Всегда выполняйте проверку **до** любых побочных эффектов и используйте сравнение с постоянным временем выполнения.
+</Warning>
+
+Для подписей запросов большинство провайдеров используют HMAC-SHA256; различаются имя заголовка, кодировка дайджеста и строка подписываемой полезной нагрузки. Несколько примеров:
+
+| Провайдер                    | Заголовки для пересылки                                | Подписываемая строка         | Дайджест                                                          |
+| ---------------------------- | ------------------------------------------------------ | ---------------------------- | ----------------------------------------------------------------- |
+| Svix (Recall, Resend, Clerk) | `webhook-id`, `webhook-timestamp`, `webhook-signature` | `{id}.{timestamp}.{rawBody}` | base64 (секрет в формате base64 после удаления префикса `whsec_`) |
+| Stripe                       | `stripe-signature`                                     | `{timestamp}.{rawBody}`      | hex                                                               |
+| GitHub                       | `x-hub-signature-256`                                  | `{rawBody}`                  | hex (с префиксом `sha256=`)                                       |
+| Shopify                      | `x-shopify-hmac-sha256`                                | `{rawBody}`                  | base64                                                            |
+| Слэк                         | `x-slack-signature`, `x-slack-request-timestamp`       | `v0:{timestamp}:{rawBody}`   | hex (с префиксом `v0=`)                                           |
+
+Приведенный выше пример резолвера уже показывает поток GitHub HMAC-SHA256 — адаптируйте имя заголовка, кодировку дайджеста и строку подписываемой полезной нагрузки в соответствии с провайдером, с которым вы интегрируетесь.
+
+<Note>
+Когда резолвер возвращает объект диспетчеризации, маршрут отвечает `202 { queued: true }`, а целевая функция запускается в очереди worker — вызывающая сторона никогда не видит задержку, результат или сбои целевой функции (они записываются в журналах выполнения). Это не позволяет повторным отправкам со стороны отправителя усиливать замедление обработки, что и требуется для приёма вебхуков.
+
+Когда вызывающей стороне нужно прочитать тело ответа в рамках того же запроса (challenge‑рукопожатия, интерактивные подтверждения), вместо этого верните `Response` из **резолвера**. Платформа синхронно эхо‑возвращает этот ответ и пропускает очередь; его заголовки проходят через тот же allow‑list, что и заголовки ответов HTTP‑маршрутов. Делайте функцию-резолвер быстрой — некоторые провайдеры (например, Slack) прерывают запрос через несколько секунд. Поскольку резолвер доступен как публичная конечная точка, защитите его с помощью ограничения частоты запросов (rate limiting) на вашем периметре (edge).
+</Note>
+
+#### Полезная нагрузка триггера события базы данных
+
+Когда триггер события базы данных вызывает вашу функцию логики, она получает по одному `DatabaseEventPayload` на каждую изменённую запись. Полезная нагрузка объединяет метаданные о рабочем пространстве-источнике и объекте с событием на уровне записи.
+
+```ts
+import type {
+  DatabaseEventPayload,
+  ObjectRecordCreateEvent,
+  ObjectRecordDestroyEvent,
+  ObjectRecordUpdateEvent,
+} from 'twenty-sdk/logic-function';
+
+type Person = {
+  id: string;
+  emails?: { primaryEmail?: string };
+};
+```
+
+Полезная нагрузка включает:
+
+| Свойство                                         | Описание                                                                                           |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `name`                                           | Имя события, например `person.updated`.                                                            |
+| `workspaceId`                                    | Рабочее пространство, в котором произошло событие.                                                 |
+| `objectMetadata`                                 | Метаданные для объекта, который изменился.                                                         |
+| `recordId`                                       | Идентификатор измененной записи.                                                                   |
+| `userId`, `userWorkspaceId`, `workspaceMemberId` | Поля инициатора, если событие было вызвано пользователем рабочего пространства.                    |
+| `properties`                                     | Данные записи для события с `before`, `after`, `diff` и `updatedFields` в зависимости от операции. |
+
+| Событие            | Данные записи                                                                                                  |
+| ------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `person.created`   | `event.properties.after`                                                                                       |
+| `person.updated`   | `event.properties.before`, `event.properties.after`, `event.properties.diff`, `event.properties.updatedFields` |
+| `person.destroyed` | `event.properties.before`                                                                                      |
+
+При логическом удалении `.deleted` имеет формат обновления, поскольку изменяется поле `deletedAt` записи.
+Для окончательного удаления используйте `.destroyed`.
+
+<Note>
+`databaseEventTriggerSettings.updatedFields` фильтрует, какие события обновления запускают функцию.
+`event.properties.updatedFields` указывает, какие поля фактически изменились в текущем событии.
+</Note>
+
+Пример события создания:
+
+```ts
+type PersonCreatedEvent = DatabaseEventPayload<
+  ObjectRecordCreateEvent<Person>
+>;
+
+const handler = async (event: PersonCreatedEvent) => {
+  const person = event.properties.after;
+
+  return {
+    personId: event.recordId,
+    email: person.emails?.primaryEmail,
+  };
+};
+```
+
+Пример события обновления:
+
+```ts
+type PersonUpdatedEvent = DatabaseEventPayload<
+  ObjectRecordUpdateEvent<Person>
+>;
+
+const handler = async (event: PersonUpdatedEvent) => {
+  const { before, after, diff, updatedFields } = event.properties;
+
+  return {
+    personId: event.recordId,
+    updatedFields,
+    previousEmail: before.emails?.primaryEmail,
+    currentEmail: after.emails?.primaryEmail,
+    emailDiff: diff.emails,
+  };
+};
+```
+
+Триггер только при обновлении email:
+
+```ts
+export default defineLogicFunction({
+  ...,
+  databaseEventTriggerSettings: {
+    eventName: 'person.updated',
+    updatedFields: ['emails'],
+  },
+});
+```
+
+Пример события уничтожения:
+
+```ts
+type PersonDestroyedEvent = DatabaseEventPayload<
+  ObjectRecordDestroyEvent<Person>
+>;
+
+const handler = async (event: PersonDestroyedEvent) => {
+  const personBeforeDestroy = event.properties.before;
+
+  return {
+    personId: event.recordId,
+    email: personBeforeDestroy.emails?.primaryEmail,
+  };
+};
+```
+
+#### Контекст выполнения
+
+Каждый обработчик получает второй аргумент, описывающий сам запуск независимо от того, что его вызвало. Если форма первого аргумента меняется в зависимости от триггера, то форма этого не меняется:
+
+```ts
+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';
+
+const handler = async (
+  event: DatabaseEventPayload,
+  { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,
+) => {
+  if (workspaceMemberId === null) {
+    throw new Error('This function must be triggered by a person');
+  }
+
+  return { reviewedBy: workspaceMemberId, workspaceId };
+};
+```
+
+| Поле                | Тип              | Описание                                                                                      |
+| ------------------- | ---------------- | --------------------------------------------------------------------------------------------- |
+| `workspaceId`       | `string`         | Рабочее пространство, к которому относится запуск.                                            |
+| `userWorkspaceId`   | `string \| null` | Человек, вызвавший запуск, представленный своим участием в этом рабочем пространстве.         |
+| `workspaceMemberId` | `string \| null` | Тот же человек в виде записи участника рабочего пространства, к которой привязываются записи. |
+| `retryCount`        | `number`         | `0` при первой попытке. См. [Фоновые задачи](/l/ru/developers/extend/apps/logic/background-jobs).  |
+| `maxRetries`        | `number`         | Верхняя граница количества повторных попыток, запрошенных приложением.                        |
+
+`userWorkspaceId` и `workspaceMemberId` имеют значение `null`, когда запуск никто не вызвал: у cron-расписаний, хуков установки и неаутентифицированных вебхуков нет человека, стоящего за ними. Они также имеют значение `null`, когда у человека нет записи участника рабочего пространства или когда она была удалена.
+
+<Note>
+**Контекст сообщает, кто вызвал запуск.** То, что запуск может *делать*, определяется отдельно, ниже.
+</Note>
+
+#### Чьи права доступа использует вызов
+
+Каждый клиент — `CoreApiClient`, `MetadataApiClient` и `RestApiClient` — действует от имени человека, вызвавшего запуск: его роль пересекается с ролью вашего приложения, поэтому вызов никогда не может сделать больше, чем позволяет любая из этих ролей. Это поведение по умолчанию, и оно означает, что человек никогда не сможет использовать ваше приложение для превышения собственных разрешений.
+
+Когда запуск никто не вызвал, нет человека, от имени которого можно действовать, поэтому тот же клиент использует права доступа самого приложения: cron-расписания, хуки установки и неаутентифицированные вебхуки не требуют специальной обработки.
+
+Для некоторых вызовов правомерно требуются права доступа самого приложения, даже когда за запуском *стоит* человек — например, для чтения записей конфигурации вашего приложения или выполнения работы, которую этот человек не мог бы выполнить сам. Создайте для них второй клиент:
+
+```ts
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const asPerson = new CoreApiClient();
+const asApplication = new CoreApiClient({ runAs: 'application' });
+
+const handler = async (event: DatabaseEventPayload) => {
+  // config records only your app may read
+  const { slackUserLinks } = await asApplication.query({ ... });
+
+  // created as the person, so it is attributed and permission-checked
+  await asPerson.mutation({ createNote: { ... } });
+};
+```
+
+Создайте оба клиента один раз в области видимости модуля, и тогда каждый сайт вызова будет указывать используемые права доступа через вызываемый клиент. `RestApiClient` принимает тот же параметр:
+
+```ts
+import { RestApiClient } from 'twenty-client-sdk/rest';
+
+const asApplication = new RestApiClient({ runAs: 'application' });
+```
+
+<Note>
+**Запуск, который никто не вызвал, действует как ваше приложение.** У cron-расписаний, хуков установки и неаутентифицированных вебхуков нет человека, стоящего за ними, поэтому клиент по умолчанию использует права доступа самого приложения и продолжает работать. `runAs: 'application'` нужен только тогда, когда вам требуются эти права доступа в запуске, который *вызвал* человек.
+
+Проверяйте `context.workspaceMemberId`, когда функция ведет себя по-разному в зависимости от того, стоит ли за ней кто-то, например чтобы указать автора записи.
+</Note>
+
+Помощники SDK, обращающиеся к собственным ресурсам вашего приложения, всегда используют его права доступа и игнорируют `runAs`: [хранилище ключей и значений](/l/ru/developers/extend/apps/logic/key-value-store), [подключения](/l/ru/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl` и списание кредитов.
+
+#### Предоставление функции в качестве инструмента ИИ или действия рабочего процесса
+
+Функции логики могут быть представлены в двух интерфейсах, у каждого — свой триггер:
+
+* **`toolTriggerSettings`** — делает функцию обнаруживаемой для возможностей ИИ Twenty (чат, MCP, вызов функций). Использует стандартную JSON Schema — формат, который модели LLM изначально понимают.
+* **`workflowActionTriggerSettings`** — делает функцию доступной как шаг в визуальном конструкторе рабочих процессов. Использует расширенную `InputSchema` от Twenty, чтобы конструктор мог отрисовывать корректные редакторы полей, селекторы переменных и подписи.
+
+Функция может выбрать один, другой или оба варианта. Они идут рядом с `cronTriggerSettings`, `databaseEventTriggerSettings` и `httpRouteTriggerSettings` — тот же шаблон, та же структура.
+
+<Note>
+**Связь с действием Code рабочего процесса.** Встроенное действие **Code** в конструкторе рабочих процессов само по себе является логической функцией — Twenty создаёт по одной на каждый шаг Code и отображает его редактор встроенным образом. `workflowActionTriggerSettings` — это способ превратить разовый встроенный код в **повторно используемое** действие: определите функцию один раз в своём приложении, и она станет доступной для выбора в любом рабочем процессе, вместо копирования и вставки в каждый шаг Code. См. [действие Code](/l/ru/user-guide/workflows/capabilities/workflow-actions#code) в руководстве пользователя, чтобы увидеть, как это выглядит для конечного пользователя.
+</Note>
+
+```ts src/logic-functions/enrich-company.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const handler = async (params: { companyName: string; domain?: string }) => {
+  const client = new CoreApiClient();
+
+  const result = await client.mutation({
+    createTask: {
+      __args: {
+        data: {
+          title: `Enrich data for ${params.companyName}`,
+          body: `Domain: ${params.domain ?? 'unknown'}`,
+        },
+      },
+      id: true,
+    },
+  });
+
+  return { taskId: result.createTask.id };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
+  name: 'enrich-company',
+  description: 'Enrich a company record with external data',
+  timeoutSeconds: 10,
+  handler,
+  toolTriggerSettings: {},
+});
+```
+
+Основные моменты:
+
+* Функция может сочетать интерфейсы — объявите и `toolTriggerSettings`, и `workflowActionTriggerSettings`, чтобы сделать её доступной и в чате, и в конструкторе рабочих процессов.
+* `toolTriggerSettings.inputSchema` и `workflowActionTriggerSettings.inputSchema` — обе необязательны. Если они опущены, конструктор манифеста выводит их из исходного кода обработчика (JSON Schema — для инструмента ИИ, `InputSchema` от Twenty — для действия рабочего процесса). Укажите её явно, когда вам нужна более богатая типизация — например, с полями, учитывающими `FieldMetadataType`, такими как `CURRENCY` или `RELATION`, для конструктора рабочих процессов, или с полями `description`, которые может прочитать ИИ-агент:
+
+```ts
+export default defineLogicFunction({
+  ...,
+  toolTriggerSettings: {
+    inputSchema: {
+      type: 'object',
+      properties: {
+        companyName: {
+          type: 'string',
+          description: 'The name of the company to enrich',
+        },
+        domain: {
+          type: 'string',
+          description: 'The company website domain (optional)',
+        },
+      },
+      required: ['companyName'],
+    },
+  },
+});
+```
+
+Чтобы объявить параметры **один раз** и использовать их в обоих сценариях, определите одну JSON Schema (`InputJsonSchema`) и преобразуйте её для действия рабочего процесса с помощью `jsonSchemaToInputSchema` из `twenty-sdk/logic-function`. `toolTriggerSettings.inputSchema` принимает JSON Schema напрямую, в то время как `workflowActionTriggerSettings.inputSchema` ожидает `InputSchema` Twenty:
+
+```ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { jsonSchemaToInputSchema, type InputJsonSchema } from 'twenty-sdk/logic-function';
+
+const inputSchema: InputJsonSchema = {
+  type: 'object',
+  properties: {
+    companyName: { type: 'string', label: 'Company name' },
+    domain: { type: 'string', label: 'Domain' },
+  },
+  required: ['companyName'],
+};
+
+export default defineLogicFunction({
+  ...,
+  toolTriggerSettings: { inputSchema },
+  workflowActionTriggerSettings: {
+    label: 'Enrich Company',
+    icon: 'IconBuilding',
+    inputSchema: jsonSchemaToInputSchema(inputSchema),
+  },
+});
+```
+
+##### Полный пример действия рабочего процесса
+
+`workflowActionTriggerSettings` принимает четыре поля:
+
+| Поле           | Назначение                                                                                                                                                                                                    |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`        | Имя, отображаемое для действия в селекторе шагов конструктора рабочих процессов. По умолчанию используется `name` функции.                                                                                    |
+| `icon`         | Иконка, отображаемая рядом с действием (имя из `tabler-icons`, например, `IconBuilding`).                                                                                                                     |
+| `inputSchema`  | Расширенная схема ввода (`InputSchema`) Twenty — то, что конструктор отображает как настраиваемые поля (с выбором переменных). Необязательно; при отсутствии выводится из обработчика.                        |
+| `outputSchema` | Определяет структуру, которую возвращает обработчик, чтобы **последующие шаги могли сопоставлять свои данные с его выходными полями**. Необязательно; без неё вывод представлен одним непрозрачным значением. |
+
+Объединяя всё вместе — функция, представленная как действие рабочего процесса, с объявленным выходом, чтобы последующие шаги могли ссылаться на `taskId`:
+
+```ts src/logic-functions/enrich-company.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { jsonSchemaToInputSchema, type InputJsonSchema } from 'twenty-sdk/logic-function';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const inputSchema: InputJsonSchema = {
+  type: 'object',
+  properties: {
+    companyName: { type: 'string', label: 'Company name' },
+    domain: { type: 'string', label: 'Domain' },
+  },
+  required: ['companyName'],
+};
+
+const handler = async (params: { companyName: string; domain?: string }) => {
+  const client = new CoreApiClient();
+
+  const result = await client.mutation({
+    createTask: {
+      __args: {
+        data: {
+          title: `Enrich data for ${params.companyName}`,
+          body: `Domain: ${params.domain ?? 'unknown'}`,
+        },
+      },
+      id: true,
+    },
+  });
+
+  // The keys returned here should match the `outputSchema` properties below.
+  return { taskId: result.createTask.id, enriched: true };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
+  name: 'enrich-company',
+  description: 'Enrich a company record with external data',
+  timeoutSeconds: 10,
+  handler,
+  workflowActionTriggerSettings: {
+    label: 'Enrich Company',
+    icon: 'IconBuilding',
+    inputSchema: jsonSchemaToInputSchema(inputSchema),
+    outputSchema: [
+      {
+        type: 'object',
+        properties: {
+          taskId: { type: 'string' },
+          enriched: { type: 'boolean' },
+        },
+      },
+    ],
+  },
+});
+```
+
+После установки приложения **Enrich Company** появляется в селекторе действий конструктора рабочих процессов. Конструктор отображает `companyName` и `domain` как поля ввода (каждое может получать значения из предыдущих шагов), а последующие шаги могут ссылаться на выходные значения шага `taskId` и `enriched`.
+
+<Note>
+**Напишите хорошее описание в поле `description`.** Агенты ИИ опираются на поле `description` функции, чтобы решить, когда использовать инструмент. Чётко опишите, что делает инструмент и когда его следует вызывать.
+</Note>
+
+</Accordion>
+</AccordionGroup>
+
+<Note>
+**Вспомогательные функции времени выполнения.** `twenty-sdk/utils` повторно экспортирует небольшие вспомогательные функции времени выполнения, поэтому обработчики никогда не импортируют напрямую из `twenty-shared`. Например, `isDefined(value)` возвращает `false` как для `null`, так и для `undefined` — используйте её, чтобы безопасно сузить необязательные входные данные обработчика, которые могут приходить как `null` во время выполнения, даже если имеют тип `T | undefined`:
+
+```ts
+import { isDefined } from 'twenty-sdk/utils';
+
+const handler = async (params: { parentMessageId?: string }) => {
+  if (isDefined(params.parentMessageId)) {
+    // params.parentMessageId is narrowed to string here
+  }
+};
+```
+</Note>
+
+<Note>
+**Хуки установки** — обработчики до установки, после установки и при удалении — используют тот же рантайм, но объявляются с помощью собственных функций `define` и не принимают настройки триггеров. См. раздел [Install Hooks](/l/ru/developers/extend/apps/config/install-hooks) для `definePreInstallLogicFunction`, `definePostInstallLogicFunction` и `defineUninstallLogicFunction`.
+</Note>
+
+## Создание действия на временной шкале.
+
+Используйте `createTimelineActivity()` для публикации явного события домена из логической функции. Сначала определите событие как [тип действия на временной шкале](/l/ru/developers/extend/apps/data/timeline-activity-types), затем укажите тип и объекты с помощью их стабильных универсальных идентификаторов:
+
+```ts
+import { createTimelineActivity } from 'twenty-sdk/logic-function';
+
+await createTimelineActivity({
+  timelineActivityTypeUniversalIdentifier:
+    'f4fa646c-6e11-4d8f-a6be-c3b7a2fc7501',
+  targetObjectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+  targetRecordId: postCardId,
+  happensAt: new Date().toISOString(),
+  properties: {
+    deliveryProvider: 'postal-service',
+  },
+});
+```
+
+Twenty преобразует универсальные идентификаторы в идентификаторы метаданных, специфичные для установки, проверяет, что тип действия на временной шкале принадлежит вызывающему приложению, и сохраняет снимок его метаданных представления в новом действии.
+
+Обязательные входные параметры: `timelineActivityTypeUniversalIdentifier`, `targetObjectUniversalIdentifier` и `targetRecordId`. Также можно указать `happensAt`, `properties` и `workspaceMemberId`. `happensAt` управляет положением события и отображаемым временем на временной шкале; по умолчанию используется время создания.
+
+Чтобы связать с событием другую запись, укажите вместе `linkedRecordId` и `linkedObjectMetadataUniversalIdentifier`. Кроме того, можно указать `linkedRecordCachedName` в качестве резервного варианта отображения исторического имени:
+
+```ts
+await createTimelineActivity({
+  timelineActivityTypeUniversalIdentifier:
+    'f4fa646c-6e11-4d8f-a6be-c3b7a2fc7501',
+  targetObjectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+  targetRecordId: postCardId,
+  linkedObjectMetadataUniversalIdentifier: RECIPIENT_UNIVERSAL_IDENTIFIER,
+  linkedRecordId: recipientId,
+  linkedRecordCachedName: recipientName,
+});
+```
+
+Роли логической функции требуется разрешение на запись в стандартный объект `timelineActivity`. Не связывайте явные типы событий с `action`; тип, связанный с действием, уже получает автоматические события аудита и в противном случае создаст дублирующиеся строки.
+
+## Типизированные клиенты API (twenty-client-sdk)
+
+Пакет `twenty-client-sdk` предоставляет два типизированных клиента GraphQL для взаимодействия с API Twenty из ваших логических функций и фронт-компонентов.
+
+| Клиент              | Импорт                       | Конечная точка                                                    | Генерируется?                    |
+| ------------------- | ---------------------------- | ----------------------------------------------------------------- | -------------------------------- |
+| `CoreApiClient`     | `twenty-client-sdk/core`     | `/graphql` — данные рабочего пространства (записи, объекты)       | Да, на этапе dev/build           |
+| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — конфигурация рабочего пространства, загрузка файлов | Нет, поставляется в готовом виде |
+
+<AccordionGroup>
+<Accordion title="CoreApiClient" description="Запрос и изменение данных рабочего пространства (записи, объекты)">
+
+`CoreApiClient` — основной клиент для запросов и изменений данных рабочего пространства. Он **генерируется из схемы вашего рабочего пространства** во время `yarn twenty dev` или `yarn twenty dev:build`, поэтому полностью типизирован в соответствии с вашими объектами и полями.
+
+```ts
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const client = new CoreApiClient();
+
+// Query records
+const { companies } = await client.query({
+  companies: {
+    edges: {
+      node: {
+        id: true,
+        name: true,
+        domainName: {
+          primaryLinkLabel: true,
+          primaryLinkUrl: true,
+        },
+      },
+    },
+  },
+});
+
+// Create a record
+const { createCompany } = await client.mutation({
+  createCompany: {
+    __args: {
+      data: {
+        name: 'Acme Corp',
+      },
+    },
+    id: true,
+    name: true,
+  },
+});
+```
+
+Клиент использует синтаксис selection-set: передайте `true`, чтобы включить поле, используйте `__args` для аргументов и вкладывайте объекты для отношений. Вы получаете полное автодополнение и проверку типов на основе схемы вашего рабочего пространства.
+
+<Note>
+**CoreApiClient генерируется на этапе dev/build.** Если вы используете его, не запустив сначала `yarn twenty dev` или `yarn twenty dev:build`, он выбросит ошибку. Генерация происходит автоматически — CLI анализирует GraphQL-схему вашего рабочего пространства и создает типизированный клиент с помощью `@genql/cli`.
+</Note>
+
+#### Использование CoreSchema для аннотаций типов
+
+`CoreSchema` предоставляет типы TypeScript, соответствующие объектам вашего рабочего пространства — это полезно для типизации состояния компонентов или параметров функций:
+
+```ts
+import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
+import { useState } from 'react';
+
+const [company, setCompany] = useState<
+  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
+>(undefined);
+
+const client = new CoreApiClient();
+const result = await client.query({
+  company: {
+    __args: { filter: { position: { eq: 1 } } },
+    id: true,
+    name: true,
+  },
+});
+setCompany(result.company);
+```
+
+</Accordion>
+<Accordion title="MetadataApiClient" description="Конфигурация рабочего пространства, приложения и загрузка файлов">
+
+`MetadataApiClient` поставляется в готовом виде вместе с SDK (генерация не требуется). Он выполняет запросы к эндпоинту `/metadata` для получения конфигурации рабочего пространства, приложений и загрузки файлов. Он принимает тот же параметр `runAs`, что и `CoreApiClient` — см. [Чьи права доступа использует вызов](#whose-access-a-call-uses).
+
+```ts
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+
+const metadataClient = new MetadataApiClient();
+
+// List first 10 objects in the workspace
+const { objects } = await metadataClient.query({
+  objects: {
+    edges: {
+      node: {
+        id: true,
+        nameSingular: true,
+        namePlural: true,
+        labelSingular: true,
+        isCustom: true,
+      },
+    },
+    __args: {
+      filter: {},
+      paging: { first: 10 },
+    },
+  },
+});
+```
+
+#### Загрузка файлов
+
+`MetadataApiClient` включает метод `uploadFile` для прикрепления файлов к полям типа файла:
+
+```ts
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import * as fs from 'fs';
+
+const metadataClient = new MetadataApiClient();
+
+const fileBuffer = fs.readFileSync('./invoice.pdf');
+
+const uploadedFile = await metadataClient.uploadFile(
+  fileBuffer,                                         // file contents as a Buffer
+  'invoice.pdf',                                      // filename
+  'application/pdf',                                  // MIME type
+  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+);
+
+console.log(uploadedFile);
+// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
+```
+
+| Параметр                           | Тип      | Описание                                                           |
+| ---------------------------------- | -------- | ------------------------------------------------------------------ |
+| `fileBuffer`                       | `Buffer` | Необработанное содержимое файла                                    |
+| `filename`                         | `string` | Имя файла (используется для хранения и отображения)                |
+| `contentType`                      | `string` | Тип MIME (по умолчанию `application/octet-stream`, если не указан) |
+| `fieldMetadataUniversalIdentifier` | `string` | Значение `universalIdentifier` для поля типа файла в вашем объекте |
+
+Основные моменты:
+* Он использует `universalIdentifier` поля (а не его идентификатор, специфичный для рабочего пространства), поэтому ваш код загрузки будет работать в любом рабочем пространстве, где установлено ваше приложение.
+* Возвращаемый `url` — это подписанный URL, который можно использовать для доступа к загруженному файлу.
+
+</Accordion>
+</AccordionGroup>
+
+<Note>
+  Когда ваш код выполняется на Twenty (логические функции или фронт-компоненты), платформа предоставляет учётные данные в виде переменных окружения:
+
+  * `TWENTY_API_URL` — базовый URL API Twenty
+  * `TWENTY_APP_ACCESS_TOKEN` — краткоживущий ключ для прав доступа по умолчанию: роль человека пересекается с ролью вашего приложения, когда за запуском кто-то стоит; если никто не стоит — используется собственная роль вашего приложения. В логической функции человек — это тот, кто вызвал запуск, а во фронтенд-компоненте — тот, кто просматривает страницу.
+  * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — краткоживущий ключ, ограниченный исключительно собственной ролью вашего приложения. Только для логических функций, всегда внедряется в них и используется `runAs: 'application'`.
+
+  Вам **не** нужно передавать их клиентам — они автоматически считываются из `process.env`, а в разделе [Чьи права доступа использует вызов](#whose-access-a-call-uses) описан выбор между ними. Собственные разрешения вашего приложения определяются ролью, объявленной с помощью `defineApplicationRole()` (или указанной через `defaultRoleUniversalIdentifier` в `application-config.ts`); запуск, действующий от имени человека, никогда не может превысить ни эту роль, ни его собственную.
+</Note>

packages/twenty-docs/l/ru/developers/extend/apps/logic/overview.mdx

@@ -0,0 +1,61 @@
+---
+title: Обзор
+description: Серверный TypeScript, который выполняется внутри Twenty — запускается HTTP-маршрутами, расписаниями cron, событиями базы данных, инструментами ИИ или действиями рабочих процессов.
+icon: bolt
+---
+
+**Логический слой** приложения Twenty — это код, который *выполняется*: серверные обработчики TypeScript, реагирующие на HTTP-запросы, расписания cron и изменения записей; навыки ИИ и агенты, работающие внутри рабочего пространства; а также OAuth-подключения, позволяющие вашим функциям действовать от имени пользователя в сторонних сервисах.
+
+```text
+            ┌─ HTTP route      ──┐
+            │  Cron schedule     │
+            │  Database event    │      ┌────────────────────┐
+  triggers ─┤  AI tool call      ├─────▶│ Logic function     │
+            │  Workflow action   │      │ (your handler)     │
+            │  Manual exec       │      └────────────────────┘
+            └────────────────────┘                │
+                                                  ▼
+                                  ┌────────────────────────────┐
+                                  │ Twenty API (records)       │
+                                  │ Third-party API            │
+                                  │   (via Connection token)   │
+                                  └────────────────────────────┘
+```
+
+## В этом разделе
+
+<CardGroup cols={2}>
+  <Card title="Логические функции" icon="bolt" href="/l/ru/developers/extend/apps/logic/logic-functions">
+    Основной строительный блок — типы триггеров, полезные данные (payloads) и типизированный клиент API.
+  </Card>
+  <Card title="Навыки и агенты" icon="robot" href="/l/ru/developers/extend/apps/logic/skills-and-agents">
+    Повторно используемые инструкции агента ИИ и ассистенты с пользовательскими системными подсказками.
+  </Card>
+  <Card title="Подключения" icon="plug" href="/l/ru/developers/extend/apps/logic/connections">
+    OAuth-учетные данные, которые ваше приложение хранит для сторонних сервисов — Linear, GitHub, Slack и других.
+  </Card>
+  <Card title="Хранилище ключ-значение" icon="database" href="/l/ru/developers/extend/apps/logic/key-value-store">
+    Сохраняйте состояние между запусками логических функций — кэши, курсоры и утверждения между рабочими пространствами.
+  </Card>
+  <Card title="Фоновые задания" icon="layer-group" href="/l/ru/developers/extend/apps/logic/background-jobs">
+    Поставьте функцию Logic в очередь на исполнение воркерами, чтобы обойти таймаут на один запуск.
+  </Card>
+</CardGroup>
+
+## Типы триггеров вкратце
+
+Логическая функция выбирает один или несколько триггеров — каждая запись ниже — это отдельное поле в `defineLogicFunction()`:
+
+| Триггер                        | Когда запускается                                                    | Настройка                       |
+| ------------------------------ | -------------------------------------------------------------------- | ------------------------------- |
+| **HTTP-маршрут**               | Запрос попадает на вашу конечную точку `/s/\<path>` | `httpRouteTriggerSettings`      |
+| **Cron**                       | Срабатывает выражение CRON                                           | `cronTriggerSettings`           |
+| **Событие базы данных**        | Запись рабочего пространства создается, обновляется или удаляется    | `databaseEventTriggerSettings`  |
+| **Инструмент ИИ**              | Возможность Twenty AI решает вызвать вашу функцию                    | `toolTriggerSettings`           |
+| **Действие рабочего процесса** | Шаг рабочего процесса вызывает вашу функцию                          | `workflowActionTriggerSettings` |
+
+Функции выполняются в изолированных процессах Node.js в песочнице и получают доступ к рабочему пространству через типизированный клиент API с областью действия, ограниченной ролью, объявленной в [`defineApplication()`](/l/ru/developers/extend/apps/config/application).
+
+<Note>
+**Хуки времени установки** — код, который выполняется до или после установки, — используют то же окружение выполнения, но свои собственные функции `define*` и находятся в разделе [Config → Install Hooks](/l/ru/developers/extend/apps/config/install-hooks).
+</Note>

packages/twenty-docs/l/ru/developers/extend/apps/logic/skills-and-agents.mdx

@@ -0,0 +1,180 @@
+---
+title: Навыки и агенты
+description: Определите навыки и агентов ИИ для вашего приложения.
+icon: robot
+---
+
+<Warning>
+  Навыки и агенты сейчас проходят альфа-тестирование. Функция работает, но продолжает развиваться.
+</Warning>
+
+Приложения могут определять возможности ИИ, которые находятся внутри рабочего пространства — повторно используемые инструкции для навыков и агенты с настраиваемыми системными подсказками.
+
+<AccordionGroup>
+<Accordion title="defineSkill" description="Определяйте навыки ИИ-агентов">
+
+Навыки определяют многократно используемые инструкции и возможности, которые агенты ИИ могут использовать в вашем рабочем пространстве. Используйте `defineSkill()` для определения навыков со встроенной валидацией:
+
+```ts src/skills/example-skill.ts
+import { defineSkill } from 'twenty-sdk/define';
+
+export default defineSkill({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'sales-outreach',
+  label: 'Sales Outreach',
+  description: 'Guides the AI agent through a structured sales outreach process',
+  icon: 'IconBrain',
+  content: `You are a sales outreach assistant. When reaching out to a prospect:
+1. Research the company and recent news
+2. Identify the prospect's role and likely pain points
+3. Draft a personalized message referencing specific details
+4. Keep the tone professional but conversational`,
+});
+```
+
+Основные моменты:
+* `name` — уникальная строка-идентификатор навыка (рекомендуется kebab-case).
+* `label` — читаемое человеком отображаемое имя, показываемое в UI.
+* `content` содержит инструкции навыка — это текст, который использует агент ИИ.
+* `icon` (необязательно) задаёт значок, отображаемый в UI.
+* `description` (необязательно) предоставляет дополнительный контекст о назначении навыка.
+
+</Accordion>
+<Accordion title="defineAgent" description="Определяйте ИИ-агентов с пользовательскими промптами">
+
+Агенты — это ИИ-помощники, работающие в вашем рабочем пространстве. Используйте `defineAgent()` для создания агентов с пользовательским системным промптом:
+
+```ts src/agents/example-agent.ts
+import { defineAgent } from 'twenty-sdk/define';
+
+export default defineAgent({
+  universalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
+  name: 'sales-assistant',
+  label: 'Sales Assistant',
+  description: 'Helps the sales team draft outreach emails and research prospects',
+  icon: 'IconRobot',
+  prompt: 'You are a helpful sales assistant. Help users with their questions and tasks.',
+});
+```
+
+Основные моменты:
+* `name` — уникальная строка-идентификатор агента (рекомендуется kebab-case).
+* `label` — отображаемое имя, показываемое в UI.
+* `prompt` — это системный промпт, определяющий поведение агента.
+* `description` (необязательно) предоставляет контекст о том, что делает агент.
+* `icon` (необязательно) задаёт значок, отображаемый в UI.
+* `modelId` (необязательно) переопределяет модель ИИ по умолчанию, используемую агентом.
+* `responseFormat` (необязательно) определяет форму вывода агента. По умолчанию для свободного текста используется `{ type: 'text' }`. Используйте `{ type: 'json', schema }`, чтобы принудительно получать структурированный JSON-вывод.
+
+По умолчанию агент возвращает свободный текст. Чтобы получить структурированный вывод, установите для `responseFormat` значение `{ type: 'json' }` и укажите `schema`:
+
+```ts src/agents/structured-agent.ts
+import { defineAgent } from 'twenty-sdk/define';
+
+export default defineAgent({
+  universalIdentifier: 'c4d5e6f7-a8b9-0123-cdef-456789012345',
+  name: 'lead-scorer',
+  label: 'Lead Scorer',
+  prompt: 'Score the lead and explain your reasoning.',
+  responseFormat: {
+    type: 'json',
+    schema: {
+      type: 'object',
+      properties: {
+        score: { type: 'number', description: 'Lead score from 0 to 100' },
+        summary: { type: 'string', description: 'Short reasoning for the score' },
+      },
+      required: ['score', 'summary'],
+      additionalProperties: false,
+    },
+  },
+});
+```
+
+Примечания к схеме:
+* Схема — это плоский объект: `type` каждого свойства должен быть примитивом (`string`, `number` или `boolean`). Вложенные объекты и массивы не поддерживаются.
+* `description` (необязательно) для каждого свойства подсказывает модели, что туда нужно поместить.
+* `required` (необязательно) перечисляет свойства, которые модель всегда должна возвращать.
+* `additionalProperties: false` (необязательно) запрещает любые свойства, не объявленные в `properties`.
+
+</Accordion>
+<Accordion title="runAgent" description="Запуск агента из логической функции">
+
+`runAgent()` позволяет логической функции запустить одного из агентов вашего приложения (с его навыками и инструментами). Идентифицируйте агента по `universalIdentifier`, который вы передали в `defineAgent()`. Передайте либо строку `prompt`, либо историю диалога `messages` — но не оба варианта одновременно:
+
+```ts src/logic-functions/run-enricher.ts
+import { runAgent } from 'twenty-sdk/logic-function';
+
+const { result, error, success } = await runAgent({
+  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
+  prompt: 'Enrich House Ad <recordId>: fill empty fields from its listing URL.',
+});
+```
+
+Для многошаговых ботов (Slack, Discord, Teams, …) передавайте историю треда как `messages` вместо одного `prompt`:
+
+```ts src/logic-functions/reply-in-thread.ts
+import { runAgent } from 'twenty-sdk/logic-function';
+
+const { result, error, success } = await runAgent({
+  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
+  messages: [
+    { role: 'user', content: 'Who owns Acme?' },
+    { role: 'assistant', content: 'Sarah owns the Acme account.' },
+    { role: 'user', content: 'What was the last touchpoint?' },
+  ],
+});
+```
+
+Основные моменты:
+* Укажите **ровно один** из `prompt` (строка) или `messages` (от 1 до 100 элементов
+  вида `{ role: 'user' | 'assistant', content: string }`).
+* Агент выполняется **синхронно** и может самостоятельно читать и обновлять записи с помощью собственных инструментов — `runAgent()` возвращает результат после завершения выполнения.
+* Приложение может запускать только собственных агентов.
+* [Роль по умолчанию](/l/ru/developers/extend/apps/config/roles) приложения должна предоставлять флаг разрешения `AI` — добавьте `SystemPermissionFlag.AI` в `permissionFlagUniversalIdentifiers` (или установите `canAccessAllTools: true`).
+  Без этого `runAgent()` завершится с ошибкой прав доступа.
+* Установите достаточно большое значение `timeoutSeconds` для логической функции — выполнение агента может занимать несколько секунд.
+* `success` имеет значение `true`, а `result` — не `null`, когда запуск завершается; при ошибке `success` равно `false`, `result` равно `null`, а в `error` содержится причина (например, если в рабочем пространстве закончились AI-кредиты во время запуска).
+
+```ts src/roles/default-role.ts
+import { defineApplicationRole, SystemPermissionFlag } from 'twenty-sdk/define';
+
+export default defineApplicationRole({
+  universalIdentifier: 'b648f87b-1d26-4961-b974-0908fd991061',
+  label: 'Default function role',
+  // runAgent() requires the AI permission flag on the app's default role.
+  permissionFlagUniversalIdentifiers: [SystemPermissionFlag.AI],
+});
+```
+
+<Warning>
+  **Избегайте циклов:** если вы вызываете `runAgent()` из триггера события базы данных `*.updated`, и агент обновляет ту же запись, ограничьте триггер, указав в `updatedFields` поле, которое агент никогда не изменяет (например, исходный URL), или добавьте проверку, что хотя бы одно целевое поле всё ещё пусто, прежде чем вызывать `runAgent()`.
+</Warning>
+
+### Запуск от имени участника рабочего пространства
+
+Передавайте `runAsWorkspaceMemberId`, когда запуск инициирован человеком — например, чат-ботом, отвечающим на сообщение, — чтобы агент действовал как этот участник, а не как приложение:
+
+```ts src/logic-functions/answer-question.ts
+const { result } = await runAgent({
+  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
+  prompt: 'How many open opportunities do we have?',
+  runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
+});
+```
+
+Затем запуск выполняется с **собственной ролью участника**: он может делать всё, что может делать этот участник, и не больше; созданные им записи приписываются этому участнику, и к ним применяются его разрешения на уровне строк. Роль агента в этом не участвует — это роль по умолчанию приложения для запусков, за которыми никто не стоит. Опускайте это поле для автономных запусков (плановые задания, триггеры событий базы данных): в таких случаях сохраняется собственная роль агента. Действующее приложение остаётся привязанным к контексту запуска для отслеживания происхождения, не сужая при этом полномочий участника.
+
+Ваше приложение отвечает за сопоставление человека, который инициировал запуск, с участником рабочего пространства. Чтобы указать участника, требуется токен доступа приложения; то, кого можно указать с помощью токена, зависит от того, привязан ли к нему пользователь:
+
+* Токен **без привязанного пользователя** может указать любого участника. Логическая функция выполняется с таким токеном; то же относится к токенам, выпущенным через `client_credentials` или на основе API‑ключа.
+* Токен, выданный **от имени пользователя** (как у фронтенд‑компонента), может указывать только на участника самого этого пользователя.
+
+Все остальное — обычная пользовательская сессия, API‑ключ без токена приложения — вообще не может указывать участника.
+
+<Warning>
+  `runAgent()` генерирует исключение, если не удаётся определить участника рабочего пространства — неизвестного или удалённого участника, либо участника без роли. При этом никогда не используется роль самого агента, так как это предоставило бы больше прав доступа, чем запросил вызывающий код.
+</Warning>
+
+</Accordion>
+</AccordionGroup>

packages/twenty-docs/l/ru/developers/extend/apps/operations/cli.mdx

@@ -0,0 +1,131 @@
+---
+title: CLI
+description: Команды `yarn twenty` для выполнения функций, потоковой передачи логов, управления установками приложений и переключения удалённых серверов.
+icon: terminal
+---
+
+CLI `yarn twenty` — ваш инструмент для всего, что связано с приложением. Полный список команд:
+
+| Команда                                         | Что делает                                                                               | Описано в                                                                                          |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `dev`                                           | Отслеживает исходные файлы и синхронизирует изменения в реальном времени                 | [Краткое руководство](/l/ru/developers/extend/apps/getting-started/quick-start)                         |
+| `план`                                          | Предпросмотр изменений метаданных без их применения                                      | [Syncing & recovery](/l/ru/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) |
+| `применить`                                     | Применить изменения метаданных после показа плана                                        | [Syncing & recovery](/l/ru/developers/extend/apps/operations/sync-and-recovery)                         |
+| `dev:build`                                     | Скомпилировать приложение и сгенерировать API‑клиент (`--tarball` для упаковки в `.tgz`) | [Публикация](/l/ru/developers/extend/apps/operations/publishing)                                        |
+| `dev:typecheck`                                 | Запустить проверку типов TypeScript                                                      | [Тестирование](/l/ru/developers/extend/apps/operations/testing)                                         |
+| `dev:add`                                       | Создать каркас новой сущности                                                            | [Создание каркаса](/l/ru/developers/extend/apps/getting-started/scaffolding)                            |
+| `dev:generate-client`                           | Повторно сгенерировать типизированный API‑клиент                                         | эта страница                                                                                       |
+| `dev:function:exec` / `dev:function:logs`       | Выполнять функции и транслировать их логи                                                | эта страница                                                                                       |
+| `dev:translations-extract`                      | Извлечь переводимые строки в каталоги `locales/`                                         | [Переводы](/l/ru/developers/extend/apps/operations/translations)                                          |
+| `dev:catalog-sync`                              | Запустить синхронизацию каталога маркетплейса                                            | [Публикация](/l/ru/developers/extend/apps/operations/publishing#how-marketplace-discovery-works)        |
+| `app:publish` / `app:install` / `app:uninstall` | Жизненный цикл релиза                                                                    | [Публикация](/l/ru/developers/extend/apps/operations/publishing) и эта страница                         |
+| `docker:*`                                      | Управлять локальным контейнером сервера Twenty                                           | [Локальный сервер](/l/ru/developers/extend/apps/getting-started/local-server)                           |
+| `remote:*`                                      | Управлять подключениями к серверам                                                       | эта страница                                                                                       |
+
+Каждая команда принимает параметр `-r, --remote \<name>`, чтобы указать конкретное удалённое подключение вместо подключения по умолчанию.
+
+## Выполнение функций (`yarn twenty dev:function:exec`)
+
+Запустите логическую функцию вручную, не вызывая её через HTTP, cron или событие базы данных:
+
+```bash filename="Terminal"
+# Execute by function name
+yarn twenty dev:function:exec -n create-new-post-card
+
+# Execute by universalIdentifier
+yarn twenty dev:function:exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
+
+# Pass a JSON payload
+yarn twenty dev:function:exec -n create-new-post-card -p '{"name": "Hello"}'
+
+# Execute the install and uninstall hooks
+yarn twenty dev:function:exec --postInstall
+yarn twenty dev:function:exec --preInstall
+yarn twenty dev:function:exec --uninstall
+```
+
+## Просмотр логов функций (`yarn twenty dev:function:logs`)
+
+Потоковая передача журналов выполнения логических функций вашего приложения:
+
+```bash filename="Terminal"
+# Stream all function logs
+yarn twenty dev:function:logs
+
+# Filter by function name
+yarn twenty dev:function:logs -n create-new-post-card
+
+# Filter by universalIdentifier
+yarn twenty dev:function:logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
+```
+
+<Note>
+Это отличается от `yarn twenty docker:logs`, который показывает логи контейнера Docker. `yarn twenty dev:function:logs` показывает журналы выполнения функций вашего приложения с сервера Twenty.
+</Note>
+
+## Генерация типизированного клиента (`yarn twenty dev:generate-client`)
+
+Повторно сгенерируйте типизированный API‑клиент (`twenty-client-sdk`) из схемы активного удалённого экземпляра, не выполняя сборку или синхронизацию приложения. Используйте это, чтобы получить типизированного клиента в любом проекте — например, в backend‑сервисе в отдельном репозитории — который взаимодействует с вашим экземпляром Twenty:
+
+```bash filename="Terminal"
+# In your project (no Twenty app definition required)
+yarn add twenty-sdk twenty-client-sdk
+
+# Connect to the Twenty instance to generate the client from
+yarn twenty remote:add
+
+# Generate the typed client into node_modules/twenty-client-sdk
+yarn twenty dev:generate-client
+```
+
+Затем импортируйте клиента в свой код:
+
+```typescript
+import { CoreApiClient } from 'twenty-client-sdk/core';
+```
+
+Повторно запустите команду при каждом изменении вашей модели данных, чтобы обновить сгенерированные типы.
+
+<Note>
+Клиент генерируется внутри `node_modules`, поэтому он не добавляется в ваш репозиторий вместе с кодом. Запускайте `yarn twenty dev:generate-client` после каждой установки (например, в скрипте `postinstall` или в CI).
+</Note>
+
+## Удаление приложения (`yarn twenty app:uninstall`)
+
+Удалите свое приложение из активного рабочего пространства:
+
+```bash filename="Terminal"
+yarn twenty app:uninstall
+
+# Skip the confirmation prompt
+yarn twenty app:uninstall --yes
+```
+
+## Управление удалёнными серверами
+
+**Remote** — это сервер Twenty, к которому подключается ваше приложение. Во время настройки скаффолдер автоматически создаст его для вас. Вы можете в любой момент добавлять новые удалённые серверы или переключаться между ними.
+
+```bash filename="Terminal"
+# Add a new remote (opens a browser for OAuth login)
+yarn twenty remote:add
+
+# Connect to a local Twenty server (auto-detects port 2020 or 3000)
+yarn twenty remote:add --local
+
+# Add a remote non-interactively (useful for CI)
+yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote
+
+# List all configured remotes
+yarn twenty remote:list
+
+# Set the active remote
+yarn twenty remote:use <name>
+
+# Check that the active remote's authentication is still valid
+yarn twenty remote:status
+
+# Remove a remote
+yarn twenty remote:remove <name>
+```
+
+Ваши учётные данные хранятся в `~/.twenty/config.json`.

packages/twenty-docs/l/ru/developers/extend/apps/operations/overview.mdx

@@ -0,0 +1,32 @@
+---
+title: Обзор
+description: Собирайте, тестируйте и поставляйте свое приложение — команды CLI, интеграционные тесты, CI и публикация на сервер или в npm.
+icon: rocket
+---
+
+**Операционный уровень** — это все, что вы делаете *над* своим приложением, а не *с ним*: выполнение команд CLI, запуск интеграционных тестов на реальном сервере Twenty, настройка CI и поставка релизов — либо в виде tar-архива, разворачиваемого на одном сервере, либо как пакет npm, размещенный в маркетплейсе.
+
+```text
+   develop ─▶ test ─▶ build ─▶ deploy / publish
+   ───────    ────    ─────    ─────────────────
+   yarn       yarn    yarn     yarn twenty app:publish --private  (tarball → one server)
+   twenty     test    twenty
+   dev                dev:build    yarn twenty app:publish         (npm → marketplace)
+```
+
+## В этом разделе
+
+<CardGroup cols={2}>
+  <Card title="CLI" icon="terminal" href="/l/ru/developers/extend/apps/operations/cli">
+    Справочник по `yarn twenty` — exec, logs, uninstall, remotes.
+  </Card>
+  <Card title="Синхронизация и восстановление" icon="compass" href="/l/ru/developers/extend/apps/operations/sync-and-recovery">
+    Какие команды когда использовать, как читать diff синхронизации и пошаговое восстановление.
+  </Card>
+  <Card title="Тестирование" icon="flask" href="/l/ru/developers/extend/apps/operations/testing">
+    Настройка Vitest, интеграционные тесты, проверка типов, рабочий процесс CI.
+  </Card>
+  <Card title="Публикация" icon="upload" href="/l/ru/developers/extend/apps/operations/publishing">
+    Сборка, развертывание tarball, публикация в npm, установка.
+  </Card>
+</CardGroup>

packages/twenty-docs/l/ru/developers/extend/apps/operations/publishing.mdx

@@ -0,0 +1,293 @@
+---
+title: Публикация
+icon: upload
+description: Распространяйте своё приложение Twenty в маркетплейсе или разверните его для внутреннего использования.
+---
+
+## Обзор
+
+После того как ваше приложение [собрано и протестировано локально](/l/ru/developers/extend/apps/getting-started/concepts), у вас есть два пути для его распространения:
+
+* **Разверните tar-архив** — загрузите своё приложение напрямую на конкретный сервер Twenty для внутреннего или частного использования.
+* **Опубликовать в npm** — разместите ваше приложение в маркетплейсе Twenty, чтобы любое рабочее пространство могло его найти и установить.
+
+Оба пути начинаются с одного и того же шага **build**.
+
+## Сборка вашего приложения
+
+Выполните команду сборки, чтобы скомпилировать приложение и сгенерировать готовый к распространению `manifest.json`:
+
+```bash filename="Terminal"
+yarn twenty dev:build
+```
+
+Это компилирует исходные файлы TypeScript, транспилирует функции логики и фронтенд-компоненты и записывает всё в `.twenty/output/`. Добавьте `--tarball`, чтобы также создать пакет `.tgz` для ручного распространения или для команды publish.
+
+## Развертывание на сервер (tarball)
+
+Для приложений, которые вы не хотите делать общедоступными — собственные инструменты, интеграции только для предприятий или экспериментальные сборки — вы можете развернуть tarball напрямую на сервер Twenty.
+
+### Требования
+
+Перед развертыванием вам нужен настроенный remote, указывающий на целевой сервер. Remotes локально хранят URL сервера и учётные данные аутентификации в `~/.twenty/config.json`.
+
+Добавьте remote:
+
+```bash filename="Terminal"
+yarn twenty remote:add --url https://your-twenty-server.com --as production
+```
+
+### Развертывание
+
+Соберите и загрузите ваше приложение на сервер в одном шаге:
+
+```bash filename="Terminal"
+yarn twenty app:publish --private
+# To deploy to a specific remote:
+# yarn twenty app:publish --private --remote production
+```
+
+### Общий доступ к развернутому приложению
+
+Приложения в формате tarball не отображаются в публичном маркетплейсе, поэтому другие рабочие пространства на том же сервере не найдут их при просмотре. Чтобы поделиться развернутым приложением:
+
+1. Перейдите в **Настройки > Приложения > Регистрации** и откройте ваше приложение
+2. На вкладке **Распространение** нажмите **Копировать ссылку для общего доступа**
+3. Поделитесь этой ссылкой с пользователями в других рабочих пространствах — она ведёт их прямо на страницу установки приложения
+
+Ссылка общего доступа использует базовый URL сервера (без какого-либо поддомена рабочего пространства), поэтому она работает для любого рабочего пространства на сервере.
+
+### Управление версиями
+
+При обновлении уже развернутого tarball-приложения сервер требует, чтобы значение `version` в `package.json` было **строго выше** (согласно упорядочиванию по [semver](https://semver.org)), чем текущая развернутая версия. Повторное развёртывание той же версии или публикация более низкой версии отклоняются до сохранения tarball — в CLI вы увидите ошибку `VERSION_ALREADY_EXISTS`.
+
+Чтобы выпустить обновление:
+
+1. Увеличьте значение поля `version` в вашем `package.json` (например: `1.2.3` → `1.2.4`, `1.3.0` или `2.0.0`).
+2. Выполните `yarn twenty app:publish --private` (или `yarn twenty app:publish --private --remote production`)
+3. Рабочие пространства, в которых приложение установлено и для него включено автообновление (на вкладке «Настройки» приложения), обновляются автоматически в фоновом режиме; в остальных рабочих пространствах пользователи увидят доступное обновление в своих настройках
+
+<Note>
+Пререлизные теги работают как ожидается: повышение версии `1.0.0-rc.1` → `1.0.0-rc.2` допускается, а финальный релиз вроде `1.0.0` корректно распознаётся как более высокий, чем `1.0.0-rc.5`. Версия в `package.json` должна сама по себе быть корректной строкой semver.
+</Note>
+
+{/* TODO: add screenshot of the Upgrade button */}
+
+### Совместимость версий сервера
+
+Если ваше приложение использует функцию, появившуюся в конкретной версии сервера Twenty (например, провайдеры OAuth, добавленные в v2.3.0), следует объявить минимальную требуемую версию сервера с помощью поля `engines.twenty` в `package.json`:
+
+```json filename="package.json"
+{
+  "name": "twenty-my-app",
+  "version": "1.0.0",
+  "engines": {
+    "node": "^24.5.0",
+    "twenty": ">=2.3.0"
+  }
+}
+```
+
+Значение — это стандартный [диапазон semver](https://github.com/npm/node-semver#ranges). Типовые шаблоны:
+
+| Диапазон                           | Значение                                           |
+| ---------------------------------- | -------------------------------------------------- |
+| `>=2.3.0`                          | Любой сервер версии 2.3.0 и новее                  |
+| `>=2.3.0 \<3.0.0` | 2.3.0 или новее, но ниже следующей мажорной версии |
+| `^2.3.0`                           | То же, что и `>=2.3.0 \<3.0.0`    |
+
+**Что происходит при развёртывании и установке:**
+
+* Если `engines.twenty` задано и версия целевого сервера не удовлетворяет диапазону, развёртывание (загрузка tarball-архива) или установка отклоняются с ошибкой `SERVER_VERSION_INCOMPATIBLE` и сообщением, указывающим как требуемый диапазон, так и фактическую версию сервера.
+* Если `engines.twenty` **не задано**, приложение принимается на сервере любой версии (обратная совместимость с существующими приложениями).
+* Если на сервере `APP_VERSION` не задано, проверка пропускается.
+
+<Note>
+Сервер выполняет окончательную проверку — он проверяет `engines.twenty` как при загрузке tarball-архива, так и при установке в рабочем пространстве. Если вы развёртываете tarball вне стандартного процесса или устанавливаете из маркетплейса, сервер всё равно принудительно проверяет совместимость.
+</Note>
+
+## Автоматизированный CI/CD (рабочие процессы, сгенерированные шаблоном)
+
+Приложения, созданные с помощью `create-twenty-app`, «из коробки» включают три рабочих процесса GitHub Actions в каталоге `.github/workflows/`. CI запускается без какой-либо настройки, для CD требуется один секрет, а публикация в npm требует однократной настройки доверенного издателя npm (trusted-publisher).
+
+### CI — `ci.yml`
+
+Автоматически запускает интеграционные тесты при каждом пуше в `main` и для каждого pull request.
+
+**Что делает:**
+
+1. Извлекает исходный код вашего приложения.
+2. Запускает изолированный тестовый экземпляр Twenty с помощью составного действия `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` (эквивалент для CI `yarn twenty docker:start --test`).
+3. Включает Corepack, настраивает Node.js на основе вашего `.nvmrc` и устанавливает зависимости с помощью `yarn install --immutable`.
+4. Запускает `yarn test`, передавая `TWENTY_API_URL` и `TWENTY_API_KEY` из запущенного экземпляра, чтобы ваши тесты могли взаимодействовать с реальным сервером.
+
+**Параметры конфигурации:**
+
+* `TWENTY_VERSION` (переменная окружения, по умолчанию `latest`) — зафиксируйте версию сервера Twenty, используемую в CI, отредактировав это значение в `ci.yml`.
+* Параллельные запуски группируются по `github.ref` и отменяют выполняющиеся прогоны при новых пушах.
+
+Секреты не требуются — тестовый экземпляр эфемерен и существует только на время выполнения задания.
+
+### CD — `cd.yml`
+
+Разворачивает ваше приложение на настроенном сервере Twenty при каждом пуше в `main` и, при необходимости, из pull request при наличии метки `deploy`.
+
+**Что делает:**
+
+1. Извлекает head-коммит PR (для PR с меткой) или запушенный коммит.
+2. Запускает `twentyhq/twenty/.github/actions/deploy-twenty-app@main` — эквивалент для CI `yarn twenty app:publish --private`.
+3. Запускает `twentyhq/twenty/.github/actions/install-twenty-app@main`, чтобы новая развернутая версия была установлена в целевое рабочее пространство.
+
+**Обязательная конфигурация:**
+
+| Настройка               | Где                                                                   | Назначение                                                                                                              |
+| ----------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `TWENTY_DEPLOY_URL`     | `env` в `cd.yml` (по умолчанию `http://localhost:3000`)               | Сервер Twenty, на который выполняется деплой. Перед первым использованием замените это на URL вашего реального сервера. |
+| `TWENTY_DEPLOY_API_KEY` | В репозитории GitHub — **Settings → Secrets and variables → Actions** | Ключ API с правом деплоя на целевом сервере.                                                                            |
+
+<Note>
+Значение `TWENTY_DEPLOY_URL` по умолчанию — `http://localhost:3000` — это заглушка: с хостируемого GitHub раннера к ней не будет доступа. Перед включением CD замените его на публичный URL вашего сервера (или используйте self-hosted раннер с сетевым доступом).
+</Note>
+
+**Запуск предварительного деплоя из PR:**
+
+Добавьте к pull request метку `deploy`. Условие `if:` в `cd.yml` запустит задачу для этого PR, используя его head-коммит, что позволит проверить изменение на целевом сервере до слияния.
+
+### Публикация — `publish.yml`
+
+Публикует ваше приложение в npm с указанием происхождения (provenance), когда вы отправляете тег версии (например, `v1.0.0`), или когда вы запускаете рабочий процесс вручную на вкладке Actions.
+
+**Что делает:**
+
+1. Клонирует ваше приложение, настраивает Node.js и обновляет npm (для доверенной публикации требуется npm версии 11.5.1 или новее).
+2. Запускает `yarn twenty app:publish`, который собирает приложение и публикует `.twenty/output` в npm. В CI он автоматически добавляет `--provenance` и `--access public`, поэтому в рабочем процессе флаги не требуются.
+
+**Первоначальная настройка:**
+
+На npmjs.com откройте свой пакет > **Settings → Trusted Publisher** и зарегистрируйте этот репозиторий, указав рабочий процесс `publish.yml` (см. [документацию по доверенной публикации в npm](https://docs.npmjs.com/trusted-publishers)). Публикация с provenance подтверждает, какой репозиторий GitHub собрал пакет, а также позволяет вам заявить права на ваше приложение в маркетплейсе Twenty.
+
+<Note>
+npm принимает подтверждение происхождения только из **публичных** репозиториев с исходным кодом. Если вы публикуете из приватного репозитория, npm отклоняет пакет подтверждения происхождения OIDC с ошибкой `E422 ... Ошибка `Unsupported GitHub Actions source repository visibility: "private"`. Чтобы публиковать из приватного репозитория, отключите подтверждение происхождения, установив `TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'`в`env`шага публикации (закомментированная подсказка включена в сгенерированный`publish.yml\`):
+
+```yaml filename=".github/workflows/publish.yml"
+      - name: Publish to npm
+        env:
+          TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'
+        run: yarn twenty app:publish
+```
+</Note>
+
+### Закрепление версий повторно используемых действий
+
+Рабочие процессы `ci.yml` и `cd.yml` ссылаются на повторно используемые действия с указанием `@main`, поэтому обновления действий в репозитории `twentyhq/twenty` подхватываются автоматически. Если вам нужны детерминированные сборки, замените `@main` на SHA коммита или тег релиза в каждой строке `uses:`.
+
+## Публикация в npm
+
+Публикация в npm делает ваше приложение видимым в маркетплейсе Twenty. Любое рабочее пространство Twenty может просматривать, устанавливать и обновлять приложения из маркетплейса непосредственно из интерфейса.
+
+### Требования
+
+* Учётная запись [npm](https://www.npmjs.com)
+* Ключевое слово `twenty-app` в массиве `keywords` вашего `package.json` (добавьте его вручную — по умолчанию оно не включено в шаблон `create-twenty-app`)
+
+```json filename="package.json"
+{
+  "name": "twenty-app-postcard-sender",
+  "version": "1.0.0",
+  "keywords": ["twenty-app"]
+}
+```
+
+### Метаданные маркетплейса
+
+Конфигурация `defineApplication()` поддерживает необязательные поля, которые определяют, как ваше приложение отображается в маркетплейсе. Используйте `logo` и `galleryImages`, чтобы ссылаться на изображения из папки `public/`:
+
+```ts src/application-config.ts
+export default defineApplication({
+  universalIdentifier: '...',
+  displayName: 'My App',
+  description: 'A great app',
+  logo: 'public/logo.png',
+  galleryImages: [
+    'public/screenshot-1.png',
+    'public/screenshot-2.png',
+  ],
+});
+```
+
+См. [аккордеон defineApplication](/l/ru/developers/extend/apps/config/application#marketplace-metadata) на странице «Создание приложений» для полного списка полей маркетплейса (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl` и т. д.).
+
+#### Рекомендуемые размеры изображений галереи
+
+Маркетплейс отображает `galleryImages` в контейнере с фиксированным соотношением сторон `8:5` (например, `1600×1000 px`).
+
+<Note>
+Изображения галереи с любым соотношением сторон отображаются полностью и никогда не обрезаются, но всё, что значительно выше или уже, чем `8:5`, будет иметь пустые поля по бокам.
+</Note>
+
+#### Ограничение размера изображения
+
+Файл `logo` и каждый файл из `galleryImages` не должны превышать **10 MB**. Более крупные файлы пропускаются при повторном размещении ваших опубликованных ресурсов на маркетплейсе, поэтому они не будут отображаться.
+
+### Публикация
+
+```bash filename="Terminal"
+yarn twenty app:publish
+```
+
+Чтобы опубликовать с определённым dist-tag (например, `beta` или `next`):
+
+```bash filename="Terminal"
+yarn twenty app:publish --tag beta
+```
+
+### Как работает обнаружение приложений в маркетплейсе
+
+Сервер Twenty синхронизирует каталог маркетплейса из реестра npm **каждый час**.
+
+Вы можете запустить синхронизацию немедленно, вместо ожидания:
+
+```bash filename="Terminal"
+yarn twenty dev:catalog-sync
+# To target a specific remote:
+# yarn twenty dev:catalog-sync --remote production
+```
+
+Метаданные, отображаемые в маркетплейсе, берутся из вашей конфигурации `defineApplication()` — см. раздел [Метаданные маркетплейса](#marketplace-metadata) выше.
+
+<Note>
+Если ваше приложение не определяет `aboutDescription` в `defineApplication()`, маркетплейс автоматически использует `README.md` вашего пакета из npm в качестве содержимого страницы «О приложении». Это означает, что вы можете поддерживать единый README как для npm, так и для маркетплейса Twenty. Если вы хотите другое описание в маркетплейсе, явно задайте `aboutDescription`.
+</Note>
+
+### Публикация через CI
+
+Сгенерированный выше рабочий процесс `publish.yml` автоматически публикует в npm по тегам версий, с provenance. Поскольку `yarn twenty app:publish` при запуске в CI добавляет за вас `--provenance` и `--access public`, в рабочем процессе не нужны флаги npm — требуется только однократная настройка доверенного издателя.
+
+Для других систем CI (GitLab CI, CircleCI и т. д.) запустите `yarn install`, затем `yarn twenty app:publish`. Provenance создается, когда среда может выпустить токен OIDC, и в противном случае автоматически пропускается.
+
+<Note>
+**npm provenance** добавляет значок доверия к вашему пакету в npm, позволяя пользователям проверить, что пакет был собран из конкретного коммита в общедоступном конвейере CI. Это также то, что позволяет вам заявить права на ваше приложение в маркетплейсе Twenty. Подробности см. в [документации по npm provenance](https://docs.npmjs.com/generating-provenance-statements).
+</Note>
+
+## Установка приложений
+
+После публикации приложения (npm) или его развертывания (tarball) рабочие пространства могут установить его через интерфейс.
+
+Перейдите на страницу **Настройки > Приложения** в Twenty, где можно просматривать и устанавливать как приложения из маркетплейса, так и развернутые через tarball.
+
+{/* TODO: add screenshot of the UI when the app is registered */}
+
+Вы также можете устанавливать приложения из командной строки:
+
+```bash filename="Terminal"
+yarn twenty app:install
+```
+
+<Note>
+Сервер при установке применяет версионирование semver, аналогичное правилам при развёртывании:
+
+* Установка той же версии, которая уже установлена в вашем рабочем пространстве, отклоняется с ошибкой `APP_ALREADY_INSTALLED`.
+* Установка версии ниже текущей отклоняется с ошибкой `CANNOT_DOWNGRADE_APPLICATION`.
+
+Чтобы установить более новую версию, сначала разверните или опубликуйте её, затем снова выполните `yarn twenty app:install`.
+</Note>

packages/twenty-docs/l/ru/developers/extend/apps/operations/sync-and-recovery.mdx

@@ -0,0 +1,126 @@
+---
+title: Синхронизация и восстановление
+description: Какую команду когда использовать, как читать вывод синхронизации и поэтапный план восстановления на случай расхождения локальных метаданных — до того, как дойдет до полного сброса.
+icon: compass
+---
+
+Локальная разработка приложения строится вокруг **синхронизации**: CLI пересобирает ваш манифест, а сервер применяет только разницу между ним и метаданными, которые уже есть в вашем рабочем пространстве. На этой странице описано, какую команду выбрать, как читать, что изменила синхронизация, и что делать — по шагам — когда локальное состояние выглядит несогласованным.
+
+## Какую команду и когда использовать
+
+<Note>
+Для повседневной локальной разработки вам почти всегда нужна команда `yarn twenty dev`. Развертывание и публикация предназначены для выпуска релизов, **а не** для локального цикла разработки.
+</Note>
+
+| Вы хотите…                                                       | Команда                             | Заметки                                                                                                                            |
+| ---------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Выполнять локальные итерации с синхронизацией в реальном времени | `yarn twenty dev`                   | Отслеживает ваши файлы и синхронизирует при каждом изменении.                                                                      |
+| Выполнить одну синхронизацию и выйти (CI, скрипты, хуки)         | `yarn twenty apply`                 | Одна сборка + синхронизация, затем завершение работы. Добавьте `--force`, чтобы пропустить подтверждение разрушительных изменений. |
+| Предпросмотр изменений **без их применения**                     | `yarn twenty plan`                  | Вычисляет и выводит diff; ничего не записывает.                                                                                    |
+| Удалить приложение из рабочего пространства                      | `yarn twenty app:uninstall`         | Добавьте `--yes`, чтобы пропустить запрос подтверждения.                                                                           |
+| Отправить на сервер tar-архив                                    | `yarn twenty app:publish --private` | Требуется **строго более высокая** версия в `package.json` — см. [Публикация](/l/ru/developers/extend/apps/operations/publishing).      |
+| Опубликовать на маркетплейсе (npm)                               | `yarn twenty app:publish`           | —                                                                                                                                  |
+| Установить / обновить развернутую версию                         | `yarn twenty app:install`           | Устанавливает версию, которая сейчас развернута.                                                                                   |
+| Очистить локальный сервер и начать с нуля                        | `yarn twenty docker:reset`          | Удаляет **все** локальные данные — крайняя мера.                                                                                   |
+
+<Note>
+`yarn twenty dev --once` и `yarn twenty dev --once --dry-run` по-прежнему работают как устаревшие псевдонимы для `yarn twenty apply` и `yarn twenty plan`.
+</Note>
+
+### Для локальной синхронизации не нужно повышать версию
+
+Правило строго возрастающей `version` (`VERSION_ALREADY_EXISTS` при deploy, `APP_ALREADY_INSTALLED` / `CANNOT_DOWNGRADE_APPLICATION` при install) относится к **`app:publish` / `app:install`** — пути релизов. `yarn twenty dev` синхронизирует ваш манифест на месте и никогда не требует изменения версии, поэтому вам не нужно трогать `package.json`, чтобы делать итерации. Если вы ловите себя на том, что поднимаете версию, чтобы протестировать локальное изменение, значит вы используете релизный путь, когда вам нужен цикл разработки (dev loop).
+
+## Чтение вывода синхронизации
+
+Каждая синхронизация выводит изменения метаданных, которые она применила (или применила бы, с `plan`), в стиле Terraform — по одному блоку на сущность с её атрибутами, затем строку с итогами:
+
+```text filename="Terminal"
+  # objectMetadata "rocket" will be created
+  + icon          = "IconRocket"
+  + labelSingular = "Rocket"
+  + ...
+
+  # fieldMetadata "launchedAt" will be updated
+  ~ isNullable = false -> true
+
+Plan: 2 to add, 1 to change, 1 to destroy.
+
+✓ Synced My App (4 files)
+```
+
+Это ваша первая диагностическая точка: она показывает, какие именно объекты, поля и макеты изменились, чтобы вы могли подтвердить, что синхронизация сделала то, что вы ожидали, до проверки в интерфейсе.
+
+Разрушительные изменения (`to destroy`) перечисляются вместе с тем, что они удаляют (например, `objectMetadata "auditNote" — drops the table and all its rows`) и требуют интерактивного подтверждения или `--force` в скриптах.
+
+Когда синхронизация завершается с ошибкой на одной сущности, в сообщении указываются проблемная сущность и её `universalIdentifier`, например:
+
+```text
+Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed
+```
+
+Используйте этот идентификатор, чтобы найти сущность в своем манифесте (и, при необходимости, в рабочем пространстве), вместо того чтобы гадать, какая из них конфликтует.
+
+## Предпросмотр изменений (plan)
+
+`yarn twenty plan` собирает ваш манифест, запрашивает у сервера план миграции и выводит его — **без применения чего-либо**. Это безопасный способ ответить на вопрос «что изменит эта синхронизация?» до того, как вы на неё согласитесь.
+
+```bash filename="Terminal"
+yarn twenty plan
+```
+
+```text filename="Terminal"
+Building manifest...
+Computing metadata plan (read-only, nothing will be applied)...
+
+  # fieldMetadata "crewCapacity" will be created
+  + ...
+
+Plan: 1 to add, 1 to change, 0 to destroy.
+
+✓ Plan complete for My App — no changes were applied
+```
+
+План:
+
+* **Ничего не записывает** — ни миграции метаданных, ни обновления записи приложения, ни изменений ролей/вкладок по умолчанию, ни генерации API‑клиента.
+* Возвращает **тот же diff**, который применит реальная синхронизация, чтобы вы могли заранее просмотреть создаваемые/обновляемые/удаляемые сущности.
+* Полезен перед рискованным изменением, при проверке изменения, сгенерированного ИИ, или в скрипте, который должен завершаться с ошибкой, если вот-вот будет применено неожиданное изменение.
+
+<Note>
+План только предварительно показывает изменения **метаданных** и требует, чтобы приложение хотя бы один раз уже было синхронизировано (чтобы рабочее пространство знало о нём). Если вы запускаете его для приложения, которое никогда не синхронизировалось, сервер сообщит, что приложение не установлено — сначала один раз выполните `yarn twenty dev`.
+</Note>
+
+## Лестница восстановления
+
+Когда локальные метаданные выглядят неверно, действуйте поэтапно в следующем порядке и останавливайтесь, как только проблема решена. Каждый следующий шаг более разрушителен, чем предыдущий.
+
+1. **Повторно синхронизируйте.** Снова выполните `yarn twenty apply`. Синхронизации идемпотентны — повторный запуск корректного манифеста безопасен и часто устраняет временный сбой.
+2. **Просмотрите план.** Выполните `yarn twenty plan`, чтобы увидеть, что именно намеревается изменить следующая синхронизация, не применяя эти изменения.
+3. **Прочитайте сообщение об ошибке.** Если синхронизация завершается с ошибкой, обратите внимание на тип метаданных и `universalIdentifier` в сообщении (см. выше) и найдите эту сущность в своем манифесте. Конфликт обычно указывает на дублированный или повторно используемый идентификатор.
+4. **Удалите и переустановите.** Выполните `yarn twenty app:uninstall`, затем синхронизируйте снова (`yarn twenty dev`). Это пересобирает метаданные приложения с нуля, сохраняя остальную часть вашего рабочего пространства нетронутой.
+5. **Полный сброс (крайняя мера).** Выполните `yarn twenty docker:reset`, затем заново выполните начальное наполнение данными и синхронизацию.
+
+<Warning>
+`yarn twenty docker:reset` удаляет **все** данные в вашей локальной инсталляции — все рабочие пространства, записи и приложения. Используйте его только после того, как предыдущие шаги не помогли.
+</Warning>
+
+<Note>
+Столкнулись с ошибкой метаданных? Пожалуйста, [создайте issue](https://github.com/twentyhq/twenty/issues/new/choose) и приложите сообщение о сбое миграции (с типом метаданных и `universalIdentifier`), вывод `Metadata changes` из синхронизации и команды, которые вы запускали.
+</Note>
+
+## Избегайте одновременных синхронизаций в одном рабочем пространстве
+
+Синхронизация применяет миграции метаданных. Запуск нескольких операций sync, deploy или install по отношению к **одному и тому же рабочему пространству одновременно** — например, из нескольких терминалов или при параллельных итерациях агентов ИИ — может перемешать эти миграции и оставить метаданные в частично примененном состоянии.
+
+Сервер последовательно обрабатывает синхронизации для каждого рабочего пространства, чтобы предотвратить это, но вам всё равно следует пропускать чувствительные операции с метаданными через **один** процесс, а не запускать их параллельно. Если вы организуете разработку с несколькими агентами, направляйте их вызовы sync/deploy/install через одну очередь, чтобы в каждый момент времени выполнялась только одна операция.
+
+## Как различать типы сбоев
+
+Когда что‑то идёт не так, diff метаданных и именованные ошибки помогают определить, на каком этапе произошел сбой:
+
+* **Ошибка сборки манифеста** — CLI завершается с ошибкой до синхронизации (`MANIFEST_BUILD_FAILED`, `TYPECHECK_FAILED`); исправьте исходный код приложения.
+* **Ошибка синхронизации / миграции** — сборка проходит успешно, но применение diff завершается сбоем с указанием сущности и `universalIdentifier`; исправьте конфликтующие метаданные.
+* **Ошибка размера зависимостей** — синхронизация или установка завершается сбоем, потому что продакшен‑зависимости приложения (`dependencies`) слишком велики, чтобы их установить в качестве слоя среды выполнения (`LOGIC_FUNCTION_DEPENDENCIES_SIZE_EXCEEDED`); перенесите пакеты, которые ваши логические функции не импортируют во время выполнения (UI-библиотеки, инструменты разработки), в `devDependencies`.
+* **Ошибка выполнения кода приложения** — синхронизация проходит успешно, но ваши логические функции или компоненты ведут себя неправильно во время выполнения; проверьте [журналы функций](/l/ru/developers/extend/apps/operations/cli).
+* **Локальное состояние экземпляра** — ни один из вышеперечисленных пунктов не подходит, и рабочее пространство всё ещё выглядит неправильно; двигайтесь вниз по лестнице восстановления.

packages/twenty-docs/l/ru/developers/extend/apps/operations/testing.mdx

@@ -0,0 +1,264 @@
+---
+title: Тестирование
+description: Настройка Vitest, интеграционные тесты с использованием реального сервера Twenty, проверка типов и CI с GitHub Actions.
+icon: flask
+---
+
+SDK предоставляет программные API, которые позволяют собирать, разворачивать, устанавливать и удалять ваше приложение из тестового кода. В сочетании с [Vitest](https://vitest.dev/) и типизированными клиентами API вы можете писать интеграционные тесты, которые проверяют, что ваше приложение работает сквозным образом на реальном сервере Twenty.
+
+## Использование пакетов npm
+
+Вы можете устанавливать и использовать любые пакеты npm в своём приложении. И логические функции, и компоненты фронтенда собираются с помощью [esbuild](https://esbuild.github.io/), который встраивает их зависимости в выходной файл — каталоги `node_modules` во время выполнения не нужны.
+
+### Установка пакета
+
+```bash filename="Terminal"
+yarn add axios
+```
+
+Затем импортируйте его в своём коде:
+
+```ts src/logic-functions/fetch-data.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import axios from 'axios';
+
+const handler = async (): Promise<any> => {
+  const { data } = await axios.get('https://api.example.com/data');
+
+  return { data };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '...',
+  name: 'fetch-data',
+  description: 'Fetches data from an external API',
+  timeoutSeconds: 10,
+  handler,
+});
+```
+
+То же самое работает для компонентов фронтенда:
+
+```tsx src/front-components/chart.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { format } from 'date-fns';
+
+const DateWidget = () => {
+  return <p>Today is {format(new Date(), 'MMMM do, yyyy')}</p>;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'date-widget',
+  component: DateWidget,
+});
+```
+
+### Как работает бандлинг
+
+Этап сборки использует esbuild для создания одного самодостаточного файла на каждую логическую функцию и на каждый компонент фронтенда. Импортированные пакеты встраиваются в бандл, за исключением перечисленных ниже.
+
+**Логические функции** выполняются в среде Node.js. Встроенные модули Node (`fs`, `path`, `crypto`, `http` и т. д.) доступны и не требуют установки.
+
+**Компоненты фронтенда** выполняются в Web Worker. Встроенные модули Node **недоступны** — доступны только пакеты npm, работающие в браузерной среде. Обратите внимание, что в песочнице реализован *частичный* DOM, поэтому пакет может успешно собраться, но все равно завершиться с ошибкой во время выполнения; см. раздел [Текущие ограничения](/l/ru/developers/extend/apps/layout/front-components#current-limitations).
+
+В обеих средах доступны как предварительно предоставленные модули `twenty-client-sdk/core` и `twenty-client-sdk/metadata` — они не включаются в бандл, а подставляются сервером во время выполнения.
+
+Фронтенд‑компоненты также могут совместно использовать зависимости через [общий бандл зависимостей](/l/ru/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components). Пакеты, перечисленные в поле `frontComponentSharedDependencies` файла package.json приложения, один раз собираются в отдельный файл и загружаются из него во время выполнения вместо внедрения в каждый компонент, поэтому компонент, который импортирует только общие пакеты, практически не содержит собственного кода зависимостей.
+
+## Настройка
+
+Приложение, созданное скэффолдером, уже включает Vitest. Если вы настраиваете его вручную, установите зависимости:
+
+```bash filename="Terminal"
+yarn add -D vitest vite-tsconfig-paths
+```
+
+Создайте `vitest.config.ts` в корне вашего приложения:
+
+```ts vitest.config.ts
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';
+const TWENTY_API_KEY = process.env.TWENTY_API_KEY ?? '<the pre-seeded local dev key>';
+
+// Make env vars available to globalSetup (test.env only applies to workers)
+process.env.TWENTY_API_URL = TWENTY_API_URL;
+process.env.TWENTY_API_KEY = TWENTY_API_KEY;
+
+export default defineConfig({
+  plugins: [
+    tsconfigPaths({
+      projects: ['tsconfig.spec.json'],
+      ignoreConfigErrors: true,
+    }),
+  ],
+  test: {
+    testTimeout: 120_000,
+    hookTimeout: 120_000,
+    fileParallelism: false,
+    include: ['src/**/*.integration-test.ts'],
+    globalSetup: ['src/__tests__/global-setup.ts'],
+    env: {
+      TWENTY_API_URL,
+      TWENTY_API_KEY,
+    },
+  },
+});
+```
+
+Создайте глобальный файл настройки, который проверяет, что сервер доступен, записывает тестовую конфигурацию для SDK (`~/.twenty/config.test.json`) и выполняет синхронизацию приложения перед запуском тестов:
+
+```ts src/__tests__/global-setup.ts
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { appDevOnce, appUninstall } from 'twenty-sdk/cli';
+
+const APP_PATH = process.cwd();
+const CONFIG_DIR = path.join(os.homedir(), '.twenty');
+
+export async function setup() {
+  const apiUrl = process.env.TWENTY_API_URL!;
+  const apiKey = process.env.TWENTY_API_KEY!;
+
+  // Verify the server is running
+  const response = await fetch(`${apiUrl}/healthz`);
+  if (!response.ok) {
+    throw new Error(`Twenty server is not reachable at ${apiUrl}.`);
+  }
+
+  // Write the SDK's test config (the CLI reads config.test.json when NODE_ENV=test)
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(
+    path.join(CONFIG_DIR, 'config.test.json'),
+    JSON.stringify({
+      remotes: { local: { apiUrl, apiKey } },
+      defaultRemote: 'local',
+    }, null, 2),
+  );
+
+  // Start from a clean slate, then sync the app
+  await appUninstall({ appPath: APP_PATH }).catch(() => {});
+
+  const result = await appDevOnce({ appPath: APP_PATH });
+  if (!result.success) {
+    throw new Error(`Dev sync failed: ${result.error?.message}`);
+  }
+}
+
+export async function teardown() {
+  await appUninstall({ appPath: APP_PATH });
+}
+```
+
+## Программные API SDK
+
+Подпуть `twenty-sdk/cli` экспортирует функции, которые можно вызывать напрямую из тестового кода:
+
+| Функция        | Описание                                                                          |
+| -------------- | --------------------------------------------------------------------------------- |
+| `appBuild`     | Собрать приложение и при необходимости упаковать tar-архив                        |
+| `appDeploy`    | Загрузить tar-архив на сервер                                                     |
+| `appDevOnce`   | Один раз собрать и синхронизировать приложение (то же, что и `yarn twenty apply`) |
+| `appInstall`   | Установить приложение в активное рабочее пространство                             |
+| `appUninstall` | Удалить приложение из активного рабочего пространства                             |
+
+Каждая функция возвращает объект результата с `success: boolean` и либо `data`, либо `error`.
+
+## Написание интеграционного теста
+
+Полный пример, который собирает, разворачивает и устанавливает приложение, а затем проверяет, что оно появляется в рабочем пространстве:
+
+```ts src/__tests__/app-install.integration-test.ts
+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';
+import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const APP_PATH = process.cwd();
+
+describe('App installation', () => {
+  beforeAll(async () => {
+    const buildResult = await appBuild({
+      appPath: APP_PATH,
+      tarball: true,
+      onProgress: (message: string) => console.log(`[build] ${message}`),
+    });
+
+    if (!buildResult.success) {
+      throw new Error(`Build failed: ${buildResult.error?.message}`);
+    }
+
+    const deployResult = await appDeploy({
+      tarballPath: buildResult.data.tarballPath!,
+      onProgress: (message: string) => console.log(`[deploy] ${message}`),
+    });
+
+    if (!deployResult.success) {
+      throw new Error(`Deploy failed: ${deployResult.error?.message}`);
+    }
+
+    const installResult = await appInstall({ appPath: APP_PATH });
+
+    if (!installResult.success) {
+      throw new Error(`Install failed: ${installResult.error?.message}`);
+    }
+  });
+
+  afterAll(async () => {
+    await appUninstall({ appPath: APP_PATH });
+  });
+
+  it('should find the installed app in the workspace', async () => {
+    const metadataClient = new MetadataApiClient();
+
+    const result = await metadataClient.query({
+      findManyApplications: {
+        id: true,
+        name: true,
+        universalIdentifier: true,
+      },
+    });
+
+    const installedApp = result.findManyApplications.find(
+      (app: { universalIdentifier: string }) =>
+        app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
+    );
+
+    expect(installedApp).toBeDefined();
+  });
+});
+```
+
+## Запуск тестов
+
+Убедитесь, что ваш локальный сервер Twenty запущен, затем:
+
+```bash filename="Terminal"
+yarn test
+```
+
+Или в режиме наблюдения во время разработки:
+
+```bash filename="Terminal"
+yarn test:watch
+```
+
+## Проверка типов
+
+Вы также можете запустить проверку типов для своего приложения без запуска тестов:
+
+```bash filename="Terminal"
+yarn twenty dev:typecheck
+```
+
+Это запускает `tsc --noEmit` для `tsconfig.json` вашего приложения и сообщает о любых ошибках типов. Сгенерированные с помощью скэффолдера приложения также поставляются со скриптом `yarn typecheck`, который проверяет и тестовые файлы (`tsconfig.spec.json`).
+
+## CI с GitHub Actions
+
+Скэффолдер генерирует готовый к использованию рабочий процесс в `.github/workflows/ci.yml`. При каждом пуше в `main` и каждом pull request он запускает эфемерный сервер Twenty в раннере (через экшен `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test`), затем выполняет `yarn lint`, `yarn typecheck`, `yarn test:unit` и `yarn test` с `TWENTY_API_URL` / `TWENTY_API_KEY`, указывающими на этот сервер. Секреты не требуются, и вы можете зафиксировать версию сервера через переменную окружения `TWENTY_VERSION` в начале рабочего процесса.
+
+См. раздел [Публикация → Автоматизированный CI/CD](/l/ru/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) для полного пошагового руководства по трем сгенерированным рабочим процессам (`ci.yml`, конвейер деплоя `cd.yml` и `publish.yml` для публикации в npm).

packages/twenty-docs/l/ru/developers/extend/apps/operations/translations.mdx

@@ -0,0 +1,144 @@
+---
+title: Переводы
+description: Выпускайте приложение на нескольких языках — переводите метки манифеста и строки пользовательского интерфейса через единый каталог локалей.
+icon: language
+---
+
+Приложения Twenty создаются на **английском**: строки в вашем исходном коде и манифесте
+являются исходным текстом на английском, `en` — это исходная локаль, с которой вы переводите, а
+любая непереведенная локаль будет использовать ее по умолчанию.
+
+В вашем приложении есть два типа переводимого текста, и оба проходят через один и тот же
+каталог `locales/`:
+
+* **Метки манифеста** — имена объектов и полей, заголовки представлений, пункты меню и
+  другие строки, объявленные в метаданных вашего приложения.
+* **Строки фронт-компонента** — пользовательский интерфейс для отображения React фронтальных компонентов.
+
+Вы помечаете переводимые строки, извлекаете их в каталоги для каждой локали,
+переводите эти каталоги, и сборка отдает правильный язык для
+текущего пользователя — без дополнительной настройки.
+
+## Маркировка переднего компонента
+
+Импортировать помощников перевода из `twenty-sdk/front-component`:
+
+```tsx
+import { Trans, t, msg, useTranslate } from 'twenty-sdk/front-component';
+
+const STATUSES = [
+  { id: 'draft', label: msg('Draft') },
+  { id: 'sent', label: msg('Sent') },
+];
+
+const Card = ({ count, name }: { count: number; name: string }) => {
+  const { t } = useTranslate();
+
+  return (
+    <section>
+      {/* Static text — reactive to the user's locale */}
+      <Trans>Loading postcard…</Trans>
+
+      {/* Disambiguate identical sources with a context */}
+      <Trans context="card-title">Untitled</Trans>
+
+      {/* Interpolation: pass values explicitly */}
+      <p>{t('Hi {name}', { name })}</p>
+      <p>{t('Saved {count} cards', { count })}</p>
+
+      {/* Resolve a lazily-declared descriptor */}
+      <ul>{STATUSES.map((s) => <li key={s.id}>{t(s.label)}</li>)}</ul>
+    </section>
+  );
+};
+```
+
+### Когда использовать, какой
+
+* **`Trans`** — статический текст в JSX. Используйте пропсы `message` и `values` для
+  интерполяции, как в `Trans message="Hi {name}" values={{ name }}`;
+  интерполяция напрямую в дочерних элементах не может быть статически извлечена.
+* **`useTranslate().t`** — динамические строки внутри компонента. Повторно отображается, когда
+  пользователь переключает язык. Предпочитать это внутри рендера.
+* **`t(...)`** (импортировано напрямую) — перевод можно использовать **где**,
+  включая обработчики событий, вспомогательные и область модулей — не только внутри рендера.
+* **`msg(...)`** — ленивый дескриптор строк, объявленный данными (константы,
+  config). Разрешите позже с помощью `t(descriptor)`.
+
+### Контекст
+
+Передайте `context` в недвусмысленный перевод идентичных исходных строк, которые переводят
+по-разному:
+
+```tsx
+t({ message: 'Open', context: 'door' });
+t({ message: 'Open', context: 'window' });
+<Trans context="card-title">Untitled</Trans>
+```
+
+Контекстные строки отображаются в каталогах локалей в виде группы, индексируемой
+по их контексту: `"\<context>": { "\<message>": "\<translation>" }`. Манифестные метки являются
+контекстными по своей природе — каждая из них несёт метаданные о своей роли
+(`objectMetadata.labelSingular`, `fieldMetadata.label`, `view.name`, …), поэтому
+одно и то же слово может переводиться по‑разному как имя объекта и как имя представления.
+
+## Извлечение и перевод
+
+Выполнить команду извлечения из вашей папки приложения:
+
+```bash
+twenty dev:translations-extract                  # collect strings into locales/en.json
+twenty dev:translations-extract --locale fr-FR   # also scaffold a target locale
+```
+
+При извлечении собираются как метки манифеста, так и строки `t()`/`msg()`/`Trans`
+из исходного кода вашего фронт‑компонента в `locales/\<locale>.json`, где ключом
+является исходная строка. Заполните перевод:
+
+```json
+// locales/fr-FR.json
+{
+  "Loading postcard…": "Chargement de la carte…",
+  "Hi {name}": "Bonjour {name}",
+  "Saved {count} cards": "{count} cartes enregistrées",
+  "door": {
+    "Open": "Ouvrir"
+  },
+  "objectMetadata.labelSingular": {
+    "Postcard": "Carte postale"
+  }
+}
+```
+
+Строки без контекста являются плоскими записями; контекстные строки — включая каждую
+метку манифеста — вложены под своим ключом контекста.
+
+Такие держатели, как `{name}`, заменяются во время выполнения — сохраняйте их в переводе
+. Любая оставленная строка пуста возвращается к исходному тексту.
+
+## Как он запускается
+
+`twenty dev:build` компилирует каталоги и предоставляет нужный язык для
+текущего пользователя: метки манифеста разрешаются на стороне сервера, а каталоги фронтенд-компонентов
+встраиваются в каждый бандл компонента. Во время выполнения компонент читает локаль
+из контекста выполнения (текущий язык узла) и разрешает
+каждую строку в соответствии со своим каталогом, возвращение к источнику, когда перевод
+отсутствует. Переключение языка в хосте повторно рендерит строки `Trans` и
+`useTranslate().t` в реальном времени.
+
+Метки манифеста компилируются при каждой синхронизации — `twenty dev:build`, `twenty apply`
+и в постоянном режиме отслеживания `twenty dev` — поэтому достаточно изменить файл локали и
+выполнить синхронизацию, чтобы увидеть новый текст. Каталоги компонентов Front встраиваются в
+каждый пакет компонентов во время сборки, поэтому изменение одного из них по-прежнему требует
+повторного запуска `twenty dev:build` (и повторного развертывания).
+
+Дочерние текстовые элементы `Trans` могут занимать несколько строк — пробельные символы схлопываются
+так же, как их схлопывает JSX, поэтому оба этих варианта извлекаются в ключ `Welcome back`:
+
+```tsx
+<Trans>Welcome back</Trans>
+<Trans>
+  Welcome
+  back
+</Trans>
+```

packages/twenty-docs/l/ru/developers/extend/apps/tutorials/document-generator/ai-agent.mdx

@@ -0,0 +1,79 @@
+---
+title: 5. An AI agent
+icon: robot
+description: Пусть агент сгенерирует документы из чата, используя ваш инструмент.
+---
+
+Потому что `generate-document` выставляется как **инструмент**, агент ИИ может назвать его.
+Давайте добавим агента и навыка, чтобы пользователи могли просто сказать *"создать предложение для
+Джеффера Гриффина"*.
+
+## Навык
+
+[Навык](/l/ru/developers/extend/apps/logic/skills-and-agents) — это многократно используемые инструкции, то есть знания, которые вы прикрепляете к агентам. Мы учим модель использования
+инструмента.
+
+```ts filename="src/skills/document-drafting.skill.ts"
+import { defineSkill } from 'twenty-sdk/define';
+
+export default defineSkill({
+  universalIdentifier: DOCUMENT_SKILL_UNIVERSAL_IDENTIFIER,
+  name: 'document-drafting',
+  label: 'Document drafting',
+  icon: 'IconFileText',
+  content: [
+    'To generate a document, call the `generate-document` tool with:',
+    '- `templateId`: the id of the document template to use.',
+    '- `recordId`: the id of the Person or Company the document is for.',
+    '',
+    'If the user names a template or person instead of an id, find the record first,',
+    'then pass its id. Make sure the template target matches the record type.',
+  ].join('\n'),
+});
+```
+
+## Агент
+
+[Агент](/l/ru/developers/extend/apps/logic/skills-and-agents) сочетает промпт с моделью. Установите `responseFormat` явно во избежание предупреждения о строительстве.
+
+```ts filename="src/agents/document-assistant.agent.ts"
+import { defineAgent } from 'twenty-sdk/define';
+
+export default defineAgent({
+  universalIdentifier: DOCUMENT_AGENT_UNIVERSAL_IDENTIFIER,
+  name: 'document-assistant',
+  label: 'Document Assistant',
+  description: 'Generates documents from your templates and CRM records.',
+  icon: 'IconFileText',
+  responseFormat: { type: 'text' },
+  prompt: [
+    'You are the Document Assistant for a CRM.',
+    'You help users generate personalized documents from reusable templates',
+    'and the data already in their CRM. Use the generate-document tool, and',
+    'always confirm what you created.',
+  ].join(' '),
+});
+```
+
+<Note>
+Агент может вызвать этот инструмент, только если его роль позволяет его. Мы уже установили
+`canAccessAllTools: true` и `canBeAssignedToAgents: true` роли приложения в
+[Глава 2](/l/ru/developers/extend/apps/tutorials/document-generator/generating-documents#grant-it-access).
+</Note>
+
+## Попробовать
+
+Откройте чат с **Document Assistant** и попросите его подготовить черновик документа для
+персоны в вашей CRM-системе. Она находит запись, называет `generate-document` и сообщает
+обратно созданный документ — который теперь появляется в вашем **Documents** представлении,
+точно соответствует командному меню и путям рабочего процесса.
+
+Это отдача от раскрытия логики в качестве инструмента: **одна функция, многие передние двери** —
+меню команд, HTTP, шаг рабочего процесса и теперь естественный язык.
+
+**После этого шага:** приложение является полноценным и действительно полезным. Пришло время
+отправить его.
+
+<Card title="Далее: публикация →" icon="rocket" href="/l/ru/developers/extend/apps/tutorials/document-generator/publishing">
+  Добавить метаданные торговой площадки и опубликовать.
+</Card>

packages/twenty-docs/l/ru/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx

@@ -0,0 +1,310 @@
+---
+title: 4. Создание пользовательского интерфейса
+icon: table-columns
+description: Виды, боковая навигация, команды и передние компоненты.
+---
+
+Сейчас объекты доступны только через Настройки. Давайте придадим приложению
+реальное присутствие в интерфейсе: представления списков, элементы боковой панели, однокнопочную
+команду **Generate document**, фронтенд-компонент на странице записи для **предварительного просмотра**
+документа и встроенную вкладку **Editor** с редактором форматированного текста для шаблонов.
+
+## Виды и навигация
+
+[view](/l/ru/developers/extend/apps/layout/views) — это сохраненный список объектов.
+[пункт меню навигации](/l/ru/developers/extend/apps/layout/navigation-menu-items)
+помещает его в боковую панель. Сервер уже автоматически создает для каждого объекта
+представление по умолчанию "All ...", поэтому представления, определяемые приложением,
+являются дополнительными, специально отобранными.
+
+```ts filename="src/views/documents.view.ts"
+import { defineView } from 'twenty-sdk/define';
+
+export default defineView({
+  universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER,
+  name: 'All documents',
+  objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER,
+  icon: 'IconFile',
+  position: 0,
+  fields: [
+    { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER,
+      fieldMetadataUniversalIdentifier: DOCUMENT_NAME_FIELD_UNIVERSAL_IDENTIFIER,
+      position: 0, isVisible: true, size: 280 },
+    { universalIdentifier: DOCUMENTS_VIEW_STATUS_FIELD_UNIVERSAL_IDENTIFIER,
+      fieldMetadataUniversalIdentifier: DOCUMENT_STATUS_FIELD_UNIVERSAL_IDENTIFIER,
+      position: 1, isVisible: true, size: 120 },
+    { universalIdentifier: DOCUMENTS_VIEW_TEMPLATE_FIELD_UNIVERSAL_IDENTIFIER,
+      fieldMetadataUniversalIdentifier: DOCUMENT_TEMPLATE_FIELD_UNIVERSAL_IDENTIFIER,
+      position: 2, isVisible: true, size: 200 },
+  ],
+});
+```
+
+```ts filename="src/navigation-menu-items/documents.navigation-menu-item.ts"
+import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
+
+export default defineNavigationMenuItem({
+  universalIdentifier: DOCUMENTS_NAVIGATION_MENU_ITEM_UNIVERSAL_IDENTIFIER,
+  name: 'Documents',
+  icon: 'IconFile',
+  color: 'green',
+  position: 1,
+  type: NavigationMenuItemType.VIEW,
+  viewUniversalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER,
+});
+```
+
+Добавьте ту же пару для шаблонов. Оба теперь показываются в боковой панели:
+
+<Frame caption="Документы и шаблоны в боковой панели, со сгенерированным документом.">
+  <img src="/images/docs/developers/extends/apps/document-generator/04-documents-view.png" alt="Просмотр документов с созданным документом" />
+</Frame>
+
+## Передний компонент
+
+[передний компонент](/l/ru/developers/extend/apps/layout/front-components) — компонент React
+внутри Twenty. Наш компонент считывает выбранную запись, загружает
+персональные шаблоны через `CoreApiClient` и отправляет POST-запрос на маршрут из прошлого
+раздела.
+
+```tsx filename="src/front-components/generate-document-form.front-component.tsx"
+import { useEffect, useState } from 'react';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { RestApiClient } from 'twenty-client-sdk/rest';
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { enqueueSnackbar, useSelectedRecordIds } from 'twenty-sdk/front-component';
+
+const GenerateDocumentForm = () => {
+  const selectedRecordIds = useSelectedRecordIds();
+  const recordId = selectedRecordIds.length === 1 ? selectedRecordIds[0] : null;
+  const [templates, setTemplates] = useState<{ id: string; name: string }[]>([]);
+  const [templateId, setTemplateId] = useState('');
+
+  useEffect(() => {
+    new CoreApiClient()
+      .query({ documentTemplates: {
+        __args: { filter: { target: { eq: 'PERSON' } }, first: 100 },
+        edges: { node: { id: true, name: true } } } })
+      .then(({ documentTemplates }) => {
+        const list = documentTemplates?.edges?.map((e) => e.node) ?? [];
+        setTemplates(list);
+        if (list[0]) setTemplateId(list[0].id);
+      });
+  }, []);
+
+  const generate = async () => {
+    const res = await new RestApiClient().post<{ success: boolean }>(
+      '/s/documents/generate',
+      { templateId, recordId },
+    );
+    await enqueueSnackbar({
+      message: res.success ? 'Document generated.' : 'Generation failed.',
+      variant: res.success ? 'success' : 'error',
+    });
+  };
+
+  // ...render a <select> of templates and a Generate button
+};
+
+export default defineFrontComponent({
+  universalIdentifier: GENERATE_DOCUMENT_FORM_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+  name: 'generate-document-form',
+  component: GenerateDocumentForm,
+});
+```
+
+<Warning>
+Стиль с inline CSS переменными (`var(--t-color-blue)`), а не значениями, импортированными из
+`twenty-ui`. SDK моктирует этот пакет во время сборки, поэтому импорт модулей уровня
+констант темы был бы `неопределённым`. См.
+[полный компонент](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/document-generator/src/front-components/generate-document-form.front-component.tsx).
+</Warning>
+
+## Команда открытия
+
+[пункт меню команды](/l/ru/developers/extend/apps/layout/command-menu-items) с
+`availabilityType: 'RECORD_SELECTION'` отображается при выборе персоны, и
+открывает компонент в боковой панели.
+
+```ts filename="src/command-menu-items/generate-document.command-menu-item.ts"
+import { defineCommandMenuItem, STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: GENERATE_DOCUMENT_COMMAND_UNIVERSAL_IDENTIFIER,
+  label: 'Generate document',
+  availabilityType: 'RECORD_SELECTION',
+  availabilityObjectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
+  frontComponentUniversalIdentifier:
+    GENERATE_DOCUMENT_FORM_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+});
+```
+
+## Попробуйте весь поток
+
+Откройте **People**, выберите человека и нажмите <kbd>⌘K</kbd> / <kbd>Ctrl K</kbd>.
+Появляется "Генерировать документ" с тегом в вашем приложении:
+
+<Frame caption="Эта команда появляется, когда выбран персон.">
+  <img src="/images/docs/developers/extends/apps/document-generator/06-command-menu.png" alt="Меню команды с документом Генерировать" />
+</Frame>
+
+Запустить — ваш компонент открывается в боковой панели. Выберите шаблон, нажмите
+**Сгенерировать** и новые записи земель в **Документах**.
+
+<Frame caption="Передний компонент, загрузка шаблонов и создание клика.">
+  <img src="/images/docs/developers/extends/apps/document-generator/06b-front-component.png" alt="Создать панель документа" />
+</Frame>
+
+Каждый сгенерированный документ записывает ваше приложение как автора:
+
+<Frame caption="Создано в виде статуса Генератора.">
+  <img src="/images/docs/developers/extends/apps/document-generator/05-document-record.png" alt="Созданная запись документа" />
+</Frame>
+
+## Предпросмотр документа на странице записи
+
+Передний компонент не только для командных меню — вы можете смонтировать его как \*\*вкладку на странице записи
+\*\*. Давайте добавим вкладку *Предварительный просмотр* к документу, который отображает
+тело Markdown как отполированную страницу для печати.
+
+Компонент считывает идентификатор текущей записи из своего контекста выполнения, загружает
+документ и отображает его. Передние компоненты запускаются в **песочнице**, что позволяет
+белым списком HTML тегов (`dangerouslySetInnerHTML`) и
+`\<style>`, поэтому мы блокируем Markdown как React elements inline
+через маленькие [`Markdown`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/document-generator/src/utils/markdown-to-react.tsx)
+помощника.
+
+```tsx filename="src/front-components/document-viewer.front-component.tsx"
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { RestApiClient } from 'twenty-client-sdk/rest';
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useFrontComponentExecutionContext } from 'twenty-sdk/front-component';
+import { Markdown } from 'src/utils/markdown-to-react';
+
+const DocumentViewer = () => {
+  const recordId = useFrontComponentExecutionContext((c) => c.recordId ?? null);
+  // ...load { content, file } for recordId, then derive the links:
+  const pdfUrl = document.file?.[0]?.url;
+  const webUrl = new RestApiClient().resolveUrl('/s/documents/view', {
+    query: { id: recordId },
+  });
+
+  // Render the template body, plus quick links to the web page and the PDF.
+  // Links open in a new tab so they don't navigate the embedded component.
+  return (
+    <div style={styles.scroll}>
+      <div style={styles.actions}>
+        <a style={styles.actionLink} href={webUrl} target="_blank" rel="noopener noreferrer">
+          Open web page
+        </a>
+        {pdfUrl ? (
+          <a style={styles.actionLink} href={pdfUrl} target="_blank" rel="noopener noreferrer">
+            Download PDF
+          </a>
+        ) : null}
+      </div>
+      <div style={styles.paper}>
+        <div style={styles.body}>
+          <Markdown content={document.content} />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: DOCUMENT_VIEWER_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+  name: 'document-viewer',
+  component: DocumentViewer,
+});
+```
+
+Монтируйте его с [разметкой](/l/ru/developers/extend/apps/layout/page-layouts). Макет
+`RECORD_PAGE` добавляет вкладки к представлению записи объекта; вкладка с одним
+виджетом `FRONT_COMPONENT` размещает компонент на всю ширину:
+
+```ts filename="src/page-layouts/document-record.page-layout.ts"
+import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';
+
+export default definePageLayout({
+  universalIdentifier: DOCUMENT_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+  name: 'Document record page',
+  type: 'RECORD_PAGE',
+  objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER,
+  tabs: [{
+    universalIdentifier: DOCUMENT_PAGE_LAYOUT_TAB_UNIVERSAL_IDENTIFIER,
+    title: 'Preview',
+    icon: 'IconEye',
+    position: 50,
+    layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
+    widgets: [{
+      universalIdentifier: DOCUMENT_PAGE_LAYOUT_WIDGET_UNIVERSAL_IDENTIFIER,
+      title: 'Document preview',
+      type: 'FRONT_COMPONENT',
+      configuration: {
+        configurationType: 'FRONT_COMPONENT',
+        frontComponentUniversalIdentifier: DOCUMENT_VIEWER_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+      },
+    }],
+  }],
+});
+```
+
+Откройте любой документ — вкладка **Preview** красиво его отобразит, с ссылками на
+общедоступную веб-страницу и PDF:
+
+<Frame caption="Вкладка &#x22;Предварительный просмотр&#x22; отображает документ в встроенных стилях, а также быстрые ссылки.">
+  <img src="/images/docs/developers/extends/apps/document-generator/09-document-viewer.png" alt="Фронтальный компонент просмотра документа в вкладке записи" />
+</Frame>
+
+## Редактировать шаблон с редактором rich-text
+
+Шаблонам вообще не нужен пользовательский компонент. Поскольку `body` — это поле
+`RICH_TEXT`, Twenty уже предоставляет для него полнофункциональный редактор форматированного текста —
+тот же, который используют стандартные объекты Note и Task. Мы просто покрываем его на странице шаблона
+.
+
+Добавьте вкладку с виджета `FIELD` в режиме отображения `EDITOR`, указывая на `body`
+поле `fieldMetadaId`:
+
+```ts filename="src/page-layouts/template-record.page-layout.ts"
+{
+  universalIdentifier: TEMPLATE_PAGE_LAYOUT_TAB_UNIVERSAL_IDENTIFIER,
+  title: 'Template',
+  position: 1,
+  layoutMode: PageLayoutTabLayoutMode.GRID,
+  widgets: [{
+    universalIdentifier: TEMPLATE_PAGE_LAYOUT_WIDGET_UNIVERSAL_IDENTIFIER,
+    title: 'Template',
+    type: 'FIELD',
+    position: { layoutMode: PageLayoutTabLayoutMode.GRID, row: 0, column: 0, rowSpan: 6, columnSpan: 12 },
+    configuration: {
+      configurationType: 'FIELD',
+      fieldMetadataId: TEMPLATE_BODY_FIELD_UNIVERSAL_IDENTIFIER,
+      fieldDisplayMode: 'EDITOR',
+    },
+  }],
+}
+```
+
+Поле `RICH_TEXT` хранит как блок JSON редактора, так и проекцию Markdown
+. Трубопровод поколения гласит, что Markdown проекция, так что
+плейсхолдеров, PDF, и общедоступной веб-страницы все работают без изменений —
+смотрите полную
+[`template-record. age-layout.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/document-generator/src/page-layouts/template-record.page-layout.ts).
+Виджеты `FIELD` также поддерживают другие режимы отображения и параметры, включая
+вывод записей вложенной связи на два шага глубже — см. раздел
+[справочник по виджетам field](/l/ru/developers/extend/apps/layout/page-layouts#field-widgets).
+Теперь редакторы пишут шаблоны в соответствующем rich-text редакторе:
+
+<Frame caption="Вкладка Template tab: родной rich-text редактор, связанный с телом.">
+  <img src="/images/docs/developers/extends/apps/document-generator/10-template-editor.png" alt="Запись шаблона с встроенным редактором rich-text" />
+</Frame>
+
+**После этого шага:** документы просматривают красиво и шаблоны можно редактировать
+в приложении. Далее позвольте агенту ИИ сгенерировать их из чата.
+
+<Card title="Далее: Агент ИИ →" icon="robot" href="/l/ru/developers/extend/apps/tutorials/document-generator/ai-agent">
+  Добавьте агента и навык, вызывающий ваш инструмент.
+</Card>

packages/twenty-docs/l/ru/developers/extend/apps/tutorials/document-generator/data-model.mdx

@@ -0,0 +1,135 @@
+---
+title: 1. Модель данных
+icon: database
+description: Типовые документы и шаблоны с объектами, полями и отношениями.
+---
+
+Нашему приложению нужны два пользовательских объекта: **шаблоны документов** (что записывать) и
+**документы** (сгенерированный результат). Давайте определим их.
+
+Строительство каждого файла сущности с CLI — он генерирует правильный UUID и правую папку
+для вас:
+
+```bash filename="Terminal"
+yarn twenty dev:add object
+```
+
+Ниже мы показываем готовые файлы.
+
+<Note>
+Каждый `*_UNIVERSAL_IDENTIFIER` живет в константе
+`src/constants/universal-identifiers.ts` и импортируется там, где используется. В приведенных ниже фрагментах
+эти импорты опущены для краткости — в своих файлах не удаляйте их.
+</Note>
+
+## Объект шаблона
+
+Шаблон имеет `name`, `body` с `{{placeholders}}` и `target`, который
+указывает, предназначен ли он для Person или Company. `body` — это поле
+`RICH_TEXT`, поэтому двадцать дает ему полный редактор rich-text.
+
+```ts filename="src/objects/document-template.object.ts"
+import { defineObject, FieldType } from 'twenty-sdk/define';
+
+export default defineObject({
+  universalIdentifier: DOCUMENT_TEMPLATE_OBJECT_UNIVERSAL_IDENTIFIER,
+  nameSingular: 'documentTemplate',
+  namePlural: 'documentTemplates',
+  labelSingular: 'Document template',
+  labelPlural: 'Document templates',
+  icon: 'IconFileText',
+  labelIdentifierFieldMetadataUniversalIdentifier:
+    TEMPLATE_NAME_FIELD_UNIVERSAL_IDENTIFIER,
+  fields: [
+    { universalIdentifier: TEMPLATE_NAME_FIELD_UNIVERSAL_IDENTIFIER,
+      type: FieldType.TEXT, name: 'name', label: 'Name', icon: 'IconAbc' },
+    { universalIdentifier: TEMPLATE_BODY_FIELD_UNIVERSAL_IDENTIFIER,
+      type: FieldType.RICH_TEXT, name: 'body', label: 'Body', icon: 'IconFileText',
+      description: 'Use {{placeholders}} like {{name.firstName}} or {{jobTitle}}.' },
+    { universalIdentifier: TEMPLATE_TARGET_FIELD_UNIVERSAL_IDENTIFIER,
+      type: FieldType.SELECT, name: 'target', label: 'Target', icon: 'IconTarget',
+      defaultValue: `'PERSON'`,
+      options: [
+        { id: TEMPLATE_TARGET_OPTION_PERSON_UNIVERSAL_IDENTIFIER,
+          value: 'PERSON', label: 'Person', color: 'blue', position: 0 },
+        { id: TEMPLATE_TARGET_OPTION_COMPANY_UNIVERSAL_IDENTIFIER,
+          value: 'COMPANY', label: 'Company', color: 'green', position: 1 },
+      ] },
+  ],
+});
+```
+
+<Warning>
+Опция `SELECT` **values** должна быть `UPPER_CASE` (`PERSON`, не `person`), а опция
+`defaultValue` завернута в дополнительные кавычки: `` `'PERSON'` ``. `label` - это то, что видят
+пользователей.
+</Warning>
+
+## Объект документа
+
+Генерируемый документ хранит отображенный `content` и `status`. Определите
+так же с параметром `status` из `DRAFT` / `GENERATED`. Полный файл:
+[`document.object.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/document-generator/src/objects/document.object.ts).
+
+## Связать их с отношением
+
+Каждый документ должен ссылаться на шаблон, из которого он вышел. Отношения
+**двусторонний** — вы определяете обе стороны в своём собственном файле полей.
+
+```ts filename="src/fields/document-template-relation.field.ts"
+import { defineField, FieldType, OnDeleteAction, RelationType } from 'twenty-sdk/define';
+
+// The "many" side: each document belongs to one template.
+export default defineField({
+  universalIdentifier: DOCUMENT_TEMPLATE_FIELD_UNIVERSAL_IDENTIFIER,
+  objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER,
+  type: FieldType.RELATION,
+  name: 'template',
+  label: 'Template',
+  relationTargetObjectMetadataUniversalIdentifier:
+    DOCUMENT_TEMPLATE_OBJECT_UNIVERSAL_IDENTIFIER,
+  relationTargetFieldMetadataUniversalIdentifier:
+    TEMPLATE_DOCUMENTS_FIELD_UNIVERSAL_IDENTIFIER,
+  universalSettings: {
+    relationType: RelationType.MANY_TO_ONE,
+    onDelete: OnDeleteAction.SET_NULL,
+    joinColumnName: 'templateId',
+  },
+});
+```
+
+Другая сторона (`template-documents-relation.field.ts`) — это поле
+`RelationType.ONE_TO_MANY` с именем `documents`, которое указывает на противоположный путь.
+Смотрите раздел [Relations](/l/ru/developers/extend/apps/data/relations) для полного шаблона.
+
+## Смотрите в двадцать
+
+С запуском `yarn twenty dev` откройте **Settings → Data model**. Оба объекта
+появляются, помеченные вашим приложением.
+
+<Frame caption="Оба пользовательских объекта, принадлежащие приложению Генератор документов.">
+  <img src="/images/docs/developers/extends/apps/document-generator/01-data-model.png" alt="Настройки модели данных с отображением шаблонов документов и документов" />
+</Frame>
+
+Создайте один шаблон для тестирования — имя *Предложение продаж*, установите **цель** на
+*Персонал* и вставьте тело с несколькими заполнителями:
+
+```text
+Dear {{name.firstName}} {{name.lastName}},
+
+As {{jobTitle}} at {{company.name}}, we think you'll love our product.
+
+Best,
+The Team
+```
+
+<Frame caption="Запись шаблона. Тело хранит свои заполнители до тех пор, пока документ не будет сгенерирован.">
+  <img src="/images/docs/developers/extends/apps/document-generator/03-template-record.png" alt="Запись шаблона предложения продаж с плейсхолдером" />
+</Frame>
+
+**После этого шага:** у вас есть объекты `documentTemplate` и `document`, связанные
+отношением и одним шаблоном для генерации данных. Далее заполняется логика.
+
+<Card title="Далее: генерация документов →" icon="bolt" href="/l/ru/developers/extend/apps/tutorials/document-generator/generating-documents">
+  Напишите логическую функцию, которая заполняет шаблон.
+</Card>

packages/twenty-docs/l/ru/developers/extend/apps/tutorials/document-generator/generating-documents.mdx

@@ -0,0 +1,239 @@
+---
+title: 2. Создание документов
+icon: bolt
+description: Одна логическая функция, выставленная в качестве инструмента ИИ и действий рабочего процесса.
+---
+
+Теперь ядро: [логическая функция](/l/ru/developers/extend/apps/logic/logic-functions)
+, загружающая шаблон и запись, заполняет плейсхолдеры, и сохраняет новый документ
+.
+
+Однажды мы напишем бизнес-логику как **обработчик**, а затем выявим его через
+несколько триггеров. В этой главе выводятся две из них — **ИИ инструмент** и
+**действие рабочего процесса**.
+
+## Помощник рендеринга
+
+Держите чистую логику в своем собственном файле, так что легко отсоединить тест. Это преобразует запись
+в токены `{{dot.path}}` и подставляет их.
+
+```ts filename="src/logic-functions/utils/render-template.ts"
+const PLACEHOLDER_PATTERN = /\{\{\s*([\w.]+)\s*\}\}/g;
+
+export const renderTemplate = (body: string, values: Record<string, string>) => {
+  const missingTokens = new Set<string>();
+  const content = body.replace(PLACEHOLDER_PATTERN, (_m, token: string) => {
+    const value = values[token];
+    if (value === undefined || value === '') { missingTokens.add(token); return ''; }
+    return value;
+  });
+  return { content, missingTokens: [...missingTokens] };
+};
+```
+
+<Tip>
+Поскольку этот файл не имеет побочных эффектов, вы можете прочитать его быстрыми модульными тестами
+(`yarn test:unit`). См. раздел [Тестирование](/l/ru/developers/extend/apps/operations/testing).
+</Tip>
+
+## Обработчик
+
+Обработчик использует [`CoreApiClient`](/l/ru/developers/extend/apps/logic/logic-functions)
+для чтения и записи данных CRM. Он загружает шаблон, загружает целевую запись, заполняет
+тело и создает `document`.
+
+```ts filename="src/logic-functions/handlers/generate-document-handler.ts"
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { loadRecordValues } from 'src/logic-functions/utils/load-record-values';
+import { renderTemplate } from 'src/logic-functions/utils/render-template';
+
+export const generateDocumentHandler = async (
+  input: { templateId: string; recordId: string },
+) => {
+  const client = new CoreApiClient();
+
+  // Use a filtered list query, not the singular lookup: the singular query
+  // throws when nothing matches, which would become a 500 instead of a 404.
+  const { documentTemplates } = await client.query({
+    documentTemplates: {
+      __args: { filter: { id: { eq: input.templateId } }, first: 1 },
+      edges: { node: { id: true, name: true, body: true, target: true } },
+    },
+  });
+  const documentTemplate = documentTemplates?.edges?.[0]?.node;
+  if (!documentTemplate?.id) return { success: false, status: 404, message: 'Template not found.' };
+
+  const record = await loadRecordValues(client, documentTemplate.target, input.recordId);
+  if (!record.found) return { success: false, status: 404, message: 'Record not found.' };
+
+  const { content, missingTokens } = renderTemplate(documentTemplate.body ?? '', record.values);
+
+  const { createDocument } = await client.mutation({
+    createDocument: {
+      __args: { data: {
+        name: `${documentTemplate.name} — ${record.displayName}`,
+        content, status: 'GENERATED', templateId: documentTemplate.id,
+      } },
+      id: true, name: true,
+    },
+  });
+
+  return { success: true, documentId: createDocument.id, content, missingTokens };
+};
+```
+
+`loadRecordValues` запускает другой запрос для персона против компании и flattens
+результат — см.
+[`load-record-values.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/document-generator/src/logic-functions/utils/load-record-values.ts).
+
+## Расскажите об этом как инструменте и действии рабочего процесса
+
+Один "defineLogicFunction" может иметь несколько триггеров. Здесь `toolTriggerSettings`
+делает его вызываемым агентами ИИ, а `workflowActionTriggerSettings` превращает его в
+шаг в визуальном конструкторе рабочих процессов. Оба описывают свои входные данные схемой JSON.
+
+```ts filename="src/logic-functions/generate-document.ts"
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { jsonSchemaToInputSchema } from 'twenty-sdk/logic-function';
+import { GENERATE_DOCUMENT_LOGIC_FUNCTION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
+import { generateDocumentHandler } from 'src/logic-functions/handlers/generate-document-handler';
+import { generateDocumentInputSchema } from 'src/logic-functions/schemas/generate-document-input.schema';
+
+export default defineLogicFunction({
+  universalIdentifier: GENERATE_DOCUMENT_LOGIC_FUNCTION_UNIVERSAL_IDENTIFIER,
+  name: 'generate-document',
+  description: 'Generate a document from a template and a CRM record.',
+  timeoutSeconds: 30,
+  toolTriggerSettings: {
+    inputSchema: generateDocumentInputSchema,
+  },
+  workflowActionTriggerSettings: {
+    label: 'Generate Document',
+    icon: 'IconFileText',
+    inputSchema: jsonSchemaToInputSchema(generateDocumentInputSchema),
+    outputSchema: [{ type: 'object', properties: {
+      success: { type: 'boolean' }, documentId: { type: 'string' },
+    } }],
+  },
+  handler: generateDocumentHandler,
+});
+```
+
+Входная схема — это обычная схема JSON, описывающая `templateId` и `recordId` —
+см. [`generate-document-input.schema.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/document-generator/src/logic-functions/schemas/generate-document-input.schema.ts).
+
+## Предоставить доступ
+
+Логические функции выполняются под ролью приложения. Ему нужно читать шаблоны и записи
+и создавать документы, поэтому разрешите это в `src/roles/default-role.ts`:
+
+```ts
+export default defineApplicationRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: 'Document Generator default role',
+  canReadAllObjectRecords: true,
+  canUpdateAllObjectRecords: true,
+  canAccessAllTools: true,
+  canBeAssignedToAgents: true,
+  permissionFlagUniversalIdentifiers: [SystemPermissionFlag.UPLOAD_FILE],
+});
+```
+
+`UPLOAD_FILE` позволяет функции загрузить сгенерированный PDF в следующем разделе.
+Смотрите [Roles](/l/ru/developers/extend/apps/config/roles) для получения более четких разрешений.
+
+## Прикрепить настоящий PDF-файл
+
+Поля отображаемого текста полезны, но пользователи хотят иметь настоящий документ. Давайте сгенерируем
+**PDF** и храним его в записи в качестве загружаемого файла.
+
+Сначала поставьте объект `document` поле `FILES` для удержания PDF. Приложения загружают файлы
+в **собственные** файловые поля, поэтому это поле определяет маршрут загрузки:
+
+```ts filename="src/objects/document.object.ts"
+{
+  universalIdentifier: DOCUMENT_FILE_FIELD_UNIVERSAL_IDENTIFIER,
+  type: FieldType.FILES,
+  name: 'file',
+  label: 'File',
+  icon: 'IconFileTypePdf',
+  universalSettings: { maxNumberOfValues: 1 },
+}
+```
+
+Введите, что PDF. Приложение — это настоящий проект Node, поэтому вы можете добавить любой нужный пакет
+npm и импортировать его, как и где угодно ещё. Мы используем **[pdf-lib](https://pdf-lib.js.org/)**
+для рисования PDF и **[marked](https://marked.js.org/)** для разбора тела Markdown
+— CLI устанавливает их во время работы функции:
+
+```bash filename="Terminal"
+yarn add pdf-lib marked
+```
+
+Полный помощник
+[`generate-document-pdf.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/document-generator/src/logic-functions/utils/generate-document-pdf.ts).
+Он анализирует Markdown в токены с `marked. exer`, затем расположите их с помощью
+pdf-lib: настоящие заголовки, **черный**/*курсив* пробег, пуля и нумерованные списки,
+blockquotes and rules — отполированный, многостраничный A4 рендеринг самого шаблона
+вместо стенки текста.
+
+<Frame caption="Сгенерированный PDF: реальная типография и форматирование разметки, отрисовка тела шаблона.">
+  <img src="/images/docs/developers/extends/apps/document-generator/07b-generated-pdf.png" alt="Отполированный, продаваемый файл PDF" />
+</Frame>
+
+<Note>
+Встроенные шрифты pdf-lib используют кодировку WinAnsi, поэтому западноевропейские символы с диакритикой отображаются
+"из коробки"; вспомогательная функция отображает типографские кавычки и тире и отбрасывает символы, которые она
+не может закодировать. Отображение нелатинских скриптов (китайский, арабский, кириллица) означало бы
+встраивание шрифта Unicode.
+</Note>
+
+Затем загрузите его и сохраните ссылку на запись. `uploadFile` маршруты байт
+в поле файлы, принадлежащее приложению; возвращается `id`, что вы сохраните:
+
+```ts filename="src/logic-functions/handlers/generate-document-handler.ts"
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { generateDocumentPdf } from 'src/logic-functions/utils/generate-document-pdf';
+
+const documentName = `${documentTemplate.name} — ${record.displayName}`;
+const bytes = await generateDocumentPdf(documentName, content);
+const fileName = 'proposal.pdf';
+
+const uploaded = await new MetadataApiClient().uploadFile(
+  Buffer.from(bytes),
+  fileName,
+  'application/pdf',
+  DOCUMENT_FILE_FIELD_UNIVERSAL_IDENTIFIER,
+);
+
+await client.mutation({
+  updateDocument: {
+    __args: {
+      id: documentId,
+      data: { file: [{ fileId: uploaded.id, label: fileName }] },
+    },
+    id: true,
+  },
+});
+```
+
+Сгенерированный документ теперь поддерживает загрузку PDF:
+
+<Frame caption="Сгенерированный PDF, хранится в поле File документа.">
+  <img src="/images/docs/developers/extends/apps/document-generator/08-document-with-pdf.png" alt="Документ записи с созданным PDF файлом" />
+</Frame>
+
+<Note>
+`uploadFile` только цели **app-owned** полей файлов (поэтому для загрузки всегда требуется
+приложение, которое владеет полем и флаг роли `UPLOAD_FILE`). Поэтому PDF
+опирается на собственное поле `file` (`file`) — тот же шаблон, что и
+[call-recorder app](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/public/call-recorder)
+используется для записей.
+</Note>
+
+**После этого шага:** у каждого сгенерированного документа есть реальный, загружаемый PDF. Но
+ничего не может *вызвать* генератор из пользовательского интерфейса — для этого нам нужен HTTP маршрут.
+
+<Card title="Далее: HTTP-маршруты →" icon="земля" href="/l/ru/developers/extend/apps/tutorials/document-generator/http-routes">
+  Сервис функции по HTTP и рендеринг документов как веб-страниц.
+</Card>

packages/twenty-docs/l/ru/developers/extend/apps/tutorials/document-generator/http-routes.mdx

@@ -0,0 +1,150 @@
+---
+title: 3. HTTP-маршруты
+icon: globe
+description: Включает функцию по HTTP и отображает документы как веб-страницы.
+---
+
+Этот же обработчик также может отвечать на HTTP-запросы. Мы добавим два маршрута:
+
+* **POST** конечная точка интерфейса для генерации документа, и
+* публичная **GET** конечная точка, которая отображает документ в виде печатной веб-страницы.
+
+Оба используют `httpRouteTriggerSettings`. Маршруты приложения доступны по пути `/s/`; на локальных
+и самостоятельно размещенных инстансах этот путь обслуживается вашим сервером Twenty
+(например, `http://localhost:2020/s/documents/generate`). В Twenty Cloud `RestApiClient`
+разрешает путь через домен функций рабочего пространства.
+
+## Маршрут POST — генерировать по запросу
+
+Это повторно использует `generateDocumentHandler`, так что нет логики повторять — просто тонкий
+адаптер, который читает тело запроса.
+
+```ts filename="src/logic-functions/generate-document-route.ts"
+import { defineLogicFunction, type RoutePayload } from 'twenty-sdk/define';
+import { Response } from 'twenty-sdk/logic-function';
+import { generateDocumentHandler } from 'src/logic-functions/handlers/generate-document-handler';
+
+const handler = async (event: RoutePayload): Promise<Response> => {
+  const body = event.body as Record<string, unknown> | null;
+
+  const result = await generateDocumentHandler({
+    templateId: (body?.templateId as string) ?? '',
+    recordId: (body?.recordId as string) ?? '',
+  });
+
+  // Map the handler's failure reason onto a real HTTP status (400/404/500)
+  // instead of always returning 200.
+  return new Response(JSON.stringify(result), {
+    status: result.success ? 200 : (result.status ?? 400),
+    headers: { 'Content-Type': 'application/json' },
+  });
+};
+
+export default defineLogicFunction({
+  universalIdentifier: GENERATE_DOCUMENT_ROUTE_UNIVERSAL_IDENTIFIER,
+  name: 'generate-document-route',
+  timeoutSeconds: 30,
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/documents/generate',
+    httpMethod: 'POST',
+    isAuthRequired: true,
+  },
+});
+```
+
+Общий обработчик при сбое возвращает предлагаемое значение `status`, чтобы маршрут
+мог ответить корректным кодом `4xx`/`5xx`. `isAuthRequired: true` означает, что звонящий
+должен представить действительный токен — передний компонент в следующей главе передает токен доступа пользователя
+.
+
+## GET маршрут — отображается как веб-страница
+
+Чтобы вернуть HTML вместо JSON, оберните тело в `Response` с заголовком
+`Content-Type`. Этот маршрут является публичным (`isAuthRequired: false`), так что сгенерированный
+документ может быть использован как ссылка.
+
+```ts filename="src/logic-functions/view-document.ts"
+import { defineLogicFunction, type RoutePayload } from 'twenty-sdk/define';
+import { Response } from 'twenty-sdk/logic-function';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { documentHtmlPage } from 'src/utils/render-document';
+
+const htmlResponse = (html: string, status = 200): Response =>
+  new Response(html, { status, headers: { 'Content-Type': 'text/html; charset=utf-8' } });
+
+const handler = async (event: RoutePayload): Promise<Response> => {
+  const documentId = event.queryStringParameters?.id;
+
+  if (!documentId) {
+    return htmlResponse(documentHtmlPage('Missing document id', 'Provide ?id=<documentId>.'), 400);
+  }
+
+  // Filtered list query so an unknown id renders a clean 404 page instead of throwing.
+  const { documents } = await new CoreApiClient().query({
+    documents: {
+      __args: { filter: { id: { eq: documentId } }, first: 1 },
+      edges: { node: { id: true, name: true, content: true } },
+    },
+  });
+
+  const document = documents?.edges?.[0]?.node;
+  if (!document?.id) {
+    return htmlResponse(documentHtmlPage('Document not found', `No document with id ${documentId}.`), 404);
+  }
+
+  return htmlResponse(documentHtmlPage(document.name ?? 'Document', document.content ?? ''));
+};
+
+export default defineLogicFunction({
+  universalIdentifier: VIEW_DOCUMENT_ROUTE_UNIVERSAL_IDENTIFIER,
+  name: 'view-document',
+  timeoutSeconds: 15,
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/documents/view',
+    httpMethod: 'GET',
+    isAuthRequired: false,
+  },
+});
+```
+
+`documentHtmlPage` отображает тело Markdown в HTML (с [marked](https://marked.js.org/),
+увлажняет) и выбросит его в чистый, страница для печати, которая показывает только содержимое шаблона
+— так же, как и PDF и превью для приложений.
+[См. помощник](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/document-generator/src/utils/render-document.ts).
+
+## Попробовать
+
+С помощью шаблона и персона в вашей рабочей области, вызовите маршрут (захватите токен из
+**Settings → APIs и Webhooks**):
+
+```bash filename="Terminal"
+curl -X POST http://localhost:2020/s/documents/generate \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"templateId":"<templateId>","recordId":"<personId>"}'
+# → {"success":true,"documentId":"...","content":"Dear Jeffery Griffin, ..."}
+```
+
+Откройте возвращаемый документ в вашем браузере:
+
+```
+http://localhost:2020/s/documents/view?id=<documentId>
+```
+
+<Frame caption="Публичный GET маршрут отображает документ в виде страницы для печати.">
+  <img src="/images/docs/developers/extends/apps/document-generator/07-rendered-document.png" alt="Веб-страница документа" />
+</Frame>
+
+<Tip>
+Вы также можете транслировать журналы функций в процессе тестирования с помощью
+`yarn twenty dev:function:logs` или вызвать их напрямую с помощью
+`yarn twenty dev:function:exec`.
+</Tip>
+
+**После этого шага:** приложение может генерировать документы по HTTP и отдавать их как
+веб-страницы. Теперь давайте сделаем его пригодным для использования без `curl`.
+
+<Card title="Далее: построение пользовательского интерфейса →" icon="table-columns" href="/l/ru/developers/extend/apps/tutorals/document-generator/building-the-ui">
+  Виды, навигация, команда и передний компонент.
+</Card>

packages/twenty-docs/l/ru/developers/extend/apps/tutorials/document-generator/overview.mdx

@@ -0,0 +1,67 @@
+---
+title: "Учебник: Генератор документов"
+icon: wand-magic-sparkles
+description: Создайте реальное приложение Twenty, которое генерирует персонализированные документы из ваших данных CRM.
+---
+
+В этом учебнике вы создадите **Document Generator** — приложение, которое преобразует многоразовые шаблоны в персонализированные документы, используя данные, уже находящиеся в вашей CRM.
+
+Один раз напишите шаблон с `{{placeholders}}`, затем генерируйте заполненный документ для любого Контакта или Компании в один клик — из командного меню, от агента ИИ или из рабочего процесса.
+
+<Frame caption="Один шаблон, сгенерированный для конкретного человека, открыт как страница для печати.">
+  <img src="/images/docs/developers/extends/apps/document-generator/07-rendered-document.png" alt="Сгенерированное коммерческое предложение" />
+</Frame>
+
+## Чему вы научитесь
+
+Каждая глава добавляет одну возможность. К концу вы познакомитесь с большинством возможностей SDK.
+
+| Глава                                                                                               | Возможность                                                                                                                                            | Справочник                                                          |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| [1. Модель данных](/l/ru/developers/extend/apps/tutorials/document-generator/data-model)                 | Объекты, поля и связь                                                                                                                                  | [Данные](/l/ru/developers/extend/apps/data/overview)                     |
+| [2. Создание документов](/l/ru/developers/extend/apps/tutorials/document-generator/generating-documents) | Логическая функция (инструмент ИИ + действие рабочего процесса), которая заполняет шаблон Markdown и прикрепляет отточенный PDF                        | [Логические функции](/l/ru/developers/extend/apps/logic/logic-functions) |
+| [3. HTTP-маршруты](/l/ru/developers/extend/apps/tutorials/document-generator/http-routes)                | Выдача JSON и доступной по ссылке HTML-страницы из маршрутов                                                                                           | [Логические функции](/l/ru/developers/extend/apps/logic/logic-functions) |
+| [4. Создание интерфейса](/l/ru/developers/extend/apps/tutorials/document-generator/building-the-ui)      | Представления, навигация, командное меню и фронтенд-компоненты, которые показывают предварительный просмотр документа и позволяют редактировать шаблон | [Макет](/l/ru/developers/extend/apps/layout/overview)                    |
+| [5. Агент ИИ](/l/ru/developers/extend/apps/tutorials/document-generator/ai-agent)                        | Агент + навык                                                                                                                                          | [Навыки и агенты](/l/ru/developers/extend/apps/logic/skills-and-agents)  |
+| [6. Публикация](/l/ru/developers/extend/apps/tutorials/document-generator/publishing)                    | Выпустить в маркетплейс                                                                                                                                | [Публикация](/l/ru/developers/extend/apps/operations/publishing)         |
+
+## Требования
+
+К этому моменту вы уже должны были пройти [быстрый старт](/l/ru/developers/extend/apps/getting-started/quick-start):
+локальный сервер Twenty, запущенный на порту `2020`, и CLI, аутентифицированный в нем.
+
+Если нет, разверните и запустите его сейчас:
+
+```bash filename="Terminal"
+npx create-twenty-app@latest document-generator
+cd document-generator
+yarn twenty dev
+```
+
+<Note>
+Предпочитаете читать готовый код? Полное приложение находится в
+[`packages/twenty-apps/examples/document-generator`](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/document-generator).
+Каждый фрагмент кода ниже скопирован из него.
+</Note>
+
+## Как устроено приложение
+
+<Frame>
+  <img src="/images/docs/developers/extends/apps/document-generator/how-it-fits.svg" alt="Шаблон с плейсхолдерами преобразуется в отточенный документ с PDF, запускаемый из командного меню, агентом ИИ, рабочим процессом или общей ссылкой" />
+</Frame>
+
+Вы один раз пишете **шаблон** в редакторе форматированного текста с `{{placeholders}}`. Выбор
+шаблона и записи CRM заполняет плейсхолдеры и сохраняет отточенный
+**документ** (с PDF-файлом). Все остальное — командное меню, агент ИИ,
+шаг рабочего процесса, общая ссылка — это всего лишь разные способы запустить
+один и тот же генератор.
+
+## Поддерживайте этот цикл
+
+Оставьте `yarn twenty dev` запущенной в терминале на протяжении всего учебника. Каждый раз, когда
+вы добавляете или изменяете файл в `src/`, он заново синхронизируется с вашим сервером в течение нескольких
+секунд, так что вы можете наблюдать, как каждая новая возможность появляется в интерфейсе по мере ее создания.
+
+<Card title="Начните разработку →" icon="database" href="/l/ru/developers/extend/apps/tutorials/document-generator/data-model">
+  Глава 1: моделируем документы и шаблоны.
+</Card>

packages/twenty-docs/l/ru/developers/extend/apps/tutorials/document-generator/publishing.mdx

@@ -0,0 +1,137 @@
+---
+title: 6. Публикация
+icon: rocket
+description: Добавьте метаданные торговой площадки и публикуйте свое приложение.
+---
+
+Ваше приложение работает. Последним шагом является его описание для рынка и публикации.
+
+## Добавить метаданные торговой площадки
+
+[Конфигурация приложений](/l/ru/developers/extend/apps/config/application) имеет идентификацию
+отображаемую на рынке: автор, категорию, логотип и поддержку
+ссылок. Поместите логотип в `public/` и укажите его в `logo`.
+
+```ts filename="src/application-config.ts"
+import { defineApplication } from 'twenty-sdk/define';
+
+export default defineApplication({
+  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+  displayName: 'Document Generator',
+  description:
+    'Create reusable document templates and generate personalized documents from your CRM records.',
+  logo: 'public/document-generator.svg',
+  author: 'Twenty',
+  category: 'Productivity',
+  websiteUrl: 'https://docs.twenty.com/l/ru/developers/extend/apps',
+  termsUrl: 'https://www.twenty.com/terms',
+  emailSupport: 'contact@twenty.com',
+  issueReportUrl: 'https://github.com/twentyhq/twenty/issues',
+});
+```
+
+<Tip>
+Роль по умолчанию объявлена `defineApplicationRole()` в своем собственном файле — вы
+больше не передаете `defaultRoleUniversalIdentifier` здесь.
+</Tip>
+
+Также добавьте ключевое слово `twenty-app` в `package.json`, чтобы приложение было найдено:
+
+```json filename="package.json"
+{ "keywords": ["twenty-app"] }
+```
+
+## Добавить скриншоты галереи
+
+Список торговых площадок продается со скриншотами. Поместите несколько PNG-файлов в
+`public/gallery/` и укажите их в `galleryImages` — они будут отображаться как галерея
+на странице каталога, в порядке следования в массиве.
+
+```ts filename="src/application-config.ts"
+export default defineApplication({
+  // ...identity from above
+  galleryImages: [
+    'public/gallery/01-generated-document.png',
+    'public/gallery/02-command-menu.png',
+    'public/gallery/03-template-editor.png',
+    'public/gallery/04-documents.png',
+  ],
+});
+```
+
+<Tip>
+Возглавие с выплатом: сделайте первый скриншот завершённый результат (сгенерированный
+документ), затем покажите как он срабатывает и аутентифицирует. Используйте четкие, высококачественные
+скриншоты — это первое, что видит пользователь.
+</Tip>
+
+Дайте `README.md` ту же обработку — это главная страница npm и GitHub.
+Начните с описания ценностного предложения и скриншота, перечислите ключевые функции,
+а затем поместите технические детали ниже основной части страницы.
+
+## Проверить перед отправкой
+
+Выполнить те же ворота CI делает:
+
+```bash filename="Terminal"
+yarn lint          # oxlint
+yarn typecheck     # tsgo
+yarn test:unit     # unit tests
+yarn twenty plan   # preview the metadata diff
+```
+
+План точно показывает, что изменится на сервере, не применяя эти изменения —
+хорошая финальная проверка. См.
+[Testing](/l/ru/developers/extend/apps/operations/testing) и
+[Синхронизация и восстановление](/l/ru/developers/extend/apps/operations/sync-and-recovery).
+
+## Публикация
+
+```bash filename="Terminal"
+# Public app → npm (default)
+yarn twenty app:publish
+
+# Or deploy privately to a specific server's registry
+yarn twenty app:publish --private -r <remote>
+```
+
+`app:publish` строит и публикует в npm по умолчанию; `--private` загружает
+tarball в частный реестр Twenty сервера. Для постройки опубликованного приложения
+в магазине экземпляра, запустите синхронизацию каталога:
+
+```bash filename="Terminal"
+yarn twenty dev:catalog-sync -r <remote>
+```
+
+Подробности и контрольный список для выпуска:
+[Публикация](/l/ru/developers/extend/apps/operations/publishing).
+
+## Вы создали приложение 🎉
+
+В шести главах вы использовали большую часть поверхности SDK:
+
+* **Объекты, поля и отношение** для моделирования данных
+* **логическая функция** выставлена как **ИИ инструмент**, **действие рабочего процесса** и **HTTP маршруты**
+* **Виды, навигация, команда и передний компонент** для интерфейса
+* **Агент + навык** для естественного поколения
+* **Метаданные торговой площадки** и поток публикаций
+
+Готовое приложение находится по адресу
+[`packages/twenty-apps/examples/document-generator`](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/document-generator).
+
+## Где перейти далее
+
+<CardGroup cols={2}>
+  <Card title="Ссылка на данные" icon="database" href="/l/ru/developers/extend/apps/data/overview">
+    Каждый параметр типа поля, отношения и индекса.
+  </Card>
+  <Card title="Ссылка на логику" icon="bolt" href="/l/ru/developers/extend/apps/logic/overview">
+    Вызовы cron и события базы данных, хранилище ключевого значения, OAuth соединения.
+  </Card>
+  <Card title="Ссылка на макет" icon="table-columns" href="/l/ru/developers/extend/apps/layout/overview">
+    Панели страниц, виджеты панели управления и другие поверхности интерфейса.
+  </Card>
+  <Card title="Операции" icon="rocket" href="/l/ru/developers/extend/apps/operations/overview">
+    CLI, testing, remotes and CI.
+  </Card>
+</CardGroup>