failproofai 0.0.5 → 0.0.6-beta.1

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

@@ -1,10 +1,10 @@
 ---
 title: Benutzerdefinierte Richtlinien
-description: "Schreiben Sie eigene Richtlinien in JavaScript – Konventionen durchsetzen, Drift verhindern, Fehler erkennen, externe Systeme integrieren"
+description: "Schreibe eigene Richtlinien in JavaScript – Konventionen durchsetzen, Drift verhindern, Fehler erkennen, externe Systeme integrieren"
 icon: code
 ---
 
-Benutzerdefinierte Richtlinien ermöglichen es Ihnen, Regeln für jedes Agentenverhalten zu definieren: Projektkonventionen durchsetzen, Drift verhindern, destruktive Operationen absichern, feststeckende Agenten erkennen oder Slack, Genehmigungsworkflows und mehr integrieren. Sie verwenden dasselbe Hook-Ereignissystem und dieselben `allow`-, `deny`- und `instruct`-Entscheidungen wie eingebaute Richtlinien.
+Benutzerdefinierte Richtlinien ermöglichen es dir, Regeln für jedes Agentenverhalten zu schreiben: Projektkonventionen durchsetzen, Drift verhindern, destruktive Operationen absichern, feststeckende Agenten erkennen oder Slack, Genehmigungsworkflows und mehr integrieren. Sie verwenden dasselbe Hook-Event-System und dieselben `allow`-, `deny`-, `instruct`-Entscheidungen wie eingebaute Richtlinien.
 
 ---
 
@@ -29,7 +29,7 @@ customPolicies.add({
 });
 ```
 
-Installation:
+Installieren:
 
 ```bash
 failproofai policies --install --custom ./my-policies.js
@@ -37,14 +37,14 @@ failproofai policies --install --custom ./my-policies.js
 
 ---
 
-## Zwei Wege zum Laden benutzerdefinierter Richtlinien
+## Zwei Möglichkeiten, benutzerdefinierte Richtlinien zu laden
 
 ### Option 1: Konventionsbasiert (empfohlen)
 
-Legen Sie `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab – sie werden automatisch geladen, ohne Flags oder Konfigurationsänderungen. Das funktioniert wie Git-Hooks: Datei ablegen, fertig.
+Lege `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab – sie werden automatisch geladen, ohne Flags oder Konfigurationsänderungen. Das funktioniert wie Git-Hooks: Datei ablegen, fertig.
 
 ```
-# Projektebene – per Git eingecheckt, mit dem Team geteilt
+# Projektebene – in Git eingecheckt, mit dem Team geteilt
 .failproofai/policies/security-policies.mjs
 .failproofai/policies/workflow-policies.mjs
 
@@ -52,15 +52,15 @@ Legen Sie `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab – sie
 ~/.failproofai/policies/my-policies.mjs
 ```
 
-**So funktioniert es:**
-- Sowohl Projekt- als auch Benutzerverzeichnisse werden durchsucht (Vereinigung – kein Erster-gewinnt-Prinzip pro Scope)
-- Dateien werden innerhalb jedes Verzeichnisses alphabetisch geladen. Präfixe wie `01-`, `02-` steuern die Reihenfolge
-- Nur Dateien, die `*policies.{js,mjs,ts}` entsprechen, werden geladen; andere Dateien werden ignoriert
+**Funktionsweise:**
+- Sowohl Projekt- als auch Benutzerverzeichnisse werden durchsucht (Vereinigung – kein „erste Scope gewinnt")
+- Dateien werden innerhalb jedes Verzeichnisses alphabetisch geladen. Mit `01-`, `02-` als Präfix lässt sich die Reihenfolge steuern
+- Nur Dateien, die auf `*policies.{js,mjs,ts}` passen, werden geladen; andere Dateien werden ignoriert
 - Jede Datei wird unabhängig geladen (fail-open pro Datei)
 - Funktioniert zusammen mit explizitem `--custom` und eingebauten Richtlinien
 
 <Tip>
-Konventionsbasierte Richtlinien sind der einfachste Weg, Richtlinien im Team zu teilen. Checken Sie `.failproofai/policies/` per Git ein, und jedes Teammitglied erhält sie automatisch.
+Konventionsrichtlinien sind der einfachste Weg, Richtlinien im Team zu teilen. Checke `.failproofai/policies/` in Git ein und alle Teammitglieder erhalten sie automatisch.
 </Tip>
 
 ### Option 2: Expliziter Dateipfad
@@ -76,13 +76,13 @@ failproofai policies --install --custom ./new-policies.js
 failproofai policies --uninstall --custom
 ```
 
