@agent-native/core 0.87.0 → 0.90.1

package/corpus/core/docs/content/locales/es-ES/agent-native-toolkit.mdx

@@ -0,0 +1,103 @@
+---
+title: "Toolkit"
+description: "Reusable app-building primitives that sit between @agent-native/core and template apps."
+---
+
+# Toolkit
+
+`@agent-native/core` owns the foundational runtime: actions, app state, auth,
+SQL, server plugins, agent chat, sharing access checks, and collaboration
+transport. `@agent-native/toolkit` owns reusable app-building pieces that sit on
+top of that runtime: UI primitives, app-local adapters, shell helpers, sharing
+badges, and collaboration UI.
+
+Apps should compose those pieces through local adapters. That keeps app UI easy
+to customize without copying Toolkit implementation code.
+
+<WireframeBlock id="doc-block-toolkit-layering">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:520px;box-sizing:border-box;padding:48px 36px;display:flex;align-items:center;justify-content:center'><div style='width:min(900px,100%);display:grid;grid-template-columns:1fr;gap:18px'><div class='wf-card' style='padding:22px 24px'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>App</strong><p class='wf-muted' style='margin:6px 0 0'>Domain routes, actions, local UI adapters, product-specific views</p></div><span class='wf-pill'>@/components/ui/button</span></div></div><div class='wf-card' style='padding:22px 24px;border-color:hsl(var(--primary))'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>Toolkit</strong><p class='wf-muted' style='margin:6px 0 0'>Reusable primitives, collab UI, sharing UI, app shell hooks</p></div><span class='wf-pill'>ToolkitProvider</span></div><div style='display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin-top:16px'><span class='wf-pill'>UI</span><span class='wf-pill'>Collab UI</span><span class='wf-pill'>Sharing UI</span><span class='wf-pill'>Shell</span></div></div><div class='wf-card' style='padding:22px 24px'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>Core</strong><p class='wf-muted' style='margin:6px 0 0'>Actions, SQL, auth, sharing runtime, Yjs transport, app state</p></div><span class='wf-pill'>@agent-native/core</span></div></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## What Ships Today {#what-ships-today}
+
+- **UI primitives**: shadcn-style components under
+  `@agent-native/toolkit/ui/*`.
+- **App adapters**: template-local wrappers such as
+  `@/components/ui/button` that re-export Toolkit primitives until an app wants
+  to customize them.
+- **ToolkitProvider**: an override layer that lets reusable Toolkit UI use an
+  app's local primitives, starting with `Button`.
+- **Collaboration UI**: presence avatars, live cursors, remote selection rings,
+  recent edit highlights, and agent presence chips under
+  `@agent-native/toolkit/collab-ui`.
+- **Sharing UI**: the reusable `VisibilityBadge` under
+  `@agent-native/toolkit/sharing`.
+- **Shell and hooks**: app-shell header actions plus shared hooks such as
+  `useIsMobile` and `useToast`.
+
+## Compatibility {#compatibility}
+
+Existing imports from `@agent-native/core/client` keep working. Core now exposes
+thin re-export shims for Toolkit-owned visual pieces while keeping runtime
+behavior in core.
+
+Those core shims are temporary migration support, not the long-term dependency
+direction. The next major can remove them; after that, reusable app-building
+packages should import Toolkit directly, and behaviorful Toolkit kits may compose
+core runtime APIs as peer/runtime dependencies instead of pushing more UI back
+into core.
+
+Extract future behaviorful kits one at a time before broadening the split.
+Sharing is the first candidate to validate that model because it exercises
+access checks, action-backed data, and share-link UI together.
+
+That means this keeps working:
+
+```tsx
+import { PresenceBar, VisibilityBadge } from "@agent-native/core/client";
+```
+
+New reusable app code should prefer Toolkit or app-local adapters:
+
+```tsx
+import { PresenceBar } from "@agent-native/toolkit/collab-ui";
+import { Button } from "@/components/ui/button";
+```
+
+## Boundary {#boundary}
+
+Move code into Toolkit when it is reusable app-building UI or a pure UI contract.
+Keep code in core when it owns access control, SQL, actions, request context,
+Yjs transport, auth, or other runtime guarantees.
+
+Good Toolkit candidates:
+
+- Components that render the same interaction across apps.
+- Display-only helpers and structural prop types.
+- Base components that receive data and callbacks from an app or core wrapper.
+- App-shell hooks and adapters that do not own domain data.
+
+Keep app-local:
+
+- Domain-specific workflows.
+- Resource-specific mutations and routes.
+- Custom visual systems an app intentionally owns.
+
+Keep core-owned:
+
+- Sharing actions and access checks.
+- Collaboration storage, awareness transport, and Yjs document sync.
+- Auth, sessions, app state, SQL, and server plugins.
+
+## Pages {#pages}
+
+- [UI Primitives](/docs/toolkit-ui)
+- [App Adapters](/docs/toolkit-app-adapters)
+- [Collaboration UI](/docs/toolkit-collaboration-ui)
+- [Sharing UI](/docs/toolkit-sharing-ui)
+- [Shell & Hooks](/docs/toolkit-shell-hooks)

package/corpus/core/docs/content/locales/es-ES/cloneable-saas.mdx

@@ -1,19 +1,19 @@
 ---
-title: "Plantillas"
+title: "Apps"
 description: "Bifurque un producto SaaS que funcione y hágalo suyo, incluido el agente."
 ---
 
