@intlayer/docs 9.1.3 → 9.3.0

package/docs/pt/intlayer_with_vite+vue.md

@@ -27,9 +27,7 @@ history:
 author: aymericzip
 ---
 
-# Traduza seu Vite and Vue com Intlayer | Internacionalização (i18n)
-
-Veja o [Modelo de Aplicação](https://github.com/aymericzip/intlayer-vite-vue-template) no GitHub.
+# Traduza seu site Vite e Vue usando Intlayer | Internacionalização (i18n)
 
 ## Índice
 

package/docs/pt/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/pt/packages/intlayer/getLocalizedUrl.md

@@ -59,36 +59,44 @@ getLocalizedUrl(
 
 ## Parâmetros
 
-## Descrição
-
-A função `getLocalizedUrl` gera uma URL localizada prefixando a URL fornecida com o locale especificado. Ela lida tanto com URLs absolutas quanto relativas, garantindo que o prefixo de locale correto seja aplicado com base na configuração.
-
----
-
-## Parâmetros
+### Parâmetros Obrigatórios
 
 - `url: string`
-  - **Descrição**: A string da URL original a ser prefixada com um locale.
-  - **Tipo**: `string`
+  - **Description**: A string de URL original a ser prefixada com um locale.
+  - **Type**: `string`
+  - **Required**: Yes
 
 - `currentLocale: Locales`
-  - **Descrição**: O locale atual para o qual a URL está sendo localizada.
-  - **Tipo**: `Locales`
-
-- `locales: Locales[]`
-  - **Descrição**: Array opcional de locales suportados. Por padrão, os locales configurados no projeto são fornecidos.
-  - **Tipo**: `Locales[]`
-  - **Padrão**: [`Configuração do Projeto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md#middleware)
-
-- `defaultLocale: Locales`
-  - **Descrição**: O locale padrão para a aplicação. Por padrão, o locale padrão configurado no projeto é fornecido.
-  - **Tipo**: `Locales`
-  - **Padrão**: [`Configuração do Projeto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md#middleware)
-
-- `prefixDefault: boolean`
-  - **Descrição**: Indica se deve prefixar a URL para o locale padrão. Por padrão, o valor configurado no projeto é fornecido.
-  - **Tipo**: `boolean`
-  - **Padrão**: [`Configuração do Projeto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md#middleware)
+  - **Description**: O locale atual para o qual a URL está sendo localizada.
+  - **Type**: `Locales`
+  - **Required**: Yes
+
+### Parâmetros Opcionais
+
+- `options?: object`
+  - **Description**: Objeto de configuração para o comportamento de localização de URL.
+  - **Type**: `object`
+  - **Required**: Não (Opcional)
+
+  - `options.locales?: Locales[]`
+    - **Description**: Array de locales suportados. Se não fornecido, usa os locales configurados na configuração do seu projeto.
+    - **Type**: `Locales[]`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md#middleware)
+
+  - `options.defaultLocale?: Locales`
+    - **Description**: O locale padrão para a aplicação. Se não fornecido, usa o locale padrão configurado na configuração do seu projeto.
+    - **Type**: `Locales`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Description**: O modo de roteamento de URL para o tratamento de locale. Se não fornecido, usa o modo configurado na configuração do seu projeto.
+    - **Type**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md#middleware)
+    - **Modes**:
+      - `prefix-no-default`: Sem prefixo para o locale padrão, prefixo para todos os outros
+      - `prefix-all`: Prefixo para todos os locales, incluindo o padrão
+      - `no-prefix`: Sem prefixo de locale na URL
+      - `search-params`: Usa parâmetros de query para locale (ex: `?locale=fr`)
 
 ### Retorno
 

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

@@ -50,26 +50,12 @@ getMultilingualUrls(
 
 ## Parâmetros
 
-## Parâmetros
+### Parâmetros Obrigatórios
 
 - `url: string`
-  - **Descrição**: A string da URL original a ser prefixada com as localidades.
-  - **Tipo**: `string`
-
-- `locales: Locales[]`
-  - **Descrição**: Array opcional de localidades suportadas. O padrão são as localidades configuradas no projeto.
-  - **Tipo**: `Locales[]`
-  - **Padrão**: `localesDefault`
-
-- `defaultLocale: Locales`
-  - **Descrição**: A localidade padrão para a aplicação. O padrão é a localidade padrão configurada no projeto.
-  - **Tipo**: `Locales`
-  - **Padrão**: `defaultLocaleDefault`
-
-- `prefixDefault: boolean`
-  - **Descrição**: Se deve prefixar a localidade padrão. O padrão é o valor configurado no projeto.
-  - **Tipo**: `boolean`
-  - **Padrão**: `prefixDefaultDefault`
+  - **Description**: A string de URL original a ser prefixada com locales.
+  - **Type**: `string`
+  - **Required**: Sim
 
 ### Parâmetros Opcionais
 

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

@@ -48,3 +48,18 @@ import "vite-intlayer";
 | `intlayerProxy`      | Plugin middleware de desenvolvimento para tratar a detecção de locale e roteamento. | -                                                                                                                      |
 | `intlayerMiddleware` | (**Obsoleto**) Alias para `intlayerProxy`.                                          | -                                                                                                                      |
 | `intlayerPrune`      | Plugin para tree-shake e remover dicionários não utilizados durante o build.        | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/vite-intlayer/intlayerPrune.md) |
+
+### Utilitários
+
+| Exportação                   | Descrição                                                                                                   | Documentação Relacionada                                                                                               |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `createIntlayerProxyHandler` | Retorna um middleware Node.js agnóstico de framework `(req, res, next)` com lógica de roteamento de locale. | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/vite-intlayer/intlayerProxy.md) |
+
+### Tipos
+
+| Exportação                   | Descrição                                                                                                       |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `IntlayerPluginOptions`      | Opções aceitas por `intlayer()`. Estende `GetConfigurationOptions` com `compatCallers` e `proxy`.               |
+| `IntlayerProxyPluginOptions` | Opções aceitas por `intlayerProxy()` e `createIntlayerProxyHandler()`. Inclui `ignore` e `configOptions`.       |
+| `IntlayerCompilerOptions`    | Opções aceitas por `intlayerCompiler()`. Inclui `configOptions` e `compilerConfig`.                             |
+| `CompatCallerConfig`         | Re-exportação de `@intlayer/babel`. Descreve um padrão de chamador compat-adapter para análise de uso de campo. |

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

@@ -39,11 +39,126 @@ export default defineConfig({
 });
 ```
 
-## Descrição
+## Opções
 
-O plugin realiza as seguintes tarefas:
+```ts
+import type { IntlayerPluginOptions } from "vite-intlayer";
+```
+
+`IntlayerPluginOptions` estende `GetConfigurationOptions` (ver `@intlayer/config`) com os seguintes campos adicionais:
+
+| Opção           | Tipo                            | Padrão      | Descrição                                                                                                                                                      |
+| --------------- | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compatCallers` | `CompatCallerConfig[]`          | `[]`        | Padrões de chamador extra para pacotes compat-adapter (ex.: `@intlayer/react-i18next`). Passado ao analisador de uso de campo no momento da compilação.        |
+| `proxy`         | `{ ignore?: (req) => boolean }` | `undefined` | Opções encaminhadas para o proxy de roteamento de locale agrupado. Use `ignore` para excluir caminhos específicos (ex.: rotas de API) do roteamento de locale. |
+
+Todas as outras opções (`override`, `configFile`, …) são encaminhadas diretamente para `getConfiguration()`.
+
+### Exemplos
+
+#### Ignorar rotas de API do roteamento de locale
+
+```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"),
+      },
+    }),
+  ],
+});
+```
+
+#### Com um caminho de arquivo de configuração personalizado
+
+```ts
+export default defineConfig({
+  plugins: [
+    intlayer({
+      configFile: "./config/intlayer.config.ts",
+    }),
+  ],
+});
+```
+
+#### Com callers compat-adapter
+
+```ts
+import { intlayer } from "vite-intlayer";
+import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      compatCallers: [reactI18nextCallerConfig],
+    }),
+  ],
+});
+```
+
+## O que o plugin faz
+
+### 1. Preparação do dicionário
+
+Antes do build iniciar (e uma vez por hora em dev), `intlayer` chama `prepareIntlayer` para compilar todos os arquivos `.content.ts` em dicionários JSON otimizados armazenados em `.intlayer/`.
+
+### 2. Aliases de módulo
+
+O plugin adiciona aliases de resolução do Vite para que `import { myDict } from 'intlayer/dictionaries/my-dict'` seja resolvido para o arquivo JSON compilado no disco. Os builds SSR usam `ssr.noExternal` para garantir que todos os pacotes `@intlayer/*` sejam agrupados com aliases aplicados.
+
+### 3. Dev-server watcher
+
+Em modo de desenvolvimento, um watcher `chokidar` é iniciado. Quando um arquivo `.content.ts` é alterado, os dicionários são recompilados e o HMR do Vite propaga a atualização para o navegador.
+
+### 4. Proxy de roteamento de locale agrupado (v9+)
+
+Desde o Intlayer v9, o middleware `intlayerProxy` é registrado automaticamente dentro de `intlayer()`. Ele trata:
+
+- Detecção de locale a partir do prefixo da URL, cookies e cabeçalho `Accept-Language`.
+- Redirecionamentos 301 quando o locale detectado não corresponde à URL atual.
+- Reescritas de URL internas para que o framework veja o parâmetro de rota `[locale]` correto.
+
+O proxy é controlado por `routing.enableProxy` (padrão `true`) na sua configuração do Intlayer. Para desabilitá-lo completamente:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  routing: { enableProxy: false },
+});
+```
+
+Para personalizar o comportamento do proxy sem uma chamada `intlayerProxy()` separada, passe opções `proxy` para o plugin principal:
+
+```ts
+intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });
+```
+
+Veja a [documentação do intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/vite-intlayer/intlayerProxy.md) para a referência completa do comportamento de roteamento.
+
+### 5. Compilador agrupado (v9+)
+
+Quando `compiler.enabled` é `true` **e** `compiler.output` está definido na sua configuração Intlayer, `intlayer()` registra `intlayerCompiler` automaticamente. O compilador extrai declarações de conteúdo inline escritas diretamente dentro de arquivos de componente e as escreve em dicionários no tempo de transformação. Consulte a [documentação do intlayerCompiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/vite-intlayer/intlayerCompiler.md).
+
+### 6. Otimizações de build
+
+Durante um build de produção, o plugin adiciona:
+
+- **intlayerOptimize** – Babel transform que reescreve `useIntlayer('key')` → `useDictionary(hash)` e injeta importações JSON diretas.
+- **intlayerPrune** – remove campos de conteúdo não utilizados do dictionary JSON.
+- **intlayerMinify** – compacta dictionary JSON e opcionalmente faz mangling de nomes de campos.
+
+Estes estão inativos em modo de desenvolvimento.
+
+## Aliases Descontinuadas
 
-1. **Preparar dicionários**: Compila os dicionários em arquivos otimizados no início do processo de build ou de desenvolvimento.
-2. **Modo de observação (watch)**: Em modo de desenvolvimento, observa mudanças nos arquivos de dicionário e os recompila automaticamente.
-3. **Aliases**: Fornece aliases para aceder aos dicionários na sua aplicação.
-4. **Tree-shaking**: Suporta tree-shaking de traduções não utilizadas através do plugin `intlayerPrune`.
+| Exportação Descontinuada | Substituição |
+| ------------------------ | ------------ |
+| `intlayerPlugin`         | `intlayer`   |
+| `intLayerPlugin`         | `intlayer`   |

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

@@ -28,19 +28,91 @@ author: aymericzip
 
 O plugin Vite `intlayerPrune` é usado para realizar tree-shaking e podar dicionários não utilizados do bundle da sua aplicação. Isso ajuda a reduzir o tamanho final do bundle incluindo apenas o conteúdo multilíngue necessário.
 
-## Uso
+## Utilização
+
+### Como parte de `intlayer()` (recomendado)
+
+Ative a poda através da sua configuração Intlayer e o plugin principal trata de tudo:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // ativa poda e minificação
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Standalone
+
+Se você está compondo a pilha de plugins manualmente, `intlayerPrune` e `intlayerMinify` compartilham um objeto `PruneContext` que deve ser criado uma vez e passado para ambos:
 
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
-ts;
-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), // opcional, lê do mesmo contexto
+  ],
 });
 ```
 
-## Descrição
+## Como funciona
+
+### 1. Análise de uso (buildStart)
+
+Durante `buildStart`, o plugin `intlayerOptimize` (também parte de `intlayer()`) verifica cada arquivo de código-fonte de componente listado em `build.filesList`. Para cada chamada `useIntlayer('key')` ou `getIntlayer('key')`, ele registra exatamente quais campos são acessados, por exemplo:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// registra: myDict → { title, description }
+```
+
+Isso constrói `pruneContext.fieldUsageMap` antes de qualquer chamada `transform` ser executada.
+
+### 2. JSON pruning (transform, enforce: 'pre')
+
+When Vite processes a compiled dictionary JSON file, `intlayerPrune` intercepts it before Vite's built-in JSON → ESM conversion. It reads the field-usage map from `pruneContext` and removes any content field that is not in the recorded usage set.
+
+Two content shapes are supported:
+
+- **Static dictionaries** — `{ nodeType: "translation", translation: { en: {...}, fr: {...} } }`. Fields are pruned per-locale inside `translation`.
+- **Dynamic (per-locale) dictionaries** — flat `{ fieldA: ..., fieldB: ... }`. Fields are pruned at the top level.
+
+### 3. Casos extremos
+
+Se a estrutura de conteúdo de um dicionário não puder ser reconhecida (por exemplo, uma forma aninhada incomum), ele será adicionado a `pruneContext.dictionariesWithEdgeCases` e **deixado intocado**. Um aviso é registrado. `intlayerMinify` também ignora esses dicionários.
+
+### 4. Mapa de renomeação de campos
+
+Quando a limpeza tem sucesso, `intlayerPrune` também escreve `pruneContext.dictionaryKeyToFieldRenameMap` — um mapeamento de nomes de campos originais para aliases curtos. `intlayerMinify` lê este mapa para renomear campos no JSON de saída, e a passagem de renomeação Babel de `intlayerOptimize` atualiza os acessos de propriedades nos arquivos fonte de acordo.
+
+## Condições de ativação
+
+`intlayerPrune` está ativo **apenas** quando todas as seguintes condições são verdadeiras:
+
+1. O comando Vite é `build`.
+2. `build.optimize` é `true` (ou `undefined`, que assume como padrão `true` para builds).
+3. `build.purge` é `true` na sua configuração do Intlayer.
 
-O plugin analisa o seu código-fonte para identificar quais chaves de dicionário são realmente utilizadas. Em seguida, remove qualquer conteúdo não utilizado dos arquivos de dicionário empacotados. Isto é particularmente útil em projetos grandes com muitos dicionários, onde apenas um subconjunto é usado em páginas ou componentes específicos.
+É automaticamente **desativado** quando `editor.enabled` é `true` porque o editor precisa do conteúdo completo do dicionário.

package/docs/pt/releases/v9.md

@@ -374,21 +374,6 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 O instalador baixa um `docker-compose.yml` e um `.env`, gera automaticamente os secrets necessários e executa `docker compose up -d`. Tudo — o dashboard, a API, o banco de dados, o armazenamento de objetos e o e-mail transacional — roda localmente em contêineres.
 
-### Serviços incluídos
-
-| Serviço                                 | Finalidade                                                                      |
-| --------------------------------------- | ------------------------------------------------------------------------------- |
-| **app** (TanStack Start)                | Interface do dashboard na porta `3000`                                          |
-| **backend** (Fastify/Bun)               | API REST na porta `3100`                                                        |
-| **MongoDB 7** (single-node replica set) | Banco de dados principal                                                        |
-| **Redis 7**                             | Filas de tarefas e cache                                                        |
-| **MinIO**                               | Armazenamento de objetos compatível com S3 (avatares, capturas de tela)         |
-| **Mailpit**                             | Sumidouro SMTP local + interface web para e-mails transacionais na porta `8025` |
-
-O Chromium (usado para geração de capturas de tela com Puppeteer) está incluído na imagem do backend — nenhum contêiner adicional é necessário.
-
----
-
 ## Notas de migração da v8
 
 Se você estiver atualizando da v8, observe que a v9 não inclui breaking changes. Mas aqui estão as principais mudanças:

package/docs/pt/self_hosting.md

@@ -62,6 +62,32 @@ O Chromium (usado para a geração de screenshots do Puppeteer) é empacotado de
 
 ---
 
+## Início Rápido
+
+Puxe e execute a imagem publicada, fornecendo suas credenciais e secrets do 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
+```
+
+Em seguida, abra **http://localhost:3000**.
+
+> O dashboard é servido em `localhost`. Veja [Limitações](#limitations) — domínios personalizados não são suportados pela imagem publicada.
+
+---
+
 ## Início rápido
 
 ```sh
@@ -99,7 +125,16 @@ As portas internas (mongo, redis) não são expostas ao host por padrão.
 
 ## Variáveis de ambiente
 
-O instalador gera um arquivo `.env` pronto para uso. A tabela abaixo descreve cada variável.
+### Obrigatório
+
+| Variável               | Exemplo                      | Descrição                                                                                                                                                     |
+| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | Usuário MongoDB Atlas                                                                                                                                         |
+| `DB_MDP`               | _(sua senha)_                | Senha MongoDB Atlas                                                                                                                                           |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | Host do cluster MongoDB Atlas (usado na URI `mongodb+srv://`)                                                                                                 |
+| `BETTER_AUTH_SECRET`   | _(gerado)_                   | Secret de 32 bytes para assinatura de sessão                                                                                                                  |
+| `S3_SECRET_ACCESS_KEY` | _(gerado)_                   | Secret para o MinIO incluído                                                                                                                                  |
+| `RESEND_API_KEY`       | _(sua chave)_                | Email transacional via Resend. Obrigatório para configuração inicial, a menos que você configure um mailer SMTP global (veja [Global mailer](#global-mailer)) |
 
 ### Obrigatórias (auto-geradas ou solicitadas)
 
@@ -141,6 +176,26 @@ O instalador gera um arquivo `.env` pronto para uso. A tabela abaixo descreve ca
 
 ---
 
+### Global mailer
+
+Por padrão, todos os emails transacionais são enviados através do Resend usando `RESEND_API_KEY`. Implantações auto-hospedadas podem, em vez disso, rotear **todos** os emails — incluindo emails não-organizacionais, como redefinições de senha e magic links — através de um mailer global configurado com variáveis de ambiente.
+
+Configure `MAIL_PROVIDER` para ativá-lo. Quando não configurado, o mailer padrão do Resend é usado.
+
+| Variable             | Example                        | Description                                                                   |
+| -------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
+| `MAIL_PROVIDER`      | `smtp`                         | Global transport: `smtp` ou `resend`. Deixe não configurado para usar padrões |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Sender header. Aceita um endereço simples ou formato `Name <email>`           |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP host (obrigatório quando `MAIL_PROVIDER=smtp`)                           |
+| `MAIL_SMTP_PORT`     | `587`                          | SMTP port (padrão é `587`)                                                    |
+| `MAIL_SMTP_SECURE`   | `false`                        | Implicit TLS. Configure `true` para a porta `465`                             |
+| `MAIL_SMTP_USER`     | _(seu usuário)_                | SMTP username (opcional; omita para relays não autenticados)                  |
+| `MAIL_SMTP_PASSWORD` | _(sua senha)_                  | SMTP password                                                                 |
+
+> Precedência: o próprio mailer de uma organização (configurado a partir do dashboard **Organization**) tem prioridade sobre o mailer global, que por sua vez tem prioridade sobre a chave padrão do Resend.
+
+---
+
 ## Conectando seu projeto Intlayer
 
 Uma vez que a stack esteja em execução, aponte seu projeto para o backend e dashboard auto-hospedados em vez de `intlayer.org`.
@@ -259,47 +314,11 @@ docker run --rm \
 
 ---
 
-## Usando um proxy reverso (Nginx / Caddy)
+## Limitações
 
-Para implantações em produção, coloque um proxy reverso na frente dos containers do aplicativo e do backend, em vez de expô-los diretamente.
-
-### Exemplo de 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;
-    }
-}
-```
-
-Atualize as seguintes variáveis `.env` para corresponder aos seus domínios públicos:
-
-```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
-```
-
-> As variáveis `VITE_*` são incorporadas à imagem do dashboard no momento da compilação. Se você as alterar após a imagem ser construída, precisará reconstruir a imagem do `app` (`docker compose build app`) ou usar a injeção de configuração em tempo de execução.
+- **MongoDB deve ser externo (Atlas).** O backend conecta apenas via `mongodb+srv://` (construído a partir de `DB_ID` / `DB_MDP` / `DB_CLUSTER`), então um simples `mongodb://host:27017` — incluindo o `mongod` incluído no container — não pode ser usado. Forneça um cluster MongoDB Atlas.
+- **Sem domínio personalizado.** Todas as URLs `VITE_*` voltadas para o navegador são inseridas no app em tempo de construção, e a imagem publicada é enviada com valores `localhost`. O dashboard deve ser acessado em `http://localhost:3000`; servir em um domínio público exigiria reconstruir a imagem com as URLs de destino incorporadas e não é suportado por padrão.
+- **Email requer um mailer funcionando.** A configuração da primeira execução impõe verificação de email, portanto, `RESEND_API_KEY` ou um [mailer SMTP global](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) deve ser configurado. Após o primeiro admin se conectar, cada organização também pode configurar seu próprio mailer SMTP ou Resend no dashboard.
 
 ---
 
@@ -324,14 +343,6 @@ docker compose build app
 docker compose up -d app
 ```
 
-### E-mail não está sendo enviado
-
-Por padrão, todos os e-mails de saída são capturados pelo Mailpit. Abra `http://localhost:8025` para ver as mensagens enviadas. Para enviar e-mails reais, defina `MAIL_PROVIDER=resend` e `RESEND_API_KEY=<sua-chave>` no `.env`, então reinicie o backend:
-
-```sh
-docker compose restart backend
-```
-
 ### Bucket MinIO ausente
 
 Se o serviço `minio-init` de execução única não foi executado (ou executou antes que o MinIO estivesse pronto), crie o bucket manualmente: