@agent-native/core 0.87.0 → 0.90.1

package/docs/content/locales/pt-BR/agent-native-toolkit.mdx

@@ -0,0 +1,103 @@
+---
+title: "Toolkit"
+description: "Reusable app-building primitives that sit between @agent-native/core and template apps."
+---
+
+# Toolkit
+
+`@agent-native/core` owns the foundational runtime: actions, app state, auth,
+SQL, server plugins, agent chat, sharing access checks, and collaboration
+transport. `@agent-native/toolkit` owns reusable app-building pieces that sit on
+top of that runtime: UI primitives, app-local adapters, shell helpers, sharing
+badges, and collaboration UI.
+
+Apps should compose those pieces through local adapters. That keeps app UI easy
+to customize without copying Toolkit implementation code.
+
+<WireframeBlock id="doc-block-toolkit-layering">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:520px;box-sizing:border-box;padding:48px 36px;display:flex;align-items:center;justify-content:center'><div style='width:min(900px,100%);display:grid;grid-template-columns:1fr;gap:18px'><div class='wf-card' style='padding:22px 24px'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>App</strong><p class='wf-muted' style='margin:6px 0 0'>Domain routes, actions, local UI adapters, product-specific views</p></div><span class='wf-pill'>@/components/ui/button</span></div></div><div class='wf-card' style='padding:22px 24px;border-color:hsl(var(--primary))'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>Toolkit</strong><p class='wf-muted' style='margin:6px 0 0'>Reusable primitives, collab UI, sharing UI, app shell hooks</p></div><span class='wf-pill'>ToolkitProvider</span></div><div style='display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin-top:16px'><span class='wf-pill'>UI</span><span class='wf-pill'>Collab UI</span><span class='wf-pill'>Sharing UI</span><span class='wf-pill'>Shell</span></div></div><div class='wf-card' style='padding:22px 24px'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>Core</strong><p class='wf-muted' style='margin:6px 0 0'>Actions, SQL, auth, sharing runtime, Yjs transport, app state</p></div><span class='wf-pill'>@agent-native/core</span></div></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## What Ships Today {#what-ships-today}
+
+- **UI primitives**: shadcn-style components under
+  `@agent-native/toolkit/ui/*`.
+- **App adapters**: template-local wrappers such as
+  `@/components/ui/button` that re-export Toolkit primitives until an app wants
+  to customize them.
+- **ToolkitProvider**: an override layer that lets reusable Toolkit UI use an
+  app's local primitives, starting with `Button`.
+- **Collaboration UI**: presence avatars, live cursors, remote selection rings,
+  recent edit highlights, and agent presence chips under
+  `@agent-native/toolkit/collab-ui`.
+- **Sharing UI**: the reusable `VisibilityBadge` under
+  `@agent-native/toolkit/sharing`.
+- **Shell and hooks**: app-shell header actions plus shared hooks such as
+  `useIsMobile` and `useToast`.
+
+## Compatibility {#compatibility}
+
+Existing imports from `@agent-native/core/client` keep working. Core now exposes
+thin re-export shims for Toolkit-owned visual pieces while keeping runtime
+behavior in core.
+
+Those core shims are temporary migration support, not the long-term dependency
+direction. The next major can remove them; after that, reusable app-building
+packages should import Toolkit directly, and behaviorful Toolkit kits may compose
+core runtime APIs as peer/runtime dependencies instead of pushing more UI back
+into core.
+
+Extract future behaviorful kits one at a time before broadening the split.
+Sharing is the first candidate to validate that model because it exercises
+access checks, action-backed data, and share-link UI together.
+
+That means this keeps working:
+
+```tsx
+import { PresenceBar, VisibilityBadge } from "@agent-native/core/client";
+```
+
+New reusable app code should prefer Toolkit or app-local adapters:
+
+```tsx
+import { PresenceBar } from "@agent-native/toolkit/collab-ui";
+import { Button } from "@/components/ui/button";
+```
+
+## Boundary {#boundary}
+
+Move code into Toolkit when it is reusable app-building UI or a pure UI contract.
+Keep code in core when it owns access control, SQL, actions, request context,
+Yjs transport, auth, or other runtime guarantees.
+
+Good Toolkit candidates:
+
+- Components that render the same interaction across apps.
+- Display-only helpers and structural prop types.
+- Base components that receive data and callbacks from an app or core wrapper.
+- App-shell hooks and adapters that do not own domain data.
+
+Keep app-local:
+
+- Domain-specific workflows.
+- Resource-specific mutations and routes.
+- Custom visual systems an app intentionally owns.
+
+Keep core-owned:
+
+- Sharing actions and access checks.
+- Collaboration storage, awareness transport, and Yjs document sync.
+- Auth, sessions, app state, SQL, and server plugins.
+
+## Pages {#pages}
+
+- [UI Primitives](/docs/toolkit-ui)
+- [App Adapters](/docs/toolkit-app-adapters)
+- [Collaboration UI](/docs/toolkit-collaboration-ui)
+- [Sharing UI](/docs/toolkit-sharing-ui)
+- [Shell & Hooks](/docs/toolkit-shell-hooks)

package/docs/content/locales/pt-BR/cloneable-saas.mdx

@@ -1,19 +1,19 @@
 ---
-title: "Modelos"
+title: "Apps"
 description: "Fork um produto SaaS funcional e torne-o seu - agente incluído."
 ---
 
-# Modelos
+# Apps
 
