failproofai 0.0.5 → 0.0.6-beta.1

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

@@ -1,21 +1,21 @@
 ---
 title: Architektur
-description: "Wie der Hook-Handler, das Laden der Konfiguration und die Policy-Auswertung intern funktionieren"
+description: "Wie der Hook-Handler, das Laden der Konfiguration und die Richtlinienauswertung intern funktionieren"
 icon: sitemap
 ---
 
-Dieses Dokument erklärt, wie failproofai intern funktioniert: wie das Hook-System Agent-Tool-Aufrufe abfängt, wie die Konfiguration geladen und zusammengeführt wird, wie Policies ausgewertet werden und wie das Dashboard die Agentenaktivität überwacht.
+Dieses Dokument erläutert, wie failproofai intern funktioniert: wie das Hook-System Agent-Tool-Aufrufe abfängt, wie die Konfiguration geladen und zusammengeführt wird, wie Richtlinien ausgewertet werden und wie das Dashboard die Agentenaktivität überwacht.
 
 ---
 
 ## Überblick
 
-failproofai besteht aus zwei unabhängigen Subsystemen:
+failproofai besteht aus zwei unabhängigen Teilsystemen:
 
-1. **Hook-Handler** – Ein schneller CLI-Subprocess, den Claude Code bei jedem Agent-Tool-Aufruf aufruft. Wertet Policies aus und gibt eine Entscheidung zurück.
-2. **Agent Monitor (Dashboard)** – Eine Next.js-Webanwendung zur Überwachung von Agentensitzungen und zur Verwaltung von Policies.
+1. **Hook-Handler** – Ein schneller CLI-Subprozess, den Claude Code bei jedem Agent-Tool-Aufruf startet. Er wertet Richtlinien aus und gibt eine Entscheidung zurück.
+2. **Agent Monitor (Dashboard)** – Eine Next.js-Webanwendung zur Überwachung von Agentensitzungen und Verwaltung von Richtlinien.
 
-Beide Subsysteme teilen sich Konfigurationsdateien in `~/.failproofai/` und im `.failproofai/`-Verzeichnis des Projekts, laufen jedoch als separate Prozesse und kommunizieren ausschließlich über das Dateisystem.
+Beide Teilsysteme teilen sich Konfigurationsdateien in `~/.failproofai/` und im `.failproofai/`-Verzeichnis des Projekts, laufen aber als separate Prozesse und kommunizieren ausschließlich über das Dateisystem.
 
 ---
 
@@ -23,7 +23,7 @@ Beide Subsysteme teilen sich Konfigurationsdateien in `~/.failproofai/` und im `
 
 ### Integration mit Claude Code
 
-Wenn Sie `failproofai policies --install` ausführen, schreibt es folgende Einträge in `~/.claude/settings.json`:
+Wenn Sie `failproofai policies --install` ausführen, werden Einträge wie diese in `~/.claude/settings.json` geschrieben:
 
 ```json
 {
@@ -44,7 +44,7 @@ Wenn Sie `failproofai policies --install` ausführen, schreibt es folgende Eintr
 }
 ```
 
-Claude Code ruft daraufhin `failproofai --hook PreToolUse` als Subprocess vor jedem Tool-Aufruf auf und übergibt dabei einen JSON-Payload über stdin.
+Claude Code startet dann `failproofai --hook PreToolUse` als Subprozess vor jedem Tool-Aufruf und übergibt dabei ein JSON-Payload über stdin.
 
 ### Payload-Format
 
@@ -60,13 +60,13 @@ Claude Code ruft daraufhin `failproofai --hook PreToolUse` als Subprocess vor je
 }
 ```
 
-Bei `PostToolUse`-Events enthält der Payload zusätzlich `tool_result` mit der Ausgabe des Tools.
+Bei `PostToolUse`-Ereignissen enthält das Payload zusätzlich `tool_result` mit der Ausgabe des Tools.
 
-Der Handler setzt ein Limit von 1 MB für stdin. Payloads, die dieses Limit überschreiten, werden verworfen und alle Policies erlauben implizit.
+Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit überschreiten, werden verworfen und alle Richtlinien erlauben implizit.
 
 ### Antwortformat
 
-**Deny (PreToolUse):**
+**Ablehnen (PreToolUse):**
 ```json
 {
   "hookSpecificOutput": {
@@ -76,7 +76,7 @@ Der Handler setzt ein Limit von 1 MB für stdin. Payloads, die dieses Limit übe
 }
 ```
 
-**Deny (PostToolUse):**
+**Ablehnen (PostToolUse):**
 ```json
 {
   "hookSpecificOutput": {
@@ -85,7 +85,7 @@ Der Handler setzt ein Limit von 1 MB für stdin. Payloads, die dieses Limit übe
 }
 ```
 
-**Instruct (alle Events außer Stop):**
+**Anweisung (beliebiges Ereignis außer Stop):**
 ```json
 {
   "hookSpecificOutput": {
@@ -94,17 +94,17 @@ Der Handler setzt ein Limit von 1 MB für stdin. Payloads, die dieses Limit übe
 }
 ```
 
