failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,63 @@
+---
+title: "Assistente IA"
+description: "Fai una domanda sui dati del tuo agente in linguaggio naturale e ottieni una risposta collegata direttamente alle prove."
+---
+
+
+Fai una domanda sui dati del tuo agente in linguaggio naturale e ottieni una risposta collegata direttamente alle prove. Niente SQL da scrivere, niente dashboard da frugare — l'assistente **Failproof AI Observability** è il modo più veloce per chiunque nel tuo team di ottenere risposte sui tuoi agenti.
+
+![L'assistente Failproof AI Observability che risponde a una domanda in linguaggio naturale all'interno del dashboard, mostrando una tabella di Agent Activity dal vivo, una suddivisione dell'utilizzo del modello per agente e considerazioni scritte, con le query eseguite mostrate inline](/agenteye/images/assistant.png)
+*Fai una domanda in linguaggio naturale e ottieni una risposta costruita dai tuoi dati. Qui scompone quali agenti sono più occupati e quali modelli usano, e mostra le query che ha eseguito per permetterti di verificare ogni numero.*
+
+Non c'è niente da imparare. Apri la chat, scrivi quello che vuoi sapere e segui i link che ti restituisce:
+
+```
+Tu:    quali sessioni hanno avuto errori oggi?
+IA:    5 sessioni hanno avuto errori oggi, le più recenti per prime. Ognuna è collegata:
+       • checkout-agent   14:02   tool timeout
+       • billing-agent    11:47   unhandled error
+       • ...e 3 altri
+
+Tu:    riassumi questa sessione          (chiesto mentre visualizzi un'esecuzione)
+IA:    Questa esecuzione ha richiesto 12 step su 3 tool e ha fallito verso la fine quando
+       un tool di pagamento ha restituito un errore. Ha ottenuto un basso punteggio
+       nella tua valutazione "resolved". Link: la sessione, l'evento che ha fallito e quella valutazione.
+```
+
+## Chiedi semplicemente e vai diretto alle prove
+
+Smetti di indovinare e smetti di scrivere query. Chiedi "come sta andando la qualità in prod questa settimana?", "quali sessioni hanno avuto errori oggi?", oppure "riassumi questa sessione", e ricevi una risposta diretta in pochi secondi invece di dover costruire una query e leggerla tu stesso.
+
+Ogni risposta viene fornita con le sue ricevute. L'assistente collega le esatte sessioni, le query salvate e i dashboard che ha utilizzato per arrivare alla risposta, così puoi cliccare e confermare invece di prendere la sua parola. È anche **consapevole della pagina**: se chiedi informazioni su "questa sessione" mentre ne stai visualizzando una, sa già quale esecuzione intendi. Riapri qualsiasi conversazione precedente in seguito dal selettore della cronologia e continua da dove hai interrotto.
+
+## Trasforma una buona risposta in una query salvata o un dashboard
+
+Quando una risposta vale la pena conservare, chiedi all'assistente di salvarla. Redige l'SQL per una query salvata, oppure assembla un dashboard da quelle query, quindi ti mostra una scheda **Approva / Rifiuta**. Niente viene scritto finché non fai clic su Approva, così ottieni la velocità di "chiedi semplicemente" con l'ultima parola sempre tua.
+
+Sulla pagina **Queries** va ancora oltre e diventa un autore SQL: descrivi la query che desideri ("mostra il tasso di errore per agente negli ultimi 7 giorni") e trasmette l'SQL direttamente nell'editor, aprendo una vista di diff così puoi **Accettare** o **Rifiutare** la modifica prima che sia finalizzata.
+
+![La pagina Observability Queries e il suo editor SQL](/agenteye/images/query-lab.png)
+*La pagina Queries: questo editor è dove l'assistente trasmette una draft di query, di sola lettura, per te da accettare o rifiutare.*
+
+La creazione di SQL chiedendo qui usa il permesso `queries:run`, lo stesso dietro al pulsante **Run** dell'editor. La chat ovunque altro ha bisogno di `agent:use`.
+
+## Sicuro da affidare a tutto il team
+
+Puoi aprire l'assistente a tutti senza preoccuparti di quello che potrebbe toccare:
+
+- **Legge solo quello che puoi già vedere.** Le risposte sono limitate ai tuoi permessi di lettura, quindi non amplia mai la tua superficie dati.
+- **Ogni scrittura è in attesa di te.** Le query salvate e i dashboard vengono creati solo dopo il tuo clic esplicito su Approva, e non c'è alcuna impostazione che disattivi questo controllo.
+- **Non può mai eliminare nulla.** Nessun tool di eliminazione è esposto e l'assistente non possiede permessi di eliminazione. Le eliminazioni rimangono nelle tue mani, nel dashboard.
+- **Rimane dentro la tua organizzazione.** L'assistente vede solo l'organizzazione che stai visualizzando al momento.
+- **Le tue domande rimangono tue.** I prompt e le risposte vivono nel tuo database Observability; l'analisi dei prodotti registra solo i metadati di utilizzo, mai il testo del tuo prompt.
+
+## Dove trovarlo
+
+L'assistente si trova lungo il bordo destro di ogni pagina sotto la tua organizzazione (`/<org-slug>/...`). Fai clic sulla barra laterale, oppure premi `⌘J` / `Ctrl+J`, per espanderlo nel pannello chat completo, e trascina il suo bordo per ridimensionarlo; la tua larghezza viene ricordata tra i ricaricamenti. Hai bisogno del permesso **`agent:use`** per usarlo, altrimenti la barra laterale è disabilitata. Se non è stato ancora attivato per la tua distribuzione (ha bisogno di una connessione LLM), vedrai una barra laterale muta al posto di una chat funzionante.
+
+## Correlati
+
+- [CLI e agenti](/it/agenteye/cli-and-agents)
+- [Query](/it/agenteye/queries)
+- [Dashboard](/it/agenteye/dashboards)
+- [Suite di valutazione](/it/agenteye/evaluation-suite)

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

@@ -0,0 +1,54 @@
+---
+title: "Audit: il tuo analista di affidabilità automatico"
+description: "Failproof AI Observability cerca i guasti che non hai mai scritto una regola per gestire e ti consegna un elenco ordinato per priorità e basato su prove di esattamente cosa correggere."
+---
+
+
+Failproof AI Observability cerca i guasti che non hai mai scritto una regola per gestire e ti consegna un elenco ordinato per priorità e basato su prove di esattamente cosa correggere. È come avere un analista che esamina i tuoi log ogni notte, lasciando sul tuo desk la lista ristretta al mattino.
+
+<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="Watch: Automatically find where your agent is failing (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 tour di due minuti: da un'esecuzione programmata a una correzione su cui puoi agire.*
+
+![La pagina Audit: lavori ricorrenti che analizzano le tue sessioni cercando pattern di guasto, ognuno con una pianificazione e sensibilità](/agenteye/images/audits.png)
+*Ogni audit è un lavoro ricorrente che analizza le tue sessioni e redige raccomandazioni ordinate per priorità e basate su prove.*
+
+## Smetti di indovinare cosa correggere dopo
+
+Gli alert catturano i problemi che già sai di dover tenere d'occhio. Gli audit catturano quelli che non conosci. Su una pianificazione che imposti tu, un audit legge tutte le tue sessioni di agent e cerca i pattern che vale la pena correggere, così puoi dedicare il tuo tempo ad agire sui risultati invece di scorrere i log sperando di individuarli da solo.
+
+Una singola esecuzione va dopo i modi di guasto che in realtà rompono gli agent in produzione:
+
+- **Cluster di errori**: lo stesso guasto che si ripete sotto una causa radice condivisa.
+- **Deriva rispetto a un baseline**: il comportamento che silenziosamente si allontana da una finestra nota e affidabile.
+- **Fallimento dell'obiettivo nei transcript**: esecuzioni che tecnicamente sono terminate ma non hanno mai svolto il lavoro.
+- **Uso errato dello strumento**: lo strumento sbagliato, argomenti errati, o loop che consumano chiamate.
+- **Compromessi tra qualità e costo**: dove stai pagando troppo per un output che potresti ottenere a un prezzo inferiore.
+- **Gap di copertura**: comportamento che nessun eval o alert sta monitorando.
+
+Decidi quanto approfondire con una singola impostazione di **sensibilità** (bassa, media o alta), così un agent di staging rumoroso e uno di produzione bloccato possono essere sintonizzati ognuno sul segnale che desideri.
+
+## Ogni raccomandazione viene con le prove
+
+Non dovrai mai prendere un risultato sulla fiducia. Ogni raccomandazione cita le esatte sessioni da cui proviene e l'SQL che l'ha riportata alla luce, così puoi aprire le prove e confermare il problema con un clic invece di fare ingegneria inversa su un'affermazione.
+
+Quando un risultato riguarda una credenziale persa, fa un passo oltre e collega gli eventi individuali che ha trovato. Fai clic su uno e atterri esattamente su quel momento nella sessione, già selezionato — non all'inizio di un lungo transcript da scorrere. Il link nomina l'evento; non copia mai il segreto rilevato nel risultato, così leggere un risultato non è un secondo posto dove la tua credenziale è scritta. Se un evento non è più presente perché la sessione ha superato la tua finestra di conservazione, la pagina lo dice chiaramente invece di lasciarti chiederti se hai cliccato sul posto sbagliato.
+
+Questo è anche quello che mantiene gli audit onesti. Il server verifica che ogni sessione citata esista effettivamente e **scarta qualsiasi raccomandazione le cui prove non si mantengono**, così l'audit indaga ma mai inventa. Quello che finisce nella tua lista è reale, riproducibile e ordinato per priorità in base a quanto conta, con i vincitori più grandi in cima.
+
+## Trasforma una correzione in una barriera protettiva
+
+Correggere un problema è solo metà della vittoria. L'altra metà è assicurarsi che non torni silenziosamente. Ogni risultato porta un **collegamento con un solo clic che redige un alert di ricorrenza**, precompilato con un trigger di partenza sensato che puoi sintonizzare. Chiudi il risultato, attiva l'alert, e la prossima volta che quel pattern riappare ricevi una notifica invece di riscoprirlo in un audit futuro.
+
+## Dove trovarlo
+
+Gli audit si trovano nel dashboard a **`/<org-slug>/audits`** (barra laterale su *analyze* quindi su *audits*). La visualizzazione delle esecuzioni e dei risultati richiede **`audits:read`**; la creazione, la modifica e la triaging degli audit richiedono **`audits:write`**. Imposta l'ambito e la cadenza di un audit, quindi fai clic su **Run now** ogni volta che desideri i risultati immediatamente invece di attendere il prossimo passaggio programmato.
+
+## Correlati
+
+- [Alerts](/it/agenteye/alerts): ricevi una notifica nel momento in cui viene superata una soglia che conosci già.
+- [Evaluations](/it/agenteye/evaluations): assegna un punteggio a ogni esecuzione così le regressioni di qualità emergono da sole.
+- [Error tracking](/it/agenteye/error-tracking): raggruppa e segui gli errori che i tuoi agent generano.
+- [Incidents](/it/agenteye/incidents): traccia un problema che un audit scopre fino alla sua correzione.

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

@@ -0,0 +1,80 @@
+---
+title: "CLI"
+description: "L'intera implementazione di Failproof AI Observability, a un solo comando di distanza."
+---
+
+
+L'intera implementazione di Failproof AI Observability, a un solo comando di distanza. Controlla la produzione, genera una chiave API o riconosci un incidente senza lasciare il terminale, quindi inserisci tutto in uno script per CI, o lascia che un agente di codifica lo faccia per te in inglese semplice.
+
+```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
+```
+
+*La CLI `agenteye` comunica con il tuo dashboard. È uno strumento diverso dal collector, che invia eventi al server.*
+
+## L'intera implementazione, a un solo comando di distanza
+
+Smetti di saltare tra le schede per rispondere a una domanda veloce. La CLI `agenteye` legge i tuoi dati e amministra la tua organizzazione da un singolo binario, quindi un controllo che prima significava cliccare nel dashboard diventa una singola riga che puoi rieseguire, creare un alias, o incollare in un runbook. Hai a disposizione quattro superfici:
+
+- **Leggi i tuoi dati:** `sessions`, `events`, `evals` e `errors`, filtrati per tempo, agente e ambiente.
+- **Gestisci la tua organizzazione:** `keys`, `users`, `settings`, `alerts` e `incidents`.
+- **Esegui analitiche:** SQL salvato più un runner ad hoc `query` sui tuoi dati di eventi.
+- **Chiedi all'assistente:** `agent ask` raggiunge lo stesso analista di sola lettura con cui chatti nel dashboard.
+
+Installalo una volta con `pipx`, accedi con un codice a 6 cifre inviato via email, e sei pronto. La sessione dura circa un giorno; riesegui `agenteye login` quando scade. Usalo per controllare la produzione, provisioning di una chiave, o triage di un incidente attivo, il tutto senza aprire un browser:
+
+```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'abitudine da conoscere: le opzioni globali come `--json` vanno prima del comando. `agenteye --json sessions` è corretto; `agenteye sessions --json` non lo è.
+
+## Inseriscilo in uno script, integralo in CI
+
+Ogni comando accetta `--json`, e questo cambia tutto. JSON pulito va a stdout mentre lo stato umano e gli avvisi vanno a stderr, quindi un capture `--json` si collega direttamente a `jq` senza alcuna riga estranea da togliere. È questo che rende la CLI altrettanto valida per te al prompt e per un agente di codifica che analizza l'output:
+
+```bash
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+```
+
+È costruito per essere eseguito senza supervisione. I prompt di conferma vengono automaticamente saltati quando nessun terminale è collegato, quindi nulla si blocca in una pipeline, e ogni comando restituisce un codice di uscita significativo: `0` successo, `4` non connesso, `5` autorizzazione mancante (il messaggio la nomina, per esempio `alerts:write`), `3` dashboard non raggiungibile. Uno script può diramarsi su un `4` per reauthenticarsi o su un `5` per dirti esattamente cosa chiedere a un amministratore, invece di fallire senza sapere il motivo.
+
+## Lascia che un agente di codifica lo guidi in inglese semplice
+
+Ancora meglio, non dovresti nemmeno dover ricordare nessuno di questi flag. La **CLI skill** è una piccola cartella di Agent Skill chiamata `agenteye-cli` che insegna a un agente di codifica come Claude Code o Codex a guidare la CLI da richieste in inglese semplice. Chiedi "c'è qualcosa di rotto oggi?" e l'agente sceglie il comando, lo esegue come te, e risponde in prosa.
+
+Per Claude Code, rilascia la cartella `agenteye-cli` in `~/.claude/skills/` e viene scoperta automaticamente. Failproof AI Observability fornisce la cartella; non c'è nulla di extra da installare, perché guida solo la CLI che hai già installato. Accedi tu stesso prima: lo skill non può completare per te l'accesso tramite codice inviato via email.
+
+Poiché l'agente esegue la CLI come te, può fare tutto ciò che la tua login consente, sia letture che scritture: creare chiavi, modificare le impostazioni, risolvere incidenti. Il prompt di conferma "sei sicuro?" della CLI non si attiva per un agente, quindi lo skill è scritto per indicare il comando esatto e attendere il tuo OK prima di qualsiasi modifica. Tu sei il passaggio di conferma.
+
+```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.
+```
+
+Le letture rimangono istantanee, e ogni scrittura ti attende:
+
+```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.
+```
+
+## Correlati
+
+- [Riferimento CLI](/it/agenteye/cli): ogni comando, flag e forma JSON.
+- [Ricette CLI per agenti](/it/agenteye/cli-recipes): pattern `jq` copia-incolla e gestione dei codici di uscita.
+- [Skill agente CLI](/it/agenteye/cli-skill): installa ed esegui lo skill `agenteye-cli`.
+- [Assistente AI](/it/agenteye/assistant): l'analista nel dashboard con cui comunica `agent ask`.

package/.next/standalone/docs-old/it/agenteye/cli-recipes.mdx

@@ -0,0 +1,179 @@
+---
+title: "Ricette CLI per gli agenti"
+description: "Copia e incolla i pattern di query e le ricette jq che trasformano i dati di sessione, evento e valutazione in qualcosa che uno script o un agente di codifica può automatizzare."
+---
+
+
+Estrai i dati di sessione, evento e valutazione (e attiva rivalutazioni) direttamente da uno script o da un agente di codifica, con JSON pulito su stdout che si collega direttamente a `jq`. Queste ricette trasformano i dati di Failproof AI Observability in qualcosa che un utente di terminale o un agente di codifica IA (Claude Code, Cursor) può interrogare e automatizzare, senza navigare nella dashboard.
+
+I pattern sottostanti sono pronti per il copia-incolla per la CLI di Failproof AI Observability (`agenteye`). Per l'installazione, l'autenticazione e l'elenco completo delle opzioni, vedi [CLI](/it/agenteye/cli); esegui `agenteye -h` o `agenteye <command> -h` per l'aiuto integrato.
+
+## Regole d'oro
+
+1. **Le opzioni globali vanno *prima* del comando.** `agenteye --json sessions` è corretto; `agenteye sessions --json` no. Le opzioni globali sono `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`.
+2. **Passa `--json` ogni volta che analizzi l'output.** I dati vanno su **stdout** come JSON; lo stato umano e gli errori vanno su **stderr**, così stdout rimane pulito per il collegamento a `jq`.
+3. **Rama sul codice di uscita**, non sul testo di stderr: `0` ok · `1` errore inaspettato · `2` argomenti non validi · `3` impossibile raggiungere la dashboard · `4` non autenticato o scaduto · `5` permesso mancante · `6` risorsa non trovata.
+4. **Scopri con `-h`.** Ogni comando documenta i suoi filtri, i formati di valore e la forma JSON.
+
+## Configurazione una tantum
+
+```bash
+export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # così non ripeti --base-url
+agenteye login --email you@example.com                       # incolla il codice ricevuto per email; valido ~24h
+```
+
+## Conferma l'autenticazione prima di fare lavoro
+
+`whoami` non dagli mai errori su una sessione mancante o scaduta; riporta invece `logged_in:false`, così un agente può controllare lo stato dell'autenticazione in sicurezza. (Può comunque uscire con codice non zero se nessun URL di base è impostato o la dashboard non è raggiungibile.)
+
+```bash
+if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
+  echo "Not authenticated. Run: agenteye login" >&2; exit 1
+fi
+```
+
+## Trova sessioni con errori o punteggi bassi
+
+```bash
+# sessioni nelle ultime 24h il cui stato di valutazione è errore
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+
+# valutazioni con punteggio <= 0.5 su utilità, per un agente
+agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
+  | jq '.evaluations[] | {session_id, scores}'
+```
+
+Il filtro del punteggio vive su **`evals`**, non su `sessions`. `--score KEY:MIN..MAX` è ripetibile e combinato con AND; entrambi i limiti sono opzionali (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Puoi passare fino a 20 filtri di punteggio per richiesta; di più restituisce HTTP 400. `sessions` condivide i filtri `--env`, `--status`, `--agent-id`, `--session-id` e intervallo di tempo con `evals`, ma non ha `--score`.
+
+## Leggi una sessione da capo a fondo
+
+Non c'è un singolo comando `session show`. Combina la traccia degli eventi con la valutazione della sessione:
+
+```bash
+# l'ultima valutazione della sessione (stato + punteggi)
+agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'
+
+# ogni evento nell'esecuzione (aumenta --limit per un controllo completo)
+agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
+
+# solo le chiamate di strumento in una sessione (--full è richiesto per ottenere il payload grezzo)
+agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
+  | jq '.events[].payload'
+```
+
+> **Nota:** Per impostazione predefinita, `events` legge un feed veloce senza payload. Ogni evento porta un `summary` di una riga calcolato dal server più flag come `is_error` e conteggi di token, ma `payload` ritorna come `{}`. Per estrarre il payload grezzo, aggiungi `--full` (o `--fields payload`). Il feed completo è più lento su larga scala, quindi mantienilo limitato: abbina `--full` a un singolo `--session-id`.
+
+## Estrai tutto (paginazione)
+
+I risultati sono più recenti in primo piano e paginati con cursore.
+
+```bash
+# un colpo: estrai fino a 500 righe in pagine di 200 righe
+agenteye --json events --session-id run-001 --limit 500 --all > events.json
+
+# paginazione manuale: reinserisci next_cursor
+page=$(agenteye --json events --limit 100)
+cursor=$(echo "$page" | jq -r '.next_cursor // empty')
+[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"
+```
+
+## Riduci l'output con --fields
+
+Limita i tasti (sia nella tabella che in `--json`) per ridurre quello che un agente deve leggere.
+
+```bash
+agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]'
+agenteye --json events --session-id run-001 --fields ts,event_type --all
+```
+
+I nomi di campo sconosciuti vengono rifiutati (uscita `2`) con l'elenco valido, un modo economico per scoprire i nomi dei campi.
+
+## Scopri i valori di filtro validi
+
+```bash
+agenteye --json list envs | jq -r '.values[]'           # valori per --env
+agenteye --json list tools | jq -r '.values[]'          # nomi degli strumenti; anche agenti, modelli, event_types, …
+agenteye --json list score_filters | jq -r '.values[]'  # KEY valida per --score KEY:MIN..MAX
+```
+
+## Scegli la tua org (multi-tenant)
+
+Se appartieni a più di un'org, scegli il tenant attivo al login (viene salvato):
+
+```bash
+agenteye login --org acme --email you@corp.com   # imposta il tenant nello stesso passaggio del login
+agenteye --json orgs list | jq -r '.orgs[].org_slug'
+agenteye --org globex --json sessions --since 24h   # sostituisci per un comando
+```
+
+Un login multi-org senza `--org` esce con codice non zero e stampa le org tra cui scegliere.
+
+## Fornisci una chiave API per SDK/collector
+
+```bash
+# il segreto viene stampato UNA VOLTA, con --json è il campo .key
+key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
+agenteye keys regenerate ci-bot --yes    # ruota; agenteye keys disable ci-bot --yes per revocare
+```
+
+## Esegui una query salvata o ad hoc
+
+```bash
+agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
+agenteye --json query run errs --arg prod | jq '.rows'   # una query salvata + un $1 posizionale
+```
+
+## Triage di un incidente in modo non interattivo
+
+```bash
+id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id')
+agenteye incidents ack "$id"
+agenteye incidents assign "$id" --assignee you@corp.com
+agenteye incidents resolve "$id" --yes
+```
+
+> **Nota:** Le mutazioni saltano automaticamente il prompt di conferma sotto `--json` o quando stdin non è una TTY, così gli agenti non si bloccano mai; passa `--yes`/`-y` per saltarlo esplicitamente altrove.
+
+## Gestione del codice di uscita in uno script
+
+```bash
+out=$(agenteye --json sessions --since 1h) || code=$?
+case "${code:-0}" in
+  0) echo "$out" | jq '.sessions | length' ;;
+  4) echo "Session expired - run 'agenteye login'." >&2 ;;
+  5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;;
+  3) echo "Dashboard unreachable - check the URL." >&2 ;;
+  *) echo "Unexpected error (exit ${code})." >&2 ;;
+esac
+```
+
+## Forme di output JSON
+
+| Comando | stdout JSON (con `--json`) |
+|---|---|
+| `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` oppure `{"logged_in": false}` |
+| `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` |
+| `events` | `{"events": [...], "next_cursor": <cursor or null>}` |
+| `evals` | `{"evaluations": [...], "next_cursor": <cursor or null>}` |
+| `sessions` | `{"sessions": [...], "next_cursor": <cursor or null>}` |
+| `errors` | `{"errors": [...], "next_cursor": <cursor or null>}` |
+| `list <kind>` | `{"kind", "values": [...]}` |
+| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` mostrata una volta) |
+| `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` |
+| `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` |
+| `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` |
+| create/update/delete (qualsiasi) | l'oggetto risorsa, oppure `{"deleted": true, "id"}` per i delete |
+| failure (qualsiasi, con `--json`) | `{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` su stdout |
+
+- Ogni elemento **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Nota che `payload` è `{}` a meno che tu non richieda il feed completo con `--full` (o `--fields payload`).
+- Ogni elemento **evaluation** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`.
+- Ogni elemento **session** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`.
+
+Ogni comando `--fields` accetta esattamente i nomi di campo del suo elemento. L'insieme differisce tra `sessions` e `evals`, quindi un nome valido per uno può essere rifiutato dall'altro.
+
+## Prossimi passi
+
+- [CLI](/it/agenteye/cli): installazione, autenticazione e il riferimento completo delle opzioni per ogni comando.
+- [CLI agent skill](/it/agenteye/cli-skill): pacchetto queste ricette come una skill che il tuo agente di codifica può caricare.
+- [API keys](/it/agenteye/api-keys): crea e delimita le chiavi con cui la CLI, SDK e collector si autenticano.
+- [Python SDK](/it/agenteye/python-sdk): invia eventi in Failproof AI Observability così c'è dati per queste ricette da interrogare.