-# Plantillas
+# Apps
 
-¿Quiere enviar su propia herramienta de análisis basada en IA? ¿Cliente de correo? ¿Constructor de formularios? Elija una plantilla y tendrá un SaaS funcional en minutos: el agente, la base de datos, la autenticación y el proceso de implementación ya están conectados.
+¿Quiere enviar su propia herramienta de análisis basada en IA? ¿Cliente de correo? ¿Constructor de formularios? Elija una app de ejemplo y tendrá un SaaS funcional en minutos: el agente, la base de datos, la autenticación y el proceso de implementación ya están conectados.
 
-La mayoría de las "plantillas" le brindan un marco en blanco y una larga lista TODO. El agente nativo cambia eso. Cada uno es un **producto completo de nivel SaaS**: ya se puede ejecutar desde el primer día, ya se puede enviar y es completamente suyo para personalizarlo, personalizarlo e implementarlo. Piensa en ellos como SaaS clonable, no como kits de inicio: estás entregando un producto terminado, no mirando un texto estándar.
+La mayoría de las plantillas iniciales le brindan un marco en blanco y una larga lista TODO. El agente nativo cambia eso. Cada app de ejemplo es un **producto completo de nivel SaaS**: ya se puede ejecutar desde el primer día, ya se puede enviar y es completamente suyo para personalizarlo, darle marca e implementarlo. Piensa en ellas como SaaS clonable, no como kits de inicio: estás entregando un producto terminado, no mirando un texto estándar.
 
-## Plantillas disponibles {#catalog}
+## Apps de ejemplo {#catalog}
 
 Cada una es una aplicación real que puedes usar hoy y la plataforma de lanzamiento para tu propia versión.
 
-| Plantilla                                 | Qué es                                                                                                                                           |
+| App                                       | Qué es                                                                                                                                           |
 | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
 | [**Chat**](/docs/template-chat)           | Aplicación mínima de chat primero con hilos duraderos, actions, autenticación y una ruta limpia hacia UI personalizado o su propio backend.      |
 | [**Mail**](/docs/template-mail)           | Un sobrehumano nativo del agente. Bandeja de entrada, etiquetas, clasificación por IA, teclado primero, borradores y envíos a través del agente. |
@@ -35,16 +35,16 @@ Vea el catálogo completo en [Apps](/apps) o vaya directamente a uno; por ejempl
 
 ## Lo que obtienes de la caja {#what-you-get}
 
-Cada plantilla se envía con las piezas que normalmente tardan meses en construirse:
+Cada app de ejemplo se envía con las piezas que normalmente tardan meses en construirse:
 
 - **Un agente en funcionamiento**: ya conectado a la aplicación, ya capaz de tomar actions de sus datos, ya consciente del contexto sobre lo que está viendo. Consulte [Messaging the agent](/docs/messaging) para saber cómo funciona.
 - **Auth**: inicio de sesión, sesiones, organizaciones, aislamiento multiinquilino. Ya hecho.
-- **Una base de datos**: cada plantilla tiene su esquema, consultas y migraciones listas para funcionar. Traiga su propia base de datos SQL (Postgres, SQLite, Turso, D1): el marco se adapta.
+- **Una base de datos**: cada app de ejemplo tiene su esquema, consultas y migraciones listas para funcionar. Traiga su propia base de datos SQL (Postgres, SQLite, Turso, D1): el marco se adapta.
 - **Un UI** en tiempo real: la pantalla permanece sincronizada con lo que hace el agente. Haga clic en "redactar un correo electrónico" en el chat y observe cómo el borrador aparece en su bandeja de entrada inmediatamente.
 - **Listo para implementar**: envíelo a Netlify, Vercel, Cloudflare, AWS o cualquier otro lugar que ejecute Node. Sin dependencia del proveedor.
 - **Ganchos de marca**: el nombre, los colores, el logotipo y el texto son fáciles de cambiar.
 
-Esta no es una afirmación teórica. El autor del marco ejecuta su bandeja de entrada real en la plantilla Correo, su calendario real en la plantilla Calendario y sus análisis reales en la plantilla Análisis. Las plantillas son un software de uso diario.
+Esta no es una afirmación teórica. El autor del marco ejecuta su bandeja de entrada real en la app Mail, su calendario real en la app Calendar y sus análisis reales en la app Analytics. Estas apps son software de uso diario.
 
 ## Qué haces {#what-you-do}
 
@@ -56,7 +56,7 @@ El camino desde "Quiero mi propio SaaS" hasta "Tengo mi propio SaaS" es corto:
 <div class="diagram-fork">
   <div class="diagram-card">
     <span class="diagram-pill">1</span><strong>Pick</strong
-    ><small class="diagram-muted">a complete template</small>
+    ><small class="diagram-muted">una app completa</small>
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card">
@@ -98,8 +98,8 @@ El camino desde "Quiero mi propio SaaS" hasta "Tengo mi propio SaaS" es corto:
 
 </Diagram>
 
-1. **Elija una plantilla.** Utilice el selector CLI o explore los documentos y elija una para comenzar.
-2. **Marca.** Cambia el nombre, los colores, el logotipo y el texto. La mayoría de las plantillas exponen esto en un único archivo de configuración.
+1. **Elija una app de ejemplo.** Utilice el selector CLI o explore los documentos y elija una para comenzar.
+2. **Marca.** Cambia el nombre, los colores, el logotipo y el texto. La mayoría de las apps de ejemplo exponen esto en un único archivo de configuración.
 3. **Personalízalo.** Pídele al agente que agregue la columna que necesitas, cambia la forma en que se agrupa la bandeja de entrada, conéctate a tu API interno, agrega una nueva vista. El agente edita el código; revisas la diferencia.
 4. **Envíelo.** Ejecute el comando de implementación. Ahora tienes tu propio SaaS de producción en tu propio dominio.
 
