failproofai 0.0.2 → 0.0.4-beta.0

package/.next/standalone/docs/ko/built-in-policies.mdx

@@ -0,0 +1,535 @@
+---
+title: 내장 정책
+description: "일반적인 에이전트 실패 유형을 감지하는 30개의 내장 정책 전체 목록"
+icon: shield
+---
+
+failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의 내장 정책을 제공합니다. 각 정책은 특정 훅 이벤트 유형과 툴 이름에 따라 실행됩니다. 9개의 정책은 코드를 작성하지 않고도 동작을 조정할 수 있는 파라미터를 허용합니다. 4개의 워크플로우 정책은 Claude가 종료되기 전에 커밋 → 푸시 → PR → CI 파이프라인을 강제합니다.
+
+---
+
+## 개요
+
+정책은 카테고리별로 분류됩니다:
+
+| 카테고리 | 정책 | 훅 유형 |
+|----------|----------|-----------|
+| [위험한 명령어](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse |
+| [시크릿 (새니타이저)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse |
+| [환경](#environment) | block-env-files, protect-env-vars | PreToolUse |
+| [파일 접근](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse |
+| [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
+| [데이터베이스](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
+| [경고](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
+| [워크플로우](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-ci-green-before-stop | Stop |
+
+- **`block-`** — 에이전트 진행을 차단합니다.
+- **`warn-`** — 에이전트가 스스로 수정할 수 있도록 추가 컨텍스트를 제공합니다.
+- **`sanitize-`** — 에이전트에게 전달되기 전에 툴 출력에서 민감한 데이터를 제거합니다.
+- **`require-`** — 조건이 충족될 때까지 Stop 이벤트를 차단합니다.
+
+---
+
+<Tip>
+모든 정책은 `policyParams`에서 선택적 `hint` 필드를 지원합니다. hint는 Claude가 보는 deny 또는 instruct 메시지에 추가되어, 정책 코드를 수정하지 않고도 실행 가능한 안내를 제공합니다. 내장, 커스텀, 컨벤션 정책 모두에서 동작합니다. 자세한 내용은 [구성 → hint](/ko/configuration#hint-cross-cutting)를 참조하세요.
+</Tip>
+
+---
+
+## 위험한 명령어
+
+에이전트가 되돌리기 어렵거나 호스트 시스템에 손상을 줄 수 있는 작업을 실행하는 것을 방지합니다.
+
+### `block-sudo`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `sudo` 키워드가 포함된 모든 명령어를 차단합니다.
+
+`sudo` 키워드가 포함된 호출을 차단합니다. 패턴 매칭은 원시 문자열이 아닌 파싱된 명령어 토큰을 기준으로 수행되어, 셸 연산자 인젝션을 통한 우회를 방지합니다.
+
+**파라미터:**
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | 허용되는 정확한 명령어 프리픽스. 각 항목은 파싱된 argv 토큰과 대조하여 매칭됩니다. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    }
+  }
+}
+```
+
+이 설정을 사용하면 `sudo systemctl status nginx`는 허용되지만, `sudo rm /etc/hosts`는 차단됩니다.
+
+<Note>
+패턴은 원시 명령어 문자열이 아닌 파싱된 토큰과 대조하여 매칭됩니다. 이를 통해 셸 연산자 추가를 통한 우회를 방지합니다 (예: `sudo systemctl status x; rm -rf /`는 `sudo systemctl status *`와 매칭되지 않습니다).
+</Note>
+
+---
+
+### `block-rm-rf`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `rm -rf`, `rm -fr` 및 유사한 재귀 삭제 형태를 차단합니다.
+
+**파라미터:**
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | 재귀 삭제가 허용되는 경로 (예: `/tmp`). |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-rm-rf": {
+      "allowPaths": ["/tmp", "/var/cache"]
+    }
+  }
+}
+```
+
+---
+
+### `block-curl-pipe-sh`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` 및 유사한 패턴을 차단합니다.
+
+파라미터 없음.
+
+---
+
+### `block-failproofai-commands`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** failproofai 자체를 제거하거나 비활성화하려는 명령어를 차단합니다 (예: `npm uninstall failproofai`, `failproofai policies --uninstall`).
+
+파라미터 없음.
+
+---
+
+## 시크릿 (새니타이저)
+
+에이전트가 자격 증명을 컨텍스트나 출력에 노출시키는 것을 방지합니다. 새니타이저 정책은 **PostToolUse** 이벤트에서 실행됩니다. Claude가 Bash 명령어를 실행하거나, 파일을 읽거나, 어떤 툴을 호출할 때, 이 정책들은 출력이 Claude에게 반환되기 전에 검사합니다. 시크릿 패턴이 감지되면, 정책은 출력이 다시 전달되는 것을 막는 deny 결정을 반환합니다.
+
+### `sanitize-jwt`
+
+**이벤트:** PostToolUse (모든 툴)  
+**기본 동작:** JWT 토큰 (`.`으로 구분된 세 개의 base64url 세그먼트)을 마스킹합니다.
+
+파라미터 없음.
+
+---
+
+### `sanitize-api-keys`
+
+**이벤트:** PostToolUse (모든 툴)  
+**기본 동작:** 일반적인 API 키 형식을 마스킹합니다: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT (`ghp_`), AWS 액세스 키 (`AKIA`), Stripe 키 (`sk_live_`, `sk_test_`), Google API 키 (`AIza`).
+
+**파라미터:**
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | 시크릿으로 처리할 추가 정규식 패턴. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
+        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### `sanitize-connection-strings`
+
+**이벤트:** PostToolUse (모든 툴)  
+**기본 동작:** 자격 증명이 포함된 데이터베이스 연결 문자열을 마스킹합니다 (예: `postgresql://user:password@host/db`).
+
+파라미터 없음.
+
+---
+
+### `sanitize-private-key-content`
+
+**이벤트:** PostToolUse (모든 툴)  
+**기본 동작:** PEM 블록(`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` 등)을 마스킹합니다.
+
+파라미터 없음.
+
+---
+
+### `sanitize-bearer-tokens`
+
+**이벤트:** PostToolUse (모든 툴)  
+**기본 동작:** 토큰이 20자 이상인 `Authorization: Bearer <token>` 헤더를 마스킹합니다.
+
+파라미터 없음.
+
+---
+
+## 환경
+
+에이전트가 민감한 환경 구성을 읽거나 노출시키는 것을 보호합니다.
+
+### `block-env-files`
+
+**이벤트:** PreToolUse (Bash, Read)  
+**기본 동작:** `cat .env`, `.env`를 파일 경로로 사용하는 `Read` 툴 호출 등을 통한 `.env` 파일 읽기를 차단합니다.
+
+`.envrc`나 다른 환경 관련 파일은 차단하지 않으며, 정확히 `.env`라는 이름의 파일만 차단합니다.
+
+파라미터 없음.
+
+---
+
+### `protect-env-vars`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** 환경 변수를 출력하는 명령어를 차단합니다: `printenv`, `env`, `echo $VAR`.
+
+파라미터 없음.
+
+---
+
+## 파일 접근
+
+에이전트가 프로젝트 경계 내에서만 작업하고 민감한 파일에 접근하지 못하도록 합니다.
+
+### `block-read-outside-cwd`
+
+**이벤트:** PreToolUse (Read, Bash)  
+**기본 동작:** 현재 작업 디렉토리(프로젝트 루트) 외부의 파일 읽기를 차단합니다.
+
+**파라미터:**
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | cwd 외부에 있더라도 허용되는 절대 경로 프리픽스. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company/config"]
+    }
+  }
+}
+```
+
+---
+
+### `block-secrets-write`
+
+**이벤트:** PreToolUse (Write, Edit)  
+**기본 동작:** 개인 키 및 인증서에 일반적으로 사용되는 파일에 대한 쓰기를 차단합니다: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
+
+**파라미터:**
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `string[]` | `[]` | 차단할 추가 파일명 패턴 (글로브 스타일). |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-secrets-write": {
+      "additionalPatterns": [".token", ".secret"]
+    }
+  }
+}
+```
+
+---
+
+## Git
+
+실수로 인한 푸시, 강제 푸시, 되돌리기 어려운 브랜치 실수를 방지합니다.
+
+### `block-push-master`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `git push origin main`과 `git push origin master`를 차단합니다.
+
+**파라미터:**
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | 직접 푸시할 수 없는 브랜치 이름. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "master", "release", "prod"]
+    }
+  }
+}
+```
+
+<Tip>
+`enabledPolicies`에서 정책을 제거하지 않고 모든 브랜치로의 푸시를 허용하려면 (사실상 정책 비활성화), `protectedBranches: []`로 설정하세요.
+</Tip>
+
+---
+
+### `block-work-on-main`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `main` 또는 `master` 브랜치를 직접 체크아웃하는 것을 차단합니다.
+
+**파라미터:**
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | 직접 체크아웃할 수 없는 브랜치 이름. |
+
+---
+
+### `block-force-push`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `git push --force`와 `git push -f`를 차단합니다.
+
+정책별 파라미터 없음. 크로스커팅 [`hint`](/ko/configuration#hint-cross-cutting)를 사용하여 대안을 제안할 수 있습니다:
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
+    }
+  }
+}
+```
+
+---
+
+### `warn-git-amend`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `git commit --amend` 실행 시 Claude에게 신중하게 진행하도록 안내합니다. 명령어 자체를 차단하지는 않습니다.
+
+파라미터 없음.
+
+---
+
+### `warn-git-stash-drop`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `git stash drop` 실행 전에 Claude에게 확인하도록 안내합니다. 명령어 자체를 차단하지는 않습니다.
+
+파라미터 없음.
+
+---
+
+### `warn-all-files-staged`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `git add -A` 또는 `git add .` 실행 시 Claude에게 스테이징할 내용을 검토하도록 안내합니다. 명령어 자체를 차단하지는 않습니다.
+
+파라미터 없음.
+
+---
+
+## 데이터베이스
+
+데이터베이스에 실행되기 전에 파괴적인 SQL 작업을 감지합니다.
+
+### `warn-destructive-sql`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `DROP TABLE`, `DROP DATABASE`, 또는 `WHERE` 절 없는 `DELETE`가 포함된 SQL 실행 전에 Claude에게 확인하도록 안내합니다.
+
+파라미터 없음.
+
+---
+
+### `warn-schema-alteration`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `ALTER TABLE` 구문 실행 전에 Claude에게 확인하도록 안내합니다.
+
+파라미터 없음.
+
+---
+
+## 경고
+
+파괴적이지는 않지만 잠재적으로 위험한 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다.
+
+### `warn-large-file-write`
+
+**이벤트:** PreToolUse (Write)  
+**기본 동작:** 1024 KB보다 큰 파일을 쓰기 전에 Claude에게 확인하도록 안내합니다.
+
+**파라미터:**
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `thresholdKb` | `number` | `1024` | 경고가 발생하는 파일 크기 임계값 (킬로바이트). |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "warn-large-file-write": {
+      "thresholdKb": 256
+    }
+  }
+}
+```
+
+<Note>
+훅 핸들러는 페이로드에 대해 1 MB stdin 제한을 적용합니다. 소용량 콘텐츠로 이 정책을 테스트하려면 `thresholdKb`를 1024보다 훨씬 낮은 값으로 설정하세요.
+</Note>
+
+---
+
+### `warn-package-publish`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `npm publish` 실행 전에 Claude에게 확인하도록 안내합니다.
+
+파라미터 없음.
+
+---
+
+### `warn-background-process`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `nohup`, `&`, `disown`, 또는 `screen`을 통해 백그라운드 프로세스를 시작할 때 Claude에게 주의하도록 안내합니다.
+
+파라미터 없음.
+
+---
+
+### `warn-global-package-install`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `npm install -g`, `yarn global add`, 또는 가상 환경 없이 `pip install` 실행 전에 Claude에게 확인하도록 안내합니다.
+
+파라미터 없음.
+
+---
+
+## AI 동작
+
+에이전트가 멈추거나 예기치 않게 동작하는 경우를 감지합니다.
+
+### `warn-repeated-tool-calls`
+
+**이벤트:** PreToolUse (모든 툴)  
+**기본 동작:** 동일한 툴이 동일한 파라미터로 3회 이상 호출될 때 Claude에게 재고하도록 안내합니다 — 이는 에이전트가 루프에 빠진 일반적인 신호입니다.
+
+파라미터 없음.
+
+---
+
+## 워크플로우
+
+세션 종료 시 체계적인 워크플로우를 강제합니다. 이 정책들은 **Stop** 이벤트에서 실행되며, 각 조건이 충족될 때까지 Claude의 종료를 차단합니다. 커밋 → 푸시 → PR → CI의 자연스러운 의존성 체인을 따릅니다. 정책이 deny를 반환하면, 체인의 이후 정책은 건너뜁니다 (deny 단락 평가).
+
+모든 워크플로우 정책은 **fail-open** 방식입니다: 필요한 툴을 사용할 수 없는 경우 (예: `gh`가 설치되지 않음, git 원격 없음), 정책은 검사를 건너뛴 이유를 설명하는 안내 메시지와 함께 허용합니다.
+
+### `require-commit-before-stop`
+
+**이벤트:** Stop  
+**기본 동작:** 커밋되지 않은 변경 사항(수정됨, 스테이징됨, 추적되지 않는 파일)이 있을 때 종료를 차단합니다. 작업 디렉토리가 깨끗할 때는 안내 메시지를 반환합니다.
+
+파라미터 없음.
+
+---
+
+### `require-push-before-stop`
+
+**이벤트:** Stop  
+**기본 동작:** 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 종료를 차단합니다. 필요한 경우 추적 브랜치 생성을 위해 `git push -u`를 제안합니다. 원격이 구성되지 않은 경우 fail-open 처리됩니다.
+
+**파라미터:**
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `remote` | `string` | `"origin"` | 푸시할 원격 이름. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "require-push-before-stop": {
+      "remote": "upstream"
+    }
+  }
+}
+```
+
+---
+
+### `require-pr-before-stop`
+
+**이벤트:** Stop  
+**기본 동작:** 현재 브랜치에 대한 풀 리퀘스트가 없거나, 기존 PR이 닫혔거나 머지된 경우 종료를 차단합니다. `gh pr create`로 PR을 생성하도록 Claude에게 안내합니다.
+
+파라미터 없음.
+
+<Note>
+이 정책은 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되고 인증되어 있어야 합니다.
+풀 리퀘스트에 대한 읽기 접근을 위해 `repo` 스코프를 가진 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않거나 인증되지 않은 경우, 정책은 fail-open 처리되고 Claude에게 이유를 보고합니다.
+</Note>
+
+---
+
+### `require-ci-green-before-stop`
+
+**이벤트:** Stop  
+**기본 동작:** 현재 브랜치에서 CI 검사가 실패 중이거나 아직 실행 중일 때 종료를 차단합니다. GitHub Actions 워크플로우 실행과 서드파티 봇 검사(예: CodeRabbit, SonarCloud, Codecov)를 모두 확인합니다. `skipped` 결론은 성공으로 처리합니다. 모든 검사가 통과하면 안내 메시지를 반환합니다.
+
+파라미터 없음.
+
+<Note>
+이 정책은 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되고 인증되어 있어야 합니다.
+Actions 워크플로우 실행 및 Checks API에 대한 읽기 접근을 위해 `repo` 스코프를 가진 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않거나 인증되지 않은 경우, 정책은 fail-open 처리되고 Claude에게 이유를 보고합니다.
+</Note>
+
+---
+
+---
+
+## 개별 정책 비활성화
+
+설정 파일의 `enabledPolicies`에서 특정 정책을 제거하거나, 대시보드의 Policies 탭에서 토글로 끄세요.
+
+```json
+{
+  "enabledPolicies": [
+    "block-rm-rf",
+    "sanitize-api-keys"
+  ]
+}
+```
+
+`enabledPolicies`에 나열되지 않은 정책은 `policyParams` 항목이 존재하더라도 실행되지 않습니다.