-Deseja enviar sua própria ferramenta de análise baseada em IA? Cliente de e-mail? Construtor de formulários? Escolha um modelo e você terá um SaaS funcional em minutos: agente, banco de dados, autenticação e pipeline de implantação já conectados.
+Deseja enviar sua própria ferramenta de análise baseada em IA? Cliente de e-mail? Construtor de formulários? Escolha um app de exemplo e você terá um SaaS funcional em minutos: agente, banco de dados, autenticação e pipeline de implantação já conectados.
 
-A maioria dos "modelos" oferece um andaime em branco e uma longa lista TODO. O agente nativo inverte isso. Cada um deles é um **produto completo de nível SaaS** — já executável no primeiro dia, já disponível para entrega e inteiramente seu para personalizar, marcar e implantar. Pense neles como SaaS clonáveis, não como kits iniciais: você está criando um produto acabado, e não olhando para um padrão.
+A maioria dos modelos iniciais oferece um andaime em branco e uma longa lista TODO. O agente nativo inverte isso. Cada app de exemplo é um **produto completo de nível SaaS** — já executável no primeiro dia, já disponível para entrega e inteiramente seu para personalizar, marcar e implantar. Pense neles como SaaS clonáveis, não como kits iniciais: você está criando um produto acabado, e não olhando para um padrão.
 
-## Modelos disponíveis {#catalog}
+## Apps de exemplo {#catalog}
 
 Cada um é um aplicativo real que você pode usar hoje e a plataforma de lançamento para sua própria versão.
 
-| Modelo                                    | O que é                                                                                                                                      |
+| App                                       | O que é                                                                                                                                      |
 | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | [**Chat**](/docs/template-chat)           | Aplicativo mínimo de bate-papo com threads duráveis, actions, autenticação e um caminho limpo para UI personalizado ou seu próprio back-end. |
 | [**Mail**](/docs/template-mail)           | Um super-humano nativo do agente. Caixa de entrada, marcadores, triagem de IA, teclado, rascunhos e envios por meio do agente.               |