@@ -159,7 +159,7 @@ El resultado: Claude: flexibilidad a nivel de código para cada usuario, con una
 
 ## ¿No quieres bifurcar? {#hosted}
 
-No es necesario. Cada plantilla también está disponible como una aplicación alojada en `agent-native.com`: `mail.agent-native.com`, `calendar.agent-native.com`, etc. Utilice la versión alojada de forma gratuita o de pago; bifurca solo cuando quieras cambiar algo que la versión alojada no expone.
+No es necesario. Cada app de ejemplo también está disponible como una aplicación alojada en `agent-native.com`: `mail.agent-native.com`, `calendar.agent-native.com`, etc. Utilice la versión alojada de forma gratuita o de pago; bifurca solo cuando quieras cambiar algo que la versión alojada no expone.
 
 ## Pruébalo con una habilidad {#try-with-a-skill}
 
@@ -168,10 +168,10 @@ No es necesario. Cada plantilla también está disponible como una aplicación a
 ## Aprovechando esto
 
 - [**Getting Started**](/docs/getting-started): crea una app chat-first, añade una action, renderiza un resultado estructurado y crece hacia una página
-- [**Messaging the agent**](/docs/messaging): cómo los usuarios (y usted) hablan con el agente que se envía con cada plantilla
-- [**Multi-App Workspace**](/docs/multi-app-workspace): agrupa varias plantillas en un espacio de trabajo que comparte autenticación, marca y agente
-- [**Dispatch**](/docs/template-dispatch): la plantilla del plano de control del espacio de trabajo
-- [**Creating Templates**](/docs/creating-templates): crea y publica tu propia plantilla
+- [**Messaging the agent**](/docs/messaging): cómo los usuarios (y usted) hablan con el agente que se envía con cada app
+- [**Multi-App Workspace**](/docs/multi-app-workspace): agrupa varias apps en un espacio de trabajo que comparte autenticación, marca y agente
+- [**Dispatch**](/docs/template-dispatch): la app del plano de control del espacio de trabajo
+- [**Creating Templates**](/docs/creating-templates): crea y publica tu propia plantilla de app
 
 ### Para desarrolladores {#dev-details}
 
