failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/ko/cli/audit.mdx

@@ -0,0 +1,131 @@
+---
+title: 과거 세션 감사 (베타)
+description: "과거 트랜스크립트에서 에이전트가 낭비적이거나 위험한 작업을 수행한 빈도 분석"
+---
+
+<Note>
+  **베타 기능.** 초기 피드백을 수집하는 동안 감사 기능은 베타로 제공됩니다.
+  디텍터 카탈로그와 리포트 형식은 다음 안정 버전 출시 전에 변경될 수 있습니다.
+  이상한 점이 있으면 이슈를 열어 주세요.
+</Note>
+
+감사 기능은 과거 에이전트 CLI 트랜스크립트를 failproofai의 정책 엔진으로 재실행하고,
+**`/audit` 대시보드 페이지**에 공유 가능한 시각적 리포트를 렌더링합니다 —
+에이전트의 아키타입, 0~100 점수, 그리고 어떤 정책이 무엇을 포착했을지 정확히 보여줍니다.
+
+## 실행 방법
+
+세 가지 방법 모두 동일한 `/audit` 리포트로 이동합니다.
+
+<CodeGroup>
+
+```bash npx (설치 불필요)
+npx -y failproofai audit
+```
+
+```bash failproofai audit
+failproofai audit
+```
+
+```bash failproofai (대시보드)
+failproofai
+```
+
+</CodeGroup>
+
+<CardGroup cols={3}>
+  <Card title="설치 불필요" icon="bolt">
+    `npx -y failproofai audit`은 failproofai를 가져와 스캔을 실행하고
+    대시보드를 자동으로 열어줍니다 — 사전 설치가 필요 없습니다.
+  </Card>
+  <Card title="CLI에서 실행" icon="terminal">
+    `failproofai audit`은 터미널에서 스캔을 실행한 후,
+    완료되면 `localhost:8020/audit`을 자동으로 엽니다.
+  </Card>
+  <Card title="대시보드에서 실행" icon="gauge">
+    `failproofai`를 실행하고 내비게이션 바의 **Audit**을 클릭하거나(Policies와
+    Projects 사이에 위치), `/audit`을 직접 열면 됩니다.
+  </Card>
+</CardGroup>
+
+<Tip>
+  `failproofai audit -h` (또는 `--help`)를 실행하면 사용법을 확인할 수 있습니다.
+  감사는 **완전 오프라인**으로 실행되며 — 계정이나 네트워크가 필요 없습니다 —
+  `Ctrl+C`로 중단할 때까지 대시보드가 계속 서비스됩니다.
+</Tip>
+
+대시보드는 이 기기의 과거 에이전트 CLI 트랜스크립트(Claude Code, Codex, Copilot, Cursor, OpenCode, Pi)를 스캔하고, 에이전트가 failproofai가 차단하도록 설계된 동작을 얼마나 자주 했는지 리포트합니다 — 환경 변수 체크, 강제 푸시, 불필요한 `cd <cwd>` 접두사, sleep 폴링 루프, 방금 편집한 파일 재읽기 등.
+
+각 트랜스크립트에서 모든 도구 사용 이벤트는 39개의 내장 정책과 런타임 정책으로는 아직 커버되지 않는 패턴을 감지하는 8개의 감사 전용 디텍터를 통해 재실행됩니다. 모든 세션에서 정책/디텍터별 카운트가 집계됩니다.
+
+## 결과물
+
+`/audit` 페이지는 단일 화면의 공유 가능한 **포스터**와 그 아래 네 개의 섹션으로 구성됩니다:
+
+1. **포스터** — 에이전트의 정체성을 한눈에: **아키타입** (8가지 중 하나 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), 페르소나 키워드, 해당 아키타입의 희귀도, 티어 밴드(`S`부터 `bottom tier`)가 포함된 **0~100 점수**. 공유용으로 설계 — X나 LinkedIn에 게시하거나 PNG로 다운로드할 수 있습니다.
+2. **`// strengths`** — 에이전트가 이미 잘 하는 것들을 스캔의 실제 수치로 표시 (예: 클린 도구 호출 비율, `0`번의 main 브랜치 푸시 시도). 관련 정책이 깨끗한 기록을 가진 경우에만 표시됩니다.
+3. **`// quirks`** — 놓친 것들: failproofai가 포착했을 동작의 순위표 — *마지막 발생 시점*, *무엇이 놓쳤는지* (차단했을 내장 정책 포함), *심각도*, 그리고 얼마나 자주 *발생했는지* (`new` / `recurring` / `N× seen`).
+4. **`// how to improve`** — 권장 수정 목록: 복사 붙여넣기 가능한 `failproofai policy add <slug>`가 포함된 정책별 행, 모든 권장 사항을 한 번에 활성화하는 **install all** 버튼과 적용 시의 **예상 점수** 표시.
+5. **`// come back better`** — 습관 형성: 재감사 이메일 **리마인더** 설정 (`3d` / `7d` / `14d` / `30d`) 또는 지금 재감사 실행, **친구 초대**를 통한 자체 감사 실행 (failproof.ai에서 발송, 참조로 사용자 포함). 리마인더와 초대는 로그인이 필요합니다.
+
+## 예약 감사
+
+**failproofaid 데몬**을 실행 중이라면 ([`failproofai config`](/ko/cli/install-policies) 참조),
+일정에 따라 감사를 자동으로 재실행하고 백그라운드에서 `/audit` 리포트를 갱신할 수 있습니다.
+기본적으로 **비활성화**되어 있습니다. 이 기기의 모든 에이전트 세션 트랜스크립트 *내용*을
+읽기 때문에 — 명시적으로 요청하기 전까지는 타이머로 스캔이 실행되지 않습니다.
+
+`~/.failproofai/config.toml`에서 활성화하세요:
+
+```toml
+[audit]
+auto = true
+interval_days = 7
+```
+
+| 키 | 의미 |
+|---|---|
+| `auto` | `true`로 설정하면 예약 스캔이 활성화됩니다. 그 외 — 없음, `false`, `"yes"` — 는 비활성화입니다. |
+| `interval_days` | 스캔 간격(일). 1~90으로 제한되며, `0`, 음수, 숫자가 아닌 값은 `7`로 대체됩니다. |
+
+- 일정은 **실제 시계** 기준이므로 절전 및 재부팅 후에도 유지됩니다: 예정 시간을 지나
+  절전 상태였던 노트북은 깨어난 후 **한 번만** 실행되며, 밀린 작업을 누적하지 않습니다.
+- 각 실행은 별도의 낮은 우선순위(`nice 19`) 프로세스로 실행됩니다 — 도구 호출 응답을
+  위해 항상 여유 있는 데몬의 훅 경로에는 영향을 주지 않습니다.
+- `failproofai audit` 또는 대시보드의 재실행이 이미 진행 중인 경우 스캔을 건너뛰며,
+  실패로 처리하는 대신 잠시 후 재시도합니다.
+- 진행 상황은 `~/.failproofai/state/audit-schedule.json`에 기록됩니다 (마지막 실행,
+  다음 예정). 해당 파일은 데몬이 관리하며 — 주기는 `config.toml`에서 변경하세요.
+
+<Note>
+이전 버전의 failproofai로 설정된 기기에서 이 기능을 활성화했다면,
+`failproofai config`를 한 번 실행하세요. CLI를 시작하기 전에 데몬의 서비스 정의에
+추가 항목이 하나 필요하며, 해당 명령 실행 시 갱신됩니다.
+</Note>
+
+## 감사 전용 디텍터
+
+런타임에 아직 적용되지 않는 "불합리한 동작" 패턴을 감지합니다. 감사 중에만 실행되며
+라이브 도구 호출을 절대 차단하지 않습니다.
+
+| 디텍터 | 감지 내용 |
+|---|---|
+| `redundant-cd-cwd` | 명령이 이미 `cwd`에서 실행되는데도 `cd <cwd> && …`로 시작하는 Bash 명령. |
+| `prefer-edit-over-read-cat` | 단일 소스 파일에 대한 `cat`/`head`/`tail`/`less`/`more` — `Read` 도구를 사용하세요. |
+| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` 인플레이스 편집 — `Edit` 도구를 사용하세요. |
+| `prefer-write-over-heredoc` | Heredoc / 멀티라인 `echo > file` 파일 쓰기 — `Write` 도구를 사용하세요. |
+| `sleep-polling-loop` | 긴 `sleep N` (≥ 30초) 또는 `while …; sleep …; done` 폴링 루프. |
+| `find-from-root` | `find /`, `find /home`, `find /usr` 등 — `cwd`로 범위를 제한하세요. |
+| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, 훅 건너뜀. |
+| `reread-after-edit` | 같은 세션에서 `Edit`/`Write`된 직후 파일을 `Read`하는 경우. |
+
+## 캐시
+
+- **트랜스크립트별 캐시**: `(mtime, size, engineVersion, detectorVersion)`을 키로 하는 `~/.failproofai/cache/audit/<sha1>.json` — 트랜스크립트나 정책/디텍터 코드가 변경되면 자동으로 무효화됩니다. 각 항목에는 **TTL 메타데이터**로 `cachedAt` 타임스탬프가 저장됩니다 (캐시 키의 일부는 아님). **7일**이 지난 항목은 읽을 때 거부되어 오래된 결과가 변화하는 디텍터 의도를 초과하지 않도록 합니다.
+- **전체 결과 캐시**: `~/.failproofai/audit-dashboard.json` (모드 0600). 재실행 없이 대시보드가 탐색 시 즉시 렌더링될 수 있도록 합니다. **7일 TTL**이 지나면 읽기 시 거부되며 — `/audit`은 빈 상태로 돌아가 새 실행을 요청합니다. 리포트 하단의 `[ re-audit now ]`를 클릭하면 갱신됩니다 — 재감사는 `noCache: true`를 전송하므로 트랜스크립트별 캐시를 우회하고 캐시된 결과 대신 모든 트랜스크립트를 재스캔합니다. 실행 중 진행 상황은 상단의 고정 스트립으로 스트리밍되며 성공 시 결과가 제자리에서 교체됩니다 (페이지 새로고침 없음; 재감사 실패 시 이전 리포트 유지).
+
+## 참고 사항
+
+- **변경 없음.** 감사는 읽기 전용 모드로 재실행됩니다. `warn-repeated-tool-calls`는 세션별 사이드카가 수정될 수 있으므로 건너뜁니다.
+- **워크플로 정책 건너뜀.** `require-*-before-stop` 정책은 `Stop` 이벤트에서만 실행되고 라이브 git 상태에 대해 `execSync`를 호출합니다 — "2025년에 어떤 일이 일어났을까"에 대한 의미 있는 해석이 없으므로 감사 카운트에 나타나지 않습니다.
+- **커스텀 정책 건너뜀.** 사용자가 제공한 커스텀 훅은 재실행되지 않습니다 (원래 세션 이후 변경되었을 수 있기 때문입니다).

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

@@ -0,0 +1,29 @@
+---
+title: 세션 보기
+description: "대시보드를 실행하여 에이전트 세션을 탐색하고 정책을 관리합니다"
+---
+
+```bash
+failproofai
+```
+
+`http://localhost:8020`에서 웹 대시보드를 시작합니다.
+
+## 옵션
+
+| 플래그 | 설명 |
+|--------|------|
+| `--port <number>` | 수신할 포트 (기본값: `8020`) |
+| `--allowed-origins <origins>` | 개발 리소스에 접근할 수 있는 쉼표로 구분된 호스트/IP 목록 |
+
+기본값이 아닌 Claude 프로젝트 폴더를 대시보드에 지정하려면, 실행 시 `CLAUDE_PROJECTS_PATH` 환경 변수를 설정하세요.
+
+## 예시
+
+```bash
+# Launch on a different port
+failproofai --port 9000
+
+# Use a custom Claude projects path via environment variable
+CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai
+```

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

