@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/pt-BR/workspace-connections.md

@@ -0,0 +1,321 @@
+---
+title: "Conexões do espaço de trabalho"
+description: "Metadados de provedor compartilhados, concessões e referências de credenciais para integrações de conexão única e utilização em todos os lugares."
+---
+
+# Conexões do espaço de trabalho
+
+As conexões do espaço de trabalho são a estrutura primitiva para metadados de integração reutilizáveis. Eles tornam possível "conectar uma vez, conceder aplicativos, reutilizar credenciais" sem fingir que cada provedor é totalmente genérico.
+
+## Início rápido {#quickstart}
+
+### Os quatro conceitos
+
+- **Conexão** — uma conta de provedor nomeada (`team-slack`, `acme-hubspot`). Registra o ID do provedor, rótulo da conta, status, escopos e configuração segura. Nunca armazena valores secretos.
+- **Grant** — permissão para um aplicativo específico usar uma conexão. Um aplicativo sem concessão não pode ver as credenciais da conexão.
+- **credentialRef** — um ponteiro para um segredo do cofre (`{ key: "SLACK_BOT_TOKEN", scope: "org" }`). A conexão indica onde o token reside; o cofre contém o valor.
+- **Prontidão** — o status combinado que um aplicativo vê: `connected` (concedido + credenciais presentes), `needs_grant`, `needs_credentials`, `needs_attention` ou `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}"
+}
+```
+
+### Exemplo resolvido: Slack
+
+Conecte Slack uma vez e conceda-o ao 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" }
+  ]
+}
+```
+
+### O que os aplicativos chamam
+
+Antes de pedir a um usuário para colar uma nova chave, verifique primeiro se ela está pronta:
+
+```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.
+}
+```
+
+## Referência {#reference}
+
+### Catálogo de Provedores
+
+Importar o 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.
+}
+```
+
+Os IDs iniciais do provedor são:
+
+| Provedor       | Capacidades                                | Usos comuns                                   |
+| -------------- | ------------------------------------------ | --------------------------------------------- |
+| `slack`        | pesquisar, importar, mensagens             | cérebro, expedição, análise                   |
+| `github`       | pesquisar, importar, codificar, documentos | cérebro, análise, expedição                   |
+| `notion`       | pesquisar, importar, documentos            | cérebro, conteúdo, expedição                  |
+| `gmail`        | pesquisar, importar, mensagens             | correio, cérebro, despacho                    |
+| `google_drive` | pesquisar, importar, documentos            | cérebro, conteúdo, slides                     |
+| `hubspot`      | pesquisar, importar, CRM                   | analítica, cérebro, e-mail                    |
+| `granola`      | pesquisa, importação, reuniões, documentos | cérebro, calendário, envio                    |
+| `clips`        | pesquisa, importação, reuniões             | cérebro, clipes, vídeos                       |
+| `generic`      | pesquisar, importar, documentos            | webhooks personalizado e descarte de arquivos |
+
+As chaves de credenciais são apenas nomes, como `SLACK_BOT_TOKEN` ou `GITHUB_TOKEN`. Os metadados do provedor nunca devem incluir valores de credenciais reais.
+
+### Armazenamento de conexões 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",
+});
+```
+
+A matriz `credentialRefs` aponta para chaves do cofre; não é armazenamento de credenciais. Por exemplo, `{ key: "SLACK_BOT_TOKEN", scope: "org" }` instrui um aplicativo concedido a procurar o segredo do cofre no escopo da organização denominado `SLACK_BOT_TOKEN` quando precisar chamar Slack. As referências no nível da conexão descrevem a conta do provedor; as referências no nível da concessão podem restringir ou substituir o que um aplicativo específico deve usar.
+
+As linhas de conexão têm como escopo a organização ativa quando uma está presente. Sem uma organização, eles têm como escopo o usuário autenticado. As linhas de concessão usam o mesmo escopo.
+
+**Campo `allowedApps` legado:** `allowedApps: []` significa que todos os aplicativos no mesmo escopo podem usar a conexão; `allowedApps: ["dispatch"]` concede acesso através do campo legado. Use linhas `workspace_connection_grants` explícitas para novas configurações – elas facilitam a revogação, a auditoria e a preparação por aplicativo. `revokeWorkspaceConnectionGrant(connectionId, appId)` remove uma concessão explícita, mas não altera o `allowedApps` legado.
+
+Use `summarizeWorkspaceConnectionProviderForApp()` e `summarizeWorkspaceConnectionProviderReadiness()` para status voltado para o aplicativo em vez de verificações de concessão manuais. Os resumos compartilhados retornam `grantState`, `grantAvailability`, nomes de referência de credenciais seguras, linhas de conexão por aplicativo e campos de preparação, como `readyConnectionCount` e `missingRequiredCredentialKeys`.
+
+Para novas telas de configuração de aplicativos, prefira `listWorkspaceConnectionProviderCatalogForApp()` como limite de nível superior. Ele combina o catálogo de provedores, conexões com escopo, concessões explícitas, resumos de acesso por aplicativo e prontidão do provedor em um único formato seguro.
+
+### Como isso complementa o cofre
+
+O cofre de credenciais responde: "Onde o segredo está armazenado, quem pode acessá-lo e quais aplicativos o recebem?"
+
+Os metadados do provedor de conexão do espaço de trabalho respondem: "Que provedor é esse, o que ele pode fazer, quais chaves de credenciais ele precisa e quais modelos devem oferecê-lo?"
+
+```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}"
+}
+```
+
+Use os dois juntos:
+
+1. O Dispatch (ou outro fluxo de configuração do espaço de trabalho) cria o segredo do cofre subjacente ou a referência de credencial OAuth.
+2. O armazenamento de conexões do workspace registra a conta do provedor, metadados seguros, referências de credenciais e concessões de aplicativos.
+3. Cada aplicativo lê metadados do provedor do catálogo e resumos de conexão/concessão do armazenamento compartilhado.
+4. O aplicativo UI mostra prontidão: conectado, concedido, mas não íntegro, precisa de concessão, credenciais ausentes ou apenas metadados.
+5. SQL específico do aplicativo armazena apenas IDs de origem, cursores, filtros, janelas de sincronização, definições de métricas, regras de revisão e escolhas do usuário específicos do aplicativo.
+6. O aplicativo actions resolve credenciais em tempo de execução por meio de referências de conexão concedidas e do cofre, e nunca retorna valores secretos.
+
+### Tempo de execução do leitor do provedor
+
+A camada provedor-leitor é primeiro um contrato, não uma promessa de que todo provedor tenha um leitor ativo compartilhado. As definições do leitor descrevem operações suportadas, requisitos de credenciais e status de implementação: `metadata-only`, `template-owned` ou `shared`. O tempo de execução resolve a conexão concedida ao espaço de trabalho e as referências de credencial para um aplicativo, chama um manipulador registrado e retorna itens normalizados sem expor valores secretos.
+
+A maioria dos manipuladores ativos permanecem de propriedade do modelo hoje, o que significa que o Brain ainda possui o comportamento de ingestão Slack/GitHub e o Analytics ainda possui a interpretação analítica. Promova um leitor para `shared` somente quando as chamadas API específicas do provedor, a paginação, as permissões e a semântica de resultados forem realmente reutilizáveis entre modelos.
+
+### Padrão de prontidão do app
+
+Aplicativos que consomem credenciais de provedor compartilhadas devem expor uma ação de prontidão somente leitura e uma pequena cobertura de superfície de configuração:
+
+- **Catálogo de provedores:** ID do provedor, rótulo, recursos, usos de modelos recomendados e nomes de chaves de credenciais necessários de `@agent-native/core/connections`.
+- **Resumo do espaço de trabalho:** contagem de conexões, contagens ativas/concedidas, estado de concessão, nomes de referência de credenciais e rótulos de contas não secretas de `@agent-native/core/workspace-connections`.
+- **Prontidão do provedor:** `ready`, `needs_credentials`, `needs_attention`, `checking`, `disabled` ou `not_configured` via `summarizeWorkspaceConnectionProviderReadiness()`.
+- **Estado de origem:** fontes configuradas localmente no aplicativo, cursores, status de sincronização e próxima ação.
+
+A página Brain's Sources é a implementação de referência. Ele mostra provedores de conexão de espaço de trabalho reutilizáveis ao lado dos registros de origem do Brain, rotula estados de concessão como `connected`, `granted`, `needs_grant` ou `not_connected` e mostra a integridade do provedor como pronto, chaves ausentes, concessão necessária, precisa de reparo ou apenas metadados.
+
+### Construindo um conector reutilizável
+
+Quando um novo provedor deve funcionar em vários modelos:
+
+1. **Metadados do provedor:** adicione ou reutilize um provedor em `@agent-native/core/connections`. Este é o ID estável, o rótulo de exibição, a lista de recursos, os usos recomendados do modelo e os nomes das chaves de credenciais.
+2. **Conexão do espaço de trabalho:** o Dispatch ou outra superfície de configuração do espaço de trabalho armazena metadados seguros, status, escopos, `credentialRefs` e concessões de aplicativos da conta conectada por meio do `@agent-native/core/workspace-connections`.
+3. **Fonte local do aplicativo:** Brain, Analytics, Mail ou outro aplicativo armazena apenas as opções específicas do aplicativo que possui, como canais Slack, repositórios GitHub, filtros de objeto HubSpot, cursores de sincronização ou cadência de pesquisa.
+
+Não duplique o armazenamento OAuth/token em cada aplicativo. O registro de conexão diz "este é Acme Slack e seu token reside em `SLACK_BOT_TOKEN`"; a fonte local do aplicativo diz "Brain pode ingerir `#product` e `#dev-fusion` dessa conexão Slack."
+
+### Configuração do plano de controle de despacho
+
+O Dispatch expõe o plano de controle actions que escreve as mesmas funções de armazenamento compartilhado que um aplicativo poderia chamar diretamente:
+
+```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",
+});
+```
+
+Use `allowedApps: []` somente quando uma conexão estiver disponível para todos os aplicativos no mesmo escopo. Prefira linhas de concessão explícitas para configuração de produção.
+
+### Resolução de credenciais
+
+O código de execução do aplicativo resolve os valores de credenciais do `credentialRefs` concedido por meio do cofre no escopo da solicitação ativa. O `source-credentials.ts` do Brain é a implementação de referência atual: ele lista as conexões do espaço de trabalho para o provedor, verifica `getWorkspaceConnectionAppAccess` para `appId: "brain"`, mescla referências de credenciais em nível de conexão e nível de concessão e lê o primeiro segredo de cofre com escopo correspondente. Outros aplicativos deveriam seguir esse formato em vez de alcançar `process.env`.
+
+## Notas de projeto {#design-notes}
+
+<details>
+Política de promoção do leitor <summary> e caminho para "conectar uma vez, usar em qualquer lugar"</summary>
+
+### Limite local do aplicativo
+
+A fronteira entre conexões compartilhadas e fontes locais de aplicativos é intencional. O que é reutilizável hoje é a identidade do provedor, a resolução de referência de credencial, concessões por aplicativo, prontidão do provedor, metadados de conta seguros e o contrato normalizado entre provedor e leitor. O que ainda não é genérico é a maior parte da leitura API do provedor ao vivo, propriedade do fluxo OAuth, cursores de ingestão, filtros de origem, cadência de sincronização e interpretação de domínio. Eles permanecem no aplicativo que possui o fluxo de trabalho, a menos que uma implementação de leitor seja explicitamente promovida para compartilhada.
+
+Os conectores de origem do aplicativo não devem ler variáveis de ambiente no nível de implantação como um substituto para credenciais de origem do usuário/organização. As variáveis ambientais são globais para a implantação e não expressam concessões de espaço de trabalho.
+
+Os agentes devem seguir uma regra simples: se um usuário solicitar a conexão Slack, GitHub, HubSpot, Gmail, Google Drive, Granola ou outro provedor compartilhado, inspecione primeiro o catálogo de conexões do espaço de trabalho. Se o provedor for `connected`, use-o. Se for `needs_grant`, solicite ou realize a concessão do aplicativo. Se for `needs_credentials`, peça a chave do cofre que falta. Solicite uma nova chave bruta somente quando não existir nenhuma conexão reutilizável.
+
+### Caminho para "conectar uma vez, usar em qualquer lugar"
+
+O catálogo de provedores e o armazenamento de concessões são a base para uma camada de espaço de trabalho mais ampla:
+
+- IDs de provedores e nomes de recursos compartilhados mantêm os modelos alinhados.
+- O inventário no nível do espaço de trabalho pode mostrar quais provedores estão configurados no Brain, Mail, Analytics, Dispatch e aplicativos futuros.
+- As linhas de conexão registram rótulos de contas, status, aplicativos permitidos, referências de credenciais e verificações de integridade sem alterar os IDs de provedor voltados para o modelo.
+- A concessão de linhas permite que o proprietário do espaço de trabalho se conecte uma vez e, em seguida, ative aplicativos individuais à medida que o espaço de trabalho os adota.
+- Os agentes podem encaminhar o trabalho entre aplicativos sabendo quais provedores já estão conectados e quais aplicativos têm concessões.
+- A pesquisa federada pode solicitar provedores com recursos `search`, `docs`, `messages`, `meetings`, `crm` ou `code` em vez de codificar a lista de conectores de cada aplicativo.
+- Leitores específicos do provedor, fluxos de atualização OAuth, pontos de verificação de ingestão e modelos de dados de propriedade do aplicativo podem ser compartilhados posteriormente, mas não estão implícitos em uma conexão de espaço de trabalho hoje.
+
+Mantenha os limites rígidos: os metadados do provedor podem ser exibidos com segurança; os valores das credenciais permanecem no cofre.
+
+</details>

