failproofai 0.0.5 → 0.0.6-beta.0

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

@@ -1,14 +1,14 @@
 ---
 title: 커스텀 정책
-description: "JavaScript로 직접 정책을 작성하세요 - 컨벤션 적용, 드리프트 방지, 실패 감지, 외부 시스템 연동"
+description: "JavaScript로 나만의 정책을 작성하세요 - 컨벤션 강제, 드리프트 방지, 실패 감지, 외부 시스템 연동 등"
 icon: code
 ---
 
-커스텀 정책을 사용하면 에이전트 동작에 대한 규칙을 직접 작성할 수 있습니다. 프로젝트 컨벤션 강제 적용, 드리프트 방지, 위험한 작업 차단, 멈춘 에이전트 감지, Slack이나 승인 워크플로우 연동 등 다양한 용도로 활용할 수 있습니다. 내장 정책과 동일한 훅 이벤트 시스템 및 `allow`, `deny`, `instruct` 결정 방식을 사용합니다.
+커스텀 정책을 사용하면 에이전트 동작에 대한 규칙을 직접 작성할 수 있습니다: 프로젝트 컨벤션 강제, 드리프트 방지, 위험한 작업 차단, 멈춘 에이전트 감지, Slack 연동, 승인 워크플로우 연동 등 다양한 용도로 활용할 수 있습니다. 빌트인 정책과 동일한 훅 이벤트 시스템과 `allow`, `deny`, `instruct` 결정 방식을 사용합니다.
 
 ---
 
-## 빠른 예제
+## 빠른 예시
 
 ```js
 // my-policies.js
@@ -37,30 +37,30 @@ failproofai policies --install --custom ./my-policies.js
 
 ---
 
-## 커스텀 정책을 불러오는 두 가지 방법
+## 커스텀 정책을 로드하는 두 가지 방법
 
 ### 방법 1: 컨벤션 기반 (권장)
 
-`.failproofai/policies/` 디렉터리에 `*policies.{js,mjs,ts}` 파일을 넣으면 자동으로 불러옵니다 — 별도의 플래그나 설정 변경이 필요 없습니다. git 훅처럼 파일을 넣으면 바로 작동합니다.
+`.failproofai/policies/` 디렉터리에 `*policies.{js,mjs,ts}` 파일을 넣기만 하면 자동으로 로드됩니다 — 별도의 플래그나 설정 변경이 필요 없습니다. git 훅처럼 파일만 넣으면 바로 동작합니다.
 
 ```
-# 프로젝트 레벨 — git에 커밋되어 팀과 공유
+# 프로젝트 레벨 — git에 커밋되어 팀 전체에 공유
 .failproofai/policies/security-policies.mjs
 .failproofai/policies/workflow-policies.mjs
 
-# 사용자 레벨 — 개인용, 모든 프로젝트에 적용
+# 사용자 레벨 — 개인 설정, 모든 프로젝트에 적용
 ~/.failproofai/policies/my-policies.mjs
 ```
 
 **동작 방식:**
-- 프로젝트와 사용자 디렉터리 모두 탐색합니다 (합집합 방식 — 첫 번째 스코프 우선이 아님)
-- 각 디렉터리 내에서 파일은 알파벳 순으로 불러옵니다. 순서를 제어하려면 `01-`, `02-` 접두사를 사용하세요
-- `*policies.{js,mjs,ts}` 패턴에 맞는 파일만 불러옵니다. 그 외 파일은 무시됩니다
-- 각 파일은 독립적으로 불러옵니다 (파일 단위 fail-open)
-- 명시적 `--custom` 및 내장 정책과 함께 사용할 수 있습니다
+- 프로젝트 디렉터리와 사용자 디렉터리를 모두 스캔합니다 (합집합 방식 — 스코프 우선순위 방식 아님)
+- 각 디렉터리 내에서 파일은 알파벳 순서로 로드됩니다. 순서를 제어하려면 `01-`, `02-` 등의 접두사를 사용하세요
+- `*policies.{js,mjs,ts}` 패턴에 맞는 파일만 로드되며, 그 외 파일은 무시됩니다
+- 각 파일은 독립적으로 로드됩니다 (파일별 fail-open)
+- 명시적 `--custom` 및 빌트인 정책과 함께 사용할 수 있습니다
 
 <Tip>
-컨벤션 정책은 팀 전체에 정책을 공유하는 가장 쉬운 방법입니다. `.failproofai/policies/`를 git에 커밋하면 팀원 모두가 자동으로 적용받습니다.
+컨벤션 정책은 팀 전체에 정책을 공유하는 가장 쉬운 방법입니다. `.failproofai/policies/`를 git에 커밋하면 모든 팀원이 자동으로 적용받습니다.
 </Tip>
 
 ### 방법 2: 명시적 파일 경로
@@ -76,11 +76,11 @@ failproofai policies --install --custom ./new-policies.js
 failproofai policies --uninstall --custom
 ```
 