@@ -0,0 +1,66 @@
+---
+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는 기본적으로 익명 사용 텔레메트리를 전송합니다. 비활성화하는 방법은
+두 가지가 있으며, 더 제한적인 설정이 우선 적용됩니다. 즉, 환경 변수로는 설정
+파일에서 비활성화한 기능을 다시 활성화할 수 없습니다.
+
+| 변수 | 설명 |
+|----------|-------------|
+| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 현재 프로세스에서 익명 사용 텔레메트리 비활성화 |
+
+머신에서 영구적으로 비활성화하려면 `~/.failproofai/config.toml`에 다음을 추가하세요:
+
+```toml
+[telemetry]
+enabled = false
+```
+
+<Note>
+**failproofaid 데몬**을 실행 중이라면 설정 파일 방식을 사용해야 합니다.
+데몬은 시스템 범위 서비스이며, 셸에서 내보낸 환경 변수를 포함하지 않으므로
+`FAILPROOFAI_TELEMETRY_DISABLED`가 데몬에 전달되지 않습니다. `[telemetry] enabled = false`는 CLI와 데몬 모두에서 읽힙니다.
+</Note>
+
+데몬은 자체적인 **라이프사이클** 이벤트만 보고합니다. 시작 여부(이전 실행이 정상 종료되었는지 포함), 중지, 평가 워커의 생성 또는 재시작, 수집기 작업 실패, 클라우드 정책 가져오기 결과 등입니다. 이 데이터는 낮은 카디널리티 값과 카운트만 포함하며, 파일 경로, 명령어, 정책, 프롬프트, 또는 트랜스크립트에서 읽은 내용은 절대 포함되지 않습니다. 도구 호출별 이벤트는 존재하지 않습니다.
+
+## 인증
+
+| 변수 | 설명 |
+|----------|-------------|
+| `FAILPROOF_API_URL` | 대시보드 인증 다이얼로그에서 사용하는 API 서버 기본 URL 재정의. 기본값은 `https://api.befailproof.ai`이며, 로컬 API 서버 실행 시 `http://localhost:8080`(또는 해당 주소)으로 설정. |
+| `FAILPROOFAI_AUTH_DIR` | `auth.json` 저장 위치 재정의 (기본값: `~/.failproofai`). 주로 격리된 테스트 환경에서 유용. |
+
+## 최초 실행 프롬프트
+
+| 변수 | 설명 |
+|----------|-------------|
+| `FAILPROOFAI_NO_FIRST_RUN=1` | `failproofai`를 처음 단독 실행할 때 정책 설치를 제안하는 프롬프트 건너뛰기 |
+
+## 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-old/ko/cli/hook.mdx

