@intlayer/docs 9.1.3 → 9.3.0

package/docs/ru/intlayer_with_vite+vue.md

@@ -30,9 +30,7 @@ history:
 author: aymericzip
 ---
 
-# Переведите ваш Vite and Vue с Intlayer | Интернационализация (i18n)
-
-Смотрите [Шаблон приложения](https://github.com/aymericzip/intlayer-vite-vue-template) на GitHub.
+# Переведите ваш сайт Vite и Vue с помощью Intlayer | Интернационализация (i18n)
 
 ## Оглавление
 

package/docs/ru/live-sync.md

@@ -13,6 +13,10 @@ keywords:
   - Intlayer
   - Next.js
   - Vite
+slugs:
+  - doc
+  - concept
+  - live-sync
 history:
   - version: 9.0.0
     date: 2026-07-08

package/docs/ru/packages/intlayer/getLocalizedUrl.md

@@ -59,36 +59,44 @@ getLocalizedUrl(
 
 ## Параметры
 
-## Описание
-
-Функция `getLocalizedUrl` генерирует локализованный URL, добавляя в начало заданного URL указанный локаль. Она обрабатывает как абсолютные, так и относительные URL, обеспечивая применение правильного префикса локали в соответствии с конфигурацией.
-
----
-
-## Параметры
+### Обязательные параметры
 
 - `url: string`
-  - **Описание**: Исходная строка URL, к которой будет добавлен префикс локали.
-  - **Тип**: `string`
+  - **Description**: Исходная строка URL, которая должна быть дополнена локалью.
+  - **Type**: `string`
+  - **Required**: Yes
 
 - `currentLocale: Locales`
-  - **Описание**: Текущая локаль, для которой локализуется URL.
-  - **Тип**: `Locales`
-
-- `locales: Locales[]`
-  - **Описание**: Необязательный массив поддерживаемых локалей. По умолчанию используются локали, настроенные в проекте.
-  - **Тип**: `Locales[]`
-  - **По умолчанию**: [`Конфигурация проекта`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md#middleware)
-
-- `defaultLocale: Locales`
-  - **Описание**: Локаль по умолчанию для приложения. По умолчанию используется локаль по умолчанию, настроенная в проекте.
-  - **Тип**: `Locales`
-  - **По умолчанию**: [`Конфигурация проекта`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md#middleware)
-
-- `prefixDefault: boolean`
-  - **Описание**: Нужно ли добавлять префикс для локали по умолчанию. По умолчанию используется значение, настроенное в проекте.
-  - **Тип**: `boolean`
-  - **По умолчанию**: [`Конфигурация проекта`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md#middleware)
+  - **Description**: Текущая локаль, для которой выполняется локализация URL.
+  - **Type**: `Locales`
+  - **Required**: Yes
+
+### Дополнительные параметры
+
+- `options?: object`
+  - **Description**: Объект конфигурации для поведения локализации URL.
+  - **Type**: `object`
+  - **Required**: No (Optional)
+
+  - `options.locales?: Locales[]`
+    - **Description**: Массив поддерживаемых локалей. Если не предоставлен, использует настроенные локали из конфигурации вашего проекта.
+    - **Type**: `Locales[]`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md#middleware)
+
+  - `options.defaultLocale?: Locales`
+    - **Description**: Локаль по умолчанию для приложения. Если не предоставлена, использует настроенную локаль по умолчанию из конфигурации вашего проекта.
+    - **Type**: `Locales`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Description**: Режим маршрутизации URL для обработки локалей. Если не предоставлен, использует настроенный режим из конфигурации вашего проекта.
+    - **Type**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md#middleware)
+    - **Modes**:
+      - `prefix-no-default`: Без префикса для локали по умолчанию, с префиксом для всех остальных
+      - `prefix-all`: Префикс для всех локалей, включая локаль по умолчанию
+      - `no-prefix`: Без префикса локали в URL
+      - `search-params`: Использование параметров запроса для локали (например, `?locale=fr`)
 
 ### Возвращает
 

package/docs/ru/packages/intlayer/getMultilingualUrls.md

@@ -49,26 +49,12 @@ author: aymericzip
 
 ## Параметры
 
-## Параметры
+### Обязательные параметры
 
 - `url: string`
-  - **Описание**: Исходная строка URL, к которой будут добавлены префиксы языков.
-  - **Тип**: `string`
-
-- `locales: Locales[]`
-  - **Описание**: Необязательный массив поддерживаемых языков. По умолчанию используется конфигурируемый список языков в проекте.
-  - **Тип**: `Locales[]`
-  - **По умолчанию**: `localesDefault`
-
-- `defaultLocale: Locales`
-  - **Описание**: Язык по умолчанию для приложения. По умолчанию используется конфигурируемый язык по умолчанию в проекте.
-  - **Тип**: `Locales`
-  - **По умолчанию**: `defaultLocaleDefault`
-
-- `prefixDefault: boolean`
-  - **Описание**: Нужно ли добавлять префикс для языка по умолчанию. По умолчанию используется настроенное значение в проекте.
-  - **Тип**: `boolean`
-  - **По умолчанию**: `prefixDefaultDefault`
+  - **Description**: Исходная строка URL, которая будет префиксирована локалями.
+  - **Type**: `string`
+  - **Required**: Да
 
 ### Опциональные параметры
 

package/docs/ru/packages/react-intlayer/useDictionary.md

@@ -24,6 +24,10 @@ history:
 author: aymericzip
 ---
 
+# Документация хука useDictionary
+
+Хук `useDictionary` позволяет обрабатывать объект, похожий на словарь (содержащий ключи и содержимое), и обрабатывать переводы, перечисления и т. д. в нём. В отличие от `useIntlayer`, который предназначен для работы с генерируемыми объявлениями словарей, `useDictionary` более гибок и может использоваться с любым объектом, который соответствует структуре словаря.
+
 ## Пример использования в React
 
 Ниже приведён пример использования хука `useDictionary` в React-компоненте:
@@ -45,27 +49,6 @@ const ComponentExample: FC = () => {
 };
 ```
 
-## Интеграция на сервере
-
-Если вы используете хук `useDictionary` вне `IntlayerProvider`, локаль должна быть явно передана в качестве параметра при рендеринге компонента:
-
-```tsx fileName="./ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useDictionary } from "react-intlayer/server";
-import clientComponentExampleContent from "./component.content";
-
-const ServerComponentExample: FC<{ locale: string }> = ({ locale }) => {
-  const { content } = useDictionary(clientComponentExampleContent, locale);
-
-  return (
-    <div>
-      <h1>{content.title}</h1>
-      <p>{content.content}</p>
-    </div>
-  );
-};
-```
-
 ## Дополнительные советы
 
 - **Типобезопасность**: Всегда используйте `Dictionary` для определения ваших словарей, чтобы обеспечить типобезопасность.

package/docs/ru/packages/vite-intlayer/exports.md

@@ -48,3 +48,18 @@ import "vite-intlayer";
 | `intlayerProxy`      | Плагин middleware для разработки, отвечающий за определение локали и маршрутизацию.      | -                                                                                                                      |
 | `intlayerMiddleware` | (**Устаревший**) Псевдоним для `intlayerProxy`.                                          | -                                                                                                                      |
 | `intlayerPrune`      | Плагин для tree-shaking и удаления неиспользуемых словарей во время сборки (build time). | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/vite-intlayer/intlayerPrune.md) |
+
+### Утилиты
+
+| Export                       | Description                                                                                             | Related Doc                                                                                                            |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `createIntlayerProxyHandler` | Возвращает фреймворк-независимый Node.js `(req, res, next)` middleware с логикой маршрутизации локалей. | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/vite-intlayer/intlayerProxy.md) |
+
+### Типы
+
+| Export                       | Описание                                                                                                              |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `IntlayerPluginOptions`      | Опции, принимаемые функцией `intlayer()`. Расширяет `GetConfigurationOptions` с помощью `compatCallers` и `proxy`.    |
+| `IntlayerProxyPluginOptions` | Опции, принимаемые функциями `intlayerProxy()` и `createIntlayerProxyHandler()`. Включает `ignore` и `configOptions`. |
+| `IntlayerCompilerOptions`    | Опции, принимаемые функцией `intlayerCompiler()`. Включает `configOptions` и `compilerConfig`.                        |
+| `CompatCallerConfig`         | Переэкспорт из `@intlayer/babel`. Описывает паттерн compat-adapter caller для анализа использования полей.            |

package/docs/ru/packages/vite-intlayer/intlayer.md

@@ -39,11 +39,126 @@ export default defineConfig({
 });
 ```
 
-## Описание
+## Параметры
 
-Плагин выполняет следующие задачи:
+```ts
+import type { IntlayerPluginOptions } from "vite-intlayer";
+```
+
+`IntlayerPluginOptions` расширяет `GetConfigurationOptions` (см. `@intlayer/config`) со следующими дополнительными полями:
+
+| Параметр        | Тип                             | По умолчанию | Описание                                                                                                                                                                    |
+| --------------- | ------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compatCallers` | `CompatCallerConfig[]`          | `[]`         | Дополнительные паттерны вызывающих функций для пакетов compat-adapter (например, `@intlayer/react-i18next`). Передается анализатору использования полей во время сборки.    |
+| `proxy`         | `{ ignore?: (req) => boolean }` | `undefined`  | Параметры, передаваемые встроенному прокси маршрутизации локалей. Используйте `ignore` для исключения определенных путей (например, маршруты API) из маршрутизации локалей. |
+
+Все остальные параметры (`override`, `configFile`, …) передаются непосредственно в `getConfiguration()`.
+
+### Примеры
+
+#### Игнорирование API маршрутов при локализации
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+#### С пользовательским путем к файлу конфигурации
+
+```ts
+export default defineConfig({
+  plugins: [
+    intlayer({
+      configFile: "./config/intlayer.config.ts",
+    }),
+  ],
+});
+```
+
+#### С использованием compat-adapter callers
+
+```ts
+import { intlayer } from "vite-intlayer";
+import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      compatCallers: [reactI18nextCallerConfig],
+    }),
+  ],
+});
+```
+
+## Что делает плагин
+
+### 1. Подготовка словарей
+
+Перед началом сборки (и один раз в час в режиме разработки), `intlayer` вызывает `prepareIntlayer` для компиляции всех файлов `.content.ts` в оптимизированные JSON-словари, хранящиеся в `.intlayer/`.
+
+### 2. Aliases модулей
+
+Плагин добавляет aliases разрешения Vite, так чтобы `import { myDict } from 'intlayer/dictionaries/my-dict'` разрешался в скомпилированный JSON файл на диске. SSR сборки используют `ssr.noExternal` для обеспечения того, чтобы все пакеты `@intlayer/*` были объединены с применёнными aliases.
+
+### 3. Dev-server watcher
+
+В режиме разработки запускается `chokidar` watcher. Когда `.content.ts` файл изменяется, словари перекомпилируются и Vite's HMR распространяет обновление на браузер.
+
+### 4. Встроенный прокси маршрутизации локалей (v9+)
+
+С Intlayer v9 промежуточное ПО `intlayerProxy` регистрируется автоматически внутри `intlayer()`. Оно обрабатывает:
+
+- Обнаружение локали из префикса URL, cookies и заголовка `Accept-Language`.
+- 301 редиректы, когда обнаруженная локаль не совпадает с текущим URL.
+- Внутренние переписывания URL, чтобы фреймворк видел корректный параметр маршрута `[locale]`.
+
+Прокси контролируется параметром `routing.enableProxy` (по умолчанию `true`) в конфигурации Intlayer. Чтобы полностью отключить его:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  routing: { enableProxy: false },
+});
+```
+
+Чтобы настроить поведение прокси без отдельного вызова `intlayerProxy()`, передайте опции `proxy` основному плагину:
+
+```ts
+intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });
+```
+
+Полную справку по поведению маршрутизации см. в [документации intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/vite-intlayer/intlayerProxy.md).
+
+### 5. Встроенный компилятор (v9+)
+
+Когда `compiler.enabled` установлено на `true` **и** `compiler.output` указан в вашей конфигурации Intlayer, `intlayer()` автоматически регистрирует `intlayerCompiler`. Компилятор извлекает встроенные объявления контента, написанные непосредственно в файлах компонентов, и записывает их в словари во время трансформации. See [intlayerCompiler documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/vite-intlayer/intlayerCompiler.md).
+
+### 6. Оптимизация сборки
+
+Во время production сборки плагин добавляет:
+
+- **intlayerOptimize** – Babel трансформация, которая переписывает `useIntlayer('key')` → `useDictionary(hash)` и внедряет прямой импорт JSON.
+- **intlayerPrune** – удаляет неиспользуемые поля содержимого из dictionary JSON.
+- **intlayerMinify** – компактирует dictionary JSON и опционально изменяет названия полей.
+
+Эти оптимизации неактивны в режиме разработки.
+
+## Устаревшие псевдонимы
 
-1. **Подготовка словарей**: Компилирует словари в оптимизированные файлы в начале процесса сборки или dev.
-2. **Режим слежения**: В режиме разработки следит за изменениями в файлах словарей и автоматически перекомпилирует их.
-3. **Алиасы**: Предоставляет алиасы для доступа к словарям в вашем приложении.
-4. **Tree-shaking**: Поддерживает tree-shaking неиспользуемых переводов через плагин `intlayerPrune`.
+| Устаревший экспорт | Замена     |
+| ------------------ | ---------- |
+| `intlayerPlugin`   | `intlayer` |
+| `intLayerPlugin`   | `intlayer` |

package/docs/ru/packages/vite-intlayer/intlayerPrune.md

@@ -30,16 +30,89 @@ author: aymericzip
 
 ## Использование
 
+### As part of `intlayer()` (recommended)
+
+Enable pruning through your Intlayer config and the main plugin handles everything:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // включает как прунинг, так и минификацию
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Standalone
+
+Если вы составляете стек плагинов вручную, `intlayerPrune` и `intlayerMinify` используют объект `PruneContext`, который должен быть создан один раз и передан обоим:
+
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
-import { intlayer, intlayerPrune } from "vite-intlayer";
+import { intlayerPrune, intlayerMinify } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+import { getConfiguration } from "@intlayer/config/node";
+
+const intlayerConfig = getConfiguration();
+const pruneContext = createPruneContext();
 
 export default defineConfig({
-  plugins: [intlayer(), intlayerPrune()],
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext), // опционально, читает из того же контекста
+  ],
 });
 ```
 
-## Описание
+## Как это работает
+
+### 1. Анализ использования (buildStart)
+
+Во время `buildStart` плагин `intlayerOptimize` (также часть `intlayer()`) сканирует каждый файл исходного кода компонента, указанный в `build.filesList`. Для каждого вызова `useIntlayer('key')` или `getIntlayer('key')` он записывает точно, какие поля доступны, например:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// записывает: myDict → { title, description }
+```
+
+Это создает `pruneContext.fieldUsageMap` перед выполнением любых вызовов `transform`.
+
+### 2. JSON pruning (transform, enforce: 'pre')
+
+Когда Vite обрабатывает скомпилированный файл JSON словаря, `intlayerPrune` перехватывает его перед встроенным преобразованием JSON → ESM в Vite. Он читает карту использования полей из `pruneContext` и удаляет любое поле содержимого, которое не находится в записанном наборе использования.
+
+Поддерживаются две формы содержимого:
+
+- **Static dictionaries** — `{ nodeType: "translation", translation: { en: {...}, fr: {...} } }`. Поля обрезаются по локали внутри `translation`.
+- **Dynamic (per-locale) dictionaries** — плоская структура `{ fieldA: ..., fieldB: ... }`. Поля обрезаются на верхнем уровне.
+
+### 3. Граничные случаи
+
+Если структура контента словаря не может быть распознана (например, необычная вложенная форма), она добавляется в `pruneContext.dictionariesWithEdgeCases` и **остается без изменений**. Записывается предупреждение. `intlayerMinify` также пропускает эти словари.
+
+### 4. Field-rename map
+
+При успешном завершении pruning `intlayerPrune` также записывает `pruneContext.dictionaryKeyToFieldRenameMap` — отображение исходных имен полей на короткие псевдонимы. `intlayerMinify` читает эту карту для переименования полей в выходном JSON, а Babel rename pass `intlayerOptimize` обновляет доступы к свойствам в исходных файлах соответственно.
+
+## Условия активации
+
+`intlayerPrune` активен **только** когда все из следующих условий верны:
+
+1. Команда Vite — `build`.
+2. `build.optimize` имеет значение `true` (или `undefined`, что по умолчанию равно `true` для сборок).
+3. `build.purge` имеет значение `true` в вашей конфигурации Intlayer.
 
-Плагин анализирует ваш исходный код, чтобы определить, какие ключи словарей действительно используются. Затем он удаляет любое неиспользуемое содержимое из собранных файлов словарей. Это особенно полезно для крупных проектов с множеством словарей, где в конкретных страницах или компонентах используется только их подмножество.
+Он автоматически **отключается** когда `editor.enabled` имеет значение `true`, потому что редактор требует полного содержимого словаря.

package/docs/ru/releases/v9.md

@@ -374,21 +374,6 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 Установщик загружает `docker-compose.yml` и `.env`, автоматически генерирует необходимые секреты и запускает `docker compose up -d`. Всё — дашборд, API, база данных, хранилище объектов и транзакционная электронная почта — работает локально в контейнерах.
 
-### Включённые сервисы
-
-| Сервис                                   | Назначение                                                                       |
-| ---------------------------------------- | -------------------------------------------------------------------------------- |
-| **app** (TanStack Start)                 | Дашборд UI на порту `3000`                                                       |
-| **backend** (Fastify/Bun)                | REST API на порту `3100`                                                         |
-| **MongoDB 7** (одноузловой набор реплик) | Основная база данных                                                             |
-| **Redis 7**                              | Очереди задач и кэширование                                                      |
-| **MinIO**                                | S3-совместимое хранилище объектов (аватары, скриншоты)                           |
-| **Mailpit**                              | Локальный SMTP-приёмник + веб-интерфейс для транзакционной почты на порту `8025` |
-
-Chromium (используемый для генерации скриншотов через Puppeteer) встроен в образ бэкенда — дополнительный контейнер не требуется.
-
----
-
 ## Примечания по миграции с v8
 
 Если вы обновляетесь с v8, обратите внимание, что v9 не содержит ломающих изменений (breaking changes). Однако вот ключевые изменения:

package/docs/ru/self_hosting.md

@@ -64,6 +64,32 @@ Chromium (используемый для генерации скриншото
 
 ## Быстрый старт
 
+Извлеките и запустите опубликованный образ, указав учетные данные и секреты MongoDB Atlas:
+
+```sh
+docker run -d --name intlayer \
+  -p 3000:3000 \
+  -p 3100:3100 \
+  -p 9000:9000 \
+  -p 9001:9001 \
+  -v intlayer-data:/data \
+  -e DB_ID="<atlas-user>" \
+  -e DB_MDP="<atlas-password>" \
+  -e DB_CLUSTER="<cluster>.xxxxx.mongodb.net" \
+  -e BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
+  -e S3_SECRET_ACCESS_KEY="$(openssl rand -hex 16)" \
+  -e RESEND_API_KEY="<your-resend-key>" \
+  aymericzip/intlayer-selfhost
+```
+
+Затем откройте **http://localhost:3000**.
+
+> Dashboard доступен на `localhost`. См. [Ограничения](#limitations) — опубликованный образ не поддерживает пользовательские домены.
+
+---
+
+## Быстрый старт
+
 ```sh
 curl -fsSL https://intlayer.org/install.sh | sh
 ```
@@ -99,7 +125,16 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ## Переменные окружения
 
-Установщик генерирует готовый к использованию файл `.env`. В таблице ниже описана каждая переменная.
+### Обязательно
+
+| Переменная             | Пример                       | Описание                                                                                                                                                      |
+| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | Пользователь MongoDB Atlas                                                                                                                                    |
+| `DB_MDP`               | _(ваш пароль)_               | Пароль MongoDB Atlas                                                                                                                                          |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | Хост кластера MongoDB Atlas (используется в URI `mongodb+srv://`)                                                                                             |
+| `BETTER_AUTH_SECRET`   | _(сгенерировано)_            | 32-байтовый секрет для подписания сессии                                                                                                                      |
+| `S3_SECRET_ACCESS_KEY` | _(сгенерировано)_            | Секрет для встроенного MinIO                                                                                                                                  |
+| `RESEND_API_KEY`       | _(ваш ключ)_                 | Транзакционные письма через Resend. Требуется для первоначальной настройки, если вы не настроили глобальный SMTP mailer (см. [Global mailer](#global-mailer)) |
 
 ### Обязательные (автоматически генерируемые или запрашиваемые)
 
@@ -141,6 +176,26 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ---
 
+### Глобальная почтовая система
+
+По умолчанию все транзакционные письма отправляются через Resend с использованием `RESEND_API_KEY`. Самостоятельно размещенные развертывания могут вместо этого маршрутизировать **все** письма — включая письма, не связанные с организацией, такие как сброс пароля и магические ссылки — через глобальную почтовую систему, настроенную с помощью переменных окружения.
+
+Установите `MAIL_PROVIDER` для её активации. Если она не установлена, используется почтовая система Resend по умолчанию.
+
+| Переменная           | Пример                         | Описание                                                                                                    |
+| -------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `MAIL_PROVIDER`      | `smtp`                         | Глобальная доставка: `smtp` или `resend`. Оставьте не установленной для использования значений по умолчанию |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Заголовок отправителя. Принимает простой адрес или формат `Name <email>`                                    |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP-хост (обязателен, когда `MAIL_PROVIDER=smtp`)                                                          |
+| `MAIL_SMTP_PORT`     | `587`                          | SMTP-порт (по умолчанию `587`)                                                                              |
+| `MAIL_SMTP_SECURE`   | `false`                        | Неявный TLS. Установите `true` для порта `465`                                                              |
+| `MAIL_SMTP_USER`     | _(ваше имя пользователя)_      | Имя пользователя SMTP (необязательно; опустите для неаутентифицированных релеев)                            |
+| `MAIL_SMTP_PASSWORD` | _(ваш пароль)_                 | Пароль SMTP                                                                                                 |
+
+> Приоритет: собственная почтовая система организации (настроенная из панели управления **Organization**) имеет приоритет над глобальной почтовой системой, которая, в свою очередь, имеет приоритет над стандартным ключом Resend.
+
+---
+
 ## Подключение вашего проекта Intlayer
 
 После запуска стека направьте свой проект на самохостинговый бэкенд и панель управления вместо `intlayer.org`.
@@ -259,47 +314,11 @@ docker run --rm \
 
 ---
 
-## Использование обратного прокси (Nginx / Caddy)
-
-Для production развертываний разместите обратный прокси перед контейнерами приложения и бэкенда вместо того, чтобы открывать их напрямую.
-
-### Пример Nginx
-
-```nginx
-server {
-    listen 80;
-    server_name cms.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
+## Ограничения
 
-server {
-    listen 80;
-    server_name api.example.com;
-
-    location / {
-        proxy_pass http://localhost:3100;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-Обновите следующие переменные `.env`, чтобы они соответствовали вашим публичным доменам:
-
-```sh
-BACKEND_URL=https://api.example.com
-APP_URL=https://cms.example.com
-DOMAIN=example.com
-VITE_BACKEND_URL=https://api.example.com
-VITE_DOMAIN=example.com
-```
-
-> Переменные `VITE_*` встраиваются в образ панели управления во время сборки. Если вы измените их после сборки образа, вам потребуется пересобрать образ `app` (`docker compose build app`) или использовать инъекцию runtime-конфигурации.
+- **MongoDB должна быть внешней (Atlas).** Backend подключается только через `mongodb+srv://` (собирается из `DB_ID` / `DB_MDP` / `DB_CLUSTER`), поэтому обычный `mongodb://host:27017` — включая встроенный `mongod` контейнера — не может быть использован. Предоставьте кластер MongoDB Atlas.
+- **Нет пользовательского домена.** Все URL-адреса `VITE_*`, обращенные к браузеру, встраиваются в приложение во время сборки, и опубликованный образ поставляется со значениями `localhost`. Доступ к панели управления должен осуществляться через `http://localhost:3000`; подача его на общедоступный домен потребует перестройки образа с встроенными целевыми URL-адресами и не поддерживается из коробки.
+- **Email требует работающего mailer.** Начальная настройка требует проверки электронной почты, поэтому должны быть настроены либо `RESEND_API_KEY`, либо [глобальный SMTP mailer](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`). После входа первого администратора каждая организация также может настроить свой собственный SMTP или Resend mailer из панели управления.
 
 ---
 
@@ -324,14 +343,6 @@ docker compose build app
 docker compose up -d app
 ```
 
-### Электронные письма не отправляются
-
-По умолчанию вся исходящая почта перехватывается Mailpit. Откройте `http://localhost:8025`, чтобы увидеть отправленные сообщения. Для отправки реальных писем установите `MAIL_PROVIDER=resend` и `RESEND_API_KEY=<your-key>` в `.env`, затем перезапустите бэкенд:
-
-```sh
-docker compose restart backend
-```
-
 ### Отсутствует корзина MinIO
 
 Если одноразовый сервис `minio-init` не запустился (или запустился до того, как MinIO был готов), создайте корзину вручную: