failproofai 0.0.2-beta.8 → 0.0.2-beta.9

package/.next/standalone/docs/ko/package-aliases.mdx

@@ -0,0 +1,82 @@
+---
+title: 패키지 별칭
+description: "등록된 오타 방지 별칭과 그 작동 방식"
+icon: copy
+---
+
+## 공식 패키지
+
+npm의 정식 패키지명은 **`failproofai`**입니다:
+
+```bash
+npm install -g failproofai
+# or
+bun add -g failproofai
+```
+
+---
+
+## 별칭 이름을 직접 소유하는 이유
+
+타이포스쿼팅(typosquatting)은 공급망 공격의 일반적인 유형으로, 악의적인 공격자가 인기 패키지명에서 한 글자만 다른 패키지를 등록합니다. 설치 명령어를 잘못 입력한 사용자는 자신도 모르게 공격자가 제어하는 코드를 전체 시스템 접근 권한으로 실행하게 됩니다. 이는 바로 Failproof AI가 막아내고자 하는 위협입니다.
+
+이 공격 표면을 없애기 위해, **npm에서 `failproofai`의 모든 일반적인 오타 및 표기 변형을 선제적으로 소유**하고 있습니다. 이 이름들은 제3자가 등록할 수 없으며, 각각은 실제 `failproofai` 패키지를 설치하고 위임하는 얇은 프록시입니다.
+
+---
+
+## 등록된 별칭
+
+**표기 변형** - "failproof ai"를 작성하는 다양한 방식:
+
+| 패키지 | 상태 |
+|---------|--------|
+| `failproof` | ✅ 게시됨 |
+| `failproof-ai` | ⏳ npm 승인 대기 중 |
+| `fail-proof-ai` | ⏳ npm 승인 대기 중 |
+| `failproof_ai` | ⏳ npm 승인 대기 중 |
+| `fail_proof_ai` | ⏳ npm 승인 대기 중 |
+| `fail-proofai` | ⏳ npm 승인 대기 중 |
+
+**`failprof*` 오타** - "proof"에서 `o` 하나가 빠진 경우:
+
+| 패키지 | 상태 |
+|---------|--------|
+| `failprof` | ✅ 게시됨 |
+| `failprof-ai` | ✅ 게시됨 |
+| `failprofai` | ⏳ npm 승인 대기 중 |
+| `fail-prof-ai` | ⏳ npm 승인 대기 중 |
+| `failprof_ai` | ⏳ npm 승인 대기 중 |
+
+**`faliproof*` 오타** - `a`와 `i`가 뒤바뀐 경우:
+
+| 패키지 | 상태 |
+|---------|--------|
+| `faliproof` | ✅ 게시됨 |
+| `faliproof-ai` | ✅ 게시됨 |
+| `faliproofai` | ⏳ npm 승인 대기 중 |
+
+> **왜 대기 중인가요?** npm의 스팸 방지 정책은 구두점을 제거하고 유사도 검사를 수행한 후 기존 패키지와 동일한 문자열로 정규화되는 이름의 등록을 차단합니다. 현재 스쿼팅 방지 목적으로 이 이름들을 예약하기 위해 npm 지원팀에 문의한 상태이며, 승인 후 활성화될 예정입니다.
+
+게시된 별칭이 저희 소유인지 다음 명령어로 확인할 수 있습니다:
+
+```bash
+npm info failproof
+# Look for: "ExosphereHost Inc." in the maintainers field
+```
+
+---
+
+## 별칭의 작동 방식
+
+각 별칭 패키지는:
+
+1. `failproofai`를 의존성으로 등록하여, 설치 시 실제 패키지(및 해당 `postinstall` 훅 설정)가 실행됩니다.
+2. 자체 이름(예: `failprof-ai`)에 해당하는 바이너리를 노출하며, 모든 인수를 `failproofai` 바이너리로 프록시합니다.
+
+프록시는 두 줄짜리 Node 스크립트로, 로직도 없고 네트워크 호출도 없으며, `failproofai` 자체가 수행하는 것 이상의 데이터 수집도 없습니다.
+
+---
+
+## 누락된 이름을 발견했다면
+
+[exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues)에 이슈를 등록해 주시면 등록하겠습니다.

package/.next/standalone/docs/ko/testing.mdx

