failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/de/cli/list-policies.mdx

@@ -0,0 +1,31 @@
+---
+title: Richtlinien auflisten
+description: "Anzeigen welche Richtlinien aktiviert sind, ihre Parameter und benutzerdefinierte Richtlinien"
+---
+
+```bash
+failproofai policies
+```
+
+Zeigt alle Richtlinien mit ihrem Status, konfigurierten Parametern und benutzerdefinierten Richtlinien an.
+
+## Beispielausgabe
+
+```text
+Failproof AI Hook Policies (user)
+
+  Status  Name                          Description
+  ──────  ──────────────────────────────────────────────────────────────
+  ✓       block-sudo                    Block sudo commands
+            allowPatterns: ["sudo systemctl status"]
+  ✓       block-rm-rf                   Block recursive deletions
+  ✗       block-curl-pipe-sh            Block curl|bash patterns
+  ✓       sanitize-api-keys             Redact API keys from output
+            additionalPatterns: [{ regex: "MY_TOKEN_...", label: "..." }]
+
+  ── Custom Policies (/home/alice/myproject/my-policies.js) ──────────────
+  ✓       require-jira-ticket           Block commits without ticket
+  ✓       approval-gate                 Approval gate for destructive ops
+```
+
+Unbekannte Schlüssel in `policyParams` werden hier markiert, damit Sie Tippfehler frühzeitig erkennen können.

package/.next/standalone/docs/de/cli/remove-policies.mdx

@@ -0,0 +1,44 @@
+---
+title: Richtlinien deinstallieren
+description: "Hook-Einträge aus den Einstellungen von Claude Code entfernen"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+Entfernt failproofai-Hook-Einträge aus der `settings.json` von Claude Code.
+
+Aliase: `failproofai p -u`
+
+## Optionen
+
+| Flag | Beschreibung |
+|------|-------------|
+| `--scope user` | Aus den globalen Einstellungen entfernen (Standard) |
+| `--scope project` | Aus den Projekteinstellungen entfernen |
+| `--scope local` | Aus den lokalen Einstellungen entfernen |
+| `--scope all` | Aus allen Geltungsbereichen auf einmal entfernen |
+| `--custom` / `-c` | Den `customPoliciesPath` aus der Konfiguration löschen |
+| `--beta` | Nur Beta-Richtlinien aus der Konfiguration entfernen |
+
+## Verhalten
+
+- **Keine Richtliniennamen** – entfernt alle failproofai-Hook-Einträge aus der Einstellungsdatei
+- **Bestimmte Namen** – deaktiviert diese Richtlinien, behält die installierten Hooks aber bei
+
+## Beispiele
+
+```bash
+# Alle Hooks global entfernen
+failproofai policies --uninstall
+
+# Eine bestimmte Richtlinie deaktivieren (Hooks bleiben installiert)
+failproofai policies --uninstall block-sudo
+
+# Hooks aus allen Geltungsbereichen entfernen
+failproofai policies --uninstall --scope all
+
+# Pfad für benutzerdefinierte Richtlinien löschen
+failproofai policies --uninstall --custom
+```

package/.next/standalone/docs/de/cli/version.mdx

@@ -0,0 +1,12 @@
+---
+title: Version prüfen
+description: "Die installierte failproofai-Version ausgeben"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+Gibt die installierte Versionsnummer aus.

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

