failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,82 @@
+---
+title: Paket Takma Adları
+description: "Kayıtlı yazım hatası önleme takma adları ve nasıl çalıştıkları"
+icon: copy
+---
+
+## Resmi paket
+
+Kanonik npm paketi **`failproofai`**'dir:
+
+```bash
+npm install -g failproofai
+# or
+bun add -g failproofai
+```
+
+---
+
+## Neden takma ad adlarına sahibiz
+
+Yazım hatası saldırısı (typosquatting), kötü niyetli bir aktörün popüler bir pakete sadece bir tuş uzakta olan bir paket adını kaydettiği yaygın bir tedarik zinciri saldırısıdır. Kurulum komutunu yanlış yazan kullanıcılar, saldırgan tarafından kontrol edilen kodu tam sistem erişimi ile çalıştırmaya maruz kalır - tam olarak Failproof AI'nin savunması için tasarlandığı tür bir tehdit.
+
+Bu riski ortadan kaldırmak için **`failproofai`'nin tüm yaygın yazım hatalarını ve biçimlendirme varyasyonlarının sahibiyiz** npm'de. Bu adların hiçbiri üçüncü bir taraf tarafından kaydettilemez. Her biri gerçek `failproofai` paketini yükleyen ve çalıştıran ince bir vekil (proxy) görevi görür.
+
+---
+
+## Kayıtlı takma adları
+
+**Biçimlendirme varyasyonları** - "failproof ai" yazmanın farklı yolları:
+
+| Paket | Durum |
+|---------|--------|
+| `failproof` | ✅ Yayınlandı |
+| `failproof-ai` | ⏳ npm desteği bekleniyor |
+| `fail-proof-ai` | ⏳ npm desteği bekleniyor |
+| `failproof_ai` | ⏳ npm desteği bekleniyor |
+| `fail_proof_ai` | ⏳ npm desteği bekleniyor |
+| `fail-proofai` | ⏳ npm desteği bekleniyor |
+
+**`failprof*` yazım hatası** - "proof"tan bir `o` eksik:
+
+| Paket | Durum |
+|---------|--------|
+| `failprof` | ✅ Yayınlandı |
+| `failprof-ai` | ✅ Yayınlandı |
+| `failprofai` | ⏳ npm desteği bekleniyor |
+| `fail-prof-ai` | ⏳ npm desteği bekleniyor |
+| `failprof_ai` | ⏳ npm desteği bekleniyor |
+
+**`faliproof*` yazım hatası** - `a` ve `i` yer değiştirilmiş:
+
+| Paket | Durum |
+|---------|--------|
+| `faliproof` | ✅ Yayınlandı |
+| `faliproof-ai` | ✅ Yayınlandı |
+| `faliproofai` | ⏳ npm desteği bekleniyor |
+
+> **Neden bekleniyor?** npm'nin spam önleme politikası, noktalama işaretleri kaldırıldığında ve benzerlik kontrolleri yapıldığında mevcut bir paketleyle aynı dizgeye normalleşen adları engeller. Bu adları anti-squatting amaçlarıyla kaydetmek için npm desteğine başvurduk. Onaylandığında etkinleştirileceklerdir.
+
+Yayınlanan herhangi bir takma adın bize ait olduğunu doğrulayabilirsiniz:
+
+```bash
+npm info failproof
+# Bak: maintainers alanında "ExosphereHost Inc."
+```
+
+---
+
+## Takma adları nasıl çalışır
+
+Her takma ad paketi:
+
+1. `failproofai`'yi bir bağımlılık olarak listeler - böylece gerçek paket (kendi `postinstall` kancası kurulumu dahil) yüklenirken çalışır
+2. Kendi adıyla eşleşen bir ikili dosyayı ortaya çıkarır (örn. `failprof-ai`) ve tüm argümanları `failproofai` ikili dosyasına yönlendirir
+
+Vekil, iki satırlı bir Node.js komut dosyasıdır; `failproofai`'nin kendisinin yaptığından başka hiçbir mantık, ağ çağrısı ve veri toplaması yoktur.
+
+---
+
+## Atladığımız bir ad bulursanız
+
+[exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) adresinde bir sorun açın ve biz onu kaydettireceğiz.

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

