failproofai 0.0.5 → 0.0.6-beta.1

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

@@ -4,7 +4,7 @@ description: "Formato del archivo de configuración, sistema de tres ámbitos y
 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.
+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 obtendrán la misma red de seguridad para el agente.
 
 ---
 
@@ -14,15 +14,15 @@ 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 |
+| **project** | `.failproofai/policies-config.json` | Configuración por repositorio, confirmada en el 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.
+Cuando failproofai recibe un evento de hook, carga y fusiona los tres archivos que existen para 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.
+**`enabledPolicies`** - la unión de los tres ámbitos. Una política habilitada en cualquier nivel está activa.
 
 ```text
 project:  ["block-sudo"]
@@ -32,13 +32,13 @@ 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.
+**`policyParams`** - el primer ámbito que define los parámetros para una política determinada gana completamente. No hay fusión profunda de 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
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project gana, global ignorado
 ```
 
 ```text
@@ -46,12 +46,12 @@ 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
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← recae en global
 ```
 
-**`customPoliciesPath`** — gana el primer ámbito que lo defina.
+**`customPoliciesPath`** - el primer ámbito que lo define gana.
 
-**`llm`** — gana el primer ámbito que lo defina.
+**`llm`** - el primer ámbito que lo define gana.
 
 ---
 
@@ -112,17 +112,17 @@ 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.
+Si una política tiene parámetros pero no los especificas, se utilizan los valores predeterminados integrados de la política. Los usuarios que no configuren `policyParams` en absoluto obtendrán un comportamiento idéntico al de 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`.
+Las claves desconocidas dentro del bloque de parámetros de una política se ignoran silenciosamente al momento de ejecutar 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í.
+Un mensaje que se añade al motivo cuando una política devuelve `deny` o `instruct`. Úsalo para dar a Claude orientación práctica 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/`).
+Funciona con cualquier tipo de política: integradas, personalizadas (`custom/`), convenciones de proyecto (`.failproofai-project/`) o convenciones de usuario (`.failproofai-user/`).
 
 ```json
 {
@@ -141,7 +141,7 @@ Funciona con cualquier tipo de política: integrada, personalizada (`custom/`),
 }
 ```
 
-Cuando block-force-push deniega, Claude ve: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+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).
 
@@ -149,24 +149,24 @@ Los valores que no sean cadenas de texto y las cadenas vacías se ignoran silenc
 
 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).
+Ruta a un archivo JavaScript que contiene políticas de hook personalizadas. Se establece automáticamente mediante `failproofai policies --install --custom <path>` (la ruta se resuelve como absoluta antes de guardarse).
 
-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.
+El archivo se carga de nuevo en cada evento de hook, sin ningún tipo de caché. Consulta [Políticas personalizadas](/es/custom-policies) para más detalles sobre cómo crearlas.
 
-### Políticas basadas en convención
+### Políticas basadas en convenciones
 
 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 |
+| Proyecto | `.failproofai/policies/` | Compartido con el equipo mediante 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.
+**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 próximo 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).
+**Carga por unión:** Se analizan tanto los directorios de convención del proyecto como los del usuario. Se cargan todos los archivos coincidentes de ambos niveles (a diferencia de `customPoliciesPath`, que utiliza el primero que gana por ámbito).
 
 Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y ejemplos.
 
@@ -174,7 +174,7 @@ Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y e
 
 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.
+Configuración del cliente LLM para políticas que realizan llamadas a IA. No es necesaria para la mayoría de las configuraciones.
 
 ```json
 {
@@ -189,12 +189,12 @@ Configuración del cliente LLM para políticas que realizan llamadas a IA. No es
 
 ## 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:
+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. Ambos 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
+- **`settings.json`** - indica a Claude Code que llame a `failproofai --hook <event>` en cada uso de herramienta
+- **`policies-config.json`** - 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.
+Puedes editar `policies-config.json` directamente en cualquier momento; los cambios surten efecto de inmediato en el próximo evento de hook, sin necesidad de reiniciar.
 
 ---
 

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

@@ -1,10 +1,10 @@
 ---
 title: Políticas Personalizadas
-description: "Escribe tus propias políticas en JavaScript: aplica convenciones, previene derivas, detecta fallos e intégrate con sistemas externos"
+description: "Escribe tus propias políticas en JavaScript: aplica convenciones, previene la deriva, detecta fallos e integra 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.
+Las políticas personalizadas te permiten escribir reglas para cualquier comportamiento del agente: aplicar convenciones del proyecto, prevenir la deriva, bloquear operaciones destructivas, detectar agentes atascados o integrarte con Slack, flujos de aprobación y más. Utilizan el mismo sistema de eventos de hook y las decisiones `allow`, `deny`, `instruct` que las políticas integradas.
 
 ---
 
@@ -29,7 +29,7 @@ customPolicies.add({
 });
 ```
 
-Instálala:
+Instálalo:
 
 ```bash
 failproofai policies --install --custom ./my-policies.js
@@ -39,9 +39,9 @@ failproofai policies --install --custom ./my-policies.js
 
 ## Dos formas de cargar políticas personalizadas
 
-### Opción 1: Basada en convención (recomendada)
+### Opción 1: Basada en convenciones (recomendada)
 
-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.
+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: deposita un archivo y ya está.
 
 ```
 # Nivel de proyecto — incluido en git, compartido con el equipo
@@ -53,14 +53,14 @@ Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargar
 ```
 
 **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
+- Se analizan tanto el directorio del proyecto como el del usuario (unión — no gana el primero en ámbito)
+- Los archivos se cargan en orden alfabético dentro de cada directorio. Usa el prefijo `01-`, `02-` para controlar el orden
+- Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}`; los demás 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.
+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 obtendrán automáticamente.
 </Tip>
 
 ### Opción 2: Ruta de archivo explícita
@@ -76,15 +76,15 @@ failproofai policies --install --custom ./new-policies.js
 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.
+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
+### Usando ambas formas 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)
+2. Archivos de convención del proyecto (`{cwd}/.failproofai/policies/`, en orden alfabético)
+3. Archivos de convención del usuario (`~/.failproofai/policies/`, en orden alfabético)
 
 ---
 
@@ -98,13 +98,13 @@ 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.
+Registra una política. Llámalo tantas veces como sea necesario para 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
+  match?: { events?: HookEventType[] }; // filtra por tipo de evento; omite para coincidir con todos
   fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
 });
 ```
@@ -113,22 +113,21 @@ customPolicies.add({
 
 | Función | Efecto | Cuándo usarla |
 |----------|--------|----------|
-| `allow()` | Permite la operación silenciosamente | La acción es segura y no se necesita mensaje |
+| `allow()` | Permite la operación en silencio | La acción es segura, 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.
+`deny(message)` — el mensaje aparece ante Claude con el prefijo `"Blocked by failproofai:"`. Un único `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.
+Puedes añadir orientación adicional a cualquier mensaje `deny` o `instruct` agregando un campo `hint` en `policyParams`, sin necesidad de cambiar el código. Esto también funciona 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
 
-
-`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.
+`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 semánticamente distinto: es una actualización de estado, no una advertencia.
 
 | Función | Efecto | Cuándo usarla |
 |----------|--------|----------|
@@ -136,8 +135,8 @@ Puedes añadir orientación adicional a cualquier mensaje `deny` o `instruct` in
 
 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
+- **Explicaciones de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — le indica a Claude por qué se omitió una verificación para que tenga contexto completo
+- **Acumulación de múltiples mensajes:** si varias políticas devuelven `allow(message)`, todos los mensajes se unen con saltos de línea y se entregan juntos
 
 ```js
 customPolicies.add({
@@ -163,8 +162,8 @@ customPolicies.add({
 | `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) |
+| `payload` | `Record<string, unknown>` | Payload completo del evento sin procesar, proveniente de Claude Code |
+| `session` | `SessionMetadata \| undefined` | Contexto de la sesión (ver más abajo) |
 
 ### Campos de `SessionMetadata`
 
@@ -179,7 +178,7 @@ customPolicies.add({
 | 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) |
+| `PostToolUse` | Después de que una herramienta completa su ejecución | 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 |
 
@@ -191,8 +190,8 @@ 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)
+3. Políticas de convención del proyecto en `.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada uno)
+4. Políticas de convención del usuario en `~/.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada uno)
 
 <Note>
 El primer `deny` cortocircuita todas las políticas siguientes. Todos los mensajes `instruct` se acumulan y se entregan juntos.
@@ -219,7 +218,7 @@ customPolicies.add({
 });
 ```
 
-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.
+Se resuelven todas las importaciones relativas alcanzables 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.
 
 ---
 
@@ -232,33 +231,33 @@ 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
+    // Solo se dispara cuando la sesión termina
+    // ctx.session.transcriptPath contiene el registro completo de la sesión
     return allow();
   },
 });
 ```
 
-Omite `match` por completo para que se dispare en todos los tipos de eventos.
+Omite `match` por completo para disparar en cada tipo de evento.
 
 ---
 
 ## 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.
