diff --git a/README.es.md b/README.es.md
new file mode 100644
index 0000000..c0815b0
--- /dev/null
+++ b/README.es.md
@@ -0,0 +1,360 @@
+# Constructa Starter
+
+
+
+
+
Kit de Inicio SAAS con IA
+
Optimizado para codificar con asistentes de IA • Impulsado por instructa.ai
+
--wipeVolume para también eliminar el volumen de datos) | `--wipeVolume` |
+| `testdata` | Crear o eliminar datos de prueba en la base de datos | `--create`, `--delete` |
+| `deploy` | Desplegar vía `git push dokku main` (ver docs/es/constructa/hosting.md) | Ejecutar según sea necesario |
+
+## 🔧 Configuración
+
+### Variables de Entorno
+
+Crea un archivo `.env` en el directorio raíz basado en `.env.example`:
+
+```bash
+# Base de Datos
+DATABASE_URL="postgresql://username:password@localhost:5432/constructa"
+
+# URL Base del Cliente (opcional - por defecto usa el origen actual en producción)
+VITE_BASE_URL="http://localhost:3000"
+
+# Configuración de IA
+OPENAI_API_KEY="sk-..."
+
+# Configuración de Facturación / Polar
+POLAR_SERVER="sandbox"
+POLAR_ACCESS_TOKEN=""
+POLAR_WEBHOOK_SECRET=""
+POLAR_ORGANIZATION_ID=""
+POLAR_PRODUCT_PRO_MONTHLY="prod_..."
+POLAR_PRODUCT_BUSINESS_MONTHLY="prod_..."
+POLAR_PRODUCT_CREDITS_50="prod_..."
+POLAR_PRODUCT_CREDITS_100="prod_..."
+PUBLIC_URL="http://localhost:3000"
+CHECKOUT_SUCCESS_URL="http://localhost:3000/dashboard/billing/success"
+CHECKOUT_CANCEL_URL="http://localhost:3000/dashboard/billing"
+VITE_ENTERPRISE_DEMO_URL="https://calendly.com/your-team/demo"
+VITE_POLAR_PRODUCT_CREDITS_50="prod_..."
+VITE_POLAR_PRODUCT_CREDITS_100="prod_..."
+VITE_POLAR_PRODUCT_PRO_MONTHLY="prod_..."
+VITE_POLAR_PRODUCT_BUSINESS_MONTHLY="prod_..."
+
+# Better Auth
+BETTER_AUTH_SECRET="your-secret-key-here"
+BETTER_AUTH_URL="http://localhost:3000"
+
+# Verificación de Email (deshabilitada por defecto)
+# Control de verificación de email del lado del servidor
+ENABLE_EMAIL_VERIFICATION="false"
+# Control de verificación de email del lado del cliente (para decisiones de UI)
+VITE_ENABLE_EMAIL_VERIFICATION="false"
+
+# Configuración del Servicio de Email (Resend es el proveedor por defecto)
+EMAIL_FROM="noreply@yourdomain.com"
+RESEND_API_KEY="your-resend-api-key"
+
+# Proveedores OAuth (opcional)
+# Configuración OAuth del lado del servidor
+GITHUB_CLIENT_ID="your-github-client-id"
+GITHUB_CLIENT_SECRET="your-github-client-secret"
+GOOGLE_CLIENT_ID="your-google-client-id"
+GOOGLE_CLIENT_SECRET="your-google-client-secret"
+
+# Configuración OAuth del lado del cliente (para botones de UI)
+VITE_GITHUB_CLIENT_ID="your-github-client-id"
+VITE_GOOGLE_CLIENT_ID="your-google-client-id"
+```
+
+- `VITE_BASE_URL` es opcional - en producción, usará automáticamente el dominio actual
+- Para desarrollo local, por defecto es `http://localhost:3000`
+
+### Configuración del Servicio de Email
+
+La aplicación soporta **múltiples proveedores de email** para máxima flexibilidad. Puedes elegir entre registro en consola, Mailhog (para desarrollo local), SMTP o Resend según tus necesidades.
+
+#### Opciones de Proveedores de Email
+
+1. **Proveedor de Consola** (Por defecto para desarrollo)
+ - Registra emails en la consola
+ - Sin dependencias externas
+ - Perfecto para desarrollo inicial
+
+ ```bash
+ EMAIL_PROVIDER="console"
+ ```
+
+2. **Mailhog** (Recomendado para desarrollo local)
+ - Captura todos los emails localmente
+ - Interfaz web para ver emails en http://localhost:8025
+ - Ya incluido en Docker Compose
+
+ ```bash
+ EMAIL_PROVIDER="mailhog"
+ # No requiere configuración adicional
+ ```
+
+ Iniciar Mailhog con Docker:
+ ```bash
+ docker-compose up -d mailhog
+ ```
+
+3. **Proveedor SMTP** (Para producción o servidores de email personalizados)
+ ```bash
+ EMAIL_PROVIDER="smtp"
+ SMTP_HOST="smtp.gmail.com"
+ SMTP_PORT="587"
+ SMTP_SECURE="false"
+ SMTP_USER="your-email@gmail.com"
+ SMTP_PASS="your-app-password"
+ ```
+
+4. **Resend** (API de email moderna)
+ ```bash
+ EMAIL_PROVIDER="resend"
+ RESEND_API_KEY="re_xxxxxxxxxxxx"
+ ```
+
+ - Regístrate en [resend.com](https://resend.com)
+ - Crea una clave API en tu panel
+ - Agrega y verifica tu dominio (para producción)
+
+#### Configuración Común de Email
+
+```bash
+# Establecer la dirección "from" por defecto
+EMAIL_FROM="noreply@yourdomain.com"
+
+# Habilitar verificación de email (opcional)
+ENABLE_EMAIL_VERIFICATION="true"
+VITE_ENABLE_EMAIL_VERIFICATION="true"
+```
+
+#### Agregar Proveedores de Email Personalizados
+
+El sistema de email está diseñado para ser extensible. Para agregar un nuevo proveedor:
+
+1. **Crear una nueva clase de proveedor** en `src/server/email/providers.ts`:
+ ```typescript
+ export class MyCustomProvider implements EmailProvider {
+ async sendEmail({ from, to, subject, html }) {
+ // Tu implementación aquí
+ }
+ }
+ ```
+
+2. **Agregar el proveedor a la fábrica** en `src/server/email/index.ts`:
+ ```typescript
+ case "custom":
+ emailProvider = new MyCustomProvider();
+ break;
+ ```
+
+3. **Actualizar tus variables de entorno**:
+ ```bash
+ EMAIL_PROVIDER="custom"
+ # Agregar cualquier configuración personalizada necesaria
+ ```
+
+#### Comportamiento de la Verificación de Email
+
+**Cuando está deshabilitada** (por defecto):
+- Los usuarios inician sesión automáticamente después del registro
+- No se envía email de verificación
+- Los usuarios son redirigidos directamente al panel
+
+**Cuando está habilitada**:
+- Los usuarios deben verificar su email antes de iniciar sesión
+- Se envía un email de verificación tras el registro
+- Los usuarios son redirigidos a una página de "verifica tu email"
+- Los usuarios no pueden iniciar sesión hasta que su email sea verificado
+
+### Configuración de Proveedores OAuth
+
+La aplicación soporta autenticación OAuth con GitHub y Google. Aquí está cómo configurarlos:
+
+#### Configuración de OAuth de GitHub
+
+1. **Crear una App OAuth de GitHub:**
+ - Ir a [Configuración de Desarrollador de GitHub](https://github.com/settings/developers)
+ - Clic en "New OAuth App"
+ - Completar los detalles de la aplicación:
+ - **Nombre de la aplicación**: Nombre de tu app
+ - **URL de la página principal**: `http://localhost:3000` (para desarrollo)
+ - **URL de callback de autorización**: `http://localhost:3000/api/auth/callback/github`
+
+2. **Obtener tus credenciales:**
+ - Después de crear la app, copiar el **Client ID**
+ - Generar un nuevo **Client Secret**
+
+3. **Agregar a las variables de entorno:**
+ ```bash
+ # Configuración del lado del servidor
+ GITHUB_CLIENT_ID="your-github-client-id"
+ GITHUB_CLIENT_SECRET="your-github-client-secret"
+
+ # Configuración del lado del cliente (para botones de UI)
+ VITE_GITHUB_CLIENT_ID="your-github-client-id"
+ ```
+
+4. **Para despliegue en producción:**
+ - Actualizar la **URL de la página principal** a tu dominio de producción
+ - Actualizar la **URL de callback de autorización** a `https://yourdomain.com/api/auth/callback/github`
+
+#### Configuración de OAuth de Google
+
+1. **Crear una App OAuth de Google:**
+ - Ir a [Google Cloud Console](https://console.cloud.google.com/)
+ - Crear un nuevo proyecto o seleccionar uno existente
+ - Habilitar la API de Google+
+ - Ir a "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
+
+2. **Configurar la pantalla de consentimiento OAuth:**
+ - Completar la información requerida de la aplicación
+ - Agregar tu dominio a los dominios autorizados
+
+3. **Crear ID de Cliente OAuth 2.0:**
+ - Tipo de aplicación: **Aplicación web**
+ - **Orígenes JavaScript autorizados**: `http://localhost:3000` (para desarrollo)
+ - **URIs de redireccionamiento autorizados**: `http://localhost:3000/api/auth/callback/google`
+
+4. **Obtener tus credenciales:**
+ - Copiar el **Client ID** y **Client Secret**
+
+5. **Agregar a las variables de entorno:**
+ ```bash
+ # Configuración del lado del servidor
+ GOOGLE_CLIENT_ID="your-google-client-id"
+ GOOGLE_CLIENT_SECRET="your-google-client-secret"
+
+ # Configuración del lado del cliente (para botones de UI)
+ VITE_GOOGLE_CLIENT_ID="your-google-client-id"
+ ```
+
+6. **Para despliegue en producción:**
+ - Actualizar orígenes autorizados a tu dominio de producción
+ - Actualizar URI de redirección a `https://yourdomain.com/api/auth/callback/google`
+
+#### Probar la Integración OAuth
+
+Una vez configurado, los usuarios verán opciones de inicio de sesión con GitHub y Google en las páginas de autenticación. Los proveedores OAuth se habilitan condicionalmente basados en la presencia de sus respectivas variables de entorno.
+
+
+## 📄 Licencia
+
+Este proyecto está bajo la Licencia MIT - ver el archivo [LICENSE](LICENSE) para más detalles.
+
+## Contribuir
+
+¡Damos la bienvenida a contribuciones! Por favor ver [CONTRIBUTING.md](CONTRIBUTING.md) para más detalles.
+
+## Enlaces
+
+- X/Twitter: [@kregenrek](https://x.com/kregenrek)
+- Bluesky: [@kevinkern.dev](https://bsky.app/profile/kevinkern.dev)
+
+## Academia de IA y Cursos
+- Aprende Cursor AI: [Curso Definitivo de Cursor](https://www.instructa.ai/en/cursor-ai)
+- Aprende a construir software con IA: [instructa.ai](https://www.instructa.ai)
+
+## Ve mis otros proyectos:
+
+* [AI Prompts](https://github.com/instructa/ai-prompts/blob/main/README.md) - Prompts de IA curados para Cursor AI, Cline, Windsurf y Github Copilot
+* [codefetch](https://github.com/regenrek/codefetch) - Convierte código en Markdown para LLMs con un simple comando de terminal
+* [aidex](https://github.com/regenrek/aidex) - Herramienta CLI que proporciona información detallada sobre modelos de lenguaje de IA, ayudando a desarrolladores a elegir el modelo correcto para sus necesidades
diff --git a/README.md b/README.md
index f3859b6..7c6d610 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,8 @@
Optimized for coding with AI assistants • Powered by instructa.ai
+> 🌍 **Documentación disponible en español** - [README en Español](README.es.md) | [Documentación en Español](docs/es/)
+
> ⚠️ **Work in Progress** - This starter kit is currently under active development. Features and documentation may change frequently.
diff --git a/docs/es/constructa/hosting.md b/docs/es/constructa/hosting.md
new file mode 100644
index 0000000..3c99b23
--- /dev/null
+++ b/docs/es/constructa/hosting.md
@@ -0,0 +1,200 @@
+# Hospedaje en Hetzner con Dokku
+
+Esta guía te proporciona un despliegue **limpio y reproducible**:
+
+- **Terraform** provisiona un VPS Debian 13 con Docker y Dokku
+- **Compose (solo servidor)** ejecuta **Postgres, MinIO, Redis, Meilisearch, Worker**
+- **Dokku** ejecuta la **aplicación web**; alcanza los servicios vía `host.docker.internal`
+- **Let's Encrypt** manejado por Dokku
+
+---
+
+## 1) Provisionar el servidor
+
+```bash
+cd infra/hetzner
+export TF_VAR_hcloud_token=YOUR_HETZNER_TOKEN
+terraform init && terraform apply
+````
+
+Esto instala:
+
+* Docker Engine
+* Dokku v0.36.7
+* Usuario `deploy` sin root con tu clave SSH
+* Firewall UFW (SSH/HTTP/HTTPS)
+
+## 1.5) Bootstrap con Ansible (recomendado)
+
+La automatización vive en `infra/ansible/`. Sincroniza el bundle de compose, renderiza `/opt/constructa/.env`, inicia los servicios y configura Dokku para apuntar a ellos.
+
+```bash
+# instalar colecciones galaxy de Ansible localmente
+ansible-galaxy collection install -r infra/ansible/requirements.yml
+
+# copiar + editar secretos (mantenidos localmente)
+cp infra/ansible/group_vars/constructa/vars.example.yml infra/ansible/group_vars/constructa/vars.yml
+$EDITOR infra/ansible/group_vars/constructa/vars.yml
+
+# actualizar inventario con tu host/IP
+$EDITOR infra/ansible/inventory/hosts.ini
+
+# ejecutar después de que terraform apply se complete
+ansible-playbook -i infra/ansible/inventory/hosts.ini infra/ansible/site.yml
+```
+
+Lo que hace el playbook:
+
+* sincroniza `infra/deploy/` en `/opt/constructa`
+* escribe `/opt/constructa/.env` desde tu archivo de variables
+* inicia Postgres/MinIO/Redis/Meilisearch + worker vía compose
+* ejecuta aprovisionamiento de buckets + `pnpm run db:migrate`
+* asegura que la app Dokku existe y apunta a `host.docker.internal`
+* provisiona un archivo swap (`constructa_swap_file` / `constructa_swap_size`) para que las compilaciones Docker tengan suficiente memoria
+* instala el plugin **dokku-redirect** y agrega redirecciones 301 para cualquier `constructa_redirect_domains`
+* instala el plugin **dokku-letsencrypt**, establece `DOKKU_LETSENCRYPT_EMAIL`, habilita certificados y programa renovaciones cuando se proporciona `constructa_letsencrypt_email`
+* si estás usando Dokku-first, establece `HOST_BIND_ADDR=0.0.0.0` para que los
+ contenedores Dokku puedan alcanzar los servicios compose vía el gateway del host
+
+---
+
+## Dokku-first (recomendado, sin registro)
+
+Usa esto si no quieres un registro en absoluto.
+
+**Primera ejecución:**
+
+1. Ejecuta el playbook una vez (la BD principal/almacenamiento de objetos/búsqueda se inician; el worker compose permanece inactivo hasta que lo apuntes a una imagen real).
+2. **Despliega una vez** para que Dokku construya la imagen localmente:
+
+ ```bash
+ pnpm run ex0 -- deploy --env dev --ref
+ # o --env prod
+ ```
+
+ Dokku produce `dokku/constructa:latest`.
+3. Apunta Compose a esa imagen local y re-ejecuta Ansible:
+
+ ```yml
+ # en vars.yml bajo constructa_compose_env
+ APP_IMAGE: "dokku/constructa"
+ APP_TAG: "latest"
+ ```
+
+ Deja `constructa_run_compose_migrate` en su valor por defecto `false`; Dokku ya ejecuta migraciones durante el despliegue. Re-ejecuta el playbook y (re)iniciará el worker usando la **imagen local de Dokku**—sin necesidad de push/pull del registro. El playbook también refrescará las redirecciones y certificados LetsEncrypt después de que la nueva configuración de dominio esté en su lugar.
+
+¿Necesitas omitir completamente el paso de compilación de Dokku? Construye y envía la imagen desde tu laptop en una línea:
+
+```bash
+pnpm run ex0 -- deploy-image --env dev
+```
+
+Este comando ejecuta `docker build`, transmite la imagen por SSH y ejecuta `dokku git:from-image` bajo el capó (cambia `--env dev` por `--env prod` según sea necesario, y agrega `--tag my-tag` si quieres un tag diferente).
+
+---
+
+## 2) DNS
+
+Apunta tu dominio de la app (ej. `app.example.com`) a la IP del servidor (un registro A proxied de Cloudflare está bien). Si quieres que `www.` redirija 301 al apex, listalo en `constructa_redirect_domains` y re-ejecuta el playbook.
+
+## 3) Iniciar servicios principales (Compose en el servidor)
+
+> Estos se ejecutan localmente en el VPS y se vinculan solo a **127.0.0.1**.
+
+> Si ejecutaste el playbook Ansible en el paso 1.5, los comandos a continuación ya fueron ejecutados. Mantenlos para referencia o cuando te recuperes manualmente.
+
+```bash
+# Copiar el bundle de infra; o deja que la Acción de GH lo haga
+scp -r infra/deploy/* deploy@your.server:/opt/constructa
+
+ssh deploy@your.server
+cd /opt/constructa
+cp .env.sample .env # completar valores
+# Para Dokku-first, establece HOST_BIND_ADDR=0.0.0.0 para que la app Dokku alcance los servicios
+
+# Iniciar Postgres, MinIO (+provisionar bucket), Redis, Meilisearch
+docker compose -f compose.yml up -d db minio redis meilisearch
+docker compose -f compose.yml up provision-minio || true
+
+# Iniciar worker en segundo plano (las migraciones se ejecutan durante el despliegue Dokku)
+docker compose -f compose.yml up -d worker
+```
+
+**¿Por qué este diseño?** Evita la variación de plugins para Postgres/MinIO en Dokku y te da una ruta estable para persistencia de datos a través de reinicios del servidor.
+
+> **Importante:** Este proyecto **no** usa los addons de Postgres/Redis de Dokku. La base de datos, caché, almacenamiento de objetos, etc. todos se ejecutan dentro del stack de compose arriba. Siempre mantén ese stack ejecutándose antes de desplegar; de lo contrario Dokku recurrirá a recursos provisionados por plugins que carecen de extensiones requeridas como `pgvector`.
+
+## 4) Crear la app Dokku
+
+> Si ejecutaste el playbook Ansible en el paso 1.5, Dokku ya ha sido configurado con la app, dominios, plugin de redirección, LetsEncrypt y opciones docker. Usa esta sección solo para bootstrap manual o recuperación ante desastres.
+
+```bash
+# creación única de app
+ssh root@your.server "dokku apps:create constructa"
+
+# dominio, enrutamiento http, y mapeo de host para alcanzar servicios compose
+ssh root@your.server "dokku domains:set constructa app.example.com"
+ssh root@your.server "dokku proxy:ports-set constructa http:80:5000"
+ssh root@your.server \"dokku docker-options:add constructa deploy,run '--add-host=host.docker.internal:host-gateway'\"
+```
+
+Ahora establece la configuración requerida. El detalle clave: **apunta a tus servicios loopback** (si omites esto, Dokku intentará usar su base de datos addon, que no incluye `pgvector` y tus migraciones fallarán):
+
+```bash
+ssh root@your.server "dokku config:set constructa \
+ NODE_ENV=production PORT=5000 \
+ DATABASE_URL='postgresql://user:password@host.docker.internal:5432/ex0' \
+ S3_ENDPOINT='http://host.docker.internal:9000' S3_REGION='us-east-1' \
+ S3_ACCESS_KEY_ID='minioadmin' S3_SECRET_ACCESS_KEY='minioadmin' \
+ S3_BUCKET='constructa-files' S3_ENABLE_PATH_STYLE=1 S3_PREVIEW_URL_EXPIRE_IN=7200 \
+ MEILI_HOST='http://host.docker.internal:7700' MEILI_API_KEY='changeme-master-key' \
+ REDIS_URL='redis://host.docker.internal:6379'"
+```
+
+Habilitar HTTPS:
+
+```bash
+ssh root@your.server "dokku letsencrypt:enable constructa"
+```
+
+(Con Ansible, establece `constructa_letsencrypt_email` en tu archivo vars y el playbook manejará la instalación del plugin, emisión del certificado y el trabajo cron de renovación.)
+
+## 5) Desplegar la app
+
+### Opción A – Simple: push desde tu laptop
+
+```bash
+git remote add dokku-prod dokku@your.server:constructa
+pnpm run ex0 -- deploy --env prod
+```
+
+### Opción B – CI/CD (GHCR): ver **docs/es/constructa/cicd.md** para login de registro y tags.
+
+---
+
+## Operaciones Comunes
+
+```bash
+# Logs
+ssh root@your.server "dokku logs constructa -t"
+
+# Escalar (solo web, worker es manejado por compose)
+ssh root@your.server "dokku ps:scale constructa web=1"
+
+# Reconstruir
+ssh root@your.server "dokku ps:rebuild constructa"
+
+# Rotar certificados
+ssh root@your.server "dokku letsencrypt:force-renew constructa"
+
+# Limpieza de disco (bajo demanda, seguro)
+pnpm run ex0 -- gc --age 720h # podar imágenes/caché sin usar más antiguas que 30 días
+```
+
+### ¿Por qué `host.docker.internal`?
+
+Los contenedores Dokku viven en la red **dokku**, pero tus servicios viven en la red **compose**. Mapear `host.docker.internal` al gateway del host Linux permite que los contenedores de la app hablen con servicios publicados en loopback (`127.0.0.1:…`). Establecemos eso con:
+
+```bash
+dokku docker-options:add constructa deploy,run "--add-host=host.docker.internal:host-gateway"
+```
diff --git a/docs/es/constructa/local-dev.md b/docs/es/constructa/local-dev.md
new file mode 100644
index 0000000..f4c5faf
--- /dev/null
+++ b/docs/es/constructa/local-dev.md
@@ -0,0 +1,65 @@
+# Desarrollo Local
+
+## Una sola vez
+
+```bash
+cp .env.example .env
+pnpm install
+pnpm run ex0 -- init # instala deps, inicia servicios principales, ejecuta migraciones
+```
+
+Esto inicia **PostgreSQL**, **MinIO**, **Redis**, **Meilisearch**, y **Mailhog** bajo el perfil `dev`.
+
+## Ejecutar la aplicación localmente
+
+```bash
+pnpm dev
+```
+
+Tu aplicación está en [http://localhost:3000](http://localhost:3000). El **worker** en segundo plano se ejecuta como un proceso separado si lo deseas (opcional):
+
+```bash
+pnpm worker
+```
+
+> El contenedor Docker `app` está reservado para auto-hospedaje/previews. En desarrollo, ejecuta el servidor Vite localmente para iteración más rápida.
+
+## Webhooks reales en desarrollo
+
+* **Ngrok**: `ngrok http 3000` — pega la URL de reenvío (ej. `https://xyz.ngrok-free.app/api/webhook/polar`) en el panel de Polar.
+* **Cloudflare Tunnel (opcional)**: Coloca tu token de túnel en `.env` como `CLOUDFLARED_TUNNEL_TOKEN`, luego:
+
+```bash
+docker compose --profile tunnel up -d cloudflared
+```
+
+> Los documentos de Polar recomiendan ngrok; Cloudflare Tunnel es una alternativa robusta con Zero Trust. Configura el que prefieras.
+
+## Emails
+
+Interfaz de Mailhog: [http://localhost:8025](http://localhost:8025) (SMTP en `mailhog:1025`).
+
+## Búsqueda
+
+* API de Meilisearch: `MEILI_HOST=http://localhost:7700`
+* Sembrar o reconstruir el índice:
+
+```bash
+pnpm run search:sync
+```
+
+## Trabajos en segundo plano
+
+* Cola: Redis (`REDIS_URL=redis://localhost:6379`)
+* La recarga diaria de créditos está programada a las 03:00 UTC vía BullMQ. Llama a tu endpoint existente `routes/api/jobs/daily-credit-refill`.
+* Puedes ejecutar el worker localmente:
+
+```bash
+pnpm worker
+```
+
+### Worker ↔ Endpoint de la App en desarrollo
+
+# Por defecto `JOB_DAILY_CREDIT_REFILL_URL=http://localhost:3000/api/jobs/daily-credit-refill`. Cuando ejecutas el worker dentro de Docker, también puede alcanzar el host vía `http://host.docker.internal:3000`.
+
+```
diff --git a/docs/es/constructa/mastra.md b/docs/es/constructa/mastra.md
new file mode 100644
index 0000000..6bae717
--- /dev/null
+++ b/docs/es/constructa/mastra.md
@@ -0,0 +1,253 @@
+# Integración de Mastra AI
+
+Este documento proporciona instrucciones completas de configuración y uso para la integración de Mastra AI en Constructa Starter.
+
+## Descripción General
+
+Constructa Starter incluye un asistente de IA consciente del repositorio impulsado por [Mastra](https://mastra.ai), un framework de agentes de IA que permite a los LLMs realizar acciones y acceder a herramientas externas. La integración presenta:
+
+- **Agente de Base de Código**: Un asistente de código senior que puede acceder a archivos almacenados en tu bucket MinIO/S3
+- **Integración de Herramientas**: Herramientas personalizadas para recuperar contenido de archivos desde almacenamiento de objetos
+- **Interfaz de Chat**: Interfaz de chat moderna construida con componentes de [Assistant UI](https://assistant-ui.com)
+- **Respuestas en Streaming**: Respuestas de IA en tiempo real con visualización de llamadas a herramientas
+
+## Arquitectura
+
+### Componentes
+
+1. **Agente Mastra** (`src/mastra/agents/codebase-agent.ts`)
+ - Impulsado por GPT-4.1-nano vía SDK de OpenAI
+ - Configurado con instrucciones para asistencia consciente del repositorio
+ - Integrado con herramientas personalizadas para acceso a archivos
+
+2. **Herramienta de Acceso a Archivos** (`src/mastra/tools/get-file-from-object-store.tool.ts`)
+ - Recupera contenido de texto UTF-8 desde buckets MinIO/S3
+ - Límites de bytes configurables (por defecto: 500KB)
+ - Maneja truncamiento de archivos y metadatos
+
+3. **Capa de Almacenamiento** (`src/mastra/storage.ts`)
+ - Se integra con infraestructura existente de S3/MinIO
+ - Proporciona interfaz unificada para operaciones de archivos
+
+4. **Endpoint API** (`src/routes/api/chat.tsx`)
+ - Ruta del lado del servidor que maneja solicitudes de chat
+ - Transmite respuestas de IA con llamadas a herramientas
+ - Validación Zod para payloads de mensajes
+
+5. **Interfaz de Chat** (`src/routes/dashboard/chat/`)
+ - Interfaz de chat basada en React con autenticación
+ - Muestra archivos disponibles desde almacenamiento de documentos
+ - Transmisión de mensajes en tiempo real con visualización de llamadas a herramientas
+
+## Prerequisitos
+
+Antes de configurar Mastra, asegúrate de tener:
+
+- ✅ **Clave API de OpenAI** - Requerida para funcionalidad LLM
+- ✅ **Configuración de MinIO/S3** - Para acceso a almacenamiento de archivos
+- ✅ **Autenticación** - El usuario debe haber iniciado sesión para acceder al chat
+- ✅ **Carga de Documentos** - Los archivos deben ser subidos vía página de Documentos para acceso de IA
+
+## Instrucciones de Configuración
+
+### 1. Configuración de Entorno
+
+Agrega tu clave API de OpenAI a tu archivo `.env`:
+
+```bash
+# Configuración de IA
+OPENAI_API_KEY="sk-your-openai-api-key-here"
+```
+
+### 2. Verificar Dependencias
+
+Los siguientes paquetes están incluidos automáticamente:
+
+```json
+{
+ "@mastra/core": "0.17.1",
+ "@ai-sdk/openai": "2.0.32",
+ "@assistant-ui/react": "^0.11.15",
+ "@assistant-ui/react-ai-sdk": "^1.1.0",
+ "@assistant-ui/react-data-stream": "^0.11.0",
+ "@assistant-ui/react-markdown": "^0.11.0",
+ "@assistant-ui/styles": "^0.2.1"
+}
+```
+
+### 3. Acceder a la Interfaz de Chat
+
+1. Iniciar el servidor de desarrollo:
+ ```bash
+ pnpm dev
+ ```
+
+2. Navegar a `/dashboard/chat` en tu navegador
+
+3. Iniciar sesión si se solicita
+
+4. Subir documentos vía `/dashboard/documents` para que la IA los referencie
+
+## Guía de Uso
+
+### Interacción Básica de Chat
+
+1. **Acceder al Chat**: Navegar a la sección "Chat" en la barra lateral
+2. **Ver Archivos Disponibles**: La interfaz muestra archivos que has subido a tu bucket MinIO
+3. **Hacer Preguntas**: Escribe preguntas sobre tu base de código o documentos subidos
+4. **Referenciar Archivos**: Menciona rutas de archivos específicas (ej. `src/lib/api.ts`) para que la IA obtenga el contenido
+
+### Herramienta de Acceso a Archivos
+
+La IA puede recuperar automáticamente contenido de archivos cuando mencionas rutas de archivos. Por ejemplo:
+
+- "¿Qué hay en `src/components/Button.tsx`?"
+- "Muéstrame el esquema de base de datos en `src/db/schema.ts`"
+- "Explica la lógica de autenticación en `src/server/auth.server.ts`"
+
+### Visualización de Llamadas a Herramientas
+
+Cuando la IA usa herramientas, verás:
+- **Indicadores de llamadas a herramientas** en los mensajes de chat
+- **Estado de recuperación de archivos** con metadatos (bytes, estado de truncamiento)
+- **Resultados de herramientas estructurados** para mejor legibilidad
+
+### Mejores Prácticas
+
+#### Referencias a Archivos
+- Usar rutas de archivos exactas de la sección "Archivos disponibles"
+- Incluir la ruta completa (ej. `src/routes/api/chat.tsx`)
+- La IA automáticamente obtendrá y analizará el contenido de los archivos
+
+#### Tipos de Preguntas
+- **Explicación de código**: "¿Qué hace esta función?"
+- **Preguntas de arquitectura**: "¿Cómo está implementada la autenticación?"
+- **Ayuda para depuración**: "¿Por qué no se está renderizando este componente?"
+- **Documentación**: "Crea un README para esta característica"
+
+#### Gestión de Contexto
+- Subir archivos relevantes antes de hacer preguntas
+- Referenciar múltiples archivos en una sola conversación
+- La IA mantiene el contexto a través de la conversación
+
+## Opciones de Configuración
+
+### Configuración del Agente
+
+El agente de base de código está configurado en `src/mastra/agents/codebase-agent.ts`:
+
+```typescript
+export const codebaseAgent = new Agent({
+ name: 'codebase-agent',
+ instructions: [
+ 'You are a senior code assistant for this repository.',
+ 'When a prompt references files or code, use the get-file-from-object-store tool to retrieve the exact content before answering.',
+ 'Always mention the object key(s) you consulted, adapt verbosity to user directions, and escalate with follow-up questions when file context is ambiguous.',
+ ].join(' '),
+ model: openai('gpt-4.1-nano'),
+ tools: {
+ getFileFromObjectStore,
+ },
+});
+```
+
+### Límites de Acceso a Archivos
+
+Configurar límites de recuperación de archivos en `src/mastra/tools/get-file-from-object-store.tool.ts`:
+
+```typescript
+const DEFAULT_MAX_BYTES = 512_000; // límite por defecto de 500 KB
+```
+
+### Selección de Modelo
+
+Cambiar el modelo de IA modificando la configuración del agente:
+
+```typescript
+model: openai('gpt-4'), // u otros modelos de OpenAI
+```
+
+## Solución de Problemas
+
+### Problemas Comunes
+
+#### "S3 bucket is not configured"
+- Asegúrate de que tu configuración de MinIO/S3 sea correcta en `.env`
+- Verifica que la variable de entorno `S3_BUCKET` esté establecida
+
+#### "No files synced yet"
+- Sube documentos vía la página de Documentos primero
+- Los archivos deben estar almacenados en tu bucket MinIO/S3 configurado
+
+#### "OpenAI API key missing"
+- Agrega `OPENAI_API_KEY` a tu archivo `.env`
+- Asegúrate de que la clave sea válida y tenga suficientes créditos
+
+#### Chat no se carga
+- Verifica la consola del navegador para errores
+- Verifica el estado de autenticación
+- Asegúrate de que todas las variables de entorno requeridas estén establecidas
+
+### Modo de Depuración
+
+Habilita registro detallado estableciendo:
+
+```bash
+DEBUG=mastra:*
+```
+
+### Consideraciones de Rendimiento
+
+- **Límites de Tamaño de Archivo**: Los archivos grandes se truncan automáticamente para prevenir desbordamiento de tokens
+- **Limitación de Tasa**: Los límites de tasa de la API de OpenAI se aplican a todas las solicitudes
+- **Caché**: Considera implementar caché de respuestas para archivos frecuentemente accedidos
+
+## Uso Avanzado
+
+### Herramientas Personalizadas
+
+Agregar nuevas herramientas creándolas en `src/mastra/tools/` y registrándolas en el agente:
+
+```typescript
+// Ejemplo de herramienta personalizada
+export const customTool = createTool({
+ id: 'custom-tool',
+ description: 'Descripción de lo que hace esta herramienta',
+ inputSchema: z.object({ /* validación de entrada */ }),
+ execute: async ({ context }) => {
+ // Implementación de la herramienta
+ },
+});
+```
+
+### Múltiples Agentes
+
+Crea agentes adicionales en `src/mastra/agents/` y regístralos en `src/mastra/index.ts`.
+
+### Backends de Almacenamiento Personalizados
+
+Extiende la capa de almacenamiento para soportar fuentes de archivos adicionales más allá de MinIO/S3.
+
+## Consideraciones de Seguridad
+
+- **Gestión de Claves API**: Nunca confirmes claves API en control de versiones
+- **Acceso a Archivos**: La IA solo puede acceder a archivos en tu bucket MinIO/S3 configurado
+- **Autenticación de Usuario**: La interfaz de chat requiere autenticación de usuario
+- **Limitación de Tasa**: Considera implementar limitación de tasa para endpoints API
+
+## Contribuir
+
+Al extender la integración de Mastra:
+
+1. Seguir los patrones existentes en `src/mastra/`
+2. Agregar tipos TypeScript apropiados
+3. Incluir manejo de errores completo
+4. Actualizar esta documentación
+5. Probar con varios tipos y tamaños de archivos
+
+## Recursos
+
+- [Documentación de Mastra](https://mastra.ai/docs)
+- [Documentación de Assistant UI](https://assistant-ui.com/docs)
+- [Referencia de API de OpenAI](https://platform.openai.com/docs/api-reference)
+- [Funciones del Servidor TanStack Start](https://tanstack.com/start/latest/docs/framework/server-functions)