failproofai 0.0.2-beta.8 → 0.0.2-beta.9

package/.next/standalone/docs/es/package-aliases.mdx

@@ -0,0 +1,82 @@
+---
+title: Alias de Paquetes
+description: "Alias registrados para prevención de typosquatting y cómo funcionan"
+icon: copy
+---
+
+## Paquete oficial
+
+El paquete npm canónico es **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# or
+bun add -g failproofai
+```
+
+---
+
+## Por qué tenemos los alias registrados
+
+El typosquatting es un ataque común a la cadena de suministro en el que un actor malicioso registra un nombre de paquete que difiere por una sola tecla del paquete popular. Los usuarios que escriben mal el comando de instalación terminan ejecutando código controlado por el atacante con acceso completo al sistema — exactamente el tipo de amenaza que Failproof AI está diseñado para defender.
+
+Para eliminar esta superficie de ataque, **registramos de forma preventiva todas las variantes ortográficas y de formato más comunes** de `failproofai` en npm. Ninguno de estos nombres puede ser registrado por terceros. Cada uno es un proxy ligero que instala y delega al paquete real `failproofai`.
+
+---
+
+## Alias registrados
+
+**Variantes de formato** - diferentes formas de escribir "failproof ai":
+
+| Paquete | Estado |
+|---------|--------|
+| `failproof` | ✅ Publicado |
+| `failproof-ai` | ⏳ Pendiente de aprobación de npm |
+| `fail-proof-ai` | ⏳ Pendiente de aprobación de npm |
+| `failproof_ai` | ⏳ Pendiente de aprobación de npm |
+| `fail_proof_ai` | ⏳ Pendiente de aprobación de npm |
+| `fail-proofai` | ⏳ Pendiente de aprobación de npm |
+
+**Errores tipográficos `failprof*`** - falta una `o` en "proof":
+
+| Paquete | Estado |
+|---------|--------|
+| `failprof` | ✅ Publicado |
+| `failprof-ai` | ✅ Publicado |
+| `failprofai` | ⏳ Pendiente de aprobación de npm |
+| `fail-prof-ai` | ⏳ Pendiente de aprobación de npm |
+| `failprof_ai` | ⏳ Pendiente de aprobación de npm |
+
+**Errores tipográficos `faliproof*`** - `a` e `i` transpuestas:
+
+| Paquete | Estado |
+|---------|--------|
+| `faliproof` | ✅ Publicado |
+| `faliproof-ai` | ✅ Publicado |
+| `faliproofai` | ⏳ Pendiente de aprobación de npm |
+
+> **¿Por qué están pendientes?** La política de prevención de spam de npm bloquea nombres que, tras eliminar la puntuación y aplicar comprobaciones de similitud, se normalizan a la misma cadena que un paquete existente. Hemos contactado con el soporte de npm para reservar estos nombres con fines de protección contra squatting. Se activarán una vez aprobados.
+
+Puedes verificar que cualquier alias publicado nos pertenece:
+
+```bash
+npm info failproof
+# Look for: "ExosphereHost Inc." in the maintainers field
+```
+
+---
+
+## Cómo funcionan los alias
+
+Cada paquete alias:
+
+1. Incluye `failproofai` como dependencia, por lo que el paquete real (incluida la configuración de su hook `postinstall`) se ejecuta durante la instalación
+2. Expone un binario con su propio nombre (p. ej. `failprof-ai`) que redirige todos los argumentos al binario `failproofai`
+
+El proxy es un script de Node de dos líneas; no contiene ninguna lógica adicional, no realiza llamadas de red ni recopila datos más allá de lo que hace el propio `failproofai`.
+
+---
+
+## Si encuentras un nombre que nos hemos perdido
+
+Abre un issue en [exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) y lo registraremos.

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

@@ -0,0 +1,260 @@
+---
+title: Pruebas
+description: "Pruebas unitarias, pruebas E2E y utilidades de prueba"
+icon: flask-vial
+---
+
+failproofai cuenta con dos suites de pruebas: **pruebas unitarias** (rápidas, con mocks) y **pruebas end-to-end** (invocaciones reales de subprocesos).
+
+---
+
+## Ejecutar las pruebas
+
+```bash
+# Ejecutar todas las pruebas unitarias una vez
+bun run test:run
+
+# Ejecutar pruebas unitarias en modo watch
+bun run test
+
+# Ejecutar pruebas E2E (requiere configuración previa; ver más abajo)
+bun run test:e2e
+
+# Verificar tipos sin compilar
+bunx tsc --noEmit
+
+# Linting
+bun run lint
+```
+
+---
+
+## Pruebas unitarias
+
+Las pruebas unitarias se encuentran en `__tests__/` y utilizan [Vitest](https://vitest.dev) con `happy-dom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Lógica de políticas para cada builtin
+    hooks-config.test.ts          # Carga de configuración y fusión de scopes
+    policy-evaluator.test.ts      # Inyección de parámetros y orden de evaluación
+    custom-hooks-registry.test.ts # Registro globalThis: add/get/clear
+    custom-hooks-loader.test.ts   # Loader ESM, imports transitivos, manejo de errores
+    manager.test.ts               # Operaciones install/remove/list
+  components/
+    sessions-list.test.tsx        # Componente de lista de sesiones
+    project-list.test.tsx         # Componente de lista de proyectos
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### Escribir una prueba unitaria para una política
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## Pruebas end-to-end
+
+Las pruebas E2E invocan el binario real de `failproofai` como un subproceso, envían un payload JSON a stdin y verifican la salida por stdout y el código de salida. Esto prueba el flujo de integración completo que utiliza Claude Code.
+
+### Configuración
+
+Las pruebas E2E ejecutan el binario directamente desde el código fuente del repositorio. Antes de la primera ejecución, compila el bundle CJS que utilizan los archivos de hooks personalizados cuando importan desde `'failproofai'`:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Luego ejecuta las pruebas:
+
+```bash
+bun run test:e2e
+```
+
+Recompila `dist/` cada vez que modifiques la API pública de hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` o `src/hooks/policy-types.ts`).
+
+### Estructura de las pruebas E2E
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # Lanza el binario, envía el payload JSON, captura código de salida + stdout + stderr
+    fixture-env.ts      # Directorios temporales aislados por prueba con archivos de configuración
+    payloads.ts         # Factorías de payloads precisas para cada tipo de evento de Claude
+  hooks/
+    builtin-policies.e2e.test.ts   # Cada política builtin con subproceso real
+    custom-hooks.e2e.test.ts       # Carga y evaluación de hooks personalizados
+    config-scopes.e2e.test.ts      # Fusión de configuración entre scopes: project/local/global
+    policy-params.e2e.test.ts      # Inyección de parámetros para cada política parametrizada
+```
+
+### Uso de los helpers E2E
+
+**`FixtureEnv`** — entorno aislado por prueba:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - directorio temporal; pásalo como payload.cwd para que detecte .failproofai/policies-config.json
+// env.home   - directorio home aislado; evita que ~/.failproofai real interfiera
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` registra la limpieza con `afterEach` automáticamente.
+
+**`runHook`** — invocar el binario:
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** — factorías de payloads predefinidas:
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### Escribir una prueba E2E
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // allow → stdout vacío
+  });
+});
+```
+
+### Formas de respuesta E2E
+
+| Decisión | Código de salida | stdout |
+|----------|-----------------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (no Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | stdout vacío; motivo en stderr |
+| Allow | `0` | cadena vacía |
+
+### Configuración de Vitest
+
+Las pruebas E2E utilizan `vitest.config.e2e.mts` con:
+
+- `environment: "node"` — no se necesitan globales del navegador
+- `pool: "forks"` — aislamiento real de procesos (las pruebas lanzan subprocesos)
+- `testTimeout: 20_000` — 20 segundos por prueba (arranque del binario + evaluación del hook)
+
+El pool `forks` es importante: los workers basados en hilos comparten `globalThis`, lo que puede interferir con pruebas que lanzan subprocesos. Los forks basados en procesos evitan este problema.
+
+---
+
+## CI
+
+La ejecución completa de CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) debe pasar antes de hacer merge. La suite E2E se ejecuta como un job de CI separado en paralelo.
+
+Consulta [Contributing](../CONTRIBUTING.md) para ver el checklist completo previo al merge.

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

