@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/es-ES/faq.md

@@ -0,0 +1,142 @@
+---
+title: "FAQ"
+description: "Preguntas comunes sobre el agente nativo: qué es, para quién es, qué se puede crear y cómo funciona."
+---
+
+# FAQ
+
+Preguntas comunes sobre el agente nativo, organizadas desde "Solo estoy mirando" hasta "Estoy conectando la autenticación ahora mismo".
+
+## Conceptos básicos {#general}
+
+### ¿Qué es el agente nativo? {#what-is-agent-native}
+
+Agent-native es un marco para crear aplicaciones en las que el agente de IA y la superficie del producto que lo rodea son socios iguales. Esa superficie puede comenzar como un agente sin cabeza con una acción personalizada, convertirse en un chat enriquecido o convertirse en un UI completo. La invariante es que los agentes y los humanos comparten el mismo actions, base de datos y estado. Consulte [What Is Agent-Native?](/docs/what-is-agent-native) para obtener la explicación completa.
+
+### ¿Para quién es esto? {#who-is-this-for}
+
+El agente nativo es para personas que desean que una aplicación real y un agente de IA trabajen con los mismos datos y actions. Las rutas comunes son:
+
+- **Utilice una aplicación alojada** si desea Correo, Calendario, Formularios, Plan u otra plantilla terminada sin configuración; comience en [template gallery](/templates).
+- **Comience con Chat** si desea una aplicación básica con la que los usuarios puedan hablar inmediatamente, luego amplíe con actions y pantallas; comience con [Getting Started](/docs/getting-started) o [Chat](/docs/template-chat).
+- **Inicie primitivo primero** si desea una acción y un bucle de agente de aplicación sin cabeza antes de comprometerse con UI; comience con [Getting Started](/docs/getting-started).
+- **Bifurque y personalice una plantilla** si desea su propio producto SaaS con autenticación, base de datos, UI y agente actions ya conectados; consulte [Templates](/docs/cloneable-saas).
+- **Compile desde cero** si desea las primitivas del marco para un nuevo producto impulsado por agentes, comience con [Getting Started](/docs/getting-started).
+- **Conecte otro agente o herramienta de código** si desea que Claude, ChatGPT, Codex, Cursor o GitHub Copilot/VS Code utilice una aplicación nativa del agente; consulte [External Agents](/docs/external-agents) y [Skills Guide](/docs/skills-guide).
+
+### ¿En qué se diferencia esto de agregar IA a una aplicación existente? {#how-is-this-different}
+
+La mayoría de las aplicaciones incorporan IA como una ocurrencia tardía que en realidad no puede _hacer_ cosas en la aplicación. En una aplicación nativa del agente, el agente es un ciudadano de primera clase que comparte el mismo actions, la misma base de datos y el mismo estado que el UI, por lo que puede hacer cualquier cosa que los botones puedan hacer y modificar el propio código de la aplicación. Ver [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder).
+
+```an-diagram title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI."
+{
+  "html": "<div class=\"diagram-vs\"><div class=\"diagram-col\"><span class=\"diagram-pill warn\">Bolted-on AI</span><div class=\"diagram-node\">Chat sidebar</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>separate AI world<br><small class=\"diagram-muted\">can't touch the app</small></div><div class=\"diagram-box diagram-muted\">App UI &amp; data</div></div><div class=\"diagram-divider\" aria-hidden=\"true\"></div><div class=\"diagram-col\"><span class=\"diagram-pill ok\">Agent-native</span><div class=\"diagram-row2\"><div class=\"diagram-node\">UI</div><div class=\"diagram-node\">Agent</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>shared actions, DB &amp; state</div></div></div>",
+  "css": ".diagram-vs{display:flex;align-items:stretch;gap:18px;flex-wrap:wrap}.diagram-vs .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:center;flex:1;min-width:200px}.diagram-vs .diagram-row2{display:flex;gap:8px}.diagram-vs .diagram-arrow{font-size:20px;line-height:1}.diagram-vs .diagram-divider{width:1px;align-self:stretch;background:currentColor;opacity:.15}"
+}
+```
+
+### ¿Es de código abierto? {#is-this-open-source}
+
+Sí. El marco y todas las plantillas son de código abierto. Puede ejecutar todo localmente, autohospedarse o utilizar la nube de Builder.io para alojamiento administrado, colaboración y funciones de equipo.
+
+### ¿Cuánto cuesta? {#how-much}
+
+El marco en sí es gratuito. Los dos costos que verás en la práctica:
+
+- **Uso de IA.** Traes tu propia clave API (Anthropic, OpenAI, etc.) y pagas directamente al proveedor del modelo. No hacemos ningún margen de beneficio.
+- **Alojamiento.** Lo que sea que cobre tu anfitrión. La mayoría de las plantillas funcionan bien en niveles gratuitos (Netlify, Vercel, Cloudflare) para cargas de trabajo pequeñas.
+
+Si prefiere no administrar nada de esto, la versión alojada en `agent-native.com` (operada por Builder.io) incluye inferencia y alojamiento en un plan por puesto.
+
+### ¿Puedo alojar esto yo mismo? {#can-i-self-host}
+
+Sí. Elija cualquier host que ejecute Node (Netlify, Vercel, Cloudflare, AWS, Deno Deploy, su propio servidor) y cualquier base de datos SQL (Postgres, SQLite, Turso, D1). El marco está diseñado para ser portátil. Ver [Deployment](/docs/deployment).
+
+### ¿Qué modelos de IA admite? {#what-models}
+
+Anthropic Claude, OpenAI (familia GPT-5), Google Gemini y cualquier proveedor que hable la forma OpenAI API (incluidos los modelos locales a través de Ollama). Configuras el modelo en la configuración; El cambio es un cambio de configuración, no una reescritura de código. La ruta más probada del marco es Claude, por lo que esa es la recomendación predeterminada.
+
+### ¿Necesito saber AI/ML? {#do-i-need-to-know-ai}
+
+No. No se entrenan modelos, no se ajustan ni se ocupan de incrustaciones. Creas una aplicación web normal y, en la versión alojada, apenas creas nada. El marco maneja la integración del agente: enrutamiento de mensajes, ejecución de actions, estado de sincronización.
+
+### ¿Puedo migrar una aplicación existente a agente nativo? {#can-i-use-existing-code}
+
+Puedes, pero el agente nativo funciona mejor cuando se construye desde cero. La arquitectura (base de datos compartida, sincronización de sondeos, actions, estado de la aplicación) debe estar integrada en todo momento. Partir de una plantilla y personalizarla es el camino recomendado. Piense en ello como el cambio de una computadora de escritorio primero a una computadora móvil primero: _puede_ modernizarse, pero crear contenido nativo es mejor.
+
+## Plantillas y lo que puedes crear {#templates}
+
+### ¿Qué plantillas están disponibles? {#what-templates-are-available}
+
+El marco se entrega con plantillas listas para producción que incluyen [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (planos visuales y resúmenes de relaciones públicas), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch) y más. Cada una es una aplicación completa con UI, agente actions, esquema de base de datos e instrucciones de IA listas para usar. Consulte [Templates](/docs/cloneable-saas) para ver el catálogo completo.
+
+### ¿Puedo personalizar plantillas? {#can-i-customize-templates}
+
+Ese es el punto. Bifurca una plantilla y personalízala preguntándole al agente. "Agregar un campo de prioridad a los formularios". "Conéctese a nuestra instancia de Salesforce". "Cambie la combinación de colores para que coincida con nuestra marca". El agente modifica el código y su aplicación evoluciona con el tiempo.
+
+### ¿Puedo crear algo que las plantillas no cubran? {#build-from-scratch}
+
+Sí. Si desea una aplicación de chat básica, ejecute `npx @agent-native/core@latest create my-chat-app --template chat`; obtienes hilos de chat duraderos, actions, autenticación, estado de ejecución respaldado por SQL y espacio para agregar tus propias pantallas. Si desea la aplicación más pequeña de acción primero sin UI, ejecute `npx @agent-native/core@latest create my-agent --headless`. Consulte [Getting Started](/docs/getting-started), [Pure-Agent Apps](/docs/pure-agent-apps) y [Chat](/docs/template-chat).
+
+### ¿Puedo probarlo sin bifurcar una plantilla? {#try-with-a-skill}
+
+Sí: instale una habilidad en un agente de codificación que ya usa con un comando y no requiere andamio. Consulte [Skills Guide](/docs/skills-guide#app-backed-skills) para ver el tutorial.
+
+## Capacidades del agente {#agent-capabilities}
+
+### ¿Puede realmente el agente modificar el propio código de la aplicación? {#can-the-agent-modify-code}
+
+Sí, y es una característica. El agente puede editar de forma segura componentes, rutas, estilos y actions. Usted pregunta "agregar un gráfico de análisis de cohorte" y el agente lo crea. Pides "conectar a nuestra cuenta Stripe" y el agente escribe la integración. Todo es código normal rastreado por Git, por lo que los cambios incorrectos son fáciles de revertir.
+
+### ¿Pueden los usuarios hablar con el agente desde fuera de la aplicación? {#external-channels}
+
+Sí. El mismo agente se ejecuta en tu web UI, en Slack, en Telegram, por correo electrónico y desde otros agentes (vía [A2A](/docs/a2a-protocol)). Es el mismo agente con la misma memoria y el mismo actions, solo que se llega a través de diferentes canales. Ver [Messaging the agent](/docs/messaging).
+
+### ¿Pueden los agentes hablar entre sí? {#can-agents-talk-to-each-other}
+
+Sí, a través del [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Cada aplicación nativa del agente obtiene automáticamente un punto final A2A. Desde la aplicación de correo, puede etiquetar al agente de análisis para consultar datos. Un agente descubre qué otros agentes están disponibles, los llama a través del protocolo y muestra los resultados en UI. No se necesita configuración: la tarjeta de agente se genera automáticamente a partir del actions de su plantilla.
+
+### ¿Qué puede ver el agente en la aplicación? {#what-can-the-agent-see}
+
+El agente siempre sabe lo que el usuario está viendo actualmente. El UI escribe el estado de navegación en la base de datos en cada cambio de ruta: qué vista está abierta, qué elemento está seleccionado. El agente lee esto antes de actuar. Si un correo electrónico está abierto, el agente sabe qué correo electrónico. Si se selecciona una diapositiva, el agente sabe qué diapositiva. Ver [Context Awareness](/docs/context-awareness).
+
+## Preguntas de desarrollo {#development}
+
+### ¿Qué herramientas de codificación de IA funcionan con el agente nativo? {#which-ai-tools-work}
+
+Cualquier herramienta de codificación de IA que lea las instrucciones del proyecto. El marco utiliza AGENTS.md como estándar universal y crea automáticamente enlaces simbólicos para herramientas específicas:
+
+- **Código Claude**: lee CLAUDE.md (enlazado simbólicamente desde AGENTS.md mediante la configuración de CLI)
+- **Cursor**: lee AGENTS.md directamente o `.cursorrules` (ubicación heredada del cursor) si está presente en su proyecto
+- **Windsurf**: lee .windsurfrules (enlazado simbólicamente desde AGENTS.md mediante la configuración de CLI)
+- **Codex, Gemini y otros**: trabaje a través del panel de agente integrado
+- **Builder.io**: agente alojado en la nube con edición visual y colaboración
+
+### ¿Puedo usar mi propia base de datos? {#can-i-use-my-own-database}
+
+Sí. Configure `DATABASE_URL` y el marco lo detectará automáticamente. Las bases de datos compatibles incluyen SQLite, Postgres (Neon, Supabase, Plain), Turso (libSQL) y Cloudflare D1. Todo SQL es independiente del dialecto a través de Drizzle ORM: el mismo código funciona en todas partes.
+
+### ¿Dónde puedo implementar? {#where-can-i-deploy}
+
+En cualquier lugar. El servidor se ejecuta en Nitro, que se compila en cualquier objetivo de implementación: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda y Bun. También puede utilizar el alojamiento de Builder.io para implementaciones administradas. Ver el [Deployment guide](/docs/deployment).
+
+## Arquitectura {#architecture}
+
+### ¿Por qué SSE más encuestas en lugar de WebSocket? {#why-polling-not-websockets}
+
+SSE proporciona a las escrituras del mismo proceso una ruta inmediata al navegador, y una encuesta ligera de contador de versiones sigue siendo la alternativa porque funciona en todos los entornos de implementación, incluidos los sin servidor y los perimetrales, donde es posible que los sockets persistentes no estén disponibles. Ver [Key Concepts — Live sync](/docs/key-concepts#polling-sync).
+
+```an-diagram title="SSE first, polling fallback" summary="Same-process writes stream instantly; a version-counter poll keeps serverless, edge, and cross-process writes convergent."
+{
+  "html": "<div class=\"diagram-transport\"><div class=\"diagram-box\" data-rough>DB write</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">SSE<br><small class=\"diagram-muted\">/_agent-native/events &middot; instant</small></div><div class=\"diagram-node\">Poll<br><small class=\"diagram-muted\">/_agent-native/poll &middot; universal fallback</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Browser refetch</div></div>",
+  "css": ".diagram-transport{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-transport .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-transport .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+### ¿Por qué el UI no puede llamar directamente a un LLM? {#why-no-inline-llm-calls}
+
+La IA no es determinista, por lo que necesita un flujo de conversación para brindar retroalimentación e iteración (no botones de un solo uso) y el agente ya tiene su código base, instrucciones, skills y el historial del que carece una llamada en línea. Dirigir todo a través del agente también es lo que permite que la aplicación se controle desde Slack, Telegram u otro agente. Ver [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge).
+
+### ¿Por qué es esto un marco y no una biblioteca? {#why-framework-not-library}
+
+La base de datos compartida, la sincronización en vivo, el sistema actions y el estado de la aplicación solo funcionan porque están conectados desde cero: el UI reacciona instantáneamente a los cambios del agente, los agentes se comunican y el agente comprende lo que el usuario está mirando. Una biblioteca te da piezas; esto es una arquitectura. Ver [Key Concepts](/docs/key-concepts).

package/docs/content/locales/es-ES/file-uploads.md

@@ -0,0 +1,122 @@
+---
+title: "Carga de archivos"
+description: "Configurar el almacenamiento de carga de archivos: respaldo SQL para desarrolladores, Builder.io o proveedores personalizados para producción."
+---
+
+# Carga de archivos
+
+El marco proporciona una abstracción de carga de archivos que enruta las cargas a través de un proveedor configurable. Las plantillas llaman a `uploadFile()` y obtienen un URL: el backend de almacenamiento se puede intercambiar sin cambiar el código de la aplicación.
+
+## Cómo funciona {#how-it-works}
+
+Las solicitudes de carga van a `POST /_agent-native/file-upload`, que las envía al proveedor activo. Puedes comprobar qué proveedor está configurado en `GET /_agent-native/file-upload/status`.
+
+El orden de resolución del proveedor es:
+
+1. **Proveedores registrados por el usuario**: proveedores personalizados registrados a través de `registerFileUploadProvider()`
+2. **Proveedor Builder.io**: integrado, se activa automáticamente cuando se conecta Builder.io
+3. **SQL reserva**: almacena archivos como base64 en la base de datos (está bien para desarrollo, no para producción)
+
+```an-diagram title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. The SQL fallback always exists so uploads work with zero setup."
+{
+  "html": "<div class=\"diagram-upload\"><div class=\"diagram-box\" data-rough>uploadFile()<br><small class=\"diagram-muted\">POST /_agent-native/file-upload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-step\"><span class=\"diagram-pill accent\">1</span><div class=\"diagram-node\">User-registered<br><small class=\"diagram-muted\">registerFileUploadProvider() — S3, R2, GCS…</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><div class=\"diagram-node\">Builder.io<br><small class=\"diagram-muted\">auto when connected — CDN-served</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill warn\">3</span><div class=\"diagram-node\">SQL fallback<br><small class=\"diagram-muted\">base64 in DB — dev only</small></div></div></div></div>",
+  "css": ".diagram-upload{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-upload .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-upload .diagram-step{display:flex;align-items:center;gap:8px}.diagram-upload .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The upload endpoint" method="POST" path="/_agent-native/file-upload"
+{
+  "method": "POST",
+  "path": "/_agent-native/file-upload",
+  "summary": "Upload a file through the active provider and get back a public URL.",
+  "description": "Dispatches to the first configured provider in resolution order. Check the active provider at `GET /_agent-native/file-upload/status`.",
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "{ url, id?, provider } — the public URL and which provider handled it." }
+  ]
+}
+```
+
+## Predeterminado: reserva de SQL {#sql-fallback}
+
+Cuando no se configura ningún proveedor, los archivos se almacenan como datos base64 en la base de datos SQL a través del sistema de recursos. Esto funciona de inmediato para el desarrollo local, pero no se recomienda para producción: los archivos grandes sobrecargan la base de datos y no hay CDN.
+
+Se registra una advertencia única cuando se utiliza el respaldo.
+
+## Alojamiento Builder.io {#builder-hosting}
+
+Cuando su aplicación está conectada a Builder.io, las cargas de archivos se enrutan automáticamente al alojamiento de activos de Builder. Los archivos se sirven desde un CDN sin necesidad de configuración. Esta es la configuración de producción recomendada.
+
+## Proveedores personalizados {#custom-providers}
+
+Registre un proveedor personalizado en un complemento de servidor para usar cualquier backend de almacenamiento (S3, Cloudflare R2, GCS, etc.):
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## Subir API {#upload-api}
+
+La interfaz `FileUploadProvider`:
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+Utilice `uploadFile()` de `@agent-native/core/file-upload` en actions o código de servidor:
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL fallback yourself, or skip
+}
+```

package/docs/content/locales/es-ES/frames.md

@@ -0,0 +1,153 @@
+---
+title: "Marcos"
+description: "El marco de desarrollo local, el panel de agente integrado y el marco de la nube: las formas en que un agente de IA se ejecuta junto con su aplicación."
+---
+
+# Marcos
+
+Cada aplicación nativa del agente se ejecuta con un agente de IA junto a la aplicación UI. Un **marco** es
+el contenedor que aloja ambos: muestra su aplicación y le da al agente un lugar para
+chatear, ejecutar y (en desarrollo) editar código. Hay tres fotogramas que comparten un tiempo de ejecución:
+
+- **Panel de agente integrado**: se envía dentro de cada aplicación desde `@agent-native/core`.
+  Esta es la barra lateral que muestra su aplicación, en desarrollo y en producción.
+- **Marco de desarrollo local**: un contenedor delgado que carga la aplicación en ejecución en un iframe
+  y agrega el mismo panel de agente más un terminal CLI integrado al lado. Usado
+  para el desarrollo local de plantillas en este repositorio.
+- **Builder.io marco de nube**: un marco alojado y administrado con colaboración,
+  edición visual y ejecuciones paralelas del agente.
+
+El código de tu aplicación es idéntico independientemente del marco que lo aloje. El agente habla
+a su aplicación a través del mismo actions y estado de la aplicación en todos los casos.
+
+```an-diagram title="Three frames, one runtime" summary="Your app and the agent panel are the same in every frame; only the wrapper around them changes."
+{
+  "html": "<div class=\"diagram-frames\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Embedded panel</span><small class=\"diagram-muted\">ships in every app · dev + prod</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Local dev frame</span><small class=\"diagram-muted\">app in an iframe + panel + CLI terminal</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Builder.io cloud frame</span><small class=\"diagram-muted\">hosted: collaboration · visual edit · parallel runs</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Same runtime<br><small class=\"diagram-muted\">your app · actions · application state</small></div></div>",
+  "css": ".diagram-frames{display:flex;flex-direction:column;gap:10px;align-items:stretch}.diagram-frames .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-frames .diagram-arrow{font-size:22px;line-height:1;align-self:center}"
+}
+```
+
+## Panel de agente integrado {#embedded-agent}
+
+El panel integrado es la barra lateral del agente que representa su aplicación. Se envía con
+`@agent-native/core`: no hay ningún paquete independiente para instalar, y es el mismo
+componente en desarrollo y producción
+
+- Exportado como `AgentPanel` desde `@agent-native/core/client`, con un
+  variante de producción exclusiva `ProductionAgentPanel`.
+- Proporciona la superficie completa de chat/CLI/espacio de trabajo, por lo que la entrada del agente permanece encendida
+  la pila de compositores compartida utilizada en el resto del marco.
+- Lee `application_state.navigation` en cada turno, por lo que ya sabe cuál
+  vista en la que te encuentras y qué está seleccionado; no tienes que volver a explicar "esto".
+
+### Modos de herramienta Aplicación vs Código {#tool-modes}
+
+El panel se ejecuta en uno de dos modos de herramienta:
+
+- **Modo de aplicación**: el agente solo tiene las herramientas propias de su aplicación: el actions usted
+  definido con `defineAction`, además de navegación y contexto. Sin sistema de archivos o
+  acceso al shell. Esto es lo que obtienen los usuarios finales.
+- **Modo de código**: agrega las herramientas de codificación compartidas (`bash`, `read`, `edit`, `write`)
+  y acceso a la base de datos además de las herramientas de la aplicación, para que el agente pueda cambiar las funciones de la aplicación
+  fuente propia. Las solicitudes de código están cerradas: cuando un mensaje requiere código
+  (`type: "code"`) y no hay ningún marco con capacidad de código conectado, el panel muestra un
+  diálogo que explica que los cambios de código necesitan Agent Native Desktop o Builder;
+  cuando se conecta una trama, la solicitud se dirige a ella y a un agente de código
+  se muestra mientras funciona (`useSendToAgentChat`). Para lo canónico
+  lista de herramientas de codificación y contratos UI compartidos, consulte
+  [Agent-Native Code UI](/docs/code-agents-ui).
+
+```an-diagram title="Code-request gating" summary="A code-typed message needs a code-capable frame. With one connected, the request routes there; without one, the panel explains code changes need Desktop or Builder."
+{
+  "html": "<div class=\"diagram-gate\"><div class=\"diagram-node\" data-rough>message<br><small class=\"diagram-muted\">type: \\\"code\\\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>code-capable frame connected?</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">yes &rarr; route to frame, show code-agent indicator</div><div class=\"diagram-pill warn\">no &rarr; dialog: needs Desktop or Builder</div></div></div>",
+  "css": ".diagram-gate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-gate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-gate .diagram-arrow{font-size:22px;line-height:1}.diagram-gate .center{text-align:center}"
+}
+```
+
+El "modo de código" es el conmutador de capacidad del agente, distinto del modo de desarrollo del entorno
+(`NODE_ENV` / Vite). El enlace del cliente es `useCodeMode()`. (Ver
+[Compatibility notes](#compatibility) para los alias de retrocompatibilidad.)
+
+En el marco de desarrollo local, el engranaje de configuración alterna entre estos modos. Cambiando
+El modo Código desactivado oculta la barra lateral del marco y muestra el agente dentro de la aplicación
+barra lateral dentro del iframe, para que puedas obtener una vista previa exactamente de lo que ven los usuarios finales.
+
+## Terminal integrado y conmutación CLI {#cli-terminal}
+
+En desarrollo, el panel incluye un terminal integrado (`AgentTerminal`, también
+de `@agent-native/core/client`) respaldado por un servidor PTY. Puedes ejecutar un verdadero
+codificar CLI justo al lado de la aplicación y alternar entre ellas; el terminal se reinicia
+con el CLI seleccionado.
+
+Los CLI compatibles provienen del registro principal CLI
+(`packages/core/src/terminal/cli-registry.ts`). Sólo estos comandos están permitidos
+para generar: el servidor PTY valida el comando solicitado en el registro
+Lista de permitidos para evitar la inyección:
+
+| CLI            | Comando    | Instalar paquete            |
+| -------------- | ---------- | --------------------------- |
+| Código Claude  | `claude`   | `@anthropic-ai/claude-code` |
+| Builder.io     | `builder`  | (integrado)                 |
+| Codex          | `codex`    | `@openai/codex`             |
+| Géminis CLI    | `gemini`   | `@google/gemini-cli`        |
+| Código abierto | `opencode` | `opencode-ai`               |
+
+Si el CLI seleccionado no se encuentra en `PATH`, el terminal vuelve a ejecutarlo
+a través de `npx --yes <install-package>@latest` (donde existe un paquete de instalación). El
+el comando predeterminado es `claude`. Cambie CLI desde la configuración del panel del agente en cualquier
+tiempo.
+
+## Marco de nube Builder.io {#cloud-frame}
+
+[Builder.io](https://www.builder.io) proporciona un marco administrado que aloja el
+misma aplicación y mismo panel de agente, en la nube:
+
+- Colaboración en tiempo real: varios usuarios pueden mirar e interactuar a la vez.
+- Edición visual, roles y permisos.
+- Ejecución paralela del agente para una iteración más rápida.
+- Bueno para uso en equipo, donde todos comparten un entorno alojado.
+
+Las solicitudes de código del panel integrado se dirigen al marco Builder de la misma manera
+se dirigen al marco de desarrollo local, por lo que el comportamiento dev-vs-prod anterior es
+consistente en ambos.
+
+## API en tiempo de ejecución {#runtime-apis}
+
+Estos se envían con `@agent-native/core` y son los que usa su aplicación para hablar con el
+agente, independientemente del marco que lo aloje:
+
+1. **Enviar un mensaje**: `sendToAgentChat()` envía un mensaje al agente. El
+   El gancho `useSendToAgentChat()` lo envuelve con la activación de solicitud de código descrita
+   arriba y devuelve un elemento `codeRequiredDialog` para renderizar. Ver
+   [Drop-in Agent](/docs/drop-in-agent) para uso completo y opciones.
+2. **Estado de generación**: `useAgentChatGenerating()` realiza un seguimiento cuando el agente está
+   en ejecución, por lo que UI puede mostrar el progreso sin sondear al agente directamente.
+3. **Sincronización de sondeo**: la sincronización respaldada por la base de datos mantiene actualizados los cachés de UI cuando el agente
+   cambia los datos o el estado de la aplicación.
+4. **Sistema de acción**: `pnpm action <name>` envía al mismo invocable
+   actions el agente invoca como herramienta, por lo que cualquier cosa que el agente pueda hacer, tú puedes hacerlo
+   guión.
+
+## Ejecutándolo {#running}
+
+El panel de agente integrado es parte de cada aplicación: cree una plantilla y ya está
+ya está ahí:
+
+```bash
+npx @agent-native/core@latest create my-app --template mail --standalone
+cd my-app
+pnpm dev
+```
+
+El marco de desarrollo local (el paquete privado `@agent-native/frame` en el repositorio del marco) es un paquete de herramientas interno que no está publicado en npm. Carga el servidor de desarrollo de la aplicación activa en un iframe y monta el panel integrado junto a él, seleccionando la aplicación a través del parámetro de consulta `app`. El terminal CLI integrado requiere el escritorio Agent Native, que proporciona el código local y el acceso PTY que necesita el terminal; sin él, el panel muestra la superficie de chat y le solicita que abra el Escritorio para usar el CLI.
+
+## Notas de compatibilidad {#compatibility}
+
+El concepto de "modo de código" se denominaba anteriormente "modo de desarrollo", por lo que se han realizado algunas retrocompatibilidades
+los nombres persisten. Puedes ignorarlos a menos que mantengas una integración anterior
+código:
+
+- La var de entorno subyacente `AGENT_MODE`, la `/_agent-native/agent-chat/mode`
+  punto final (cuya clave de carga útil sigue siendo `devMode`) y `agent-chat.mode`
+  La clave de configuración no se modifica.
+- `useDevMode()` permanece como un alias obsoleto para `useCodeMode()`.

package/docs/content/locales/es-ES/getting-started.md

@@ -0,0 +1,199 @@
+---
+title: "Cómo empezar"
+description: "Cree una aplicación de agente, comprenda las instrucciones skills y actions y luego observe cómo el agente ejecuta su primera acción."
+---
+
+# Cómo empezar
+
+Las aplicaciones Agent-Native brindan a un agente de IA y a su UI el mismo actions, datos y
+estado. Un agente básico se hace a partir de instrucciones que lo guían, skills que enseñan
+comportamiento repetible y actions que le permiten hacer un trabajo real.
+
+**¿Quieres una aplicación completa para empezar?** Clona una de nuestras plantillas enriquecidas:
+[Chat](/docs/template-chat), [Mail](/docs/template-mail),
+[Calendar](/docs/template-calendar), [Content](/docs/template-content),
+[Analytics](/docs/template-analytics) y [many more](/docs/cloneable-saas) —
+cada una de ellas es una aplicación con todas las funciones que puedes personalizar.
+
+¿Construir desde cero? La única opción desde el principio es si quieres un UI —
+todo lo posterior (escribir instrucciones, agregar skills, definir actions, ejecutar
+el agente) es el mismo en ambos sentidos.
+
+```an-file-tree title="A basic Agent-Native agent"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, rules, tone, and the map of what the agent can do" },
+    { "path": ".agents/skills/customer-research/SKILL.md", "note": "a reusable playbook the agent loads when the task matches" },
+    { "path": "actions/summarize-week.ts", "note": "typed code the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks can run" }
+  ]
+}
+```
+
+Esto es cierto ya sea que comiences con un chat UI, un agente sin cabeza o una aplicación completa.
+El UI cambia la superficie; instrucciones, skills y actions le dan al agente su
+orientación y comportamiento.
+
+## 1. Crea tu aplicación
+
+Necesitarás [Node.js 22+](https://nodejs.org) y [pnpm](https://pnpm.io).
+
+Ejecute `create` sin indicadores y le preguntará cómo desea comenzar (una plantilla completa,
+Chat o Headless) antes que nada:
+
+```bash
+npx @agent-native/core@latest create my-app
+```
+
+O pase una marca para omitir el mensaje:
+
+**¿Quieres un UI?** Comience desde la plantilla de Chat. Obtienes un agente de trabajo más un
+Chat personalizable UI, y cada acción que agregas se muestra automáticamente en él:
+
+```bash
+npx @agent-native/core@latest create my-app --template chat
+```
+
+**¿Solo la primitiva sin cabeza?** Comience sin cabeza: el mismo actions y agente
+bucle, sin shell UI:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+Luego instálelo desde la carpeta que creó:
+
+```bash
+cd my-agent # or my-app if you chose the Chat template
+pnpm install
+```
+
+A partir de ahora, los dos son idénticos.
+
+## 2. Añadir una acción
+
+Una acción es una operación que su agente (y su UI) pueden realizar. Ambos andamios
+envío con este ejemplo:
+
+```an-annotated-code title="Tu primera action"
+{
+  "filename": "actions/hello.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"Saluda desde el agente local.\",\n  schema: z.object({\n    name: z.string().default(\"world\"),\n  }),\n  http: { method: \"GET\" },\n  readOnly: true,\n  run: async ({ name }) => {\n    return { message: `Hello, ${name}!` };\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "Descripción de herramienta", "note": "El agente lee `description` para decidir cuándo llamarla como herramienta." },
+    { "lines": "6-8", "label": "Contrato tipado", "note": "Un `schema` de zod valida entradas desde cada superficie: agente, UI, HTTP, MCP y A2A." },
+    { "lines": "9", "label": "HTTP verb", "note": "Opt this action into an auto-mounted HTTP endpoint." },
+    { "lines": "10", "label": "Read-only", "note": "`readOnly` marks the action as safe to call without approval and cacheable for queries." },
+    { "lines": "11-13", "label": "One implementation", "note": "The `run` body is the single source of truth that every surface executes." }
+  ]
+}
+```
+
+Reemplace `hello` con la primera operación real en su dominio. Lo defines una vez;
+todas las superficies lo recogen.
+
+Utilice `AGENTS.md` como guía que debe aplicarse en cada giro. Usa una habilidad cuando
+el agente necesita un flujo de trabajo o un procedimiento de dominio reutilizable. Utilice una acción cuando
+el agente necesita una forma escrita y comprobable de leer datos, escribir datos, llamar a un API o
+realizar una aprobación.
+
+## 3. Ejecútelo
+
+Llame a la acción directamente:
+
+```bash
+pnpm action hello --name Steve
+```
+
+O pídale al agente que lo llame por usted:
+
+```bash
+pnpm agent "Call the hello action for Steve and explain what happened."
+```
+
+Si comenzó desde la plantilla de Chat, ejecute la aplicación y use el mismo agente en
+navegador: ya puede llamar a cada acción que definas:
+
+```bash
+pnpm dev
+```
+
+Ahora se puede acceder a esa acción desde el chat UI, CLI, HTTP, MCP, A2A,
+trabajos programados y webhooks. Defina una vez y llame desde cualquier lugar.
+
+```an-diagram title="One action, every surface" summary="A single defineAction file fans out to every consumer with no extra wiring."
+{
+  "html": "<div class=\"diagram-fan\"><div class=\"diagram-box\" data-rough>defineAction</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-surfaces\"><span class=\"diagram-pill\">Chat UI</span><span class=\"diagram-pill\">CLI</span><span class=\"diagram-pill\">HTTP</span><span class=\"diagram-pill\">MCP</span><span class=\"diagram-pill\">A2A</span><span class=\"diagram-pill\">Scheduled jobs</span><span class=\"diagram-pill\">Webhooks</span></div></div>",
+  "css": ".diagram-fan{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fan .diagram-surfaces{display:flex;flex-wrap:wrap;gap:8px;max-width:420px}.diagram-fan .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## El estado está integrado
+
+Sin cabeza no significa apátrida. Actions, sesiones, estado de la aplicación, subprocesos,
+el historial de ejecución y las credenciales se encuentran en SQL. A nivel local es SQLite en
+`data/app.db`; en producción se configura `DATABASE_URL`. Ver
+[Deployment](/docs/deployment).
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Headless is still a real app.** The app-agent loop persists sessions, threads, runs, settings, and credentials in SQL — it is not a stateless prompt. You can add a UI later without touching your actions or state."
+}
+```
+
+## Personaliza el UI
+
+Si comenzó desde la plantilla de Chat, el UI es suyo para editarlo. El chat en sí
+es una pequeña ruta construida sobre el componente `<AgentChatSurface>`:
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-full" />;
+}
+```
+
+- **`app/routes/_index.tsx`**: la página de chat. Cambiar las sugerencias, vacía
+  estado y diseño.
+- **`app/root.tsx`**: el shell de la aplicación. Añade tus propias rutas y pantallas alrededor del
+  agente.
+- Suelte el agente en cualquier pantalla con `<AgentSidebar>`, trabaje manualmente desde un
+  botón con `sendToAgentChat()`, o ejecuta una acción directamente con
+  `useActionMutation()`.
+
+Consulte [Drop-in Agent](/docs/drop-in-agent) para conocer el conjunto completo de componentes y
+[Native Chat UI](/docs/native-chat-ui) para representar los resultados de la acción como tablas,
+gráficos y tarjetas mecanografiadas en lugar de texto sin formato.
+
+**¿Empezaste sin cabeza y quieres un UI más tarde?** La plantilla de chat _es_ la rampa de acceso a UI —
+su capa `app/` (React Router + Vite) es exactamente lo que el andamio sin cabeza
+se va. El movimiento más limpio es comenzar (o reestructurar) desde el Chat
+plantilla; su estado `actions/`, agente y SQL se mantienen sin cambios. Ver
+[Agent Surfaces](/docs/agent-surfaces) para cada superficie intermedia.
+
+## Estructura del proyecto
+
+```text
+my-app/
+  actions/         # Agent-callable actions
+  app/             # React frontend (UI templates only; omitted when headless)
+  server/          # Nitro API server (routes, plugins)
+  AGENTS.md        # Always-on agent instructions
+  .agents/         # Skills the agent can pull in when relevant
+  data/app.db      # Local SQLite state when DATABASE_URL is unset
+```
+
+## Adónde ir a continuación
+
+- **[Key Concepts](/docs/key-concepts)**: la arquitectura principal: SQL, actions,
+  sincronización y reconocimiento del contexto.
+- **[Actions](/docs/actions)**: la acción completa API: esquemas, HTTP, autenticación y
+  aprobación.
+- **[Agent Surfaces](/docs/agent-surfaces)**: sin cabeza, chat, sidecar integrado,
+  y aplicación completa.
+- **[Drop-in Agent](/docs/drop-in-agent)**: agrega el chat del agente a cualquier aplicación React.
+- **[Deployment](/docs/deployment)**: coloca tu aplicación en tu propio dominio.
+- **[FAQ](/docs/faq)**: preguntas sobre configuración y productos.