@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/pt-BR/template-analytics.md

@@ -0,0 +1,259 @@
+---
+title: "Análise"
+description: "Faça perguntas analíticas em inglês simples e receba gráficos e painéis de volta. Um substituto de código aberto para Amplitude, Mixpanel e Looker."
+---
+
+# Análise
+
+Faça perguntas analíticas em inglês simples e receba gráficos e painéis de volta. O agente se conecta ao BigQuery, GA4, Amplitude, ao coletor de eventos primário integrado, HubSpot, Jira e uma dúzia de outras fontes, escreve a consulta para você, valida-a e renderiza a resposta como um gráfico, tabela ou painel de painel salvo.
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:500px;box-sizing:border-box'><h1 style='margin:0'>Agent-Native Templates</h1><p class='wf-muted' style='margin:0'>Adoption and engagement across the last 12 weeks.</p><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px'><div class='wf-card'><small class='wf-muted'>Weekly active users</small><br/><strong>24,318</strong><br/><span class='wf-pill accent'>+12.4%</span></div><div class='wf-card'><small class='wf-muted'>New signups</small><br/><strong>1,842</strong><br/><span class='wf-pill accent'>+8.7%</span></div><div class='wf-card'><small class='wf-muted'>Revenue MRR</small><br/><strong>$48,210</strong><br/><span class='wf-pill accent'>+21.3%</span></div></div><div style='display:grid;grid-template-columns:1fr 1fr;gap:12px;flex:1'><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Weekly active users</strong><div style='flex:1;display:flex;align-items:end;gap:8px'><div style='height:38%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:44%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:58%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:74%;flex:1;background:var(--wf-accent-soft)'></div></div></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Revenue over time</strong><div style='flex:1;display:flex;align-items:end;gap:8px'><div style='height:32%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:48%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:63%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:80%;flex:1;background:var(--wf-accent-soft)'></div></div></div></div><div class='wf-card'><strong>Signups by source</strong><br/><small class='wf-muted'>Lower chart begins below the main charts.</small></div></div>"
+}
+```
+
+É um substituto de código aberto para Amplitude, Mixpanel e Looker — para equipes que desejam possuir o código, as consultas e os dados.
+
+```an-diagram title="Question to chart" summary="The agent consults the data dictionary, writes SQL, validates it against the warehouse, then renders a chart or saves a panel."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-node\">Plain-English<br>question</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Agent</span><small class=\"diagram-muted\">reads data dictionary</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Writes SQL</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">Dry-run validate</div><small class=\"diagram-muted\">BigQuery / source</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Chart, table, or<br>saved panel</div></div>",
+  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-col{display:flex;flex-direction:column;gap:6px;align-items:center}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## O que você pode fazer com isso
+
+- **Faça perguntas sobre dados em inglês simples.** "Qual porcentagem de inscrições no mês passado foi convertida em paga?" ou "Mostre-me usuários ativos semanais nos últimos 6 meses". O agente escolhe a fonte certa, escreve o SQL e renderiza o gráfico.
+- **Crie painéis SQL reutilizáveis** com filtros, visualizações salvas e consultas paramétricas.
+- **Execute análises ad hoc** que cruzam várias fontes de dados, salvas como investigações reexecutáveis com a pergunta, as instruções e as descobertas originais.
+- **Mantenha um dicionário de dados vivo** de métricas, tabelas e receitas SQL para que o agente use sempre os nomes de colunas corretos (chega de adivinhar `is_closed` quando na verdade é `hs_is_closed`).
+- **Compartilhe painéis** com sua equipe: privados por padrão, compartilháveis por usuário ou por organização com funções de visualizador/editor/administrador.
+- **Conecte-se a muitas fontes** prontas para uso: BigQuery, GA4, Mixpanel, Amplitude, PostHog, HubSpot, Jira, Apollo, Pylon, Gong, Common Room, Twitter, além de fontes SEO específicas do aplicativo.
+- **Reutilize integrações de espaços de trabalho** quando um espaço de trabalho já estiver conectado e
+  concedeu um provedor ao Analytics. O provedor de lojas de integração compartilhada
+  referências de identidade e credenciais; O Analytics mantém a seleção de fontes específicas do aplicativo,
+  entradas de dicionário de dados, painel SQL e histórico de análise.
+
+## Primeiros passos
+
+Demonstração ao vivo: [analytics.agent-native.com](https://analytics.agent-native.com).
+
+Quando você abre o aplicativo pela primeira vez:
+
+1. Faça login com o Google.
+2. Abra a página **Fontes de dados** na barra lateral.
+3. Cada fonte tem um passo a passo. Conecte as que você precisa (comece com uma, como BigQuery, GA4, Amplitude ou rastreamento primário).
+4. Abra um novo chat com o agente e faça uma pergunta: "Quantas inscrições conseguimos na semana passada?"
+
+A primeira pergunta é suficiente para confirmar se a conexão funciona. A partir daí, peça ao agente para "salvar como um painel" ou "criar um painel de visão geral de quatro painéis para nossas principais métricas".
+
+### Instruções úteis
+
+- "Crie um painel mostrando usuários ativos semanais nos últimos seis meses."
+- "Qual porcentagem de inscrições no mês passado foi convertida em paga?"
+- "Adicione um gráfico comparando a receita por plano a este painel."
+- "Reordene os painéis neste painel para que a métrica MRR fique em primeiro lugar."
+- "Analise nossos negócios fechados e perdidos do primeiro trimestre e salve a análise."
+- "Execute novamente a análise de rotatividade com os dados deste mês."
+- "Documente esta métrica no dicionário de dados."
+
+O agente sempre sabe o que você está vendo (painel atual, filtros, visualização), então você pode dizer "este painel" ou "aquele painel" sem ser explícito.
+
+## Três coisas para saber
+
+O aplicativo tem três superfícies principais nas quais você passará o tempo:
+
+- **SQL Dashboards** — painéis reutilizáveis com filtros e visualizações salvas. Melhor para métricas que você verifica regularmente.
+- **Análises Ad-hoc** — investigações longas extraídas de diversas fontes, com instruções de reexecução salvas junto. Ideal para perguntas pontuais que você talvez queira revisar.
+- **Dicionário de Dados** — o catálogo canônico de métricas, tabelas, colunas e receitas SQL. O agente o consulta antes de escrever qualquer SQL, portanto ele usa nomes reais de colunas do warehouse e conhece advertências como "exclui e-mails internos".
+
+O dicionário é propagado perguntando ao agente: "importar nossas definições de dbt" ou "extrair as métricas de nosso manual Notion" e ele faz o trabalho.
+
+## Para desenvolvedores
+
+O restante deste documento é para qualquer pessoa que faça bifurcação do modelo do Analytics ou estenda-o.
+
+### Início rápido
+
+Crie um novo aplicativo Analytics a partir do CLI:
+
+```bash
+npx @agent-native/core@latest create my-analytics --standalone --template analytics
+```
+
+Desenvolvedor local:
+
+```bash
+cd my-analytics
+pnpm install
+pnpm dev
+```
+
+O CLI imprime o dev local URL. Faça login com o Google e abra a página **Fontes de dados** para conectar BigQuery, GA4, rastreamento primário, HubSpot, Jira e o resto.
+
+### Principais recursos
+
+**Faça perguntas, obtenha gráficos.** O agente escolhe uma fonte de dados, grava e valida SQL e, em seguida, renderiza um gráfico, tabela, métrica ou painel salvo.
+
+**Painéis e investigações.** Painéis reutilizáveis mantêm painéis SQL, filtros, visualizações salvas e compartilhamento; análises ad-hoc salvam descobertas mais longas com instruções de nova execução.
+
+**Dicionário de dados vivos.** Definições de métricas, proprietários, tabelas de origem e advertências conhecidas fornecem ao agente o vocabulário real do warehouse antes de escrever consultas.
+
+**Superfície de conector ampla.** BigQuery, GA4, análise de produto, CRM, suporte, comunidade, GitHub/Jira, SEO e eventos `/track` primários, todos vêm por meio do actions que o agente pode ligar.
+
+### Trabalhando com o agente
+
+O agente sempre sabe o que você está vendo. O estado atual da tela é injetado em cada mensagem como um bloco `<current-screen>` — ele contém a visualização ativa, o painel ou análise aberta e quaisquer filtros selecionados.
+
+O prompt do sistema do agente recebe um bloco `<data-dictionary>` injetado com as entradas de métricas aprovadas para a organização ativa. Quando você solicita um painel, o agente consulta primeiro o dicionário e usa os `table`/`columns`/`queryTemplate` documentados literalmente — ele não adivinha os nomes das colunas.
+
+**Contexto que possui automaticamente:**
+
+- **Visualização atual** — `overview`, `adhoc` (com `dashboardId`), `analyses` (com `analysisId`), `data-dictionary`, `data-sources` ou `settings`.
+- **Organização ativa** — abrange todas as consultas e gravações.
+- **Entradas de dicionário aprovadas** — para o espaço de trabalho ativo.
+
+**Edições do painel.** O agente usa a ação `update-dashboard` para editar painéis. Suporta dois modos:
+
+- `ops` — Patches de ponteiro JSON para edições cirúrgicas (mover um painel, substituir uma string SQL, remover um filtro).
+- `config` — substituição completa da configuração do painel.
+
+Cada SQL do painel do BigQuery é testado no warehouse antes que o painel seja salvo. Se uma coluna estiver errada, o salvamento será rejeitado com o erro do BigQuery. O agente corrige o SQL e tenta novamente em vez de persistir os painéis quebrados.
+
+### Conectando fontes de dados
+
+Abra a página **Fontes de dados** (`/data-sources`) para conectar provedores. Cada
+a fonte expõe uma lista de chaves de ambiente, um passo a passo e um botão **Testar conexão**.
+Quando o Analytics está sendo executado em um espaço de trabalho, `data-source-status` também gera relatórios
+concedeu conexões de espaço de trabalho reutilizáveis para `appId=analytics` para que o agente possa
+solicite uma concessão de aplicativo em vez de outra cópia da mesma chave do provedor.
+Para provedores reutilizáveis, como Slack, HubSpot, Notion e GitHub, os Dados
+Fontes UI mostra o estado de integração compartilhada diretamente: pronto via espaço de trabalho,
+precisa de concessão, precisa de credenciais ou credenciais locais.
+
+Integrações de espaço de trabalho reutilizáveis são a direção do tempo de execução para provedores compartilhados:
+a estrutura armazena identidade do provedor, metadados da conta, referências de credenciais e
+concessões por aplicativo uma vez; O Analytics armazena interpretação da fonte de dados, fonte de
+escolhas verdadeiras, definições de métricas, painéis e análises.
+
+As credenciais são armazenadas através da camada de configurações/ambiente da estrutura - sem segredos no git. A produção requer:
+
+| Variável                                 | Propósito                                               |
+| ---------------------------------------- | ------------------------------------------------------- |
+| `DATABASE_URL`                           | Conexão SQL persistente URL                             |
+| `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` | Autorização                                             |
+| `GOOGLE_SIGN_IN_CLIENT_ID` / `_SECRET`   | Cliente de login do Google preferencial (OAuth 2.0)     |
+| `GOOGLE_CLIENT_ID` / `_SECRET`           | Backup de login legado/cliente de integração Google API |
+| `BIGQUERY_PROJECT_ID`                    | Projeto BigQuery                                        |
+| `GOOGLE_APPLICATION_CREDENTIALS_JSON`    | Conta de serviço do BigQuery JSON                       |
+| `ANTHROPIC_API_KEY`                      | Bate-papo com agente                                    |
+
+As chaves específicas do provedor (HubSpot, Jira, Gong, Pylon etc.) estão documentadas no passo a passo de cada fonte na página Fontes de dados. Se você adicionar uma nova ação que precise de uma chave API, ela aparecerá como uma nova fonte nessa página por meio do registro de integração do modelo.
+
+Observação: a credencial OAuth do BigQuery para login do Google é **separada**
+credencial da conta de serviço do BigQuery JSON. Crie o cliente de login em
+Console GCP → APIs e serviços → Credenciais → ID do cliente OAuth e prefira o
+Nomes de ambiente `GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET`, então este
+o cliente de login de baixo escopo permanece separado dos clientes de integração do Google API.
+
+### Modelo de dados
+
+Tabelas principais (consulte `templates/analytics/server/db/schema.ts`):
+
+```an-schema title="Analytics data model" summary="Dashboards and analyses are the resources; views, shares, and a query cache hang off them. Org tables come from @agent-native/core/org."
+{
+  "entities": [
+    {
+      "id": "dashboards",
+      "name": "dashboards",
+      "note": "Explorer and SQL dashboards",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "kind", "type": "text", "note": "\"explorer\" or \"sql\"" },
+        { "name": "config", "type": "text", "note": "JSON matching SqlDashboardConfig" }
+      ]
+    },
+    {
+      "id": "dashboard_views",
+      "name": "dashboard_views",
+      "note": "Saved filter presets per dashboard",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "dashboard_id", "type": "text", "fk": "dashboards.id" }
+      ]
+    },
+    {
+      "id": "analyses",
+      "name": "analyses",
+      "note": "Re-runnable ad-hoc investigations",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "question", "type": "text" },
+        { "name": "instructions", "type": "text", "note": "Re-run steps" },
+        { "name": "dataSources", "type": "text", "note": "Sources touched" },
+        { "name": "resultMarkdown", "type": "text" },
+        { "name": "resultData", "type": "text", "nullable": true }
+      ]
+    },
+    {
+      "id": "bigquery_cache",
+      "name": "bigquery_cache",
+      "note": "Result cache keyed by SQL hash",
+      "fields": [
+        { "name": "sql_hash", "type": "text", "pk": true },
+        { "name": "bytes_processed", "type": "integer" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "dashboards", "to": "dashboard_views", "kind": "1-n", "label": "saved views" }
+  ]
+}
+```
+
+Mais tabelas de compartilhamento por recurso (`dashboard_shares`, `analysis_shares`) e tabelas organizacionais (`organizations`, `org_members`, `org_invitations`) fornecidas por `@agent-native/core/org`. O dicionário de dados reside na tabela `settings` da estrutura sob chaves com escopo definido.
+
+- **`dashboards`** — painéis Explorer e SQL. `kind` é `"explorer"` ou `"sql"`; `config` é um blob JSON correspondente a `SqlDashboardConfig`.
+- **`dashboard_shares`** — concessões de compartilhamento por recurso (principal, função).
+- **`dashboard_views`** — predefinições de filtro salvas por painel.
+- **`analyses`** — investigações ad hoc com `question`, `instructions`, `dataSources`, `resultMarkdown` e `resultData` opcional.
+- **`analysis_shares`** — concessões de compartilhamento por recurso para análises.
+- **`bigquery_cache`** — cache de resultados de consulta codificado por hash SQL com contabilidade processada por bytes.
+
+Além das tabelas organizacionais (`organizations`, `org_members`, `org_invitations`) fornecidas por `@agent-native/core/org`.
+
+O dicionário de dados reside na tabela `settings` da estrutura sob chaves com escopo definido; veja `list-data-dictionary` e `save-data-dictionary-entry` actions para ver o formato completo.
+
+### Personalizando
+
+O modelo do Analytics deve ser bifurcado e estendido. Tudo vive em `templates/analytics/`:
+
+- **`AGENTS.md`** — o guia de nível superior do agente. Visualizações de documentos, actions e fluxos de trabalho.
+- **`actions/`** — todas as operações que podem ser chamadas pelo agente. Adicione um novo arquivo para adicionar uma nova ação. Notáveis:
+  - `update-dashboard.ts` — edições no painel (operações + substituição completa)
+  - `save-analysis.ts`/`list-analyses.ts` — análises ad hoc
+  - `save-data-dictionary-entry.ts` / `list-data-dictionary.ts` — dicionário
+  - `bigquery.ts` — execução bruta do BigQuery
+  - `view-screen.ts` / `navigate.ts` — reconhecimento de contexto
+- **`app/routes/`** — rotas baseadas em arquivo. Cada rota é um invólucro fino em torno de uma página em `app/pages/`.
+- **`app/pages/adhoc/sql-dashboard/`** — o renderizador do painel SQL, editor de painel, barra de filtros, visualizações salvas.
+- **`app/pages/analyses/`** — analisa lista e visualização detalhada.
+- **`app/pages/DataSources.tsx`** — a integração da fonte de dados UI.
+- **`app/pages/DataDictionary.tsx`** — o navegador e editor de dicionário.
+- **`.agents/skills/`** — padrão orienta que o agente lê sob demanda:
+  - `dashboard-management` — armazenamento, resolução de escopo, formato de configuração do painel
+  - `data-querying` — qual script usar, padrões de filtragem
+  - `adhoc-analysis` — fluxo de trabalho para investigações de fontes cruzadas
+  - `data-querying`, `real-time-sync`, `frontend-design`, `storing-data`, `self-modifying-code`
+- **`.builder/skills/<provider>/SKILL.md`** — pegadinhas específicas do provedor (BigQuery, HubSpot, Jira, GA4 etc.). Leia antes de consultar; atualize quando aprender algo novo.
+- **`server/db/schema.ts`** — esquema Drizzle para painéis, compartilhamentos, visualizações, análises e cache do BigQuery.
+- **`server/lib/dashboards-store.ts`** — leitura/gravação de painel com resolução de escopo e migração KV legada.
+- **`server/lib/bigquery.ts`** — cliente do BigQuery, validador de simulação, lógica de cache.
+
+Para adicionar uma nova fonte de dados, coloque um script em `actions/` que chama o provedor e retorna resultados por meio do auxiliar `output()`. Ele fica disponível para o agente imediatamente e pode ser usado dentro de painéis de controle (se você expor o resultado por meio de um manipulador de servidor).
+
+Para adicionar um novo tipo de gráfico, estenda a união `ChartType` em `app/pages/adhoc/sql-dashboard/types.ts`, manipule-a em `SqlChartCard.tsx` e o agente poderá usá-la em qualquer painel.
+
+Para um padrão mais amplo de extensão de modelos, consulte [Skills guide](/docs/skills-guide) e [Actions](/docs/actions).

package/docs/content/locales/pt-BR/template-assets.md

@@ -0,0 +1,303 @@
+---
+title: "Ativos"
+description: "Um gerenciador de ativos digitais nativo do agente e serviço de geração entre agentes para mídia consistente com a marca."
+---
+
+# Recursos
+
+Assets é um espaço de trabalho nativo do agente para criar e gerenciar mídia consistente com a marca. Ele organiza uploads e resultados gerados em bibliotecas e pastas, permite que as equipes coletem exemplos de heróis de blog, diagramas, páginas de destino, fotos de produtos, vídeos e logotipos e, em seguida, roteia a geração por meio do chat do agente para que cada ativo possa ser revisado e refinado.
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:520px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Launch brand</h1><span class='wf-pill accent'>Blog heroes</span><span class='wf-pill'>Product shots</span><span class='wf-pill'>Logos</span><div style='flex:1'></div><button>Upload</button><button class='primary'>Generate</button></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Create brand media</strong><div class='wf-box'>Three homepage hero options using the approved logo and product references.</div><div style='display:flex;gap:8px;flex-wrap:wrap'><span class='wf-pill accent'>4 references</span><span class='wf-pill'>16:9</span><span class='wf-pill'>Web export</span></div></div><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px;flex:1'><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill accent'>Hero A</span></div><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill'>Reference set</span></div><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill'>Logo safe</span></div></div><div class='wf-card' style='display:grid;grid-template-columns:repeat(4,1fr);gap:8px'><div class='wf-box'>Use</div><div class='wf-box'>Refine</div><div class='wf-box'>Compare</div><div class='wf-box'>Export</div></div></div>"
+}
+```
+
+Ao abrir o aplicativo, a biblioteca selecionada, o prompt, as referências e os candidatos gerados permanecem em um espaço de trabalho. O agente pode navegar, pesquisar, gerar, refinar e exportar cada ativo por meio do mesmo actions usado pelo UI.
+
+```an-diagram title="Generate, review, reuse" summary="References and prompts feed a generate-and-choose session; chosen assets land in a library and flow out to other apps via the picker or A2A."
+{
+  "html": "<div class=\"diagram-assets\"><div class=\"diagram-col\"><div class=\"diagram-node\">References<br><small class=\"diagram-muted\">logos, product shots, style</small></div><div class=\"diagram-node\">Prompt<br><small class=\"diagram-muted\">chat or Generate controls</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill accent\">Generation session</span><small class=\"diagram-muted\">image &amp; video candidates · audit log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill ok\">Library</span><small class=\"diagram-muted\">chosen, brand-consistent assets</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">Picker<br><small class=\"diagram-muted\">iframe / MCP App</small></div><div class=\"diagram-node\">A2A<br><small class=\"diagram-muted\">Slides · Design · Content</small></div></div></div>",
+  "css": ".diagram-assets{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-assets .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-assets .diagram-box{display:flex;flex-direction:column;gap:4px}.diagram-assets .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## Quando escolher
+
+- **Sua equipe precisa de orientação visual reutilizável**, e não de solicitações de mídia genéricas e únicas. Colete logotipos aprovados, fotos de produtos e exemplos de estilo para que gerações permaneçam na marca.
+- **Você deseja que a mídia gerada seja revisada e refinada**, com um registro de auditoria completo de prompts, modelos, referências e linhagem para cada execução.
+- **Outros aplicativos precisam de um seletor ou gerador de recursos** — Slides, Design, Conteúdo, um editor de blog ou um construtor de sites podem incorporar o seletor ou chamar Assets por A2A.
+- **Você deseja que a mídia da marca seja disponibilizada pelo seu agente de codificação** — Codex, Claude Code, Claude ou ChatGPT podem gerar e selecionar recursos sem sair do chat.
+
+## Primeiros passos
+
+Demonstração ao vivo: [assets.agent-native.com](https://assets.agent-native.com).
+
+1. **Crie uma biblioteca.** Adicione a marca, a campanha, o produto ou o fluxo de conteúdo que você deseja
+   deseja gerenciar.
+2. **Fazer upload de referências.** Adicione logotipos aprovados, fotos de produtos, exemplos de estilo ou
+   vídeos existentes para que o agente tenha material concreto para trabalhar.
+3. **Gere no chat ou em uma biblioteca.** Solicite uma imagem principal, um diagrama ou um produto
+   imagem ou variante de vídeo. O Assets armazena prompt, referências, modelo, status,
+   e linhagem para revisão.
+4. **Use o recurso em outro lugar.** Copie a exportação e incorpore o seletor em outro
+   aplicativo ou deixe outro agente ligar para o Assets por A2A.
+
+## Instruções úteis
+
+- "Gere três opções de heróis do blog usando as referências de produtos Acme."
+- "Crie uma imagem social quadrada no estilo da campanha de lançamento."
+- "Encontre todos os recursos aprovados para a reformulação da integração."
+- "Transforme este diagrama enviado em uma imagem explicativa do produto mais limpa."
+- "Crie um storyboard de vídeo e salve o melhor conjunto de quadros nesta biblioteca."
+
+## O que você pode fazer com isso
+
+- **Crie bibliotecas de recursos.** Agrupe imagens de referência, vídeos, logotipos canônicos, notas de estilo, paletas, pastas e resultados gerados por marca, campanha, produto ou categoria.
+- **Gerar por meio de bate-papo.** O compositor inicial e os controles Gerar da biblioteca enviam o prompt ao agente com `sendToAgentChat()`, para que os usuários possam inspecionar variantes, fornecer feedback e iterar.
+- **Gere imagens e vídeos.** A geração de imagens gerenciadas pelo Builder está disponível quando ativada, e o Gemini potencializa a geração de vídeo e o substituto manual de imagens.
+- **Carregue e descreva referências.** Adicione imagens ou vídeos da biblioteca UI ou solicite o botão de anexo do compositor e pesquise por título, descrição, texto alternativo, prompt, modelo, tipo de mídia, status, função, pasta ou coleção.
+- **Mantenha um registro de auditoria de geração.** Cada execução registra prompts, modelo, proporção, referências, ativo de origem, linhagem, ativos gerados, status, erros e carimbos de data/hora para revisão posterior do projeto.
+- **Preserva a precisão do logotipo.** O agente pode gerar uma área de espaço reservado e o servidor compõe o logotipo canônico carregado na imagem final, em vez de depender do modelo de imagem para redesenhá-lo.
+- **Incorporado como um seletor.** Outros aplicativos podem criar iframe `/picker` e ouvir o evento `chooseAsset` de `@agent-native/embedding`, transformando o Assets em um seletor/gerador de ativos para editores de blog, construtores de sites, apresentações de slides e aplicativos personalizados. O seletor também emite o alias herdado `chooseImage` para hosts somente de imagem existentes.
+- **Instalar como uma habilidade apoiada por aplicativo.** O manifesto `agent-native.app-skill.json` exporta uma habilidade de Ativos mais metadados do conector MCP para que os mercados possam instalar o aplicativo, suas instruções e seu seletor juntos.
+- **Servir outros agentes.** Slides, Design, Content, Mail e Dispatch podem chamar recursos por meio de A2A para listar bibliotecas, gerar lotes, criar vídeos, refinar um recurso, buscar exportações e renderizar visualizações in-line onde a incorporação é permitida.
+
+## Usando-o do seu agente de codificação
+
+Gere e escolha mídia de marca sem sair do código Codex, Claude, Claude ou ChatGPT.
+
+1. **Instale uma vez.** Isso adiciona as instruções de habilidade e registra o conector MCP hospedado em conjunto:
+
+   ```bash
+   npx @agent-native/core@latest skills adicionar ativos # alias: geração de imagem
+   ```
+
+   O cliente padrão é `codex`; adicione `--client claude-code` ou `--client all` para outros.
+   Se você deseja apenas as instruções de habilidades portáteis através do Vercel/open
+   Skills CLI, use:
+
+   ```bash
+   npx skills@latest adicionar BuilderIO/agent-native --skill assets
+   ```
+
+   O Vercel/open Skills CLI instala apenas o arquivo de instruções; isso não acontece
+   execute a configuração do conector MCP. Use o caminho Agent Native CLI acima quando quiser
+   a configuração com um comando.
+
+2. **Peça imagens.** No chat do seu agente: "Gere três opções de heróis do blog a partir das fotos dos produtos Acme." O agente abre o seletor com imagens candidatas que você pode regenerar, reajustar (prompt, aspecto, contagem) e escolher.
+3. **Escolha.** Em hosts inline (bate-papo principal ChatGPT, Claude.ai, Claude Desktop), o seletor é renderizado diretamente no bate-papo - clique em um candidato e a escolha retorna automaticamente. Em hosts CLI/somente link (Codex, Claude Code, guia "Código" do Claude Desktop), você obtém um link **"Abrir em Ativos →"**; abra-o, escolha no navegador e cole o resumo da transferência copiado de volta no seu bate-papo ou apenas diga "use a imagem A".
+
+   ```texto
+   Cole esta seleção novamente em seu chat para que o agente possa usá-la.
+
+   Imagem de ativos selecionados para a próxima etapa: <label>
+   Mídia URL: <url>
+   Use este recurso selecionado no artefato ou design atual.
+
+   Contexto do recurso selecionado:
+   { "selectedAsset": { "assetId": "...", "url": "...", "mediaType": "image", ... } }
+   ```
+
+4. **Aplicar ao código.** As mídias escolhidas URL e `assetId` voltam para o agente, que usa o URL diretamente no código que escreve (um src `<img>`, um download) ou chama `export-asset`.
+
+## Para desenvolvedores
+
+O restante deste documento é para qualquer pessoa que faça bifurcação do modelo Assets ou estenda-o.
+
+### Andaimes
+
+```bash
+npx @agent-native/core@latest create my-assets --standalone --template assets
+```
+
+### Modelo de dados
+
+Todos os dados residem em SQL via Drizzle ORM (a mídia binária reside no armazenamento de objetos ou no substituto de upload de arquivo local durante o desenvolvimento). Esquema: `templates/assets/server/db/schema.ts`. As bibliotecas carregam o `ownableColumns` padrão e uma tabela de compartilhamentos de estrutura correspondente, para que elas se encaixem no modelo de compartilhamento por usuário/por organização.
+
+Observação: os nomes das tabelas SQL mantêm o prefixo `image_*` herdado de quando o aplicativo era chamado de Imagens. Eles também cobrem vídeos e outras mídias.
+
+| Tabela                           | O que ele contém                                                                                                                                                                                                      |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `image_libraries`                | Uma biblioteca — o contêiner de nível superior agrupado por marca, campanha, produto ou categoria. Contém `custom_instructions`, `style_brief`, logotipo canônico e referências de ativos de capa e estado do arquivo |
+| `image_library_shares`           | O Framework compartilha princípios de mapeamento de tabelas (usuários ou organizações) para funções (visualizador, editor, administrador) por biblioteca                                                              |
+| `image_collections`              | Agrupamentos de estilo/categoria dentro de uma biblioteca — `style_brief`, `prompt_template`, proporção padrão e tamanho da imagem                                                                                    |
+| `asset_folders`                  | Pastas aninháveis dentro de uma biblioteca (`parent_id` para hierarquia)                                                                                                                                              |
+| `image_generation_presets`       | Receitas de geração salvas — tipo de mídia, modelo de prompt, proporção de aspecto, modelo e política de texto/referência                                                                                             |
+| `image_generation_sessions`      | Uma sessão iterativa de geração e escolha com um resumo, status, ativo ativo e feedback de feedback                                                                                                                   |
+| `image_generation_session_items` | Recursos do candidato em uma sessão, cada um com uma função e uma observação                                                                                                                                          |
+| `image_assets`                   | O registro do ativo — tipo de mídia, função, status, título/descrição/texto alternativo, prompt, modelo, dimensões, tipo MIME, chaves de objeto/miniatura e linhagem                                                  |
+| `image_generation_runs`          | O log de auditoria de geração — prompt, prompt compilado, modelo, referências, status, erros e o `source` (`chat` / `ui` / `a2a`) que o acionou                                                                       |
+
+```an-schema title="Assets data model" summary="Libraries are the ownable container; collections, folders, and presets organize them. Sessions drive generate-and-choose; assets and runs hold output and the audit log. Table names keep the legacy image_* prefix but cover all media."
+{
+  "entities": [
+    { "id": "library", "name": "image_libraries", "note": "Top-level ownable container", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "custom_instructions", "type": "text", "nullable": true },
+      { "name": "style_brief", "type": "text", "nullable": true },
+      { "name": "logo_asset_id", "type": "id", "fk": "image_assets.id", "nullable": true },
+      { "name": "archived", "type": "boolean" }
+    ] },
+    { "id": "library_shares", "name": "image_library_shares", "note": "Framework shares table", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "role", "type": "text", "note": "viewer / editor / admin" }
+    ] },
+    { "id": "collections", "name": "image_collections", "note": "Style/category groupings", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "style_brief", "type": "text", "nullable": true },
+      { "name": "prompt_template", "type": "text", "nullable": true }
+    ] },
+    { "id": "folders", "name": "asset_folders", "note": "Nestable folders", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "parent_id", "type": "id", "fk": "asset_folders.id", "nullable": true }
+    ] },
+    { "id": "presets", "name": "image_generation_presets", "note": "Saved generation recipes", "fields": [
+      { "name": "media_type", "type": "text" },
+      { "name": "prompt_template", "type": "text" },
+      { "name": "model", "type": "text" }
+    ] },
+    { "id": "sessions", "name": "image_generation_sessions", "note": "Iterative generate-and-choose", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "status", "type": "text" },
+      { "name": "active_asset_id", "type": "id", "fk": "image_assets.id", "nullable": true }
+    ] },
+    { "id": "session_items", "name": "image_generation_session_items", "note": "Candidate assets in a session", "fields": [
+      { "name": "session_id", "type": "id", "fk": "image_generation_sessions.id" },
+      { "name": "asset_id", "type": "id", "fk": "image_assets.id" },
+      { "name": "role", "type": "text" }
+    ] },
+    { "id": "assets", "name": "image_assets", "note": "The asset record", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "media_type", "type": "text", "note": "image / video" },
+      { "name": "status", "type": "text" },
+      { "name": "prompt", "type": "text", "nullable": true },
+      { "name": "object_key", "type": "text", "nullable": true }
+    ] },
+    { "id": "runs", "name": "image_generation_runs", "note": "Generation audit log", "fields": [
+      { "name": "model", "type": "text" },
+      { "name": "status", "type": "text" },
+      { "name": "source", "type": "text", "note": "chat / ui / a2a" }
+    ] }
+  ],
+  "relations": [
+    { "from": "library", "to": "collections", "kind": "1-n" },
+    { "from": "library", "to": "folders", "kind": "1-n" },
+    { "from": "library", "to": "assets", "kind": "1-n" },
+    { "from": "sessions", "to": "session_items", "kind": "1-n" },
+    { "from": "library", "to": "library_shares", "kind": "1-n" }
+  ]
+}
+```
+
+### Personalizando
+
+Assets é um modelo completo e clonável. Algumas ideias práticas de extensão:
+
+- "Adicione um conector de catálogo de produtos para que as fotos de referência do produto possam ser selecionadas por SKU."
+- "Adicione uma fila de aprovação rigorosa antes que os recursos gerados sejam marcados como utilizáveis para marketing."
+- "Adicione um painel de avaliação da marca que filtre gerações com falha ou com classificação baixa por modelo."
+- "Crie uma biblioteca de recursos padrão para todo o espaço de trabalho e direcione a geração de imagens do Apresentações por meio dela."
+- "Adicione um novo provedor por trás da interface de geração de imagens depois de verificar a documentação mais recente do provedor."
+
+O agente edita rotas, componentes, modelos actions, skills e SQL conforme necessário. Consulte [Templates](/docs/cloneable-saas) para clonagem completa, personalização e fluxo de implantação e [A2A Protocol](/docs/a2a-protocol) para geração entre aplicativos.
+
+### Incorpore o seletor
+
+Use a rota do seletor quando um humano estiver escolhendo ou gerando um ativo interno
+outro produto. Imagem é o tipo de mídia padrão; passe `mediaType=video` quando
+você deseja navegar/selecionar vídeos:
+
+```tsx
+import { EmbeddedApp } from "@agent-native/embedding";
+
+<EmbeddedApp
+  url="https://assets.agent-native.com/picker?mediaType=image"
+  onMessage={(name, payload) => {
+    if (name === "chooseAsset") {
+      insertAsset((payload as { url: string }).url);
+    }
+  }}
+/>;
+```
+
+Hosts MCP externos devem chamar `open-asset-picker` em vez de construí-lo
+iframe manualmente. A ação retorna um link substituto do navegador e metadados do aplicativo MCP
+para hosts embutidos. Quando um usuário seleciona um ativo, o seletor emite `chooseAsset`,
+o alias herdado `chooseImage` para recursos de imagem e atualizações do modelo do aplicativo MCP
+contexto onde o host o suporta. Quando um host abre o link substituto em um
+guia normal do navegador em vez de renderizar o aplicativo MCP inline, selecionando um ativo
+copia um resumo de transferência e mostra um bloco de contexto copiável; cole esse resumo
+voltar ao chat para que o agente externo possa usar a mídia selecionada URL e
+metadados de recursos.
+
+Codex, Claude Code e Claude Desktop Code devem ser tratados como hosts de link-out
+para este fluxo. Eles não podem renderizar aplicativos MCP inline e descontos CDN remotos
+as imagens podem não ser exibidas de forma confiável na transcrição do bate-papo. Os agentes devem manter o
+link de ativos como fonte da verdade; quando uma visualização in-line visível é necessária em um
+bate-papo do editor de código, baixe o `previewUrl`/`downloadUrl` selecionado para um local
+arquivo de imagem e incorpore esse caminho local absoluto.
+
+Para fluxos de geração e escolha, chame `open-asset-picker` com `prompt`,
+`autoGenerate: true` e `count: 3` (personalizáveis de 1 a 6). O seletor é aberto
+com imagens candidatas e permite que o usuário ajuste a contagem, a proporção ou um
+predefinição de geração antes de escolher o ativo final URL.
+
+Use A2A quando outro agente precisar criar, pesquisar ou exportar ativos sem
+selecionador humano UI.
+
+### Desenvolvedor: distribua a habilidade do aplicativo
+
+A habilidade do aplicativo Assets tem o ID do aplicativo `assets` e MCP hospedado URL hospedado
+`https://assets.agent-native.com/_agent-native/mcp`.
+
+```bash
+# Easiest hosted install: exported skill instructions plus MCP connector.
+npx @agent-native/core@latest skills add assets
+
+# Vercel/open Skills CLI install: exported instructions only, no MCP config.
+npx skills@latest add BuilderIO/agent-native --skill assets
+
+# Hosted install: URL-only MCP connector, no shared secrets in skill files.
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# Local editable launch.
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# Marketplace package, including Claude Code marketplace and Vercel Labs skills adapters.
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# Install a local exported Assets bundle with the open skills CLI.
+npx skills@latest add ./dist/assets-skill --skill assets -a codex -y
+
+# Install from the generated Claude Code marketplace adapter.
+claude plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace
+claude plugin install agent-native-assets@agent-native-apps
+```
+
+A habilidade exportada ensina os agentes a usar o seletor para interação humana
+seleção, actions direto para geração autônoma de imagem/vídeo e navegador
+links quando os aplicativos MCP inline não estão disponíveis.
+
+O adaptador de mercado Claude contém um `.claude-plugin/marketplace.json`
+catálogo e um plugin `agent-native-assets` com `skills/assets/SKILL.md` plus
+o `.mcp.json` hospedado. No código Claude interativo, o mesmo fluxo está disponível
+como `/plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace`,
+`/plugin install agent-native-assets@agent-native-apps`, `/reload-plugins` e
+`/mcp` para autenticação MCP.
+
+Se você instalar a partir de um pacote de mercado bruto com `npx skills@latest`, registre o
+conector MCP hospedado para que essas instruções possam chamar o aplicativo Assets ativo:
+
+```bash
+npx @agent-native/core@latest app-skill ensure --manifest ./dist/assets-skill/agent-native.app-skill.json --yes
+```
+
+## O que vem a seguir
+
+- [**Templates**](/docs/cloneable-saas) — o modelo clone e próprio
+- [**Embedding SDK**](/docs/embedding-sdk) — seletor de iframe e padrões de sidecar
+- [**A2A Protocol**](/docs/a2a-protocol) — como outros aplicativos chamam ativos
+- [**File Uploads**](/docs/file-uploads) — armazenamento e serviço de ativos autenticados
+- [**Sharing & Privacy**](/docs/sharing) — controle de acesso em nível de biblioteca