failproofai 0.0.2 → 0.0.4-beta.0

package/.next/standalone/docs/ar/cli/list-policies.mdx

@@ -0,0 +1,31 @@
+---
+title: عرض السياسات
+description: "اطّلع على السياسات المُفعّلة وپاراميتراتها والسياسات المخصصة"
+---
+
+```bash
+failproofai policies
+```
+
+يعرض جميع السياسات مع حالتها والپاراميترات المُعدّة والسياسات المخصصة.
+
+## نموذج من المخرجات
+
+```text
+Failproof AI Hook Policies (user)
+
+  Status  Name                          Description
+  ──────  ──────────────────────────────────────────────────────────────
+  ✓       block-sudo                    Block sudo commands
+            allowPatterns: ["sudo systemctl status"]
+  ✓       block-rm-rf                   Block recursive deletions
+  ✗       block-curl-pipe-sh            Block curl|bash patterns
+  ✓       sanitize-api-keys             Redact API keys from output
+            additionalPatterns: [{ regex: "MY_TOKEN_...", label: "..." }]
+
+  ── Custom Policies (/home/alice/myproject/my-policies.js) ──────────────
+  ✓       require-jira-ticket           Block commits without ticket
+  ✓       approval-gate                 Approval gate for destructive ops
+```
+
+يتم هنا تحديد المفاتيح غير المعروفة في `policyParams` بحيث يمكنك اكتشاف الأخطاء الإملائية مبكراً.

package/.next/standalone/docs/ar/cli/remove-policies.mdx

@@ -0,0 +1,43 @@
+---
+title: إلغاء تثبيت السياسات
+description: "إزالة مدخلات Hook من إعدادات Claude Code"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+يزيل مدخلات failproofai hook من ملف `settings.json` في Claude Code.
+
+الأسماء المستعارة: `failproofai p -u`
+
+## الخيارات
+
+| الخيار | الوصف |
+|------|-------------|
+| `--scope user` | إزالة من الإعدادات العامة (الافتراضي) |
+| `--scope project` | إزالة من إعدادات المشروع |
+| `--scope local` | إزالة من الإعدادات المحلية |
+| `--scope all` | إزالة من جميع النطاقات في نفس الوقت |
+| `--custom` / `-c` | مسح `customPoliciesPath` من الإعدادات |
+
+## السلوك
+
+- **بدون أسماء السياسات** - يزيل جميع مدخلات failproofai hook من ملف الإعدادات
+- **أسماء محددة** - يعطّل تلك السياسات لكن يبقي Hooks مثبتة
+
+## أمثلة
+
+```bash
+# إزالة جميع Hooks عامة
+failproofai policies --uninstall
+
+# تعطيل سياسة محددة (يبقي Hooks مثبتة)
+failproofai policies --uninstall block-sudo
+
+# إزالة Hooks من كل نطاق
+failproofai policies --uninstall --scope all
+
+# مسح مسار السياسات المخصصة
+failproofai policies --uninstall --custom
+```

package/.next/standalone/docs/ar/cli/version.mdx

@@ -0,0 +1,13 @@
+---
+---
+title: التحقق من الإصدار
+description: "طباعة إصدار failproofai المثبت"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+يطبع رقم الإصدار المثبت.

package/.next/standalone/docs/ar/configuration.mdx