@@ -0,0 +1,332 @@
+---
+title: Architecture
+description: "Fonctionnement interne du gestionnaire de hooks, du chargement de la configuration et de l'évaluation des politiques"
+icon: sitemap
+---
+
+Ce document explique le fonctionnement interne de failproofai : comment le système de hooks intercepte les appels d'outils des agents, comment la configuration est chargée et fusionnée, comment les politiques sont évaluées, et comment le tableau de bord surveille l'activité des agents.
+
+---
+
+## Vue d'ensemble
+
+failproofai comporte deux sous-systèmes indépendants :
+
+1. **Gestionnaire de hooks** - Un sous-processus CLI rapide que Claude Code invoque à chaque appel d'outil d'agent. Il évalue les politiques et retourne une décision.
+2. **Moniteur d'agent (Tableau de bord)** - Une application web Next.js pour surveiller les sessions d'agent et gérer les politiques.
+
+Les deux sous-systèmes partagent les fichiers de configuration dans `~/.failproofai/` et le répertoire `.failproofai/` du projet, mais s'exécutent en tant que processus séparés et ne communiquent qu'à travers le système de fichiers.
+
+---
+
+## Gestionnaire de hooks
+
+### Intégration avec Claude Code
+
+Lorsque vous exécutez `failproofai policies --install`, des entrées comme celle-ci sont écrites dans `~/.claude/settings.json` :
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code invoque ensuite `failproofai --hook PreToolUse` en tant que sous-processus avant chaque appel d'outil, en transmettant un payload JSON sur stdin.
+
+### Format du payload
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
+  "cwd": "/home/user/myproject",
+  "permission_mode": "default",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Bash",
+  "tool_input": { "command": "sudo apt install nodejs" }
+}
+```
+
+Pour les événements `PostToolUse`, le payload contient également `tool_result` avec la sortie de l'outil.
+
+Le gestionnaire impose une limite de 1 Mo sur stdin. Les payloads dépassant cette limite sont ignorés et toutes les politiques autorisent implicitement.
+
+### Format de la réponse
+
+**Refus (PreToolUse) :**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Refus (PostToolUse) :**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Instruction (tout événement sauf Stop) :**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Instruction sur l'événement Stop :**
+- Code de sortie : `2`
+- Raison écrite sur stderr (pas sur stdout)
+
+**Autorisation :**
+- Code de sortie : `0`
+- stdout vide
+
+**Autorisation avec message (bêta) :**
+
+Depuis la version v0.0.2-beta.3, `allow(message)` permet à une politique d'envoyer un contexte informatif à Claude même lorsque l'opération est autorisée. Le gestionnaire de hooks écrit le JSON suivant sur **stdout** (pas dans un fichier de configuration — il s'agit de la réponse du gestionnaire à Claude Code, tout comme les réponses de refus et d'instruction ci-dessus) :
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Code de sortie : `0` (l'opération est autorisée)
+- Lorsque plusieurs politiques retournent `allow` avec un message, leurs messages sont joints par des sauts de ligne en une seule chaîne `additionalContext`
+- Si aucune politique ne fournit de message, stdout est vide (comme auparavant)
+
+### Pipeline de traitement
+
+`src/hooks/handler.ts` implémente le pipeline complet :
+
+```text
+stdin JSON
+  → analyser le payload (max 1 Mo)
+  → extraire les métadonnées de session (session_id, cwd, tool_name, tool_input, etc.)
+  → readMergedHooksConfig(cwd)    ← fusionne la config projet + locale + globale
+  → enregistrer les politiques intégrées activées avec les paramètres résolus
+  → charger les politiques personnalisées depuis customPoliciesPath (si défini)
+  → enregistrer les politiques personnalisées dans le registre de politiques
+  → évaluer toutes les politiques (intégrées en premier, puis personnalisées)
+      → le premier refus court-circuite
+      → les décisions d'instruction s'accumulent
+      → les messages d'autorisation s'accumulent
+  → écrire la décision JSON sur stdout
+  → persister l'événement dans ~/.failproofai/hook-activity.jsonl
+  → quitter
+```
+
+L'ensemble du processus s'exécute en moins de 100 ms pour les payloads typiques, sans aucun appel LLM.
+
+---
+
+## Chargement de la configuration
+
+`src/hooks/hooks-config.ts` implémente le chargement de configuration à trois portées.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← projet   (priorité la plus haute)
+[2] {cwd}/.failproofai/policies-config.local.json  ← local
+[3] ~/.failproofai/policies-config.json             ← global   (priorité la plus basse)
+```
+
+Logique de fusion :
+- `enabledPolicies` - union dédupliquée sur les trois fichiers
+- `policyParams` - par clé de politique, le premier fichier qui la définit l'emporte entièrement
+- `customPoliciesPath` - le premier fichier qui le définit l'emporte
+- `llm` - le premier fichier qui le définit l'emporte
+
+Le tableau de bord web utilise `readHooksConfig()` (global uniquement) pour la lecture et l'écriture, car il n'est pas invoqué avec un répertoire de travail de projet.
+
+---
+
+## Évaluation des politiques
+
+`src/hooks/policy-evaluator.ts` exécute les politiques dans l'ordre.
+
+Pour chaque politique :
+
+1. Rechercher le schéma `params` de la politique (si elle en possède un).
+2. Lire `policyParams[policy.name]` depuis la configuration fusionnée.
+3. Fusionner les valeurs fournies par l'utilisateur sur les valeurs par défaut du schéma pour produire `ctx.params`.
+4. Appeler `policy.fn(ctx)` avec le contexte résolu.
+5. Si le résultat est `deny`, s'arrêter immédiatement et retourner cette décision.
+6. Si le résultat est `instruct`, accumuler le message et continuer.
+7. Si le résultat est `allow`, passer à la politique suivante.
+
+Après l'exécution de toutes les politiques :
+- Si un `deny` a été retourné, émettre la réponse de refus.
+- Si des retours `instruct` ont été collectés, émettre une seule réponse d'instruction avec tous les messages joints.
+- Sinon, émettre une réponse d'autorisation (stdout vide, code de sortie 0).
+
+---
+
+## Politiques intégrées
+
+`src/hooks/builtin-policies.ts` définit les 26 politiques intégrées sous forme d'objets `BuiltinPolicyDefinition` :
+
+```typescript
+interface BuiltinPolicyDefinition {
+  name: string;
+  description: string;
+  fn: (ctx: PolicyContext) => PolicyResult;
+  match: {
+    events: HookEventType[];
+    tools?: string[];
+  };
+  defaultEnabled: boolean;
+  category: string;
+  beta?: boolean;
+  params?: PolicyParamsSchema;
+}
+```
+
+Les politiques qui acceptent des `params` déclarent un `PolicyParamsSchema` avec les types et les valeurs par défaut de chaque paramètre. L'évaluateur de politiques injecte les valeurs résolues dans `ctx.params` avant d'appeler `fn`. Les fonctions de politique lisent `ctx.params` sans vérification de nullité, car les valeurs par défaut sont toujours appliquées en premier.
+
+La correspondance de motifs à l'intérieur des politiques utilise des tokens de commande analysés (argv), et non une correspondance de chaînes brutes. Cela empêche le contournement via l'injection d'opérateurs shell (par exemple, un motif pour `sudo systemctl status *` ne peut pas être contourné en ajoutant `; rm -rf /` à la commande).
+
+---
+
+## Politiques personnalisées
+
+`src/hooks/custom-hooks-registry.ts` implémente un registre basé sur `globalThis` :
+
+```typescript
+const REGISTRY_KEY = "__failproofai_custom_hooks__";
+
+export const customPolicies = {
+  add(hook: CustomHook): void { ... }
+};
+
+export function getCustomHooks(): CustomHook[] { ... }
+export function clearCustomHooks(): void { ... }  // used in tests
+```
+
+`src/hooks/custom-hooks-loader.ts` charge le fichier de politique de l'utilisateur :
+
+1. Lire `customPoliciesPath` depuis la configuration ; ignorer si absent.
+2. Résoudre le chemin absolu ; vérifier que le fichier existe.
+3. Réécrire tous les imports `from "failproofai"` vers le chemin dist réel afin que `customPolicies` résolve vers le même registre `globalThis`.
+4. Réécrire récursivement les imports locaux transitifs pour assurer la compatibilité ESM.
+5. Écrire des fichiers `.mjs` temporaires et `import()` le fichier d'entrée.
+6. Appeler `getCustomHooks()` pour récupérer les hooks enregistrés.
+7. Nettoyer tous les fichiers temporaires dans un bloc `finally`.
+
+En cas d'erreur (fichier introuvable, erreur de syntaxe, échec d'import), l'erreur est consignée dans `~/.failproofai/hook.log` et le chargeur retourne un tableau vide. Les politiques intégrées ne sont pas affectées.
+
+Les politiques personnalisées sont évaluées après toutes les politiques intégrées. Un `deny` d'une politique personnalisée court-circuite quand même les politiques personnalisées suivantes (mais toutes les politiques intégrées ont déjà été exécutées à ce stade).
+
+---
+
+## Journalisation de l'activité
+
+Après chaque événement de hook, le gestionnaire ajoute une ligne JSONL dans `~/.failproofai/hook-activity.jsonl` :
+
+```json
+{
+  "timestamp": "2026-04-06T12:34:56.789Z",
+  "sessionId": "abc123",
+  "eventType": "PreToolUse",
+  "toolName": "Bash",
+  "policyName": "block-sudo",
+  "decision": "deny",
+  "reason": "sudo command blocked by failproofai",
+  "durationMs": 12
+}
+```
+
+Une ligne par politique ayant pris une décision autre que allow. Les décisions d'autorisation ne sont pas journalisées (pour maintenir la taille du fichier réduite).
+
+---
+
+## Architecture du tableau de bord
+
+Le tableau de bord est une application **Next.js 16** utilisant l'App Router avec des React Server Components et des Server Actions.
+
+```text
+app/
+  layout.tsx                  ← Mise en page racine (thème, télémétrie, nav)
+  projects/page.tsx           ← Composant serveur : liste tous les projets Claude
+  project/[name]/page.tsx     ← Composant serveur : liste les sessions d'un projet
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Composant serveur : affiche le visualiseur de session
+  policies/page.tsx           ← Composant client : gestion des politiques + journal d'activité
+  actions/
+    get-hooks-config.ts       ← Lire la config + la liste des politiques
+    update-hooks-config.ts    ← Activer/désactiver une politique
+    update-policy-params.ts   ← Mettre à jour les paramètres d'une politique
+    get-hook-activity.ts      ← Paginer/rechercher dans le journal d'activité
+    install-hooks-web.ts      ← Installer/supprimer les hooks depuis le navigateur
+  api/
+    download/[project]/[session]/route.ts   ← Exporter une session en ZIP/JSONL
+```
+
+**Flux de données :**
+
+- Les composants de page appellent `lib/projects.ts` et `lib/log-entries.ts` pour lire les données de projet/session directement depuis le système de fichiers (pas de couche API pour les lectures).
+- La page Politiques utilise des Server Actions pour toutes les mutations (activation/désactivation, mise à jour des paramètres, installation/suppression).
+- Le visualiseur de session analyse le format de transcript JSONL de Claude et affiche une chronologie des messages et des appels d'outils.
+
+**Décisions de conception clés :**
+
+- Pas de base de données - tout l'état persistant est dans des fichiers simples (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions pour les mutations - aucune API REST nécessaire pour les opérations CRUD.
+- React Server Components pour les pages de lecture - chargement initial plus rapide, pas de bundle client pour la récupération des données.
+- Composants client uniquement là où l'interactivité est nécessaire (bascules de politique, recherche d'activité, visualiseur de journal).
+
+---
+
+## Organisation des fichiers
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # Routeur CLI (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Pipeline d'événements de hook
+│   ├── builtin-policies.ts       # 26 définitions de politiques
+│   ├── policy-evaluator.ts       # Moteur d'exécution des politiques
+│   ├── policy-registry.ts        # Enregistrement et recherche de politiques
+│   ├── policy-types.ts           # Interfaces TypeScript
+│   ├── hooks-config.ts           # Chargement de configuration multi-portée
+│   ├── custom-hooks-registry.ts  # Registre de hooks basé sur globalThis
+│   ├── custom-hooks-loader.ts    # Chargeur ESM pour les hooks JS utilisateur
+│   ├── manager.ts                # Opérations install / remove / list
+│   ├── install-prompt.ts         # Invite de sélection interactive des politiques
+│   ├── hook-logger.ts            # Journalisation vers hook.log
+│   ├── hook-activity-store.ts    # Persistance de l'activité dans hook-activity.jsonl
+│   └── llm-client.ts             # Client API LLM (pour les politiques pilotées par IA)
+├── app/                          # Tableau de bord Next.js (pages + server actions)
+├── lib/                          # Utilitaires partagés
+│   ├── projects.ts               # Enumération des projets Claude depuis le système de fichiers
+│   ├── log-entries.ts            # Analyse du format JSONL des transcripts Claude
+│   ├── paths.ts                  # Résolution des chemins système
+│   └── ...
+├── components/                   # Composants React UI partagés
+├── contexts/                     # Fournisseurs de contexte React (thème, actualisation automatique, télémétrie)
+├── examples/                     # Exemples de fichiers de hooks personnalisés
+└── __tests__/                    # Tests unitaires et E2E
+```