failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/pt-br/agenteye/alerts.mdx

@@ -0,0 +1,63 @@
+---
+title: "Alertas"
+description: "Saiba no momento em que algo ultrapassa seu limite, no canal que sua equipe já monitora, em vez de ficar sabendo pelo cliente."
+---
+
+
+Saiba no momento em que algo ultrapassa seu limite, no canal que sua equipe já monitora, em vez de ficar sabendo pelo cliente. Configure uma regra uma vez e a Observabilidade do Failproof AI verifica ela periodicamente, depois te notifica por e-mail, Slack, webhook ou direto no dashboard.
+
+![A página de Alertas: uma grade de cartões de regras de alerta, cada um mostrando seu gatilho, janela de avaliação, canais e um selo de severidade informativo, de aviso ou crítico](/agenteye/images/alerts.png)
+*Todas as regras de alerta de relance: o que monitoram, com que frequência, onde notificam e qual a urgência.*
+
+## Saiba dos problemas antes dos seus usuários
+
+Pare de ficar atualizando um dashboard na esperança de capturar uma regressão. Use um alerta sempre que houver um sinal que você precisaria saber mesmo quando ninguém está olhando, e receba-o onde você já está:
+
+- **E-mail**, para quem precisa saber.
+- **Slack**, uma mensagem rica com um botão que vai direto ao incidente.
+- **Webhook**, um POST JSON para PagerDuty, Opsgenie ou seu próprio endpoint, com uma assinatura opcional para que o receptor possa confiar nele.
+- **No dashboard**, discreto por design, para quando você está ajustando uma regra e ainda não quer notificar ninguém.
+
+Combine qualquer combinação em uma única regra, e a severidade (informativo, aviso ou crítico) é incluída para que os urgentes pareçam urgentes.
+
+## Monte a regra em um formulário, não em JSON
+
+Você descreve o que "quebrado" significa em um formulário, e a Observabilidade do Failproof AI escreve a regra subjacente para você. A especificação JSON é apenas o que esse formulário produz nos bastidores, então você pode lê-la para entender uma regra, mas raramente precisa digitá-la.
+
+![O formulário de novo alerta: nome e descrição, um botão de ativar/desativar, e um seletor de gatilho oferecendo limite de métrica, SQL personalizado, pontuação de avaliação, avaliação composta e condições por evento](/agenteye/images/alert-new.png)
+*Escolha um gatilho e o formulário exibe os campos corretos; Salvar grava a regra.*
+
+O caminho feliz é rápido: dê um nome, escolha um **gatilho** (o que monitorar), defina o **limite e a janela** (quão grave, por quanto tempo), adicione pelo menos um **canal**, depois **Salve** e clique em **Testar** para disparar uma notificação sintética e confirmar que cada destino está configurado. Por baixo dos panos, isso produz uma pequena especificação como:
+
+```json
+{ "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 }
+```
+
+Você não está limitado a um tipo de sinal. Escolha o gatilho que corresponde à forma como você pensa sobre a falha:
+
+| Gatilho | Dispara quando |
+|---|---|
+| **Limite de métrica** | uma métrica predefinida (taxa de erros, latência p95 ou p99, contagens de eventos ou erros, gasto com tokens) ultrapassa seu limite em uma janela |
+| **SQL personalizado** | sua própria consulta somente leitura retorna uma linha, ou um valor calculado ultrapassa um limite |
+| **Pontuação de avaliação** | a média da pontuação de um avaliador (por exemplo, alucinação) ultrapassa um limite |
+| **Avaliação composta** | várias verificações de pontuação se combinam com lógica any, all ou pelo-menos-N, para capturar uma regressão que só aparece entre pontuações |
+| **Por evento** | um único evento correspondente ocorre: um agente específico, um tipo de erro específico ou uma substring de mensagem |
+
+Já está olhando para uma falha na [página de Erros](/pt-br/agenteye/error-tracking)? Cada linha lá tem um botão **+ alerta** que abre esse mesmo formulário preenchido para capturar exatamente aquela falha novamente, de modo que o incidente que você acabou de triar se torna o próximo a te notificar.
+
+**Onde encontrar:** Os alertas ficam em `/<org-slug>/alerts`. Criar, editar, excluir e testar regras requer **`alerts:write`**; `alerts:read` é suficiente para visualizar. O seletor de destinatários lista os membros da sua organização por nome, para que você possa notificar uma pessoa sem sair do formulário.
+
+## Notifique-me apenas quando for real
+
+Uma medição ruim não deveria te acordar. O filtro de ruído **M de N** controla quantas das últimas verificações precisam falhar antes que o alerta realmente te notifique. Defina como **3 de 5** e a regra só dispara após ter ultrapassado o limite em três das últimas cinco verificações, evitando que um sinal instável gere alarmes falsos; deixe no padrão **1 de 1** para disparar na primeira violação. Você também escolhe com que frequência a regra é executada, a partir de predefinições de 1m, 5m, 15m e 1h, adequadas à velocidade com que o sinal realmente se move.
+
+## O que acontece quando um alerta dispara
+
+Uma violação abre um **incidente** e notifica seus canais uma vez. A partir daí, sua equipe confirma o recebimento, atribui um responsável, discute o problema e o resolve, tudo contra um registro limpo e atribuído. Esse fluxo de triagem tem seu próprio espaço: veja [Incidentes](/pt-br/agenteye/incidents).
+
+## Relacionados
+
+- [Incidentes](/pt-br/agenteye/incidents): acompanhe um alerta disparado do estado aberto ao confirmado e ao resolvido.
+- [Rastreamento de erros](/pt-br/agenteye/error-tracking): agrupe falhas de agentes e promova uma delas a um alerta com um clique.
+- [Dashboards](/pt-br/agenteye/dashboards): monitore os painéis compartilhados de onde vêm os limites que você alerta.
+- [CLI e agentes](/pt-br/agenteye/cli-and-agents): crie alertas e confirme incidentes pelo terminal, ou automatize-os no CI.

