failproofai 1.0.1-beta.1 → 1.0.1

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

@@ -0,0 +1,151 @@
+---
+title: 대시보드
+description: "에이전트 세션 모니터링, 도구 호출 검토, 정책 관리"
+icon: chart-line
+---
+
+failproofai 대시보드는 AI 에이전트 세션을 모니터링하고 정책을 관리하는 로컬 웹 애플리케이션입니다. 자리를 비운 동안 에이전트가 무엇을 했는지 확인하세요.
+
+---
+
+## 대시보드 시작하기
+
+```bash
+failproofai
+```
+
+`http://localhost:8020`에서 열립니다.
+
+대시보드는 로컬 프로젝트, 세션, failproofai 설정 데이터를 파일시스템에서 직접 읽어옵니다. 감사 알림 및 초대와 같은 선택적 인증 기능은 해당 요청에 필요한 정보(이메일 주소 포함)를 원격 API로 전송합니다.
+
+---
+
+## 페이지
+
+### 프로젝트
+
+머신에서 발견된 Claude Code, OpenAI Codex, GitHub Copilot CLI _(베타)_, Cursor Agent _(베타)_, OpenCode _(베타)_, Pi _(베타)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, Goose 프로젝트를 모두 나열합니다. Claude 프로젝트는 `~/.claude/projects/`(또는 `CLAUDE_PROJECTS_PATH`로 설정된 경로)에서 검색됩니다. Codex 프로젝트는 `~/.codex/sessions/<YYYY>/<MM>/<DD>/*.jsonl` 아래의 모든 트랜스크립트를 스캔하고 각 세션의 첫 번째 레코드에 기록된 `cwd`로 그룹화하여 검색됩니다. Copilot CLI 프로젝트는 각 `~/.copilot/session-state/<sessionId>/workspace.yaml`(`COPILOT_HOME`으로 설정 가능)을 스캔하고 `cwd` 필드로 그룹화하여 검색됩니다. Cursor Agent 프로젝트는 `~/.cursor/agent-sessions/<sessionId>/`(`CURSOR_HOME`으로 설정 가능, `conversations/`와 `sessions/`를 대체 경로로 탐색) 아래의 세션별 메타데이터를 스캔하여 `meta.json` / `session.json` / `workspace.yaml`의 `cwd` 스칼라 값으로 검색됩니다. OpenCode 프로젝트는 `~/.local/share/opencode/opencode.db`의 SQLite DB를 `opencode db --format json`으로 쿼리하여 검색됩니다(`session` 및 `project` 테이블을 읽고 `project_id`로 그룹화). Pi 프로젝트는 `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`(`PI_SESSIONS_DIR`으로 설정 가능) 아래의 세션별 JSONL 트랜스크립트를 스캔하고 각 세션의 첫 번째 레코드에서 `cwd`를 가져와 검색됩니다. Hermes 게이트웨이 세션은 모든 프로필의 SQLite 스토어(~/.hermes/state.db와 `~/.hermes/profiles/<name>/state.db`, `HERMES_HOME` 또는 단일 데이터베이스의 경우 `HERMES_DB_PATH`로 재정의 가능)에서 직접 읽혀 프로필과 `source`(Slack/Telegram/cli/cron — 게이트웨이 세션에는 cwd가 없음)로 `hermes-<profile>-<source>` 프로젝트에 그룹화됩니다. OpenClaw 게이트웨이 세션은 `~/.openclaw/agents/<agentId>/sessions/*.jsonl`에서 읽혀 에이전트와 채널로 `openclaw-<agentId>-<channel>` 프로젝트에 그룹화됩니다(역시 cwd 없음). Factory Droid 프로젝트는 `~/.factory/sessions/<encoded-cwd>/*.jsonl`의 JSONL 트랜스크립트에서 cwd로 그룹화하여 검색됩니다. Devin 프로젝트는 `~/.local/share/devin/cli/sessions.db`의 SQLite DB에서(각 세션의 `working_directory`로 그룹화), Antigravity 프로젝트는 `~/.gemini/antigravity-cli/brain/<conversationId>/…/transcript_full.jsonl`의 JSONL 트랜스크립트에서 cwd로 그룹화하여, Goose 프로젝트는 `~/.local/share/goose/sessions/sessions.db`의 SQLite DB에서(각 세션의 `working_dir`로 그룹화) 검색됩니다. 여러 CLI에서 사용된 프로젝트는 해당하는 모든 배지가 표시된 단일 행으로 렌더링됩니다. 테이블 위의 **CLI** 드롭다운을 사용하여 특정 에이전트 CLI로 필터링할 수 있으며, URL은 선택 항목을 `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` 형식으로 보존합니다.
+
+Hermes와 OpenClaw는 사용자 범위이며 그룹화할 작업 디렉터리가 없으므로 **접을 수 있는 폴더 트리**로 렌더링됩니다(프로필 또는 에이전트가 최상위 레벨, 그 아래에 채널). cwd 기반 CLI는 모두 플랫 행으로 유지됩니다. 폴더 행은 하위 항목의 세션 수와 가장 최근 활동을 집계하고, 접힌 폴더 상태는 방문 간에 기억되며, 키워드 검색은 일치하는 항목을 자동으로 펼칩니다.
+
+각 프로젝트에는 다음이 표시됩니다:
+- 프로젝트 이름 (폴더 경로에서 파생)
+- CLI 배지 — `Claude Code`(주황), `OpenAI Codex`(보라), `GitHub Copilot`(파랑), `Cursor Agent`(에메랄드), `OpenCode`(앰버), `Pi`(분홍), `Hermes`(인디고) 중 하나 이상
+- 가장 최근 세션 활동 날짜
+
+프로젝트를 클릭하면 해당 세션을 볼 수 있습니다.
+
+### 세션
+
+프로젝트 내 모든 세션을 나열합니다. 각 세션에는 다음이 표시됩니다:
+- 세션 ID
+- 시작 및 종료 타임스탬프
+- 도구 호출 횟수
+- 훅 활동 횟수 (실행된 정책)
+
+날짜 범위 필터와 세션 ID 검색을 사용하여 목록을 좁힐 수 있습니다. 세션은 페이지네이션됩니다.
+
+세션을 클릭하면 세션 뷰어가 열립니다.
+
+### 세션 뷰어
+
+세션 뷰어는 자율 에이전트에 대한 핵심 질문에 답합니다: 에이전트가 무엇을 했으며, 올바른 방향을 유지했는가? 헤더 옆의 CLI 배지는 해당 세션이 Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, Goose 트랜스크립트 중 어느 것인지 나타냅니다. 세션에서 발생한 모든 것의 타임라인이 표시됩니다:
+
+- **메시지** - Claude의 텍스트 응답과 사용자 프롬프트
+- **도구 호출** - Claude가 호출한 모든 도구와 입력 및 출력
+- **정책 활동** - 각 도구 호출에 대해 어떤 정책이 실행되었고 어떤 결정을 반환했는지
+
+상단의 통계 표시줄에는 세션 지속 시간, 총 도구 호출 횟수, 훅 결정 요약(allow / deny / instruct 횟수)이 표시됩니다.
+
+**로그 다운로드** 버튼을 클릭하면 세션을 내보낼 수 있습니다. Claude Code, Codex, Copilot, Cursor, Pi 세션의 경우 디스크에 있는 원본 JSONL 트랜스크립트를 바이트 그대로 가져오고, OpenCode(세션이 디스크가 아닌 SQLite에 저장)의 경우 기본 `session` / `messages` / `parts` 테이블을 미러링한 JSON 문서를 가져옵니다.
+
+### 감사
+
+지난 세션 전반에 걸쳐 에이전트가 실제로 어떻게 행동해왔는지에 대한 성격 기반 보고서입니다. `failproofai audit` CLI와 동일한 스캔을 실행하지만, 단일 화면의 공유 가능한 포스터와 스크롤 아래의 네 개 섹션으로 렌더링됩니다:
+
+1. **포스터** — 첫 번째 뷰포트를 채웁니다. failproof_ai 워드마크 + 감사 레이블 · 아키타입 인덱스(`№ NN of 08`) + 감사 날짜 · 수치 점수(0–100) + 백분위 순위 pill(`top 15%`) · 아키타입 이름(`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` 중 하나) + 3개 키워드 스트립 · `// only N% of agents are this archetype` 희귀도 라인 · 8×8 픽셀 시길 타일 · `audit yours → failproof.ai` 푸터가 포함된 독립형 PNG 캡처 영역. 캡처 박스 바로 바깥에 세 개의 공유 버튼이 있습니다: `post your archetype`(X intent), `share on linkedin`, `download poster`. 캡처는 `html-to-image`를 통해 실행되어 PNG가 화면 렌더링과 픽셀 단위로 일치합니다(점선 테두리, SVG 로고 마스크, 그라디언트, 폰트 메트릭 모두 보존).
+2. **장점** — 에이전트가 이미 올바르게 수행하고 있는 동작의 체크 목록으로, 실시간 감사 데이터(깨끗한 도구 호출 비율, 메인에 직접 푸시 없음, 자격증명 유출 없음, 재시도 폭풍 없음)에서 도출됩니다. 감사 기간 동안 관련 정책이 깨끗한 기록을 가진 경우에만 각 항목이 표시됩니다.
+3. **문제점** — 발생한 문제를 심각도 순으로 정렬한 테이블: `발생 시점 · 무엇이 문제였는지 + 이를 감지했을 정책 · 심각도 pill · 발생 횟수`. 재발 횟수는 `new`(1회), `N× seen`(2–9회), `recurring`(10회 이상)으로 표시됩니다.
+4. **개선 방법** — 권장 정책별 목록: 흰색으로 정책 이름, 한 줄 설명, 오른쪽에 설치 명령어 + 복사 버튼. 섹션 헤더는 `enable all N → projected <score> · <tier>`(모든 수정 사항 적용 시 도달할 점수)로 표시되며, `[install all]` 버튼은 모든 권장 정책에 대한 `failproofai policy add a b c …` 명령어 전체를 복사합니다.
+5. **더 나은 복귀** — 나란히 배치된 두 개의 카드. 왼쪽: 알림 설정(`3d` / `7d` / `14d` / `30d` 주기 선택기; 인증 후 `/api/auth/reminder`를 통해 저장). 오른쪽: failproof 혜택 잠금 해제 — `invite a friend`는 친구 이메일을 쉼표/공백/줄바꿈으로 구분하여 입력하는 모달을 열고(한 번에 최대 10명), `/api/audit/invite`로 POST하여 api-server의 `POST /v0/invite`로 전달합니다. api-server는 `invite@failproof.ai`에서 수신자당 한 통의 이메일을 발송하며 발신자를 참조(Cc)로 추가하고 `Reply-To`를 설정합니다. 따라서 수신자는 누가 초대했는지 확인할 수 있고 발신자는 받은 편지함에 사본을 받게 됩니다. 익명 사용자는 초대 발송 전에 발신자 이메일을 확인하기 위해 먼저 `AuthDialog`로 안내됩니다. 권한 부여 / 혜택 이행은 추후 진행될 예정입니다.
+
+`failproofai audit` 런타임으로 구동됩니다 — 기본 스캔 엔진, 지원 플래그, 트랜스크립트별 캐시 불변성에 대해서는 [감사 CLI](/ko/cli/audit)를 참고하세요. 대시보드는 최신 결과를 `~/.failproofai/audit-dashboard.json`(모드 `0600`, 단일 슬롯, 새 실행 시 덮어씀)에 캐시하므로 재방문 시 즉시 로드됩니다. **트랜스크립트별 캐시와 전체 결과 캐시 모두 7일이 지나면 읽기 시 거부되어** 대시보드가 1주일 된 결과를 조용히 제공하는 일이 없습니다. TTL이 지나면 `/audit`는 빈 상태로 돌아가 새 실행을 요청합니다. 보고서 하단의 `[ re-audit now ]`를 클릭하면 `noCache: true`와 함께 `/api/audit/run`에 POST합니다. 재감사는 트랜스크립트별 캐시를 우회하고 캐시된 결과를 조용히 반환하는 대신 모든 트랜스크립트를 처음부터 다시 스캔합니다. 대시보드는 실행이 완료될 때까지 1Hz로 `/api/audit/status`를 폴링하며, 실행 중에는 경과 타이머와 함께 핑크색 진행 표시줄이 뷰포트 상단에 고정됩니다. 성공하면 새 결과가 전체 페이지 새로고침 없이 즉시 교체됩니다. 재감사 실패 시 표시줄은 `RerunError.kind`(`timeout` / `network` / `post_failed`)에 따른 메시지와 함께 빨간색으로 변하며 이전 보고서는 그대로 유지됩니다. 빈 상태(캐시 없음 또는 만료)와 세션 없는 상태(캐시는 있지만 스캔에서 트랜스크립트를 찾지 못함)는 별도로 표시됩니다.
+
+### 정책
+
+정책을 관리하고 활동을 검토하는 두 개의 탭으로 구성된 페이지입니다.
+
+<Tabs>
+  <Tab title="정책 탭">
+  - 단일 패널에서 failproofai가 보호할 에이전트 CLI를 다중 선택합니다 — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Hermes가 각각 설치 상태(`Active` / `Detected` / `Inactive`), 사용자 범위 설정 경로, 브랜드 색상 액센트와 함께 행으로 표시됩니다. 원하는 CLI를 체크하거나 해제하고 `Apply changes`를 클릭하면 차이점을 한 번에 설치/제거할 수 있습니다. PATH에서 바이너리가 감지된 CLI는 미리 체크됩니다.
+  - 클릭 한 번으로 개별 정책을 켜거나 끕니다(`~/.failproofai/policies-config.json`에 쓰여지며 모든 설치된 CLI에서 공유됨)
+  - 정책을 펼쳐 매개변수를 구성합니다(`policyParams`를 지원하는 정책에 한함)
+  - 사용자 정의 정책 파일 경로 설정
+  </Tab>
+  <Tab title="활동 탭">
+  - 모든 세션에서 실행된 모든 훅 이벤트의 페이지네이션된 전체 이력
+  - 결정, 이벤트 유형, CLI(Claude Code / OpenAI Codex / GitHub Copilot _(베타)_ / Cursor Agent _(베타)_ / OpenCode _(베타)_ / Pi _(베타)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), 정책 이름, 또는 세션 ID로 필터링
+  - 각 행에 표시되는 항목: 타임스탬프, 정책 이름, 결정, CLI 배지(주황 = Claude Code, 보라 = OpenAI Codex, 파랑 = GitHub Copilot, 에메랄드 = Cursor Agent, 앰버 = OpenCode, 분홍 = Pi, 인디고 = Hermes, 청록 = OpenClaw, 로즈 = Factory Droid, 바이올렛 = Devin, 시안 = Antigravity, 라임 = Goose), 도구 이름, 세션 ID, deny/instruct 결정의 이유
+  - 세션 ID를 클릭하면 트랜스크립트가 열립니다 — 뷰어는 훅을 실행한 CLI(Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state/<id>/events.jsonl`, Cursor Agent `~/.cursor/agent-sessions/<id>/events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions/<encoded-cwd>/<id>.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents/<id>/sessions/*.jsonl`, Factory Droid `~/.factory/sessions/<encoded-cwd>/<id>.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain/<id>/…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`)를 자동 감지하고 헤더에 해당 CLI 배지를 렌더링합니다
+  </Tab>
+</Tabs>
+
+---
+
+## 자동 새로고침
+
+대시보드 상단 네비게이션에는 자동 새로고침 토글이 있습니다. 활성화하면 현재 페이지가 주기적으로 새로고침되어 새로운 세션과 정책 활동이 나타날 때 표시됩니다. 장시간 실행되는 자율 에이전트 세션을 모니터링할 때 필수적인 기능입니다.
+
+---
+
+## 페이지 비활성화
+
+대시보드의 일부 기능만 필요한 경우, `FAILPROOFAI_DISABLE_PAGES`를 비활성화할 페이지 이름의 쉼표 구분 목록으로 설정하세요:
+
+```bash
+FAILPROOFAI_DISABLE_PAGES=policies failproofai
+```
+
+유효한 값: `policies`, `projects`, `audit`.
+
+---
+
+## 프로젝트 경로 구성
+
+기본적으로 대시보드는 표준 Claude Code 프로젝트 디렉터리에서 읽어옵니다. 사용자 정의 설정을 위해 재정의할 수 있습니다:
+
+```bash
+CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
+```
+
+---
+
+## localhost가 아닌 호스트에서 접근하기
+
+**개발 모드**(`npm run dev`)로 대시보드를 실행하고 localhost가 아닌 호스트명(예: 사용자 정의 도메인, 원격 IP, 터널링된 URL)에서 접근하는 경우 다음과 같은 경고가 표시될 수 있습니다:
+
+```text
+⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
+```
+
+이는 Next.js가 개발 전용 기능인 HMR(핫 모듈 리로드) 웹소켓에 대한 교차 출처 접근을 차단하는 것입니다. 호스트를 허용하려면 `--allowed-origins` 플래그를 사용하세요:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com
+```
+
+여러 호스트나 IP의 경우 쉼표 구분 목록을 전달하세요:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
+```
+
+`FAILPROOFAI_ALLOWED_DEV_ORIGINS` 환경 변수를 대신 설정할 수도 있습니다:
+
+```bash
+FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
+```
+
+<Note>
+이는 개발 모드에만 적용됩니다. `failproofai`(프로덕션 모드)를 실행할 때는 HMR 웹소켓도 없고 교차 출처 개발 리소스 문제도 발생하지 않습니다.
+</Note>

package/.next/standalone/docs-old/ko/examples.mdx

@@ -0,0 +1,307 @@
+---
+title: 예제
+description: "Claude Code 및 Agents SDK에 훅을 설정하는 방법"
+icon: book-open
+---
+
+일반적인 시나리오에 바로 사용할 수 있는 예제 모음입니다. 각 예제는 설치 방법과 예상 동작을 안내합니다.
+
+---
+
+## Claude Code에 훅 설정하기
+
+Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/docs/claude-code/hooks)을 통해 통합됩니다. `failproofai policies --install`을 실행하면, 모든 도구 호출 시 실행되는 훅 명령어가 Claude Code의 `settings.json`에 등록됩니다.
+
+<Steps>
+  <Step title="failproofai 설치">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="모든 기본 제공 정책 활성화">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="훅 등록 확인">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    `PreToolUse`, `PostToolUse`, `Notification`, `Stop` 이벤트에 대한 훅 항목이 보여야 합니다.
+  </Step>
+  <Step title="Claude Code 실행">
+    ```bash
+    claude
+    ```
+
+    이제 모든 도구 호출 시 정책이 자동으로 실행됩니다. Claude에게 `sudo rm -rf /`를 실행해보라고 요청해보세요 — 차단됩니다.
+  </Step>
+</Steps>
+
+---
+
+## Agents SDK에 훅 설정하기
+
+[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk)로 개발 중이라면, 동일한 훅 시스템을 프로그래밍 방식으로 사용할 수 있습니다.
+
+<Steps>
+  <Step title="프로젝트에 failproofai 설치">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="에이전트에 훅 설정">
+    에이전트 프로세스 생성 시 훅 명령어를 전달하세요. 훅은 Claude Code와 동일한 방식으로 — stdin/stdout JSON을 통해 — 동작합니다:
+
+    ```bash
+    failproofai --hook PreToolUse   # called before each tool
+    failproofai --hook PostToolUse  # called after each tool
+    ```
+  </Step>
+  <Step title="에이전트용 커스텀 정책 작성">
+    ```javascript
+    import { customPolicies, allow, deny } from "failproofai";
+
+    customPolicies.add({
+      name: "limit-to-project-dir",
+      description: "Keep the agent inside the project directory",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        const path = String(ctx.toolInput?.file_path ?? "");
+        if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
+          return deny("Agent is restricted to the project directory");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="커스텀 정책 설치">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## 파괴적인 명령어 차단
+
+가장 일반적인 설정으로, 에이전트가 되돌릴 수 없는 피해를 입히는 것을 방지합니다.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+각 정책의 역할:
+- `block-sudo` — 모든 `sudo` 명령어를 차단합니다
+- `block-rm-rf` — 재귀적 파일 삭제를 차단합니다
+- `block-force-push` — `git push --force`를 차단합니다
+- `block-curl-pipe-sh` — 원격 스크립트를 셸로 파이프하는 것을 차단합니다
+
+---
+
+## 시크릿 유출 방지
+
+에이전트가 도구 출력에서 자격 증명을 보거나 유출하는 것을 방지합니다.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+이 정책들은 `PostToolUse` 시점에 실행됩니다 — 도구가 실행된 후, 에이전트가 출력을 보기 전에 민감한 정보를 제거합니다.
+
+---
+
+## 에이전트가 대기 중일 때 Slack 알림 받기
+
+알림 훅을 사용하여 유휴 알림을 Slack으로 전달합니다.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "slack-on-idle",
+  description: "Alert Slack when the agent is waiting for input",
+  match: { events: ["Notification"] },
+  fn: async (ctx) => {
+    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+    if (!webhookUrl) return allow();
+
+    const message = String(ctx.payload?.message ?? "Agent is waiting");
+    const project = ctx.session?.cwd ?? "unknown";
+
+    try {
+      await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          text: `*${message}*\nProject: \`${project}\``,
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // never block the agent if Slack is unreachable
+    }
+
+    return allow();
+  },
+});
+```
+
+설치:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## 에이전트를 특정 브랜치에 고정
+
+에이전트가 브랜치를 변경하거나 보호된 브랜치에 푸시하는 것을 방지합니다.
+
+```javascript
+import { customPolicies, allow, deny } from "failproofai";
+
+customPolicies.add({
+  name: "stay-on-branch",
+  description: "Prevent the agent from checking out other branches",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
+      return deny("Stay on the current branch. Create a new branch with -b if needed.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## 커밋 전 테스트 실행 요구
+
+커밋 전에 테스트를 실행하도록 에이전트에게 알립니다.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "test-before-commit",
+  description: "Remind the agent to run tests before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## 프로덕션 저장소 보호
+
+프로젝트 수준의 설정을 커밋하여 팀의 모든 개발자가 동일한 정책을 적용받도록 합니다.
+
+저장소에 `.failproofai/policies-config.json`을 생성합니다:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-force-push",
+    "block-push-master",
+    "block-env-files",
+    "sanitize-api-keys",
+    "sanitize-jwt"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "production"]
+    }
+  }
+}
+```
+
+그런 다음 커밋합니다:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+failproofai가 설치된 모든 팀원에게 이 규칙이 자동으로 적용됩니다.
+
+---
+
+## 컨벤션 정책으로 조직 전체 품질 기준 수립
+
+가장 효과적인 설정: 프로젝트에 맞게 커스터마이징한 정책을 `.failproofai/policies/`에 저장하고 저장소에 커밋하세요. 모든 팀원이 자동으로 적용받으며, 별도의 설치 명령어나 설정 변경이 필요 없습니다.
+
+<Steps>
+  <Step title="디렉토리를 생성하고 정책 추가">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    // Enforce your team's preferred package manager
+    // (or enable the built-in prefer-package-manager policy instead)
+    customPolicies.add({
+      name: "enforce-bun",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        const cmd = String(ctx.toolInput?.command ?? "");
+        if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
+        return allow();
+      },
+    });
+
+    // Remind the agent to run tests before committing
+    customPolicies.add({
+      name: "test-before-commit",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
+          return instruct("Run tests before committing.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="git에 커밋">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+  </Step>
+  <Step title="지속적으로 개선">
+    팀에서 새로운 문제가 발생할 때마다 정책을 추가하고 푸시하세요. 모든 팀원이 다음 `git pull` 시 업데이트를 받게 됩니다. 이 정책들은 팀과 함께 성장하는 살아있는 품질 기준이 됩니다.
+  </Step>
+</Steps>
+
+---
+
+## 더 많은 예제
+
+저장소의 [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) 디렉토리에 다음이 포함되어 있습니다:
+
+| 파일 | 내용 |
+|------|---------------|
+| `policies-basic.js` | 기본 정책 — 프로덕션 쓰기, 강제 푸시, 파이프된 스크립트 차단 |
+| `policies-notification.js` | 유휴 알림 및 세션 종료 시 Slack 알림 |
+| `policies-advanced/index.js` | 전이적 임포트, 비동기 훅, PostToolUse 출력 제거, Stop 이벤트 처리 |

package/.next/standalone/docs-old/ko/for-agents.mdx

@@ -0,0 +1,38 @@
+---
+title: "에이전트용"
+description: "한 줄의 명령으로 코딩 에이전트에 Failproof AI 지식을 추가하세요. Claude Code, Cursor, Windsurf 등과 함께 작동합니다."
+---
+
+한 줄의 명령으로 코딩 에이전트에 Failproof AI 전체 레퍼런스를 추가하세요. Claude Code, Cursor, Windsurf 및 스킬을 지원하는 모든 에이전트와 함께 작동합니다.
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+`npx skills`는 설치된 에이전트를 자동으로 감지하고, 각 에이전트에 맞는 형식으로 스킬을 추가합니다.
+
+## 스킬이 다루는 내용
+
+| 영역 | 포함 내용 |
+|------|----------------|
+| 정책 | 기본 제공 정책 이름, 이벤트 타입, 파라미터, 활성화/비활성화 |
+| 커스텀 정책 | `customPolicies.add()`, 매치 필터, `allow`/`deny`/`instruct` API |
+| 컨텍스트 객체 | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` |
+| 구성 | `policies-config.json` 구조, 스코프 병합, `policyParams` |
+| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, 스코프 |
+| 대시보드 | 세션 뷰어, 정책 활동, 환경 변수 |
+| 아키텍처 | 훅 핸들러 흐름, 종료 코드, stdin/stdout 계약 |
+
+## 스킬은 완전한가요?
+
+Mintlify는 내비게이션의 모든 페이지에서 `llms.txt`를 생성합니다. Failproof AI 문서는 전체 API를 다루며, 모든 정책, 옵션, 예제가 포함되어 있습니다. 누락된 내용이 있다면 소스는 `https://docs.befailproof.ai/llms-full.txt`에서 확인할 수 있습니다.
+
+특정 맥락에 집중하려면 특정 페이지에 직접 링크하세요:
+
+```bash
+# 커스텀 정책 API만
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# 기본 제공 정책만
+npx skills add https://docs.befailproof.ai/built-in-policies
+```