-**Stop-Event instruct:**
+**Stop-Ereignis mit Anweisung:**
 - Exit-Code: `2`
-- Grund wird nach stderr geschrieben (nicht stdout)
+- Begründung wird in stderr geschrieben (nicht stdout)
 
-**Allow:**
+**Erlauben:**
 - Exit-Code: `0`
 - Leerer stdout
 
-**Allow mit Nachricht:**
+**Erlauben mit Nachricht:**
 
-`allow(message)` ermöglicht einer Policy, informativen Kontext an Claude zurückzusenden, auch wenn die Operation erlaubt wird. Der Hook-Handler schreibt folgendes JSON nach **stdout** (keine Konfigurationsdatei – dies ist die Antwort des Handlers an Claude Code, genau wie deny- und instruct-Antworten oben):
+`allow(message)` erlaubt es einer Richtlinie, informationellen Kontext an Claude zurückzusenden, auch wenn die Operation erlaubt ist. Der Hook-Handler schreibt folgenden JSON-Inhalt in **stdout** (nicht in eine Konfigurationsdatei – dies ist die Antwort des Handlers an Claude Code, genau wie Ablehnen- und Anweisungsantworten oben):
 
 ```json
 // Written to stdout by the hook handler process
@@ -115,8 +115,8 @@ Der Handler setzt ein Limit von 1 MB für stdin. Payloads, die dieses Limit übe
 }
 ```
 - Exit-Code: `0` (Operation ist erlaubt)
-- Wenn mehrere Policies `allow` mit einer Nachricht zurückgeben, werden ihre Nachrichten mit Zeilenumbrüchen zu einem einzigen `additionalContext`-String verbunden
-- Wenn keine Policy eine Nachricht liefert, ist stdout leer (wie zuvor)
+- Wenn mehrere Richtlinien `allow` mit einer Nachricht zurückgeben, werden ihre Nachrichten mit Zeilenumbrüchen zu einem einzelnen `additionalContext`-String zusammengefügt
+- Wenn keine Richtlinie eine Nachricht liefert, ist stdout leer (wie zuvor)
 
 ### Verarbeitungspipeline
 
@@ -124,28 +124,28 @@ Der Handler setzt ein Limit von 1 MB für stdin. Payloads, die dieses Limit übe
 
 ```text
 stdin JSON
-  → 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
+  → Payload parsen (max. 1 MB)
+  → Sitzungsmetadaten extrahieren (session_id, cwd, tool_name, tool_input, etc.)
+  → readMergedHooksConfig(cwd)    ← führt Projekt-, lokale und globale Konfiguration zusammen
+  → aktivierte eingebaute Richtlinien mit aufgelösten Parametern registrieren
+  → benutzerdefinierte Richtlinien aus customPoliciesPath laden (falls gesetzt)
+  → benutzerdefinierte Richtlinien in die Policy-Registry registrieren
+  → alle Richtlinien auswerten (zuerst eingebaute, dann benutzerdefinierte)
+      → erstes deny unterbricht sofort die Auswertung
+      → instruct-Entscheidungen werden gesammelt
+      → allow-Nachrichten werden gesammelt
+  → JSON-Entscheidung in stdout schreiben
+  → Ereignis in ~/.failproofai/hook-activity.jsonl speichern
+  → beenden
 ```
 
 Der gesamte Prozess läuft bei typischen Payloads ohne LLM-Aufrufe in unter 100 ms ab.
 
 ---
 
-## Konfiguration laden
+## Konfigurationsladen
 
-`src/hooks/hooks-config.ts` implementiert das dreistufige Laden der Konfiguration.
+`src/hooks/hooks-config.ts` implementiert das Laden der Konfiguration mit drei Geltungsbereichen.
 
 ```text
 [1] {cwd}/.failproofai/policies-config.json        ← Projekt  (höchste Priorität)
@@ -154,39 +154,39 @@ Der gesamte Prozess läuft bei typischen Payloads ohne LLM-Aufrufe in unter 100
 ```
 
 Zusammenführungslogik:
-- `enabledPolicies` – deduplizierte Vereinigung aller drei Dateien
-- `policyParams` – pro Policy-Schlüssel gewinnt die erste Datei, die ihn definiert, vollständig
-- `customPoliciesPath` – die erste Datei, die ihn definiert, gewinnt
-- `llm` – die erste Datei, die ihn definiert, gewinnt
+- `enabledPolicies` – deduplizierte Vereinigung aus allen drei Dateien
+- `policyParams` – pro Richtlinienschlüssel gewinnt die erste Datei, die ihn definiert, vollständig
+- `customPoliciesPath` – die erste Datei, die diesen Wert definiert, gewinnt
+- `llm` – die erste Datei, die diesen Wert definiert, gewinnt
 