@@ -0,0 +1,222 @@
+---
+title: Konfiguration
+description: "Konfigurationsdateiformat, Drei-Scope-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.
+
+---
+
+## Konfigurationsscopes
+
+Es gibt drei Konfigurationsscopes, die in Prioritätsreihenfolge ausgewertet werden:
+
+| Scope | 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 |
+| **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.
+
+### Zusammenführungsregeln
+
+**`enabledPolicies`** – die Vereinigung aller drei Scopes. Eine Richtlinie, die auf irgendeiner Ebene aktiviert ist, ist aktiv.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+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.
+
+```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
+```
+
+```text
+project:  (kein block-sudo-Eintrag)
+local:    (kein block-sudo-Eintrag)
+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.
+
+**`llm`** – der erste Scope, der diesen Wert definiert, gewinnt.
+
+---
+
+## Konfigurationsdateiformat
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "sanitize-jwt",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "block-rm-rf": {
+      "allowPaths": ["/tmp"]
+    },
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  },
+  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
+}
+```
+
+---
+
+## Feldreferenz
+
+### `enabledPolicies`
+
+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).
+
+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).
+
+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.
+
+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.
+
+#### `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.
+
+Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom/`), Projektkonvention (`.failproofai-project/`) oder Benutzerkonvention (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Try creating a fresh branch instead."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Use apt-get directly without sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Ask the user for approval first."
+    }
+  }
+}
+```
+
+Wenn `block-force-push` verweigert, sieht Claude: *„Force-Pushing ist blockiert. Versuche stattdessen, einen neuen Branch zu erstellen."*
+
+Nicht-String-Werte und leere Zeichenketten werden stillschweigend ignoriert. Wenn `hint` nicht gesetzt ist, bleibt das Verhalten unverändert (abwärtskompatibel).
+
+### `customPoliciesPath`
+
+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).
+
+### Konventionsbasierte Richtlinien (ab v0.0.2-beta.7)
+
+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 |
+| 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.
+
+**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).
+
+Weitere Details und Beispiele finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies).
+
+### `llm`
+
+Typ: `object` (optional)
+
+LLM-Client-Konfiguration für Richtlinien, die KI-Aufrufe durchführen. Für die meisten Setups nicht erforderlich.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## 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:
+
+- **`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
+
+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.
+
+---
+
+## Beispiel: Konfiguration auf Projektebene mit Team-Standardwerten
+
+Committen Sie `.failproofai/policies-config.json` in Ihr Repository:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Jeder Entwickler kann dann `.failproofai/policies-config.local.json` (per .gitignore ausgeschlossen) für persönliche Überschreibungen erstellen, ohne die Teamkollegen zu beeinflussen.

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

@@ -0,0 +1,357 @@
+---
+title: Benutzerdefinierte Richtlinien
+description: "Schreiben Sie 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.
+
+---
+
+## Schnellbeispiel
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+Installation:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Zwei Wege zum Laden benutzerdefinierter Richtlinien
+
+### Option 1: Konventionsbasiert (empfohlen, v0.0.2-beta.7+)
+
+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.
+
+```
+# Projektebene – per Git eingecheckt, mit dem Team geteilt
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Benutzerebene – persönlich, gilt für alle Projekte
+~/.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
+- 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.
+</Tip>
+
+### Option 2: Expliziter Dateipfad
+
+```bash
+# Mit einer benutzerdefinierten Richtliniendatei installieren
+failproofai policies --install --custom ./my-policies.js
+
+# Den Richtliniendateipfad ersetzen
+failproofai policies --install --custom ./new-policies.js
+
+# Den benutzerdefinierten Richtlinienpfad aus der Konfiguration entfernen
+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.
+
+### Beide Methoden kombinieren
+
+Konventionsbasierte Richtlinien und die explizite `--custom`-Datei können nebeneinander existieren. Ladereihenfolge:
+
+1. Explizite `customPoliciesPath`-Datei (falls konfiguriert)
+2. Projekt-Konventionsdateien (`{cwd}/.failproofai/policies/`, alphabetisch)
+3. Benutzer-Konventionsdateien (`~/.failproofai/policies/`, alphabetisch)
+
+---
+
+## API
+
+### Import
+
+```js
+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.
+
+```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
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Entscheidungs-Hilfsfunktionen
+
+| Funktion | Wirkung | Verwendung |
+|----------|---------|------------|
+| `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 |
+
+`deny(message)` – die Nachricht erscheint gegenüber Claude mit dem Präfix `"Blocked by failproofai:"`. Ein einzelnes `deny` bricht die gesamte 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.
+
+<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.
+</Tip>
+
+### Informative allow-Nachrichten (Beta)
+
+<Note>
+`allow(message)` ist eine Beta-Funktion, verfügbar seit v0.0.2-beta.3. Die API kann sich in zukünftigen Releases ändern. Ältere Versionen unterstützen nur `allow()` ohne Argumente.
+</Note>
+
+`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.
+
+| 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 |
+
+Anwendungsfälle:
+- **Statusbestätigungen:** `allow("All CI checks passed.")` – teilt Claude mit, dass alles in Ordnung 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
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... Branch-Status prüfen ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### `PolicyContext`-Felder
+
+| Feld | Typ | Beschreibung |
+|------|-----|--------------|
+| `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 |
+| `session` | `SessionMetadata \| undefined` | Sitzungskontext (siehe unten) |
+
+### `SessionMetadata`-Felder
+
+| Feld | Typ | Beschreibung |
+|------|-----|--------------|
+| `sessionId` | `string` | Claude Code-Sitzungsbezeichner |
+| `cwd` | `string` | Arbeitsverzeichnis der Claude Code-Sitzung |
+| `transcriptPath` | `string` | Pfad zur JSONL-Transkriptdatei der Sitzung |
+
+### Ereignistypen
+
+| Ereignis | 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) |
+| `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 |
+
+---
+
+## Auswertungsreihenfolge
+
+Richtlinien werden in dieser Reihenfolge ausgewertet:
+
+1. Eingebaute Richtlinien (in Definitionsreihenfolge)
+2. Explizite benutzerdefinierte Richtlinien aus `customPoliciesPath` (in `.add()`-Reihenfolge)
+3. Konventionsrichtlinien aus dem Projekt `.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb)
+4. Konventionsrichtlinien aus dem Benutzerverzeichnis `~/.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb)
+
+<Note>
+Das erste `deny` bricht alle nachfolgenden Richtlinien ab. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam zugestellt.
+</Note>
+
+---
+
+## Transitive Importe
+
+Benutzerdefinierte Richtliniendateien können lokale Module über relative Pfade importieren:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+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.
+
+---
+
+## Ereignistypfilterung
+
+Verwenden Sie `match.events`, um einzuschränken, wann eine Richtlinie ausgelöst wird:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Wird nur ausgelöst, wenn die Sitzung endet
+    // ctx.session.transcriptPath enthält das vollständige Sitzungsprotokoll
+    return allow();
+  },
+});
+```
+
+Lassen Sie `match` vollständig weg, um bei jedem Ereignistyp auszulösen.
+
+---
+
+## Fehlerbehandlung und Fehlermodi
+
+Benutzerdefinierte Richtlinien sind **fail-open**: Fehler blockieren niemals eingebaute Richtlinien und bringen den Hook-Handler nicht zum Absturz.
+
+| Fehler | Verhalten |
+|--------|-----------|
+| `customPoliciesPath` nicht gesetzt | Keine expliziten benutzerdefinierten Richtlinien werden ausgeführt; Konventionsrichtlinien und eingebaute Richtlinien laufen normal weiter |
+| Datei nicht gefunden | Warnung wird in `~/.failproofai/hook.log` protokolliert; eingebaute Richtlinien laufen weiter |
+| 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 |
+| Konventionsverzeichnis fehlt | Keine Konventionsrichtlinien werden ausgeführt; kein Fehler |
+
+<Tip>
+Um Fehler in benutzerdefinierten Richtlinien zu debuggen, beobachten Sie die Log-Datei:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Vollständiges Beispiel: mehrere Richtlinien
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Verhindert, dass der Agent in das secrets/-Verzeichnis schreibt
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// Agenten auf Kurs halten: Tests vor dem Commit prüfen
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// Ungeplante Abhängigkeitsänderungen während des Freeze verhindern
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## Beispiele
+
+Das Verzeichnis `examples/` enthält sofort 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) |
+
+### Explizite Dateibeispiele verwenden
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Konventionsbasierte Beispiele verwenden
+
+```bash
+# Auf Projektebene kopieren
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Oder auf Benutzerebene kopieren
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Kein Installationsbefehl erforderlich – die Dateien werden beim nächsten Hook-Ereignis automatisch erkannt.