@@ -0,0 +1,30 @@
+---
+title: Hook handler (내부)
+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-old/ko/cli/install-policies.mdx

@@ -0,0 +1,57 @@
+---
+title: 정책 설치
+description: "에이전트의 모든 도구 호출에서 정책이 실행되도록 활성화합니다"
+---
+
+```bash
+failproofai policies --install [policy-names...] [options]
+```
+
+설치된 에이전트 CLI(Claude Code, OpenAI Codex, 또는 GitHub Copilot CLI _(베타)_)의 설정 파일에 훅 항목을 작성하여 failproofai가 도구 호출을 가로챌 수 있도록 합니다.
+
+별칭: `failproofai p -i`
+
+## 옵션
+
+| 플래그 | 설명 |
+|------|-------------|
+| `--cli claude\|codex\|copilot` | 설치할 에이전트 CLI; 공백으로 구분(예: `--cli claude codex copilot`)하거나 반복 사용 가능. 생략하면 설치된 CLI를 자동으로 감지하고 선택 프롬프트를 표시합니다. |
+| `--scope user` | 사용자 범위 설정 파일에 설치합니다(Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). 기본값. |
+| `--scope project` | 프로젝트 범위 설정 파일에 설치합니다(Claude: `<cwd>/.claude/settings.json`; Codex: `<cwd>/.codex/hooks.json`; Copilot: `<cwd>/.github/hooks/failproofai.json`). |
+| `--scope local` | Claude 전용 — `<cwd>/.claude/settings.local.json`에 설치합니다. Codex와 Copilot은 `local` 범위를 지원하지 않습니다. |
+| `--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
+
+# OpenAI Codex에 설치 (프로젝트 범위)
+failproofai policies --install --cli codex --scope project
+
+# 현재 프로젝트에 GitHub Copilot CLI (베타) 설치
+failproofai policies --install --cli copilot --scope project
+
+# 세 가지 CLI 모두에 한 번에 설치
+failproofai policies --install --cli claude codex copilot
+```
+
+`--custom <path>`가 지정된 경우, 파일이 즉시 유효성 검사를 거칩니다 — `customPolicies.add()`를 최소 한 번 이상 호출해야 합니다. 확인된 경로는 `customPoliciesPath`로 `policies-config.json`에 저장됩니다.