@@ -0,0 +1,260 @@
+---
+title: Test Etme
+description: "Birim testleri, uçtan uca testleri ve test yardımcıları"
+icon: flask-vial
+---
+
+failproofai iki test paketi içerir: **birim testleri** (hızlı, simüle edilmiş) ve **uçtan uca testleri** (gerçek alt işlem çağırmaları).
+
+---
+
+## Testleri çalıştırma
+
+```bash
+# Tüm birim testlerini bir kez çalıştır
+bun run test:run
+
+# Birim testlerini izleme modunda çalıştır
+bun run test
+
+# E2E testlerini çalıştır (setup gerektirir - aşağıya bakın)
+bun run test:e2e
+
+# Derlemeden tip kontrolü yap
+bunx tsc --noEmit
+
+# Lint
+bun run lint
+```
+
+---
+
+## Birim testleri
+
+Birim testleri `__tests__/` içinde bulunur ve [Vitest](https://vitest.dev) ile `happy-dom` kullanır.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Her yerleşik ilke için ilke mantığı
+    hooks-config.test.ts          # Yapılandırma yükleme ve kapsam birleştirme
+    policy-evaluator.test.ts      # Parametre enjeksiyonu ve değerlendirme sırası
+    custom-hooks-registry.test.ts # globalThis kayıt defteri ekleme/alma/temizleme
+    custom-hooks-loader.test.ts   # ESM yükleyici, geçişli içeri aktarmalar, hata işleme
+    manager.test.ts               # kurulum/kaldırma/listeleme işlemleri
+  components/
+    sessions-list.test.tsx        # Oturum listesi bileşeni
+    project-list.test.tsx         # Proje listesi bileşeni
+    ...
+  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
+```
+
+### İlke birim testi yazma
+
+```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("sudo komutlarını reddeder", () => {
+    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("sudo olmayan komutlara izin verir", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allowPatterns içindeki desenlere izin verir", () => {
+    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());
+  });
+});
+```
+
+---
+
+## Uçtan uca testleri
+
+E2E testleri gerçek `failproofai` ikilisini alt işlem olarak çağırır, JSON yükünü stdin'e aktarır ve stdout çıkışı ile çıkış kodu üzerinde doğrulamalar yapar. Bu, Claude Code'un kullandığı tam entegrasyon yolunu test eder.
+
+### Setup
+
+E2E testleri doğrudan depo kaynağından ikiliyi çalıştırır. İlk çalıştırmadan önce, özel kanca dosyalarının `'failproofai'`'den içeri aktarırken kullanacağı CJS paketini oluşturun:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Ardından testleri çalıştırın:
+
+```bash
+bun run test:e2e
+```
+
+Genel kanca API'sini değiştirdiğinizde `dist/` öğesini yeniden oluşturun (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` veya `src/hooks/policy-types.ts`).
+
+### E2E test yapısı
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # İkiliyi oluştur, yük JSON'unu aktar, çıkış kodu + stdout + stderr'ı yakala
+    fixture-env.ts      # Test başına izole edilen geçici dizinler yapılandırma dosyalarıyla
+    payloads.ts         # Her olay türü için Claude'a uygun yük fabrikaları
+  hooks/
+    builtin-policies.e2e.test.ts   # Her yerleşik ilke gerçek alt işlemle
+    custom-hooks.e2e.test.ts       # Özel kanca yükleme ve değerlendirmesi
+    config-scopes.e2e.test.ts      # Proje/yerel/genel arasında yapılandırma birleştirme
+    policy-params.e2e.test.ts      # Her parametreli ilke için parametre enjeksiyonu
+```
+
+### E2E yardımcılarını kullanma
+
+**`FixtureEnv`** - test başına izole ortam:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - geçici dizin; .failproofai/policies-config.json'ı almak için payload.cwd olarak geçir
+// env.home   - izole ev dizini; gerçek ~/.failproofai sızıntıya uğramaz
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` `afterEach` temizlemesini otomatik olarak kaydeder.
+
+**`runHook`** - ikiliyi çağır:
+
+```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`** - hazır yük fabrikaları:
+
+```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 testi yazma
+
+```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("rm -rf'yi reddeder", 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("özyinelemeli olmayan rm'ye izin verir", 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("");  // izin ver → boş stdout
+  });
+});
+```
+
+### E2E yanıt şekilleri
+
+| Karar | Çıkış kodu | stdout |
+|----------|-----------|--------|
+| `PreToolUse` reddet | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` reddet | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Talimati (Stop olmayan) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop talimatı | `2` | boş stdout; neden stderr'de |
+| İzin ver | `0` | boş dize |
+
+### Vitest yapılandırması
+
+E2E testleri `vitest.config.e2e.mts` kullanır:
+
+- `environment: "node"` - tarayıcı globalleri gerekli değil
+- `pool: "forks"` - gerçek işlem izolasyonu (testler alt işlemler oluşturur)
+- `testTimeout: 20_000` - test başına 20 saniye (ikili başlatma + kanca değerlendirmesi)
+
+`forks` havuzu önemlidir: iş parçacığı tabanlı işçiler `globalThis` paylaşırlar ve bu, alt işlem oluşturan testleri etkileyebilir. İşlem tabanlı çatallama bunu önler.
+
+---
+
+## CI
+
+Birleştirmeden önce tam CI çalıştırması (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) geçmesi gerekir. E2E paketi paralel olarak ayrı bir CI işinde çalışır.
+
+Tam ön birleştirme kontrol listesi için [Contributing](../CONTRIBUTING.md) bölümüne bakın.

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

