@intlayer/docs 9.1.3 → 9.2.0

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

@@ -59,36 +59,44 @@ getLocalizedUrl(
 
 ## Parámetros
 
-## Descripción
-
-La función `getLocalizedUrl` genera una URL localizada anteponiendo la URL dada con el locale especificado. Maneja tanto URLs absolutas como relativas, asegurando que se aplique el prefijo de locale correcto según la configuración.
-
----
-
-## Parámetros
+### Parámetros Requeridos
 
 - `url: string`
-  - **Descripción**: La cadena de URL original a la que se le antepondrá un locale.
+  - **Descripción**: La cadena de URL original a la que se le añadirá un prefijo de locale.
   - **Tipo**: `string`
+  - **Requerido**: Sí
 
 - `currentLocale: Locales`
   - **Descripción**: El locale actual para el cual se está localizando la URL.
   - **Tipo**: `Locales`
-
-- `locales: Locales[]`
-  - **Descripción**: Array opcional de locales soportados. Por defecto, se proporcionan los locales configurados en el proyecto.
-  - **Tipo**: `Locales[]`
-  - **Por defecto**: [`Configuración del Proyecto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md#middleware)
-
-- `defaultLocale: Locales`
-  - **Descripción**: El locale por defecto para la aplicación. Por defecto, se proporciona el locale por defecto configurado en el proyecto.
-  - **Tipo**: `Locales`
-  - **Por defecto**: [`Configuración del Proyecto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md#middleware)
-
-- `prefixDefault: boolean`
-  - **Descripción**: Indica si se debe anteponer el prefijo para el locale por defecto. Por defecto, se proporciona el valor configurado en el proyecto.
-  - **Tipo**: `boolean`
-  - **Por defecto**: [`Configuración del Proyecto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md#middleware)
+  - **Requerido**: Sí
+
+### Parámetros Opcionales
+
+- `options?: object`
+  - **Description**: Objeto de configuración para el comportamiento de localización de URL.
+  - **Type**: `object`
+  - **Required**: No (Opcional)
+
+  - `options.locales?: Locales[]`
+    - **Description**: Array de locales soportadas. Si no se proporciona, utiliza las locales configuradas en la configuración de tu proyecto.
+    - **Type**: `Locales[]`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md#middleware)
+
+  - `options.defaultLocale?: Locales`
+    - **Description**: La locale predeterminada para la aplicación. Si no se proporciona, utiliza la locale predeterminada configurada en la configuración de tu proyecto.
+    - **Type**: `Locales`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Description**: El modo de enrutamiento de URL para el manejo de locales. Si no se proporciona, utiliza el modo configurado en la configuración de tu proyecto.
+    - **Type**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md#middleware)
+    - **Modes**:
+      - `prefix-no-default`: Sin prefijo para la locale predeterminada, prefijo para todas las demás
+      - `prefix-all`: Prefijo para todas las locales incluyendo la predeterminada
+      - `no-prefix`: Sin prefijo de locale en la URL
+      - `search-params`: Usar parámetros de consulta para la locale (p. ej., `?locale=fr`)
 
 ### Retorna
 

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

@@ -50,26 +50,12 @@ getMultilingualUrls(
 
 ## Parámetros
 
-## Parámetros
+### Parámetros Requeridos
 
 - `url: string`
-  - **Descripción**: La cadena URL original a la que se le antepondrán los prefijos de localización.
-  - **Tipo**: `string`
-
-- `locales: Locales[]`
-  - **Descripción**: Arreglo opcional de locales soportados. Por defecto, usa los locales configurados en el proyecto.
-  - **Tipo**: `Locales[]`
-  - **Por defecto**: `localesDefault`
-
-- `defaultLocale: Locales`
-  - **Descripción**: El local predeterminado para la aplicación. Por defecto, usa el local predeterminado configurado en el proyecto.
-  - **Tipo**: `Locales`
-  - **Por defecto**: `defaultLocaleDefault`
-
-- `prefixDefault: boolean`
-  - **Descripción**: Indica si se debe anteponer el prefijo para el local predeterminado. Por defecto, usa el valor configurado en el proyecto.
-  - **Tipo**: `boolean`
-  - **Por defecto**: `prefixDefaultDefault`
+  - **Description**: La cadena URL original que se prefijará con locales.
+  - **Type**: `string`
+  - **Required**: Yes
 
 ### Parámetros Opcionales
 

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

@@ -48,3 +48,18 @@ import "vite-intlayer";
 | `intlayerProxy`      | Plugin middleware de desarrollo para gestionar la detección de locale y el enrutamiento.     | -                                                                                                                      |
 | `intlayerMiddleware` | (**Deprecado**) Alias de `intlayerProxy`.                                                    | -                                                                                                                      |
 | `intlayerPrune`      | Plugin para realizar tree-shaking y podar diccionarios no utilizados durante la compilación. | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/vite-intlayer/intlayerPrune.md) |
+
+### Utilities
+
+| Export                       | Description                                                                                   | Related Doc                                                                                                            |
+| ---------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `createIntlayerProxyHandler` | Returns a framework-agnostic Node.js `(req, res, next)` middleware with locale-routing logic. | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/vite-intlayer/intlayerProxy.md) |
+
+### Tipos
+
+| Export                       | Descripción                                                                                                       |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `IntlayerPluginOptions`      | Opciones aceptadas por `intlayer()`. Extiende `GetConfigurationOptions` con `compatCallers` y `proxy`.            |
+| `IntlayerProxyPluginOptions` | Opciones aceptadas por `intlayerProxy()` y `createIntlayerProxyHandler()`. Incluye `ignore` y `configOptions`.    |
+| `IntlayerCompilerOptions`    | Opciones aceptadas por `intlayerCompiler()`. Incluye `configOptions` y `compilerConfig`.                          |
+| `CompatCallerConfig`         | Re-export desde `@intlayer/babel`. Describe un patrón de caller de compat-adapter para análisis de uso de campos. |

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

@@ -39,11 +39,126 @@ export default defineConfig({
 });
 ```
 
-## Descripción
+## Opciones
 
-El plugin realiza las siguientes tareas:
+```ts
+import type { IntlayerPluginOptions } from "vite-intlayer";
+```
+
+`IntlayerPluginOptions` extends `GetConfigurationOptions` (see `@intlayer/config`) with the following additional fields:
+
+| Option          | Type                            | Default     | Description                                                                                                                           |
+| --------------- | ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `compatCallers` | `CompatCallerConfig[]`          | `[]`        | Extra caller patterns for compat-adapter packages (e.g. `@intlayer/react-i18next`). Passed to the field-usage analyser at build time. |
+| `proxy`         | `{ ignore?: (req) => boolean }` | `undefined` | Options forwarded to the bundled locale-routing proxy. Use `ignore` to exclude specific paths (e.g. API routes) from locale routing.  |
+
+All other options (`override`, `configFile`, …) are forwarded directly to `getConfiguration()`.
+
+### Ejemplos
+
+#### Ignorar rutas de API del enrutamiento 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"),
+      },
+    }),
+  ],
+});
+```
+
+#### Con una ruta de archivo de configuración personalizada
+
+```ts
+export default defineConfig({
+  plugins: [
+    intlayer({
+      configFile: "./config/intlayer.config.ts",
+    }),
+  ],
+});
+```
+
+#### Con llamadas de compat-adapter
+
+```ts
+import { intlayer } from "vite-intlayer";
+import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      compatCallers: [reactI18nextCallerConfig],
+    }),
+  ],
+});
+```
+
+## Qué hace el plugin
+
+### 1. Preparación del diccionario
+
+Antes de que comience la compilación (y una vez por hora en desarrollo), `intlayer` llama a `prepareIntlayer` para compilar todos los archivos `.content.ts` en diccionarios JSON optimizados almacenados en `.intlayer/`.
+
+### 2. Alias de módulos
+
+El plugin añade alias de resolución de Vite para que `import { myDict } from 'intlayer/dictionaries/my-dict'` se resuelva al archivo JSON compilado en disco. Las compilaciones SSR utilizan `ssr.noExternal` para asegurar que todos los paquetes `@intlayer/*` se agrupan con los alias aplicados.
+
+### 3. Dev-server watcher
+
+En modo de desarrollo se inicia un watcher de `chokidar`. Cuando un archivo `.content.ts` cambia, los diccionarios se recompilan y HMR de Vite propaga la actualización al navegador.
+
+### 4. Proxy de enrutamiento de locale agrupado (v9+)
+
+Desde Intlayer v9, el middleware `intlayerProxy` se registra automáticamente dentro de `intlayer()`. Maneja:
+
+- Detección de locale desde el prefijo de URL, cookies y encabezado `Accept-Language`.
+- Redirecciones 301 cuando la locale detectada no coincide con la URL actual.
+- Reescrituras de URL internas para que el framework vea el parámetro de ruta `[locale]` correcto.
+
+El proxy se controla mediante `routing.enableProxy` (por defecto `true`) en tu configuración de Intlayer. Para deshabilitarlo completamente:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  routing: { enableProxy: false },
+});
+```
+
+Para personalizar el comportamiento del proxy sin una llamada `intlayerProxy()` separada, pasa opciones de `proxy` al plugin principal:
+
+```ts
+intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });
+```
+
+Consulta la [documentación de intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/vite-intlayer/intlayerProxy.md) para la referencia completa del comportamiento de enrutamiento.
+
+### 5. Compilador empaquetado (v9+)
+
+Cuando `compiler.enabled` es `true` **y** `compiler.output` está configurado en tu configuración de Intlayer, `intlayer()` registra `intlayerCompiler` automáticamente. El compilador extrae declaraciones de contenido inline escritas directamente dentro de archivos de componentes y las escribe en diccionarios en tiempo de transformación. Consulta la [documentación de intlayerCompiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/vite-intlayer/intlayerCompiler.md).
+
+### 6. Optimizaciones de compilación
+
+Durante una compilación de producción el plugin añade:
+
+- **intlayerOptimize** – Transformación de Babel que reescribe `useIntlayer('key')` → `useDictionary(hash)` e inyecta importaciones directas de JSON.
+- **intlayerPrune** – elimina campos de contenido no utilizados del JSON del diccionario.
+- **intlayerMinify** – compacta el JSON del diccionario y opcionalmente ofusca nombres de campos.
+
+Estas están inactivas en modo de desarrollo.
+
+## Alias obsoletos
 
-1. **Preparar diccionarios**: Compila los diccionarios en archivos optimizados al inicio del proceso de build o dev.
-2. **Modo de vigilancia**: En modo de desarrollo, vigila los cambios en los archivos de diccionario y los recompila automáticamente.
-3. **Alias**: Proporciona alias para acceder a los diccionarios en tu aplicación.
-4. **Tree-shaking**: Soporta el tree-shaking de traducciones no usadas a través del plugin `intlayerPrune`.
+| Exportación obsoleta | Reemplazo  |
+| -------------------- | ---------- |
+| `intlayerPlugin`     | `intlayer` |
+| `intLayerPlugin`     | `intlayer` |

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

@@ -30,16 +30,83 @@ El plugin `intlayerPrune` para Vite se utiliza para aplicar tree-shaking y elimi
 
 ## Uso
 
+### Como parte de `intlayer()` (recomendado)
+
+Habilita la poda a través de tu configuración de Intlayer y el plugin principal se encarga de todo:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // habilita tanto poda como minificación
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Independiente
+
+Si está componiendo manualmente la pila de plugins, `intlayerPrune` e `intlayerMinify` comparten un objeto `PruneContext` que debe crearse una vez y pasarse a ambos:
+
 ```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), // opcional, lee del mismo contexto
+  ],
 });
 ```
 
+## Cómo funciona
+
+### 1. Análisis de uso (buildStart)
+
+Durante `buildStart`, el plugin `intlayerOptimize` (también parte de `intlayer()`) escanea cada archivo de componente fuente listado en `build.filesList`. Para cada llamada `useIntlayer('key')` o `getIntlayer('key')`, registra exactamente qué campos se acceden, por ejemplo:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// registra: myDict → { title, description }
+```
+
+Esto construye `pruneContext.fieldUsageMap` antes de que se ejecuten las llamadas `transform`.
+
+### 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 especiales
+
+Si la estructura de contenido de un diccionario no puede ser reconocida (por ejemplo, una forma anidada inusual), se añade a `pruneContext.dictionariesWithEdgeCases` y se **deja sin modificar**. Se registra una advertencia. `intlayerMinify` también omite estos diccionarios.
+
+### 4. Mapa de renombrado de campos
+
+Cuando la poda tiene éxito, `intlayerPrune` también escribe `pruneContext.dictionaryKeyToFieldRenameMap` — un mapeo de nombres de campos originales a alias cortos. `intlayerMinify` lee este mapa para renombrar campos en el JSON de salida, y el paso de renombrado de Babel de `intlayerOptimize` actualiza los accesos a propiedades en los archivos de origen en consecuencia.
+
 ## Descripción
 
 El plugin analiza tu código fuente para identificar qué claves de diccionario se usan realmente. A continuación elimina cualquier contenido no utilizado de los archivos de diccionario empaquetados. Esto es especialmente útil en proyectos grandes con muchos diccionarios donde solo se utiliza un subconjunto en páginas o componentes específicos.

package/docs/es/releases/v9.md

@@ -370,21 +370,6 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 El instalador descarga un `docker-compose.yml` y un `.env`, genera automáticamente los secretos necesarios y ejecuta `docker compose up -d`. Todo — el panel de control, la API, la base de datos, el almacenamiento de objetos y el correo electrónico transaccional — se ejecuta localmente en contenedores.
 
-### Servicios incluidos
-
-| Servicio                                | Propósito                                                                        |
-| --------------------------------------- | -------------------------------------------------------------------------------- |
-| **app** (TanStack Start)                | Interfaz del panel de control en el puerto `3000`                                |
-| **backend** (Fastify/Bun)               | API REST en el puerto `3100`                                                     |
-| **MongoDB 7** (single-node replica set) | Base de datos principal                                                          |
-| **Redis 7**                             | Colas de trabajos y caché                                                        |
-| **MinIO**                               | Almacenamiento de objetos compatible con S3 (avatares, capturas de pantalla)     |
-| **Mailpit**                             | Sumidero SMTP local + interfaz web para correo transaccional en el puerto `8025` |
-
-Chromium (usado para la generación de capturas de pantalla con Puppeteer) está incluido dentro de la imagen del backend — no se necesita ningún contenedor adicional.
-
----
-
 ## Notas de migración desde v8
 
 Si estás actualizando desde v8, ten en cuenta que la v9 no incluye cambios disruptivos. Pero aquí están los cambios clave:

package/docs/es/self_hosting.md

@@ -80,6 +80,18 @@ Una vez que la pila esté en funcionamiento, abre **http://localhost:3000** y cr
 
 ---
 
+## Configuración inicial
+
+En una instancia nueva (base de datos vacía), abrir el dashboard te redirige a la página **`/init`**:
+
+1. Crea la primera cuenta. Como la colección de usuarios está vacía, esta cuenta se promociona automáticamente a **super admin**.
+2. Se envía un email de verificación (vía Resend). La verificación de email es **obligatoria** — por eso `RESEND_API_KEY` debe estar configurado antes de empezar.
+3. Haz clic en el enlace del email e inicia sesión.
+
+Una vez que existe un admin, `/init` redirige a la página estándar de inicio de sesión.
+
+---
+
 ## Servicios
 
 | Servicio    | Imagen                                     | Puerto(s) del host                   | Propósito                                                                        |
@@ -99,7 +111,16 @@ Los puertos internos (mongo, redis) no se exponen al host por defecto.
 
 ## Variables de entorno
 
-El instalador genera un archivo `.env` listo para usar. La siguiente tabla describe cada variable.
+### Requerido
+
+| Variable               | Ejemplo                      | Descripción                                                                                                                                                        |
+| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `DB_ID`                | `intlayer`                   | Usuario de MongoDB Atlas                                                                                                                                           |
+| `DB_MDP`               | _(tu contraseña)_            | Contraseña de MongoDB Atlas                                                                                                                                        |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | Host del cluster de MongoDB Atlas (utilizado en el URI `mongodb+srv://`)                                                                                           |
+| `BETTER_AUTH_SECRET`   | _(generado)_                 | Secret de 32 bytes para la firma de sesiones                                                                                                                       |
+| `S3_SECRET_ACCESS_KEY` | _(generado)_                 | Secret para el MinIO incluido                                                                                                                                      |
+| `RESEND_API_KEY`       | _(tu clave)_                 | Email transaccional a través de Resend. Requerido para la configuración inicial a menos que configures un mailer SMTP global (ver [Global mailer](#global-mailer)) |
 
 ### Requeridas (autogeneradas o solicitadas)
 
@@ -141,6 +162,26 @@ El instalador genera un archivo `.env` listo para usar. La siguiente tabla descr
 
 ---
 
+### Servicio de correo global
+
+De forma predeterminada, todos los correos electrónicos transaccionales se envían a través de Resend utilizando `RESEND_API_KEY`. Los despliegues auto-hospedados pueden enrutar **todos** los correos electrónicos — incluyendo correos no organizacionales como restablecimiento de contraseña y enlaces mágicos — a través de un servicio de correo global configurado con variables de entorno.
+
+Establece `MAIL_PROVIDER` para activarlo. Cuando no está configurado, se utiliza el servicio de correo Resend predeterminado.
+
+| Variable             | Ejemplo                        | Descripción                                                                                       |
+| -------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `MAIL_PROVIDER`      | `smtp`                         | Transporte global: `smtp` o `resend`. Déjalo sin configurar para usar los valores predeterminados |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Encabezado del remitente. Acepta una dirección simple o formato `Name <email>`                    |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | Host SMTP (requerido cuando `MAIL_PROVIDER=smtp`)                                                 |
+| `MAIL_SMTP_PORT`     | `587`                          | Puerto SMTP (por defecto `587`)                                                                   |
+| `MAIL_SMTP_SECURE`   | `false`                        | TLS implícito. Establece `true` para el puerto `465`                                              |
+| `MAIL_SMTP_USER`     | _(tu usuario)_                 | Usuario SMTP (opcional; omitir para relés sin autenticar)                                         |
+| `MAIL_SMTP_PASSWORD` | _(tu contraseña)_              | Contraseña SMTP                                                                                   |
+
+> Precedencia: el servicio de correo propio de una organización (configurado desde el panel de control de **Organization**) tiene prioridad sobre el servicio de correo global, que a su vez tiene prioridad sobre la clave Resend predeterminada.
+
+---
+
 ## Conectando tu proyecto Intlayer
 
 Una vez que la pila esté en funcionamiento, apunta tu proyecto al backend y dashboard autoalojados en lugar de `intlayer.org`.
@@ -259,47 +300,11 @@ docker run --rm \
 
 ---
 
-## Uso de un proxy inverso (Nginx / Caddy)
-
-Para despliegues de producción, coloca un proxy inverso delante de los contenedores de la aplicación y del backend en lugar de exponerlos directamente.
+## Limitaciones
 
-### Ejemplo 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;
-    }
-}
-```
-
-Actualiza las siguientes variables `.env` para que coincidan con tus dominios 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
-```
-
-> Las variables `VITE_*` se integran en la imagen del dashboard en el momento de la construcción. Si las cambias después de que se construya la imagen, necesitas reconstruir la imagen de la `app` (`docker compose build app`) o usar la inyección de configuración en tiempo de ejecución.
+- **MongoDB debe ser externo (Atlas).** El backend se conecta solo a través de `mongodb+srv://` (construido desde `DB_ID` / `DB_MDP` / `DB_CLUSTER`), por lo que un simple `mongodb://host:27017` — incluyendo el `mongod` incluido en el contenedor — no se puede usar. Proporciona un cluster de MongoDB Atlas.
+- **Sin dominio personalizado.** Todas las URLs `VITE_*` que enfrenta el navegador se insertan en línea en la aplicación en tiempo de compilación, y la imagen publicada se envía con valores de `localhost`. El dashboard debe accederse en `http://localhost:3000`; servirlo en un dominio público requeriría reconstruir la imagen con las URLs de destino incorporadas y no es compatible de forma predeterminada.
+- **El correo electrónico requiere un mailer que funcione.** La configuración de primera ejecución obliga a la verificación de correo electrónico, por lo que se debe configurar `RESEND_API_KEY` o un [mailer SMTP global](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`). Después de que el primer administrador inicie sesión, cada organización también puede configurar su propio mailer SMTP o Resend desde el dashboard.
 
 ---
 
@@ -324,14 +329,6 @@ docker compose build app
 docker compose up -d app
 ```
 
-### El correo electrónico no se envía
-
-Por defecto, todos los correos electrónicos salientes son capturados por Mailpit. Abre `http://localhost:8025` para ver los mensajes enviados. Para enviar correos electrónicos reales, establece `MAIL_PROVIDER=resend` y `RESEND_API_KEY=<tu-clave>` en `.env`, luego reinicia el backend:
-
-```sh
-docker compose restart backend
-```
-
 ### Falta el bucket de MinIO
 
 Si el servicio de un solo uso `minio-init` no se ejecutó (o se ejecutó antes de que MinIO estuviera listo), crea el bucket manualmente: