failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/es/agenteye/alerts.mdx

@@ -0,0 +1,63 @@
+---
+title: "Alertas"
+description: "Entérate en el momento en que algo cruza tu línea, en el canal que tu equipo ya monitorea, en lugar de que te lo diga un cliente."
+---
+
+
+Entérate en el momento en que algo cruza tu línea, en el canal que tu equipo ya monitorea, en lugar de que te lo diga un cliente. Define una regla una vez y Failproof AI Observability la evalúa según un calendario, notificándote por email, Slack, webhook o directamente en el dashboard.
+
+![La página de Alertas: una cuadrícula de tarjetas de reglas de alerta, cada una con su disparador, ventana de evaluación, canales y una insignia de severidad informativa, de advertencia o crítica](/agenteye/images/alerts.png)
+*Todas las reglas de alerta de un vistazo: qué monitorea, con qué frecuencia, dónde notifica y qué tan urgente es.*
+
+## Entérate de los problemas antes que tus usuarios
+
+Deja de actualizar un dashboard esperando detectar una regresión. Configura una alerta cada vez que haya una señal que quieras conocer incluso cuando nadie esté mirando, y recíbela donde ya estás:
+
+- **Email**, para quienes deban saberlo.
+- **Slack**, un mensaje enriquecido con un botón que lleva directamente al incidente.
+- **Webhook**, un POST JSON para PagerDuty, Opsgenie o tu propio endpoint, con una firma opcional para que el receptor pueda verificar su origen.
+- **En el dashboard**, silencioso por diseño, para cuando estés ajustando una regla y aún no quieras notificar a nadie.
+
+Combina cualquier cantidad de canales en una sola regla, y su severidad (informativa, de advertencia o crítica) viaja junto con ella para que las urgentes luzcan urgentes.
+
+## Crea la regla en un formulario, no en JSON
+
+Describes lo que significa "roto" en un formulario y Failproof AI Observability escribe la regla subyacente por ti. La especificación JSON es simplemente lo que produce ese formulario internamente, así que puedes leerla para entender una regla, pero rara vez necesitarás escribirla.
+
+![El formulario de nueva alerta: nombre y descripción, un interruptor de activación y un selector de disparador que ofrece umbral de métrica, SQL personalizado, puntuación de evaluación, evaluación compuesta y condiciones por evento](/agenteye/images/alert-new.png)
+*Elige un disparador y el formulario muestra los campos correctos; Guardar escribe la regla.*
+
+El flujo principal es rápido: nómbrala, elige un **disparador** (qué monitorear), define el **umbral y la ventana** (qué tan grave, durante cuánto tiempo), adjunta al menos un **canal**, luego **Guarda** y haz clic en **Probar** para enviar una notificación sintética y confirmar que todos los destinos están correctamente configurados. Internamente, eso produce una pequeña especificación como esta:
+
+```json
+{ "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 }
+```
+
+No estás limitado a un solo tipo de señal. Elige el disparador que se adapte a cómo piensas sobre el fallo:
+
+| Disparador | Se activa cuando |
+|---|---|
+| **Umbral de métrica** | una métrica predefinida (tasa de errores, latencia p95 o p99, conteos de eventos o errores, gasto en tokens) cruza tu línea durante una ventana de tiempo |
+| **SQL personalizado** | tu propia consulta de solo lectura devuelve una fila, o un valor calculado cruza un umbral |
+| **Puntuación de evaluación** | el promedio de la puntuación de un evaluador (por ejemplo, alucinaciones) cruza un umbral |
+| **Evaluación compuesta** | varias verificaciones de puntuación se combinan con lógica any, all o al-menos-N para detectar una regresión que solo se manifiesta entre múltiples puntuaciones |
+| **Por evento** | llega un único evento coincidente: un agente específico, un tipo de error específico o una subcadena de mensaje |
+
+¿Ya estás mirando un fallo en la [página de Errores](/es/agenteye/error-tracking)? Cada fila tiene un botón **+ alerta** que abre este mismo formulario prellenado para detectar exactamente ese fallo en el futuro, de modo que el incidente que acabas de atender sea el que te notifique la próxima vez.
+
+**Dónde encontrarlo:** Las Alertas están en `/<org-slug>/alerts`. Para crear, editar, eliminar y probar reglas se necesita **`alerts:write`**; con `alerts:read` es suficiente para consultar. El selector de destinatarios lista a los miembros de tu organización por nombre, así que puedes notificar a una persona sin salir del formulario.
+
+## Notifícame solo cuando sea real
+
+Una medición errónea no debería despertarte. El filtro de ruido **M de N** controla cuántas de las últimas verificaciones deben fallar antes de que la alerta te notifique realmente. Configúralo en **3 de 5** y la regla se activa solo después de que haya superado el umbral en tres de sus últimas cinco verificaciones, de modo que una señal inestable deje de dar falsas alarmas; déjalo en el valor predeterminado **1 de 1** para que se active en la primera infracción. También eliges con qué frecuencia se ejecuta la regla, a partir de intervalos predefinidos de 1m, 5m, 15m y 1h, ajustados a la velocidad real con que se mueve la señal.
+
+## Qué ocurre cuando se activa una alerta
+
+Una infracción abre un **incidente** y notifica a tus canales una sola vez. A partir de ahí, tu equipo lo reconoce, asigna un responsable, lo discute y lo resuelve, todo con un registro limpio y atribuido. Ese flujo de trabajo de triaje tiene su propio espacio: consulta [Incidentes](/es/agenteye/incidents).
+
+## Relacionado
+
+- [Incidentes](/es/agenteye/incidents): sigue una alerta activa desde abierta hasta reconocida y resuelta.
+- [Seguimiento de errores](/es/agenteye/error-tracking): agrupa fallos de agentes y conviértelos en una alerta con un clic.
+- [Dashboards](/es/agenteye/dashboards): monitorea los paneles compartidos de los que provienen los umbrales que alertas.
+- [CLI y agentes](/es/agenteye/cli-and-agents): crea alertas y confirma incidentes desde tu terminal, o incorpóralos a scripts de CI.

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

