@agent-native/core 0.84.34 → 0.84.36

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

@@ -1,259 +1,193 @@
 ---
 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."
+description: "Crie uma app agentic começando pelo chat, adicione uma action, renderize resultados estruturados inline e evolua para uma página persistente que o agent pode abrir."
 ---
 
 # 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.
-
-<FileTree
-  id="doc-block-z4fwh6"
-  title={"Um agente Agent-Native básico"}
-  entries={[
-    {
-      path: "AGENTS.md",
-      note: "Instruções sempre ativas: propósito, regras, tom e mapa do que o agente pode fazer",
-    },
-    {
-      path: ".agents/skills/customer-research/SKILL.md",
-      note: "Um playbook reutilizável que o agente carrega quando a tarefa combina",
-    },
-    {
-      path: "actions/summarize-week.ts",
-      note: "Código tipado que o agente, UI, CLI, HTTP, MCP, A2A, jobs e webhooks podem executar",
-    },
-  ]}
-/>
-
-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:
+Agent-Native é para criar agentic applications: o AI agent e a UI compartilham as mesmas [actions](/docs/actions), dados SQL e application state. O caminho principal começa pelo Chat para que usuários possam falar com o agent imediatamente, e depois adiciona as superfícies de app que o fluxo merece.
 
-```bash
-npx @agent-native/core@latest create my-app
-```
+O fluxo útil:
 
-Ou passe um sinalizador para ignorar o prompt:
+1. Criar uma Chat app.
+2. Adicionar uma action.
+3. Renderizar o resultado da action inline no chat.
+4. Persistir dados em SQL.
+5. Adicionar uma página que o agent pode abrir quando a inspeção visual fizer mais sentido.
 
-**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:
+## 1. Crie uma Chat app {#create-your-app}
+
+Você precisa de [Node.js 22+](https://nodejs.org) e [pnpm](https://pnpm.io).
 
 ```bash
 npx @agent-native/core@latest create my-app --template chat
+cd my-app
+pnpm install
+pnpm dev
 ```
 
-**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
+O template inclui durable chat threads, auth, live sync, diretório `actions/`, actions padrão `view-screen` e `navigate`, e uma app React pronta para estender.
+
+## 2. Adicione uma action {#add-an-action}
+
+Uma action é uma operação tipada que o agent e a UI chamam juntos. Para este fluxo, crie `actions/analyze-responses.ts`: ela analisa respostas de formulários e retorna um formato validado para um gráfico de chat customizado.
+
+{/* prettier-ignore */}
+```ts
+// actions/analyze-responses.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+const responseChartResultSchema = z.object({
+  title: z.string(),
+  points: z.array(z.object({ day: z.string(), responses: z.number() })),
+});
+
+export default defineAction({
+  description: "Analyze recent form responses and render a custom chart.",
+  schema: z.object({ 
+    formId: z.string().default("demo") 
+  }),
+  outputSchema: responseChartResultSchema,
+  chatUI: { 
+    renderer: "responses.response-chart", 
+    title: "Gráfico de respostas" 
+  },
+  readOnly: true,
+  run: async ({ formId }) => ({
+    title: `Responses for ${formId}`,
+    points: [{ day: "Mon", responses: 12 }, { day: "Tue", responses: 18 }, { day: "Wed", responses: 24 }, { day: "Thu", responses: 21 }],
+  }),
+});
 ```
 
-Em seguida, instale a partir da pasta que você criou:
+Execute diretamente:
 
 ```bash
-cd my-agent # ou my-app se você escolheu o modelo Chat
-pnpm install
+pnpm action analyze-responses --formId demo
 ```
 
-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:
-
-<AnnotatedCode
-  id="doc-block-r8sat6"
-  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: "Verbo HTTP",
-      note: "Exponha esta ação em um endpoint HTTP montado automaticamente.",
-    },
-    {
-      lines: "10",
-      label: "Somente leitura",
-      note: "`readOnly` marca a ação como segura para chamar sem aprovação e cacheável para consultas.",
-    },
-    {
-      lines: "11-13",
-      label: "Uma implementação",
-      note: "O corpo de `run` é a única fonte da verdade que todas as superfícies executam.",
-    },
-  ]}
-/>
-
-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:
+Ou peça ao agent no navegador:
 
