truthmark/docs/readmes/README.ar.md

Truthmark

وكلاؤك يكتبون الكود. يحافظ Truthmark على توثيق موجّه للبشر وقابل للمراجعة عبر Git.

🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇧🇷 Português | 🇷🇺 Русский | 🇸🇦 العربية | 🇮🇹 Italiano | 🇵🇱 Polski | 🇹🇷 Türkçe | 🇻🇳 Tiếng Việt | 🇮🇩 Bahasa Indonesia | 🇬🇷 Ελληνικά

🚀 البدء السريع: التشغيل محلياً خلال خمس دقائق

شغّل هذا داخل مستودع Git الذي تريد أن يديره Truthmark:

cd /path/to/your-repo
npm install -g truthmark
truthmark config

فعّل مضيف الذكاء الاصطناعي الذي تستخدمه فعلياً. تكون الإعدادات الجديدة محايدة تجاه المضيف، لذلك أضف قائمة platforms في المستوى الأعلى إلى .truthmark/config.yml قبل التهيئة:

version: 2
platforms:
  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
truthmark:
  workspace: docs/truthmark
  generated:
    portal:
      enabled: false

ثم ثبّت توثيق الحقيقة المحلي للمستودع، والتوجيه، وأسطح سير عمل الوكلاء:

truthmark init
truthmark check
git diff

جرّب الآن مسار الاعتماد الأكثر شيوعاً: توثيق سلوك موجود من الكود والاختبارات. في مضيف البرمجة بالذكاء الاصطناعي، اطلب من سير العمل المثبّت:

/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts

بعد ذلك، لا ينبغي للمستخدمين عادةً استدعاء Truth Sync مباشرة. واصل البرمجة عبر مضيف الذكاء الاصطناعي؛ فتعليمات المستودع المثبّتة تطلب من الوكيل تشغيل الاختبارات ذات الصلة وتنفيذ مراجعة Truth Sync قبل التسليم عندما تتغير الشيفرة الوظيفية. أنت تراجع فرق الكود الناتج مع فرق توثيق الحقيقة.

إذا كنت تريد فقط التحقق عبر CLI ولا تريد بعدُ مسارات عمل ذكاء اصطناعي خاصة بمضيف، فاترك platforms محذوفة وشغّل truthmark init && truthmark check؛ يمكنك إضافة منصة لاحقاً وإعادة تشغيل truthmark init.

💡 المشكلة: فجوة توثيق الذكاء الاصطناعي

وكلاء البرمجة بالذكاء الاصطناعي مذهلون في كتابة الكود بسرعة. لكن هذه السرعة تخلق نمط فشل جديداً وخطيراً: قصة المستودع تنحرف عن الواقع.

• يضيع السلوك داخل سجلات محادثة عابرة.
• تتأخر وثائق المعمارية بسرعة.
• تختفي قرارات المنتج بعد التسليم.
• يُترك مراجعو الكود لفحص فروق كود خام من دون فهم "السبب".
• تُجبر كل جلسة ذكاء اصطناعي جديدة على إعادة اكتشاف حقيقة مستودعك من الصفر.

🎯 الحل: Truthmark

يثبّت Truthmark طبقة سير عمل أصلية لـ Git داخل مستودعك. وهو يعالج الجزء الذي يتعطل عادةً في تطوير الذكاء الاصطناعي: مساعدة التوثيق على البقاء متوافقاً مع الكود.

بدلاً من الأمل في أن يتذكر البشر ووكلاء الذكاء الاصطناعي تحديث الوثائق، يجعل Truthmark التوثيق عادةً منهجية قابلة للمراجعة داخل مستودعك مباشرةً.

✨ لماذا يتميّز Truthmark

Truthmark ليس مجرد أداة توثيق أخرى. إنه مدمج بعمق في سير عمل الذكاء الاصطناعي:

• 🚫 بلا ارتباط بمورّد واحد: لا خدمات مستضافة، ولا قواعد بيانات مخفية، ولا خوادم إضافية للتشغيل.
• 🌳 أصلي 100% لـ Git: كل شيء يعيش في مستودعك. تنتقل الحقيقة مع فرعك.
• 🤝 عقد يملكه البشر ويتبعه الوكلاء: الصائنون يملكون عقد المستودع؛ والوكلاء يتبعون التعليمات المثبّتة أثناء البرمجة.
• ✅ الثقة عبر التحقق: يصبح عمل الذكاء الاصطناعي أسهل للثقة لأن العمل الذي يغيّر السلوك يتضمن قراراً أو فرقاً في توثيق الحقيقة يمكن للبشر مراجعته.