-Das Web-Dashboard verwendet `readHooksConfig()` (nur global) zum Lesen und Schreiben, da es nicht mit einem Projekt-cwd aufgerufen wird.
+Das Web-Dashboard verwendet `readHooksConfig()` (nur global) zum Lesen und Schreiben, da es ohne Projekt-cwd aufgerufen wird.
 
 ---
 
-## Policy-Auswertung
+## Richtlinienauswertung
 
-`src/hooks/policy-evaluator.ts` führt Policies der Reihe nach aus.
+`src/hooks/policy-evaluator.ts` führt Richtlinien der Reihe nach aus.
 
-Für jede Policy:
+Für jede Richtlinie:
 
-1. Das `params`-Schema der Policy nachschlagen (sofern vorhanden).
+1. Das `params`-Schema der Richtlinie nachschlagen (falls vorhanden).
 2. `policyParams[policy.name]` aus der zusammengeführten Konfiguration lesen.
-3. Benutzerdefinierte Werte über Schema-Standardwerte zusammenführen, um `ctx.params` zu erzeugen.
+3. Vom Benutzer angegebene Werte über Schema-Standardwerte legen, um `ctx.params` zu erzeugen.
 4. `policy.fn(ctx)` mit dem aufgelösten Kontext aufrufen.
-5. Ist das Ergebnis `deny`, sofort stoppen und diese Entscheidung zurückgeben.
-6. Ist das Ergebnis `instruct`, die Nachricht sammeln und fortfahren.
-7. Ist das Ergebnis `allow`, mit der nächsten Policy fortfahren.
+5. Wenn das Ergebnis `deny` ist, sofort abbrechen und diese Entscheidung zurückgeben.
+6. Wenn das Ergebnis `instruct` ist, die Nachricht sammeln und fortfahren.
+7. Wenn das Ergebnis `allow` ist, mit der nächsten Richtlinie fortfahren.
 
-Nach Ausführung aller Policies:
-- Wenn ein `deny` zurückgegeben wurde, die Deny-Antwort ausgeben.
-- Wenn `instruct`-Rückgaben gesammelt wurden, eine einzelne instruct-Antwort mit allen verbundenen Nachrichten ausgeben.
-- Andernfalls eine Allow-Antwort ausgeben (leerer stdout, Exit 0).
+Nach dem Durchlauf aller Richtlinien:
+- Falls ein `deny` zurückgegeben wurde, die Ablehnungsantwort ausgeben.
+- Falls `instruct`-Rückgaben gesammelt wurden, eine einzelne instruct-Antwort mit allen zusammengefügten Nachrichten ausgeben.
+- Andernfalls eine allow-Antwort ausgeben (leerer stdout, Exit 0).
 
 ---
 
-## Eingebaute Policies
+## Eingebaute Richtlinien
 
-`src/hooks/builtin-policies.ts` definiert alle 26 eingebauten Policies als `BuiltinPolicyDefinition`-Objekte:
+`src/hooks/builtin-policies.ts` definiert alle 26 eingebauten Richtlinien als `BuiltinPolicyDefinition`-Objekte:
 
 ```typescript
 interface BuiltinPolicyDefinition {
@@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition {
 }
 ```
 
-Policies, die `params` akzeptieren, deklarieren ein `PolicyParamsSchema` mit Typen und Standardwerten für jeden Parameter. Der Policy-Evaluator injiziert aufgelöste Werte in `ctx.params`, bevor `fn` aufgerufen wird. Policy-Funktionen lesen `ctx.params` ohne Null-Prüfung, da Standardwerte immer zuerst angewendet werden.
+Richtlinien, die `params` akzeptieren, deklarieren ein `PolicyParamsSchema` mit Typen und Standardwerten für jeden Parameter. Der Richtlinienauswerter injiziert aufgelöste Werte in `ctx.params`, bevor `fn` aufgerufen wird. Richtlinienfunktionen lesen `ctx.params` ohne Null-Prüfung, da Standardwerte immer zuerst angewendet werden.
 
-Pattern-Matching innerhalb von Policies verwendet geparste Befehlstoken (argv) statt einfachen String-Vergleichen. Dies verhindert Umgehungsversuche durch Shell-Operator-Injection (z. B. kann ein Muster für `sudo systemctl status *` nicht durch Anhängen von `; rm -rf /` an den Befehl umgangen werden).
+Das Muster-Matching in Richtlinien verwendet geparste Befehls-Token (argv), keine rohe Zeichenkettenübereinstimmung. Dies verhindert Umgehungsversuche durch Shell-Operator-Injection (z. B. kann ein Muster für `sudo systemctl status *` nicht durch Anhängen von `; rm -rf /` an den Befehl umgangen werden).
 
 ---
 
-## Benutzerdefinierte Policies
+## Benutzerdefinierte Richtlinien
 
