@agent-native/core 0.88.0 → 0.90.1

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

@@ -1,77 +1,103 @@
 ---
-title: "Toolkit de Agent-Native"
-description: "Kits reutilizables para colaboración, ajustes, compartir, navegación, presencia, historial, configuración y UX del agente."
+title: "Toolkit"
+description: "Reusable app-building primitives that sit between @agent-native/core and template apps."
 ---
 
-# Toolkit de Agent-Native
-
-Las apps de Agent-Native no deberían reconstruir la fontanería del workspace.
-Las apps son dueñas de sus modelos, acciones y vistas de producto. El framework
-y `@agent-native/toolkit` son dueños de las piezas reutilizables que todas las
-apps deberían heredar: colaboración, compartir, ajustes, navegación,
-organización, configuración, UX del agente, historial y visibilidad operativa.
-
-El objetivo es que los usuarios aprendan una sola forma de compartir, conectar
-claves, ver al agente editar junto a ellos, encontrar ajustes y entender qué
-cambió.
-
-## Contrato del toolkit {#toolkit-contract}
-
-Mueve comportamiento al toolkit cuando sea:
-
-- **De workspace** - los usuarios esperan que funcione igual en todas las apps.
-- **Visible para el agente** - el agente necesita la misma capacidad mediante
-  acciones, instrucciones o estado de aplicación.
-- **Gobernado** - aplican permisos, auditoría, secretos, política de org,
-  facturación o reglas de compartir.
-- **Repetido** - dos apps ya construyeron UI o lógica parecida.
-- **No específico del dominio** - la app aporta nombres y acciones de recursos,
-  pero el patrón de interacción es genérico.
-
-Mantén lo local cuando dependa de un modelo de dominio o de un flujo propio de
-la app.
-
-## Kits reutilizables {#reusable-kits}
-
-- **Settings kit** - pestañas estándar para cuenta, workspace, modelos de AI,
-  claves LLM, conexiones, secretos, uso, notificaciones, changelog y preferencias
-  de app. La configuración durable vive en Settings; la barra lateral del agente
-  conserva controles contextuales y enlaces profundos.
-- **Collaboration kit** - edición en tiempo real, documentos Yjs, presencia,
-  presencia del agente, cursores, selecciones remotas, resaltado de ediciones y
-  undo/redo compartido. Ver
-  [Real-Time Collaboration](/docs/real-time-collaboration).
-- **Sharing kit** - un solo modelo de privacidad y permisos para privado,
-  workspace, org, enlace público, invitaciones, roles, expiraciones y acceso
-  legible por agentes. Ver [Sharing & Privacy](/docs/sharing).
-- **Navigation and command kit** - app shell, navegación, breadcrumbs, app
-  switcher, command palette, recursos recientes, recursos fijados y búsqueda.
-- **Organization kit** - carpetas, tags, favoritos, archivo, papelera,
-  propietarios, membresía y metadata común.
-- **Setup and connections kit** - claves API, OAuth, conexiones, estado de
-  modelos, secretos faltantes y onboarding declarativo. Ver
-  [Workspace Connections](/docs/workspace-connections).
-- **Agent UX kit** - sidebar, composer, contexto preparado, menciones, voz,
-  aprobación humana, UI generativa, progreso y estado visible para el agente.
-- **History and recovery kit** - audit log, activity feed, version history,
-  checkpoints, undo, redo, restore y proof-of-done. Ver
-  [Audit Log](/docs/audit-log).
-- **Comments and review kit** - comentarios anclados, pines, menciones,
-  solicitudes de revisión, threads resueltos y tareas de seguimiento del agente.
-- **Workflow and observability kit** - notificaciones, aprobaciones, runs en
-  background, jobs recurrentes, traces, evals, feedback y líneas de tiempo. Ver
-  [Observability](/docs/observability).
-
-## Orden de implementación {#implementation-order}
-
-1. Consolidar la configuración durable en pestañas estándar de Settings.
-2. Normalizar colaboración, presence, agent presence, undo/redo y edición en
-   tiempo real detrás de adapters compartidos.
-3. Mover navegación, comandos, recientes, favoritos, carpetas, tags, archivo y
-   papelera a primitivas compartidas.
-4. Registrar todos los recursos compartibles en el mismo modelo de permisos y
-   acceso legible por agentes.
-5. Dar a cada recurso colaborativo una historia consistente de actividad,
-   comentarios, revisión, restore y auditoría.
-6. Unificar notificaciones, aprobaciones, estado de runs, traces, evals y
-   feedback.
+# 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/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/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`    |