@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/es-ES/workspace-connections.md

@@ -0,0 +1,321 @@
+---
+title: "Conexiones del espacio de trabajo"
+description: "Metadatos, subvenciones y referencias de credenciales de proveedores compartidos para integraciones de conexión única y uso en todas partes."
+---
+
+# Conexiones del espacio de trabajo
+
+Las conexiones del espacio de trabajo son el marco primitivo para los metadatos de integración reutilizables. Hacen posible "conectarse una vez, otorgar aplicaciones, reutilizar credenciales" sin pretender que cada proveedor sea completamente genérico.
+
+## Inicio rápido {#quickstart}
+
+### Los cuatro conceptos
+
+- **Conexión**: una cuenta de proveedor denominada (`team-slack`, `acme-hubspot`). Registra la identificación del proveedor, la etiqueta de la cuenta, el estado, los alcances y la configuración segura. Nunca almacena valores secretos.
+- **Conceder**: permiso para que una aplicación específica utilice una conexión. Una aplicación sin una concesión no puede ver las credenciales de la conexión.
+- **credentialRef**: un puntero a un secreto de almacén (`{ key: "SLACK_BOT_TOKEN", scope: "org" }`). La conexión dice dónde vive el token; la bóveda guarda el valor.
+- **Preparación**: el estado combinado que ve una aplicación: `connected` (otorgado + credenciales presentes), `needs_grant`, `needs_credentials`, `needs_attention` o `not_configured`.
+
+```an-diagram title="Connect once, grant apps, reuse credentials" summary="A Connection holds provider metadata (never secrets) and credentialRefs that point at the vault. Per-app Grants unlock it. Apps read a single Readiness status."
+{
+  "html": "<div class=\"diagram-conn\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection</span><div class=\"diagram-box\" data-rough>named provider account<br><small class=\"diagram-muted\">provider, label, status, scopes, config &middot; never stores secret values</small></div><div class=\"diagram-muted\">credentialRef &rarr; pointer to a vault secret</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill\">Grant</span><div class=\"diagram-box\" data-rough>per-app permission<br><small class=\"diagram-muted\">no grant = no credential access</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Readiness</span><small class=\"diagram-muted\">what the app sees</small><div class=\"sev-row\"><span class=\"diagram-pill ok\">connected</span><span class=\"diagram-pill warn\">needs_grant</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">needs_credentials</span><span class=\"diagram-pill warn\">needs_attention</span></div><div class=\"sev-row\"><span class=\"diagram-pill\">not_configured</span></div></div></div>",
+  "css": ".diagram-conn{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-conn .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-conn .diagram-arrow{font-size:22px;line-height:1}.diagram-conn .sev-row{display:flex;gap:8px;flex-wrap:wrap}"
+}
+```
+
+### Ejemplo resuelto: Slack
+
+Conecta Slack una vez y concédelo a Brain and Analytics:
+
+```ts
+import {
+  upsertWorkspaceConnection,
+  upsertWorkspaceConnectionGrant,
+} from "@agent-native/core/workspace-connections";
+
+await upsertWorkspaceConnection({
+  id: "acme-slack",
+  provider: "slack",
+  label: "Acme Slack",
+  accountId: "T012345",
+  accountLabel: "Acme",
+  status: "connected",
+  scopes: ["channels:history", "groups:history", "chat:write"],
+  config: {
+    teamDomain: "acme",
+    channelHints: ["product", "dev-fusion", "customer-success"],
+  },
+  credentialRefs: [{ key: "SLACK_BOT_TOKEN", scope: "org" }],
+});
+
+await upsertWorkspaceConnectionGrant({
+  connectionId: "acme-slack",
+  appId: "brain",
+});
+await upsertWorkspaceConnectionGrant({
+  connectionId: "acme-slack",
+  appId: "analytics",
+});
+```
+
+```an-schema title="The connection model" summary="A connection records safe provider metadata and credentialRefs (pointers, not secrets). Each grant unlocks one app — one connection, many grants."
+{
+  "entities": [
+    {
+      "id": "conn",
+      "name": "workspace_connections",
+      "note": "Named provider account. Never stores secret values.",
+      "fields": [
+        { "name": "id", "type": "string", "pk": true, "note": "e.g. acme-slack" },
+        { "name": "provider", "type": "string", "note": "stable provider id, e.g. slack" },
+        { "name": "label", "type": "string" },
+        { "name": "accountId", "type": "string", "nullable": true },
+        { "name": "accountLabel", "type": "string", "nullable": true },
+        { "name": "status", "type": "string", "note": "e.g. connected" },
+        { "name": "scopes", "type": "string[]", "nullable": true },
+        { "name": "config", "type": "json", "nullable": true, "note": "safe, non-secret config" },
+        { "name": "credentialRefs", "type": "json", "nullable": true, "note": "pointers to vault keys, e.g. { key, scope }" }
+      ]
+    },
+    {
+      "id": "grant",
+      "name": "workspace_connection_grants",
+      "note": "Per-app permission to use a connection.",
+      "fields": [
+        { "name": "connectionId", "type": "string", "fk": "conn.id" },
+        { "name": "appId", "type": "string", "note": "e.g. brain, analytics" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "conn", "to": "grant", "kind": "1-n", "label": "grants apps" }
+  ]
+}
+```
+
+### Cómo llaman las aplicaciones
+
+Antes de pedirle a un usuario que pegue una nueva clave, verifique primero que esté lista:
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+  appId: "brain",
+  templateUse: "brain",
+  provider: "slack",
+  includeConnections: "all",
+});
+
+const slack = catalog.providers[0];
+if (slack.workspaceConnection.grantState === "needs_grant") {
+  // Show "Grant Brain access" instead of asking for a second Slack token.
+}
+if (slack.readiness.status === "needs_credentials") {
+  // Show the missing credential ref names, never a secret value.
+}
+```
+
+## Referencia {#reference}
+
+### Catálogo de proveedores
+
+Importar el catálogo de `@agent-native/core/connections`:
+
+```ts
+import {
+  getWorkspaceConnectionProvider,
+  listWorkspaceConnectionProvidersForTemplate,
+  workspaceConnectionProviderSupports,
+} from "@agent-native/core/connections";
+
+const brainProviders = listWorkspaceConnectionProvidersForTemplate("brain");
+const slack = getWorkspaceConnectionProvider("slack");
+
+if (workspaceConnectionProviderSupports("slack", "messages")) {
+  // Offer a Slack source, sync check, or onboarding step.
+}
+```
+
+Los identificadores de proveedor iniciales son:
+
+| Proveedor      | Capacidades                             | Usos comunes                                 |
+| -------------- | --------------------------------------- | -------------------------------------------- |
+| `slack`        | buscar, importar, mensajes              | cerebro, despacho, análisis                  |
+| `github`       | buscar, importar, codificar, documentos | cerebro, análisis, despacho                  |
+| `notion`       | buscar, importar, documentos            | cerebro, contenido, despacho                 |
+| `gmail`        | buscar, importar, mensajes              | correo, cerebro, despacho                    |
+| `google_drive` | buscar, importar, documentos            | cerebro, contenido, diapositivas             |
+| `hubspot`      | buscar, importar, crm                   | análisis, cerebro, correo                    |
+| `granola`      | buscar, importar, reuniones, documentos | cerebro, calendario, despacho                |
+| `clips`        | buscar, importar, reuniones             | cerebro, clips, vídeos                       |
+| `generic`      | buscar, importar, documentos            | webhooks personalizado y entrega de archivos |
+
+Las claves de credenciales son solo nombres, como `SLACK_BOT_TOKEN` o `GITHUB_TOKEN`. Los metadatos del proveedor nunca deben incluir valores de credenciales reales.
+
+### Tienda de conexión API
+
+```ts
+import {
+  listWorkspaceConnectionProviderCatalogForApp,
+  listWorkspaceConnectionGrants,
+  listWorkspaceConnections,
+  summarizeWorkspaceConnectionProviderForApp,
+  summarizeWorkspaceConnectionProviderReadiness,
+  upsertWorkspaceConnection,
+  upsertWorkspaceConnectionGrant,
+  revokeWorkspaceConnectionGrant,
+} from "@agent-native/core/workspace-connections";
+
+const connections = await listWorkspaceConnections({ includeDisabled: true });
+const grants = await listWorkspaceConnectionGrants({ appId: "brain" });
+
+const appGrant = summarizeWorkspaceConnectionProviderForApp({
+  providerId: "slack",
+  appId: "brain",
+  connections,
+  grants,
+});
+
+const readiness = summarizeWorkspaceConnectionProviderReadiness({
+  provider: slack!,
+  appId: "brain",
+  connections,
+  grants,
+});
+
+const brainCatalog = await listWorkspaceConnectionProviderCatalogForApp({
+  appId: "brain",
+  templateUse: "brain",
+});
+```
+
+La matriz `credentialRefs` apunta a las claves del almacén; no es almacenamiento de credenciales. Por ejemplo, `{ key: "SLACK_BOT_TOKEN", scope: "org" }` le dice a una aplicación autorizada que busque el secreto de la bóveda con ámbito de organización denominado `SLACK_BOT_TOKEN` cuando necesita llamar a Slack. Las referencias a nivel de conexión describen la cuenta del proveedor; Las referencias a nivel de concesión pueden limitar o anular lo que debe usar una aplicación específica.
+
+Las filas de conexión tienen como ámbito la organización activa cuando hay una presente. Sin una organización, su ámbito es el usuario autenticado. Las filas de concesión utilizan el mismo ámbito.
+
+**Campo `allowedApps` heredado:** `allowedApps: []` significa que todas las aplicaciones en el mismo ámbito pueden usar la conexión; `allowedApps: ["dispatch"]` otorga acceso a través del campo heredado. Utilice filas `workspace_connection_grants` explícitas para una nueva configuración: facilitan la revocación, la auditoría y la preparación por aplicación. `revokeWorkspaceConnectionGrant(connectionId, appId)` elimina una concesión explícita pero no cambia el `allowedApps` heredado.
+
+Utilice `summarizeWorkspaceConnectionProviderForApp()` y `summarizeWorkspaceConnectionProviderReadiness()` para el estado de la aplicación en lugar de realizar comprobaciones de subvenciones manuales. Los resúmenes compartidos devuelven `grantState`, `grantAvailability`, nombres de referencia de credenciales seguras, filas de conexión por aplicación y campos de preparación como `readyConnectionCount` y `missingRequiredCredentialKeys`.
+
+Para las pantallas de configuración de aplicaciones nuevas, prefiera `listWorkspaceConnectionProviderCatalogForApp()` como límite de nivel superior: combina el catálogo de proveedores, las conexiones con alcance, las concesiones explícitas, los resúmenes de acceso por aplicación y la preparación del proveedor en una sola forma segura.
+
+### Cómo complementa esto la bóveda
+
+La bóveda de credenciales responde: "¿Dónde se almacena el secreto, quién puede acceder a él y qué aplicaciones se lo otorgan?"
+
+Los metadatos del proveedor de conexión del espacio de trabajo responden: "¿Qué proveedor es este, qué puede hacer, qué claves de credenciales podría necesitar y qué plantillas deberían ofrecerlo?"
+
+```an-diagram title="Connection store vs. vault" summary="The vault owns the secret value. The connection owns provider metadata plus credentialRefs (pointers). At execution time the app resolves the ref through a granted connection and reads the value from the vault."
+{
+  "html": "<div class=\"diagram-vault\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection store</span><div class=\"diagram-box\" data-rough>provider account + metadata<br><small class=\"diagram-muted\">status, scopes, config</small></div><div class=\"diagram-box\" data-rough>credentialRef<br><small class=\"diagram-muted\">{ key: SLACK_BOT_TOKEN, scope: org }</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">App action</span><small class=\"diagram-muted\">resolves at execution time through a granted ref</small><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Vault</span><div class=\"diagram-box\" data-rough>secret value<br><small class=\"diagram-muted\">never returned to the agent or UI</small></div></div></div>",
+  "css": ".diagram-vault{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-vault .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-vault .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-vault .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Usar ambos juntos:
+
+1. El envío (u otro flujo de configuración del espacio de trabajo) crea el secreto de la bóveda subyacente o la referencia de credencial OAuth.
+2. El almacén de conexiones del espacio de trabajo registra la cuenta del proveedor, los metadatos seguros, las referencias de credenciales y las concesiones de aplicaciones.
+3. Cada aplicación lee los metadatos del proveedor del catálogo y los resúmenes de conexión/concesión del almacén compartido.
+4. La aplicación UI muestra que está lista: conectada, otorgada pero en mal estado, necesita concesión, faltan credenciales o solo metadatos.
+5. SQL específico de la aplicación almacena solo identificadores de fuente, cursores, filtros, ventanas de sincronización, definiciones de métricas, reglas de revisión y opciones de usuario específicas de la aplicación.
+6. La aplicación actions resuelve las credenciales en el momento de la ejecución a través de referencias de conexión otorgadas y la bóveda, y nunca devuelve valores secretos.
+
+### Tiempo de ejecución del lector del proveedor
+
+La capa proveedor-lector es primero un contrato, no una promesa de que cada proveedor tenga un lector en vivo compartido. Las definiciones del lector describen las operaciones admitidas, los requisitos de credenciales y el estado de implementación: `metadata-only`, `template-owned` o `shared`. El tiempo de ejecución resuelve la conexión del espacio de trabajo otorgado y las referencias de credenciales para una aplicación, llama a un controlador registrado y devuelve elementos normalizados sin exponer valores secretos.
+
+La mayoría de los controladores en vivo siguen siendo propiedad de las plantillas en la actualidad, lo que significa que Brain todavía posee el comportamiento de ingesta de Slack/GitHub y Analytics aún posee la interpretación analítica. Promocione a un lector a `shared` solo cuando las llamadas, la paginación, los permisos y la semántica de resultados de API específicos del proveedor sean realmente reutilizables en todas las plantillas.
+
+### Patrón de preparación de la aplicación
+
+Las aplicaciones que consumen credenciales de proveedores compartidas deben exponer una acción de preparación de solo lectura y una pequeña superficie de configuración que cubra:
+
+- **Catálogo de proveedores:** ID de proveedor, etiqueta, capacidades, usos de plantilla recomendados y nombres de claves de credenciales requeridas de `@agent-native/core/connections`.
+- **Resumen del espacio de trabajo:** recuento de conexiones, recuentos activos/concedidos, estado de concesión, nombres de referencia de credenciales y etiquetas de cuentas no secretas de `@agent-native/core/workspace-connections`.
+- **Preparación del proveedor:** `ready`, `needs_credentials`, `needs_attention`, `checking`, `disabled` o `not_configured` a través de `summarizeWorkspaceConnectionProviderReadiness()`.
+- **Estado de la fuente:** fuentes configuradas locales de la aplicación, cursores, estado de sincronización y siguiente acción.
+
+La página Fuentes de Brain es la implementación de referencia. Muestra proveedores de conexión de espacio de trabajo reutilizables junto a los registros de origen de Brain, etiqueta los estados de concesión como `connected`, `granted`, `needs_grant` o `not_connected` y muestra el estado del proveedor como listo, claves faltantes, concesión necesaria, necesita reparación o solo metadatos.
+
+### Construyendo un conector reutilizable
+
+Cuándo un nuevo proveedor debería funcionar en varias plantillas:
+
+1. **Metadatos del proveedor:** agregue o reutilice un proveedor en `@agent-native/core/connections`. Esta es la identificación estable, la etiqueta para mostrar, la lista de capacidades, los usos recomendados de la plantilla y los nombres de las claves de credenciales.
+2. **Conexión del espacio de trabajo:** Dispatch u otra superficie de configuración del espacio de trabajo almacena los metadatos seguros, el estado, los alcances, `credentialRefs` y las concesiones de aplicaciones de la cuenta conectada a través de `@agent-native/core/workspace-connections`.
+3. **Fuente local de la aplicación:** Brain, Analytics, Mail u otra aplicación almacena solo las opciones específicas de la aplicación que posee, como canales Slack, repositorios GitHub, filtros de objetos HubSpot, cursores de sincronización o cadencia de sondeo.
+
+No duplique OAuth/almacenamiento de tokens en cada aplicación. El registro de conexión dice "este es Acme Slack y su token se encuentra en `SLACK_BOT_TOKEN`"; la fuente local de la aplicación dice "Brain puede ingerir `#product` y `#dev-fusion` de esa conexión Slack".
+
+### Configuración del plano de control de despacho
+
+Dispatch expone el plano de control actions que escribe las mismas funciones de tienda compartida que una aplicación podría llamar directamente:
+
+```ts
+// templates/dispatch/actions/upsert-workspace-connection.ts delegates to this.
+await upsertWorkspaceConnection({
+  id: "team-slack",
+  provider: "slack",
+  label: "Acme Slack",
+  accountId: "T012345",
+  accountLabel: "acme",
+  status: "connected",
+  scopes: ["channels:history", "groups:history"],
+  config: { teamDomain: "acme", preferredChannels: ["product", "dev-fusion"] },
+  credentialRefs: [
+    {
+      key: "SLACK_BOT_TOKEN",
+      scope: "org",
+      provider: "slack",
+      label: "Slack bot token",
+    },
+  ],
+});
+
+// Then grant the apps that should reuse the provider.
+await upsertWorkspaceConnectionGrant({
+  connectionId: "team-slack",
+  appId: "brain",
+});
+await upsertWorkspaceConnectionGrant({
+  connectionId: "team-slack",
+  appId: "analytics",
+});
+```
+
+Utilice `allowedApps: []` solo cuando una conexión deba estar disponible para todas las aplicaciones en el mismo ámbito. Prefiere filas de concesión explícitas para la configuración de producción.
+
+### Resolución de credenciales
+
+El código de ejecución de la aplicación resuelve los valores de credenciales de `credentialRefs` concedido a través del almacén en el alcance de la solicitud activa. `source-credentials.ts` de Brain es la implementación de referencia actual: enumera las conexiones del espacio de trabajo para el proveedor, verifica `getWorkspaceConnectionAppAccess` para `appId: "brain"`, fusiona referencias de credenciales de nivel de conexión y de nivel de concesión, y lee el primer secreto de bóveda con alcance coincidente. Otras aplicaciones deberían seguir esa forma en lugar de buscar `process.env`.
+
+## Notas de diseño {#design-notes}
+
+<details>
+<summary>Política de promoción de lectores y ruta para "conectarse una vez, utilizar en todas partes"</summary>
+
+### Límite local de la aplicación
+
+El límite entre las conexiones compartidas y las fuentes locales de la aplicación es intencional. Lo que hoy es reutilizable es la identidad del proveedor, la resolución de referencia de credenciales, las concesiones por aplicación, la preparación del proveedor, los metadatos de cuenta seguros y el contrato normalizado entre proveedor y lector. Lo que aún no es genérico es la lectura más activa del proveedor API, la propiedad del flujo OAuth, los cursores de ingesta, los filtros de origen, la cadencia de sincronización y la interpretación del dominio. Estos permanecen en la aplicación propietaria del flujo de trabajo a menos que una implementación de lector se promueva explícitamente como compartida.
+
+Los conectores de origen de aplicaciones no deben leer variables de entorno de nivel de implementación como respaldo para las credenciales de origen de usuario/organización. Las variables de entorno son globales para la implementación y no expresan concesiones de espacio de trabajo.
+
+Los agentes deben seguir una regla simple: si un usuario solicita conectarse a Slack, GitHub, HubSpot, Gmail, Google Drive, Granola u otro proveedor compartido, primero inspeccione el catálogo de conexiones del espacio de trabajo. Si el proveedor es `connected`, úselo. Si es `needs_grant`, solicite o realice la concesión de la aplicación. Si es `needs_credentials`, solicite la clave de la bóveda que falta. Sólo solicite una nueva clave sin formato cuando no exista una conexión reutilizable.
+
+### Ruta para "conectarse una vez y utilizar en todas partes"
+
+El catálogo de proveedores y el almacén de subvenciones son la base de una capa de espacio de trabajo más amplia:
+
+- Los identificadores de proveedores compartidos y los nombres de capacidades mantienen las plantillas alineadas.
+- El inventario a nivel de espacio de trabajo puede mostrar qué proveedores están configurados en Brain, Mail, Analytics, Dispatch y aplicaciones futuras.
+- Las filas de conexión registran etiquetas de cuenta, estado, aplicaciones permitidas, referencias de credenciales y comprobaciones de estado sin cambiar los ID de proveedor de la plantilla.
+- Las filas de concesión permiten que el propietario de un espacio de trabajo se conecte una vez y luego habilitan aplicaciones individuales a medida que el espacio de trabajo las adopta.
+- Los agentes pueden dirigir el trabajo entre aplicaciones sabiendo qué proveedores ya están conectados y qué aplicaciones tienen concesiones.
+- La búsqueda federada puede solicitar proveedores con capacidades `search`, `docs`, `messages`, `meetings`, `crm` o `code` en lugar de codificar la lista de conectores de cada aplicación.
+- Los lectores específicos del proveedor, los flujos de actualización OAuth, los puntos de control de ingesta y los modelos de datos propiedad de las aplicaciones se pueden compartir más adelante, pero no están implicados en una conexión de espacio de trabajo actual.
+
+Mantenga los límites estrictos: es seguro mostrar los metadatos del proveedor; los valores de credenciales permanecen en la bóveda.
+
+</details>

package/docs/content/locales/es-ES/workspace-management.md

@@ -0,0 +1,175 @@
+---
+title: "Gobernanza del espacio de trabajo"
+description: "Bifurcación, CODEOWNERS, revisión de relaciones públicas y cómo Dispatch maneja la gobernanza en tiempo de ejecución junto con la gobernanza a nivel de git."
+---
+
+# Gobernanza del espacio de trabajo
+
+> **¿Qué documento de espacio de trabajo?** Esta página cubre **gobernanza**: quién revisa, aprueba y es propietario de qué en muchas aplicaciones en un repositorio. Para saber qué es un espacio de trabajo (la capa de personalización), consulte [Workspace](/docs/workspace); para conocer la forma de implementación (un monorepo, muchas aplicaciones), consulte [Multi-App Workspaces](/docs/multi-app-workspace).
+
+Esta guía cubre el aspecto operativo de la ejecución de un espacio de trabajo nativo del agente: cómo bifurcar, quién revisa qué, cómo configurar la propiedad del código y cómo el plano de control de envío encaja en su modelo de gobierno.
+
+```an-diagram title="Two governance planes" summary="Git governs code; Dispatch governs runtime. They are complementary — don't replicate one inside the other."
+{
+  "html": "<div class=\"gov\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Git / GitHub</span><strong>Code governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">CODEOWNERS</span><span class=\"diagram-pill\">branch protection</span><span class=\"diagram-pill\">PR review</span><span class=\"diagram-pill\">git log / blame</span></div></div><div class=\"diagram-pill diagram-muted\">+</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Dispatch</span><strong>Runtime governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">vault secrets &amp; grants</span><span class=\"diagram-pill\">workspace resources</span><span class=\"diagram-pill\">agent profiles</span><span class=\"diagram-pill\">approvals &amp; audit</span></div></div></div>",
+  "css": ".gov{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.gov .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.gov .gov-list{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}"
+}
+```
+
+## Bifurcación
+
+### Ramas de funciones
+
+Utilice ramas de funciones de corta duración para todo el trabajo:
+
+```
+main                         ← production
+├── feat/mail-filters        ← single-app change
+├── feat/core-oauth-refresh  ← framework change
+├── fix/analytics-chart      ← targeted bug fix
+└── feat/vault-encryption    ← dispatch/infra change
+```
+
+**Convenciones de nomenclatura:**
+
+- **Cambios en una sola aplicación:** `feat/<app>-<description>` o `fix/<app>-<description>`, p. `feat/mail-thread-search`, `fix/calendar-recurrence-parse`
+- **Cambios en el marco:** `feat/core-<description>` o `fix/core-<description>`, p. `feat/core-polling-v2`
+- **Cambios en el envío:** `feat/dispatch-<description>` — p.e. `feat/dispatch-vault-policies`
+- **Cambios entre aplicaciones:** si un cambio en el marco requiere actualizaciones de plantilla, haga ambas cosas en una rama para que se envíen de forma atómica
+
+Mantenga las ramas de corta duración. Las ramas de larga duración divergen de las principales y crean fusiones dolorosas, especialmente en un monorepo donde varios equipos presionan diariamente.
+
+### Bifurcación para no desarrolladores
+
+No todos los que necesitan realizar cambios se sienten cómodos con git. [Builder.io](https://www.builder.io) admite un modelo de ramificación visual que se asigna a ramas de git internas, lo que resulta útil para cambios de contenido y copia, ajustes de diseño, iteraciones de diseño y pruebas A/B sin un entorno de desarrollo.
+
+## Propiedad del código
+
+La gobernanza del código se configura mediante un puñado de archivos en la raíz del repositorio:
+
+```an-file-tree title="Governance config in the repo"
+{
+  "entries": [
+    { "path": ".github/CODEOWNERS", "note": "Auto-assigns reviewers per changed path" },
+    { "path": ".github/labeler.yml", "note": "Auto-labels PRs by app" },
+    { "path": "pnpm-workspace.yaml", "note": "Workspace-level — broad review" },
+    { "path": "package.json", "note": "Workspace-level — platform team owns" }
+  ]
+}
+```
+
+El archivo CODEOWNERS de GitHub asigna automáticamente revisores a los RP según los archivos modificados. Cree `.github/CODEOWNERS` en la raíz del repositorio:
+
+```
+# Framework core — affects every app; platform team reviews all changes
+packages/core/                     @your-org/platform-team
+
+# Dispatch control plane — secrets, integrations, workspace resources
+templates/dispatch/                @your-org/platform-team
+
+# Per-app ownership — each team reviews their own app
+templates/mail/                    @your-org/mail-team
+templates/analytics/               @your-org/analytics-team
+templates/calendar/                @your-org/calendar-team
+# ... add an entry per app
+
+# Workspace-level config — broad review since it affects everyone
+.github/                           @your-org/platform-team
+package.json                       @your-org/platform-team
+pnpm-workspace.yaml                @your-org/platform-team
+```
+
+Consejos clave: utilice equipos GitHub (`@org/team`), no individuos. Los cambios en el marco y el envío siempre deben requerir una revisión de la plataforma. Consulte [GitHub CODEOWNERS docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) para conocer la sintaxis global y los patrones de múltiples propietarios.
+
+Para habilitar las revisiones requeridas: Configuración → Sucursales → Protección de sucursales para `main` → **Requerir una solicitud de extracción antes de fusionar** → **Requerir revisión de los propietarios del código**.
+
+## Etiquetado de relaciones públicas
+
+Etiquetar relaciones públicas automáticamente por aplicación con `.github/labeler.yml` (extracto):
+
+```yaml
+app:mail:
+  - changed-files:
+      - any-glob-to-any-file: templates/mail/**
+app:analytics:
+  - changed-files:
+      - any-glob-to-any-file: templates/analytics/**
+core:
+  - changed-files:
+      - any-glob-to-any-file: packages/core/**
+```
+
+Luego agregue la acción [actions/labeler](https://github.com/actions/labeler); consulte el README de ese repositorio para conocer el flujo de trabajo completo YAML. Las etiquetas se aplican automáticamente cuando se abren o actualizan los PR.
+
+## Pautas de revisión de relaciones públicas
+
+| Tipo de cambio                           | Quién revisa                                            | A qué prestar atención                                                                   |
+| ---------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Solo aplicación** (`templates/<app>/`) | Equipo propietario de la aplicación                     | Corrección del dominio, esquemas de acción                                               |
+| **Marco** (`packages/core/`)             | Equipo de plataforma + un equipo de aplicación afectado | Cambios importantes, rendimiento, compatibilidad con versiones anteriores                |
+| **Migraciones de esquema**               | Equipo de plataforma + ingeniero senior                 | Seguridad de datos, agnosticismo dialectal (SQLite + Postgres)                           |
+| **Actions**                              | Equipo propietario                                      | Actions son herramientas de agente AND HTTP puntos finales: revisión desde ambos ángulos |
+| **A2A multiaplicación**                  | Ambos equipos de aplicaciones                           | Si cambia una interfaz A2A, las personas que llaman deben saberlo                        |
+| **Bóveda de envío/recursos**             | Equipo de plataforma                                    | Acceso secreto, alcance de la concesión, quién obtiene qué                               |
+
+### Trabajo de agente simultáneo
+
+Los espacios de trabajo nativos del agente a menudo tienen varios agentes de IA trabajando en la misma rama simultáneamente. Esto es así por diseño: los agentes comparten una sucursal y trabajan de forma independiente.
+
+```an-callout
+{ "tone": "warning", "body": "**The later commit wins.** Two agents touching the same file won't conflict at commit time — the conflict surfaces at review. Run `pnpm run prep` (typecheck + test + format) before pushing, and don't revert changes you didn't make unless they're clearly broken." }
+```
+
+Al revisar relaciones públicas en este entorno:
+
+- **No revierta los cambios que no realizó** a menos que estén claramente incorrectos
+- **Múltiples agentes pueden modificar los archivos** en el mismo PR; esto es normal
+- **Ejecute `pnpm run prep`** (verificación de tipo + prueba + formato) antes de presionar para detectar problemas de integración entre los cambios de los agentes
+- **Si dos agentes tocan el mismo archivo,** gana la confirmación posterior. Los conflictos surgen en el momento de la revisión, no en el momento de la confirmación
+- **Corregir errores en cualquier código del PR,** independientemente de qué agente lo escribió. El PR se revisa en su conjunto.
+
+## Envío como gobernanza
+
+La aplicación [Dispatch](/docs/dispatch) es el plano de control de tiempo de ejecución del espacio de trabajo. Complementa la gobernanza a nivel de git con la gobernanza en tiempo de ejecución:
+
+| Preocupación                                | Git/GitHub                     | Envío                                                                       |
+| ------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------- |
+| Quién puede cambiar el código               | CODEOWNERS, protección de rama | —                                                                           |
+| Quién puede acceder a los secretos          | —                              | Política de Vault, subvenciones, flujo de trabajo de solicitudes            |
+| Qué instrucciones siguen los agentes        | —                              | Recursos globales del espacio de trabajo (AGENTS.md, instrucciones, skills) |
+| Qué agentes se comparten                    | —                              | Perfiles de agentes de Workspace                                            |
+| Inventario de integración                   | —                              | Catálogo de conexiones e integraciones del espacio de trabajo               |
+| Aprobación de cambio de tiempo de ejecución | —                              | Flujo de aprobación de envío                                                |
+| Pista de auditoría                          | `git log` / `git blame`        | Auditoría de bóveda + registros de auditoría de envío                       |
+| Mensajería y enrutamiento                   | —                              | Slack / Integración de Telegram                                             |
+
+**Git maneja la gobernanza del código. Dispatch maneja la gobernanza del tiempo de ejecución.** No intente replicar flujos de trabajo de git dentro de Dispatch o viceversa.
+
+Dispatch gestiona: secretos de bóveda, conexiones de espacio de trabajo reutilizables, recursos del espacio de trabajo (skills, instrucciones, perfiles de agentes, servidores MCP), aprobaciones y registros de auditoría. Para la configuración de rutas de aplicaciones públicas (`workspaceApp.audience` / `publicPaths` / `protectedPaths`), consulte [Multi-App Workspaces — Public app routes](/docs/multi-app-workspace#deployment).
+
+Para conocer el modelo de recursos y las rutas canónicas, consulte [Workspace — Global resources](/docs/workspace#global-resources).
+
+## Lista de verificación de configuración
+
+Para un nuevo espacio de trabajo, después de ejecutar `npx @agent-native/core@latest create`:
+
+**Git y GitHub:**
+
+- [ ] Crear `.github/CODEOWNERS` con propiedad del equipo por aplicación
+- [ ] Habilite la protección de sucursales en `main` con las revisiones requeridas del propietario del código
+- [ ] Agregue `.github/labeler.yml` para etiquetar automáticamente las relaciones públicas por aplicación
+- [ ] Cree equipos GitHub para cada aplicación y el equipo de la plataforma
+
+**Envío:**
+
+- [ ] Agregue secretos compartidos a la bóveda (claves API, credenciales OAuth, etc.)
+- [ ] Mantenga la política de almacenamiento predeterminada para todas las aplicaciones o cambie a concesiones manuales por aplicación
+- [ ] Sincronizar secretos de la bóveda para enviarlos a las aplicaciones
+- [ ] Registre conexiones de espacio de trabajo reutilizables para cuentas de proveedores compartidos y luego
+      otorgar aplicaciones como Brain, Analytics, Mail o Dispatch solo cuando lo necesiten
+      esa cuenta
+- [ ] Agregue skills para todo el espacio de trabajo, instrucciones de barandilla y recursos de referencia de marca/empresa a través de la página Recursos. Consulte [Workspace](/docs/workspace#global-resources) para ver la tabla completa de modelos de recursos y el paquete de inicio recomendado.
+- [ ] Configurar la política de aprobación y los correos electrónicos del aprobador
+- [ ] Configurar SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) para notificaciones de administrador
+- [ ] Conecte Slack o Telegram para mensajería en el espacio de trabajo
+- [ ] Configure servidores MCP compartidos: agregue recursos del espacio de trabajo `mcp-servers/<name>.json` en Dispatch para concesiones para todas las aplicaciones o para aplicaciones seleccionadas; utilice `mcp.config.json` o [MCP hub mode](/docs/mcp-clients#hub) para implementaciones de nivel inferior