+Las políticas personalizadas son **fail-open**: los errores nunca bloquean las políticas integradas ni hacen fallar 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 |
+| `customPoliciesPath` no configurado | No se ejecutan políticas personalizadas explícitas; las políticas de convención y las integradas continúan con normalidad |
+| Archivo no encontrado | Se registra una advertencia en `~/.failproofai/hook.log`; las 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 |
+| Error de sintaxis/importación (convención) | Error registrado; ese archivo se omite, los demás archivos de convención se cargan igualmente |
 | `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 |
+| `fn` tarda más de 10 segundos | Se registra el timeout; se trata como `allow` |
+| Directorio de convención faltante | No se ejecutan políticas de convención; sin error |
 
 <Tip>
-Para depurar errores en políticas personalizadas, observa el archivo de log:
+Para depurar errores en políticas personalizadas, monitorea el archivo de log:
 
 ```bash
 tail -f ~/.failproofai/hook.log
@@ -273,7 +272,7 @@ tail -f ~/.failproofai/hook.log
 // my-policies.js
 import { customPolicies, allow, deny, instruct } from "failproofai";
 
-// Prevent agent from writing to secrets/ directory
+// Evitar que el agente escriba en el directorio secrets/
 customPolicies.add({
   name: "block-secrets-dir",
   description: "Prevent agent from writing to secrets/ directory",
@@ -286,7 +285,7 @@ customPolicies.add({
   },
 });
 
-// Keep the agent on track: verify tests before committing
+// Mantener al agente en curso: verificar tests antes de hacer commit
 customPolicies.add({
   name: "remind-test-before-commit",
   description: "Keep the agent on track: verify tests pass before committing",
@@ -301,7 +300,7 @@ customPolicies.add({
   },
 });
 
-// Prevent unplanned dependency changes during freeze
+// Prevenir cambios de dependencias no planificados durante el período de congelamiento
 customPolicies.add({
   name: "dependency-freeze",
   description: "Prevent unplanned dependency changes during freeze period",
@@ -324,22 +323,22 @@ export { customPolicies };
 
 ## Ejemplos
 
-El directorio `examples/` contiene archivos de políticas listos para ejecutar:
+El directorio `examples/` contiene archivos de políticas listos para usar:
 
 | 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) |
+| `examples/policies-basic.js` | Cinco políticas iniciales que cubren los modos de fallo más comunes del agente |
+| `examples/policies-advanced/index.js` | Patrones avanzados: importaciones transitivas, llamadas asíncronas, limpieza de salida y hooks al final de sesión |
+| `examples/convention-policies/security-policies.mjs` | Políticas de seguridad basadas en convenciones (bloquear escrituras en .env, prevenir la reescritura del historial de git) |
+| `examples/convention-policies/workflow-policies.mjs` | Políticas de flujo de trabajo basadas en convenciones (recordatorios de tests, auditoría de escrituras en archivos) |
 
-### Usar los ejemplos con archivo explícito
+### Uso de los ejemplos con archivo explícito
 
 ```bash
 failproofai policies --install --custom ./examples/policies-basic.js
 ```
 
-### Usar los ejemplos basados en convención
+### Uso de los ejemplos basados en convenciones
 
 ```bash
 # Copiar al nivel del proyecto
@@ -351,4 +350,4 @@ 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.
+No se necesita ningún comando de instalación — los archivos se detectan automáticamente en el próximo evento de hook.

package/.next/standalone/docs/examples.mdx

@@ -242,6 +242,60 @@ Every team member who has failproofai installed will automatically pick up these
 
 ---
 
+## Build an org-wide quality standard with convention policies
+
+The most impactful setup: commit `.failproofai/policies/` to your repo with policies tailored to your project. Every team member gets them automatically — no install commands, no config changes.
+
+<Steps>
+  <Step title="Create the directory and add policies">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    // Enforce your team's preferred package manager
+    // (or enable the built-in prefer-package-manager policy instead)
+    customPolicies.add({
+      name: "enforce-bun",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        const cmd = String(ctx.toolInput?.command ?? "");
+        if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
+        return allow();
+      },
+    });
+
+    // Remind the agent to run tests before committing
+    customPolicies.add({
+      name: "test-before-commit",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
+          return instruct("Run tests before committing.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Commit to git">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+  </Step>
+  <Step title="Keep improving">
+    As your team hits new failure modes, add policies and push. Everyone gets the update on their next `git pull`. These policies become a living quality standard that grows with your team.
+  </Step>
+</Steps>
+
+---
+
 ## More examples
 
 The [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) directory in the repo contains: