# 🤖 AGENTS.md — دليل الوكلاء لمشروع diyaa.de

> أي agent (Claude Code أو غيره) يشتغل على هالمشروع لازم يتبع هالملف. الهدف: تعرف الوضع وتشتغل صح **بدون ما تقرأ كل الكود**.

---

## 1) قبل أي شغل — اقرأ التوثيق

كل الحقيقة موجودة بمجلد [`docs/`](./docs/):

1. [`docs/PROJECT-STATE.md`](./docs/PROJECT-STATE.md) — **الوضع الحالي الفعلي**. اقرأه أول شي.
2. [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) — المعمارية، مخطط الداتابيس، اتفاقيات المجلدات والمكوّنات.
3. [`docs/STACK.md`](./docs/STACK.md) — الستاك المعتمد (لا تضيف مكتبة خارج المعتمد بدون توثيق السبب).
4. [`docs/TODO.md`](./docs/TODO.md) — المهام المفتوحة.
5. [`docs/CHECKLIST.md`](./docs/CHECKLIST.md) — نظرة شاملة على المتبقّي.
6. [`docs/IDEAS.md`](./docs/IDEAS.md) — أفكار مستقبلية.

## 2) لما يُسأل "شو عنا شي نعملو؟"

- افتح `docs/TODO.md`.
- اقترح **أول مهمة `🔵 مفتوحة` وغير محجوبة** من أعلى القائمة.
- لا تقترح مهمة حالتها `⛔ محجوبة` قبل ما تخلص المهمة يلي بتحجبها.

## 3) أثناء التنفيذ

- غيّر حالة المهمة بـ `TODO.md` لـ `🟡 قيد التنفيذ`.
- التزم باتفاقيات `ARCHITECTURE.md`:
  - **كل شي مكوّنات قابلة لإعادة الاستخدام.**
  - **Tailwind + shadcn/ui** فقط للتنسيق (بدون CSS خام جديد).
  - **كل المكتبات محليّة** — بدون CDN وقت التشغيل.
  - Server Components افتراضياً؛ `"use client"` عند الحاجة فقط.
  - دعم ar/en و RTL/LTR بكل مكوّن عام.
  - كل مدخلات المستخدم تتحقّق بـ Zod.

## 4) بعد إنجاز المهمة (إلزامي)

1. **`docs/TODO.md`**: انقل المهمة من "🔵 مفتوحة" لـ "✅ منجزة (Ready)" مع التاريخ ورقم المهمة، وحرّر حالات المهام يلي انفتحت (من ⛔ لـ 🔵).
2. **`docs/PROJECT-STATE.md`**: حدّث جداول "الموجود/الناقص"، وأضف سطر بالـ Changelog إذا كانت خطوة كبيرة.
3. **`docs/CHECKLIST.md`**: علّم البنود المنجزة `[x]`.
4. إذا انبثقت فكرة جديدة مو مجدولة → ضيفها لـ `docs/IDEAS.md`.

> ⚠️ **القاعدة الذهبية:** لا تخلّي الكود يسبق التوثيق. إذا غيّرت كود وما وثّقت — الشغل مو خالص.

## 5) أوامر مفيدة

```bash
make start      # تشغيل عبر Docker
make logs       # اللوقات
make stop
npm run dev     # تطوير محلي
npm run check   # lint + typecheck + build
```

(بعد إضافة الداتابيس رح ينضاف: `make migrate`, `make studio`, `make seed` — شوف `ARCHITECTURE.md §9`.)

## 6) حدود مهمة

- **لا ترفع أسرار للـ git** (SMTP, DATABASE_URL, AUTH secret). كلها بـ `.env` فقط.
- لا تضيف dependency خارج `STACK.md` بدون توثيق السبب بـ `PROJECT-STATE.md`.
- لا تكسر وضع coming-soon / الصيانة الموجود.
- حافظ على بنية النشر (Docker + Traefik) شغّالة.