failproofai 0.0.6-beta.1 → 0.0.6-beta.2

package/.next/standalone/docs/it/custom-policies.mdx

@@ -1,14 +1,14 @@
 ---
-title: Politiche personalizzate
-description: "Scrivi le tue politiche in JavaScript - applica convenzioni, previeni derive, rileva guasti, integrati con sistemi esterni"
+title: Policy Personalizzate
+description: "Scrivi le tue regole in JavaScript - applica convenzioni, previeni derive, rileva errori, integra con sistemi esterni"
 icon: code
 ---
 
-Le politiche personalizzate ti permettono di scrivere regole per qualsiasi comportamento dell'agente: applica convenzioni di progetto, previeni derive, blocca operazioni distruttive, rileva agenti bloccati, oppure integrati con Slack, flussi di approvazione e altro. Utilizzano lo stesso sistema di eventi hook e le stesse decisioni `allow`, `deny`, `instruct` delle politiche integrate.
+Le policy personalizzate ti permettono di scrivere regole per qualsiasi comportamento dell'agente: applicare convenzioni di progetto, prevenire derive, bloccare operazioni distruttive, rilevare agenti bloccati, o integrarsi con Slack, workflow di approvazione e altro. Utilizzano lo stesso sistema di eventi hook e le decisioni `allow`, `deny`, `instruct` delle policy built-in.
 
 ---
 
-## Esempio rapido
+## Esempio veloce
 
 ```js
 // my-policies.js
@@ -37,14 +37,14 @@ failproofai policies --install --custom ./my-policies.js
 
 ---
 
-## Due modi per caricare politiche personalizzate
+## Due modi per caricare policy personalizzate
 
 ### Opzione 1: Basata su convenzione (consigliato)
 
-Inserisci file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e verranno caricati automaticamente — nessun flag o modifica della configurazione necessari. Funziona come i git hook: inserisci un file, e semplicemente funziona.
+Posiziona file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e vengono caricati automaticamente — nessun flag o modifica di configurazione necessaria. Funziona come i git hook: aggiungi un file, e semplicemente funziona.
 
 ```
-# Livello di progetto — commesso in git, condiviso con il team
+# Livello di progetto — committato su git, condiviso con il team
 .failproofai/policies/security-policies.mjs
 .failproofai/policies/workflow-policies.mjs
 
@@ -53,38 +53,38 @@ Inserisci file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e verranno ca
 ```
 
 **Come funziona:**
-- Entrambe le directory di progetto e utente vengono scansionate (unione — non vince il primo ambito)
+- Entrambe le directory di progetto e utente sono scansionate (unione — non first-scope-wins)
 - I file vengono caricati alfabeticamente all'interno di ogni directory. Aggiungi il prefisso `01-`, `02-` per controllare l'ordine
-- Solo i file che corrispondono a `*policies.{js,mjs,ts}` vengono caricati; gli altri file vengono ignorati
+- Solo i file corrispondenti a `*policies.{js,mjs,ts}` vengono caricati; altri file vengono ignorati
 - Ogni file viene caricato indipendentemente (fail-open per file)
-- Funziona insieme alle politiche esplicite `--custom` e a quelle integrate
+- Funziona insieme a policy `--custom` esplicite e built-in
 
 <Tip>
-Le politiche di convenzione sono il modo più semplice per condividere politiche in un team. Esegui il commit di `.failproofai/policies/` in git e ogni membro del team le otterrà automaticamente.
+Le policy per convenzione sono il modo più semplice per creare uno standard di qualità per la tua organizzazione. Committa `.failproofai/policies/` su git e ogni membro del team ottiene automaticamente le stesse regole — nessuna configurazione per-sviluppatore necessaria. Man mano che il tuo team scopre nuove modalità di errore, aggiungi una policy e fai push. Nel tempo queste diventano uno standard di qualità vivente che migliora continuamente con ogni contributo.
 </Tip>
 
 ### Opzione 2: Percorso file esplicito
 
 ```bash
-# Installa con un file di politiche personalizzate
+# Installa con un file di policy personalizzate
 failproofai policies --install --custom ./my-policies.js
 
-# Sostituisci il percorso del file di politiche
+# Sostituisci il percorso del file di policy
 failproofai policies --install --custom ./new-policies.js
 
