failproofai 0.0.5 → 0.0.6-beta.1

package/.next/standalone/docs/tr/custom-policies.mdx

@@ -1,10 +1,11 @@
 ---
-title: Özel Politikalar
-description: "JavaScript'te kendi politikalarınızı yazın - kuralları uygulayın, sapmayı önleyin, hataları algılayın, harici sistemlerle entegre olun"
+---
+title: Özel İlkeler
+description: "JavaScript'te kendi ilkelerinizi yazın - kuralları uygulayın, kaymaları önleyin, arızaları tespit edin, dış sistemlerle entegre olun"
 icon: code
 ---
 
-Özel politikalar, herhangi bir agent davranışı için kurallar yazmanıza izin verir: proje kurallarını uygulayın, sapmayı önleyin, yıkıcı işlemleri engelle, sıkışmış aracıları algılayın veya Slack, onay iş akışları ve daha fazlasıyla entegre olun. Yerleşik politikalarla aynı hook etkinliği sistemini ve `allow`, `deny`, `instruct` kararlarını kullanırlar.
+Özel ilkeler, herhangi bir agent davranışı için kurallar yazmanıza izin verir: proje kurallarını uygulayın, kaymaları önleyin, yıkıcı işlemleri engelleyin, takılmış agent'ları tespit edin veya Slack, onay iş akışları ve daha fazlasıyla entegre olun. Yerleşik ilkelerle aynı hook event sistemini ve `allow`, `deny`, `instruct` kararlarını kullanırlar.
 
 ---
 
@@ -37,14 +38,14 @@ failproofai policies --install --custom ./my-policies.js
 
 ---
 
-## Özel politikaları yüklemenin iki yolu
+## Özel ilkeleri yüklemenin iki yolu
 
-### Seçenek 1: Kural tabanlı (önerilen)
+### Seçenek 1: Kural tabanlı (önerilir)
 
-`.failproofai/policies/` dizinine `*policies.{js,mjs,ts}` dosyalarını bırakın ve otomatik olarak yüklenirler — hiçbir bayrak veya yapılandırma değişikliğine gerek yoktur. Bu git hook'ları gibi çalışır: bir dosya bırakın ve çalışır.
+`*policies.{js,mjs,ts}` dosyalarını `.failproofai/policies/` dizinine bırakın ve otomatik olarak yüklenir — bayrak veya yapılandırma değişikliğine gerek yoktur. Bu, git hook'ları gibi çalışır: bir dosya bırakın, çalışır.
 
 ```
-# Proje düzeyi — git'e kaydedilir, ekiple paylaşılır
+# Proje düzeyi — git'e kaydedilir, takımla paylaşılır
 .failproofai/policies/security-policies.mjs
 .failproofai/policies/workflow-policies.mjs
 
@@ -53,38 +54,38 @@ failproofai policies --install --custom ./my-policies.js
 ```
 
 **Nasıl çalışır:**
-- Hem proje hem de kullanıcı dizinleri taranır (birleşim — ilk-kapsam-kazanır değil)
-- Dosyalar her dizin içinde alfabetik olarak yüklenir. Sırayı kontrol etmek için `01-`, `02-` ile önekleyin
+- Hem proje hem de kullanıcı dizinleri taranır (birleşim — ilk kapsam kazanmaz)
+- Dosyalar her dizin içinde alfabetik olarak yüklenir. Sırayı kontrol etmek için `01-`, `02-` ön eki ekleyin
 - Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir; diğer dosyalar yoksayılır
-- Her dosya bağımsız olarak yüklenir (dosya başına açık-fail)
-- Açık `--custom` ve yerleşik politikalarla birlikte çalışır
+- Her dosya bağımsız olarak yüklenir (dosya başına açık başarısızlık)
+- Açık `--custom` ve yerleşik ilkelerle birlikte çalışır
 
 <Tip>