package/.next/standalone/docs-old/ko/cli/list-policies.mdx

@@ -0,0 +1,31 @@
+---
+title: 정책 목록 보기
+description: "활성화된 정책, 매개변수, 커스텀 정책 확인하기"
+---
+
+```bash
+failproofai policies
+```
+
+모든 정책의 상태, 구성된 매개변수, 커스텀 정책을 표시합니다.
+
+## 출력 예시
+
+```text
+Failproof AI Hook Policies (user)
+
+  Status  Name                          Description
+  ──────  ──────────────────────────────────────────────────────────────
+  ✓       block-sudo                    Block sudo commands
+            allowPatterns: ["sudo systemctl status"]
+  ✓       block-rm-rf                   Block recursive deletions
+  ✗       block-curl-pipe-sh            Block curl|bash patterns
+  ✓       sanitize-api-keys             Redact API keys from output
+            additionalPatterns: [{ regex: "MY_TOKEN_...", label: "..." }]
+
+  ── Custom Policies (/home/alice/myproject/my-policies.js) ──────────────
+  ✓       require-jira-ticket           Block commits without ticket
+  ✓       approval-gate                 Approval gate for destructive ops
+```
+
+`policyParams`에 알 수 없는 키가 있으면 이 목록에 표시되므로 오타를 조기에 발견할 수 있습니다.

