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

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

@@ -0,0 +1,82 @@
+---
+title: Alias dei Pacchetti
+description: "Alias registrati per la prevenzione del typosquatting e come funzionano"
+icon: copy
+---
+
+## Pacchetto ufficiale
+
+Il pacchetto npm canonico è **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# or
+bun add -g failproofai
+```
+
+---
+
+## Perché possediamo i nomi degli alias
+
+Il typosquatting è un attacco comune alla supply chain in cui un malintenzionato registra un nome di pacchetto che è a una pressione di tasto di distanza da un pacchetto popolare. Gli utenti ignari che digitano male il comando di installazione finiscono per eseguire codice controllato dall'attaccante con accesso completo al sistema - esattamente il tipo di minaccia che Failproof AI è progettato per difendere.
+
+Per eliminare questa superficie di attacco, **possediamo preventivamente tutte le comuni varianti di ortografia e formattazione** di `failproofai` su npm. Nessuno di questi nomi può essere registrato da terzi. Ognuno di essi è un proxy sottile che installa e delega al vero pacchetto `failproofai`.
+
+---
+
+## Alias registrati
+
+**Varianti di formattazione** - diversi modi di scrivere "failproof ai":
+
+| Pacchetto | Stato |
+|---------|--------|
+| `failproof` | ✅ Pubblicato |
+| `failproof-ai` | ⏳ In attesa di supporto npm |
+| `fail-proof-ai` | ⏳ In attesa di supporto npm |
+| `failproof_ai` | ⏳ In attesa di supporto npm |
+| `fail_proof_ai` | ⏳ In attesa di supporto npm |
+| `fail-proofai` | ⏳ In attesa di supporto npm |
+
+**Errori di digitazione `failprof*`** - manca una `o` da "proof":
+
+| Pacchetto | Stato |
+|---------|--------|
+| `failprof` | ✅ Pubblicato |
+| `failprof-ai` | ✅ Pubblicato |
+| `failprofai` | ⏳ In attesa di supporto npm |
+| `fail-prof-ai` | ⏳ In attesa di supporto npm |
+| `failprof_ai` | ⏳ In attesa di supporto npm |
+
+**Errori di digitazione `faliproof*`** - `a` e `i` invertite:
+
+| Pacchetto | Stato |
+|---------|--------|
+| `faliproof` | ✅ Pubblicato |
+| `faliproof-ai` | ✅ Pubblicato |
+| `faliproofai` | ⏳ In attesa di supporto npm |
+
+> **Perché in sospeso?** La politica anti-spam di npm blocca i nomi che si normalizzano alla stessa stringa di un pacchetto esistente dopo aver rimosso la punteggiatura e eseguito controlli di somiglianza. Abbiamo contattato il supporto npm per riservare questi nomi a scopo di prevenzione del typosquatting. Saranno attivati una volta approvati.
+
+Puoi verificare che qualsiasi alias pubblicato sia di nostra proprietà:
+
+```bash
+npm info failproof
+# Cercare: "ExosphereHost Inc." nel campo maintainers
+```
+
+---
+
+## Come funzionano gli alias
+
+Ogni pacchetto alias:
+
+1. Elenca `failproofai` come dipendenza - in modo che il vero pacchetto (inclusa la configurazione del suo hook `postinstall`) venga eseguito all'installazione
+2. Espone un binario che corrisponde al suo nome (ad es. `failprof-ai`) che inoltra tutti gli argomenti al binario `failproofai`
+
+Il proxy è uno script Node a due righe; non c'è logica, nessuna chiamata di rete e nessuna raccolta dati oltre a quella che fa `failproofai` stesso.
+
+---
+
+## Se trovi un nome che ci è sfuggito
+
+Apri un issue su [exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) e lo registreremo.

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

@@ -0,0 +1,260 @@
+---
+title: Test
+description: "Unit test, test end-to-end e assistenti di test"
+icon: flask-vial
+---
+
+failproofai dispone di due suite di test: **unit test** (veloci, con mock) e **test end-to-end** (invocazioni reali di subprocess).
+
+---
+
+## Esecuzione dei test
+
+```bash
+# Esegui tutti gli unit test una sola volta
+bun run test:run
+
+# Esegui gli unit test in modalità watch
+bun run test
+
+# Esegui i test E2E (richiede setup - vedi sotto)
+bun run test:e2e
+
+# Verifica i tipi senza compilare
+bunx tsc --noEmit
+
+# Linting
+bun run lint
+```
+
+---
+
+## Unit test
+
+Gli unit test si trovano in `__tests__/` e utilizzano [Vitest](https://vitest.dev) con `happy-dom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Logica delle policy per ogni builtin
+    hooks-config.test.ts          # Caricamento della config e merge dello scope
+    policy-evaluator.test.ts      # Iniezione di parametri e ordine di valutazione
+    custom-hooks-registry.test.ts # Registry di globalThis add/get/clear
+    custom-hooks-loader.test.ts   # Loader ESM, importazioni transitive, gestione errori
+    manager.test.ts               # Operazioni install/remove/list
+  components/
+    sessions-list.test.tsx        # Componente lista sessioni
+    project-list.test.tsx         # Componente lista progetti
+    ...
+  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
+```
+
+### Scrivere un unit test per una policy
+
+```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());
+  });
+});
+```
+
+---
+
+## Test end-to-end
+
+I test E2E invocano il binario `failproofai` reale come subprocess, inviano un payload JSON a stdin e effettuano asserzioni sull'output stdout e il codice di uscita. Questo verifica il percorso di integrazione completo che utilizza Claude Code.
+
+### Setup
+
+I test E2E eseguono il binario direttamente dal codice sorgente del repository. Prima della prima esecuzione, compila il bundle CJS che i file di custom hook utilizzano quando importano da `'failproofai'`:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Quindi esegui i test:
+
+```bash
+bun run test:e2e
+```
+
+Ricompila `dist/` ogni volta che modifichi l'API pubblica dei hook (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, o `src/hooks/policy-types.ts`).
+
+### Struttura dei test E2E
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # Avvia il binario, invia payload JSON, cattura codice di uscita + stdout + stderr
+    fixture-env.ts      # Directory temp isolate per test con file di config
+    payloads.ts         # Factory di payload conformi a Claude per ogni tipo di evento
+  hooks/
+    builtin-policies.e2e.test.ts   # Ogni policy builtin con subprocess reale
+    custom-hooks.e2e.test.ts       # Caricamento e valutazione di custom hook
+    config-scopes.e2e.test.ts      # Merge della configurazione tra project/local/global
+    policy-params.e2e.test.ts      # Iniezione di parametri per ogni policy parametrizzata
+```
+
+### Utilizzo degli helper E2E
+
+**`FixtureEnv`** - ambiente isolato per ogni test:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - directory temporanea; passa come payload.cwd per raccogliere .failproofai/policies-config.json
+// env.home   - directory home isolata; nessun vero ~/.failproofai in conflitto
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` registra la pulizia `afterEach` automaticamente.
+
+**`runHook`** - invoca il binario:
+
+```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`** - factory di payload già pronti:
+
+```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)
+```
+
+### Scrivere un test 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 vuoto
+  });
+});
+```
+
+### Forme di risposta E2E
+
+| Decisione | Codice di uscita | stdout |
+|-----------|------------------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | stdout vuoto; ragione in stderr |
+| Allow | `0` | stringa vuota |
+
+### Config di Vitest
+
+I test E2E utilizzano `vitest.config.e2e.mts` con:
+
+- `environment: "node"` - nessuna global del browser necessaria
+- `pool: "forks"` - vera isolazione dei processi (i test avviano subprocess)
+- `testTimeout: 20_000` - 20s per test (startup del binario + valutazione hook)
+
+Il pool `forks` è importante: i worker basati su thread condividono `globalThis`, il che può interferire con i test che avviano subprocess. I fork basati su processi evitano questo problema.
+
+---
+
+## CI
+
+L'esecuzione CI completa (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) è richiesta per essere approvata prima di fare merge. La suite E2E viene eseguita come un job CI separato in parallelo.
+
+Consulta [Contributing](../CONTRIBUTING.md) per la checklist completa pre-merge.

