failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,562 @@
+---
+title: 기본 제공 정책
+description: "일반적인 에이전트 실패 패턴을 감지하는 30개의 기본 제공 정책"
+icon: shield
+---
+
+failproofai는 일반적인 에이전트 실패 패턴을 감지하는 30개의 기본 제공 정책을 포함합니다. 각 정책은 특정 훅 이벤트 타입과 도구 이름에 따라 실행됩니다. 9개의 정책은 코드 작성 없이 동작을 조정할 수 있는 파라미터를 지원합니다. 4개의 베타 워크플로우 정책은 Claude가 중단하기 전에 commit → push → 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-beta) | 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>
+
+---
+
+## 위험한 명령어 {#dangerous-commands}
+
+되돌리기 어렵거나 호스트 시스템에 손상을 줄 수 있는 작업을 에이전트가 실행하지 못하도록 방지합니다.
+
+### `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`).
+
+파라미터 없음.
+
+---
+
+## 시크릿 (새니타이저) {#secrets-sanitizers}
+
+에이전트가 자격 증명을 컨텍스트나 출력에 노출하지 못하도록 방지합니다. 새니타이저 정책은 **PostToolUse** 이벤트에 실행됩니다. Claude가 Bash 명령을 실행하거나, 파일을 읽거나, 도구를 호출할 때 이 정책들은 Claude에게 반환되기 전에 출력을 검사합니다. 시크릿 패턴이 감지되면, 정책은 출력이 다시 전달되지 않도록 차단 결정을 반환합니다.
+
+### `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>` 헤더를 삭제합니다.
+
+파라미터 없음.
+
+---
+
+## 환경 {#environment}
+
+에이전트가 민감한 환경 설정을 읽거나 노출하지 못하도록 보호합니다.
+
+### `block-env-files`
+
+**이벤트:** PreToolUse (Bash, Read)  
+**기본 동작:** `cat .env`, 파일 경로가 `.env`인 `Read` 도구 호출 등을 통한 `.env` 파일 읽기를 거부합니다.
+
+`.envrc`나 다른 환경 관련 파일은 차단하지 않으며, 정확히 `.env`라는 이름의 파일만 차단합니다.
+
+파라미터 없음.
+
+---
+
+### `protect-env-vars`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** 환경 변수를 출력하는 명령을 거부합니다: `printenv`, `env`, `echo $VAR`.
+
+파라미터 없음.
+
+---
+
+## 파일 접근 {#file-access}
+
+에이전트가 프로젝트 경계 내에서만 작업하고 민감한 파일에 접근하지 못하도록 유지합니다.
+
+### `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[]` | `[]` | 차단할 추가 파일명 패턴(glob 방식). |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-secrets-write": {
+      "additionalPatterns": [".token", ".secret"]
+    }
+  }
+}
+```
+
+---
+
+## Git {#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에게 스테이징할 내용을 검토하도록 안내합니다. 명령을 차단하지 않습니다.
+
+파라미터 없음.
+
+---
+
+## 데이터베이스 {#database}
+
+데이터베이스에 대해 실행되기 전에 파괴적인 SQL 작업을 감지합니다.
+
+### `warn-destructive-sql`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `DROP TABLE`, `DROP DATABASE`, 또는 `WHERE` 절이 없는 `DELETE`가 포함된 SQL 실행 전 Claude에게 확인을 요청하도록 안내합니다.
+
+파라미터 없음.
+
+---
+
+### `warn-schema-alteration`
+
+**이벤트:** PreToolUse (Bash)  
+**기본 동작:** `ALTER TABLE` 문 실행 전 Claude에게 확인을 요청하도록 안내합니다.
+
+파라미터 없음.
+
+---
+
+## 경고 {#warnings}
+
+파괴적이지 않지만 잠재적으로 위험한 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다.
+
+### `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 동작 {#ai-behavior}
+
+에이전트가 막히거나 예상치 못한 동작을 하는 경우를 감지합니다.
+
+### `warn-repeated-tool-calls`
+
+**이벤트:** PreToolUse (모든 도구)  
+**기본 동작:** 동일한 도구가 동일한 파라미터로 3번 이상 호출될 때(에이전트가 루프에 빠진 일반적인 신호) Claude에게 재고하도록 안내합니다.
+
+파라미터 없음.
+
+---
+
+## 워크플로우 (베타) {#workflow-beta}
+
+세션 종료 시 규율 잡힌 워크플로우를 강제합니다. 이 정책들은 **Stop** 이벤트에 실행되며, 각 조건이 충족될 때까지 Claude가 중단하지 못하도록 차단합니다. 자연스러운 의존성 체인을 따릅니다: commit → push → PR → CI. 정책이 거부하면 체인의 이후 정책은 건너뜁니다(거부 시 단락).
+
+모든 워크플로우 정책은 **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>
+
+---
+
+## 베타 정책
+
+일부 정책은 `beta`로 표시되어 있으며 기본적으로 설치되지 않습니다. 베타 정책은 일부 미흡한 부분이 있거나 오탐이 발생할 수 있습니다. 향후 릴리스에서 안정 버전으로 승격됩니다.
+
+**현재 베타 정책:**
+
+- `require-commit-before-stop` — 중단 전 모든 변경 사항 커밋
+- `require-push-before-stop` — 모든 커밋을 원격에 푸시
+- `require-pr-before-stop` — 브랜치에 대한 PR 존재 여부 확인
+- `require-ci-green-before-stop` — 모든 CI 검사 통과 필요
+
+이 정책들을 합치면 **commit → push → PR → CI** 워크플로우가 강제됩니다.
+
+모든 베타 정책을 설치하려면:
+
+```bash
+failproofai policies --install --beta
+```
+
+또는 특정 워크플로우 정책을 설치하려면:
+
+```bash
+failproofai policies --install require-commit-before-stop require-push-before-stop require-pr-before-stop require-ci-green-before-stop
+```
+
+베타 플래그가 있는 정책을 확인하려면 `failproofai policies`를 실행하세요.
+
+---
+
+## 개별 정책 비활성화
+
+설정의 `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,48 @@
+---
+title: 정책 설치
+description: "에이전트의 모든 도구 호출 시 정책이 실행되도록 활성화"
+---
+
+```bash
+failproofai policies --install [policy-names...] [options]
+```
+
+failproofai가 도구 호출을 가로챌 수 있도록 Claude Code의 `settings.json`에 훅 항목을 작성합니다.
+
+별칭: `failproofai p -i`
+
+## 옵션
+
+| 플래그 | 설명 |
+|--------|------|
+| `--scope user` | `~/.claude/settings.json`에 설치 (기본값 - 모든 세션) |
+| `--scope project` | 현재 디렉터리의 `.claude/settings.json`에 설치 |
+| `--scope local` | 현재 디렉터리의 `.claude/settings.local.json`에 설치 |
+| `--custom <path>` / `-c` | 커스텀 훅 정책이 포함된 JS 파일 경로 |
+| `--beta` | 베타 정책 포함 |
+
+## 동작 방식
+
+- **정책 이름 미지정** - 정책을 선택할 수 있는 인터랙티브 프롬프트를 표시
+- **특정 이름 지정** - 해당 정책을 활성화 (이미 활성화된 정책에 추가됨)
+- **`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`에 저장됩니다.