-`src/hooks/custom-hooks-registry.ts` implementiert eine `globalThis`-basierte Registry:
+`src/hooks/custom-hooks-registry.ts` implementiert eine auf `globalThis` basierende Registry:
 
 ```typescript
 const REGISTRY_KEY = "__failproofai_custom_hooks__";
@@ -225,25 +225,25 @@ export function getCustomHooks(): CustomHook[] { ... }
 export function clearCustomHooks(): void { ... }  // used in tests
 ```
 
-`src/hooks/custom-hooks-loader.ts` lädt die Policy-Datei des Benutzers:
+`src/hooks/custom-hooks-loader.ts` lädt die Richtliniendatei des Benutzers:
 
 1. `customPoliciesPath` aus der Konfiguration lesen; überspringen, falls nicht vorhanden.
-2. Zu absolutem Pfad auflösen; prüfen, ob die Datei existiert.
-3. Alle `from "failproofai"`-Imports zum tatsächlichen dist-Pfad umschreiben, damit `customPolicies` zur selben `globalThis`-Registry aufgelöst wird.
-4. Transitive lokale Imports rekursiv umschreiben, um ESM-Kompatibilität sicherzustellen.
+2. Zum absoluten Pfad auflösen; prüfen, ob die Datei existiert.
+3. Alle `from "failproofai"`-Importe in den tatsächlichen dist-Pfad umschreiben, damit `customPolicies` zur gleichen `globalThis`-Registry aufgelöst wird.
+4. Transitive lokale Importe rekursiv umschreiben, um ESM-Kompatibilität sicherzustellen.
 5. Temporäre `.mjs`-Dateien schreiben und die Einstiegsdatei per `import()` laden.
 6. `getCustomHooks()` aufrufen, um registrierte Hooks abzurufen.
 7. Alle temporären Dateien in einem `finally`-Block bereinigen.
 
-Bei jedem Fehler (Datei nicht gefunden, Syntaxfehler, Import-Fehler) wird der Fehler in `~/.failproofai/hook.log` protokolliert und der Loader gibt ein leeres Array zurück. Eingebaute Policies sind davon nicht betroffen.
+Bei jedem Fehler (Datei nicht gefunden, Syntaxfehler, Import-Fehler) wird der Fehler in `~/.failproofai/hook.log` protokolliert und der Loader gibt ein leeres Array zurück. Eingebaute Richtlinien sind davon nicht betroffen.
 
-Benutzerdefinierte Policies werden nach allen eingebauten Policies ausgewertet. Ein `deny` einer benutzerdefinierten Policy unterbricht dennoch weitere benutzerdefinierte Policies (alle eingebauten Policies sind zu diesem Zeitpunkt jedoch bereits ausgeführt worden).
+Benutzerdefinierte Richtlinien werden nach allen eingebauten Richtlinien ausgewertet. Ein `deny` einer benutzerdefinierten Richtlinie unterbricht weiterhin die Auswertung weiterer benutzerdefinierter Richtlinien (aber alle eingebauten wurden zu diesem Zeitpunkt bereits ausgeführt).
 
 ---
 
 ## Aktivitätsprotokollierung
 