-Der aufgelöste absolute Pfad wird in `policies-config.json` als `customPoliciesPath` gespeichert. Die Datei wird bei jedem Hook-Ereignis neu geladen – es gibt kein Caching zwischen Ereignissen.
+Der aufgelöste absolute Pfad wird in `policies-config.json` als `customPoliciesPath` gespeichert. Die Datei wird bei jedem Hook-Event neu geladen – es gibt kein Caching zwischen Events.
 
-### Beide Methoden kombinieren
+### Beide Varianten kombiniert
 
-Konventionsbasierte Richtlinien und die explizite `--custom`-Datei können nebeneinander existieren. Ladereihenfolge:
+Konventionsrichtlinien und die explizite `--custom`-Datei können nebeneinander existieren. Ladereihenfolge:
 
-1. Explizite `customPoliciesPath`-Datei (falls konfiguriert)
+1. Explizite `customPoliciesPath`-Datei (sofern konfiguriert)
 2. Projekt-Konventionsdateien (`{cwd}/.failproofai/policies/`, alphabetisch)
 3. Benutzer-Konventionsdateien (`~/.failproofai/policies/`, alphabetisch)
 
@@ -98,13 +98,13 @@ import { customPolicies, allow, deny, instruct } from "failproofai";
 
 ### `customPolicies.add(hook)`
 
-Registriert eine Richtlinie. Kann beliebig oft aufgerufen werden, um mehrere Richtlinien in derselben Datei zu definieren.
+Registriert eine Richtlinie. Kann mehrfach aufgerufen werden, um mehrere Richtlinien in derselben Datei zu definieren.
 
 ```ts
 customPolicies.add({
   name: string;                         // erforderlich – eindeutiger Bezeichner
-  description?: string;                 // wird in der `failproofai policies`-Ausgabe angezeigt
-  match?: { events?: HookEventType[] }; // nach Ereignistyp filtern; weglassen für alle Ereignisse
+  description?: string;                 // erscheint in der `failproofai policies`-Ausgabe
+  match?: { events?: HookEventType[] }; // nach Event-Typ filtern; weglassen für alle Events
   fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
 });
 ```
