@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,259 @@
+---
+title: "Análisis"
+description: "Haga preguntas sobre análisis en inglés sencillo y obtenga gráficos y paneles. Un reemplazo de código abierto para Amplitude, Mixpanel y Looker."
+---
+
+# Análisis
+
+Haga preguntas sobre análisis en inglés sencillo y obtenga gráficos y paneles. El agente se conecta a BigQuery, GA4, Amplitude, el recopilador de eventos propio integrado, HubSpot, Jira y una docena de fuentes más, escribe la consulta por usted, la valida y representa la respuesta como un gráfico, una tabla o un panel de control guardado.
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:500px;box-sizing:border-box'><h1 style='margin:0'>Agent-Native Templates</h1><p class='wf-muted' style='margin:0'>Adoption and engagement across the last 12 weeks.</p><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px'><div class='wf-card'><small class='wf-muted'>Weekly active users</small><br/><strong>24,318</strong><br/><span class='wf-pill accent'>+12.4%</span></div><div class='wf-card'><small class='wf-muted'>New signups</small><br/><strong>1,842</strong><br/><span class='wf-pill accent'>+8.7%</span></div><div class='wf-card'><small class='wf-muted'>Revenue MRR</small><br/><strong>$48,210</strong><br/><span class='wf-pill accent'>+21.3%</span></div></div><div style='display:grid;grid-template-columns:1fr 1fr;gap:12px;flex:1'><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Weekly active users</strong><div style='flex:1;display:flex;align-items:end;gap:8px'><div style='height:38%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:44%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:58%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:74%;flex:1;background:var(--wf-accent-soft)'></div></div></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Revenue over time</strong><div style='flex:1;display:flex;align-items:end;gap:8px'><div style='height:32%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:48%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:63%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:80%;flex:1;background:var(--wf-accent-soft)'></div></div></div></div><div class='wf-card'><strong>Signups by source</strong><br/><small class='wf-muted'>Lower chart begins below the main charts.</small></div></div>"
+}
+```
+
+Es un reemplazo de código abierto para Amplitude, Mixpanel y Looker, para equipos que desean poseer el código, las consultas y los datos.
+
+```an-diagram title="Question to chart" summary="The agent consults the data dictionary, writes SQL, validates it against the warehouse, then renders a chart or saves a panel."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-node\">Plain-English<br>question</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Agent</span><small class=\"diagram-muted\">reads data dictionary</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Writes SQL</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">Dry-run validate</div><small class=\"diagram-muted\">BigQuery / source</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Chart, table, or<br>saved panel</div></div>",
+  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-col{display:flex;flex-direction:column;gap:6px;align-items:center}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Qué puedes hacer con él
+
+- **Haga preguntas sobre datos en un lenguaje sencillo.** "¿Qué porcentaje de registros del mes pasado se convirtieron en pagos?" o "Muéstrame usuarios activos semanales durante los últimos 6 meses". El agente elige la fuente correcta, escribe SQL y genera el gráfico.
+- **Cree paneles SQL reutilizables** con filtros, vistas guardadas y consultas paramétricas.
+- **Ejecute análisis ad hoc** que crucen varias fuentes de datos y se guarden como investigaciones que se pueden volver a ejecutar con la pregunta, las instrucciones y los hallazgos originales.
+- **Mantenga un diccionario de datos vivo** de métricas, tablas y recetas SQL para que el agente utilice los nombres de columna correctos cada vez (ya no tendrá que adivinar `is_closed` cuando en realidad es `hs_is_closed`).
+- **Comparte paneles** con tu equipo: privados de forma predeterminada, compartibles por usuario o por organización con funciones de espectador/editor/administrador.
+- **Conéctese a muchas fuentes** listas para usar: BigQuery, GA4, Mixpanel, Amplitude, PostHog, HubSpot, Jira, Apollo, Pylon, Gong, Common Room, Twitter, además de fuentes SEO específicas de la aplicación.
+- **Reutilizar integraciones de espacios de trabajo** cuando un espacio de trabajo ya se ha conectado y
+  otorgó un proveedor a Analytics. El proveedor de tiendas de integración compartida
+  referencias de identidad y credenciales; Analytics mantiene la selección de fuentes específicas de la aplicación
+  entradas del diccionario de datos, panel SQL e historial de análisis.
+
+## Empezando
+
+Demostración en vivo: [analytics.agent-native.com](https://analytics.agent-native.com).
+
+Cuando abres la aplicación por primera vez:
+
+1. Inicia sesión con Google.
+2. Abra la página **Fuentes de datos** desde la barra lateral.
+3. Cada fuente tiene un tutorial: conecta las que necesitas (comienza con una, como BigQuery, GA4, Amplitude o seguimiento propio).
+4. Abra un nuevo chat con el agente y haga una pregunta: "¿Cuántas suscripciones obtuvimos la semana pasada?"
+
+La primera pregunta es suficiente para confirmar que la conexión funciona. A partir de ahí, pídale al agente que "guarde esto como un panel" o "cree un panel de descripción general de 4 paneles para nuestras métricas clave".
+
+### Indicaciones útiles
+
+- "Cree un panel que muestre los usuarios activos semanales durante los últimos 6 meses."
+- "¿Qué porcentaje de registros del mes pasado se convirtieron en pagos?"
+- "Agregue un gráfico que compare los ingresos por plan a este panel."
+- "Reordene los paneles de este panel para que la métrica MRR sea lo primero".
+- "Analice nuestros acuerdos cerrados y perdidos del primer trimestre y guarde el análisis."
+- "Vuelva a ejecutar el análisis de abandono con los datos de este mes."
+- "Documente esta métrica en el diccionario de datos."
+
+El agente siempre sabe lo que estás viendo (panel de control actual, filtros, vista), por lo que puedes decir "este panel" o "ese panel" sin ser explícito.
+
+## Tres cosas que debes saber
+
+La aplicación tiene tres superficies principales en las que pasarás el tiempo:
+
+- **SQL Paneles**: paneles reutilizables con filtros y vistas guardadas. Lo mejor para métricas que verificas periódicamente.
+- **Análisis ad hoc**: investigaciones extensas que se obtienen de múltiples fuentes, con instrucciones para volver a ejecutarlas guardadas al lado. Ideal para preguntas puntuales que tal vez quieras volver a abordar.
+- **Diccionario de datos**: el catálogo canónico de métricas, tablas, columnas y recetas SQL. El agente lo consulta antes de escribir cualquier SQL, por lo que utiliza nombres de columnas de almacén reales y conoce advertencias como "excluye correos electrónicos internos".
+
+El diccionario se genera preguntando al agente: "importa nuestras definiciones dbt" o "extrae las métricas de nuestro manual Notion" y hace el trabajo.
+
+## Para desarrolladores
+
+El resto de este documento es para cualquiera que bifurque la plantilla de Analytics o la amplíe.
+
+### Inicio rápido
+
+Cree una nueva aplicación de Analytics desde CLI:
+
+```bash
+npx @agent-native/core@latest create my-analytics --standalone --template analytics
+```
+
+Desarrollador local:
+
+```bash
+cd my-analytics
+pnpm install
+pnpm dev
+```
+
+El CLI imprime el desarrollador local URL. Inicia sesión con Google y luego abre la página **Fuentes de datos** para conectar BigQuery, GA4, seguimiento propio, HubSpot, Jira y el resto.
+
+### Características clave
+
+**Haga preguntas, obtenga gráficos.** El agente elige una fuente de datos, escribe y valida SQL y luego genera un gráfico, una tabla, una métrica o un panel guardado.
+
+**Paneles e investigaciones.** Los paneles reutilizables mantienen los paneles SQL, los filtros, las vistas guardadas y el uso compartido; Los análisis ad hoc guardan hallazgos más largos con instrucciones de repetición.
+
+**Diccionario de datos vivientes.** Las definiciones de métricas, los propietarios, las tablas de origen y las advertencias conocidas brindan al agente el vocabulario real del almacén antes de escribir consultas.
+
+**Amplia superficie de conector.** BigQuery, GA4, análisis de productos, CRM, soporte, comunidad, GitHub/Jira, SEO y eventos propios `/track` llegan a través de actions al que el agente puede llamar.
+
+### Trabajar con el agente
+
+El agente siempre sabe lo que estás mirando. El estado actual de la pantalla se inyecta en cada mensaje como un bloque `<current-screen>`: contiene la vista activa, el panel o análisis abierto y los filtros seleccionados.
+
+El mensaje del sistema del agente recibe un bloque `<data-dictionary>` inyectado con las entradas de métricas aprobadas para la organización activa. Cuando solicita un panel, el agente consulta primero el diccionario y utiliza el documento `table` / `columns` / `queryTemplate` palabra por palabra; no adivina los nombres de las columnas.
+
+**Contexto que tiene automáticamente:**
+
+- **Vista actual**: `overview`, `adhoc` (con `dashboardId`), `analyses` (con `analysisId`), `data-dictionary`, `data-sources` o `settings`.
+- **Organización activa**: abarca todas las consultas y escrituras.
+- **Entradas de diccionario aprobadas**: para el espacio de trabajo activo.
+
+**Ediciones del panel.** El agente utiliza la acción `update-dashboard` para editar paneles. Admite dos modos:
+
+- `ops` — Parches de puntero JSON para ediciones quirúrgicas (mover un panel, reemplazar una cadena SQL, eliminar un filtro).
+- `config`: reemplazo completo de la configuración del tablero.
+
+El SQL de cada panel de BigQuery se realiza un ensayo en el almacén antes de que se guarde el panel. Si una columna es incorrecta, el guardado se rechaza con el error de BigQuery: el agente corrige el SQL y vuelve a intentarlo en lugar de conservar los paneles rotos.
+
+### Conectar fuentes de datos
+
+Abra la página **Fuentes de datos** (`/data-sources`) para conectar proveedores. Cada
+la fuente expone una lista de claves de entorno, un tutorial y un botón **Probar conexión**.
+Cuando Analytics se ejecuta en un espacio de trabajo, `data-source-status` también informa
+Otorgó conexiones de espacio de trabajo reutilizables para `appId=analytics` para que el agente pueda
+solicite una concesión de aplicación en lugar de otra copia de la misma clave de proveedor.
+Para proveedores reutilizables como Slack, HubSpot, Notion y GitHub, los datos
+Las fuentes UI muestran el estado de la integración compartida directamente: listo a través del espacio de trabajo,
+necesita concesión, necesita credenciales o credenciales locales.
+
+Las integraciones de espacios de trabajo reutilizables son la dirección del tiempo de ejecución para los proveedores compartidos:
+el marco almacena la identidad del proveedor, los metadatos de la cuenta, las referencias de credenciales y
+concesiones por aplicación una vez; Analytics almacena la interpretación de la fuente de datos, fuente de
+opciones de verdad, definiciones de métricas, paneles y análisis.
+
+Las credenciales se almacenan a través de la capa de configuración/entorno del marco; no hay secretos en git. La producción requiere:
+
+| Variable                                 | Propósito                                                             |
+| ---------------------------------------- | --------------------------------------------------------------------- |
+| `DATABASE_URL`                           | Conexión persistente SQL URL                                          |
+| `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` | Autenticación                                                         |
+| `GOOGLE_SIGN_IN_CLIENT_ID` / `_SECRET`   | Cliente de inicio de sesión de Google preferido (OAuth 2.0)           |
+| `GOOGLE_CLIENT_ID` / `_SECRET`           | Reserva de inicio de sesión antiguo/cliente de integración Google API |
+| `BIGQUERY_PROJECT_ID`                    | Proyecto BigQuery                                                     |
+| `GOOGLE_APPLICATION_CREDENTIALS_JSON`    | Cuenta de servicio de BigQuery JSON                                   |
+| `ANTHROPIC_API_KEY`                      | Chat del agente                                                       |
+
+Las claves específicas del proveedor (HubSpot, Jira, Gong, Pylon, etc.) están documentadas en el tutorial de cada fuente en la página Fuentes de datos. Si agrega una nueva acción que necesita una clave API, aparece como una nueva fuente en esa página a través del registro de incorporación de la plantilla.
+
+Nota: la credencial OAuth de BigQuery para el inicio de sesión de Google es **independiente**
+credencial de la cuenta de servicio de BigQuery JSON. Cree el cliente de inicio de sesión en
+Consola GCP → API y servicios → Credenciales → ID de cliente OAuth y prefiere el
+Nombres de entorno `GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET` para que esto
+El cliente de inicio de sesión de bajo alcance permanece separado de los clientes de integración API de Google.
+
+### Modelo de datos
+
+Tablas principales (ver `templates/analytics/server/db/schema.ts`):
+
+```an-schema title="Analytics data model" summary="Dashboards and analyses are the resources; views, shares, and a query cache hang off them. Org tables come from @agent-native/core/org."
+{
+  "entities": [
+    {
+      "id": "dashboards",
+      "name": "dashboards",
+      "note": "Explorer and SQL dashboards",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "kind", "type": "text", "note": "\"explorer\" or \"sql\"" },
+        { "name": "config", "type": "text", "note": "JSON matching SqlDashboardConfig" }
+      ]
+    },
+    {
+      "id": "dashboard_views",
+      "name": "dashboard_views",
+      "note": "Saved filter presets per dashboard",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "dashboard_id", "type": "text", "fk": "dashboards.id" }
+      ]
+    },
+    {
+      "id": "analyses",
+      "name": "analyses",
+      "note": "Re-runnable ad-hoc investigations",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "question", "type": "text" },
+        { "name": "instructions", "type": "text", "note": "Re-run steps" },
+        { "name": "dataSources", "type": "text", "note": "Sources touched" },
+        { "name": "resultMarkdown", "type": "text" },
+        { "name": "resultData", "type": "text", "nullable": true }
+      ]
+    },
+    {
+      "id": "bigquery_cache",
+      "name": "bigquery_cache",
+      "note": "Result cache keyed by SQL hash",
+      "fields": [
+        { "name": "sql_hash", "type": "text", "pk": true },
+        { "name": "bytes_processed", "type": "integer" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "dashboards", "to": "dashboard_views", "kind": "1-n", "label": "saved views" }
+  ]
+}
+```
+
+Además de las tablas compartidas por recurso (`dashboard_shares`, `analysis_shares`) y las tablas de organización (`organizations`, `org_members`, `org_invitations`) proporcionadas por `@agent-native/core/org`. El diccionario de datos se encuentra en la tabla `settings` del marco bajo claves de ámbito.
+
+- **`dashboards`**: paneles de Explorer y SQL. `kind` es `"explorer"` o `"sql"`; `config` es un blob JSON que coincide con `SqlDashboardConfig`.
+- **`dashboard_shares`**: subvenciones compartidas por recurso (principal, función).
+- **`dashboard_views`**: ajustes preestablecidos de filtro guardados por panel.
+- **`analyses`**: investigaciones ad hoc con `question`, `instructions`, `dataSources`, `resultMarkdown` y `resultData` opcional.
+- **`analysis_shares`**: subvenciones compartidas por recurso para análisis.
+- **`bigquery_cache`**: caché de resultados de consultas codificados por hash SQL con contabilidad procesada en bytes.
+
+Además de las tablas de organización (`organizations`, `org_members`, `org_invitations`) proporcionadas por `@agent-native/core/org`.
+
+El diccionario de datos se encuentra en la tabla `settings` del marco bajo claves de alcance; consulte `list-data-dictionary` y `save-data-dictionary-entry` actions para ver la forma completa.
+
+### Personalizarlo
+
+La plantilla de Analytics está destinada a bifurcarse y ampliarse. Todo vive en `templates/analytics/`:
+
+- **`AGENTS.md`**: la guía de nivel superior del agente. Vistas de documentos, actions y flujos de trabajo.
+- **`actions/`**: cada operación invocable por el agente. Agregue un nuevo archivo para agregar una nueva acción. Los más notables:
+  - `update-dashboard.ts`: ediciones del panel (operaciones + reemplazo completo)
+  - `save-analysis.ts` / `list-analyses.ts`: análisis ad hoc
+  - `save-data-dictionary-entry.ts` / `list-data-dictionary.ts` — diccionario
+  - `bigquery.ts`: ejecución sin formato de BigQuery
+  - `view-screen.ts` / `navigate.ts`: conciencia del contexto
+- **`app/routes/`**: rutas basadas en archivos. Cada ruta es una fina envoltura alrededor de una página en `app/pages/`.
+- **`app/pages/adhoc/sql-dashboard/`**: renderizador del panel SQL, editor de paneles, barra de filtros y vistas guardadas.
+- **`app/pages/analyses/`**: lista de análisis y vista detallada.
+- **`app/pages/DataSources.tsx`**: la fuente de datos que incorpora UI.
+- **`app/pages/DataDictionary.tsx`**: el navegador y editor de diccionarios.
+- **`.agents/skills/`**: guías de patrones que el agente lee según demanda:
+  - `dashboard-management`: almacenamiento, resolución de alcance, forma de configuración del panel
+  - `data-querying`: qué script utilizar, patrones de filtrado
+  - `adhoc-analysis`: flujo de trabajo para investigaciones de fuentes cruzadas
+  - `data-querying`, `real-time-sync`, `frontend-design`, `storing-data`, `self-modifying-code`
+- **`.builder/skills/<provider>/SKILL.md`**: errores específicos del proveedor (BigQuery, HubSpot, Jira, GA4, etc.). Leer antes de consultar; actualiza cuando aprendas algo nuevo.
+- **`server/db/schema.ts`**: esquema Drizzle para paneles, recursos compartidos, vistas, análisis y caché de BigQuery.
+- **`server/lib/dashboards-store.ts`**: lectura/escritura del panel con resolución de alcance y migración de KV heredado.
+- **`server/lib/bigquery.ts`**: cliente de BigQuery, validador de prueba y lógica de caché.
+
+Para agregar una nueva fuente de datos, coloque un script en `actions/` que llame al proveedor y devuelva resultados a través del asistente `output()`. Está disponible para el agente inmediatamente y se puede utilizar dentro de los paneles del panel (si expone el resultado a través de un controlador de servidor).
+
+Para agregar un nuevo tipo de gráfico, extienda la unión `ChartType` en `app/pages/adhoc/sql-dashboard/types.ts`, manéjela en `SqlChartCard.tsx` y el agente podrá usarla en cualquier panel.
+
+Para conocer un patrón más amplio sobre cómo ampliar plantillas, consulte [Skills guide](/docs/skills-guide) y [Actions](/docs/actions).

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

@@ -0,0 +1,303 @@
+---
+title: "Activos"
+description: "Un administrador de activos digitales nativo del agente y un servicio de generación entre agentes para medios consistentes con la marca."
+---
+
+# Activos
+
+Assets es un espacio de trabajo nativo del agente para crear y gestionar medios coherentes con la marca. Organiza las cargas y los resultados generados en bibliotecas y carpetas, permite a los equipos recopilar ejemplos de héroes de blogs, diagramas, páginas de destino, fotografías de productos, vídeos y logotipos, y luego dirige la generación a través del chat del agente para que cada activo pueda revisarse y perfeccionarse.
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:520px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Launch brand</h1><span class='wf-pill accent'>Blog heroes</span><span class='wf-pill'>Product shots</span><span class='wf-pill'>Logos</span><div style='flex:1'></div><button>Upload</button><button class='primary'>Generate</button></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Create brand media</strong><div class='wf-box'>Three homepage hero options using the approved logo and product references.</div><div style='display:flex;gap:8px;flex-wrap:wrap'><span class='wf-pill accent'>4 references</span><span class='wf-pill'>16:9</span><span class='wf-pill'>Web export</span></div></div><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px;flex:1'><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill accent'>Hero A</span></div><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill'>Reference set</span></div><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill'>Logo safe</span></div></div><div class='wf-card' style='display:grid;grid-template-columns:repeat(4,1fr);gap:8px'><div class='wf-box'>Use</div><div class='wf-box'>Refine</div><div class='wf-box'>Compare</div><div class='wf-box'>Export</div></div></div>"
+}
+```
+
+Cuando abre la aplicación, la biblioteca seleccionada, el mensaje, las referencias y los candidatos generados permanecen en un solo espacio de trabajo. El agente puede explorar, buscar, generar, refinar y exportar cada activo a través del mismo actions que utiliza el UI.
+
+```an-diagram title="Generate, review, reuse" summary="References and prompts feed a generate-and-choose session; chosen assets land in a library and flow out to other apps via the picker or A2A."
+{
+  "html": "<div class=\"diagram-assets\"><div class=\"diagram-col\"><div class=\"diagram-node\">References<br><small class=\"diagram-muted\">logos, product shots, style</small></div><div class=\"diagram-node\">Prompt<br><small class=\"diagram-muted\">chat or Generate controls</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill accent\">Generation session</span><small class=\"diagram-muted\">image &amp; video candidates · audit log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill ok\">Library</span><small class=\"diagram-muted\">chosen, brand-consistent assets</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">Picker<br><small class=\"diagram-muted\">iframe / MCP App</small></div><div class=\"diagram-node\">A2A<br><small class=\"diagram-muted\">Slides · Design · Content</small></div></div></div>",
+  "css": ".diagram-assets{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-assets .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-assets .diagram-box{display:flex;flex-direction:column;gap:4px}.diagram-assets .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## Cuándo elegirlo
+
+- **Tu equipo necesita una dirección visual reutilizable**, no indicaciones multimedia genéricas únicas: recopila logotipos, fotografías de productos y ejemplos de estilo aprobados para que las generaciones sigan enfocadas en la marca.
+- **Quiere que los medios generados se revisen y refinen**, con un registro de auditoría completo de indicaciones, modelos, referencias y linaje para cada ejecución.
+- **Otras aplicaciones necesitan un selector o generador de recursos**: Presentaciones, Diseño, Contenido, un editor de blog o un creador de sitios pueden insertar el selector o llamar a Recursos a través de A2A.
+- **Quiere que los medios de marca estén disponibles a través de su agente de codificación**: Codex, Claude Code, Claude o ChatGPT pueden generar y seleccionar recursos sin salir del chat.
+
+## Cómo empezar
+
+Demostración en vivo: [assets.agent-native.com](https://assets.agent-native.com).
+
+1. **Crea una biblioteca.** Añade la marca, la campaña, el producto o el flujo de contenido que desees
+   quiero administrar.
+2. **Subir referencias.** Agregar logotipos aprobados, fotografías de productos, ejemplos de estilo o
+   vídeos existentes para que el agente tenga material concreto con el que trabajar.
+3. **Generar desde un chat o una biblioteca.** Solicitar una imagen destacada, un diagrama o un producto
+   toma o variante de vídeo. Assets almacena el mensaje, referencias, modelo, estado,
+   y linaje para revisión.
+4. **Utilice el recurso en otro lugar.** Copie la exportación, incruste el selector en otro
+   aplicación o permita que otro agente llame a Assets a través de A2A.
+
+## Indicaciones útiles
+
+- "Genere tres opciones de blog hero utilizando las referencias de productos Acme."
+- "Crea una imagen social cuadrada con el estilo de campaña de lanzamiento".
+- "Encontrar todos los recursos aprobados para el rediseño de incorporación."
+- "Convierta este diagrama subido en una imagen explicativa del producto más limpia."
+- "Crea un guión gráfico de vídeo y guarda el mejor conjunto de fotogramas en esta biblioteca."
+
+## Qué puedes hacer con él
+
+- **Crea bibliotecas de recursos.** Agrupa imágenes de referencia, vídeos, logotipos canónicos, notas de estilo, paletas, carpetas y resultados generados por marca, campaña, producto o categoría.
+- **Generar a través del chat.** El compositor principal y los controles Generar de la biblioteca envían el mensaje al agente con `sendToAgentChat()`, para que los usuarios puedan inspeccionar variantes, dar comentarios e iterar.
+- **Generar imágenes y vídeos.** La generación de imágenes administrada por Builder está disponible cuando está habilitada, y Gemini potencia la generación de vídeos además del respaldo manual de imágenes.
+- **Cargue y describa referencias.** Agregue imágenes o videos de la biblioteca UI o solicite el botón adjunto del compositor, luego busque por título, descripción, texto alternativo, mensaje, modelo, tipo de medio, estado, función, carpeta o colección.
+- **Mantenga un registro de auditoría de generación.** Cada ejecución registra indicaciones, modelo, relación de aspecto, referencias, activo de origen, linaje, activos generados, estado, errores y marcas de tiempo para una revisión posterior del diseño.
+- **Preservar la precisión del logotipo.** El agente puede generar un área de marcador de posición y el servidor compone el logotipo canónico cargado en la imagen final en lugar de depender del modelo de imagen para volver a dibujarlo.
+- **Insertar como selector.** Otras aplicaciones pueden encuadrar `/picker` y escuchar el evento `chooseAsset` desde `@agent-native/embedding`, lo que convierte a Assets en un selector/generador de recursos para editores de blogs, creadores de sitios, presentaciones de diapositivas y aplicaciones personalizadas. El selector también emite el alias heredado `chooseImage` para hosts existentes de solo imágenes.
+- **Instalar como una habilidad respaldada por una aplicación.** El manifiesto `agent-native.app-skill.json` exporta una habilidad de Activos más metadatos del conector MCP para que los mercados puedan instalar la aplicación, sus instrucciones y su selector juntos.
+- **Servir a otros agentes.** Diapositivas, Diseño, Contenido, Correo y Envío pueden llamar a Recursos a través de A2A para enumerar bibliotecas, generar lotes, crear videos, refinar un recurso, recuperar exportaciones y generar vistas previas en línea donde se permite la incrustación.
+
+## Usándolo desde su agente de codificación
+
+Genere y seleccione medios de marca sin salir de Codex, Claude Code, Claude o ChatGPT.
+
+1. **Instalar una vez.** Esto agrega las instrucciones de habilidad y registra el conector MCP alojado en conjunto:
+
+   ```bash
+   npx @agent-native/core@latest skills agregar activos # alias: generación de imágenes
+   ```
+
+   El cliente predeterminado es `codex`; agregue `--client claude-code` o `--client all` para otros.
+   Si solo deseas las instrucciones de habilidades portátiles a través de Vercel/open
+   Skills CLI, utilice:
+
+   ```bash
+   npx skills@latest agregar BuilderIO/agent-native --skill activos
+   ```
+
+   Vercel/open Skills CLI instala únicamente el archivo de instrucciones; no es así
+   ejecute la configuración del conector MCP. Utilice la ruta Agent Native CLI anterior cuando lo desee
+   la configuración de un solo comando.
+
+2. **Solicite imágenes.** En el chat de su agente: "Genere tres opciones de blog hero a partir de las fotografías de productos Acme". El agente abre el selector con imágenes candidatas que puede regenerar, reajustar (indicar, aspecto, contar) y elegir.
+3. **Pick.** En los hosts en línea (ChatGPT, Claude.ai, chat principal de escritorio Claude), el selector se muestra directamente en el chat: haga clic en un candidato y la elección volverá automáticamente. En los hosts CLI/solo enlace (Codex, Código Claude, pestaña "Código" del escritorio Claude), aparece un enlace **"Abrir en Activos →"**; ábrelo, selecciona en el navegador y luego pega el resumen de transferencia copiado nuevamente en tu chat, o simplemente di "usar imagen A".
+
+   ```texto
+   Pegue esta selección nuevamente en su chat para que el agente pueda usarla.
+
+   Imagen de activos seleccionados para el siguiente paso: <label>
+   Medios URL: <url>
+   Utilice este activo seleccionado en el artefacto o diseño actual.
+
+   Contexto del activo seleccionado:
+   { "selectedAsset": { "assetId": "...", "url": "...", "mediaType": "imagen", ... } }
+   ```
+
+4. **Aplicar al código.** Los medios URL y `assetId` elegidos regresan al agente, que utiliza el URL directamente en el código que escribe (un src de `<img>`, una descarga) o llama a `export-asset`.
+
+## Para desarrolladores
+
+El resto de este documento es para cualquiera que bifurque la plantilla de Activos o la amplíe.
+
+### Andamios
+
+```bash
+npx @agent-native/core@latest create my-assets --standalone --template assets
+```
+
+### Modelo de datos
+
+Todos los datos residen en SQL a través de Drizzle ORM (los medios binarios residen en el almacenamiento de objetos o en el respaldo de carga de archivos local durante el desarrollo). Esquema: `templates/assets/server/db/schema.ts`. Las bibliotecas llevan el estándar `ownableColumns` y una tabla de recursos compartidos de marco coincidente, por lo que encajan en el modelo de uso compartido por usuario/por organización.
+
+Nota: los nombres de las tablas SQL mantienen el prefijo `image_*` heredado de cuando la aplicación se llamaba Imágenes. Cubren vídeos y otros medios también.
+
+| Tabla                            | Qué contiene                                                                                                                                                                                                                |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `image_libraries`                | Una biblioteca: el contenedor de nivel superior agrupado por marca, campaña, producto o categoría. Contiene `custom_instructions`, `style_brief`, logotipo canónico, referencias de recursos de portada y estado de archivo |
+| `image_library_shares`           | El marco comparte tablas que asignan principales (usuarios u organizaciones) a roles (visor, editor, administrador) por biblioteca                                                                                          |
+| `image_collections`              | Agrupaciones de estilos/categorías dentro de una biblioteca: `style_brief`, `prompt_template`, relación de aspecto predeterminada y tamaño de imagen                                                                        |
+| `asset_folders`                  | Carpetas anidables dentro de una biblioteca (`parent_id` para jerarquía)                                                                                                                                                    |
+| `image_generation_presets`       | Recetas de generación guardadas: tipo de medio, plantilla de mensaje, relación de aspecto, modelo y política de texto/referencia                                                                                            |
+| `image_generation_sessions`      | Una sesión iterativa de generación y elección con un resumen breve, de estado, de activos activos y de comentarios                                                                                                          |
+| `image_generation_session_items` | Activos candidatos dentro de una sesión, cada uno con una función y una nota                                                                                                                                                |
+| `image_assets`                   | El registro de activo: tipo de medio, función, estado, título/descripción/texto alternativo, mensaje, modelo, dimensiones, tipo MIME, claves de objeto/miniatura y linaje                                                   |
+| `image_generation_runs`          | El registro de auditoría de generación: mensaje, mensaje compilado, modelo, referencias, estado, errores y el `source` (`chat` / `ui` / `a2a`) que lo activó                                                                |
+
+```an-schema title="Assets data model" summary="Libraries are the ownable container; collections, folders, and presets organize them. Sessions drive generate-and-choose; assets and runs hold output and the audit log. Table names keep the legacy image_* prefix but cover all media."
+{
+  "entities": [
+    { "id": "library", "name": "image_libraries", "note": "Top-level ownable container", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "custom_instructions", "type": "text", "nullable": true },
+      { "name": "style_brief", "type": "text", "nullable": true },
+      { "name": "logo_asset_id", "type": "id", "fk": "image_assets.id", "nullable": true },
+      { "name": "archived", "type": "boolean" }
+    ] },
+    { "id": "library_shares", "name": "image_library_shares", "note": "Framework shares table", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "role", "type": "text", "note": "viewer / editor / admin" }
+    ] },
+    { "id": "collections", "name": "image_collections", "note": "Style/category groupings", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "style_brief", "type": "text", "nullable": true },
+      { "name": "prompt_template", "type": "text", "nullable": true }
+    ] },
+    { "id": "folders", "name": "asset_folders", "note": "Nestable folders", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "parent_id", "type": "id", "fk": "asset_folders.id", "nullable": true }
+    ] },
+    { "id": "presets", "name": "image_generation_presets", "note": "Saved generation recipes", "fields": [
+      { "name": "media_type", "type": "text" },
+      { "name": "prompt_template", "type": "text" },
+      { "name": "model", "type": "text" }
+    ] },
+    { "id": "sessions", "name": "image_generation_sessions", "note": "Iterative generate-and-choose", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "status", "type": "text" },
+      { "name": "active_asset_id", "type": "id", "fk": "image_assets.id", "nullable": true }
+    ] },
+    { "id": "session_items", "name": "image_generation_session_items", "note": "Candidate assets in a session", "fields": [
+      { "name": "session_id", "type": "id", "fk": "image_generation_sessions.id" },
+      { "name": "asset_id", "type": "id", "fk": "image_assets.id" },
+      { "name": "role", "type": "text" }
+    ] },
+    { "id": "assets", "name": "image_assets", "note": "The asset record", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "media_type", "type": "text", "note": "image / video" },
+      { "name": "status", "type": "text" },
+      { "name": "prompt", "type": "text", "nullable": true },
+      { "name": "object_key", "type": "text", "nullable": true }
+    ] },
+    { "id": "runs", "name": "image_generation_runs", "note": "Generation audit log", "fields": [
+      { "name": "model", "type": "text" },
+      { "name": "status", "type": "text" },
+      { "name": "source", "type": "text", "note": "chat / ui / a2a" }
+    ] }
+  ],
+  "relations": [
+    { "from": "library", "to": "collections", "kind": "1-n" },
+    { "from": "library", "to": "folders", "kind": "1-n" },
+    { "from": "library", "to": "assets", "kind": "1-n" },
+    { "from": "sessions", "to": "session_items", "kind": "1-n" },
+    { "from": "library", "to": "library_shares", "kind": "1-n" }
+  ]
+}
+```
+
+### Personalizarlo
+
+Assets es una plantilla completa y clonable. Algunas ideas prácticas de extensión:
+
+- "Agregue un conector de catálogo de productos para que SKU pueda seleccionar fotografías de referencia de productos."
+- "Agregue una cola de aprobación estricta antes de que los recursos generados se marquen como utilizables para marketing."
+- "Agregue un panel de revisión de marca que filtre las generaciones fallidas o con calificaciones bajas por modelo".
+- "Crea una biblioteca de recursos predeterminada para todo el espacio de trabajo y dirige la generación de imágenes de Presentaciones a través de ella."
+- "Agregue un nuevo proveedor detrás de la interfaz de generación de imágenes después de verificar los últimos documentos del proveedor."
+
+El agente edita rutas, componentes y modelos respaldados por actions, skills y SQL según sea necesario. Consulte [Templates](/docs/cloneable-saas) para ver el flujo completo de clonación, personalización e implementación y [A2A Protocol](/docs/a2a-protocol) para generación entre aplicaciones.
+
+### Incrustar el selector
+
+Utilice la ruta del selector cuando un humano elija o genere un activo dentro
+otro producto. La imagen es el tipo de medio predeterminado; pasar `mediaType=video` cuando
+quieres buscar/selección de vídeos:
+
+```tsx
+import { EmbeddedApp } from "@agent-native/embedding";
+
+<EmbeddedApp
+  url="https://assets.agent-native.com/picker?mediaType=image"
+  onMessage={(name, payload) => {
+    if (name === "chooseAsset") {
+      insertAsset((payload as { url: string }).url);
+    }
+  }}
+/>;
+```
+
+Los hosts externos MCP deberían llamar a `open-asset-picker` en lugar de construir esto
+iframe a mano. La acción devuelve un enlace alternativo del navegador y metadatos de la aplicación MCP
+para hosts en línea. Cuando un usuario selecciona un activo, el selector emite `chooseAsset`,
+el alias `chooseImage` heredado para recursos de imagen y actualizaciones del modelo de aplicación MCP
+contexto donde el host lo admite. Cuando un host abre el enlace alternativo en un
+pestaña normal del navegador en lugar de mostrar la aplicación MCP en línea, seleccionando un activo
+copia un resumen de transferencia y muestra un bloque de contexto copiable; pega ese resumen
+volver al chat para que el agente externo pueda usar el medio seleccionado URL y
+metadatos de activos.
+
+Codex, código Claude y código de escritorio Claude deben tratarse como hosts de enlace externo
+para este flujo. Es posible que no representen aplicaciones MCP en línea ni rebajas remotas de CDN
+Es posible que las imágenes no se muestren de manera confiable en la transcripción del chat. Los agentes deben mantener el
+vínculo de activos como fuente de verdad; cuando se necesita una vista previa en línea visible en un
+Chat del editor de código, descarga el `previewUrl`/`downloadUrl` seleccionado a un local
+archivo de imagen e incrustar esa ruta local absoluta.
+
+Para generar y elegir flujos, llame a `open-asset-picker` con `prompt`,
+`autoGenerate: true` y `count: 3` (personalizables del 1 al 6). Se abre el selector
+con imágenes candidatas y permite al usuario ajustar el recuento, la relación de aspecto o
+preajuste de generación antes de elegir el activo final URL.
+
+Utilice A2A cuando otro agente necesite crear, buscar o exportar activos sin
+recolector humano UI.
+
+### Desarrollador: distribuir la habilidad de la aplicación
+
+La habilidad de la aplicación Assets tiene el ID de aplicación `assets` y está alojado MCP URL
+`https://assets.agent-native.com/_agent-native/mcp`.
+
+```bash
+# Easiest hosted install: exported skill instructions plus MCP connector.
+npx @agent-native/core@latest skills add assets
+
+# Vercel/open Skills CLI install: exported instructions only, no MCP config.
+npx skills@latest add BuilderIO/agent-native --skill assets
+
+# Hosted install: URL-only MCP connector, no shared secrets in skill files.
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# Local editable launch.
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# Marketplace package, including Claude Code marketplace and Vercel Labs skills adapters.
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# Install a local exported Assets bundle with the open skills CLI.
+npx skills@latest add ./dist/assets-skill --skill assets -a codex -y
+
+# Install from the generated Claude Code marketplace adapter.
+claude plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace
+claude plugin install agent-native-assets@agent-native-apps
+```
+
+La habilidad exportada enseña a los agentes a utilizar el selector para el contacto humano
+selección, actions directo para generación desatendida de imágenes/videos y navegador
+enlaces cuando las aplicaciones MCP en línea no están disponibles.
+
+El adaptador de mercado Claude contiene un `.claude-plugin/marketplace.json`
+catálogo y complemento `agent-native-assets` con `skills/assets/SKILL.md` plus
+el `.mcp.json` alojado. En el código interactivo Claude, el mismo flujo está disponible
+como `/plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace`,
+`/plugin install agent-native-assets@agent-native-apps`, `/reload-plugins` y
+`/mcp` para autenticación MCP.
+
+Si instala desde un paquete de mercado sin formato con `npx skills@latest`, registre el
+Conector MCP alojado para que esas instrucciones puedan llamar a la aplicación Assets en vivo:
+
+```bash
+npx @agent-native/core@latest app-skill ensure --manifest ./dist/assets-skill/agent-native.app-skill.json --yes
+```
+
+## ¿Qué sigue?
+
+- [**Templates**](/docs/cloneable-saas): el modelo de clonar y poseer
+- [**Embedding SDK**](/docs/embedding-sdk): selector de iframe y patrones sidecar
+- [**A2A Protocol**](/docs/a2a-protocol): cómo otras aplicaciones llaman a los Activos
+- [**File Uploads**](/docs/file-uploads): almacenamiento y servicio de activos autenticados
+- [**Sharing & Privacy**](/docs/sharing): control de acceso a nivel de biblioteca