-```bash
-pnpm action hello --name Steve
-```
+> Analise as respostas recentes do formulário de demonstração.
 
-Ou peça ao agente para ligar para você:
+## 3. Renderize o resultado no chat {#render-inline}
 
-```bash
-pnpm agent "Call the hello action for Steve and explain what happened."
-```
+Como a action declara `outputSchema` e uma `chatUI.renderer` específica do produto, o transcript não transforma dados estruturados em texto corrido. Registre um componente React para esse id exato no startup da app, por exemplo importando `app/chat-renderers.tsx` uma vez a partir de `app/root.tsx`:
 
-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:
+{/* prettier-ignore */}
+```tsx
+import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
+
+type ResponseChartResult = {
+  title: string;
+  points: Array<{ day: string; responses: number }>;
+};
+
+function ResponseChart({ context }: ToolRendererProps) {
+  const result = context.resultJson as ResponseChartResult;
+  const max = Math.max(...result.points.map((point) => point.responses), 1);
+  return (
+    <section className="rounded-lg border bg-card p-4">
+      <h3 className="text-sm font-medium">{result.title}</h3>
+      <div className="mt-4 flex h-32 items-end gap-2">
+        {result.points.map((point) => (
+          <div key={point.day} className="flex flex-1 flex-col items-center gap-2">
+            <div className="w-full rounded-t bg-primary" style={{ height: `${(point.responses / max) * 100}%` }} />
+            <span className="text-xs text-muted-foreground">{point.day}</span>
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}
 
-```bash
-pnpm dev
+registerActionChatRenderer({
+  id: "responses.response-chart",
+  renderer: "responses.response-chart",
+  Component: ResponseChart,
+});
 ```
 
-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.
-
-<Diagram id="doc-block-12nw2be" title={"Uma ação, cada superfície"} summary={"Um único arquivo defineAction é distribuído para todos os consumidores sem fiação extra."}>
-
-```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">Interface de chat</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">Jobs agendados</span
-    ><span class="diagram-pill">Webhooks</span>
-  </div>
-</div>
-```
+Para saídas genéricas reutilizáveis, o framework também oferece renderers integrados `data-chart` e `data-table`, além de `data-insights` para cards combinados de resumo/gráfico/tabela. Veja [Native Chat UI](/docs/native-chat-ui).
 
-```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;
-}
-```
+<WireframeBlock id="doc-block-inline-result-wireframe-pt">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:340px;box-sizing:border-box;padding:24px;display:flex;justify-content:center;align-items:center;background:var(--wf-bg)'><div style='width:min(530px,100%);display:flex;flex-direction:column;gap:14px'><div class='wf-card' data-rough style='align-self:flex-end;max-width:70%;padding:12px 14px'><strong>User</strong><p style='margin:6px 0 0'>Analise respostas de demo.</p></div><div class='wf-card' data-rough style='align-self:flex-start;width:min(370px,100%);padding:14px'><strong>Agent</strong><p class='wf-muted' style='margin:6px 0 12px'>Renderizado com responses.response-chart.</p><section class='wf-card' data-rough style='padding:14px'><h3 style='margin:0 0 12px;font-size:14px'>Gráfico de respostas</h3><div data-rough='line:bottom' style='height:104px;display:flex;align-items:end;gap:8px;border-bottom:1.4px solid var(--wf-line);padding-bottom:4px'><div style='flex:1;display:flex;flex-direction:column;align-items:center;gap:6px'><div data-rough style='height:38px;width:100%;background:color-mix(in srgb, var(--wf-accent) 24%, transparent);border:1.4px solid var(--wf-accent);border-radius:8px 8px 3px 3px'></div><span class='wf-muted'>Seg</span></div><div style='flex:1;display:flex;flex-direction:column;align-items:center;gap:6px'><div data-rough style='height:62px;width:100%;background:color-mix(in srgb, var(--wf-accent) 30%, transparent);border:1.4px solid var(--wf-accent);border-radius:8px 8px 3px 3px'></div><span class='wf-muted'>Ter</span></div><div style='flex:1;display:flex;flex-direction:column;align-items:center;gap:6px'><div data-rough style='height:86px;width:100%;background:color-mix(in srgb, var(--wf-accent) 36%, transparent);border:1.4px solid var(--wf-accent);border-radius:8px 8px 3px 3px'></div><span class='wf-muted'>Qua</span></div><div style='flex:1;display:flex;flex-direction:column;align-items:center;gap:6px'><div data-rough style='height:54px;width:100%;background:color-mix(in srgb, var(--wf-accent) 42%, transparent);border:1.4px solid var(--wf-accent);border-radius:8px 8px 3px 3px'></div><span class='wf-muted'>Qui</span></div></div></section></div></div></div>"
+    }
+  />
+</WireframeBlock>
 
-</Diagram>
+## 4. Persista dados em SQL {#persist-data}
 
-## O estado está integrado
+Quando o resultado precisa ser revisitado, comparado ou atualizado, salve em SQL e mantenha leitura/escrita atrás de actions:
 
-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).
+Defina a tabela com os helpers portáveis do framework, não com imports de `drizzle-orm/sqlite-core` ou `drizzle-orm/pg-core`:
 
-<Callout id="doc-block-bg3mt6" tone="info">
+```ts
+// server/db/schema.ts
+import { integer, now, table, text } from "@agent-native/core/db/schema";
 