-Nach jedem Hook-Event hängt der Handler eine JSONL-Zeile an `~/.failproofai/hook-activity.jsonl` an:
+Nach jedem Hook-Ereignis fügt der Handler eine JSONL-Zeile an `~/.failproofai/hook-activity.jsonl` an:
 
 ```json
 {
@@ -258,7 +258,7 @@ Nach jedem Hook-Event hängt der Handler eine JSONL-Zeile an `~/.failproofai/hoo
 }
 ```
 
-Eine Zeile pro Policy, die eine Nicht-Allow-Entscheidung getroffen hat. Allow-Entscheidungen werden nicht protokolliert (um die Dateigröße gering zu halten).
+Eine Zeile pro Richtlinie, die eine Nicht-allow-Entscheidung getroffen hat. Allow-Entscheidungen werden nicht protokolliert (um die Dateigröße gering zu halten).
 
 ---
 
@@ -272,13 +272,13 @@ app/
   projects/page.tsx           ← Server-Komponente: alle Claude-Projekte auflisten
   project/[name]/page.tsx     ← Server-Komponente: Sitzungen in einem Projekt auflisten
   project/[name]/session/
-    [sessionId]/page.tsx      ← Server-Komponente: Sitzungsansicht rendern
-  policies/page.tsx           ← Client-Komponente: Policy-Verwaltung + Aktivitätslog
+    [sessionId]/page.tsx      ← Server-Komponente: Sitzungs-Viewer rendern
+  policies/page.tsx           ← Client-Komponente: Richtlinienverwaltung + Aktivitätsprotokoll
   actions/
-    get-hooks-config.ts       ← Konfiguration + Policy-Liste lesen
-    update-hooks-config.ts    ← Policy ein-/ausschalten
-    update-policy-params.ts   ← Policy-Parameter aktualisieren
-    get-hook-activity.ts      ← Aktivitätslog paginieren/durchsuchen
+    get-hooks-config.ts       ← Konfiguration + Richtlinienliste lesen
+    update-hooks-config.ts    ← Richtlinie aktivieren/deaktivieren
+    update-policy-params.ts   ← Richtlinienparameter aktualisieren
+    get-hook-activity.ts      ← Aktivitätsprotokoll paginieren/durchsuchen
     install-hooks-web.ts      ← Hooks über den Browser installieren/entfernen
   api/
     download/[project]/[session]/route.ts   ← Sitzung als ZIP/JSONL exportieren
@@ -286,16 +286,16 @@ app/
 
 **Datenfluss:**
 
-- Seitenkomponenten rufen `lib/projects.ts` und `lib/log-entries.ts` auf, um Projekt-/Sitzungsdaten direkt aus dem Dateisystem zu lesen (keine API-Schicht für Lesevorgänge).
-- Die Policies-Seite verwendet Server Actions für alle Mutationen (Umschalten, Parameter-Aktualisierung, Installieren/Entfernen).
-- Der Sitzungs-Viewer parst das JSONL-Transkriptformat von Claude und rendert einen Zeitstrahl von Nachrichten und Tool-Aufrufen.
+- Seitenkomponenten rufen `lib/projects.ts` und `lib/log-entries.ts` auf, um Projekt- und Sitzungsdaten direkt aus dem Dateisystem zu lesen (keine API-Schicht für Lesevorgänge).
+- Die Policies-Seite verwendet Server Actions für alle Mutationen (Umschalten, Parameteraktualisierung, Installieren/Entfernen).
+- Der Sitzungs-Viewer parst das JSONL-Transkriptformat von Claude und rendert eine Zeitachse mit Nachrichten und Tool-Aufrufen.
 
 **Wesentliche Designentscheidungen:**
 
 - Keine Datenbank – der gesamte persistente Zustand liegt in einfachen Dateien (`~/.failproofai/`, `~/.claude/projects/`).
-- Server Actions für Mutationen – kein REST-API für CRUD-Operationen erforderlich.
-- React Server Components für Lese-Seiten – schnelleres initiales Laden, kein Client-Bundle für Datenabruf.
-- Client-Komponenten nur dort, wo Interaktivität benötigt wird (Policy-Umschalter, Aktivitätssuche, Log-Viewer).
+- Server Actions für Mutationen – keine REST-API für CRUD-Operationen erforderlich.
+- React Server Components für Leseseiten – schnelleres initiales Laden, kein Client-Bundle für das Datenabrufen.
+- Client-Komponenten nur dort, wo Interaktivität benötigt wird (Richtlinien-Schalter, Aktivitätssuche, Log-Viewer).
 
 ---
 
@@ -304,29 +304,29 @@ app/
 ```text
 failproofai/
 ├── bin/
-│   └── failproofai.mjs           # CLI-Router (hook / dashboard / install / etc.)
+│   └── failproofai.mjs           # CLI-Router (Hook / Dashboard / Install / etc.)
 ├── src/hooks/
-│   ├── handler.ts                # Hook-Event-Pipeline
-│   ├── builtin-policies.ts       # 26 Policy-Definitionen
-│   ├── policy-evaluator.ts       # Policy-Ausführungs-Engine
-│   ├── policy-registry.ts        # Policy-Registrierung und -Nachschlagen
+│   ├── handler.ts                # Hook-Ereignis-Pipeline
+│   ├── builtin-policies.ts       # 26 Richtliniendefinitionen
+│   ├── policy-evaluator.ts       # Richtlinienausführungs-Engine
+│   ├── policy-registry.ts        # Richtlinienregistrierung und -suche
 │   ├── policy-types.ts           # TypeScript-Interfaces
-│   ├── hooks-config.ts           # Mehrstufiges Laden der Konfiguration
+│   ├── hooks-config.ts           # Konfigurationsladen mit mehreren Geltungsbereichen
 │   ├── custom-hooks-registry.ts  # globalThis-basierte Hook-Registry
 │   ├── custom-hooks-loader.ts    # ESM-Loader für benutzerdefinierte JS-Hooks
-│   ├── manager.ts                # Installations-/Entfernen-/Auflistungsoperationen
-│   ├── install-prompt.ts         # Interaktive Policy-Auswahlabfrage
-│   ├── hook-logger.ts            # Protokollierung nach hook.log
-│   ├── hook-activity-store.ts    # Aktivität nach hook-activity.jsonl persistieren
-│   └── llm-client.ts             # LLM-API-Client (für KI-gestützte Policies)
+│   ├── manager.ts                # Install-, Entfernen- und Listen-Operationen
+│   ├── install-prompt.ts         # Interaktive Richtlinienauswahl-Eingabeaufforderung
+│   ├── hook-logger.ts            # Protokollierung in hook.log
+│   ├── hook-activity-store.ts    # Aktivitäten in hook-activity.jsonl speichern
+│   └── llm-client.ts             # LLM-API-Client (für KI-gestützte Richtlinien)
 ├── app/                          # Next.js-Dashboard (Seiten + Server Actions)
