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

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).