@@ -0,0 +1,260 @@
+---
+title: 테스트
+description: "유닛 테스트, E2E 테스트, 테스트 헬퍼"
+icon: flask-vial
+---
+
+failproofai에는 두 가지 테스트 스위트가 있습니다: **유닛 테스트** (빠르고 모킹 사용)와 **엔드투엔드 테스트** (실제 서브프로세스 실행).
+
+---
+
+## 테스트 실행
+
+```bash
+# 유닛 테스트를 한 번 실행
+bun run test:run
+
+# 유닛 테스트를 워치 모드로 실행
+bun run test
+
+# E2E 테스트 실행 (설정 필요 - 아래 참고)
+bun run test:e2e
+
+# 빌드 없이 타입 검사
+bunx tsc --noEmit
+
+# 린트
+bun run lint
+```
+
+---
+
+## 유닛 테스트
+
+유닛 테스트는 `__tests__/` 디렉터리에 위치하며 `happy-dom`과 함께 [Vitest](https://vitest.dev)를 사용합니다.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # 각 내장 정책의 로직
+    hooks-config.test.ts          # 설정 로딩 및 스코프 병합
+    policy-evaluator.test.ts      # 파라미터 주입과 평가 순서
+    custom-hooks-registry.test.ts # globalThis 레지스트리 add/get/clear
+    custom-hooks-loader.test.ts   # ESM 로더, 전이적 임포트, 오류 처리
+    manager.test.ts               # install/remove/list 작업
+  components/
+    sessions-list.test.tsx        # 세션 목록 컴포넌트
+    project-list.test.tsx         # 프로젝트 목록 컴포넌트
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### 정책 유닛 테스트 작성하기
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## 엔드투엔드 테스트
+
+E2E 테스트는 실제 `failproofai` 바이너리를 서브프로세스로 실행하고, JSON 페이로드를 stdin으로 파이핑한 뒤, stdout 출력과 종료 코드를 검증합니다. 이를 통해 Claude Code가 실제로 사용하는 전체 통합 경로를 테스트합니다.
+
+### 설정
+
+E2E 테스트는 저장소 소스에서 바이너리를 직접 실행합니다. 최초 실행 전에, 커스텀 훅 파일이 `'failproofai'`에서 임포트할 때 사용하는 CJS 번들을 빌드하세요:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+그 다음 테스트를 실행합니다:
+
+```bash
+bun run test:e2e
+```
+
+공개 훅 API(`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, `src/hooks/policy-types.ts`)를 변경할 때마다 `dist/`를 다시 빌드하세요.
+
+### E2E 테스트 구조
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # 바이너리 실행, 페이로드 JSON 파이핑, 종료 코드 + stdout + stderr 캡처
+    fixture-env.ts      # 테스트별 격리된 임시 디렉터리와 설정 파일
+    payloads.ts         # 각 이벤트 타입에 대한 Claude 형식의 페이로드 팩토리
+  hooks/
+    builtin-policies.e2e.test.ts   # 실제 서브프로세스로 각 내장 정책 테스트
+    custom-hooks.e2e.test.ts       # 커스텀 훅 로딩 및 평가
+    config-scopes.e2e.test.ts      # 프로젝트/로컬/글로벌 간 설정 병합
+    policy-params.e2e.test.ts      # 파라미터화된 정책별 파라미터 주입
+```
+
+### E2E 헬퍼 사용하기
+
+**`FixtureEnv`** - 테스트별 격리 환경:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - 임시 디렉터리; payload.cwd로 전달하면 .failproofai/policies-config.json을 읽음
+// env.home   - 격리된 홈 디렉터리; 실제 ~/.failproofai가 누출되지 않음
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()`는 `afterEach` 정리를 자동으로 등록합니다.
+
+**`runHook`** - 바이너리 실행:
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** - 미리 준비된 페이로드 팩토리:
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### E2E 테스트 작성하기
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // allow → 빈 stdout
+  });
+});
+```
+
+### E2E 응답 형식
+
+| 결정 | 종료 코드 | stdout |
+|----------|-----------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (Stop 제외) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | 빈 stdout; 이유는 stderr에 기록 |
+| Allow | `0` | 빈 문자열 |
+
+### Vitest 설정
+
+E2E 테스트는 다음 설정으로 `vitest.config.e2e.mts`를 사용합니다:
+
+- `environment: "node"` - 브라우저 전역 객체 불필요
+- `pool: "forks"` - 진정한 프로세스 격리 (테스트가 서브프로세스를 생성)
+- `testTimeout: 20_000` - 테스트당 20초 (바이너리 시작 + 훅 평가)
+
+`forks` 풀이 중요한 이유: 스레드 기반 워커는 `globalThis`를 공유하므로, 서브프로세스를 생성하는 테스트에 영향을 줄 수 있습니다. 프로세스 기반 포크는 이를 방지합니다.
+
+---
+
+## CI
+
+머지 전에 전체 CI 실행(`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`)이 통과되어야 합니다. E2E 스위트는 별도의 CI 작업으로 병렬 실행됩니다.
+
+완전한 머지 전 체크리스트는 [Contributing](../CONTRIBUTING.md)을 참고하세요.

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

@@ -0,0 +1,332 @@
+---
+title: Arquitetura
+description: "Como o handler de hooks, o carregamento de configuração e a avaliação de políticas funcionam internamente"
+icon: sitemap
+---
+
+Este documento explica como o failproofai funciona internamente: como o sistema de hooks intercepta chamadas de ferramentas do agente, como a configuração é carregada e mesclada, como as políticas são avaliadas e como o dashboard monitora a atividade do agente.
+
+---
+
+## Visão geral
+
+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.
+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
+
+### Integração com o Claude Code
+
+Quando você executa `failproofai policies --install`, ele escreve entradas como esta em `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+O Claude Code então invoca `failproofai --hook PreToolUse` como subprocesso antes de cada chamada de ferramenta, passando um payload JSON via stdin.
+
+### Formato do payload
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
+  "cwd": "/home/user/myproject",
+  "permission_mode": "default",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Bash",
+  "tool_input": { "command": "sudo apt install nodejs" }
+}
+```
+
+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.
+
+### Formato da resposta
+
+**Deny (PreToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Deny (PostToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Instruct (qualquer evento exceto Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Instruct para evento Stop:**
+- Código de saída: `2`
+- Motivo escrito em stderr (não em stdout)
+
+**Allow:**
+- Código de saída: `0`
+- stdout vazio
+
+**Allow com mensagem (beta):**
+
+Desde a v0.0.2-beta.3, `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):
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- 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)
+
+### Pipeline de processamento
+
+`src/hooks/handler.ts` implementa o pipeline completo:
+
+```text
+stdin JSON
+  → parse payload (max 1 MB)
+  → extract session metadata (session_id, cwd, tool_name, tool_input, etc.)
+  → readMergedHooksConfig(cwd)    ← merges project + local + global config
+  → register enabled builtin policies with resolved params
+  → load custom policies from customPoliciesPath (if set)
+  → register custom policies into policy registry
+  → evaluate all policies (builtins first, then custom)
+      → first deny short-circuits
+      → instruct decisions accumulate
+      → allow messages accumulate
+  → write JSON decision to stdout
+  → persist event to ~/.failproofai/hook-activity.jsonl
+  → exit
+```
+
+Todo o processo é executado em menos de 100ms para payloads típicos, sem nenhuma chamada a LLMs.
+
+---
+
+## Carregamento de configuração
+
+`src/hooks/hooks-config.ts` implementa o carregamento de configuração em três escopos.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← projeto   (maior prioridade)
+[2] {cwd}/.failproofai/policies-config.local.json  ← local
+[3] ~/.failproofai/policies-config.json             ← global    (menor prioridade)
+```
+
+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
+
+O dashboard web utiliza `readHooksConfig()` (somente global) para leitura e escrita, pois não é invocado com um cwd de projeto.
+
+---
+
+## Avaliação de políticas
+
+`src/hooks/policy-evaluator.ts` executa as políticas em ordem.
+
+Para cada política:
+
+1. Busca o esquema 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`.
+4. Chama `policy.fn(ctx)` com o contexto resolvido.
+5. Se o resultado for `deny`, interrompe 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).
+
+---
+
+## Políticas embutidas
+
+`src/hooks/builtin-policies.ts` define todas as 26 políticas embutidas como objetos `BuiltinPolicyDefinition`:
+
+```typescript
+interface BuiltinPolicyDefinition {
+  name: string;
+  description: string;
+  fn: (ctx: PolicyContext) => PolicyResult;
+  match: {
+    events: HookEventType[];
+    tools?: string[];
+  };
+  defaultEnabled: boolean;
+  category: string;
+  beta?: boolean;
+  params?: PolicyParamsSchema;
+}
+```
+
+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).
+
+---
+
+## Políticas personalizadas
+
+`src/hooks/custom-hooks-registry.ts` implementa um registro baseado em `globalThis`:
+
+```typescript
+const REGISTRY_KEY = "__failproofai_custom_hooks__";
+
+export const customPolicies = {
+  add(hook: CustomHook): void { ... }
+};
+
+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:
+
+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.
+6. Chama `getCustomHooks()` para recuperar os hooks registrados.
+7. Limpa 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.
+
+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).
+
+---
+
+## Log de atividade
+
+Após cada evento de hook, o handler anexa uma linha JSONL em `~/.failproofai/hook-activity.jsonl`:
+
+```json
+{
+  "timestamp": "2026-04-06T12:34:56.789Z",
+  "sessionId": "abc123",
+  "eventType": "PreToolUse",
+  "toolName": "Bash",
+  "policyName": "block-sudo",
+  "decision": "deny",
+  "reason": "sudo command blocked by failproofai",
+  "durationMs": 12
+}
+```
+
+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).
+
+---
+
+## Arquitetura do dashboard
+
+O dashboard é uma aplicação **Next.js 16** usando o App Router com React Server Components e Server Actions.
+
+```text
+app/
+  layout.tsx                  ← Layout raiz (tema, telemetria, navegação)
+  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/
+    [sessionId]/page.tsx      ← Server component: renderiza o visualizador de sessão
+  policies/page.tsx           ← Client component: gerenciamento de políticas + log de atividade
+  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
+    install-hooks-web.ts      ← Instala/remove hooks pelo navegador
+  api/
+    download/[project]/[session]/route.ts   ← Exporta sessão como ZIP/JSONL
+```
+
+**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).
+- 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).
+
+---
+
+## Estrutura de arquivos
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # Roteador CLI (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Pipeline de eventos de hook
+│   ├── builtin-policies.ts       # 26 definições de políticas
+│   ├── policy-evaluator.ts       # Motor de execução de políticas
+│   ├── policy-registry.ts        # Registro e busca de políticas
+│   ├── 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
+│   ├── 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)
+├── 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
+└── __tests__/                    # Testes unitários e E2E
+```