failproofai 0.0.2 → 0.0.4-beta.0

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

@@ -0,0 +1,31 @@
+---
+title: Lister les politiques
+description: "Voir quelles politiques sont activées, leurs paramètres, et les politiques personnalisées"
+---
+
+```bash
+failproofai policies
+```
+
+Affiche toutes les politiques avec leur statut, leurs paramètres configurés, et les politiques personnalisées.
+
+## Exemple de sortie
+
+```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
+```
+
+Les clés inconnues dans `policyParams` sont signalées ici afin que vous puissiez détecter les fautes de frappe rapidement.

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

@@ -0,0 +1,43 @@
+---
+title: Désinstaller les politiques
+description: "Supprimer les entrées de hook des paramètres de Claude Code"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+Supprime les entrées de hook failproofai du fichier `settings.json` de Claude Code.
+
+Alias : `failproofai p -u`
+
+## Options
+
+| Indicateur | Description |
+|------------|-------------|
+| `--scope user` | Supprimer des paramètres globaux (par défaut) |
+| `--scope project` | Supprimer des paramètres du projet |
+| `--scope local` | Supprimer des paramètres locaux |
+| `--scope all` | Supprimer de tous les scopes à la fois |
+| `--custom` / `-c` | Effacer le `customPoliciesPath` de la configuration |
+
+## Comportement
+
+- **Aucun nom de politique** — supprime toutes les entrées de hook failproofai du fichier de paramètres
+- **Noms spécifiques** — désactive ces politiques mais conserve les hooks installés
+
+## Exemples
+
+```bash
+# Supprimer tous les hooks globalement
+failproofai policies --uninstall
+
+# Désactiver une politique spécifique (conserve les hooks installés)
+failproofai policies --uninstall block-sudo
+
+# Supprimer les hooks de tous les scopes
+failproofai policies --uninstall --scope all
+
+# Effacer le chemin des politiques personnalisées
+failproofai policies --uninstall --custom
+```

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

@@ -0,0 +1,12 @@
+---
+title: Vérifier la version
+description: "Afficher la version installée de failproofai"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+Affiche le numéro de version installé.

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