package/.next/standalone/docs-old/it/agenteye/cli-skill.mdx

@@ -0,0 +1,159 @@
+---
+title: "Competenza CLI dell'Agente di Osservabilità Failproof AI"
+description: "Chiedi al tuo agente di codifica \"c'è qualcosa di rotto oggi?\" e lascia che risponda dai tuoi dati di Osservabilità Failproof AI in tempo reale, senza comandi da memorizzare."
+---
+
+
+Chiedi al tuo agente di codifica *"c'è qualcosa di rotto oggi?"* e lascia che risponda dai tuoi dati di Osservabilità Failproof AI in tempo reale, senza comandi da memorizzare. La **competenza CLI di Osservabilità Failproof AI** (`agenteye-cli`) è un'*Agent Skill*: una piccola cartella di istruzioni che un agente di codifica come Claude Code o Codex carica su richiesta. Insegna all'agente a operare il tuo deployment di Osservabilità tramite la [`agenteye` CLI](/it/agenteye/cli) da richieste in linguaggio naturale come *"dai a CI una chiave che può solo inviare eventi"* o *"conferma l'incident in corso e assegnalo a me."*
+
+**Non** è un servizio o un binario separato; non c'è nulla da distribuire. Funziona sulla CLI che hai già installato: l'agente esegue `agenteye --json …`, analizza il JSON pulito, e ti risponde in prosa. Tutto ciò che può fare, potresti farlo tu digitando gli stessi comandi.
+
+---
+
+## Come si relaziona con le altre interfacce di Osservabilità Failproof AI
+
+Osservabilità Failproof AI ti offre quattro modi per raggiungere gli stessi dati e controlli. Si completano a vicenda:
+
+| Interfaccia | Che cos'è | Dove viene eseguita | Usala quando |
+|---|---|---|---|
+| **[CLI](/it/agenteye/cli)** | Il riferimento comando/flag per `agenteye` | Il tuo terminale | Vuoi eseguire o scrivere uno script per un comando specifico |
+| **[Ricette CLI](/it/agenteye/cli-recipes)** | Pattern `jq`/pipeline da copiare e incollare | Il tuo terminale / script | Stai integrando la CLI nell'automazione |
+| **Competenza CLI** (questo documento) | Una porta in linguaggio naturale sulla CLI | Il tuo agente di codifica, sulla tua workstation | Vuoi *semplicemente chiedere* e lasciare che l'agente scelga il comando |
+| **[Competenza Evaluator](/it/agenteye/evaluator-skill)** | Una competenza gemella che progetta e costruisce il tuo servizio di scoring | Il tuo agente di codifica, sulla tua workstation | Vuoi *produrre* punteggi di valutazione piuttosto che leggerli |
+| **[Competenza Python SDK](/it/agenteye/python-sdk-skill)** | Una competenza gemella che strumenta il tuo agente in modo che emetta telemetria | Il tuo agente di codifica, sulla tua workstation | Vuoi che il tuo agente *produca* gli eventi che questa competenza legge |
+| **[Assistente AI nella dashboard](/it/agenteye/assistant)** | Una chat incorporata nella dashboard | Lato server (nella dashboard) | Vuoi domande e risposte nella dashboard sui tuoi dati |
+
+La competenza stessa non ha privilegi propri; converte semplicemente le tue parole in chiamate CLI che vengono eseguite come te:
+
+```mermaid
+flowchart TD
+    YOU["tu: 'conferma l'incident in corso'"] --> AGENT["agente di codifica (Claude Code / Codex)<br/>carica la competenza agenteye-cli"]
+    AGENT --> CLI["agenteye --json incidents ack ..."]
+    CLI -->|la tua sessione CLI autenticata| API["API dashboard Osservabilità"]
+```
+
+### vs. assistente AI nella dashboard: una distinzione importante
+
+Questi sono due strumenti diversi con raggi di esplosione molto diversi:
+
+- L'**assistente AI nella dashboard** ([Assistente AI](/it/agenteye/assistant)) è una chat incorporata nella dashboard, supportata dal servizio agente. È **di sola lettura più authoring controllato dall'approvazione**: può bozze salvate query e dashboard, ma ogni scrittura si ferma per la tua approvazione esplicita cliccabile, e non cancella mai. È controllato dall'autorizzazione `agent:use` e vede solo i dati dell'organizzazione che stai visualizzando.
+- La **competenza CLI** viene eseguita sulla *tua* workstation dentro *il tuo* agente di codifica e guida la CLI `agenteye` come **tu**. Può eseguire la **superficie completa, incluse le mutazioni** (create/ruota/disabilita chiavi API, cambia impostazioni org, risolvi incident, elimina query salvate), limitato solo dalle autorizzazioni del tuo accesso CLI. Trattala esattamente come faresti con l'esecuzione manuale di quei comandi.
+
+---
+
+## Prerequisiti
+
+1. La **CLI `agenteye` installata** e su `PATH` (vedi il riferimento [CLI](/it/agenteye/cli): `pipx install agenteye`).
+2. Il **tuo URL della dashboard impostato** (`AGENTEYE_DASHBOARD_URL`, o l'agente passa `--base-url`).
+3. Una **sessione autenticata**: esegui prima `agenteye login` tu stesso. La competenza **non può** completare l'accesso con codice monouso inviato per email; ti dirà di eseguire `agenteye login` se la sessione manca o è scaduta (codice di uscita CLI `4`).
+
+---
+
+## Dove trovarla
+
+La competenza è pubblicata nella raccolta di competenze pubbliche di Failproof AI:
+
+**[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli)
+
+Niente è controllato — il repository è pubblico e la competenza non ha bisogno di credenziali proprie, perché guida solo la CLI `agenteye` **pubblica** contro *la tua* dashboard, usando la sessione in cui *tu* hai effettuato l'accesso. Non devi chiedere a nessuno.
+
+Nota che viene spedita come sua propria cartella e **non** si trova all'interno del pacchetto `pipx install agenteye`, quindi non cercarla lì.
+
+## Installazione della competenza
+
+Il percorso più veloce è la CLI [`skills`](https://skills.sh), che recupera la cartella e la mette dove il tuo agente guarda:
+
+```bash
+# Claude Code, questo progetto solo
+npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code
+
+# ogni progetto (installa in ~/.claude/skills/)
+npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy
+
+# Codex invece
+npx skills add FailproofAI/skills --skill agenteye-cli -a codex
+```
+
+Quindi gestiscila come qualsiasi altra competenza:
+
+```bash
+npx skills list -a claude-code      # cosa è installato
+npx skills update agenteye-cli      # tira l'ultima versione
+npx skills remove agenteye-cli      # rimuovila
+```
+
+Preferisci installare a mano? Un'Agent Skill è solo una cartella contenente un `SKILL.md` (più riferimenti opzionali), quindi copiarla funziona:
+
+- **Claude Code**: metti la cartella `agenteye-cli/` in `~/.claude/skills/` (ogni progetto) o `<your-repo>/.claude/skills/` (solo quel repository). Claude Code la scopre automaticamente — verifica con la lista `/skills`, o semplicemente fai una domanda che corrisponde alla sua descrizione.
+- **Codex (OpenAI)**: Codex legge lo stesso `SKILL.md`. Il `agents/openai.yaml` in bundle imposta `allow_implicit_invocation: true`, quindi Codex seleziona automaticamente la competenza quando un'attività corrisponde; altrimenti invocala esplicitamente come `$agenteye-cli`.
+
+---
+
+## Sicurezza: le mutazioni NON chiedono conferma quando un agente esegue la CLI
+
+> **Avvertenza:** Leggi questo prima di lasciare che un agente faccia cambiamenti.
+
+La CLI `agenteye` normalmente chiede *"sei sicuro?"* prima di un'azione distruttiva. **Salta automaticamente quella conferma ogni volta che non è collegata a un terminale (che è esattamente come un agente di codifica la esegue), e `--json` la salta anche.** Quindi il prompt di sicurezza **non** attiverà per l'agente.
+
+La competenza è scritta per compensare: le è stato insegnato di dichiarare il comando esatto che eseguirà e ottenere il tuo **OK esplicito prima di qualsiasi cambio di stato**. Mantieni quella disciplina. Quando guidi Osservabilità Failproof AI attraverso un agente, *tu* sei il passo di conferma. I comandi che cambiano lo stato da osservare:
+
+- `keys create` / `update` / `disable` / `regenerate`
+- `users create` / `update` / `disable` / `enable`
+- `settings set`
+- `alerts create` / `update` / `delete` / `test`
+- i sottocomandi di scrittura `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe`
+- `query create` / `update` / `delete`
+- `agent rename` / `delete`
+- `orgs switch`
+
+Tutto sotto **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) è di sola lettura e non cambia nulla.
+
+Poiché l'agente agisce come **tu**, può fare solo ciò che il tuo accesso è autorizzato a fare; le autorizzazioni vengono risolte **per organizzazione** (vedi [Chiavi API](/it/agenteye/api-keys)). Un comando per il quale non hai autorizzazione restituisce il codice di uscita `5` con l'autorizzazione esatta denominata, quindi l'agente può dirti precisamente cosa chiedere a un amministratore invece di fallire oscuramente.
+
+---
+
+## Cosa puoi chiederle
+
+Ecco come appare un vero scambio, una lettura, quindi un cambio che attende il tuo OK:
+
+```text
+tu    ▸ C'è qualcosa di rotto nell'ultimo giorno?
+
+agente ▸ Esecuzione: agenteye --json errors --since 24h --aggregate
+         3 tipi di errore nelle ultime 24h. Il più grande è TimeoutError
+         (18 hit, tutti su checkout-agent), poi RateLimited (5).
+         Vuoi le sessioni fallite per TimeoutError?
+
+tu    ▸ Dai a CI una chiave che può solo inviare eventi.
+
+agente ▸ Questo crea una chiave API. Eseguirò:
+         agenteye keys create ci --add events:add
+         OK per procedere?
+
+tu    ▸ sì
+
+agente ▸ Fatto. Chiave "ci" creata con solo events:add.
+         Il segreto viene mostrato solo una volta, quindi salvalo ora. Non posso ristamparlo.
+```
+
+La competenza mappa ogni intento in linguaggio naturale al giusto comando `agenteye`, scoprendo prima i valori validi (`list <kind>`, `whoami`) quindi non indovina, e dichiara il comando esatto prima di qualsiasi cambio. Altri esempi:
+
+- *"C'è qualcosa di rotto / fallito nelle ultime 24 ore?"* → `errors --since 24h --aggregate`, poi un breakdown.
+- *"Perché la sessione `run-001` ha fallito?"* → `events --session-id run-001 --all` + `evals --session-id run-001`.
+- *"Come sta andando la qualità questa settimana?"* → `evals --aggregate --since 7d`, poi approfondisci nei run con punteggio basso.
+- *"Dai a CI una chiave che può solo inviare eventi."* → `keys create ci --add events:add` (dichiara il comando, lo crea e cattura il segreto monouso).
+- *"Chi ha accesso? Rendi Dana di sola lettura."* → `users list` → `users update dana@… --permission-set read-only` (dopo confirmare con te).
+- *"Conferma l'incident in corso e assegnalo a me."* → `incidents list --state firing` → `incidents ack <id>` / `incidents assign <id> you@…`.
+
+Per i comandi esatti, flag e forme JSON dietro questi, vedi il riferimento [CLI](/it/agenteye/cli) e [Ricette CLI per agenti](/it/agenteye/cli-recipes).
+
+---
+
+## Prossimi passi
+
+- **[CLI](/it/agenteye/cli)**: riferimento completo di comando e flag per `agenteye`.
+- **[Ricette CLI per agenti](/it/agenteye/cli-recipes)**: pattern `jq` da copiare e incollare e gestione del codice di uscita.
+- **[Competenza agente Evaluator](/it/agenteye/evaluator-skill)**: la competenza gemella, per costruire l'evaluator i cui punteggi `agenteye evals` legge.
+- **[Competenza agente Python SDK](/it/agenteye/python-sdk-skill)**: la competenza gemella, per strumentare un agente in modo che emetta la telemetria che `agenteye` legge.
+- **[Assistente AI](/it/agenteye/assistant)**: l'assistente nella dashboard (da non confondere con questa competenza di terminale).
+- **[Chiavi API](/it/agenteye/api-keys)**: il modello di autorizzazione per organizzazione che limita quello che la competenza può fare.