package/.next/standalone/docs-old/pt-br/agenteye/api-keys.mdx

@@ -0,0 +1,280 @@
+---
+title: "API Keys"
+description: "As API keys controlam quem e o que pode acessar seu servidor de Observabilidade do Failproof AI, para que um coletor possa enviar eventos sem nunca obter poderes de leitura ou administração."
+---
+
+
+As API keys controlam quem e o que pode acessar seu servidor de Observabilidade do Failproof AI, para que um coletor possa enviar eventos sem nunca obter poderes de leitura ou administração. Cada chave carrega uma ou mais permissões, e cada permissão controla rotas específicas do servidor; você concede apenas as necessárias para cada função. A maioria dos deployments cria apenas três tipos de chave.
+
+## As 3 chaves que a maioria dos deployments precisa
+
+| Chave | Permissões | Quem usa |
+|---|---|---|
+| Chave de coletor | `events:add` | O `agenteye-collector` em cada máquina de agente, para enviar eventos. |
+| Chave de leitura do dashboard | `events:read`, `keys:read` | Um operador somente leitura ou integração que consulta dados sem modificá-los. |
+| Chave admin bootstrap | todas as permissões | O operador que inicializa a instância (e o dashboard) pela primeira vez. Gerada a partir da variável de ambiente `ADMIN_KEY`. Veja [Chave admin bootstrap](#bootstrap-admin-key). |
+
+Comece por aqui. Recorra ao catálogo completo de permissões abaixo apenas quando precisar de uma chave personalizada com escopo mais restrito. Veja também [Layout de chaves recomendado](#recommended-key-layout) e [Criando chaves](#creating-keys).
+
+---
+
+## Permissões
+
+O servidor aplica um catálogo fixo de permissões; cada uma controla rotas HTTP específicas. Uma **chave admin** possui todas elas; uma chave com escopo definido possui o subconjunto que você concede na criação. Strings de permissão desconhecidas são rejeitadas ao criar uma chave.
+
+> **Nota:** Duas permissões válidas são exclusivas para humanos/dashboard e não podem ser concedidas a uma API key: `orgs:admin` (administração da instância, exclusiva do operador) e `keys:update`. Uma requisição para `POST /keys` ou `PATCH /keys/:id` que tente conceder qualquer uma delas é rejeitada com HTTP 422. Veja a linha `keys:update` abaixo para entender por que uma chave bearer pode criar chaves, mas nunca editá-las.
+
+### Ingestão e consulta de eventos
+
+| Permissão | Rotas HTTP | O que permite |
+|---|---|---|
+| `events:add` | `POST /events` | Ingerir lotes de eventos de um coletor. É a única permissão que um coletor precisa. |
+| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Consultar eventos, listar os ambientes conhecidos, listar os identificadores de modelos vistos nos dados (usados pela visualização de Modelos e filtros de modelo), calcular o agregado de latência que alimenta o mapa de calor / banda de percentil, e exportar uma sessão como JSONL. Os endpoints de faceta do filtro compartilhado `GET /events/environments` e `GET /events/agent_ids` são acessíveis com **qualquer um** de `events:read` **ou** `evaluations:read`, para que a página de sessões (restrita a `evaluations:read`) reutilize a mesma faceta por organização. `GET /events/models` não é um deles: requer `events:read`, então um principal que possui apenas `evaluations:read` recebe um 403 nessa rota. |
+
+### Sessões e avaliações
+
+| Permissão | Rotas HTTP | O que permite |
+|---|---|---|
+| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Listar sessões, ler resultados de avaliações, a saúde consolidada de avaliações usada pelos dashboards, e o estado da fila de trabalhadores de jobs de avaliação. |
+| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Enfileirar manualmente uma reavaliação para uma sessão concluída. |
+
+### Dashboards
+
+| Permissão | Rotas HTTP | O que permite |
+|---|---|---|
+| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Listar dashboards, carregar um e ler seus tiles. |
+| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Criar e editar dashboards, adicionar / editar / remover tiles, e reordenar o grid de tiles. |
+| `dashboards:delete` | `DELETE /dashboards/:id` | Excluir um dashboard inteiro (a exclusão no nível de tile fica em `dashboards:write`). |
+
+### Consultas salvas (compositor SQL)
+
+| Permissão | Rotas HTTP | O que permite |
+|---|---|---|
+| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Listar consultas salvas, carregar uma e inspecionar o schema somente leitura que o compositor usa como alvo. |
+| `queries:write` | `POST /queries`, `PUT /queries/:id` | Criar e editar consultas salvas. O SQL ainda é roteado pelo mesmo papel somente leitura e verificações de SQL protegidas que uma chamada `queries:run`. |
+| `queries:delete` | `DELETE /queries/:id` | Excluir uma consulta salva. |
+| `queries:run` | `POST /queries/run` | Executar SQL salvo ou ad-hoc contra o papel somente leitura usado pelo compositor. |
+
+### Assistente de IA
+
+| Permissão | Rotas HTTP | O que permite |
+|---|---|---|
+| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Conversar com o assistente de IA e gerenciar suas próprias conversas (privadas). Necessário no **usuário** para ver o painel do assistente; a chave própria do assistente é `dashboard-assistant` e é gerada separadamente (veja abaixo). |
+
+### API keys
+
+| Permissão | Rotas HTTP | O que permite |
+|---|---|---|
+| `keys:create` | `POST /keys` | Criar uma nova API key com escopo definido. **Não** concede edição das permissões de uma chave existente (isso é `keys:update`). |
+| `keys:read` | `GET /keys` | Listar chaves existentes. Segredos nunca são retornados por este endpoint. |
+| `keys:update` | `PATCH /keys/:id` | Editar as permissões de uma chave existente. Permissão **exclusiva para humanos/dashboard**; não pode ser atribuída a uma API key (uma chave bearer pode criar chaves, mas nunca editá-las). |
+| `keys:disable` | `POST /keys/:id/disable` | Revogar uma chave. Chaves protegidas (`admin`, `dashboard-assistant`) não podem ser desativadas; faça a rotação por variável de ambiente + reinicialização. |
+| `keys:regenerate` | `POST /keys/:id/regenerate` | Rotacionar o segredo de uma chave. Chaves protegidas não podem ser regeneradas por esta rota. |
+
+### Usuários do dashboard
+
+| Permissão | Rotas HTTP | O que permite |
+|---|---|---|
+| `users:create` | `POST /users`, `GET /users/defaults` | Convidar um novo usuário do dashboard (envia um e-mail + login com senha de uso único (OTP)) e ler o conjunto de permissões padrão configurado no dashboard usado para pré-preencher o formulário de convite. |
+| `users:read` | `GET /users`, `GET /users/:id` | Listar usuários e carregar um registro de usuário individual. |
+| `users:update` | `PUT /users/:id` | Editar as permissões de um usuário. As atualizações enviam um e-mail de alteração de permissões ao usuário afetado e entram em vigor na próxima requisição dele; nenhum novo login é necessário. |
+| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Desativar um usuário (revoga suas sessões imediatamente) e reativar um usuário anteriormente desativado. |
+
+Essas permissões sustentam a página **Users** do dashboard, onde os escopos concedidos a cada membro são exibidos como chips:
+
+![A página Users: um card por usuário do dashboard com seu e-mail, permissões concedidas e controles de edição/desativação](/agenteye/images/users.png)
+
+### Configurações operacionais
+
+| Permissão | Rotas HTTP | O que permite |
+|---|---|---|
+| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Visualizar configurações operacionais gerenciadas pelo dashboard e seus metadados; listar substituições de janela de contexto por modelo; e resolver a janela efetiva para um modelo. |
+| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Editar configurações operacionais e adicionar, alterar ou remover substituições de janela de contexto por modelo. As alterações afetam novos eventos sem reiniciar o servidor. |
+
+![A página Settings: configurações operacionais gerenciadas pelo dashboard, como logins permitidos e tempos de vida de sessão/OTP, editáveis sem reinicialização](/agenteye/images/settings.png)
+
+### Alertas e incidentes
+
+| Permissão | Rotas HTTP | O que permite |
+|---|---|---|
+| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Visualizar definições de alertas configurados. |
+| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Criar, editar, excluir e disparar alertas de teste. |
+| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Visualizar incidentes e seu histórico de triagem. |
+| `incidents:write` | `POST /alerts/:id/incidents` | Abrir um incidente manualmente contra um alerta existente. |
+| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Reconhecer, atribuir, resolver e comentar incidentes. |
+
+### Auditorias
+
+| Permissão | Rotas HTTP | O que permite |
+|---|---|---|
+| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Visualizar definições de auditoria, histórico de execuções e achados. |
+| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Criar, editar, excluir e executar auditorias; triar achados (reconhecer / silenciar / descartar / resolver / reabrir / atribuir). |
+
+> **Nota:** Para conceder a uma chave acesso à superfície de auditoria, conceda `audits:*` a ela explicitamente. Veja [Notas de atualização e compatibilidade retroativa](#upgrade-and-backward-compatibility-notes) para saber como os beneficiários existentes foram migrados quando Auditorias foi lançado.
+
+> O endpoint de seleção de destinatários `GET /alerts/recipients` (que lista os e-mails de membros que um editor de alertas pode notificar) é acessível por um portador de **qualquer um** de `alerts:read` **ou** `alerts:write`, para que editores de alertas possam preencher o seletor sem precisar de `users:read`.
+
+> Um visualizador de dashboards precisa de **ambos** `dashboards:read` (para carregar as visualizações salvas) e `evaluations:read` (as métricas de saúde são calculadas a partir de dados de avaliação). Conceda `dashboards:write` para permitir que um usuário crie ou edite dashboards, e `dashboards:delete` para removê-los.
+
+> `/health` e `/auth/*` (solicitação de OTP, verificação de OTP, verificação de sessão, logout) são não autenticados por design; são o fluxo de login e a sonda de disponibilidade. `GET /access-granters` requer uma chave válida, mas nenhuma permissão específica, para que qualquer usuário logado possa ver quais admins contatar sobre alterações de acesso.
+
+---
+
+## Conjuntos de Permissões
+
+Os conjuntos de permissões permitem aplicar um papel nomeado em vez de selecionar tokens individuais manualmente toda vez. Em vez de selecionar uma dúzia de permissões uma a uma para cada novo usuário do dashboard ou API key, você escolhe um conjunto, e todos os atribuídos a ele carregam uma concessão consistente e revisável. Editar um conjunto personalizado reaplicará a nova concessão a todos os usuários já atribuídos a ele, portanto uma mudança de papel é uma única edição, e não uma varredura por todos os membros.
+
+Cada organização é inicializada com três conjuntos integrados:
+
+| Conjunto | Permissões | Destinado a |
+|---|---|---|
+| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Acesso somente leitura em todas as superfícies operacionais. |
+| `standard` | tudo em `read-only`, mais `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Somente leitura mais as ações cotidianas do plantão: executar consultas, reavaliar sessões, reconhecer incidentes e usar o assistente de IA. |
+| `admin` | todas as permissões atribuíveis | Controle total da organização. |
+
+Os três conjuntos integrados são **imutáveis**; seus nomes sempre significam a mesma coisa, portanto `read-only`, `standard` e `admin` são seguros para referenciar em políticas e onboarding. Um operador pode criar **conjuntos personalizados** adicionais para modelar papéis específicos da sua organização (por exemplo, um papel de "autor de dashboard" ou "somente coletor").
+
+Os conjuntos são exibidos no dashboard e gerenciados pela API em `GET /permission-sets` (listar, restrito a `users:read`) e `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (criar, editar, excluir um conjunto personalizado, restrito a `settings:write`). Excluir ou editar um conjunto integrado é recusado.
+
+A associação a conjuntos sustenta dois outros recursos:
+
+- **`DEFAULT_USER_PERMISSIONS`** (a concessão pré-selecionada quando um admin abre **+ novo usuário**) tem como padrão o conjunto `standard`.
+- **A flag `--set`** no `agenteye-orgctl` (gerenciamento de membros pelo operador) inicia um membro a partir de um conjunto nomeado, que você então ajusta com `--add` / `--remove`.
+
+> **Nota:** Quando um conjunto inclui uma permissão que não pode ser atribuída a chaves (por exemplo, um conjunto personalizado que carrega `keys:update`), ao gerar uma chave a partir desse conjunto, os tokens não atribuíveis são descartados; caso contrário, o servidor rejeitaria a chave com HTTP 422. Usuários do dashboard não estão sujeitos a essa restrição.
+
+---
+
+## Chave Admin Bootstrap
+
+A chave admin é a única credencial raiz que permite a um operador inicializar o acesso do zero: com ela você pode criar todas as outras chaves com escopo definido, convidar os primeiros usuários do dashboard e configurar a instância antes que qualquer outra chave exista. É a única chave que você não cria pela API de chaves; ela é provisionada a partir do ambiente para que o servidor seja acessível na primeira inicialização.
+
+Defina a variável de ambiente `ADMIN_KEY` no servidor. A cada inicialização, o servidor faz um upsert desse valor como uma chave admin com todas as permissões.
+
+Para rotacionar: altere `ADMIN_KEY` para um novo segredo e reinicie o servidor.
+
+---
+
+## Escopo por organização
+
+**As organizações em si são criadas e gerenciadas fora de banda por um operador, não por esta API de chaves.** O ciclo de vida de organizações e membros (criar / renomear / excluir / purgar uma organização; adicionar / atualizar / remover um membro) é feito com o CLI **`agenteye-orgctl`**; não há API HTTP nem botão no dashboard para isso. O que *não* muda: **as API keys por organização ainda são criadas no dashboard (ou via esta API de chaves)** por membros da organização.
+
+Em um deployment multi-organização, cada chave que um membro da organização cria (por esta API de chaves ou pela página **Keys** do dashboard) pertence a **uma organização** e só pode ler ou escrever os dados dessa organização; a organização é registrada na chave na criação e aplicada em cada requisição. As duas chaves bootstrap são a única exceção: a chave `admin` (gerada a partir de `ADMIN_KEY`) e a chave `dashboard-assistant` (gerada a partir de `AGENT_API_KEY`) têm **escopo de instância** (não carregam nenhuma organização). O dashboard se autentica com a chave `admin` para poder fazer proxy de requisições por organização em nome dos membros logados. Deployments de locatário único não precisam se preocupar com isso; todas as chaves pertencem à organização `default` integrada.
+
+---
+
+## Criando Chaves
+
+Use a chave admin (ou qualquer chave com permissão `keys:create`) para criar chaves com escopo adicional.
+
+### Chave de coletor (somente ingestão)
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "prod-collector",
+    "key": "your-collector-secret",
+    "permissions": ["events:add"]
+  }'
+```
+
+### Chave de dashboard (somente leitura)
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "dashboard",
+    "key": "your-dashboard-secret",
+    "permissions": ["events:read", "keys:read"]
+  }'
+```
+
+Ao criar uma chave pela API HTTP, você fornece o valor de `key` por conta própria; escolha um segredo forte e armazene-o com segurança. (O dashboard funciona de forma diferente: ele gera um segredo forte para você e o exibe uma única vez na criação; veja [Gerenciamento de Chaves no Dashboard](#key-management-in-the-dashboard).) A resposta confirma que a chave foi criada:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "prod-collector",
+  "permissions": ["events:add"],
+  "created_at": "2026-04-01T12:00:00Z"
+}
+```
+
+---
+
+## Listando Chaves
+
+```bash
+curl -s http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+Os segredos das chaves não são retornados nas respostas de listagem, apenas IDs, nomes e permissões.
+
+---
+
+## Desativando uma Chave
+
+Desativar revoga o acesso imediatamente sem excluir o registro da chave.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/disable \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+---
+
+## Regenerando uma Chave
+
+Gera um novo segredo para uma chave existente. O segredo antigo é invalidado imediatamente.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/regenerate \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+A resposta inclui o novo segredo em texto simples, **exibido apenas uma vez**.
+
+---
+
+## Gerenciamento de Chaves no Dashboard
+
+A página **Keys** no dashboard fornece uma interface para todas as operações acima. Você precisa de uma chave com permissão `keys:read` para visualizar a lista, e `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` para as ações de criar / editar / desativar / regenerar, respectivamente. Editar as permissões de uma chave (`keys:update`) é separado de criar uma (`keys:create`), portanto você pode conceder a um operador a capacidade de criar chaves sem a capacidade de reescopar as existentes, ou vice-versa. A chave admin cobre todas essas ações.
+
+Ao criar uma chave pelo dashboard, você não fornece o segredo; o dashboard gera um segredo forte para você e o exibe **uma única vez** na criação. Copie-o imediatamente e armazene-o com segurança; ele nunca será exibido novamente, exatamente como em uma regeneração. Você ainda pode escolher as permissões da chave diretamente ou gerá-las a partir de um conjunto de permissões (veja abaixo).
+
+![A página API Keys: um card por chave mostrando seu nome, permissões concedidas e horário de criação, com ações de regenerar e desativar; chaves protegidas como `admin` são marcadas](/agenteye/images/api-keys.png)
+
+---
+
+## Layout de Chaves Recomendado
+
+| Chave | Permissões | Usada por |
+|---|---|---|
+| `admin` (bootstrap via variável de ambiente `ADMIN_KEY`) | todas | Ops/configuração, e o dashboard (autentica com `ADMIN_KEY`, faz proxy de requisições de usuários com verificações de permissão) |
+| Chave de coletor por host | `events:add` | Coletor em cada máquina de agente |
+| `dashboard-assistant` (bootstrap via variável de ambiente `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Assistente de IA, gerado automaticamente, **protegido**; não pode ser editado pela API |
+| Chave de telemetria do assistente (opcional) | `events:add` | Auto-instrumentação do assistente de IA, se habilitada |
+
+> **Nota:** A chave do assistente é **gerada automaticamente** pelo servidor a partir da variável de ambiente `AGENT_API_KEY` (o mesmo segredo que o agente apresenta como `AGENTEYE_API_KEY`); não há etapa manual de criação de chave nem envolvimento da chave admin. Suas permissões são fixadas no código-fonte para que o escopo não possa ser ampliado por má configuração: leitura de eventos / avaliações / dashboards, mais gravação de dashboards e leitura / gravação / execução de consultas para o fluxo de criação de "Pedir à IA para escrever uma consulta". Todo o SQL ainda passa pelo mesmo papel somente leitura e caminho SQL protegido que uma consulta escrita pelo usuário, portanto isso amplia a *superfície de criação*, não a superfície de dados; operações destrutivas (`queries:delete`, `dashboards:delete`) são deliberadamente mantidas fora da chave do assistente. Assim como a chave `admin`, ela é **protegida**: não pode ser desativada ou regenerada pela API de chaves, apenas rotacionada alterando `AGENT_API_KEY` e reiniciando. Os *usuários* do dashboard também precisam da permissão `agent:use` para ver e usar o assistente. Se você habilitar a auto-instrumentação, dê ao assistente uma chave separada somente com `events:add`.
+
+---
+
+## Notas de atualização e compatibilidade retroativa
+
+Você só precisa disso se estiver atualizando uma instância existente; novos deployments podem pular esta seção.
+
+> Quando Auditorias foi lançado, os beneficiários existentes tiveram seus escopos ampliados seguindo os mesmos formatos de papel que os alertas: todo usuário e conjunto de permissões que possuía `alerts:read` ganhou `audits:read`, e todo portador de `alerts:write` ganhou `audits:write`. As API keys existentes **não** foram ampliadas. Conceda `audits:*` a uma chave explicitamente se ela precisar da superfície de auditoria.
+
+> Concessões armazenadas do token legado `alerts:ack` são interpretadas como `incidents:ack` para que os plantões mantenham o acesso sem precisar criar novas chaves. O token não é mais atribuível pelo editor de usuários do dashboard; a matriz oferece `incidents:ack` em seu lugar.
+
+---
+
+## Próximos passos
+
+- [Python SDK](/pt-br/agenteye/python-sdk): como o código do seu agente se autentica ao enviar eventos.
+- [Segurança](/pt-br/agenteye/security): como funcionam o login, o controle de acesso e o isolamento de dados por organização.

package/.next/standalone/docs-old/pt-br/agenteye/assistant.mdx

@@ -0,0 +1,63 @@
+---
+title: "Assistente de IA"
+description: "Faça uma pergunta em português simples sobre os dados do seu agente e receba uma resposta com links diretos para as evidências."
+---
+
+
+Faça uma pergunta em linguagem natural sobre os dados do seu agente e receba uma resposta com links diretos para as evidências. Sem SQL para escrever, sem dashboards para vasculhar — o assistente do **Failproof AI Observability** é a forma mais rápida de qualquer pessoa da sua equipe obter respostas sobre seus agentes.
+
+![O assistente do Failproof AI Observability respondendo uma pergunta em linguagem natural dentro do dashboard, exibindo uma tabela de Atividade de Agentes ao vivo, um detalhamento de uso de modelos por agente e conclusões por escrito, com as consultas executadas mostradas inline](/agenteye/images/assistant.png)
+*Pergunte em linguagem natural e receba uma resposta construída a partir dos seus próprios dados. Aqui, ele detalha quais agentes estão mais ocupados e quais modelos utilizam, e mostra as consultas executadas para que você possa verificar cada número.*
+
+Não há nada para aprender. Abra o chat, digite o que você quer saber e siga os links que ele retorna:
+
+```
+Você:  quais sessões tiveram erro hoje?
+IA:    5 sessões tiveram erros hoje, das mais recentes para as mais antigas. Cada uma tem um link:
+      • checkout-agent   14:02   timeout de ferramenta
+      • billing-agent    11:47   erro não tratado
+      • ...e mais 3
+
+Você:  resuma esta sessão          (perguntado enquanto visualizava uma execução)
+IA:    Esta execução teve 12 etapas em 3 ferramentas e falhou perto do fim quando uma
+      ferramenta de pagamento retornou um erro. Ela teve uma pontuação baixa na sua avaliação "resolved".
+      Links: a sessão, o evento que falhou e essa avaliação.
+```
+
+## Pergunte e vá direto para a prova
+
+Você para de adivinhar e para de escrever consultas. Pergunte "como está a qualidade em produção esta semana?", "quais sessões tiveram erro hoje?" ou "resuma esta sessão", e você obtém uma resposta direta em segundos — sem precisar montar uma consulta e interpretá-la por conta própria.
+
+Cada resposta vem acompanhada de suas fontes. O assistente linka as sessões exatas, as consultas salvas e os dashboards que usou para chegar à resposta, para que você possa clicar e confirmar em vez de simplesmente confiar na palavra dele. Ele também é **consciente da página**: pergunte sobre "esta sessão" enquanto estiver visualizando uma e ele já sabe a qual execução você se refere. Reabra qualquer conversa anterior pelo seletor de histórico e continue de onde parou.
+
+## Transforme uma boa resposta em consulta salva ou dashboard
+
+Quando uma resposta vale a pena guardar, peça ao assistente para salvá-la. Ele elabora o SQL para uma consulta salva ou monta um dashboard a partir dessas consultas e, em seguida, exibe um card de **Aprovar / Rejeitar**. Nada é gravado até você clicar em Aprovar, então você tem a agilidade do "é só perguntar" com a palavra final sempre sendo sua.
+
+Na página de **Queries**, ele vai além e assume o papel de autor de SQL: descreva a consulta que você quer ("mostrar taxa de erros por agente nos últimos 7 dias") e ele transmite o SQL diretamente para o editor, abrindo uma visualização de diff para que você possa **Aceitar** ou **Rejeitar** a alteração antes que ela seja aplicada.
+
+![A página de Queries do Observability e seu editor de SQL](/agenteye/images/query-lab.png)
+*A página de Queries: é neste editor que o assistente transmite um rascunho de consulta, somente leitura, para você aceitar ou rejeitar.*
+
+Criar SQL por meio de perguntas aqui usa a permissão `queries:run`, a mesma por trás do botão **Run** do editor. O chat em todos os outros lugares requer `agent:use`.
+
+## Seguro para toda a equipe
+
+Você pode abrir o assistente para todos sem se preocupar com o que ele pode acessar:
+
+- **Ele lê apenas o que você já pode ver.** As respostas são limitadas às suas próprias permissões de leitura, portanto ele nunca amplia sua superfície de dados.
+- **Toda escrita aguarda sua aprovação.** Consultas salvas e dashboards só são criados após seu clique explícito em Aprovar, e não há nenhuma configuração que desative essa barreira.
+- **Ele nunca pode excluir nada.** Nenhuma ferramenta de exclusão está exposta e o assistente não possui permissão de exclusão. As exclusões permanecem em suas mãos, no dashboard.
+- **Ele fica dentro da sua organização.** O assistente só visualiza a organização que você está acessando no momento.
+- **Suas perguntas são suas.** Prompts e respostas ficam armazenados no seu próprio banco de dados do Observability; a análise de produto registra apenas metadados de uso, nunca o texto dos seus prompts.
+
+## Onde encontrá-lo
+
+O assistente acompanha a borda direita de cada página dentro da sua organização (`/<org-slug>/...`). Clique na barra lateral ou pressione `⌘J` / `Ctrl+J` para expandi-lo no painel de chat completo; arraste sua borda para redimensionar — a largura escolhida é lembrada entre recarregamentos. Você precisa da permissão **`agent:use`** para utilizá-lo; caso contrário, a barra estará desativada. Se ele ainda não foi ativado na sua instalação (é necessária uma conexão com um LLM), você verá uma barra silenciosa no lugar de um chat funcional.
+
+## Relacionados
+
+- [CLI e agentes](/pt-br/agenteye/cli-and-agents)
+- [Queries](/pt-br/agenteye/queries)
+- [Dashboards](/pt-br/agenteye/dashboards)
+- [Suite de avaliação](/pt-br/agenteye/evaluation-suite)

package/.next/standalone/docs-old/pt-br/agenteye/audits.mdx

@@ -0,0 +1,54 @@
+---
+title: "Auditorias: seu analista de confiabilidade automático"
+description: "O Failproof AI Observability vai atrás das falhas para as quais você nunca criou uma regra e entrega uma lista de tarefas priorizadas, com evidências, mostrando exatamente o que corrigir."
+---
+
+
+O Failproof AI Observability vai atrás das falhas para as quais você nunca criou uma regra e entrega uma lista de tarefas priorizadas, com evidências, mostrando exatamente o que corrigir. É como ter um analista vasculhando seus logs toda noite e deixando o resumo na sua mesa de manhã.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/C5nHKGQIqZQ?autoplay=1&mute=1&loop=1&playlist=C5nHKGQIqZQ&rel=0&playsinline=1" title="Assista: Encontre automaticamente onde seu agente está falhando (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Um tour de dois minutos: de uma execução agendada a uma correção que você pode tomar como ação.*
+
+![A página de Auditorias: jobs recorrentes que analisam suas sessões em busca de padrões de falha, cada um com um cronograma e sensibilidade](/agenteye/images/audits.png)
+*Cada auditoria é um job recorrente que minera suas sessões e gera recomendações priorizadas com base em evidências.*
+
+## Pare de adivinhar o que corrigir a seguir
+
+Alertas detectam os problemas que você já sabe monitorar. Auditorias detectam os que você não sabe. Em um cronograma que você define, uma auditoria percorre todas as suas sessões de agente e caça os padrões que valem a pena corrigir — para que você gaste seu tempo agindo sobre os achados em vez de rolar logs esperando encontrá-los sozinho.
+
+Uma única execução vai atrás dos modos de falha que realmente quebram agentes em produção:
+
+- **Clusters de erros**: a mesma falha se repetindo com uma causa raiz comum.
+- **Desvio em relação a uma linha de base**: comportamento deslizando silenciosamente para fora de uma janela conhecida como boa.
+- **Falha de objetivo em transcrições**: execuções que tecnicamente terminaram, mas nunca cumpriram o objetivo.
+- **Uso incorreto de ferramentas**: a ferramenta errada, argumentos inválidos ou loops que desperdiçam chamadas.
+- **Trade-offs de qualidade e custo**: onde você está pagando caro por uma saída que poderia obter mais barato.
+- **Lacunas de cobertura**: comportamento que nenhuma avaliação ou alerta está monitorando.
+
+Você decide com que intensidade a auditoria analisa usando uma única configuração de **sensibilidade** (baixa, média ou alta), para que um agente barulhento de staging e um de produção mais restrito possam ser ajustados ao sinal que você deseja.
+
+## Cada recomendação vem com evidências
+
+Você nunca precisa aceitar um achado por fé. Cada recomendação cita as sessões exatas de onde veio e o SQL que a trouxe à tona, para que você possa abrir as evidências e confirmar o problema com um clique em vez de ter que reverter uma afirmação.
+
+Quando um achado é sobre uma credencial vazada, ele vai um passo além e vincula os eventos individuais que corresponderam. Clique em um e você cai naquele momento exato da sessão, já selecionado — não no topo de uma longa transcrição para rolar. O link nomeia o evento; ele nunca copia o segredo detectado para o achado, então ler um achado não é um segundo lugar onde sua credencial está escrita. Se um evento não estiver mais lá porque a sessão passou da sua janela de retenção, a página informa isso claramente em vez de deixá-lo se perguntando se clicou na coisa errada.
+
+É também o que mantém as auditorias honestas. O servidor verifica se cada sessão citada realmente existe e **descarta qualquer recomendação cujas evidências não se sustentem**, então a auditoria investiga, mas nunca inventa. O que aparece na sua lista é real, reproduzível e classificado por importância, com os maiores ganhos no topo.
+
+## Transforme uma correção em uma proteção
+
+Corrigir um problema é apenas metade da vitória. A outra metade é garantir que ele não volte silenciosamente. Cada achado traz um **atalho de um clique que cria um rascunho de alerta de recorrência**, pré-preenchido com um gatilho inicial razoável que você pode ajustar. Feche o achado, ative o alerta e, na próxima vez que esse padrão aparecer, você será notificado em vez de redescobri-lo em uma auditoria futura.
+
+## Onde encontrar
+
+As auditorias ficam no dashboard em **`/<org-slug>/audits`** (barra lateral em *analyze* > *audits*). Visualizar execuções e achados requer **`audits:read`**; criar, editar e triar auditorias requer **`audits:write`**. Defina o escopo e a cadência de uma auditoria e clique em **Run now** sempre que quiser resultados imediatamente em vez de esperar pela próxima execução agendada.
+
+## Relacionados
+
+- [Alertas](/pt-br/agenteye/alerts): seja notificado no momento em que um limite que você já conhece for ultrapassado.
+- [Avaliações](/pt-br/agenteye/evaluations): pontue cada execução para que regressões de qualidade apareçam por conta própria.
+- [Rastreamento de erros](/pt-br/agenteye/error-tracking): agrupe e acompanhe os erros que seus agentes lançam.
+- [Incidentes](/pt-br/agenteye/incidents): acompanhe um problema encontrado por uma auditoria até a sua correção.

package/.next/standalone/docs-old/pt-br/agenteye/cli-and-agents.mdx

@@ -0,0 +1,80 @@
+---
+title: "CLI"
+description: "Todo o seu deployment de Observabilidade do Failproof AI a um comando de distância."
+---
+
+
+Todo o seu deployment de Observabilidade do Failproof AI a um comando de distância. Verifique produção, gere uma chave de API ou reconheça um incidente sem sair do terminal — e ainda automatize tudo isso em CI, ou deixe um agente de código fazer por você em linguagem natural.
+
+```bash
+pipx install agenteye
+agenteye login --email você@exemplo.com      # um código de 6 dígitos chega na sua caixa de entrada
+agenteye --json sessions --since 24h         # todas as execuções de agentes das últimas 24h, mais recentes primeiro
+```
+
+*O CLI `agenteye` se comunica com o seu dashboard. É uma ferramenta diferente do coletor, que envia eventos para o servidor.*
+
+## Todo o seu deployment, a um comando de distância
+
+Pare de alternar entre abas para responder uma pergunta rápida. O CLI `agenteye` lê seus dados e administra sua organização a partir de um único binário, então uma verificação que antes exigia clicar pelo dashboard vira uma linha que você pode reexecutar, criar um alias ou colar em um runbook. Você tem quatro superfícies:
+
+- **Leia seus dados:** `sessions`, `events`, `evals` e `errors`, filtrados por tempo, agente e ambiente.
+- **Gerencie sua organização:** `keys`, `users`, `settings`, `alerts` e `incidents`.
+- **Execute análises:** SQL salvo mais um executor `query` ad-hoc sobre seus dados de eventos.
+- **Consulte o assistente:** `agent ask` acessa o mesmo analista somente leitura com quem você conversa no dashboard.
+
+Instale uma vez com `pipx`, faça login com um código de 6 dígitos enviado por e-mail e está pronto. A sessão dura cerca de um dia; reexecute `agenteye login` quando expirar. Use-o para verificar produção, provisionar uma chave ou triagear um incidente ativo — tudo sem abrir um navegador:
+
+```bash
+agenteye errors --since 24h --aggregate      # o que está quebrando, agrupado por tipo de erro
+agenteye incidents list --state firing       # o que está pegando fogo agora
+agenteye keys create ci --add events:add     # uma chave que só pode enviar eventos, secret exibido uma vez
+```
+
+Um hábito importante: opções globais como `--json` vão antes do comando. `agenteye --json sessions` está correto; `agenteye sessions --json` não está.
+
+## Automatize, integre ao CI
+
+Todo comando aceita `--json`, e isso muda tudo. JSON limpo vai para stdout enquanto status e avisos para humanos vão para stderr, então uma captura com `--json` vai direto para o `jq` sem nenhuma linha extra para remover. É isso que torna o CLI igualmente útil para você no terminal e para um agente de código analisando a saída:
+
+```bash
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+```
+
+Ele foi construído para rodar de forma não supervisionada. Prompts de confirmação são ignorados automaticamente quando não há terminal conectado, então nada trava em um pipeline, e todo comando retorna um código de saída significativo: `0` sucesso, `4` não autenticado, `5` sem permissão (a mensagem nomeia qual, por exemplo `alerts:write`), `3` dashboard inacessível. Um script pode ramificar em um `4` para reautenticar ou em um `5` para dizer exatamente o que pedir a um administrador, em vez de falhar silenciosamente.
+
+## Deixe um agente de código conduzir em linguagem natural
+
+Ainda melhor: você não deveria precisar lembrar nenhuma dessas flags. A **CLI skill** é uma pequena pasta Agent Skill chamada `agenteye-cli` que ensina um agente de código como Claude Code ou Codex a conduzir o CLI a partir de pedidos em linguagem natural. Pergunte "tem algo quebrado hoje?" e o agente escolhe o comando, executa como você e responde em prosa.
+
+Para Claude Code, coloque a pasta `agenteye-cli` em `~/.claude/skills/` e ela é descoberta automaticamente. O Failproof AI Observability fornece a pasta; não há nada extra para instalar, pois ela apenas conduz o CLI que você já instalou. Faça login você mesmo primeiro: a skill não consegue completar o login por código enviado por e-mail por você.
+
+Como o agente executa o CLI como você, ele pode fazer tudo que seu login permite, tanto leituras quanto escritas: criar chaves, alterar configurações, resolver incidentes. O prompt "tem certeza?" do CLI não é acionado para um agente, então a skill foi escrita para declarar o comando exato e aguardar sua aprovação antes de qualquer alteração. Você é a etapa de confirmação.
+
+```text
+você   Por que a sessão run-001 falhou?
+
+agente Executando: agenteye --json events --session-id run-001 --all
+       O checkout-agent encontrou um TimeoutError em sua terceira chamada de ferramenta.
+```
+
+Leituras são instantâneas, e toda escrita pausa para você:
+
+```text
+você   Dê ao CI uma chave que só possa enviar eventos.
+
+agente Isso cria uma chave de API. Vou executar:
+         agenteye keys create ci --add events:add
+       Pode prosseguir?
+
+você   sim
+
+agente Feito. Chave "ci" criada com events:add apenas. O secret é exibido uma vez, então guarde agora.
+```
+
+## Relacionado
+
+- [Referência do CLI](/pt-br/agenteye/cli): todos os comandos, flags e formatos JSON.
+- [Receitas de CLI para agentes](/pt-br/agenteye/cli-recipes): padrões `jq` para copiar e colar e tratamento de códigos de saída.
+- [CLI agent skill](/pt-br/agenteye/cli-skill): instale e execute a skill `agenteye-cli`.
+- [Assistente de IA](/pt-br/agenteye/assistant): o analista no dashboard com quem `agent ask` se comunica.