> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

title: البدء السريع
description: "ثبّت failproofai، فعّل السياسات، واترك وكلاءك يعملون بموثوقية"
icon: rocket
------------

## المتطلبات

* **Node.js** >= 20.9.0
* **Bun** >= 1.3.0 (اختياري - مطلوب فقط للبناء من المصدر)

***

## التثبيت

<CodeGroup>
  ```bash npm theme={null}
  npm install -g failproofai
  ```

  ```bash bun theme={null}
  bun add -g failproofai
  ```
</CodeGroup>

***

## البدء السريع

<Steps>
  <Step title="تفعيل السياسات">
    السياسات هي قواعد تعمل قبل وبعد كل استدعاء أداة لدى الوكيل. تلتقط الأوامر الضارة، تسرب الأسرار، وأوضاع الفشل الأخرى قبل أن تسبب ضررًا.

    ```bash theme={null}
    failproofai policies --install
    ```

    يكتب هذا إدخالات hook في أدوات الوكيل المثبتة لديك (ملف Claude Code `~/.claude/settings.json`، ملف OpenAI Codex `~/.codex/hooks.json`، ملف GitHub Copilot CLI `~/.copilot/hooks/failproofai.json`، ملف Cursor Agent `~/.cursor/hooks.json`، مكون OpenCode المولد في `~/.config/opencode/plugins/failproofai.mjs` بالإضافة إلى إدخال التسجيل في مصفوفة `plugin` في `~/.config/opencode/opencode.json`، ملف Pi `~/.pi/agent/settings.json`، أو ملف Hermes `~/.hermes/config.yaml`). عند وجود أكثر من واحد ستُطلب منك المتابعة؛ مرر `--cli claude codex copilot cursor opencode pi hermes` (أي مجموعة فرعية) لتخطي الطلب.

    دعم GitHub Copilot CLI و Cursor Agent و OpenCode و Pi موجود في مرحلة **تجريبية** — ثبّت باستخدام `--cli copilot` أو `--cli cursor` أو `--cli opencode` أو `--cli pi`. يثبّت Hermes (hermes-agent، بوابة Slack/Telegram) بنطاق المستخدم باستخدام `--cli hermes` وهو أيضًا **مصدر تدقيق** دون اتصال.

    ```bash theme={null}
    failproofai policies --install --scope project
    failproofai policies --install --cli codex --scope project
    failproofai policies --install --cli copilot --scope project
    failproofai policies --install --cli cursor --scope project
    failproofai policies --install --cli opencode --scope project
    failproofai policies --install --cli pi --scope project
    failproofai policies --install --cli hermes --scope user
    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
    ```
  </Step>

  <Step title="التحقق">
    ```bash theme={null}
    failproofai policies
    ```

    يعرض كل سياسة، وما إذا كانت مفعّلة، وأي معاملات مُعدّة.
  </Step>

  <Step title="تشغيل لوحة المعلومات">
    ```bash theme={null}
    failproofai
    ```

    يفتح لوحة معلومات محلية على `http://localhost:8020` حيث يمكنك استعراض الجلسات، فحص استدعاءات الأدوات، وإدارة السياسات.
  </Step>

  <Step title="تشغيل وكيلك">
    شغّل Claude Code كالمعتاد. إذا حاول الوكيل فعل شيء محفوف بالمخاطر، سيعترضه failproofai تلقائيًا. اتركه يعمل دون إشراف واستعرض ما حدث في لوحة المعلومات.
  </Step>
</Steps>

***

## كيف تعمل السياسات

في كل مرة يشغّل الوكيل أداة، يستدعي Claude Code failproofai كعملية فرعية:

```text theme={null}
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
```

كل سياسة تعيد أحد ثلاث قرارات:

* **allow** - يمضي الوكيل بشكل طبيعي
* **deny** - يتم حظر الإجراء، يُخبر الوكيل السبب
* **instruct** - يتم إضافة سياق إضافي إلى فوري الوكيل

<Note>
  تعمل السياسات في عمليتك المحلية. لا شيء يُرسل إلى خدمة بعيدة.
</Note>

***

## إعداد سياسات الفريق باستخدام السياسات المستندة إلى الاتفاقية

أسرع طريقة لإنشاء معايير الجودة عبر فريقك هي اتفاقية `.failproofai/policies/`. ضع ملفات السياسة في هذا الدليل وسيتم تحميلها تلقائيًا — لا أعلام، لا تغييرات إعدادات، لا أوامر تثبيت.

<Steps>
  <Step title="إنشاء دليل السياسات">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```
  </Step>

  <Step title="إضافة ملفات السياسة">
    انسخ أمثلة المبتدئين أو اكتب خاصتك:

    ```bash theme={null}
    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
    ```

    أو أنشئ واحدة جديدة:

    ```js theme={null}
    // .failproofai/policies/team-policies.mjs
    import { customPolicies, allow, deny, instruct } from "failproofai";

    customPolicies.add({
      name: "test-before-commit",
      match: { events: ["PreToolUse"] },
      fn: async (ctx) => {
        if (ctx.toolName !== "Bash") return allow();
        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
          return instruct("Run tests before committing.");
        }
        return allow();
      },
    });
    ```
  </Step>

  <Step title="الالتزام بـ git">
    ```bash theme={null}
    git add .failproofai/policies/
    git commit -m "Add team quality policies"
    ```

    كل فرد من فريقك الذي لديه failproofai مثبت سيستقبل هذه السياسات تلقائيًا. لا يلزم إعداد لكل مطور.
  </Step>
</Steps>

<Tip>
  التزم بـ `.failproofai/policies/` في مستودعك حتى يتشارك الفريق بأكمله نفس المعايير. كلما اكتشف فريقك أوضاع فشل جديدة، أضف سياسات وادفع — الجميع يحصلون على التحديث في `git pull` التالي. بمرور الوقت تصبح هذه السياسات معيار جودة حي يستمر في التحسن.
</Tip>

***

## تخزين البيانات

جميع الإعدادات والسجلات تبقى على جهازك:

| المسار                                    | ما يخزنه                        |
| ----------------------------------------- | ------------------------------- |
| `~/.failproofai/policies-config.json`     | إعدادات السياسة العامة          |
| `~/.failproofai/hook-activity.jsonl`      | سجل تنفيذ Hook                  |
| `~/.failproofai/hook.log`                 | سجل تصحيح أخطاء Hook المخصص     |
| `.failproofai/policies-config.json`       | إعدادات لكل مشروع (مُلتزم به)   |
| `.failproofai/policies-config.local.json` | تجاوزات شخصية (مُستثناة من git) |

***

## إلغاء التثبيت

```bash theme={null}
failproofai policies --uninstall
```

يزيل إدخالات hook من `~/.claude/settings.json`. ملفات الإعدادات في `~/.failproofai/` يتم الاحتفاظ بها.

***

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="الإعدادات" icon="gear" href="/ar/configuration">
    النطاقات وتنسيق ملف الإعدادات
  </Card>

  <Card title="السياسات المدمجة" icon="shield" href="/ar/built-in-policies">
    جميع 26 سياسة مع المعاملات
  </Card>

  <Card title="السياسات المخصصة" icon="code" href="/ar/custom-policies">
    اكتب سياساتك الخاصة في JavaScript
  </Card>

  <Card title="مراقب الوكيل" icon="chart-line" href="/ar/dashboard">
    مراقبة الجلسات واستعرض نشاط السياسة
  </Card>
</CardGroup>