@@ -0,0 +1,280 @@
+---
+title: "API Keys"
+description: "Las API keys controlan quién y qué puede acceder a tu servidor de Observabilidad de Failproof AI, de modo que un collector pueda enviar eventos sin obtener permisos de lectura ni de administración."
+---
+
+
+Las API keys controlan quién y qué puede acceder a tu servidor de Observabilidad de Failproof AI, de modo que un collector pueda enviar eventos sin obtener permisos de lectura ni de administración. Cada clave lleva uno o más permisos, y cada permiso protege rutas específicas del servidor; solo otorgas los que un trabajo necesita. La mayoría de los despliegues crean únicamente tres tipos de clave.
+
+## Las 3 claves que necesitan la mayoría de los despliegues
+
+| Clave | Permisos | Quién la usa |
+|---|---|---|
+| Clave de collector | `events:add` | El `agenteye-collector` en cada máquina agente, para enviar eventos. |
+| Clave de lectura del dashboard | `events:read`, `keys:read` | Un operador o integración de solo lectura que consulta datos sin modificarlos. |
+| Clave admin de bootstrap | todos los permisos | El operador que levanta la instancia por primera vez (junto con el dashboard). Se inicializa desde la variable de entorno `ADMIN_KEY`. Ver [Clave admin de bootstrap](#bootstrap-admin-key). |
+
+Empieza aquí. Consulta el catálogo completo de permisos a continuación solo cuando necesites una clave con un ámbito más estrecho y personalizado. Ver también [Distribución recomendada de claves](#recommended-key-layout) y [Crear claves](#creating-keys).
+
+---
+
+## Permisos
+
+El servidor aplica un catálogo fijo de permisos; cada uno protege rutas HTTP específicas. Una **clave admin** los tiene todos; una clave con ámbito tiene el subconjunto que otorgues al crearla. Las cadenas de permisos desconocidas son rechazadas al crear una clave.
+
+> **Nota:** Dos permisos válidos son exclusivos para humanos/dashboard y no pueden asignarse a una API key: `orgs:admin` (administración de la instancia, exclusiva para operadores) y `keys:update`. Una solicitud a `POST /keys` o `PATCH /keys/:id` que intente otorgar cualquiera de los dos es rechazada con HTTP 422. Consulta la fila `keys:update` a continuación para entender por qué una clave bearer puede crear claves pero nunca editarlas.
+
+### Ingesta y consulta de eventos
+
+| Permiso | Rutas HTTP | Qué permite |
+|---|---|---|
+| `events:add` | `POST /events` | Ingestar lotes de eventos desde un collector. Es el único permiso que necesita un collector. |
+| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Consultar eventos, listar los entornos conocidos, listar los identificadores de modelos encontrados en los datos (usados por la vista de Modelos y los filtros de modelos), calcular el agregado de latencia que alimenta el mapa de calor / banda de percentiles, y exportar una sesión como JSONL. Los endpoints de facetas de la barra de filtros compartida `GET /events/environments` y `GET /events/agent_ids` son accesibles con **`events:read`** **o** `evaluations:read`, de modo que la página de sesiones (protegida por `evaluations:read`) reutiliza la misma faceta por organización. `GET /events/models` no es uno de ellos: requiere `events:read`, por lo que un principal que solo tenga `evaluations:read` recibirá un 403. |
+
+### Sesiones y evaluaciones
+
+| Permiso | Rutas HTTP | Qué permite |
+|---|---|---|
+| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Listar sesiones, leer resultados de evaluaciones, el estado de salud resumido de evaluaciones usado por los dashboards, y el estado de la cola de trabajos de evaluación. |
+| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Encolar manualmente una reevaluación para una sesión finalizada. |
+
+### Dashboards
+
+| Permiso | Rutas HTTP | Qué permite |
+|---|---|---|
+| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Listar dashboards, cargar uno y leer sus 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` | Crear y editar dashboards, agregar / editar / eliminar tiles, y reorganizar la cuadrícula de tiles. |
+| `dashboards:delete` | `DELETE /dashboards/:id` | Eliminar un dashboard completo (la eliminación a nivel de tile corresponde a `dashboards:write`). |
+
+### Consultas guardadas (compositor SQL)
+
+| Permiso | Rutas HTTP | Qué permite |
+|---|---|---|
+| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Listar consultas guardadas, cargar una e inspeccionar el esquema de solo lectura al que apunta el compositor. |
+| `queries:write` | `POST /queries`, `PUT /queries/:id` | Crear y editar consultas guardadas. El SQL se enruta a través del mismo rol de solo lectura y las mismas verificaciones de SQL protegido que una llamada `queries:run`. |
+| `queries:delete` | `DELETE /queries/:id` | Eliminar una consulta guardada. |
+| `queries:run` | `POST /queries/run` | Ejecutar SQL guardado o ad-hoc contra el rol de solo lectura utilizado por el compositor. |
+
+### Asistente de IA
+
+| Permiso | Rutas HTTP | Qué 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` | Interactuar con el asistente de IA y gestionar tus propias conversaciones (privadas). Requerido en el **usuario** para ver el panel del asistente; la clave propia del asistente es `dashboard-assistant` y se inicializa por separado (ver más abajo). |
+
+### API keys
+
+| Permiso | Rutas HTTP | Qué permite |
+|---|---|---|
+| `keys:create` | `POST /keys` | Crear una nueva API key con ámbito. **No** otorga la capacidad de editar los permisos de una clave existente (eso es `keys:update`). |
+| `keys:read` | `GET /keys` | Listar las claves existentes. Los secretos nunca son devueltos por este endpoint. |
+| `keys:update` | `PATCH /keys/:id` | Editar los permisos de una clave existente. Permiso **exclusivo para humanos/dashboard**; no puede asignarse a una API key (una clave bearer puede crear claves pero nunca editarlas). |
+| `keys:disable` | `POST /keys/:id/disable` | Revocar una clave. Las claves protegidas (`admin`, `dashboard-assistant`) no pueden deshabilitarse; rótalas mediante la variable de entorno y un reinicio. |
+| `keys:regenerate` | `POST /keys/:id/regenerate` | Rotar el secreto de una clave. Las claves protegidas no pueden regenerarse mediante esta ruta. |
+
+### Usuarios del dashboard
+
+| Permiso | Rutas HTTP | Qué permite |
+|---|---|---|
+| `users:create` | `POST /users`, `GET /users/defaults` | Invitar a un nuevo usuario del dashboard (emite un correo electrónico + inicio de sesión con código de un solo uso (OTP)) y leer el conjunto de permisos predeterminado configurado en el dashboard utilizado para prellenar el formulario de invitación. |
+| `users:read` | `GET /users`, `GET /users/:id` | Listar usuarios y cargar el registro de un usuario individual. |
+| `users:update` | `PUT /users/:id` | Editar los permisos de un usuario. Las actualizaciones envían un correo de cambio de permisos al usuario afectado y surten efecto en su siguiente solicitud; no requieren volver a iniciar sesión. |
+| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Deshabilitar un usuario (revoca sus sesiones de inmediato) y rehabilitar a un usuario previamente deshabilitado. |
+
+Estos permisos respaldan la página **Users** del dashboard, donde los ámbitos otorgados a cada miembro se muestran como chips:
+
+![La página Users: una tarjeta por usuario del dashboard con su email, permisos otorgados y controles de edición/deshabilitación](/agenteye/images/users.png)
+
+### Configuración operacional
+
+| Permiso | Rutas HTTP | Qué permite |
+|---|---|---|
+| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Ver la configuración operacional gestionada por el dashboard y sus metadatos; listar las anulaciones de ventana de contexto por modelo; y resolver la ventana efectiva para un modelo. |
+| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Editar la configuración operacional y agregar, cambiar o eliminar anulaciones de ventana de contexto por modelo. Los cambios afectan a los nuevos eventos sin necesidad de reiniciar el servidor. |
+
+![La página Settings: configuración operacional gestionada por el dashboard, como los inicios de sesión permitidos y los tiempos de vida de sesión/OTP, editable sin reiniciar](/agenteye/images/settings.png)
+
+### Alertas e incidentes
+
+| Permiso | Rutas HTTP | Qué permite |
+|---|---|---|
+| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Ver las definiciones de alertas configuradas. |
+| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Crear, editar, eliminar y disparar alertas de prueba. |
+| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Ver incidentes y su historial de triaje. |
+| `incidents:write` | `POST /alerts/:id/incidents` | Abrir un incidente manualmente contra una 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` | Reconocer, asignar, resolver y comentar incidentes. |
+
+### Auditorías
+
+| Permiso | Rutas HTTP | Qué permite |
+|---|---|---|
+| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Ver definiciones de auditorías, historial de ejecuciones y hallazgos. |
+| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Crear, editar, eliminar y ejecutar auditorías; triar hallazgos (reconocer / silenciar / descartar / resolver / reabrir / asignar). |
+
+> **Nota:** Para dar a una clave acceso a la superficie de auditorías, otórgale `audits:*` explícitamente. Ver [Notas de actualización y compatibilidad con versiones anteriores](#upgrade-and-backward-compatibility-notes) para saber cómo se migraron los titulares existentes cuando se lanzó Audits.
+
+> El endpoint del selector de destinatarios `GET /alerts/recipients` (que lista los emails de los miembros a los que puede notificar un editor de alertas) es accesible por un titular de **`alerts:read`** **o** `alerts:write`, de modo que los editores de alertas pueden llenar el selector sin necesitar `users:read`.
+
+> Un visualizador de dashboards necesita **tanto** `dashboards:read` (para cargar las vistas guardadas) como `evaluations:read` (las métricas de salud se calculan a partir de datos de evaluaciones). Otorga `dashboards:write` para que un usuario pueda crear o editar dashboards, y `dashboards:delete` para eliminarlos.
+
+> `/health` y `/auth/*` (solicitud OTP, verificación OTP, comprobación de sesión, cierre de sesión) no requieren autenticación por diseño; forman el flujo de inicio de sesión y la sonda de disponibilidad. `GET /access-granters` requiere una clave válida pero ningún permiso específico, por lo que cualquier usuario conectado puede ver qué administradores contactar sobre cambios de acceso.
+
+---
+
+## Conjuntos de permisos
+
+Los conjuntos de permisos te permiten aplicar un rol con nombre en lugar de seleccionar tokens individuales cada vez. En vez de elegir una docena de permisos uno por uno para cada nuevo usuario del dashboard o API key, eliges un conjunto, y todos los asignados a él llevan un otorgamiento consistente y revisable. Editar un conjunto personalizado vuelve a aplicar el nuevo otorgamiento a todos los usuarios ya asignados a él, de modo que un cambio de rol es una sola edición en lugar de recorrer cada miembro.
+
+Cada organización se inicializa con tres conjuntos integrados:
+
+| Conjunto | Permisos | Para quién |
+|---|---|---|
+| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Acceso de solo lectura en toda la superficie operacional. |
+| `standard` | todo lo de `read-only`, más `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Solo lectura más las acciones cotidianas del operador de guardia: ejecutar consultas, reevaluar sesiones, reconocer incidentes y usar el asistente de IA. |
+| `admin` | todos los permisos asignables | Control total de la organización. |
+
+Los tres conjuntos integrados son **inmutables**; sus nombres siempre significan lo mismo, por lo que `read-only`, `standard` y `admin` son seguros para referenciar en políticas e incorporaciones. Un operador puede crear **conjuntos personalizados** adicionales para modelar roles específicos de su organización (por ejemplo, un rol de "autor de dashboard" o un rol de "solo collector").
+
+Los conjuntos están disponibles en el dashboard y se gestionan a través de la API en `GET /permission-sets` (listar, protegido por `users:read`) y `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (crear, editar, eliminar un conjunto personalizado, protegido por `settings:write`). Eliminar o editar un conjunto integrado está prohibido.
+
+La pertenencia a conjuntos respalda otras dos funcionalidades:
+
+- **`DEFAULT_USER_PERMISSIONS`** (el otorgamiento preseleccionado cuando un admin abre **+ nuevo usuario**) usa como valor predeterminado el conjunto `standard`.
+- **El flag `--set`** en `agenteye-orgctl` (gestión de miembros por el operador) inicia un miembro desde un conjunto con nombre, que luego puedes ajustar con `--add` / `--remove`.
+
+> **Nota:** Cuando un conjunto incluye un permiso que no se puede asignar a claves (por ejemplo, un conjunto personalizado que lleva `keys:update`), inicializar una clave desde ese conjunto descarta los tokens no asignables; de lo contrario el servidor rechazaría la clave con HTTP 422. Los usuarios del dashboard no están sujetos a esa restricción.
+
+---
+
+## Clave Admin de Bootstrap
+
+La clave admin es la credencial raíz única que permite a un operador poner en marcha el acceso desde cero: con ella puedes crear todas las demás claves con ámbito, invitar a los primeros usuarios del dashboard y configurar la instancia antes de que exista cualquier otra clave. Es la única clave que no se crea a través de la API de claves; se provisiona desde el entorno para que el servidor sea accesible en el primer arranque.
+
+Establece la variable de entorno `ADMIN_KEY` en el servidor. En cada inicio, el servidor hace un upsert de este valor como clave admin con todos los permisos.
+
+Para rotarla: cambia `ADMIN_KEY` por un nuevo secreto y reinicia el servidor.
+
+---
+
+## Ámbito de organización
+
+**Las organizaciones se crean y gestionan fuera de banda por un operador, no a través de esta API de claves.** El ciclo de vida de orgs y miembros (crear / renombrar / eliminar / purgar una org; agregar / actualizar / eliminar un miembro) se realiza con la CLI **`agenteye-orgctl`**; no existe una API HTTP ni un botón en el dashboard para ello. Lo que *sí* permanece igual: **las API keys por organización se siguen creando en el dashboard (o mediante esta API de claves)** por los miembros de la org.
+
+En un despliegue multi-org, cada clave que crea un miembro de una org (a través de esta API de claves o la página **Keys** del dashboard) pertenece a **una organización** y solo puede leer o escribir los datos de esa org; la org queda estampada en la clave al crearla y se aplica en cada solicitud. Las dos claves de bootstrap son la única excepción: la clave `admin` (inicializada desde `ADMIN_KEY`) y la clave `dashboard-assistant` (inicializada desde `AGENT_API_KEY`) tienen **ámbito de instancia** (no llevan org). El dashboard se autentica con la clave `admin` para poder proxiar solicitudes por organización en nombre de los miembros conectados. Los despliegues de un solo tenant no necesitan preocuparse por esto; todas las claves pertenecen a la org `default` integrada.
+
+---
+
+## Crear claves
+
+Usa la clave admin (o cualquier clave con permiso `keys:create`) para crear claves adicionales con ámbito.
+
+### Clave de collector (solo ingesta)
+
+```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"]
+  }'
+```
+
+### Clave de dashboard (solo lectura)
+
+```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"]
+  }'
+```
+
+Cuando creas una clave a través de la API HTTP, tú mismo proporcionas el valor de `key`; elige un secreto robusto y guárdalo de forma segura. (El dashboard funciona al revés: genera un secreto robusto por ti y lo muestra una sola vez al crearlo; ver [Gestión de claves en el dashboard](#key-management-in-the-dashboard).) La respuesta confirma que la clave fue creada:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "prod-collector",
+  "permissions": ["events:add"],
+  "created_at": "2026-04-01T12:00:00Z"
+}
+```
+
+---
+
+## Listar claves
+
+```bash
+curl -s http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+Los secretos de las claves no se devuelven en las respuestas de listado; solo los IDs, nombres y permisos.
+
+---
+
+## Deshabilitar una clave
+
+Deshabilitar revoca el acceso de inmediato sin eliminar el registro de la clave.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/disable \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+---
+
+## Regenerar una clave
+
+Genera un nuevo secreto para una clave existente. El secreto anterior se invalida de inmediato.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/regenerate \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+La respuesta incluye el nuevo secreto en texto plano, **mostrado solo una vez**.
+
+---
+
+## Gestión de claves en el dashboard
+
+La página **Keys** del dashboard proporciona una interfaz de usuario para todas las operaciones anteriores. Necesitas una clave con permiso `keys:read` para ver el listado, y `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` para las acciones de crear / editar / deshabilitar / regenerar respectivamente. Editar los permisos de una clave (`keys:update`) es independiente de crearla (`keys:create`), por lo que puedes otorgar a un operador la capacidad de crear claves sin la capacidad de cambiar el ámbito de las existentes, o viceversa. La clave admin cubre todas estas acciones.
+
+Cuando creas una clave desde el dashboard no proporcionas el secreto; el dashboard genera un secreto robusto por ti y lo muestra **una sola vez** al crearlo. Cópialo de inmediato y guárdalo de forma segura; nunca se vuelve a mostrar, exactamente igual que con una regeneración. Puedes seguir seleccionando los permisos de la clave directamente, o inicializarlos desde un conjunto de permisos (ver más abajo).
+
+![La página API Keys: una tarjeta por clave con su nombre, permisos otorgados y fecha de creación, con acciones de regenerar y deshabilitar; las claves protegidas como `admin` están marcadas](/agenteye/images/api-keys.png)
+
+---
+
+## Distribución recomendada de claves
+
+| Clave | Permisos | Usada por |
+|---|---|---|
+| `admin` (bootstrap mediante la variable de entorno `ADMIN_KEY`) | todos | Operaciones/configuración, y el dashboard (se autentica con `ADMIN_KEY`, proxia solicitudes de usuarios con verificaciones de permisos) |
+| Clave de collector por host | `events:add` | Collector en cada máquina agente |
+| `dashboard-assistant` (bootstrap mediante la variable de entorno `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Asistente de IA, inicializado automáticamente, **protegido**; no puede editarse a través de la API |
+| Clave de telemetría del asistente (opcional) | `events:add` | Auto-instrumentación del asistente de IA, si está habilitada |
+
+> **Nota:** La clave del asistente se **inicializa automáticamente** por el servidor desde la variable de entorno `AGENT_API_KEY` (el mismo secreto que el agente presenta como `AGENTEYE_API_KEY`); no hay un paso manual de creación de clave ni se involucra la clave admin. Sus permisos están fijos en el código fuente para que el ámbito no pueda ampliarse por una mala configuración: lectura sobre eventos / evaluaciones / dashboards, más escritura de dashboards y lectura / escritura / ejecución de consultas para el flujo de autoría "Pídele a la IA que escriba una consulta". Todo el SQL sigue pasando por el mismo rol de solo lectura y la misma ruta de SQL protegido que una consulta escrita por un usuario, por lo que esto amplía la *superficie de autoría*, no la superficie de datos; las operaciones destructivas (`queries:delete`, `dashboards:delete`) se excluyen deliberadamente de la clave del asistente. Al igual que la clave `admin`, está **protegida**: no puede deshabilitarse ni regenerarse a través de la API de claves, solo rotarse cambiando `AGENT_API_KEY` y reiniciando. Los *usuarios* del dashboard también necesitan el permiso `agent:use` para ver y usar el asistente. Si habilitas la auto-instrumentación, dale al asistente una clave separada con solo `events:add`.
+
+---
+
+## Notas de actualización y compatibilidad con versiones anteriores
+
+Solo necesitas estas notas si estás actualizando una instancia existente; los nuevos despliegues pueden omitirlas.
+
+> Cuando se lanzó Audits, los titulares existentes fueron ampliados siguiendo las mismas formas de rol que las alertas: cada usuario y conjunto de permisos que tenía `alerts:read` obtuvo `audits:read`, y cada titular de `alerts:write` obtuvo `audits:write`. Las API keys existentes **no** fueron ampliadas. Otorga `audits:*` a una clave explícitamente si necesita acceso a la superficie de auditorías.
+
+> Los otorgamientos almacenados del token heredado `alerts:ack` se interpretan como `incidents:ack` para que los operadores de guardia conserven el acceso sin necesidad de regenerar claves. El token ya no se puede asignar desde el editor de usuarios del dashboard; la matriz ofrece `incidents:ack` en su lugar.
+
+---
+
+## Próximos pasos
+
+- [SDK de Python](/es/agenteye/python-sdk): cómo se autentica el código de tu agente al enviar eventos.
+- [Seguridad](/es/agenteye/security): cómo funcionan el inicio de sesión, el control de acceso y el aislamiento de datos por organización.

package/.next/standalone/docs-old/es/agenteye/assistant.mdx

@@ -0,0 +1,63 @@
+---
+title: "Asistente de IA"
+description: "Haz una pregunta en lenguaje natural sobre los datos de tu agente y obtén una respuesta vinculada directamente a la evidencia."
+---
+
+
+Haz una pregunta en lenguaje natural sobre los datos de tu agente y obtén una respuesta vinculada directamente a la evidencia. Sin SQL que escribir, sin dashboards que explorar — el asistente de **Failproof AI Observability** es la forma más rápida para que cualquier miembro de tu equipo obtenga respuestas sobre sus agentes.
+
+![El asistente de Failproof AI Observability respondiendo una pregunta en lenguaje natural dentro del dashboard, mostrando una tabla de actividad de agentes en vivo, un desglose de uso de modelos por agente y conclusiones escritas, con las consultas ejecutadas mostradas inline](/agenteye/images/assistant.png)
+*Pregunta en lenguaje natural y obtén una respuesta construida a partir de tus propios datos. Aquí desglosa qué agentes están más activos y qué modelos usan, y muestra las consultas que ejecutó para que puedas verificar cada número.*
+
+No hay nada que aprender. Abre el chat, escribe lo que quieres saber y sigue los enlaces que te devuelve:
+
+```
+You:  which sessions errored today?
+AI:   5 sessions errored today, newest first. Each one is linked:
+      • checkout-agent   14:02   tool timeout
+      • billing-agent    11:47   unhandled error
+      • ...and 3 more
+
+You:  summarize this session          (asked while viewing a run)
+AI:   This run took 12 steps across 3 tools and failed near the end when a
+      payment tool returned an error. It scored low on your "resolved" eval.
+      Links: the session, the failing event, and that evaluation.
+```
+
+## Solo pregunta y ve directo a la prueba
+
+Dejas de adivinar y de escribir consultas. Pregunta "¿cómo está evolucionando la calidad en producción esta semana?", "¿qué sesiones dieron error hoy?" o "resume esta sesión", y obtienes una respuesta directa en segundos, en lugar de construir una consulta y leerla tú mismo.
+
+Cada respuesta viene con sus justificantes. El asistente enlaza las sesiones exactas, las consultas guardadas y los dashboards que utilizó para llegar a la respuesta, para que puedas hacer clic y confirmar en lugar de tomar su palabra como válida. También es **consciente del contexto de la página**: pregunta sobre "esta sesión" mientras la estás viendo y ya sabe a qué ejecución te refieres. Vuelve a abrir cualquier conversación anterior desde el selector de historial y retoma donde lo dejaste.
+
+## Convierte una buena respuesta en una consulta guardada o un dashboard
+
+Cuando una respuesta vale la pena conservar, pídele al asistente que la guarde. Redacta el SQL para una consulta guardada, o ensambla un dashboard a partir de esas consultas, y luego te muestra una tarjeta de **Aprobar / Rechazar**. Nada se escribe hasta que hagas clic en Aprobar, por lo que obtienes la velocidad de "solo pregunta" con la última decisión siempre en tus manos.
+
+En la página de **Queries** va un paso más allá y se convierte en autor de SQL: describe la consulta que quieres ("muestra la tasa de errores por agente durante los últimos 7 días") y transmite SQL directamente al editor, abriendo una vista de diferencias para que puedas **Aceptar** o **Rechazar** el cambio antes de que se aplique.
+
+![La página Queries de Observability y su editor SQL](/agenteye/images/query-lab.png)
+*La página Queries: este editor es donde el asistente transmite un borrador de consulta de solo lectura para que lo aceptes o rechaces.*
+
+Crear SQL mediante preguntas aquí usa el permiso `queries:run`, el mismo que hay detrás del botón **Run** del editor. El chat en cualquier otro lugar necesita `agent:use`.
+
+## Seguro para todo el equipo
+
+Puedes abrir el asistente a todos sin preocuparte por lo que podría tocar:
+
+- **Solo lee lo que tú ya puedes ver.** Las respuestas están limitadas a tus propios permisos de lectura, por lo que nunca amplía tu superficie de datos.
+- **Cada escritura espera tu confirmación.** Las consultas guardadas y los dashboards solo se crean tras tu clic explícito en Aprobar, y no existe ninguna configuración que desactive esa barrera.
+- **Nunca puede eliminar nada.** No hay ninguna herramienta de eliminación expuesta y el asistente no tiene permiso de eliminación. Las eliminaciones permanecen en tus manos, en el dashboard.
+- **Se mantiene dentro de tu organización.** El asistente solo ve la organización que estás visualizando en ese momento.
+- **Tus preguntas son tuyas.** Los prompts y las respuestas viven en tu propia base de datos de Observability; los análisis del producto registran solo metadatos de uso, nunca el texto de tus prompts.
+
+## Dónde encontrarlo
+
+El asistente aparece en el borde derecho de cada página bajo tu organización (`/<org-slug>/...`). Haz clic en el rail, o pulsa `⌘J` / `Ctrl+J`, para expandirlo al panel de chat completo, y arrastra su borde para redimensionarlo; tu anchura se recuerda entre recargas. Necesitas el permiso **`agent:use`** para usarlo; de lo contrario, el rail aparece en gris. Si todavía no se ha activado para tu despliegue (requiere una conexión LLM), verás un rail atenuado en lugar de un chat funcional.
+
+## Relacionado
+
+- [CLI y agentes](/es/agenteye/cli-and-agents)
+- [Queries](/es/agenteye/queries)
+- [Dashboards](/es/agenteye/dashboards)
+- [Suite de evaluación](/es/agenteye/evaluation-suite)

package/.next/standalone/docs-old/es/agenteye/audits.mdx

@@ -0,0 +1,54 @@
+---
+title: "Auditorías: tu analista de fiabilidad automático"
+description: "Failproof AI Observability busca los fallos para los que nunca escribiste una regla y te entrega una lista priorizada de exactamente qué corregir, respaldada por evidencias."
+---
+
+
+Failproof AI Observability busca los fallos para los que nunca escribiste una regla y te entrega una lista priorizada de exactamente qué corregir, respaldada por evidencias. Es como tener un analista que revisa tus logs cada noche y te deja la lista corta sobre el escritorio antes de que empiece el día.
+
+<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="Ver: Encuentra automáticamente dónde falla tu agente (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>
+
+*Un recorrido de dos minutos: desde una ejecución programada hasta una corrección sobre la que puedes actuar.*
+
+![La página de Auditorías: trabajos recurrentes que analizan tus sesiones en busca de patrones de fallo, cada uno con una programación y sensibilidad](/agenteye/images/audits.png)
+*Cada auditoría es un trabajo recurrente que examina tus sesiones y elabora recomendaciones priorizadas respaldadas por evidencias.*
+
+## Deja de adivinar qué corregir a continuación
+
+Las alertas detectan los problemas que ya sabías que debías vigilar. Las auditorías detectan los que no sabías. Según una cadencia que tú defines, una auditoría lee todas tus sesiones de agente y busca los patrones que vale la pena corregir, para que dediques tu tiempo a actuar sobre los hallazgos en lugar de desplazarte por los logs esperando detectarlos tú mismo.
+
+Una sola ejecución ataca los modos de fallo que realmente rompen agentes en producción:
+
+- **Clusters de errores**: el mismo fallo repitiéndose bajo una causa raíz común.
+- **Deriva respecto a una línea base**: comportamiento que se aleja silenciosamente de una ventana conocida como buena.
+- **Fallo de objetivo en transcripciones**: ejecuciones que técnicamente terminaron pero nunca cumplieron el objetivo.
+- **Uso incorrecto de herramientas**: la herramienta equivocada, argumentos incorrectos o bucles que consumen llamadas.
+- **Equilibrio entre calidad y coste**: dónde estás pagando de más por una salida que podrías obtener más barato.
+- **Brechas de cobertura**: comportamiento que ninguna evaluación ni alerta está vigilando.
+
+Tú decides con qué intensidad busca mediante un único ajuste de **sensibilidad** (baja, media o alta), para que tanto un agente de staging ruidoso como uno de producción bien controlado puedan sintonizarse a la señal que deseas.
+
+## Cada recomendación viene con pruebas
+
+Nunca tendrás que aceptar un hallazgo por fe. Cada recomendación cita las sesiones exactas de las que proviene y el SQL que la descubrió, para que puedas abrir la evidencia y confirmar el problema con un clic en lugar de tener que reconstruir una afirmación.
+
+Cuando un hallazgo trata sobre una credencial filtrada, va un paso más allá y vincula los eventos individuales que coincidieron. Haz clic en uno y llegas a ese momento exacto en la sesión, ya seleccionado — no al inicio de una larga transcripción que desplazar. El enlace nombra el evento; nunca copia el secreto detectado en el hallazgo, de modo que leer un hallazgo no sea un segundo lugar donde tu credencial queda escrita. Si un evento ya no existe porque la sesión ha superado tu ventana de retención, la página lo indica claramente en lugar de dejarte preguntándote si hiciste clic en lo incorrecto.
+
+Eso es también lo que mantiene las auditorías honestas. El servidor verifica que cada sesión citada realmente existe y **descarta cualquier recomendación cuya evidencia no se sostenga**, de modo que la auditoría investiga pero nunca inventa. Lo que llega a tu lista es real, reproducible y está ordenado por impacto, con las ganancias más grandes al principio.
+
+## Convierte una corrección en una salvaguarda
+
+Corregir un problema es solo la mitad de la victoria. La otra mitad es asegurarse de que no pueda volver silenciosamente. Cada hallazgo incluye un **acceso directo con un clic que crea una alerta de recurrencia**, prellenada con un activador inicial sensato que puedes ajustar. Cierra el hallazgo, activa la alerta y la próxima vez que ese patrón reaparezca recibirás una notificación en lugar de redescubrirlo en una auditoría futura.
+
+## Dónde encontrarlo
+
+Las auditorías se encuentran en el panel de control en **`/<org-slug>/audits`** (barra lateral en *analyze* → *audits*). Ver ejecuciones y hallazgos requiere **`audits:read`**; crear, editar y gestionar auditorías requiere **`audits:write`**. Define el alcance y la cadencia de una auditoría y pulsa **Run now** cuando quieras resultados inmediatos en lugar de esperar al siguiente ciclo programado.
+
+## Relacionado
+
+- [Alertas](/es/agenteye/alerts): recibe una notificación en el momento en que se supera un umbral que ya conoces.
+- [Evaluaciones](/es/agenteye/evaluations): puntúa cada ejecución para que las regresiones de calidad se detecten por sí solas.
+- [Seguimiento de errores](/es/agenteye/error-tracking): agrupa y sigue los errores que lanzan tus agentes.
+- [Incidentes](/es/agenteye/incidents): rastrea un problema que detecta una auditoría hasta su corrección.

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

@@ -0,0 +1,80 @@
+---
+title: "CLI"
+description: "Todo tu despliegue de Failproof AI Observability, a un comando de distancia."
+---
+
+
+Todo tu despliegue de Failproof AI Observability, a un comando de distancia. Revisa producción, genera una clave de API o reconoce un incidente sin salir de tu terminal, luego automatiza cualquiera de estas acciones en CI, o deja que un agente de código lo haga por ti en lenguaje natural.
+
+```bash
+pipx install agenteye
+agenteye login --email you@example.com      # a 6-digit code lands in your inbox
+agenteye --json sessions --since 24h         # every agent run from the last day, newest first
+```
+
+*El CLI `agenteye` se comunica con tu dashboard. Es una herramienta distinta al colector, que envía eventos al servidor.*
+
+## Todo tu despliegue, a un comando de distancia
+
+Deja de cambiar de pestaña para responder una pregunta rápida. El CLI `agenteye` lee tus datos y administra tu organización desde un único binario, de modo que una verificación que antes requería navegar por el dashboard se convierte en una línea que puedes volver a ejecutar, crear un alias o pegar en un runbook. Dispones de cuatro áreas:
+
+- **Lee tus datos:** `sessions`, `events`, `evals` y `errors`, filtrados por tiempo, agente y entorno.
+- **Administra tu organización:** `keys`, `users`, `settings`, `alerts` e `incidents`.
+- **Ejecuta análisis:** SQL guardado y un ejecutor `query` ad hoc sobre tus datos de eventos.
+- **Consulta al asistente:** `agent ask` accede al mismo analista de solo lectura con el que conversas en el dashboard.
+
+Instálalo una vez con `pipx`, inicia sesión con un código de 6 dígitos enviado por correo, y ya estás listo. La sesión dura aproximadamente un día; vuelve a ejecutar `agenteye login` cuando expire. Úsalo para revisar producción a fondo, aprovisionar una clave o clasificar un incidente activo, todo sin abrir un navegador:
+
+```bash
+agenteye errors --since 24h --aggregate      # what is breaking, grouped by error type
+agenteye incidents list --state firing       # what is on fire right now
+agenteye keys create ci --add events:add     # a key that can only push events, secret shown once
+```
+
+Un hábito importante: las opciones globales como `--json` van antes del comando. `agenteye --json sessions` es correcto; `agenteye sessions --json`, no.
+
+## Automatízalo, intégralo en CI
+
+Cada comando acepta `--json`, y eso lo cambia todo. El JSON limpio va a stdout mientras los mensajes de estado y advertencias van a stderr, por lo que una captura con `--json` se puede pasar directamente a `jq` sin necesidad de limpiar líneas adicionales. Esto hace que el CLI sea igual de útil tanto para ti en la terminal como para un agente de código que procesa la salida:
+
+```bash
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+```
+
+Está diseñado para ejecutarse de forma desatendida. Las confirmaciones se omiten automáticamente cuando no hay terminal conectada, así que nada queda bloqueado en un pipeline, y cada comando devuelve un código de salida significativo: `0` éxito, `4` no autenticado, `5` permiso faltante (el mensaje lo indica, por ejemplo `alerts:write`), `3` dashboard inaccesible. Un script puede bifurcarse en un `4` para reautenticarse o en un `5` para saber exactamente qué solicitar a un administrador, en lugar de fallar sin información.
+
+## Deja que un agente de código lo maneje en lenguaje natural
+
+Mejor aún, no deberías tener que recordar ninguna de estas opciones. El **CLI skill** es una pequeña carpeta de Agent Skill llamada `agenteye-cli` que enseña a un agente de código como Claude Code o Codex a manejar el CLI mediante solicitudes en lenguaje natural. Pregunta "¿hay algo roto hoy?" y el agente selecciona el comando, lo ejecuta como tú y responde en prosa.
+
+Para Claude Code, coloca la carpeta `agenteye-cli` en `~/.claude/skills/` y se descubre automáticamente. Failproof AI Observability proporciona la carpeta; no hay nada extra que instalar, ya que solo controla el CLI que ya tienes instalado. Inicia sesión tú mismo primero: el skill no puede completar el inicio de sesión con código enviado por correo en tu lugar.
+
+Como el agente ejecuta el CLI como tú, puede hacer todo lo que tu sesión permite, tanto lecturas como escrituras: crear claves, cambiar configuraciones, resolver incidentes. La confirmación interactiva del CLI no se activa para un agente, por lo que el skill está diseñado para indicar el comando exacto y esperar tu aprobación antes de cualquier cambio. Tú eres el paso de confirmación.
+
+```text
+you    Why did session run-001 fail?
+
+agent  Running: agenteye --json events --session-id run-001 --all
+       The checkout-agent hit a TimeoutError on its third tool call.
+```
+
+Las lecturas son inmediatas, y cada escritura se pausa esperando tu confirmación:
+
+```text
+you    Give CI a key that can only push events.
+
+agent  This creates an API key. I'll run:
+         agenteye keys create ci --add events:add
+       OK to proceed?
+
+you    yes
+
+agent  Done. Key "ci" created with events:add only. The secret is shown once, so store it now.
+```
+
+## Relacionado
+
+- [Referencia del CLI](/es/agenteye/cli): cada comando, opción y estructura JSON.
+- [Recetas del CLI para agentes](/es/agenteye/cli-recipes): patrones `jq` listos para usar y manejo de códigos de salida.
+- [CLI agent skill](/es/agenteye/cli-skill): instala y ejecuta el skill `agenteye-cli`.
+- [Asistente de IA](/es/agenteye/assistant): el analista integrado en el dashboard con el que `agent ask` se comunica.