-├── lib/                          # Gemeinsame Hilfsfunktionen
+├── lib/                          # Gemeinsam genutzte Hilfsfunktionen
 │   ├── projects.ts               # Claude-Projekte aus dem Dateisystem aufzählen
 │   ├── log-entries.ts            # Claude-Transkript-JSONL-Format parsen
 │   ├── paths.ts                  # Systempfade auflösen
 │   └── ...
-├── components/                   # Gemeinsame React-UI-Komponenten
-├── contexts/                     # React-Context-Provider (Theme, Auto-Refresh, Telemetrie)
+├── components/                   # Gemeinsam genutzte React-UI-Komponenten
+├── contexts/                     # React-Kontext-Provider (Theme, Auto-Refresh, Telemetrie)
 ├── examples/                     # Beispieldateien für benutzerdefinierte Hooks
 └── __tests__/                    # Unit- und E2E-Tests
 ```

package/.next/standalone/docs/de/configuration.mdx

@@ -1,28 +1,28 @@
 ---
 title: Konfiguration
-description: "Konfigurationsdateiformat, Drei-Scope-System und Zusammenführungsregeln"
+description: "Konfigurationsdateiformat, Drei-Ebenen-System und Zusammenführungsregeln"
 icon: gear
 ---
 
-failproofai verwendet JSON-Konfigurationsdateien, um festzulegen, welche Richtlinien aktiv sind, wie sie sich verhalten und woher benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist so gestaltet, dass sie einfach mit dem Team geteilt werden kann – committen Sie sie in Ihr Repository und jeder Entwickler erhält dasselbe Sicherheitsnetz für Agenten.
+failproofai verwendet JSON-Konfigurationsdateien, um festzulegen, welche Richtlinien aktiv sind, wie sie sich verhalten und woher benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist darauf ausgelegt, einfach mit dem Team geteilt zu werden – checke sie in dein Repository ein, und jeder Entwickler profitiert vom gleichen Sicherheitsnetz für den Agenten.
 
 ---
 
-## Konfigurationsscopes
+## Konfigurationsebenen
 
-Es gibt drei Konfigurationsscopes, die in Prioritätsreihenfolge ausgewertet werden:
+Es gibt drei Konfigurationsebenen, die in Prioritätsreihenfolge ausgewertet werden:
 
-| Scope | Dateipfad | Zweck |
+| Ebene | Dateipfad | Zweck |
 |-------|-----------|-------|
-| **project** | `.failproofai/policies-config.json` | Repository-spezifische Einstellungen, in die Versionsverwaltung eingecheckt |
-| **local** | `.failproofai/policies-config.local.json` | Persönliche repository-spezifische Überschreibungen, per .gitignore ausgeschlossen |
+| **project** | `.failproofai/policies-config.json` | Repo-spezifische Einstellungen, in die Versionskontrolle eingecheckt |
+| **local** | `.failproofai/policies-config.local.json` | Persönliche Repo-spezifische Überschreibungen, via gitignore ausgeschlossen |
 | **global** | `~/.failproofai/policies-config.json` | Benutzerweite Standardeinstellungen für alle Projekte |
 
-Wenn failproofai ein Hook-Ereignis empfängt, lädt und zusammenführt es alle drei Dateien, die für das aktuelle Arbeitsverzeichnis vorhanden sind.
+Wenn failproofai ein Hook-Ereignis empfängt, lädt und fügt es alle drei Dateien zusammen, die für das aktuelle Arbeitsverzeichnis vorhanden sind.
 
 ### Zusammenführungsregeln
 
-**`enabledPolicies`** – die Vereinigung aller drei Scopes. Eine Richtlinie, die auf irgendeiner Ebene aktiviert ist, ist aktiv.
+**`enabledPolicies`** – die Vereinigung aller drei Ebenen. Eine Richtlinie, die auf einer beliebigen Ebene aktiviert ist, ist aktiv.
 
 ```text
 project:  ["block-sudo"]
@@ -32,13 +32,13 @@ global:   ["block-sudo", "sanitize-api-keys"]
 resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← deduplizierte Vereinigung
 ```
 
-**`policyParams`** – der erste Scope, der Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es findet kein tiefes Zusammenführen von Werten innerhalb der Parameter einer Richtlinie statt.
+**`policyParams`** – die erste Ebene, die Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es findet kein tiefes Zusammenführen von Werten innerhalb der Parameter einer Richtlinie statt.
 
 ```text
 project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
 global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
 
-resolved: { allowPatterns: ["sudo apt-get update"] }   ← project gewinnt, global ignoriert
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project gewinnt, global wird ignoriert
 ```
 
 ```text