package/.next/standalone/docs-old/ko/cli/migrate.mdx

@@ -0,0 +1,86 @@
+---
+title: 홈 디렉토리 마이그레이션
+description: "~/.failproofai를 현재 버전의 레이아웃에 맞게 업데이트하고, 실행 전 변경 사항을 미리 확인하세요"
+---
+
+```bash
+failproofai migrate --dry-run   # 계획만 출력하고 아무것도 변경하지 않음
+failproofai migrate             # 실제 실행
+```
+
+대부분의 경우 이 명령을 직접 입력할 필요는 없습니다. 업그레이드 후 처음 명령을 실행할 때 자동으로 실행되며, [`failproofai update`](/ko/cli/update)에도 포함되어 있습니다. 실행 전에 계획을 확인하거나 마이그레이션만 단독으로 실행하고 싶을 때 직접 사용하세요.
+
+## 버전이 아닌 레이아웃 기준
+
+`~/.failproofai/VERSION`에는 **레이아웃** 번호가 기록됩니다. 이는 릴리스 버전이 아니라 디렉토리 구조를 나타냅니다. 마이그레이션은 이 번호를 기준으로 동작하므로, 버전을 크게 건너뛰어도 부담이 없습니다.
+
+- npm 버전은 릴리스마다 바뀌며, 두 레이아웃 사이에 수십 개의 릴리스가 있을 수 있습니다.
+- 따라서 **레이아웃 변경 없이** 서른 번의 릴리스를 건너뛴 머신은 마이그레이션을 **한 번도 실행하지 않습니다**. 불필요한 no-op 서른 번이 발생하지 않습니다.
+- 여러 레이아웃을 한 번에 건너뛰는 경우, 각 단계가 순서대로 실행되며 각 단계는 자신의 시작과 끝만 알고 있습니다.
+
+이는 npm이 설치된 패키지를 자체적으로 업데이트할 수 없기 때문에 중요합니다. 한 버전에 수개월간 머물다가 여러 레이아웃을 한 번에 건너뛰는 상황은 예외적인 케이스가 아니라 일반적인 경우입니다.
+
+## Dry run
+
+`--dry-run`은 실행될 체인과 먼저 저장될 파일들을 정확하게 출력하며, 마이그레이션, 백업, 기록 항목 등 아무것도 변경하지 않습니다.
+
+```
+Layout 2 on disk; this build speaks 3.
+1 step(s) would run:
+  2 → 3  layout 2 → 3: carry config.toml and credentials.toml into JSON, move
+         custom-policies/ back up into policies/, nest the policy config at the root
+
+These would be copied to ~/.failproofai/migrations/backup-layout2 first:
+  VERSION
+  config.toml
+  credentials.toml
+```
+
+## 보존되는 항목과 재생성되는 항목
+
+홈 디렉토리의 모든 경로는 보유하는 데이터의 종류를 나타내며, 이에 따라 마이그레이션 시 삭제 여부가 결정됩니다. 규칙은 다음과 같습니다. **파생되거나 다시 가져올 수 있는 데이터는 삭제될 수 있으며, 사용자가 직접 입력한 데이터, 아직 전달되지 않은 데이터, 머신을 식별하는 데이터는 보존됩니다.**
+
+| 보존 | 재생성 또는 재취득 |
+|---|---|
+| `config.json` — 설정, `daemon.configured`, 추가 캡처 경로 | 감사 캐시 |
+| `credentials.json` — 클라우드 등록 정보 | 클라우드 관리 배포 (다음 폴링 시 재취득 및 다이제스트 검증) |
+| `policies-config.json` — 정책 선택 및 파라미터 | 데몬 임시 상태 |
+| `policies/` — 사용자 정의 정책 파일 및 임포트된 헬퍼 파일 | |
+| `hook-activity/` — 대시보드에서 읽는 결정 로그 | |
+| 업로드 대기 중인 미전달 이벤트 | |
+| `cursors/` — 콜렉터 워터마크 | |
+| `bin/`의 데몬 바이너리 | |
+
+<Note>
+  미전달 이벤트는 삭제하면 복구가 불가능하기 때문에 보존됩니다. 단순히 느린 것이 아니라 영구적인 손실이 됩니다. 콜렉터의 워터마크가 이미 스풀에 있는 항목보다 앞으로 진행되었기 때문에, 해당 트랜스크립트 범위를 다시 읽을 수 없게 됩니다. 마이그레이션은 완료 즉시 데몬에게 스풀에 있는 내용을 전달하도록 요청하므로, 일반적으로 보존할 항목이 남아 있지 않습니다.
+</Note>
+
+*최신* 버전이 `config.json`, `credentials.json`, `policies-config.json`에 기록한 키도 이전 버전 리더에 의해 삭제되지 않고 보존됩니다.
+
+## 남겨지는 기록
+
+```
+~/.failproofai/migrations/
+  applied.json                 단계별 항목: 레이아웃, CLI, 타임스탬프, 소요 시간, 결과
+  backup-layout<n>/            첫 번째 단계 실행 전에 복사된 중요 파일들
+```
+
+`applied.json`은 업그레이드 후 문제가 발생했을 때 가장 먼저 확인해야 할 질문인 "이 머신이 실제로 어떤 과정을 거쳤는가"에 대한 답을 제공합니다. 버그 리포트에 첨부하세요.
+
+백업은 전체 디렉토리 복사본이 아닌 의도적으로 작은 크기로 유지됩니다. 마이그레이션은 설계상 더 이상 복구 불가능한 항목을 삭제하지 않으므로, 보험이 필요한 경우는 *단계의 결함*뿐이며, 이 몇 가지 파일이 그러한 결함의 영향을 받는 부분입니다.
+
+## 단계 실패 시
+
+해당 지점에서 체인이 중지됩니다. `VERSION`은 완료된 단계에 의해서만 스탬프가 찍히므로, 홈 디렉토리는 이전 레이아웃으로 표시된 채 유지되고 다음 명령 실행 시 재시도됩니다. 불완전한 마이그레이션으로 인해 홈 디렉토리가 현재 상태로 표시되는 일은 없습니다. 해당 단계는 `applied.json`에 `"ok": false`로 기록되며, 백업은 생성된 위치에 그대로 유지됩니다.
+
+## 더 최신 홈 디렉토리는 마이그레이션되지 않고 거부됩니다
+
+`~/.failproofai/`가 현재 실행 중인 failproofai보다 **더 최신** 버전에 의해 작성된 경우, 명령이 중지되고 업그레이드를 권장합니다. 해당 데이터는 정상이며 최신 CLI로 읽을 수 있습니다. 데이터를 "앞으로" 마이그레이션하는 개념 자체가 존재하지 않으며, 초기화하면 복구 가능한 데이터가 손실됩니다.
+
+```
+This machine's failproofai directory was written by a newer version (layout 4;
+this build speaks 3). Upgrade rather than migrate:
+  npm install -g failproofai@latest
+```
+
+데몬도 동일한 규칙을 적용합니다. `failproofaid`는 이해하지 못하는 레이아웃에 대해 시작을 거부하며, 이동된 경로를 읽고 쓰려 하지 않습니다.