@@ -0,0 +1,223 @@
+---
+---
+title: التكوين
+description: "صيغة ملف التكوين، نظام النطاقات الثلاثة، وقواعد الدمج"
+icon: gear
+---
+
+يستخدم failproofai ملفات تكوين JSON للتحكم في السياسات النشطة، وكيفية تصرفها، وأين يتم تحميل السياسات المخصصة. تم تصميم التكوين ليكون سهل المشاركة مع فريقك - قم بالتزام به في المستودع الخاص بك وسيحصل كل مطور على نفس شبكة الأمان للوكيل.
+
+---
+
+## نطاقات التكوين
+
+هناك ثلاثة نطاقات تكوين، يتم تقييمها بترتيب الأولوية:
+
+| النطاق | مسار الملف | الغرض |
+|-------|-----------|---------|
+| **مشروع** | `.failproofai/policies-config.json` | إعدادات لكل مستودع، مرتبطة بالتحكم في الإصدار |
+| **محلي** | `.failproofai/policies-config.local.json` | تجاوزات شخصية لكل مستودع، في gitignored |
+| **عام** | `~/.failproofai/policies-config.json` | الإعدادات الافتراضية على مستوى المستخدم عبر جميع المشاريع |
+
+عندما يتلقى failproofai حدث hook، فإنه يقوم بتحميل ودمج جميع الملفات الثلاثة الموجودة للمجلد الحالي.
+
+### قواعد الدمج
+
+**`enabledPolicies`** - اتحاد جميع النطاقات الثلاثة. السياسة المفعلة في أي مستوى تكون نشطة.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← إزالة التكرار من الاتحاد
+```
+
+**`policyParams`** - النطاق الأول الذي يحدد معاملات السياسة المعينة يفوز كليًا. لا يوجد دمج عميق للقيم ضمن معاملات السياسة.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← المشروع يفوز، يتم تجاهل العام
+```
+
+```text
+project:  (no block-sudo entry)
+local:    (no block-sudo entry)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← ينتقل إلى العام
+```
+
+**`customPoliciesPath`** - النطاق الأول الذي يحدده يفوز.
+
+**`llm`** - النطاق الأول الذي يحدده يفوز.
+
+---
+
+## صيغة ملف التكوين
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "sanitize-jwt",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "block-rm-rf": {
+      "allowPaths": ["/tmp"]
+    },
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  },
+  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
+}
+```
+
+---
+
+## مرجع الحقول
+
+### `enabledPolicies`
+
+النوع: `string[]`
+
+قائمة أسماء السياسات التي سيتم تفعيلها. يجب أن تطابق الأسماء بالضبط معرفات السياسة التي يعرضها `failproofai policies`. انظر [السياسات المدمجة](/ar/built-in-policies) للقائمة الكاملة.
+
+السياسات غير الموجودة في `enabledPolicies` غير نشطة، حتى لو كانت لديها إدخالات في `policyParams`.
+
+### `policyParams`
+
+النوع: `Record<string, Record<string, unknown>>`
+
+تجاوزات معاملات لكل سياسة. المفتاح الخارجي هو اسم السياسة؛ المفاتيح الداخلية خاصة بكل سياسة. تتوثق كل سياسة معاملاتها المتاحة في [السياسات المدمجة](/ar/built-in-policies).
+
+إذا كانت السياسة لديها معاملات ولكنك لم تحددها، يتم استخدام الإعدادات الافتراضية المدمجة للسياسة. المستخدمون الذين لا يقومون بتكوين `policyParams` على الإطلاق يحصلون على سلوك مطابق للإصدارات السابقة.
+
+المفاتيح غير المعروفة داخل كتلة معاملات السياسة يتم تجاهلها بصمت في وقت إطلاق hook ولكن يتم وضع علامة عليها كتحذيرات عند تشغيل `failproofai policies`.
+
+#### `hint` (عام)
+
+النوع: `string` (اختياري)
+
+رسالة تُضاف إلى السبب عندما تُرجع سياسة `deny` أو `instruct`. استخدمها لإعطاء Claude توجيهات قابلة للتنفيذ دون تعديل السياسة نفسها.
+
+يعمل مع أي نوع سياسة — مدمج، مخصص (`custom/`)، اتفاقية مشروع (`.failproofai-project/`)، أو اتفاقية مستخدم (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Try creating a fresh branch instead."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Use apt-get directly without sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Ask the user for approval first."
+    }
+  }
+}
+```
+
+عندما يرفض `block-force-push`، يرى Claude: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+القيم غير الحرفية والسلاسل الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين `hint`، فإن السلوك لم يتغير (متوافق للخلف).
+
+### `customPoliciesPath`
+
+النوع: `string` (مسار مطلق)
+
+المسار إلى ملف JavaScript يحتوي على سياسات hook مخصصة. يتم تعيينه تلقائيًا بواسطة `failproofai policies --install --custom <path>` (يتم حل المسار إلى مسار مطلق قبل تخزينه).
+
+يتم تحميل الملف جديدًا في كل حدث hook - لا يوجد تخزين مؤقت. انظر [السياسات المخصصة](/ar/custom-policies) لتفاصيل الإنشاء.
+
+### السياسات القائمة على الاتفاقية (v0.0.2-beta.7+)
+
+بالإضافة إلى `customPoliciesPath` الصريح، يقوم failproofai تلقائيًا باكتشاف وتحميل ملفات السياسة من المجلدات `.failproofai/policies/`:
+
+| المستوى | المجلد | النطاق |
+|-------|--------|---------|
+| مشروع | `.failproofai/policies/` | مشاركة مع الفريق عبر التحكم في الإصدار |
+| مستخدم | `~/.failproofai/policies/` | شخصي، ينطبق على جميع المشاريع |
+
+**مطابقة الملفات:** يتم تحميل الملفات المطابقة فقط لـ `*policies.{js,mjs,ts}` (مثل `security-policies.mjs`, `workflow-policies.js`). الملفات الأخرى في المجلد يتم تجاهلها.
+
+**لا يلزم التكوين:** لا تتطلب سياسات الاتفاقية إدخالات في `policies-config.json`. فقط أسقط الملفات في المجلد وسيتم التقاطها في حدث hook التالي.
+
+**التحميل المتحد:** يتم مسح كلا مجلدي الاتفاقية للمشروع والمستخدم. جميع الملفات المطابقة من كلا المستويين يتم تحميلها (بخلاف `customPoliciesPath` الذي يستخدم نطاق-أول-يفوز).
+
+انظر [السياسات المخصصة](/ar/custom-policies) لمزيد من التفاصيل والأمثلة.
+
+### `llm`
+
+النوع: `object` (اختياري)
+
+تكوين عميل LLM للسياسات التي تقوم باستدعاءات AI. غير مطلوب لمعظم الإعدادات.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## إدارة التكوين من CLI
+
+تقوم أوامر `policies --install` و `policies --uninstall` بالكتابة إلى `settings.json` لـ Claude Code (نقاط دخول hook)، بينما `policies-config.json` هو الملف الذي تديره مباشرة. الاثنان منفصلان:
+
+- **`settings.json`** - يخبر Claude Code باستدعاء `failproofai --hook <event>` في كل استخدام أداة
+- **`policies-config.json`** - يخبر failproofai بالسياسات التي يجب تقييمها وبأي معاملات
+
+يمكنك تحرير `policies-config.json` مباشرة في أي وقت؛ التغييرات تصبح نافذة المفعول فورًا في حدث hook التالي بدون الحاجة لإعادة التشغيل.
+
+---
+
+## مثال: تكوين على مستوى المشروع مع إعدادات الفريق الافتراضية
+
+التزم `.failproofai/policies-config.json` بمستودعك:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+يمكن لكل مطور بعد ذلك إنشاء `.failproofai/policies-config.local.json` (في gitignored) للتجاوزات الشخصية دون التأثير على زملائه.

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

