Imported from KAYANSTOR/kroutek (AGENTS.md). Install upstream with npx skills add KAYANSTOR/kroutek. Copyright stays with the author.

AGENTS.md — تعليمات ملزمة لأي وكيل ذكاء اصطناعي يعمل على مستودع كروتك

هذا الملف يُقرأ تلقائياً من أدوات مثل Antigravity قبل بدء أي جلسة عمل. إن كنت وكيلاً تعمل هنا: اقرأ هذا الملف كاملاً أولاً، ثم اقرأ docs/RESTRUCTURING_PLAN.md كاملاً (القسم 8 خصوصاً — القواعد الأصلية التي يستند إليها هذا الملف)، ثم راجع القسم 9 من نفس الوثيقة (سجل التنفيذ) لمعرفة ما أُنجز فعلاً وما لا يزال معلَّقاً قبل أن تفترض أي شيء عن حالة المشروع.

0) من صاحب هذا المشروع

المشروع تطبيق أندرويد (Kotlin/Jetpack Compose) لأتمتة بيع كروت الإنترنت عبر قراءة رسائل SMS من محافظ الدفع اليمنية (جيب، جوالي، الكريمي)، مع سيرفر Node.js/TypeScript/Prisma/PostgreSQL. صاحب المشروع ليس مبرمجاً بالضرورة — يعتمد عليك لاتخاذ قرارات تقنية سليمة، لكنه يريد أن يُستشار في أي قرار عمل أو أمان أو تغيير سلوك حقيقي، لا أن يُفاجَأ به بعد التنفيذ.

1) القواعد الملزمة (ملخّص — المرجع الكامل في القسم 8 من docs/RESTRUCTURING_PLAN.md)

1. لا تحذف أو تعطّل أي ميزة تعمل حالياً دون موافقة صريحة ومكتوبة في نفس الجلسة.
2. لا تغيّر أي سلوك وظيفي ملاحظ للمستخدم (نصوص، شروط قبول/رفض، حسابات مالية، تنسيق كروت) أثناء إعادة هيكلة بحتة. النقل يكون حرفياً (1:1) ما لم يكن الهدف المصرَّح به هو تغيير السلوك نفسه.
3. كل تعديل = فرع Git منفصل + Commit واحد بهدف واحد واضح. لا تدمج على main مباشرة دون مراجعة صاحب المشروع، إلا إذا طلب ذلك صراحة.
4. الأسرار لا تُكتب كنص صريح في الكود أبداً. استخدم متغيرات بيئة (.env، غير مرفوعة لـ Git).
5. لا تخترع افتراضات عن قواعد العمل (نسب أرباح، صيغ، مهلات). إن لم تكن موجودة بوضوح في الكود، اسأل صاحب المشروع.
6. لا "تحسين تطوعي" خارج نطاق المهمة المطلوبة. التزم بحدود ما طُلب فقط.
7. بعد كل مهمة: لخّص ماذا تغيّر فعلياً (ملفات + سلوك) بلغة بسيطة، اذكر أي جزء لم تنفّذه أو يحتاج قراراً، وحدّث القسم 9 (سجل التنفيذ) في docs/RESTRUCTURING_PLAN.md بنفس الأسلوب المتبع فيه (جدول، حالة، ملاحظات دقيقة، لا "✅ مكتمل" إلا بتأكيد صاحب المشروع صراحة).

2) قبل أي عمل UI/UX — اقرأ هذا أولاً

الوكلاء الذين عملوا على هذا المشروع سابقاً (Claude عبر واجهة محادثة) لم يملكوا محاكي أندرويد ولا قدرة على رؤية أي واجهة فعلياً — كل عمل UX تم حتى الآن (القسم 9، البند 7) اعتمد على قراءة الكود فقط، بلا أي تحقق بصري حقيقي. أنت (على Antigravity، على جهاز صاحب المشروع) لا تملك هذا العذر.

مصدر تصميم جديد ومُلزِم (أضيف لاحقاً — تحقق منه دائماً)

صاحب المشروع رفع تصاميم مرجعية فعلية (docs/design/reference-screens/) يريد أن يطابقها التطبيق (تنسيق، خطوط، ألوان). راجع docs/UI_REDESIGN_PLAN.md قبل أي عمل UI — يوثّق الألوان المستخرَجة فعلياً من هذه الصور (تحليل بكسلات برمجي)، ويشير بوضوح لتغيير هوية بصرية محتمل (الانتقال من أحمر/ذهبي إلى تيل/Teal كلون أساسي) لم يُؤكَّد بعد من صاحب المشروع. لا تفترض اكتمال هذا القرار، ولا تبدأ تنفيذاً واسعاً قبل التأكد أن هذه الوثيقة تعكس تأكيده الصريح.