@@ -35,16 +35,16 @@ Veja o catálogo completo em [Apps](/apps) ou vá direto para um. Por exemplo, [
 
 ## O que você ganha imediatamente {#what-you-get}
 
-Cada modelo vem com peças que normalmente levam meses para serem construídas:
+Cada app de exemplo vem com peças que normalmente levam meses para serem construídas:
 
 - **Um agente funcional** — já conectado ao aplicativo, já capaz de capturar actions em seus dados, já ciente do contexto sobre o que você está vendo. Veja [Messaging the agent](/docs/messaging) para saber como funciona.
 - **Auth** — login, sessões, organizações, isolamento multilocatário. Já pronto.
-- **Um banco de dados** — cada modelo tem seu esquema, consultas e migrações prontos para uso. Traga seu próprio banco de dados SQL (Postgres, SQLite, Turso, D1) — a estrutura se adapta.
+- **Um banco de dados** — cada app de exemplo tem seu esquema, consultas e migrações prontos para uso. Traga seu próprio banco de dados SQL (Postgres, SQLite, Turso, D1) — a estrutura se adapta.
 - **UI em tempo real** — a tela permanece sincronizada com o que o agente faz. Clique em "rascunhar um e-mail" no bate-papo e veja o rascunho aparecer na sua caixa de entrada imediatamente.
 - **Pronto para implantação** — envie para Netlify, Vercel, Cloudflare, AWS ou qualquer outro lugar que execute Node. Sem dependência de fornecedor.
 - **Ganchos de branding** — nome, cores, logotipo e cópia são fáceis de alterar.
 
-Esta não é uma afirmação teórica. O autor da estrutura executa sua caixa de entrada real no modelo Mail, seu calendário real no modelo Calendário e suas análises reais no modelo Analytics. Os modelos são softwares de driver diário.
+Esta não é uma afirmação teórica. O autor da estrutura executa sua caixa de entrada real no app Mail, seu calendário real no app Calendar e suas análises reais no app Analytics. Esses apps são softwares de uso diário.
 
 ## O que você faz {#what-you-do}
 
@@ -56,7 +56,7 @@ O caminho de "Quero meu próprio SaaS" até "Tenho meu próprio SaaS" é curto:
 <div class="diagram-fork">
   <div class="diagram-card">
     <span class="diagram-pill">1</span><strong>Pick</strong
-    ><small class="diagram-muted">a complete template</small>
+    ><small class="diagram-muted">um app completo</small>
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card">
@@ -98,8 +98,8 @@ O caminho de "Quero meu próprio SaaS" até "Tenho meu próprio SaaS" é curto:
 
 </Diagram>
 
-1. **Escolha um modelo.** Use o seletor CLI ou navegue nos documentos e escolha um para começar.
-2. **Marque.** Altere o nome, as cores, o logotipo e a cópia. A maioria dos modelos expõe isso em um único arquivo de configuração.
+1. **Escolha um app de exemplo.** Use o seletor CLI ou navegue nos documentos e escolha um para começar.
+2. **Marque.** Altere o nome, as cores, o logotipo e a cópia. A maioria dos apps de exemplo expõe isso em um único arquivo de configuração.
 3. **Personalize.** Peça ao agente para adicionar a coluna que você precisa, altere a forma como os grupos de caixa de entrada, conecte-se ao seu API interno, adicione uma nova visualização. O agente edita o código; você analisa a diferença.
 4. **Envie.** Execute o comando de implantação. Agora você tem seu próprio SaaS de produção em seu próprio domínio.
 
@@ -159,7 +159,7 @@ O resultado: flexibilidade em nível de código Claude para cada usuário, com e
 
 ## Não quer desembolsar? {#hosted}
 
-Você não precisa. Cada modelo também está disponível como um aplicativo hospedado em `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com` e assim por diante. Use a versão hospedada gratuitamente ou paga; bifurque apenas quando quiser alterar algo que a versão hospedada não expõe.
+Você não precisa. Cada app de exemplo também está disponível como um aplicativo hospedado em `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com` e assim por diante. Use a versão hospedada gratuitamente ou paga; bifurque apenas quando quiser alterar algo que a versão hospedada não expõe.
 
 ## Experimente com habilidade {#try-with-a-skill}
 
@@ -168,10 +168,10 @@ Não está pronto para montar o andaime? Você pode adicionar superpoderes nativ
 ## Com base nisso
 
 - [**Getting Started**](/docs/getting-started) — crie uma app chat-first, adicione uma action, renderize resultado estruturado e evolua para uma página
-- [**Messaging the agent**](/docs/messaging) — como os usuários (e você) conversam com o agente que acompanha cada modelo
-- [**Multi-App Workspace**](/docs/multi-app-workspace) — agrupa vários modelos em um espaço de trabalho que compartilha autenticação, marca e agente
-- [**Dispatch**](/docs/template-dispatch) — o modelo do plano de controle do espaço de trabalho
-- [**Creating Templates**](/docs/creating-templates) — crie e publique seu próprio modelo
+- [**Messaging the agent**](/docs/messaging) — como os usuários (e você) conversam com o agente que acompanha cada app
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — agrupa vários apps em um espaço de trabalho que compartilha autenticação, marca e agente
+- [**Dispatch**](/docs/template-dispatch) — o app do plano de controle do espaço de trabalho
+- [**Creating Templates**](/docs/creating-templates) — crie e publique seu próprio modelo de app
 
 ### Para desenvolvedores {#dev-details}
 
@@ -181,10 +181,10 @@ Se você estiver montando um andaime agora, o comando CLI é:
 npx @agent-native/core@latest create my-platform
 ```
 
-Você receberá um seletor de seleção múltipla. Escolha um aplicativo (autônomo) ou vários (espaço de trabalho — os aplicativos compartilham autenticação, marca, configuração do agente e banco de dados). Cada modelo escolhido é estruturado em `apps/<name>/` com todos os arquivos que você precisa. Para uma automação sem UI no navegador em vez de um modelo UI, use `npx @agent-native/core@latest create my-agent --headless`.
+Você receberá um seletor de seleção múltipla. Escolha um aplicativo (autônomo) ou vários (espaço de trabalho — os aplicativos compartilham autenticação, marca, configuração do agente e banco de dados). Cada app escolhido é estruturado em `apps/<name>/` com todos os arquivos que você precisa. Para uma automação sem UI no navegador em vez de uma UI de app, use `npx @agent-native/core@latest create my-agent --headless`.
 
 Preencha `.env` (principalmente `ANTHROPIC_API_KEY` e `DATABASE_URL`), `pnpm install`, `pnpm dev` e funciona. Sem "TODO: implementar login", sem rotas de espaço reservado.
 
 Destinos de implantação: qualquer host compatível com Nitro (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) e qualquer banco de dados SQL compatível com Drizzle (SQLite, Postgres, Turso, D1, Supabase, Neon). Para espaços de trabalho, `npx @agent-native/core@latest deploy` cria todos os aplicativos de uma vez e os envia para uma única origem. Consulte [Deployment](/docs/deployment).
 
-Para criar e publicar seu próprio modelo, consulte [Creating Templates](/docs/creating-templates).
+Para criar e publicar seu próprio modelo de app, consulte [Creating Templates](/docs/creating-templates).

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

@@ -25,7 +25,9 @@ Evite importar componentes UI do pacote `@agent-native/core` simples. Usar
 `@agent-native/core/client` ou um subcaminho `@agent-native/core/client/*` em foco
 para que os empacotadores escolham a entrada segura para o navegador.
 
-Use `@agent-native/toolkit` para peças reutilizáveis de construção de aplicativos que não fazem parte do contrato fundamental do runtime: primitivas UI no estilo shadcn, hooks compartilhados, helpers simples de shell do app e outros módulos de composição de templates. Core mantém reexports de compatibilidade durante a transição, mas novo código de templates e apps deve importar módulos do toolkit diretamente:
+Use `@agent-native/toolkit` para peças reutilizáveis de construção de aplicativos que não fazem parte do contrato fundamental do runtime: primitivas UI no estilo shadcn, hooks compartilhados, helpers simples de shell do app e outros módulos de composição de templates. Core mantém reexports de compatibilidade durante a transição.
+
+Pacotes reutilizáveis podem importar módulos do Toolkit diretamente:
 
 ```tsx
 import { Button } from "@agent-native/toolkit/ui/button";
@@ -34,6 +36,13 @@ import { useToast } from "@agent-native/toolkit/hooks/use-toast";
 import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
 ```
 
+Dentro de apps de template, prefira adaptadores locais do app para que equipes possam substituir primitivas uma vez e fazer toda superfície reutilizada do Toolkit usar a implementação local:
+
+```tsx
+import { Button } from "@/components/ui/button";
+import { useToast } from "@/hooks/use-toast";
+```
+
 <Diagram id="doc-block-smqhxh" title={"Desça uma camada, não fora da estrutura"} summary={"Cada camada mantém o mesmo tempo de execução – ações, estado do thread e sincronização SQL-backed – enquanto oferece mais controle sobre o cromo."}>
 
 ```html
@@ -443,7 +452,8 @@ function WorkspaceResources() {
 
 | Área             | APIs                                                            | Caminho de importação                     |
 | ---------------- | --------------------------------------------------------------- | ----------------------------------------- |
-| Compartilhamento | `<ShareButton>`, `<ShareDialog>`, `<VisibilityBadge>`           | `@agent-native/core/client/sharing`       |
+| Compartilhamento | `<ShareButton>`, `<ShareDialog>`                                | `@agent-native/core/client/sharing`       |
+| Sharing UI       | `<VisibilityBadge>`                                             | `@agent-native/toolkit/sharing`           |
 | Notificações     | `<NotificationsBell>`                                           | `@agent-native/core/client/notifications` |
 | Progresso        | `<RunsTray>`, ganchos e tipos de progresso                      | `@agent-native/core/client/progress`      |
 | Integração       | `useOnboarding()`, ganchos de painel integrados                 | `@agent-native/core/client/onboarding`    |

package/docs/content/locales/pt-BR/data-programs.mdx

@@ -0,0 +1,329 @@
+---
+title: "Programas de dados"
+description: "Scripts JS armazenados e escritos pelo agente que buscam, unem e agregam dados no servidor, armazenados em cache no SQL e renderizados por painéis de dashboard — o meio-termo de dados ao vivo entre uma consulta run-code pontual e uma action de provedor codificada."
+search: "data program emit rows schema providerFetch dashboard panel program source refresh TTL viewer-scoped cache save-data-program run-data-program"
+---
+
+# Programas de dados
+
+Um **programa de dados** é um script JS nomeado, armazenado e escrito pelo agente que busca, une, filtra ou agrega dados — APIs de provedores via `providerFetch` / `providerFetchAll` / `providerSearchAll`, dados de app via `appAction`, ou arquivos de workspace baseados em Resources — e chama `emit(rows, schema)` exatamente uma vez com o resultado. O resultado é armazenado em cache no SQL, e qualquer componente de gráfico/tabela pode renderizá-lo, atualizado conforme uma política que você escolher em vez de a cada visualização de página.
+
+Ele é disponibilizado automaticamente onde quer que [`run-code`](/docs/actions) esteja disponível — não há nada para montar ou configurar por app. Se sua app já tem o run-code habilitado, `save-data-program`, `preview-data-program`, `run-data-program`, `list-data-programs`, `get-data-program` e `delete-data-program` já são actions registradas.
+
+<Diagram id="doc-block-dp-overview" title={"De consulta pontual a painel ao vivo"} summary={"Um script run-code se torna um programa armazenado assim que chama emit(); qualquer painel de dashboard pode se vincular a ele, e a política de cache/atualização assume a partir daí."}>
+
+```html
+<div class="dp-flow">
+  <div class="diagram-card" data-rough>
+    <span class="diagram-pill">run-code script</span
+    ><small class="diagram-muted">providerFetch, joins, aggregation</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel">
+    <span class="diagram-pill accent">emit(rows, schema)</span
+    ><small class="diagram-muted"
+      >save-data-program dry-runs, then persists</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    data_program_runs<br /><small class="diagram-muted"
+      >cached per (program, params, viewer)</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">Painel de dashboard</span
+    ><small class="diagram-muted"><code>source: "program"</code></small>
+  </div>
+</div>
+```
+
+```css
+.dp-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dp-flow .diagram-card,
+.dp-flow .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
+  min-width: 180px;
+}
+.dp-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Por que isso existe {#why}
+
+Sem um programa de dados armazenado, "construir uma visão ao vivo de X" costuma terminar em um de dois lugares ruins:
+
+- **Uma action codificada por fornecedor/formato de consulta.** Frágil, e não consegue antecipar as propriedades personalizadas de cada cliente, um join entre provedores, ou um filtro arbitrário que você não pensou em incluir.
+- **Reexecutar a mesma lógica de busca/join do zero a cada visualização de página.** Lento, e volta a gastar a mesma cota de API do provedor toda vez que alguém olha para um gráfico.
+
+Um programa de dados é o meio-termo: escreva a lógica de busca/join/agregação uma vez como `run-code` comum, salve-a, e deixe que o cache e a política de atualização decidam com que frequência ela realmente precisa ser reexecutada.
+
+## Quando usar um {#when-to-use-one}
+
+| Situação                                                                                                                                                                                              | Recorra a                                                                              |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Um rollup padrão já tem uma action de primeira classe (um filtro `hubspot-deals` predefinido, uma métrica embutida)                                                                                   | A action existente — não a envolva em um programa                                      |
+| Uma pergunta de chat pontual que você nunca mais vai olhar                                                                                                                                            | `run-code` simples ou `provider-api-request` — responda diretamente, não persista nada |
+| Uma extensão precisa de um pequeno widget interativo por usuário com sua própria UI                                                                                                                   | [Extensões](/docs/extensions) — um programa de dados não tem UI própria                |
+| Uma coorte precisa de um filtro de propriedade arbitrário, uma busca IN sobre valores personalizados, ou um join entre dois provedores, **e** alguém vai querer vê-la novamente com dados atualizados | Um programa de dados                                                                   |
+| Um painel de dashboard deve mostrar esse resultado unido/agregado e atualizar conforme a política de cache                                                                                            | Um programa de dados vinculado a um painel `"program"`                                 |
+
+Uma comparação com as outras opções no formato run-code:
+
+|                                                | `run-code` pontual         | Action de provedor codificada                      | Programa de dados                                         |
+| ---------------------------------------------- | -------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
+| **Persiste entre chamadas**                    | Não                        | N/A (é código-fonte)                               | Sim — linha armazenada + cache de resultado               |
+| **Resultado é armazenado em cache/atualizado** | Não, reexecuta toda vez    | Sem cache embutido                                 | Sim — `refreshMode`/`refreshTtlMs`                        |
+| **Lida com filtros/joins arbitrários**         | Sim, mas descartado depois | Não — limitado ao que o schema da action expõe     | Sim — ainda é código comum                                |
+| **Vinculável a um painel de dashboard**        | Não                        | Só se uma fonte de painel foi construída para isso | Sim — a fonte genérica `"program"`                        |
+| **Requer um deploy**                           | Não                        | Sim (nova action = mudança de código)              | Não — criado pelo agente em tempo de execução             |
+| **Credenciais usadas no momento da leitura**   | Do chamador                | Do chamador                                        | **Do visualizador**, resolvidas por leitura (veja abaixo) |
+
+## Fluxo de autoria {#authoring-workflow}
+
+1. **Prototipe no chat primeiro.** Escreva a lógica de busca/join/agregação como um script `run-code` normal e confirme que ele retorna as linhas esperadas.
+2. **Altere-o para chamar `emit(rows, schema?)` exatamente uma vez** no final, em vez de retornar ou imprimir o resultado.
+3. **Salve-o** com `save-data-program`. Isso **executa um dry-run do código com `defaultParams` antes de persistir** e rejeita o salvamento com um erro estruturado se falhar, de modo que um programa quebrado nunca é armazenado. Em caso de sucesso, retorna `{ programId, rowCount, columns, sampleRows }` — trate isso como prova de que o programa produz as linhas esperadas antes de dizer ao usuário que está pronto.
+4. **Vincule um painel de dashboard a ele**, ou chame `run-data-program` diretamente do seu próprio caminho de leitura. Não há encanamento específico de dashboard embutido na própria primitiva — a fonte de painel `"program"` do template de analytics (abaixo) é uma adoção, não um padrão obrigatório.
+5. **Itere sem persistir** via `preview-data-program({ code, params? })` — o mesmo caminho de dry-run, sem linha armazenada.
+
+### Um exemplo realista
+
+Suponha que uma app queira uma tabela ao vivo de "tickets de suporte recentes de alto valor" obtida de um provedor de suporte, filtrada por um limiar que nenhuma action embutida expõe:
+
+```ts
+// The program's stored `code` — ordinary run-code, with one emit() call.
+const minValue = Number(params.minValue || 5000);
+
+const tickets = await providerFetchAll("acme-support", "/v1/tickets", {
+  query: { status: "open" },
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "next_cursor",
+    maxPages: 10,
+  },
+});
+
+const rows = (tickets.items || [])
+  .filter((t) => Number(t.contract_value || 0) >= minValue)
+  .map((t) => ({
+    ticket_id: t.id,
+    subject: t.subject,
+    account: t.account_name,
+    contract_value: Number(t.contract_value || 0),
+    opened_at: t.created_at,
+  }));
+
+emit(rows, [
+  { name: "ticket_id", type: "string" },
+  { name: "subject", type: "string" },
+  { name: "account", type: "string" },
+  { name: "contract_value", type: "number" },
+  { name: "opened_at", type: "string" },
+]);
+```
+
+Salvando-o:
+
+```ts
+await appAction("save-data-program", {
+  name: "high-value-open-tickets",
+  title: "High-Value Open Tickets",
+  description:
+    "Open support tickets above a configurable contract-value threshold.",
+  code: "/* the script above */",
+  defaultParams: { minValue: 5000 },
+  refreshMode: "ttl",
+  refreshTtlMs: 300_000,
+});
+```
+
+A resposta traz `{ programId, rowCount, columns, sampleRows }` — a prova de conclusão do dry-run. A partir daí, `run-data-program({ programId, params: { minValue: 10000 } })` o reexecuta (ou serve o cache) para um limiar diferente, e um painel de dashboard pode se vincular a `programId` da mesma forma.
+
+## A superfície do sandbox {#sandbox-surface}
+
+Um programa de dados roda exatamente pelo mesmo sandbox `executeSandboxCode` que o `run-code` — não existe novo código de sandboxing, credenciais, SSRF ou cota para essa primitiva. Ele obtém os mesmos globals (`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`, `webFetch`, helpers de Resources `workspace*`) mais duas adições de um pequeno preâmbulo injetado pelo framework:
+
+- **`params`** — um objeto global **congelado** contendo os params desta execução (`defaultParams` mesclado com o que foi passado para `run-data-program` ou o descritor do painel). Lê-lo é seguro; mutá-lo lança um erro.
+- **`emit(rows, schema?)`** — chame isso **exatamente uma vez**, no final. Uma segunda chamada lança um erro. `rows` deve ser um array de objetos simples. `schema`, quando fornecido, é `{ name: string, type: string }[]`; quando omitido, é inferido das primeiras 50 linhas (uma coluna é `"json"` se as linhas discordarem sobre o tipo primitivo na amostra, caso contrário `"number"` / `"string"` / `"boolean"`). `console.log` permanece completamente livre para depuração — o runner captura stdout/stderr combinados e só remove a linha sentinela que `emit()` escreve ao analisar o resultado.
+
+Limites aplicados em cada execução (não configuráveis por programa):
+
+| Limite                                                           | Valor                                                                                                                                                         |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Máx. de linhas emitidas                                          | 10.000 — linhas além disso são descartadas, `truncated: true`                                                                                                 |
+| Tamanho máx. do resultado emitido                                | 4 MiB — linhas descartadas do final para caber; uma única linha acima do limite é uma falha rígida `result_too_large`, já que não há nada seguro para truncar |
+| Máx. de programas ativos (não arquivados) por app                | 200 — arquive os não utilizados para liberar espaço                                                                                                           |
+| TTL mínimo de atualização                                        | 60.000 ms                                                                                                                                                     |
+| Linhas de execução mantidas por (programa, params, visualizador) | 5 mais recentes — as mais antigas são removidas automaticamente a cada escrita                                                                                |
+
+O truncamento é sempre explícito (`truncated: true` no resultado) — nunca uma perda silenciosa.
+
+## Params e vinculação de painel de dashboard {#params-and-panel-binding}
+
+Programas declaram um `paramsSchema` opcional (JSON Schema descrevendo os params aceitos) e `defaultParams`. Um dashboard adota a fonte de painel `"program"` colocando um pequeno descritor JSON no campo de consulta do painel em vez de uma string de consulta:
+
+```json
+{ "programId": "dp_a1b2c3d4e5f6", "params": { "minValue": 10000 } }
+```
+
+O painel renderiza através exatamente dos mesmos componentes de gráfico/tabela que qualquer outra fonte de painel — ele só recebe `{ rows, schema }` de volta. Vincular um painel a um programa é apenas "qual programa armazenado, com quais sobrescritas de params"; não há nenhum caminho de execução específico de dashboard duplicado em outro lugar.
+
+## Semântica de atualização, TTL e cache {#refresh-and-caching}
+
+Cada par `(programId, paramsHash)` tem seu próprio histórico de execução em `data_program_runs`, e `paramsHash` incorpora **o visualizador**, não apenas os params (veja a seção de segurança para entender o motivo). O que acontece a cada leitura:
+
+| Situação                                                                                           | Comportamento                                                                                                                                                                                                                   |
+| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cache fresco (mais recente que `refreshTtlMs`, ou `refreshMode: "manual"` com um sucesso anterior) | Retorna as linhas em cache instantaneamente, `cacheHit: true`                                                                                                                                                                   |
+| O cache é mais antigo que o TTL                                                                    | Reexecuta sincronamente — um orçamento de 25s para leituras acionadas por visualização de painel, 120s para chamadas de agente/manuais — e substitui o cache em caso de sucesso                                                 |
+| `refreshMode: "manual"`                                                                            | Nunca atualiza automaticamente; apenas um `forceRefresh: true` explícito (ou uma action de UI de atualização manual) o reexecuta                                                                                                |
+| Ainda sem cache                                                                                    | Executa sincronamente como uma primeira busca normal                                                                                                                                                                            |
+| Programa `background: true`, sem cache fresco                                                      | Serve a última execução bem-sucedida imediatamente com `stale: true` e enfileira uma execução em segundo plano durável (orçamento de 10 minutos); uma chamada posterior finaliza o resultado assim que a execução for concluída |
+| Programa em segundo plano ainda em execução, sem sucesso anterior                                  | Falha `background_pending` — exiba um estado explícito "ainda calculando", nunca um resultado em branco                                                                                                                         |
+| A execução falha (timeout, erro de sandbox, formato de `emit()` inválido)                          | Uma falha estruturada `{ code, message }`; se existir um sucesso anterior, ele é anexado como `lastGoodRun` para que um painel possa servir dados obsoletos em vez de ficar em branco                                           |
+| O programa foi arquivado (soft-delete via `delete-data-program`)                                   | Falha explícita `archived` — nunca um painel em branco silencioso                                                                                                                                                               |
+
+Recorra a `background: true` apenas para programas que rotineiramente excedem o timeout em primeiro plano — grandes joins multi-provedor, paginação profunda. Todo o resto deve permanecer em primeiro plano: é mais simples de raciocinar e serve dados atualizados mais rápido.
+
+### Por que o cache é delimitado por visualizador {#per-viewer-cache}
+
+`providerFetch` dentro de um programa resolve a autenticação usando **o próprio contexto de requisição do visualizador que chama** — nunca o do autor do programa. Isso é verdade quer a chamada venha do agente, de uma chamada `run-data-program`, ou de um painel de dashboard sendo visto por um colega de equipe. Dois visualizadores diferentes executando o mesmo programa com os mesmos params podem legitimamente obter dois resultados diferentes: um tem uma chave do HubSpot configurada e o outro não, ou as permissões de provedor em nível de linha diferem por pessoa.
+
+Por causa disso, `hashDataProgramParams` incorpora a identidade do chamador na chave de cache junto com os params canonicalizados. Isso importa mais para **dashboards compartilhados**: se o cache fosse indexado apenas por params, a primeira pessoa a visualizar um painel determinaria silenciosamente o que cada outro visualizador vê, incluindo um visualizador sem as credenciais que produziram aquele resultado em cache. A delimitação por visualizador significa que um colega de equipe sem uma credencial vê seu próprio erro de autenticação naquele painel, não os dados de outra pessoa.
+
+## Modelo de segurança {#security}
+
+<Callout id="doc-block-dp-security" tone="success">
+
+**Tokens brutos de provedor nunca chegam ao modelo ou ao navegador.** A única coisa que sai do sandbox é o `{ rows, schema }` que uma chamada `emit()` produz — a mesma fronteira de confiança que qualquer outra execução run-code e qualquer outra fonte de painel de dashboard.
+
+</Callout>
+
+- **Somente do lado do servidor.** O código de um programa de dados executa exclusivamente dentro de `executeSandboxCode` no servidor. Nem o código-fonte armazenado nem qualquer credencial que ele toque é enviado ao navegador ou ao modelo — apenas as linhas/schema emitidos e metadados compactos de execução (contagem de linhas, colunas, linhas de amostra) são.
+- **Credenciais são sempre do visualizador que chama, nunca do autor original do programa.** Veja [Semântica de atualização, TTL e cache](#per-viewer-cache) acima para entender por que isso também determina a chave de cache.
+- **`allowPublic: false` é um invariante rígido, não um padrão.** Programas de dados se registram no registro de sharing da mesma forma que as [Extensões](/docs/extensions#security), com o compartilhamento público desabilitado. Um programa público permitiria que qualquer usuário autenticado executasse código arbitrário armazenado sob seu próprio token — compartilhar um programa é limitado à sua organização, e significa apenas "colegas de equipe podem ver seu resultado em cache e disparar reexecuções", nunca "a internet em geral pode executar isso".
+- **As actions que mutam e executam não são invocáveis como ferramenta a partir da bridge de extensão/iframe em sandbox.** `save-data-program`, `preview-data-program`, `run-data-program` e `delete-data-program` são `toolCallable: false` — apenas o agente ou um caminho de leitura do lado do servidor pode invocá-las, nunca um iframe de extensão sob a sessão de quem o abriu. `list-data-programs` e `get-data-program` são somente leitura e delimitados por acesso através dos mesmos helpers de sharing que qualquer outro recurso ownable.
+- **Programas são delimitados à app que os criou.** Passar `appId` para uma busca significa que um programa criado em uma app não é executável a partir do chat do agente de outra app em um deploy de banco de dados compartilhado, mesmo para um chamador que de outra forma teria acesso em nível de linha (owner/org/share) a ele.
+- **Só se vincule a ou visualize um programa em que confie.** Como a execução sempre usa as próprias credenciais do visualizador, visualizar o resultado de um programa compartilhado é exatamente como abrir a extensão de outra pessoa — confie no código, não apenas na concessão de acesso.
+
+## O exemplo trabalhado do Risk Meeting {#risk-meeting-example}
+
+O template de analytics traz um estudo de caso concreto e executável: a action `ensure-risk-meeting-dashboard` instala de forma idempotente dois programas de dados mais um dashboard "Risk Meeting" de dois painéis, demonstrando três coisas que uma action codificada não consegue antecipar para cada cliente.
+
+<FileTree
+  id="doc-block-dp-risk-meeting-files"
+  title={"Instalador do Risk Meeting"}
+  entries={[
+    {
+      path: "templates/analytics/actions/ensure-risk-meeting-dashboard.ts",
+      note: "action idempotente: atualiza ambos os programas por nome estável, depois o dashboard por id",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-cohort.js",
+      note: "payload de programa armazenado — texto JS simples, não um arquivo-fonte de build",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-pylon-early-warning.js",
+      note: "o programa complementar de alerta antecipado",
+    },
+  ]}
+/>
+
+**`risk-meeting-cohort.js`** — busca uma coorte configurável de deals de CRM por uma propriedade `risk_status` arbitrária (uma busca IN sobre valores personalizados que uma action predefinida não consegue antecipar), resolve a empresa de cada deal através de uma busca de associação em lote, resolve o domínio de cada empresa, busca o sentimento de conta de um segundo provedor não relacionado, e une os dois por domínio:
+
+```js
+// params: { riskStatuses?: string[], enterpriseOnly?: boolean }
+const riskStatuses = params.riskStatuses?.length
+  ? params.riskStatuses
+  : ["On the Radar", "Churn Risk", "Confirmed Churn", "No Save Attempted"];
+
+// 1. Arbitrary property IN-search — not expressible through a canned filter.
+const dealSearch = await providerFetchAll("crm-provider", "/deals/search", {
+  method: "POST",
+  body: {
+    filterGroups: [
+      {
+        filters: [
+          { propertyName: "risk_status", operator: "IN", values: riskStatuses },
+        ],
+      },
+    ],
+  },
+  itemsPath: "results",
+  pagination: {
+    cursorBodyPath: "after",
+    nextCursorPath: "paging.next.after",
+    maxPages: 20,
+  },
+});
+
+// 2-3. Batched deal -> company -> domain resolution (elided here; see the
+// real seed file for the full batching helper).
+
+// 4. A second, unrelated provider — zero bespoke glue action required.
+const accounts = await providerFetchAll("support-provider", "/accounts", {
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "pagination.cursor",
+    maxPages: 20,
+  },
+});
+
+// 5. Join + emit.
+const rows = dealSearch.items.map((deal) => ({
+  deal_id: deal.id,
+  risk_status: deal.properties.risk_status,
+  arr: Number(deal.properties.total_contract_value || 0),
+  // ...domain lookup + sentiment join...
+}));
+
+emit(rows, [
+  { name: "deal_id", type: "string" },
+  { name: "risk_status", type: "string" },
+  { name: "arr", type: "number" },
+]);
+```
+
+**`risk-meeting-pylon-early-warning.js`** — a visão complementar: contas já sinalizadas como em risco pelo sentimento de suporte que **ainda não** apareceram na coorte de CRM acima. Essa lacuna — sinal de suporte ultrapassando o sinal de CRM — requer excluir a coorte de um provedor da de outro, exatamente o tipo de lógica de conjuntos entre provedores que nenhuma action de fornecedor único consegue expressar.
+
+Ambos os programas são instalados e mantidos atualizados pelo `ensure-risk-meeting-dashboard`, que:
+
+- Atualiza cada programa pelo seu `name` estável, de modo que reexecutar o instalador atualiza as mesmas linhas em vez de duplicá-las.
+- Não requer credenciais de CRM/suporte no momento da instalação — a autenticação do provedor é resolvida por visualizador somente quando um painel é realmente renderizado ou `run-data-program` é chamado, consistente com a delimitação de cache por visualizador acima.
+- Constrói um dashboard de dois painéis cujos painéis usam `source: "program"`, vinculados ao id de cada programa.
+
+Veja a skill `data-programs` para a fonte totalmente anotada.
+
+## Como outras apps adotam a fonte de painel {#adopting-the-panel-source}
+
+A fonte de painel de dashboard `"program"` é uma adoção da primitiva, implementada inteiramente na própria camada de consulta de painéis da app hospedeira — nada específico de dashboard está embutido no próprio `@agent-native/core/data-programs`. A implementação do template de analytics é uma referência útil para conectar a sua:
+
+- A coluna `sql` do painel carrega um pequeno descritor JSON — `{ programId, params? }` — em vez de uma string de consulta.
+- Renderizar um painel chama `runDataProgram` com `triggeredBy: "panel_view"` e a identidade do visualizador atual, de modo que o cache por visualizador e a resolução de credenciais se apliquem automaticamente.
+- Em caso de sucesso, o painel obtém `{ rows, schema }` — o mesmo formato que qualquer outra fonte de painel retorna, de modo que flui sem modificações pelos componentes de gráfico/tabela existentes.
+- Em caso de falha, um `lastGoodRun` é preferido a um painel quebrado sempre que existir um; somente quando não há sucesso anterior o painel exibe um erro estruturado (com texto mais amigável para códigos comuns como `access_denied`, `archived` e `background_pending`).
+
+Qualquer app pode implementar a mesma adoção para seus próprios dashboards/tabelas: chame `run-data-program` (ou `runDataProgram` diretamente se estiver no mesmo processo de servidor) a partir do seu próprio caminho de leitura, e passe os `rows`/`schema` retornados para seus próprios componentes de renderização.
+
+## Docs relacionadas {#related}
+
+- [Extensões](/docs/extensions) — a primitiva de mini-app em sandbox com a qual os programas de dados compartilham uma postura de segurança e um modelo de sharing, mas com uma UI própria.
+- [Actions](/docs/actions) — as convenções de `run-code` e os globals de sandbox (`providerFetch`, `appAction`, etc.) sobre os quais os programas de dados são construídos.
+- [Sharing e privacidade](/docs/sharing) — o modelo de sharing interno à organização, nunca público, que os programas de dados usam.
+- [Segurança](/docs/security) — os invariantes de tratamento de credenciais e delimitação de acesso do framework.

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

@@ -384,24 +384,23 @@ Alterne-os substituindo o env var em cada instância e reimplantando. As sessõe
 ## Ferramentas do agente de produção {#production-agent-tools}
 
 Os agentes de produção obtêm o actions registrado do aplicativo, além das ferramentas de estrutura de
-o plugin de chat do agente. As gravações no banco de dados são habilitadas por padrão porque o banco de dados bruto
-as ferramentas têm como escopo o usuário/organização autenticado, mas os proprietários de aplicativos podem restringir o
-descobre quando uma implantação deveria ser mais opinativa:
+o plugin de bate-papo do agente. A inspeção SQL fica habilitada por padrão; as gravações
+passam por actions tipadas do app, a menos que o app habilite explicitamente ferramentas de escrita SQL bruta:
 
 ```ts
 // server/plugins/agent-chat.ts
 export default createAgentChatPlugin({
-  // Default: "write" (also true)
+  // Default: "read"
   databaseTools: "read", // "write" | "read" | "off"
   extensionTools: false,
 });
 ```
 
-- `databaseTools: "write"` — padrão. Registra `db-schema`, `db-query`,
-  `db-exec` e `db-patch`. As gravações têm como escopo o usuário/organização atual e
-  as alterações de esquema estão bloqueadas.
-- `databaseTools: "read"` — registra apenas `db-schema` e `db-query`; agentes
-  inspecione os dados com SQL, mas deve usar o aplicativo digitado actions para gravações.
+- `databaseTools: "read"` — padrão. Registra apenas `db-schema` e `db-query`;
+  os agentes inspecionam dados com SQL, mas devem usar actions tipadas do app para gravar.
+- `databaseTools: "write"` ou `true` — também registra `db-exec` e `db-patch`
+  para manutenção SQL bruta deliberada. As gravações são limitadas ao usuário/
+  organização atual e alterações de esquema são bloqueadas.
 - `databaseTools: "off"` ou `false` — remove ferramentas de banco de dados brutos do
   superfície do agente para que o actions do aplicativo seja o único caminho de acesso aos dados.
 - `extensionTools: false` — remove o gerenciamento de extensão da estrutura actions e