package/.next/standalone/docs/ko/cli/dashboard.mdx

@@ -0,0 +1,28 @@
+---
+title: 세션 보기
+description: "대시보드를 실행하여 에이전트 세션을 탐색하고 정책을 관리합니다"
+---
+
+```bash
+failproofai
+```
+
+`http://localhost:8020`에서 웹 대시보드를 시작합니다.
+
+## 옵션
+
+| 플래그 | 설명 |
+|------|-------------|
+| `--port <number>` | 수신 대기할 포트 (기본값: `8020`) |
+| `--projects-path <path>` | Claude Code 프로젝트 폴더 위치를 재정의합니다 |
+| `--allowed-origins <origins>` | 개발 리소스 접근이 허용된 호스트/IP 목록 (쉼표로 구분) |
+
+## 예시
+
+```bash
+# 다른 포트에서 실행
+failproofai --port 9000
+
+# 커스텀 프로젝트 경로 사용
+failproofai --projects-path ~/my-claude-projects
+```

package/.next/standalone/docs/ko/cli/environment-variables.mdx

@@ -0,0 +1,34 @@
+---
+title: 환경 변수
+description: "환경 변수를 통한 failproofai 동작 설정"
+---
+
+## 대시보드
+
+| 변수 | 설명 |
+|----------|-------------|
+| `PORT` | 대시보드 포트 (기본값: `8020`) |
+| `CLAUDE_PROJECTS_PATH` | Claude Code 프로젝트 폴더 위치 재정의 |
+| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | 숨길 대시보드 페이지를 쉼표로 구분하여 지정 |
+| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | 개발 리소스에 접근을 허용할 호스트/IP. `--allowed-origins`와 동일. |
+
+## 로깅
+
+| 변수 | 설명 |
+|----------|-------------|
+| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | 서버 로그 레벨 (기본값: `warn`) |
+| `FAILPROOFAI_HOOK_LOG_FILE` | 커스텀 훅 로그 파일 경로, 또는 기본값(`~/.failproofai/logs/hooks.log`)을 사용하려면 `true` |
+
+## 텔레메트리
+
+| 변수 | 설명 |
+|----------|-------------|
+| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 익명 사용 텔레메트리 비활성화 |
+
+## LLM (정책 평가용)
+
+| 변수 | 설명 |
+|----------|-------------|
+| `FAILPROOFAI_LLM_BASE_URL` | LLM API 엔드포인트 (기본값: `https://api.openai.com/v1`) |
+| `FAILPROOFAI_LLM_API_KEY` | LLM 기반 정책을 위한 API 키 |
+| `FAILPROOFAI_LLM_MODEL` | 모델 이름 (기본값: `gpt-4o-mini`) |

