failproofai 0.0.5 → 0.0.6-beta.1

package/.next/standalone/docs/pt-br/configuration.mdx

@@ -4,7 +4,7 @@ description: "Formato do arquivo de configuração, sistema de três escopos e r
 icon: gear
 ---
 
-failproofai usa arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde as políticas personalizadas são carregadas. A configuração foi pensada para ser fácil de compartilhar com o time — faça commit dela no seu repositório e todos os desenvolvedores terão a mesma rede de segurança para agentes.
+failproofai utiliza arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde políticas customizadas são carregadas. A configuração foi projetada para ser fácil de compartilhar com o time — faça o commit no repositório e todos os desenvolvedores terão a mesma rede de segurança para o agente.
 
 ---
 
@@ -13,12 +13,12 @@ failproofai usa arquivos de configuração JSON para controlar quais políticas
 Existem três escopos de configuração, avaliados em ordem de prioridade:
 
 | Escopo | Caminho do arquivo | Finalidade |
-|--------|-------------------|------------|
+|--------|--------------------|------------|
 | **project** | `.failproofai/policies-config.json` | Configurações por repositório, commitadas no controle de versão |
 | **local** | `.failproofai/policies-config.local.json` | Substituições pessoais por repositório, ignoradas pelo git |
-| **global** | `~/.failproofai/policies-config.json` | Padrões do usuário para todos os projetos |
+| **global** | `~/.failproofai/policies-config.json` | Padrões do usuário aplicados a todos os projetos |
 
-Quando failproofai recebe um evento de hook, ele carrega e mescla os três arquivos que existirem para o diretório de trabalho atual.
+Quando failproofai recebe um evento de hook, ele carrega e mescla todos os três arquivos existentes para o diretório de trabalho atual.
 
 ### Regras de mesclagem
 
@@ -32,26 +32,26 @@ global:   ["block-sudo", "sanitize-api-keys"]
 resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← união sem duplicatas
 ```
 
-**`policyParams`** — o primeiro escopo que define os parâmetros de uma determinada política vence por completo. Não há mesclagem profunda dos valores dentro dos parâmetros de uma política.
+**`policyParams`** — o primeiro escopo que define parâmetros para uma determinada política prevalece completamente. Não há mesclagem profunda de valores dentro dos parâmetros de uma política.
 
 ```text
 project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
 global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
 
-resolved: { allowPatterns: ["sudo apt-get update"] }   ← project vence, global é ignorado
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project prevalece, global ignorado
 ```
 
 ```text
-project:  (sem entrada block-sudo)
-local:    (sem entrada block-sudo)
+project:  (sem entrada para block-sudo)
+local:    (sem entrada para block-sudo)
 global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
 