@@ -181,10 +181,10 @@ Si está realizando un scaffolding ahora, el comando CLI es:
 npx @agent-native/core@latest create my-platform
 ```
 
-Obtendrás un selector de selección múltiple. Elija una aplicación (independiente) o varias (espacio de trabajo: las aplicaciones comparten autenticación, marca, configuración del agente y base de datos). Cada plantilla seleccionada se estructura en `apps/<name>/` con cada archivo que necesita. Para una automatización sin UI de navegador en lugar de una plantilla UI, use `npx @agent-native/core@latest create my-agent --headless`.
+Obtendrás un selector de selección múltiple. Elija una aplicación (independiente) o varias (espacio de trabajo: las aplicaciones comparten autenticación, marca, configuración del agente y base de datos). Cada app seleccionada se estructura en `apps/<name>/` con cada archivo que necesita. Para una automatización sin UI de navegador en lugar de una UI de app, use `npx @agent-native/core@latest create my-agent --headless`.
 
 Complete `.env` (principalmente `ANTHROPIC_API_KEY` y `DATABASE_URL`), `pnpm install`, `pnpm dev` y funciona. Sin "TODO: implementar inicio de sesión", sin rutas de marcador de posición.
 
 Destinos de implementación: cualquier host compatible con Nitro (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) y cualquier base de datos SQL compatible con Drizzle (SQLite, Postgres, Turso, D1, Supabase, Neon). Para los espacios de trabajo, `npx @agent-native/core@latest deploy` crea todas las aplicaciones a la vez y las envía detrás de un único origen. Ver [Deployment](/docs/deployment).
 
-Para crear y publicar su propia plantilla, consulte [Creating Templates](/docs/creating-templates).
+Para crear y publicar su propia plantilla de app, consulte [Creating Templates](/docs/creating-templates).

package/corpus/core/docs/content/locales/es-ES/components.mdx

@@ -25,7 +25,9 @@ Evite importar componentes UI desde el paquete básico `@agent-native/core`. Usa
 `@agent-native/core/client` o una subruta `@agent-native/core/client/*` enfocada
 para que los paquetes elijan la entrada segura para el navegador.
 
-Use `@agent-native/toolkit` para piezas reutilizables de construcción de aplicaciones que no forman parte del contrato fundacional del runtime: primitivas UI estilo shadcn, hooks compartidos, ayudantes simples de shell de aplicación y otros módulos para componer plantillas. Core conserva reexports de compatibilidad durante la transición, pero el código nuevo de plantillas y aplicaciones debe importar módulos de toolkit directamente:
+Use `@agent-native/toolkit` para piezas reutilizables de construcción de aplicaciones que no forman parte del contrato fundacional del runtime: primitivas UI estilo shadcn, hooks compartidos, ayudantes simples de shell de aplicación y otros módulos para componer plantillas. Core conserva reexports de compatibilidad durante la transición.
+
+Los paquetes reutilizables pueden importar módulos de Toolkit directamente:
 
 ```tsx
 import { Button } from "@agent-native/toolkit/ui/button";
@@ -34,6 +36,13 @@ import { useToast } from "@agent-native/toolkit/hooks/use-toast";
 import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
 ```
 
+Dentro de las apps de plantilla, prefiera adaptadores locales de la app para que los equipos puedan sustituir primitivas una vez y hacer que cada superficie reutilizada de Toolkit use la implementación local:
+
+```tsx
+import { Button } from "@/components/ui/button";
+import { useToast } from "@/hooks/use-toast";
+```
+
 <Diagram id="doc-block-1v79shu" title="Bajar una capa, no fuera del marco." summary={"Cada capa mantiene el mismo tiempo de ejecución (acciones, estado del subproceso y sincronización SQL-backed) al tiempo que le brinda más control sobre Chrome."}>
 
 ```html
@@ -443,7 +452,8 @@ function WorkspaceResources() {
 
 | Área               | APIs                                                                       | Ruta de importación                       |
 | ------------------ | -------------------------------------------------------------------------- | ----------------------------------------- |
-| Compartir          | `<ShareButton>`, `<ShareDialog>`, `<VisibilityBadge>`                      | `@agent-native/core/client/sharing`       |
+| Compartir          | `<ShareButton>`, `<ShareDialog>`                                           | `@agent-native/core/client/sharing`       |
+| Sharing UI         | `<VisibilityBadge>`                                                        | `@agent-native/toolkit/sharing`           |
 | Notificaciones     | `<NotificationsBell>`                                                      | `@agent-native/core/client/notifications` |
 | Progreso           | `<RunsTray>`, ganchos de progreso y tipos                                  | `@agent-native/core/client/progress`      |
 | Incorporación      | `useOnboarding()`, ganchos para panel de incorporación                     | `@agent-native/core/client/onboarding`    |

package/corpus/core/docs/content/locales/es-ES/data-programs.mdx

@@ -0,0 +1,329 @@
+---
+title: "Programas de datos"
+description: "Scripts JS almacenados y escritos por el agente que obtienen, unen y agregan datos en el servidor, se almacenan en caché en SQL y se renderizan mediante paneles de dashboard: el término medio de datos en vivo entre una consulta run-code puntual y una action de proveedor codificada."
+search: "data program emit rows schema providerFetch dashboard panel program source refresh TTL viewer-scoped cache save-data-program run-data-program"
+---
+
+# Programas de datos
+
+Un **programa de datos** es un script JS con nombre, almacenado y escrito por el agente que obtiene, une, filtra o agrega datos — APIs de proveedores mediante `providerFetch` / `providerFetchAll` / `providerSearchAll`, datos de la app mediante `appAction`, o archivos de workspace respaldados por Resources — y llama a `emit(rows, schema)` exactamente una vez con el resultado. El resultado se almacena en caché en SQL y cualquier componente de gráfico/tabla puede renderizarlo, actualizado según una política que usted elija en lugar de en cada vista de página.
+
+Está disponible automáticamente donde sea que [`run-code`](/docs/actions) esté disponible — no hay nada que montar o configurar por app. Si su app ya tiene run-code habilitado, `save-data-program`, `preview-data-program`, `run-data-program`, `list-data-programs`, `get-data-program` y `delete-data-program` ya son actions registradas.
+
+<Diagram id="doc-block-dp-overview" title={"De consulta puntual a panel en vivo"} summary={"Un script run-code se convierte en un programa almacenado en cuanto llama a emit(); cualquier panel de dashboard puede vincularse a él y la política de caché/actualización se hace cargo desde ahí."}>
+
+```html
+<div class="dp-flow">
+  <div class="diagram-card" data-rough>
+    <span class="diagram-pill">run-code script</span
+    ><small class="diagram-muted">providerFetch, joins, aggregation</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel">
+    <span class="diagram-pill accent">emit(rows, schema)</span
+    ><small class="diagram-muted"
+      >save-data-program dry-runs, then persists</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    data_program_runs<br /><small class="diagram-muted"
+      >cached per (program, params, viewer)</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">Panel de dashboard</span
+    ><small class="diagram-muted"><code>source: "program"</code></small>
+  </div>
+</div>
+```
+
+```css
+.dp-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dp-flow .diagram-card,
+.dp-flow .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
+  min-width: 180px;
+}
+.dp-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Por qué existe {#why}
+
+Sin un programa de datos almacenado, "construir una vista en vivo de X" suele terminar en uno de dos malos lugares:
+
+- **Una action codificada por proveedor/tipo de consulta.** Frágil, y no puede anticipar las propiedades personalizadas de cada cliente, un join entre proveedores o un filtro arbitrario que no se le ocurrió incluir.
+- **Volver a ejecutar la misma lógica de obtención/unión desde cero en cada vista de página.** Lento, y vuelve a gastar la misma cuota de API del proveedor cada vez que alguien mira un gráfico.
+
+Un programa de datos es el término medio: escriba la lógica de obtención/unión/agregación una vez como `run-code` ordinario, guárdela, y deje que la caché y la política de actualización decidan con qué frecuencia realmente necesita volver a ejecutarse.
+
+## Cuándo usar uno {#when-to-use-one}
+
+| Situación                                                                                                                                                                                         | Recurra a                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Un rollup estándar ya tiene una action de primera clase (un filtro `hubspot-deals` predefinido, una métrica incorporada)                                                                          | La action existente — no la envuelva en un programa                                    |
+| Una pregunta de chat puntual que nunca volverá a mirar                                                                                                                                            | `run-code` simple o `provider-api-request` — respóndala directamente, no persista nada |
+| Una extensión necesita un widget interactivo pequeño por usuario con su propia UI                                                                                                                 | [Extensiones](/docs/extensions) — un programa de datos no tiene UI propia              |
+| Una cohorte necesita un filtro de propiedad arbitrario, una búsqueda IN sobre valores personalizados, o un join entre dos proveedores, **y** alguien querrá verlo de nuevo con datos actualizados | Un programa de datos                                                                   |
+| Un panel de dashboard debe mostrar ese resultado unido/agregado y actualizarse según la política de caché                                                                                         | Un programa de datos vinculado a un panel `"program"`                                  |
+
+Una comparación con las otras opciones con forma de run-code:
+
+|                                                 | `run-code` puntual                | Action de proveedor codificada                        | Programa de datos                                    |
+| ----------------------------------------------- | --------------------------------- | ----------------------------------------------------- | ---------------------------------------------------- |
+| **Persiste entre llamadas**                     | No                                | N/A (es código fuente)                                | Sí — fila almacenada + caché de resultado            |
+| **El resultado se almacena en caché/actualiza** | No, se vuelve a ejecutar cada vez | Sin caché incorporada                                 | Sí — `refreshMode`/`refreshTtlMs`                    |
+| **Maneja filtros/joins arbitrarios**            | Sí, pero se descarta después      | No — limitado a lo que el esquema de la action expone | Sí — sigue siendo código ordinario                   |
+| **Vinculable a un panel de dashboard**          | No                                | Solo si se construyó una fuente de panel para ello    | Sí — la fuente genérica `"program"`                  |
+| **Requiere un deploy**                          | No                                | Sí (nueva action = cambio de código)                  | No — creado por el agente en tiempo de ejecución     |
+| **Credenciales usadas al momento de lectura**   | Las del llamador                  | Las del llamador                                      | **Las del visor**, resueltas por lectura (vea abajo) |
+
+## Flujo de trabajo de autoría {#authoring-workflow}
+
+1. **Prototipe en el chat primero.** Escriba la lógica de obtención/unión/agregación como un script `run-code` normal y confirme que devuelve las filas esperadas.
+2. **Cámbielo para que llame a `emit(rows, schema?)` exactamente una vez** al final, en lugar de devolver o imprimir el resultado.
+3. **Guárdelo** con `save-data-program`. Esto **ejecuta un dry-run del código con `defaultParams` antes de persistir** y rechaza el guardado con un error estructurado si falla, de modo que un programa roto nunca se almacena. En caso de éxito devuelve `{ programId, rowCount, columns, sampleRows }` — trate eso como prueba de que el programa produce las filas esperadas antes de decirle al usuario que está listo.
+4. **Vincule un panel de dashboard a él**, o llame a `run-data-program` directamente desde su propia ruta de lectura. No hay conexión específica de dashboard integrada en la primitiva misma — la fuente de panel `"program"` de la plantilla de analytics (abajo) es una adopción, no un patrón obligatorio.
+5. **Itere sin persistir** mediante `preview-data-program({ code, params? })` — la misma ruta de dry-run, sin fila almacenada.
+
+### Un ejemplo realista
+
+Suponga que una app quiere una tabla en vivo de "tickets de soporte recientes de alto valor" obtenida de un proveedor de soporte, filtrada a un umbral que ninguna action incorporada expone:
+
+```ts
+// The program's stored `code` — ordinary run-code, with one emit() call.
+const minValue = Number(params.minValue || 5000);
+
+const tickets = await providerFetchAll("acme-support", "/v1/tickets", {
+  query: { status: "open" },
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "next_cursor",
+    maxPages: 10,
+  },
+});
+
+const rows = (tickets.items || [])
+  .filter((t) => Number(t.contract_value || 0) >= minValue)
+  .map((t) => ({
+    ticket_id: t.id,
+    subject: t.subject,
+    account: t.account_name,
+    contract_value: Number(t.contract_value || 0),
+    opened_at: t.created_at,
+  }));
+
+emit(rows, [
+  { name: "ticket_id", type: "string" },
+  { name: "subject", type: "string" },
+  { name: "account", type: "string" },
+  { name: "contract_value", type: "number" },
+  { name: "opened_at", type: "string" },
+]);
+```
+
+Guardándolo:
+
+```ts
+await appAction("save-data-program", {
+  name: "high-value-open-tickets",
+  title: "High-Value Open Tickets",
+  description:
+    "Open support tickets above a configurable contract-value threshold.",
+  code: "/* the script above */",
+  defaultParams: { minValue: 5000 },
+  refreshMode: "ttl",
+  refreshTtlMs: 300_000,
+});
+```
+
+La respuesta incluye `{ programId, rowCount, columns, sampleRows }` — la prueba de finalización del dry-run. A partir de ahí, `run-data-program({ programId, params: { minValue: 10000 } })` lo vuelve a ejecutar (o sirve la caché) para un umbral diferente, y un panel de dashboard puede vincularse a `programId` de la misma manera.
+
+## La superficie del sandbox {#sandbox-surface}
+
+Un programa de datos se ejecuta a través del mismo sandbox `executeSandboxCode` que `run-code` — no existe código nuevo de sandboxing, credenciales, SSRF o cuotas para esta primitiva. Obtiene los mismos globals (`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`, `webFetch`, helpers de Resources `workspace*`) más dos adiciones de un pequeño preámbulo inyectado por el framework:
+
+- **`params`** — un objeto global **congelado** que contiene los params para esta ejecución (`defaultParams` fusionado con lo que se pasó a `run-data-program` o al descriptor del panel). Leerlo está bien; mutarlo lanza un error.
+- **`emit(rows, schema?)`** — llame a esto **exactamente una vez**, al final. Una segunda llamada lanza un error. `rows` debe ser un array de objetos planos. `schema`, cuando se proporciona, es `{ name: string, type: string }[]`; cuando se omite se infiere de las primeras 50 filas (una columna es `"json"` si las filas no coinciden en tipo primitivo en la muestra, de lo contrario `"number"` / `"string"` / `"boolean"`). `console.log` permanece completamente libre para depuración — el runner captura stdout/stderr combinados y solo elimina la línea centinela que escribe `emit()` al analizar el resultado.
+
+Límites impuestos en cada ejecución (no configurables por programa):
+
+| Límite                                                       | Valor                                                                                                                                                                       |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Máx. filas emitidas                                          | 10,000 — las filas más allá se descartan, `truncated: true`                                                                                                                 |
+| Máx. tamaño del resultado emitido                            | 4 MiB — las filas se descartan desde el final para ajustarse; una sola fila que supere el límite es un fallo `result_too_large` duro, ya que no hay nada seguro que truncar |
+| Máx. programas activos (no archivados) por app               | 200 — archive los no usados para liberar espacio                                                                                                                            |
+| TTL mínimo de actualización                                  | 60,000 ms                                                                                                                                                                   |
+| Filas de ejecución conservadas por (programa, params, visor) | 5 más recientes — las más antiguas se eliminan automáticamente en cada escritura                                                                                            |
+
+El truncamiento siempre es explícito (`truncated: true` en el resultado) — nunca una pérdida silenciosa.
+
+## Params y vinculación de paneles de dashboard {#params-and-panel-binding}
+
+Los programas declaran un `paramsSchema` opcional (JSON Schema que describe los params aceptados) y `defaultParams`. Un dashboard adopta la fuente de panel `"program"` colocando un pequeño descriptor JSON en el campo de consulta del panel en lugar de una cadena de consulta:
+
+```json
+{ "programId": "dp_a1b2c3d4e5f6", "params": { "minValue": 10000 } }
+```
+
+El panel se renderiza a través de exactamente los mismos componentes de gráfico/tabla que cualquier otra fuente de panel — solo recibe `{ rows, schema }` de vuelta. Vincular un panel a un programa es simplemente "qué programa almacenado, con qué sobrescrituras de params"; no hay ninguna ruta de ejecución específica de dashboard duplicada en otro lugar.
+
+## Semántica de actualización, TTL y caché {#refresh-and-caching}
+
+Cada par `(programId, paramsHash)` tiene su propio historial de ejecución en `data_program_runs`, y `paramsHash` incorpora **al visor**, no solo los params (vea la sección de seguridad para saber por qué). Qué sucede en cada lectura:
+
+| Situación                                                                                     | Comportamiento                                                                                                                                                                                                                    |
+| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Caché fresca (más reciente que `refreshTtlMs`, o `refreshMode: "manual"` con un éxito previo) | Devuelve las filas en caché instantáneamente, `cacheHit: true`                                                                                                                                                                    |
+| La caché es más antigua que el TTL                                                            | Se vuelve a ejecutar sincrónicamente — un presupuesto de 25s para lecturas activadas por vista de panel, 120s para llamadas de agente/manuales — y reemplaza la caché en caso de éxito                                            |
+| `refreshMode: "manual"`                                                                       | Nunca se actualiza automáticamente; solo un `forceRefresh: true` explícito (o una action de UI de actualización manual) lo vuelve a ejecutar                                                                                      |
+| Aún no hay caché                                                                              | Se ejecuta sincrónicamente como una primera obtención normal                                                                                                                                                                      |
+| Programa `background: true`, sin caché fresca                                                 | Sirve la última ejecución exitosa inmediatamente con `stale: true` y encola una ejecución en segundo plano duradera (presupuesto de 10 minutos); una llamada posterior finaliza el resultado una vez que la ejecución se completa |
+| Programa en segundo plano aún ejecutándose, sin éxito previo                                  | Fallo `background_pending` — muestre un estado explícito de "aún calculando", nunca un resultado en blanco                                                                                                                        |
+| La ejecución falla (timeout, error de sandbox, forma de `emit()` incorrecta)                  | Un fallo estructurado `{ code, message }`; si existe un éxito previo, se adjunta como `lastGoodRun` para que un panel pueda servir datos obsoletos en lugar de quedar en blanco                                                   |
+| El programa fue archivado (soft-delete mediante `delete-data-program`)                        | Fallo explícito `archived` — nunca un panel en blanco silencioso                                                                                                                                                                  |
+
+Recurra a `background: true` solo para programas que rutinariamente exceden el timeout en primer plano — grandes joins entre múltiples proveedores, paginación profunda. Todo lo demás debería permanecer en primer plano: es más simple de razonar y sirve datos frescos más rápido.
+
+### Por qué la caché está delimitada por visor {#per-viewer-cache}
+
+`providerFetch` dentro de un programa resuelve la autenticación usando **el propio contexto de solicitud del visor que llama** — nunca el del autor del programa. Eso es cierto ya sea que la llamada provenga del agente, de una llamada a `run-data-program`, o de un panel de dashboard que un compañero de equipo está viendo. Dos visores diferentes ejecutando el mismo programa con los mismos params pueden legítimamente obtener dos resultados distintos: uno tiene una clave de HubSpot configurada y el otro no, o los permisos de proveedor a nivel de fila difieren por persona.
+
+Debido a eso, `hashDataProgramParams` incorpora la identidad del llamador en la clave de caché junto con los params canonicalizados. Esto importa más en **dashboards compartidos**: si la caché estuviera indexada solo por params, la primera persona en ver un panel determinaría silenciosamente lo que ve cada otro visor, incluyendo un visor sin las credenciales que produjeron ese resultado en caché. La delimitación por visor significa que un compañero de equipo sin una credencial ve su propio error de autenticación en ese panel, no los datos de otra persona.
+
+## Modelo de seguridad {#security}
+
+<Callout id="doc-block-dp-security" tone="success">
+
+**Los tokens de proveedor en bruto nunca llegan al modelo ni al navegador.** Lo único que sale del sandbox es el `{ rows, schema }` que produce una llamada a `emit()` — el mismo límite de confianza que cualquier otra ejecución de run-code y cualquier otra fuente de panel de dashboard.
+
+</Callout>
+
+- **Solo del lado del servidor.** El código de un programa de datos se ejecuta exclusivamente dentro de `executeSandboxCode` en el servidor. Ni el código fuente almacenado ni ninguna credencial que toque se envía al navegador o al modelo — solo las filas/esquema emitidos y los metadatos compactos de la ejecución (recuento de filas, columnas, filas de muestra) se envían.
+- **Las credenciales son siempre las del visor que llama, nunca las del autor original del programa.** Vea [Semántica de actualización, TTL y caché](#per-viewer-cache) arriba para saber por qué esto también impulsa la clave de caché.
+- **`allowPublic: false` es un invariante estricto, no un valor por defecto.** Los programas de datos se registran en el registro de sharing de la misma manera que [Extensiones](/docs/extensions#security), con el sharing público deshabilitado. Un programa público permitiría que cualquier usuario autenticado ejecute código arbitrario almacenado bajo su propio token — compartir un programa está limitado a su organización, y solo significa "los compañeros de equipo pueden ver su resultado en caché y activar nuevas ejecuciones", nunca "el internet general puede ejecutar esto."
+- **Las actions que mutan y ejecutan no son invocables como herramienta desde el bridge de extensión/iframe en sandbox.** `save-data-program`, `preview-data-program`, `run-data-program` y `delete-data-program` son `toolCallable: false` — solo el agente o una ruta de lectura del lado del servidor pueden invocarlas, nunca un iframe de extensión bajo la sesión del que lo abrió. `list-data-programs` y `get-data-program` son de solo lectura y están delimitados por acceso mediante los mismos helpers de sharing que cualquier otro recurso ownable.
+- **Los programas están limitados a la app que los creó.** Pasar `appId` a una búsqueda significa que un programa creado en una app no se puede ejecutar desde el chat del agente de otra app en un despliegue de base de datos compartida, incluso para un llamador que de otro modo tendría acceso a nivel de fila (owner/org/share) a él.
+- **Solo vincúlese a o vea un programa en el que confíe.** Dado que la ejecución siempre usa las propias credenciales del visor, ver el resultado de un programa compartido es exactamente como abrir la extensión de otra persona — confíe en el código, no solo en el permiso de acceso.
+
+## El ejemplo desarrollado de Risk Meeting {#risk-meeting-example}
+
+La plantilla de analytics incluye un caso de estudio concreto y ejecutable: la action `ensure-risk-meeting-dashboard` instala de forma idempotente dos programas de datos más un dashboard "Risk Meeting" de dos paneles, demostrando tres cosas que una action codificada no puede anticipar para cada cliente.
+
+<FileTree
+  id="doc-block-dp-risk-meeting-files"
+  title={"Instalador de Risk Meeting"}
+  entries={[
+    {
+      path: "templates/analytics/actions/ensure-risk-meeting-dashboard.ts",
+      note: "action idempotente: actualiza ambos programas por nombre estable, luego el dashboard por id",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-cohort.js",
+      note: "payload de programa almacenado — texto JS simple, no un archivo fuente de build",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-pylon-early-warning.js",
+      note: "el programa de alerta temprana complementario",
+    },
+  ]}
+/>
+
+**`risk-meeting-cohort.js`** — busca una cohorte configurable de deals de CRM mediante una propiedad `risk_status` arbitraria (una búsqueda IN sobre valores personalizados que una action predefinida no puede anticipar), resuelve la empresa de cada deal mediante una búsqueda de asociación por lotes, resuelve el dominio de cada empresa, obtiene el sentimiento de cuenta de un segundo proveedor no relacionado, y une los dos por dominio:
+
+```js
+// params: { riskStatuses?: string[], enterpriseOnly?: boolean }
+const riskStatuses = params.riskStatuses?.length
+  ? params.riskStatuses
+  : ["On the Radar", "Churn Risk", "Confirmed Churn", "No Save Attempted"];
+
+// 1. Arbitrary property IN-search — not expressible through a canned filter.
+const dealSearch = await providerFetchAll("crm-provider", "/deals/search", {
+  method: "POST",
+  body: {
+    filterGroups: [
+      {
+        filters: [
+          { propertyName: "risk_status", operator: "IN", values: riskStatuses },
+        ],
+      },
+    ],
+  },
+  itemsPath: "results",
+  pagination: {
+    cursorBodyPath: "after",
+    nextCursorPath: "paging.next.after",
+    maxPages: 20,
+  },
+});
+
+// 2-3. Batched deal -> company -> domain resolution (elided here; see the
+// real seed file for the full batching helper).
+
+// 4. A second, unrelated provider — zero bespoke glue action required.
+const accounts = await providerFetchAll("support-provider", "/accounts", {
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "pagination.cursor",
+    maxPages: 20,
+  },
+});
+
+// 5. Join + emit.
+const rows = dealSearch.items.map((deal) => ({
+  deal_id: deal.id,
+  risk_status: deal.properties.risk_status,
+  arr: Number(deal.properties.total_contract_value || 0),
+  // ...domain lookup + sentiment join...
+}));
+
+emit(rows, [
+  { name: "deal_id", type: "string" },
+  { name: "risk_status", type: "string" },
+  { name: "arr", type: "number" },
+]);
+```
+
+**`risk-meeting-pylon-early-warning.js`** — la vista complementaria: cuentas ya marcadas como en riesgo por sentimiento de soporte que **aún no** han aparecido en la cohorte de CRM anterior. Esa brecha — señal de soporte adelantándose a la señal de CRM — requiere excluir la cohorte de un proveedor de la de otro, exactamente el tipo de lógica de conjuntos entre proveedores que ninguna action de un solo proveedor puede expresar.
+
+Ambos programas son instalados y mantenidos actualizados por `ensure-risk-meeting-dashboard`, que:
+
+- Actualiza cada programa por su `name` estable, de modo que volver a ejecutar el instalador actualiza las mismas filas en lugar de duplicarlas.
+- No requiere credenciales de CRM/soporte al momento de la instalación — la autenticación del proveedor se resuelve por visor solo cuando un panel realmente se renderiza o se llama a `run-data-program`, consistente con la delimitación de caché por visor de arriba.
+- Construye un dashboard de dos paneles cuyos paneles usan `source: "program"`, vinculados al id de cada programa.
+
+Vea la skill `data-programs` para la fuente completamente anotada.
+
+## Cómo otras apps adoptan la fuente de panel {#adopting-the-panel-source}
+
+La fuente de panel de dashboard `"program"` es una adopción de la primitiva, implementada enteramente en la propia capa de consulta de paneles de la app host — nada específico de dashboard está integrado en `@agent-native/core/data-programs` en sí. La implementación de la plantilla de analytics es una referencia útil para su propia conexión:
+
+- La columna `sql` del panel lleva un pequeño descriptor JSON — `{ programId, params? }` — en lugar de una cadena de consulta.
+- Renderizar un panel llama a `runDataProgram` con `triggeredBy: "panel_view"` y la identidad del visor actual, de modo que la caché por visor y la resolución de credenciales se apliquen automáticamente.
+- En caso de éxito, el panel obtiene `{ rows, schema }` — la misma forma que devuelve cualquier otra fuente de panel, de modo que fluye sin modificaciones a través de los componentes de gráfico/tabla existentes.
+- En caso de fallo, se prefiere un `lastGoodRun` sobre un panel roto siempre que exista uno; solo cuando no hay un éxito previo el panel muestra un error estructurado (con texto más amigable para códigos comunes como `access_denied`, `archived` y `background_pending`).
+
+Cualquier app puede implementar la misma adopción para sus propios dashboards/tablas: llame a `run-data-program` (o `runDataProgram` directamente si está dentro del mismo proceso de servidor) desde su propia ruta de lectura, y entregue las `rows`/`schema` devueltas a sus propios componentes de renderizado.
+
+## Documentación relacionada {#related}
+
+- [Extensiones](/docs/extensions) — la primitiva de mini-app en sandbox con la que los programas de datos comparten un modelo de seguridad y de sharing, pero con una UI propia.
+- [Actions](/docs/actions) — las convenciones de `run-code` y los globals del sandbox (`providerFetch`, `appAction`, etc.) sobre los que se construyen los programas de datos.
+- [Sharing y privacidad](/docs/sharing) — el modelo de sharing interno de la organización, nunca público, que usan los programas de datos.
+- [Seguridad](/docs/security) — los invariantes de manejo de credenciales y delimitación de acceso del framework.

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

@@ -384,24 +384,23 @@ Gírelos reemplazando la var de entorno en cada instancia y volviéndolos a impl
 ## 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:
+el complemento de chat del agente. La inspección SQL está habilitada de forma predeterminada;
+las escrituras pasan por actions tipadas de la app salvo que la app active explícitamente las herramientas de escritura sin formato:
 
 ```ts
 // server/plugins/agent-chat.ts
 export default createAgentChatPlugin({
-  // Default: "write" (also true)
+  // Default: "read"
   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: "read"`: predeterminado. Registra solo `db-schema` y `db-query`;
+  los agentes inspeccionan datos con SQL, pero deben usar actions tipadas de la app para escribir.
+- `databaseTools: "write"` o `true`: registra además `db-exec` y `db-patch`
+  para mantenimiento SQL sin formato deliberado. Las escrituras se limitan al
+  usuario/organización actual y los cambios de esquema están bloqueados.
 - `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