package/.next/standalone/docs/ko/cli/hook.mdx

@@ -0,0 +1,30 @@
+---
+title: 훅 핸들러 (내부)
+description: "각 도구 이벤트에서 Claude Code가 호출하는 서브프로세스"
+---
+
+```bash
+failproofai --hook <EventType>
+```
+
+이 명령은 `failproofai policies --install`에 의해 Claude Code의 `settings.json`에 등록됩니다. 일반적으로 직접 호출하지 않습니다.
+
+stdin에서 JSON 페이로드를 읽고, 활성화된 모든 정책을 평가한 후, 결정을 나타내는 종료 코드와 함께 종료됩니다:
+
+| 종료 코드 | 결정 | 효과 |
+|-----------|----------|--------|
+| `0` | `allow` | 작업을 허용합니다 |
+| `1` | `deny` | 작업을 차단합니다 - Claude가 거부 이유를 확인합니다 |
+| `2` | `instruct` | Claude의 컨텍스트에 가이던스를 주입합니다 |
+
+### 지원되는 이벤트 유형
+
+| 카테고리 | 이벤트 |
+|----------|--------|
+| **도구 실행** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` |
+| **세션 생명주기** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` |
+| **사용자 상호작용** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` |
+| **서브에이전트 및 태스크** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` |
+| **구성** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` |
+| **파일 시스템** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` |
+| **컨텍스트** | `PreCompact`, `PostCompact` |

package/.next/standalone/docs/ko/cli/install-policies.mdx

@@ -0,0 +1,47 @@
+---
+title: 정책 설치
+description: "에이전트의 모든 도구 호출에서 정책이 실행되도록 활성화합니다"
+---
+
+```bash
+failproofai policies --install [policy-names...] [options]
+```
+
+Claude Code의 `settings.json`에 훅 항목을 작성하여 failproofai가 도구 호출을 가로챌 수 있도록 합니다.
+
+별칭: `failproofai p -i`
+
+## 옵션
+
+| 플래그 | 설명 |
+|------|-------------|
+| `--scope user` | `~/.claude/settings.json`에 설치 (기본값 - 모든 세션에 적용) |
+| `--scope project` | 현재 디렉터리의 `.claude/settings.json`에 설치 |
+| `--scope local` | 현재 디렉터리의 `.claude/settings.local.json`에 설치 |
+| `--custom <path>` / `-c` | 커스텀 훅 정책이 포함된 JS 파일 경로 |
+
+## 동작 방식
+
+- **정책 이름 미지정** - 정책을 선택할 수 있는 대화형 프롬프트가 열립니다
+- **특정 이름 지정** - 해당 정책을 활성화합니다 (이미 활성화된 정책에 추가됨)
+- **`all`** - 사용 가능한 모든 정책을 활성화합니다
+
+설치는 누적 방식으로 동작합니다. `--install`을 다시 실행하면 기존 정책을 제거하지 않고 새 정책을 추가합니다.
+
+## 예시
+
+```bash
+# 전역에 모든 기본 정책 설치 (대화형)
+failproofai policies --install
+
+# 현재 프로젝트에 특정 정책 설치
+failproofai policies --install block-sudo sanitize-api-keys --scope project
+
+# 모든 정책을 한 번에 활성화
+failproofai policies --install all
+
+# 커스텀 정책 파일과 함께 설치
+failproofai policies --install --custom ./my-policies.js
+```
+
+`--custom <path>`가 제공되면 해당 파일이 즉시 유효성 검사를 거칩니다. 파일은 `customPolicies.add()`를 최소 한 번 이상 호출해야 합니다. 확인된 경로는 `customPoliciesPath`로 `policies-config.json`에 저장됩니다.