@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/pt-BR/creating-templates.md

@@ -0,0 +1,411 @@
+---
+title: "Criando modelos"
+description: "Como criar e publicar seus próprios modelos de aplicativos nativos de agente."
+---
+
+# Criando modelos
+
+Os modelos são aplicativos nativos do agente completos e bifurcáveis que resolvem um fluxo de trabalho real. Os modelos primários são criados com a mesma superfície de estrutura que você usa: rotas React para UI, Drizzle SQL para dados, actions para operações, recursos de espaço de trabalho para comportamento do agente e sincronização de sondagem para que o agente e UI permaneçam alinhados.
+
+Um bom modelo:
+
+- Resolve um fluxo de trabalho de ponta a ponta, com dados iniciais úteis ou um fluxo de estado vazio.
+- Armazena estado durável em arquivos SQL, não em arquivos JSON.
+- Define as operações do aplicativo como `defineAction()` actions.
+- Expõe navegação e seleção por meio do estado do aplicativo.
+- Fornece um `AGENTS.md` claro e um skills focado para fluxos de trabalho não óbvios.
+- Registra etapas de integração para provedores e segredos necessários.
+- Funciona como um aplicativo independente e como parte de um espaço de trabalho com vários aplicativos.
+
+## Iniciar no bate-papo {#start-from-chat}
+
+Use o modelo de bate-papo quando quiser um aplicativo mínimo com a estrutura já instalada:
+
+```bash
+npx @agent-native/core@latest create my-template --template chat --standalone
+```
+
+Para um workspace com vários aplicativos, execute o seletor e inclua o Chat com os modelos de domínio desejados:
+
+```bash
+npx @agent-native/core@latest create my-platform
+```
+
+O Chat oferece autenticação, threads de bate-papo duráveis, recursos apoiados por SQL, ferramentas, estado do aplicativo, actions e sincronização de pesquisa. Você adiciona o modelo de domínio e o produto UI.
+
+Se você ainda não estiver criando um modelo UI reutilizável, use a rampa de acesso headless no [Getting Started](/docs/getting-started#1-create-your-app): defina uma ação, execute-a com `pnpm agent` e adicione UI posteriormente quando o fluxo de trabalho precisar de uma superfície durável.
+
+## Estrutura do Projeto {#project-structure}
+
+Cada modelo segue o mesmo layout amplo:
+
+```an-file-tree title="Template project layout"
+{
+  "title": "my-template/",
+  "entries": [
+    { "path": "app/", "note": "React frontend" },
+    { "path": "app/root.tsx", "note": "HTML shell and providers" },
+    { "path": "app/routes/", "note": "React Router file routes" },
+    { "path": "app/components/", "note": "Template UI" },
+    { "path": "app/hooks/", "note": "UI state and data hooks" },
+    { "path": "actions/", "note": "defineAction operations — the single source of truth" },
+    { "path": "server/db/schema.ts", "note": "Drizzle schema" },
+    { "path": "server/plugins/db.ts", "note": "additive migrations" },
+    { "path": "server/plugins/", "note": "startup integrations" },
+    { "path": "server/routes/api/", "note": "custom routes only when actions are not enough" },
+    { "path": "shared/types.ts", "note": "shared client/server types" },
+    { "path": ".agents/skills/", "note": "<skill>/SKILL.md — agent guidance for complex workflows" },
+    { "path": "AGENTS.md", "note": "template-specific agent instructions" },
+    { "path": "package.json" },
+    { "path": "react-router.config.ts" },
+    { "path": "vite.config.ts" }
+  ]
+}
+```
+
+Não adicione um diretório `data/` para o estado do aplicativo. Os dados duráveis do aplicativo pertencem ao SQL, e o UI os lê por meio do actions ou de manipuladores de servidor digitados.
+
+As quatro áreas de cada modelo se conectam por meio de uma superfície de ação compartilhada e um banco de dados SQL — o agente e o UI são parceiros iguais nas mesmas operações:
+
+```an-diagram title="How a template's four areas connect" summary="The UI and the agent both reach SQL through the same actions; application state and polling sync keep them aligned."
+{
+  "html": "<div class=\"diagram-tmpl\"><div class=\"diagram-col\"><div class=\"diagram-node\">React UI<br><small class=\"diagram-muted\">app/routes · components</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">AGENTS.md · skills</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defineAction()</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL via Drizzle<br><small class=\"diagram-muted\">additive schema</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">Polling sync</div></div>",
+  "css": ".diagram-tmpl{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-tmpl .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-tmpl .diagram-arrow{font-size:22px;line-height:1}.diagram-tmpl .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Dados do modelo em SQL {#data-models}
+
+Defina tabelas de domínio com os auxiliares da estrutura Drizzle para que os esquemas permaneçam portáveis em SQLite, Postgres, D1, Turso, Supabase, Neon e outros back-ends suportados:
+
+```ts
+// server/db/schema.ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  status: text("status", {
+    enum: ["draft", "active", "archived"],
+  })
+    .notNull()
+    .default("draft"),
+  sortOrder: integer("sort_order").notNull().default(0),
+  ...ownableColumns(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export const projectShares = createSharesTable("project_shares");
+```
+
+As alterações de esquema devem ser aditivas. Adicione tabelas e colunas através de `runMigrations()` em `server/plugins/db.ts`; nunca use SQL, `drizzle-kit push` destrutivos, renomeações de tabelas ou eliminações de colunas.
+
+Para leituras e gravações de aplicativos, use o construtor de consultas do Drizzle e os operadores portáteis do `drizzle-orm`. Não escreva o código do produto com SQL bruto quando Drizzle puder expressar a consulta e não importe de `drizzle-orm/sqlite-core` ou `drizzle-orm/pg-core` em modelos.
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'draft',
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      visibility TEXT NOT NULL DEFAULT 'private',
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+Use os documentos [Database](/docs/database) e [Security](/docs/security) antes de adicionar esquemas que contenham dados do usuário ou da organização.
+
+## Definir operações como Actions {#actions}
+
+Actions são a única fonte de verdade sobre o comportamento do aplicativo. O agente os chama como ferramentas, o frontend os chama por meio de ganchos e outros aplicativos podem alcançá-los por meio de MCP/A2A.
+
+```an-annotated-code title="actions/create-project.ts"
+{
+  "filename": "actions/create-project.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { getDb } from \"../server/db/index.js\";\nimport { nanoid } from \"nanoid\";\nimport { z } from \"zod\";\nimport * as schema from \"../server/db/schema\";\n\nexport default defineAction({\n  description: \"Create a project.\",\n  schema: z.object({\n    title: z.string().min(1).describe(\"Project title\"),\n  }),\n  run: async ({ title }, ctx) => {\n    const db = getDb();\n    const id = nanoid();\n    await db.insert(schema.projects).values({\n      id,\n      title,\n      ownerEmail: ctx.userEmail,\n      orgId: ctx.orgId,\n    });\n    return { id, title };\n  },\n});",
+  "annotations": [
+    { "lines": "2", "note": "`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`." },
+    { "lines": "8", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this action as a tool." },
+    { "lines": "9-11", "label": "Contrato tipado", "note": "One zod `schema` validates input from the agent, the UI, HTTP, MCP, and A2A." },
+    { "lines": "18-19", "label": "Scoped write", "note": "Stamp `ownerEmail` / `orgId` from `ctx` so the row is correctly scoped for sharing and access checks." }
+  ]
+}
+```
+
+Use `http: { method: "GET" }` ou `readOnly: true` para actions somente leitura. Use `parallelSafe: true` apenas para actions mutantes que são seguros para serem executados simultaneamente com chamadas de ferramenta no mesmo turno. Use `toolCallable: false` para actions de alto raio de explosão que não deve ser executado em ferramentas em sandbox.
+
+## Construa o UI {#ui}
+
+As rotas residem em `app/routes/` e usam o roteamento de arquivos do React Router v7. Consulte dados por meio de manipuladores actions ou API e torne as mutações otimistas por padrão.
+
+```tsx
+import { useActionMutation, useActionQuery } from "@agent-native/core/client";
+
+export default function ProjectsPage() {
+  const { data: projects = [] } = useActionQuery("list-projects", {});
+  const create = useActionMutation("create-project");
+
+  return (
+    <button onClick={() => create.mutate({ title: "Launch plan" })}>
+      New project ({projects.length})
+    </button>
+  );
+}
+```
+
+Conecte a sincronização ao vivo uma vez perto do shell do aplicativo para que os caches de consulta React sejam atualizados quando o agente, outra guia ou uma ação alterar os dados:
+
+```tsx
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+export function AppSync() {
+  const queryClient = useQueryClient();
+  useDbSync({ queryClient });
+  return null;
+}
+```
+
+**A promessa do agente nativo: as gravações do agente aparecem no UI sem uma atualização manual.** `useActionQuery` é o caminho mais fácil — cada gancho é buscado novamente quando uma ação mutante emite `source: "action"`. Se você acessar `useQuery` bruto com uma chave personalizada (por exemplo, um auxiliar de cliente de baixo nível que lê o status de integração), inclua o contador por origem no queryKey para atualizações direcionadas:
+
+```tsx
+import { useChangeVersions } from "@agent-native/core/client";
+
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({
+  queryKey: ["dashboard", id, v],
+  queryFn: () => fetchDashboard(id),
+  placeholderData: (prev) => prev, // no flicker on refetch
+});
+```
+
+Fontes comuns: `"action"` (cada ação bem-sucedida do agente — o substituto confiável), `"app-state"`, `"settings"`, além de qualquer fonte de recurso personalizada que sua loja emite via `recordChange`. Veja a habilidade `real-time-sync` para o padrão completo.
+
+## Adicionar estado do aplicativo {#application-state}
+
+O estado da aplicação é como o agente sabe o que o usuário está vendo. No mínimo, adicione:
+
+- Um gancho UI que grava o estado semântico `navigation` quando rotas, registros selecionados, guias ativas ou seleções do editor mudam.
+- Uma ação `view-screen` que lê esse estado e retorna o instantâneo da tela atual.
+- Uma ação `navigate` que grava um comando `navigate` único para o UI consumir.
+
+Use `useAgentRouteState` para o gancho UI para que gravações no estado do aplicativo, leituras de comandos com escopo de guia, exclusão após leitura e proteção de comando duplicado permaneçam consistentes:
+
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      selectedId: searchParams.get("id"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+    navigateOptions: { replace: true, flushSync: true },
+  });
+}
+```
+
+Mantenha filtros compartilháveis ​​nos parâmetros de consulta URL. A estrutura os expõe ao agente como `<current-url>` e o agente integrado pode alterá-los com `set-search-params`; `navigation` deve conter IDs semânticos e aliases, e não uma segunda cópia da string de consulta completa.
+
+Para navegação no aplicativo, prefira um comando `navigate` que inclua uma mesma origem
+`path` quando o URL é conhecido. Não escreva também `__set_url__` para o mesmo movimento;
+essa chave é reservada para as ferramentas da estrutura URL e alterações de filtro somente URL.
+
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the UI.",
+  schema: z.object({
+    view: z.enum(["home", "project"]),
+    projectId: z.string().optional(),
+    path: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
+```
+
+Veja [Context Awareness](/docs/context-awareness) para o padrão completo.
+
+## Use rotas API com moderação {#api-routes}
+
+Prefira actions para operações de aplicativos. Crie rotas Nitro personalizadas apenas para superfícies que não podem ser actions limpas:
+
+- Upload de arquivo ou streaming binário.
+- Páginas públicas anônimas e webhooks.
+- Retornos de chamada OAuth e manipuladores de protocolo específicos do provedor.
+- Conteúdo público renderizado pelo servidor.
+
+Rotas personalizadas que tocam dados proprietários devem chamar `getSession(event)` e agrupar o trabalho do banco de dados em `runWithRequestContext({ userEmail, orgId }, fn)` antes de usar auxiliares de acesso.
+
+## Escrever instruções para o agente {#write-agents-md}
+
+`AGENTS.md` é o mapa do agente do seu aplicativo — um arquivo pequeno e passível de leitura com um
+linha de propósito, regras básicas, chaves de estado do aplicativo, uma tabela de ação e um skills
+índice:
+
+```markdown
+# My Template
+
+One workspace for projects, tasks, and notes.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes; schema is additive.
+- Use `view-screen` before acting on "this project" if the screen is unclear.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                  |
+| ---------------- | ------------------------ |
+| `list-projects`  | List accessible projects |
+| `create-project` | Create a project         |
+```
+
+Atualize `AGENTS.md` sempre que você adicionar uma nova ação, rota, chave de estado ou recorrente
+fluxo de trabalho. [Writing Agent Instructions](/docs/writing-agent-instructions) é o
+guia completo — como manter `AGENTS.md` passível de leitura, o que pertence a cada um dos quatro
+superfícies de orientação e como redigir descrições de habilidades e ferramentas para que o agente
+aciona-os de forma confiável.
+
+## Adicionar Skills {#skills}
+
+Use skills para padrões detalhados que sobrecarregariam `AGENTS.md`: APIs específicos do provedor, formatos de importação/exportação, fluxos de edição complexos ou terminologia de domínio.
+
+```markdown
+---
+name: project-imports
+description: How to import projects from the legacy CSV export.
+---
+
+# Project Imports
+
+Use this skill when the user uploads a legacy project CSV.
+
+## Rules
+
+- Validate required columns before creating rows.
+- Use `create-project` for each project so ownership and sync are correct.
+- Save rejected rows as a note attached to the import summary.
+```
+
+Armazene o modelo skills em `.agents/skills/<name>/SKILL.md`. Se os usuários puderem editar as orientações em tempo de execução, mostre-as também nos recursos do espaço de trabalho.
+
+## Etapas de configuração do registro {#onboarding}
+
+Se um modelo precisar de uma chave API, conexão OAuth ou conta de provedor, registre uma etapa de integração em vez de enterrar o requisito em um README.
+
+```ts
+// server/plugins/onboarding.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+export default defineNitroPlugin(() => {
+  registerOnboardingStep({
+    id: "github",
+    title: "Connect GitHub",
+    description: "Needed to import repositories and pull requests.",
+    order: 100,
+    methods: [
+      {
+        id: "token",
+        kind: "form",
+        primary: true,
+        label: "Save token",
+        payload: {
+          fields: [
+            { key: "GITHUB_TOKEN", label: "GitHub token", secret: true },
+          ],
+        },
+      },
+    ],
+    isComplete: () => !!process.env.GITHUB_TOKEN,
+  });
+});
+```
+
+Veja [Onboarding & API Keys](/docs/onboarding).
+
+## Prepare-o para o espaço de trabalho {#workspace-ready}
+
+Os modelos devem se encaixar naturalmente em [Multi-App Workspaces](/docs/multi-app-workspace), geralmente coordenados por [Dispatch](/docs/dispatch).
+
+Lista de verificação:
+
+- Monte A2A por meio do plug-in de bate-papo do agente da estrutura ou `mountA2A()` para que aplicativos irmãos possam ligar para seu agente.
+- Mantenha as descrições do cartão do agente específicas o suficiente para que o Dispatch encaminhe o trabalho com precisão.
+- Registre os segredos/integração necessários para que a configuração apareça na barra lateral e o Dispatch possa gerenciar as credenciais compartilhadas.
+- Mantenha instruções transversais no espaço de trabalho `AGENTS.md` ou nos recursos do espaço de trabalho, e não copiadas em todos os aplicativos.
+- Use auxiliares de compartilhamento/acesso para todos os recursos proprietários para que os espaços de trabalho no escopo da organização permaneçam isolados.
+
+## Publicar um modelo {#publishing}
+
+Antes de compartilhar:
+
+1. Execute `pnpm install`, `pnpm typecheck` e os testes do modelo.
+2. Verifique se funciona sem nenhuma chave de provedor opcional configurada.
+3. Verifique a autenticação, o compartilhamento e o isolamento de dados de dois usuários.
+4. Documente as variáveis de ambiente necessárias e as etapas de integração.
+5. Inclua exemplos ou linhas iniciais por meio de migrações aditivas, e não de arquivos de dados de tempo de execução rastreados.
+
+Os modelos de comunidade podem ser criados a partir de um repositório GitHub:
+
+```bash
+npx @agent-native/core@latest create my-app --template github:user/repo
+```
+
+## Contribuindo para a estrutura monorepo {#contributing}
+
+### Testar alterações de estrutura não publicadas {#test-unpublished-framework-changes}
+
+Quando você está trabalhando dentro do framework monorepo e precisa de um
+workspace para usar pacotes não publicados ou alterações de modelo, execute create com o
+sinalizador de pacote local:
+
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
+```
+
+O espaço de trabalho gerado vincula o `@agent-native/core` local e
+Pacotes `@agent-native/dispatch`, portanto, mudanças nos Core APIs, espaço de trabalho Dispatch
+comportamento ou modelos próprios podem ser testados antes da publicação. O pacote
+Os scripts `prepack` constroem `dist` antes da vinculação, o que mantém o gerado
+espaço de trabalho apontado para a saída atual do build.

package/corpus/core/docs/content/locales/pt-BR/cross-app-sso.md

@@ -0,0 +1,185 @@
+---
+title: "SSO entre aplicativos"
+description: "Faça login uma vez em cada aplicativo nativo do agente hospedado por meio da federação de identidade com o Dispatch como autoridade de identidade — ativação por aplicativo, reversível com uma única variável de ambiente."
+---
+
+# SSO entre aplicativos
+
+Cada aplicativo hospedado no `*.agent-native.com` executa sua própria implantação com seu **próprio armazenamento de usuário separado**. `mail.agent-native.com` e `calendar.agent-native.com` não compartilham um banco de dados, uma tabela de sessão ou um domínio de cookie. Portanto, "fazer login uma vez, usar todos os aplicativos" não pode ser um cookie compartilhado. Tem que ser uma **federação de identidades**, com [Dispatch](/docs/dispatch) atuando como autoridade de identidade para o espaço de trabalho.
+
+Esta é a mesma primitiva de confiança que [A2A](/docs/a2a-protocol) e [External Agents](/docs/external-agents) já usam — um `A2A_SECRET` assinado por JWT verificado no limite da solicitação — aplicado ao caminho de login humano em vez de chamadas de agente para agente.
+
+> **Implantação unificada versus implantação por domínio.** Se você hospedar todos os aplicativos em uma origem (`your-agents.com/mail`, `your-agents.com/calendar`), você já terá login compartilhado por meio de um único domínio de cookie, sem necessidade de federação. Cross-App SSO só é necessário quando os aplicativos são executados em domínios separados. Consulte [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+
+## O quê e por quê {#what-why}
+
+Os armazenamentos de usuários por aplicativo significam que não existe um único lugar onde um cookie do navegador possa residir em que todo aplicativo confie. Em vez disso, o modelo de federação nomeia um aplicativo — **Dispatch** — como autoridade de identidade. Qualquer outro aplicativo pode delegar “quem é essa pessoa?” para o Dispatch, receba de volta uma declaração assinada de curta duração do e-mail verificado do usuário e **vincule-a à sua própria conta local por e-mail**.
+
+A regra de vinculação é deliberadamente restrita e aditiva:
+
+- **Usuário existente com mesmo e-mail → vinculado.** A conta local é correspondida por e-mail verificado e reutilizada como está. Ele **nunca é modificado, renomeado ou excluído** — a camada de federação apenas o lê e cria uma sessão para ele.
+- **Novo e-mail → criado.** Uma nova conta local é criada para esse e-mail verificado e, em seguida, uma sessão local normal é criada.
+
+Isso torna a implementação segura, mesmo que desconecte as pessoas. **O logout é esperado.** Quando um aplicativo ativa esse recurso, as sessões existentes terminam e os usuários são autenticados novamente por meio do Dispatch. Mas eles sempre fazem login novamente na **mesma conta de e-mail correspondente, com todos os dados intactos**, porque as linhas de identidade só são _adicionadas_, nunca destruídas, renomeadas ou renomeadas.
+
+## Como funciona {#how-it-works}
+
+O fluxo é um redirecionamento padrão de autorização → token assinado → retorno de chamada, com e-mail como a única coisa que ultrapassa o limite de confiança.
+
+```an-diagram title="Identity federation flow" summary="Dispatch authenticates the human and returns a short-lived signed assertion of one thing — the verified email. The app links by email and mints its own local session."
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>Client app</strong><small class=\"diagram-muted\">own user store</small></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill\">authorize</span></div><div class=\"diagram-card\" data-rough><strong>Dispatch</strong><small class=\"diagram-muted\">identity authority</small><span class=\"diagram-pill accent\">authenticates human</span></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill accent\">302 + signed JWT</span></div><div class=\"diagram-card\" data-rough><strong>App callback</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">JIT-link by email</span><span class=\"diagram-pill ok\">mint local session</span></div></div>",
+  "css": ".diagram-sso{display:flex;align-items:stretch;gap:12px;flex-wrap:wrap}.diagram-sso .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px}.diagram-sso .diagram-step{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px}.diagram-sso .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+1. **Aplicativo → Envio (autorizar).** O aplicativo envia o usuário para a autoridade de identidade:
+
+   ```
+   GET https://dispatch.agent-native.com/_agent-native/identity/authorize
+       ?app=<requesting-app>
+       &redirect_uri=<app-callback-url>
+       &estado=<csrf-state>
+   ```
+
+   ```an-api title="Endpoint de autorização de identidade"
+   {
+     "método": "GET",
+     "caminho": "/_agent-native/identity/authorize",
+     "summary": "Dispatch (autoridade de identidade) autentica o humano e redireciona de volta com um token de identidade assinado",
+     "auth": "Sessão de envio (login interativo se não houver)",
+     "parâmetros": [
+       { "name": "app", "in": "query", "type": "string", "required": true, "description": "O identificador do aplicativo solicitante." },
+       { "name": "redirect_uri", "in": "query", "type": "string", "required": true, "description": "Retorno de chamada do aplicativo URL. Validado em uma lista de permissões estrita (`*.agent-native.com` ou localhost por padrão)." },
+       { "name": "state", "in": "query", "type": "string", "required": true, "description": "Estado CSRF ecoado de volta no redirecionamento." }
+     ],
+     "respostas": [
+       { "status": "302", "description": "Redireciona para `redirect_uri` carregando uma identidade JWT assinada por `A2A_SECRET` de curta duração (`scope: \"identity\"`, `exp` ≤ 2 minutos) mais o `state` original." },
+       { "status": "400", "description": "`redirect_uri` falhou na validação da lista de permissões (origem cruzada, `//host` relativo ao esquema ou sufixo não listado)." }
+     ]
+   }
+   ```
+
+2. **O Dispatch autentica o humano.** Se o usuário já tiver uma sessão do Dispatch, isso é transparente. Caso contrário, o Dispatch mostra seu próprio login normal (e-mail/senha, Google, etc. — consulte [Authentication](/docs/authentication)). O Dispatch é apenas um aplicativo nativo do agente normal aqui; ele não está executando um modo de autenticação especial.
+
+3. **Dispatch → Aplicativo (token de identidade assinado).** O Dispatch valida `redirect_uri` em uma lista de permissões estrita e redireciona 302 de volta para o `redirect_uri` do aplicativo carregando uma identidade de curta duração **`A2A_SECRET` assinada por JWT**. As reivindicações do token são intencionalmente mínimas:
+
+   | Reivindicação | Significado                                                |
+   | ------------- | ---------------------------------------------------------- |
+   | `sub`         | ID de usuário estável na autoridade de identidade          |
+   | `email`       | E-mail **verificado** do usuário — a única chave de adesão |
+   | `name`        | Nome de exibição (não oficial, somente para UI)            |
+   | `org_domain`  | Domínio do espaço de trabalho/organização, quando presente |
+   | `scope`       | Sempre `"identity"` — este token autoriza apenas o login   |
+   | `exp`         | **≤ 2 minutos** a partir da edição                         |
+
+4. **O aplicativo verifica os links JIT por e-mail.** O aplicativo verifica a assinatura do token com seu próprio `A2A_SECRET`, verifica `scope: "identity"` e `exp` e, em seguida, executa **vinculação just-in-time estritamente por e-mail verificado**:
+   - Se existir um usuário local com esse e-mail → reutilize-o inalterado.
+   - Caso contrário → crie um usuário local para esse e-mail.
+
+5. **O aplicativo gera uma sessão local normal.** A partir daqui, o usuário tem uma sessão local comum na própria loja do aplicativo — todas as verificações de acesso, escopo organizacional e proteção de ação existentes funcionam exatamente como antes. A federação só aconteceu na porta da frente.
+
+### Ativar {#opt-in}
+
+Um aplicativo participa **somente** quando esta variável de ambiente é definida em sua implantação:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+- **Set** → o aplicativo mostra uma opção **"Entrar com Agent-Native"** que executa o fluxo acima. O login local direto (e-mail/senha, Google) ainda funciona junto com ele.
+- **Desativado (padrão)** → **nenhuma mudança de comportamento.** O aplicativo é autenticado exatamente como antes; o caminho do código de federação está inativo. Não há alteração de esquema e nada para migrar, portanto, ativar ou desativar a variável é totalmente reversível a qualquer momento.
+
+## Segurança {#security}
+
+Todo o modelo se baseia em algumas garantias deliberadamente pequenas:
+
+- **Token assinado de curta duração.** A declaração de identidade é um JWT assinado por `A2A_SECRET` com expiração de **≤ 2 minutos** e `scope: "identity"`. Ele autoriza um único login e não pode ser reproduzido por muito tempo ou reaproveitado para acesso API/A2A.
+- **Lista de permissões `redirect_uri` estrita.** O despacho apenas redireciona para `*.agent-native.com` ou localhost por padrão. Os alvos de redirecionamento arbitrários, relativos ao esquema (`//host`) e de origem cruzada são rejeitados, portanto, a autoridade não pode ser transformada em um oráculo de redirecionamento aberto ou de exfiltração de token.
+- **Junção somente por e-mail a partir de um token verificado.** A _única_ coisa que ultrapassa o limite de confiança é o e-mail verificado em um token assinado. O aplicativo não aceita ID de usuário, função, associação à organização ou qualquer estado privilegiado da transmissão. Ele deriva tudo localmente da conta correspondente.
+- **Gravações de identidade somente aditivas.** A vinculação reutiliza uma conta de mesmo e-mail existente intacta ou insere uma nova. Nenhuma atualização, renomeação, reposicionamento ou exclusão de linhas de identidade ocorre nesse caminho.
+- **Desativado por padrão.** Com `AGENT_NATIVE_IDENTITY_HUB_URL` não definido, todo o recurso fica inerte.
+
+```an-callout
+{
+  "tone": "success",
+  "body": "**Safe to enable, safe to revert.** Identity writes are **additive only** — an existing same-email account is reused untouched, and a new email just inserts a fresh row. There is no schema change and nothing to migrate, so flipping `AGENT_NATIVE_IDENTITY_HUB_URL` on or off is fully reversible at any time, per app."
+}
+```
+
+O link just-in-time é uma decisão única digitada inteiramente no e-mail verificado:
+
+```an-diagram title="JIT-link decision" summary="Linking is keyed on the verified email and is additive only — existing accounts are reused unchanged, new emails create a fresh local user."
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>Verified email<br><small class=\"diagram-muted\">from signed identity JWT</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-branch\"><div class=\"diagram-box\" data-rough>Local user exists?<span class=\"diagram-pill ok\">yes &rarr; reuse unchanged</span><span class=\"diagram-pill accent\">no &rarr; create local user</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Mint normal local session</div></div></div>",
+  "css": ".diagram-jit{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-node{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-jit .diagram-branch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-box{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-jit .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Auto-hospedagem {#self-hosting}
+
+Qualquer implantação do Dispatch pode servir como hub de identidade — você não está limitado ao `dispatch.agent-native.com`. Defina `AGENT_NATIVE_IDENTITY_HUB_URL` em cada aplicativo cliente para apontar para sua instância do Dispatch:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**Lista de permissões de redirecionamento.** O hub (Dispatch) valida `redirect_uri` no endpoint autorizado antes de emitir um token. A lista de permissões está configurada em `templates/dispatch/server/lib/identity-sso.ts`:
+
+- **Padrão:** somente `*.agent-native.com` e localhost (a constante `DEFAULT_ALLOWED_HOST_SUFFIXES`).
+- **Estendendo:** defina a variável de ambiente `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` na implantação do Dispatch com uma lista separada por vírgulas de sufixos de host adicionais:
+
+  ```bash
+  # Permitir subdomínios suaempresa.com além dos padrões
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".suaempresa.com,.staging.suaempresa.com"
+  ```
+
+  Cada entrada é normalizada para um sufixo com prefixo de ponto (`.yourcompany.com`), portanto, uma verificação de sufixo é suficiente e menos propensa a armas de fogo - não há lista por aplicativo para manter sincronizada. As entradas que correspondem a tudo (vazias ou apenas `.`) são filtradas.
+
+- **Localhost** é sempre permitido para desenvolvimento local de aplicativos do lado do cliente, independentemente de `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`.
+
+Sem `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`, um Dispatch auto-hospedado só pode emitir tokens para aplicativos em `*.agent-native.com`. Defina a variável env em sua implantação do Dispatch para desbloquear outros domínios.
+
+## Runbook de implementação Canary {#canary-rollout}
+
+A transferência e a reversão são **uma única variável de ambiente por implantação de aplicativo**. Implemente um aplicativo por vez, verifique e expanda. Não defina a variável em todos os aplicativos de uma só vez.
+
+**1. Implante o código — sem alteração de comportamento.**
+Envie o lançamento para todos os aplicativos com `AGENT_NATIVE_IDENTITY_HUB_URL` **desativado em todos os lugares**. Confirme se os logins normais ainda funcionam em alguns apps.
+
+**2. Ative o canário no aplicativo ONE de cada vez.**
+Definir, apenas em uma implantação:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+Deixe o ambiente de todos os outros aplicativos indefinido. Reimplante/reinicie para que ele pegue a variável.
+
+**3. Verifique o canário (lista de verificação).**
+
+- **Saia** do aplicativo.
+- A tela de login agora mostra **"Entrar com Agent-Native"**. Clique nele.
+- Você será direcionado ao **Dispatch** e completará seu login (ou passará diretamente se já estiver conectado lá).
+- Você será redirecionado **de volta ao aplicativo, conectado** — e é a **mesma conta pré-existente** (mesmo e-mail) que você tinha antes, e não uma nova.
+- **Os dados do aplicativo estão intactos** — seus registros, configurações e escopo organizacional existentes são exatamente como eram.
+- **Logins diretos existentes ainda funcionam** — e-mail/senha e login do Google continuam funcionando junto com SSO.
+
+Se alguma verificação falhar, vá direto para a etapa 4 (reversão) — é instantâneo e protege os dados.
+
+**4. Expanda aplicativo por aplicativo.**
+Depois que um aplicativo for verificado, repita as etapas 2 a 3 para o próximo aplicativo — configurando `AGENT_NATIVE_IDENTITY_HUB_URL` em uma implantação por vez. Nunca habilite em lote.
+
+**5. Rollback = desativa a variável env na implantação desse aplicativo.**
+Para reverter qualquer aplicativo, **remova `AGENT_NATIVE_IDENTITY_HUB_URL` do ambiente desse aplicativo e reimplante-o/reinicie-o.** O aplicativo retorna imediatamente ao seu comportamento de autenticação anterior. Não há **nenhuma alteração de dados para desfazer** — as linhas de identidade apenas foram adicionadas e a desativação da variável simplesmente torna o caminho da federação inativo novamente. A substituição e a reversão de cada app são independentes e reversíveis.
+
+> A implementação desconecta os usuários à medida que cada aplicativo é ativado (eles autenticam novamente via Dispatch), mas eles sempre fazem login novamente na **mesma conta correspondente por e-mail com os dados intactos**, porque as linhas de identidade nunca são destruídas ou renomeadas, apenas adicionadas.
+
+## Relacionado {#related}
+
+- [Authentication](/docs/authentication) — modos de autenticação local, sessões, organizações, a variável de ambiente `A2A_SECRET`.
+- [A2A Protocol](/docs/a2a-protocol) — o modelo de confiança JWT assinado e de verificação no limite que ele reutiliza.
+- [External Agents](/docs/external-agents) — o mesmo padrão de identidade assinado por `A2A_SECRET` aplicado a conexões de agente e links diretos.
+- [Dispatch](/docs/dispatch) — a autoridade de identidade do espaço de trabalho e hub de roteamento.
+- [Security & Data Scoping](/docs/security) — gravações de dados somente aditivas e escopo por conta.
+- [Multi-App Workspaces](/docs/multi-app-workspace) — a implantação unificada de origem única que evita totalmente SSO entre domínios.