-확인된 절대 경로는 `policies-config.json`에 `customPoliciesPath`로 저장됩니다. 파일은 매 훅 이벤트마다 새로 불러옵니다 — 이벤트 간 캐싱은 없습니다.
+변환된 절대 경로는 `policies-config.json`의 `customPoliciesPath`에 저장됩니다. 파일은 매 훅 이벤트마다 새로 로드됩니다 - 이벤트 간 캐싱은 없습니다.
 
 ### 두 방법 함께 사용하기
 
-컨벤션 정책과 명시적 `--custom` 파일은 함께 사용할 수 있습니다. 불러오는 순서:
+컨벤션 정책과 명시적 `--custom` 파일은 함께 사용할 수 있습니다. 로드 순서:
 
 1. 명시적 `customPoliciesPath` 파일 (설정된 경우)
 2. 프로젝트 컨벤션 파일 (`{cwd}/.failproofai/policies/`, 알파벳 순)
@@ -90,7 +90,7 @@ failproofai policies --uninstall --custom
 
 ## API
 
-### Import
+### 임포트
 
 ```js
 import { customPolicies, allow, deny, instruct } from "failproofai";
@@ -98,13 +98,13 @@ import { customPolicies, allow, deny, instruct } from "failproofai";
 
 ### `customPolicies.add(hook)`
 
-정책을 등록합니다. 같은 파일에 여러 정책을 등록하려면 필요한 만큼 호출하세요.
+정책을 등록합니다. 하나의 파일에 여러 정책을 추가하려면 여러 번 호출하면 됩니다.
 
 ```ts
 customPolicies.add({
   name: string;                         // 필수 - 고유 식별자
   description?: string;                 // `failproofai policies` 출력에 표시됨
-  match?: { events?: HookEventType[] }; // 이벤트 유형으로 필터링; 생략 시 모든 이벤트에 적용
+  match?: { events?: HookEventType[] }; // 이벤트 타입으로 필터링; 생략 시 모든 이벤트에 매칭
   fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
 });
 ```
@@ -113,31 +113,30 @@ customPolicies.add({
 
 | 함수 | 효과 | 사용 시점 |
 |----------|--------|----------|
-| `allow()` | 조용히 작업을 허용 | 작업이 안전하고 메시지가 필요 없을 때 |
-| `deny(message)` | 작업을 차단 | 에이전트가 해당 작업을 수행해서는 안 될 때 |
-| `instruct(message)` | 차단 없이 컨텍스트 추가 | 에이전트가 올바른 방향을 유지하도록 추가 정보를 제공할 때 |
+| `allow()` | 조용히 작업을 허용 | 동작이 안전하고 메시지가 필요 없을 때 |
+| `deny(message)` | 작업을 차단 | 에이전트가 이 동작을 수행해서는 안 될 때 |
+| `instruct(message)` | 차단 없이 컨텍스트 추가 | 에이전트가 올바른 방향을 유지하도록 추가 컨텍스트를 제공할 때 |
 
-`deny(message)` — 메시지는 `"Blocked by failproofai:"` 접두사가 붙어 Claude에게 전달됩니다. 하나의 `deny`가 이후 모든 평가를 단락시킵니다.
+`deny(message)` - 메시지는 `"Blocked by failproofai:"` 접두사와 함께 Claude에게 표시됩니다. 하나의 `deny`가 발생하면 이후 모든 평가가 중단됩니다.
 
-`instruct(message)` — 메시지는 현재 도구 호출에 대한 Claude의 컨텍스트에 추가됩니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
+`instruct(message)` - 메시지는 현재 툴 호출에 대한 Claude의 컨텍스트에 추가됩니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
 
 <Tip>
-`policyParams`의 `hint` 필드를 추가하면 코드 변경 없이 `deny` 또는 `instruct` 메시지에 추가 안내를 덧붙일 수 있습니다. 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 작동합니다. 자세한 내용은 [Configuration → hint](/ko/configuration#hint-cross-cutting)를 참고하세요.
+`policyParams`의 `hint` 필드를 추가하면 코드 변경 없이 `deny` 또는 `instruct` 메시지에 추가 가이던스를 붙일 수 있습니다. 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 동작합니다. 자세한 내용은 [설정 → hint](/ko/configuration#hint-cross-cutting)를 참조하세요.
 </Tip>
 
 ### 정보성 allow 메시지
 
-
-`allow(message)`는 작업을 허용하면서 **동시에** 정보성 메시지를 Claude에게 전달합니다. 메시지는 훅 핸들러의 stdout 응답에서 `additionalContext`로 전달됩니다 — `instruct`와 동일한 메커니즘이지만, 의미적으로 다릅니다. 이는 경고가 아닌 상태 업데이트입니다.
+`allow(message)`는 작업을 허용하면서 **동시에** Claude에게 정보성 메시지를 전달합니다. 메시지는 훅 핸들러의 stdout 응답에서 `additionalContext`로 전달되며, `instruct`와 동일한 메커니즘을 사용하지만 의미상 다릅니다: 경고가 아닌 상태 업데이트입니다.
 
 | 함수 | 효과 | 사용 시점 |
 |----------|--------|----------|
 | `allow(message)` | 허용하면서 Claude에게 컨텍스트 전달 | 검사가 통과되었음을 확인하거나, 검사가 건너뛰어진 이유를 설명할 때 |
 
-사용 사례:
-- **상태 확인:** `allow("All CI checks passed.")` — 모든 것이 정상임을 Claude에게 알림
-- **Fail-open 설명:** `allow("GitHub CLI not installed, skipping CI check.")` — 검사가 건너뛰어진 이유를 Claude에게 알려 전체 컨텍스트를 제공
-- **다중 메시지 누적:** 여러 정책이 각각 `allow(message)`를 반환하면 모든 메시지가 줄바꿈으로 이어져 함께 전달됨
+활용 예시:
+- **상태 확인:** `allow("All CI checks passed.")` — Claude에게 모든 것이 정상임을 알림
+- **Fail-open 설명:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude가 완전한 컨텍스트를 갖도록 검사가 건너뛰어진 이유를 알림
+- **다중 메시지 누적:** 여러 정책이 각각 `allow(message)`를 반환하면 모든 메시지가 줄바꿈으로 연결되어 함께 전달됩니다
 
 ```js
 customPolicies.add({
@@ -161,9 +160,9 @@ customPolicies.add({
 | 필드 | 타입 | 설명 |
 |-------|------|-------------|
 | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | 호출되는 도구 (예: `"Bash"`, `"Write"`, `"Read"`) |
-| `toolInput` | `Record<string, unknown> \| undefined` | 도구의 입력 파라미터 |
-| `payload` | `Record<string, unknown>` | Claude Code에서 전달된 전체 원시 이벤트 페이로드 |
+| `toolName` | `string \| undefined` | 호출되는 툴 (예: `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | 툴의 입력 파라미터 |
+| `payload` | `Record<string, unknown>` | Claude Code로부터의 전체 원시 이벤트 페이로드 |
 | `session` | `SessionMetadata \| undefined` | 세션 컨텍스트 (아래 참조) |
 
 ### `SessionMetadata` 필드
@@ -174,14 +173,14 @@ customPolicies.add({
 | `cwd` | `string` | Claude Code 세션의 작업 디렉터리 |
 | `transcriptPath` | `string` | 세션의 JSONL 트랜스크립트 파일 경로 |
 
-### 이벤트 유형
+### 이벤트 타입
 
 | 이벤트 | 발생 시점 | `toolInput` 내용 |
 |-------|--------------|----------------------|
-| `PreToolUse` | Claude가 도구를 실행하기 전 | 도구의 입력 (예: Bash의 경우 `{ command: "..." }`) |
-| `PostToolUse` | 도구 실행 완료 후 | 도구의 입력 + `tool_result` (출력값) |
-| `Notification` | Claude가 알림을 보낼 때 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - 훅은 항상 `allow()`를 반환해야 하며 알림을 차단할 수 없습니다 |
-| `Stop` | Claude 세션 종료 시 | 비어 있음 |
+| `PreToolUse` | Claude가 툴을 실행하기 전 | 툴의 입력 (예: Bash의 경우 `{ command: "..." }`) |
+| `PostToolUse` | 툴 실행 완료 후 | 툴의 입력 + `tool_result` (출력) |
+| `Notification` | Claude가 알림을 보낼 때 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - 훅은 항상 `allow()`를 반환해야 하며, 알림을 차단할 수 없습니다 |
+| `Stop` | Claude 세션이 종료될 때 | 비어 있음 |
 
 ---
 
@@ -189,20 +188,20 @@ customPolicies.add({
 
 정책은 다음 순서로 평가됩니다:
 
-1. 내장 정책 (정의 순서대로)
-2. `customPoliciesPath`의 명시적 커스텀 정책 (`.add()` 호출 순서대로)
-3. 프로젝트 `.failproofai/policies/`의 컨벤션 정책 (파일은 알파벳 순, 파일 내에서는 `.add()` 순서)
-4. 사용자 `~/.failproofai/policies/`의 컨벤션 정책 (파일은 알파벳 순, 파일 내에서는 `.add()` 순서)
+1. 빌트인 정책 (정의 순서)
+2. `customPoliciesPath`의 명시적 커스텀 정책 (`.add()` 순서)
+3. 프로젝트 `.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내 `.add()` 순서)
+4. 사용자 `~/.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내 `.add()` 순서)
 
 <Note>
-첫 번째 `deny`는 이후 모든 정책을 단락시킵니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
+첫 번째 `deny`가 이후 모든 정책 평가를 중단시킵니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
 </Note>
 
 ---
 
-## 전이적 import
+## 전이적 임포트
 
-커스텀 정책 파일은 상대 경로를 사용해 로컬 모듈을 import할 수 있습니다:
+커스텀 정책 파일은 상대 경로를 사용하여 로컬 모듈을 임포트할 수 있습니다:
 
 ```js
 // my-policies.js
@@ -219,46 +218,46 @@ customPolicies.add({
 });
 ```
 
-엔트리 파일에서 도달 가능한 모든 상대 import가 처리됩니다. 이는 `from "failproofai"` import를 실제 dist 경로로 재작성하고, ESM 호환성을 보장하기 위해 임시 `.mjs` 파일을 생성하는 방식으로 구현됩니다.
+엔트리 파일에서 도달 가능한 모든 상대 임포트가 해석됩니다. 이는 `from "failproofai"` 임포트를 실제 dist 경로로 재작성하고 ESM 호환성을 보장하기 위해 임시 `.mjs` 파일을 생성하는 방식으로 구현됩니다.
 
 ---
 
-## 이벤트 유형 필터링
+## 이벤트 타입 필터링
 
-`match.events`를 사용해 정책이 발동되는 시점을 제한하세요:
+`match.events`를 사용하여 정책이 발동되는 시점을 제한합니다:
 
 ```js
 customPolicies.add({
   name: "require-summary-on-stop",
   match: { events: ["Stop"] },
   fn: async (ctx) => {
-    // 세션이 종료될 때만 발동
-    // ctx.session.transcriptPath에 전체 세션 로그가 포함됨
+    // 세션이 종료될 때만 발동됨
+    // ctx.session.transcriptPath에 전체 세션 로그가 있음
     return allow();
   },
 });
 ```
 
-`match`를 완전히 생략하면 모든 이벤트 유형에서 발동됩니다.
+`match`를 완전히 생략하면 모든 이벤트 타입에서 발동됩니다.
 
 ---
 
-## 오류 처리 및 실패 모드
+## 에러 처리 및 실패 모드
 
-커스텀 정책은 **fail-open** 방식입니다: 오류가 발생해도 내장 정책을 차단하거나 훅 핸들러를 중단시키지 않습니다.
+커스텀 정책은 **fail-open** 방식입니다: 에러가 발생해도 빌트인 정책이 차단되거나 훅 핸들러가 크래시되지 않습니다.
 
 | 실패 상황 | 동작 |
 |---------|----------|
-| `customPoliciesPath` 미설정 | 명시적 커스텀 정책이 실행되지 않음; 컨벤션 정책과 내장 정책은 정상 계속 |
-| 파일을 찾을 수 없음 | `~/.failproofai/hook.log`에 경고 기록; 내장 정책은 계속 |
-| 구문/import 오류 (명시적) | `~/.failproofai/hook.log`에 오류 기록; 명시적 커스텀 정책 건너뜀 |
-| 구문/import 오류 (컨벤션) | 오류 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 계속 로드 |
-| `fn` 런타임 예외 | 오류 기록; 해당 훅은 `allow`로 처리; 다른 훅은 계속 |
-| `fn` 실행 10초 초과 | 타임아웃 기록; `allow`로 처리 |
-| 컨벤션 디렉터리 없음 | 컨벤션 정책 실행 안 됨; 오류 없음 |
+| `customPoliciesPath` 미설정 | 명시적 커스텀 정책이 실행되지 않음; 컨벤션 정책과 빌트인은 정상 계속 |
+| 파일 없음 | `~/.failproofai/hook.log`에 경고 기록; 빌트인 계속 |
+| 문법/임포트 에러 (명시적) | `~/.failproofai/hook.log`에 에러 기록; 명시적 커스텀 정책 건너뜀 |
+| 문법/임포트 에러 (컨벤션) | 에러 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 계속 로드 |
+| `fn` 런타임 에러 | 에러 기록; 해당 훅은 `allow`로 처리; 다른 훅은 계속 |
+| `fn`이 10초 초과 | 타임아웃 기록; `allow`로 처리 |
+| 컨벤션 디렉터리 없음 | 컨벤션 정책 실행 안 됨; 에러 없음 |
 
 <Tip>
-커스텀 정책 오류를 디버깅하려면 로그 파일을 모니터링하세요:
+커스텀 정책 에러를 디버깅하려면 로그 파일을 모니터링하세요:
 
 ```bash
 tail -f ~/.failproofai/hook.log
@@ -267,7 +266,7 @@ tail -f ~/.failproofai/hook.log
 
 ---
 
-## 전체 예제: 다중 정책
+## 전체 예시: 다중 정책
 
 ```js
 // my-policies.js
@@ -286,7 +285,7 @@ customPolicies.add({
   },
 });
 
-// 에이전트가 올바른 방향 유지: 커밋 전 테스트 확인
+// 에이전트가 올바른 방향을 유지하도록: 커밋 전 테스트 확인
 customPolicies.add({
   name: "remind-test-before-commit",
   description: "Keep the agent on track: verify tests pass before committing",
@@ -301,7 +300,7 @@ customPolicies.add({
   },
 });
 
-// 프리즈 기간 중 계획되지 않은 의존성 변경 방지
+// 동결 기간 중 계획되지 않은 의존성 변경 방지
 customPolicies.add({
   name: "dependency-freeze",
   description: "Prevent unplanned dependency changes during freeze period",
@@ -322,24 +321,24 @@ export { customPolicies };
 
 ---
 
-## 예제 파일
+## 예시 파일
 
-`examples/` 디렉터리에는 바로 실행 가능한 정책 파일이 포함되어 있습니다:
+`examples/` 디렉터리에는 바로 실행 가능한 정책 파일들이 있습니다:
 
 | 파일 | 내용 |
 |------|----------|
 | `examples/policies-basic.js` | 일반적인 에이전트 실패 모드를 다루는 5가지 기본 정책 |
-| `examples/policies-advanced/index.js` | 고급 패턴: 전이적 import, 비동기 호출, 출력 스크러빙, 세션 종료 훅 |
-| `examples/convention-policies/security-policies.mjs` | 컨벤션 기반 보안 정책 (.env 쓰기 차단, git 히스토리 재작성 방지) |
-| `examples/convention-policies/workflow-policies.mjs` | 컨벤션 기반 워크플로우 정책 (테스트 알림, 감사 파일 쓰기) |
+| `examples/policies-advanced/index.js` | 고급 패턴: 전이적 임포트, 비동기 호출, 출력 스크러빙, 세션 종료 훅 |
+| `examples/convention-policies/security-policies.mjs` | 컨벤션 기반 보안 정책 (.env 파일 쓰기 차단, git 히스토리 재작성 방지) |
+| `examples/convention-policies/workflow-policies.mjs` | 컨벤션 기반 워크플로우 정책 (테스트 리마인더, 파일 쓰기 감사) |
 
-### 명시적 파일 예제 사용하기
+### 명시적 파일 예시 사용
 
 ```bash
 failproofai policies --install --custom ./examples/policies-basic.js
 ```
 
-### 컨벤션 기반 예제 사용하기
+### 컨벤션 기반 예시 사용
 
 ```bash
 # 프로젝트 레벨로 복사
@@ -351,4 +350,4 @@ mkdir -p ~/.failproofai/policies
 cp examples/convention-policies/*.mjs ~/.failproofai/policies/
 ```
 
-설치 명령이 필요하지 않습니다 — 다음 훅 이벤트 시 파일이 자동으로 인식됩니다.
+설치 명령어가 필요 없습니다 — 다음 훅 이벤트 시 파일이 자동으로 감지됩니다.

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

@@ -12,18 +12,18 @@ Este documento explica como o failproofai funciona internamente: como o sistema
 
 O failproofai possui dois subsistemas independentes:
 
-1. **Hook handler** - Um subprocesso CLI rápido que o Claude Code invoca a cada chamada de ferramenta do agente. Avalia as políticas e retorna uma decisão.
+1. **Handler de hooks** - Um subprocesso CLI rápido que o Claude Code invoca em cada chamada de ferramenta do agente. Avalia as políticas e retorna uma decisão.
 2. **Monitor de Agentes (Dashboard)** - Uma aplicação web Next.js para monitorar sessões de agentes e gerenciar políticas.
 
 Ambos os subsistemas compartilham arquivos de configuração em `~/.failproofai/` e no diretório `.failproofai/` do projeto, mas são executados como processos separados e se comunicam apenas pelo sistema de arquivos.
 
 ---
 
-## Hook handler
+## Handler de hooks
 
 ### Integração com o Claude Code
 
-Quando você executa `failproofai policies --install`, ele escreve entradas como esta em `~/.claude/settings.json`:
+Quando você executa `failproofai policies --install`, ele escreve entradas como esta no `~/.claude/settings.json`:
 
 ```json
 {
@@ -44,7 +44,7 @@ Quando você executa `failproofai policies --install`, ele escreve entradas como
 }
 ```
 
-O Claude Code então invoca `failproofai --hook PreToolUse` como subprocesso antes de cada chamada de ferramenta, passando um payload JSON via stdin.
+O Claude Code então invoca `failproofai --hook PreToolUse` como um subprocesso antes de cada chamada de ferramenta, passando um payload JSON via stdin.
 
 ### Formato do payload
 
@@ -62,11 +62,11 @@ O Claude Code então invoca `failproofai --hook PreToolUse` como subprocesso ant
 
 Para eventos `PostToolUse`, o payload também contém `tool_result` com a saída da ferramenta.
 
-O handler impõe um limite de 1 MB para stdin. Payloads que excedam esse tamanho são descartados e todas as políticas permitem implicitamente.
+O handler aplica um limite de 1 MB para o stdin. Payloads que excedam esse limite são descartados e todas as políticas implicitamente permitem a operação.
 
 ### Formato da resposta
 
-**Deny (PreToolUse):**
+**Negar (PreToolUse):**
 ```json
 {
   "hookSpecificOutput": {
@@ -76,7 +76,7 @@ O handler impõe um limite de 1 MB para stdin. Payloads que excedam esse tamanho
 }
 ```
 
-**Deny (PostToolUse):**
+**Negar (PostToolUse):**
 ```json
 {
   "hookSpecificOutput": {
@@ -85,7 +85,7 @@ O handler impõe um limite de 1 MB para stdin. Payloads que excedam esse tamanho
 }
 ```
 
-**Instruct (qualquer evento exceto Stop):**
+**Instruir (qualquer evento exceto Stop):**
 ```json
 {
   "hookSpecificOutput": {
@@ -94,17 +94,17 @@ O handler impõe um limite de 1 MB para stdin. Payloads que excedam esse tamanho
 }
 ```
 
-**Instruct para evento Stop:**
+**Instruir em evento Stop:**
 - Código de saída: `2`
-- Motivo escrito em stderr (não em stdout)
+- Motivo escrito no stderr (não no stdout)
 
-**Allow:**
+**Permitir:**
 - Código de saída: `0`
 - stdout vazio
 
-**Allow com mensagem:**
+**Permitir com mensagem:**
 
-`allow(message)` permite que uma política envie contexto informativo de volta ao Claude mesmo quando a operação é permitida. O hook handler escreve o seguinte JSON em **stdout** (não em um arquivo de configuração — esta é a resposta do handler ao Claude Code, assim como as respostas de deny e instruct acima):
+`allow(message)` permite que uma política envie contexto informativo de volta ao Claude mesmo quando a operação é permitida. O handler de hooks escreve o seguinte JSON no **stdout** (não em um arquivo de configuração — esta é a resposta do handler ao Claude Code, assim como as respostas de deny e instruct acima):
 
 ```json
 // Written to stdout by the hook handler process
@@ -115,8 +115,8 @@ O handler impõe um limite de 1 MB para stdin. Payloads que excedam esse tamanho
 }
 ```
 - Código de saída: `0` (a operação é permitida)
-- Quando múltiplas políticas retornam `allow` com uma mensagem, suas mensagens são unidas com quebras de linha em uma única string `additionalContext`
-- Se nenhuma política fornecer uma mensagem, stdout fica vazio (igual ao comportamento anterior)
+- Quando múltiplas políticas retornam `allow` com uma mensagem, as mensagens são unidas com quebras de linha em uma única string `additionalContext`
+- Se nenhuma política fornecer uma mensagem, o stdout fica vazio (como antes)
 
 ### Pipeline de processamento
 
@@ -139,7 +139,7 @@ stdin JSON
   → exit
 ```
 
-Todo o processo é executado em menos de 100ms para payloads típicos, sem nenhuma chamada a LLMs.
+Todo o processo é executado em menos de 100ms para payloads típicos, sem nenhuma chamada a LLM.
 
 ---
 
@@ -154,12 +154,12 @@ Todo o processo é executado em menos de 100ms para payloads típicos, sem nenhu
 ```
 
 Lógica de mesclagem:
-- `enabledPolicies` - união sem duplicatas entre os três arquivos
-- `policyParams` - por chave de política, o primeiro arquivo que a define vence inteiramente
-- `customPoliciesPath` - o primeiro arquivo que a define vence
-- `llm` - o primeiro arquivo que a define vence
+- `enabledPolicies` - união deduplicada entre os três arquivos
+- `policyParams` - por chave de política, o primeiro arquivo que a define prevalece inteiramente
+- `customPoliciesPath` - o primeiro arquivo que o define prevalece
+- `llm` - o primeiro arquivo que o define prevalece
 
-O dashboard web utiliza `readHooksConfig()` (somente global) para leitura e escrita, pois não é invocado com um cwd de projeto.
+O dashboard web usa `readHooksConfig()` (somente global) para leitura e escrita, pois não é invocado com um cwd de projeto.
 
 ---
 
@@ -169,24 +169,24 @@ O dashboard web utiliza `readHooksConfig()` (somente global) para leitura e escr
 
 Para cada política:
 
-1. Busca o esquema de `params` da política (se houver).
+1. Busca o schema de `params` da política (se houver).
 2. Lê `policyParams[policy.name]` da configuração mesclada.
-3. Mescla os valores fornecidos pelo usuário sobre os padrões do esquema para produzir `ctx.params`.
+3. Mescla os valores fornecidos pelo usuário sobre os padrões do schema para produzir `ctx.params`.
 4. Chama `policy.fn(ctx)` com o contexto resolvido.
-5. Se o resultado for `deny`, interrompe imediatamente e retorna essa decisão.
+5. Se o resultado for `deny`, para imediatamente e retorna essa decisão.
 6. Se o resultado for `instruct`, acumula a mensagem e continua.
 7. Se o resultado for `allow`, continua para a próxima política.
 
 Após todas as políticas serem executadas:
 - Se algum `deny` foi retornado, emite a resposta de deny.
-- Se algum retorno `instruct` foi coletado, emite uma única resposta instruct com todas as mensagens unidas.
-- Caso contrário, emite uma resposta allow (stdout vazio, saída 0).
+- Se algum retorno `instruct` foi coletado, emite uma única resposta de instruct com todas as mensagens unidas.
+- Caso contrário, emite uma resposta de allow (stdout vazio, exit 0).
 
 ---
 
-## Políticas embutidas
+## Políticas integradas
 
-`src/hooks/builtin-policies.ts` define todas as 26 políticas embutidas como objetos `BuiltinPolicyDefinition`:
+`src/hooks/builtin-policies.ts` define todas as 26 políticas integradas como objetos `BuiltinPolicyDefinition`:
 
 ```typescript
 interface BuiltinPolicyDefinition {
@@ -206,11 +206,11 @@ interface BuiltinPolicyDefinition {
 
 Políticas que aceitam `params` declaram um `PolicyParamsSchema` com tipos e valores padrão para cada parâmetro. O avaliador de políticas injeta os valores resolvidos em `ctx.params` antes de chamar `fn`. As funções de política leem `ctx.params` sem verificações de nulo porque os padrões são sempre aplicados primeiro.
 
-A correspondência de padrões dentro das políticas usa tokens de comando analisados (argv), não correspondência de strings brutas. Isso evita bypass por injeção de operadores shell (por exemplo, um padrão para `sudo systemctl status *` não pode ser ignorado anexando `; rm -rf /` ao comando).
+A correspondência de padrões dentro das políticas usa tokens de comando analisados (argv), não correspondência de strings brutas. Isso evita bypass por injeção de operadores de shell (por exemplo, um padrão para `sudo systemctl status *` não pode ser contornado adicionando `; rm -rf /` ao comando).
 
 ---
 
-## Políticas personalizadas
+## Políticas customizadas
 
 `src/hooks/custom-hooks-registry.ts` implementa um registro baseado em `globalThis`:
 
@@ -225,25 +225,25 @@ export function getCustomHooks(): CustomHook[] { ... }
 export function clearCustomHooks(): void { ... }  // used in tests
 ```
 
-`src/hooks/custom-hooks-loader.ts` carrega o arquivo de políticas do usuário:
+`src/hooks/custom-hooks-loader.ts` carrega o arquivo de política do usuário:
 
 1. Lê `customPoliciesPath` da configuração; ignora se ausente.
 2. Resolve para caminho absoluto; verifica se o arquivo existe.
-3. Reescreve todas as importações `from "failproofai"` para o caminho real do dist, de modo que `customPolicies` resolva para o mesmo registro `globalThis`.
-4. Reescreve recursivamente importações locais transitivas para garantir compatibilidade ESM.
-5. Grava arquivos `.mjs` temporários e realiza `import()` do arquivo de entrada.
+3. Reescreve todas as importações `from "failproofai"` para o caminho real de dist, de modo que `customPolicies` resolva para o mesmo registro `globalThis`.
+4. Reescreve recursivamente as importações locais transitivas para garantir compatibilidade com ESM.
+5. Escreve arquivos `.mjs` temporários e faz `import()` do arquivo de entrada.
 6. Chama `getCustomHooks()` para recuperar os hooks registrados.
-7. Limpa todos os arquivos temporários em um bloco `finally`.
+7. Remove todos os arquivos temporários em um bloco `finally`.
 
-Em caso de qualquer erro (arquivo não encontrado, erro de sintaxe, falha na importação), o erro é registrado em `~/.failproofai/hook.log` e o loader retorna um array vazio. As políticas embutidas não são afetadas.
+Em caso de qualquer erro (arquivo não encontrado, erro de sintaxe, falha de importação), o erro é registrado em `~/.failproofai/hook.log` e o loader retorna um array vazio. As políticas integradas não são afetadas.
 
-As políticas personalizadas são avaliadas após todas as políticas embutidas. Um `deny` de política personalizada ainda interrompe as demais políticas personalizadas (mas todos os embutidos já terão sido executados nesse ponto).
+As políticas customizadas são avaliadas após todas as políticas integradas. Um `deny` de uma política customizada ainda interrompe as demais políticas customizadas (mas todas as políticas integradas já terão sido executadas nesse ponto).
 
 ---
 
-## Log de atividade
+## Registro de atividade
 
-Após cada evento de hook, o handler anexa uma linha JSONL em `~/.failproofai/hook-activity.jsonl`:
+Após cada evento de hook, o handler anexa uma linha JSONL ao `~/.failproofai/hook-activity.jsonl`:
 
 ```json
 {
@@ -258,17 +258,17 @@ Após cada evento de hook, o handler anexa uma linha JSONL em `~/.failproofai/ho
 }
 ```
 
-Uma linha por política que tomou uma decisão diferente de allow. Decisões allow não são registradas (para manter o arquivo pequeno).
+Uma linha por política que tomou uma decisão diferente de allow. Decisões de allow não são registradas (para manter o arquivo pequeno).
 
 ---
 
 ## Arquitetura do dashboard
 
-O dashboard é uma aplicação **Next.js 16** usando o App Router com React Server Components e Server Actions.
+O dashboard é uma aplicação **Next.js 16** que utiliza o App Router com React Server Components e Server Actions.
 
 ```text
 app/
-  layout.tsx                  ← Layout raiz (tema, telemetria, navegação)
+  layout.tsx                  ← Layout raiz (tema, telemetria, nav)
   projects/page.tsx           ← Server component: lista todos os projetos Claude
   project/[name]/page.tsx     ← Server component: lista sessões em um projeto
   project/[name]/session/
@@ -277,8 +277,8 @@ app/
   actions/
     get-hooks-config.ts       ← Lê configuração + lista de políticas
     update-hooks-config.ts    ← Ativa/desativa política
-    update-policy-params.ts   ← Atualiza parâmetros da política
-    get-hook-activity.ts      ← Paginação/busca no log de atividade
+    update-policy-params.ts   ← Atualiza parâmetros de política
+    get-hook-activity.ts      ← Pagina/pesquisa log de atividade
     install-hooks-web.ts      ← Instala/remove hooks pelo navegador
   api/
     download/[project]/[session]/route.ts   ← Exporta sessão como ZIP/JSONL
@@ -287,15 +287,15 @@ app/
 **Fluxo de dados:**
 
 - Os componentes de página chamam `lib/projects.ts` e `lib/log-entries.ts` para ler dados de projeto/sessão diretamente do sistema de arquivos (sem camada de API para leituras).
-- A página de Políticas usa Server Actions para todas as mutações (alternar, atualizar parâmetros, instalar/remover).
+- A página de Políticas usa Server Actions para todas as mutações (toggle, atualização de parâmetros, instalação/remoção).
 - O visualizador de sessão analisa o formato de transcrição JSONL do Claude e renderiza uma linha do tempo de mensagens e chamadas de ferramentas.
 
 **Principais decisões de design:**
 
-- Sem banco de dados - todo estado persistente está em arquivos simples (`~/.failproofai/`, `~/.claude/projects/`).
-- Server Actions para mutações - sem necessidade de API REST para operações CRUD.
-- React Server Components para páginas de leitura - carregamento inicial mais rápido, sem bundle no cliente para busca de dados.
-- Client components apenas onde interatividade é necessária (alternância de políticas, busca de atividade, visualizador de log).
+- Sem banco de dados - todo o estado persistente está em arquivos simples (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions para mutações - nenhuma API REST necessária para operações CRUD.
+- React Server Components para páginas de leitura - carregamento inicial mais rápido, sem bundle do cliente para busca de dados.
+- Client components apenas onde a interatividade é necessária (toggles de política, pesquisa de atividade, visualizador de log).
 
 ---
 
@@ -313,20 +313,20 @@ failproofai/
 │   ├── policy-types.ts           # Interfaces TypeScript
 │   ├── hooks-config.ts           # Carregamento de configuração multi-escopo
 │   ├── custom-hooks-registry.ts  # Registro de hooks baseado em globalThis
-│   ├── custom-hooks-loader.ts    # Carregador ESM para hooks JS do usuário
+│   ├── custom-hooks-loader.ts    # Loader ESM para hooks JS do usuário
 │   ├── manager.ts                # Operações de instalação / remoção / listagem
 │   ├── install-prompt.ts         # Prompt interativo de seleção de políticas
 │   ├── hook-logger.ts            # Registro em hook.log
-│   ├── hook-activity-store.ts    # Persiste atividade em hook-activity.jsonl
-│   └── llm-client.ts             # Cliente de API LLM (para políticas com IA)
+│   ├── hook-activity-store.ts    # Persistência de atividade em hook-activity.jsonl
+│   └── llm-client.ts             # Cliente de API LLM (para políticas baseadas em IA)
 ├── app/                          # Dashboard Next.js (páginas + server actions)
 ├── lib/                          # Utilitários compartilhados
 │   ├── projects.ts               # Enumera projetos Claude do sistema de arquivos
 │   ├── log-entries.ts            # Analisa o formato JSONL de transcrição do Claude
 │   ├── paths.ts                  # Resolve caminhos do sistema
 │   └── ...
-├── components/                   # Componentes React de UI compartilhados
-├── contexts/                     # Provedores de contexto React (tema, atualização automática, telemetria)
-├── examples/                     # Exemplos de arquivos de hooks personalizados
+├── components/                   # Componentes React UI compartilhados
+├── contexts/                     # Provedores de contexto React (tema, auto-refresh, telemetria)
+├── examples/                     # Exemplos de arquivos de hooks customizados
 └── __tests__/                    # Testes unitários e E2E
 ```