failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/i18n/README.zh.md

@@ -0,0 +1,219 @@
+> **⚠️** This is an auto-generated translation. For the latest version, see the [English README](../../README.md). Community corrections welcome!
+
+[🇺🇸 English](../../README.md) | **🇨🇳 简体中文** | [🇯🇵 日本語](README.ja.md) | [🇰🇷 한국어](README.ko.md) | [🇪🇸 Español](README.es.md) | [🇧🇷 Português](README.pt-br.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇷🇺 Русский](README.ru.md) | [🇮🇳 हिन्दी](README.hi.md) | [🇹🇷 Türkçe](README.tr.md) | [🇻🇳 Tiếng Việt](README.vi.md) | [🇮🇹 Italiano](README.it.md) | [🇸🇦 العربية](README.ar.md) | [🇮🇱 עברית](README.he.md)
+
+---
+
+<div align="center">
+
+<img src="https://d2wq11aau0arks.cloudfront.net/failproof/fa_updated_full.svg" alt="failproof ai" width="220" />
+
+[![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai)
+[![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions)
+[![Supply Chain](https://img.shields.io/badge/supply%20chain-secure-brightgreen?style=flat-square)](https://github.com/failproofai/failproofai/actions/workflows/osv-scanner.yml)
+[![Discord](https://img.shields.io/badge/Discord-join%20us-5865F2?style=flat-square&logo=discord)](https://discord.befailproof.ai/)
+[![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://docs.befailproof.ai/introduction)
+[![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](../../LICENSE)
+
+**翻译：** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md)
+
+**为编程 Agent 提供运行时故障处理能力。**
+接入 Claude Code 和 Codex，在循环、危险操作和密钥泄漏演变为事故之前将其拦截。零延迟，本地运行。
+
+</div>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/readme-arch-hq.gif" alt="Failproof AI in action" width="800" />
+</p>
+
+---
+
+## 支持的 Agent CLI
+
+{/* A 6-column table instead of inline <img> runs: table columns never re-wrap,
+     so the grid stays 2×6 at any window width (scrolling on very narrow screens
+     instead of collapsing into ragged orphan rows). */}
+<table align="center">
+  <tr>
+    <td align="center" width="96">
+      <a href="https://claude.com/claude-code" title="Claude Code">
+        <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/claude.svg" alt="Claude Code" width="56" height="56" />
+      </a>
+    </td>
+    <td align="center" width="96">
+      <a href="https://learn.chatgpt.com" title="OpenAI Codex">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/openai-dark.svg" />
+          <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/openai-light.svg" alt="OpenAI Codex" width="56" height="56" />
+        </picture>
+      </a>
+    </td>
+    <td align="center" width="96">
+      <a href="https://github.com/features/copilot/cli" title="GitHub Copilot CLI">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/copilot-dark.svg" />
+          <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/copilot-light.svg" alt="GitHub Copilot" width="56" height="56" />
+        </picture>
+      </a>
+    </td>
+    <td align="center" width="96">
+      <a href="https://cursor.com" title="Cursor Agent CLI">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/cursor-dark.svg" />
+          <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/cursor-light.svg" alt="Cursor Agent" width="56" height="56" />
+        </picture>
+      </a>
+    </td>
+    <td align="center" width="96">
+      <a href="https://opencode.ai/" title="OpenCode">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/opencode-dark.svg" />
+          <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/opencode-light.svg" alt="OpenCode" width="56" height="56" />
+        </picture>
+      </a>
+    </td>
+    <td align="center" width="96">
+      <a href="https://pi.dev/" title="Pi (pi-coding-agent)">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/pi-dark.svg" />
+          <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/pi-light.svg" alt="Pi" width="56" height="56" />
+        </picture>
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="96">
+      <a href="https://hermes-agent.nousresearch.com/" title="Hermes (hermes-agent)">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/hermes-dark.svg" />
+          <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/hermes-light.svg" alt="Hermes" width="56" height="56" />
+        </picture>
+      </a>
+    </td>
+    <td align="center" width="96">
+      <a href="https://openclaw.ai/" title="OpenClaw (openclaw gateway)">
+        <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/openclaw.svg" alt="OpenClaw" width="56" height="56" />
+      </a>
+    </td>
+    <td align="center" width="96">
+      <a href="https://factory.ai/" title="Factory Droid (droid)">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/factory-dark.png" />
+          <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/factory-light.png" alt="Factory Droid" width="56" height="56" />
+        </picture>
+      </a>
+    </td>
+    <td align="center" width="96">
+      <a href="https://devin.ai" title="Devin CLI (Cognition)">
+        <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/devin.svg" alt="Devin CLI" width="56" height="56" />
+      </a>
+    </td>
+    <td align="center" width="96">
+      <a href="https://antigravity.google" title="Antigravity CLI (agy)">
+        <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/antigravity.svg" alt="Antigravity CLI" width="56" height="56" />
+      </a>
+    </td>
+    <td align="center" width="96">
+      <a href="https://goose-docs.ai/" title="Goose (codename goose)">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/goose-dark.svg" />
+          <img src="https://raw.githubusercontent.com/FailproofAI/failproofai/main/assets/logos/goose-light.svg" alt="Goose" width="56" height="56" />
+        </picture>
+      </a>
+    </td>
+  </tr>
+</table>
+
+## 安装
+
+```sh
+npm install -g failproofai
+failproofai policies --install   # 或直接运行 `failproofai` 并在首次运行提示时确认
+failproofai
+```
+
+30 条内置策略立即生效。控制台地址：`localhost:8020`。可通过设置 `FAILPROOFAI_NO_FIRST_RUN=1` 禁用首次运行提示。
+
+---
+
+## 拦截范围
+
+| 策略 | 拦截内容 |
+|---|---|
+| `block-push-master` | 直接推送到 `main` / `master` 分支 |
+| `block-force-push` | `git push --force` |
+| `block-work-on-main` | 在 `main` / `master` 上执行提交、合并、变基 |
+| `block-rm-rf` | 递归删除文件 |
+| `sanitize-api-keys` | API 密钥泄漏至 Agent 上下文 |
+
+→ [全部 30 条内置策略](https://docs.befailproof.ai/built-in-policies)
+
+---
+
+## 自定义策略
+
+将文件放入 `.failproofai/policies/` 目录即可自动加载，无需任何参数。
+提交到代码仓库后，团队成员下次拉取代码时即可生效。
+
+```js
+import { customPolicies, deny, allow } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolInput?.file_path?.includes("production"))
+      return deny("Writes to production paths are blocked.");
+    return allow();
+  },
+});
+```
+
+每条策略可使用三种决策：
+
+| 决策 | 效果 |
+|---|---|
+| `allow()` | 允许该操作 |
+| `deny(message)` | 拦截操作——消息将返回给 Agent |
+| `instruct(message)` | 放行操作，但在 Agent 的下一条提示中附加上下文信息 |
+
+→ [自定义策略指南](https://docs.befailproof.ai/custom-policies)
+
+---
+
+## 会话可视化
+
+Agent 发起的每次工具调用都会在本地记录日志。控制台展示已执行的操作、已拦截的操作，以及策略向 Agent 返回的内容——出现问题时无需猜测。→ [控制台指南](https://docs.befailproof.ai/dashboard)
+
+---
+
+## 文档
+
+| | |
+|---|---|
+| [快速入门](https://docs.befailproof.ai/getting-started) | 安装与初始步骤 |
+| [内置策略](https://docs.befailproof.ai/built-in-policies) | 全部 30 条策略及其参数 |
+| [自定义策略](https://docs.befailproof.ai/custom-policies) | 编写自己的策略 |
+| [配置](https://docs.befailproof.ai/configuration) | 配置作用域与合并规则 |
+| [控制台](https://docs.befailproof.ai/dashboard) | 会话监控与策略活动 |
+| [架构](https://docs.befailproof.ai/architecture) | Hook 系统的工作原理 |
+
+---
+
+## 许可证
+
+MIT 附加 [Commons Clause](https://commonsclause.com/)——可免费用于内部及个人用途；将 failproofai 本身进行商业转售须另行签订协议。完整条款见 [LICENSE](../../LICENSE)。
+
+---
+
+## 贡献
+
+请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。欢迎贡献新策略、边界用例及翻译。
+
+> **开始前请先构建项目。** 首先运行 `bun install && bun run build`。本仓库会将 failproofai 自身的 Hook 应用于自身，这些 Hook 会从已编译的 `dist/` 包中解析 `failproofai` 导入——若未构建，将触发 `Cannot find package 'failproofai'` Hook 错误。修改 `src/` 后请重新构建。详见
+> [构建后才能使用仓库内的开发 Hook](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)。
+
+---
+
+由 [Nivedit Jain](https://github.com/NiveditJain) 和 [Nikita Agarwal](https://github.com/nk-ag) 构建。
+[befailproof.ai](https://befailproof.ai)

package/.next/standalone/docs-old/introduction.mdx

@@ -0,0 +1,57 @@
+---
+title: "Failproof AI"
+description: "FailproofAI gives AI agents 39 built-in failure policies that catch loops, secret leaks, destructive tool calls, and more in a single install."
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Hooks and policies for **AI failure handling**, **error recovery**, and **LLM reliability**. Keep your AI agents reliable and running autonomously across **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI**, and the **Agents SDK**.
+
+AI agents fail in predictable ways. They run destructive commands, leak secrets, drift off-task, get stuck in loops, or push directly to main. Left unattended, small failures cascade into outages, leaked credentials, and lost work.
+
+FailproofAI solves this with **policies**. These rules hook into every agent tool call to **detect failures**, **mitigate them** (block, instruct, sanitize), and **alert you** when something needs attention. A local dashboard lets you review every tool call, agent failure, and recovery action afterward.
+
+Transcripts and policy evaluation stay on your machine. Data is sent only when you explicitly use an online feature, such as authenticated audit reminders or invitations.
+
+## Get started
+
+<CardGroup cols={2}>
+
+<Card title="39 built-in policies" icon="shield" href="/built-in-policies">
+  Block destructive commands, prevent secret leakage, keep agents inside project boundaries, and more. All out of the box.
+</Card>
+
+<Card title="Custom policies" icon="code" href="/custom-policies">
+  Write your own rules in JavaScript with a simple allow / deny / instruct API.
+</Card>
+
+<Card title="Agent monitor" icon="chart-line" href="/dashboard">
+  See what your agents did while you were away. Browse sessions, inspect tool calls, review where policies fired.
+</Card>
+
+<Card title="Easy configuration" icon="gear" href="/configuration">
+  Tune any policy without code. Set allowlists, protected branches, or thresholds per-project or globally.
+</Card>
+
+</CardGroup>
+
+## Quick start
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # enable policies (or skip — `failproofai` will offer to set them up on first run)
+failproofai                      # launch the dashboard
+```
+
+See the [Getting started](/getting-started) guide for the full walkthrough.

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

@@ -0,0 +1,62 @@
+---
+title: "Avvisi"
+description: "Scopri nel momento stesso in cui qualcosa supera i tuoi limiti, sul canale che il tuo team già monitora, invece di venire a conoscenza dal cliente."
+---
+
+Scopri nel momento stesso in cui qualcosa supera i tuoi limiti, sul canale che il tuo team già monitora, invece di venire a conoscenza dal cliente. Imposta una regola una volta e Failproof AI Observability la controlla secondo una pianificazione, poi ti avvisa via email, Slack, webhook o direttamente nella dashboard.
+
+![La pagina Avvisi: una griglia di schede di regole di avviso, ognuna che mostra il suo trigger, la finestra di valutazione, i canali e un badge di gravità info, warning o critical](/agenteye/images/alerts.png)
+*Ogni regola di avviso a colpo d'occhio: cosa monitora, con quale frequenza, dove avvisa e quanto è urgente.*
+
+## Vieni a conoscenza dei problemi prima dei tuoi utenti
+
+Smetti di aggiornare una dashboard sperando di cogliere una regressione. Imposta un avviso ogni volta che c'è un segnale che vorresti conoscere anche quando nessuno sta guardando, e fallo arrivare dove sei già:
+
+- **Email**, a chiunque debba saperlo.
+- **Slack**, un messaggio ricco con un pulsante che ti porta direttamente all'incidente.
+- **Webhook**, un POST JSON per PagerDuty, Opsgenie o il tuo endpoint, con una firma opzionale in modo che il destinatario possa fidarsi.
+- **In-dashboard**, silenzioso per design, per quando stai mettendo a punto una regola e non vuoi avvisare ancora nessuno.
+
+Allega qualsiasi combinazione a una singola regola, e la sua gravità (info, warning o critical) viene mantenuta in modo che gli urgenti sembrino urgenti.
+
+## Costruisci la regola in un form, non in JSON
+
+Descrivi cosa significa "rotto" in un form, e Failproof AI Observability scrive la regola sottostante per te. La spec JSON è semplicemente ciò che quel form produce dietro le quinte, quindi puoi leggerla per capire una regola ma raramente la digiti.
+
+![Il form per il nuovo avviso: nome e descrizione, un toggle abilitato e un picker di trigger che offre soglia di metrica, SQL personalizzato, punteggio di valutazione, valutazione composta e condizioni per evento](/agenteye/images/alert-new.png)
+*Scegli un trigger e il form mostra i campi giusti; Salva scrive la regola.*
+
+Il percorso semplice è veloce: nominalo, scegli un **trigger** (cosa monitorare), imposta la **soglia e la finestra** (quanto grave, per quanto tempo), allega almeno un **canale**, quindi **Salva** e premi **Test** per attivare una notifica sintetica e confermare che ogni destinazione è collegata. Dietro le quinte questo produce una spec piccola come:
+
+```json
+{ "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 }
+```
+
+Non sei limitato a un solo tipo di segnale. Scegli il trigger che corrisponde a come pensi al guasto:
+
+| Trigger | Si attiva quando |
+|---|---|
+| **Soglia di metrica** | una metrica preimpostata (tasso di errore, latenza p95 o p99, conteggi di eventi o errori, spesa di token) supera il tuo limite in una finestra |
+| **SQL personalizzato** | la tua query di sola lettura restituisce una riga, o un valore che calcola supera una soglia |
+| **Punteggio di valutazione** | la media del punteggio di un valutatore (ad es. allucinazione) supera una soglia |
+| **Valutazione composta** | diversi controlli di punteggio si combinano con logica any, all o at-least-N, per cogliere una regressione che si vede solo nei punteggi |
+| **Per evento** | arriva un singolo evento corrispondente: un agente specifico, un tipo di errore specifico o una sottostringa di messaggio |
+
+Stai già guardando un guasto sulla [pagina Errori](/it/agenteye/error-tracking)? Ogni riga lì ha un pulsante **+ avviso** che apre questo stesso form precompilato per cogliere quel guasto esatto di nuovo, così l'incidente che hai appena triato diventa quello che ti avviserà la prossima volta.
+
+**Dove trovarlo:** Gli avvisi si trovano in `/<org-slug>/alerts`. La creazione, modifica, eliminazione e test delle regole richiede **`alerts:write`**; `alerts:read` è sufficiente per visualizzare. Il picker dei destinatari elenca i membri della tua organizzazione per nome, così puoi avvisare una persona senza lasciare il form.
+
+## Avvisami solo quando è reale
+
+Una misurazione errata non dovrebbe svegliarti. Il filtro di rumore **M di N** controlla quanti degli ultimi controlli devono fallire prima che l'avviso ti paghi effettivamente. Impostalo su **3 di 5** e la regola si attiva solo dopo che ha violato tre dei suoi ultimi cinque controlli, quindi un segnale instabile smette di dare falsi allarmi; lascialo al default **1 di 1** per attivarsi al primo sfondamento. Scegli anche con quale frequenza la regola viene eseguita, da preset di 1m, 5m, 15m e 1h, adattati a quanto veloce il segnale si muove veramente.
+
+## Cosa succede quando un avviso si attiva
+
+Una violazione apre un **incidente** e avvisa i tuoi canali una volta. Da lì il tuo team lo riconosce, assegna un proprietario, ne discute e lo risolve, tutto su un registro pulito e attribuito. Quel flusso di lavoro di triage ha la sua casa: vedi [Incidenti](/it/agenteye/incidents).
+
+## Correlati
+
+- [Incidenti](/it/agenteye/incidents): traccia un avviso che si attiva da aperto a riconosciuto a risolto.
+- [Tracciamento degli errori](/it/agenteye/error-tracking): raggruppa i guasti degli agenti e promuovi uno a avviso in un click.
+- [Dashboard](/it/agenteye/dashboards): osserva le board condivise da cui provengono le soglie su cui avvisi.
+- [CLI e agenti](/it/agenteye/cli-and-agents): crea avvisi e riconosci incidenti dal tuo terminale, o scrivili in CI.

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

@@ -0,0 +1,279 @@
+---
+title: "Chiavi API"
+description: "Le chiavi API controllano chi e cosa può raggiungere il tuo server Failproof AI Observability, in modo che un collector possa inviare eventi senza mai acquisire permessi di lettura o amministrazione."
+---
+
+Le chiavi API controllano chi e cosa può raggiungere il tuo server Failproof AI Observability, in modo che un collector possa inviare eventi senza mai acquisire permessi di lettura o amministrazione. Ogni chiave porta uno o più permessi e ogni permesso controlla specifiche rotte del server; concedi solo quelli di cui un job ha bisogno. La maggior parte delle implementazioni crea solo tre tipi di chiave.
+
+## Le 3 chiavi di cui la maggior parte delle implementazioni ha bisogno
+
+| Chiave | Permessi | Chi la usa |
+|---|---|---|
+| Chiave collector | `events:add` | L'`agenteye-collector` su ogni macchina agente, per inviare eventi. |
+| Chiave lettura dashboard | `events:read`, `keys:read` | Un operatore di sola lettura o un'integrazione che interroga dati senza modificarli. |
+| Chiave amministratore bootstrap | tutti i permessi | L'operatore che avvia l'istanza (e il dashboard). Fornita dalla variabile d'ambiente `ADMIN_KEY`. Vedi [Chiave amministratore bootstrap](#chiave-amministratore-bootstrap). |
+
+Inizia da qui. Consulta il catalogo completo dei permessi qui sotto solo quando hai bisogno di una chiave più ristretta e personalizzata. Vedi anche [Layout di chiave consigliato](#layout-di-chiave-consigliato) e [Creazione di chiavi](#creazione-di-chiavi).
+
+---
+
+## Permessi
+
+Il server applica un catalogo fisso di permessi; ognuno controlla specifiche rotte HTTP. Una **chiave amministratore** li contiene tutti; una chiave limitata contiene il sottoinsieme che concedi al momento della creazione. Le stringhe di permesso sconosciute vengono rifiutate quando viene creata una chiave.
+
+> **Nota:** Due permessi validi sono solo per umani/dashboard e non possono essere concessi a una chiave API: `orgs:admin` (amministrazione dell'istanza, solo per operatori) e `keys:update`. Una richiesta a `POST /keys` o `PATCH /keys/:id` che tenta di concedere uno di questi viene rifiutata con HTTP 422. Vedi la riga `keys:update` di seguito per capire perché una chiave bearer può creare chiavi ma mai modificarle.
+
+### Ingestione e interrogazione di eventi
+
+| Permesso | Rotte HTTP | Cosa consente |
+|---|---|---|
+| `events:add` | `POST /events` | Ingestione di batch di eventi da un collector. L'unico permesso di cui un collector ha bisogno. |
+| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Interrogazione di eventi, elenco degli ambienti noti, elenco degli identificativi di modello visti nei dati (usato dalla vista Modelli e dai filtri dei modelli), calcolo dell'aggregato di latenza che alimenta la mappa di calore/banda percentile ed esportazione di una sessione come JSONL. Gli endpoint della barra di filtro condivisa `GET /events/environments` e `GET /events/agent_ids` sono raggiungibili con **uno qualsiasi** tra `events:read` **o** `evaluations:read`, in modo che la pagina sessioni (controllata da `evaluations:read`) riutilizzi lo stesso aspetto per organizzazione. `GET /events/models` non fa parte di loro: richiede `events:read`, quindi un soggetto che possiede solo `evaluations:read` riceve un 403. |
+
+### Sessioni e valutazioni
+
+| Permesso | Rotte HTTP | Cosa consente |
+|---|---|---|
+| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Elenco delle sessioni, lettura dei risultati di valutazione, lo stato di salute della valutazione aggregato utilizzato dai dashboard e lo stato della coda di worker dei job di valutazione. |
+| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Accodamento manuale di una rivalutazione per una sessione completata. |
+
+### Dashboard
+
+| Permesso | Rotte HTTP | Cosa consente |
+|---|---|---|
+| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Elenco dei dashboard, caricamento di uno e lettura dei suoi tile. |
+| `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` | Creazione e modifica dei dashboard, aggiunta/modifica/rimozione dei tile e riordinamento della griglia dei tile. |
+| `dashboards:delete` | `DELETE /dashboards/:id` | Eliminazione di un intero dashboard (l'eliminazione a livello di tile rientra in `dashboards:write`). |
+
+### Query salvate (compositore SQL)
+
+| Permesso | Rotte HTTP | Cosa consente |
+|---|---|---|
+| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Elenco delle query salvate, caricamento di una e ispezione dello schema di sola lettura a cui il compositore è destinato. |
+| `queries:write` | `POST /queries`, `PUT /queries/:id` | Creazione e modifica delle query salvate. SQL viene comunque instradato attraverso lo stesso ruolo di sola lettura e controlli SQL protetti come una chiamata `queries:run`. |
+| `queries:delete` | `DELETE /queries/:id` | Eliminazione di una query salvata. |
+| `queries:run` | `POST /queries/run` | Esecuzione di SQL salvato o ad hoc contro il ruolo di sola lettura utilizzato dal compositore. |
+
+### Assistente AI
+
+| Permesso | Rotte HTTP | Cosa consente |
+|---|---|---|
+| `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` | Comunicazione con l'assistente AI e gestione delle tue conversazioni personali (private). Richiesto sull'**utente** per visualizzare il dock dell'assistente; la chiave dell'assistente stesso è `dashboard-assistant` ed è fornita separatamente (vedi di seguito). |
+
+### Chiavi API
+
+| Permesso | Rotte HTTP | Cosa consente |
+|---|---|---|
+| `keys:create` | `POST /keys` | Creazione di una nuova chiave API limitata. **Non** concede la modifica dei permessi di una chiave esistente (quello è `keys:update`). |
+| `keys:read` | `GET /keys` | Elenco delle chiavi esistenti. I segreti non vengono mai restituiti da questo endpoint. |
+| `keys:update` | `PATCH /keys/:id` | Modifica dei permessi di una chiave esistente. Un permesso **solo per umani/dashboard**; non può essere assegnato a una chiave API (una chiave bearer può creare chiavi ma mai modificarle). |
+| `keys:disable` | `POST /keys/:id/disable` | Revoca di una chiave. Le chiavi protette (`admin`, `dashboard-assistant`) non possono essere disabilitate; ruotale tramite variabile di ambiente + riavvio. |
+| `keys:regenerate` | `POST /keys/:id/regenerate` | Rotazione del segreto di una chiave. Le chiavi protette non possono essere rigenerate tramite questa rotta. |
+
+### Utenti del dashboard
+
+| Permesso | Rotte HTTP | Cosa consente |
+|---|---|---|
+| `users:create` | `POST /users`, `GET /users/defaults` | Invito di un nuovo utente del dashboard (invia un'email + login con passcode monouso (OTP)) e lettura del set di permessi predefinito configurato nel dashboard utilizzato per inizializzare il modulo di invito. |
+| `users:read` | `GET /users`, `GET /users/:id` | Elenco degli utenti e caricamento di un singolo record utente. |
+| `users:update` | `PUT /users/:id` | Modifica dei permessi di un utente. Gli aggiornamenti inviano un'email di cambio permessi all'utente interessato e hanno effetto sulla sua prossima richiesta; non è richiesto il riaccesso. |
+| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Disabilitazione di un utente (revoca immediatamente le sue sessioni) e riabilitazione di un utente precedentemente disabilitato. |
+
+Questi permessi supportano la pagina **Utenti** del dashboard, dove gli ambiti concessi di ogni membro sono mostrati come chip:
+
+![La pagina Utenti: una scheda per utente del dashboard con la sua email, permessi concessi e controlli di modifica/disabilitazione](/agenteye/images/users.png)
+
+### Impostazioni operative
+
+| Permesso | Rotte HTTP | Cosa consente |
+|---|---|---|
+| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Visualizzazione delle impostazioni operative gestite dal dashboard e dei loro metadati; elenco degli override della finestra di contesto per modello; e risoluzione della finestra effettiva per un modello. |
+| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Modifica delle impostazioni operative e aggiunta, modifica o rimozione degli override della finestra di contesto per modello. I cambiamenti interessano i nuovi eventi senza riavviare il server. |
+
+![La pagina Impostazioni: impostazioni operative gestite dal dashboard come accessi consentiti e durate di sessione/OTP, modificabili senza riavvio](/agenteye/images/settings.png)
+
+### Avvisi e incidenti
+
+| Permesso | Rotte HTTP | Cosa consente |
+|---|---|---|
+| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Visualizzazione delle definizioni di avviso configurate. |
+| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Creazione, modifica, eliminazione e test-firing delle definizioni di avviso. |
+| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Visualizzazione degli incidenti e della loro traccia di triage. |
+| `incidents:write` | `POST /alerts/:id/incidents` | Apertura manuale di un incidente rispetto a un avviso esistente. |
+| `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` | Riconoscimento, assegnazione, risoluzione e commento degli incidenti. |
+
+### Audit
+
+| Permesso | Rotte HTTP | Cosa consente |
+|---|---|---|
+| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Visualizzazione delle definizioni di audit, della cronologia di esecuzione e dei risultati. |
+| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Creazione, modifica, eliminazione ed esecuzione di audit; triage dei risultati (riconoscimento / silenziamento / dismissione / risoluzione / riapertura / assegnazione). |
+
+> **Nota:** Per concedere a una chiave la superficie di audit, assegna esplicitamente `audits:*` a essa. Vedi [Note di aggiornamento e compatibilità all'indietro](#note-di-aggiornamento-e-compatibilità-allindietro) per come i beneficiari esistenti sono stati migrati al rilascio di Audits.
+
+> L'endpoint del selettore dei destinatari `GET /alerts/recipients` (che elenca le email dei membri che un editor di avvisi può notificare) è raggiungibile da un titolare di **uno qualsiasi** tra `alerts:read` **o** `alerts:write`, così gli editor di avvisi possono popolare il selettore senza essere assegnati a `users:read`.
+
+> Un visualizzatore di dashboard ha bisogno di **entrambi** `dashboards:read` (per caricare le viste salvate) e `evaluations:read` (le metriche di salute vengono calcolate dai dati di valutazione). Assegna `dashboards:write` per consentire a un utente di creare o modificare dashboard e `dashboards:delete` per rimuoverli.
+
+> `/health` e `/auth/*` (richiesta OTP, verifica OTP, controllo sessione, logout) sono senza autenticazione per progettazione; sono il flusso di accesso e la sonda di vivacità. `GET /access-granters` richiede una chiave valida ma nessun permesso specifico, in modo che qualsiasi utente registrato possa vedere quali amministratori contattare per i cambiamenti di accesso.
+
+---
+
+## Set di permessi
+
+I set di permessi ti permettono di applicare un ruolo denominato invece di selezionare manualmente i token individuali ogni volta. Invece di selezionare una dozzina di permessi uno per uno per ogni nuovo utente del dashboard o chiave API, scegli un set e tutti assegnati a esso portano una concessione coerente e verificabile. La modifica di un set personalizzato riapplica la nuova concessione a ogni utente già assegnato a esso, quindi un cambiamento di ruolo è una modifica piuttosto che un'operazione su ogni membro.
+
+Ogni organizzazione è inizializzata con tre set incorporati:
+
+| Set | Permessi | Destinato a |
+|---|---|---|
+| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Accesso di sola visualizzazione su ogni superficie operativa. |
+| `standard` | tutto in `read-only`, più `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Sola lettura più le azioni quotidiane on-caller: esecuzione di query, rivalutazione di sessioni, riconoscimento di incidenti e uso dell'assistente AI. |
+| `admin` | ogni permesso assegnabile | Controllo completo dell'organizzazione. |
+
+I tre set incorporati sono **immutabili**; i loro nomi significano sempre la stessa cosa, quindi `read-only`, `standard` e `admin` sono sicuri da referenziare in policy e onboarding. Un operatore può creare **set personalizzati** aggiuntivi per modellare ruoli specifici della tua organizzazione (ad esempio, un ruolo di "autore di dashboard" o un ruolo di "solo collector").
+
+I set sono presentati nel dashboard e gestiti tramite API su `GET /permission-sets` (elenco, controllato da `users:read`) e `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (creazione, modifica, eliminazione di un set personalizzato, controllato da `settings:write`). L'eliminazione o la modifica di un set incorporato viene rifiutata.
+
+L'appartenenza al set è ciò che supporta due altre funzionalità:
+
+- **`DEFAULT_USER_PERMISSIONS`** (la concessione preselezionata quando un amministratore apre **+ nuovo utente**) per impostazione predefinita è il set `standard`.
+- **Il flag `--set`** su `agenteye-orgctl` (gestione dei membri dell'organizzazione) avvia un membro da un set denominato, che quindi affini con `--add` / `--remove`.
+
+> **Nota:** Quando un set include un permesso che non è assegnabile a una chiave (ad esempio un set personalizzato con `keys:update`), l'inizializzazione di una chiave da quel set elimina i token non assegnabili; il server altrimenti rifiuterebbe la chiave con HTTP 422. Gli utenti del dashboard non sono soggetti a quella restrizione.
+
+---
+
+## Chiave amministratore bootstrap
+
+La chiave amministratore è la credenziale radice singola che consente a un operatore di avviare l'accesso da zero: con essa puoi creare ogni altra chiave limitata, invitare i primi utenti del dashboard e configurare l'istanza prima che esista qualsiasi altra chiave. È l'unica chiave che non crei tramite l'API delle chiavi; è fornita dall'ambiente in modo che il server sia raggiungibile al primo avvio.
+
+Imposta la variabile d'ambiente `ADMIN_KEY` sul server. Ad ogni avvio il server inserisce/aggiorna questo valore come una chiave amministratore con tutti i permessi.
+
+Per ruotare: cambia `ADMIN_KEY` con un nuovo segreto e riavvia il server.
+
+---
+
+## Scoping dell'organizzazione
+
+**Le organizzazioni stesse sono create e gestite fuori banda da un operatore, non tramite questa API di chiavi.** Il ciclo di vita dell'organizzazione e del membro (creazione/ridenominazione/eliminazione/purga di un'organizzazione; aggiunta/aggiornamento/rimozione di un membro) viene eseguito con la CLI **`agenteye-orgctl`**; non esiste un'API HTTP o pulsante del dashboard per ciò. Quello che *rimane* invariato: **le chiavi API per organizzazione vengono comunque create nel dashboard (o tramite questa API di chiavi)** dai membri dell'organizzazione.
+
+In un'implementazione multi-org, ogni chiave che un membro dell'organizzazione crea (tramite questa API di chiavi o la pagina **Chiavi** del dashboard) appartiene a **un'organizzazione** e può solo leggere o scrivere i dati di quell'organizzazione; l'organizzazione viene timbrata sulla chiave al momento della creazione e applicata ad ogni richiesta. Le due chiavi bootstrap sono l'unica eccezione: la chiave `admin` (fornita da `ADMIN_KEY`) e la chiave `dashboard-assistant` (fornita da `AGENT_API_KEY`) sono **con ambito istanza** (non portano alcun'organizzazione). Il dashboard si autentica con la chiave `admin` in modo da poter rappresentare le richieste per organizzazione per conto dei membri registrati. Le implementazioni single-tenant non hanno bisogno di pensare a questo; tutte le chiavi appartengono all'organizzazione `default` incorporata.
+
+---
+
+## Creazione di chiavi
+
+Usa la chiave amministratore (o qualsiasi chiave con permesso `keys:create`) per creare ulteriori chiavi limitate.
+
+### Chiave collector (solo ingestione)
+
+```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"]
+  }'
+```
+
+### Chiave dashboard (sola lettura)
+
+```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"]
+  }'
+```
+
+Quando crei una chiave tramite l'API HTTP, fornisci tu stesso il valore `key`; scegli un segreto forte e conservalo in modo sicuro. (Il dashboard funziona al contrario: genera un segreto forte per te e lo mostra una sola volta al momento della creazione; vedi [Gestione delle chiavi nel dashboard](#gestione-delle-chiavi-nel-dashboard).) La risposta conferma che la chiave è stata creata:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "prod-collector",
+  "permissions": ["events:add"],
+  "created_at": "2026-04-01T12:00:00Z"
+}
+```
+
+---
+
+## Elenco delle chiavi
+
+```bash
+curl -s http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+I segreti delle chiavi non vengono restituiti negli elenchi, solo ID, nomi e permessi.
+
+---
+
+## Disabilitazione di una chiave
+
+La disabilitazione revoca l'accesso immediatamente senza eliminare il record della chiave.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/disable \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+---
+
+## Rigenerazione di una chiave
+
+Genera un nuovo segreto per una chiave esistente. Il vecchio segreto viene invalidato immediatamente.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/regenerate \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+La risposta include il nuovo segreto in testo libero, **mostrato una sola volta**.
+
+---
+
+## Gestione delle chiavi nel dashboard
+
+La pagina **Chiavi** nel dashboard fornisce un'interfaccia utente per tutte le operazioni di cui sopra. Hai bisogno di una chiave con permesso `keys:read` per visualizzare l'elenco e `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` per le azioni di creazione/modifica/disabilitazione/rigenerazione rispettivamente. La modifica dei permessi di una chiave (`keys:update`) è separata dalla creazione di una (`keys:create`), quindi puoi concedere a un operatore la capacità di creare chiavi senza la capacità di riscrivere le esistenti, o viceversa. La chiave amministratore copre tutti questi.
+
+Quando crei una chiave dal dashboard non fornisci il segreto; il dashboard genera un segreto forte per te e lo visualizza **una volta** al momento della creazione. Copialo immediatamente e conservalo in modo sicuro; non viene mai più mostrato, esattamente come con una rigenerazione. Puoi comunque selezionare i permessi della chiave direttamente o inizializzarli da un set di permessi (vedi di seguito).
+
+![La pagina Chiavi API: una scheda per chiave che mostra il suo nome, permessi concessi e tempo di creazione, con azioni di rigenerazione e disabilitazione; le chiavi protette come `admin` sono contrassegnate](/agenteye/images/api-keys.png)
+
+---
+
+## Layout di chiave consigliato
+
+| Chiave | Permessi | Usata da |
+|---|---|---|
+| `admin` (bootstrap tramite variabile d'ambiente `ADMIN_KEY`) | tutti | Ops/setup e il dashboard (autentica con `ADMIN_KEY`, rappresenta le richieste dell'utente con controlli di permessi) |
+| Chiave collector per host | `events:add` | Collector su ogni macchina agente |
+| `dashboard-assistant` (bootstrap tramite variabile d'ambiente `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Assistente AI, inizializzato automaticamente, **protetto**; non può essere modificato tramite l'API |
+| Chiave telemetria assistente (opzionale) | `events:add` | Auto-strumentazione assistente AI, se abilitata |
+
+> **Nota:** La chiave dell'assistente è **inizializzata automaticamente** dal server dalla variabile d'ambiente `AGENT_API_KEY` (lo stesso segreto che l'agente presenta come `AGENTEYE_API_KEY`); non c'è un passaggio manuale di creazione della chiave e nessuna chiave amministratore coinvolta. I suoi permessi sono fissi nel codice sorgente quindi l'ambito non può essere ampliato per errore di configurazione: lettura tra eventi/valutazioni/dashboard, più dashboards-write e queries-read/write/run per il flusso di authoring di "Chiedi AI di scrivere una query". Tutto il SQL passa comunque attraverso lo stesso ruolo di sola lettura e percorso SQL protetto come una query scritta dall'utente, quindi ciò amplia la *superficie di authoring*, non la superficie dei dati; le operazioni distruttive (`queries:delete`, `dashboards:delete`) rimangono deliberatamente fuori dalla chiave dell'assistente. Come la chiave `admin`, è **protetta**: non può essere disabilitata o rigenerata tramite l'API delle chiavi, solo ruotata cambiando `AGENT_API_KEY` e riavviando. Gli *utenti* del dashboard inoltre hanno bisogno del permesso `agent:use` per vedere e usare l'assistente. Se abiliti l'auto-strumentazione, dai all'assistente una chiave separata solo per `events:add`.
+
+---
+
+## Note di aggiornamento e compatibilità all'indietro
+
+Ne hai bisogno solo se stai aggiornando un'istanza esistente; le nuove implementazioni possono saltarle.
+
+> Al rilascio di Audits, i beneficiari esistenti sono stati ampliati lungo le stesse forme di ruolo degli avvisi: ogni utente e set di permessi che contiene `alerts:read` ha acquisito `audits:read` e ogni titolare di `alerts:write` ha acquisito `audits:write`. Le chiavi API esistenti **non** sono state ampliate. Assegna `audits:*` a una chiave esplicitamente se necessita della superficie di audit.
+
+> Le concessioni memorizzate del token legacy `alerts:ack` vengono analizzate come `incidents:ack` in modo che gli on-caller mantengano l'accesso senza ricreate le chiavi. Il token non è più assegnabile dall'editor utente del dashboard; la matrice offre invece `incidents:ack`.
+
+---
+
+## Prossimi passi
+
+- [Python SDK](/it/agenteye/python-sdk): come il tuo codice agente si autentica quando invia eventi.
+- [Sicurezza](/it/agenteye/security): come funzionano l'accesso, il controllo degli accessi e l'isolamento dei dati per organizzazione.