failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,31 @@
+---
+title: Listar políticas
+description: "Ver qué políticas están habilitadas, sus parámetros y políticas personalizadas"
+---
+
+```bash
+failproofai policies
+```
+
+Muestra todas las políticas con su estado, parámetros configurados y políticas personalizadas.
+
+## Ejemplo de salida
+
+```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
+```
+
+Las claves desconocidas en `policyParams` se marcan aquí para que puedas detectar errores tipográficos con anticipación.

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

@@ -0,0 +1,44 @@
+---
+title: Desinstalar políticas
+description: "Eliminar entradas de hooks de la configuración de Claude Code"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+Elimina las entradas de hooks de failproofai del archivo `settings.json` de Claude Code.
+
+Alias: `failproofai p -u`
+
+## Opciones
+
+| Indicador | Descripción |
+|-----------|-------------|
+| `--scope user` | Eliminar de la configuración global (predeterminado) |
+| `--scope project` | Eliminar de la configuración del proyecto |
+| `--scope local` | Eliminar de la configuración local |
+| `--scope all` | Eliminar de todos los ámbitos a la vez |
+| `--custom` / `-c` | Limpiar el `customPoliciesPath` de la configuración |
+| `--beta` | Eliminar solo las políticas beta de la configuración |
+
+## Comportamiento
+
+- **Sin nombres de política** - elimina todas las entradas de hooks de failproofai del archivo de configuración
+- **Nombres específicos** - deshabilita esas políticas pero mantiene los hooks instalados
+
+## Ejemplos
+
+```bash
+# Eliminar todos los hooks de forma global
+failproofai policies --uninstall
+
+# Deshabilitar una política específica (mantiene los hooks instalados)
+failproofai policies --uninstall block-sudo
+
+# Eliminar hooks de todos los ámbitos
+failproofai policies --uninstall --scope all
+
+# Limpiar la ruta de políticas personalizadas
+failproofai policies --uninstall --custom
+```

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

@@ -0,0 +1,12 @@
+---
+title: Verificar versión
+description: "Mostrar la versión instalada de failproofai"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+Muestra el número de versión instalada.

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

