@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/es-ES/database.md

@@ -0,0 +1,183 @@
+---
+title: "Base de datos"
+description: "Conecte una base de datos SQL portátil a su aplicación nativa del agente y escriba código Drizzle independiente del proveedor."
+---
+
+# Base de datos
+
+Las aplicaciones nativas del agente utilizan [Drizzle ORM](https://orm.drizzle.team) y admiten backends portátiles SQL. Para cualquier cosa más allá del desarrollo local, conecte una base de datos persistente SQL (Postgres, libSQL/Turso u otro backend compatible con Drizzle) configurando `DATABASE_URL`. Cuando esa variable no está configurada, la aplicación recurre a un archivo SQLite local de configuración cero para que pueda comenzar a desarrollar de inmediato.
+
+```an-diagram title="One schema, many backends" summary="App code uses the framework's dialect-agnostic helpers. The dialect is auto-detected from DATABASE_URL at runtime; unset means a local SQLite file."
+{
+  "html": "<div class=\"diagram-db\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">@agent-native/core/db/schema</span><small class=\"diagram-muted\">table · text · integer · real · now</small><small class=\"diagram-muted\">+ Drizzle query DSL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>DATABASE_URL<br><small class=\"diagram-muted\">dialect auto-detected</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Postgres<br><small class=\"diagram-muted\">Neon · Supabase</small></span><span class=\"diagram-pill\">libSQL / Turso</span><span class=\"diagram-pill\">Cloudflare D1</span><span class=\"diagram-pill warn\">SQLite file<br><small class=\"diagram-muted\">unset = local dev only</small></span></div></div>",
+  "css": ".diagram-db{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-db .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-db .diagram-arrow{font-size:22px;line-height:1}.diagram-db .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+}
+```
+
+## Valor predeterminado local: archivo SQLite {#default-sqlite}
+
+Cuando `DATABASE_URL` no está configurado, la aplicación crea una base de datos SQLite en `data/app.db`. Este es el valor predeterminado de configuración cero para el desarrollo local: no se requiere configuración. Está destinado únicamente al desarrollo; para producción, configure `DATABASE_URL` en una base de datos persistente SQL.
+
+No confíe en ese archivo local para las aplicaciones implementadas. Los contenedores, las funciones sin servidor y los entornos de vista previa pueden restablecer su sistema de archivos, lo que significa que un archivo SQLite local puede desaparecer entre reinicios. Configure `DATABASE_URL` en una base de datos alojada persistente antes de su uso en producción.
+
+## Conectar una base de datos de producción {#production}
+
+Configure `DATABASE_URL` en su archivo `.env` o entorno de proveedor de implementación para conectar una base de datos alojada. No se requiere Turso; utilice cualquier backend SQL compatible con Drizzle que se ajuste a su implementación:
+
+```bash
+# Neon Postgres
+DATABASE_URL=postgres://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/mydb?sslmode=require
+
+# Supabase Postgres
+DATABASE_URL=postgres://postgres.xxxx:pass@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+
+# Plain Postgres
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+
+# Turso (libSQL)
+DATABASE_URL=libsql://my-db-org.turso.io
+DATABASE_AUTH_TOKEN=your-token
+```
+
+El marco detecta automáticamente el dialecto del URL y configura el Drizzle en consecuencia. Los adaptadores integrados cubren Postgres URL, libSQL/Turso URL, SQLite file URL y enlaces Cloudflare D1. Las opciones de producción comunes incluyen entornos administrados Neon, Supabase, Turso/libSQL, Postgres simple, SQLite duradero y Builder.io cuando estén disponibles.
+
+## Base de datos administrada Builder.io {#builder-managed}
+
+_Planificado (aún no disponible):_ cuando esté conectado a Builder.io, su aplicación podrá utilizar una base de datos administrada y aprovisionada automáticamente, sin necesidad de cadenas de conexión.
+
+## Dónde vive el cliente DB {#db-client}
+
+Cada plantilla crea un cliente Drizzle único y diferido llamando a `createGetDb(schema)` desde `@agent-native/core/db`. La ubicación canónica es `server/db/index.ts`:
+
+```ts
+// server/db/index.ts
+import { createGetDb } from "@agent-native/core/db";
+import * as schema from "./schema.js";
+
+export const getDb = createGetDb(schema);
+```
+
+Importe `getDb` desde esta ruta local de plantilla (`../../server/db/index.js` en rutas, `../server/db/index.js` en actions) en lugar de hacerlo directamente desde `@agent-native/core`. La exportación principal devuelve una instancia genérica sin tipo; El `getDb()` de la plantilla lleva sus tipos de esquema. Consulte [Server](/docs/server#request-context) para saber cómo lo importan actions y las rutas personalizadas.
+
+## Esquemas y consultas independientes del dialecto {#schema}
+
+El código de la base de datos de la aplicación debe usar el esquema de Drizzle y consultar DSL para que pueda ejecutarse en todos los proveedores. Nunca escriba la sintaxis exclusiva de SQLite (`INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`) o la sintaxis exclusiva de Postgres en el código de producto.
+
+Utilice los ayudantes de esquema del marco de `@agent-native/core/db/schema`:
+
+```ts
+import { table, text, integer, real, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  priority: integer("priority").notNull().default(0),
+  weight: real("weight"),
+  done: integer("done", { mode: "boolean" }).notNull().default(false),
+  ownerEmail: text("owner_email").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+| Ayudante  | Propósito                                                                |
+| --------- | ------------------------------------------------------------------------ |
+| `table`   | Definir una tabla: delega en `pgTable` o `sqliteTable`                   |
+| `text`    | Columna de texto, compatible con `{ enum: [...] }`                       |
+| `integer` | Columna entera, `{ mode: "boolean" }` se asigna al booleano Postgres     |
+| `real`    | Columna flotante: `real` en SQLite, `double precision` en Postgres       |
+| `now`     | Marca de tiempo actual independiente del dialecto para `.default(now())` |
+
+La tabla `tasks` anterior define las mismas columnas en cada backend:
+
+```an-schema title="The tasks table" summary="Defined once with the framework helpers; the dialect is chosen at runtime from DATABASE_URL."
+{
+  "entities": [
+    {
+      "id": "tasks",
+      "name": "tasks",
+      "note": "Domain table. Add owner_email (or ...ownableColumns()) so SQL-level scoping can filter rows to the authenticated user.",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true, "nullable": false },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "priority", "type": "integer", "nullable": false, "note": "default 0" },
+        { "name": "weight", "type": "real", "nullable": true },
+        { "name": "done", "type": "integer (boolean mode)", "nullable": false, "note": "default false; maps to a Postgres boolean" },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "enables data scoping" },
+        { "name": "created_at", "type": "text", "nullable": false, "note": "default now()" }
+      ]
+    }
+  ]
+}
+```
+
+Nunca importe desde `drizzle-orm/sqlite-core` o `drizzle-orm/pg-core` directamente. Utilice siempre `@agent-native/core/db/schema`.
+
+Las tablas que almacenan datos de cara al usuario deben incluir una columna `owner_email` para que el alcance del nivel SQL del marco pueda filtrar filas para el usuario autenticado; consulte [Security](/docs/security#data-scoping). Las tablas que también admiten el uso compartido con otros usuarios u organizaciones deberían difundir `...ownableColumns()`, lo que agrega `owner_email`, `org_id` y `visibility` en una sola llamada; consulte [Sharing](/docs/sharing#building).
+
+Para lecturas y escrituras, utilice el generador de consultas de Drizzle y los operadores portátiles de `drizzle-orm`:
+
+```ts
+import { and, desc, eq } from "drizzle-orm";
+import { getDb } from "../server/db/index.js";
+import { tasks } from "../server/db/schema.js";
+
+const db = getDb();
+
+const openTasks = await db
+  .select()
+  .from(tasks)
+  .where(and(eq(tasks.ownerEmail, userEmail), eq(tasks.done, false)))
+  .orderBy(desc(tasks.createdAt));
+
+await db.update(tasks).set({ done: true }).where(eq(tasks.id, taskId));
+```
+
+## Trampillas de escape SQL sin procesar {#raw-sql}
+
+Raw SQL no es el código de aplicación predeterminado API. Úselo solo para migraciones aditivas, controles de estado, consultas avanzadas cuidadosamente revisadas que Drizzle no puede expresar o mantenimiento único. Manténgalo parametrizado e independiente del dialecto. Para marcas de tiempo en esquemas Drizzle, prefiera `.default(now())`; para la migración SQL, use `runMigrations()` para que las reescrituras de compatibilidad compatibles con el marco y las declaraciones controladas por dialecto permanezcan centralizadas.
+
+Para los casos en los que realmente necesita SQL sin formato fuera de las consultas Drizzle:
+
+- `getDbExec()`: convierte automáticamente los parámetros de `?` a `$1` para Postgres
+- `isPostgres()`: comprobación del dialecto en tiempo de ejecución
+- `intType()`: devuelve el tipo entero correcto para el dialecto actual
+
+## Migraciones y actualizaciones de esquemas {#migrations}
+
+En entornos alojados, varias vistas previas de implementación, sucursales y el servidor de producción comparten la misma base de datos subyacente. Por lo tanto, las actualizaciones del esquema de la base de datos deben seguir restricciones estrictas para evitar la pérdida de datos y la interrupción del servicio.
+
+### La regla de "Cero cambios destructivos"
+
+Todas las actualizaciones del esquema de la base de datos deben ser **estrictamente aditivas**.
+
+- **No elimine tablas ni columnas.**
+- **No cambie el nombre de tablas o columnas.** Cambiar el nombre de una columna o tabla parece una secuencia de soltar + crear a Drizzle, que eliminará permanentemente sus datos de producción existentes.
+- Si es necesario cambiar el nombre o reemplazar una columna, agregue la nueva columna junto con la anterior, actualice el código de su aplicación para leer y escribir en ambas, migre los datos y retire la columna anterior solo en una versión posterior una vez que no haya implementaciones activas que hagan referencia a ella.
+
+> [!WARNING]
+> **Nunca ejecute `drizzle-kit push` en una base de datos de producción.**
+> Los esquemas de bases de datos de plantilla solo definen tablas de dominio específicas de la aplicación; no definen tablas marco centrales (`user`, `session`, `application_state`, etc.). Si ejecuta `drizzle-kit push` en producción, Drizzle detectará estas tablas de marco como "no en el esquema" e intentará eliminarlas, lo que provocará una falla inmediata en todo el sistema y pérdida de datos.
+
+### Ruta de migración segura
+
+En lugar de enviarlos directamente, los cambios de esquema deben aplicarse mediante migraciones SQL ejecutadas al inicio de la aplicación. Implemente migraciones aditivas dentro de un complemento de servidor (por ejemplo, `server/plugins/db.ts`) invocando el asistente `runMigrations()` del marco:
+
+```an-annotated-code title="An additive migration plugin"
+{
+  "filename": "server/plugins/db.ts",
+  "language": "ts",
+  "code": "import { runMigrations } from \"@agent-native/core/db\";\n\nexport default runMigrations(\n  [\n    {\n      version: 1,\n      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,\n    },\n    {\n      // Dialect-gated: runs only on the matching backend. Omit the other key\n      // to make it a no-op on that dialect.\n      version: 2,\n      sql: {\n        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,\n        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only\n      },\n    },\n  ],\n  { table: \"my_app_migrations\" },\n);",
+  "annotations": [
+    { "lines": "6-7", "label": "Additive only", "note": "`ADD COLUMN IF NOT EXISTS` is safe to re-run and never drops data. Renames look like drop+create to Drizzle, so add-then-migrate instead." },
+    { "lines": "13-16", "label": "Dialect gating", "note": "Pass an object keyed by dialect to run different SQL per backend. Make the other key a no-op (`SELECT 1`) for Postgres-only or SQLite-only features." },
+    { "lines": "19", "label": "Per-app version table", "note": "Each app tracks its own applied versions so migrations are idempotent across restarts and instances." }
+  ]
+}
+```
+
+## Variables de entorno {#environment-variables}
+
+| Variable              | Propósito                                                                                                         |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`        | Cadena de conexión SQL persistente (no configurada = SQLite local, que solo es duradera para el desarrollo local) |
+| `DATABASE_AUTH_TOKEN` | Token de autenticación para proveedores que requieren un token separado, como Turso/libSQL                        |