@@ -0,0 +1,333 @@
+---
+---
+title: Kiến trúc
+description: "Cách hook handler, config loading, và policy evaluation hoạt động bên trong"
+icon: sitemap
+---
+
+Tài liệu này giải thích cách failproofai hoạt động bên trong: cách hệ thống hook chặn các lệnh gọi tool của agent, cách cấu hình được tải và hợp nhất, cách các chính sách được đánh giá, và cách dashboard giám sát hoạt động của agent.
+
+---
+
+## Tổng quan
+
+failproofai có hai subsystem độc lập:
+
+1. **Hook handler** - Một CLI subprocess nhanh mà Claude Code gọi trên mỗi lệnh gọi tool của agent. Đánh giá các chính sách và trả về một quyết định.
+2. **Agent Monitor (Dashboard)** - Một ứng dụng web Next.js để giám sát các session agent và quản lý các chính sách.
+
+Cả hai subsystem chia sẻ các tệp cấu hình trong `~/.failproofai/` và thư mục `.failproofai/` của dự án, nhưng chúng chạy dưới dạng các process riêng biệt và chỉ giao tiếp thông qua hệ thống tệp.
+
+---
+
+## Hook handler
+
+### Tích hợp với Claude Code
+
+Khi bạn chạy `failproofai policies --install`, nó sẽ ghi các mục như thế này vào `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code sau đó gọi `failproofai --hook PreToolUse` dưới dạng một subprocess trước mỗi lệnh gọi tool, truyền một payload JSON trên stdin.
+
+### Định dạng 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" }
+}
+```
+
+Đối với các sự kiện `PostToolUse`, payload cũng chứa `tool_result` với kết quả đầu ra của tool.
+
+Handler thực thi giới hạn 1 MB cho stdin. Các payload vượt quá giới hạn này bị loại bỏ và tất cả các chính sách được phép một cách ngầm.
+
+### Định dạng phản hồi
+
+**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 (bất kỳ sự kiện nào ngoại trừ Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Stop event instruct:**
+- Mã thoát: `2`
+- Lý do được ghi vào stderr (không phải stdout)
+
+**Allow:**
+- Mã thoát: `0`
+- Stdout trống
+
+**Allow with message (beta):**
+
+Kể từ v0.0.2-beta.3, `allow(message)` cho phép một chính sách gửi context thông tin trở lại Claude ngay cả khi thao tác được cho phép. Hook handler ghi JSON sau đây vào **stdout** (không phải một tệp cấu hình — đây là phản hồi của handler process đối với Claude Code, giống như các phản hồi deny và instruct ở trên):
+
+```json
+// Được ghi vào stdout bởi hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Mã thoát: `0` (thao tác được cho phép)
+- Khi nhiều chính sách trả về `allow` với một thông báo, các thông báo của chúng được nối với ký tự xuống dòng thành một chuỗi `additionalContext` duy nhất
+- Nếu không có chính sách nào cung cấp một thông báo, stdout trống (giống như trước đây)
+
+### Processing pipeline
+
+`src/hooks/handler.ts` triển khai toàn bộ pipeline:
+
+```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
+```
+
+Toàn bộ quá trình chạy trong dưới 100ms cho các payload điển hình mà không có lệnh gọi LLM.
+
+---
+
+## Configuration loading
+
+`src/hooks/hooks-config.ts` triển khai config loading ba phạm vi.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← project  (highest priority)
+[2] {cwd}/.failproofai/policies-config.local.json  ← local
+[3] ~/.failproofai/policies-config.json             ← global   (lowest priority)
+```
+
+Merge logic:
+- `enabledPolicies` - union không trùng lặp trên cả ba tệp
+- `policyParams` - mỗi chính sách là một key, tệp đầu tiên xác định nó sẽ giành toàn bộ
+- `customPoliciesPath` - tệp đầu tiên xác định nó sẽ giành
+- `llm` - tệp đầu tiên xác định nó sẽ giành
+
+Dashboard web sử dụng `readHooksConfig()` (chỉ global) để đọc và ghi, vì nó không được gọi với một project cwd.
+
+---
+
+## Policy evaluation
+
+`src/hooks/policy-evaluator.ts` chạy các chính sách theo thứ tự.
+
+Đối với mỗi chính sách:
+
+1. Tìm kiếm schema `params` của chính sách (nếu có).
+2. Đọc `policyParams[policy.name]` từ config đã hợp nhất.
+3. Hợp nhất các giá trị do người dùng cung cấp trên các giá trị mặc định của schema để tạo ra `ctx.params`.
+4. Gọi `policy.fn(ctx)` với context đã được giải quyết.
+5. Nếu kết quả là `deny`, dừng ngay lập tức và trả về quyết định đó.
+6. Nếu kết quả là `instruct`, tích lũy thông báo và tiếp tục.
+7. Nếu kết quả là `allow`, tiếp tục đến chính sách tiếp theo.
+
+Sau khi tất cả các chính sách chạy:
+- Nếu bất kỳ `deny` nào được trả về, phát ra phản hồi deny.
+- Nếu bất kỳ kết quả `instruct` nào được thu thập, phát ra một phản hồi instruct duy nhất với tất cả các thông báo được nối.
+- Nếu không, phát ra một phản hồi allow (stdout trống, exit 0).
+
+---
+
+## Builtin policies
+
+`src/hooks/builtin-policies.ts` định nghĩa tất cả 26 chính sách tích hợp dưới dạng các đối tượng `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;
+}
+```
+
+Các chính sách chấp nhận `params` khai báo một `PolicyParamsSchema` với các kiểu và giá trị mặc định cho mỗi tham số. Policy evaluator tiêm các giá trị đã được giải quyết vào `ctx.params` trước khi gọi `fn`. Các hàm chính sách đọc `ctx.params` mà không cần null-guard vì các giá trị mặc định luôn được áp dụng trước.
+
+Khớp mẫu bên trong các chính sách sử dụng các command token được phân tích cú pháp (argv), không phải khớp chuỗi thô. Điều này ngăn chặn bypass thông qua shell operator injection (ví dụ: một mẫu cho `sudo systemctl status *` không thể bị bypass bằng cách thêm `; rm -rf /` vào command).
+
+---
+
+## Custom policies
+
+`src/hooks/custom-hooks-registry.ts` triển khai một registry hỗ trợ bởi `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` tải tệp chính sách của người dùng:
+
+1. Đọc `customPoliciesPath` từ cấu hình; bỏ qua nếu không có.
+2. Giải quyết đến đường dẫn tuyệt đối; kiểm tra xem tệp có tồn tại.
+3. Viết lại tất cả các import `from "failproofai"` đến đường dẫn dist thực tế để `customPolicies` giải quyết đến cùng một registry `globalThis`.
+4. Viết lại đệ quy các import cục bộ chuyển tiếp để đảm bảo khả năng tương thích ESM.
+5. Ghi các tệp `.mjs` tạm thời và `import()` tệp entry.
+6. Gọi `getCustomHooks()` để truy xuất các hook đã đăng ký.
+7. Dọn sạch tất cả các tệp tạm thời trong một khối `finally`.
+
+Đối với bất kỳ lỗi nào (tệp không tìm thấy, lỗi cú pháp, lỗi import), lỗi được ghi nhật ký vào `~/.failproofai/hook.log` và loader trả về một mảng trống. Các chính sách tích hợp không bị ảnh hưởng.
+
+Các chính sách tùy chỉnh được đánh giá sau tất cả các chính sách tích hợp. Một chính sách tùy chỉnh `deny` vẫn short-circuit các chính sách tùy chỉnh tiếp theo (nhưng tất cả các tích hợp đã chạy ở thời điểm này).
+
+---
+
+## Activity logging
+
+Sau mỗi sự kiện hook, handler nối một dòng JSONL vào `~/.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
+}
+```
+
+Một dòng cho mỗi chính sách đã đưa ra quyết định không phải allow. Các quyết định Allow không được ghi nhật ký (để giữ tệp nhỏ).
+
+---
+
+## Dashboard architecture
+
+Dashboard là một ứng dụng **Next.js 16** sử dụng App Router với React Server Components và Server Actions.
+
+```text
+app/
+  layout.tsx                  ← Root layout (theme, telemetry, nav)
+  projects/page.tsx           ← Server component: list all Claude projects
+  project/[name]/page.tsx     ← Server component: list sessions in a project
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Server component: render session viewer
+  policies/page.tsx           ← Client component: policy management + activity log
+  actions/
+    get-hooks-config.ts       ← Read config + policy list
+    update-hooks-config.ts    ← Toggle policy on/off
+    update-policy-params.ts   ← Update policy parameters
+    get-hook-activity.ts      ← Paginate/search activity log
+    install-hooks-web.ts      ← Install/remove hooks from the browser
+  api/
+    download/[project]/[session]/route.ts   ← Export session as ZIP/JSONL
+```
+
+**Data flow:**
+
+- Các trang component gọi `lib/projects.ts` và `lib/log-entries.ts` để đọc dữ liệu dự án/session trực tiếp từ hệ thống tệp (không có lớp API cho việc đọc).
+- Trang Policies sử dụng Server Actions cho tất cả các mutations (toggle, params update, install/remove).
+- Session viewer phân tích định dạng transcript JSONL của Claude và hiển thị một timeline của các thông báo và lệnh gọi tool.
+
+**Key design decisions:**
+
+- Không có database - tất cả trạng thái persistent nằm trong các tệp thuần túy (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions cho mutations - không cần REST API cho các thao tác CRUD.
+- React Server Components cho các trang đọc - tải lần đầu nhanh hơn, không có client bundle cho việc tìm nạp dữ liệu.
+- Client components chỉ khi cần tương tác (policy toggles, activity search, log viewer).
+
+---
+
+## File layout
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Hook event pipeline
+│   ├── builtin-policies.ts       # 26 policy definitions
+│   ├── policy-evaluator.ts       # Policy execution engine
+│   ├── policy-registry.ts        # Policy registration and lookup
+│   ├── policy-types.ts           # TypeScript interfaces
+│   ├── hooks-config.ts           # Multi-scope config loading
+│   ├── custom-hooks-registry.ts  # globalThis-backed hook registry
+│   ├── custom-hooks-loader.ts    # ESM loader for user JS hooks
+│   ├── manager.ts                # install / remove / list operations
+│   ├── install-prompt.ts         # Interactive policy selection prompt
+│   ├── hook-logger.ts            # Logging to hook.log
+│   ├── hook-activity-store.ts    # Persist activity to hook-activity.jsonl
+│   └── llm-client.ts             # LLM API client (for AI-powered policies)
+├── app/                          # Next.js dashboard (pages + server actions)
+├── lib/                          # Shared utilities
+│   ├── projects.ts               # Enumerate Claude projects from filesystem
+│   ├── log-entries.ts            # Parse Claude transcript JSONL format
+│   ├── paths.ts                  # Resolve system paths
+│   └── ...
+├── components/                   # Shared React UI components
+├── contexts/                     # React context providers (theme, auto-refresh, telemetry)
+├── examples/                     # Example custom hook files
+└── __tests__/                    # Unit and E2E tests
+```