@@ -49,9 +49,9 @@ global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
 resolved: { allowPatterns: ["sudo systemctl status"] }  ← fällt auf global zurück
 ```
 
-**`customPoliciesPath`** – der erste Scope, der diesen Wert definiert, gewinnt.
+**`customPoliciesPath`** – die erste Ebene, die diesen Wert definiert, gewinnt.
 
-**`llm`** – der erste Scope, der diesen Wert definiert, gewinnt.
+**`llm`** – die erste Ebene, die diesen Wert definiert, gewinnt.
 
 ---
 
@@ -102,25 +102,25 @@ resolved: { allowPatterns: ["sudo systemctl status"] }  ← fällt auf global zu
 
 Typ: `string[]`
 
-Liste der zu aktivierenden Richtliniennamen. Die Namen müssen exakt mit den Richtlinienbezeichnern übereinstimmen, die von `failproofai policies` angezeigt werden. Die vollständige Liste finden Sie unter [Integrierte Richtlinien](/de/built-in-policies).
+Liste der zu aktivierenden Richtliniennamen. Die Namen müssen exakt mit den Richtlinienbezeichnern übereinstimmen, die von `failproofai policies` angezeigt werden. Eine vollständige Liste findest du unter [Integrierte Richtlinien](/de/built-in-policies).
 
-Richtlinien, die nicht in `enabledPolicies` aufgeführt sind, sind inaktiv, auch wenn sie Einträge in `policyParams` haben.
+Richtlinien, die nicht in `enabledPolicies` aufgeführt sind, sind inaktiv – auch wenn sie Einträge in `policyParams` haben.
 
 ### `policyParams`
 
 Typ: `Record<string, Record<string, unknown>>`
 
-Richtlinienspezifische Parameterüberschreibungen. Der äußere Schlüssel ist der Richtlinienname; die inneren Schlüssel sind richtlinienspezifisch. Jede Richtlinie dokumentiert ihre verfügbaren Parameter unter [Integrierte Richtlinien](/de/built-in-policies).
+Richtlinienspezifische Parameterüberschreibungen. Der äußere Schlüssel ist der Richtlinienname, die inneren Schlüssel sind richtlinienspezifisch. Jede Richtlinie dokumentiert ihre verfügbaren Parameter unter [Integrierte Richtlinien](/de/built-in-policies).
 
-Wenn eine Richtlinie Parameter hat, Sie diese aber nicht angeben, werden die integrierten Standardwerte der Richtlinie verwendet. Benutzer, die `policyParams` gar nicht konfigurieren, erhalten dasselbe Verhalten wie in früheren Versionen.
+Wenn eine Richtlinie Parameter hat, du diese aber nicht angibst, werden die integrierten Standardwerte der Richtlinie verwendet. Benutzer, die `policyParams` gar nicht konfigurieren, erhalten identisches Verhalten wie in früheren Versionen.
 
-Unbekannte Schlüssel innerhalb des Parameterblocks einer Richtlinie werden zum Zeitpunkt der Hook-Auslösung stillschweigend ignoriert, aber als Warnungen markiert, wenn Sie `failproofai policies` ausführen.
+Unbekannte Schlüssel innerhalb des Parameterblocks einer Richtlinie werden zum Zeitpunkt der Hook-Ausführung still ignoriert, aber als Warnungen ausgegeben, wenn du `failproofai policies` ausführst.
 
 #### `hint` (übergreifend)
 
 Typ: `string` (optional)
 
-Eine Nachricht, die an die Begründung angehängt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Verwenden Sie diesen Wert, um Claude handlungsrelevante Hinweise zu geben, ohne die Richtlinie selbst zu ändern.
+Eine Nachricht, die dem Grund hinzugefügt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Verwende sie, um Claude handlungsorientierte Hinweise zu geben, ohne die Richtlinie selbst zu ändern.
 
 Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom/`), Projektkonvention (`.failproofai-project/`) oder Benutzerkonvention (`.failproofai-user/`).
 
