@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,142 @@
+---
+title: "FAQ"
+description: "Perguntas comuns sobre agente nativo: o que é, para quem se destina, o que você pode criar e como funciona."
+---
+
+# FAQ
+
+Perguntas comuns sobre agente nativo, organizadas de "Estou apenas olhando" até "Estou conectando a autenticação agora".
+
+## O básico {#general}
+
+### O que é agente nativo? {#what-is-agent-native}
+
+Agent-native é uma estrutura para criar aplicativos onde o agente de IA e a superfície do produto ao seu redor são parceiros iguais. Essa superfície pode começar como um agente headless com uma ação personalizada, evoluir para um bate-papo avançado ou se tornar um UI completo. A invariante é que agentes e humanos compartilham o mesmo actions, banco de dados e estado. Consulte [What Is Agent-Native?](/docs/what-is-agent-native) para obter a explicação completa.
+
+### Para quem é isso? {#who-is-this-for}
+
+Agente nativo é para pessoas que desejam que um aplicativo real e um agente de IA trabalhem a partir dos mesmos dados e actions. Os caminhos comuns são:
+
+- **Use um aplicativo hospedado** se quiser Mail, Calendário, Formulários, Plano ou outro modelo finalizado sem configuração. Comece no [template gallery](/templates).
+- **Comece com bate-papo** se quiser um aplicativo básico com o qual os usuários possam conversar imediatamente e, em seguida, estenda com actions e telas — comece com [Getting Started](/docs/getting-started) ou [Chat](/docs/template-chat).
+- **Inicie o primitivo primeiro** se quiser uma ação e um loop de agente de aplicativo sem comando antes de confirmar com UI — comece com [Getting Started](/docs/getting-started).
+- **Bifurque e personalize um modelo** se desejar seu próprio produto SaaS com autenticação, banco de dados, UI e agente actions já conectados — consulte [Templates](/docs/cloneable-saas).
+- **Compile do zero** se quiser as primitivas da estrutura para um novo produto orientado por agente — comece com [Getting Started](/docs/getting-started).
+- **Conecte outro agente ou ferramenta de código** se desejar que Claude, ChatGPT, Codex, Cursor ou GitHub Copilot / VS Code usem um aplicativo nativo do agente — consulte [External Agents](/docs/external-agents) e [Skills Guide](/docs/skills-guide).
+
+### Qual a diferença entre isso e adicionar IA a um aplicativo existente? {#how-is-this-different}
+
+A maioria dos aplicativos utiliza a IA como uma reflexão tardia que não pode realmente _fazer_ coisas no aplicativo. Em um aplicativo nativo do agente, o agente é um cidadão de primeira classe que compartilha o mesmo actions, banco de dados e estado que o UI, portanto, pode fazer qualquer coisa que os botões puderem — e modificar o próprio código do aplicativo. Consulte [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder).
+
+```an-diagram title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI."
+{
+  "html": "<div class=\"diagram-vs\"><div class=\"diagram-col\"><span class=\"diagram-pill warn\">Bolted-on AI</span><div class=\"diagram-node\">Chat sidebar</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>separate AI world<br><small class=\"diagram-muted\">can't touch the app</small></div><div class=\"diagram-box diagram-muted\">App UI &amp; data</div></div><div class=\"diagram-divider\" aria-hidden=\"true\"></div><div class=\"diagram-col\"><span class=\"diagram-pill ok\">Agent-native</span><div class=\"diagram-row2\"><div class=\"diagram-node\">UI</div><div class=\"diagram-node\">Agent</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>shared actions, DB &amp; state</div></div></div>",
+  "css": ".diagram-vs{display:flex;align-items:stretch;gap:18px;flex-wrap:wrap}.diagram-vs .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:center;flex:1;min-width:200px}.diagram-vs .diagram-row2{display:flex;gap:8px}.diagram-vs .diagram-arrow{font-size:20px;line-height:1}.diagram-vs .diagram-divider{width:1px;align-self:stretch;background:currentColor;opacity:.15}"
+}
+```
+
+### É código aberto? {#is-this-open-source}
+
+Sim. A estrutura e todos os modelos são de código aberto. Você pode executar tudo localmente, hospedar-se sozinho ou usar a nuvem do Builder.io para hospedagem gerenciada, colaboração e recursos de equipe.
+
+### Quanto custa? {#how-much}
+
+A estrutura em si é gratuita. Os dois custos que você verá na prática:
+
+- **Uso de IA.** Você traz sua própria chave API (Anthropic, OpenAI, etc.) e paga diretamente ao fornecedor do modelo. Não há nenhuma marcação nossa.
+- **Hospedagem.** Quaisquer que sejam as tarifas do seu anfitrião. A maioria dos modelos funciona bem em níveis gratuitos (Netlify, Vercel, Cloudflare) para pequenas cargas de trabalho.
+
+Se você preferir não gerenciar nada disso, a versão hospedada no `agent-native.com` (operada pela Builder.io) agrupa inferência e hospedagem em um plano por usuário.
+
+### Posso hospedar isso sozinho? {#can-i-self-host}
+
+Sim. Escolha qualquer host que execute Node – Netlify, Vercel, Cloudflare, AWS, Deno Deploy, seu próprio servidor – e qualquer banco de dados SQL (Postgres, SQLite, Turso, D1). A estrutura foi construída para ser portátil. Consulte [Deployment](/docs/deployment).
+
+### Quais modelos de IA são compatíveis? {#what-models}
+
+Anthropic Claude, OpenAI (família GPT-5), Google Gemini e qualquer fornecedor que fale o formato OpenAI API (incluindo modelos locais via Ollama). Você configura o modelo nas configurações; a troca é uma mudança de configuração, não uma reescrita de código. O caminho testado mais pesado da estrutura é Claude, então essa é a recomendação padrão.
+
+### Preciso conhecer IA/ML? {#do-i-need-to-know-ai}
+
+Não. Você não treina modelos, não ajusta ou lida com incorporações. Você cria um aplicativo da web normal – e na versão hospedada, você quase não constrói nada. A estrutura lida com a integração do agente: roteamento de mensagens, execução de actions, sincronização de estado.
+
+### Posso migrar um aplicativo existente para agente nativo? {#can-i-use-existing-code}
+
+Você pode, mas o agente nativo funciona melhor quando construído do zero. A arquitetura – banco de dados compartilhado, sincronização de polling, actions, estado do aplicativo – precisa ser totalmente integrada. Começar a partir de um modelo e personalizá-lo é o caminho recomendado. Pense nisso como a mudança do desktop para o mobile: você _pode_ fazer o retrofit, mas construir nativo é melhor.
+
+## Modelos e o que você pode construir {#templates}
+
+### Quais modelos estão disponíveis? {#what-templates-are-available}
+
+A estrutura vem com modelos prontos para produção, incluindo [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (planos visuais e recapitulações de relações públicas), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch) e muito mais. Cada um é um aplicativo completo com UI, agente actions, esquema de banco de dados e instruções de IA prontas para uso. Consulte [Templates](/docs/cloneable-saas) para o catálogo completo.
+
+### Posso personalizar modelos? {#can-i-customize-templates}
+
+Esse é o ponto principal. Bifurque um modelo e personalize-o perguntando ao agente. "Adicione um campo prioritário aos formulários." "Conecte-se à nossa instância do Salesforce." "Mude o esquema de cores para combinar com a nossa marca." O agente modifica o código e seu aplicativo evolui com o tempo.
+
+### Posso criar algo que os modelos não cobrem? {#build-from-scratch}
+
+Sim. Se você deseja um aplicativo de bate-papo básico, execute `npx @agent-native/core@latest create my-chat-app --template chat`; você obtém threads de bate-papo duráveis, actions, autenticação, estado de tempo de execução apoiado por SQL e espaço para adicionar suas próprias telas. Se você deseja o menor aplicativo de ação sem UI, execute `npx @agent-native/core@latest create my-agent --headless`. Consulte [Getting Started](/docs/getting-started), [Pure-Agent Apps](/docs/pure-agent-apps) e [Chat](/docs/template-chat).
+
+### Posso experimentar sem bifurcar um modelo? {#try-with-a-skill}
+
+Sim — instale uma habilidade em um agente de codificação que você já usa com um comando e sem necessidade de scaffold. Consulte o [Skills Guide](/docs/skills-guide#app-backed-skills) para ver o passo a passo.
+
+## Recursos do agente {#agent-capabilities}
+
+### O agente pode realmente modificar o código do próprio aplicativo? {#can-the-agent-modify-code}
+
+Sim, e é um recurso. O agente pode editar com segurança componentes, rotas, estilos e actions. Você pergunta “adicionar um gráfico de análise de coorte” e o agente o constrói. Você pergunta “conectar-se à nossa conta Stripe” e o agente escreve a integração. Tudo é código normal rastreado pelo Git, portanto, alterações incorretas são fáceis de reverter.
+
+### Os usuários podem falar com o agente de fora do aplicativo? {#external-channels}
+
+Sim. O mesmo agente é executado em seu web UI, em Slack, em Telegram, por e-mail e de outros agentes (via [A2A](/docs/a2a-protocol)). É o mesmo agente com a mesma memória e o mesmo actions, apenas alcançado através de canais diferentes. Consulte [Messaging the agent](/docs/messaging).
+
+### Os agentes podem conversar entre si? {#can-agents-talk-to-each-other}
+
+Sim, através do [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Cada aplicativo nativo do agente obtém automaticamente um endpoint A2A. No aplicativo de e-mail, você pode marcar o agente de análise para consultar dados. Um agente descobre quais outros agentes estão disponíveis, chama-os pelo protocolo e mostra os resultados no UI. Não é necessária configuração: o cartão do agente é gerado automaticamente a partir do actions do seu modelo.
+
+### O que o agente pode ver no aplicativo? {#what-can-the-agent-see}
+
+O agente sempre sabe o que o usuário está visualizando no momento. O UI grava o estado de navegação no banco de dados em cada mudança de rota – qual visualização está aberta, qual item está selecionado. O agente lê isso antes de agir. Se um e-mail estiver aberto, o agente saberá qual e-mail. Se um slide for selecionado, o agente saberá qual slide. Consulte [Context Awareness](/docs/context-awareness).
+
+## Perguntas de desenvolvimento {#development}
+
+### Quais ferramentas de codificação de IA funcionam com agentes nativos? {#which-ai-tools-work}
+
+Qualquer ferramenta de codificação de IA que leia instruções do projeto. A estrutura usa AGENTS.md como padrão universal e cria automaticamente links simbólicos para ferramentas específicas:
+
+- **Código Claude** — lê CLAUDE.md (linkado simbolicamente de AGENTS.md pela configuração CLI)
+- **Cursor** — lê AGENTS.md diretamente ou `.cursorrules` (local legado do Cursor) se presente em seu projeto
+- **Windsurf** — lê .windsurfrules (linkado simbolicamente de AGENTS.md pela configuração CLI)
+- **Codex, Gemini e outros** — trabalhe por meio do painel de agente integrado
+- **Builder.io** — agente hospedado na nuvem com edição visual e colaboração
+
+### Posso usar meu próprio banco de dados? {#can-i-use-my-own-database}
+
+Sim. Defina `DATABASE_URL` e a estrutura o detecta automaticamente. Os bancos de dados suportados incluem SQLite, Postgres (Neon, Supabase, plain), Turso (libSQL) e Cloudflare D1. Todo SQL é independente de dialeto via Drizzle ORM — o mesmo código funciona em qualquer lugar.
+
+### Onde posso implantar? {#where-can-i-deploy}
+
+Em qualquer lugar. O servidor é executado em Nitro, que compila para qualquer destino de implantação: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda e Bun. Você também pode usar a hospedagem Builder.io para implantações gerenciadas. Veja o [Deployment guide](/docs/deployment).
+
+## Arquitetura {#architecture}
+
+### Por que SSE mais polling em vez de WebSockets? {#why-polling-not-websockets}
+
+SSE fornece às gravações do mesmo processo um caminho imediato para o navegador, e uma pesquisa leve de contador de versões continua sendo a alternativa porque funciona em todos os ambientes de implantação - incluindo sem servidor e de borda, onde soquetes persistentes podem não estar disponíveis. Consulte [Key Concepts — Live sync](/docs/key-concepts#polling-sync).
+
+```an-diagram title="SSE first, polling fallback" summary="Same-process writes stream instantly; a version-counter poll keeps serverless, edge, and cross-process writes convergent."
+{
+  "html": "<div class=\"diagram-transport\"><div class=\"diagram-box\" data-rough>DB write</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">SSE<br><small class=\"diagram-muted\">/_agent-native/events &middot; instant</small></div><div class=\"diagram-node\">Poll<br><small class=\"diagram-muted\">/_agent-native/poll &middot; universal fallback</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Browser refetch</div></div>",
+  "css": ".diagram-transport{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-transport .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-transport .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+### Por que o UI não pode chamar um LLM diretamente? {#why-no-inline-llm-calls}
+
+A IA não é determinística, portanto, você precisa de fluxo de conversa para fornecer feedback e iterar (não botões únicos) e o agente já tem sua base de código, instruções, skills e histórico que faltam em uma chamada inline. Rotear tudo através do agente também é o que permite que o aplicativo seja conduzido a partir de Slack, Telegram ou outro agente. Consulte [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge).
+
+### Por que isso é um framework e não uma biblioteca? {#why-framework-not-library}
+
+O banco de dados compartilhado, a sincronização ao vivo, o sistema actions e o estado do aplicativo só funcionam porque estão conectados desde o início: o UI reage instantaneamente às alterações do agente, os agentes se comunicam e o agente entende o que o usuário está vendo. Uma biblioteca oferece peças; isso é uma arquitetura. Consulte [Key Concepts](/docs/key-concepts).

package/docs/content/locales/pt-BR/file-uploads.md

@@ -0,0 +1,122 @@
+---
+title: "Uploads de arquivos"
+description: "Configurar armazenamento de upload de arquivo — substituto SQL para dev, Builder.io ou provedores personalizados para produção."
+---
+
+# Uploads de arquivos
+
+A estrutura fornece uma abstração de upload de arquivo que roteia uploads por meio de um provedor configurável. Os modelos chamam `uploadFile()` e retornam um URL — o back-end de armazenamento pode ser trocado sem alterar o código do aplicativo.
+
+## Como funciona {#how-it-works}
+
+As solicitações de upload vão para `POST /_agent-native/file-upload`, que é despachado para o provedor ativo. Você pode verificar qual provedor está configurado em `GET /_agent-native/file-upload/status`.
+
+A ordem de resolução do provedor é:
+
+1. **Provedores registrados pelo usuário** — provedores personalizados registrados via `registerFileUploadProvider()`
+2. **Provedor Builder.io** — integrado, ativado automaticamente quando Builder.io é conectado
+3. **SQL substituto** — armazena arquivos como base64 no banco de dados (ótimo para desenvolvimento, não para produção)
+
+```an-diagram title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. The SQL fallback always exists so uploads work with zero setup."
+{
+  "html": "<div class=\"diagram-upload\"><div class=\"diagram-box\" data-rough>uploadFile()<br><small class=\"diagram-muted\">POST /_agent-native/file-upload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-step\"><span class=\"diagram-pill accent\">1</span><div class=\"diagram-node\">User-registered<br><small class=\"diagram-muted\">registerFileUploadProvider() — S3, R2, GCS…</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><div class=\"diagram-node\">Builder.io<br><small class=\"diagram-muted\">auto when connected — CDN-served</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill warn\">3</span><div class=\"diagram-node\">SQL fallback<br><small class=\"diagram-muted\">base64 in DB — dev only</small></div></div></div></div>",
+  "css": ".diagram-upload{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-upload .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-upload .diagram-step{display:flex;align-items:center;gap:8px}.diagram-upload .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The upload endpoint" method="POST" path="/_agent-native/file-upload"
+{
+  "method": "POST",
+  "path": "/_agent-native/file-upload",
+  "summary": "Upload a file through the active provider and get back a public URL.",
+  "description": "Dispatches to the first configured provider in resolution order. Check the active provider at `GET /_agent-native/file-upload/status`.",
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "{ url, id?, provider } — the public URL and which provider handled it." }
+  ]
+}
+```
+
+## Padrão: substituto SQL {#sql-fallback}
+
+Quando nenhum provedor está configurado, os arquivos são armazenados como dados base64 no banco de dados SQL por meio do sistema de recursos. Isso funciona imediatamente para desenvolvimento local, mas não é recomendado para produção: arquivos grandes sobrecarregam o banco de dados e não há CDN.
+
+Um aviso único é registrado quando o substituto é usado.
+
+## Hospedagem Builder.io {#builder-hosting}
+
+Quando seu aplicativo está conectado ao Builder.io, os uploads de arquivos são automaticamente roteados para a hospedagem de ativos do Builder. Os arquivos são servidos a partir de um CDN sem necessidade de configuração. Esta é a configuração de produção recomendada.
+
+## Provedores personalizados {#custom-providers}
+
+Registre um provedor personalizado em um plug-in de servidor para usar qualquer back-end de armazenamento (S3, Cloudflare R2, GCS etc.):
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## Carregar API {#upload-api}
+
+A interface `FileUploadProvider`:
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+Use `uploadFile()` de `@agent-native/core/file-upload` em actions ou código do servidor:
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL fallback yourself, or skip
+}
+```

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

@@ -0,0 +1,153 @@
+---
+title: "Quadros"
+description: "O quadro de desenvolvimento local, o painel do agente incorporado e o quadro da nuvem: as formas como um agente de IA é executado junto com seu aplicativo."
+---
+
+# Quadros
+
+Todo aplicativo nativo do agente é executado com um agente de IA próximo ao aplicativo UI. Um **quadro** é
+o wrapper que hospeda ambos: ele mostra seu aplicativo e dá ao agente um local para
+converse, execute e (no desenvolvimento) edite o código. Existem três frames, compartilhando um tempo de execução:
+
+- **Painel de agente incorporado** — fornecido em todos os aplicativos do `@agent-native/core`.
+  Esta é a barra lateral que seu aplicativo renderiza, em desenvolvimento e em produção.
+- **Quadro de desenvolvimento local** — um wrapper fino que carrega seu aplicativo em execução em um iframe
+  e adiciona o mesmo painel de agente mais um terminal CLI integrado ao lado dele. Usado
+  para desenvolvimento local de modelos neste repositório.
+- **Builder.io cloud frame** — um frame gerenciado e hospedado com colaboração,
+  edição visual e execução de agentes paralelos.
+
+O código do seu aplicativo é idêntico, independentemente do quadro que o hospeda. O agente fala
+ao seu aplicativo por meio do mesmo actions e estado do aplicativo em todos os casos.
+
+```an-diagram title="Three frames, one runtime" summary="Your app and the agent panel are the same in every frame; only the wrapper around them changes."
+{
+  "html": "<div class=\"diagram-frames\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Embedded panel</span><small class=\"diagram-muted\">ships in every app · dev + prod</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Local dev frame</span><small class=\"diagram-muted\">app in an iframe + panel + CLI terminal</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Builder.io cloud frame</span><small class=\"diagram-muted\">hosted: collaboration · visual edit · parallel runs</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Same runtime<br><small class=\"diagram-muted\">your app · actions · application state</small></div></div>",
+  "css": ".diagram-frames{display:flex;flex-direction:column;gap:10px;align-items:stretch}.diagram-frames .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-frames .diagram-arrow{font-size:22px;line-height:1;align-self:center}"
+}
+```
+
+## Painel de agente incorporado {#embedded-agent}
+
+O painel incorporado é a barra lateral do agente que seu aplicativo renderiza. Ele é enviado com
+`@agent-native/core` — não há pacote separado para instalar — e é o mesmo
+componente em desenvolvimento e produção.
+
+- Exportado como `AgentPanel` de `@agent-native/core/client`, com um
+  variante somente de produção `ProductionAgentPanel`.
+- Fornece a superfície completa do Chat / CLI / Workspace, para que a entrada do agente permaneça ativada
+  a pilha compartilhada do compositor usada em todos os outros lugares da estrutura.
+- Lê `application_state.navigation` a cada turno, então já sabe qual
+  visualização em que você está e o que está selecionado. Você não precisa explicar novamente "isso".
+
+### Modos de ferramenta Aplicativo vs Código {#tool-modes}
+
+O painel é executado em um dos dois modos de ferramenta:
+
+- **Modo aplicativo** — o agente possui apenas as ferramentas próprias do seu aplicativo: o actions você
+  definido com `defineAction`, além de navegação e contexto. Nenhum sistema de arquivos ou
+  acesso ao shell. Isso é o que os usuários finais recebem.
+- **Modo de código** — adiciona as ferramentas de codificação compartilhadas (`bash`, `read`, `edit`, `write`)
+  e acesso ao banco de dados além das ferramentas do aplicativo, para que o agente possa alterar as configurações do aplicativo
+  fonte própria. Solicitações de código são bloqueadas: quando uma mensagem requer código
+  (`type: "code"`) e nenhum quadro com capacidade de código estiver conectado, o painel mostra um
+  caixa de diálogo explicando que alterações de código precisam de Agent Native Desktop ou Builder;
+  quando um quadro é conectado, a solicitação é roteada para ele e para um agente de código
+  indicador mostra enquanto funciona (`useSendToAgentChat`). Para o canônico
+  lista de ferramentas de codificação e contratos UI compartilhados, consulte
+  [Agent-Native Code UI](/docs/code-agents-ui).
+
+```an-diagram title="Code-request gating" summary="A code-typed message needs a code-capable frame. With one connected, the request routes there; without one, the panel explains code changes need Desktop or Builder."
+{
+  "html": "<div class=\"diagram-gate\"><div class=\"diagram-node\" data-rough>message<br><small class=\"diagram-muted\">type: \\\"code\\\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>code-capable frame connected?</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">yes &rarr; route to frame, show code-agent indicator</div><div class=\"diagram-pill warn\">no &rarr; dialog: needs Desktop or Builder</div></div></div>",
+  "css": ".diagram-gate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-gate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-gate .diagram-arrow{font-size:22px;line-height:1}.diagram-gate .center{text-align:center}"
+}
+```
+
+"Modo de código" é a alternância da capacidade do agente — diferente do modo de desenvolvimento do ambiente
+(`NODE_ENV`/Vite). O gancho do cliente é `useCodeMode()`. (Veja
+[Compatibility notes](#compatibility) para os aliases de retrocompatibilidade.)
+
+No quadro de desenvolvimento local, a engrenagem de configurações alterna entre esses modos. Troca
+o modo off Code oculta a barra lateral do próprio frame e mostra o agente no aplicativo do aplicativo
+barra lateral dentro do iframe, para que você possa visualizar exatamente o que os usuários finais veem.
+
+## Terminal integrado e comutação CLI {#cli-terminal}
+
+Em desenvolvimento, o painel inclui um terminal incorporado (`AgentTerminal`, também
+de `@agent-native/core/client`) apoiado por um servidor PTY. Você pode executar um verdadeiro
+codifique CLI ao lado do aplicativo e alterne entre eles; o terminal reinicia
+com o CLI selecionado.
+
+Os CLIs suportados vêm do registro CLI principal
+(`packages/core/src/terminal/cli-registry.ts`). Somente estes comandos são permitidos
+para gerar — o servidor PTY valida o comando solicitado no registro
+lista de permissões para evitar injeção:
+
+| CLI           | Comando    | Instalar pacote             |
+| ------------- | ---------- | --------------------------- |
+| Código Claude | `claude`   | `@anthropic-ai/claude-code` |
+| Builder.io    | `builder`  | (integrado)                 |
+| Codex         | `codex`    | `@openai/codex`             |
+| Gêmeos CLI    | `gemini`   | `@google/gemini-cli`        |
+| OpenCode      | `opencode` | `opencode-ai`               |
+
+Se o CLI selecionado não for encontrado em `PATH`, o terminal volta a executá-lo
+através de `npx --yes <install-package>@latest` (onde existe um pacote de instalação). O
+o comando padrão é `claude`. Alterne CLIs nas configurações do painel do agente a qualquer momento
+hora.
+
+## Quadro de nuvem Builder.io {#cloud-frame}
+
+[Builder.io](https://www.builder.io) fornece um quadro gerenciado que hospeda o
+mesmo aplicativo e mesmo painel de agente, na nuvem:
+
+- Colaboração em tempo real: vários usuários podem assistir e interagir ao mesmo tempo.
+- Edição visual, funções e permissões.
+- Execução paralela do agente para iteração mais rápida.
+- Bom para uso em equipe, onde todos compartilham um ambiente hospedado.
+
+As solicitações de código do painel incorporado são roteadas para o quadro Builder da mesma maneira
+eles roteiam para o quadro de desenvolvimento local, então o comportamento dev-vs-prod acima é
+consistente em ambos.
+
+## APIs de tempo de execução {#runtime-apis}
+
+Eles são fornecidos com o `@agent-native/core` e são o que seu aplicativo usa para se comunicar com o
+agente, independentemente do frame que o hospeda:
+
+1. **Enviar uma mensagem** — `sendToAgentChat()` envia uma mensagem ao agente. O
+   O gancho `useSendToAgentChat()` envolve-o com o gate de solicitação de código descrito
+   acima e retorna um elemento `codeRequiredDialog` para renderizar. Veja
+   [Drop-in Agent](/docs/drop-in-agent) para uso completo e opções.
+2. **Estado de geração** — `useAgentChatGenerating()` rastreia quando o agente está
+   em execução, para que o UI possa mostrar o progresso sem consultar o agente diretamente.
+3. **Sincronização de pesquisa** — a sincronização baseada em banco de dados mantém os caches UI atualizados quando o agente
+   altera os dados ou o estado do aplicativo.
+4. **Sistema de ação** — `pnpm action <name>` despacha para o mesmo chamável
+   actions que o agente invoca como ferramentas, então tudo o que o agente pode fazer, você pode
+   roteiro.
+
+## Executando {#running}
+
+O painel do agente incorporado faz parte de todos os aplicativos. Crie um modelo e pronto
+já está lá:
+
+```bash
+npx @agent-native/core@latest create my-app --template mail --standalone
+cd my-app
+pnpm dev
+```
+
+O quadro de desenvolvimento local (o pacote `@agent-native/frame` privado no repositório da estrutura) é um pacote de ferramentas interno que não é publicado no npm. Ele carrega o servidor de desenvolvimento do aplicativo ativo em um iframe e monta o painel incorporado ao lado dele, selecionando o aplicativo por meio do parâmetro de consulta `app`. O terminal CLI integrado requer o Agent Native Desktop, que fornece o código local e acesso PTY às necessidades do terminal; sem ele, o painel mostra a superfície de bate-papo e solicita que você abra a área de trabalho para usar o CLI.
+
+## Notas de compatibilidade {#compatibility}
+
+O conceito de "modo de código" era anteriormente chamado de "modo de desenvolvimento", portanto, alguns retrocompatibilidades
+os nomes persistem. Você pode ignorá-los, a menos que esteja mantendo uma integração mais antiga
+código:
+
+- A variável de ambiente `AGENT_MODE` subjacente, o `/_agent-native/agent-chat/mode`
+  endpoint (cuja chave de carga útil ainda é `devMode`) e o `agent-chat.mode`
+  a chave de configurações permanece inalterada.
+- `useDevMode()` permanece como um alias obsoleto para `useCodeMode()`.

package/docs/content/locales/pt-BR/getting-started.md

@@ -0,0 +1,199 @@
+---
+title: "Primeiros passos"
+description: "Crie um aplicativo de agente, entenda as instruções skills e actions e observe o agente chamar sua primeira ação."
+---
+
+# Primeiros passos
+
+Os aplicativos Agent-Native fornecem a um agente de IA e ao seu UI os mesmos actions, dados e
+estado. Um agente básico é feito de instruções que o orientam, skills que ensinam
+comportamento repetível e actions que permite que ele faça um trabalho real.
+
+**Quer um aplicativo completo para começar?** Clone um de nossos modelos avançados —
+[Chat](/docs/template-chat), [Mail](/docs/template-mail),
+[Calendar](/docs/template-calendar), [Content](/docs/template-content),
+[Analytics](/docs/template-analytics) e [many more](/docs/cloneable-saas) —
+cada um deles é um aplicativo completo que você personaliza.
+
+Construir do zero? A única escolha inicial é se você deseja um UI —
+tudo depois (escrever instruções, adicionar skills, definir actions, executar
+o agente) é o mesmo de qualquer maneira.
+
+```an-file-tree title="A basic Agent-Native agent"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, rules, tone, and the map of what the agent can do" },
+    { "path": ".agents/skills/customer-research/SKILL.md", "note": "a reusable playbook the agent loads when the task matches" },
+    { "path": "actions/summarize-week.ts", "note": "typed code the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks can run" }
+  ]
+}
+```
+
+Isso é verdade quer você comece com um bate-papo UI, um agente sem cabeça ou um aplicativo completo.
+O UI muda a superfície; instruções, skills e actions dão ao agente seu
+orientação e comportamento.
+
+## 1. Crie seu aplicativo
+
+Você precisará de [Node.js 22+](https://nodejs.org) e [pnpm](https://pnpm.io).
+
+Execute `create` sem sinalizadores e ele perguntará como você deseja iniciar (um modelo completo,
+Chat ou Headless) antes de mais nada:
+
+```bash
+npx @agent-native/core@latest create my-app
+```
+
+Ou passe um sinalizador para ignorar o prompt:
+
+**Quer um UI?** Comece pelo modelo de bate-papo. Você recebe um agente ativo mais um
+bate-papo personalizável UI, e cada ação que você adiciona aparece nele automaticamente:
+
+```bash
+npx @agent-native/core@latest create my-app --template chat
+```
+
+**Apenas o primitivo sem cabeça?** Comece sem cabeça — o mesmo actions e agente
+loop, sem shell UI:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+Em seguida, instale a partir da pasta que você criou:
+
+```bash
+cd my-agent # or my-app if you chose the Chat template
+pnpm install
+```
+
+De agora em diante, os dois são idênticos.
+
+## 2. Adicione uma ação
+
+Uma ação é uma operação que seu agente — e seu UI — podem chamar. Ambos os andaimes
+envie com este exemplo:
+
+```an-annotated-code title="Sua primeira action"
+{
+  "filename": "actions/hello.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"Diga olá a partir do agente local.\",\n  schema: z.object({\n    name: z.string().default(\"world\"),\n  }),\n  http: { method: \"GET\" },\n  readOnly: true,\n  run: async ({ name }) => {\n    return { message: `Hello, ${name}!` };\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "Descrição da ferramenta", "note": "O agente lê `description` para decidir quando chamar isto como ferramenta." },
+    { "lines": "6-8", "label": "Contrato tipado", "note": "Um `schema` zod valida entradas de todas as superfícies: agente, UI, HTTP, MCP e A2A." },
+    { "lines": "9", "label": "HTTP verb", "note": "Opt this action into an auto-mounted HTTP endpoint." },
+    { "lines": "10", "label": "Read-only", "note": "`readOnly` marks the action as safe to call without approval and cacheable for queries." },
+    { "lines": "11-13", "label": "One implementation", "note": "The `run` body is the single source of truth that every surface executes." }
+  ]
+}
+```
+
+Substitua `hello` pela primeira operação real em seu domínio. Você define uma vez;
+todas as superfícies captam isso.
+
+Use `AGENTS.md` para orientação que deve ser aplicada a cada turno. Use uma habilidade quando o
+o agente precisa de um fluxo de trabalho ou procedimento de domínio reutilizável. Use uma ação quando o
+o agente precisa de uma maneira digitada e testável para ler dados, gravar dados, chamar um API ou
+realizar uma aprovação.
+
+## 3. Execute-o
+
+Chame a ação diretamente:
+
+```bash
+pnpm action hello --name Steve
+```
+
+Ou peça ao agente para ligar para você:
+
+```bash
+pnpm agent "Call the hello action for Steve and explain what happened."
+```
+
+Se você começou a partir do modelo Chat, execute o aplicativo e use o mesmo agente no
+navegador — ele já pode chamar todas as ações que você definir:
+
+```bash
+pnpm dev
+```
+
+Essa ação agora pode ser acessada no chat UI, CLI, HTTP, MCP, A2A,
+trabalhos agendados e webhooks. Defina uma vez, ligue de qualquer lugar.
+
+```an-diagram title="One action, every surface" summary="A single defineAction file fans out to every consumer with no extra wiring."
+{
+  "html": "<div class=\"diagram-fan\"><div class=\"diagram-box\" data-rough>defineAction</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-surfaces\"><span class=\"diagram-pill\">Chat UI</span><span class=\"diagram-pill\">CLI</span><span class=\"diagram-pill\">HTTP</span><span class=\"diagram-pill\">MCP</span><span class=\"diagram-pill\">A2A</span><span class=\"diagram-pill\">Scheduled jobs</span><span class=\"diagram-pill\">Webhooks</span></div></div>",
+  "css": ".diagram-fan{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fan .diagram-surfaces{display:flex;flex-wrap:wrap;gap:8px;max-width:420px}.diagram-fan .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## O estado está integrado
+
+Sem cabeça não significa sem estado. Actions, sessões, estado do aplicativo, threads,
+histórico de execução e credenciais residem em SQL. Localmente é SQLite em
+`data/app.db`; na produção você define `DATABASE_URL`. Veja
+[Deployment](/docs/deployment).
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Headless is still a real app.** The app-agent loop persists sessions, threads, runs, settings, and credentials in SQL — it is not a stateless prompt. You can add a UI later without touching your actions or state."
+}
+```
+
+## Personalizar o UI
+
+Se você começou a partir do modelo Chat, o UI é seu para editar. O bate-papo em si
+é uma pequena rota construída no componente `<AgentChatSurface>`:
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-full" />;
+}
+```
+
+- **`app/routes/_index.tsx`** — a página de bate-papo. Altere as sugestões, vazio
+  estado e layout.
+- **`app/root.tsx`** — o shell do aplicativo. Adicione suas próprias rotas e telas ao redor
+  agente.
+- Coloque o agente em qualquer tela com `<AgentSidebar>`, trabalhe manualmente nele a partir de um
+  botão com `sendToAgentChat()` ou execute uma ação diretamente com
+  `useActionMutation()`.
+
+Veja [Drop-in Agent](/docs/drop-in-agent) para o conjunto completo de componentes e
+[Native Chat UI](/docs/native-chat-ui) para renderizar resultados de ações como tabelas,
+gráficos e cartões digitados em vez de texto simples.
+
+**Começou sem cabeça e quer um UI mais tarde?** O modelo de bate-papo _é_ a rampa de acesso do UI —
+sua camada `app/` (Roteador React + Vite) é exatamente o que o andaime sem cabeça
+deixa de fora. A atitude mais limpa é iniciar (ou reformular) a partir do bate-papo
+modelo; seu estado `actions/`, agente e SQL permanecem inalterados. Veja
+[Agent Surfaces](/docs/agent-surfaces) para cada superfície intermediária.
+
+## Estrutura do projeto
+
+```text
+my-app/
+  actions/         # Agent-callable actions
+  app/             # React frontend (UI templates only; omitted when headless)
+  server/          # Nitro API server (routes, plugins)
+  AGENTS.md        # Always-on agent instructions
+  .agents/         # Skills the agent can pull in when relevant
+  data/app.db      # Local SQLite state when DATABASE_URL is unset
+```
+
+## Para onde ir a seguir
+
+- **[Key Concepts](/docs/key-concepts)** — a arquitetura principal: SQL, actions,
+  sincronização e reconhecimento de contexto.
+- **[Actions](/docs/actions)** — a ação completa API: esquemas, HTTP, autenticação e
+  aprovação.
+- **[Agent Surfaces](/docs/agent-surfaces)** — headless, chat, sidecar incorporado,
+  e aplicativo completo.
+- **[Drop-in Agent](/docs/drop-in-agent)** — adicione o bate-papo do agente a qualquer aplicativo React.
+- **[Deployment](/docs/deployment)** — coloque seu aplicativo em seu próprio domínio.
+- **[FAQ](/docs/faq)** — dúvidas sobre configuração e produto.