@@ -0,0 +1,359 @@
+---
+
+---
+title: السياسات المخصصة
+description: "اكتب سياساتك الخاصة في JavaScript - فرض الاتفاقيات، منع الانجراف، الكشف عن الأعطال، التكامل مع الأنظمة الخارجية"
+icon: code
+---
+
+تتيح لك السياسات المخصصة كتابة قواعد لأي سلوك وكيل: فرض اتفاقيات المشروع، منع الانجراف، التحكم في العمليات الضارة، الكشف عن الوكلاء المعلقة، أو التكامل مع Slack وسير العمل الموافقات والمزيد. تستخدم نفس نظام حدث الخطاف وقرارات `allow` و `deny` و `instruct` كما هو الحال في السياسات المدمجة.
+
+---
+
+## مثال سريع
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+تثبيتها:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## طريقتان لتحميل السياسات المخصصة
+
+### الخيار 1: المبنية على الاتفاقية (موصى به، v0.0.2-beta.7+)
+
+أسقط ملفات `*policies.{js,mjs,ts}` في `.failproofai/policies/` وسيتم تحميلها تلقائياً - لا تحتاج إلى أعلام أو تغييرات في الإعدادات. يعمل هذا مثل خطافات git: أسقط ملفاً، وهو يعمل فقط.
+
+```
+# Project level — committed to git, shared with the team
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# User level — personal, applies to all projects
+~/.failproofai/policies/my-policies.mjs
+```
+
+**كيفية عمله:**
+- يتم فحص كلا المجلدات (المشروع والمستخدم) (الاتحاد - وليس first-scope-wins)
+- يتم تحميل الملفات أبجدياً في كل مجلد. اجعل البادئة `01-` أو `02-` للتحكم في الترتيب
+- يتم تحميل الملفات المطابقة `*policies.{js,mjs,ts}` فقط؛ يتم تجاهل الملفات الأخرى
+- يتم تحميل كل ملف بشكل مستقل (fail-open لكل ملف)
+- يعمل جنباً إلى جنب مع السياسات الصريحة `--custom` والمدمجة
+
+<Tip>
+سياسات الاتفاقية هي أسهل طريقة لمشاركة السياسات عبر الفريق. التزم `.failproofai/policies/` بـ git ويحصل كل عضو في الفريق عليها تلقائياً.
+</Tip>
+
+### الخيار 2: مسار الملف الصريح
+
+```bash
+# Install with a custom policies file
+failproofai policies --install --custom ./my-policies.js
+
+# Replace the policies file path
+failproofai policies --install --custom ./new-policies.js
+
+# Remove the custom policies path from config
+failproofai policies --uninstall --custom
+```
+
+يتم حفظ المسار المطلق المُحل في `policies-config.json` كـ `customPoliciesPath`. يتم تحميل الملف بشكل جديد في كل حدث خطاف - لا يوجد تخزين مؤقت بين الأحداث.
+
+### استخدام كليهما معاً
+
+يمكن لسياسات الاتفاقية والملف الصريح `--custom` أن يتعايشا. ترتيب التحميل:
+
+1. ملف `customPoliciesPath` الصريح (إذا تم تكوينه)
+2. ملفات اتفاقية المشروع (`{cwd}/.failproofai/policies/`، أبجدياً)
+3. ملفات اتفاقية المستخدم (`~/.failproofai/policies/`، أبجدياً)
+
+---
+
+## واجهة برمجية التطبيقات
+
+### الاستيراد
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+تسجيل سياسة. اتصل بها عدة مرات حسب الحاجة لسياسات متعددة في نفس الملف.
+
+```ts
+customPolicies.add({
+  name: string;                         // required - unique identifier
+  description?: string;                 // shown in `failproofai policies` output
+  match?: { events?: HookEventType[] }; // filter by event type; omit to match all
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### مساعدو القرار
+
+| الدالة | التأثير | استخدم عندما |
+|----------|--------|----------|
+| `allow()` | السماح بالعملية بصمت | الإجراء آمن، لا توجد رسالة مطلوبة |
+| `deny(message)` | حظر العملية | يجب ألا يتخذ الوكيل هذا الإجراء |
+| `instruct(message)` | إضافة سياق دون حظر | إعطاء الوكيل سياق إضافي للبقاء على المسار |
+
+`deny(message)` - تظهر الرسالة إلى Claude بسابقة `"Blocked by failproofai:"`. يقطع `deny` واحد كل تقييم آخر.
+
+`instruct(message)` - يتم إلحاق الرسالة بسياق Claude لاستدعاء الأداة الحالي. يتم تجميع جميع رسائل `instruct` وتسليمها معاً.
+
+<Tip>
+يمكنك إلحاق إرشادات إضافية بأي رسالة `deny` أو `instruct` بإضافة حقل `hint` في `policyParams` - لا حاجة لتغيير الرمز. يعمل هذا أيضاً للسياسات المخصصة (`custom/`)، واتفاقية المشروع (`.failproofai-project/`)، واتفاقية المستخدم (`.failproofai-user/`). انظر [التكوين → hint](/ar/configuration#hint-cross-cutting) للتفاصيل.
+</Tip>
+
+### رسائل السماح المعلوماتية (بيتا)
+
+<Note>
+`allow(message)` هي ميزة بيتا متاحة منذ v0.0.2-beta.3. قد تتغير واجهة برمجية التطبيقات في الإصدارات المستقبلية. الإصدارات السابقة تدعم فقط `allow()` بدون وسائط.
+</Note>
+
+`allow(message)` يسمح بالعملية **و** يرسل رسالة معلومات مرة أخرى إلى Claude. يتم تسليم الرسالة كـ `additionalContext` في استجابة stdout لمعالج الخطاف - نفس الآلية المستخدمة من قبل `instruct`، لكن مختلفة من الناحية الدلالية: إنها تحديث حالة وليست تحذير.
+
+| الدالة | التأثير | استخدم عندما |
+|----------|--------|----------|
+| `allow(message)` | السماح وإرسال السياق إلى Claude | تأكيد نجاح الفحص، أو شرح سبب تخطي الفحص |
+
+حالات الاستخدام:
+- **تأكيدات الحالة:** `allow("All CI checks passed.")` - يخبر Claude أن كل شيء أخضر
+- **شروحات fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` - يخبر Claude سبب تخطي الفحص حتى يكون لديه السياق الكامل
+- **تراكم الرسائل المتعددة:** إذا أرجعت عدة سياسات `allow(message)`، يتم ربط جميع الرسائل بخطوط جديدة وتسليمها معاً
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### حقول `PolicyContext`
+
+| الحقل | النوع | الوصف |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`، `"PostToolUse"`، `"Notification"`، `"Stop"` |
+| `toolName` | `string \| undefined` | الأداة التي يتم استدعاؤها (مثل `"Bash"`، `"Write"`، `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | معاملات إدخال الأداة |
+| `payload` | `Record<string, unknown>` | حمل الحدث الخام الكامل من Claude Code |
+| `session` | `SessionMetadata \| undefined` | سياق الجلسة (انظر أدناه) |
+
+### حقول `SessionMetadata`
+
+| الحقل | النوع | الوصف |
+|-------|------|-------------|
+| `sessionId` | `string` | معرّف جلسة Claude Code |
+| `cwd` | `string` | دليل العمل لجلسة Claude Code |
+| `transcriptPath` | `string` | المسار إلى ملف النسخة JSONL الخاص بالجلسة |
+
+### أنواع الأحداث
+
+| الحدث | متى يتم تشغيله | محتويات `toolInput` |
+|-------|--------------|----------------------|
+| `PreToolUse` | قبل تشغيل Claude لأداة | إدخال الأداة (مثل `{ command: "..." }` لـ Bash) |
+| `PostToolUse` | بعد اكتمال الأداة | إدخال الأداة + `tool_result` (الإخراج) |
+| `Notification` | عندما يرسل Claude إشعاراً | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - يجب أن تعيد الخطافات دائماً `allow()`، فلا يمكنها حظر الإشعارات |
+| `Stop` | عند انتهاء جلسة Claude | فارغة |
+
+---
+
+## ترتيب التقييم
+
+يتم تقييم السياسات بهذا الترتيب:
+
+1. السياسات المدمجة (بترتيب التعريف)
+2. السياسات المخصصة الصريحة من `customPoliciesPath` (بترتيب `.add()`)
+3. سياسات الاتفاقية من `.failproofai/policies/` للمشروع (ملفات أبجدياً، ترتيب `.add()` بداخلها)
+4. سياسات الاتفاقية من `~/.failproofai/policies/` للمستخدم (ملفات أبجدياً، ترتيب `.add()` بداخلها)
+
+<Note>
+يقطع أول `deny` جميع السياسات اللاحقة. يتم تجميع جميع رسائل `instruct` وتسليمها معاً.
+</Note>
+
+---
+
+## الواردات المتعدية
+
+يمكن لملفات السياسة المخصصة استيراد الوحدات المحلية باستخدام المسارات النسبية:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+يتم حل جميع الواردات النسبية الممكنة من ملف الإدخال. يتم تطبيق هذا بإعادة كتابة واردات `from "failproofai"` إلى مسار dist الفعلي وإنشاء ملفات `.mjs` مؤقتة لضمان توافق ESM.
+
+---
+
+## تصفية نوع الحدث
+
+استخدم `match.events` لتحديد متى يتم تشغيل سياسة:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Only fires when the session ends
+    // ctx.session.transcriptPath contains the full session log
+    return allow();
+  },
+});
+```
+
+حذف `match` بالكامل للتشغيل في كل نوع حدث.
+
+---
+
+## معالجة الأخطاء وأوضاع الفشل
+
+السياسات المخصصة هي **fail-open**: الأخطاء لا تحظر السياسات المدمجة أو تعطل معالج الخطاف.
+
+| الفشل | السلوك |
+|---------|----------|
+| `customPoliciesPath` لم تُعيّن | لا تعمل السياسات المخصصة الصريحة؛ سياسات الاتفاقية والمدمجة تستمر بشكل طبيعي |
+| ملف غير موجود | تم تسجيل تحذير في `~/.failproofai/hook.log`؛ المدمجة تستمر |
+| خطأ في الصيغة/الاستيراد (صريح) | تم تسجيل الخطأ في `~/.failproofai/hook.log`؛ سياسات مخصصة صريحة تم تخطيها |
+| خطأ في الصيغة/الاستيراد (اتفاقية) | تم تسجيل الخطأ؛ هذا الملف تم تخطيه، ملفات اتفاقية أخرى لا تزال تحمل |
+| `fn` رمي في وقت التشغيل | تم تسجيل الخطأ؛ تم التعامل مع الخطاف كـ `allow`؛ الخطافات الأخرى تستمر |
+| `fn` يستغرق أكثر من 10 ثوان | تم تسجيل المهلة الزمنية؛ تم التعامل معها كـ `allow` |
+| مجلد الاتفاقية مفقود | لا تعمل سياسات الاتفاقية؛ لا خطأ |
+
+<Tip>
+لتصحيح أخطاء السياسة المخصصة، راقب ملف السجل:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## مثال كامل: سياسات متعددة
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Prevent agent from writing to secrets/ directory
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// Keep the agent on track: verify tests before committing
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// Prevent unplanned dependency changes during freeze
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## أمثلة
+
+يحتوي دليل `examples/` على ملفات السياسات الجاهزة للتشغيل:
+
+| الملف | المحتوى |
+|------|----------|
+| `examples/policies-basic.js` | خمس سياسات للمبتدئين تغطي أوضاع فشل الوكيل الشائعة |
+| `examples/policies-advanced/index.js` | أنماط متقدمة: واردات متعدية، استدعاءات غير متزامنة، تنقية الإخراج، وخطافات نهاية الجلسة |
+| `examples/convention-policies/security-policies.mjs` | سياسات الأمان المبنية على الاتفاقية (حظر كتابة .env، منع إعادة كتابة سجل git) |
+| `examples/convention-policies/workflow-policies.mjs` | سياسات سير العمل المبنية على الاتفاقية (تذكيرات الاختبار، ملفات التدقيق) |
+
+### استخدام أمثلة الملفات الصريحة
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### استخدام أمثلة الاتفاقية
+
+```bash
+# Copy to project level
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Or copy to user level
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+لا حاجة لأمر التثبيت - يتم اختيار الملفات تلقائياً عند حدث الخطاف التالي.