-**Headless ainda é um aplicativo real.** O loop do agente de aplicativo persiste sessões, threads, execuções, configurações e credenciais em SQL — não é um prompt sem estado. Você pode adicionar um UI posteriormente sem alterar suas ações ou estado.
+export const responseInsights = table("response_insights", {
+  id: text("id").primaryKey(),
+  formId: text("form_id").notNull(),
+  title: text("title").notNull(),
+  summary: text("summary").notNull(),
+  responseCount: integer("response_count").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+```
 
-</Callout>
+Esses helpers escolhem o backend SQL configurado, então o mesmo schema pode rodar com SQLite local e em produção com Postgres, Turso/libSQL, D1 ou outro provider SQL suportado.
 
-## Personalizar o UI
+- `create-response-insight` escreve um novo insight.
+- `list-response-insights` lê dados para a página.
+- `update-response-insight` atualiza um registro.
+- `analyze-responses` continua retornando o widget nativo do chat.
 
-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>`:
+Não crie uma REST route duplicada só para o navegador; UI e agent devem compartilhar actions.
 
-```tsx
-// app/routes/_index.tsx
-import { AgentChatSurface } from "@agent-native/core/client";
+## 5. Adicione uma página que o agent pode abrir {#add-a-page}
 
-export default function ChatRoute() {
-  return <AgentChatSurface mode="page" className="h-full" />;
-}
-```
+Adicione a route `/response-insights` com `useActionQuery("list-response-insights")` e `useActionMutation("create-response-insight")`. A página é uma projeção do SQL state; os dados continuam sendo escritos pelas mesmas actions.
 
-- **`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()`.
+<WireframeBlock id="doc-block-response-insights-page-wireframe-pt">
+  <Screen
+    surface="desktop"
+    html={
+      "<main style='min-height:440px;box-sizing:border-box;padding:28px;background:var(--wf-bg)'><section style='max-width:960px;margin:0 auto;display:grid;grid-template-columns:minmax(0,1fr) 260px;gap:16px;align-items:stretch'><section class='wf-card' data-rough style='display:flex;flex-direction:column;gap:16px'><header><h2 style='margin:0 0 4px;font-size:28px'>Insights de respostas</h2><p class='wf-muted' style='margin:0'>Insights que o agente criou a partir das respostas do formulário.</p></header><button class='primary' data-rough style='align-self:flex-start'>Analisar formulário demo</button><section style='display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px'><article class='wf-box' data-rough style='padding:12px'><strong>Tema de preços</strong><p class='wf-muted' style='margin:8px 0 0'>Usuários pedem um plano de equipe.</p></article><article class='wf-box' data-rough style='padding:12px'><strong>Queda no onboarding</strong><p class='wf-muted' style='margin:8px 0 0'>Três etapas precisam de texto mais claro.</p></article></section><section class='wf-card' data-rough style='display:flex;flex-direction:column;gap:10px'><div class='wf-row wf-box' data-rough style='padding:10px 12px;gap:12px;justify-content:space-between'><strong>Formulário de demonstração</strong><span class='wf-muted'>42 respostas analisadas</span></div><div class='wf-row wf-box' data-rough style='padding:10px 12px;gap:12px;justify-content:space-between'><strong>Próximo passo</strong><span class='wf-muted'>Revisar dois rascunhos de insights</span></div></section></section><aside class='wf-card' data-rough style='height:100%;box-sizing:border-box;display:flex;flex-direction:column;gap:12px'><strong>Chat</strong><div class='wf-box' data-rough style='align-self:flex-end;max-width:210px;padding:10px 12px'><span class='wf-muted'>Você</span><p style='margin:4px 0 0'>Abra insights de respostas.</p></div><div class='wf-box' data-rough style='align-self:flex-start;max-width:210px;padding:10px 12px'><span class='wf-muted'>Agent</span><p style='margin:4px 0 0'>Insights de respostas abertos.</p></div></aside></section></main>"
+    }
+  />
+</WireframeBlock>
 
-Veja [Drop-in Agent](/docs/drop-in-agent) para o conjunto completo de componentes e
-[Native Interface de chat](/docs/native-chat-ui) para renderizar resultados de ações como tabelas,
-gráficos e cartões digitados em vez de texto simples.
+Estenda `view-screen` e `navigate` para que o agent saiba a route atual e possa abrir `/response-insights`. Resultados também podem incluir `href: "/response-insights"` para mostrar um botão "Abrir insights de respostas".
 
-**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.
+Quando o chat em página inteira abrir uma página da app, use `AgentChatSurface`, `AgentSidebar`, `useAgentChatHomeHandoff`, `useAgentChatHomeHandoffLinks` e `chatViewTransition` de [Agent Surfaces](/docs/agent-surfaces#rich-chat) para mover o chat para a lateral sem perder o thread.
 
-## Estrutura do projeto
+## Estrutura do projeto {#project-structure}
 
 ```text
 my-app/
-  actions/         # Ações que o agente pode chamar
-  app/             # Frontend React (apenas templates UI; omitido em headless)
-  server/          # Servidor API Nitro (rotas, plugins)
-  AGENTS.md        # Instruções permanentes do agente
-  .agents/         # Skills que o agente pode carregar quando relevantes
+  actions/         # Operações acionáveis pelo agente e pela interface
+  app/             # Rotas, páginas e superfícies de chat em React
+  server/          # Servidor Nitro e esquema SQL
+  AGENTS.md        # Instruções sempre ativas para o agente do app
+  .agents/         # Skills que o agente carrega quando relevante
   data/app.db      # Estado SQLite local quando DATABASE_URL não está definido
 ```
 
-## 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.
+## Quer um ponto de partida completo para analytics? {#analytics-starting-point}
+
+O exemplo de Insights de respostas acima é pequeno de propósito para mostrar as peças do framework. Se você estiver criando um produto real de analytics, comece com [Analytics](/docs/template-analytics). É o ponto de partida robusto: conecte seus providers, use os dashboards e agent actions existentes e personalize a partir daí.
+
+## Próximos passos {#next}
+
+- **[Actions](/docs/actions)** — schemas, auth, approvals, hooks e transport.
+- **[Native Chat UI](/docs/native-chat-ui)** — tabelas, gráficos e typed cards para resultados de actions.
+- **[Chat Template](/docs/template-chat)** — a app mínima chat-first.
+- **[Analytics Template](/docs/template-analytics)** — uma base robusta para analytics; conecte providers e personalize a partir daí.
+- **[Context Awareness](/docs/context-awareness)** — `view-screen`, `navigate`, route state e objetos selecionados.
+- **[Agent Surfaces](/docs/agent-surfaces)** — chat, inline UI, app pages, embedded sidecars, automation e agents externos.

package/docs/content/locales/pt-BR/pure-agent-apps.mdx

@@ -1,16 +1,11 @@
 ---
-title: "Aplicativos de agente puro"
-description: "Aplicativos em que o agente é o produto completo: o loop app-agent é a porta de entrada e UI é adicionado apenas quando humanos precisam dele."
+title: "Automation-First Apps"
+description: "Apps Agent-Native sem navegador para scheduled jobs, filas, scripts, integration workers e agents externos."
 ---
 
-# Aplicativos de agente puro
+# Automation-First Apps
 
-Um aplicativo de agente puro é o fim mínimo do agente nativo: o loop app-agent é o
-produto, não um painel. Você envia uma solicitação do terminal, Slack, email, um
-trabalho agendado, outro agente ou bate-papo — "resumir meus e-mails não lidos", "postar o
-métricas diárias para Slack" — e o agente atua e retorna o resultado onde quer que esteja
-pertence. Ainda é um aplicativo real: actions, sessões, estado do aplicativo, histórico,
-configurações, credenciais e registros de compartilhamento, todos ativos em SQL.
+Uma automation-first app é uma app Agent-Native sem navegador para scheduled jobs, filas, scripts, integration workers e agents externos. Não é o caminho padrão de Getting Started, mas é útil quando o workflow ainda não precisa de uma página. Ainda é uma app real: actions, sessions, application state, run history, settings, credentials e registros de compartilhamento vivem em SQL.
 
 <Diagram id="doc-block-8brd1i" title={"O loop app-agent é a porta de entrada"} summary={"Muitos pontos de entrada alcançam um loop de agente sobre ações e estados SQL-backed; os resultados retornam para o local de origem da solicitação. A IU é adicionada apenas quando humanos precisam supervisionar."}>
 

package/docs/content/locales/pt-BR/template-chat.mdx

@@ -7,7 +7,7 @@ description: "Um aplicativo nativo de agente com foco mínimo no chat: threads d
 
 O Chat é o ponto de partida básico do aplicativo nativo do agente. Ele oferece um shell limpo no estilo ChatGPT com bate-papo no centro, uma lista de tópicos à esquerda, navegação padrão do aplicativo, autenticação, sincronização ao vivo, actions e um exemplo de ação. Comece aqui quando quiser um aplicativo de navegador real no qual você possa desenvolver sem se comprometer com um modelo de domínio.
 
-Se você deseja o menor tempo de execução somente de ação sem navegador UI, comece com [Pure-Agent Apps](/docs/pure-agent-apps). Se você quiser um formato de produto de domínio finalizado, comece com [Calendar](/docs/template-calendar), [Mail](/docs/template-mail), [Content](/docs/template-content), [Forms](/docs/template-forms), [Analytics](/docs/template-analytics) ou outro modelo de domínio.
+Se você deseja um runtime automation-first sem navegador UI, comece com [Automation-First Apps](/docs/pure-agent-apps). Se você quiser um formato de produto de domínio finalizado, comece com [Calendar](/docs/template-calendar), [Mail](/docs/template-mail), [Content](/docs/template-content), [Forms](/docs/template-forms), [Analytics](/docs/template-analytics) ou outro modelo de domínio.
 
 <WireframeBlock id="doc-block-a4b2bv">
   <Screen
@@ -200,4 +200,4 @@ O agente deve adicionar um esquema Drizzle, actions, rota, navegação e instru
 - [**Agent Surfaces**](/docs/agent-surfaces) — padrões headless, chat, incorporados e de aplicativo completo
 - [**Actions**](/docs/actions) — o bate-papo do sistema de ação e UI chamam
 - [**Native Interface de chat**](/docs/native-chat-ui) — primitivas da superfície de bate-papo e opções de tempo de execução
-- [**Pure-Agent Apps**](/docs/pure-agent-apps): aplicativos somente de ação que podem se transformar no Chat mais tarde
+- [**Automation-First Apps**](/docs/pure-agent-apps): automações, filas, scripts e workflows de agents externos sem UI de navegador

package/docs/content/locales/pt-BR/using-your-agent.mdx

@@ -99,7 +99,7 @@ O agente não é um aplicativo separado que você acessa. Ele é fornecido como
 
 Nem todo aplicativo precisa de um painel completo. Quando o agente _é_ o produto, você pode pular a maior parte do UI personalizado: abra o aplicativo, peça o que deseja e deixe o agente fazer o resto. O agente ainda tem sua superfície de gerenciamento (histórico, espaço de trabalho, configurações), mas a interação principal é a conversa, e não os cliques.
 
-→ [**Pure-Agent Apps**](/docs/pure-agent-apps) — aplicativos onde o agente é o produto completo.
+→ [**Automation-First Apps**](/docs/pure-agent-apps) — apps sem navegador para jobs, filas, scripts e agents externos.
 
 ## Você coedita com ele {#you-co-edit}
 
@@ -113,5 +113,5 @@ Quando você e o agente estão trabalhando no mesmo documento, vocês não se re
 - [**Agent Mentions**](/docs/agent-mentions) — direcione-o com menções a `@`
 - [**Voice Input**](/docs/voice-input) — direcione falando
 - [**Drop-in Agent**](/docs/drop-in-agent) — incorpore-o em qualquer aplicativo React
-- [**Pure-Agent Apps**](/docs/pure-agent-apps) — vá para UI leve quando o agente for o produto
+- [**Automation-First Apps**](/docs/pure-agent-apps) — apps sem navegador para jobs, filas, scripts e agents externos
 - [**Real-Time Collaboration**](/docs/real-time-collaboration) — coeditam o mesmo documento juntos

package/docs/content/locales/zh-CN/cloneable-saas.mdx

@@ -30,7 +30,7 @@ description: "分叉一个可用的 SaaS 产品并使其成为您的产品 - 包
 | [**Plan**](/docs/template-plan)           | 带有图表、线框图和注释的视觉计划和公关概述。                                                        |
 | [**Dispatch**](/docs/template-dispatch)   | 工作区控制平面：共享秘密、可重用集成、Slack/Telegram、计划作业。                                    |
 
-不需要域应用？当您想要一个用户可以立即交谈的基本应用程序时，请使用 [Chat](/docs/template-chat)，或者从 [Pure-Agent Apps](/docs/pure-agent-apps) 中的一个操作开始。
+不需要域应用？当您想要一个用户可以立即交谈，并可继续扩展 actions、原生结果和页面的基本应用时，请使用 [Chat](/docs/template-chat)。只有在暂时不需要浏览器 UI 的自动化工作流中，才使用 [Automation-First Apps](/docs/pure-agent-apps)。
 
 查看 [Apps](/apps) 下的完整目录，或直接跳到其中一个 - 例如，如果您想要一款工作区风格的应用，[Dispatch](/docs/template-dispatch) 是一个很好的起点。
 
@@ -166,7 +166,7 @@ description: "分叉一个可用的 SaaS 产品并使其成为您的产品 - 包
 
 ## 在此基础上构建
 
-- [**Getting Started**](/docs/getting-started) - 创建一个最小的聊天应用程序或无头代理
+- [**Getting Started**](/docs/getting-started) - 创建聊天优先应用，添加 action，渲染结构化结果，并扩展为页面
 - [**Messaging the agent**](/docs/messaging) - 用户（和您）如何与每个模板附带的代理对话
 - [**Multi-App Workspace**](/docs/multi-app-workspace) — 将多个模板捆绑到一个共享身份验证、品牌和代理的工作区
 - [**Dispatch**](/docs/template-dispatch) — 工作区控制平面模板
@@ -180,7 +180,7 @@ description: "分叉一个可用的 SaaS 产品并使其成为您的产品 - 包
 npx @agent-native/core@latest create my-platform
 ```
 
-您将获得一个多选选择器。选择一个应用程序（独立）或多个应用程序（工作区 - 应用程序共享身份验证、品牌、代理配置和数据库）。每个挑选的模板都与您需要的每个文件一起构建到 `apps/<name>/` 中。对于仅限操作的应用程序而不是模板 UI，请使用 `npx @agent-native/core@latest create my-agent --headless`。
+您将获得一个多选选择器。选择一个应用程序（独立）或多个应用程序（工作区 - 应用程序共享身份验证、品牌、代理配置和数据库）。每个挑选的模板都与您需要的每个文件一起构建到 `apps/<name>/` 中。对于没有浏览器 UI 的自动化应用，而不是模板 UI，请使用 `npx @agent-native/core@latest create my-agent --headless`。
 
 填写`.env`（主要是`ANTHROPIC_API_KEY`和`DATABASE_URL`）、`pnpm install`、`pnpm dev`，就可以了。没有“TODO：实现登录”，没有占位符路由。
 

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

@@ -11,15 +11,15 @@ description: "有关原生代理的常见问题 - 它是什么、它的用途、
 
 ### 什么是代理原生？ {#what-is-agent-native}
 
-Agent-native 是一个用于构建应用程序的框架，其中 AI 代理及其周围的产品表面是平等的合作伙伴。该界面可以从一个无头代理开始，通过一个自定义操作，发展成为丰富的聊天，或者成为一个完整的 UI。不变的是智能体和人类共享相同的 actions、数据库和状态。完整解释请参见 [What Is Agent-Native?](/docs/what-is-agent-native)。
+Agent-native 是一个用于构建应用程序的框架，其中 AI 代理及其周围的产品界面是平等的合作伙伴。通常的路径是从聊天开始，添加 typed actions，在聊天中渲染结构化结果，然后围绕同一份 SQL state 扩展成持久页面。不变的是智能体和人类共享相同的 actions、数据库和状态。完整解释请参见 [What Is Agent-Native?](/docs/what-is-agent-native)。
 
 ### 这是给谁的？ {#who-is-this-for}
 
 Agent-native 适合那些想要真正的应用程序和 AI 代理使用相同数据和 actions 工作的人。常见的路径是：
 
 - **如果您需要邮件、日历、表单、计划或其他无需设置的成品模板，请使用托管应用程序** - 从 [template gallery](/templates) 开始。
-- **从聊天开始**如果您想要一个用户可以立即交谈的基本应用程序，然后使用 actions 和屏幕进行扩展 - 从 [Getting Started](/docs/getting-started) 或 [Chat](/docs/template-chat) 开始。
-- **如果您想要在提交到 UI 之前执行一个操作和一个无头应用程序代理循环，请先启动原语优先** — 从 [Getting Started](/docs/getting-started) 开始。
+- **从聊天开始**如果您想要默认的从零构建路径：用户可以立即与 agent 对话，然后您用 actions、原生结果和屏幕扩展它 - 从 [Getting Started](/docs/getting-started) 或 [Chat](/docs/template-chat) 开始。
+- **从 automation-first 开始**如果您正在构建定时任务、队列、脚本、integration worker 或暂时没有浏览器 UI 的外部 agent 工作流 — 从 [Automation-First Apps](/docs/pure-agent-apps) 开始。
 - **分叉并自定义模板**如果您想要自己的 SaaS 产品，并且已连接身份验证、数据库、UI 和代理 actions — 请参阅 [Templates](/docs/cloneable-saas)。
 - **从头开始构建**如果您想要新的代理驱动产品的框架原语 - 从 [Getting Started](/docs/getting-started) 开始。
 - **如果您希望 Claude、ChatGPT、Codex、Cursor 或 GitHub Copilot / VS Code 使用代理本机应用程序，请连接另一个代理或代码工具** - 请参阅 [External Agents](/docs/external-agents) 和 [Skills Guide](/docs/skills-guide)。
@@ -128,7 +128,7 @@ Anthropic Claude、OpenAI（GPT-5 系列）、Google Gemini 以及使用 OpenAI
 
 ### 我可以构建模板未涵盖的内容吗？ {#build-from-scratch}
 
-是的。如果你想要一个基本的聊天应用程序，请运行`npx @agent-native/core@latest create my-chat-app --template chat`；您可以获得持久的聊天线程、actions、身份验证、SQL 支持的运行时状态以及添加您自己的屏幕的空间。如果您想要没有 UI 的最小操作优先应用程序，请运行 `npx @agent-native/core@latest create my-agent --headless`。请参阅 [Getting Started](/docs/getting-started)、[Pure-Agent Apps](/docs/pure-agent-apps) 和 [Chat](/docs/template-chat)。
+是的。如果你想要一个基本的 agentic app，请运行 `npx @agent-native/core@latest create my-chat-app --template chat`；您可以获得持久的聊天线程、actions、身份验证、SQL 支持的运行时状态、原生内联结果渲染，以及添加自己屏幕的空间。如果您正在构建 no-browser automation，请运行 `npx @agent-native/core@latest create my-agent --headless`。请参阅 [Getting Started](/docs/getting-started)、[Automation-First Apps](/docs/pure-agent-apps) 和 [Chat](/docs/template-chat)。
 
 ### 我可以在不分叉模板的情况下尝试它吗？ {#try-with-a-skill}