package/.next/standalone/docs/ja/architecture.mdx

@@ -0,0 +1,332 @@
+---
+title: アーキテクチャ
+description: "フックハンドラー、設定の読み込み、ポリシー評価が内部でどのように機能するか"
+icon: sitemap
+---
+
+このドキュメントでは、failproofai の内部動作を説明します。フックシステムがエージェントのツール呼び出しをどのようにインターセプトするか、設定がどのように読み込まれてマージされるか、ポリシーがどのように評価されるか、そしてダッシュボードがエージェントの活動をどのように監視するかについて解説します。
+
+---
+
+## 概要
+
+failproofai には2つの独立したサブシステムがあります。
+
+1. **フックハンドラー** - Claude Code がエージェントのすべてのツール呼び出し時に起動する高速な CLI サブプロセス。ポリシーを評価し、決定を返します。
+2. **エージェントモニター（ダッシュボード）** - エージェントセッションの監視とポリシー管理を行う Next.js ウェブアプリケーション。
+
+どちらのサブシステムも `~/.failproofai/` およびプロジェクトの `.failproofai/` ディレクトリにある設定ファイルを共有しますが、それぞれ独立したプロセスとして動作し、ファイルシステムを通じてのみ通信します。
+
+---
+
+## フックハンドラー
+
+### Claude Code との統合
+
+`failproofai policies --install` を実行すると、以下のようなエントリが `~/.claude/settings.json` に書き込まれます。
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code は各ツール呼び出しの前に `failproofai --hook PreToolUse` をサブプロセスとして起動し、stdin に JSON ペイロードを渡します。
+
+### ペイロードの形式
+
+```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" }
+}
+```
+
+`PostToolUse` イベントの場合、ペイロードにはツールの出力を含む `tool_result` も含まれます。
+
+ハンドラーは stdin の上限を 1 MB に制限しています。これを超えるペイロードは破棄され、すべてのポリシーは暗黙的に allow となります。
+
+### レスポンスの形式
+
+**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（Stop 以外のすべてのイベント）:**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Stop イベントの instruct:**
+- 終了コード: `2`
+- 理由は stdout ではなく stderr に書き込まれます
+
+**Allow:**
+- 終了コード: `0`
+- stdout は空
+
+**メッセージ付き Allow（ベータ）:**
+
+v0.0.2-beta.3 以降、`allow(message)` を使用することで、操作が許可されている場合でもポリシーが Claude に情報コンテキストを返せるようになりました。フックハンドラーは以下の JSON を **stdout** に書き込みます（設定ファイルではありません。上記の deny や instruct のレスポンスと同様に、Claude Code へのハンドラープロセスのレスポンスです）。
+
+```json
+// フックハンドラープロセスによって stdout に書き込まれます
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- 終了コード: `0`（操作は許可されます）
+- 複数のポリシーがメッセージ付きで `allow` を返した場合、それらのメッセージは改行で結合されて単一の `additionalContext` 文字列になります
+- どのポリシーもメッセージを提供しない場合、stdout は空（従来と同じ）
+
+### 処理パイプライン
+
+`src/hooks/handler.ts` が完全なパイプラインを実装しています。
+
+```text
+stdin JSON
+  → ペイロードのパース（最大 1 MB）
+  → セッションメタデータの抽出（session_id、cwd、tool_name、tool_input など）
+  → readMergedHooksConfig(cwd)    ← プロジェクト + ローカル + グローバル設定をマージ
+  → 解決済みパラメーターで有効なビルトインポリシーを登録
+  → customPoliciesPath からカスタムポリシーを読み込み（設定されている場合）
+  → カスタムポリシーをポリシーレジストリに登録
+  → すべてのポリシーを評価（ビルトインが先、次にカスタム）
+      → 最初の deny で短絡
+      → instruct の決定を蓄積
+      → allow メッセージを蓄積
+  → JSON 決定を stdout に書き込み
+  → イベントを ~/.failproofai/hook-activity.jsonl に永続化
+  → 終了
+```
+
+プロセス全体は、LLM 呼び出しなしで典型的なペイロードに対して 100ms 未満で実行されます。
+
+---
+
+## 設定の読み込み
+
+`src/hooks/hooks-config.ts` が3スコープの設定読み込みを実装しています。
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← プロジェクト（最高優先度）
+[2] {cwd}/.failproofai/policies-config.local.json  ← ローカル
+[3] ~/.failproofai/policies-config.json             ← グローバル（最低優先度）
+```
+
+マージロジック:
+- `enabledPolicies` - 3つのファイル全体で重複排除された和集合
+- `policyParams` - ポリシーごとのキー。最初に定義されたファイルが完全に優先
+- `customPoliciesPath` - 最初に定義されたファイルが優先
+- `llm` - 最初に定義されたファイルが優先
+
+ウェブダッシュボードはプロジェクトの cwd で起動されないため、読み取りと書き込みには `readHooksConfig()`（グローバルのみ）を使用します。
+
+---
+
+## ポリシー評価
+
+`src/hooks/policy-evaluator.ts` がポリシーを順番に実行します。
+
+各ポリシーについて:
+
+1. ポリシーの `params` スキーマを検索します（存在する場合）。
+2. マージされた設定から `policyParams[policy.name]` を読み取ります。
+3. スキーマのデフォルト値にユーザー提供の値をマージして `ctx.params` を生成します。
+4. 解決されたコンテキストと共に `policy.fn(ctx)` を呼び出します。
+5. 結果が `deny` の場合、即座に停止してその決定を返します。
+6. 結果が `instruct` の場合、メッセージを蓄積して続行します。
+7. 結果が `allow` の場合、次のポリシーに進みます。
+
+すべてのポリシーの実行後:
+- `deny` が返された場合、deny レスポンスを出力します。
+- `instruct` の結果が収集された場合、すべてのメッセージを結合した単一の instruct レスポンスを出力します。
+- それ以外の場合、allow レスポンスを出力します（stdout 空、終了コード 0）。
+
+---
+
+## ビルトインポリシー
+
+`src/hooks/builtin-policies.ts` が `BuiltinPolicyDefinition` オブジェクトとして26個のビルトインポリシーをすべて定義しています。
+
+```typescript
+interface BuiltinPolicyDefinition {
+  name: string;
+  description: string;
+  fn: (ctx: PolicyContext) => PolicyResult;
+  match: {
+    events: HookEventType[];
+    tools?: string[];
+  };
+  defaultEnabled: boolean;
+  category: string;
+  beta?: boolean;
+  params?: PolicyParamsSchema;
+}
+```
+
+`params` を受け付けるポリシーは、各パラメーターの型とデフォルト値を含む `PolicyParamsSchema` を宣言します。ポリシーエバリュエーターは `fn` を呼び出す前に解決済みの値を `ctx.params` に注入します。デフォルト値は常に最初に適用されるため、ポリシー関数は null チェックなしで `ctx.params` を読み取ります。
+
+ポリシー内のパターンマッチングは生の文字列マッチングではなく、パース済みのコマンドトークン（argv）を使用します。これにより、シェル演算子の挿入によるバイパスを防ぎます（例: `sudo systemctl status *` のパターンに `; rm -rf /` を追加してもバイパスできません）。
+
+---
+
+## カスタムポリシー
+
+`src/hooks/custom-hooks-registry.ts` が `globalThis` バックのレジストリを実装しています。
+
+```typescript
+const REGISTRY_KEY = "__failproofai_custom_hooks__";
+
+export const customPolicies = {
+  add(hook: CustomHook): void { ... }
+};
+
+export function getCustomHooks(): CustomHook[] { ... }
+export function clearCustomHooks(): void { ... }  // テストで使用
+```
+
+`src/hooks/custom-hooks-loader.ts` がユーザーのポリシーファイルを読み込みます。
+
+1. 設定から `customPoliciesPath` を読み取り、存在しない場合はスキップします。
+2. 絶対パスに解決し、ファイルの存在を確認します。
+3. `customPolicies` が同じ `globalThis` レジストリに解決されるよう、すべての `from "failproofai"` インポートを実際の dist パスに書き換えます。
+4. ESM 互換性を確保するため、推移的なローカルインポートを再帰的に書き換えます。
+5. 一時的な `.mjs` ファイルを書き込み、エントリファイルを `import()` します。
+6. `getCustomHooks()` を呼び出して登録済みフックを取得します。
+7. `finally` ブロックですべての一時ファイルを削除します。
+
+エラー（ファイルが見つからない、構文エラー、インポートの失敗など）が発生した場合、エラーは `~/.failproofai/hook.log` に記録され、ローダーは空の配列を返します。ビルトインポリシーには影響しません。
+
+カスタムポリシーはすべてのビルトインポリシーの後に評価されます。カスタムポリシーの `deny` はそれ以降のカスタムポリシーの実行を短絡させますが（その時点ではすべてのビルトインはすでに実行済みです）。
+
+---
+
+## アクティビティログ
+
+各フックイベントの後、ハンドラーは `~/.failproofai/hook-activity.jsonl` に 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
+}
+```
+
+allow 以外の決定を下したポリシー1件につき1行。allow の決定はログに記録されません（ファイルサイズを小さく保つため）。
+
+---
+
+## ダッシュボードのアーキテクチャ
+
+ダッシュボードは、React Server Components と Server Actions を使用した App Router 採用の **Next.js 16** アプリケーションです。
+
+```text
+app/
+  layout.tsx                  ← ルートレイアウト（テーマ、テレメトリー、ナビゲーション）
+  projects/page.tsx           ← サーバーコンポーネント: すべての Claude プロジェクトを一覧表示
+  project/[name]/page.tsx     ← サーバーコンポーネント: プロジェクト内のセッションを一覧表示
+  project/[name]/session/
+    [sessionId]/page.tsx      ← サーバーコンポーネント: セッションビューアーを表示
+  policies/page.tsx           ← クライアントコンポーネント: ポリシー管理 + アクティビティログ
+  actions/
+    get-hooks-config.ts       ← 設定とポリシーリストの読み取り
+    update-hooks-config.ts    ← ポリシーのオン/オフ切り替え
+    update-policy-params.ts   ← ポリシーパラメーターの更新
+    get-hook-activity.ts      ← アクティビティログのページング/検索
+    install-hooks-web.ts      ← ブラウザからのフックのインストール/削除
+  api/
+    download/[project]/[session]/route.ts   ← セッションを ZIP/JSONL としてエクスポート
+```
+
+**データフロー:**
+
+- ページコンポーネントは `lib/projects.ts` と `lib/log-entries.ts` を呼び出し、ファイルシステムからプロジェクト/セッションデータを直接読み取ります（読み取りに API レイヤーは不要）。
+- ポリシーページはすべての変更操作（切り替え、パラメーター更新、インストール/削除）に Server Actions を使用します。
+- セッションビューアーは Claude の JSONL トランスクリプト形式をパースし、メッセージとツール呼び出しのタイムラインをレンダリングします。
+
+**主要な設計上の決定事項:**
+
+- データベースなし - すべての永続状態はプレーンファイル（`~/.failproofai/`、`~/.claude/projects/`）に保存されます。
+- 変更操作には Server Actions を使用 - CRUD 操作に REST API は不要。
+- 読み取りページには React Server Components を使用 - 初期ロードが高速で、データフェッチのクライアントバンドルが不要。
+- クライアントコンポーネントはインタラクティブ性が必要な場合のみ使用（ポリシーの切り替え、アクティビティ検索、ログビューアー）。
+
+---
+
+## ファイル構成
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI ルーター（フック / ダッシュボード / インストール など）
+├── src/hooks/
+│   ├── handler.ts                # フックイベントパイプライン
+│   ├── builtin-policies.ts       # 26のポリシー定義
+│   ├── policy-evaluator.ts       # ポリシー実行エンジン
+│   ├── policy-registry.ts        # ポリシーの登録と検索
+│   ├── policy-types.ts           # TypeScript インターフェース
+│   ├── hooks-config.ts           # マルチスコープ設定読み込み
+│   ├── custom-hooks-registry.ts  # globalThis バックのフックレジストリ
+│   ├── custom-hooks-loader.ts    # ユーザー JS フック用の ESM ローダー
+│   ├── manager.ts                # インストール / 削除 / 一覧操作
+│   ├── install-prompt.ts         # インタラクティブなポリシー選択プロンプト
+│   ├── hook-logger.ts            # hook.log へのロギング
+│   ├── hook-activity-store.ts    # hook-activity.jsonl へのアクティビティの永続化
+│   └── llm-client.ts             # LLM API クライアント（AI 搭載ポリシー用）
+├── app/                          # Next.js ダッシュボード（ページ + サーバーアクション）
+├── lib/                          # 共有ユーティリティ
+│   ├── projects.ts               # ファイルシステムから Claude プロジェクトを列挙
+│   ├── log-entries.ts            # Claude トランスクリプトの JSONL 形式をパース
+│   ├── paths.ts                  # システムパスの解決
+│   └── ...
+├── components/                   # 共有 React UI コンポーネント
+├── contexts/                     # React コンテキストプロバイダー（テーマ、自動更新、テレメトリー）
+├── examples/                     # カスタムフックファイルの例
+└── __tests__/                    # ユニットテストと E2E テスト
+```