🔄 كيف يعمل

عندما يعدّل وكيل ذكاء اصطناعي كودك، لا تكون المهمة قد انتهت. يثبّت Truthmark حاجز سير عمل عند وقت الإنهاء يتبعه الوكلاء قبل التسليم:

1. 💻 الكود: يغيّر الوكيل الكود الوظيفي.
2. 🧪 الاختبار: تُشغّل الاختبارات ذات الصلة.
3. 🔍 التحقق: يتحقق Truthmark من التوثيق المربوط كجزء من مراجعة وقت الإنهاء المثبّتة.
4. 📝 التوثيق: يحدّث الوكيل الوثائق عندما تتغير حقيقة المستودع.
5. 👀 المراجعة: يراجع إنسان فرق الكود + فرق الحقيقة.

🛠 كيف تتفاعل مع Truthmark

لدى Truthmark عقد واحد محلي داخل المستودع، وطريقتان لاستخدامه.

البشر يثبّتون العقد ويتحققون منه

يستخدم الصائنون وCI واجهة CLI:

• truthmark config - إنشاء الإعدادات الأولية.
• truthmark init - تثبيت أو تحديث التوجيه، وقوالب وثائق الحقيقة، وتعليمات مضيف الذكاء الاصطناعي.
• truthmark check - التحقق من حقيقة المستودع من الطرفية.

الوكلاء يتبعون العقد أثناء البرمجة

يثبّت Truthmark تعليمات محلية في المستودع لمضيفي البرمجة بالذكاء الاصطناعي المدعومين مثل Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor.

الحلقة العادية بسيطة:

1. اطلب من الوكيل تغيير كود، أو اطلب منه توثيق سلوك موجود.
2. تخبر التعليمات المثبّتة الوكيل متى يختبر، ومتى يحدّث وثائق الحقيقة، ومتى يتوقف للمراجعة البشرية.
3. أنت تراجع فروق Git العادية: الكود وأي تغييرات في وثائق الحقيقة.

طلبات الوكيل التي يبدأها المستخدم قليلة عمداً:

• /truthmark-document - توثيق سلوك منفّذ موجود من الكود والاختبارات.
• /truthmark-realize - تنفيذ الكود من وثائق الحقيقة الموجودة.
• /truthmark-check - تدقيق حقيقة المستودع.

Truth Sync ليس الطريقة المعتادة لبدء العمل؛ إنه مراجعة وقت الإنهاء بعد تغييرات الكود الوظيفية. Truth Structure ليس أمراً يومياً؛ إنه يصلح التوجيه أو الملكية فقط عندما يعيق ذلك العمل.

ما الذي تحصل عليه

القدرة	ما تفعله
حقيقة أصلية لـ Git	تُبقي حقيقة المستودع في Markdown وإعدادات ملتزم بها.
توثيق مرتبط بالفرع	تنتقل الحقيقة مع الفرع بدلاً من العيش في جلسة خاصة.
CLI بشري	يمنح الصائنين أوامر للإعداد والتحديث والتحقق والفحص.
إرشادات الوكيل المثبّتة	تخبر وكلاء البرمجة متى يوثقون، أو يختبرون، أو يزامنون الحقيقة، أو يدققون، أو يتوقفون للمراجعة.
توجيه صريح	يربط مناطق الكود بوثائق الحقيقة المعتمدة.
تسليمات قابلة للمراجعة	ينتج فروق Git عادية لكل من الكود ووثائق الحقيقة.
تشغيل محلي أولاً	لا يتطلب خدمة مستضافة أو daemon أو قاعدة بيانات أو خادم MCP.
حدود كتابة أكثر أماناً	يفصل بين مسارات العمل التي تبدأ بالكود، أو تبدأ بالتوثيق، أو للقراءة فقط، أو للتوثيق فقط.
التحقق	يبلّغ عن مشكلات التوجيه والسلطة وfrontmatter والروابط والأسطح المولّدة ونطاق الفرع والحداثة والتغطية.
Portal اختياري	يولّد موقع عرض HTML ثابتاً وملتزماً به من وثائق حقيقة Markdown عندما يُفعّل ويُطلب ذلك صراحةً.

نظرة بصرية عامة

الميزات: ما يثبّته Truthmark وكيف ينقسم سطح سير العمل.