-Kural politikaları, politikaları bir ekip genelinde paylaşmanın en kolay yoludur. `.failproofai/policies/` öğesini git'e işleyin ve her takım üyesi otomatik olarak bunları alır.
+Kural tabanlı ilkeler, ilkeleri bir takım arasında paylaşmanın en kolay yoludur. `.failproofai/policies/` öğesini git'e gönderin ve her takım üyesi otomatik olarak bunları alır.
 </Tip>
 
 ### Seçenek 2: Açık dosya yolu
 
 ```bash
-# Özel politika dosyasıyla yükleyin
+# Özel ilkeler dosyasıyla yükleyin
 failproofai policies --install --custom ./my-policies.js
 
-# Politika dosyasının yolunu değiştirin
+# İlkeler dosya yolunu değiştirin
 failproofai policies --install --custom ./new-policies.js
 
-# Yapılandırmadan özel politika yolunu kaldırın
+# Yapılandırmadan özel ilkeler yolunu kaldırın
 failproofai policies --uninstall --custom
 ```
 
-Çözümlenen mutlak yol, `policies-config.json` içinde `customPoliciesPath` olarak depolanır. Dosya her hook etkinliğinde yeniden yüklenir - olaylar arasında önbellekleme yoktur.
+Çözümlenen mutlak yol, `policies-config.json` öğesine `customPoliciesPath` olarak depolanır. Dosya her hook event'i sırasında yeni yüklenir - event'ler arasında hiçbir önbelleğe alma yoktur.
 
 ### Her ikisini birlikte kullanma
 
-Kural politikaları ve açık `--custom` dosyası birlikte varolabilir. Yükleme sırası:
+Kural tabanlı ilkeler ve açık `--custom` dosyası bir arada bulunabilir. Yükleme sırası:
 
 1. Açık `customPoliciesPath` dosyası (yapılandırılmışsa)
-2. Proje kural dosyaları (`{cwd}/.failproofai/policies/`, alfabetik)
-3. Kullanıcı kural dosyaları (`~/.failproofai/policies/`, alfabetik)
+2. Proje kural tabanlı dosyaları (`{cwd}/.failproofai/policies/`, alfabetik)
+3. Kullanıcı kural tabanlı dosyaları (`~/.failproofai/policies/`, alfabetik)
 
 ---
 
@@ -98,13 +99,13 @@ import { customPolicies, allow, deny, instruct } from "failproofai";
 
 ### `customPolicies.add(hook)`
 
-Bir politikayı kaydeder. Aynı dosyada birden çok politika için gerektiği kadar çağırın.
+Bir ilkeyi kaydeder. Aynı dosyada birden fazla ilke için gerektiği kadar çağırın.
 
 ```ts
 customPolicies.add({
-  name: string;                         // zorunlu - benzersiz tanımlayıcı
+  name: string;                         // gerekli - benzersiz tanımlayıcı
   description?: string;                 // `failproofai policies` çıktısında gösterilir
-  match?: { events?: HookEventType[] }; // etkinlik türüne göre filtrele; tümünü eşleştirmek için atlayın
+  match?: { events?: HookEventType[] }; // event türüne göre filtre; tümüyle eşleştirmek için atla
   fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
 });
 ```