-# Rimuovi il percorso delle politiche personalizzate dalla configurazione
+# Rimuovi il percorso delle policy personalizzate dalla configurazione
 failproofai policies --uninstall --custom
 ```
 
-Il percorso assoluto risolto viene memorizzato in `policies-config.json` come `customPoliciesPath`. Il file viene caricato nuovamente ad ogni evento hook - non esiste cache tra gli eventi.
+Il percorso assoluto risolto viene archiviato in `policies-config.json` come `customPoliciesPath`. Il file viene caricato di nuovo ad ogni evento hook - non c'è caching tra gli eventi.
 
 ### Usare entrambi insieme
 
-Le politiche di convenzione e il file esplicito `--custom` possono coesistere. Ordine di caricamento:
+Le policy per convenzione e il file `--custom` esplicito possono coesistere. Ordine di caricamento:
 
 1. File `customPoliciesPath` esplicito (se configurato)
-2. File di convenzione di progetto (`{cwd}/.failproofai/policies/`, alfabetico)
-3. File di convenzione utente (`~/.failproofai/policies/`, alfabetico)
+2. File per convenzione di progetto (`{cwd}/.failproofai/policies/`, alfabetico)
+3. File per convenzione utente (`~/.failproofai/policies/`, alfabetico)
 
 ---
 
@@ -98,7 +98,7 @@ import { customPolicies, allow, deny, instruct } from "failproofai";
 
 ### `customPolicies.add(hook)`
 
-Registra una politica. Chiama questo metodo tutte le volte che è necessario per più politiche nello stesso file.
+Registra una policy. Chiama questa funzione tutte le volte necessarie per più policy nello stesso file.
 
 ```ts
 customPolicies.add({
@@ -109,34 +109,34 @@ customPolicies.add({
 });
 ```
 
-### Helper per decisioni
+### Decision helpers
 
 | Funzione | Effetto | Usare quando |
-|----------|---------|----------|
-| `allow()` | Consenti l'operazione silenziosamente | L'azione è sicura, nessun messaggio necessario |
-| `deny(message)` | Blocca l'operazione | L'agente non dovrebbe intraprendere questa azione |
-| `instruct(message)` | Aggiungi contesto senza bloccare | Fornisci all'agente contesto extra per restare in pista |
+|----------|--------|----------|
+| `allow()` | Permetti l'operazione silenziosamente | L'azione è sicura, nessun messaggio necessario |
+| `deny(message)` | Blocca l'operazione | L'agente non dovrebbe eseguire questa azione |
+| `instruct(message)` | Aggiungi contesto senza bloccare | Dai all'agente contesto extra per rimanere in traccia |
 
-`deny(message)` - il messaggio appare a Claude con prefisso `"Blocked by failproofai:"`. Un singolo `deny` interrompe la valutazione successiva.
+`deny(message)` - il messaggio appare a Claude con prefisso `"Blocked by failproofai:"`. Un singolo `deny` interrompe tutta la valutazione successiva.
 
 `instruct(message)` - il messaggio viene aggiunto al contesto di Claude per la chiamata dello strumento corrente. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme.
 
 <Tip>
-Puoi aggiungere guidance extra a qualsiasi messaggio `deny` o `instruct` aggiungendo un campo `hint` in `policyParams` — nessuna modifica del codice necessaria. Questo funziona anche per le politiche personalizzate (`custom/`), di convenzione di progetto (`.failproofai-project/`), e di convenzione utente (`.failproofai-user/`). Vedi [Configuration → hint](/it/configuration#hint-cross-cutting) per dettagli.
+Puoi aggiungere guida extra a qualsiasi messaggio `deny` o `instruct` aggiungendo un campo `hint` in `policyParams` — nessuna modifica del codice necessaria. Questo funziona per policy personalizzate (`custom/`), per convenzione di progetto (`.failproofai-project/`), e per convenzione utente (`.failproofai-user/`) anche. Vedi [Configuration → hint](/it/configuration#hint-cross-cutting) per i dettagli.
 </Tip>
 
-### Messaggi informativi di consenso
+### Messaggi allow informativi
 
-`allow(message)` consente l'operazione **e** invia un messaggio informativo a Claude. Il messaggio viene consegnato come `additionalContext` nella risposta stdout del gestore hook — lo stesso meccanismo utilizzato da `instruct`, ma semanticamente diverso: è un aggiornamento di stato, non un avviso.
+`allow(message)` permette l'operazione **e** invia un messaggio informativo indietro a Claude. Il messaggio viene consegnato come `additionalContext` nella risposta stdout del gestore hook — lo stesso meccanismo usato da `instruct`, ma semanticamente diverso: è un aggiornamento di stato, non un avviso.
 
 | Funzione | Effetto | Usare quando |
-|----------|---------|----------|
-| `allow(message)` | Consenti e invia contesto a Claude | Conferma che un controllo è stato superato, o spiega perché un controllo è stato saltato |
+|----------|--------|----------|
+| `allow(message)` | Permetti e invia contesto a Claude | Conferma che un controllo è passato, o spiega perché un controllo è stato saltato |
 
 Casi d'uso:
 - **Conferme di stato:** `allow("All CI checks passed.")` — dice a Claude che tutto è verde
-- **Spiegazioni fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — dice a Claude perché un controllo è stato saltato in modo da avere il contesto completo
-- **Più messaggi si accumulano:** se diverse politiche restituiscono `allow(message)`, tutti i messaggi vengono uniti con newline e consegnati insieme
+- **Spiegazioni fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — dice a Claude perché un controllo è stato saltato così ha il contesto completo
+- **Più messaggi si accumulano:** se più policy ciascuna restituisce `allow(message)`, tutti i messaggi vengono uniti con newline e consegnati insieme
 
 ```js
 customPolicies.add({
@@ -160,9 +160,9 @@ customPolicies.add({
 | Campo | Tipo | Descrizione |
 |-------|------|-------------|
 | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | Lo strumento che viene chiamato (es. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolName` | `string \| undefined` | Lo strumento in corso di chiamata (es. `"Bash"`, `"Write"`, `"Read"`) |
 | `toolInput` | `Record<string, unknown> \| undefined` | I parametri di input dello strumento |
-| `payload` | `Record<string, unknown>` | Payload dell'evento grezzo completo da Claude Code |
+| `payload` | `Record<string, unknown>` | Payload evento grezzo completo da Claude Code |
 | `session` | `SessionMetadata \| undefined` | Contesto della sessione (vedi sotto) |
 
 ### Campi `SessionMetadata`
@@ -175,33 +175,33 @@ customPolicies.add({
 
 ### Tipi di evento
 
-| Evento | Quando viene attivato | Contenuti `toolInput` |
-|--------|----------------------|-----|
+| Evento | Quando si attiva | Contenuti `toolInput` |
+|-------|--------------|----------------------|
 | `PreToolUse` | Prima che Claude esegua uno strumento | L'input dello strumento (es. `{ command: "..." }` per Bash) |
 | `PostToolUse` | Dopo che uno strumento si completa | L'input dello strumento + `tool_result` (l'output) |
-| `Notification` | Quando Claude invia una notifica | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - i hook devono sempre restituire `allow()`, non possono bloccare le notifiche |
+| `Notification` | Quando Claude invia una notifica | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - gli hook devono sempre restituire `allow()`, non possono bloccare le notifiche |
 | `Stop` | Quando la sessione Claude termina | Vuoto |
 
 ---
 
 ## Ordine di valutazione
 
-Le politiche vengono valutate in questo ordine:
+Le policy vengono valutate in questo ordine:
 
-1. Politiche integrate (in ordine di definizione)
-2. Politiche personalizzate esplicite da `customPoliciesPath` (in ordine `.add()`)
-3. Politiche di convenzione da progetto `.failproofai/policies/` (file alfabetico, ordine `.add()` all'interno)
-4. Politiche di convenzione da utente `~/.failproofai/policies/` (file alfabetico, ordine `.add()` all'interno)
+1. Policy built-in (in ordine di definizione)
+2. Policy personalizzate esplicite da `customPoliciesPath` (in ordine `.add()`)
+3. Policy per convenzione dal progetto `.failproofai/policies/` (file alfabetico, ordine `.add()` interno)
+4. Policy per convenzione dall'utente `~/.failproofai/policies/` (file alfabetico, ordine `.add()` interno)
 
 <Note>
-Il primo `deny` interrompe tutte le politiche successive. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme.
+Il primo `deny` interrompe tutte le policy successive. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme.
 </Note>
 
 ---
 
 ## Import transitivi
 
-I file di politiche personalizzate possono importare moduli locali utilizzando percorsi relativi:
+I file di policy personalizzate possono importare moduli locali usando percorsi relativi:
 
 ```js
 // my-policies.js
@@ -222,42 +222,42 @@ Tutti gli import relativi raggiungibili dal file di entry vengono risolti. Quest
 
 ---
 
-## Filtraggio per tipo di evento
+## Filtraggio del tipo di evento
 
-Usa `match.events` per limitare quando una politica si attiva:
+Usa `match.events` per limitare quando una policy si attiva:
 
 ```js
 customPolicies.add({
   name: "require-summary-on-stop",
   match: { events: ["Stop"] },
   fn: async (ctx) => {
-    // Si attiva solo quando la sessione termina
-    // ctx.session.transcriptPath contiene il log della sessione completa
+    // Only fires when the session ends
+    // ctx.session.transcriptPath contains the full session log
     return allow();
   },
 });
 ```
 
-Ometti completamente `match` per attivarsi su ogni tipo di evento.
+Ometti `match` completamente per attivare su ogni tipo di evento.
 
 ---
 
-## Gestione degli errori e modalità di fallimento
+## Gestione degli errori e modalità di guasto
 
-Le politiche personalizzate sono **fail-open**: gli errori non bloccano mai le politiche integrate o bloccano il gestore hook.
+Le policy personalizzate sono **fail-open**: gli errori non bloccheranno mai le policy built-in o crasheranno il gestore hook.
 
-| Errore | Comportamento |
-|--------|----------|
-| `customPoliciesPath` non impostato | Nessuna politica personalizzata esplicita viene eseguita; le politiche di convenzione e gli integrati continuano normalmente |
-| File non trovato | Avviso registrato in `~/.failproofai/hook.log`; gli integrati continuano |
-| Errore di sintassi/import (esplicito) | Errore registrato in `~/.failproofai/hook.log`; le politiche personalizzate esplicite vengono saltate |
-| Errore di sintassi/import (convenzione) | Errore registrato; quel file viene saltato, gli altri file di convenzione vengono ancora caricati |
-| `fn` genera errore a runtime | Errore registrato; quel hook viene trattato come `allow`; altri hook continuano |
+| Guasto | Comportamento |
+|---------|----------|
+| `customPoliciesPath` non impostato | Nessuna policy personalizzata esplicita viene eseguita; le policy per convenzione e le built-in continuano normalmente |
+| File non trovato | Avviso registrato in `~/.failproofai/hook.log`; le built-in continuano |
+| Errore di sintassi/import (esplicito) | Errore registrato in `~/.failproofai/hook.log`; le policy personalizzate esplicite vengono saltate |
+| Errore di sintassi/import (convenzione) | Errore registrato; quel file viene saltato, altri file per convenzione si caricano ancora |
+| `fn` lancia a runtime | Errore registrato; quell'hook viene trattato come `allow`; altri hook continuano |
 | `fn` impiega più di 10s | Timeout registrato; trattato come `allow` |
-| Directory di convenzione mancante | Nessuna politica di convenzione viene eseguita; nessun errore |
+| Directory per convenzione mancante | Nessuna policy per convenzione viene eseguita; nessun errore |
 
 <Tip>
-Per eseguire il debug degli errori di politiche personalizzate, osserva il file di log:
+Per debuggare gli errori delle policy personalizzate, guarda il file log:
 
 ```bash
 tail -f ~/.failproofai/hook.log
@@ -266,7 +266,7 @@ tail -f ~/.failproofai/hook.log
 
 ---
 
-## Esempio completo: più politiche
+## Esempio completo: policy multiple
 
 ```js
 // my-policies.js
@@ -323,22 +323,22 @@ export { customPolicies };
 
 ## Esempi
 
-La directory `examples/` contiene file di politiche pronti all'uso:
+La directory `examples/` contiene file di policy pronti all'esecuzione:
 
 | File | Contenuti |
 |------|----------|
-| `examples/policies-basic.js` | Cinque politiche iniziali che coprono modalità di fallimento comuni dell'agente |
-| `examples/policies-advanced/index.js` | Pattern avanzati: import transitivi, chiamate async, scrubbing dell'output, e hook di fine sessione |
-| `examples/convention-policies/security-policies.mjs` | Politiche di sicurezza basate su convenzione (blocca scritture .env, previeni riscrittura della cronologia git) |
-| `examples/convention-policies/workflow-policies.mjs` | Politiche di flusso di lavoro basate su convenzione (promemoria test, controllare scritture di file) |
+| `examples/policies-basic.js` | Cinque policy per iniziare che coprono modalità di guasto comuni dell'agente |
+| `examples/policies-advanced/index.js` | Pattern avanzati: import transitivi, chiamate async, output scrubbing, e hook di fine sessione |
+| `examples/convention-policies/security-policies.mjs` | Policy di sicurezza basate su convenzione (blocca scritture .env, previeni riscrittura della cronologia git) |
+| `examples/convention-policies/workflow-policies.mjs` | Policy di workflow basate su convenzione (promemoria test, file di audit writes) |
 
-### Uso di esempi di file espliciti
+### Usando esempi di file espliciti
 
 ```bash
 failproofai policies --install --custom ./examples/policies-basic.js
 ```
 
-### Uso di esempi basati su convenzione
+### Usando esempi basati su convenzione
 
 ```bash
 # Copy to project level
@@ -350,4 +350,4 @@ mkdir -p ~/.failproofai/policies
 cp examples/convention-policies/*.mjs ~/.failproofai/policies/
 ```
 
-Nessun comando install necessario — i file vengono ripresi automaticamente al prossimo evento hook.
+Nessun comando di installazione necessario — i file vengono raccolti automaticamente al prossimo evento hook.

package/.next/standalone/docs/it/examples.mdx

@@ -1,16 +1,16 @@
 ---
 title: Esempi
-description: "Come configurare hook per Claude Code e Agents SDK"
+description: "Come configurare i hook per Claude Code e l'Agents SDK"
 icon: book-open
 ---
 
-Esempi pronti all'uso per scenari comuni. Ogni esempio mostra come installare e cosa aspettarsi.
+Esempi pronti all'uso per scenari comuni. Ognuno mostra come installare e cosa aspettarsi.
 
 ---
 
-## Configurazione di hook per Claude Code
+## Configurazione dei hook per Claude Code
 
-Failproof AI si integra con Claude Code tramite il suo [sistema di hook](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando esegui `failproofai policies --install`, registra comandi hook nel file `settings.json` di Claude Code che si attivano ad ogni chiamata di tool.
+Failproof AI si integra con Claude Code tramite il suo [sistema di hook](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando esegui `failproofai policies --install`, registra i comandi dei hook in `settings.json` di Claude Code che si attivano ad ogni chiamata di strumento.
 
 <Steps>
   <Step title="Installa failproofai">
@@ -18,32 +18,32 @@ Failproof AI si integra con Claude Code tramite il suo [sistema di hook](https:/
     npm install -g failproofai
     ```
   </Step>
-  <Step title="Abilita tutte le policy integrate">
+  <Step title="Abilita tutte le politiche integrate">
     ```bash
     failproofai policies --install
     ```
   </Step>
-  <Step title="Verifica che gli hook siano registrati">
+  <Step title="Verifica che i hook siano registrati">
     ```bash
     cat ~/.claude/settings.json | grep failproofai
     ```
 
-    Dovresti vedere voci di hook per gli eventi `PreToolUse`, `PostToolUse`, `Notification` e `Stop`.
+    Dovresti vedere le voci dei hook per gli eventi `PreToolUse`, `PostToolUse`, `Notification` e `Stop`.
   </Step>
   <Step title="Esegui Claude Code">
     ```bash
     claude
     ```
 
-    Le policy ora vengono eseguite automaticamente ad ogni chiamata di tool. Prova a chiedere a Claude di eseguire `sudo rm -rf /` - verrà bloccato.
+    Le politiche ora vengono eseguite automaticamente ad ogni chiamata di strumento. Prova a chiedere a Claude di eseguire `sudo rm -rf /` - verrà bloccato.
   </Step>
 </Steps>
 
 ---
 
-## Configurazione di hook per Agents SDK
+## Configurazione dei hook per l'Agents SDK
 
-Se stai costruendo con [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), puoi utilizzare lo stesso sistema di hook a livello programmatico.
+Se stai costruendo con l'[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), puoi usare lo stesso sistema di hook a livello programmatico.
 
 <Steps>
   <Step title="Installa failproofai nel tuo progetto">
@@ -51,33 +51,33 @@ Se stai costruendo con [Agents SDK](https://docs.anthropic.com/en/docs/agents-sd
     npm install failproofai
     ```
   </Step>
-  <Step title="Configura gli hook nel tuo agent">
-    Passa comandi hook quando crei il tuo processo agent. Gli hook si attivano allo stesso modo che in Claude Code - tramite JSON su stdin/stdout:
+  <Step title="Configura i hook nel tuo agent">
+    Passa i comandi dei hook quando crei il tuo processo di agent. I hook si attivano allo stesso modo di Claude Code - tramite JSON su stdin/stdout:
 
     ```bash
-    failproofai --hook PreToolUse   # called before each tool
-    failproofai --hook PostToolUse  # called after each tool
+    failproofai --hook PreToolUse   # chiamato prima di ogni strumento
+    failproofai --hook PostToolUse  # chiamato dopo ogni strumento
     ```
   </Step>
-  <Step title="Scrivi una policy personalizzata per il tuo agent">
+  <Step title="Scrivi una politica personalizzata per il tuo agent">
     ```javascript
     import { customPolicies, allow, deny } from "failproofai";
 
     customPolicies.add({
       name: "limit-to-project-dir",
-      description: "Keep the agent inside the project directory",
+      description: "Mantieni l'agent all'interno della directory del progetto",
       match: { events: ["PreToolUse"] },
       fn: async (ctx) => {
         const path = String(ctx.toolInput?.file_path ?? "");
         if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
-          return deny("Agent is restricted to the project directory");
+          return deny("L'agent è limitato alla directory del progetto");
         }
         return allow();
       },
     });
     ```
   </Step>
-  <Step title="Installa la policy personalizzata">
+  <Step title="Installa la politica personalizzata">
     ```bash
     failproofai policies --install --custom ./my-agent-policies.js
     ```
@@ -88,7 +88,7 @@ Se stai costruendo con [Agents SDK](https://docs.anthropic.com/en/docs/agents-sd
 
 ## Blocca i comandi distruttivi
 
-La configurazione più comune - impedisci agli agent di causare danni irreversibili.
+La configurazione più comune - previeni agli agent di causare danni irreversibili.
 
 ```bash
 failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
@@ -104,45 +104,45 @@ Cosa fa:
 
 ## Previeni la perdita di segreti
 
-Impedisci agli agent di vedere o perdere credenziali nell'output dei tool.
+Impedisci agli agent di visualizzare o perdere credenziali nell'output dello strumento.
 
 ```bash
 failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
 ```
 
-Queste si attivano su `PostToolUse` - dopo che uno strumento viene eseguito, puliscono l'output prima che l'agent lo veda.
+Questi si attivano su `PostToolUse` - dopo che uno strumento è stato eseguito, ripuliscono l'output prima che l'agent lo veda.
 
 ---
 
 ## Ricevi avvisi Slack quando gli agent hanno bisogno di attenzione
 
-Utilizza l'hook di notifica per inviare gli avvisi di inattività a Slack.
+Usa l'hook di notifica per inoltrare gli avvisi di inattività a Slack.
 
 ```javascript
 import { customPolicies, allow, instruct } from "failproofai";
 
 customPolicies.add({
   name: "slack-on-idle",
-  description: "Alert Slack when the agent is waiting for input",
+  description: "Avvisa Slack quando l'agent è in attesa di input",
   match: { events: ["Notification"] },
   fn: async (ctx) => {
     const webhookUrl = process.env.SLACK_WEBHOOK_URL;
     if (!webhookUrl) return allow();
 
-    const message = String(ctx.payload?.message ?? "Agent is waiting");
-    const project = ctx.session?.cwd ?? "unknown";
+    const message = String(ctx.payload?.message ?? "L'agent è in attesa");
+    const project = ctx.session?.cwd ?? "sconosciuto";
 
     try {
       await fetch(webhookUrl, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          text: `*${message}*\nProject: \`${project}\``,
+          text: `*${message}*\nProgetto: \`${project}\``,
         }),
         signal: AbortSignal.timeout(5000),
       });
     } catch {
-      // never block the agent if Slack is unreachable
+      // non bloccare mai l'agent se Slack non è raggiungibile
     }
 
     return allow();
@@ -160,20 +160,20 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c
 
 ## Mantieni gli agent su un branch
 
-Impedisci agli agent di cambiare branch o fare push su quelli protetti.
+Previeni agli agent di cambiare branch o fare push a quelli protetti.
 
 ```javascript
 import { customPolicies, allow, deny } from "failproofai";
 
 customPolicies.add({
   name: "stay-on-branch",
-  description: "Prevent the agent from checking out other branches",
+  description: "Impedisci all'agent di fare checkout di altri branch",
   match: { events: ["PreToolUse"] },
   fn: async (ctx) => {
     if (ctx.toolName !== "Bash") return allow();
     const cmd = String(ctx.toolInput?.command ?? "");
     if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
-      return deny("Stay on the current branch. Create a new branch with -b if needed.");
+      return deny("Rimani sul branch corrente. Crea un nuovo branch con -b se necessario.");
     }
     return allow();
   },
@@ -182,7 +182,7 @@ customPolicies.add({
 
 ---
 
-## Richiedi test prima dei commit
+## Richiedi i test prima dei commit
 
 Ricorda agli agent di eseguire i test prima di fare commit.
 
@@ -191,13 +191,13 @@ import { customPolicies, allow, instruct } from "failproofai";
 
 customPolicies.add({
   name: "test-before-commit",
-  description: "Remind the agent to run tests before committing",
+  description: "Ricorda all'agent di eseguire i test prima di fare commit",
   match: { events: ["PreToolUse"] },
   fn: async (ctx) => {
     if (ctx.toolName !== "Bash") return allow();
     const cmd = String(ctx.toolInput?.command ?? "");
     if (/git\s+commit/.test(cmd)) {
-      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
+      return instruct("Esegui i test prima di fare commit. Usa prima `npm test` o `bun test`.");
     }
     return allow();
   },
@@ -206,9 +206,9 @@ customPolicies.add({
 
 ---
 
-## Proteggi un repository di produzione
+## Blocca un repository di produzione
 
-Fai il commit di una config a livello di progetto in modo che ogni sviluppatore del tuo team ottenga le stesse policy.
+Commit una configurazione a livello di progetto in modo che ogni sviluppatore del tuo team ottenga le stesse politiche.
 
 Crea `.failproofai/policies-config.json` nel tuo repository:
 
@@ -235,19 +235,73 @@ Poi fai il commit:
 
 ```bash
 git add .failproofai/policies-config.json
-git commit -m "Add failproofai team policies"
+git commit -m "Aggiungi politiche failproofai del team"
 ```
 
 Ogni membro del team che ha failproofai installato raccoglierà automaticamente queste regole.
 
 ---
 
+## Costruisci uno standard di qualità a livello di organizzazione con politiche di convenzione
+
+La configurazione più impattante: commit `.failproofai/policies/` nel tuo repository con politiche personalizzate per il tuo progetto. Ogni membro del team le ottiene automaticamente — nessun comando di installazione, nessun cambiamento di configurazione.
+
+<Steps>
+  <Step title="Crea la directory e aggiungi le politiche">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    // Applica il package manager preferito del tuo team
+    // (o abilita invece la politica integrata prefer-package-manager)
+    customPolicies.add({
+      name: "enforce-bun",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        const cmd = String(ctx.toolInput?.command ?? "");
+        if (/\bnpm\b/.test(cmd)) return deny("Usa bun invece di npm.");
+        return allow();
+      },
+    });
+
+    // Ricorda all'agent di eseguire i test prima di fare commit
+    customPolicies.add({
+      name: "test-before-commit",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
+          return instruct("Esegui i test prima di fare commit.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Commit su git">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Aggiungi politiche di qualità del team"
+    ```
+  </Step>
+  <Step title="Continua a migliorare">
+    Mentre il tuo team incontra nuove modalità di fallimento, aggiungi politiche e fai push. Tutti ricevono l'aggiornamento al loro prossimo `git pull`. Queste politiche diventano uno standard di qualità vivo che cresce con il tuo team.
+  </Step>
+</Steps>
+
+---
+
 ## Altri esempi
 
 La directory [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) nel repository contiene:
 
 | File | Cosa mostra |
-|------|-------------|
-| `policies-basic.js` | Policy di base - blocca scritture in produzione, force-push, script pipati |
-| `policies-notification.js` | Avvisi Slack per notifiche di inattività e fine sessione |
+|------|---------------|
+| `policies-basic.js` | Politiche di avvio - blocca le scritture di produzione, force-push, script in pipe |
+| `policies-notification.js` | Avvisi Slack per notifiche di inattività e fine della sessione |
 | `policies-advanced/index.js` | Import transitivi, hook asincroni, scrubbing dell'output PostToolUse, gestione dell'evento Stop |