package/docs/content/locales/pt-BR/workspace-management.md

@@ -0,0 +1,175 @@
+---
+title: "Governança do espaço de trabalho"
+description: "Branching, CODEOWNERS, revisão de PR e como o Dispatch lida com a governança em tempo de execução juntamente com a governança em nível git."
+---
+
+# Governança do espaço de trabalho
+
+> **Qual documento do espaço de trabalho?** Esta página aborda a **governança** — quem analisa, aprova e possui o que em vários aplicativos em um único repositório. Para saber o que _é_ um espaço de trabalho (a camada de personalização), consulte [Workspace](/docs/workspace); para o formato de implantação (um monorepo, muitos aplicativos), consulte [Multi-App Workspaces](/docs/multi-app-workspace).
+
+Este guia aborda o lado operacional da execução de um espaço de trabalho nativo do agente: como ramificar, quem revisa o quê, como configurar a propriedade do código e como o plano de controle do Dispatch se ajusta ao seu modelo de governança.
+
+```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}"
+}
+```
+
+## Ramificação
+
+### Ramos de recursos
+
+Use ramificações de recursos de curta duração para todo o trabalho:
+
+```
+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
+```
+
+**Convenções de nomenclatura:**
+
+- **Alterações em um único aplicativo:** `feat/<app>-<description>` ou `fix/<app>-<description>` — por exemplo, `feat/mail-thread-search`, `fix/calendar-recurrence-parse`
+- **Alterações na estrutura:** `feat/core-<description>` ou `fix/core-<description>` — por exemplo, `feat/core-polling-v2`
+- **Alterações de envio:** `feat/dispatch-<description>` — por ex. `feat/dispatch-vault-policies`
+- **Alterações entre aplicativos:** se uma alteração na estrutura exigir atualizações de modelo, faça as duas coisas em um branch para que sejam enviadas atomicamente
+
+Mantenha os galhos de curta duração. As ramificações de longa duração divergem da principal e criam fusões dolorosas, especialmente em um monorepo onde várias equipes fazem push diariamente.
+
+### Ramificação sem desenvolvedor
+
+Nem todo mundo que precisa fazer alterações se sente confortável com o git. [Builder.io](https://www.builder.io) oferece suporte a um modelo de ramificação visual que mapeia ramificações git nos bastidores — útil para alterações de conteúdo e cópia, ajustes de layout, iterações de design e testes A/B sem um ambiente de desenvolvimento.
+
+## Propriedade do código
+
+A governança do código é configurada por alguns arquivos na raiz do repositório:
+
+```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" }
+  ]
+}
+```
+
+O arquivo CODEOWNERS de GitHub atribui automaticamente revisores aos PRs com base em quais arquivos foram alterados. Crie `.github/CODEOWNERS` na raiz do repositório:
+
+```
+# 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
+```
+
+Dicas importantes: use equipes GitHub (`@org/team`), não indivíduos. As alterações na estrutura e no despacho devem sempre exigir a revisão da plataforma. Consulte [GitHub CODEOWNERS docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) para sintaxe glob e padrões de múltiplos proprietários.
+
+Para ativar as revisões necessárias: Configurações → Branches → Proteção de branch para `main` → **Exigir uma solicitação pull antes da fusão** → **Exigir revisão dos proprietários do código**.
+
+## Rotulagem de relações públicas
+
+Rotular PRs automaticamente por aplicativo com `.github/labeler.yml` (trecho):
+
+```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/**
+```
+
+Em seguida, adicione a ação [actions/labeler](https://github.com/actions/labeler) - consulte o README desse repositório para obter o fluxo de trabalho completo YAML. Os rótulos são aplicados automaticamente quando os PRs são abertos ou atualizados.
+
+## Diretrizes para revisão de relações públicas
+
+| Tipo de alteração                           | Quem avalia                                             | O que observar                                                                     |
+| ------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| **Somente aplicativo** (`templates/<app>/`) | É proprietária da equipe do aplicativo                  | Correção de domínio, esquemas de ação                                              |
+| **Estrutura** (`packages/core/`)            | Equipe da plataforma + uma equipe do aplicativo afetado | Alterações importantes, desempenho, compatibilidade com versões anteriores         |
+| **Migrações de esquema**                    | Equipe da plataforma + engenheiro sênior                | Segurança de dados, agnosticismo de dialeto (SQLite + Postgres)                    |
+| **Actions**                                 | Equipe proprietária                                     | Actions são ferramentas de agente AND endpoints HTTP — análise de ambos os ângulos |
+| **A2A entre aplicativos**                   | Ambas as equipes de aplicativos                         | Se você alterar uma interface A2A, os chamadores precisam saber                    |
+| **Enviar cofre/recursos**                   | Equipe da plataforma                                    | Acesso secreto, escopo de concessão, quem recebe o quê                             |
+
+### Trabalho de agente simultâneo
+
+Os espaços de trabalho nativos do agente geralmente têm vários agentes de IA trabalhando na mesma filial simultaneamente. Isso ocorre intencionalmente: os agentes compartilham uma ramificação e enviam push de forma independente.
+
+```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." }
+```
+
+Ao analisar PRs neste ambiente:
+
+- **Não reverta alterações que você não fez** a menos que elas estejam claramente quebradas
+- **Os arquivos podem ser modificados por vários agentes** no mesmo PR — isso é normal
+- **Execute `pnpm run prep`** (typecheck + teste + formato) antes de enviar para detectar problemas de integração entre as alterações dos agentes
+- **Se dois agentes tocarem no mesmo arquivo,** o commit posterior vence. Os conflitos surgem no momento da revisão, não no momento do commit
+- **Corrige bugs em qualquer código do PR,** independentemente de qual agente o escreveu. O PR é revisado como um todo.
+
+## Despacho como governança
+
+O aplicativo [Dispatch](/docs/dispatch) é o plano de controle de tempo de execução do espaço de trabalho. Ele complementa a governança em nível git com governança em tempo de execução:
+
+| Preocupação                                 | Git/GitHub                          | Envio                                                                  |
+| ------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
+| Quem pode alterar o código                  | CODEOWNERS, proteção de ramificação | —                                                                      |
+| Quem pode acessar segredos                  | —                                   | Política do Vault, concessões, fluxo de trabalho de solicitação        |
+| Quais instruções os agentes seguem          | —                                   | Recursos globais do espaço de trabalho (AGENTS.md, instruções, skills) |
+| Quais agentes são compartilhados            | —                                   | Perfis de agente do espaço de trabalho                                 |
+| Inventário de integração                    | —                                   | Catálogo de conexões e integrações do espaço de trabalho               |
+| Aprovação de alteração no tempo de execução | —                                   | Fluxo de aprovação de envio                                            |
+| Trilha de auditoria                         | `git log` / `git blame`             | Auditoria do Vault + envio de registros de auditoria                   |
+| Mensagens e roteamento                      | —                                   | Integração Slack / Telegram                                            |
+
+**Git cuida da governança de código. O Dispatch cuida da governança do tempo de execução.** Não tente replicar fluxos de trabalho git dentro do Dispatch ou vice-versa.
+
+O Dispatch gerencia: segredos do cofre, conexões reutilizáveis do espaço de trabalho, recursos do espaço de trabalho (skills, instruções, perfis de agentes, servidores MCP), aprovações e registros de auditoria. Para configuração de rota de aplicativo público (`workspaceApp.audience`/`publicPaths`/`protectedPaths`), consulte [Multi-App Workspaces — Public app routes](/docs/multi-app-workspace#deployment).
+
+Para o modelo de recursos e caminhos canônicos, consulte [Workspace — Global resources](/docs/workspace#global-resources).
+
+## Lista de verificação de configuração
+
+Para um novo espaço de trabalho, após executar `npx @agent-native/core@latest create`:
+
+**Git e GitHub:**
+
+- [ ] Criar `.github/CODEOWNERS` com propriedade de equipe por aplicativo
+- [ ] Habilite a proteção de ramificação em `main` com revisões obrigatórias do proprietário do código
+- [] Adicionar `.github/labeler.yml` para rotulagem automática de PRs por aplicativo
+- [ ] Crie equipes GitHub para cada aplicativo e a equipe da plataforma
+
+**Envio:**
+
+- [ ] Adicione segredos compartilhados ao cofre (chaves API, credenciais OAuth, etc.)
+- [ ] Manter a política padrão do vault para todos os aplicativos ou mudar para concessões manuais por aplicativo
+- [ ] Sincronize segredos do cofre para enviá-los aos aplicativos
+- [ ] Registre conexões de espaço de trabalho reutilizáveis para contas de provedor compartilhadas e, em seguida,
+      conceder aplicativos como Brain, Analytics, Mail ou Dispatch somente quando necessário
+      essa conta
+- [ ] Adicione skills para todo o espaço de trabalho, instruções de proteção e recursos de referência de marca/empresa por meio da página Recursos. Consulte [Workspace](/docs/workspace#global-resources) para obter a tabela completa de modelos de recursos e o pacote inicial recomendado.
+- [ ] Configure a política de aprovação e os e-mails do aprovador
+- [ ] Configurar SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) para notificações administrativas
+- [ ] Conecte Slack ou Telegram para mensagens no espaço de trabalho
+- [ ] Configurar servidores MCP compartilhados — adicionar recursos de espaço de trabalho `mcp-servers/<name>.json` no Dispatch para concessões de todos os aplicativos ou aplicativos selecionados; use `mcp.config.json` ou [MCP hub mode](/docs/mcp-clients#hub) para implantações de nível inferior