@@ -141,9 +141,9 @@ Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom
 }
 ```
 
-Wenn `block-force-push` verweigert, sieht Claude: *„Force-Pushing ist blockiert. Versuche stattdessen, einen neuen Branch zu erstellen."*
+Wenn `block-force-push` ablehnt, sieht Claude: *„Force-Pushing ist blockiert. Try creating a fresh branch instead."*
 
-Nicht-String-Werte und leere Zeichenketten werden stillschweigend ignoriert. Wenn `hint` nicht gesetzt ist, bleibt das Verhalten unverändert (abwärtskompatibel).
+Nicht-String-Werte und leere Zeichenfolgen werden still ignoriert. Wenn `hint` nicht gesetzt ist, bleibt das Verhalten unverändert (abwärtskompatibel).
 
 ### `customPoliciesPath`
 
@@ -151,24 +151,24 @@ Typ: `string` (absoluter Pfad)
 
 Pfad zu einer JavaScript-Datei mit benutzerdefinierten Hook-Richtlinien. Dieser Wert wird automatisch durch `failproofai policies --install --custom <path>` gesetzt (der Pfad wird vor der Speicherung in einen absoluten Pfad aufgelöst).
 
-Die Datei wird bei jedem Hook-Ereignis neu geladen – es gibt kein Caching. Informationen zur Erstellung finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies).
+Die Datei wird bei jedem Hook-Ereignis neu geladen – es gibt kein Caching. Einzelheiten zur Erstellung findest du unter [Benutzerdefinierte Richtlinien](/de/custom-policies).
 
 ### Konventionsbasierte Richtlinien
 
 Zusätzlich zum expliziten `customPoliciesPath` erkennt und lädt failproofai automatisch Richtliniendateien aus `.failproofai/policies/`-Verzeichnissen:
 
-| Ebene | Verzeichnis | Scope |
-|-------|-------------|-------|
-| Projekt | `.failproofai/policies/` | Wird mit dem Team über die Versionsverwaltung geteilt |
+| Ebene | Verzeichnis | Geltungsbereich |
+|-------|-------------|-----------------|
+| Projekt | `.failproofai/policies/` | Gemeinsam mit dem Team über die Versionskontrolle |
 | Benutzer | `~/.failproofai/policies/` | Persönlich, gilt für alle Projekte |
 
 **Dateiabgleich:** Es werden nur Dateien geladen, die dem Muster `*policies.{js,mjs,ts}` entsprechen (z. B. `security-policies.mjs`, `workflow-policies.js`). Andere Dateien im Verzeichnis werden ignoriert.
 
-**Keine Konfiguration erforderlich:** Konventionsrichtlinien benötigen keine Einträge in `policies-config.json`. Legen Sie die Dateien einfach im Verzeichnis ab und sie werden beim nächsten Hook-Ereignis aufgenommen.
+**Keine Konfiguration nötig:** Konventionsrichtlinien benötigen keine Einträge in `policies-config.json`. Lege die Dateien einfach im Verzeichnis ab, und sie werden beim nächsten Hook-Ereignis aufgegriffen.
 
-**Vereinigtes Laden:** Sowohl das Projekt- als auch das Benutzerkonventionsverzeichnis werden durchsucht. Alle passenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das das Prinzip „erster Scope gewinnt" verwendet).
+**Vereinigtes Laden:** Sowohl das Projekt- als auch das Benutzerkonventionsverzeichnis werden durchsucht. Alle übereinstimmenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das nach dem Prinzip „erste Ebene gewinnt" vorgeht).
 
-Weitere Details und Beispiele finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies).
+Weitere Details und Beispiele findest du unter [Benutzerdefinierte Richtlinien](/de/custom-policies).
 
 ### `llm`
 
@@ -189,18 +189,18 @@ LLM-Client-Konfiguration für Richtlinien, die KI-Aufrufe durchführen. Für die
 
 ## Konfiguration über die CLI verwalten
 
-Die Befehle `policies --install` und `policies --uninstall` schreiben in Claude Codes `settings.json` (die Hook-Einstiegspunkte), während `policies-config.json` die Datei ist, die Sie direkt verwalten. Beide sind voneinander getrennt:
+Die Befehle `policies --install` und `policies --uninstall` schreiben in Claude Codes `settings.json` (die Hook-Einstiegspunkte), während `policies-config.json` die Datei ist, die du direkt verwaltest. Beide sind voneinander getrennt:
 
-- **`settings.json`** – weist Claude Code an, bei jeder Toolnutzung `failproofai --hook <event>` aufzurufen
-- **`policies-config.json`** – teilt failproofai mit, welche Richtlinien mit welchen Parametern ausgewertet werden sollen
+- **`settings.json`** – weist Claude Code an, bei jeder Tool-Nutzung `failproofai --hook <event>` aufzurufen
+- **`policies-config.json`** – weist failproofai an, welche Richtlinien mit welchen Parametern ausgewertet werden sollen
 
-Sie können `policies-config.json` jederzeit direkt bearbeiten; Änderungen treten sofort beim nächsten Hook-Ereignis in Kraft, ohne dass ein Neustart erforderlich ist.
+Du kannst `policies-config.json` jederzeit direkt bearbeiten; Änderungen treten beim nächsten Hook-Ereignis sofort in Kraft – kein Neustart erforderlich.
 
 ---
 
 ## Beispiel: Konfiguration auf Projektebene mit Team-Standardwerten
 
-Committen Sie `.failproofai/policies-config.json` in Ihr Repository:
+Checke `.failproofai/policies-config.json` in dein Repository ein:
 
 ```json
 {
@@ -219,4 +219,4 @@ Committen Sie `.failproofai/policies-config.json` in Ihr Repository:
 }
 ```
 
-Jeder Entwickler kann dann `.failproofai/policies-config.local.json` (per .gitignore ausgeschlossen) für persönliche Überschreibungen erstellen, ohne die Teamkollegen zu beeinflussen.
+Jeder Entwickler kann dann `.failproofai/policies-config.local.json` (via gitignore ausgeschlossen) für persönliche Überschreibungen erstellen, ohne die Teammitglieder zu beeinflussen.