package/.next/standalone/docs-old/ko/cli/remove-policies.mdx

@@ -0,0 +1,43 @@
+---
+title: 정책 제거
+description: "Claude Code의 설정에서 훅 항목 제거"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+Claude Code의 `settings.json`에서 failproofai 훅 항목을 제거합니다.
+
+별칭: `failproofai p -u`
+
+## 옵션
+
+| 플래그 | 설명 |
+|------|-------------|
+| `--scope user` | 전역 설정에서 제거 (기본값) |
+| `--scope project` | 프로젝트 설정에서 제거 |
+| `--scope local` | 로컬 설정에서 제거 |
+| `--scope all` | 모든 범위에서 한 번에 제거 |
+| `--custom` / `-c` | 설정에서 `customPoliciesPath` 초기화 |
+
+## 동작 방식
+
+- **정책 이름 미지정** - 설정 파일에서 모든 failproofai 훅 항목을 제거합니다
+- **특정 이름 지정** - 해당 정책을 비활성화하되 훅은 설치된 상태로 유지합니다
+
+## 예시
+
+```bash
+# 전역에서 모든 훅 제거
+failproofai policies --uninstall
+
+# 특정 정책 비활성화 (훅은 설치 상태 유지)
+failproofai policies --uninstall block-sudo
+
+# 모든 범위에서 훅 제거
+failproofai policies --uninstall --scope all
+
+# 커스텀 정책 경로 초기화
+failproofai policies --uninstall --custom
+```