@@ -113,31 +114,30 @@ customPolicies.add({
 
 | İşlev | Etki | Ne zaman kullanılır |
 |----------|--------|----------|
-| `allow()` | İşleme sessizce izin ver | İşlem güvenli, mesaj gerekmez |
+| `allow()` | İşleme izin ver sessizce | İşlem güvenli, ileti gerekmez |
 | `deny(message)` | İşlemi engelle | Agent bu işlemi yapmamalı |
-| `instruct(message)` | Bloklamadan bağlam ekle | Agent'a yolunda kalması için ekstra bağlam ver |
+| `instruct(message)` | Engellemeden bağlam ekle | Agent'a yolunda kalmak için ek bağlam ver |
 
-`deny(message)` - ileti Claude'a `"Blocked by failproofai:"` ön eki ile görünür. Tek bir `deny` tüm diğer değerlendirmeleri kısaltır.
+`deny(message)` - ileti Claude'a `"Blocked by failproofai:"` ön ekiyle görünür. Tek bir `deny`, tüm sonraki değerlendirmeleri kısaltır.
 
-`instruct(message)` - ileti, Claude'un geçerli araç çağrısı için bağlamına eklenir. Tüm `instruct` iletileri biriktirilir ve birlikte iletilir.
+`instruct(message)` - ileti, geçerli araç çağrısı için Claude'un bağlamına eklenir. Tüm `instruct` iletileri biriktirilir ve birlikte teslim edilir.
 
 <Tip>
-`policyParams` içinde `hint` alanı ekleyerek herhangi bir `deny` veya `instruct` iletisine ekstra rehberlik ekleyebilirsiniz — kod değişikliğine gerek yoktur. Bu özel (`custom/`), proje kural (`.failproofai-project/`) ve kullanıcı kural (`.failproofai-user/`) politikaları için de çalışır. Ayrıntılar için [Yapılandırma → hint](/tr/configuration#hint-cross-cutting) bölümüne bakın.
+Kod değişikliğine gerek olmadan `policyParams` öğesinde bir `hint` alanı ekleyerek herhangi bir `deny` veya `instruct` iletisine ek rehberlik ekleyebilirsiniz. Bu, özel (`custom/`), proje kuralı (`.failproofai-project/`), ve kullanıcı kuralı (`.failproofai-user/`) ilkeleri için de çalışır. Ayrıntılar için bkz. [Yapılandırma → hint](/tr/configuration#hint-cross-cutting).
 </Tip>
 
-### Bilgilendirici izin iletileri
-
+### Bilgisel izin iletileri
 
-`allow(message)` işleme izin verir **ve** Claude'a bilgilendirici bir ileti gönderir. İleti, hook işleyicisinin stdout yanıtında `additionalContext` olarak iletilir — `instruct` tarafından kullanılan mekanizmayla aynı, ancak anlamsal olarak farklı: bir uyarı değil, bir durum güncellemesidir.
+`allow(message)` işleme izin verir **ve** Claude'a geri bilgisel bir ileti gönderir. İleti, hook handler'ın stdout yanıtında `additionalContext` olarak teslim edilir — `instruct` tarafından kullanılan aynı mekanizma, ancak anlamsal olarak farklıdır: bir uyarı değil, bir durum güncellemesidir.
 
 | İşlev | Etki | Ne zaman kullanılır |
 |----------|--------|----------|
-| `allow(message)` | İzin ver ve Claude'a bağlam gönder | Bir kontrol geçmesini onaylayın veya bir kontrol neden atlandığını açıklayın |
+| `allow(message)` | İzin ver ve Claude'a bağlam gönder | Bir kontrolün geçtiğini doğrula veya neden atlandığını açıkla |
 
-Kullanım örnekleri:
+Kullanım durumları:
 - **Durum onayları:** `allow("All CI checks passed.")` — Claude'a her şeyin yeşil olduğunu söyler
-- **Fail-open açıklamaları:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude'a bir kontrol neden atlandığını söyler, böylece tam bağlama sahiptir
-- **Birden çok ileti birikir:** birden çok politika `allow(message)` döndürürse, tüm iletiler yeni satırlarla birleştirilir ve birlikte iletilir
+- **Açık başarısızlık açıklamaları:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude'a bir kontrolün neden atlandığını söyler böylece tam bağlama sahip olur
+- **Birden fazla ileti birikir:** birkaç ilke her biri `allow(message)` döndürürse, tüm iletiler yeni satırlarla birleştirilir ve birlikte teslim edilir
 
 ```js
 customPolicies.add({
@@ -147,7 +147,7 @@ customPolicies.add({
     const cwd = ctx.session?.cwd;
     if (!cwd) return allow("No working directory, skipping branch check.");
 
-    // ... branch durumunu kontrol et ...
+    // ... check branch status ...
     if (allPushed) {
       return allow("Branch is up to date with remote.");
     }
@@ -161,9 +161,9 @@ customPolicies.add({
 | Alan | Tür | Açıklama |
 |-------|------|-------------|
 | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | Çağrılan araç (örn. `"Bash"`, `"Write"`, `"Read"`) |
-| `toolInput` | `Record<string, unknown> \| undefined` | Aracının giriş parametreleri |
-| `payload` | `Record<string, unknown>` | Claude Code'dan tam ham olay yükü |
+| `toolName` | `string \| undefined` | Çağrılan araç (ör. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Aracın giriş parametreleri |
+| `payload` | `Record<string, unknown>` | Claude Code'dan tam ham event payload |
 | `session` | `SessionMetadata \| undefined` | Oturum bağlamı (aşağıya bakın) |
 
 ### `SessionMetadata` alanları
@@ -172,37 +172,37 @@ customPolicies.add({
 |-------|------|-------------|
 | `sessionId` | `string` | Claude Code oturum tanımlayıcısı |
 | `cwd` | `string` | Claude Code oturumunun çalışma dizini |
-| `transcriptPath` | `string` | Oturumun JSONL transkript dosyasının yolu |
+| `transcriptPath` | `string` | Oturumun JSONL transcript dosyasının yolu |
 
-### Etkinlik türleri
+### Event türleri
 
-| Etkinlik | Ne zaman ateşlenir | `toolInput` içeriği |
+| Event | Ne zaman çalışır | `toolInput` içeriği |
 |-------|--------------|----------------------|
-| `PreToolUse` | Claude bir aracı çalıştırmadan önce | Aracının girdisi (örn. Bash için `{ command: "..." }`) |
-| `PostToolUse` | Bir araç tamamlandıktan sonra | Aracının girdisi + `tool_result` (çıktı) |
-| `Notification` | Claude bir bildirim gönderdiğinde | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hook'lar her zaman `allow()` döndürmelidir, bildirimleri bloklamaz |
+| `PreToolUse` | Claude bir aracı çalıştırmadan önce | Aracın girdisi (ör. Bash için `{ command: "..." }`) |
+| `PostToolUse` | Bir araç tamamlandıktan sonra | Aracın girdisi + `tool_result` (çıktı) |
+| `Notification` | Claude bir bildirim gönderdiğinde | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hook'lar her zaman `allow()` döndürmelidir, bildirimleri engelleyemezler |
 | `Stop` | Claude oturumu sona erdiğinde | Boş |
 
 ---
 
 ## Değerlendirme sırası
 
-Politikalar şu sırayla değerlendirilir:
+İlkeler şu sırayla değerlendirilir:
 
-1. Yerleşik politikalar (tanım sırasında)
-2. `customPoliciesPath` öğesinden açık özel politikalar (`.add()` sırasında)
-3. Proje `.failproofai/policies/` öğesinden kural politikaları (dosyalar alfabetik, içinde `.add()` sırası)
-4. Kullanıcı `~/.failproofai/policies/` öğesinden kural politikaları (dosyalar alfabetik, içinde `.add()` sırası)
+1. Yerleşik ilkeler (tanım sırasında)
+2. `customPoliciesPath` öğesinden açık özel ilkeler (.add() sırasında)
+3. Proje `.failproofai/policies/` öğesinden kural ilkeleri (dosyalar alfabetik, .add() sırasında)
+4. Kullanıcı `~/.failproofai/policies/` öğesinden kural ilkeleri (dosyalar alfabetik, .add() sırasında)
 
 <Note>
-İlk `deny` tüm sonraki politikaları kısaltır. Tüm `instruct` iletileri biriktirilir ve birlikte iletilir.
+İlk `deny`, sonraki tüm ilkeleri kısaltır. Tüm `instruct` iletileri biriktirilir ve birlikte teslim edilir.
 </Note>
 
 ---
 
 ## Geçişli içe aktarmalar
 
-Özel politika dosyaları göreli yolları kullanan yerel modülleri içe aktarabilir:
+Özel ilke dosyaları, göreceli yollar kullanarak yerel modülleri içe aktarabilir:
 
 ```js
 // my-policies.js
@@ -219,46 +219,46 @@ customPolicies.add({
 });
 ```
 
-Giriş dosyasından erişilebilen tüm göreli içe aktarmalar çözülür. Bu, `from "failproofai"` içe aktarmalarını gerçek dist yoluna yeniden yazarak ve ESM uyumluluğunu sağlamak için geçici `.mjs` dosyaları oluşturarak uygulanır.
+Giriş dosyasından ulaşılabilir tüm göreceli içe aktarmalar çözümlenir. Bu, `from "failproofai"` içe aktarmalarını gerçek dist yoluna yeniden yazarak ve ESM uyumluluğunu sağlamak için geçici `.mjs` dosyaları oluşturarak uygulanır.
 
 ---
 
-## Etkinlik türü filtrelemesi
+## Event türü filtrelemesi
 
-Bir politikanın ne zaman ateşlendiğini sınırlamak için `match.events` öğesini kullanın:
+Bir ilkenin ne zaman çalıştığını sınırlandırmak için `match.events` kullanın:
 
 ```js
 customPolicies.add({
   name: "require-summary-on-stop",
   match: { events: ["Stop"] },
   fn: async (ctx) => {
-    // Yalnızca oturum sona erdiğinde ateşlenir
+    // Yalnızca oturum sona erdiğinde çalışır
     // ctx.session.transcriptPath tam oturum günlüğünü içerir
     return allow();
   },
 });
 ```
 
-Her etkinlik türünde ateşlemek için `match` öğesini tamamen atlayın.
+Her event türüne ateş etmek için `match` öğesini tamamen atlayın.
 
 ---
 
 ## Hata işleme ve başarısızlık modları
 
-Özel politikalar **açık başarısızlık**: hatalar hiçbir zaman yerleşik politikaları bloklamaz veya hook işleyicisini çökmez.
+Özel ilkeler **açık başarısızlıktır**: hatalar asla yerleşik ilkeleri engelleme veya hook handler'ı kilitlenmez.
 
 | Başarısızlık | Davranış |
 |---------|----------|
-| `customPoliciesPath` ayarlanmadı | Açık özel politika çalışmaz; kural politikaları ve yerleşikler normal şekilde devam eder |
-| Dosya bulunamadı | Uyarı `~/.failproofai/hook.log` öğesine kaydedilir; yerleşikler devam eder |
-| Sözdizimi/içe aktarma hatası (açık) | Hata `~/.failproofai/hook.log` öğesine kaydedilir; açık özel politikalar atlanır |
-| Sözdizimi/içe aktarma hatası (kural) | Hata kaydedilir; bu dosya atlanır, diğer kural dosyaları yine de yüklenir |
-| `fn` çalışma zamanında hatası | Hata kaydedilir; bu hook `allow` olarak kabul edilir; diğer hook'lar devam eder |
-| `fn` 10 saniyeden uzun sürerse | Zaman aşımı kaydedilir; `allow` olarak kabul edilir |
-| Kural dizini eksik | Kural politikası çalışmaz; hata yoktur |
+| `customPoliciesPath` ayarlanmadı | Açık özel ilkeler çalışmaz; kural ilkeleri ve yerleşikler normal şekilde devam eder |
+| Dosya bulunamadı | `~/.failproofai/hook.log` öğesine uyarı kaydedilir; yerleşikler devam eder |
+| Söz dizimi/içe aktarma hatası (açık) | Hata `~/.failproofai/hook.log` öğesine kaydedilir; açık özel ilkeler atlanır |
+| Söz dizimi/içe aktarma hatası (kural) | Hata kaydedilir; dosya atlanır, diğer kural dosyaları yine de yüklenir |
+| `fn` çalışma zamanında throw atar | Hata kaydedilir; bu hook `allow` olarak kabul edilir; diğer hook'lar devam eder |
+| `fn` 10s'den daha uzun sürer | Zaman aşımı kaydedilir; `allow` olarak kabul edilir |
+| Kural dizini eksik | Kural ilkeleri çalışmaz; hata yok |
 
 <Tip>
-Özel politika hatalarını ayıklamak için günlük dosyasını izleyin:
+Özel ilke hatalarını ayıklamak için günlük dosyasını izleyin:
 
 ```bash
 tail -f ~/.failproofai/hook.log
@@ -267,13 +267,13 @@ tail -f ~/.failproofai/hook.log
 
 ---
 
-## Tam örnek: birden çok politika
+## Tam örnek: birden fazla ilke
 
 ```js
 // my-policies.js
 import { customPolicies, allow, deny, instruct } from "failproofai";
 
-// Agent'i secrets/ dizinine yazmaktan önle
+// Agent'ı secrets/ dizinine yazmasını engelle
 customPolicies.add({
   name: "block-secrets-dir",
   description: "Prevent agent from writing to secrets/ directory",
@@ -286,7 +286,7 @@ customPolicies.add({
   },
 });
 
-// Agent'i yolunda tut: işleme atmadan önce testleri doğrula
+// Agent'ı yolunda tut: commit'lemeden önce testleri doğrula
 customPolicies.add({
   name: "remind-test-before-commit",
   description: "Keep the agent on track: verify tests pass before committing",
@@ -301,7 +301,7 @@ customPolicies.add({
   },
 });
 
-// Dondurma döneminde plansız bağımlılık değişikliklerini önle
+// Dondurma döneminde planlanmamış bağımlılık değişikliklerini engelle
 customPolicies.add({
   name: "dependency-freeze",
   description: "Prevent unplanned dependency changes during freeze period",
@@ -324,14 +324,14 @@ export { customPolicies };
 
 ## Örnekler
 
-`examples/` dizini çalışmaya hazır politika dosyalarını içerir:
+`examples/` dizini çalışmaya hazır ilke dosyalarını içerir:
 
 | Dosya | İçerik |
 |------|----------|
-| `examples/policies-basic.js` | Ortak agent başarısızlık modlarını kapsayan beş başlatıcı politika |
-| `examples/policies-advanced/index.js` | Gelişmiş desenleri: geçişli içe aktarmalar, eşzamansız çağrılar, çıktı temizleme ve oturum sonu hook'ları |
-| `examples/convention-policies/security-policies.mjs` | Kural tabanlı güvenlik politikaları (.env yazılarını blokla, git geçmişini yeniden yazmayı önle) |
-| `examples/convention-policies/workflow-policies.mjs` | Kural tabanlı iş akışı politikaları (test hatırlatmaları, dosya yazma denetimi) |
+| `examples/policies-basic.js` | Yaygın agent başarısızlık modlarını kapsayan beş başlangıç ilkesi |
+| `examples/policies-advanced/index.js` | İleri düzey desenler: geçişli içe aktarmalar, zaman uyumsuz çağrılar, çıktı temizleme ve oturum sonu hook'ları |
+| `examples/convention-policies/security-policies.mjs` | Kural tabanlı güvenlik ilkeleri (.env yazmalarını engelle, git geçmişi yeniden yazmayı önle) |
+| `examples/convention-policies/workflow-policies.mjs` | Kural tabanlı iş akışı ilkeleri (test anımsatıcıları, denetim dosyası yazmaları) |
 
 ### Açık dosya örneklerini kullanma
 
@@ -351,4 +351,4 @@ mkdir -p ~/.failproofai/policies
 cp examples/convention-policies/*.mjs ~/.failproofai/policies/
 ```
 
-Yükleme komutu gerekli değildir — dosyalar sonraki hook etkinliğinde otomatik olarak seçilir.
+Yükleme komutu gerekmez — dosyalar sonraki hook event'i sırasında otomatik olarak alınır.

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

@@ -1,11 +1,12 @@
 ---
+
 ---
 title: Kiến trúc
-description: "Cách hook handler, config loading, và policy evaluation hoạt động bên trong"
+description: "Cách hook handler, config loading, và policy evaluation hoạt động nội bộ"
 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ài liệu này giải thích cách failproofai hoạt động nội bộ: cách hook system chặn các tool call của agent, cách configuration được load và merge, cách policies được đánh giá, và cách dashboard giám sát hoạt động của agent.
 
 ---
 
@@ -13,10 +14,10 @@ Tài liệu này giải thích cách failproofai hoạt động bên trong: các
 
 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.
+1. **Hook handler** - Một subprocess CLI nhanh mà Claude Code gọi trên mỗi agent tool call. Đánh giá policies và trả về quyết định.
+2. **Agent Monitor (Dashboard)** - Một ứng dụng web Next.js để giám sát các agent session và quản lý policies.
 
-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.
+Cả hai subsystem chia sẻ các file cấu hình trong `~/.failproofai/` và thư mục `.failproofai/` của project, nhưng chúng chạy như các process riêng biệt và chỉ giao tiếp thông qua filesystem.
 
 ---
 
@@ -24,7 +25,7 @@ Cả hai subsystem chia sẻ các tệp cấu hình trong `~/.failproofai/` và
 
 ### 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`:
+Khi bạn chạy `failproofai policies --install`, nó sẽ ghi các entry như sau vào `~/.claude/settings.json`:
 
 ```json
 {
@@ -45,7 +46,7 @@ Khi bạn chạy `failproofai policies --install`, nó sẽ ghi các mục như
 }
 ```
 
-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.
+Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess trước mỗi tool call, truyền một JSON payload trên stdin.
 
 ### Định dạng payload
 
@@ -61,11 +62,11 @@ Claude Code sau đó gọi `failproofai --hook PreToolUse` dưới dạng một
 }
 ```
 
-Đố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.
+Đối với `PostToolUse` events, payload cũng chứa `tool_result` với output 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.
+Handler enforces giới hạn stdin 1 MB. Các payload vượt quá giới hạn này được loại bỏ và tất cả policies implicit cho phép.
 
-### Định dạng phản hồi
+### Định dạng response
 
 **Deny (PreToolUse):**
 ```json
@@ -86,7 +87,7 @@ Handler thực thi giới hạn 1 MB cho stdin. Các payload vượt quá giới
 }
 ```
 
-**Instruct (bất kỳ sự kiện nào ngoại trừ Stop):**
+**Instruct (any event except Stop):**
 ```json
 {
   "hookSpecificOutput": {
@@ -96,32 +97,32 @@ Handler thực thi giới hạn 1 MB cho stdin. Các payload vượt quá giới
 ```
 
 **Stop event instruct:**
-- Mã thoát: `2`
+- Exit code: `2`
 - Lý do được ghi vào stderr (không phải stdout)
 
 **Allow:**
-- Mã thoát: `0`
+- Exit code: `0`
 - Stdout trống
 
-**Allow with message:**
+**Allow với message:**
 
-`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):
+`allow(message)` cho phép một policy gửi informational context trở lại Claude ngay cả khi operation được phép. Hook handler ghi JSON sau vào **stdout** (không phải config file — đây là handler's response tới Claude Code, giống như deny và instruct responses ở trên):
 
 ```json
-// Được ghi vào stdout bởi hook handler process
+// Written to stdout by the 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)
+- Exit code: `0` (operation được phép)
+- Khi nhiều policies trả về `allow` với một message, các messages của chúng được join với newlines thành một single `additionalContext` string
+- Nếu không có policy nào cung cấp message, stdout trống (giống như trước)
 
 ### Processing pipeline
 
-`src/hooks/handler.ts` triển khai toàn bộ pipeline:
+`src/hooks/handler.ts` implements toàn bộ pipeline:
 
 ```text
 stdin JSON
@@ -140,13 +141,13 @@ stdin JSON
   → 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.
+Toàn bộ process chạy dưới 100ms cho các typical payloads mà không có LLM calls.
 
 ---
 
 ## Configuration loading
 
-`src/hooks/hooks-config.ts` triển khai config loading ba phạm vi.
+`src/hooks/hooks-config.ts` implements three-scope config loading.
 
 ```text
 [1] {cwd}/.failproofai/policies-config.json        ← project  (highest priority)
@@ -155,39 +156,39 @@ Toàn bộ quá trình chạy trong dưới 100ms cho các payload điển hình
 ```
 
 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
+- `enabledPolicies` - deduplicated union across all three files
+- `policyParams` - per-policy key, first file that defines it wins entirely
+- `customPoliciesPath` - first file that defines it wins
+- `llm` - first file that defines it wins
 
-Dashboard web sử dụng `readHooksConfig()` (chỉ global) để đọc và ghi, vì nó không được gọi với một project cwd.
+Web dashboard sử dụng `readHooksConfig()` (global only) để đọc và ghi, vì nó không được gọi với project cwd.
 
 ---
 
 ## Policy evaluation
 
-`src/hooks/policy-evaluator.ts` chạy các chính sách theo thứ tự.
+`src/hooks/policy-evaluator.ts` chạy policies theo thứ tự.
 
-Đối với mỗi chính sách:
+Với mỗi policy:
 
-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.
+1. Look up policy's `params` schema (nếu nó có).
+2. Đọc `policyParams[policy.name]` từ merged config.
+3. Merge user-provided values over schema defaults để tạo `ctx.params`.
+4. Gọi `policy.fn(ctx)` với resolved context.
+5. Nếu result là `deny`, dừng ngay lập tức và trả về quyết định đó.
+6. Nếu result là `instruct`, accumulate message và tiếp tục.
+7. Nếu result là `allow`, tiếp tục tới policy 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).
+Sau khi tất cả policies chạy:
+- Nếu bất kỳ `deny` nào được trả về, emit deny response.
+- Nếu bất kỳ `instruct` returns nào được collected, emit một single instruct response với tất cả messages được join.
+- Ngoài ra, emit một allow response (empty stdout, 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`:
+`src/hooks/builtin-policies.ts` định nghĩa tất cả 26 built-in policies như `BuiltinPolicyDefinition` objects:
 
 ```typescript
 interface BuiltinPolicyDefinition {
@@ -205,15 +206,15 @@ interface BuiltinPolicyDefinition {
 }
 ```
 
-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.
+Các policies chấp nhận `params` khai báo một `PolicyParamsSchema` với types và defaults cho mỗi parameter. Policy evaluator injects resolved values vào `ctx.params` trước khi gọi `fn`. Policy functions đọc `ctx.params` mà không cần null-guarding vì defaults luôn được applied 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).
+Pattern matching bên trong policies sử dụng parsed command tokens (argv), không phải raw string matching. Điều này ngăn chặn bypass thông qua shell operator injection (ví dụ: một pattern cho `sudo systemctl status *` không thể bypass bằng cách append `; rm -rf /` vào command).
 
 ---
 
 ## Custom policies
 
-`src/hooks/custom-hooks-registry.ts` triển khai một registry hỗ trợ bởi `globalThis`:
+`src/hooks/custom-hooks-registry.ts` implements một `globalThis`-backed registry:
 
 ```typescript
 const REGISTRY_KEY = "__failproofai_custom_hooks__";
@@ -226,25 +227,25 @@ 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:
+`src/hooks/custom-hooks-loader.ts` load user's policy file:
 
-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`.
+1. Đọc `customPoliciesPath` từ config; skip nếu absent.
+2. Resolve tới absolute path; check file exists.
+3. Rewrite tất cả `from "failproofai"` imports tới actual dist path để `customPolicies` resolve tới cùng `globalThis` registry.
+4. Recursively rewrite transitive local imports để ensure ESM compatibility.
+5. Write temporary `.mjs` files và `import()` entry file.
+6. Gọi `getCustomHooks()` để retrieve registered hooks.
+7. Clean up tất cả temp files trong một `finally` block.
 
-Đố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.
+Trên bất kỳ error nào (file not found, syntax error, import failure), error được logged tới `~/.failproofai/hook.log` và loader trả về một empty array. Built-in policies 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).
+Custom policies được đánh giá sau tất cả built-in policies. Một custom policy `deny` vẫn short-circuits further custom policies (nhưng tất cả built-ins đã chạy rồi ở điểm đó).
 
 ---
 
 ## Activity logging
 
-Sau mỗi sự kiện hook, handler nối một dòng JSONL vào `~/.failproofai/hook-activity.jsonl`:
+Sau mỗi hook event, handler appends một JSONL line tới `~/.failproofai/hook-activity.jsonl`:
 
 ```json
 {
@@ -259,13 +260,13 @@ Sau mỗi sự kiện hook, handler nối một dòng JSONL vào `~/.failproofai
 }
 ```
 
-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ỏ).
+Một line cho mỗi policy mà có một non-allow decision. Allow decisions không được logged (để giữ file 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.
+Dashboard là một **Next.js 16** application sử dụng App Router với React Server Components và Server Actions.
 
 ```text
 app/
@@ -287,16 +288,16 @@ app/
 
 **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.
+- Page components gọi `lib/projects.ts` và `lib/log-entries.ts` để đọc project/session data trực tiếp từ filesystem (không API layer cho reads).
+- Policies page sử dụng Server Actions cho tất cả mutations (toggle, params update, install/remove).
+- Session viewer parse Claude's JSONL transcript format và render một timeline của messages và tool calls.
 
 **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).
+- Không database - tất cả persistent state nằm trong plain files (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions cho mutations - không cần REST API cho CRUD operations.
+- React Server Components cho read pages - faster initial load, không client bundle cho data fetching.
+- Client components chỉ ở nơi cần interactivity (policy toggles, activity search, log viewer).
 
 ---