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

# المساهمة

> كيفية المساهمة في وولف فيش - الكود والقدرات والتوثيق

# ثلاث طرق للمساهمة

هناك ثلاث طرق للمساهمة في وولف فيش:

<CardGroup cols={1}>
  <Card title="الكود" icon="code">
    TypeScript - إصلاح الأخطاء، إضافة الميزات، تحسين بيئة التشغيل.
  </Card>

  <Card title="القدرات" icon="puzzle-piece">
    SKILL.md + إضافة اختيارية - علّم وولف فيش أشياء جديدة.
  </Card>

  <Card title="التوثيق" icon="book">
    صفحات MDX - حسّن أو ترجم الوثائق.
  </Card>
</CardGroup>

***

## المساهمات البرمجية

### سير العمل

1. انسخ المستودع واستنسخ نسختك
2. أنشئ فرع ميزة:
   ```bash theme={null}
   git checkout -b feature/my-thing
   # or
   git checkout -b fix/the-bug
   ```
3. أجرِ تغييراتك
4. تحقق:
   ```bash theme={null}
   npm run typecheck && npm run lint
   ```
5. اختبر تغييرات الواجهة في المتصفح (`npm run dev`)
6. أنشئ التزامًا بالتنسيق التقليدي
7. ادفع وافتح طلب سحب ضد `main`

### رسائل الالتزام

استخدم [الالتزامات التقليدية](https://www.conventionalcommits.org/):

```
type(scope): subject

feat(runtime): add token counting to prefrontal
fix(renderer): prevent flash on theme switch
refactor(motor): simplify retry logic
docs(capabilities): add plugin lifecycle diagram
```

الأنواع الشائعة: `feat`، `fix`، `refactor`، `docs`، `chore`، `test`

### اتفاقيات الكود

<AccordionGroup>
  <Accordion title="لا تعليقات إلا إذا كان السبب غير واضح">
    يجب أن يكون الكود موثقًا ذاتيًا. إذا احتجت لتعليق، اشرح لماذا وليس ماذا.

    ```typescript theme={null}
    // Bad
    // Get the user
    const user = getUser()

    // Good — the WHY is non-obvious
    // Fallback to default user when workspace has no user.md yet
    const user = getUser() ?? DEFAULT_USER
    ```
  </Accordion>

  <Accordion title="لا إفراط في التجريد">
    لا تُنشئ تجريدات حتى يكون لديك ثلاث حالات استخدام ملموسة. إصلاح الخطأ هو إصلاح خطأ - لا تُعد هيكلة العالم حوله.
  </Accordion>

  <Accordion title="لا تبعيات غير ضرورية">
    قبل إضافة حزمة، تحقق مما إذا كانت المكتبة القياسية أو التبعيات الحالية تغطيها بالفعل. يستخدم وولف فيش `fetch()` مباشرة بدلاً من Axios، و `mitt` بدلاً من EventEmitter3، وهكذا.
  </Accordion>

  <Accordion title="IPC هي القناة الوحيدة بين main و renderer">
    لا تستورد أبدًا من `@main/*` في كود العارض. جميع الاتصالات تمر عبر قنوات IPC المعرّفة في طبقة preload.

    ```typescript theme={null}
    // In renderer — use the exposed API
    const result = await window.api.someChannel(args)

    // NEVER do this in renderer
    import { something } from '@main/some-module' // Breaks process isolation
    ```
  </Accordion>

  <Accordion title="لا تكتب أبدًا خارج ~/.wolffish/">
    البصمة الكاملة للتطبيق موجودة في `~/.wolffish/`. لا تكتب أبدًا على سطح المكتب أو المستندات أو المجلدات المؤقتة أو أي مكان آخر. إذا احتاجت ميزة لتخزين، ضعها داخل مساحة العمل.
  </Accordion>
</AccordionGroup>

***

## المساهمة بالقدرات

القدرات هي أسهل طريقة لتوسيع وولف فيش دون المساس بالكود الأساسي.

### إنشاء قدرة

1. أنشئ مجلدًا في `src/defaults/workspace/brain/cerebellum/`:
   ```
   brain/cerebellum/my-capability/
   ├── SKILL.md          # Required — defines triggers, tools, behavior
   └── plugin/           # Optional — custom tool logic
       └── index.mjs
   ```

2. اكتب `SKILL.md` مع البيانات الوصفية المناسبة:
   ```yaml theme={null}
   ---
   name: my-capability
   description: What this capability does
   triggers:
     - keyword that activates this
     - another trigger phrase
   tools:
     - name: my_tool
       description: What this tool does
       parameters:
         type: object
         properties:
           input:
             type: string
             description: The input to process
         required: [input]
   danger:
     - pattern: "rm -rf"
       reason: "Destructive file operation"
   ---

   # Instructions for the LLM

   When the user asks about [topic], use the `my_tool` tool to...
   ```

3. اختبر مع النماذج السحابية (DeepSeek، Claude، GPT) والنماذج المحلية (Ollama) - يجب أن يكون السلوك متسقًا.

### مشاركة القدرات

يمكن أن تكون القدرات أيضًا في مستودعات مستقلة. يستنسخها المستخدمون مباشرة في مجلد `~/.wolffish/workspace/brain/cerebellum/`:

```bash theme={null}
cd ~/.wolffish/workspace/brain/cerebellum/
git clone https://github.com/you/wolffish-capability-name.git
```

يكتشفها وولف فيش عند التشغيل التالي.

***

## المساهمة في التوثيق

### الإعداد

الوثائق موجودة في مستودع `wolffish-docs` (منفصل عن التطبيق):

```bash theme={null}
git clone https://github.com/thewolffish/wolffish-docs.git
cd wolffish-docs
npx mintlify dev
```

### التنسيق

* ملفات MDX مع مكونات Mintlify (`Card`، `CardGroup`، `Note`، `Tip`، `Warning`، `Tabs`، `Accordion`، إلخ.)
* حافظ على المحتوى عمليًا وموجزًا
* استخدم كتل الكود بكثرة

### الترجمات

<Warning>
  الترجمات العربية مطلوبة لجميع الصفحات الجديدة. يعكس مجلد `ar/` بنية الإنجليزية بالضبط.
</Warning>

لكل صفحة جديدة في `section/page.mdx`، أنشئ صفحة مقابلة في `ar/section/page.mdx` بنفس البنية والمحتوى المترجم. حدّث تنقل `mint.json` لكلا الإصدارين.

<CardGroup cols={2}>
  <Card title="إعداد بيئة التطوير" icon="terminal" href="/ar/development/setup">
    شغّل بيئة التطوير أولاً.
  </Card>

  <Card title="إضافة وحدات الدماغ" icon="brain" href="/ar/development/adding-brain-modules">
    تساهم بوحدة بيئة تشغيل جديدة؟ اقرأ هذا.
  </Card>
</CardGroup>