@agent-native/core 0.79.25 → 0.79.27

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

@@ -16,13 +16,75 @@ As conexões do espaço de trabalho são a estrutura primitiva para metadados de
 - **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="Conecte-se uma vez, conceda aplicativos e reutilize credenciais" summary="Uma conexão contém metadados do provedor (nunca segredos) e credentialRefs que apontam para o cofre. As concessões por aplicativo desbloqueiam-no. Os aplicativos leem um único status de prontidão."
-{
-  "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, escopos, configuração &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}"
+<Diagram id="doc-block-110loev" title="Conecte-se uma vez, conceda aplicativos e reutilize credenciais" summary={"Uma conexão contém metadados do provedor (nunca segredos) e credentialRefs que apontam para o cofre. As concessões por aplicativo desbloqueiam-no. Os aplicativos leem um único status de prontidão."}>
+
+```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, escopos, configuração &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;
 }
 ```
 
+</Diagram>
+
 ### Exemplo resolvido: Slack
 
 Conecte Slack uma vez e conceda-o ao Brain and Analytics:
@@ -260,13 +322,71 @@ O cofre de credenciais responde: "Onde o segredo está armazenado, quem pode ace
 
 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="Armazenamento de conexão vs. cofre" summary="O cofre possui o valor secreto. A conexão possui metadados do provedor mais credentialRefs (ponteiros). No tempo de execução, o aplicativo resolve a referência por meio de uma conexão concedida e lê o valor do vault."
-{
-  "html": "<div class=\"diagram-vault\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Armazenamento de conexões</span><div class=\"diagram-box\" data-rough>provider account + metadata<br><small class=\"diagram-muted\">status, escopos, configuração</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\">Ação do app</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\">nunca retornado ao agente ou à 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}"
+<Diagram id="doc-block-ft9j7t" title={"Armazenamento de conexão vs. cofre"} summary={"O cofre possui o valor secreto. A conexão possui metadados do provedor mais credentialRefs (ponteiros). No tempo de execução, o aplicativo resolve a referência por meio de uma conexão concedida e lê o valor do vault."}>
+
+```html
+<div class="diagram-vault">
+  <div class="diagram-panel col" data-rough>
+    <span class="diagram-pill accent">Armazenamento de conexões</span>
+    <div class="diagram-box" data-rough>
+      provider account + metadata<br /><small class="diagram-muted"
+        >status, escopos, configuração</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">Ação do app</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"
+        >nunca retornado ao agente ou à 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;
 }
 ```
 
+</Diagram>
+
 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.

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

@@ -9,13 +9,59 @@ description: "Branching, CODEOWNERS, revisão de PR e como o Dispatch lida com a
 
 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="Dois planos de governança" summary="Git governa o código; Dispatch rege o tempo de execução. Eles são complementares – não reproduzam um dentro do outro."
-{
-  "html": "<div class=\"gov\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Git e GitHub</span><strong>Governança de código</strong><div class=\"gov-list\"><span class=\"diagram-pill\">CODEOWNERS</span><span class=\"diagram-pill\">branch protection</span><span class=\"diagram-pill\">Revisão de PR</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}"
+<Diagram id="doc-block-ps96tz" title={"Dois planos de governança"} summary={"Git governa o código; Dispatch rege o tempo de execução. Eles são complementares – não reproduzam um dentro do outro."}>
+
+```html
+<div class="gov">
+  <div class="diagram-card">
+    <span class="diagram-pill accent">Git e GitHub</span
+    ><strong>Governança de código</strong>
+    <div class="gov-list">
+      <span class="diagram-pill">CODEOWNERS</span
+      ><span class="diagram-pill">branch protection</span
+      ><span class="diagram-pill">Revisão de PR</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;
 }
 ```
 
+</Diagram>
+
 ## Ramificação
 
 ### Ramos de recursos

package/docs/content/locales/pt-BR/workspace.mdx

@@ -11,13 +11,68 @@ Todo aplicativo nativo do agente vem com um **espaço de trabalho**: a camada de
 
 A diferença: **são linhas SQL, não arquivos do sistema de arquivos.** Cada usuário obtém seu próprio espaço de trabalho armazenado no banco de dados. Não há dev-box para ativar, nem contêiner por usuário, nem arquivos para montar. Um SaaS multilocatário pode oferecer a cada usuário um agente totalmente personalizável, essencialmente gratuito, porque tudo isso são linhas – memória pessoal, servidores MCP pessoais, skills pessoais, subagentes pessoais – e a base de código compartilhada hospeda todos eles de uma vez.
 
-```an-diagram title="Um espaço de trabalho Claude-Code, mas armazenado em SQL" summary="A mesma camada de personalização — instruções, habilidades, memória, agentes, trabalhos, MCP — exceto que cada arquivo é uma linha em um banco de dados multilocatário compartilhado."
-{
-  "html": "<div class=\"ws-map\"><div class=\"diagram-card cc\"><span class=\"diagram-pill warn\">Claude Code / Codex</span><small class=\"diagram-muted\">~/.claude/ on a local disk</small><div class=\"ws-files\"><span class=\"diagram-box\">CLAUDE.md</span><span class=\"diagram-box\">skills/</span><span class=\"diagram-box\">memory</span><span class=\"diagram-box\">mcp.json</span></div><small class=\"diagram-muted\">one codebase per developer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card an\"><span class=\"diagram-pill accent\">Workspace agent-native</span><small class=\"diagram-muted\">rows in one banco de dados SQL</small><div class=\"ws-rows\"><span class=\"diagram-pill\">AGENTS.md</span><span class=\"diagram-pill\">skills/&hellip;</span><span class=\"diagram-pill\">memory/&hellip;</span><span class=\"diagram-pill\">mcp-servers/&hellip;</span></div><small class=\"diagram-muted\">uma base de código, muitos usuários, com escopo <code>u:&lt;email&gt;:&hellip;</code></small></div></div>",
-  "css": ".ws-map{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ws-map .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:220px}.ws-map .ws-files,.ws-map .ws-rows{display:flex;flex-wrap:wrap;gap:6px;margin:4px 0}.ws-map .diagram-arrow{font-size:24px}"
+<Diagram id="doc-block-1l7jkfd" title={"Um espaço de trabalho Claude-Code, mas armazenado em SQL"} summary={"A mesma camada de personalização — instruções, habilidades, memória, agentes, trabalhos, MCP — exceto que cada arquivo é uma linha em um banco de dados multilocatário compartilhado."}>
+
+```html
+<div class="ws-map">
+  <div class="diagram-card cc">
+    <span class="diagram-pill warn">Claude Code / Codex</span
+    ><small class="diagram-muted">~/.claude/ on a local disk</small>
+    <div class="ws-files">
+      <span class="diagram-box">CLAUDE.md</span
+      ><span class="diagram-box">skills/</span
+      ><span class="diagram-box">memory</span
+      ><span class="diagram-box">mcp.json</span>
+    </div>
+    <small class="diagram-muted">one codebase per developer</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card an">
+    <span class="diagram-pill accent">Workspace agent-native</span
+    ><small class="diagram-muted">rows in one banco de dados SQL</small>
+    <div class="ws-rows">
+      <span class="diagram-pill">AGENTS.md</span
+      ><span class="diagram-pill">skills/&hellip;</span
+      ><span class="diagram-pill">memory/&hellip;</span
+      ><span class="diagram-pill">mcp-servers/&hellip;</span>
+    </div>
+    <small class="diagram-muted"
+      >uma base de código, muitos usuários, com escopo
+      <code>u:&lt;email&gt;:&hellip;</code></small
+    >
+  </div>
+</div>
+```
+
+```css
+.ws-map {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+.ws-map .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 16px 18px;
+  flex: 1;
+  min-width: 220px;
+}
+.ws-map .ws-files,
+.ws-map .ws-rows {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin: 4px 0;
+}
+.ws-map .diagram-arrow {
+  font-size: 24px;
 }
 ```
 
+</Diagram>
+
 | Código Claude / Codex                | Espaço de trabalho nativo do agente                                    |
 | ------------------------------------ | ---------------------------------------------------------------------- |
 | Arquivos em seu disco local          | Linhas em um banco de dados SQL compartilhado                          |
@@ -51,13 +106,61 @@ Os caminhos canônicos que controlam como o agente usa cada recurso:
 
 Esses caminhos se aplicam a todos os três escopos: espaço de trabalho, organização/aplicativo e pessoal. O escopo posterior vence quando o mesmo caminho existe em vários níveis.
 
-```an-diagram title="Três escopos, um arquivo eficaz" summary="O tempo de execução resolve o mesmo caminho no espaço de trabalho, no aplicativo e nos escopos pessoais na leitura – o escopo mais específico vence."
-{
-  "html": "<div class=\"ws-stack\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Workspace</span><small class=\"diagram-muted\">padrões da empresa pelo Dispatch</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Organização / app</span><small class=\"diagram-muted\">team override for one app</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Personal</span><small class=\"diagram-muted\">per-user override &mdash; wins</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Effective <code>context/brand.md</code></div></div>",
-  "css": ".ws-stack{display:flex;flex-direction:column;align-items:flex-start;gap:8px}.ws-stack .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px;min-width:280px}.ws-stack .diagram-arrow{font-size:20px;align-self:center}.ws-stack code{font-size:.85em}.ws-stack .diagram-box{align-self:center;margin-top:4px}"
+<Diagram id="doc-block-e47wl0" title={"Três escopos, um arquivo eficaz"} summary={"O tempo de execução resolve o mesmo caminho no espaço de trabalho, no aplicativo e nos escopos pessoais na leitura – o escopo mais específico vence."}>
+
+```html
+<div class="ws-stack">
+  <div class="diagram-card">
+    <span class="diagram-pill">Workspace</span
+    ><small class="diagram-muted">padrões da empresa pelo Dispatch</small
+    ><code>context/brand.md</code>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">Organização / app</span
+    ><small class="diagram-muted">team override for one app</small
+    ><code>context/brand.md</code>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill accent">Personal</span
+    ><small class="diagram-muted">per-user override &mdash; wins</small
+    ><code>context/brand.md</code>
+  </div>
+  <div class="diagram-arrow diagram-accent" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box ok">Effective <code>context/brand.md</code></div>
+</div>
+```
+
+```css
+.ws-stack {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 8px;
+}
+.ws-stack .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 12px 16px;
+  min-width: 280px;
+}
+.ws-stack .diagram-arrow {
+  font-size: 20px;
+  align-self: center;
+}
+.ws-stack code {
+  font-size: 0.85em;
+}
+.ws-stack .diagram-box {
+  align-self: center;
+  margin-top: 4px;
 }
 ```
 
+</Diagram>
+
 ## Primeiros passos: um passo a passo de 1 minuto {#getting-started}
 
 Mude o comportamento do agente em 60 segundos.

package/docs/content/locales/pt-BR/writing-agent-instructions.mdx

@@ -7,13 +7,55 @@ description: "Como escrever ótimas instruções de agente para um aplicativo ou
 
 O comportamento do agente em um aplicativo nativo do agente é tão bom quanto as instruções fornecidas. Três superfícies trazem essa orientação: `AGENTS.md` (o mapa), skills (os mergulhos profundos) e descrições de ação/ferramenta (como o agente escolhe a ferramenta certa). Escreva cada um para recuperação rápida, não para prosa.
 
-```an-diagram title="Três superfícies de autoria + uma superfície de tempo de execução" summary="AGENTS.md e descrições de ferramentas são carregadas a cada turno; carga de habilidades sob demanda; application_state é escrito ao vivo pela sua UI."
-{
-  "html": "<div class=\"diagram-surfaces\"><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Cada turno</span><strong>AGENTS.md</strong><small class=\"diagram-muted\">o mapa: propósito, regras centrais, chaves de estado, índice de ações + skills</small></div><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Cada turno</span><strong>Descrições de ferramentas</strong><small class=\"diagram-muted\">orienta a seleção de ferramentas — uma frase precisa cada</small></div><div class=\"diagram-card ondemand\" data-rough><span class=\"diagram-pill\">Sob demanda</span><strong>Habilidades</strong><small class=\"diagram-muted\">guia aprofundado, carregado quando a descrição dispara</small></div><div class=\"diagram-card runtime\" data-rough><span class=\"diagram-pill ok\">Live</span><strong>application_state</strong><small class=\"diagram-muted\">escrito pela sua UI: navegação, seleção, foco</small></div></div>",
-  "css": ".diagram-surfaces{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.diagram-surfaces .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+<Diagram id="doc-block-dgl70m" title={"Três superfícies de autoria + uma superfície de tempo de execução"} summary={"AGENTS.md e descrições de ferramentas são carregadas a cada turno; carga de habilidades sob demanda; application_state é escrito ao vivo pela sua UI."}>
+
+```html
+<div class="diagram-surfaces">
+  <div class="diagram-card always" data-rough>
+    <span class="diagram-pill accent">Cada turno</span><strong>AGENTS.md</strong
+    ><small class="diagram-muted"
+      >o mapa: propósito, regras centrais, chaves de estado, índice de ações +
+      skills</small
+    >
+  </div>
+  <div class="diagram-card always" data-rough>
+    <span class="diagram-pill accent">Cada turno</span
+    ><strong>Descrições de ferramentas</strong
+    ><small class="diagram-muted"
+      >orienta a seleção de ferramentas — uma frase precisa cada</small
+    >
+  </div>
+  <div class="diagram-card ondemand" data-rough>
+    <span class="diagram-pill">Sob demanda</span><strong>Habilidades</strong
+    ><small class="diagram-muted"
+      >guia aprofundado, carregado quando a descrição dispara</small
+    >
+  </div>
+  <div class="diagram-card runtime" data-rough>
+    <span class="diagram-pill ok">Live</span><strong>application_state</strong
+    ><small class="diagram-muted"
+      >escrito pela sua UI: navegação, seleção, foco</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-surfaces {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+}
+.diagram-surfaces .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
 }
 ```
 
+</Diagram>
+
 ## Mantenha AGENTS.md pequeno e passível de leitura {#small-agents-md}
 
 `AGENTS.md` é carregado como orientação. Deve ser a menor coisa que permite ao agente agir corretamente, com tudo profundamente inserido em skills. Procure estas seções e pouco mais:

package/docs/content/locales/zh-CN/a2a-protocol.mdx

@@ -20,13 +20,53 @@ A2A 是此框架中跨应用程序委派的基础 - 最显着的是 [Dispatch](/
 - **任务** - 每条消息都会创建一个具有生命周期的任务（已提交、正在工作、已完成、失败、已取消）
 - **JWT 承载身份验证** - 生产 A2A 需要 `A2A_SECRET` 或显式遗留 `apiKeyEnv`
 
-```an-diagram title="一名代理人将工作交给另一名代理人" summary="邮件代理发现分析代理的卡，发送 JSON-RPC 消息，并返回已完成的任务。"
-{
-  "html": "<div class=\"diagram-handoff\"><div class=\"diagram-card\"><strong>邮件 Agent</strong><small class=\"diagram-muted\">needs analytics</small></div><div class=\"diagram-col\"><div class=\"diagram-pill\">GET /.well-known/agent-card.json</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">POST /_agent-native/a2a<br><small class=\"diagram-muted\">message/send</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div><div class=\"diagram-pill ok\">任务 · 已完成</div></div><div class=\"diagram-card\" data-rough><strong>分析 Agent</strong><small class=\"diagram-muted\">运行 run-query，返回结果</small></div></div>",
-  "css": ".diagram-handoff{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-handoff .diagram-col{display:flex;flex-direction:column;align-items:center;gap:6px}.diagram-handoff .diagram-arrow{font-size:20px;line-height:1}"
+<Diagram id="doc-block-gtq7z8" title={"一名代理人将工作交给另一名代理人"} summary={"邮件代理发现分析代理的卡，发送 JSON-RPC 消息，并返回已完成的任务。"}>
+
+```html
+<div class="diagram-handoff">
+  <div class="diagram-card">
+    <strong>邮件 Agent</strong
+    ><small class="diagram-muted">needs analytics</small>
+  </div>
+  <div class="diagram-col">
+    <div class="diagram-pill">GET /.well-known/agent-card.json</div>
+    <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+    <div class="diagram-pill accent">
+      POST /_agent-native/a2a<br /><small class="diagram-muted"
+        >message/send</small
+      >
+    </div>
+    <div class="diagram-arrow diagram-muted" aria-hidden="true">&larr;</div>
+    <div class="diagram-pill ok">任务 · 已完成</div>
+  </div>
+  <div class="diagram-card" data-rough>
+    <strong>分析 Agent</strong
+    ><small class="diagram-muted">运行 run-query，返回结果</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-handoff {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+.diagram-handoff .diagram-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+}
+.diagram-handoff .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 ## 服务器设置 {#server-setup}
 
 大多数模板通过框架代理聊天插件获取 A2A。如果您自己安装它，请在服务器插件中调用 `mountA2A()`：
@@ -176,14 +216,62 @@ JSON-RPC 2.0 endpoint for `message/send`, `message/stream`, `tasks/get`, and `ta
 
 当使用 `async: true` 调用 `message/send` 时，JSON-RPC 处理程序会将任务排入队列，并将 POST 自触发到内部 `/_agent-native/a2a/_process-task` 路由，以便处理程序在具有自己的完全超时的新函数执行中运行。该路由使用绑定到任务 ID 的 HMAC 令牌进行身份验证（5 分钟生存期，使用 `A2A_SECRET` 签名）。它安装在 `/_agent-native/a2a` JSON-RPC 路由之前，因此 h3 的前缀匹配不会吞噬它。
 
-```an-diagram title="无服务器上的异步任务生命周期" summary="async:true 在几毫秒内返回工作，然后在调用者轮询时重新执行运行代理循环。"
-{
-  "html": "<div class=\"diagram-async\"><div class=\"diagram-box\" data-rough>message/send<br><small class=\"diagram-muted\">async: true</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill\">enqueue task</span><span class=\"diagram-pill warn\">return working</span><small class=\"diagram-muted\">约毫秒级</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>自触发 POST /_agent-native/a2a/_process-task<br><small class=\"diagram-muted\">HMAC token · 全新执行 · 完整超时</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">tasks/get (poll)</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">completed</div></div></div>",
-  "css": ".diagram-async{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-async .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:6px}.diagram-async .diagram-col{display:flex;flex-direction:column;align-items:center;gap:6px}.diagram-async .diagram-arrow{font-size:20px;line-height:1}",
-  "caption": "A recurring sweeper re-claims any task left in flight if the function execution dies mid-run."
+<Diagram id="doc-block-m7jmcy" title={"无服务器上的异步任务生命周期"} summary={"async:true 在几毫秒内返回工作，然后在调用者轮询时重新执行运行代理循环。"} caption="A recurring sweeper re-claims any task left in flight if the function execution dies mid-run.">
+
+```html
+<div class="diagram-async">
+  <div class="diagram-box" data-rough>
+    message/send<br /><small class="diagram-muted">async: true</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel">
+    <span class="diagram-pill">enqueue task</span
+    ><span class="diagram-pill warn">return working</span
+    ><small class="diagram-muted">约毫秒级</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-box" data-rough>
+    自触发 POST /_agent-native/a2a/_process-task<br /><small
+      class="diagram-muted"
+      >HMAC token · 全新执行 · 完整超时</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-pill">tasks/get (poll)</div>
+    <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
+    <div class="diagram-pill ok">completed</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-async {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-async .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+}
+.diagram-async .diagram-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+}
+.diagram-async .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 > [!IMPORTANT]
 > **无服务器 Webhook 和网关超时：**
 > 托管环境网关（例如 Netlify、Vercel 或 Cloudflare Pages）对面向公众的 HTTP 路由施加严格的执行限制（通常为 10 到 30 秒）。由于代理循环可能需要大量时间来运行查询、获取上下文和执行工具，因此在调用 A2A 端点或处理外部 webhooks 时，您**必须使用 `async: true`**。这会立即将 `working` 状态返回到 API 网关，仅保持连接打开几毫秒，而自触发的 `/process-task` POST 在后台执行代理循环。不要阻止主 HTTP 请求等待代理循环完成。

package/docs/content/locales/zh-CN/actions.mdx

@@ -19,13 +19,74 @@ Actions 是您的应用所做的任何事情的唯一事实来源。使用 `defi
 如果您正在决定是否在聊天中、在聊天中无头公开操作
 嵌入式 sidecar，或作为完整的应用屏幕，请参阅 [Agent Surfaces](/docs/agent-surfaces)。
 
-```an-diagram title="一个定义，七个消费者" summary="单个 defineAction() 扇出到每个表面 - 代理、UI、HTTP、MCP、A2A 和 CLI - 具有一个经过验证的模式和一个 run() 主体。"
-{
-  "html": "<div class=\"diagram-fanout\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">defineAction()</span><small class=\"diagram-muted\">schema + run()，只定义一次</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><div class=\"diagram-node\">Agent 工具<br><small class=\"diagram-muted\">上下文中的 JSON Schema</small></div><div class=\"diagram-node\">React 钩子<br><small class=\"diagram-muted\">useActionQuery/Mutation</small></div><div class=\"diagram-node\">callAction()<br><small class=\"diagram-muted\">命令式客户端</small></div><div class=\"diagram-node\">HTTP<br><small class=\"diagram-muted\">/_agent-native/actions/:name</small></div><div class=\"diagram-node\">MCP 工具<br><small class=\"diagram-muted\">外部主机</small></div><div class=\"diagram-node\">A2A 工具<br><small class=\"diagram-muted\">其他 agent-native 应用</small></div><div class=\"diagram-node\">CLI<br><small class=\"diagram-muted\">pnpm action &lt;name&gt;</small></div></div></div>",
-  "css": ".diagram-fanout{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fanout .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-fanout .diagram-arrow{font-size:22px;line-height:1}.diagram-fanout .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+<Diagram id="doc-block-1dnenk6" title={"一个定义，七个消费者"} summary={"单个 defineAction() 扇出到每个表面 - 代理、UI、HTTP、MCP、A2A 和 CLI - 具有一个经过验证的模式和一个 run() 主体。"}>
+
+```html
+<div class="diagram-fanout">
+  <div class="diagram-panel center" data-rough>
+    <span class="diagram-pill accent">defineAction()</span
+    ><small class="diagram-muted">schema + run()，只定义一次</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-grid">
+    <div class="diagram-node">
+      Agent 工具<br /><small class="diagram-muted"
+        >上下文中的 JSON Schema</small
+      >
+    </div>
+    <div class="diagram-node">
+      React 钩子<br /><small class="diagram-muted"
+        >useActionQuery/Mutation</small
+      >
+    </div>
+    <div class="diagram-node">
+      callAction()<br /><small class="diagram-muted">命令式客户端</small>
+    </div>
+    <div class="diagram-node">
+      HTTP<br /><small class="diagram-muted"
+        >/_agent-native/actions/:name</small
+      >
+    </div>
+    <div class="diagram-node">
+      MCP 工具<br /><small class="diagram-muted">外部主机</small>
+    </div>
+    <div class="diagram-node">
+      A2A 工具<br /><small class="diagram-muted">其他 agent-native 应用</small>
+    </div>
+    <div class="diagram-node">
+      CLI<br /><small class="diagram-muted">pnpm action &lt;name&gt;</small>
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fanout {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-fanout .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  padding: 14px 16px;
+}
+.diagram-fanout .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-fanout .diagram-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 8px;
 }
 ```
 
+</Diagram>
+
 如果 UI 和代理都需要做某事，请采取行动 - 而不是自定义
 路线。对于何时路由型协议才是正确的调用，请参阅[首选 Actions
 对于应用程序操作](/docs/server#actions-first)。