-resolved: { allowPatterns: ["sudo systemctl status"] }  ← recai para o global
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← cai para o global
 ```
 
-**`customPoliciesPath`** — o primeiro escopo que o define vence.
+**`customPoliciesPath`** — o primeiro escopo que o definir prevalece.
 
-**`llm`** — o primeiro escopo que o define vence.
+**`llm`** — o primeiro escopo que o definir prevalece.
 
 ---
 
@@ -102,46 +102,46 @@ resolved: { allowPatterns: ["sudo systemctl status"] }  ← recai para o global
 
 Tipo: `string[]`
 
-Lista de nomes de políticas a habilitar. Os nomes devem corresponder exatamente aos identificadores de política exibidos por `failproofai policies`. Consulte [Políticas integradas](/pt-br/built-in-policies) para a lista completa.
+Lista de nomes de políticas a habilitar. Os nomes devem corresponder exatamente aos identificadores de política exibidos por `failproofai policies`. Consulte [Políticas Integradas](/pt-br/built-in-policies) para a lista completa.
 
-Políticas ausentes de `enabledPolicies` ficam inativas, mesmo que possuam entradas em `policyParams`.
+Políticas que não estão em `enabledPolicies` ficam inativas, mesmo que possuam entradas em `policyParams`.
 
 ### `policyParams`
 
 Tipo: `Record<string, Record<string, unknown>>`
 
-Substituições de parâmetros por política. A chave externa é o nome da política; as chaves internas são específicas de cada política. Cada política documenta seus parâmetros disponíveis em [Políticas integradas](/pt-br/built-in-policies).
+Substituições de parâmetros por política. A chave externa é o nome da política; as chaves internas são específicas de cada política. Cada política documenta seus parâmetros disponíveis em [Políticas Integradas](/pt-br/built-in-policies).
 
-Se uma política possui parâmetros mas você não os especifica, os valores padrão da política são utilizados. Usuários que não configuram `policyParams` têm comportamento idêntico ao das versões anteriores.
+Se uma política possui parâmetros, mas você não os especifica, os padrões integrados da política são utilizados. Usuários que não configuram `policyParams` obtêm comportamento idêntico ao das versões anteriores.
 
-Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenciosamente ignoradas no momento de disparo do hook, mas sinalizadas como avisos ao executar `failproofai policies`.
+Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenciosamente ignoradas no momento do disparo do hook, mas sinalizadas como avisos quando você executa `failproofai policies`.
 
 #### `hint` (transversal)
 
 Tipo: `string` (opcional)
 
-Uma mensagem anexada ao motivo quando uma política retorna `deny` ou `instruct`. Use-o para fornecer orientações acionáveis ao Claude sem modificar a própria política.
+Uma mensagem anexada ao motivo quando uma política retorna `deny` ou `instruct`. Use para fornecer orientações acionáveis ao Claude sem modificar a política em si.
 
-Funciona com qualquer tipo de política — integrada, personalizada (`custom/`), convenção de projeto (`.failproofai-project/`) ou convenção de usuário (`.failproofai-user/`).
+Funciona com qualquer tipo de política — integrada, customizada (`custom/`), convenção de projeto (`.failproofai-project/`) ou convenção do usuário (`.failproofai-user/`).
 
 ```json
 {
   "policyParams": {
     "block-force-push": {
-      "hint": "Tente criar um branch novo em vez disso."
+      "hint": "Try creating a fresh branch instead."
     },
     "block-sudo": {
       "allowPatterns": ["sudo apt-get"],
-      "hint": "Use apt-get diretamente sem sudo."
+      "hint": "Use apt-get directly without sudo."
     },
     "custom/my-policy": {
-      "hint": "Peça aprovação ao usuário primeiro."
+      "hint": "Ask the user for approval first."
     }
   }
 }
 ```
 
-Quando `block-force-push` nega, Claude recebe: *"Force-pushing está bloqueado. Tente criar um branch novo em vez disso."*
+Quando `block-force-push` nega, Claude vê: *"Force-pushing is blocked. Try creating a fresh branch instead."*
 
 Valores não textuais e strings vazias são silenciosamente ignorados. Se `hint` não estiver definido, o comportamento permanece inalterado (compatível com versões anteriores).
 
@@ -149,32 +149,32 @@ Valores não textuais e strings vazias são silenciosamente ignorados. Se `hint`
 
 Tipo: `string` (caminho absoluto)
 
-Caminho para um arquivo JavaScript contendo políticas de hook personalizadas. Esse campo é definido automaticamente por `failproofai policies --install --custom <path>` (o caminho é resolvido para absoluto antes de ser armazenado).
+Caminho para um arquivo JavaScript contendo políticas de hook customizadas. Este valor é definido automaticamente por `failproofai policies --install --custom <path>` (o caminho é resolvido para absoluto antes de ser armazenado).
 
-O arquivo é carregado novamente a cada evento de hook — não há cache. Consulte [Políticas personalizadas](/pt-br/custom-policies) para detalhes de autoria.
+O arquivo é carregado novamente a cada evento de hook — não há cache. Consulte [Políticas Customizadas](/pt-br/custom-policies) para detalhes sobre como criá-las.
 
 ### Políticas baseadas em convenção
 
-Além do `customPoliciesPath` explícito, failproofai descobre e carrega automaticamente arquivos de políticas dos diretórios `.failproofai/policies/`:
+Além do `customPoliciesPath` explícito, failproofai descobre e carrega automaticamente arquivos de política dos diretórios `.failproofai/policies/`:
 
 | Nível | Diretório | Escopo |
 |-------|-----------|--------|
 | Projeto | `.failproofai/policies/` | Compartilhado com o time via controle de versão |
-| Usuário | `~/.failproofai/policies/` | Pessoal, aplica-se a todos os projetos |
+| Usuário | `~/.failproofai/policies/` | Pessoal, aplicado a todos os projetos |
 
-**Correspondência de arquivos:** Apenas arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados (por exemplo, `security-policies.mjs`, `workflow-policies.js`). Outros arquivos no diretório são ignorados.
+**Correspondência de arquivos:** Somente arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados (ex.: `security-policies.mjs`, `workflow-policies.js`). Outros arquivos no diretório são ignorados.
 
-**Sem necessidade de configuração:** Políticas de convenção não exigem entradas em `policies-config.json`. Basta adicionar os arquivos ao diretório e eles serão detectados no próximo evento de hook.
+**Sem necessidade de configuração:** Políticas de convenção não requerem entradas em `policies-config.json`. Basta colocar os arquivos no diretório e eles serão detectados no próximo evento de hook.
 
-**Carregamento por união:** Os diretórios de convenção do projeto e do usuário são varridos. Todos os arquivos correspondentes de ambos os níveis são carregados (ao contrário de `customPoliciesPath`, que usa o primeiro escopo vencedor).
+**Carregamento por união:** Tanto o diretório de convenção do projeto quanto o do usuário são verificados. Todos os arquivos correspondentes de ambos os níveis são carregados (ao contrário de `customPoliciesPath`, que utiliza o primeiro escopo que prevalece).
 
-Consulte [Políticas personalizadas](/pt-br/custom-policies) para mais detalhes e exemplos.
+Consulte [Políticas Customizadas](/pt-br/custom-policies) para mais detalhes e exemplos.
 
 ### `llm`
 
 Tipo: `object` (opcional)
 
-Configuração do cliente LLM para políticas que fazem chamadas de IA. Não é necessário para a maioria dos casos.
+Configuração do cliente LLM para políticas que realizam chamadas de IA. Não é necessário para a maioria das configurações.
 
 ```json
 {
@@ -192,15 +192,15 @@ Configuração do cliente LLM para políticas que fazem chamadas de IA. Não é
 Os comandos `policies --install` e `policies --uninstall` escrevem no `settings.json` do Claude Code (os pontos de entrada do hook), enquanto `policies-config.json` é o arquivo que você gerencia diretamente. Os dois são separados:
 
 - **`settings.json`** — instrui o Claude Code a chamar `failproofai --hook <event>` a cada uso de ferramenta
-- **`policies-config.json`** — instrui o failproofai sobre quais políticas avaliar e com quais parâmetros
+- **`policies-config.json`** — instrui failproofai sobre quais políticas avaliar e com quais parâmetros
 
 Você pode editar `policies-config.json` diretamente a qualquer momento; as alterações entram em vigor imediatamente no próximo evento de hook, sem necessidade de reinicialização.
 
 ---
 
-## Exemplo: configuração no nível do projeto com padrões do time
+## Exemplo: configuração no nível do projeto com padrões da equipe
 
-Faça commit de `.failproofai/policies-config.json` no seu repositório:
+Faça o commit de `.failproofai/policies-config.json` no seu repositório:
 
 ```json
 {
@@ -219,4 +219,4 @@ Faça commit de `.failproofai/policies-config.json` no seu repositório:
 }
 ```
 
-Cada desenvolvedor pode então criar `.failproofai/policies-config.local.json` (ignorado pelo git) para substituições pessoais sem afetar os colegas de time.
+Cada desenvolvedor pode então criar `.failproofai/policies-config.local.json` (ignorado pelo git) para substituições pessoais sem afetar os colegas de equipe.

package/.next/standalone/docs/pt-br/custom-policies.mdx

@@ -1,10 +1,10 @@
 ---
 title: Políticas Personalizadas
-description: "Escreva suas próprias políticas em JavaScript - aplique convenções, previna desvios, detecte falhas, integre com sistemas externos"
+description: "Escreva suas próprias políticas em JavaScript - aplique convenções, evite desvios, detecte falhas e integre com sistemas externos"
 icon: code
 ---
 
-As políticas personalizadas permitem que você escreva regras para qualquer comportamento do agente: aplicar convenções do projeto, prevenir desvios, controlar operações destrutivas, detectar agentes travados ou integrar com Slack, fluxos de aprovação e muito mais. Elas usam o mesmo sistema de eventos de hook e as decisões `allow`, `deny`, `instruct` das políticas embutidas.
+As políticas personalizadas permitem que você escreva regras para qualquer comportamento do agente: aplicar convenções do projeto, evitar desvios, bloquear operações destrutivas, detectar agentes travados ou integrar com Slack, fluxos de aprovação e muito mais. Elas utilizam o mesmo sistema de eventos de hook e as decisões `allow`, `deny`, `instruct` das políticas integradas.
 
 ---
 
@@ -41,32 +41,32 @@ failproofai policies --install --custom ./my-policies.js
 
 ### Opção 1: Baseada em convenção (recomendada)
 
-Coloque arquivos `*policies.{js,mjs,ts}` dentro de `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração. Funciona como git hooks: coloque o arquivo e pronto.
+Coloque arquivos `*policies.{js,mjs,ts}` na pasta `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração. Funciona como git hooks: basta adicionar o arquivo e pronto.
 
 ```
-# Nível do projeto — commitado no git, compartilhado com o time
+# Nível de projeto — versionado no git, compartilhado com a equipe
 .failproofai/policies/security-policies.mjs
 .failproofai/policies/workflow-policies.mjs
 
-# Nível do usuário — pessoal, aplicado a todos os projetos
+# Nível de usuário — pessoal, aplicado a todos os projetos
 ~/.failproofai/policies/my-policies.mjs
 ```
 
 **Como funciona:**
-- Tanto o diretório do projeto quanto o do usuário são escaneados (união — não prevalece o primeiro escopo encontrado)
-- Os arquivos são carregados em ordem alfabética dentro de cada diretório. Use prefixos `01-`, `02-` para controlar a ordem
-- Apenas arquivos que correspondem a `*policies.{js,mjs,ts}` são carregados; outros arquivos são ignorados
+- Os diretórios de projeto e usuário são verificados (união — sem prioridade por escopo)
+- Os arquivos são carregados em ordem alfabética dentro de cada diretório. Use o prefixo `01-`, `02-` para controlar a ordem
+- Somente arquivos que correspondem a `*policies.{js,mjs,ts}` são carregados; outros arquivos são ignorados
 - Cada arquivo é carregado de forma independente (fail-open por arquivo)
-- Funciona junto com `--custom` explícito e políticas embutidas
+- Funciona em conjunto com `--custom` explícito e políticas integradas
 
 <Tip>
-As políticas por convenção são a forma mais fácil de compartilhar políticas com um time. Faça commit de `.failproofai/policies/` no git e todos os membros do time as recebem automaticamente.
+As políticas por convenção são a forma mais fácil de compartilhar políticas em uma equipe. Versione `.failproofai/policies/` no git e todos os membros da equipe receberão as políticas automaticamente.
 </Tip>
 
 ### Opção 2: Caminho de arquivo explícito
 
 ```bash
-# Instalar com um arquivo de políticas personalizado
+# Instalar com um arquivo de políticas personalizadas
 failproofai policies --install --custom ./my-policies.js
 
 # Substituir o caminho do arquivo de políticas
@@ -78,13 +78,13 @@ failproofai policies --uninstall --custom
 
 O caminho absoluto resolvido é armazenado em `policies-config.json` como `customPoliciesPath`. O arquivo é carregado novamente a cada evento de hook — não há cache entre eventos.
 
-### Usando as duas opções juntas
+### Usando ambas juntas
 
 As políticas por convenção e o arquivo `--custom` explícito podem coexistir. Ordem de carregamento:
 
 1. Arquivo `customPoliciesPath` explícito (se configurado)
-2. Arquivos de convenção do projeto (`{cwd}/.failproofai/policies/`, ordem alfabética)
-3. Arquivos de convenção do usuário (`~/.failproofai/policies/`, ordem alfabética)
+2. Arquivos de convenção do projeto (`{cwd}/.failproofai/policies/`, em ordem alfabética)
+3. Arquivos de convenção do usuário (`~/.failproofai/policies/`, em ordem alfabética)
 
 ---
 
@@ -104,39 +104,38 @@ Registra uma política. Chame quantas vezes forem necessárias para múltiplas p
 customPolicies.add({
   name: string;                         // obrigatório - identificador único
   description?: string;                 // exibido na saída de `failproofai policies`
-  match?: { events?: HookEventType[] }; // filtra por tipo de evento; omita para corresponder a todos
+  match?: { events?: HookEventType[] }; // filtra por tipo de evento; omitir para corresponder a todos
   fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
 });
 ```
 
-### Helpers de decisão
+### Funções auxiliares de decisão
 
-| Função | Efeito | Use quando |
-|--------|--------|------------|
-| `allow()` | Permite a operação silenciosamente | A ação é segura, nenhuma mensagem é necessária |
+| Função | Efeito | Quando usar |
+|----------|--------|----------|
+| `allow()` | Permite a operação silenciosamente | A ação é segura, sem mensagem necessária |
 | `deny(message)` | Bloqueia a operação | O agente não deve executar esta ação |
 | `instruct(message)` | Adiciona contexto sem bloquear | Fornece contexto adicional ao agente para mantê-lo no caminho certo |
 
-`deny(message)` — a mensagem aparece para Claude com o prefixo `"Blocked by failproofai:"`. Um único `deny` interrompe toda avaliação posterior.
+`deny(message)` — a mensagem aparece para Claude com o prefixo `"Blocked by failproofai:"`. Um único `deny` interrompe toda avaliação subsequente.
 
-`instruct(message)` — a mensagem é anexada ao contexto de Claude para a chamada de ferramenta atual. Todas as mensagens `instruct` são acumuladas e entregues juntas.
+`instruct(message)` — a mensagem é anexada ao contexto do Claude para a chamada de ferramenta atual. Todas as mensagens `instruct` são acumuladas e entregues juntas.
 
 <Tip>
-Você pode adicionar orientações extras a qualquer mensagem `deny` ou `instruct` incluindo um campo `hint` em `policyParams` — sem necessidade de alteração de código. Isso funciona para políticas personalizadas (`custom/`), de convenção do projeto (`.failproofai-project/`) e de convenção do usuário (`.failproofai-user/`) também. Veja [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para detalhes.
+Você pode adicionar orientações extras a qualquer mensagem `deny` ou `instruct` incluindo um campo `hint` em `policyParams` — sem necessidade de alteração no código. Isso também funciona para políticas personalizadas (`custom/`), de convenção de projeto (`.failproofai-project/`) e de convenção de usuário (`.failproofai-user/`). Consulte [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para mais detalhes.
 </Tip>
 
 ### Mensagens informativas de allow
 
+`allow(message)` permite a operação **e** envia uma mensagem informativa para Claude. A mensagem é entregue como `additionalContext` na resposta stdout do handler de hook — o mesmo mecanismo usado por `instruct`, mas semanticamente diferente: é uma atualização de status, não um aviso.
 
-`allow(message)` permite a operação **e** envia uma mensagem informativa de volta para Claude. A mensagem é entregue como `additionalContext` na resposta stdout do handler de hook — o mesmo mecanismo usado por `instruct`, mas semanticamente diferente: é uma atualização de status, não um aviso.
-
-| Função | Efeito | Use quando |
-|--------|--------|------------|
-| `allow(message)` | Permite e envia contexto para Claude | Confirmar que uma verificação passou, ou explicar por que foi ignorada |
+| Função | Efeito | Quando usar |
+|----------|--------|----------|
+| `allow(message)` | Permite e envia contexto para Claude | Confirma que uma verificação passou ou explica por que foi ignorada |
 
 Casos de uso:
-- **Confirmações de status:** `allow("All CI checks passed.")` — informa Claude que tudo está ok
-- **Explicações de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa Claude por que uma verificação foi ignorada, para que tenha contexto completo
+- **Confirmações de status:** `allow("All CI checks passed.")` — informa ao Claude que tudo está ok
+- **Explicações de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa ao Claude por que uma verificação foi ignorada para que ele tenha contexto completo
 - **Múltiplas mensagens se acumulam:** se várias políticas retornarem `allow(message)`, todas as mensagens são unidas com quebras de linha e entregues juntas
 
 ```js
@@ -147,7 +146,7 @@ customPolicies.add({
     const cwd = ctx.session?.cwd;
     if (!cwd) return allow("No working directory, skipping branch check.");
 
-    // ... check branch status ...
+    // ... verificar status do branch ...
     if (allPushed) {
       return allow("Branch is up to date with remote.");
     }
@@ -159,27 +158,27 @@ customPolicies.add({
 ### Campos de `PolicyContext`
 
 | Campo | Tipo | Descrição |
-|-------|------|-----------|
+|-------|------|-------------|
 | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | A ferramenta sendo chamada (ex.: `"Bash"`, `"Write"`, `"Read"`) |
+| `toolName` | `string \| undefined` | A ferramenta sendo chamada (ex: `"Bash"`, `"Write"`, `"Read"`) |
 | `toolInput` | `Record<string, unknown> \| undefined` | Os parâmetros de entrada da ferramenta |
-| `payload` | `Record<string, unknown>` | Payload bruto completo do evento do Claude Code |
+| `payload` | `Record<string, unknown>` | Payload completo do evento bruto do Claude Code |
 | `session` | `SessionMetadata \| undefined` | Contexto da sessão (veja abaixo) |
 
 ### Campos de `SessionMetadata`
 
 | Campo | Tipo | Descrição |
-|-------|------|-----------|
-| `sessionId` | `string` | Identificador da sessão do Claude Code |
+|-------|------|-------------|
+| `sessionId` | `string` | Identificador de sessão do Claude Code |
 | `cwd` | `string` | Diretório de trabalho da sessão do Claude Code |
 | `transcriptPath` | `string` | Caminho para o arquivo de transcrição JSONL da sessão |
 
 ### Tipos de evento
 
 | Evento | Quando dispara | Conteúdo de `toolInput` |
-|--------|---------------|------------------------|
-| `PreToolUse` | Antes de Claude executar uma ferramenta | A entrada da ferramenta (ex.: `{ command: "..." }` para Bash) |
-| `PostToolUse` | Após a conclusão de uma ferramenta | A entrada da ferramenta + `tool_result` (a saída) |
+|-------|--------------|----------------------|
+| `PreToolUse` | Antes de Claude executar uma ferramenta | A entrada da ferramenta (ex: `{ command: "..." }` para Bash) |
+| `PostToolUse` | Após uma ferramenta ser concluída | A entrada da ferramenta + `tool_result` (a saída) |
 | `Notification` | Quando Claude envia uma notificação | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks devem sempre retornar `allow()`, não podem bloquear notificações |
 | `Stop` | Quando a sessão Claude encerra | Vazio |
 
@@ -189,10 +188,10 @@ customPolicies.add({
 
 As políticas são avaliadas nesta ordem:
 
-1. Políticas embutidas (na ordem de definição)
-2. Políticas personalizadas explícitas do `customPoliciesPath` (na ordem de `.add()`)
-3. Políticas de convenção do projeto `.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo)
-4. Políticas de convenção do usuário `~/.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo)
+1. Políticas integradas (na ordem de definição)
+2. Políticas personalizadas explícitas de `customPoliciesPath` (na ordem de `.add()`)
+3. Políticas de convenção do projeto em `.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo)
+4. Políticas de convenção do usuário em `~/.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo)
 
 <Note>
 O primeiro `deny` interrompe todas as políticas subsequentes. Todas as mensagens `instruct` são acumuladas e entregues juntas.
@@ -219,7 +218,7 @@ customPolicies.add({
 });
 ```
 
-Todas as importações relativas acessíveis a partir do arquivo de entrada são resolvidas. Isso é implementado reescrevendo as importações de `from "failproofai"` para o caminho real do dist e criando arquivos `.mjs` temporários para garantir compatibilidade com ESM.
+Todas as importações relativas acessíveis a partir do arquivo de entrada são resolvidas. Isso é implementado reescrevendo as importações `from "failproofai"` para o caminho real em dist e criando arquivos `.mjs` temporários para garantir compatibilidade com ESM.
 
 ---
 
@@ -232,7 +231,7 @@ customPolicies.add({
   name: "require-summary-on-stop",
   match: { events: ["Stop"] },
   fn: async (ctx) => {
-    // Dispara apenas quando a sessão encerra
+    // Só dispara quando a sessão encerra
     // ctx.session.transcriptPath contém o log completo da sessão
     return allow();
   },
@@ -245,20 +244,20 @@ Omita `match` completamente para disparar em todos os tipos de evento.
 
 ## Tratamento de erros e modos de falha
 
-As políticas personalizadas são **fail-open**: erros nunca bloqueiam as políticas embutidas nem causam crash no handler de hook.
+Políticas personalizadas são **fail-open**: erros nunca bloqueiam políticas integradas nem derrubam o handler de hook.
 
 | Falha | Comportamento |
-|-------|---------------|
-| `customPoliciesPath` não definido | Nenhuma política personalizada explícita é executada; políticas de convenção e embutidas continuam normalmente |
-| Arquivo não encontrado | Aviso registrado em `~/.failproofai/hook.log`; políticas embutidas continuam |
-| Erro de sintaxe/importação (explícito) | Erro registrado em `~/.failproofai/hook.log`; políticas personalizadas explícitas são ignoradas |
-| Erro de sintaxe/importação (convenção) | Erro registrado; aquele arquivo é ignorado, outros arquivos de convenção ainda são carregados |
-| `fn` lança erro em tempo de execução | Erro registrado; aquele hook é tratado como `allow`; outros hooks continuam |
+|---------|----------|
+| `customPoliciesPath` não configurado | Nenhuma política personalizada explícita é executada; políticas por convenção e integradas continuam normalmente |
+| Arquivo não encontrado | Aviso registrado em `~/.failproofai/hook.log`; integradas continuam |
+| Erro de sintaxe/importação (explícito) | Erro registrado em `~/.failproofai/hook.log`; políticas personalizadas explícitas ignoradas |
+| Erro de sintaxe/importação (convenção) | Erro registrado; aquele arquivo é ignorado, outros arquivos de convenção continuam carregando |
+| `fn` lança exceção em tempo de execução | Erro registrado; aquele hook é tratado como `allow`; outros hooks continuam |
 | `fn` demora mais de 10s | Timeout registrado; tratado como `allow` |
 | Diretório de convenção ausente | Nenhuma política de convenção é executada; sem erro |
 
 <Tip>
-Para depurar erros de políticas personalizadas, monitore o arquivo de log:
+Para depurar erros em políticas personalizadas, acompanhe o arquivo de log:
 
 ```bash
 tail -f ~/.failproofai/hook.log
@@ -286,7 +285,7 @@ customPolicies.add({
   },
 });
 
-// Mantém o agente no caminho certo: verifica testes antes de commitar
+// Mantém o agente no caminho certo: verificar testes antes de fazer 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({
   },
 });
 
-// Previne alterações de dependências não planejadas durante o período de congelamento
+// Evita mudanças de dependências não planejadas durante o período de freeze
 customPolicies.add({
   name: "dependency-freeze",
   description: "Prevent unplanned dependency changes during freeze period",
@@ -327,11 +326,11 @@ export { customPolicies };
 O diretório `examples/` contém arquivos de políticas prontos para uso:
 
 | Arquivo | Conteúdo |
-|---------|----------|
-| `examples/policies-basic.js` | Cinco políticas iniciais cobrindo modos de falha comuns de agentes |
-| `examples/policies-advanced/index.js` | Padrões avançados: importações transitivas, chamadas assíncronas, limpeza de saída e hooks de fim de sessão |
-| `examples/convention-policies/security-policies.mjs` | Políticas de segurança baseadas em convenção (bloquear escritas em .env, impedir reescrita do histórico git) |
-| `examples/convention-policies/workflow-policies.mjs` | Políticas de fluxo de trabalho baseadas em convenção (lembretes de testes, auditoria de escritas em arquivos) |
+|------|----------|
+| `examples/policies-basic.js` | Cinco políticas iniciais cobrindo modos comuns de falha de agentes |
+| `examples/policies-advanced/index.js` | Padrões avançados: importações transitivas, chamadas assíncronas, sanitização de saída e hooks de fim de sessão |
+| `examples/convention-policies/security-policies.mjs` | Políticas de segurança baseadas em convenção (bloquear escritas em .env, evitar reescrita de histórico git) |
+| `examples/convention-policies/workflow-policies.mjs` | Políticas de fluxo de trabalho baseadas em convenção (lembretes de teste, auditoria de escritas em arquivos) |
 
 ### Usando exemplos com arquivo explícito
 
@@ -342,11 +341,11 @@ failproofai policies --install --custom ./examples/policies-basic.js
 ### Usando exemplos baseados em convenção
 
 ```bash
-# Copiar para o nível do projeto
+# Copiar para o nível de projeto
 mkdir -p .failproofai/policies
 cp examples/convention-policies/*.mjs .failproofai/policies/
 
-# Ou copiar para o nível do usuário
+# Ou copiar para o nível de usuário
 mkdir -p ~/.failproofai/policies
 cp examples/convention-policies/*.mjs ~/.failproofai/policies/
 ```