@@ -0,0 +1,222 @@
+---
+title: Configuration
+description: "Format du fichier de configuration, système à trois portées et règles de fusion"
+icon: gear
+---
+
+failproofai utilise des fichiers de configuration JSON pour contrôler quelles politiques sont actives, leur comportement et l'emplacement des politiques personnalisées. La configuration est conçue pour être facilement partageable avec votre équipe — committez-la dans votre dépôt et chaque développeur bénéficie du même filet de sécurité pour l'agent.
+
+---
+
+## Portées de configuration
+
+Il existe trois portées de configuration, évaluées par ordre de priorité :
+
+| Portée | Chemin du fichier | Objectif |
+|--------|-------------------|----------|
+| **project** | `.failproofai/policies-config.json` | Paramètres par dépôt, committés dans le contrôle de version |
+| **local** | `.failproofai/policies-config.local.json` | Surcharges personnelles par dépôt, ignorées par git |
+| **global** | `~/.failproofai/policies-config.json` | Paramètres par défaut au niveau utilisateur pour tous les projets |
+
+Quand failproofai reçoit un événement de hook, il charge et fusionne les trois fichiers existants pour le répertoire de travail courant.
+
+### Règles de fusion
+
+**`enabledPolicies`** — union des trois portées. Une politique activée à n'importe quel niveau est active.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← union dédupliquée
+```
+
+**`policyParams`** — la première portée qui définit les paramètres d'une politique donnée l'emporte entièrement. Il n'y a pas de fusion profonde des valeurs au sein des paramètres d'une politique.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project l'emporte, global ignoré
+```
+
+```text
+project:  (aucune entrée block-sudo)
+local:    (aucune entrée block-sudo)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← retombe sur global
+```
+
+**`customPoliciesPath`** — la première portée qui le définit l'emporte.
+
+**`llm`** — la première portée qui le définit l'emporte.
+
+---
+
+## Format du fichier de configuration
+
+```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"
+}
+```
+
+---
+
+## Référence des champs
+
+### `enabledPolicies`
+
+Type : `string[]`
+
+Liste des noms de politiques à activer. Les noms doivent correspondre exactement aux identifiants de politique affichés par `failproofai policies`. Consultez [Politiques intégrées](/fr/built-in-policies) pour la liste complète.
+
+Les politiques absentes de `enabledPolicies` sont inactives, même si elles ont des entrées dans `policyParams`.
+
+### `policyParams`
+
+Type : `Record<string, Record<string, unknown>>`
+
+Surcharges de paramètres par politique. La clé externe est le nom de la politique ; les clés internes sont spécifiques à chaque politique. Chaque politique documente ses paramètres disponibles dans [Politiques intégrées](/fr/built-in-policies).
+
+Si une politique possède des paramètres mais que vous ne les spécifiez pas, les valeurs par défaut intégrées de la politique sont utilisées. Les utilisateurs qui ne configurent pas `policyParams` du tout obtiennent un comportement identique aux versions précédentes.
+
+Les clés inconnues dans le bloc de paramètres d'une politique sont silencieusement ignorées au moment du déclenchement du hook, mais signalées comme avertissements lors de l'exécution de `failproofai policies`.
+
+#### `hint` (transversal)
+
+Type : `string` (optionnel)
+
+Un message ajouté à la raison lorsqu'une politique retourne `deny` ou `instruct`. Utilisez-le pour donner à Claude des indications exploitables sans modifier la politique elle-même.
+
+Fonctionne avec n'importe quel type de politique — intégrée, personnalisée (`custom/`), convention de projet (`.failproofai-project/`), ou convention utilisateur (`.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."
+    }
+  }
+}
+```
+
+Lorsque `block-force-push` refuse, Claude voit : *« Force-pushing is blocked. Try creating a fresh branch instead. »*
+
+Les valeurs non-chaînes et les chaînes vides sont silencieusement ignorées. Si `hint` n'est pas défini, le comportement est inchangé (rétrocompatible).
+
+### `customPoliciesPath`
+
+Type : `string` (chemin absolu)
+
+Chemin vers un fichier JavaScript contenant des politiques de hook personnalisées. Ce champ est défini automatiquement par `failproofai policies --install --custom <path>` (le chemin est résolu en chemin absolu avant d'être enregistré).
+
+Le fichier est chargé à chaque événement de hook — il n'y a pas de mise en cache. Consultez [Politiques personnalisées](/fr/custom-policies) pour les détails de création.
+
+### Politiques basées sur les conventions (v0.0.2-beta.7+)
+
+En plus du `customPoliciesPath` explicite, failproofai découvre et charge automatiquement les fichiers de politiques depuis les répertoires `.failproofai/policies/` :
+
+| Niveau | Répertoire | Portée |
+|--------|-----------|--------|
+| Projet | `.failproofai/policies/` | Partagé avec l'équipe via le contrôle de version |
+| Utilisateur | `~/.failproofai/policies/` | Personnel, s'applique à tous les projets |
+
+**Correspondance de fichiers :** Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés (par exemple `security-policies.mjs`, `workflow-policies.js`). Les autres fichiers du répertoire sont ignorés.
+
+**Aucune configuration nécessaire :** Les politiques de convention ne nécessitent aucune entrée dans `policies-config.json`. Déposez simplement les fichiers dans le répertoire et ils seront pris en compte au prochain événement de hook.
+
+**Chargement par union :** Les répertoires de convention du projet et de l'utilisateur sont tous deux analysés. Tous les fichiers correspondants des deux niveaux sont chargés (contrairement à `customPoliciesPath` qui utilise la règle du premier gagnant).
+
+Consultez [Politiques personnalisées](/fr/custom-policies) pour plus de détails et des exemples.
+
+### `llm`
+
+Type : `object` (optionnel)
+
+Configuration du client LLM pour les politiques qui effectuent des appels à l'IA. Non requis pour la plupart des configurations.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Gestion de la configuration depuis l'interface en ligne de commande
+
+Les commandes `policies --install` et `policies --uninstall` écrivent dans le fichier `settings.json` de Claude Code (les points d'entrée des hooks), tandis que `policies-config.json` est le fichier que vous gérez directement. Les deux sont distincts :
+
+- **`settings.json`** — indique à Claude Code d'appeler `failproofai --hook <event>` à chaque utilisation d'outil
+- **`policies-config.json`** — indique à failproofai quelles politiques évaluer et avec quels paramètres
+
+Vous pouvez modifier `policies-config.json` directement à tout moment ; les modifications prennent effet immédiatement au prochain événement de hook, sans redémarrage nécessaire.
+
+---
+
+## Exemple : configuration au niveau projet avec les paramètres par défaut de l'équipe
+
+Committez `.failproofai/policies-config.json` dans votre dépôt :
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Chaque développeur peut ensuite créer `.failproofai/policies-config.local.json` (ignoré par git) pour ses surcharges personnelles sans affecter ses coéquipiers.

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

@@ -0,0 +1,357 @@
+---
+title: Politiques personnalisées
+description: "Écrivez vos propres politiques en JavaScript — appliquez des conventions, prévenez la dérive, détectez les échecs, intégrez des systèmes externes"
+icon: code
+---
+
+Les politiques personnalisées vous permettent d'écrire des règles pour n'importe quel comportement d'agent : appliquer des conventions de projet, prévenir la dérive, bloquer les opérations destructrices, détecter les agents bloqués, ou s'intégrer avec Slack, des workflows d'approbation, et bien plus. Elles utilisent le même système d'événements hook et les mêmes décisions `allow`, `deny`, `instruct` que les politiques intégrées.
+
+---
+
+## Exemple rapide
+
+```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();
+  },
+});
+```
+
+Installez-le :
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Deux façons de charger des politiques personnalisées
+
+### Option 1 : Par convention (recommandé, v0.0.2-beta.7+)
+
+Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et ils sont chargés automatiquement — aucun indicateur ni changement de configuration requis. Cela fonctionne comme les git hooks : déposez un fichier, il est pris en compte immédiatement.
+
+```
+# Niveau projet — commité dans git, partagé avec l'équipe
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Niveau utilisateur — personnel, s'applique à tous les projets
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Comment ça fonctionne :**
+- Les répertoires projet et utilisateur sont tous deux analysés (union — pas de priorité au premier scope)
+- Les fichiers sont chargés alphabétiquement dans chaque répertoire. Préfixez avec `01-`, `02-` pour contrôler l'ordre
+- Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés ; les autres fichiers sont ignorés
+- Chaque fichier est chargé indépendamment (fail-open par fichier)
+- Fonctionne en parallèle avec les indicateurs `--custom` explicites et les politiques intégrées
+
+<Tip>
+Les politiques par convention sont le moyen le plus simple de partager des politiques au sein d'une équipe. Commitez `.failproofai/policies/` dans git et chaque membre de l'équipe les reçoit automatiquement.
+</Tip>
+
+### Option 2 : Chemin de fichier explicite
+
+```bash
+# Installer avec un fichier de politiques personnalisées
+failproofai policies --install --custom ./my-policies.js
+
+# Remplacer le chemin du fichier de politiques
+failproofai policies --install --custom ./new-policies.js
+
+# Supprimer le chemin de politiques personnalisées de la configuration
+failproofai policies --uninstall --custom
+```
+
+Le chemin absolu résolu est stocké dans `policies-config.json` sous `customPoliciesPath`. Le fichier est chargé à nouveau à chaque événement hook — aucune mise en cache entre les événements.
+
+### Utiliser les deux ensemble
+
+Les politiques par convention et le fichier `--custom` explicite peuvent coexister. Ordre de chargement :
+
+1. Fichier `customPoliciesPath` explicite (si configuré)
+2. Fichiers de convention projet (`{cwd}/.failproofai/policies/`, alphabétique)
+3. Fichiers de convention utilisateur (`~/.failproofai/policies/`, alphabétique)
+
+---
+
+## API
+
+### Import
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Enregistre une politique. Appelez cette méthode autant de fois que nécessaire pour plusieurs politiques dans le même fichier.
+
+```ts
+customPolicies.add({
+  name: string;                         // obligatoire - identifiant unique
+  description?: string;                 // affiché dans la sortie de `failproofai policies`
+  match?: { events?: HookEventType[] }; // filtrer par type d'événement ; omettre pour tout correspondre
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Fonctions d'aide aux décisions
+
+| Fonction | Effet | Utiliser quand |
+|----------|--------|----------|
+| `allow()` | Autorise l'opération silencieusement | L'action est sûre, aucun message nécessaire |
+| `deny(message)` | Bloque l'opération | L'agent ne doit pas effectuer cette action |
+| `instruct(message)` | Ajoute du contexte sans bloquer | Fournir à l'agent du contexte supplémentaire pour rester sur la bonne voie |
+
+`deny(message)` — le message apparaît à Claude préfixé par `"Blocked by failproofai:"`. Un seul `deny` court-circuite toute évaluation ultérieure.
+
+`instruct(message)` — le message est ajouté au contexte de Claude pour l'appel d'outil en cours. Tous les messages `instruct` sont accumulés et délivrés ensemble.
+
+<Tip>
+Vous pouvez ajouter des instructions supplémentaires à n'importe quel message `deny` ou `instruct` en ajoutant un champ `hint` dans `policyParams` — sans modifier le code. Cela fonctionne également pour les politiques personnalisées (`custom/`), par convention projet (`.failproofai-project/`) et par convention utilisateur (`.failproofai-user/`). Voir [Configuration → hint](/fr/configuration#hint-cross-cutting) pour les détails.
+</Tip>
+
+### Messages allow informationnels (bêta)
+
+<Note>
+`allow(message)` est une fonctionnalité bêta disponible depuis la v0.0.2-beta.3. L'API peut changer dans les versions futures. Les versions antérieures ne prennent en charge que `allow()` sans arguments.
+</Note>
+
+`allow(message)` autorise l'opération **et** envoie un message informationnel à Claude. Le message est délivré en tant que `additionalContext` dans la réponse stdout du gestionnaire de hook — le même mécanisme qu'`instruct`, mais sémantiquement différent : c'est une mise à jour de statut, pas un avertissement.
+
+| Fonction | Effet | Utiliser quand |
+|----------|--------|----------|
+| `allow(message)` | Autorise et envoie du contexte à Claude | Confirmer qu'une vérification a réussi, ou expliquer pourquoi une vérification a été ignorée |
+
+Cas d'utilisation :
+- **Confirmations de statut :** `allow("All CI checks passed.")` — indique à Claude que tout est en ordre
+- **Explications fail-open :** `allow("GitHub CLI not installed, skipping CI check.")` — indique à Claude pourquoi une vérification a été ignorée pour qu'il ait le contexte complet
+- **Accumulation de messages multiples :** si plusieurs politiques retournent chacune `allow(message)`, tous les messages sont joints par des sauts de ligne et délivrés ensemble
+
+```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.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### Champs de `PolicyContext`
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | L'outil appelé (ex. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Les paramètres d'entrée de l'outil |
+| `payload` | `Record<string, unknown>` | Payload brut complet de l'événement provenant de Claude Code |
+| `session` | `SessionMetadata \| undefined` | Contexte de session (voir ci-dessous) |
+
+### Champs de `SessionMetadata`
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `sessionId` | `string` | Identifiant de session Claude Code |
+| `cwd` | `string` | Répertoire de travail de la session Claude Code |
+| `transcriptPath` | `string` | Chemin vers le fichier de transcription JSONL de la session |
+
+### Types d'événements
+
+| Événement | Quand il se déclenche | Contenu de `toolInput` |
+|-------|--------------|----------------------|
+| `PreToolUse` | Avant que Claude exécute un outil | L'entrée de l'outil (ex. `{ command: "..." }` pour Bash) |
+| `PostToolUse` | Après qu'un outil se termine | L'entrée de l'outil + `tool_result` (la sortie) |
+| `Notification` | Quand Claude envoie une notification | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — les hooks doivent toujours retourner `allow()`, ils ne peuvent pas bloquer les notifications |
+| `Stop` | Quand la session Claude se termine | Vide |
+
+---
+
+## Ordre d'évaluation
+
+Les politiques sont évaluées dans cet ordre :
+
+1. Politiques intégrées (dans l'ordre de définition)
+2. Politiques personnalisées explicites de `customPoliciesPath` (dans l'ordre `.add()`)
+3. Politiques de convention projet `.failproofai/policies/` (fichiers alphabétiques, ordre `.add()` à l'intérieur)
+4. Politiques de convention utilisateur `~/.failproofai/policies/` (fichiers alphabétiques, ordre `.add()` à l'intérieur)
+
+<Note>
+Le premier `deny` court-circuite toutes les politiques suivantes. Tous les messages `instruct` sont accumulés et délivrés ensemble.
+</Note>
+
+---
+
+## Imports transitifs
+
+Les fichiers de politiques personnalisées peuvent importer des modules locaux en utilisant des chemins relatifs :
+
+```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");
+  },
+});
+```
+
+Tous les imports relatifs accessibles depuis le fichier d'entrée sont résolus. Cela est implémenté en réécrivant les imports `from "failproofai"` vers le chemin dist réel et en créant des fichiers `.mjs` temporaires pour assurer la compatibilité ESM.
+
+---
+
+## Filtrage par type d'événement
+
+Utilisez `match.events` pour limiter le déclenchement d'une politique :
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Ne se déclenche que lorsque la session se termine
+    // ctx.session.transcriptPath contient le journal complet de la session
+    return allow();
+  },
+});
+```
+
+Omettez `match` entièrement pour se déclencher sur chaque type d'événement.
+
+---
+
+## Gestion des erreurs et modes de défaillance
+
+Les politiques personnalisées sont **fail-open** : les erreurs ne bloquent jamais les politiques intégrées ni ne font planter le gestionnaire de hook.
+
+| Défaillance | Comportement |
+|---------|----------|
+| `customPoliciesPath` non défini | Aucune politique personnalisée explicite ne s'exécute ; les politiques de convention et les politiques intégrées continuent normalement |
+| Fichier introuvable | Avertissement consigné dans `~/.failproofai/hook.log` ; les politiques intégrées continuent |
+| Erreur de syntaxe/import (explicite) | Erreur consignée dans `~/.failproofai/hook.log` ; politiques personnalisées explicites ignorées |
+| Erreur de syntaxe/import (convention) | Erreur consignée ; ce fichier ignoré, les autres fichiers de convention se chargent quand même |
+| `fn` lève une exception à l'exécution | Erreur consignée ; ce hook traité comme `allow` ; les autres hooks continuent |
+| `fn` prend plus de 10s | Timeout consigné ; traité comme `allow` |
+| Répertoire de convention manquant | Aucune politique de convention ne s'exécute ; aucune erreur |
+
+<Tip>
+Pour déboguer les erreurs de politiques personnalisées, surveillez le fichier journal :
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Exemple complet : plusieurs politiques
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Prevent agent from writing to secrets/ directory
+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();
+  },
+});
+
+// Keep the agent on track: verify tests before committing
+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();
+  },
+});
+
+// Prevent unplanned dependency changes during freeze
+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 };
+```
+
+---
+
+## Exemples
+
+Le répertoire `examples/` contient des fichiers de politiques prêts à l'emploi :
+
+| Fichier | Contenu |
+|------|----------|
+| `examples/policies-basic.js` | Cinq politiques de démarrage couvrant les modes d'échec courants des agents |
+| `examples/policies-advanced/index.js` | Patterns avancés : imports transitifs, appels asynchrones, nettoyage de sortie et hooks de fin de session |
+| `examples/convention-policies/security-policies.mjs` | Politiques de sécurité par convention (bloquer les écritures .env, empêcher la réécriture de l'historique git) |
+| `examples/convention-policies/workflow-policies.mjs` | Politiques de workflow par convention (rappels de tests, audit des écritures de fichiers) |
+
+### Utiliser les exemples de fichiers explicites
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Utiliser les exemples par convention
+
+```bash
+# Copier au niveau projet
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Ou copier au niveau utilisateur
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Aucune commande d'installation requise — les fichiers sont pris en compte automatiquement au prochain événement hook.