@@ -0,0 +1,222 @@
+---
+title: Configuración
+description: "Formato del archivo de configuración, sistema de tres ámbitos y reglas de fusión"
+icon: gear
+---
+
+failproofai utiliza archivos de configuración JSON para controlar qué políticas están activas, cómo se comportan y desde dónde se cargan las políticas personalizadas. La configuración está diseñada para compartirse fácilmente con tu equipo: confírmala en tu repositorio y todos los desarrolladores tendrán la misma red de seguridad para el agente.
+
+---
+
+## Ámbitos de configuración
+
+Existen tres ámbitos de configuración, evaluados en orden de prioridad:
+
+| Ámbito | Ruta del archivo | Propósito |
+|--------|-----------------|-----------|
+| **project** | `.failproofai/policies-config.json` | Configuración por repositorio, confirmada en control de versiones |
+| **local** | `.failproofai/policies-config.local.json` | Anulaciones personales por repositorio, ignoradas por git |
+| **global** | `~/.failproofai/policies-config.json` | Valores predeterminados a nivel de usuario para todos los proyectos |
+
+Cuando failproofai recibe un evento de hook, carga y fusiona los tres archivos que existen en el directorio de trabajo actual.
+
+### Reglas de fusión
+
+**`enabledPolicies`** — la unión de los tres ámbitos. Una política habilitada en cualquier nivel estará activa.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← unión sin duplicados
+```
+
+**`policyParams`** — el primer ámbito que defina parámetros para una política determinada gana por completo. No se realiza una fusión profunda de los valores dentro de los parámetros de una política.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← gana project, se ignora global
+```
+
+```text
+project:  (sin entrada block-sudo)
+local:    (sin entrada block-sudo)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← cae al nivel global
+```
+
+**`customPoliciesPath`** — gana el primer ámbito que lo defina.
+
+**`llm`** — gana el primer ámbito que lo defina.
+
+---
+
+## Formato del archivo de configuración
+
+```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"
+}
+```
+
+---
+
+## Referencia de campos
+
+### `enabledPolicies`
+
+Tipo: `string[]`
+
+Lista de nombres de políticas a habilitar. Los nombres deben coincidir exactamente con los identificadores de política que muestra `failproofai policies`. Consulta [Políticas integradas](/es/built-in-policies) para ver la lista completa.
+
+Las políticas que no estén en `enabledPolicies` estarán inactivas, incluso si tienen entradas en `policyParams`.
+
+### `policyParams`
+
+Tipo: `Record<string, Record<string, unknown>>`
+
+Anulaciones de parámetros por política. La clave externa es el nombre de la política; las claves internas son específicas de cada política. Cada política documenta sus parámetros disponibles en [Políticas integradas](/es/built-in-policies).
+
+Si una política tiene parámetros pero no los especificas, se usan los valores predeterminados integrados de la política. Los usuarios que no configuren `policyParams` en absoluto obtendrán un comportamiento idéntico al de las versiones anteriores.
+
+Las claves desconocidas dentro del bloque de parámetros de una política se ignoran silenciosamente en el momento de disparar el hook, pero se marcan como advertencias cuando ejecutas `failproofai policies`.
+
+#### `hint` (transversal)
+
+Tipo: `string` (opcional)
+
+Un mensaje que se añade al motivo cuando una política devuelve `deny` o `instruct`. Úsalo para dar a Claude orientación accionable sin modificar la política en sí.
+
+Funciona con cualquier tipo de política: integrada, personalizada (`custom/`), convención de proyecto (`.failproofai-project/`) o convención de usuario (`.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."
+    }
+  }
+}
+```
+
+Cuando block-force-push deniega, Claude ve: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+Los valores que no sean cadenas de texto y las cadenas vacías se ignoran silenciosamente. Si `hint` no está definido, el comportamiento no cambia (compatible con versiones anteriores).
+
+### `customPoliciesPath`
+
+Tipo: `string` (ruta absoluta)
+
+Ruta a un archivo JavaScript que contiene políticas de hook personalizadas. Este valor lo establece automáticamente `failproofai policies --install --custom <path>` (la ruta se resuelve a absoluta antes de almacenarse).
+
+El archivo se carga desde cero en cada evento de hook; no hay caché. Consulta [Políticas personalizadas](/es/custom-policies) para ver los detalles de creación.
+
+### Políticas basadas en convención (v0.0.2-beta.7+)
+
+Además del `customPoliciesPath` explícito, failproofai descubre y carga automáticamente archivos de políticas desde directorios `.failproofai/policies/`:
+
+| Nivel | Directorio | Ámbito |
+|-------|-----------|--------|
+| Proyecto | `.failproofai/policies/` | Compartido con el equipo a través del control de versiones |
+| Usuario | `~/.failproofai/policies/` | Personal, se aplica a todos los proyectos |
+
+**Coincidencia de archivos:** Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}` (por ejemplo, `security-policies.mjs`, `workflow-policies.js`). Los demás archivos del directorio se ignoran.
+
+**Sin configuración necesaria:** Las políticas de convención no requieren entradas en `policies-config.json`. Simplemente coloca los archivos en el directorio y se detectarán en el siguiente evento de hook.
+
+**Carga por unión:** Se analizan tanto el directorio de convención del proyecto como el del usuario. Todos los archivos coincidentes de ambos niveles se cargan (a diferencia de `customPoliciesPath`, que usa el criterio de primer ámbito que gana).
+
+Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y ejemplos.
+
+### `llm`
+
+Tipo: `object` (opcional)
+
+Configuración del cliente LLM para políticas que realizan llamadas a IA. No es necesario para la mayoría de las configuraciones.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Gestión de la configuración desde la CLI
+
+Los comandos `policies --install` y `policies --uninstall` escriben en el settings.json de Claude Code (los puntos de entrada del hook), mientras que policies-config.json es el archivo que gestionas directamente. Los dos son independientes:
+
+- **`settings.json`** — le indica a Claude Code que llame a `failproofai --hook <event>` en cada uso de herramienta
+- **`policies-config.json`** — le indica a failproofai qué políticas evaluar y con qué parámetros
+
+Puedes editar `policies-config.json` directamente en cualquier momento; los cambios surten efecto de inmediato en el siguiente evento de hook sin necesidad de reiniciar.
+
+---
+
+## Ejemplo: configuración a nivel de proyecto con valores predeterminados del equipo
+
+Confirma `.failproofai/policies-config.json` en tu repositorio:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Cada desarrollador puede entonces crear `.failproofai/policies-config.local.json` (ignorado por git) para sus anulaciones personales sin afectar a sus compañeros de equipo.

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

@@ -0,0 +1,357 @@
+---
+title: Políticas Personalizadas
+description: "Escribe tus propias políticas en JavaScript: aplica convenciones, previene derivas, detecta fallos e intégrate con sistemas externos"
+icon: code
+---
+
+Las políticas personalizadas te permiten escribir reglas para cualquier comportamiento del agente: aplicar convenciones del proyecto, prevenir derivas, controlar operaciones destructivas, detectar agentes bloqueados o integrarte con Slack, flujos de aprobación y más. Utilizan el mismo sistema de eventos de hook y las mismas decisiones `allow`, `deny`, `instruct` que las políticas integradas.
+
+---
+
+## Ejemplo rápido
+
+```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();
+  },
+});
+```
+
+Instálala:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Dos formas de cargar políticas personalizadas
+
+### Opción 1: Basada en convención (recomendada, v0.0.2-beta.7+)
+
+Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargarán automáticamente, sin necesidad de flags ni cambios de configuración. Funciona como los git hooks: coloca el archivo y listo.
+
+```
+# Nivel de proyecto — incluido en git, compartido con el equipo
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Nivel de usuario — personal, se aplica a todos los proyectos
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Cómo funciona:**
+- Se analizan tanto el directorio del proyecto como el del usuario (unión — no el primero que coincida por alcance)
+- Los archivos se cargan alfabéticamente dentro de cada directorio. Usa prefijos `01-`, `02-` para controlar el orden
+- Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}`; el resto se ignoran
+- Cada archivo se carga de forma independiente (fail-open por archivo)
+- Funciona junto con `--custom` explícito y las políticas integradas
+
+<Tip>
+Las políticas por convención son la forma más sencilla de compartir políticas en un equipo. Incluye `.failproofai/policies/` en git y todos los miembros del equipo las recibirán automáticamente.
+</Tip>
+
+### Opción 2: Ruta de archivo explícita
+
+```bash
+# Instalar con un archivo de políticas personalizadas
+failproofai policies --install --custom ./my-policies.js
+
+# Reemplazar la ruta del archivo de políticas
+failproofai policies --install --custom ./new-policies.js
+
+# Eliminar la ruta de políticas personalizadas de la configuración
+failproofai policies --uninstall --custom
+```
+
+La ruta absoluta resuelta se almacena en `policies-config.json` como `customPoliciesPath`. El archivo se carga de nuevo en cada evento de hook; no hay caché entre eventos.
+
+### Usar ambas juntas
+
+Las políticas por convención y el archivo `--custom` explícito pueden coexistir. Orden de carga:
+
+1. Archivo explícito `customPoliciesPath` (si está configurado)
+2. Archivos de convención del proyecto (`{cwd}/.failproofai/policies/`, alfabético)
+3. Archivos de convención del usuario (`~/.failproofai/policies/`, alfabético)
+
+---
+
+## API
+
+### Importación
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Registra una política. Llámalo las veces que necesites para definir múltiples políticas en el mismo archivo.
+
+```ts
+customPolicies.add({
+  name: string;                         // requerido - identificador único
+  description?: string;                 // se muestra en la salida de `failproofai policies`
+  match?: { events?: HookEventType[] }; // filtra por tipo de evento; omítelo para coincidir con todos
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Funciones auxiliares de decisión
+
+| Función | Efecto | Cuándo usarla |
+|----------|--------|----------|
+| `allow()` | Permite la operación silenciosamente | La acción es segura y no se necesita mensaje |
+| `deny(message)` | Bloquea la operación | El agente no debería realizar esta acción |
+| `instruct(message)` | Añade contexto sin bloquear | Proporciona contexto adicional al agente para mantenerlo en curso |
+
+`deny(message)` — el mensaje aparece para Claude con el prefijo `"Blocked by failproofai:"`. Un solo `deny` cortocircuita toda evaluación posterior.
+
+`instruct(message)` — el mensaje se añade al contexto de Claude para la llamada de herramienta actual. Todos los mensajes `instruct` se acumulan y se entregan juntos.
+
+<Tip>
+Puedes añadir orientación adicional a cualquier mensaje `deny` o `instruct` incluyendo un campo `hint` en `policyParams`, sin necesidad de cambiar el código. Esto funciona también para políticas personalizadas (`custom/`), de convención de proyecto (`.failproofai-project/`) y de convención de usuario (`.failproofai-user/`). Consulta [Configuración → hint](/es/configuration#hint-cross-cutting) para más detalles.
+</Tip>
+
+### Mensajes informativos en allow (beta)
+
+<Note>
+`allow(message)` es una funcionalidad en beta disponible desde v0.0.2-beta.3. La API podría cambiar en versiones futuras. Las versiones anteriores solo admiten `allow()` sin argumentos.
+</Note>
+
+`allow(message)` permite la operación **y** envía un mensaje informativo a Claude. El mensaje se entrega como `additionalContext` en la respuesta stdout del manejador de hooks — el mismo mecanismo que usa `instruct`, pero con una semántica diferente: es una actualización de estado, no una advertencia.
+
+| Función | Efecto | Cuándo usarla |
+|----------|--------|----------|
+| `allow(message)` | Permite y envía contexto a Claude | Confirmar que una verificación pasó, o explicar por qué se omitió |
+
+Casos de uso:
+- **Confirmaciones de estado:** `allow("All CI checks passed.")` — le indica a Claude que todo está en orden
+- **Explicaciones de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — le dice a Claude por qué se omitió una verificación para que tenga contexto completo
+- **Los mensajes se acumulan:** si varias políticas devuelven `allow(message)`, todos los mensajes se unen con saltos de línea y se entregan juntos
+
+```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.");
+  },
+});
+```
+
+### Campos de `PolicyContext`
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | La herramienta que se está invocando (p. ej. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Los parámetros de entrada de la herramienta |
+| `payload` | `Record<string, unknown>` | Payload completo del evento raw de Claude Code |
+| `session` | `SessionMetadata \| undefined` | Contexto de sesión (ver más abajo) |
+
+### Campos de `SessionMetadata`
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| `sessionId` | `string` | Identificador de sesión de Claude Code |
+| `cwd` | `string` | Directorio de trabajo de la sesión de Claude Code |
+| `transcriptPath` | `string` | Ruta al archivo de transcripción JSONL de la sesión |
+
+### Tipos de eventos
+
+| Evento | Cuándo se dispara | Contenido de `toolInput` |
+|-------|--------------|----------------------|
+| `PreToolUse` | Antes de que Claude ejecute una herramienta | La entrada de la herramienta (p. ej. `{ command: "..." }` para Bash) |
+| `PostToolUse` | Después de que una herramienta completa | La entrada de la herramienta + `tool_result` (la salida) |
+| `Notification` | Cuando Claude envía una notificación | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — los hooks siempre deben devolver `allow()`, no pueden bloquear notificaciones |
+| `Stop` | Cuando la sesión de Claude finaliza | Vacío |
+
+---
+
+## Orden de evaluación
+
+Las políticas se evalúan en este orden:
+
+1. Políticas integradas (en orden de definición)
+2. Políticas personalizadas explícitas de `customPoliciesPath` (en orden de `.add()`)
+3. Políticas de convención del proyecto `.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada archivo)
+4. Políticas de convención del usuario `~/.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada archivo)
+
+<Note>
+El primer `deny` cortocircuita todas las políticas siguientes. Todos los mensajes `instruct` se acumulan y se entregan juntos.
+</Note>
+
+---
+
+## Importaciones transitivas
+
+Los archivos de políticas personalizadas pueden importar módulos locales usando rutas relativas:
+
+```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");
+  },
+});
+```
+
+Se resuelven todas las importaciones relativas accesibles desde el archivo de entrada. Esto se implementa reescribiendo las importaciones `from "failproofai"` a la ruta real de dist y creando archivos `.mjs` temporales para garantizar la compatibilidad con ESM.
+
+---
+
+## Filtrado por tipo de evento
+
+Usa `match.events` para limitar cuándo se dispara una política:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Solo se dispara cuando la sesión finaliza
+    // ctx.session.transcriptPath contiene el log completo de la sesión
+    return allow();
+  },
+});
+```
+
+Omite `match` por completo para que se dispare en todos los tipos de eventos.
+
+---
+
+## Manejo de errores y modos de fallo
+
+Las políticas personalizadas son **fail-open**: los errores nunca bloquean las políticas integradas ni causan un crash en el manejador de hooks.
+
+| Fallo | Comportamiento |
+|---------|----------|
+| `customPoliciesPath` no configurado | No se ejecutan políticas personalizadas explícitas; las políticas por convención y las integradas continúan con normalidad |
+| Archivo no encontrado | Se registra una advertencia en `~/.failproofai/hook.log`; las políticas integradas continúan |
+| Error de sintaxis/importación (explícito) | Error registrado en `~/.failproofai/hook.log`; se omiten las políticas personalizadas explícitas |
+| Error de sintaxis/importación (convención) | Error registrado; ese archivo se omite, los demás archivos de convención siguen cargándose |
+| `fn` lanza un error en tiempo de ejecución | Error registrado; ese hook se trata como `allow`; los demás hooks continúan |
+| `fn` tarda más de 10 segundos | Timeout registrado; se trata como `allow` |
+| Directorio de convención inexistente | No se ejecutan políticas de convención; sin error |
+
+<Tip>
+Para depurar errores en políticas personalizadas, observa el archivo de log:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Ejemplo completo: múltiples políticas
+
+```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 };
+```
+
+---
+
+## Ejemplos
+
+El directorio `examples/` contiene archivos de políticas listos para ejecutar:
+
+| Archivo | Contenido |
+|------|----------|
+| `examples/policies-basic.js` | Cinco políticas de inicio que cubren los modos de fallo más comunes de los agentes |
+| `examples/policies-advanced/index.js` | Patrones avanzados: importaciones transitivas, llamadas asíncronas, limpieza de salidas y hooks de fin de sesión |
+| `examples/convention-policies/security-policies.mjs` | Políticas de seguridad por convención (bloquea escrituras en .env, previene reescritura del historial de git) |
+| `examples/convention-policies/workflow-policies.mjs` | Políticas de flujo de trabajo por convención (recordatorios de tests, auditoría de escrituras en archivos) |
+
+### Usar los ejemplos con archivo explícito
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Usar los ejemplos basados en convención
+
+```bash
+# Copiar al nivel del proyecto
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# O copiar al nivel del usuario
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+No se necesita ningún comando de instalación — los archivos se detectan automáticamente en el siguiente evento de hook.