@@ -115,29 +115,28 @@ customPolicies.add({
 |----------|---------|------------|
 | `allow()` | Operation lautlos zulassen | Die Aktion ist sicher, keine Meldung erforderlich |
 | `deny(message)` | Operation blockieren | Der Agent soll diese Aktion nicht ausführen |
-| `instruct(message)` | Kontext hinzufügen ohne zu blockieren | Dem Agenten zusätzlichen Kontext geben, um auf Kurs zu bleiben |
+| `instruct(message)` | Kontext hinzufügen ohne zu blockieren | Dem Agenten zusätzlichen Kontext geben, um ihn auf Kurs zu halten |
 
-`deny(message)` – die Nachricht erscheint gegenüber Claude mit dem Präfix `"Blocked by failproofai:"`. Ein einzelnes `deny` bricht die gesamte weitere Auswertung ab.
+`deny(message)` – die Nachricht erscheint für Claude mit dem Präfix `"Blocked by failproofai:"`. Ein einzelnes `deny` bricht alle weitere Auswertung ab.
 
-`instruct(message)` – die Nachricht wird dem Claude-Kontext für den aktuellen Tool-Aufruf angehängt. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam zugestellt.
+`instruct(message)` – die Nachricht wird dem Kontext von Claude für den aktuellen Tool-Aufruf angehängt. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam zugestellt.
 
 <Tip>
-Sie können jeder `deny`- oder `instruct`-Nachricht zusätzliche Hinweise hinzufügen, indem Sie ein `hint`-Feld in `policyParams` setzen – ohne Codeänderung. Das funktioniert auch für benutzerdefinierte (`custom/`), Projekt-Konventions- (`.failproofai-project/`) und Benutzer-Konventionsrichtlinien (`.failproofai-user/`). Siehe [Konfiguration → hint](/de/configuration#hint-cross-cutting) für Details.
+Zu jeder `deny`- oder `instruct`-Nachricht können zusätzliche Hinweise hinzugefügt werden, indem ein `hint`-Feld in `policyParams` gesetzt wird – ohne Codeänderung. Das funktioniert auch für benutzerdefinierte (`custom/`), Projekt-Konventions- (`.failproofai-project/`) und Benutzer-Konventionsrichtlinien (`.failproofai-user/`). Siehe [Konfiguration → hint](/de/configuration#hint-cross-cutting) für Details.
 </Tip>
 
-### Informative allow-Nachrichten
+### Informative Allow-Nachrichten
 
-
-`allow(message)` lässt die Operation zu **und** sendet eine informative Nachricht an Claude zurück. Die Nachricht wird als `additionalContext` in der stdout-Antwort des Hook-Handlers zugestellt – derselbe Mechanismus wie bei `instruct`, jedoch semantisch anders: Es handelt sich um eine Statusmeldung, nicht um eine Warnung.
+`allow(message)` erlaubt die Operation **und** sendet eine informative Nachricht zurück an Claude. Die Nachricht wird als `additionalContext` in der stdout-Antwort des Hook-Handlers zugestellt – derselbe Mechanismus wie bei `instruct`, aber semantisch anders: Es ist eine Statusmeldung, keine Warnung.
 
 | Funktion | Wirkung | Verwendung |
 |----------|---------|------------|
-| `allow(message)` | Zulassen und Kontext an Claude senden | Bestätigen, dass eine Prüfung bestanden wurde, oder erklären, warum eine Prüfung übersprungen wurde |
+| `allow(message)` | Zulassen und Kontext an Claude senden | Bestätigen, dass eine Prüfung bestanden wurde, oder erklären, warum sie übersprungen wurde |
 
 Anwendungsfälle:
-- **Statusbestätigungen:** `allow("All CI checks passed.")` – teilt Claude mit, dass alles in Ordnung ist
+- **Statusbestätigungen:** `allow("All CI checks passed.")` – teilt Claude mit, dass alles grün ist
 - **Fail-open-Erklärungen:** `allow("GitHub CLI not installed, skipping CI check.")` – erklärt Claude, warum eine Prüfung übersprungen wurde, damit er den vollen Kontext hat
-- **Mehrere Nachrichten werden gesammelt:** Wenn mehrere Richtlinien jeweils `allow(message)` zurückgeben, werden alle Nachrichten mit Zeilenumbrüchen verbunden und gemeinsam zugestellt
+- **Mehrere Nachrichten werden akkumuliert:** Geben mehrere Richtlinien je ein `allow(message)` zurück, werden alle Nachrichten mit Zeilenumbrüchen verbunden und gemeinsam zugestellt
 
 ```js
 customPolicies.add({
@@ -163,23 +162,23 @@ customPolicies.add({
 | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
 | `toolName` | `string \| undefined` | Das aufgerufene Tool (z. B. `"Bash"`, `"Write"`, `"Read"`) |
 | `toolInput` | `Record<string, unknown> \| undefined` | Die Eingabeparameter des Tools |
-| `payload` | `Record<string, unknown>` | Vollständige rohe Ereignis-Payload von Claude Code |
+| `payload` | `Record<string, unknown>` | Vollständiger roher Event-Payload von Claude Code |
 | `session` | `SessionMetadata \| undefined` | Sitzungskontext (siehe unten) |
 
 ### `SessionMetadata`-Felder
 
 | Feld | Typ | Beschreibung |
 |------|-----|--------------|
-| `sessionId` | `string` | Claude Code-Sitzungsbezeichner |
+| `sessionId` | `string` | Claude Code-Sitzungskennung |
 | `cwd` | `string` | Arbeitsverzeichnis der Claude Code-Sitzung |
 | `transcriptPath` | `string` | Pfad zur JSONL-Transkriptdatei der Sitzung |
 
-### Ereignistypen
+### Event-Typen
 
-| Ereignis | Wann es ausgelöst wird | Inhalt von `toolInput` |
-|----------|------------------------|------------------------|
+| Event | Wann es ausgelöst wird | Inhalt von `toolInput` |
+|-------|----------------------|----------------------|
 | `PreToolUse` | Bevor Claude ein Tool ausführt | Die Eingabe des Tools (z. B. `{ command: "..." }` für Bash) |
-| `PostToolUse` | Nachdem ein Tool abgeschlossen hat | Die Eingabe des Tools + `tool_result` (die Ausgabe) |
+| `PostToolUse` | Nachdem ein Tool abgeschlossen wurde | Die Eingabe des Tools + `tool_result` (die Ausgabe) |
 | `Notification` | Wenn Claude eine Benachrichtigung sendet | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` – Hooks müssen immer `allow()` zurückgeben, Benachrichtigungen können nicht blockiert werden |
 | `Stop` | Wenn die Claude-Sitzung endet | Leer |
 
@@ -219,13 +218,13 @@ customPolicies.add({
 });
 ```
 
-Alle relativen Importe, die von der Einstiegsdatei aus erreichbar sind, werden aufgelöst. Dies wird implementiert, indem `from "failproofai"`-Importe auf den tatsächlichen dist-Pfad umgeschrieben und temporäre `.mjs`-Dateien erstellt werden, um ESM-Kompatibilität sicherzustellen.
+Alle transitiv erreichbaren relativen Importe von der Einstiegsdatei werden aufgelöst. Dies wird umgesetzt, indem `from "failproofai"`-Importe auf den tatsächlichen dist-Pfad umgeschrieben und temporäre `.mjs`-Dateien erstellt werden, um ESM-Kompatibilität sicherzustellen.
 
 ---
 
-## Ereignistypfilterung
+## Event-Typ-Filterung
 
-Verwenden Sie `match.events`, um einzuschränken, wann eine Richtlinie ausgelöst wird:
+Mit `match.events` lässt sich einschränken, wann eine Richtlinie ausgelöst wird:
 
 ```js
 customPolicies.add({
@@ -239,13 +238,13 @@ customPolicies.add({
 });
 ```
 
-Lassen Sie `match` vollständig weg, um bei jedem Ereignistyp auszulösen.
+`match` ganz weglassen, um bei jedem Event-Typ auszulösen.
 
 ---
 
-## Fehlerbehandlung und Fehlermodi
+## Fehlerbehandlung und Fehlerverhalten
 
-Benutzerdefinierte Richtlinien sind **fail-open**: Fehler blockieren niemals eingebaute Richtlinien und bringen den Hook-Handler nicht zum Absturz.
+Benutzerdefinierte Richtlinien sind **fail-open**: Fehler blockieren niemals eingebaute Richtlinien oder bringen den Hook-Handler zum Absturz.
 
 | Fehler | Verhalten |
 |--------|-----------|
@@ -254,11 +253,11 @@ Benutzerdefinierte Richtlinien sind **fail-open**: Fehler blockieren niemals ein
 | Syntax-/Importfehler (explizit) | Fehler wird in `~/.failproofai/hook.log` protokolliert; explizite benutzerdefinierte Richtlinien werden übersprungen |
 | Syntax-/Importfehler (Konvention) | Fehler wird protokolliert; diese Datei wird übersprungen, andere Konventionsdateien werden weiterhin geladen |
 | `fn` wirft zur Laufzeit | Fehler wird protokolliert; dieser Hook wird als `allow` behandelt; andere Hooks laufen weiter |
-| `fn` dauert länger als 10s | Timeout wird protokolliert; als `allow` behandelt |
+| `fn` dauert länger als 10 s | Timeout wird protokolliert; wird als `allow` behandelt |
 | Konventionsverzeichnis fehlt | Keine Konventionsrichtlinien werden ausgeführt; kein Fehler |
 
 <Tip>
-Um Fehler in benutzerdefinierten Richtlinien zu debuggen, beobachten Sie die Log-Datei:
+Zum Debuggen von benutzerdefinierten Richtlinienfehlern die Log-Datei beobachten:
 
 ```bash
 tail -f ~/.failproofai/hook.log
@@ -267,7 +266,7 @@ tail -f ~/.failproofai/hook.log
 
 ---
 
-## Vollständiges Beispiel: mehrere Richtlinien
+## Vollständiges Beispiel: Mehrere Richtlinien
 
 ```js
 // my-policies.js
@@ -286,7 +285,7 @@ customPolicies.add({
   },
 });
 
-// Agenten auf Kurs halten: Tests vor dem Commit prüfen
+// Hält den Agenten auf Kurs: Tests vor dem Commit prüfen
 customPolicies.add({
   name: "remind-test-before-commit",
   description: "Keep the agent on track: verify tests pass before committing",
@@ -301,7 +300,7 @@ customPolicies.add({
   },
 });
 
-// Ungeplante Abhängigkeitsänderungen während des Freeze verhindern
+// Verhindert ungeplante Abhängigkeitsänderungen während des Freeze
 customPolicies.add({
   name: "dependency-freeze",
   description: "Prevent unplanned dependency changes during freeze period",
@@ -324,14 +323,14 @@ export { customPolicies };
 
 ## Beispiele
 
-Das Verzeichnis `examples/` enthält sofort ausführbare Richtliniendateien:
+Das Verzeichnis `examples/` enthält direkt ausführbare Richtliniendateien:
 
 | Datei | Inhalt |
 |-------|--------|
 | `examples/policies-basic.js` | Fünf Starter-Richtlinien für häufige Agenten-Fehlermodi |
-| `examples/policies-advanced/index.js` | Fortgeschrittene Muster: transitive Importe, asynchrone Aufrufe, Ausgabe-Bereinigung und Sitzungsende-Hooks |
-| `examples/convention-policies/security-policies.mjs` | Konventionsbasierte Sicherheitsrichtlinien (blockiert .env-Schreibzugriffe, verhindert Git-History-Umschreibung) |
-| `examples/convention-policies/workflow-policies.mjs` | Konventionsbasierte Workflow-Richtlinien (Test-Erinnerungen, Audit-Datei-Schreibzugriffe) |
+| `examples/policies-advanced/index.js` | Fortgeschrittene Muster: transitive Importe, asynchrone Aufrufe, Ausgabebereinigung und Sitzungsend-Hooks |
+| `examples/convention-policies/security-policies.mjs` | Konventionsbasierte Sicherheitsrichtlinien (blockiert .env-Schreibzugriffe, verhindert Umschreiben der Git-Historie) |
+| `examples/convention-policies/workflow-policies.mjs` | Konventionsbasierte Workflow-Richtlinien (Test-Erinnerungen, Protokollierung von Datei-Schreibzugriffen) |
 
 ### Explizite Dateibeispiele verwenden
 
@@ -351,4 +350,4 @@ mkdir -p ~/.failproofai/policies
 cp examples/convention-policies/*.mjs ~/.failproofai/policies/
 ```
 
-Kein Installationsbefehl erforderlich – die Dateien werden beim nächsten Hook-Ereignis automatisch erkannt.
+Kein Installationsbefehl erforderlich – die Dateien werden beim nächsten Hook-Event automatisch erkannt.

package/.next/standalone/docs/es/architecture.mdx

@@ -4,16 +4,16 @@ description: "Cómo funcionan internamente el manejador de hooks, la carga de co
 icon: sitemap
 ---
 
-Este documento explica cómo funciona failproofai internamente: cómo el sistema de hooks intercepta las llamadas a herramientas del agente, cómo se carga y fusiona la configuración, cómo se evalúan las políticas y cómo el panel de control monitorea la actividad del agente.
+Este documento explica cómo funciona failproofai internamente: cómo el sistema de hooks intercepta las llamadas a herramientas del agente, cómo se carga y combina la configuración, cómo se evalúan las políticas y cómo el panel de control monitoriza la actividad del agente.
 
 ---
 
 ## Descripción general
 
-failproofai cuenta con dos subsistemas independientes:
+failproofai tiene dos subsistemas independientes:
 
-1. **Manejador de hooks** - Un subproceso CLI rápido que Claude Code invoca en cada llamada a herramienta del agente. Evalúa las políticas y devuelve una decisión.
-2. **Monitor de agentes (Panel de control)** - Una aplicación web Next.js para monitorear sesiones de agentes y gestionar políticas.
+1. **Manejador de hooks** — Un subproceso CLI rápido que Claude Code invoca en cada llamada a herramienta del agente. Evalúa las políticas y devuelve una decisión.
+2. **Monitor de agentes (Panel de control)** — Una aplicación web Next.js para monitorizar sesiones de agentes y gestionar políticas.
 
 Ambos subsistemas comparten archivos de configuración en `~/.failproofai/` y en el directorio `.failproofai/` del proyecto, pero se ejecutan como procesos separados y se comunican únicamente a través del sistema de archivos.
 
@@ -23,7 +23,7 @@ Ambos subsistemas comparten archivos de configuración en `~/.failproofai/` y en
 
 ### Integración con Claude Code
 
-Al ejecutar `failproofai policies --install`, se escriben entradas como estas en `~/.claude/settings.json`:
+Cuando ejecutas `failproofai policies --install`, escribe entradas como esta en `~/.claude/settings.json`:
 
 ```json
 {
@@ -44,7 +44,7 @@ Al ejecutar `failproofai policies --install`, se escriben entradas como estas en
 }
 ```
 
-Claude Code luego invoca `failproofai --hook PreToolUse` como subproceso antes de cada llamada a herramienta, pasando un payload JSON por stdin.
+Claude Code invoca entonces `failproofai --hook PreToolUse` como subproceso antes de cada llamada a herramienta, pasando un payload JSON por stdin.
 
 ### Formato del payload
 
@@ -62,7 +62,7 @@ Claude Code luego invoca `failproofai --hook PreToolUse` como subproceso antes d
 
 Para eventos `PostToolUse`, el payload también contiene `tool_result` con la salida de la herramienta.
 
-El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este límite son descartados y todas las políticas permiten implícitamente.
+El manejador impone un límite de 1 MB en stdin. Los payloads que superen este tamaño se descartan y todas las políticas permiten implícitamente.
 
 ### Formato de respuesta
 
@@ -96,7 +96,7 @@ El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este l
 
 **Instruir en evento Stop:**
 - Código de salida: `2`
-- Motivo escrito en stderr (no en stdout)
+- El motivo se escribe en stderr (no en stdout)
 
 **Permitir:**
 - Código de salida: `0`
@@ -104,7 +104,7 @@ El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este l
 
 **Permitir con mensaje:**
 
-`allow(message)` permite que una política envíe contexto informativo a Claude incluso cuando la operación está permitida. El manejador de hooks escribe el siguiente JSON en **stdout** (no en un archivo de configuración — esta es la respuesta del manejador a Claude Code, igual que las respuestas de deny e instruct anteriores):
+`allow(message)` permite que una política envíe contexto informativo de vuelta a Claude incluso cuando la operación está permitida. El manejador de hooks escribe el siguiente JSON en **stdout** (no en un archivo de configuración — esta es la respuesta del manejador a Claude Code, igual que las respuestas de deny e instruct anteriores):
 
 ```json
 // Written to stdout by the hook handler process
@@ -115,8 +115,8 @@ El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este l
 }
 ```
 - Código de salida: `0` (la operación está permitida)
-- Cuando múltiples políticas devuelven `allow` con un mensaje, sus mensajes se unen con saltos de línea en una sola cadena `additionalContext`
-- Si ninguna política proporciona un mensaje, stdout está vacío (igual que antes)
+- Cuando varias políticas devuelven `allow` con un mensaje, sus mensajes se unen con saltos de línea en una sola cadena `additionalContext`
+- Si ninguna política proporciona un mensaje, stdout queda vacío (igual que antes)
 
 ### Pipeline de procesamiento
 
@@ -124,22 +124,22 @@ El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este l
 
 ```text
 stdin JSON
-  → parsear payload (máx 1 MB)
-  → extraer metadatos de sesión (session_id, cwd, tool_name, tool_input, etc.)
-  → readMergedHooksConfig(cwd)    ← fusiona configuración del proyecto + local + global
-  → registrar políticas integradas habilitadas con parámetros resueltos
-  → cargar políticas personalizadas desde customPoliciesPath (si está definido)
-  → registrar políticas personalizadas en el registro de políticas
-  → evaluar todas las políticas (primero las integradas, luego las personalizadas)
-      → el primer deny detiene el proceso inmediatamente
-      → las decisiones instruct se acumulan
-      → los mensajes allow se acumulan
-  → escribir decisión JSON en stdout
-  → persistir evento en ~/.failproofai/hook-activity.jsonl
-  → salir
+  → parse payload (max 1 MB)
+  → extract session metadata (session_id, cwd, tool_name, tool_input, etc.)
+  → readMergedHooksConfig(cwd)    ← merges project + local + global config
+  → register enabled builtin policies with resolved params
+  → load custom policies from customPoliciesPath (if set)
+  → register custom policies into policy registry
+  → evaluate all policies (builtins first, then custom)
+      → first deny short-circuits
+      → instruct decisions accumulate
+      → allow messages accumulate
+  → write JSON decision to stdout
+  → persist event to ~/.failproofai/hook-activity.jsonl
+  → exit
 ```
 
-Todo el proceso se ejecuta en menos de 100 ms para payloads típicos sin llamadas a LLM.
+Todo el proceso se ejecuta en menos de 100 ms para payloads típicos sin ninguna llamada a LLM.
 
 ---
 
@@ -148,18 +148,18 @@ Todo el proceso se ejecuta en menos de 100 ms para payloads típicos sin llamada
 `src/hooks/hooks-config.ts` implementa la carga de configuración en tres ámbitos.
 
 ```text
-[1] {cwd}/.failproofai/policies-config.json        ← proyecto  (mayor prioridad)
+[1] {cwd}/.failproofai/policies-config.json        ← proyecto  (máxima prioridad)
 [2] {cwd}/.failproofai/policies-config.local.json  ← local
-[3] ~/.failproofai/policies-config.json             ← global   (menor prioridad)
+[3] ~/.failproofai/policies-config.json             ← global   (mínima prioridad)
 ```
 
-Lógica de fusión:
-- `enabledPolicies` - unión deduplicada de los tres archivos
-- `policyParams` - por clave de política, gana completamente el primer archivo que la defina
-- `customPoliciesPath` - gana el primer archivo que lo defina
-- `llm` - gana el primer archivo que lo defina
+Lógica de combinación:
+- `enabledPolicies` — unión sin duplicados de los tres archivos
+- `policyParams` — clave por política; gana íntegramente el primer archivo que la defina
+- `customPoliciesPath` — gana el primer archivo que lo defina
+- `llm` — gana el primer archivo que lo defina
 
-El panel de control web utiliza `readHooksConfig()` (solo global) para leer y escribir, ya que no se invoca con un cwd de proyecto.
+El panel de control web utiliza `readHooksConfig()` (solo global) para lectura y escritura, ya que no se invoca con un cwd de proyecto.
 
 ---
 
@@ -169,18 +169,18 @@ El panel de control web utiliza `readHooksConfig()` (solo global) para leer y es
 
 Para cada política:
 
-1. Buscar el esquema `params` de la política (si tiene uno).
-2. Leer `policyParams[policy.name]` de la configuración fusionada.
-3. Fusionar los valores proporcionados por el usuario sobre los valores predeterminados del esquema para producir `ctx.params`.
-4. Llamar a `policy.fn(ctx)` con el contexto resuelto.
-5. Si el resultado es `deny`, detener inmediatamente y devolver esa decisión.
-6. Si el resultado es `instruct`, acumular el mensaje y continuar.
-7. Si el resultado es `allow`, continuar con la siguiente política.
+1. Busca el esquema `params` de la política (si tiene uno).
+2. Lee `policyParams[policy.name]` de la configuración combinada.
+3. Combina los valores proporcionados por el usuario sobre los valores predeterminados del esquema para producir `ctx.params`.
+4. Llama a `policy.fn(ctx)` con el contexto resuelto.
+5. Si el resultado es `deny`, se detiene inmediatamente y devuelve esa decisión.
+6. Si el resultado es `instruct`, acumula el mensaje y continúa.
+7. Si el resultado es `allow`, continúa con la siguiente política.
 
-Una vez que todas las políticas se han ejecutado:
-- Si se devolvió algún `deny`, emitir la respuesta de denegación.
-- Si se recopilaron respuestas `instruct`, emitir una única respuesta instruct con todos los mensajes unidos.
-- En caso contrario, emitir una respuesta de allow (stdout vacío, exit 0).
+Tras ejecutar todas las políticas:
+- Si se devolvió algún `deny`, emite la respuesta de deny.
+- Si se recopilaron respuestas `instruct`, emite una única respuesta instruct con todos los mensajes unidos.
+- En caso contrario, emite una respuesta allow (stdout vacío, exit 0).
 
 ---
 
@@ -206,7 +206,7 @@ interface BuiltinPolicyDefinition {
 
 Las políticas que aceptan `params` declaran un `PolicyParamsSchema` con tipos y valores predeterminados para cada parámetro. El evaluador de políticas inyecta los valores resueltos en `ctx.params` antes de llamar a `fn`. Las funciones de política leen `ctx.params` sin comprobaciones de nulo porque los valores predeterminados siempre se aplican primero.
 
-La coincidencia de patrones dentro de las políticas usa tokens de comando parseados (argv), no coincidencia de cadenas sin procesar. Esto evita elusiones mediante inyección de operadores shell (por ejemplo, un patrón para `sudo systemctl status *` no puede ser eludido añadiendo `; rm -rf /` al comando).
+La coincidencia de patrones dentro de las políticas utiliza tokens de comando analizados (argv), no coincidencia de cadenas sin procesar. Esto evita la elusión mediante inyección de operadores de shell (p. ej., un patrón para `sudo systemctl status *` no puede eludirse añadiendo `; rm -rf /` al comando).
 
 ---
 
@@ -227,23 +227,23 @@ export function clearCustomHooks(): void { ... }  // used in tests
 
 `src/hooks/custom-hooks-loader.ts` carga el archivo de políticas del usuario:
 
-1. Leer `customPoliciesPath` de la configuración; omitir si está ausente.
-2. Resolver a una ruta absoluta; verificar que el archivo existe.
-3. Reescribir todas las importaciones `from "failproofai"` a la ruta real de dist para que `customPolicies` se resuelva al mismo registro `globalThis`.
-4. Reescribir recursivamente las importaciones locales transitivas para garantizar compatibilidad con ESM.
-5. Escribir archivos `.mjs` temporales e importar (`import()`) el archivo de entrada.
-6. Llamar a `getCustomHooks()` para recuperar los hooks registrados.
-7. Limpiar todos los archivos temporales en un bloque `finally`.
+1. Lee `customPoliciesPath` de la configuración; omite si no existe.
+2. Resuelve a ruta absoluta; comprueba que el archivo existe.
+3. Reescribe todas las importaciones `from "failproofai"` a la ruta dist real para que `customPolicies` resuelva al mismo registro `globalThis`.
+4. Reescribe recursivamente las importaciones locales transitivas para garantizar la compatibilidad con ESM.
+5. Escribe archivos `.mjs` temporales e importa el archivo de entrada con `import()`.
+6. Llama a `getCustomHooks()` para recuperar los hooks registrados.
+7. Limpia todos los archivos temporales en un bloque `finally`.
 
 Ante cualquier error (archivo no encontrado, error de sintaxis, fallo de importación), el error se registra en `~/.failproofai/hook.log` y el cargador devuelve un array vacío. Las políticas integradas no se ven afectadas.
 
-Las políticas personalizadas se evalúan después de todas las políticas integradas. Un `deny` de una política personalizada sigue deteniendo las políticas personalizadas posteriores (pero todas las integradas ya habrán sido ejecutadas en ese punto).
+Las políticas personalizadas se evalúan después de todas las políticas integradas. Un `deny` de una política personalizada sigue cortocircuitando las demás políticas personalizadas (pero en ese punto todas las integradas ya han sido ejecutadas).
 
 ---
 
 ## Registro de actividad
 
-Después de cada evento de hook, el manejador añade una línea JSONL a `~/.failproofai/hook-activity.jsonl`:
+Tras cada evento de hook, el manejador añade una línea JSONL a `~/.failproofai/hook-activity.jsonl`:
 
 ```json
 {
@@ -258,7 +258,7 @@ Después de cada evento de hook, el manejador añade una línea JSONL a `~/.fail
 }
 ```
 
-Una línea por política que tomó una decisión diferente a allow. Las decisiones allow no se registran (para mantener el archivo pequeño).
+Una línea por política que tomó una decisión distinta de allow. Las decisiones allow no se registran (para mantener el archivo pequeño).
 
 ---
 
@@ -268,11 +268,11 @@ El panel de control es una aplicación **Next.js 16** que utiliza el App Router
 
 ```text
 app/
-  layout.tsx                  ← Layout raíz (tema, telemetría, navegación)
-  projects/page.tsx           ← Componente servidor: listar todos los proyectos Claude
-  project/[name]/page.tsx     ← Componente servidor: listar sesiones en un proyecto
+  layout.tsx                  ← Diseño raíz (tema, telemetría, nav)
+  projects/page.tsx           ← Componente servidor: lista todos los proyectos Claude
+  project/[name]/page.tsx     ← Componente servidor: lista sesiones de un proyecto
   project/[name]/session/
-    [sessionId]/page.tsx      ← Componente servidor: renderizar visor de sesión
+    [sessionId]/page.tsx      ← Componente servidor: renderiza el visor de sesión
   policies/page.tsx           ← Componente cliente: gestión de políticas + registro de actividad
   actions/
     get-hooks-config.ts       ← Leer configuración + lista de políticas
@@ -286,16 +286,16 @@ app/
 
 **Flujo de datos:**
 
-- Los componentes de página llaman a `lib/projects.ts` y `lib/log-entries.ts` para leer datos de proyectos/sesiones directamente desde el sistema de archivos (sin capa de API para lecturas).
-- La página de políticas usa Server Actions para todas las mutaciones (activar/desactivar, actualización de parámetros, instalar/eliminar).
-- El visor de sesión parsea el formato de transcripción JSONL de Claude y renderiza una línea de tiempo de mensajes y llamadas a herramientas.
+- Los componentes de página llaman a `lib/projects.ts` y `lib/log-entries.ts` para leer datos de proyectos y sesiones directamente desde el sistema de archivos (sin capa de API para lecturas).
+- La página de políticas usa Server Actions para todas las mutaciones (activar/desactivar, actualizar parámetros, instalar/eliminar).
+- El visor de sesiones analiza el formato de transcripción JSONL de Claude y renderiza una línea de tiempo de mensajes y llamadas a herramientas.
 
 **Decisiones de diseño clave:**
 
-- Sin base de datos - todo el estado persistente está en archivos planos (`~/.failproofai/`, `~/.claude/projects/`).
-- Server Actions para mutaciones - no se necesita una API REST para operaciones CRUD.
-- React Server Components para páginas de lectura - carga inicial más rápida, sin bundle del cliente para la obtención de datos.
-- Componentes cliente solo donde se necesita interactividad (activación de políticas, búsqueda de actividad, visor de logs).
+- Sin base de datos — todo el estado persistente está en archivos planos (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions para mutaciones — no se necesita una API REST para operaciones CRUD.
+- React Server Components para páginas de lectura — carga inicial más rápida, sin bundle de cliente para la obtención de datos.
+- Componentes cliente solo donde se necesita interactividad (activación de políticas, búsqueda de actividad, visor de registros).
 
 ---
 
@@ -313,20 +313,20 @@ failproofai/
 │   ├── policy-types.ts           # Interfaces TypeScript
 │   ├── hooks-config.ts           # Carga de configuración multi-ámbito
 │   ├── custom-hooks-registry.ts  # Registro de hooks respaldado por globalThis
-│   ├── custom-hooks-loader.ts    # Cargador ESM para hooks JS del usuario
-│   ├── manager.ts                # Operaciones de instalación / eliminación / listado
+│   ├── custom-hooks-loader.ts    # Cargador ESM para hooks JS de usuario
+│   ├── manager.ts                # Operaciones de instalar / eliminar / listar
 │   ├── install-prompt.ts         # Prompt interactivo de selección de políticas
 │   ├── hook-logger.ts            # Registro en hook.log
 │   ├── hook-activity-store.ts    # Persistir actividad en hook-activity.jsonl
-│   └── llm-client.ts             # Cliente API de LLM (para políticas impulsadas por IA)
+│   └── llm-client.ts             # Cliente API LLM (para políticas con IA)
 ├── app/                          # Panel de control Next.js (páginas + server actions)
 ├── lib/                          # Utilidades compartidas
 │   ├── projects.ts               # Enumerar proyectos Claude desde el sistema de archivos
-│   ├── log-entries.ts            # Parsear formato JSONL de transcripciones Claude
+│   ├── log-entries.ts            # Analizar el formato JSONL de transcripción de Claude
 │   ├── paths.ts                  # Resolver rutas del sistema
 │   └── ...
-├── components/                   # Componentes UI React compartidos
+├── components/                   # Componentes React UI compartidos
 ├── contexts/                     # Proveedores de contexto React (tema, auto-refresco, telemetría)
 ├── examples/                     # Archivos de hooks personalizados de ejemplo
-└── __tests__/                    # Tests unitarios y E2E
+└── __tests__/                    # Pruebas unitarias y E2E
 ```