قاعدة إلزامية خاصة بك تحديداً:

لكل تعديل واجهة، يجب أن تُشغِّل التطبيق فعلياً (محاكي أو جهاز حقيقي) وتلتقط لقطة شاشة قبل وبعد التعديل، وتُرفقها في ملخصك. لا يُقبل أي ادعاء "تم تحسين الواجهة" بلا دليل بصري فعلي — أنت تملك القدرة التي لم يملكها من عمل قبلك، فاستخدمها.

مصادر السياق الإلزامية قبل تعديل أي شاشة:

• docs/RESTRUCTURING_PLAN.md القسم 3 (تحليل الشاشات الحالي — نقاط ضعف موثّقة لكل شاشة رئيسية).
• docs/RESTRUCTURING_PLAN.md القسم 4 (خطة تطوير UX الكاملة، 3 مراحل: أ-مكاسب سريعة، ب-إعادة تصميم تدفقات، ج-نظام تصميم موحّد).
• docs/RESTRUCTURING_PLAN.md القسم 9، البند 7 (ما نُفّذ فعلياً من UX حتى الآن بالضبط — لا تكرر عملاً منجزاً، ولا تفترض أن الباقي منجز).
• kurotek/src/main/java/com/example/ui/theme/Color.kt وTheme.kt — نظام الألوان المركزي. أي لون جديد يجب أن يُضاف هنا كثابت مسمّى، لا كقيمة حرفية Color(0x...) متفرقة في ملفات الشاشات.

قيود معمارية حقيقية يجب معرفتها قبل تعديل أي شاشة:

• التنقل حالياً يدوي بالكامل (enum AppScreen + when)، ليس NavHost. navigation-compose مُضافة كتبعية لكن غير مُستخدمة فعلياً (القسم 2، البند 14 من الخطة). لا تفترض وجود Navigation Graph.
• MainViewModel.kt (713 سطر) لا يزال "ViewModel إله" يغطي كل الشاشات تقريباً — أي تعديل في شاشة قد يتطلب لمس هذا الملف، كن حذراً من كسر شاشات أخرى تعتمد عليه.
• Hilt مُدخَل جزئياً فقط (المرحلة 1، القسم 9 البند 6) — MainViewModel وMainActivity يستخدمانه، لكن SmsReceiver/PendingApprovalReceiver لا يزالان خارج الحقن.
• التطبيق لا يزال بلا اختبارات آلية إطلاقاً (لا Unit ولا UI Tests) رغم توفر Espresso/Roborazzi كتبعيات.

أولوية العمل المقترحة (يمكن تجاوزها بقرار صاحب المشروع):

اتبع القسم 4 بترتيبه: أكمل باقي بنود المرحلة أ أولاً (توحيد نظام الحوارات المنبثقة في طابور واحد، فصل شاشة الدخول عن شاشة التفعيل، استبدال Toast برسائل خطأ مضمّنة، مؤشرات SLA بصرية في شاشة الموافقات) قبل الانتقال للمرحلة ب (إعادة تصميم تدفقات) أو ج (نظام تصميم موحّد كامل).

3) قواعد عامة للكود (تنطبق على كل عمل، ليس فقط UI)

• Kotlin/Compose: اتبع نمط الملفات الموجود (feature_*/ui/*.kt)، لا تُعد تسمية حزم أو مجلدات دون طلب صريح.
• السيرفر: TypeScript فقط للكود الجديد (server/src/)، منظّم كوحدات (config, middleware, auth, license, sync, ...). لا تُضف منطقاً في server/api_server.js القديم (JS) — هذا الملف قيد الاستبدال التدريجي، أي تعديل مطلوب فيه يجب أن يُرحَّل أيضاً للبنية الجديدة في نفس المهمة.
• قبل أي Commit: شغّل ./gradlew assembleDebug (أندرويد) و/أو npx tsc --noEmit (سيرفر) للتأكد من نجاح البناء فعلياً — أنت تملك بيئة كاملة لفعل هذا، بخلاف من عمل هنا قبلك.
• رسائل الـ Commit: بالعربية أو الإنجليزية (اتبع نمط تاريخ المستودع)، يجب أن توضح: ماذا تغيّر، لماذا، وما الذي لم يتغيّر عمداً.

4) عند الشك

إن واجهت قراراً بين خيارين تقنيين متكافئين، اختر الأقرب لما هو موثّق في docs/RESTRUCTURING_PLAN.md (القسم 5 للمعمارية العامة). إن لم تجد إجابة هناك، توقف واسأل صاحب المشروع بدل الافتراض والمتابعة — هذا ليس اختيارياً، بل القاعدة الأولى في القسم 8.1 من نفس الوثيقة.