@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/pt-BR/blueprint-installer.md

@@ -0,0 +1,83 @@
+---
+title: "Instalador do Blueprint"
+description: "agent-native add imprime uma receita de integração Markdown selecionada para stdout — canalize-a para seu agente de codificação, que aplica as alterações em seu repositório ativo."
+---
+
+# Instalador do Blueprint
+
+> **A quem se destina:** autores de hospedagem e integradores adicionando um provedor, canal,
+> back-end de sandbox ou ação para um repositório canalizando uma receita para seu agente de codificação.
+
+`agent-native add` **não** é um andaime burro que grava arquivos para você. Ele emite um _plano de integração_ Markdown com curadoria para stdout. Você canaliza esse projeto para seu próprio agente de codificação (código Claude, Codex,…), que aplica as alterações ao repositório ativo com contexto completo.
+
+Isso se ajusta ao estilo doméstico do agente-aplica-mudanças, sistema de arquivos primeiro: a estrutura fornece a receita (os arquivos canônicos a serem alterados, as regras a serem respeitadas, a etapa de verificação) e o agente de codificação faz a edição.
+
+```bash
+agent-native add provider stripe | claude
+agent-native add channel discord  | codex
+```
+
+```an-diagram title="add prints a recipe; your coding agent applies it" summary="agent-native emits a Markdown blueprint to stdout (diagnostics to stderr); you pipe it into Claude Code or Codex, which edits your live repo with full context."
+{
+  "html": "<div class=\"diagram-bp\"><div class=\"diagram-node\" data-rough>agent-native add<br><small class=\"diagram-muted\">&lt;kind&gt; &lt;name|URL&gt;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Markdown blueprint<br><small class=\"diagram-muted\">stdout · files to touch · rules · Verify</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>Coding agent<br><small class=\"diagram-muted\">claude · codex</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">edits your live repo</div></div>",
+  "css": ".diagram-bp{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bp .diagram-arrow{font-size:22px;line-height:1}.diagram-bp .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Uso {#usage}
+
+```bash
+agent-native add <kind> <name>            # print a curated blueprint
+agent-native add <kind> <https://docs…>   # research-and-integrate from a URL
+agent-native add --list                   # list available kinds and blueprints
+```
+
+- Um **nome** simples resolve um blueprint selecionado de `blueprints/<kind>/<name>.md`.
+- Um **URL** em vez de um nome emite um projeto genérico de _pesquisa e integração_ para esse tipo, com o URL incorporado como o ponto de partida da pesquisa (um URL é uma semente de pesquisa, não uma receita conhecida).
+- O blueprint vai para **stdout**; os diagnósticos vão para stderr, então `… | claude` só recebe o projeto.
+
+## Projetos propagados {#seeded}
+
+`agent-native add --list` mostra o que vem na caixa:
+
+| Gentil     | Nome      | O que configura                                                                            |
+| ---------- | --------- | ------------------------------------------------------------------------------------------ |
+| `provider` | `stripe`  | Conecte um provedor ao substrato `provider-api` (catálogo/documentos/trio de solicitação). |
+| `channel`  | `discord` | Implemente um canal webhook de entrada `PlatformAdapter` e registre-o.                     |
+| `sandbox`  | `docker`  | Implemente a junção `SandboxAdapter` para executar `run-code` em um contêiner Docker.      |
+| `action`   | `crud`    | Adicione um único `defineAction` multisuperfície com um esquema Zod (um `update` sobre N). |
+
+Cada blueprint é independente: o agente de codificação que o lê faz com que os arquivos sejam tocados, as regras da estrutura sejam respeitadas (actions são a única fonte da verdade, nunca codificam segredos, definem o escopo dos dados que podem ser adquiridos, adicionam um conjunto de alterações para a fonte `packages/*`) e uma seção concreta **Verificar**.
+
+## URL → plano de pesquisa {#url}
+
+Quando você passa por um URL do tipo que não tem uma receita selecionada (ou deseja uma nova integração), o `add` emite um modelo genérico de "pesquisar e integrar" com o URL como semente:
+
+```bash
+agent-native add provider https://docs.example.com/api | claude
+```
+
+O blueprint gerado diz ao agente de codificação para buscar o URL (e as páginas às quais ele está vinculado) para os endpoints reais, modelo de autenticação, formas de carga útil e requisitos de assinatura/verificação - _não_ para adivinhar a partir dos dados de treinamento - e então implementar e verificar. Ele também traz orientações específicas do tipo (por exemplo, um `provider` URL é direcionado para o substrato `provider-api`; um `channel` URL para um `PlatformAdapter`).
+
+## Adicionando seu próprio projeto {#authoring}
+
+Solte um arquivo Markdown em `packages/core/blueprints/<kind>/<name>.md`. O tipo é o subdiretório; o nome é o nome do arquivo sem `.md`. Ele é obtido automaticamente - `--list`, resolução de nomes e o catálogo leem o diretório em tempo de execução. Nenhuma alteração de código é necessária para registrá-lo.
+
+Os arquivos Blueprint `.md` são enviados no pacote publicado por meio da entrada `blueprints` em `package.json` `files`, portanto, eles são resolvidos em `node_modules/@agent-native/core/blueprints/**` para usuários finais.
+
+Escreva cada blueprint como um conjunto de instruções para um agente de codificação sem outro contexto. Um bom plano tem:
+
+1. **Uma meta de uma linha** e um enquadramento "você é um agente de codificação em um aplicativo nativo do agente, aplique-os como alterações de origem reais".
+2. **Leia primeiro** — os arquivos exatos que _são_ o contrato.
+3. **Arquivos para tocar** — caminhos concretos e o que cada alteração faz.
+4. **Regras de estrutura a serem respeitadas** — actions-first, sem segredos codificados, escopo de dados proprietários, adição de um conjunto de alterações para fonte de pacote publicável.
+5. **Verificar** — verificação de tipo, um `*.spec.ts` focado e uma verificação de ponta a ponta.
+
+> [!TIP]
+> Um novo blueprint selecionado em um tipo existente não precisa de código, mas se você criar um diretório de tipo totalmente novo, esse tipo também aparecerá automaticamente em `--list`.
+
+## O que vem a seguir
+
+- [**Sandbox Adapters**](/docs/sandbox-adapters) — a costura que o projeto `add sandbox docker` tem como alvo
+- [**Actions**](/docs/actions) — a única fonte de verdade na qual todo projeto se baseia
+- [**External Agents**](/docs/external-agents) — conectando o agente de codificação ao qual você canaliza os projetos

package/docs/content/locales/pt-BR/cli-adapters.md

@@ -0,0 +1,129 @@
+---
+title: "Adaptadores CLI"
+description: "Dê ao agente acesso estruturado a qualquer ferramenta CLI (gh, ffmpeg, stripe) por meio de uma interface de adaptador padrão — uma das duas costuras de adaptador abordadas no guia Adaptadores."
+---
+
+# Adaptadores CLI
+
+> **Onde isso se encaixa:** Os adaptadores CLI são uma das duas costuras do adaptador no
+> . O guia canônico é [Adapters](/docs/sandbox-adapters), que
+> cobre esta junção e a junção sandbox `run-code` — incluindo a compartilhada
+> restrição de borda/sem servidor. Esta página é uma referência rápida para o lado CLI.
+
+Um adaptador CLI envolve uma única ferramenta de linha de comando (`gh`, `ffmpeg`, `stripe`, `aws`) para que o agente possa descobri-lo, verificar se está instalado e executá-lo com um resultado stdout/stderr/código de saída consistente. Sem essa costura, todo script reinventa como invocar um CLI e analisar sua saída.
+
+```an-diagram title="CLI adapter → registry → action surface" summary="ShellCliAdapter wraps a binary; CliRegistry collects adapters for discovery; defineAction exposes one call on the agent + UI action surface."
+{
+  "html": "<div class=\"diagram-cli\"><div class=\"diagram-node\" data-rough>gh · ffmpeg · stripe<br><small class=\"diagram-muted\">command-line tools</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>ShellCliAdapter<br><small class=\"diagram-muted\">isAvailable · execute</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>CliRegistry<br><small class=\"diagram-muted\">describe() for discovery</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">defineAction</div></div>",
+  "css": ".diagram-cli{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-cli .diagram-arrow{font-size:22px;line-height:1}.diagram-cli .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## A interface {#the-interface}
+
+Cada adaptador CLI implementa `CliAdapter`:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+## ShellCliAdapter {#shell-adapter}
+
+Para a maioria dos CLIs você não precisa de uma classe personalizada — `ShellCliAdapter` envolve qualquer binário com padrões razoáveis:
+
+```ts
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const gh = new ShellCliAdapter({
+  command: "gh",
+  description: "GitHub CLI — manage repos, PRs, issues, and releases",
+});
+
+const ffmpeg = new ShellCliAdapter({
+  command: "ffmpeg",
+  description: "Audio/video processing and transcoding",
+  timeoutMs: 120_000, // 2 min for long encodes
+  env: { STRIPE_API_KEY: process.env.STRIPE_SECRET_KEY! },
+});
+```
+
+Opções: `command` (obrigatório), `description` (obrigatório), `name` (o padrão é `command`), `env` (mesclado com `process.env`), `cwd` (o padrão é `process.cwd()`) e `timeoutMs` (padrão). `30000`).
+
+Para autenticação personalizada, análise de saída ou pré/pós-processamento, implemente `CliAdapter` diretamente em vez de usar `ShellCliAdapter`.
+
+## Registro {#registry}
+
+`CliRegistry` coleta adaptadores para que o agente possa descobrir o que está disponível em tempo de execução:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({ command: "gh", description: "GitHub CLI" }),
+);
+
+cliRegistry.list(); // all registered
+await cliRegistry.listAvailable(); // only installed
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+## Usando de actions {#from-actions}
+
+Envolva uma chamada CLI em `defineAction` para expô-la na superfície de ação — `defineAction` é necessário quando o código é executado dentro da superfície de ação do servidor; caso contrário, use um adaptador diretamente em um arquivo `scripts/`. Nunca chame `process.exit` em uma ação; em vez disso, gera um erro.
+
+```ts
+// actions/list-prs.ts
+import { defineAction } from "@agent-native/core/action";
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+import { z } from "zod";
+
+const gh = new ShellCliAdapter({ command: "gh", description: "GitHub CLI" });
+
+export default defineAction({
+  description: "List open pull requests via the GitHub CLI.",
+  schema: z.object({}),
+  async run() {
+    if (!(await gh.isAvailable())) {
+      throw new Error("GitHub CLI not installed. Run: brew install gh");
+    }
+    const result = await gh.execute([
+      "pr",
+      "list",
+      "--json",
+      "title,url,state",
+      "--limit",
+      "10",
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || "gh pr list failed");
+    }
+    return JSON.parse(result.stdout);
+  },
+});
+```
+
+## Edge e sem servidor {#edge-serverless}
+
+Os adaptadores CLI usam `node:child_process`, que não existe em tempos de execução de borda/trabalhador (Cloudflare Workers, Netlify Edge Functions). Execute tarefas e terminais do adaptador CLI em um ambiente Node.js padrão. Essa restrição é compartilhada com a costura sandbox — veja a discussão completa em [Adapters](/docs/sandbox-adapters#edge-serverless).
+
+## O que vem a seguir
+
+- [**Adapters**](/docs/sandbox-adapters) — o guia canônico para ambas as costuras do adaptador.
+- [**Actions**](/docs/actions) — os adaptadores CLI da superfície de ação geralmente são incluídos.

package/docs/content/locales/pt-BR/client.md

@@ -0,0 +1,398 @@
+---
+title: "Cliente"
+description: "Ganchos e utilitários React para aplicativos nativos do agente: sendToAgentChat, estado de contexto de bate-papo do agente opcional, useDbSync, useAgentChatGenerating e cn."
+---
+
+# Cliente
+
+`@agent-native/core` fornece ganchos e utilitários React para o lado do navegador de aplicativos nativos do agente.
+
+Esses clientes/React APIs são exportados de `@agent-native/core` e `@agent-native/core/client`. Importe-os de `@agent-native/core/client` (a entrada do navegador) para maior clareza e agrupamento correto, já que a raiz `@agent-native/core` simples é resolvida para a compilação do Node por padrão.
+
+Para roteamento baseado em arquivo — adição de páginas, parâmetros dinâmicos e navegação — consulte [Routing](/docs/routing).
+
+## Busca e mutação de dados {#fetching-mutating}
+
+A principal maneira de ler e gravar dados de aplicativos no navegador é por meio de ganchos de ação. Nunca escreva manualmente chamadas `fetch` para rotas `/_agent-native/*`; em vez disso, use os auxiliares nomeados (consulte [Actions](/docs/actions)).
+
+```an-diagram title="The browser data loop" summary="Hooks read and write through actions; useDbSync watches the database so agent and background writes refetch the same caches automatically."
+{
+  "html": "<div class=\"diagram-client\"><div class=\"diagram-col\"><div class=\"diagram-node\">useActionQuery<br><small class=\"diagram-muted\">cached read</small></div><div class=\"diagram-node\">useActionMutation<br><small class=\"diagram-muted\">write + invalidate</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-box\" data-rough>Actions<br><small class=\"diagram-muted\">/_agent-native/actions/*</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-panel\" data-rough><strong>SQL database</strong></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">useDbSync &rarr; refetch on change</div></div>",
+  "css": ".diagram-client{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-client .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-client .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```tsx
+import {
+  useActionQuery,
+  useActionMutation,
+  callAction,
+} from "@agent-native/core/client";
+
+// Read: auto-cached, auto-invalidated on mutations
+const { data, isLoading } = useActionQuery("get-lead", { leadId });
+
+// Mutate: emits a change event so query caches refetch
+const { mutate, isPending } = useActionMutation("create-lead");
+mutate({ name: "Alice", company: "Acme" });
+
+// Imperative: for one-off calls outside a component
+await callAction("archive-lead", { leadId });
+```
+
+## sendToAgentChat(opções) {#sendtoagentchat}
+
+Envie uma mensagem para o chat do agente via postMessage — a maneira comum de delegar uma tarefa de IA de uma interação UI. Passe `context` para contexto de modelo oculto e `submit: true` para enviar imediatamente ou `submit: false` para preencher previamente um rascunho que o usuário analisará primeiro.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client";
+
+// Auto-submit a prompt with hidden context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+Dentro de um aplicativo MCP incorporado criado com `embedApp()`, mensagens enviadas automaticamente
+(`submit` omitido ou `true`) são encaminhados para a ponte de host do aplicativo MCP, que
+pede ao host que o contém para adicionar contexto oculto e enviar a vez do usuário visível.
+`context` permanece visível para o modelo sem ser postado como bate-papo voltado para o usuário.
+`submit: false` mantém o comportamento de pré-preenchimento/revisão local porque os aplicativos MCP não o fazem
+defina um rascunho pré-preenchido API padrão. Internamente, este é o caminho do chat enviado
+às vezes aparecia como `agentNative.submitChat`; o código do aplicativo deve chamar
+`sendToAgentChat()` em vez de postar esse evento diretamente.
+
+### Envios silenciosos em segundo plano {#background-send}
+
+Use `background: true` quando uma ação UI iniciar o trabalho real do agente sem
+abrindo ou focando a barra lateral. Isso ainda cria uma conversa/execução de bate-papo normal,
+usa as ferramentas/actions/contexto do agente e mantém o trabalho observável por meio
+a bandeja de corridas; não é uma chamada de modelo única e bruta.
+
+```ts
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` deve ser emparelhado com `newTab` para que o trabalho oculto não ocorra
+substituir a conversa ativa do usuário. Use o `tabId` retornado se o UI
+precisa correlacionar o status de acompanhamento ou criar um link direto para a execução posteriormente.
+
+### AgentChatMessage {#agentchatmessage}
+
+| Opção                 | Tipo        | Descrição                                                               |
+| --------------------- | ----------- | ----------------------------------------------------------------------- |
+| `message`             | `string`    | O prompt visível enviado para o chat                                    |
+| `context`             | `string?`   | Contexto oculto anexado (não mostrado no chat UI)                       |
+| `submit`              | `boolean?`  | true = envio automático, false = somente preenchimento prévio           |
+| `newTab`              | `boolean?`  | Crie um tópico de bate-papo separado para este prompt                   |
+| `background`          | `boolean?`  | Com `newTab`, execute sem focar a aba e mostre a execução em `RunsTray` |
+| `openSidebar`         | `boolean?`  | Defina false para enviar/preencher sem abrir a barra lateral            |
+| `projectSlug`         | `string?`   | Slug de projeto opcional para contexto estruturado                      |
+| `preset`              | `string?`   | Nome predefinido opcional para consumidores downstream                  |
+| `referenceImagePaths` | `string[]?` | Caminhos de imagem de referência opcionais                              |
+
+## Estado do contexto do chat do agente (avançado) {#agent-chat-context-state}
+
+Os APIs de estado de contexto são encanamentos opcionais para UI que precisam de sincronização bidirecional com
+chips de contexto de teste: renderizando os itens de teste atuais fora do compositor,
+refletindo se um item já está anexado ou fornecendo informações explícitas
+remover/limpar controles.
+
+Não procure esses ajudantes para simplesmente "enviar isto para o agente" ou
+"preencher este rascunho para revisão". Use `sendToAgentChat()` com `context`
+e `submit` para esses.
+
+| API                               | Usar quando                                                                                 |
+| --------------------------------- | ------------------------------------------------------------------------------------------- |
+| `useAgentChatContext()`           | Um componente React precisa da lista de contexto preparada ao vivo                          |
+| `setAgentChatContextItem(item)`   | O código imperativo deve preparar ou substituir um item de contexto digitado                |
+| `listAgentChatContext()`          | O código não React precisa de um instantâneo único do contexto preparado                    |
+| `removeAgentChatContextItem(key)` | UI deve remover um item de contexto preparado por seu `key` estável                         |
+| `clearAgentChatContext()`         | UI deve limpar todo o contexto preparado, como após uma visualização ou redefinição de modo |
+| `refreshAgentChatContext()`       | O código imperativo deve reler o instantâneo de contexto persistido mais recente            |
+
+`useAgentChatContext()` retorna `{ items, set, remove, clear, refresh }`.
+
+## openAgentSettings(seção?) {#openagentsettings}
+
+Use `openAgentSettings()` quando uma página de configurações de aplicativo ou um cartão de configuração for aberto
+guia Configurações da barra lateral do agente. Passe um ID de seção como `"llm"`, `"secrets"`,
+`"automations"`, `"voice"` ou `"limits"` para abrir uma seção específica.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client";
+
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+Prefira este auxiliar ao despachar `agent-panel:open-settings` diretamente.
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client";
+
+function SelectionContextButton({ record }: { record: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-record:${record.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Record",
+          context: JSON.stringify(record, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` é para código imperativo que só precisa inspecionar o
+itens atualmente preparados uma vez. `clearAgentChatContext()` é intencionalmente amplo; usar
+`removeAgentChatContextItem(key)` quando apenas uma seleção foi alterada.
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| Opção         | Tipo       | Descrição                                                                   |
+| ------------- | ---------- | --------------------------------------------------------------------------- |
+| `key`         | `string`   | Identificador estável usado para substituir um nugget existente             |
+| `title`       | `string`   | Etiqueta abreviada mostrada no chip do compositor                           |
+| `context`     | `string`   | Contexto oculto incluído no próximo prompt enviado                          |
+| `openSidebar` | `boolean?` | O padrão é verdadeiro; passe false para preparar o contexto silenciosamente |
+
+## askUserQuestion(opções) {#ask-user-question}
+
+Faça ao usuário uma pergunta de múltipla escolha no código do aplicativo e coloque-a em linha no
+painel do agente e **aguarde a resposta**. É o gêmeo do lado do cliente do
+ferramenta `ask-question` integrada do agente: ela grava um `GuidedQuestionPayload` no
+Chave de estado do aplicativo `"guided-questions"` (onde está montada
+`GuidedQuestionFlow` renderiza) e revela o painel do agente, então a pergunta é
+visível. Ao contrário da ferramenta do agente — cuja resposta retorna ao agente —
+`askUserQuestion()` **resolve com a resposta ao chamador**, então o UI pode
+ramifique-o.
+
+Use-o quando o UI precisar de exatamente uma pequena decisão (2–4 opções) antes dele
+inicia o trabalho do agente — em vez de criar um modal personalizado. Alcance o
+composer para detalhes de forma livre e um formulário/popover para entrada de vários campos.
+
+```tsx
+import { askUserQuestion, sendToAgentChat } from "@agent-native/core/client";
+
+const length = await askUserQuestion({
+  question: "How long should this deck be?",
+  header: "Deck length", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Short (3–5 slides)", value: "short" },
+    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
+    { label: "Long (11+ slides)", value: "long" },
+  ],
+  allowFreeText: false, // omit the "Other" free-text option (default adds it)
+  allowMultiple: false, // single-select (default)
+});
+
+if (length) {
+  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
+}
+```
+
+Cada opção é `{ label, value?, description?, preview?, recommended? }`; `value`
+o padrão é `label` e `preview` renderiza um pequeno trecho de maquete/código sob o
+opção. A promessa é resolvida com o `value` selecionado (ou `value[]` quando
+`allowMultiple`), a string de texto livre quando o usuário escolhe "Outro" ou `null`
+se pularem — fica pendente até que o usuário responda. Requer o painel do agente
+para ser montado (está em todos os modelos).
+
+O agente chega ao mesmo UI através de sua ferramenta `ask-question`: prefira deixar o
+o agente pergunta quando _it_ atinge uma bifurcação genuína que não consegue resolver no contexto; usar
+`askUserQuestion()` quando _UI_ precisa definir uma ação em uma escolha.
+
+## Ponte de host do aplicativo MCP {#mcp-app-host-bridge}
+
+As rotas incorporadas como aplicativos MCP devem ser URL primeiro: carregue o artefato atual de
+parâmetros de caminho/consulta, renderize a rota React real ou um componente compartilhado focado,
+e use a ponte de host apenas para comportamento de propriedade do host. `@agent-native/core/client`
+exporta a chamada de rotas incorporadas dos auxiliares:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client";
+```
+
+`getMcpAppHostContext()` lê o último instantâneo de contexto do host enviado;
+`useMcpAppHostContext()` subscreve componentes React para alterações. A solicitação
+ajudantes (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) retorna `false` fora de um quadro de aplicativo MCP incorporado ou
+`Promise<boolean>` dentro de um quadro. `sendToAgentChat()` usa a mesma ponte para
+prompts enviados automaticamente a partir de rotas incorporadas.
+
+A ponte em si — as mensagens `ui/*` JSON-RPC, o `agentNative.mcpHost.*`
+retransmissão de wrapper, transplante versus renderização de quadro controlado, contexto de host e
+solicitações de modo de exibição — propriedade de
+[External Agents](/docs/external-agents#mcp-app-bridge).
+
+## Sugestões dinâmicas {#dynamic-suggestions}
+
+`<AgentSidebar>`, `<AgentPanel>` e `<AssistantChat>` mesclam `suggestions` estático com sugestões baseadas no contexto por padrão. A estrutura lê `navigation`, `selection`, `pending-selection-context` e o URL atual do estado do aplicativo enquanto um bate-papo vazio está visível e, em seguida, oferece chips de prompt que correspondem à tela atual.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+Defina `dynamicSuggestions={false}` para manter apenas chips estáticos. Passe `getSuggestions` quando um aplicativo deseja chips determinísticos específicos de domínio do mesmo contexto de estado do aplicativo.
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+Gancho React que envolve sendToAgentChat com rastreamento de estado de carregamento:
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core/client";
+
+function GenerateButton() {
+  const [isGenerating, send] = useAgentChatGenerating();
+
+  return (
+    <button
+      disabled={isGenerating}
+      onClick={() => send({
+        message: "Generate a summary",
+        context: documentContent,
+        submit: true,
+      })}
+    >
+      {isGenerating ? "Generating..." : "Generate"}
+    </button>
+  );
+}
+```
+
+`isGenerating` se torna verdadeiro quando você chama `send()` e é redefinido automaticamente para falso quando o agente termina de gerar.
+
+## useDbSync(opções?) {#usedbsync}
+
+Gancho React (anteriormente `useFileWatcher`) que escuta alterações no banco de dados em SSE, recorre à pesquisa e invalida os caches de consulta da estrutura que mantêm o UI alinhado com as gravações do agente:
+
+```ts
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+### Opções {#usedbsync-options}
+
+| Opção              | Tipo               | Descrição                                                                                                      |
+| ------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `queryClient`      | `QueryClient?`     | Cliente de consulta React para invalidação de cache                                                            |
+| `queryKeys`        | `string[]?`        | Obsoleto e ignorado; mantido para sites de chamada antigos                                                     |
+| `pollUrl`          | `string?`          | Poll endpoint URL. Padrão: `"/_agent-native/poll"`                                                             |
+| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only                         |
+| `interval`         | `number?`          | Intervalo de pesquisa em ms. Padrão: `2000`                                                                    |
+| `fallbackInterval` | `number?`          | Intervalo de pesquisa de fallback quando SSE não está disponível. Padrão: `15000`                              |
+| `pauseWhenHidden`  | `boolean?`         | Pausar a pesquisa quando a guia do navegador estiver oculta. Padrão: `true`                                    |
+| `ignoreSource`     | `string?`          | Origem de solicitação por guia a ser ignorada para que uma guia não seja recuperada de suas próprias gravações |
+| `onEvent`          | `(data) => void`   | Retorno de chamada opcional quando SSE/polling recebe um evento de alteração                                   |
+
+Para CRUD normal, prefira `useActionQuery` e `useActionMutation`; actions mutante emite `source: "action"` e esses ganchos são buscados novamente automaticamente.
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+A estrutura usa versões alteradas para sincronizar caches de consulta React com alterações feitas por agentes em segundo plano, cron jobs ou outros usuários.
+
+Quando ocorre qualquer mutação no banco de dados do lado do servidor, o servidor registra um evento de alteração com uma chave `source` específica. O ouvinte `useDbSync` do cliente recebe esses eventos e aumenta o contador de versão de alteração local dessa origem. Ao incluir o contador de versões em suas chaves de consulta React, as consultas são buscadas automaticamente sempre que o back-end notifica o cliente sobre novas atividades.
+
+- **`useChangeVersion(source: string): number`** — retorna um contador que aumenta sempre que o `source` especificado sofre mutação.
+- **`useChangeVersions(sources: readonly string[]): number`** — retorna a soma dos contadores de versão para múltiplas fontes.
+
+### Exemplo: sincronizando uma consulta bruta com o banco de dados
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client";
+
+function DashboardView({ id }) {
+  // Get version for dashboards domain source
+  const v = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+### Modelos de latência e comportamento de invalidação
+
+- **Mutações iniciadas por UI:** Quando você executa uma ação do UI usando `useActionMutation`, a mutação dispara imediatamente um evento local com `source: "action"` em caso de sucesso. Isso aciona uma **nova busca instantânea e otimista** de todas as chaves de consulta dependendo da ação, evitando atraso visual.
+- **Mutações em segundo plano ou de agente:** Quando o agente de IA, um webhook ou um trabalhador em segundo plano altera dados, a atualização é transmitida para o cliente. O `useDbSync` do cliente captura isso instantaneamente por meio de SSE (eventos enviados pelo servidor) ou recorre ao **tique de pesquisa de 2 segundos**. A versão da chave de consulta então falha, acionando uma nova busca em segundo plano.
+
+```an-diagram title="Two paths to a refetch" summary="A local mutation invalidates its own caches instantly; a remote write reaches this tab over SSE, or the polling tick as a fallback."
+{
+  "html": "<div class=\"diagram-latency\"><div class=\"diagram-col\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill ok\">This tab</span><strong>useActionMutation</strong><small class=\"diagram-muted\">fires source: \"action\" on success &rarr; instant local refetch</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Agent · webhook · other tab</span><strong>Remote write</strong><small class=\"diagram-muted\">SSE push, or the ~2s polling tick as fallback &rarr; version bumps &rarr; background refetch</small></div></div></div>",
+  "css": ".diagram-latency .diagram-col{display:flex;flex-direction:column;gap:12px}.diagram-latency .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px}"
+}
+```
+
+## cn(...entradas) {#cn}
+
+Utilitário para mesclar nomes de classes (clsx + tailwind-merge):
+
+```ts
+import { cn } from "@agent-native/core/client";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```