@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/pt-BR/local-file-mode.md

@@ -0,0 +1,433 @@
+---
+title: "Modo de arquivo local"
+description: "Execute aplicativos nativos do agente com Markdown, MDX locais e outros arquivos repo como fonte da verdade, incluindo documentos MDX no estilo Obsidian com componentes personalizados."
+---
+
+# Modo de arquivo local
+
+O modo de arquivo local permite que um aplicativo nativo do agente anexe seu UI normal e sua superfície de ação
+diretamente para arquivos em um repositório ou espaço de trabalho. O aplicativo ainda parece hospedado
+produto, mas suas visualizações de lista, editor e ferramentas de agente leem e gravam arquivos locais
+em vez de registros de aplicativos baseados em SQL.
+
+A primeira implementação está no modelo Conteúdo: a barra lateral esquerda está
+preenchido a partir de arquivos locais `.md` e `.mdx`, selecionar uma página abre o padrão
+Editor de conteúdo e gravação de gravação no arquivo selecionado. Os mesmos arquivos podem
+também pode ser editado por Codex, Claude Code, agente da barra lateral Agent-Native ou um normal
+editor.
+
+Para conteúdo, isso faz com que o produto pareça Obsidian de código aberto para MDX:
+seus documentos ficam como arquivos, enquanto o aplicativo adiciona um editor visual, o agente actions,
+cópias compartilháveis e componentes MDX interativos avançados.
+
+Use o modo de arquivo local quando desejar um fluxo de trabalho com foco no repositório:
+
+- um repositório de documentos com `docs/*.mdx`
+- um blog com `blog/*.mdx`
+- recursos como posicionamento, mensagens ou notas da equipe em `resources/*.md`
+- uma base de conhecimento pessoal no estilo Obsidian com um editor MDX mais rico
+- documentos que precisam de blocos MDX personalizados interativos gerados a partir do código React local
+- artefatos de aplicativos que devem ser fáceis de serem inspecionados e corrigidos pelos agentes de codificação
+
+Use o modo de banco de dados quando desejar a experiência de aplicativo colaborativo hospedado:
+compartilhamento multiusuário, permissões baseadas em SQL, comentários, histórico de versões e
+hospedagem de produção sem acesso ao sistema de arquivos local.
+
+## O modelo mental
+
+Existem dois modos de fonte da verdade:
+
+| Modo                  | Fonte da verdade                                         | Melhor para                                                                                                                |
+| --------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Modo banco de dados   | Linhas SQL até Drizzle                                   | Aplicativos hospedados, colaboração, compartilhamento, comentários, histórico de versões                                   |
+| Modo de arquivo local | Arquivos repositórios declarados por `agent-native.json` | Fluxos de trabalho locais/de desenvolvimento, revisão do Git, edições do agente de codificação, conteúdo nativo de arquivo |
+
+O UI e o agente actions devem permanecer na mesma forma em ambos os modos. Um conteúdo
+editor ainda edita documentos; a diferença é se esses documentos resolvem
+para linhas SQL ou arquivos locais.
+
+```an-diagram title="Same actions, two sources of truth" summary="The UI and agent call identical actions in both modes. The action layer decides whether each call resolves to SQL rows or repo files."
+{
+  "html": "<div class=\"diagram-mode\"><div class=\"diagram-col entry\"><div class=\"diagram-node\">Content UI</div><div class=\"diagram-node\">Agent + actions<br><small class=\"diagram-muted\">list/get/update-document</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-row resolve\"><div class=\"diagram-panel\" data-rough><span class=\"diagram-pill accent\">Database mode</span><small class=\"diagram-muted\">SQL rows via Drizzle</small><small class=\"diagram-muted\">hosted · sharing · comments · history</small></div><div class=\"diagram-panel\" data-rough><span class=\"diagram-pill ok\">Local File Mode</span><small class=\"diagram-muted\">repo files via agent-native.json</small><small class=\"diagram-muted\">Git review · coding-agent edits</small></div></div></div>",
+  "css": ".diagram-mode{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-mode .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-mode .diagram-arrow{font-size:22px;line-height:1}.diagram-mode .resolve{display:flex;gap:12px;flex-wrap:wrap}.diagram-mode .diagram-panel{display:flex;flex-direction:column;gap:4px;padding:12px 14px}"
+}
+```
+
+## Exemplo de repositório
+
+Um espaço de trabalho Conteúdo pode ser tão pequeno quanto isto:
+
+```an-file-tree title="A Content workspace repo"
+{
+  "entries": [
+    { "path": "agent-native.json", "note": "declares which folders are content roots and their kinds" },
+    { "path": "docs/", "note": "content root — shows in the sidebar as pages" },
+    { "path": "docs/getting-started.mdx" },
+    { "path": "docs/guides/custom-components.mdx" },
+    { "path": "blog/", "note": "content root" },
+    { "path": "blog/launch-post.mdx" },
+    { "path": "resources/", "note": "content root" },
+    { "path": "resources/messaging/positioning.md" },
+    { "path": "components/", "note": "NOT a content root — preview component library MDX can import" },
+    { "path": "components/FrameworkTabs.tsx" },
+    { "path": "components/Callout.tsx" },
+    { "path": "extensions/", "note": "NOT a content root — local extension library (sandboxed widgets)" },
+    { "path": "extensions/doc-status/extension.json" },
+    { "path": "extensions/doc-status/index.html" }
+  ]
+}
+```
+
+No modo de arquivo local, a barra lateral de conteúdo mostra `docs/`, `blog/` e
+Árvores `resources/` como páginas. Selecionar `docs/getting-started.mdx` abre isso
+arquivo no editor de conteúdo padrão; a edição no UI grava de volta em
+`docs/getting-started.mdx`.
+
+`components/` não é uma raiz de conteúdo. É uma biblioteca de componentes de visualização que MDX
+arquivos podem ser importados ou referenciados. O editor pode renderizar componentes MDX locais simples
+sem precisar clonar ou bifurcar todo o aplicativo Content.
+
+`extensions/` também não é uma raiz de conteúdo. É uma biblioteca de extensão local:
+pequenos widgets em sandbox que podem ser renderizados em slots de aplicativos enquanto sua fonte permanece em
+o repositório.
+
+## Instalar conteúdo em um repositório
+
+Para documentos, blogs ou espaço de trabalho MDX existentes, instale os arquivos locais de conteúdo
+habilidade:
+
+```bash
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+```
+
+Isso copia a habilidade `content` nas pastas de habilidades do agente do repositório e grava
+ou atualiza `agent-native.json` com padrões de conteúdo:
+
+- `mode: "local-files"` no nível do espaço de trabalho
+- `apps.content.mode: "local-files"`
+- raízes de conteúdo para `docs/`, `blog/`, `content/` e `resources/`
+- `components/` para componentes MDX locais
+- `extensions/` para widgets de extensão local
+
+A habilidade instalada informa aos agentes de codificação para usarem o Conteúdo actions
+(`list-documents`, `get-document`, `edit-document`, `update-document`,
+`share-local-file-document` e arquivo de componente actions) quando um aplicativo de conteúdo local
+ou Agent Native Desktop bridge os expõe. Se nenhuma ponte estiver funcionando, a habilidade
+volta para edições de repositório diretas e seguras, preservando o frontmatter, as importações, JSX,
+e MDX desconhecido.
+
+## Configuração
+
+Adicione `agent-native.json` ao repositório ou raiz do espaço de trabalho:
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "content": {
+      "mode": "local-files",
+      "roots": [
+        {
+          "name": "Docs",
+          "path": "docs",
+          "kind": "docs",
+          "extensions": [".md", ".mdx"]
+        },
+        {
+          "name": "Blog",
+          "path": "blog",
+          "kind": "blog",
+          "extensions": [".md", ".mdx"]
+        },
+        {
+          "name": "Resources",
+          "path": "resources",
+          "kind": "resources",
+          "extensions": [".md", ".mdx"]
+        }
+      ],
+      "components": "components",
+      "extensions": "extensions",
+      "hide": ["**/_*.md", "**/_*.mdx"]
+    }
+  }
+}
+```
+
+Você também pode ativar arquivos locais com `AGENT_NATIVE_MODE=local-files` ou
+`AGENT_NATIVE_DATA_MODE=local-files`; o manifesto é preferido porque
+documenta o contrato da pasta no próprio repositório.
+
+## Formato de arquivo de conteúdo
+
+O conteúdo diz Markdown e MDX. Frontmatter contém metadados da página e o corpo é
+o documento editável:
+
+```mdx
+---
+title: "Getting Started"
+icon: "sparkles"
+isFavorite: true
+updatedAt: "2026-06-12T20:00:00.000Z"
+---
+
+# Getting Started
+
+Use <FrameworkTabs value="react" /> to show framework-specific code.
+```
+
+O título vem do frontmatter `title` quando presente, caso contrário, do
+nome do arquivo. O editor preserva a fonte MDX que ainda não pode ser editada visualmente, portanto
+agentes de codificação e editores de texto normais permanecem como saídas de escape seguras.
+
+## Componentes MDX personalizados
+
+O conteúdo pode visualizar componentes locais da pasta `components` configurada.
+Isso se destina a componentes MDX de estilo de documento, como guias, textos explicativos, pacote
+instale snippets ou blocos de código específicos da estrutura.
+
+Por exemplo, adicione um componente interativo próximo ao seu conteúdo:
+
+```tsx
+// components/ImpactCounter.tsx
+import { useState } from "react";
+
+export function ImpactCounter({
+  label = "points",
+  accent = "blue",
+  featured = false,
+}: {
+  label?: string;
+  accent?: "blue" | "green" | "purple";
+  featured?: boolean;
+}) {
+  const [count, setCount] = useState(3);
+  const accentClass =
+    accent === "green"
+      ? "border-green-300 bg-green-50"
+      : accent === "purple"
+        ? "border-purple-300 bg-purple-50"
+        : "border-blue-300 bg-blue-50";
+
+  return (
+    <div className={`rounded-md border p-4 ${accentClass}`}>
+      <div className="text-sm text-muted-foreground">Launch impact</div>
+      <div className="mt-1 text-3xl font-semibold">
+        {count} {label}
+      </div>
+      {featured ? <div className="mt-1 text-sm">Featured metric</div> : null}
+      <button
+        type="button"
+        className="mt-3 rounded border px-3 py-1 text-sm"
+        onClick={() => setCount((value) => value + 1)}
+      >
+        Add point
+      </button>
+    </div>
+  );
+}
+
+export const ImpactCounterInputs = {
+  label: {
+    type: "string",
+    label: "Metric label",
+    default: "points",
+  },
+  accent: {
+    type: "select",
+    label: "Accent",
+    options: ["blue", "green", "purple"],
+    default: "blue",
+  },
+  featured: {
+    type: "boolean",
+    label: "Featured",
+    default: false,
+  },
+};
+```
+
+Em seguida, use-o em qualquer arquivo MDX local:
+
+```mdx
+---
+title: "Launch Notes"
+---
+
+# Launch Notes
+
+<ImpactCounter label="wins" />
+```
+
+O servidor de desenvolvimento de conteúdo descobre exportações nomeadas de PascalCase e padrão de PascalCase
+exporta arquivos `.tsx`, `.jsx`, `.ts` e `.js` em `components/`. Aqueles
+componentes são renderizados dentro do editor e aparecem no menu de barras em
+**Componentes locais**. A inserção de barra cria uma tag mínima como
+`<ImpactCounter />`; adicione adereços na fonte MDX quando necessário.
+
+A execução do componente é intencionalmente um recurso de ponte local-dev/Desktop, não
+acesso simples à pasta do navegador hospedado. Se você abrir `content.agent-native.com`,
+escolha **Arquivos locais** e escolha uma pasta no Chrome, o app pode ler e gravar
+os arquivos `.md` e `.mdx` através do navegador Sistema de Arquivos Acesse API, mas
+O Chrome não expõe um caminho de pasta absoluto para Vite compilar
+`components/*.tsx`. Para visualizar e recarregar componentes React personalizados, execute
+Conteúdo localmente ou use o Agent Native Desktop para que a ponte local confiável possa
+registre o espaço de trabalho escolhido no servidor de desenvolvimento de conteúdo local. Nesse modo,
+edições em arquivos de componentes existentes, recarregamento a quente por meio de Vite e adição de ou
+a remoção de arquivos de componentes recarrega o registro do componente e o menu de barras.
+
+Os agentes também podem trabalhar com esses arquivos de componentes registrados. Usar
+`list-local-component-files` para encontrar o ID do espaço de trabalho registrado e, em seguida,
+`write-local-component-file` para criar ou atualizar `.tsx`, `.jsx`, `.ts` ou
+Arquivos `.js` na pasta `components/` do espaço de trabalho. Os arquivos MDX permanecem os
+fonte de verdade para uso de componentes; os arquivos do componente permanecem no repositório normal
+arquivos de origem revisados com Git.
+
+Se um componente exportar metadados de entrada, selecione o componente no editor
+mostra um botão de edição no canto superior direito do componente. Tipos de entrada suportados
+são `string`, `textarea`, `number`, `boolean` e `select`. O formulário escreve
+volta para a tag MDX, então os arquivos locais permanecem a fonte da verdade. O
+metadados podem ser exportados como `ComponentNameInputs`, `ComponentNameConfig.inputs`,
+`Component.inputs` ou `agentNative.inputs`.
+
+Tags de componentes simples com adereços literais podem ser visualizados in-line:
+
+```mdx
+<FrameworkTabs value="react" />
+
+<Callout type="warning">This setting affects production deploys.</Callout>
+```
+
+Expressões JSX complexas são preservadas na origem. Se o editor não puder com segurança
+visualizar um suporte de componente ainda, ele mostra um espaço reservado de aviso em vez de
+descartando dados silenciosamente.
+
+## Compartilhando arquivos locais
+
+Os arquivos locais não são compartilhados diretamente porque outros usuários não conseguem ler um caminho
+sua máquina. O botão Compartilhar da barra de ferramentas Conteúdo cria ou atualiza um
+cópia do arquivo selecionado com base no banco de dados, navega até essa cópia e abre o
+popover de compartilhamento normal. O arquivo local original permanece em Arquivos locais; o
+a cópia do banco de dados aparece em Cópias compartilhadas no modo de arquivo local e usa o
+modelo padrão de compartilhamento de documentos.
+
+## Extensões locais
+
+O modo de arquivo local também pode carregar extensões apoiadas por repositório a partir do configurado
+Pasta `extensions`. Cada extensão é um diretório com um `extension.json`
+manifesto e um arquivo de entrada HTML:
+
+```text
+extensions/
+  doc-status/
+    extension.json
+    index.html
+```
+
+```json
+{
+  "id": "doc-status",
+  "name": "Doc Status",
+  "description": "Shows metadata for the selected Content file.",
+  "entry": "index.html",
+  "slots": ["content.sidebar.bottom"],
+  "permissions": {
+    "appActions": ["list-documents"],
+    "extensionData": true
+  }
+}
+```
+
+`index.html` é o mesmo formato de corpo de extensão Alpine/Tailwind usado pelo normal
+extensões apoiadas por banco de dados. Quando o aplicativo Content vê uma extensão local que
+declara `content.sidebar.bottom`, ele renderiza essa extensão na parte inferior de
+a barra lateral de Conteúdo. O host passa `window.slotContext` com o selecionado
+ID do documento, título, metadados de origem e se o conteúdo está no modo de arquivo local.
+
+As extensões locais são visualizadas pelo aplicativo, mas editadas como arquivos. As extensões
+a lista mostra-os com um selo de arquivo local, e o visualizador de página inteira aponta de volta para
+o arquivo de entrada. Extensão actions apoiada por SQL, como atualizar, excluir, compartilhar e
+história não se aplica; use seu editor, código Codex, Claude ou histórico do Git para
+alterações na origem.
+
+Para v1, as extensões locais são intencionalmente conservadoras:
+
+- eles podem usar `extensionData` para seu próprio estado de tempo de execução pequeno
+- eles podem ligar apenas para os `appAction`s listados em `extension.json`
+- ajudantes SQL brutos e `extensionFetch` externos estão desabilitados
+- os destinos dos slots são declarados em `extension.json`, não instalados por meio de SQL
+
+Isso dá aos espaços de trabalho locais uma superfície de plug-in semelhante ao Obsidian, sem permitir
+O arquivo repositório arbitrário herda todos os recursos de uma extensão baseada em banco de dados.
+
+## Como os aplicativos usam isso
+
+O modo de arquivo local é implementado por meio dos auxiliares de artefatos locais da estrutura.
+Um aplicativo declara raízes para os tipos de artefatos que possui, depois lê e grava
+através da mesma ação, o UI e o agente já usam.
+
+Para Conteúdo, isso significa:
+
+- `list-documents` lista os arquivos `.md` e `.mdx` configurados.
+- `get-document` lê um arquivo local selecionado.
+- `update-document` grava o arquivo local selecionado.
+- `create-document` cria um novo arquivo `.mdx` local na pasta selecionada.
+- `delete-document` exclui o arquivo local.
+- a pesquisa é executada nos arquivos locais configurados.
+
+Mover, renomear e reordenar páginas de arquivos locais do Conteúdo UI não é
+ainda compatível. Faça essas operações no espaço de trabalho ou com um agente de codificação; o
+A barra lateral de conteúdo refletirá a árvore de arquivos resultante.
+
+Isso mantém o contrato do agente simples: o agente pode continuar usando o Conteúdo actions,
+e aqueles actions decidem se o alvo é apoiado por SQL ou por arquivo.
+
+Outros aplicativos podem adotar o mesmo padrão ao longo do tempo. Um aplicativo Apresentações pode mapear
+`slides/*.mdx` para decks, um aplicativo de Planos pode mapear `plans/*` para documentos de planejamento e um
+O aplicativo Dashboards pode mapear `dashboards/*.mdx` para dashboards. Aqueles específicos do aplicativo
+pastas são convenções colocadas em camadas sobre o mesmo contrato de artefato local.
+
+## Arquivos locais x exportação/importação
+
+O conteúdo tem dois fluxos de trabalho de arquivo diferentes:
+
+| Fluxo de trabalho                    | O que acontece                                                                                                                                                   |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Exportação/importação `/local-files` | O modo banco de dados continua sendo a fonte da verdade. Os arquivos são uma superfície de sincronização explícita que você exporta, edita, visualiza e importa. |
+| Modo de arquivo local                | Os arquivos são a fonte da verdade. A barra lateral e o editor de conteúdo operam diretamente em arquivos locais.                                                |
+
+Use exportar/importar quando quiser revisar arquivos ocasionalmente em um espaço de trabalho hospedado.
+Use o modo de arquivo local quando o próprio repositório for o espaço de trabalho.
+
+## História e colaboração
+
+O modo de arquivo local depende do histórico nativo do arquivo:
+
+- confirmar alterações importantes no Git
+- use pull requests para revisão
+- permitir que os agentes de codificação editem os mesmos arquivos diretamente
+- use diferenças normais de arquivo para entender as alterações
+
+O modo banco de dados continua sendo o mais adequado para recursos de colaboração hospedados, como
+compartilhamento, comentários, histórico de versões apoiado por SQL e edição multiusuário ao vivo.
+
+A sincronização do provedor pode ser colocada em camadas sobre qualquer um dos modos. Por exemplo, um repositório de documentos pode
+adicione actions que extrai conteúdo de um CMS para arquivos MDX locais ou envia por push os selecionados
+arquivos locais de volta para esse CMS.
+
+## Segurança de produção
+
+O modo de arquivo local fornece ao aplicativo actions acesso direto de gravação ao espaço de trabalho configurado
+arquivos. Isso é apropriado para desenvolvimento local e arquivo confiável de locatário único
+pontes, mas não é o modelo de segurança de produção padrão.
+
+Quando `NODE_ENV=production`, a estrutura recusa o modo `local-files`, a menos que você
+definir:
+
+```bash
+AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION=true
+```
+
+Defina isso apenas para uma implantação confiável de locatário único, onde todos que podem usar
+o aplicativo tem permissão para ler e gravar os arquivos configurados. Para hospedagem normal,
+aplicativos multiusuário, usam modo de banco de dados e compartilhamento apoiado por SQL.

package/corpus/core/docs/content/locales/pt-BR/mcp-apps.md

@@ -0,0 +1,147 @@
+---
+title: "Aplicativos MCP"
+description: "Criar e incorporar aplicativos MCP interativos UIs dentro de Claude, ChatGPT e outros hosts compatíveis — usando rotas de aplicativos reais, a ponte incorporada e a ponte de host API."
+---
+
+# Aplicativos MCP
+
+**Esta página: UIs inline em Claude/ChatGPT.** Criação de recursos do aplicativo MCP e a ponte incorporada que renderiza uma rota de aplicativo real dentro do bate-papo de um host compatível. Esta página também é o único local da **matriz de suporte ao cliente** ([below](#client-support)).
+
+| Se você quiser…                                                                                  | Ler                                      |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------- |
+| Conecte um agente/host externo ao seu aplicativo                                                 | [External Agents](/docs/external-agents) |
+| Dê mais ferramentas ao seu agente (consuma outros servidores MCP)                                | [MCP Clients](/docs/mcp-clients)         |
+| Crie UIs embutidos que renderizam em Claude/ChatGPT                                              | **Esta página** — Aplicativos MCP        |
+| Referência do servidor MCP de nível inferior (autenticação, ferramentas, montagem personalizada) | [MCP Protocol](/docs/mcp-protocol)       |
+
+Os aplicativos MCP são a extensão `io.modelcontextprotocol/ui` oficial que permite que hosts compatíveis – Claude, Claude Desktop, ChatGPT, VS Code GitHub Copilot, Goose, Postman, MCPJam e Cursor – renderizem UIs interativos inline no bate-papo. Em aplicativos nativos de agente, cada aplicativo MCP é uma **rota React real**, não um widget HTML simples separado.
+
+No próprio bate-papo do aplicativo Agent-Native, prefira [native chat renderers](/docs/native-chat-ui) para widgets originais, como tabelas, gráficos, resultados digitados e recursos de aprovação. Use aplicativos MCP para UI em linha externo/entre hosts em Claude, ChatGPT, Copilot, Cursor e outros hosts compatíveis, com a ação `link` como substituto de deep-link universal.
+
+## Autoria: aplicativos MCP opcionais UI {#mcp-apps}
+
+Para hosts que suportam a extensão MCP Apps, uma ação também pode anunciar um recurso UI embutido com `mcpApp`. Esta é uma melhoria progressiva para fluxos em que o agente externo deve entregar ao usuário uma superfície interativa em vez de apenas texto — por exemplo, revisando um rascunho de e-mail, editando um convite de calendário ou escolhendo entre variantes de painel geradas.
+
+Use o aplicativo React real com `embedRoute()` ou `embedApp()` sempre que o usuário precisar do UI. O modelo mental é simples: o alvo `link` da ação também é o alvo de incorporação do aplicativo MCP. Exponha a operação como uma ação/ferramenta normal, retorne um link direto focado com `link` e adicione `mcpApp.resource = embedApp(...)` para que hosts capazes carreguem a mesma rota inline em vez de abrir uma nova guia. Quando ambos devem ser construídos a partir da mesma rota, prefira `embedRoute({ title, openLabel, path })`: é o wrapper de conveniência que retorna os campos `link` e `mcpApp` correspondentes de uma chamada, enquanto `embedApp(...)` é o recurso de nível inferior que você atribui diretamente a `mcpApp.resource`.
+
+Isso significa que as incorporações completas do aplicativo podem fazer tudo o que a rota pode fazer depois de aberta: revisar ou editar um rascunho de e-mail, mostrar uma caixa de entrada/pesquisa filtrada, abrir um evento de calendário ou rascunho de evento, carregar uma página de extensão, inspecionar um painel de análise completo ou análise salva, continuar uma apresentação no editor de Slides ou abrir um projeto/editor de Design. Prefira os parâmetros URL/deep-link e a ponte de navegação/estado do aplicativo `/_agent-native/open` existente a inventar um protocolo de segundo estado para aplicativos MCP.
+
+Em raras ocasiões, o alvo certo é uma rota de aplicativo focada que renderiza um componente React compartilhado em vez de todo o shell do aplicativo. A rota `/chart` do Analytics é o modelo: ela pega uma carga `SqlPanel` compacta no URL e renderiza o mesmo componente gráfico que o painel usa. Este ainda é um aplicativo incorporado, não um aplicativo HTML MCP simples. Exponha ou chame-o por meio de uma ação normal / `open_app({ path, embed: true })`, mantenha o URL determinístico e deixe `embedApp()` renderizar essa rota inline.
+
+Não escreva à mão aplicativos HTML MCP simples e únicos para o produto UI; se a ação precisar de uma superfície personalizada, primeiro adicione ou reutilize uma rota/componente real do aplicativo e incorpore essa rota.
+
+```an-diagram title="MCP App embed round-trip" summary="The action's link target is also the embed target. Capable hosts load the same signed app route inline; everyone else falls back to the deep link."
+{
+  "html": "<div class=\"diagram-embed\"><div class=\"diagram-card\" data-rough><strong>Action</strong><small class=\"diagram-muted\">`link` target = MCP App embed target</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\" data-rough><strong>embedApp()</strong><span class=\"diagram-pill accent\">create_embed_session</span><small class=\"diagram-muted\">mints short-lived embed session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\" data-rough><strong>/_agent-native/embed/start</strong><small class=\"diagram-muted\">exchanges one-time SQL ticket</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\" data-rough><strong>Signed app route</strong><span class=\"diagram-pill ok\">real React route</span><small class=\"diagram-muted\">short-lived browser session</small></div><div class=\"diagram-fallback\"><span class=\"diagram-pill warn\">no MCP Apps support</span><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>&quot;Open in … &rarr;&quot; deep link</div></div></div>",
+"css": ".diagram-embed{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-embed .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:140px}.diagram-embed .diagram-arrow{font-size:22px;line-height:1}.diagram-embed .diagram-fallback{display:flex;flex-direction:column;align-items:center;gap:6px;margin-inline-start:8px}"
+}
+
+```
+
+```ts
+import { embedApp } from "@agent-native/core";
+
+export default defineAction({
+  // ...description, schema, run, link...
+  mcpApp: {
+    resource: embedApp({
+      title: "Review draft",
+      description: "Open the generated draft in the real Mail compose UI.",
+      iframeTitle: "Agent-Native Mail",
+      openLabel: "Open in Mail",
+    }),
+  },
+});
+```
+
+```an-annotated-code title="The mcpApp resource config"
+{
+  "filename": "actions/review-draft.ts",
+  "language": "ts",
+  "code": "import { embedApp } from \"@agent-native/core\";\n\nexport default defineAction({\n  // ...description, schema, run, link...\n  mcpApp: {\n    resource: embedApp({\n      title: \"Review draft\",\n      description: \"Open the generated draft in the real Mail compose UI.\",\n      iframeTitle: \"Agent-Native Mail\",\n      openLabel: \"Open in Mail\",\n    }),\n  },\n});",
+  "annotations": [
+    { "lines": "6", "label": "Progressive enhancement", "note": "`mcpApp.resource` advertises an inline UI for hosts that support the MCP Apps extension. Keep the action's `link` builder too — CLI-only and older hosts ignore the UI metadata and still need the deep link." },
+    { "lines": "7", "label": "Embed = the link target", "note": "`embedApp()` uses the action's `link` as its launch target: it calls `create_embed_session`, exchanges a one-time SQL ticket at `/_agent-native/embed/start`, and navigates the MCP App frame to the same signed app route." },
+    { "lines": "11", "label": "Universal fallback label", "note": "`openLabel` is the visible `\"Open in … →\"` text used as the deep-link escape hatch when a host does not render the inline iframe." }
+  ]
+}
+```
+
+O servidor MCP anuncia a extensão `io.modelcontextprotocol/ui`, adiciona `_meta.ui.resourceUri` mais `_meta["ui/resourceUri"]` a `tools/list` e também emite metadados de compatibilidade de aplicativos ChatGPT SDK (`openai/outputTemplate`, widget CSP/descrição/acessibilidade). Ele expõe HTML até `resources/list`, `resources/templates/list` e `resources/read` usando MIME `text/html;profile=mcp-app`. O proxy stdio encaminha esses manipuladores de recursos do aplicativo ativo, para que os clientes desktop e CLI vejam os mesmos recursos que os clientes HTTP.
+
+Mantenha o construtor `link` existente mesmo ao adicionar `mcpApp`. Clientes somente CLI, hosts mais antigos e qualquer host que não renderize aplicativos MCP ignorarão os metadados UI e ainda precisarão do link `"Open in … →"`. `embedApp()` usa esse link como destino de lançamento, chama o auxiliar `create_embed_session` somente de aplicativo, troca um ticket SQL único em `/_agent-native/embed/start` e navega no quadro do aplicativo MCP para a rota de destino com uma sessão de navegador de curta duração mais um substituto de portador para buscas da mesma origem. `open_app({ app, path, embed: true })` é a saída de emergência genérica para rotas como painéis completos, caixas de entrada filtradas, visualizações de rascunhos de calendário, análises e páginas de extensão, e deve ser usado generosamente quando o aplicativo completo é a superfície de revisão/edição mais clara.
+
+`embedApp()` inclui a origem da solicitação MCP no recurso CSP para que o inicializador possa buscar e, quando solicitado explicitamente, enquadrar a rota do aplicativo primário assinada. O Dispatch adiciona as origens exatas dos aplicativos concedidos ao seu recurso `open_app` para que um único conector do Dispatch possa incorporar Mail, Calendário, Apresentações e o resto sem permitir todas as origens HTTPS. Transmita apenas quadros adicionais ou domínios de recursos para um aplicativo MCP personalizado que realmente incorpore um player de terceiros ou carregue recursos de terceiros.
+
+Dentro dessas rotas `embedApp()`, `sendToAgentChat()` tem reconhecimento de incorporação. Os prompts enviados automaticamente são retransmitidos para o host MCP como `ui/update-model-context` mais `ui/message`, portanto, um botão no aplicativo incorporado pode continuar intencionalmente a conversa Claude/ChatGPT a partir do estado do aplicativo selecionado. O contexto oculto é enviado como contexto do modelo; a rotação visível do usuário permanece apenas no prompt do aplicativo, o que evita o consentimento assustador do host em torno dos caminhos internos dos arquivos de estado do aplicativo. `submit: false` permanece com comportamento de pré-preenchimento/revisão local.
+
+## Ponte de aplicativo MCP de primeira classe {#mcp-app-bridge}
+
+As incorporações de aplicativos MCP são incorporações de rota, e não miniprodutos separados. `embedApp()` inicia a partir do destino `link` da ação, cria uma sessão de incorporação de curta duração e inicia a rota do aplicativo assinada. Os hosts de aplicativos MCP padrão podem navegar pelo próprio quadro do aplicativo MCP quando o host pode hidratar a rota diretamente.
+
+```an-diagram title="Two host bridge paths, one signed route" summary="Claude transplants the hydrated route and uses the direct ui/_bridge; ChatGPT gets a controlled iframe via window.openai and relays host actions over postMessage. Both point at the same signed app route."
+{
+  "html": "<div class=\"diagram-bridge\"><div class=\"diagram-col\"><div class=\"diagram-card\" data-rough><strong>Claude web</strong><span class=\"diagram-pill accent\">single-frame transplant</span><small class=\"diagram-muted\">hydrates signed app HTML in Claude's iframe, then direct`ui/_` host bridge</small></div><div class=\"diagram-card\" data-rough><strong>ChatGPT web</strong><span class=\"diagram-pill accent\">controlled route iframe</span><small class=\"diagram-muted\">`window.openai`host APIs ·`agentNative.mcpHost.*` postMessage relay</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Same signed app route<br><small class=\"diagram-muted\">normal route + React components</small></div></div>",
+"css": ".diagram-bridge{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-bridge .diagram-col{display:flex;flex-direction:column;gap:12px}.diagram-bridge .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;max-width:300px}.diagram-bridge .diagram-arrow{font-size:22px;line-height:1}.diagram-bridge .diagram-box{padding:16px 18px;text-align:center}"
+}
+
+```
+
+Claude web usa um caminho de transplante de quadro único: o documento de recurso busca o aplicativo assinado HTML e o hidrata dentro do iframe do aplicativo MCP de Claude porque Claude não permite de forma confiável iframes filhos de propriedade do aplicativo ou navegação de quadro externo. A web ChatGPT obtém um iframe de rota controlada porque sua ponte de aplicativos nos fornece hosts `window.openai` estáveis ​​​​APIs e controle de altura limitado. Todos os caminhos apontam para a mesma rota de aplicativo assinada e renderizam a rota normal e os componentes React. Projete rotas incorporadas para que uma recarga com o mesmo URL assinado reconstrua a mesma visualização.
+
+Para `open_app({ embed: true })` do mesmo aplicativo, a estrutura cria o ticket de início incorporado durante a chamada da ferramenta original e armazena o URL de início assinado em metadados de ferramenta ocultos. actions personalizado pode retornar `embedStartUrl` para o mesmo caminho rápido; a camada MCP retira aquele URL com ticket do `structuredContent` visível ao modelo e dos metadados normais de link aberto. Quando não há URL de início incorporado, o recurso volta para o auxiliar `create_embed_session` somente de aplicativo. Isso mantém os hosts de produção que restringem as chamadas de ferramenta iniciadas por iframe na rota direta sem vazar URLs de sessão única do aplicativo na transcrição. Se um usuário reabrir um bate-papo antigo após a expiração de um ticket inicial único, a rota inicial retornará uma pequena página de atualização e postará `agentNative.embedSessionExpired` no wrapper; `embedApp()` limpa o início obsoleto URL e cria um novo ticket através de `create_embed_session` quando ainda tem a rota original do aplicativo.
+
+ChatGPT obtém um caminho de compatibilidade dedicado por meio de `window.openai`: o documento de lançamento lê `toolInput`, `toolOutput` e `toolResponseMetadata` diretamente e depois chama `create_embed_session` via `window.openai.callTool(...)`. Os hosts de aplicativos MCP padrão usam a ponte `ui/*` JSON-RPC. Rotas diretamente hidratadas podem chamar `ui/update-model-context`, `ui/message`, `ui/open-link` e `ui/request-display-mode` por meio dos auxiliares da ponte de host. A rota transplantada de Claude usa a mesma ponte hospedeira direta `ui/*` após a hidratação. Quando o caminho ChatGPT ou iframe de diagnóstico explícito é usado, o wrapper retransmite o mesmo host actions por meio de solicitações postMessage `agentNative.mcpHost.*`. Mantenha o formato do resultado idêntico para ambos os caminhos: retorne um `link` focado e um conteúdo estruturado conciso.
+
+Não defina `_meta.ui.domain` padrão para um aplicativo URL. Os aplicativos MCP tratam esse campo como específico do host: Claude valida domínios sandbox no estilo `{hash}.claudemcpcontent.com`, enquanto ChatGPT usa seus próprios metadados `openai/widgetDomain`. Omita `ui.domain`, a menos que você esteja emitindo deliberadamente um valor específico do host; o host escolherá uma origem de sandbox padrão.
+
+As páginas de extensão mantêm sua sandbox nas incorporações de bate-papo MCP sem navegar em um iframe de segunda rota. O uso normal do aplicativo renderiza `/_agent-native/extensions/:id/render` como um iframe filho em área restrita. No modo ponte de bate-papo MCP, a estrutura renderiza o mesmo documento de extensão que `srcDoc` em sandbox dentro do iframe de rota, evitando falhas de host `frame-ancestors`/`X-Frame-Options` e preservando `sandbox="allow-scripts allow-forms"`.
+
+O shell de recursos possui o tamanho do host externo. O padrão `embedApp({ height })` é `560px`, fixa o shell em `320-900px` e reserva `44px` para a pequena barra de ferramentas, portanto, a janela de visualização da rota é `height - 44px`. Mantenha as rotas de aplicativos incorporadas com rolagem interna e deixe o inicializador relatar a altura intrínseca limitada em vez da altura total do documento; caso contrário, o redimensionamento automático do host pode transformar uma página normal do aplicativo em um artefato de bate-papo muito alto. Um shell alterado afeta apenas novos recursos do aplicativo MCP e novas chamadas de ferramentas. Os quadros de conversação ChatGPT/Claude antigos podem manter o comportamento anterior do recurso, portanto, verifique o dimensionamento com uma nova renderização in-line antes de julgar uma correção.
+
+### Modos incorporados {#embed-modes}
+
+Claude usa o caminho de transplante de quadro único por padrão. Você também pode forçá-lo em outros hosts com `embedMode: "transplant"` ou `frame: "transplant"` ao depurar o comportamento de carregamento do módulo do host. Você pode forçar o iframe de diagnóstico aninhado com `embedMode: "iframe"`, `renderMode: "iframe"`, `nested: true` ou `frame: "iframe"`. Se o iframe estiver bloqueado, `embedApp()` o substitui por um substituto de aplicativo aberto: o usuário pode tentar novamente in-line, abrir uma sessão de incorporação recém-criada por meio do host ou usar a rota visível URL. Mantenha o alvo `link` da ação útil por si só, porque ele ainda é a saída de emergência universal.
+
+Ao testar Claude por meio do ngrok, use uma compilação de produção (`npx @agent-native/core@latest build` e depois `npx @agent-native/core@latest start`) ou uma visualização/produção implantada URL. O caminho de transplante de quadro único do Claude funciona com pedaços de ativos de produção; módulos de desenvolvimento Vite brutos, como `/app/root.tsx`, podem ser protegidos pela autenticação do aplicativo e falhar nas importações dinâmicas da origem do recurso Claude.
+
+## Ponte de host API {#host-bridge}
+
+A ponte do host é deliberadamente pequena:
+
+| Modo                  | Tipo de mensagem                      | Use-o para                                          |
+| --------------------- | ------------------------------------- | --------------------------------------------------- |
+| rota direta do host   | `ui/update-model-context`             | Contexto oculto para o modelo host                  |
+| rota direta do host   | `ui/message`                          | Postar uma transformação de usuário visível no host |
+| rota direta do host   | `ui/open-link`                        | Abra um URL externo ou aplicativo por meio do host  |
+| rota direta do host   | `ui/request-display-mode`             | Solicitar `inline`, `fullscreen` ou `pip`           |
+| Transplante Claude    | `ui/*`                                | Mesma ponte direta do hospedeiro após a hidratação  |
+| ChatGPT / rota iframe | `agentNative.mcpHostContext`          | Tema, localidade, plataforma host, dimensões        |
+| ChatGPT / rota iframe | `agentNative.embeddedAppReady`        | Confirme o iframe da rota carregado                 |
+| ChatGPT / rota iframe | `agentNative.mcpHost.*` / `.response` | Retransmissão wrapper para solicitações de host     |
+
+Rotas incorporadas podem usar `updateMcpAppModelContext()`, `openMcpAppHostLink()`, `requestMcpAppDisplayMode()`, `getMcpAppHostContext()` e `useMcpAppHostContext()` de `@agent-native/core/client`. `sendToAgentChat()` usa o mesmo caminho das incorporações completas do aplicativo para solicitações enviadas automaticamente.
+
+O modo de exibição é o melhor esforço. O `McpAppRenderer` no aplicativo atualmente relata um contexto de host da web embutido e um modo de exibição somente embutido; hosts externos podem atender a solicitações de exibição maiores, ignorá-las ou responder com um erro de modo não suportado. Sempre mantenha a rota inline utilizável.
+
+## Suporte ao cliente e armazenamento em cache {#client-support}
+
+A atual lista oficial de clientes do MCP Apps inclui Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT e Cursor; o suporte do host ainda varia de acordo com o plano, canal de lançamento e versão do cliente, portanto verifique o [MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix). Os aplicativos MCP personalizados ChatGPT estão disponíveis no modo de desenvolvedor para espaços de trabalho Business e Enterprise/Edu na web ChatGPT; veja as notas [developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-apps-in-chatgpt-beta) de OpenAI.
+
+Claude Code, Codex e outros clientes CLI/editor de código ainda recebem os mesmos recursos e metadados quando oferecem suporte a aplicativos MCP, mas os tratam como hosts de link-out, a menos que você tenha verificado a renderização de iframe in-line nessa superfície exata. O link direto continua sendo o substituto confiável quando um host opta por não renderizar um iframe. Na prática, cada aplicativo nativo do agente deve ser criado com ambos: aplicativos MCP para revisão/edição in-line em hosts compatíveis e `link` para retorno universal ao aplicativo completo.
+
+Claude e ChatGPT podem armazenar em cache metadados de ferramentas e recursos para um conector personalizado existente. Depois de alterar os metadados do aplicativo MCP, verifique com uma nova chamada de ferramenta; se o host ainda usar o descritor antigo, reconecte o conector Claude ou verifique novamente/revise o conector ChatGPT para que ele atualize o catálogo. Se Claude registrar um aviso sobre `_meta.ui.csp` ou `_meta.ui.permissions` residindo no descritor de ferramenta após uma implantação, esse conector está usando metadados obsoletos: exclua/reconecte o conector Claude e inicie um novo bate-papo.
+
+## Teste {#testing}
+
+Teste aplicativos MCP com acessórios leves em torno de `embedApp()` e `McpAppRenderer`; eles cobrem CSP, contexto de host, inicialização de aplicativo e comportamento de mensagem de ponte sem a necessidade de um host externo real. Ao validar a web ChatGPT ou Claude, acione uma nova chamada de ferramenta após as alterações do shell e meça o iframe visível. Os frames renderizados anteriormente na mesma conversa ainda podem mostrar a altura em cache ou o comportamento de inicialização.
+
+## Relacionado {#related}
+
+- [External Agents](/docs/external-agents) — conectando Claude, ChatGPT, Codex e Cursor a aplicativos hospedados; Matriz de compatibilidade de aplicativos MCP; camadas de catálogo; links diretos.
+- [MCP Protocol](/docs/mcp-protocol) — o servidor MCP montado automaticamente, autenticação, ferramentas e `ask-agent`.
+- [Actions](/docs/actions) — `defineAction`, o construtor `link`, `publicAgent`.
+
+```
+
+```