الموضع: أين يندرج Truthmark مقارنةً بالمطالبات والذاكرة ومسارات عمل المواصفات.

تدفق المزامنة: كيف ينهي Truth Sync تغييرات الكود العادية قبل التسليم.

لماذا تتبناه الفرق

Truthmark مخصص للفرق التي تعرف بالفعل أن وكلاء الذكاء الاصطناعي يستطيعون توليد الكود.

المشكلة التالية هي الحوكمة.

ليست الحوكمة كطقوس. بل الحوكمة كسؤال بسيط:

بعد هذا التغيير المدعوم بالذكاء الاصطناعي، هل ما زال المستودع يقول الحقيقة؟

يساعد Truthmark الفرق على الإجابة عن ذلك بملفات ملتزم بها، وتوجيه صريح، وفروق قابلة للمراجعة.

يكون مفيداً عندما تحتاج إلى:

• انحراف أقل في التوثيق
• تسليمات أفضل
• حقيقة منتج خاصة بالفرع
• توثيق معماري وAPI دائم
• ملكية صريحة بين الوثائق والكود
• حدود كتابة أكثر أماناً للوكلاء
• توثيق قابل للمراجعة بدلاً من ذاكرة مخفية
• مسارات عمل ذكاء اصطناعي تستمر في العمل من ملفات المستودع الملتزم بها

أين يندرج Truthmark

لا يستبدل Truthmark المطالبات أو الذاكرة أو المواصفات أو الاختبارات أو مراجعة الكود.

إنه يمنح تلك المسارات مكاناً دائماً للرسو في Git.

الحاجة	الأنسب
مخرجات أفضل من جلسة وكيل واحدة	مطالبة أفضل
استمرارية شخصية أو على مستوى الجلسة	أداة ذاكرة
عمل ميزات يبدأ بالخطة	سير عمل مواصفات
حقيقة مرتبطة بالفرع تنتقل مع الكود	Truthmark
التحقق من صحة السلوك	الاختبارات والمراجعة
مراجعة تغييرات التوثيق المدعومة بالذكاء الاصطناعي	Truthmark مع مراجعة Git

مجال Truthmark ضيق عمداً بحسب التصميم:

make repository truth explicit
route it to code
تثبيت إرشادات الوكلاء حولها
keep the result reviewable in Git

تعمّق أكثر

README هو الواجهة: سياق سريع، وبدء سريع، والنموذج الذهني الأساسي.

للاستخدام أمراً بأمر، ومقارنات الأسطح، وتفاصيل المنصات المدعومة، والإعداد، والتوجيه، وPortal، والأمثلة، اقرأ دليل مستخدم Truthmark.

حالة المشروع

يوفر الإصدار الحالي:

• أوامر CLI محلية للإعداد والتهيئة والتحقق والفهرسة وتحليل الأثر وحالة سير العمل
• تعليمات وكلاء محلية مولّدة لـ Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor
• تشخيصات للتوجيه والسلطة وfrontmatter والروابط والحداثة والأسطح المولّدة ونطاق الفرع والتغطية
• وثائق حقيقة مرتبطة بالفرع وعناصر مستمدة لاستخبارات المستودع

التوثيق

• دليل المستخدم
• فهرس الوثائق
• نظرة عامة على المعمارية
• عقود API وCLI
• دليل صيانة حقيقة المستودع

لأوامر التطوير المحلي والمساهمة، راجع CONTRIBUTING.md.

حدود التصميم

Truthmark صغير عمداً: محلي، ملتزم به، مرتبط بالفرع، وقابل للمراجعة.

إنه ليس خدمة مستضافة، ولا خادم MCP، ولا قاعدة بيانات متجهات، ولا طبقة ذاكرة مخفية، ولا منتج إنفاذ CI، ولا محركاً مستقلاً لإعادة كتابة الكود. يساعد حقيقة المستودع على البقاء مرئية؛ ولا يستبدل الاختبارات أو مراجعة الكود أو حكم البشر.

الترخيص

MIT. راجع LICENSE.

إزالة آمنة

استخدم truthmark uninstall --dry-run لمراجعة أسطح الاستضافة المولّدة بدقة، ثم truthmark uninstall --apply لإزالتها. يتم الاحتفاظ بـ truth المؤلفة والتكوين والقوالب ومخرجات البوابة وملفات Gemini والملفات غير المتعلقة بالمستخدم؛ أزل التثبيت العالمي لـ npm بشكل منفصل عبر مدير الحزم.