package/corpus/core/docs/content/locales/es-ES/deployment.md

@@ -0,0 +1,349 @@
+---
+title: "Implementación"
+description: "Implemente aplicaciones nativas del agente en cualquier plataforma con ajustes preestablecidos de Nitro: Node.js, Vercel, Netlify, Cloudflare, AWS y más."
+---
+
+# Implementación
+
+Las aplicaciones nativas del agente usan [Nitro](https://nitro.build) internamente, lo que significa que puedes implementarlas en cualquier plataforma sin cambios de configuración: solo establece un ajuste preestablecido.
+
+## Antes de implementar: elija una base de datos persistente {#persistent-database}
+
+Cada aplicación implementada necesita una base de datos SQL persistente. En el desarrollo local, el agente nativo recurre a un archivo SQLite en `data/app.db`; eso es conveniente en su máquina, pero no es duradero en contenedores, vistas previas o entornos sin servidor donde se puede restablecer el sistema de archivos.
+
+Configure `DATABASE_URL` en su proveedor de implementación antes de promocionar una aplicación a producción. El agente nativo utiliza Drizzle para esquemas y consultas, por lo que la capa de datos es portátil entre backends SQL compatibles con Drizzle y el marco detecta automáticamente el dialecto de URL. Consulte [Database](/docs/database#production) para obtener la lista de adaptadores y detalles del dialecto.
+
+Utilice `DATABASE_AUTH_TOKEN` solo cuando su proveedor de base de datos requiera un token separado, como Turso/libSQL. Para los espacios de trabajo, todas las aplicaciones heredan la raíz `DATABASE_URL` de forma predeterminada; configure `<APP_NAME>_DATABASE_URL` cuando una aplicación deba usar una base de datos diferente.
+
+## Implementación del espacio de trabajo: un origen, muchas aplicaciones {#workspace-deploy}
+
+Si tu proyecto es [workspace](/docs/multi-app-workspace), puedes enviar todas las aplicaciones que contiene a un único origen con un solo comando:
+
+```bash
+npx @agent-native/core@latest deploy
+# https://your-agents.com/mail/*       → apps/mail
+# https://your-agents.com/calendar/*   → apps/calendar
+# https://your-agents.com/forms/*      → apps/forms
+```
+
+Cada aplicación se crea con `APP_BASE_PATH=/<name>` y `VITE_APP_BASE_PATH=/<name>` y luego se empaqueta para el ajuste preestablecido Nitro de destino. Cloudflare Pages es el valor preestablecido predeterminado y utiliza un trabajador despachador generado en `dist/_worker.js`; Netlify usa una función por aplicación en `.netlify/functions-internal/<app>-server` más redireccionamientos generados; Vercel escribe un `.vercel/output` a nivel de espacio de trabajo utilizando Build Output API.
+
+```an-diagram title="One origin, many apps" summary="Each workspace app is built with its own base path and mounted under a path prefix on a single origin — so login and cross-app A2A are same-origin and free."
+{
+  "html": "<div class=\"diagram-ws\"><div class=\"diagram-panel\" data-rough><strong>https://your-agents.com</strong><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/mail/*</span><small class=\"diagram-muted\">apps/mail</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/calendar/*</span><small class=\"diagram-muted\">apps/calendar</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/forms/*</span><small class=\"diagram-muted\">apps/forms</small></div></div><div class=\"diagram-col wins\"><span class=\"diagram-pill ok\">shared login session</span><span class=\"diagram-pill ok\">zero-config cross-app A2A</span></div></div>",
+  "css": ".diagram-ws{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-ws .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:14px 16px}.diagram-ws .diagram-row{display:flex;align-items:center;gap:8px}.diagram-ws .wins{display:flex;flex-direction:column;gap:8px;align-items:flex-start}"
+}
+```
+
+La implementación del mismo origen te ofrece dos grandes beneficios gratis:
+
+- **Sesión de inicio de sesión compartida**: inicie sesión en cualquier aplicación, todas las aplicaciones están iniciadas.
+- **Zero-config cross-app A2A**: etiquetar `@calendar` desde el correo es una recuperación del mismo origen; nada de CORS, nada de firmas JWT entre hermanos.
+
+Publicar el resultado con:
+
+```bash
+wrangler pages deploy dist
+```
+
+Para implementaciones unificadas de Netlify, utilice el ajuste preestablecido de Netlify:
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+Para implementaciones unificadas de Vercel, utilice el ajuste preestablecido de Vercel:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+Al configurar un comando de compilación de proveedor, use el mismo comando con `--build-only`. Vercel debería ejecutar `npx @agent-native/core@latest deploy --preset vercel --build-only`; el comando escribe `.vercel/output` directamente, por lo que no se requiere ningún `vercel.json` para el enrutamiento del espacio de trabajo.
+
+Las compilaciones de espacios de trabajo alojados requieren `A2A_SECRET` en el entorno del proveedor de implementación.
+Esto hace que los currículums Slack, webhooks entrante y A2A entre aplicaciones funcionen mediante firma
+procesadores en segundo plano. Las comprobaciones de artefactos locales `--build-only` aún se ejecutan sin él.
+
+Aún se admite la implementación independiente por aplicación, solo `cd apps/<name> && npx @agent-native/core@latest build` como un andamio independiente.
+
+## Cómo funciona {#how-it-works}
+
+Cuando ejecuta `npx @agent-native/core@latest build`, Nitro construye tanto el cliente SPA como el servidor API en `.output/`:
+
+```an-file-tree title="Build output"
+{
+  "entries": [
+    { "path": ".output/", "note": "self-contained — copy to any environment and run" },
+    { "path": ".output/public/", "note": "built SPA (static assets)" },
+    { "path": ".output/server/index.mjs", "note": "server entry point" },
+    { "path": ".output/server/chunks/", "note": "server code chunks" }
+  ]
+}
+```
+
+El resultado es autónomo: copie `.output/` a cualquier entorno y ejecútelo.
+
+```an-diagram title="Build to deploy" summary="One source tree builds to a Nitro preset; the same self-contained output runs on Node, Vercel, Netlify, Cloudflare, AWS, or Deno. Every instance points at the same persistent DATABASE_URL."
+{
+  "html": "<div class=\"diagram-deploy\"><div class=\"diagram-box\" data-rough>App source</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">build</span><small class=\"diagram-muted\">Nitro preset</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Node.js</span><span class=\"diagram-pill\">Vercel</span><span class=\"diagram-pill\">Netlify</span><span class=\"diagram-pill\">Cloudflare</span><span class=\"diagram-pill\">AWS Lambda</span><span class=\"diagram-pill\">Deno</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Persistent DATABASE_URL<br><small class=\"diagram-muted\">shared by every instance</small></div></div>",
+  "css": ".diagram-deploy{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-deploy .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-deploy .diagram-arrow{font-size:22px;line-height:1}.diagram-deploy .diagram-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}"
+}
+```
+
+## Configuración del preajuste {#setting-the-preset}
+
+De forma predeterminada, Nitro se compila para Node.js. Para apuntar a una plataforma diferente, configure el ajuste preestablecido en su `vite.config.ts`:
+
+```ts
+import { defineConfig } from "@agent-native/core/vite";
+
+export default defineConfig({
+  nitro: {
+    preset: "vercel",
+  },
+});
+```
+
+O utilice la variable de entorno `NITRO_PRESET` en el momento de la compilación:
+
+```bash
+NITRO_PRESET=netlify npx @agent-native/core@latest build
+```
+
+## Node.js (predeterminado) {#nodejs}
+
+El valor predeterminado predeterminado. Construir y ejecutar:
+
+```bash
+npx @agent-native/core@latest build
+node .output/server/index.mjs
+```
+
+Establezca `PORT` para configurar el puerto de escucha (predeterminado: `3000`).
+
+Utilice la línea actual Node.js LTS para implementaciones de producción. A partir de mayo de 2026,
+es Node.js 24; Node.js 20 llegó al final de su vida útil el 30 de abril de 2026 y ya no
+recibe actualizaciones de seguridad ascendentes.
+
+### Acoplador {#docker}
+
+```dockerfile
+FROM node:24-slim AS build
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+FROM node:24-slim
+WORKDIR /app
+COPY --from=build /app/.output .output
+# data/ is a runtime-created SQLite directory — do not copy a dev DB into prod.
+# For production, set DATABASE_URL to a hosted Postgres or Turso instance.
+RUN mkdir -p /app/data
+ENV PORT=3000
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+## Vercel {#vercel}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "vercel" },
+});
+```
+
+Implemente a través de Vercel CLI o git push:
+
+```bash
+vercel deploy
+```
+
+Para un espacio de trabajo, cree cada aplicación en un paquete Vercel Build Output API:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+Para implementaciones de Vercel Git, configure el comando de compilación en:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel --build-only
+```
+
+La compilación del espacio de trabajo copia la salida Nitro `vercel` de cada aplicación en la raíz `.vercel/output`, le da a cada función su propio entorno de ruta de montaje y escribe la configuración de ruta que sirve a las aplicaciones en `/<app-id>`.
+
+## Netlificar {#netlify}
+
+El ajuste preestablecido Nitro `netlify` funciona bien y, en la práctica, nos ha brindado inicios en frío mucho más rápidos que Cloudflare Pages (~200 ms TTFB frente a ~9 s) para plantillas que se comunican con Postgres externo (Neon). Configure el valor preestablecido en `vite.config.ts`:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "netlify" },
+});
+```
+
+…o configure `NITRO_PRESET=netlify` en el momento de la compilación.
+
+Para un espacio de trabajo, implemente todas las aplicaciones desde un sitio de Netlify ejecutando:
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+La compilación del espacio de trabajo escribe recursos estáticos en `dist/_workspace_static/` y enruta cada aplicación a su propia función Netlify sin redirecciones forzadas de activos, por lo que archivos como `/mail/assets/...` se sirven estáticamente antes de que la función del servidor maneje las rutas de las aplicaciones.
+
+## Páginas de Cloudflare {#cloudflare-pages}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "cloudflare_pages" },
+});
+```
+
+## AWS Lambda {#aws-lambda}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "aws_lambda" },
+});
+```
+
+## Implementación de Deno {#deno-deploy}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "deno_deploy" },
+});
+```
+
+## Variables de entorno {#environment-variables}
+
+### Compilación/Tiempo de ejecución {#env-runtime}
+
+| Variables                   | Descripción                                                                                                                                                                           |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                      | Puerto del servidor (solo Node.js)                                                                                                                                                    |
+| `NITRO_PRESET`              | Anular el valor preestablecido de compilación en el momento de la compilación                                                                                                         |
+| `APP_BASE_PATH`             | Monte la aplicación bajo un prefijo (por ejemplo, `/mail`). Establecido automáticamente por `npx @agent-native/core@latest deploy`; déjelo sin configurar para que sea independiente. |
+| `AGENT_PROD_CODE_EXECUTION` | Modo de ejecución de código de producción opcional: `off` (predeterminado), `sandboxed` o `trusted`. Ver [Production Code Execution](#production-code-execution).                     |
+
+Las variables de conexión de la base de datos (`DATABASE_URL`, `DATABASE_AUTH_TOKEN`, `<APP_NAME>_DATABASE_URL` por aplicación) se encuentran en [Database](/docs/database#production).
+
+### Requerido en producción {#env-required-prod}
+
+Estos deben configurarse antes de promocionar una aplicación para una implementación de producción real. Los valores faltantes se cierran fallidamente (el marco se niega a iniciar/se niega a manejar solicitudes) o recurren a un comportamiento más débil con una advertencia fuerte.
+
+| Variable                 | Descripción                                                                                                                                                                                                                                                                                              |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`     | Cadena aleatoria de más de 32 caracteres. Las cookies de sesión de signos AND son la alternativa HMAC para `OAUTH_STATE_SECRET` y `SECRETS_ENCRYPTION_KEY`. Requerido: el marco se inicia al inicio si falta en producción.                                                                              |
+| `BETTER_AUTH_URL`        | Origen público de esta aplicación (por ejemplo, `https://mail.example.com`). Se utiliza para el dominio de cookies y la construcción de redirecciones OAuth.                                                                                                                                             |
+| `ANTHROPIC_API_KEY`      | Clave API para el agente de producción integrado. **En implementaciones multiinquilino**, el marco se niega a recurrir a esto cuando el usuario no tiene una clave por usuario; es necesario traer su propia clave. Las instalaciones autohospedadas de un solo inquilino la utilizan como clave global. |
+| `OAUTH_STATE_SECRET`     | Clave HMAC dedicada para sobres de estado OAuth (Google, Atlassian, Zoom). Vuelve a `BETTER_AUTH_SECRET` cuando no está configurado, pero se recomienda un valor dedicado para que rotar uno no invalide el otro. Generar a través de `openssl rand -hex 32`.                                            |
+| `A2A_SECRET`             | HMAC compartido para A2A JSON-RPC entre aplicaciones. Sin él, cada terminal A2A y el terminal automático `/_agent-native/integrations/process-task` devuelven 503 en producción.                                                                                                                         |
+| `SECRETS_ENCRYPTION_KEY` | Clave AES-256-GCM para la bóveda de secretos cifrados en reposo. Vuelve a `BETTER_AUTH_SECRET`. Se producen fallos graves en producción cuando ambos están desarmados.                                                                                                                                   |
+
+### Autenticación e identidad {#env-auth}
+
+Las credenciales del proveedor OAuth (Google, GitHub), los respaldos de portador estáticos de MCP (`ACCESS_TOKEN` / `ACCESS_TOKENS`) y los conmutadores de verificación de correo electrónico están documentados en [Authentication](/docs/authentication). Configúrelos allí según el modo de autenticación que elija.
+
+### Entrante Webhooks {#env-webhooks}
+
+Cada integración de mensajería requiere su propio secreto de firma en producción (los controladores fallan en solicitudes falsificadas cuando falta el secreto). Las variables por integración se enumeran en [Messaging](/docs/messaging) y [Security](/docs/security). Solo para desarrollo local, `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` vuelve a optar por "advertir y aceptar"; nunca lo configure en producción.
+
+### Configuración de seguridad (optación) {#security-config}
+
+Los valores predeterminados son estrictos. Un puñado de indicadores de participación relajan el comportamiento (rastreos de pila de depuración, webhooks no verificado, reserva de clave con ámbito de espacio de trabajo, conmutador multiorganización del concentrador MCP, escrituras env-var en tiempo de ejecución). Están documentados con sus compensaciones de seguridad en [Security](/docs/security). No los establezcas a menos que quieras específicamente el camino relajado.
+
+### Herencia del espacio de trabajo .env {#env-inheritance}
+
+Dentro de un espacio de trabajo, la raíz `.env` se carga automáticamente en cada aplicación, por lo que las claves compartidas como `ANTHROPIC_API_KEY`, `A2A_SECRET`, `BETTER_AUTH_SECRET` y `OAUTH_STATE_SECRET` solo deben configurarse una vez. El `apps/<name>/.env` por aplicación gana en caso de conflicto.
+
+### Generando secretos fuertes {#env-generate-secrets}
+
+Para cualquier secreto marcado como "32+ caracteres aleatorios" (`BETTER_AUTH_SECRET`, `OAUTH_STATE_SECRET`, `A2A_SECRET`, `SECRETS_ENCRYPTION_KEY`), genere valores nuevos con:
+
+```bash
+openssl rand -hex 32
+```
+
+Gírelos reemplazando la var de entorno en cada instancia y volviéndolos a implementar: los sobres de estado de sesiones/OAuth firmados con la clave anterior dejan de ser válidos, por lo que es posible que los usuarios deban iniciar sesión nuevamente.
+
+## Herramientas del agente de producción {#production-agent-tools}
+
+Los agentes de producción obtienen las herramientas de marco actions plus registradas de la aplicación de
+el complemento de chat del agente. Las escrituras en bases de datos están habilitadas de forma predeterminada porque la base de datos sin formato
+herramientas están dirigidas al usuario/organización autenticado, pero los propietarios de aplicaciones pueden limitar el
+cuando una implementación debería ser más obstinada:
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  // Default: "write" (also true)
+  databaseTools: "read", // "write" | "read" | "off"
+  extensionTools: false,
+});
+```
+
+- `databaseTools: "write"`: predeterminado. Registros `db-schema`, `db-query`,
+  `db-exec` y `db-patch`. Las escrituras tienen como ámbito el usuario/organización actual y
+  Los cambios de esquema están bloqueados.
+- `databaseTools: "read"`: registra solo `db-schema` y `db-query`; agentes
+  inspecciona los datos con SQL pero debes usar la aplicación escrita actions para las escrituras.
+- `databaseTools: "off"` o `false`: elimina las herramientas de base de datos sin procesar del
+  superficie del agente para que los actions de la aplicación sean la única ruta de acceso a los datos.
+- `extensionTools: false`: elimina la gestión de extensiones del marco actions y
+  orientación rápida (`create-extension`, `update-extension`, etc.) para aplicaciones que
+  No quiero que el agente cree miniaplicaciones en espacio aislado.
+
+## Ejecución del código de producción {#production-code-execution}
+
+De forma predeterminada, los agentes de producción se ejecutan sin herramientas de ejecución de código. Pueden llamar a la aplicación actions, herramientas de base de datos, herramientas MCP, herramientas de navegador/sesión y otras herramientas de marco registradas, pero no obtienen acceso al shell ni al sistema de archivos.
+
+Las implementaciones compatibles con nodos pueden optar por la ejecución de código de producción a través del complemento de chat del agente o una anulación del entorno:
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  codeExecution: { production: "sandboxed" },
+});
+```
+
+Los modos disponibles son:
+
+- `off`: el valor predeterminado. No hay herramientas de ejecución de código registradas en producción.
+- `sandboxed`: registra `run-code`, un ejecutor aislado Node.js JavaScript con un entorno limpio, un directorio temporal nuevo, límites de salida/tiempo y un puente de host local para herramientas registradas en la lista permitida, como `provider-api-request`, `provider-api-docs`, `provider-api-catalog`, `web-request` y el puente de archivos del espacio de trabajo respaldado por recursos utilizado por `workspaceRead` / `workspaceWrite`.
+- `trusted`: registra `run-code` más el registro completo de la herramienta de codificación (`bash`, `read`, `edit`, `write`). Úselo solo para implementaciones de un solo inquilino o controladas por un operador donde el acceso completo al host es intencional.
+
+Configure `AGENT_PROD_CODE_EXECUTION=sandboxed` o `AGENT_PROD_CODE_EXECUTION=trusted` para anular la opción del complemento para una implementación específica sin un cambio de código. `AGENT_PROD_CODE_EXECUTION=off` fuerza la ejecución del código incluso cuando la opción del complemento lo habilita.
+
+El entorno limitado `run-code` es un aislamiento a nivel de proceso, no un contenedor de sistema operativo. Elimina los secretos de la aplicación del entorno del proceso secundario y utiliza el modelo de permisos de Node cuando está disponible, pero el propio Node no bloquea la red saliente; las llamadas autenticadas deben pasar por los asistentes de puente que expone la herramienta.
+
+## Actualizando UI en producción {#updating-ui-in-production}
+
+Una de las características principales del agente nativo es que el agente puede modificar el código fuente de su aplicación: componentes, rutas, estilos, actions. Durante el desarrollo local, esto funciona perfectamente porque el agente tiene acceso total al sistema de archivos.
+
+En una implementación de producción estándar con [production code execution](#production-code-execution) excluido, el agente tiene acceso a las herramientas de la aplicación (actions, base de datos, MCP), pero no al sistema de archivos. Esto significa que el agente puede leer y escribir datos, ejecutar actions e interactuar con servicios externos, pero no puede editar los componentes de React ni agregar nuevas rutas en una instancia implementada.
+
+### Builder.io: Edición visual en producción {#builderio}
+
+[Builder.io](https://www.builder.io) resuelve este problema proporcionando un entorno de nube administrado donde el agente conserva la capacidad de modificar el UI de su aplicación en producción. Conecte su repositorio a Builder.io y solicite los cambios de UI directamente, sin necesidad de volver a implementarlo.
+
+**Cómo funciona:**
+
+1. Conecte su repositorio nativo del agente a Builder.io
+2. Builder.io proporciona un marco en la nube con el agente, edición visual y colaboración en tiempo real
+3. Solicite al agente que realice cambios UI: edita sus componentes, rutas y estilos en vivo
+4. Los cambios se confirman en su repositorio
+
+Consulte [Frames](/docs/frames) para obtener más información sobre el panel de agente integrado frente a las opciones del marco de nube.
+
+## Implementaciones de instancias múltiples {#multi-instance}
+
+Las aplicaciones nativas del agente almacenan todo el estado en SQL a través de Drizzle y sincronizan el UI a través de [polling](/docs/key-concepts#polling-sync) con la base de datos: sin estado del sistema de archivos, sin sesiones fijas, sin cachés en memoria. Eso significa que las implementaciones de múltiples instancias y sin servidor funcionan de inmediato: apunte cada instancia al mismo `DATABASE_URL` y convergerán automáticamente. Ver [Key Concepts — Data in SQL](/docs/key-concepts#data-in-sql) y [Portability](/docs/key-concepts#hosting-agnostic).