package/.next/standalone/docs-old/ko/cli/update.mdx

@@ -0,0 +1,64 @@
+---
+title: 업그레이드 후 업데이트
+description: "npm이 처리할 수 없는 업그레이드의 나머지 절반: 홈 디렉터리 마이그레이션 및 데몬 동기화"
+---
+
+```bash
+npm install -g failproofai@latest && failproofai update
+```
+
+전체 업그레이드 과정은 이것이 전부입니다. `npm`은 CLI를 교체하고, `failproofai update`가 나머지를 처리합니다.
+
+## 두 번째 명령이 필요한 이유
+
+`npm install -g`는 단 하나, CLI만 교체합니다. failproofai 설치의 다른 두 구성 요소는 의도적으로 패키지 외부에 존재하며, npm 실행 시 어느 것도 이동하지 않습니다:
+
+- **`~/.failproofai/`**: 설정, 클라우드 등록, 정책 선택 및 기록이 저장됩니다. 새 버전은 이를 다르게 구성할 수 있으며, 재구성은 두 가지 구조를 모두 아는 코드가 처리해야 합니다.
+- **`failproofaid` 데몬 바이너리**: `~/.failproofai/bin/failproofaid-<version>` 경로에 위치합니다. 이는 의도적으로 `node_modules` 내부에 *두지 않습니다*. 실행 중인 서비스 아래의 파일을 교체하는 업그레이드는 라이브 데몬을 다른 소스에서 빌드된 바이너리로 연결하게 되고, 패키지를 제거하면 서비스가 부팅마다 크래시 루프에 빠지게 됩니다.
+
+따라서 `npm install -g`만 실행하면 CLI는 새로운 버전이지만 데몬은 그렇지 않습니다. `failproofaid`는 자신이 인식하지 못하는 홈 디렉터리 레이아웃에 대해 시작을 거부합니다. 이는 불일치를 조용히 넘기지 않고 명시적으로 알리는 방식입니다. 두 부분을 함께 맞추는 것이 바로 `failproofai update`의 역할입니다.
+
+## 수행 내용
+
+<Steps>
+  <Step title="대기 중인 레이아웃 마이그레이션 실행">
+    `~/.failproofai/VERSION`에 기록된 레이아웃을 읽고, 현재 버전이 사용하는 레이아웃으로 전환하는 단계를 실행합니다. 대부분의 경우 아무 작업도 필요하지 않습니다 — [`failproofai migrate`](/ko/cli/migrate)를 참조하세요.
+  </Step>
+  <Step title="일치하는 데몬 바이너리 배치">
+    npm이 이미 다운로드한 플랫폼 패키지에서 가능한 경우 네트워크 없이 처리하며, 그렇지 않은 경우 정확한 버전의 릴리스 에셋에서 가져옵니다. 사용 전에 SHA-256로 검증됩니다.
+  </Step>
+  <Step title="서비스 재시작 및 복구 확인">
+    가정이 아닌 실제 프로브를 통해 확인합니다. 서비스 관리자는 프로세스가 포크되는 즉시 활성 상태로 보고하지만, 이는 실제로 동작하는 것과 다릅니다.
+  </Step>
+</Steps>
+
+## 옵션
+
+| 플래그 | 효과 |
+|--------|------|
+| `--no-daemon` | 홈 디렉터리만 마이그레이션하고 데몬은 현재 버전으로 유지합니다. |
+
+<Warning>
+  `--no-daemon`을 사용하면 버전이 맞지 않는 데몬이 그대로 남습니다. 데몬을 필요로 하도록 설정된 머신에서는 데몬이 응답하지 못하면 모든 훅 이벤트가 **차단(fails closed)** 됩니다. 마이그레이션된 홈에 대해 시작을 거부하는 데몬은 응답할 수 없습니다. 데몬 절반도 함께 실행하는 것을 권장합니다.
+</Warning>
+
+## 문제가 발생한 경우
+
+명령이 0이 아닌 종료 코드로 종료되며 어느 절반이 실패했는지 알려줍니다. 알아두어야 할 두 가지 경우:
+
+- **마이그레이션 단계가 완료되지 않은 경우.** 홈 디렉터리는 *이전* 레이아웃으로 표시된 채 남으므로, 다음 명령 실행 시 재시도합니다. 부분 마이그레이션이 성공한 것처럼 홈이 현재 버전으로 표시되는 일은 절대 없습니다. 설정 및 등록 정보의 복사본이 실행 전에 `~/.failproofai/migrations/backup-layout<n>/`에 저장됩니다.
+- **비밀번호 없이 데몬을 재시작할 수 없는 경우.** `sudo -n`이 의도적으로 사용되므로, 진행 표시 중에는 어떤 프롬프트도 나타나지 않습니다. 명령은 직접 실행해야 할 정확한 명령줄을 출력합니다.
+
+<Note>
+  이 과정에서 대화형 설정 마법사는 필요하지 않습니다. 설정, 클라우드 등록 및 정책 선택은 업그레이드 후에도 유지되므로, 마이그레이션된 머신은 이전과 동일하게 정책을 적용합니다. 이는 CI 러너, 플릿 서버, 헤드리스 게이트웨이처럼 아무도 앉아 있지 않는 머신에서 특히 중요합니다.
+</Note>
+
+## 자동화
+
+`failproofai update`는 비대화형이며, 아무것도 할 일이 없을 때 실행해도 안전합니다. "no migration was needed"를 출력하고 0으로 종료합니다. 프로비저닝 스크립트나 Dockerfile에서 매 업그레이드 후 실행하는 것이 권장 사용법입니다:
+
+```dockerfile
+RUN npm install -g failproofai@latest && failproofai update --no-daemon
+```
+
+(이미지 빌드에서는 `--no-daemon`을 사용합니다. 아직 재시작할 서비스가 없기 때문입니다.)

package/.next/standalone/docs-old/ko/cli/version.mdx

@@ -0,0 +1,12 @@
+---
+title: 버전 확인
+description: "설치된 failproofai 버전 출력"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+설치된 버전 번호를 출력합니다.