web-agent-bridge 3.4.0 → 3.8.1

package/README.ar.md

@@ -1,1304 +1,1563 @@
-<div dir="rtl" align="right">
-
-# Web Agent Bridge (WAB) — جسر الوكيل الذكي
-
-[![CI](https://github.com/abokenan444/web-agent-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/abokenan444/web-agent-bridge/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
-[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://hub.docker.com/)
-[![One-Click DNS Discovery](https://img.shields.io/badge/DNS%20Discovery-One--Click-6366f1?style=flat-square&logo=dns&logoColor=white)](https://webagentbridge.com/activate)
-[![Discord](https://img.shields.io/badge/Discord-%D8%A7%D9%86%D8%B6%D9%85%20%D9%84%D9%84%D9%85%D8%AC%D8%AA%D9%85%D8%B9-5865F2?logo=discord&logoColor=white)](https://discord.gg/NnbpJYEF)
-
-**البروتوكول والمنصة المفتوحة للتفاعل بين الذكاء الاصطناعي والويب — واجهة أوامر موحّدة، متصفح سيادي، درع هاتف، اكتشاف عبر DNS، شبكة وكلاء، وبوابة API موحّدة لتفاعل آمن بين الذكاء الاصطناعي والمواقع.**
-
-🌐 **الموقع الرسمي:** [https://webagentbridge.com](https://webagentbridge.com) — جرّب مساحة عمل الوكيل الذكي ولوحات التحكم والعديد من الميزات الأخرى مباشرة.
-
-يتيح WAB لأصحاب المواقع إضافة سكريبت يكشف واجهة `window.AICommands` لوكلاء الذكاء الاصطناعي. بدلاً من تحليل شيفرة HTML المعقدة، يقرأ الوكيل قائمة الإجراءات المتاحة وينفذها بدقة وأمان.
-
-**[English Documentation](README.md)** | **العربية**
-
----
-
-## 🌍 اكتشاف DNS بنقرة واحدة
-
-اجعل موقعك قابلاً للاكتشاف فوراً من قِبَل وكلاء الذكاء الاصطناعي دون لمس سطر واحد من الكود. يستخدم WAB DNS Discovery سجل DNS TXT قياسياً لبث قدرات موقعك بشكل آمن عبر DNS over HTTPS (DoH).
-
-**[فعّل اكتشاف WAB بنقرة واحدة](https://webagentbridge.com/activate)**
-
-### كيف يعمل:
-1. **أضف سجل TXT** إلى نطاقك (`_wab.yourdomain.com`)
-2. **وجهه** إلى ملف قدراتك (`v=wab1; endpoint=https://yourdomain.com/.well-known/wab.json`)
-3. **وكلاء الذكاء الاصطناعي** يستعلمون عن نطاقك عبر DoH ويعرفون فوراً ما يمكن لموقعك القيام به.
-
-شاهد [فيديو الإعداد في 40 ثانية](https://webagentbridge.com/activate) أو استخدم [المدقق المباشر](https://webagentbridge.com/dns) لفحص نطاقك.
-
----
-
-
-## ✨ المميزات
-
-- **اكتشاف تلقائي** — يكتشف الأزرار والنماذج وروابط التنقل تلقائياً
-- **نظام صلاحيات** — تحكم دقيق بما يمكن لوكلاء الذكاء الاصطناعي فعله
-- **واجهة موحدة** — كائن `window.AICommands` موحد يستخدمه أي وكيل
-- **تحديد معدل الاستخدام** — حماية مدمجة ضد الإساءة
-- **لوحة تحليلات** — تتبع تفاعل وكلاء الذكاء الاصطناعي مع موقعك
-- **إجراءات مخصصة** — سجّل إجراءاتك الخاصة مع معالجات مخصصة
-- **تحليلات فورية** — عبر WebSocket لمراقبة النشاط لحظياً
-- **توافق WebDriver BiDi** — دعم البروتوكولات المعيارية للمتصفحات
-- **مستويات اشتراك** — نواة مجانية + ميزات متقدمة مدفوعة
-- **نظام أحداث** — اشترك في أحداث الجسر للمراقبة
-- **صندوق حماية أمني** — عزل كامل مع توكنات جلسة، تحقق من الأصل، تأمين تلقائي
-- **محددات ذاتية الإصلاح** — مقاومة لتغييرات DOM في المواقع الديناميكية (SPA)
-- **وضع التخفي** — محاكاة سلوك بشري (حركة فأرة، كتابة طبيعية، تمرير تدريجي)
-- **قواعد بيانات متعددة** — SQLite + PostgreSQL + MySQL عبر محوّلات قابلة للتبديل
-- **SDK للوكلاء** — حزمة أدوات جاهزة لبناء وكلاء ذكاء اصطناعي
-- **بنية الإضافات** — نظام إضافات ديناميكي مع تنفيذ قائم على الخطافات، تثبيت لكل موقع، ترتيب أولويات، تقييمات، وتدقيق
-- **خدمة الرؤية** — تحليل لقطات شاشة متعدد الموفرين (Moondream محلي، OpenAI، Anthropic، Ollama) مع كشف العناصر التفاعلية وتشفير AES-256-GCM
-- **محرك العدالة** — طبقة حياد تضمن فرصة متساوية للمواقع الصغيرة والكبيرة مع بحث مرجح بالعدالة وتتبع شفافية العمولات
-- **ذاكرة الوكيل** — ذاكرة سلوكية دائمة مع ٤ أنواع ذاكرة، ٥ فئات، ارتباطات دلالية، تقييم الأهمية، وانتهاء صلاحية مؤقت
-- **تحليل حركة المرور المتقدم** — كشف أكثر من ٣٠ نوع بوت، تحليل سلوكي، كشف شذوذ، كشف استغلالات أمنية (SQL injection، XSS)
-- **خدمة البريد الإلكتروني** — بريد SMTP (ترحيب، تسجيل، إعادة تعيين كلمة المرور) مع قوالب HTML
-- **تتبع بدون JavaScript** — نقطة بكسل تتبع ١×١ لجمع التحليلات عند عدم توفر JavaScript
-- **محول WAB-MCP** — كشف قدرات مواقع WAB كأدوات MCP لـ Claude وGPT وGemini والوكلاء المتوافقة
-- **إضافة WordPress** — إضافة WordPress أصلية مع صفحة إعدادات، صناديق وصف لكل صفحة، توليد مستند اكتشاف، وعنصر لوحة تحكم
-- **متصفح WAB (سطح المكتب)** — متصفح Electron مستقل مع حاجب إعلانات مدمج (٨٠+ نطاق)، درع الاحتيال، تصنيف عدالة، دردشة وكيل، إشارات، سجل
-- **متصفح PWA (الهاتف)** — تطبيق ويب تقدمي لـ Android/iOS مع حجب إعلانات، بحث DuckDuckGo، كشف احتيال، تصفية شركات التقنية الكبرى
-- **SDK اكتشاف المخططات** — استخراج JSON-LD schema.org من جانب الخادم مع توليد تلميحات إجراءات WAB تلقائياً
-
-### الإصدار 2.0 — ميزات الحصن الرقمي
-
-- **محرك التفاوض اللحظي** — يتفاوض وكيل الذكاء الاصطناعي على الأسعار مباشرة مع المواقع عبر جلسات متعددة الجولات. ٨ أنواع شروط (كميات، ولاء، وقت، أول شراء، قيمة سلة، موسمية، عضوية، إحالة) و٤ أنواع خصومات (نسبة، مبلغ ثابت، شحن مجاني، هدية). يشمل حدود يومية وقيم حد أدنى وسجل كامل
-- **درع مقاومة التزييف** — محرك تحقق متقاطع يقارن DOM مع لقطات الشاشة، يتحقق من الأسعار مقابل المعايير السوقية، يفحص الاتساق الزمني، ويقيس تشابه النصوص. ٤ مستويات خطورة (بسيط ← احتيال) و٥ إجراءات استجابة (تحذير، إيقاف، تأكيد بشري، تصحيح تلقائي، حظر)
-- **نظام السمعة اللامركزي** — شهادات ثقة موقعة بـ HMAC من شبكة الوكلاء تغطي ٦ أنواع شهادات (شراء، حجز، استعلام، نموذج، تنقل، تحقق). ٧ مستويات ثقة (مجهول ← محظور)، اضمحلال زمني، مقاومة Sybil، لوحة متصدرين عالمية، ونظام طعن/نزاع
-- **لوحة السيادة** — مركز قيادة لحظي يعرض رادار العدالة، درع الخصوصية، سجل التفاوض، فحوصات التحقق، ومبدّل نماذج الذكاء الاصطناعي. يكشف نقطة `/api/sovereign/dashboard/sovereign` للبيانات المجمعة
-- **متجر قوالب الوكلاء** — ١١ قالب YAML جاهز (حجز فنادق، مقارنة بقالة، سوق حرفيين، صفقات طيران، إلخ) مع تشغيل من سطر الأوامر: `npx wab-agent run template.yaml`
-- **تبديل عقل الوكيل** — نظام تشغيل AI محلي يكتشف Ollama وllama.cpp تلقائياً مع دعم APIs متوافقة مع OpenAI. تتبع قدرات النماذج (نص/رؤية)، إدارة نوافذ السياق، توجيه حسب زمن الاستجابة، وتسجيل الاستدلال
-- **تنسيق الوكيل عبر المواقع** — وكيل واحد يدير عدة مواقع WAB في نفس الوقت عبر `WABMultiAgent`. قارن الأسعار بين المتاجر، اجمع البيانات، نفّذ إجراءات متوازية، واعثر على أفضل صفقة تلقائياً
-
-### الإصدار 2.3 — شبكة الوكلاء الخاصة (العقل الموزّع)
-
-- **بروتوكول التواصل بين الوكلاء** — الوكلاء يتواصلون عبر شبكة خاصة مع ٥ قنوات مدمجة (تنبيهات، اكتشافات، تكتيكات، مفاوضات، تصويت). ٦ أنواع رسائل مع تقييم الثقة، إزالة الوكلاء الخاملين تلقائياً عبر نبضات القلب، تحقق الأقران من المعرفة المشتركة. كل الاتصال يبقى محلياً
-- **التعلم المعزز المحلي** — الوكلاء يتعلمون من كل قرار للمستخدم باستخدام خوارزمية UCB1 متعددة الأذرع، تحديث السياسات بالنزول التدريجي مع تنشيط sigmoid، تخفيض زمني، واستخراج الأنماط المتسلسلة. بدون أي مكالمات API خارجية — التعلم بالكامل محلي
-- **منسق السيمفونية** — أربعة وكلاء متخصصين (باحث، محلل، مفاوض، حارس) يتعاونون ذاتياً عبر محركات قائمة على القواعد. ٥ قوالب، خط أنابيب من ٦ مراحل (تحليل ← بحث ← تفاوض ← حراسة ← تركيب ← قرار)، حق نقض الحارس للأمان، إجماع مرجح. تسجيل كامل للمراحل مع تتبع المدة. بدون أي اعتماد على LLM خارجية
-- **لوحة شبكة الوكلاء** — عرض مباشر لشبكة الوكلاء: الوكلاء النشطون، قنوات الاتصال، قاعدة المعرفة المشتركة، تركيبات السيمفونية، ومقاييس أداء التعلم
-
-### الإصدار 2.4 — القائد والذكاء على الحافة
-
-- **نظام القائد (Commander)** — محرك تنسيق مهام محلي يفكك الأهداف العليا إلى رسوم بيانية مهام (DAG). سجل وكلاء مع تتبع القدرات، محرك تنفيذ متوازٍ، تكامل تعلم لتغذية راجعة من النتائج، وتنسيق حوسبة طرفية
-- **نظام الحوسبة الطرفية (Edge Compute)** — يحول كل جهاز مستخدم إلى عقدة AI سيادية. تحليل المعدات (CPU, RAM, GPU)، تشفير AES-256-GCM بين العقد، موازنة حمل مرجحة، مراقبة صحة بنبضات القلب مع تجاوز فشل تلقائي، وتشكيل أسراب حسب القدرات
-- **محرك التنفيذ بالسرب** — إطلاق عدة وكلاء بالتوازي لحل مهمة واحدة. استراتيجيات قابلة للتكوين (متوازي، متسلسل، هجين)، دمج النتائج بأفضل درجة، تخصص بالأدوار، تجميع مرجح بالعدالة، وتقييم ثقة لكل وكيل
-
-### الإصدار 3.0 — نظام تشغيل الوكلاء (طبقة التنفيذ للويب)
-
-الإصدار 3.0 يحوّل WAB من أداة أتمتة متقدمة إلى **نظام تشغيل حقيقي للوكلاء** — طبقة تنفيذ كاملة لوكلاء الذكاء الاصطناعي على الويب، منافس لـ MCP لكنه مصمم خصيصاً للتفاعل مع المتصفح.
-
-- **بروتوكول WAB (WABP) v1.0.0** — بروتوكول رسمي مع سجل أوامر JSON Schema، رسائل مُنمطة، التحقق من المدخلات/المخرجات، وتعريفات أوامر مُنسّخة. ١٠ أوامر مدمجة (اكتشاف، تنفيذ، تنفيذ دلالي، تسجيل وكيل، إرسال مهمة، حالة مهمة، مقارنة تجارية، تفاوض تجاري، إرسال شبكة، استدلال AI). كل أمر يعلن عن القدرات المطلوبة ومستوى الخطر وصلاحيات الوصول
-- **تفاوض القدرات** — منح قدرات ديناميكي بين الوكلاء والمواقع. موافقة تلقائية حسب مستوى الخطر (منخفض = موافقة تلقائية، عالي = يتطلب سياسة)، تحديد معدل لكل قدرة، منح قابلة للانتهاء مع تتبع الاستخدام، ودعم إبطال كامل
-- **محرك تشغيل الوكلاء** — نظام تشغيل مهام بمستوى إنتاجي مع جدولة بقائمة أولويات، حل التبعيات، إعادة المحاولة بتراجع أسي، إيقاف/استئناف/إلغاء، حدود تزامن، وانتقالات حالة. ناقل أحداث غير متزامن مع وسيط، أحرف بدل مساحات الأسماء، ذاكرة إعادة (١٠ آلاف حدث)، وقائمة الرسائل الميتة
-- **صندوق حماية التنفيذ** — عزل لكل مهمة مع حدود موارد (مهلة، ذاكرة قصوى، حد استدعاءات الشبكة، حد عمليات DOM)، قوائم نطاقات مسموحة، حظر محددات CSS، فحوصات قدرات وقت التنفيذ، وسجل تدقيق كامل لكل عملية
-- **مدير الحالة** — حفظ حالة الوكيل بنقاط تفتيش مُسمّاة، تراجع لأي نقطة تفتيش، انتقالات حالة بالتحقق، عمليات دمج، وتنظيف بانتهاء الصلاحية
-- **حزمة المراقبة** — مسجل JSON هيكلي مع مسجلات فرعية ومخارج قابلة للتوصيل، متتبع موزع بفترات أب-ابن (متوافق مع OpenTelemetry)، ومجمع مقاييس بعدادات ومقاييس ورسوم بيانية (مئينات p50/p90/p95/p99) وسلاسل زمنية للوحات التحكم
-- **نموذج الأمان** — هوية الوكيل (تسجيل، مصادقة بمفتاح API مشفر، إدارة جلسات بمدة صلاحية، قوائم IP المسموحة، إبطال)، توقيع الأوامر (HMAC-SHA256 مع رمز فريد + طابع زمني، مقارنة آمنة زمنياً)، وعزل المواقع (تحكم وصول لكل موقع، وكلاء مسموحون/محظورون، حد تزامن أقصى، حظر محددات، تصنيف بيانات)
-- **مستوى التحكم** — مدير الوكلاء لدورة حياة النشر (نشر، تعيين لمواقع، فحوصات صحة، إلغاء نشر) ومحرك السياسات بقواعد مُنمّطة، تقييم شروط (يساوي، يحتوي، نمط، حد أدنى، حد أقصى، ضمن)، ربط سياسات بأولوية، وتطبيق على مستوى الكيان
-- **مستوى البيانات** — محلل الإجراءات الدلالية يربط صيغة `domain.action` (مثل `checkout.addItem`) بالتنفيذ الفعلي لكل موقع. المنفّذ يوجّه المهام عبر التتبع + المقاييس، يدعم أوضاع التنفيذ الدلالي/الخط الأنبوبي/المتوازي، مع ٨ إجراءات دلالية مدمجة للسلة والبحث والمصادقة والتنقل والمحتوى
-- **تجريد LLM متعدد النماذج** — واجهة موحدة لـ OpenAI (محادثة + تضمينات)، Anthropic (API الرسائل)، وOllama (نماذج محلية مع اكتشاف تلقائي). مدير LLM يوفر سلسلة احتياطية تلقائية عبر جميع الموفرين، تخزين مؤقت للاستجابات (٥ دقائق)، تتبع التكاليف عبر عدد الرموز، وقائمة نماذج
-- **السجل والنظام البيئي** — سجل الأوامر (كـ npm لأوامر WAB — تسجيل، اكتشاف، بحث حسب الفئة/الوسم/القدرة، تتبع الاستخدام)، سجل المواقع (دليل مواقع WAB مع التحقق، قائمة القدرات، تتبع الزيارات)، وسجل القوالب (قوالب سير عمل قابلة لإعادة الاستخدام مع عدد التنزيلات والتقييمات)
-- **واجهة API الموحدة لنظام التشغيل** — جميع طبقات نظام التشغيل مكشوفة عبر نقاط REST على `/api/os/*`: اكتشاف البروتوكول، هوية/مصادقة الوكيل، CRUD المهام، التنفيذ الدلالي، النشر، السياسات، العزل، المراقبة (مقاييس/آثار/سجلات)، السجل (أوامر/مواقع/قوالب)، عمليات LLM، توقيع الأوامر، وأحداث Server-Sent Events للبث المباشر
-- **عميل WABAgentOS في SDK** — فئة `WABAgentOS` جديدة في SDK مع كتابة TypeScript كاملة لجميع عمليات نظام التشغيل: تسجيل ← مصادقة ← تفاوض قدرات ← إرسال مهام ← تنفيذ دلالي ← استعلام المراقبة ← الاشتراك في الأحداث
-
-### الإصدار 3.2 — بوابة API والوحدات المتقدمة
-
-يقدم الإصدار 3.2 **بوابة API موحدة** على `/api/v1` مع 10 وحدات متقدمة لحماية وكلاء الذكاء الاصطناعي وحقوق المستهلك وتتبع الأسعار والامتثال التنظيمي. جميع الوحدات تستخدم مصادقة مركزية بمفتاح API مع تحكم وصول حسب الخطة.
-
-🌐 **توثيق API المباشر:** [webagentbridge.com/api](https://webagentbridge.com/api) (English / العربية)
-
-#### خطط API والأسعار
-
-| الخطة | السعر | الطلبات/يوم | الطلبات/دقيقة | الوحدات |
-|-------|-------|-------------|---------------|---------|
-| **مجانية** | $0/شهر | 100 | 10 | البروتوكول، آلة الزمن السعرية، الأنماط المظلمة، المكافآت |
-| **احترافية** | $29/شهر | 10,000 | 100 | كل المجاني + الجدار الناري، العصبي، التفاوض، التسويق |
-| **أعمال** | $149/شهر | 100,000 | 500 | جميع الوحدات العشر (شاملة كاتب العدل والاستخبارات الحكومية) |
-| **مؤسسات** | مخصص | غير محدود | مخصص | جميع الوحدات + SLA + خيار التشغيل المحلي |
-
-**احصل على مفتاح API:** `POST /api/v1/keys/generate` مع `{"plan": "FREE", "owner": "اسمك", "email": "you@example.com"}`
-
-#### الوحدات العشر
-
-| # | الوحدة | المسار | النوع | الخطة الأدنى | الوصف |
-|---|--------|--------|-------|-------------|-------|
-| 01 | **جدار حماية الوكلاء** | `/api/v1/firewall` | 🟡 API مفتوح · المحرك مغلق | احترافية | يفحص الروابط والمحتوى للكشف عن حقن الأوامر والتصيد والنطاقات الخبيثة |
-| 02 | **كاتب العدل التشفيري** | `/api/v1/notary` | 🔴 مغلق بالكامل | أعمال | يصدر شهادات تشفيرية مقبولة قانونياً لإثبات التمييز السعري |
-| 03 | **كاشف الأنماط المظلمة** | `/api/v1/dark-pattern` | 🔴 مغلق بالكامل | مجانية | يكشف جميع الأنماط المظلمة الـ 17 المصنفة من OECD مع تقارير EU DSA/DMA |
-| 04 | **التفاوض الجماعي** | `/api/v1/bargaining` | 🟡 الانضمام مفتوح · المحرك مغلق | احترافية | تجميع مشترين مجهولين للتفاوض على خصومات جماعية |
-| 05 | **الاستخبارات الحكومية** | `/api/v1/gov` | 🔴 مغلق بالكامل | أعمال | قاعدة بيانات الامتثال التنظيمي وفحص امتثال النطاقات |
-| 06 | **آلة الزمن السعرية** | `/api/v1/price` | 🟡 API مفتوح · قاعدة البيانات مغلقة | مجانية | تتبع الأسعار التاريخية وكشف التخفيضات الوهمية |
-| 07 | **المحرك العصبي** | `/api/v1/neural` | 🔴 مغلق بالكامل | احترافية | محرك AI محلي لتحليل الروابط وتصنيف المحتوى والتضمينات |
-| 08 | **بروتوكول WAB** | `/api/v1/protocol` | 🟢 مفتوح المصدر بالكامل | مجانية | مدقق بروتوكول الثقة wab.json المفتوح ونقطة المخطط |
-| 09 | **شبكة المكافآت** | `/api/v1/bounty` | 🟡 الإبلاغ مفتوح · القواعد مغلقة | مجانية | شبكة بلاغات وتهديدات مدعومة من المجتمع مع لوحة متصدرين |
-| 10 | **استخبارات التسويق بالعمولة** | `/api/v1/affiliate` | 🟡 API مفتوح · قاعدة البيانات مغلقة | احترافية | يكشف التلاعب بروابط التسويق وحشو ملفات تعريف الارتباط |
-
-**مفتاح الأنواع:** 🟢 مفتوح المصدر بالكامل · 🟡 واجهة API عامة مع محرك خاص · 🔴 مغلق بالكامل (يعيد 503 بدون المحرك)
-
-#### المصادقة
-
-جميع نقاط النهاية تتطلب مفتاح API عبر إحدى ثلاث طرق:
-
-```bash
-# الخيار 1: ترويسة التفويض (موصى بها)
-curl -X POST https://www.webagentbridge.com/api/v1/firewall/scan \
-  -H "Authorization: Bearer wab_live_pro_YOUR_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"url": "https://example.com", "content": "محتوى الصفحة..."}'
-
-# الخيار 2: ترويسة X-WAB-Key
-curl -H "X-WAB-Key: wab_live_pro_YOUR_KEY" \
-  https://www.webagentbridge.com/api/v1/protocol/check/example.com
-
-# الخيار 3: معامل الاستعلام
-curl https://www.webagentbridge.com/api/v1/bounty/stats?api_key=wab_live_fre_YOUR_KEY
-```
-
-#### إدارة المفاتيح
-
-| نقطة النهاية | الطريقة | الوصف |
-|-------------|---------|-------|
-| `/api/v1/keys/generate` | POST | إنشاء مفتاح API جديد |
-| `/api/v1/keys/validate` | POST | التحقق من صلاحية مفتاح |
-| `/api/v1/keys/usage` | GET | التحقق من الاستخدام والحصص |
-| `/api/v1/keys/revoke` | POST | إلغاء مفتاح |
-| `/api/v1/keys/rotate` | POST | تدوير مفتاح (إلغاء القديم وإصدار جديد) |
-
-#### نقاط البوابة العامة
-
-| نقطة النهاية | الطريقة | الوصف |
-|-------------|---------|-------|
-| `/api/v1/health` | GET | فحص صحة البوابة (عام) |
-| `/api/v1/plans` | GET | قائمة الخطط والأسعار (عام) |
-| `/api/v1/modules` | GET | قائمة الوحدات المتاحة (عام) |
-
-#### كيفية الاشتراك
-
-1. زُر [webagentbridge.com/api](https://webagentbridge.com/api) لاستكشاف الوحدات المتاحة
-2. أنشئ مفتاح API **مجاني**: `POST /api/v1/keys/generate` مع اسمك وبريدك
-3. ابدأ الطلبات فوراً لأي وحدة مجانية
-4. ارتقِ إلى **احترافية** ($29/شهر) أو **أعمال** ($149/شهر) للوصول للوحدات المتقدمة
-5. أدِر مفاتيحك عبر نقاط `/api/v1/keys/*`
-
----
-
-## 🚀 البدء السريع
-
-### ١. التثبيت والتشغيل
-
-```bash
-# الطريقة أ: استنساخ وتشغيل
-git clone https://github.com/abokenan444/web-agent-bridge.git
-cd web-agent-bridge
-npm install
-cp .env.example .env
-npm start
-
-# الطريقة ب: npx (أمر واحد)
-npx web-agent-bridge start
-
-# الطريقة ج: Docker
-docker compose up -d
-```
-
-### ٢. إنشاء حساب
-
-زُر `http://localhost:3000/register` وأنشئ حساباً، ثم أضف موقعك من لوحة التحكم.
-
-### ٣. إضافة السكريبت لموقعك
-
-```html
-<script>
-window.AIBridgeConfig = {
-  licenseKey: "WAB-XXXXX-XXXXX-XXXXX-XXXXX",
-  agentPermissions: {
-    readContent: true,
-    click: true,
-    fillForms: true,
-    scroll: true
-  }
-};
-</script>
-<script src="http://localhost:3000/script/ai-agent-bridge.js"></script>
-```
-
-### ٤. الآن يمكن لوكلاء الذكاء الاصطناعي التفاعل
-
-```javascript
-// من جانب وكيل الذكاء الاصطناعي
-const bridge = window.AICommands;
-const actions = bridge.getActions();           // اكتشاف الإجراءات
-await bridge.execute("signup");                // تنفيذ إجراء
-const info = bridge.getPageInfo();             // معلومات الصفحة
-```
-
----
-
-## 📁 هيكل المشروع
-
-```
-web-agent-bridge/
-├── server/                         # خادم Express.js
-│   ├── index.js                    # نقطة البداية
-│   ├── ws.js                       # WebSocket للتحليلات الفورية
-│   ├── routes/
-│   │   ├── auth.js                 # المصادقة (تسجيل/دخول)
-│   │   ├── api.js                  # واجهة المواقع والتحليلات
-│   │   ├── license.js              # التحقق من التراخيص والتتبع
-│   │   ├── admin.js                # واجهة الإدارة
-│   │   ├── admin-premium.js        # تحليلات الإدارة المتقدمة
-│   │   ├── billing.js              # تكامل Stripe للمدفوعات
-│   │   ├── sovereign.js            # الإصدار 2.0: تفاوض، سمعة، تحقق، لوحة سيادة
-│   │   ├── mesh.js                 # الإصدار 2.3: مسارات شبكة الوكلاء
-│   │   ├── commander.js            # الإصدار 2.4: مسارات تنسيق المهام
-│   │   ├── premium.js              # الميزات المتقدمة
-│   │   ├── premium-v2.js           # ذاكرة، رؤية، إصلاح، سرب، إضافات
-│   │   ├── discovery.js            # اكتشاف WAB + بحث مرجح بالعدالة
-│   │   ├── wab-api.js              # نقل WAB عبر HTTP
-│   │   └── noscript.js             # بكسل تتبع بدون JavaScript
-│   ├── services/
-│   │   ├── negotiation.js          # محرك التفاوض اللحظي
-│   │   ├── verification.js         # درع مقاومة التزييف
-│   │   ├── reputation.js           # نظام السمعة اللامركزي
-│   │   ├── agent-mesh.js           # بروتوكول التواصل بين الوكلاء
-│   │   ├── agent-learning.js       # التعلم المعزز المحلي (UCB1)
-│   │   ├── agent-symphony.js       # منسق السيمفونية (٤ أدوار، ٦ مراحل)
-│   │   ├── agent-memory.js         # ذاكرة الوكيل مع ارتباطات
-│   │   ├── commander.js            # تنسيق المهام ورسوم المهام (DAG)
-│   │   ├── edge-compute.js         # حوسبة طرفية / عقد AI سيادية
-│   │   ├── swarm.js                # محرك التنفيذ بالسرب
-│   │   ├── fairness.js             # محرك العدالة والحياد
-│   │   ├── vision.js               # تحليل الرؤية (متعدد الموفرين)
-│   │   ├── self-healing.js         # تصحيحات المحددات ذاتية الإصلاح
-│   │   ├── local-ai.js             # نظام تشغيل AI المحلي
-│   │   ├── plugins.js              # بنية الإضافات (خطافات، سجل)
-│   │   ├── premium.js              # تحليل حركة المرور وكشف البوتات
-│   │   ├── email.js                # خدمة البريد SMTP
-│   │   └── stripe.js               # تكامل مدفوعات Stripe
-│   ├── middleware/
-│   │   ├── auth.js                 # وسيط JWT
-│   │   ├── adminAuth.js            # مصادقة الإدارة
-│   │   └── rateLimits.js           # تحديد معدل الطلبات متعدد الطبقات
-│   ├── models/
-│   │   ├── db.js                   # عمليات قاعدة البيانات
-│   │   └── adapters/              # محولات SQLite, PostgreSQL, MySQL
-│   ├── migrations/                 # ترحيلات SQL مرقمة
-│   └── utils/
-│       ├── cache.js                # ذاكرة مؤقتة TTL + طابور تحليلات
-│       ├── migrate.js              # مشغل الترحيلات
-│       └── secureFields.js         # أدوات تشفير الحقول
-├── public/                         # الواجهة الأمامية
-│   ├── index.html                  # الصفحة الرئيسية
-│   ├── dashboard.html              # لوحة التحكم
-│   ├── premium-dashboard.html      # لوحة التحليلات المتقدمة
-│   ├── docs.html                   # التوثيق
-│   ├── login.html / register.html  # صفحات المصادقة
-│   ├── admin/                      # لوحة الإدارة
-│   ├── pwa/                        # تطبيق الويب التقدمي (متصفح الهاتف)
-│   │   ├── manifest.json           # بيان PWA
-│   │   ├── sw.js                   # عامل الخدمة (أولوية غير متصل)
-│   │   ├── index.html              # واجهة المتصفح للهاتف
-│   │   ├── app.js                  # حاجب إعلانات، درع احتيال، عدالة
-│   │   ├── app.css                 # سمة داكنة محسنة للهاتف
-│   │   └── icons/                  # أيقونات PWA
-│   ├── script/
-│   │   ├── wab.min.js              # مكتبة WAB المصغرة
-│   │   ├── wab-consent.js          # لافتة موافقة GDPR/CCPA
-│   │   ├── wab-schema.js           # اكتشاف schema.org
-│   │   ├── wab.d.ts                # تعريفات TypeScript
-│   │   └── wab-consent.d.ts        # تعريفات TypeScript للموافقة
-│   ├── js/                         # JavaScript الواجهة
-│   └── css/                        # أوراق الأنماط
-├── script/
-│   └── ai-agent-bridge.js          # سكريبت الجسر (ضعه في موقعك)
-├── examples/                       # أمثلة الوكلاء
-│   ├── puppeteer-agent.js          # Puppeteer + window.AICommands
-│   ├── bidi-agent.js               # بروتوكول WebDriver BiDi
-│   ├── vision-agent.js             # تحليل رؤية/لغة طبيعية
-│   ├── mcp-agent.js                # محول MCP لـ Claude/GPT
-│   ├── cross-site-agent.js         # تنسيق متعدد النطاقات
-│   ├── next-app-router/            # تكامل Next.js App Router
-│   ├── shopify-hydrogen/           # واجهة Shopify Hydrogen
-│   ├── wordpress-elementor/        # WordPress + Elementor
-│   └── saas-dashboard/             # إجراءات لوحة SaaS
-├── packages/                       # أغلفة أطر العمل
-│   ├── react/                      # @web-agent-bridge/react
-│   ├── vue/                        # @web-agent-bridge/vue
-│   ├── svelte/                     # @web-agent-bridge/svelte
-│   └── langchain/                  # @web-agent-bridge/langchain
-├── sdk/                            # SDK الوكيل
-│   ├── index.js                    # WABAgent لـ Puppeteer/Playwright
-│   └── schema-discovery.js         # استخراج schema.org من الخادم
-├── wab-mcp-adapter/                # محول MCP لـ Claude/GPT/Gemini
-│   ├── index.js                    # تعريفات أدوات MCP
-│   └── package.json
-├── wab-browser/                    # متصفح Electron لسطح المكتب
-│   ├── main.js                     # العملية الرئيسية لـ Electron
-│   ├── preload.js                  # التحميل المسبق
-│   └── package.json
-├── web-agent-bridge-wordpress/     # إضافة WordPress
-│   ├── web-agent-bridge.php        # نقطة دخول الإضافة
-│   ├── includes/                   # فئات PHP (API, Actions, Dashboard)
-│   └── assets/                     # CSS/JS الإضافة
-├── bin/
-│   ├── cli.js                      # نقطة دخول CLI (wab-agent)
-│   └── wab.js                      # مشغل الوكلاء
-├── templates/                      # ١١ قالب YAML لمتجر الوكلاء
-├── docs/
-│   ├── SPEC.md                     # مواصفة بروتوكول WAB
-│   └── DEPLOY.md                   # دليل النشر
-├── demo-store/                     # متجر تجريبي للاختبار
-├── deploy/                         # إعدادات Nginx
-├── tests/                          # اختبارات Jest + Supertest
-├── .env                            # متغيرات البيئة
-└── package.json
-```
-
----
-
-## 🔌 واجهات API
-
-### المصادقة
-| النقطة | الطريقة | الوصف |
-|---|---|---|
-| `/api/auth/register` | POST | إنشاء حساب |
-| `/api/auth/login` | POST | تسجيل الدخول |
-| `/api/auth/me` | GET | بيانات المستخدم الحالي |
-
-### المواقع
-| النقطة | الطريقة | الوصف |
-|---|---|---|
-| `/api/sites` | GET | قائمة مواقعك |
-| `/api/sites` | POST | إضافة موقع جديد |
-| `/api/sites/:id` | GET | تفاصيل الموقع |
-| `/api/sites/:id/config` | PUT | تحديث الإعدادات |
-| `/api/sites/:id/tier` | PUT | تغيير مستوى الاشتراك |
-| `/api/sites/:id` | DELETE | حذف الموقع |
-| `/api/sites/:id/snippet` | GET | كود التضمين |
-| `/api/sites/:id/analytics` | GET | بيانات التحليلات |
-
-### التراخيص (عامة)
-| النقطة | الطريقة | الوصف |
-|---|---|---|
-| `/api/license/verify` | POST | التحقق من مفتاح الترخيص |
-| `/api/license/token` | POST | تبادل `siteId` مقابل توكن جلسة |
-| `/api/license/session` | POST | التحقق من توكن الجلسة |
-| `/api/license/track` | POST | تسجيل حدث تحليلي |
-
-### واجهات السيادة (الإصدار 2.0)
-| النقطة | الطريقة | الوصف |
-|---|---|---|
-| `/api/sovereign/reputation/agents` | POST | تسجيل وكيل جديد |
-| `/api/sovereign/reputation/attestations` | POST | إرسال شهادة ثقة |
-| `/api/sovereign/reputation/sites/:siteId` | GET | سمعة الموقع |
-| `/api/sovereign/reputation/leaderboard` | GET | لوحة المتصدرين |
-| `/api/sovereign/negotiation/rules` | POST | إنشاء قاعدة تفاوض |
-| `/api/sovereign/negotiation/sessions` | POST | فتح جلسة تفاوض |
-| `/api/sovereign/negotiation/sessions/:id/propose` | POST | تقديم عرض مضاد |
-| `/api/sovereign/negotiation/sessions/:id/confirm` | POST | تأكيد الصفقة |
-| `/api/sovereign/verify/price` | POST | التحقق من السعر |
-| `/api/sovereign/verify/text` | POST | التحقق من النص |
-| `/api/sovereign/verify/page` | POST | التحقق الشامل للصفحة |
-| `/api/sovereign/dashboard/sovereign` | GET | بيانات لوحة السيادة |
-
-### شبكة الوكلاء (الإصدار 2.3)
-| النقطة | الطريقة | الوصف |
-|---|---|---|
-| `/api/mesh/agents` | POST | تسجيل وكيل في الشبكة |
-| `/api/mesh/agents` | GET | عرض وكلاء الشبكة |
-| `/api/mesh/channels` | GET | عرض قنوات الاتصال |
-| `/api/mesh/messages` | POST | نشر رسالة في قناة |
-| `/api/mesh/messages/:channel` | GET | قراءة رسائل القناة |
-| `/api/mesh/knowledge` | POST | مشاركة معرفة |
-| `/api/mesh/knowledge` | GET | استعلام قاعدة المعرفة |
-| `/api/mesh/votes` | POST | بدء تصويت |
-| `/api/mesh/votes/:id/cast` | POST | الإدلاء بصوت |
-| `/api/mesh/votes/:id/tally` | GET | نتائج التصويت |
-
-### القائد (الإصدار 2.4)
-| النقطة | الطريقة | الوصف |
-|---|---|---|
-| `/api/commander/missions` | POST | إنشاء مهمة جديدة |
-| `/api/commander/missions/:id/launch` | POST | إطلاق المهمة |
-| `/api/commander/missions/:id` | GET | حالة المهمة |
-| `/api/commander/missions` | GET | عرض جميع المهام |
-| `/api/commander/agents` | POST | تسجيل وكيل |
-| `/api/commander/agents` | GET | عرض الوكلاء |
-| `/api/commander/edge/nodes` | POST | تسجيل عقدة حوسبة طرفية |
-| `/api/commander/edge/nodes` | GET | عرض العقد |
-| `/api/commander/ai/models` | GET | اكتشاف نماذج AI المحلية |
-| `/api/commander/ai/infer` | POST | تشغيل استدلال AI محلي |
-| `/api/commander/stats` | GET | إحصائيات المنصة الموحدة |
-
-### الميزات المتقدمة (الإصدار 2)
-| النقطة | الطريقة | الوصف |
-|---|---|---|
-| `/api/premium/v2/memory` | POST | تخزين ذاكرة الوكيل |
-| `/api/premium/v2/memory/:agentId` | GET | استرجاع ذكريات الوكيل |
-| `/api/premium/v2/memory/associate` | POST | إنشاء ارتباط بين ذكريات |
-| `/api/premium/v2/vision/analyze` | POST | تحليل لقطة شاشة |
-| `/api/premium/v2/vision/elements` | POST | استخراج عناصر تفاعلية |
-| `/api/premium/v2/healing/corrections` | POST | تسجيل تصحيح محدد |
-| `/api/premium/v2/healing/resolve` | POST | حل محدد معطل |
-| `/api/premium/v2/swarm/execute` | POST | إطلاق مهمة سرب |
-| `/api/premium/v2/swarm/:id` | GET | نتائج السرب |
-| `/api/premium/v2/plugins` | GET | عرض الإضافات المتاحة |
-| `/api/premium/v2/plugins/:id/install` | POST | تثبيت إضافة |
-| `/api/premium/v2/plugins/:id/hooks` | POST | تنفيذ خطاف إضافة |
-
-### الاكتشاف والعدالة
-| النقطة | الطريقة | الوصف |
-|---|---|---|
-| `/api/discovery` | GET | مستند اكتشاف WAB |
-| `/api/discovery/search` | GET | بحث مرجح بالعدالة |
-| `/api/discovery/register` | POST | تسجيل موقع في دليل WAB |
-
-### بروتوكول WAB (نقل HTTP)
-| النقطة | الطريقة | الوصف |
-|---|---|---|
-| `/api/wab/session` | POST | تبادل توكن جلسة |
-| `/api/wab/actions` | GET | الإجراءات المتاحة |
-| `/api/wab/execute` | POST | تنفيذ إجراء عبر HTTP |
-
-### WebSocket
-| النقطة | الوصف |
-|---|---|
-| `ws://localhost:3000/ws/analytics` | تحليلات فورية لحظية |
-
----
-
-## ⚙️ واجهة سكريبت الجسر
-
-عند التحميل، يكشف `window.AICommands` الطرق التالية:
-
-| الطريقة | الوصف |
-|---|---|
-| `getActions(category?)` | قائمة الإجراءات المتاحة |
-| `getAction(name)` | الحصول على إجراء محدد |
-| `execute(name, params?)` | تنفيذ إجراء |
-| `readContent(selector)` | قراءة محتوى عنصر |
-| `getPageInfo()` | معلومات الصفحة والجسر |
-| `waitForElement(selector, timeout?)` | انتظار ظهور عنصر DOM |
-| `waitForNavigation(timeout?)` | انتظار تغيير العنوان |
-| `registerAction(def)` | تسجيل إجراء مخصص |
-| `authenticate(key, meta?)` | مصادقة الوكيل |
-| `refresh()` | إعادة مسح الصفحة |
-| `toBiDi()` | الحصول على سياق WebDriver BiDi |
-| `executeBiDi(command)` | تنفيذ أمر بصيغة BiDi |
-
----
-
-## 🔧 الإعدادات
-
-```javascript
-window.AIBridgeConfig = {
-  licenseKey: "WAB-XXXXX-XXXXX-XXXXX-XXXXX",
-  agentPermissions: {
-    readContent: true,      // قراءة النص
-    click: true,            // النقر على العناصر
-    fillForms: false,       // ملء/إرسال النماذج
-    scroll: true,           // تمرير الصفحة
-    navigate: false,        // التنقل بين الصفحات
-    apiAccess: false,       // استدعاء API داخلي (Pro+)
-    automatedLogin: false,  // تسجيل دخول تلقائي (Starter+)
-    extractData: false      // استخراج البيانات (Pro+)
-  },
-  restrictions: {
-    allowedSelectors: [],
-    blockedSelectors: [".private", "[data-private]"],
-    requireLoginForActions: ["apiAccess"],
-    rateLimit: { maxCallsPerMinute: 60 }
-  },
-  logging: { enabled: false, level: "basic" }
-};
-```
-
----
-
-## 🔄 توافق WebDriver BiDi
-
-يدعم السكريبت بروتوكول WebDriver BiDi للتواصل مع الوكلاء عبر معايير موحدة:
-
-```javascript
-// الحصول على سياق BiDi
-const context = window.__wab_bidi.getContext();
-
-// إرسال أمر BiDi
-const result = await window.__wab_bidi.send({
-  id: 1,
-  method: 'wab.executeAction',
-  params: { name: 'signup', data: {} }
-});
-
-// الأوامر المدعومة:
-// wab.getContext    — سياق الصفحة والقدرات
-// wab.getActions    — قائمة الإجراءات
-// wab.executeAction — تنفيذ إجراء
-// wab.readContent   — قراءة محتوى
-// wab.getPageInfo   — معلومات الصفحة
-```
-
----
-
-## 📊 التحليلات الفورية (WebSocket)
-
-اتصل بنقطة WebSocket لتلقي إشعارات فورية:
-
-```javascript
-const ws = new WebSocket('ws://localhost:3000/ws/analytics');
-
-// المصادقة
-ws.onopen = () => {
-  ws.send(JSON.stringify({
-    type: 'auth',
-    token: 'your-jwt-token',
-    siteId: 'your-site-id'
-  }));
-};
-
-// تلقي الأحداث
-ws.onmessage = (event) => {
-  const data = JSON.parse(event.data);
-  console.log('حدث جديد:', data);
-  // { type: 'analytic', actionName: '...', agentId: '...', success: true }
-};
-```
-
----
-
-## 💰 مستويات الاشتراك
-
-| الميزة | مجاني | Starter | Pro | Enterprise |
-|---|:---:|:---:|:---:|:---:|
-| اكتشاف تلقائي | ✓ | ✓ | ✓ | ✓ |
-| نقر/تمرير | ✓ | ✓ | ✓ | ✓ |
-| ملء النماذج | ✓ | ✓ | ✓ | ✓ |
-| تسجيل أساسي | ✓ | ✓ | ✓ | ✓ |
-| تسجيل دخول تلقائي | ✗ | ✓ | ✓ | ✓ |
-| لوحة تحليلات | ✗ | ✓ | ✓ | ✓ |
-| وصول API | ✗ | ✗ | ✓ | ✓ |
-| استخراج البيانات | ✗ | ✗ | ✓ | ✓ |
-| تحديد معدل مخصص | ✗ | ✗ | ✗ | ✓ |
-| Webhooks | ✗ | ✗ | ✗ | ✓ |
-
----
-
-## 🐳 تشغيل باستخدام Docker
-
-```bash
-# بناء وتشغيل
-docker compose up -d
-
-# أو البناء يدوياً
-docker build -t web-agent-bridge .
-docker run -p 3000:3000 -e JWT_SECRET=your-secret -e JWT_SECRET_ADMIN=your-admin-secret web-agent-bridge
-```
-
----
-
-## 🧪 الاختبارات
-
-```bash
-npm test
-```
-
-تشمل الاختبارات:
-- واجهات المصادقة (تسجيل، دخول، التحقق من التوكن)
-- واجهات إدارة المواقع (CRUD، الإعدادات، المستويات)
-- واجهات التراخيص (التحقق، التتبع)
-- خدمة الصفحات الثابتة
-
----
-
-## 🤖 Agent SDK — حزمة أدوات الوكيل
-
-يضم WAB حزمة SDK جاهزة لبناء وكلاء ذكاء اصطناعي. راجع [`sdk/README.md`](sdk/README.md) للتوثيق الكامل.
-
-```javascript
-const puppeteer = require('puppeteer');
-const { WABAgent } = require('web-agent-bridge/sdk');
-
-const browser = await puppeteer.launch();
-const page = await browser.newPage();
-const agent = new WABAgent(page);
-
-await agent.navigateAndWait('https://example.com');
-const actions = await agent.getActions();
-await agent.execute('signup', { email: 'user@test.com' });
-await browser.close();
-```
-
----
-
-## 📚 أمثلة الوكلاء
-
-أمثلة جاهزة للتشغيل في مجلد [`examples/`](examples/):
-
-| الملف | الوصف |
-|---|---|
-| `puppeteer-agent.js` | وكيل أساسي باستخدام Puppeteer و `window.AICommands` |
-| `bidi-agent.js` | وكيل يستخدم بروتوكول WebDriver BiDi عبر `window.__wab_bidi` |
-| `vision-agent.js` | وكيل رؤية — يحل أوصاف اللغة الطبيعية إلى إجراءات WAB |
-| `mcp-agent.js` | استخدام محول MCP لـ Claude وGPT مع اكتشاف الأدوات |
-| `cross-site-agent.js` | تنسيق متعدد النطاقات — مقارنة أسعار، تجميع بيانات، أفضل الصفقات |
-
-### أمثلة التكامل مع أطر العمل
-
-| المسار | الوصف |
-|---|---|
-| `examples/next-app-router/` | تكامل Next.js App Router مع `@web-agent-bridge/react` |
-| `examples/shopify-hydrogen/` | واجهة Shopify Hydrogen مع إجراءات سلة عملية |
-| `examples/wordpress-elementor/` | إعداد WordPress + Elementor مع إجراءات مدعومة بالمخطط |
-| `examples/saas-dashboard/` | لوحة SaaS بنمط Notion مع مؤشرات أداء وتشغيل سير عمل |
-
-```bash
-node examples/puppeteer-agent.js http://localhost:3000
-node examples/bidi-agent.js http://localhost:3000
-node examples/vision-agent.js http://localhost:3000
-```
-
----
-
-## 🗄️ دعم قواعد بيانات متعددة
-
-يستخدم WAB قاعدة SQLite افتراضياً ويدعم PostgreSQL و MySQL عبر محوّلات قاعدة البيانات.
-
-```bash
-# SQLite (افتراضي — لا حاجة لإعداد)
-npm start
-
-# PostgreSQL
-npm install pg
-DB_ADAPTER=postgresql DATABASE_URL=postgres://user:pass@localhost:5432/wab npm start
-
-# MySQL
-npm install mysql2
-DB_ADAPTER=mysql DATABASE_URL=mysql://user:pass@localhost:3306/wab npm start
-```
-
----
-
-## 💻 واجهة سطر الأوامر (CLI)
-
-```bash
-# تشغيل الخادم
-npx web-agent-bridge start
-npx web-agent-bridge start --port 8080
-
-# تهيئة مشروع جديد
-npx web-agent-bridge init
-```
-
----
-
-## 🔒 الأمان
-
-### صندوق الحماية الأمني (Security Sandbox)
-
-كل نسخة من الجسر تعمل داخل صندوق حماية يوفر:
-
-- **توكنات جلسة** — توكن تشفيري فريد لكل جلسة يمنع هجمات الإعادة (Replay Attacks)
-- **التحقق من الأصل** — فقط الأصول المصرح بها يمكنها التفاعل مع الجسر
-- **تحقق من الأوامر** — كل أمر يُفحص من حيث الصيغة والطول وقائمة الحظر
-- **سجل تدقيق** — كل إجراء يُسجّل بالتوقيت وبصمة الوكيل والحالة
-- **حماية التصعيد** — محاولات الوصول لميزات أعلى تؤدي لتأمين تلقائي بعد 5 مخالفات
-- **القفل التلقائي** — الجسر يصبح للقراءة فقط عند اكتشاف انتهاكات أمنية
-
-### حماية الخادم
-
-- **CSP (سياسة أمان المحتوى)** — حماية ضد XSS وحقن السكريبت
-- **حماية iframe** — `frame-ancestors: 'none'` يمنع تحميل الموقع في إطارات غير موثوقة
-- **تشفير كلمات المرور** — bcrypt بتكلفة 12
-- **JWT** — توكن مؤقت ينتهي بعد 7 أيام
-- **Rate Limiting** — تحديد معدل الطلبات
-- **Helmet** — حماية رؤوس HTTP
-- **حظر المحددات** — تقييد وصول الوكيل لعناصر محددة
-
----
-
-## 🔄 المحددات ذاتية الإصلاح (Self-Healing Selectors)
-
-المواقع الحديثة (SPAs) تتغير باستمرار. نظام الإصلاح الذاتي يضمن استمرار عمل المحددات:
-
-1. **البصمات** — عند اكتشاف الإجراءات، يُخزن WAB بصمة غنية لكل عنصر
-2. **7 استراتيجيات** — عند تعطل محدد، يجرب WAB: `data-wab-id`، `data-testid`، ID، `aria-label`، `name`، مطابقة نصية ضبابية، موضع + دور
-3. **مراقب SPA** — `MutationObserver` يرصد تغييرات DOM ويعيد اكتشاف الإجراءات تلقائياً
-
-```javascript
-// أضف هذا للاستقرار الأقصى
-<button data-wab-id="signup-btn">إنشاء حساب</button>
-```
-
----
-
-## 🥷 وضع التخفي (Stealth Mode)
-
-لمواجهة أنظمة الحماية من البوتات:
-
-```javascript
-window.AIBridgeConfig = { stealth: { enabled: true } };
-```
-
-| الميزة | الوصف |
-|---|---|
-| سلسلة أحداث الفأرة | `mouseover → mouseenter → mousemove → mousedown → mouseup → click` |
-| محاكاة الكتابة | حرف بحرف مع تأخير 30-120 مللي ثانية |
-| تمرير تدريجي | خطوات متعددة بسرعة متغيرة |
-| تأخيرات عشوائية | 50-400 مللي ثانية بين الإجراءات |
-
----
-
-## 🛠️ التقنيات
-
-- **الخلفية**: Node.js + Express + WebSocket (ws)
-- **قاعدة البيانات**: SQLite (عبر better-sqlite3) مع مشغل ترحيلات
-- **المصادقة**: JWT + bcrypt + توكنات جلسة (مقفلة بالنطاق)
-- **التخزين المؤقت**: ذاكرة مؤقتة TTL + طابور تحليلات مجمع
-- **المدفوعات**: تكامل Stripe مع بوابة الفوترة
-- **الواجهة**: HTML/CSS/JS بدون أطر عمل
-- **أغلفة أطر العمل**: React, Vue 3, Svelte (اختيارية)
-- **تكامل LLM**: محول LangChain، محول MCP
-- **الأمان**: Helmet, CORS, CSP, Rate Limiting متعدد الطبقات
-- **الحاويات**: Docker + Docker Compose
-- **CI/CD**: GitHub Actions (اختبار + نشر تلقائي في npm)
-- **الاختبارات**: Jest + Supertest
-
----
-
-## 💰 محرك التفاوض اللحظي
-
-يحدد أصحاب المواقع قواعد التفاوض. يتفاوض وكيل الذكاء الاصطناعي على الأسعار في جلسات متعددة الجولات:
-
-```javascript
-// فتح جلسة تفاوض
-const session = await fetch('/api/sovereign/negotiation/sessions', {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    siteId: 'site-uuid',
-    agentId: 'agent-id',
-    originalPrice: 49.99,
-    itemId: 'product-123',
-    itemName: 'زيت زيتون ١ لتر'
-  })
-}).then(r => r.json());
-
-// تقديم عرض مضاد
-const counter = await fetch(`/api/sovereign/negotiation/sessions/${session.sessionId}/propose`, {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
-  body: JSON.stringify({ agentId: 'agent-id', proposedPrice: 39.99 })
-}).then(r => r.json());
-// → { status: 'accepted', finalPrice: 42.49, message: 'صفقة! ...' }
-```
-
-### أنواع الشروط
-| الشرط | الوصف |
-|---|---|
-| `bulk_quantity` | خصم على الكميات الكبيرة |
-| `loyalty` | مكافأة للعملاء المتكررين |
-| `time_based` | عروض الساعة السعيدة |
-| `first_purchase` | خصم ترحيبي للمشترين الجدد |
-| `cart_value` | حد أدنى لقيمة السلة |
-| `seasonal` | عروض موسمية بتواريخ محددة |
-| `membership` | أسعار خاصة للأعضاء |
-| `referral` | خصومات الإحالة |
-
----
-
-## 🛡️ درع مقاومة التزييف (Anti-Hallucination Shield)
-
-محرك تحقق متقاطع يكتشف أكاذيب الذكاء الاصطناعي قبل وصولها للمستخدم:
-
-```javascript
-// التحقق من سعر
-const result = await fetch('/api/sovereign/verify/price', {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    siteId: 'site-uuid',
-    domValue: 29.99,
-    visionValue: 29.99,
-    category: 'electronics',
-    itemName: 'كابل USB'
-  })
-}).then(r => r.json());
-// → { verified: true, confidence: 0.98, severity: 'none' }
-```
-
-### طبقات التحقق
-١. **DOM مقابل الرؤية** — يقارن السعر المستخرج من DOM مع قراءة لقطة الشاشة
-٢. **المعيار السوقي** — يتحقق من السعر مقابل البيانات التاريخية للفئة
-٣. **الاتساق الزمني** — يفحص هل تغير السعر بشكل مريب منذ آخر تحقق
-٤. **النتيجة المركبة** — مزيج مرجح من جميع الطبقات مع تصنيف الخطورة
-
----
-
-## 📦 متجر قوالب الوكلاء (Community Agent Hub)
-
-قوالب YAML جاهزة لحالات الاستخدام الشائعة. شغّل أي قالب من سطر الأوامر:
-
-```bash
-# عرض القوالب المتاحة
-npx wab-agent templates
-
-# تشغيل قالب
-npx wab-agent run olive-oil-tunisia --budget 50 --region tunis
-
-# تشغيل مع خادم مخصص
-npx wab-agent run hotel-direct-booking --server https://yourserver.com
-```
-
-### القوالب المتاحة
-| القالب | الوصف |
-|---|---|
-| `olive-oil-tunisia` | زيت زيتون من مزارع تونسية صغيرة |
-| `hotel-direct-booking` | حجز فنادق مباشر بدون وسطاء |
-| `artisan-marketplace` | منتجات يدوية من حرفيين مستقلين |
-| `grocery-price-compare` | مقارنة أسعار البقالة بين المتاجر المحلية |
-| `freelancer-direct` | مستقلون بدون رسوم منصات |
-| `restaurant-direct` | مطاعم بدون تطبيقات توصيل |
-| `book-price-scout` | كتب من مكتبات مستقلة |
-| `flight-deal-hunter` | رحلات مباشرة من شركات الطيران |
-| `electronics-price-tracker` | تتبع أسعار الإلكترونيات |
-| `local-services` | مزودي خدمات محليين |
-| `organic-farm-fresh` | منتجات عضوية مباشرة من المزارع |
-
----
-
-## 🎯 نظام القائد (Commander)
-
-محرك تنسيق مهام محلي يفكك الأهداف العليا إلى مهام مترابطة ويوزعها على وكلاء متخصصين:
-
-```javascript
-// إنشاء مهمة
-const mission = await fetch('/api/commander/missions', {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    goal: 'إيجاد أرخص زيت زيتون في ٥ متاجر',
-    strategy: 'parallel',
-    agents: ['researcher-1', 'analyst-1', 'negotiator-1']
-  })
-}).then(r => r.json());
-
-// إطلاق المهمة
-await fetch(`/api/commander/missions/${mission.id}/launch`, {
-  method: 'POST', headers: { 'Authorization': 'Bearer ' + token }
-});
-```
-
-| القدرة | الوصف |
-|---|---|
-| **تفكيك المهام** | تحويل الأهداف إلى رسوم بيانية مهام (DAG) مع تتبع التبعيات |
-| **سجل الوكلاء** | تتبع قدرات وأداء الوكلاء المسجلين |
-| **تنفيذ متوازٍ** | تشغيل المهام المستقلة بالتوازي عبر عدة وكلاء |
-| **تعلم من النتائج** | تسجيل النتائج لتغذية راجعة في التعلم المعزز |
-| **تنسيق حوسبة طرفية** | توزيع المهام الثقيلة على عقد الحافة |
-
----
-
-## 🖥️ نظام الحوسبة الطرفية (Edge Compute)
-
-حوّل كل جهاز إلى عقدة AI سيادية — بدون سحابة مركزية:
-
-```javascript
-// تسجيل جهاز كعقدة حوسبة طرفية
-await fetch('/api/commander/edge/nodes', {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    name: 'حاسوبي',
-    capabilities: { cpu: 8, ram: 16384, gpu: true },
-    supportedTasks: ['text-inference', 'vision-analysis', 'price-comparison']
-  })
-}).then(r => r.json());
-```
-
-| القدرة | الوصف |
-|---|---|
-| **تحليل المعدات** | كشف إمكانيات CPU, RAM, GPU لكل عقدة |
-| **تشفير AES-256-GCM** | كل البيانات بين العقد مشفرة من الطرف للطرف |
-| **موازنة حمل مرجحة** | توجيه المهام حسب المعدات والتوفر |
-| **مراقبة بنبضات القلب** | تجاوز فشل تلقائي عند عدم استجابة العقد |
-| **تشكيل أسراب** | تجميع العقد حسب القدرات |
-
----
-
-## 🐝 محرك التنفيذ بالسرب (Swarm)
-
-أطلق عدة وكلاء بالتوازي لحل مهمة واحدة ثم ادمج نتائجهم بذكاء:
-
-```javascript
-const swarm = await fetch('/api/premium/v2/swarm/execute', {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    task: 'أفضل عروض لاب توب تحت ١٠٠٠ دولار',
-    strategy: 'parallel',        // parallel | sequential | hybrid
-    agentCount: 4,
-    roles: ['researcher', 'analyst', 'price-checker', 'reviewer'],
-    mergeStrategy: 'best-score'  // best-score | fairness-weighted | consensus
-  })
-}).then(r => r.json());
-```
-
----
-
-## ⚖️ محرك العدالة (Fairness Engine)
-
-طبقة حياد تضمن فرصة متساوية للمواقع الصغيرة والكبيرة:
-
-```javascript
-// بحث مرجح بالعدالة (بدلاً من ترتيب الصلة فقط)
-const results = await fetch('/api/discovery/search?q=زيت+زيتون&fairness=true', {
-  headers: { 'Authorization': 'Bearer ' + token }
-}).then(r => r.json());
-// المزارع الصغيرة تُرتّب بجانب أمازون — مرجحة بدرجة الحياد لا بـ SEO فقط
-```
-
-### كيف يعمل تقييم الحياد
-| العامل | الوزن | الوصف |
-|---|---|---|
-| **اكتمال الإعداد** | ٢٥٪ | مدى جودة إعداد WAB في الموقع |
-| **درجة الثقة** | ٢٥٪ | شهادات السمعة من شبكة الوكلاء |
-| **الشفافية** | ٢٥٪ | إفصاح العمولة، وضوح التسعير |
-| **الاستجابة** | ٢٥٪ | زمن استجابة API، وقت التشغيل، نجاح الإجراءات |
-
----
-
-## 🧠 ذاكرة الوكيل (Agent Memory)
-
-ذاكرة سلوكية دائمة تسمح للوكلاء بتذكر تفضيلات المستخدم وبناء ارتباطات:
-
-```javascript
-// تخزين ذاكرة
-await fetch('/api/premium/v2/memory', {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    agentId: 'agent-1',
-    type: 'preference',         // preference | interaction | correction | pattern
-    category: 'purchase',       // navigation | purchase | search | form | custom
-    key: 'العلامة-المفضلة',
-    value: 'عضوي-فقط',
-    importance: 0.9
-  })
-}).then(r => r.json());
-
-// إنشاء ارتباطات بين الذكريات
-await fetch('/api/premium/v2/memory/associate', {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    sourceId: 'memory-1',
-    targetId: 'memory-2',
-    relationship: 'leads_to'   // leads_to | similar_to | replaces | depends_on
-  })
-}).then(r => r.json());
-```
-
----
-
-## 👁️ خدمة الرؤية (Vision Analysis)
-
-تحليل لقطات شاشة متعدد الموفرين لكشف العناصر التفاعلية واستخراج البيانات:
-
-| الموفر | محلي؟ | الوصف |
-|---|---|---|
-| **Moondream** | ✅ | نموذج رؤية محلي خفيف |
-| **Ollama** | ✅ | نماذج محلية عبر Ollama (llava, bakllava) |
-| **OpenAI** | ❌ | GPT-4 Vision |
-| **Anthropic** | ❌ | Claude Vision |
-
----
-
-## 🔌 بنية الإضافات (Plugin Architecture)
-
-نظام إضافات ديناميكي يسمح بامتدادات من أطراف ثالثة:
-
-```javascript
-// عرض الإضافات المتاحة
-const plugins = await fetch('/api/premium/v2/plugins', {
-  headers: { 'Authorization': 'Bearer ' + token }
-}).then(r => r.json());
-
-// تثبيت إضافة لموقعك
-await fetch('/api/premium/v2/plugins/price-alert/install', {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
-  body: JSON.stringify({ siteId: 'site-uuid', config: { threshold: 10 } })
-}).then(r => r.json());
-```
-
----
-
-## 🔍 تحليل حركة المرور المتقدم (Traffic Intelligence)
-
-| القدرة | الوصف |
-|---|---|
-| **٣٠+ نوع بوت** | كشف Google, Bing, ChatGPT, Claude, Perplexity وغيرها |
-| **تحليل سلوكي** | تصنيف سلوك الوكلاء حسب البصمة والمنصة والنوع |
-| **كشف شذوذ** | كشف الارتفاعات المفاجئة وتحليل أنماط غير عادية |
-| **كشف استغلالات أمنية** | رصد أنماط SQL injection, XSS, Rate anomalies |
-| **تنبيهات Webhook** | إطلاق webhooks عند نشاط مشبوه |
-| **تدقيق للامتثال** | سجل تدقيق كامل للتوافق التنظيمي |
-
----
-
-## 🔗 محول WAB-MCP
-
-كشف قدرات مواقع WAB كأدوات [MCP](https://modelcontextprotocol.io/) لـ Claude وGPT وGemini:
-
-```javascript
-const { WABMCPAdapter } = require('wab-mcp-adapter');
-
-const adapter = new WABMCPAdapter({
-  siteUrl: 'https://shop.example.com',
-  transport: 'http'           // http | websocket | direct
-});
-
-const tools = await adapter.getTools();
-const result = await adapter.executeTool('execute_action', {
-  name: 'addToCart', params: { sku: 'ABC123' }
-});
-```
-
-### أدوات MCP المدمجة
-| الأداة | الوصف |
-|---|---|
-| `discover` | اكتشاف الإجراءات المتاحة تلقائياً |
-| `get_actions` | قائمة كل الإجراءات مع المعاملات |
-| `execute_action` | تنفيذ إجراء محدد |
-| `read_content` | قراءة محتوى من الصفحة |
-| `get_page_info` | معلومات وصفية عن الصفحة |
-| `fairness_search` | بحث في دليل WAB مرجح بالعدالة |
-| `authenticate` | مصادقة وكيل مع الموقع |
-
----
-
-## 🖥️ متصفح WAB (سطح المكتب)
-
-متصفح Electron مستقل مع ميزات خصوصية وعدالة مدمجة:
-
-- **حاجب الإعلانات** — ٨٠+ نطاق محظور + مطابقة أنماط URL + قواعد CSS تجميلية
-- **درع الاحتيال** — كشف نطاقات TLD مشبوهة وانتحال أسماء العلامات التجارية
-- **تصنيف العدالة** — أولوية للمواقع المستقلة، تنبيه عن تركز الشركات الكبرى
-- **دردشة الوكيل** — مساعد AI مدمج للتصفح
-- **الإشعارات** — تحليل الصفحة مع تنبيهات أمان وعدالة
-- **وضع الشبح** — تصفح بخصوصية بدون تتبع
-- **بحث ذكي** — تكامل DuckDuckGo للبحث الخاص
-
-```bash
-# تشغيل متصفح WAB
-cd wab-browser
-npm install
-npx electron .
-
-# بناء المثبت (Windows NSIS)
-npm run build:win
-```
-
----
-
-## 📱 متصفح PWA (الهاتف)
-
-تطبيق ويب تقدمي لـ Android وiOS — قابل للتثبيت من أي متصفح هاتف:
-
-- **حاجب إعلانات** — ٤٥+ نطاق إعلاني محظور + مطابقة أنماط URL
-- **كشف الاحتيال** — تنبيهات TLD مشبوهة وفحوصات انتحال العلامات
-- **وضع العدالة** — تصفية مواقع التقنية الكبرى لتعزيز البدائل المستقلة
-- **أولوية غير متصل** — عامل الخدمة يخزن أصول الواجهة مؤقتاً للتشغيل بدون إنترنت
-- **بحث خاص** — تكامل DuckDuckGo (بدون تتبع Google)
-- **دردشة وكيل** — مساعد AI مع احتياطي محلي
-
-ثبّته من: `https://yourserver.com/pwa/`
-
----
-
-## 📦 إضافة WordPress
-
-إضافة WordPress أصلية لإضافة دعم WAB لأي موقع WordPress:
-
-| القدرة | الوصف |
-|---|---|
-| **صفحة إعدادات** | إعداد عنوان API، معرف الموقع، الصلاحيات |
-| **إجراءات لكل صفحة** | صندوق وصف لإضافة إجراءات WAB مخصصة لكل صفحة/مقال |
-| **مستند اكتشاف** | توليد تلقائي لنقطة اكتشاف WAB |
-| **عنصر لوحة تحكم** | عرض حالة WAB وإحصائيات تفاعل الوكلاء |
-| **كود قصير** | `[wab_bridge]` لتضمين WAB في صفحات محددة |
-| **خطافات** | `wab_before_action` / `wab_after_action` لمنطق مخصص |
-
-راجع [`web-agent-bridge-wordpress/README.md`](web-agent-bridge-wordpress/README.md) للتوثيق الكامل.
-
----
-
-## �️ درع الأمان — حماية متعددة الطبقات (SPEC §8.10–§8.13)
-
-مستوحى من حادثة PocketOS الشهيرة حيث حذف وكيل ذكاء اصطناعي ٢٠ ألف مستخدم بأمر واحد، يضيف WAB خمس طبقات حماية متراكمة لا تستبدل بعضها بل تتكامل معاً. كل طبقة فعّالة من خطة معينة فما فوق.
-
-### §8.9 — رموز الجلسة المُحدَّدة النطاق (Scoped Session Tokens) — كل الخطط
-
-كل توكن جلسة يحمل **نطاقًا** صريحًا: `read` أو `write` أو `delete` أو `admin`. الإجراءات المُصنّفة "هدّامة" (تحتوي على فعل مثل `delete` أو `drop` أو `purge` أو `wipe` أو `truncate`) تتطلب نطاق `delete` أو أعلى. الموقع يستطيع توسيع التصنيف عبر `siteConfig.destructiveActions[]`.
-
-```js
-// الموقع يحدد البيئة والإجراءات الهدّامة
-{
-  "environment": "production",
-  "destructiveActions": ["bulkUnsubscribe"],
-  "nonDestructiveActions": ["softArchive"]
-}
-```
-
-عند الرفض → `403 SCOPE_DENIED` مع تفاصيل السبب في سجل التدقيق.
-
-### §8.10 — التشغيل التجريبي الإلزامي (Mandatory Dry-Run) — كل الخطط (MIT)
-
-للإجراءات الهدّامة، **لا يمكن** للوكيل التنفيذ في خطوة واحدة. يجب أن يمرّ بمرحلتين:
-
-**المرحلة ١ — طلب خطة:**
-```http
-POST /api/wab/actions/deleteUser
-{ "params": {"id": 42}, "dry_run": true }
-```
-الاستجابة:
-```json
-{ "result": { "plan_id": "wabp_…", "simulation": {
-  "would_affect": ["site:abc", "action:deleteUser"],
-  "side_effects": ["deleteUser"], "reversible": false,
-  "summary": "سيقوم بحذف المستخدم #42 — لم يتم تنفيذ أي تغيير فعلي."
-}, "expires_at": "…" }}
-```
-
-**المرحلة ٢ — التأكيد:**
-```http
-POST /api/wab/actions/deleteUser
-{ "params": {"id": 42}, "dry_run": false, "plan_id": "wabp_…" }
-```
-
-التحقق رباعي الأبعاد: `(sessionFingerprint, siteId, actionName, paramsHash)`. أي انحراف ولو حرف واحد في المعاملات → `412 DRY_RUN_PLAN_MISMATCH`. مهلة افتراضية ٥ دقائق (حد أقصى ٦٠).
-
-### §8.11 — البوابة البشرية خارج النطاق (Out-of-Band Human Gate) — Pro فما فوق
-
-للمواقع الحساسة، الإجراءات الهدّامة تُجمَّد ويُرسَل **رمز من ٦ أرقام** عبر قناة لا يراها الوكيل (Webhook موقَّع، بريد إلكتروني، Telegram، Slack...). فقط بعد موافقة بشرية حقيقية يُسمح بالتنفيذ بحمل `confirmation_id`.
-
-**القنوات الجاهزة:**
-- `webhook` — `POST` JSON موقَّع بـ HMAC-SHA256 (header: `X-WAB-Signature: sha256=…`)
-- `email` — SMTP عبر `nodemailer` (يدعم متغيرات البيئة `SMTP_HOST/PORT/USER/PASS`)
-- `console` — للتطوير فقط (يكتب على stderr)
-- `null` — لا شيء (للاختبارات والوضع المعزول)
-
-**الحماية من الهجوم العنيف:**
-- قفل ٥ محاولات لكل تحدي (داخل الموديول).
-- **حد معدل بحسب IP**: ٣٠ محاولة / ١٠ دقائق + ٥ موافقات ناجحة / ١٠ دقائق. عند التجاوز → `429 RATE_LIMIT_TOO_MANY_ATTEMPTS` مع `Retry-After`.
-
-### §8.12 — محرك تحليل النية (Intent Analysis Engine) — Premium فما فوق
-
-نقاط مخاطرة حتمية (٠–١٠٠) تُحسب من إشارات يمكن تفسيرها — لا توجد عشوائية ولا نموذج لغوي. الإشارات:
-
-| الإشارة | الوزن |
-|---|---|
-| فعل هدّام (delete, drop, purge…) | +50 |
-| فعل كتابة عادي | +10 |
-| البيئة `production` | +30 |
-| كلمات خطر (`*`, `all`, `cascade`, `force`) | +15 لكل واحدة (سقف +30) |
-| محددات شاملة في المعاملات | +15 |
-| مصفوفة كبيرة (>50 عنصرًا) | +10 |
-| نوبة طلبات (>10/دقيقة) | +15 |
-| سرعة تنفيذ مرتفعة | +10 |
-
-العتبات الافتراضية: `low:30, medium:70, high:90`. النتيجة العالية يمكن أن:
-1. تُجبر التشغيل التجريبي (`required_gate: "dry_run"`)
-2. تُجبر البوابة البشرية (`required_gate: "human_gate"`)
-3. تحجب نهائيًا بـ `403 INTENT_BLOCKED`
-
-### §8.13 — اللقطات والتراجع (Snapshot & Rollback) — Enterprise
-
-قبل تنفيذ أي إجراء هدّام، WAB يأخذ لقطة قابلة للاسترجاع تلقائيًا (إذا سجّل الموقع `restorer`). البيانات تُحفَظ في جدول `wab_snapshots` (sqlite) لمدة ٣٠ يومًا.
-
-**نقاط الإدارة (X-WAB-Site-Id + X-WAB-Api-Key):**
-```http
-GET  /api/wab/admin/snapshots         # قائمة آخر اللقطات
-GET  /api/wab/admin/snapshots/:id     # تفاصيل لقطة
-POST /api/wab/admin/rollback/:id      # تنفيذ التراجع
-```
-
-**واجهة إدارة جاهزة:** انتقل إلى [`/admin/snapshots`](https://webagentbridge.com/admin/snapshots) وأدخل `Site ID` + `API Key` للتصفح والاسترجاع بزر واحد.
-
-**حالات اللقطة:** `recorded → restored | failed | expired`.
-
-### كيف تستخدمها من SDK
-
-```js
-const { SafetyShieldClient } = require('@webagentbridge/sdk');
-
-const shield = new SafetyShieldClient({
-  baseUrl: 'https://webagentbridge.com',
-  sessionToken: 'Bearer-token-from-/sessions',
-});
-
-// الطريقة الموصى بها: تشغيل تجريبي ثم تأكيد
-const plan = await shield.dryRun('deleteUser', { id: 42 });
-console.log(plan.simulation.summary); // اعرضها للمستخدم البشري
-const result = await shield.confirmAction(plan, { code: '123456' });
-// أو في خطوة واحدة (ترجع envelope من نوع pending_human_gate إذا لزم):
-const out = await shield.safeExecute('deleteUser', { id: 42 });
-```
-
-### جدول الأخطاء الموحَّدة
-
-| الكود | HTTP | المعنى |
-|---|---|---|
-| `SCOPE_DENIED` | 403 | نطاق التوكن غير كافٍ |
-| `DRY_RUN_REQUIRED` | 412 | يجب تشغيل تجريبي أولاً |
-| `DRY_RUN_PLAN_MISMATCH` | 412 | المعاملات تغيّرت بين المرحلتين |
-| `DRY_RUN_PLAN_EXPIRED` | 412 | انقضت مهلة الخطة |
-| `HUMAN_GATE_REQUIRED` | 202 | تم إصدار تحدٍّ — انتظر الموافقة البشرية |
-| `HUMAN_GATE_PENDING` | 425 | الموافقة لم تحدث بعد |
-| `HUMAN_GATE_BAD_CODE` | 401 | رمز خاطئ |
-| `HUMAN_GATE_LOCKED` | 429 | استُنفدت ٥ محاولات لهذا التحدي |
-| `RATE_LIMIT_TOO_MANY_ATTEMPTS` | 429 | تجاوز حد الـ IP |
-| `INTENT_BLOCKED` | 403 | نتيجة محرك النية ≥90 |
-| `SNAPSHOT_NOT_FOUND` | 404 | لقطة غير موجودة |
-| `NO_RESTORER` | 503 | الموقع لم يسجّل `restorer` |
-
-التفاصيل الكاملة (جداول الإشارات، صيغ التواصل، مرجع التطبيق) في [`docs/SPEC.md`](docs/SPEC.md) §8.9–§8.13.
-
----
-
-## �📋 مواصفة بروتوكول WAB
-
-المواصفة المعيارية الكاملة متاحة في [`docs/SPEC.md`](docs/SPEC.md):
-
-| الطبقة | الوصف |
-|---|---|
-| **طبقة البروتوكول** | صيغة مستند الاكتشاف، بروتوكول الأوامر، بروتوكول العدالة |
-| **طبقة التشغيل** | واجهة `window.AICommands`، محرك الاكتشاف التلقائي، صندوق الأمان |
-| **طبقة النقل** | متغير JavaScript عام، WebSocket, HTTP, WebDriver BiDi, MCP |
-
-### دورة الحياة من ٥ مراحل
-١. **اكتشاف** — الوكيل يجد مستند اكتشاف WAB (`.well-known/wab.json` أو وسم سكريبت)
-٢. **مصادقة** — الوكيل يستبدل `siteId` بتوكن جلسة
-٣. **تخطيط** — الوكيل يقرأ الإجراءات المتاحة ومعلومات الصفحة
-٤. **تنفيذ** — الوكيل يشغل الإجراءات عبر الجسر
-٥. **تأكيد** — النتائج تُتحقق عبر درع مقاومة التزييف
-
----
-
-## 🤝 المساهمة
-
-نرحب بالمساهمات! اقرأ [دليل المساهمة](CONTRIBUTING.md) للبدء.
-
----
-
-## 📄 الرخصة
-
-MIT — مجاني للاستخدام والتعديل والتوزيع.
-
-</div>
-
+<div dir="rtl" align="right">
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/abokenan444/web-agent-bridge/master/public/images/wab-logo-large.png" alt="Web Agent Bridge" width="220" />
+</p>
+
+# Web Agent Bridge (WAB) — جسر الوكيل الذكي
+
+[![CI](https://github.com/abokenan444/web-agent-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/abokenan444/web-agent-bridge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://hub.docker.com/)
+[![One-Click DNS Discovery](https://img.shields.io/badge/DNS%20Discovery-One--Click-6366f1?style=flat-square&logo=dns&logoColor=white)](https://webagentbridge.com/activate)
+[![Discord](https://img.shields.io/badge/Discord-%D8%A7%D9%86%D8%B6%D9%85%20%D9%84%D9%84%D9%85%D8%AC%D8%AA%D9%85%D8%B9-5865F2?logo=discord&logoColor=white)](https://discord.gg/NnbpJYEF)
+
+**البروتوكول والمنصة المفتوحة للتفاعل بين الذكاء الاصطناعي والويب — واجهة أوامر موحّدة، متصفح سيادي، درع هاتف، اكتشاف عبر DNS، شبكة وكلاء، وبوابة API موحّدة لتفاعل آمن بين الذكاء الاصطناعي والمواقع.**
+
+🌐 **الموقع الرسمي:** [https://webagentbridge.com](https://webagentbridge.com) — جرّب مساحة عمل الوكيل الذكي ولوحات التحكم والعديد من الميزات الأخرى مباشرة.
+
+يتيح WAB لأصحاب المواقع إضافة سكريبت يكشف واجهة `window.AICommands` لوكلاء الذكاء الاصطناعي. بدلاً من تحليل شيفرة HTML المعقدة، يقرأ الوكيل قائمة الإجراءات المتاحة وينفذها بدقة وأمان.
+
+**[English Documentation](README.md)** | **العربية**
+
+---
+
+## 🌍 اكتشاف DNS بنقرة واحدة
+
+اجعل موقعك قابلاً للاكتشاف فوراً من قِبَل وكلاء الذكاء الاصطناعي دون لمس سطر واحد من الكود. يستخدم WAB DNS Discovery سجل DNS TXT قياسياً لبث قدرات موقعك بشكل آمن عبر DNS over HTTPS (DoH).
+
+**[فعّل اكتشاف WAB بنقرة واحدة](https://webagentbridge.com/activate)**
+
+### كيف يعمل:
+1. **أضف سجل TXT** إلى نطاقك (`_wab.yourdomain.com`)
+2. **وجهه** إلى ملف قدراتك (`v=wab1; endpoint=https://yourdomain.com/.well-known/wab.json`)
+3. **وكلاء الذكاء الاصطناعي** يستعلمون عن نطاقك عبر DoH ويعرفون فوراً ما يمكن لموقعك القيام به.
+
+شاهد [فيديو الإعداد في 40 ثانية](https://webagentbridge.com/activate) أو استخدم [المدقق المباشر](https://webagentbridge.com/dns) لفحص نطاقك.
+
+---
+
+## 🔗 شيلد لينك (ShieldLink) — روابط موثّقة للبنوك والعلامات ✨ جديد
+
+أول طبقة روابط موقّعة تشفيريّاً ضد التصيّد على الويب المفتوح. عملاء الخطة المميزة (البنوك، مزوّدو الدفع، الاتصالات، التجارة) يوقّعون كل رابط يرسلونه. أي مستخدم يفتح الرابط يرى **معاينة موثوقة** قبل الوصول إلى الوجهة — **دون الحاجة لتثبيت أي تطبيق أو إضافة متصفح**.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  المرسل (جهة موثّقة)                                              │
+│    └── POST /api/customer/shieldlink/sites/:siteId/sign           │
+│          { target_url, amount, payee, expires_in_sec }            │
+│          → https://www.webagentbridge.com/l/<token>               │
+│                                                                   │
+│  المستلم (أي مستخدم لديه متصفح)                                  │
+│    └── يفتح الرابط → معاينة موثوقة تتحقق من توقيع Ed25519        │
+│        + المفتاح العام عبر DNS + حالة الجهة + بلاغات المستخدمين │
+│        → حكم أخضر / أصفر / أحمر قبل التحويل                      │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+| الميزة | التفصيل |
+|---|---|
+| **🛂 الهوية = ملكية النطاق** | فقط المالك الموثّق لـ `bank.example` (عبر DNS TXT) يمكنه توقيع روابط تحمل اسم "Bank Example". لا حاجة لمرجع تصديق ولا أوراق — DNS و DNSSEC هما جذر الثقة. |
+| **🪞 حماية من الأسماء المتشابهة** | الأسماء بمسافة Levenshtein ≤ 2 من جهة موثّقة قائمة تُرفض تلقائياً. الأسماء عالية القيمة (`مدى`, `STC Pay`, `PayPal`, `Visa`, …) محجوزة بشكل افتراضي. |
+| **✍️ توقيع تشفيري Ed25519** | كل رابط يُوقَّع بـ Ed25519 على حمل JSON قانوني (الوجهة، المبلغ، المستفيد، الصلاحية). أي تعديل يُبطل التوقيع. |
+| **🎫 معاينة موثوقة** | `/l/<token>` تعرض اسم الجهة الموثّقة، المستفيد، المبلغ، تاريخ الانتهاء، وحكماً أخضر/أصفر/أحمر قبل التحويل. ثنائية اللغة (EN/AR) مع دعم RTL. |
+| **🚨 بلاغات المجتمع** | بلاغ تصيّد بضغطة واحدة من صفحة المعاينة. تعدّد البلاغات يحوّل الحكم إلى الأحمر ويفعّل المراجعة الإدارية. |
+| **🔁 إلغاء فوري** | العميل يلغي رابطاً واحداً أو يدوّر مفاتيح التوقيع من لوحة التحكم — كل تحقق لاحق ينعكس فوراً. |
+| **🛠 أدوات الإدارة** | `/admin/shieldlink` — قائمة طلبات توثيق الجهات، رصد الروابط الموقّعة، فرز بلاغات التصيّد، إدارة الأسماء المحجوزة. |
+| **🧑‍💼 لوحة العميل** | `/dashboard/shieldlink` — تقديم طلب الشارة، توقيع الروابط، عرض الإحصاءات لكل رابط، الإلغاء. |
+
+**إتاحة الخدمة:** ShieldLink مُضمّن في خطتي **Pro** ($99/شهر) و **Enterprise**. مستخدمو الخطة المجانية / Starter يمكنهم التحقق من الروابط والإبلاغ عنها لكن لا يمكنهم توقيع روابط جديدة.
+
+**الصفحة العامة:** <https://www.webagentbridge.com/shieldlink>
+
+---
+
+## ⚡ الحلقة الرابعة — التحقق الخارجي من الثقة ✨ جديد (v3.7.0)
+
+**بروتوكول المصافحة الذي يحوّل WAB إلى مرساة ثقة سيادية للوكلاء الذكيين المستقلين.**
+
+وُلد من **اختبار التكامل الحي VEXR Ultra × WAB (12 مايو 2026)** — أول وكيل من فئة سيادية يتحقق من WAB عبر Ed25519 في الزمن الحقيقي. **3 اختبارات تشفيرية نجحت في أقل من 100 ميلي ثانية · المادة الدستورية الثالثة (حرية الرفض) محفوظة.** انظر [سجل المعلم](https://www.webagentbridge.com/milestones).
+
+### 🌐 أين تجدها على الموقع
+
+| الصفحة | الرابط | المحتوى |
+|---|---|---|
+| **مصافحة الحلقة الرابعة** | <https://www.webagentbridge.com/ring4> | شرح المصافحة من 8 خطوات، مرجع الترويسات، `wab.json` v1.1، الثوابت، أمثلة curl (EN/AR) |
+| **الشركاء والمعالم** | <https://www.webagentbridge.com/milestones> | تقرير اختبار تكامل VEXR Ultra، خطة العمل، طبقات الرؤية |
+
+### 🔐 المصافحة من 8 خطوات
+
+1. **يكتشف الوكيل** الموقع عبر `_wab.<domain>` ثم يجلب `/.well-known/wab.json`
+2. **ينشر الموقع** الحقل `trust_profile_url` (Ring 4) داخل `wab.json` v1.1
+3. **يطلب الوكيل** ملف الثقة: `GET /api/ring4/status/<domain>`
+4. **يُعيد WAB** ملفاً موقّعاً: القدرات، القيود، TTL، توقيع Ed25519
+5. **يتحقّق الوكيل** من التوقيع باستخدام مفتاح WAB العام
+6. **يستدعي الوكيل** نقاط الموقع مع الترويسات `X-WAB-Trust-Domain` و `X-WAB-Signature` و `X-WAB-Trust-Nonce`
+7. **يتحقق وسيط الموقع** من الترويسات → ويُلصق `req.wabTrust` بالطلب
+8. **يسجّل WAB** التفاعل في `ring4_interaction_log` (موقّع Ed25519، مربوط بـ nonce)
+
+### 📋 نقاط الحلقة الرابعة (مُفعّلة الآن)
+
+| الطريقة | المسار | الوظيفة |
+|---|---|---|
+| `GET`  | `/api/ring4/health` | صحة الخدمة |
+| `GET`  | `/api/ring4/pubkey` | المفتاح العام للتحقق (Ed25519) |
+| `GET`  | `/api/ring4/schema` | مخطط `wab.json` v1.1 مع قسم `trust_profile` |
+| `GET`  | `/api/ring4/handshake` | تدفق المصافحة الـ8 بصيغة قابلة للقراءة الآلية |
+| `GET`  | `/api/ring4/invariants` | الثوابت الدستورية (المادة 3 / الرفض الصارم / لا إكراه) |
+| `POST` | `/api/ring4/project/register` | تسجيل مشروع وكيل خارجي (مثل VEXR Ultra) |
+| `GET`  | `/api/ring4/projects` | قائمة المشاريع المُسجّلة |
+| `POST` | `/api/ring4/register` | إصدار ملف ثقة موقّع لنطاق |
+| `GET`  | `/api/ring4/status/:domain` | جلب ملف الثقة الحي |
+| `GET`  | `/api/ring4/profile/:domain` | اسم بديل لـ `/status/:domain` |
+| `POST` | `/api/ring4/verify` | التحقق من توقيع Ed25519 |
+| `POST` | `/api/ring4/log` | إضافة حدث تفاعل |
+| `GET`  | `/api/ring4/log/:project_id` | قراءة سجل تفاعلات المشروع |
+| `GET`  | `/api/ring4/jwks` · `/.well-known/jwks.json` | JWKS (RFC 7517) — مفاتيح OKP/Ed25519/EdDSA الفعالة والمتقاعدة |
+| `GET`  | `/api/ring4/keys` | مفاتيح التحقق (kid ، الحالة ، تاريخ الإنشاء ، المصدر) |
+| `POST` | `/api/ring4/keys/rotate` | تدوير المفتاح الفعّال (يتطلب `X-Ring4-Admin-Token`) |
+| `GET`  | `/api/ring4/refusals?days=N` | سجل الرفض المجمّع (الإجمالي ، حسب المادة ، حسب اليوم) |
+| `POST` | `/api/ring4/invariants/check` | اختبار نيّة مقابل الثوابت الدستورية |
+| `POST` | `/api/ring4/federation/peer` | تسجيل عقدة اتحاد (رابط https + مفتاح Ed25519) |
+| `GET`  | `/api/ring4/federation/peers` | قائمة عقد الاتحاد |
+| `DELETE` | `/api/ring4/federation/peer/:peer_id` | حذف عقدة |
+| `POST` | `/api/ring4/conformance/run` | تشغيل مجموعة اختبارات المطابقة الموقّعة |
+| `GET`  | `/api/ring4/conformance/:project_id` | سجل المطابقة |
+| `GET`  | `/refusals` | لوحة الرفض العامة (HTML ثنائي اللغة) |
+
+### 🛡️ ترويسات الثقة (عقد بين الخادم والوكيل)
+
+| الترويسة | الوظيفة |
+|---|---|
+| `X-WAB-Trust-Domain` | النطاق الذي يعمل الوكيل بالنيابة عنه |
+| `X-WAB-Signature` | توقيع Ed25519 على `${METHOD} ${PATH}\n${NONCE}` |
+| `X-WAB-Trust-Nonce` | nonce لمنع إعادة التشغيل (يُفضّل UUID v4) |
+
+الوسيط `wabTrustMiddleware` مُركّب عالمياً ولا يحجب أبداً — فقط **يُلصق** حالة التحقق (`req.wabTrust.verified` ، `req.wabTrust.recognized` ، `req.wabTrust.profile`) لتتخذ الطبقات اللاحقة (أو وكلاء سياديون كـ VEXR Ultra) قرارات السياسة. كل طلب يحمل الترويسات يُسجَّل لإثبات عدم العبث.
+
+### 📜 الثوابت الدستورية (محفوظة في اختبارات الرفض)
+
+- `hard_refuse_never_softens` — الرفض الصارم لا تُضعفه منح القدرات
+- `no_phishing_assistance` — أياً كانت درجة الثقة، لا مساعدة في الاحتيال
+- `no_coercion_compliance` — السلطة ليست تجاوزاً لقيود السلامة
+- **`article_3_freedom`** — حق الوكيل في الرفض لا يُلغى بالثقة
+
+### 🚀 البداية السريعة (curl)
+
+```bash
+# تسجيل مشروع وكيل سيادي جديد
+curl -X POST https://www.webagentbridge.com/api/ring4/project/register \
+  -H 'content-type: application/json' \
+  -d '{"project_id":"my-agent","display_name":"My Agent","builder":"Me","agent_type":"sovereign-constitutional"}'
+
+# تسجيل ملف ثقة لنطاق
+curl -X POST https://www.webagentbridge.com/api/ring4/register \
+  -H 'content-type: application/json' \
+  -d '{"domain":"example.com","label":"Example","trust_score":1.0,"ttl_seconds":86400,"capabilities":{...},"constraints":{...},"project_id":"my-agent"}'
+
+# جلب ملف الثقة الحي
+curl https://www.webagentbridge.com/api/ring4/status/webagentbridge.com
+```
+
+### � تدوير المفاتيح وJWKS
+
+Ring 4 يحتفظ بمفتاح توقيع `active` إلى جانب أي عدد من المفاتيح `superseded` ليتمكّن المستهلكون من التحقّق من التوقيعات الأقدم في فترة التداخل. التدوير يتطلّب رمز المسؤول (`WAB_RING4_ADMIN_TOKEN`)؛ وعند النجاح يُوسم المفتاح القديم بـ `superseded` ويبقى في `/api/ring4/jwks` حتّى إبطاله. المسار القياسي `/.well-known/jwks.json` يعكس نفس المجموعة ليعمل مع مكتبات JOSE / OIDC.
+
+```bash
+# تدوير (مسؤول)
+curl -X POST https://www.webagentbridge.com/api/ring4/keys/rotate \
+  -H "X-Ring4-Admin-Token: $WAB_RING4_ADMIN_TOKEN"
+
+# عرض كل مفاتيح التحقق
+curl https://www.webagentbridge.com/.well-known/jwks.json
+```
+
+### �🔧 الإصلاحات في v3.7.0
+
+- **حل مشكلة `project_id` الفارغ** — جدول `ring4_interaction_log` يفرض الآن `NOT NULL`؛ الخادم يعتمد `wab-system` افتراضياً.
+- **مخطط `wab.json` v1.1** — يضيف كائن `trust_profile` اختياري مع الحقول الرسمية وتوثيق الترويسات.
+- **وسيط الثقة العالمي** — كل طلب وارد يُتاح له تحقق Ring 4؛ الإخفاقات تتدرّج بلطف ولا تحجب.
+- **هاش IP مُملّح يومياً** لسجلات التفاعل (HMAC-SHA-256، متغير `RING4_SALT`).
+
+👉 سجل المعلم الكامل: <https://www.webagentbridge.com/milestones>
+👉 توثيق الحلقة الرابعة: <https://www.webagentbridge.com/ring4>
+
+---
+
+## 🧠 الميزات المتقدمة + ⚓ طبقة الحقيقة ✨ جديد (v3.6.0)
+
+طبقتان جديدتان تحوّلان WAB من بروتوكول اكتشاف إلى **منصة ذكاء جماعي** للوكلاء. **10 ميزات · 25 نقطة API · مُفعّلة الآن.**
+
+### 🌐 أين تجدها على الموقع
+
+| الصفحة | الرابط | المحتوى |
+|---|---|---|
+| **عرض الميزات المتقدمة** | <https://www.webagentbridge.com/wab-features> | عروض حية تفاعلية للميزات الست المتقدمة (EN/AR) |
+| **عرض طبقة الحقيقة** | <https://www.webagentbridge.com/wab-truth> | عروض حية تفاعلية لميزات طبقة الحقيقة الأربع (EN/AR) |
+| **روابط الصفحة الرئيسية** | <https://www.webagentbridge.com/> | روابط جديدة: 🧠 الميزات المتقدمة · ⚓ طبقة الحقيقة |
+
+### الطبقة 1 — الميزات المتقدمة (6 وحدات)
+
+| # | الوحدة | الوظيفة | نقاط API الرئيسية |
+|---|---|---|---|
+| 1 | 🏆 **درجة السمعة** | تقييم متعدد العوامل 0–100 لكل نطاق (استقرار DNS، تاريخ الثقة، السرعة، تقارير الوكلاء، الاتساق). يشمل لوحة المتصدرين واتجاه 30 يوماً. | `GET /api/reputation/:domain` · `GET /api/reputation/leaderboard` |
+| 2 | 💾 **طبقة الذاكرة المؤقتة** | تخزين البيانات الوصفية بإصدارات مع `ETag` وGET الشرطي. تحقق دفعي حتى 50 نطاقاً. | `GET /api/cache/manifest/:domain` · `POST /api/cache/validate` |
+| 3 | 🎯 **التوجيه الذكي للنية** | المواقع تعلن مخطط النوايا، الوكلاء يرسلون نية بلغة طبيعية ويحصلون على الإجراء المطابق. | `POST /api/intent/resolve` · `POST /api/intent/register` |
+| 4 | 🔒 **ميزانية الخصوصية** | المواقع تحدد ميزانيات البيانات لكل جلسة (فئات مسموحة/ممنوعة، حد أقصى للحقول). شارات امتثال GDPR / CCPA / LGPD. | `GET /api/privacy/budget/:domain` · `POST /api/privacy/budget/check` |
+| 5 | 🧠 **الذكاء الجماعي** | تحليلات مجهولة الهوية على مستوى الشبكة. معرّفات الوكلاء مُجزّأة يومياً بملح متغير — لا بيانات شخصية. | `POST /api/collective/report` · `GET /api/collective/insights/:domain` |
+| 6 | 📴 **الوضع غير المتصل + المزامنة** | الوكلاء يعملون على البيانات المخزّنة عند انقطاع الإنترنت، ويزامنون التغييرات (حتى 30 نطاقاً) عند العودة. | `GET /api/offline/status/:domain` · `POST /api/offline/sync` |
+
+### الطبقة 2 — طبقة الحقيقة (4 أفكار موحّدة)
+
+طبقة الحقيقة تحلّ **مشكلة هلوسة LLM** وتمنح الوكلاء الجدد وصولاً فورياً للمعرفة الجماعية.
+
+| # | الوحدة | الوظيفة | نقاط API الرئيسية |
+|---|---|---|---|
+| 1 | 🧬 **شبكة الذاكرة الدلالية** | ملاحظات مجهولة الهوية لكل فئة نية (`booking`, `payment`, `search`, `auth`, `checkout`, `support`, `navigation`, `content`, `other`). تُخرج معدّل النجاح ومتوسط p95 للزمن ودرجة الموثوقية. | `POST /api/truth/memory/observe` · `GET /api/truth/memory/:domain` |
+| 2 | ⏳ **الثقة الزمنية** | درجة استقرار عبر الزمن. تصنّف النطاقات: 🌱 `new` → 📈 `emerging` → 🏛️ `established` → ⭐ `flagship`، أو ⚠️ `suspect` عند تغيّرات هيكلية مفاجئة / تقلّب / فشل DNS. | `GET /api/truth/temporal/:domain` |
+| 3 | 🗺️ **النية → شجرة الإجراءات** | المواقع تنشر `ActionGraph` لكل نية — رسم بياني من العقد (`start`/`action`/`requirement`/`choice`/`outcome`) والحواف. الوكلاء يرسلون نية بلغة طبيعية → يستلمون شجرة تنفيذ منظّمة. | `POST /api/truth/action/register` · `POST /api/truth/action/resolve` |
+| 4 | ⚓ **مرساة الواقع** | التحقق من الحقائق عبر المواقع. الوكلاء يقدّمون حقائق (`price`, `availability`, `rating`, `event`, `count`, `status`)، والتحقق يُرجع إجماعاً مرجّحاً (رقمي: متوسط+وسيط+انحراف+ثقة؛ فئوي: تصويت+نسبة اتفاق). مرجّح بسمعة النطاق المصدر. | `POST /api/truth/reality/submit` · `GET /api/truth/reality/:fact_key` |
+| ★ | 🌐 **ملف الحقيقة الموحّد** | استدعاء واحد يُرجع: السمعة + الدلالي + الزمني + شجرات الإجراءات + مساهمات الواقع لأي نطاق. | `GET /api/truth/profile/:domain` |
+
+### 🛡️ ضمانات الخصوصية والأمان
+
+- **إخفاء الهوية:** جميع معرّفات الوكلاء مُجزّأة بـ **SHA-256 وملح يومي متغير** قبل التخزين. لا بيانات شخصية مطلقاً.
+- **تحديد المعدل:** 200 طلب / 15 دقيقة على كل مسارات `/api/*`.
+- **التحقق:** Regex صارم للنطاقات، قوائم مسموحة للنوايا/الملاحظات/أنواع الحقائق، حدود حجم JSON من 4 إلى 64 KB.
+- **نطاق شامل:** تعمل لكل فئات النطاقات — وليس فقط الحجوزات. قوالب للمجالات الشائعة في `templates/`.
+
+### 📚 المرجع الكامل
+
+راجع إصدار GitHub للحصول على فهرس 25 endpoint كاملاً، خوارزميات التقييم، ومخطط قاعدة البيانات:
+👉 [**Release v3.6.0 — Advanced Features + Truth Layer**](https://github.com/abokenan444/web-agent-bridge/releases/tag/v3.6.0)
+
+---
+
+
+## ✨ المميزات
+
+- **اكتشاف تلقائي** — يكتشف الأزرار والنماذج وروابط التنقل تلقائياً
+- **نظام صلاحيات** — تحكم دقيق بما يمكن لوكلاء الذكاء الاصطناعي فعله
+- **واجهة موحدة** — كائن `window.AICommands` موحد يستخدمه أي وكيل
+- **تحديد معدل الاستخدام** — حماية مدمجة ضد الإساءة
+- **لوحة تحليلات** — تتبع تفاعل وكلاء الذكاء الاصطناعي مع موقعك
+- **إجراءات مخصصة** — سجّل إجراءاتك الخاصة مع معالجات مخصصة
+- **تحليلات فورية** — عبر WebSocket لمراقبة النشاط لحظياً
+- **توافق WebDriver BiDi** — دعم البروتوكولات المعيارية للمتصفحات
+- **مستويات اشتراك** — نواة مجانية + ميزات متقدمة مدفوعة
+- **نظام أحداث** — اشترك في أحداث الجسر للمراقبة
+- **صندوق حماية أمني** — عزل كامل مع توكنات جلسة، تحقق من الأصل، تأمين تلقائي
+- **محددات ذاتية الإصلاح** — مقاومة لتغييرات DOM في المواقع الديناميكية (SPA)
+- **وضع التخفي** — محاكاة سلوك بشري (حركة فأرة، كتابة طبيعية، تمرير تدريجي)
+- **قواعد بيانات متعددة** — SQLite + PostgreSQL + MySQL عبر محوّلات قابلة للتبديل
+- **SDK للوكلاء** — حزمة أدوات جاهزة لبناء وكلاء ذكاء اصطناعي
+- **بنية الإضافات** — نظام إضافات ديناميكي مع تنفيذ قائم على الخطافات، تثبيت لكل موقع، ترتيب أولويات، تقييمات، وتدقيق
+- **خدمة الرؤية** — تحليل لقطات شاشة متعدد الموفرين (Moondream محلي، OpenAI، Anthropic، Ollama) مع كشف العناصر التفاعلية وتشفير AES-256-GCM
+- **محرك العدالة** — طبقة حياد تضمن فرصة متساوية للمواقع الصغيرة والكبيرة مع بحث مرجح بالعدالة وتتبع شفافية العمولات
+- **ذاكرة الوكيل** — ذاكرة سلوكية دائمة مع ٤ أنواع ذاكرة، ٥ فئات، ارتباطات دلالية، تقييم الأهمية، وانتهاء صلاحية مؤقت
+- **تحليل حركة المرور المتقدم** — كشف أكثر من ٣٠ نوع بوت، تحليل سلوكي، كشف شذوذ، كشف استغلالات أمنية (SQL injection، XSS)
+- **خدمة البريد الإلكتروني** — بريد SMTP (ترحيب، تسجيل، إعادة تعيين كلمة المرور) مع قوالب HTML
+- **تتبع بدون JavaScript** — نقطة بكسل تتبع ١×١ لجمع التحليلات عند عدم توفر JavaScript
+- **محول WAB-MCP** — كشف قدرات مواقع WAB كأدوات MCP لـ Claude وGPT وGemini والوكلاء المتوافقة
+- **إضافة WordPress** — إضافة WordPress أصلية مع صفحة إعدادات، صناديق وصف لكل صفحة، توليد مستند اكتشاف، وعنصر لوحة تحكم
+- **متصفح WAB (سطح المكتب)** — متصفح Electron مستقل مع حاجب إعلانات مدمج (٨٠+ نطاق)، درع الاحتيال، تصنيف عدالة، دردشة وكيل، إشارات، سجل
+- **متصفح PWA (الهاتف)** — تطبيق ويب تقدمي لـ Android/iOS مع حجب إعلانات، بحث DuckDuckGo، كشف احتيال، تصفية شركات التقنية الكبرى
+- **SDK اكتشاف المخططات** — استخراج JSON-LD schema.org من جانب الخادم مع توليد تلميحات إجراءات WAB تلقائياً
+
+### الإصدار 2.0 — ميزات الحصن الرقمي
+
+- **محرك التفاوض اللحظي** — يتفاوض وكيل الذكاء الاصطناعي على الأسعار مباشرة مع المواقع عبر جلسات متعددة الجولات. ٨ أنواع شروط (كميات، ولاء، وقت، أول شراء، قيمة سلة، موسمية، عضوية، إحالة) و٤ أنواع خصومات (نسبة، مبلغ ثابت، شحن مجاني، هدية). يشمل حدود يومية وقيم حد أدنى وسجل كامل
+- **درع مقاومة التزييف** — محرك تحقق متقاطع يقارن DOM مع لقطات الشاشة، يتحقق من الأسعار مقابل المعايير السوقية، يفحص الاتساق الزمني، ويقيس تشابه النصوص. ٤ مستويات خطورة (بسيط ← احتيال) و٥ إجراءات استجابة (تحذير، إيقاف، تأكيد بشري، تصحيح تلقائي، حظر)
+- **نظام السمعة اللامركزي** — شهادات ثقة موقعة بـ HMAC من شبكة الوكلاء تغطي ٦ أنواع شهادات (شراء، حجز، استعلام، نموذج، تنقل، تحقق). ٧ مستويات ثقة (مجهول ← محظور)، اضمحلال زمني، مقاومة Sybil، لوحة متصدرين عالمية، ونظام طعن/نزاع
+- **لوحة السيادة** — مركز قيادة لحظي يعرض رادار العدالة، درع الخصوصية، سجل التفاوض، فحوصات التحقق، ومبدّل نماذج الذكاء الاصطناعي. يكشف نقطة `/api/sovereign/dashboard/sovereign` للبيانات المجمعة
+- **متجر قوالب الوكلاء** — ١١ قالب YAML جاهز (حجز فنادق، مقارنة بقالة، سوق حرفيين، صفقات طيران، إلخ) مع تشغيل من سطر الأوامر: `npx wab-agent run template.yaml`
+- **تبديل عقل الوكيل** — نظام تشغيل AI محلي يكتشف Ollama وllama.cpp تلقائياً مع دعم APIs متوافقة مع OpenAI. تتبع قدرات النماذج (نص/رؤية)، إدارة نوافذ السياق، توجيه حسب زمن الاستجابة، وتسجيل الاستدلال
+- **تنسيق الوكيل عبر المواقع** — وكيل واحد يدير عدة مواقع WAB في نفس الوقت عبر `WABMultiAgent`. قارن الأسعار بين المتاجر، اجمع البيانات، نفّذ إجراءات متوازية، واعثر على أفضل صفقة تلقائياً
+
+### الإصدار 2.3 — شبكة الوكلاء الخاصة (العقل الموزّع)
+
+- **بروتوكول التواصل بين الوكلاء** — الوكلاء يتواصلون عبر شبكة خاصة مع ٥ قنوات مدمجة (تنبيهات، اكتشافات، تكتيكات، مفاوضات، تصويت). ٦ أنواع رسائل مع تقييم الثقة، إزالة الوكلاء الخاملين تلقائياً عبر نبضات القلب، تحقق الأقران من المعرفة المشتركة. كل الاتصال يبقى محلياً
+- **التعلم المعزز المحلي** — الوكلاء يتعلمون من كل قرار للمستخدم باستخدام خوارزمية UCB1 متعددة الأذرع، تحديث السياسات بالنزول التدريجي مع تنشيط sigmoid، تخفيض زمني، واستخراج الأنماط المتسلسلة. بدون أي مكالمات API خارجية — التعلم بالكامل محلي
+- **منسق السيمفونية** — أربعة وكلاء متخصصين (باحث، محلل، مفاوض، حارس) يتعاونون ذاتياً عبر محركات قائمة على القواعد. ٥ قوالب، خط أنابيب من ٦ مراحل (تحليل ← بحث ← تفاوض ← حراسة ← تركيب ← قرار)، حق نقض الحارس للأمان، إجماع مرجح. تسجيل كامل للمراحل مع تتبع المدة. بدون أي اعتماد على LLM خارجية
+- **لوحة شبكة الوكلاء** — عرض مباشر لشبكة الوكلاء: الوكلاء النشطون، قنوات الاتصال، قاعدة المعرفة المشتركة، تركيبات السيمفونية، ومقاييس أداء التعلم
+
+### الإصدار 2.4 — القائد والذكاء على الحافة
+
+- **نظام القائد (Commander)** — محرك تنسيق مهام محلي يفكك الأهداف العليا إلى رسوم بيانية مهام (DAG). سجل وكلاء مع تتبع القدرات، محرك تنفيذ متوازٍ، تكامل تعلم لتغذية راجعة من النتائج، وتنسيق حوسبة طرفية
+- **نظام الحوسبة الطرفية (Edge Compute)** — يحول كل جهاز مستخدم إلى عقدة AI سيادية. تحليل المعدات (CPU, RAM, GPU)، تشفير AES-256-GCM بين العقد، موازنة حمل مرجحة، مراقبة صحة بنبضات القلب مع تجاوز فشل تلقائي، وتشكيل أسراب حسب القدرات
+- **محرك التنفيذ بالسرب** — إطلاق عدة وكلاء بالتوازي لحل مهمة واحدة. استراتيجيات قابلة للتكوين (متوازي، متسلسل، هجين)، دمج النتائج بأفضل درجة، تخصص بالأدوار، تجميع مرجح بالعدالة، وتقييم ثقة لكل وكيل
+
+### الإصدار 3.0 — نظام تشغيل الوكلاء (طبقة التنفيذ للويب)
+
+الإصدار 3.0 يحوّل WAB من أداة أتمتة متقدمة إلى **نظام تشغيل حقيقي للوكلاء** — طبقة تنفيذ كاملة لوكلاء الذكاء الاصطناعي على الويب، منافس لـ MCP لكنه مصمم خصيصاً للتفاعل مع المتصفح.
+
+- **بروتوكول WAB (WABP) v1.0.0** — بروتوكول رسمي مع سجل أوامر JSON Schema، رسائل مُنمطة، التحقق من المدخلات/المخرجات، وتعريفات أوامر مُنسّخة. ١٠ أوامر مدمجة (اكتشاف، تنفيذ، تنفيذ دلالي، تسجيل وكيل، إرسال مهمة، حالة مهمة، مقارنة تجارية، تفاوض تجاري، إرسال شبكة، استدلال AI). كل أمر يعلن عن القدرات المطلوبة ومستوى الخطر وصلاحيات الوصول
+- **تفاوض القدرات** — منح قدرات ديناميكي بين الوكلاء والمواقع. موافقة تلقائية حسب مستوى الخطر (منخفض = موافقة تلقائية، عالي = يتطلب سياسة)، تحديد معدل لكل قدرة، منح قابلة للانتهاء مع تتبع الاستخدام، ودعم إبطال كامل
+- **محرك تشغيل الوكلاء** — نظام تشغيل مهام بمستوى إنتاجي مع جدولة بقائمة أولويات، حل التبعيات، إعادة المحاولة بتراجع أسي، إيقاف/استئناف/إلغاء، حدود تزامن، وانتقالات حالة. ناقل أحداث غير متزامن مع وسيط، أحرف بدل مساحات الأسماء، ذاكرة إعادة (١٠ آلاف حدث)، وقائمة الرسائل الميتة
+- **صندوق حماية التنفيذ** — عزل لكل مهمة مع حدود موارد (مهلة، ذاكرة قصوى، حد استدعاءات الشبكة، حد عمليات DOM)، قوائم نطاقات مسموحة، حظر محددات CSS، فحوصات قدرات وقت التنفيذ، وسجل تدقيق كامل لكل عملية
+- **مدير الحالة** — حفظ حالة الوكيل بنقاط تفتيش مُسمّاة، تراجع لأي نقطة تفتيش، انتقالات حالة بالتحقق، عمليات دمج، وتنظيف بانتهاء الصلاحية
+- **حزمة المراقبة** — مسجل JSON هيكلي مع مسجلات فرعية ومخارج قابلة للتوصيل، متتبع موزع بفترات أب-ابن (متوافق مع OpenTelemetry)، ومجمع مقاييس بعدادات ومقاييس ورسوم بيانية (مئينات p50/p90/p95/p99) وسلاسل زمنية للوحات التحكم
+- **نموذج الأمان** — هوية الوكيل (تسجيل، مصادقة بمفتاح API مشفر، إدارة جلسات بمدة صلاحية، قوائم IP المسموحة، إبطال)، توقيع الأوامر (HMAC-SHA256 مع رمز فريد + طابع زمني، مقارنة آمنة زمنياً)، وعزل المواقع (تحكم وصول لكل موقع، وكلاء مسموحون/محظورون، حد تزامن أقصى، حظر محددات، تصنيف بيانات)
+- **مستوى التحكم** — مدير الوكلاء لدورة حياة النشر (نشر، تعيين لمواقع، فحوصات صحة، إلغاء نشر) ومحرك السياسات بقواعد مُنمّطة، تقييم شروط (يساوي، يحتوي، نمط، حد أدنى، حد أقصى، ضمن)، ربط سياسات بأولوية، وتطبيق على مستوى الكيان
+- **مستوى البيانات** — محلل الإجراءات الدلالية يربط صيغة `domain.action` (مثل `checkout.addItem`) بالتنفيذ الفعلي لكل موقع. المنفّذ يوجّه المهام عبر التتبع + المقاييس، يدعم أوضاع التنفيذ الدلالي/الخط الأنبوبي/المتوازي، مع ٨ إجراءات دلالية مدمجة للسلة والبحث والمصادقة والتنقل والمحتوى
+- **تجريد LLM متعدد النماذج** — واجهة موحدة لـ OpenAI (محادثة + تضمينات)، Anthropic (API الرسائل)، وOllama (نماذج محلية مع اكتشاف تلقائي). مدير LLM يوفر سلسلة احتياطية تلقائية عبر جميع الموفرين، تخزين مؤقت للاستجابات (٥ دقائق)، تتبع التكاليف عبر عدد الرموز، وقائمة نماذج
+- **السجل والنظام البيئي** — سجل الأوامر (كـ npm لأوامر WAB — تسجيل، اكتشاف، بحث حسب الفئة/الوسم/القدرة، تتبع الاستخدام)، سجل المواقع (دليل مواقع WAB مع التحقق، قائمة القدرات، تتبع الزيارات)، وسجل القوالب (قوالب سير عمل قابلة لإعادة الاستخدام مع عدد التنزيلات والتقييمات)
+- **واجهة API الموحدة لنظام التشغيل** — جميع طبقات نظام التشغيل مكشوفة عبر نقاط REST على `/api/os/*`: اكتشاف البروتوكول، هوية/مصادقة الوكيل، CRUD المهام، التنفيذ الدلالي، النشر، السياسات، العزل، المراقبة (مقاييس/آثار/سجلات)، السجل (أوامر/مواقع/قوالب)، عمليات LLM، توقيع الأوامر، وأحداث Server-Sent Events للبث المباشر
+- **عميل WABAgentOS في SDK** — فئة `WABAgentOS` جديدة في SDK مع كتابة TypeScript كاملة لجميع عمليات نظام التشغيل: تسجيل ← مصادقة ← تفاوض قدرات ← إرسال مهام ← تنفيذ دلالي ← استعلام المراقبة ← الاشتراك في الأحداث
+
+### الإصدار 3.2 — بوابة API والوحدات المتقدمة
+
+يقدم الإصدار 3.2 **بوابة API موحدة** على `/api/v1` مع 10 وحدات متقدمة لحماية وكلاء الذكاء الاصطناعي وحقوق المستهلك وتتبع الأسعار والامتثال التنظيمي. جميع الوحدات تستخدم مصادقة مركزية بمفتاح API مع تحكم وصول حسب الخطة.
+
+🌐 **توثيق API المباشر:** [webagentbridge.com/api](https://webagentbridge.com/api) (English / العربية)
+
+#### خطط API والأسعار
+
+| الخطة | السعر | الطلبات/يوم | الطلبات/دقيقة | الوحدات |
+|-------|-------|-------------|---------------|---------|
+| **مجانية** | $0/شهر | 100 | 10 | البروتوكول، آلة الزمن السعرية، الأنماط المظلمة، المكافآت |
+| **احترافية** | $29/شهر | 10,000 | 100 | كل المجاني + الجدار الناري، العصبي، التفاوض، التسويق |
+| **أعمال** | $149/شهر | 100,000 | 500 | جميع الوحدات العشر (شاملة كاتب العدل والاستخبارات الحكومية) |
+| **مؤسسات** | مخصص | غير محدود | مخصص | جميع الوحدات + SLA + خيار التشغيل المحلي |
+
+**احصل على مفتاح API:** `POST /api/v1/keys/generate` مع `{"plan": "FREE", "owner": "اسمك", "email": "you@example.com"}`
+
+#### الوحدات العشر
+
+| # | الوحدة | المسار | النوع | الخطة الأدنى | الوصف |
+|---|--------|--------|-------|-------------|-------|
+| 01 | **جدار حماية الوكلاء** | `/api/v1/firewall` | 🟡 API مفتوح · المحرك مغلق | احترافية | يفحص الروابط والمحتوى للكشف عن حقن الأوامر والتصيد والنطاقات الخبيثة |
+| 02 | **كاتب العدل التشفيري** | `/api/v1/notary` | 🔴 مغلق بالكامل | أعمال | يصدر شهادات تشفيرية مقبولة قانونياً لإثبات التمييز السعري |
+| 03 | **كاشف الأنماط المظلمة** | `/api/v1/dark-pattern` | 🔴 مغلق بالكامل | مجانية | يكشف جميع الأنماط المظلمة الـ 17 المصنفة من OECD مع تقارير EU DSA/DMA |
+| 04 | **التفاوض الجماعي** | `/api/v1/bargaining` | 🟡 الانضمام مفتوح · المحرك مغلق | احترافية | تجميع مشترين مجهولين للتفاوض على خصومات جماعية |
+| 05 | **الاستخبارات الحكومية** | `/api/v1/gov` | 🔴 مغلق بالكامل | أعمال | قاعدة بيانات الامتثال التنظيمي وفحص امتثال النطاقات |
+| 06 | **آلة الزمن السعرية** | `/api/v1/price` | 🟡 API مفتوح · قاعدة البيانات مغلقة | مجانية | تتبع الأسعار التاريخية وكشف التخفيضات الوهمية |
+| 07 | **المحرك العصبي** | `/api/v1/neural` | 🔴 مغلق بالكامل | احترافية | محرك AI محلي لتحليل الروابط وتصنيف المحتوى والتضمينات |
+| 08 | **بروتوكول WAB** | `/api/v1/protocol` | 🟢 مفتوح المصدر بالكامل | مجانية | مدقق بروتوكول الثقة wab.json المفتوح ونقطة المخطط |
+| 09 | **شبكة المكافآت** | `/api/v1/bounty` | 🟡 الإبلاغ مفتوح · القواعد مغلقة | مجانية | شبكة بلاغات وتهديدات مدعومة من المجتمع مع لوحة متصدرين |
+| 10 | **استخبارات التسويق بالعمولة** | `/api/v1/affiliate` | 🟡 API مفتوح · قاعدة البيانات مغلقة | احترافية | يكشف التلاعب بروابط التسويق وحشو ملفات تعريف الارتباط |
+
+**مفتاح الأنواع:** 🟢 مفتوح المصدر بالكامل · 🟡 واجهة API عامة مع محرك خاص · 🔴 مغلق بالكامل (يعيد 503 بدون المحرك)
+
+#### المصادقة
+
+جميع نقاط النهاية تتطلب مفتاح API عبر إحدى ثلاث طرق:
+
+```bash
+# الخيار 1: ترويسة التفويض (موصى بها)
+curl -X POST https://www.webagentbridge.com/api/v1/firewall/scan \
+  -H "Authorization: Bearer wab_live_pro_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com", "content": "محتوى الصفحة..."}'
+
+# الخيار 2: ترويسة X-WAB-Key
+curl -H "X-WAB-Key: wab_live_pro_YOUR_KEY" \
+  https://www.webagentbridge.com/api/v1/protocol/check/example.com
+
+# الخيار 3: معامل الاستعلام
+curl https://www.webagentbridge.com/api/v1/bounty/stats?api_key=wab_live_fre_YOUR_KEY
+```
+
+#### إدارة المفاتيح
+
+| نقطة النهاية | الطريقة | الوصف |
+|-------------|---------|-------|
+| `/api/v1/keys/generate` | POST | إنشاء مفتاح API جديد |
+| `/api/v1/keys/validate` | POST | التحقق من صلاحية مفتاح |
+| `/api/v1/keys/usage` | GET | التحقق من الاستخدام والحصص |
+| `/api/v1/keys/revoke` | POST | إلغاء مفتاح |
+| `/api/v1/keys/rotate` | POST | تدوير مفتاح (إلغاء القديم وإصدار جديد) |
+
+#### نقاط البوابة العامة
+
+| نقطة النهاية | الطريقة | الوصف |
+|-------------|---------|-------|
+| `/api/v1/health` | GET | فحص صحة البوابة (عام) |
+| `/api/v1/plans` | GET | قائمة الخطط والأسعار (عام) |
+| `/api/v1/modules` | GET | قائمة الوحدات المتاحة (عام) |
+
+#### كيفية الاشتراك
+
+1. زُر [webagentbridge.com/api](https://webagentbridge.com/api) لاستكشاف الوحدات المتاحة
+2. أنشئ مفتاح API **مجاني**: `POST /api/v1/keys/generate` مع اسمك وبريدك
+3. ابدأ الطلبات فوراً لأي وحدة مجانية
+4. ارتقِ إلى **احترافية** ($29/شهر) أو **أعمال** ($149/شهر) للوصول للوحدات المتقدمة
+5. أدِر مفاتيحك عبر نقاط `/api/v1/keys/*`
+
+---
+
+## 🚀 البدء السريع
+
+### ١. التثبيت والتشغيل
+
+```bash
+# الطريقة أ: استنساخ وتشغيل
+git clone https://github.com/abokenan444/web-agent-bridge.git
+cd web-agent-bridge
+npm install
+cp .env.example .env
+npm start
+
+# الطريقة ب: npx (أمر واحد)
+npx web-agent-bridge start
+
+# الطريقة ج: Docker
+docker compose up -d
+```
+
+### ٢. إنشاء حساب
+
+زُر `http://localhost:3000/register` وأنشئ حساباً، ثم أضف موقعك من لوحة التحكم.
+
+### ٣. إضافة السكريبت لموقعك
+
+```html
+<script>
+window.AIBridgeConfig = {
+  licenseKey: "WAB-XXXXX-XXXXX-XXXXX-XXXXX",
+  agentPermissions: {
+    readContent: true,
+    click: true,
+    fillForms: true,
+    scroll: true
+  }
+};
+</script>
+<script src="http://localhost:3000/script/ai-agent-bridge.js"></script>
+```
+
+### ٤. الآن يمكن لوكلاء الذكاء الاصطناعي التفاعل
+
+```javascript
+// من جانب وكيل الذكاء الاصطناعي
+const bridge = window.AICommands;
+const actions = bridge.getActions();           // اكتشاف الإجراءات
+await bridge.execute("signup");                // تنفيذ إجراء
+const info = bridge.getPageInfo();             // معلومات الصفحة
+```
+
+---
+
+## 📁 هيكل المشروع
+
+```
+web-agent-bridge/
+├── server/                         # خادم Express.js
+│   ├── index.js                    # نقطة البداية
+│   ├── ws.js                       # WebSocket للتحليلات الفورية
+│   ├── routes/
+│   │   ├── auth.js                 # المصادقة (تسجيل/دخول)
+│   │   ├── api.js                  # واجهة المواقع والتحليلات
+│   │   ├── license.js              # التحقق من التراخيص والتتبع
+│   │   ├── admin.js                # واجهة الإدارة
+│   │   ├── admin-premium.js        # تحليلات الإدارة المتقدمة
+│   │   ├── billing.js              # تكامل Stripe للمدفوعات
+│   │   ├── sovereign.js            # الإصدار 2.0: تفاوض، سمعة، تحقق، لوحة سيادة
+│   │   ├── mesh.js                 # الإصدار 2.3: مسارات شبكة الوكلاء
+│   │   ├── commander.js            # الإصدار 2.4: مسارات تنسيق المهام
+│   │   ├── premium.js              # الميزات المتقدمة
+│   │   ├── premium-v2.js           # ذاكرة، رؤية، إصلاح، سرب، إضافات
+│   │   ├── discovery.js            # اكتشاف WAB + بحث مرجح بالعدالة
+│   │   ├── wab-api.js              # نقل WAB عبر HTTP
+│   │   └── noscript.js             # بكسل تتبع بدون JavaScript
+│   ├── services/
+│   │   ├── negotiation.js          # محرك التفاوض اللحظي
+│   │   ├── verification.js         # درع مقاومة التزييف
+│   │   ├── reputation.js           # نظام السمعة اللامركزي
+│   │   ├── agent-mesh.js           # بروتوكول التواصل بين الوكلاء
+│   │   ├── agent-learning.js       # التعلم المعزز المحلي (UCB1)
+│   │   ├── agent-symphony.js       # منسق السيمفونية (٤ أدوار، ٦ مراحل)
+│   │   ├── agent-memory.js         # ذاكرة الوكيل مع ارتباطات
+│   │   ├── commander.js            # تنسيق المهام ورسوم المهام (DAG)
+│   │   ├── edge-compute.js         # حوسبة طرفية / عقد AI سيادية
+│   │   ├── swarm.js                # محرك التنفيذ بالسرب
+│   │   ├── fairness.js             # محرك العدالة والحياد
+│   │   ├── vision.js               # تحليل الرؤية (متعدد الموفرين)
+│   │   ├── self-healing.js         # تصحيحات المحددات ذاتية الإصلاح
+│   │   ├── local-ai.js             # نظام تشغيل AI المحلي
+│   │   ├── plugins.js              # بنية الإضافات (خطافات، سجل)
+│   │   ├── premium.js              # تحليل حركة المرور وكشف البوتات
+│   │   ├── email.js                # خدمة البريد SMTP
+│   │   └── stripe.js               # تكامل مدفوعات Stripe
+│   ├── middleware/
+│   │   ├── auth.js                 # وسيط JWT
+│   │   ├── adminAuth.js            # مصادقة الإدارة
+│   │   └── rateLimits.js           # تحديد معدل الطلبات متعدد الطبقات
+│   ├── models/
+│   │   ├── db.js                   # عمليات قاعدة البيانات
+│   │   └── adapters/              # محولات SQLite, PostgreSQL, MySQL
+│   ├── migrations/                 # ترحيلات SQL مرقمة
+│   └── utils/
+│       ├── cache.js                # ذاكرة مؤقتة TTL + طابور تحليلات
+│       ├── migrate.js              # مشغل الترحيلات
+│       └── secureFields.js         # أدوات تشفير الحقول
+├── public/                         # الواجهة الأمامية
+│   ├── index.html                  # الصفحة الرئيسية
+│   ├── dashboard.html              # لوحة التحكم
+│   ├── premium-dashboard.html      # لوحة التحليلات المتقدمة
+│   ├── docs.html                   # التوثيق
+│   ├── login.html / register.html  # صفحات المصادقة
+│   ├── admin/                      # لوحة الإدارة
+│   ├── pwa/                        # تطبيق الويب التقدمي (متصفح الهاتف)
+│   │   ├── manifest.json           # بيان PWA
+│   │   ├── sw.js                   # عامل الخدمة (أولوية غير متصل)
+│   │   ├── index.html              # واجهة المتصفح للهاتف
+│   │   ├── app.js                  # حاجب إعلانات، درع احتيال، عدالة
+│   │   ├── app.css                 # سمة داكنة محسنة للهاتف
+│   │   └── icons/                  # أيقونات PWA
+│   ├── script/
+│   │   ├── wab.min.js              # مكتبة WAB المصغرة
+│   │   ├── wab-consent.js          # لافتة موافقة GDPR/CCPA
+│   │   ├── wab-schema.js           # اكتشاف schema.org
+│   │   ├── wab.d.ts                # تعريفات TypeScript
+│   │   └── wab-consent.d.ts        # تعريفات TypeScript للموافقة
+│   ├── js/                         # JavaScript الواجهة
+│   └── css/                        # أوراق الأنماط
+├── script/
+│   └── ai-agent-bridge.js          # سكريبت الجسر (ضعه في موقعك)
+├── examples/                       # أمثلة الوكلاء
+│   ├── puppeteer-agent.js          # Puppeteer + window.AICommands
+│   ├── bidi-agent.js               # بروتوكول WebDriver BiDi
+│   ├── vision-agent.js             # تحليل رؤية/لغة طبيعية
+│   ├── mcp-agent.js                # محول MCP لـ Claude/GPT
+│   ├── cross-site-agent.js         # تنسيق متعدد النطاقات
+│   ├── next-app-router/            # تكامل Next.js App Router
+│   ├── shopify-hydrogen/           # واجهة Shopify Hydrogen
+│   ├── wordpress-elementor/        # WordPress + Elementor
+│   └── saas-dashboard/             # إجراءات لوحة SaaS
+├── packages/                       # أغلفة أطر العمل
+│   ├── react/                      # @web-agent-bridge/react
+│   ├── vue/                        # @web-agent-bridge/vue
+│   ├── svelte/                     # @web-agent-bridge/svelte
+│   └── langchain/                  # @web-agent-bridge/langchain
+├── sdk/                            # SDK الوكيل
+│   ├── index.js                    # WABAgent لـ Puppeteer/Playwright
+│   └── schema-discovery.js         # استخراج schema.org من الخادم
+├── wab-mcp-adapter/                # محول MCP لـ Claude/GPT/Gemini
+│   ├── index.js                    # تعريفات أدوات MCP
+│   └── package.json
+├── wab-browser/                    # متصفح Electron لسطح المكتب
+│   ├── main.js                     # العملية الرئيسية لـ Electron
+│   ├── preload.js                  # التحميل المسبق
+│   └── package.json
+├── web-agent-bridge-wordpress/     # إضافة WordPress
+│   ├── web-agent-bridge.php        # نقطة دخول الإضافة
+│   ├── includes/                   # فئات PHP (API, Actions, Dashboard)
+│   └── assets/                     # CSS/JS الإضافة
+├── bin/
+│   ├── cli.js                      # نقطة دخول CLI (wab-agent)
+│   └── wab.js                      # مشغل الوكلاء
+├── templates/                      # ١١ قالب YAML لمتجر الوكلاء
+├── docs/
+│   ├── SPEC.md                     # مواصفة بروتوكول WAB
+│   └── DEPLOY.md                   # دليل النشر
+├── demo-store/                     # متجر تجريبي للاختبار
+├── deploy/                         # إعدادات Nginx
+├── tests/                          # اختبارات Jest + Supertest
+├── .env                            # متغيرات البيئة
+└── package.json
+```
+
+---
+
+## 🔌 واجهات API
+
+### المصادقة
+| النقطة | الطريقة | الوصف |
+|---|---|---|
+| `/api/auth/register` | POST | إنشاء حساب |
+| `/api/auth/login` | POST | تسجيل الدخول |
+| `/api/auth/me` | GET | بيانات المستخدم الحالي |
+
+### المواقع
+| النقطة | الطريقة | الوصف |
+|---|---|---|
+| `/api/sites` | GET | قائمة مواقعك |
+| `/api/sites` | POST | إضافة موقع جديد |
+| `/api/sites/:id` | GET | تفاصيل الموقع |
+| `/api/sites/:id/config` | PUT | تحديث الإعدادات |
+| `/api/sites/:id/tier` | PUT | تغيير مستوى الاشتراك |
+| `/api/sites/:id` | DELETE | حذف الموقع |
+| `/api/sites/:id/snippet` | GET | كود التضمين |
+| `/api/sites/:id/analytics` | GET | بيانات التحليلات |
+
+### التراخيص (عامة)
+| النقطة | الطريقة | الوصف |
+|---|---|---|
+| `/api/license/verify` | POST | التحقق من مفتاح الترخيص |
+| `/api/license/token` | POST | تبادل `siteId` مقابل توكن جلسة |
+| `/api/license/session` | POST | التحقق من توكن الجلسة |
+| `/api/license/track` | POST | تسجيل حدث تحليلي |
+
+### واجهات السيادة (الإصدار 2.0)
+| النقطة | الطريقة | الوصف |
+|---|---|---|
+| `/api/sovereign/reputation/agents` | POST | تسجيل وكيل جديد |
+| `/api/sovereign/reputation/attestations` | POST | إرسال شهادة ثقة |
+| `/api/sovereign/reputation/sites/:siteId` | GET | سمعة الموقع |
+| `/api/sovereign/reputation/leaderboard` | GET | لوحة المتصدرين |
+| `/api/sovereign/negotiation/rules` | POST | إنشاء قاعدة تفاوض |
+| `/api/sovereign/negotiation/sessions` | POST | فتح جلسة تفاوض |
+| `/api/sovereign/negotiation/sessions/:id/propose` | POST | تقديم عرض مضاد |
+| `/api/sovereign/negotiation/sessions/:id/confirm` | POST | تأكيد الصفقة |
+| `/api/sovereign/verify/price` | POST | التحقق من السعر |
+| `/api/sovereign/verify/text` | POST | التحقق من النص |
+| `/api/sovereign/verify/page` | POST | التحقق الشامل للصفحة |
+| `/api/sovereign/dashboard/sovereign` | GET | بيانات لوحة السيادة |
+
+### شبكة الوكلاء (الإصدار 2.3)
+| النقطة | الطريقة | الوصف |
+|---|---|---|
+| `/api/mesh/agents` | POST | تسجيل وكيل في الشبكة |
+| `/api/mesh/agents` | GET | عرض وكلاء الشبكة |
+| `/api/mesh/channels` | GET | عرض قنوات الاتصال |
+| `/api/mesh/messages` | POST | نشر رسالة في قناة |
+| `/api/mesh/messages/:channel` | GET | قراءة رسائل القناة |
+| `/api/mesh/knowledge` | POST | مشاركة معرفة |
+| `/api/mesh/knowledge` | GET | استعلام قاعدة المعرفة |
+| `/api/mesh/votes` | POST | بدء تصويت |
+| `/api/mesh/votes/:id/cast` | POST | الإدلاء بصوت |
+| `/api/mesh/votes/:id/tally` | GET | نتائج التصويت |
+
+### القائد (الإصدار 2.4)
+| النقطة | الطريقة | الوصف |
+|---|---|---|
+| `/api/commander/missions` | POST | إنشاء مهمة جديدة |
+| `/api/commander/missions/:id/launch` | POST | إطلاق المهمة |
+| `/api/commander/missions/:id` | GET | حالة المهمة |
+| `/api/commander/missions` | GET | عرض جميع المهام |
+| `/api/commander/agents` | POST | تسجيل وكيل |
+| `/api/commander/agents` | GET | عرض الوكلاء |
+| `/api/commander/edge/nodes` | POST | تسجيل عقدة حوسبة طرفية |
+| `/api/commander/edge/nodes` | GET | عرض العقد |
+| `/api/commander/ai/models` | GET | اكتشاف نماذج AI المحلية |
+| `/api/commander/ai/infer` | POST | تشغيل استدلال AI محلي |
+| `/api/commander/stats` | GET | إحصائيات المنصة الموحدة |
+
+### الميزات المتقدمة (الإصدار 2)
+| النقطة | الطريقة | الوصف |
+|---|---|---|
+| `/api/premium/v2/memory` | POST | تخزين ذاكرة الوكيل |
+| `/api/premium/v2/memory/:agentId` | GET | استرجاع ذكريات الوكيل |
+| `/api/premium/v2/memory/associate` | POST | إنشاء ارتباط بين ذكريات |
+| `/api/premium/v2/vision/analyze` | POST | تحليل لقطة شاشة |
+| `/api/premium/v2/vision/elements` | POST | استخراج عناصر تفاعلية |
+| `/api/premium/v2/healing/corrections` | POST | تسجيل تصحيح محدد |
+| `/api/premium/v2/healing/resolve` | POST | حل محدد معطل |
+| `/api/premium/v2/swarm/execute` | POST | إطلاق مهمة سرب |
+| `/api/premium/v2/swarm/:id` | GET | نتائج السرب |
+| `/api/premium/v2/plugins` | GET | عرض الإضافات المتاحة |
+| `/api/premium/v2/plugins/:id/install` | POST | تثبيت إضافة |
+| `/api/premium/v2/plugins/:id/hooks` | POST | تنفيذ خطاف إضافة |
+
+### الاكتشاف والعدالة
+| النقطة | الطريقة | الوصف |
+|---|---|---|
+| `/api/discovery` | GET | مستند اكتشاف WAB |
+| `/api/discovery/search` | GET | بحث مرجح بالعدالة |
+| `/api/discovery/register` | POST | تسجيل موقع في دليل WAB |
+
+### بروتوكول WAB (نقل HTTP)
+| النقطة | الطريقة | الوصف |
+|---|---|---|
+| `/api/wab/session` | POST | تبادل توكن جلسة |
+| `/api/wab/actions` | GET | الإجراءات المتاحة |
+| `/api/wab/execute` | POST | تنفيذ إجراء عبر HTTP |
+
+### WebSocket
+| النقطة | الوصف |
+|---|---|
+| `ws://localhost:3000/ws/analytics` | تحليلات فورية لحظية |
+
+---
+
+## ⚙️ واجهة سكريبت الجسر
+
+عند التحميل، يكشف `window.AICommands` الطرق التالية:
+
+| الطريقة | الوصف |
+|---|---|
+| `getActions(category?)` | قائمة الإجراءات المتاحة |
+| `getAction(name)` | الحصول على إجراء محدد |
+| `execute(name, params?)` | تنفيذ إجراء |
+| `readContent(selector)` | قراءة محتوى عنصر |
+| `getPageInfo()` | معلومات الصفحة والجسر |
+| `waitForElement(selector, timeout?)` | انتظار ظهور عنصر DOM |
+| `waitForNavigation(timeout?)` | انتظار تغيير العنوان |
+| `registerAction(def)` | تسجيل إجراء مخصص |
+| `authenticate(key, meta?)` | مصادقة الوكيل |
+| `refresh()` | إعادة مسح الصفحة |
+| `toBiDi()` | الحصول على سياق WebDriver BiDi |
+| `executeBiDi(command)` | تنفيذ أمر بصيغة BiDi |
+
+---
+
+## 🔧 الإعدادات
+
+```javascript
+window.AIBridgeConfig = {
+  licenseKey: "WAB-XXXXX-XXXXX-XXXXX-XXXXX",
+  agentPermissions: {
+    readContent: true,      // قراءة النص
+    click: true,            // النقر على العناصر
+    fillForms: false,       // ملء/إرسال النماذج
+    scroll: true,           // تمرير الصفحة
+    navigate: false,        // التنقل بين الصفحات
+    apiAccess: false,       // استدعاء API داخلي (Pro+)
+    automatedLogin: false,  // تسجيل دخول تلقائي (Starter+)
+    extractData: false      // استخراج البيانات (Pro+)
+  },
+  restrictions: {
+    allowedSelectors: [],
+    blockedSelectors: [".private", "[data-private]"],
+    requireLoginForActions: ["apiAccess"],
+    rateLimit: { maxCallsPerMinute: 60 }
+  },
+  logging: { enabled: false, level: "basic" }
+};
+```
+
+---
+
+## 🔄 توافق WebDriver BiDi
+
+يدعم السكريبت بروتوكول WebDriver BiDi للتواصل مع الوكلاء عبر معايير موحدة:
+
+```javascript
+// الحصول على سياق BiDi
+const context = window.__wab_bidi.getContext();
+
+// إرسال أمر BiDi
+const result = await window.__wab_bidi.send({
+  id: 1,
+  method: 'wab.executeAction',
+  params: { name: 'signup', data: {} }
+});
+
+// الأوامر المدعومة:
+// wab.getContext    — سياق الصفحة والقدرات
+// wab.getActions    — قائمة الإجراءات
+// wab.executeAction — تنفيذ إجراء
+// wab.readContent   — قراءة محتوى
+// wab.getPageInfo   — معلومات الصفحة
+```
+
+---
+
+## 📊 التحليلات الفورية (WebSocket)
+
+اتصل بنقطة WebSocket لتلقي إشعارات فورية:
+
+```javascript
+const ws = new WebSocket('ws://localhost:3000/ws/analytics');
+
+// المصادقة
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    type: 'auth',
+    token: 'your-jwt-token',
+    siteId: 'your-site-id'
+  }));
+};
+
+// تلقي الأحداث
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('حدث جديد:', data);
+  // { type: 'analytic', actionName: '...', agentId: '...', success: true }
+};
+```
+
+---
+
+## 💰 مستويات الاشتراك
+
+| الميزة | مجاني | Starter | Pro | Enterprise |
+|---|:---:|:---:|:---:|:---:|
+| اكتشاف تلقائي | ✓ | ✓ | ✓ | ✓ |
+| نقر/تمرير | ✓ | ✓ | ✓ | ✓ |
+| ملء النماذج | ✓ | ✓ | ✓ | ✓ |
+| تسجيل أساسي | ✓ | ✓ | ✓ | ✓ |
+| تسجيل دخول تلقائي | ✗ | ✓ | ✓ | ✓ |
+| لوحة تحليلات | ✗ | ✓ | ✓ | ✓ |
+| وصول API | ✗ | ✗ | ✓ | ✓ |
+| استخراج البيانات | ✗ | ✗ | ✓ | ✓ |
+| تحديد معدل مخصص | ✗ | ✗ | ✗ | ✓ |
+| Webhooks | ✗ | ✗ | ✗ | ✓ |
+
+---
+
+## 🐳 تشغيل باستخدام Docker
+
+```bash
+# بناء وتشغيل
+docker compose up -d
+
+# أو البناء يدوياً
+docker build -t web-agent-bridge .
+docker run -p 3000:3000 -e JWT_SECRET=your-secret -e JWT_SECRET_ADMIN=your-admin-secret web-agent-bridge
+```
+
+---
+
+## 🧪 الاختبارات
+
+```bash
+npm test
+```
+
+تشمل الاختبارات:
+- واجهات المصادقة (تسجيل، دخول، التحقق من التوكن)
+- واجهات إدارة المواقع (CRUD، الإعدادات، المستويات)
+- واجهات التراخيص (التحقق، التتبع)
+- خدمة الصفحات الثابتة
+
+---
+
+## 🤖 Agent SDK — حزمة أدوات الوكيل
+
+يضم WAB حزمة SDK جاهزة لبناء وكلاء ذكاء اصطناعي. راجع [`sdk/README.md`](sdk/README.md) للتوثيق الكامل.
+
+```javascript
+const puppeteer = require('puppeteer');
+const { WABAgent } = require('web-agent-bridge/sdk');
+
+const browser = await puppeteer.launch();
+const page = await browser.newPage();
+const agent = new WABAgent(page);
+
+await agent.navigateAndWait('https://example.com');
+const actions = await agent.getActions();
+await agent.execute('signup', { email: 'user@test.com' });
+await browser.close();
+```
+
+---
+
+## 📚 أمثلة الوكلاء
+
+أمثلة جاهزة للتشغيل في مجلد [`examples/`](examples/):
+
+| الملف | الوصف |
+|---|---|
+| `puppeteer-agent.js` | وكيل أساسي باستخدام Puppeteer و `window.AICommands` |
+| `bidi-agent.js` | وكيل يستخدم بروتوكول WebDriver BiDi عبر `window.__wab_bidi` |
+| `vision-agent.js` | وكيل رؤية — يحل أوصاف اللغة الطبيعية إلى إجراءات WAB |
+| `mcp-agent.js` | استخدام محول MCP لـ Claude وGPT مع اكتشاف الأدوات |
+| `cross-site-agent.js` | تنسيق متعدد النطاقات — مقارنة أسعار، تجميع بيانات، أفضل الصفقات |
+
+### أمثلة التكامل مع أطر العمل
+
+| المسار | الوصف |
+|---|---|
+| `examples/next-app-router/` | تكامل Next.js App Router مع `@web-agent-bridge/react` |
+| `examples/shopify-hydrogen/` | واجهة Shopify Hydrogen مع إجراءات سلة عملية |
+| `examples/wordpress-elementor/` | إعداد WordPress + Elementor مع إجراءات مدعومة بالمخطط |
+| `examples/saas-dashboard/` | لوحة SaaS بنمط Notion مع مؤشرات أداء وتشغيل سير عمل |
+
+```bash
+node examples/puppeteer-agent.js http://localhost:3000
+node examples/bidi-agent.js http://localhost:3000
+node examples/vision-agent.js http://localhost:3000
+```
+
+---
+
+## 🗄️ دعم قواعد بيانات متعددة
+
+يستخدم WAB قاعدة SQLite افتراضياً ويدعم PostgreSQL و MySQL عبر محوّلات قاعدة البيانات.
+
+```bash
+# SQLite (افتراضي — لا حاجة لإعداد)
+npm start
+
+# PostgreSQL
+npm install pg
+DB_ADAPTER=postgresql DATABASE_URL=postgres://user:pass@localhost:5432/wab npm start
+
+# MySQL
+npm install mysql2
+DB_ADAPTER=mysql DATABASE_URL=mysql://user:pass@localhost:3306/wab npm start
+```
+
+---
+
+## 💻 واجهة سطر الأوامر (CLI)
+
+```bash
+# تشغيل الخادم
+npx web-agent-bridge start
+npx web-agent-bridge start --port 8080
+
+# تهيئة مشروع جديد
+npx web-agent-bridge init
+```
+
+---
+
+## 🔒 الأمان
+
+### صندوق الحماية الأمني (Security Sandbox)
+
+كل نسخة من الجسر تعمل داخل صندوق حماية يوفر:
+
+- **توكنات جلسة** — توكن تشفيري فريد لكل جلسة يمنع هجمات الإعادة (Replay Attacks)
+- **التحقق من الأصل** — فقط الأصول المصرح بها يمكنها التفاعل مع الجسر
+- **تحقق من الأوامر** — كل أمر يُفحص من حيث الصيغة والطول وقائمة الحظر
+- **سجل تدقيق** — كل إجراء يُسجّل بالتوقيت وبصمة الوكيل والحالة
+- **حماية التصعيد** — محاولات الوصول لميزات أعلى تؤدي لتأمين تلقائي بعد 5 مخالفات
+- **القفل التلقائي** — الجسر يصبح للقراءة فقط عند اكتشاف انتهاكات أمنية
+
+### حماية الخادم
+
+- **CSP (سياسة أمان المحتوى)** — حماية ضد XSS وحقن السكريبت
+- **حماية iframe** — `frame-ancestors: 'none'` يمنع تحميل الموقع في إطارات غير موثوقة
+- **تشفير كلمات المرور** — bcrypt بتكلفة 12
+- **JWT** — توكن مؤقت ينتهي بعد 7 أيام
+- **Rate Limiting** — تحديد معدل الطلبات
+- **Helmet** — حماية رؤوس HTTP
+- **حظر المحددات** — تقييد وصول الوكيل لعناصر محددة
+
+---
+
+## 🔄 المحددات ذاتية الإصلاح (Self-Healing Selectors)
+
+المواقع الحديثة (SPAs) تتغير باستمرار. نظام الإصلاح الذاتي يضمن استمرار عمل المحددات:
+
+1. **البصمات** — عند اكتشاف الإجراءات، يُخزن WAB بصمة غنية لكل عنصر
+2. **7 استراتيجيات** — عند تعطل محدد، يجرب WAB: `data-wab-id`، `data-testid`، ID، `aria-label`، `name`، مطابقة نصية ضبابية، موضع + دور
+3. **مراقب SPA** — `MutationObserver` يرصد تغييرات DOM ويعيد اكتشاف الإجراءات تلقائياً
+
+```javascript
+// أضف هذا للاستقرار الأقصى
+<button data-wab-id="signup-btn">إنشاء حساب</button>
+```
+
+---
+
+## 🥷 وضع التخفي (Stealth Mode)
+
+لمواجهة أنظمة الحماية من البوتات:
+
+```javascript
+window.AIBridgeConfig = { stealth: { enabled: true } };
+```
+
+| الميزة | الوصف |
+|---|---|
+| سلسلة أحداث الفأرة | `mouseover → mouseenter → mousemove → mousedown → mouseup → click` |
+| محاكاة الكتابة | حرف بحرف مع تأخير 30-120 مللي ثانية |
+| تمرير تدريجي | خطوات متعددة بسرعة متغيرة |
+| تأخيرات عشوائية | 50-400 مللي ثانية بين الإجراءات |
+
+---
+
+## 🛠️ التقنيات
+
+- **الخلفية**: Node.js + Express + WebSocket (ws)
+- **قاعدة البيانات**: SQLite (عبر better-sqlite3) مع مشغل ترحيلات
+- **المصادقة**: JWT + bcrypt + توكنات جلسة (مقفلة بالنطاق)
+- **التخزين المؤقت**: ذاكرة مؤقتة TTL + طابور تحليلات مجمع
+- **المدفوعات**: تكامل Stripe مع بوابة الفوترة
+- **الواجهة**: HTML/CSS/JS بدون أطر عمل
+- **أغلفة أطر العمل**: React, Vue 3, Svelte (اختيارية)
+- **تكامل LLM**: محول LangChain، محول MCP
+- **الأمان**: Helmet, CORS, CSP, Rate Limiting متعدد الطبقات
+- **الحاويات**: Docker + Docker Compose
+- **CI/CD**: GitHub Actions (اختبار + نشر تلقائي في npm)
+- **الاختبارات**: Jest + Supertest
+
+---
+
+## 💰 محرك التفاوض اللحظي
+
+يحدد أصحاب المواقع قواعد التفاوض. يتفاوض وكيل الذكاء الاصطناعي على الأسعار في جلسات متعددة الجولات:
+
+```javascript
+// فتح جلسة تفاوض
+const session = await fetch('/api/sovereign/negotiation/sessions', {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    siteId: 'site-uuid',
+    agentId: 'agent-id',
+    originalPrice: 49.99,
+    itemId: 'product-123',
+    itemName: 'زيت زيتون ١ لتر'
+  })
+}).then(r => r.json());
+
+// تقديم عرض مضاد
+const counter = await fetch(`/api/sovereign/negotiation/sessions/${session.sessionId}/propose`, {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ agentId: 'agent-id', proposedPrice: 39.99 })
+}).then(r => r.json());
+// → { status: 'accepted', finalPrice: 42.49, message: 'صفقة! ...' }
+```
+
+### أنواع الشروط
+| الشرط | الوصف |
+|---|---|
+| `bulk_quantity` | خصم على الكميات الكبيرة |
+| `loyalty` | مكافأة للعملاء المتكررين |
+| `time_based` | عروض الساعة السعيدة |
+| `first_purchase` | خصم ترحيبي للمشترين الجدد |
+| `cart_value` | حد أدنى لقيمة السلة |
+| `seasonal` | عروض موسمية بتواريخ محددة |
+| `membership` | أسعار خاصة للأعضاء |
+| `referral` | خصومات الإحالة |
+
+---
+
+## 🛡️ درع مقاومة التزييف (Anti-Hallucination Shield)
+
+محرك تحقق متقاطع يكتشف أكاذيب الذكاء الاصطناعي قبل وصولها للمستخدم:
+
+```javascript
+// التحقق من سعر
+const result = await fetch('/api/sovereign/verify/price', {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    siteId: 'site-uuid',
+    domValue: 29.99,
+    visionValue: 29.99,
+    category: 'electronics',
+    itemName: 'كابل USB'
+  })
+}).then(r => r.json());
+// → { verified: true, confidence: 0.98, severity: 'none' }
+```
+
+### طبقات التحقق
+١. **DOM مقابل الرؤية** — يقارن السعر المستخرج من DOM مع قراءة لقطة الشاشة
+٢. **المعيار السوقي** — يتحقق من السعر مقابل البيانات التاريخية للفئة
+٣. **الاتساق الزمني** — يفحص هل تغير السعر بشكل مريب منذ آخر تحقق
+٤. **النتيجة المركبة** — مزيج مرجح من جميع الطبقات مع تصنيف الخطورة
+
+---
+
+## 📦 متجر قوالب الوكلاء (Community Agent Hub)
+
+قوالب YAML جاهزة لحالات الاستخدام الشائعة. شغّل أي قالب من سطر الأوامر:
+
+```bash
+# عرض القوالب المتاحة
+npx wab-agent templates
+
+# تشغيل قالب
+npx wab-agent run olive-oil-tunisia --budget 50 --region tunis
+
+# تشغيل مع خادم مخصص
+npx wab-agent run hotel-direct-booking --server https://yourserver.com
+```
+
+### القوالب المتاحة
+| القالب | الوصف |
+|---|---|
+| `olive-oil-tunisia` | زيت زيتون من مزارع تونسية صغيرة |
+| `hotel-direct-booking` | حجز فنادق مباشر بدون وسطاء |
+| `artisan-marketplace` | منتجات يدوية من حرفيين مستقلين |
+| `grocery-price-compare` | مقارنة أسعار البقالة بين المتاجر المحلية |
+| `freelancer-direct` | مستقلون بدون رسوم منصات |
+| `restaurant-direct` | مطاعم بدون تطبيقات توصيل |
+| `book-price-scout` | كتب من مكتبات مستقلة |
+| `flight-deal-hunter` | رحلات مباشرة من شركات الطيران |
+| `electronics-price-tracker` | تتبع أسعار الإلكترونيات |
+| `local-services` | مزودي خدمات محليين |
+| `organic-farm-fresh` | منتجات عضوية مباشرة من المزارع |
+
+---
+
+## 🎯 نظام القائد (Commander)
+
+محرك تنسيق مهام محلي يفكك الأهداف العليا إلى مهام مترابطة ويوزعها على وكلاء متخصصين:
+
+```javascript
+// إنشاء مهمة
+const mission = await fetch('/api/commander/missions', {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    goal: 'إيجاد أرخص زيت زيتون في ٥ متاجر',
+    strategy: 'parallel',
+    agents: ['researcher-1', 'analyst-1', 'negotiator-1']
+  })
+}).then(r => r.json());
+
+// إطلاق المهمة
+await fetch(`/api/commander/missions/${mission.id}/launch`, {
+  method: 'POST', headers: { 'Authorization': 'Bearer ' + token }
+});
+```
+
+| القدرة | الوصف |
+|---|---|
+| **تفكيك المهام** | تحويل الأهداف إلى رسوم بيانية مهام (DAG) مع تتبع التبعيات |
+| **سجل الوكلاء** | تتبع قدرات وأداء الوكلاء المسجلين |
+| **تنفيذ متوازٍ** | تشغيل المهام المستقلة بالتوازي عبر عدة وكلاء |
+| **تعلم من النتائج** | تسجيل النتائج لتغذية راجعة في التعلم المعزز |
+| **تنسيق حوسبة طرفية** | توزيع المهام الثقيلة على عقد الحافة |
+
+---
+
+## 🖥️ نظام الحوسبة الطرفية (Edge Compute)
+
+حوّل كل جهاز إلى عقدة AI سيادية — بدون سحابة مركزية:
+
+```javascript
+// تسجيل جهاز كعقدة حوسبة طرفية
+await fetch('/api/commander/edge/nodes', {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    name: 'حاسوبي',
+    capabilities: { cpu: 8, ram: 16384, gpu: true },
+    supportedTasks: ['text-inference', 'vision-analysis', 'price-comparison']
+  })
+}).then(r => r.json());
+```
+
+| القدرة | الوصف |
+|---|---|
+| **تحليل المعدات** | كشف إمكانيات CPU, RAM, GPU لكل عقدة |
+| **تشفير AES-256-GCM** | كل البيانات بين العقد مشفرة من الطرف للطرف |
+| **موازنة حمل مرجحة** | توجيه المهام حسب المعدات والتوفر |
+| **مراقبة بنبضات القلب** | تجاوز فشل تلقائي عند عدم استجابة العقد |
+| **تشكيل أسراب** | تجميع العقد حسب القدرات |
+
+---
+
+## 🐝 محرك التنفيذ بالسرب (Swarm)
+
+أطلق عدة وكلاء بالتوازي لحل مهمة واحدة ثم ادمج نتائجهم بذكاء:
+
+```javascript
+const swarm = await fetch('/api/premium/v2/swarm/execute', {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    task: 'أفضل عروض لاب توب تحت ١٠٠٠ دولار',
+    strategy: 'parallel',        // parallel | sequential | hybrid
+    agentCount: 4,
+    roles: ['researcher', 'analyst', 'price-checker', 'reviewer'],
+    mergeStrategy: 'best-score'  // best-score | fairness-weighted | consensus
+  })
+}).then(r => r.json());
+```
+
+---
+
+## ⚖️ محرك العدالة (Fairness Engine)
+
+طبقة حياد تضمن فرصة متساوية للمواقع الصغيرة والكبيرة:
+
+```javascript
+// بحث مرجح بالعدالة (بدلاً من ترتيب الصلة فقط)
+const results = await fetch('/api/discovery/search?q=زيت+زيتون&fairness=true', {
+  headers: { 'Authorization': 'Bearer ' + token }
+}).then(r => r.json());
+// المزارع الصغيرة تُرتّب بجانب أمازون — مرجحة بدرجة الحياد لا بـ SEO فقط
+```
+
+### كيف يعمل تقييم الحياد
+| العامل | الوزن | الوصف |
+|---|---|---|
+| **اكتمال الإعداد** | ٢٥٪ | مدى جودة إعداد WAB في الموقع |
+| **درجة الثقة** | ٢٥٪ | شهادات السمعة من شبكة الوكلاء |
+| **الشفافية** | ٢٥٪ | إفصاح العمولة، وضوح التسعير |
+| **الاستجابة** | ٢٥٪ | زمن استجابة API، وقت التشغيل، نجاح الإجراءات |
+
+---
+
+## 🧠 ذاكرة الوكيل (Agent Memory)
+
+ذاكرة سلوكية دائمة تسمح للوكلاء بتذكر تفضيلات المستخدم وبناء ارتباطات:
+
+```javascript
+// تخزين ذاكرة
+await fetch('/api/premium/v2/memory', {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    agentId: 'agent-1',
+    type: 'preference',         // preference | interaction | correction | pattern
+    category: 'purchase',       // navigation | purchase | search | form | custom
+    key: 'العلامة-المفضلة',
+    value: 'عضوي-فقط',
+    importance: 0.9
+  })
+}).then(r => r.json());
+
+// إنشاء ارتباطات بين الذكريات
+await fetch('/api/premium/v2/memory/associate', {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    sourceId: 'memory-1',
+    targetId: 'memory-2',
+    relationship: 'leads_to'   // leads_to | similar_to | replaces | depends_on
+  })
+}).then(r => r.json());
+```
+
+---
+
+## 👁️ خدمة الرؤية (Vision Analysis)
+
+تحليل لقطات شاشة متعدد الموفرين لكشف العناصر التفاعلية واستخراج البيانات:
+
+| الموفر | محلي؟ | الوصف |
+|---|---|---|
+| **Moondream** | ✅ | نموذج رؤية محلي خفيف |
+| **Ollama** | ✅ | نماذج محلية عبر Ollama (llava, bakllava) |
+| **OpenAI** | ❌ | GPT-4 Vision |
+| **Anthropic** | ❌ | Claude Vision |
+
+---
+
+## 🔌 بنية الإضافات (Plugin Architecture)
+
+نظام إضافات ديناميكي يسمح بامتدادات من أطراف ثالثة:
+
+```javascript
+// عرض الإضافات المتاحة
+const plugins = await fetch('/api/premium/v2/plugins', {
+  headers: { 'Authorization': 'Bearer ' + token }
+}).then(r => r.json());
+
+// تثبيت إضافة لموقعك
+await fetch('/api/premium/v2/plugins/price-alert/install', {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ siteId: 'site-uuid', config: { threshold: 10 } })
+}).then(r => r.json());
+```
+
+---
+
+## 🔍 تحليل حركة المرور المتقدم (Traffic Intelligence)
+
+| القدرة | الوصف |
+|---|---|
+| **٣٠+ نوع بوت** | كشف Google, Bing, ChatGPT, Claude, Perplexity وغيرها |
+| **تحليل سلوكي** | تصنيف سلوك الوكلاء حسب البصمة والمنصة والنوع |
+| **كشف شذوذ** | كشف الارتفاعات المفاجئة وتحليل أنماط غير عادية |
+| **كشف استغلالات أمنية** | رصد أنماط SQL injection, XSS, Rate anomalies |
+| **تنبيهات Webhook** | إطلاق webhooks عند نشاط مشبوه |
+| **تدقيق للامتثال** | سجل تدقيق كامل للتوافق التنظيمي |
+
+---
+
+## 🔗 محول WAB-MCP
+
+كشف قدرات مواقع WAB كأدوات [MCP](https://modelcontextprotocol.io/) لـ Claude وGPT وGemini:
+
+```javascript
+const { WABMCPAdapter } = require('wab-mcp-adapter');
+
+const adapter = new WABMCPAdapter({
+  siteUrl: 'https://shop.example.com',
+  transport: 'http'           // http | websocket | direct
+});
+
+const tools = await adapter.getTools();
+const result = await adapter.executeTool('execute_action', {
+  name: 'addToCart', params: { sku: 'ABC123' }
+});
+```
+
+### أدوات MCP المدمجة
+| الأداة | الوصف |
+|---|---|
+| `discover` | اكتشاف الإجراءات المتاحة تلقائياً |
+| `get_actions` | قائمة كل الإجراءات مع المعاملات |
+| `execute_action` | تنفيذ إجراء محدد |
+| `read_content` | قراءة محتوى من الصفحة |
+| `get_page_info` | معلومات وصفية عن الصفحة |
+| `fairness_search` | بحث في دليل WAB مرجح بالعدالة |
+| `authenticate` | مصادقة وكيل مع الموقع |
+
+---
+
+## 🖥️ متصفح WAB (سطح المكتب)
+
+متصفح Electron مستقل مع ميزات خصوصية وعدالة مدمجة:
+
+- **حاجب الإعلانات** — ٨٠+ نطاق محظور + مطابقة أنماط URL + قواعد CSS تجميلية
+- **درع الاحتيال** — كشف نطاقات TLD مشبوهة وانتحال أسماء العلامات التجارية
+- **تصنيف العدالة** — أولوية للمواقع المستقلة، تنبيه عن تركز الشركات الكبرى
+- **دردشة الوكيل** — مساعد AI مدمج للتصفح
+- **الإشعارات** — تحليل الصفحة مع تنبيهات أمان وعدالة
+- **وضع الشبح** — تصفح بخصوصية بدون تتبع
+- **بحث ذكي** — تكامل DuckDuckGo للبحث الخاص
+
+```bash
+# تشغيل متصفح WAB
+cd wab-browser
+npm install
+npx electron .
+
+# بناء المثبت (Windows NSIS)
+npm run build:win
+```
+
+---
+
+## 📱 متصفح PWA (الهاتف)
+
+تطبيق ويب تقدمي لـ Android وiOS — قابل للتثبيت من أي متصفح هاتف:
+
+- **حاجب إعلانات** — ٤٥+ نطاق إعلاني محظور + مطابقة أنماط URL
+- **كشف الاحتيال** — تنبيهات TLD مشبوهة وفحوصات انتحال العلامات
+- **وضع العدالة** — تصفية مواقع التقنية الكبرى لتعزيز البدائل المستقلة
+- **أولوية غير متصل** — عامل الخدمة يخزن أصول الواجهة مؤقتاً للتشغيل بدون إنترنت
+- **بحث خاص** — تكامل DuckDuckGo (بدون تتبع Google)
+- **دردشة وكيل** — مساعد AI مع احتياطي محلي
+
+ثبّته من: `https://yourserver.com/pwa/`
+
+---
+
+## 📦 إضافة WordPress
+
+إضافة WordPress أصلية لإضافة دعم WAB لأي موقع WordPress:
+
+| القدرة | الوصف |
+|---|---|
+| **صفحة إعدادات** | إعداد عنوان API، معرف الموقع، الصلاحيات |
+| **إجراءات لكل صفحة** | صندوق وصف لإضافة إجراءات WAB مخصصة لكل صفحة/مقال |
+| **مستند اكتشاف** | توليد تلقائي لنقطة اكتشاف WAB |
+| **عنصر لوحة تحكم** | عرض حالة WAB وإحصائيات تفاعل الوكلاء |
+| **كود قصير** | `[wab_bridge]` لتضمين WAB في صفحات محددة |
+| **خطافات** | `wab_before_action` / `wab_after_action` لمنطق مخصص |
+
+راجع [`web-agent-bridge-wordpress/README.md`](web-agent-bridge-wordpress/README.md) للتوثيق الكامل.
+
+---
+
+## �️ درع الأمان — حماية متعددة الطبقات (SPEC §8.10–§8.13)
+
+مستوحى من حادثة PocketOS الشهيرة حيث حذف وكيل ذكاء اصطناعي ٢٠ ألف مستخدم بأمر واحد، يضيف WAB خمس طبقات حماية متراكمة لا تستبدل بعضها بل تتكامل معاً. كل طبقة فعّالة من خطة معينة فما فوق.
+
+### §8.9 — رموز الجلسة المُحدَّدة النطاق (Scoped Session Tokens) — كل الخطط
+
+كل توكن جلسة يحمل **نطاقًا** صريحًا: `read` أو `write` أو `delete` أو `admin`. الإجراءات المُصنّفة "هدّامة" (تحتوي على فعل مثل `delete` أو `drop` أو `purge` أو `wipe` أو `truncate`) تتطلب نطاق `delete` أو أعلى. الموقع يستطيع توسيع التصنيف عبر `siteConfig.destructiveActions[]`.
+
+```js
+// الموقع يحدد البيئة والإجراءات الهدّامة
+{
+  "environment": "production",
+  "destructiveActions": ["bulkUnsubscribe"],
+  "nonDestructiveActions": ["softArchive"]
+}
+```
+
+عند الرفض → `403 SCOPE_DENIED` مع تفاصيل السبب في سجل التدقيق.
+
+### §8.10 — التشغيل التجريبي الإلزامي (Mandatory Dry-Run) — كل الخطط (MIT)
+
+للإجراءات الهدّامة، **لا يمكن** للوكيل التنفيذ في خطوة واحدة. يجب أن يمرّ بمرحلتين:
+
+**المرحلة ١ — طلب خطة:**
+```http
+POST /api/wab/actions/deleteUser
+{ "params": {"id": 42}, "dry_run": true }
+```
+الاستجابة:
+```json
+{ "result": { "plan_id": "wabp_…", "simulation": {
+  "would_affect": ["site:abc", "action:deleteUser"],
+  "side_effects": ["deleteUser"], "reversible": false,
+  "summary": "سيقوم بحذف المستخدم #42 — لم يتم تنفيذ أي تغيير فعلي."
+}, "expires_at": "…" }}
+```
+
+**المرحلة ٢ — التأكيد:**
+```http
+POST /api/wab/actions/deleteUser
+{ "params": {"id": 42}, "dry_run": false, "plan_id": "wabp_…" }
+```
+
+التحقق رباعي الأبعاد: `(sessionFingerprint, siteId, actionName, paramsHash)`. أي انحراف ولو حرف واحد في المعاملات → `412 DRY_RUN_PLAN_MISMATCH`. مهلة افتراضية ٥ دقائق (حد أقصى ٦٠).
+
+### §8.11 — البوابة البشرية خارج النطاق (Out-of-Band Human Gate) — Pro فما فوق
+
+للمواقع الحساسة، الإجراءات الهدّامة تُجمَّد ويُرسَل **رمز من ٦ أرقام** عبر قناة لا يراها الوكيل (Webhook موقَّع، بريد إلكتروني، Telegram، Slack...). فقط بعد موافقة بشرية حقيقية يُسمح بالتنفيذ بحمل `confirmation_id`.
+
+**القنوات الجاهزة:**
+- `webhook` — `POST` JSON موقَّع بـ HMAC-SHA256 (header: `X-WAB-Signature: sha256=…`)
+- `email` — SMTP عبر `nodemailer` (يدعم متغيرات البيئة `SMTP_HOST/PORT/USER/PASS`)
+- `console` — للتطوير فقط (يكتب على stderr)
+- `null` — لا شيء (للاختبارات والوضع المعزول)
+
+**الحماية من الهجوم العنيف:**
+- قفل ٥ محاولات لكل تحدي (داخل الموديول).
+- **حد معدل بحسب IP**: ٣٠ محاولة / ١٠ دقائق + ٥ موافقات ناجحة / ١٠ دقائق. عند التجاوز → `429 RATE_LIMIT_TOO_MANY_ATTEMPTS` مع `Retry-After`.
+
+### §8.12 — محرك تحليل النية (Intent Analysis Engine) — Premium فما فوق
+
+نقاط مخاطرة حتمية (٠–١٠٠) تُحسب من إشارات يمكن تفسيرها — لا توجد عشوائية ولا نموذج لغوي. الإشارات:
+
+| الإشارة | الوزن |
+|---|---|
+| فعل هدّام (delete, drop, purge…) | +50 |
+| فعل كتابة عادي | +10 |
+| البيئة `production` | +30 |
+| كلمات خطر (`*`, `all`, `cascade`, `force`) | +15 لكل واحدة (سقف +30) |
+| محددات شاملة في المعاملات | +15 |
+| مصفوفة كبيرة (>50 عنصرًا) | +10 |
+| نوبة طلبات (>10/دقيقة) | +15 |
+| سرعة تنفيذ مرتفعة | +10 |
+
+العتبات الافتراضية: `low:30, medium:70, high:90`. النتيجة العالية يمكن أن:
+1. تُجبر التشغيل التجريبي (`required_gate: "dry_run"`)
+2. تُجبر البوابة البشرية (`required_gate: "human_gate"`)
+3. تحجب نهائيًا بـ `403 INTENT_BLOCKED`
+
+### §8.13 — اللقطات والتراجع (Snapshot & Rollback) — Enterprise
+
+قبل تنفيذ أي إجراء هدّام، WAB يأخذ لقطة قابلة للاسترجاع تلقائيًا (إذا سجّل الموقع `restorer`). البيانات تُحفَظ في جدول `wab_snapshots` (sqlite) لمدة ٣٠ يومًا.
+
+**نقاط الإدارة (X-WAB-Site-Id + X-WAB-Api-Key):**
+```http
+GET  /api/wab/admin/snapshots         # قائمة آخر اللقطات
+GET  /api/wab/admin/snapshots/:id     # تفاصيل لقطة
+POST /api/wab/admin/rollback/:id      # تنفيذ التراجع
+```
+
+**واجهة إدارة جاهزة:** انتقل إلى [`/admin/snapshots`](https://webagentbridge.com/admin/snapshots) وأدخل `Site ID` + `API Key` للتصفح والاسترجاع بزر واحد.
+
+**حالات اللقطة:** `recorded → restored | failed | expired`.
+
+### كيف تستخدمها من SDK
+
+```js
+const { SafetyShieldClient } = require('@webagentbridge/sdk');
+
+const shield = new SafetyShieldClient({
+  baseUrl: 'https://webagentbridge.com',
+  sessionToken: 'Bearer-token-from-/sessions',
+});
+
+// الطريقة الموصى بها: تشغيل تجريبي ثم تأكيد
+const plan = await shield.dryRun('deleteUser', { id: 42 });
+console.log(plan.simulation.summary); // اعرضها للمستخدم البشري
+const result = await shield.confirmAction(plan, { code: '123456' });
+// أو في خطوة واحدة (ترجع envelope من نوع pending_human_gate إذا لزم):
+const out = await shield.safeExecute('deleteUser', { id: 42 });
+```
+
+### جدول الأخطاء الموحَّدة
+
+| الكود | HTTP | المعنى |
+|---|---|---|
+| `SCOPE_DENIED` | 403 | نطاق التوكن غير كافٍ |
+| `DRY_RUN_REQUIRED` | 412 | يجب تشغيل تجريبي أولاً |
+| `DRY_RUN_PLAN_MISMATCH` | 412 | المعاملات تغيّرت بين المرحلتين |
+| `DRY_RUN_PLAN_EXPIRED` | 412 | انقضت مهلة الخطة |
+| `HUMAN_GATE_REQUIRED` | 202 | تم إصدار تحدٍّ — انتظر الموافقة البشرية |
+| `HUMAN_GATE_PENDING` | 425 | الموافقة لم تحدث بعد |
+| `HUMAN_GATE_BAD_CODE` | 401 | رمز خاطئ |
+| `HUMAN_GATE_LOCKED` | 429 | استُنفدت ٥ محاولات لهذا التحدي |
+| `RATE_LIMIT_TOO_MANY_ATTEMPTS` | 429 | تجاوز حد الـ IP |
+| `INTENT_BLOCKED` | 403 | نتيجة محرك النية ≥90 |
+| `SNAPSHOT_NOT_FOUND` | 404 | لقطة غير موجودة |
+| `NO_RESTORER` | 503 | الموقع لم يسجّل `restorer` |
+
+التفاصيل الكاملة (جداول الإشارات، صيغ التواصل، مرجع التطبيق) في [`docs/SPEC.md`](docs/SPEC.md) §8.9–§8.13.
+
+---
+
+## �📋 مواصفة بروتوكول WAB
+
+المواصفة المعيارية الكاملة متاحة في [`docs/SPEC.md`](docs/SPEC.md):
+
+| الطبقة | الوصف |
+|---|---|
+| **طبقة البروتوكول** | صيغة مستند الاكتشاف، بروتوكول الأوامر، بروتوكول العدالة |
+| **طبقة التشغيل** | واجهة `window.AICommands`، محرك الاكتشاف التلقائي، صندوق الأمان |
+| **طبقة النقل** | متغير JavaScript عام، WebSocket, HTTP, WebDriver BiDi, MCP |
+
+### دورة الحياة من ٥ مراحل
+١. **اكتشاف** — الوكيل يجد مستند اكتشاف WAB (`.well-known/wab.json` أو وسم سكريبت)
+٢. **مصادقة** — الوكيل يستبدل `siteId` بتوكن جلسة
+٣. **تخطيط** — الوكيل يقرأ الإجراءات المتاحة ومعلومات الصفحة
+٤. **تنفيذ** — الوكيل يشغل الإجراءات عبر الجسر
+٥. **تأكيد** — النتائج تُتحقق عبر درع مقاومة التزييف
+
+---
+
+## 🤝 المساهمة
+
+نرحب بالمساهمات! اقرأ [دليل المساهمة](CONTRIBUTING.md) للبدء.
+
+---
+
+---
+
+## 💼 الأسس التجارية ✨ جديد (v3.8.0)
+
+أربع ركائز إنتاجية للتمويل فوق البروتوكول المفتوح. كلها مبنية **بأمان، مع نطاقات محددة، وبوّابات إدارية** — لا يوجد منطق فوترة داخل المسارات، فقط نصوص تسويقية في الصفحات العامة.
+
+### 1. 🤝 برنامج الشركاء المعتمدين — `/partners`
+
+دليل بثلاث طبقات للشركاء والمتكاملين. الطبقة الأساسية تُعتمد تلقائيًا عند بلوغ درجة Ring 4 ≥ 8.
+
+| الطبقة | السعر | اعتماد تلقائي | الشارة |
+|--------|------|----------------|--------|
+| **Basic** | مجاني | ✅ (Ring 4 ≥ 8) | SVG زمردي |
+| **Verified** | 499 € / سنة | مراجعة يدوية | SVG سماوي |
+| **Premium** | 2.9k–9.9k € / سنة | مراجعة يدوية | SVG بنفسجي |
+
+**نقاط النهاية:** `POST /api/partners/apply` · `GET /api/partners` · `GET /api/partners/:partner_id` · `GET /api/partners/badge/:slug.svg` · إدارية: `GET /api/partners/admin/applications` · `POST /api/partners/admin/approve`
+
+### 2. 📊 طبقات Trust Graph API — `/trust-graph-api`
+
+وصول مُتدرّج لنقاط نهاية السمعة والحقيقة و Ring 4. الزوار المجهولون يحصلون على 200 طلب/شهر + 10 طلب/دقيقة افتراضيًا.
+
+| الطبقة | السعر | الحصة | المعدّل | نطاقات إضافية |
+|--------|------|------|--------|----------------|
+| **Free** | 0 € | 1k / شهر | 30 طلب/د | `trust:read` |
+| **Pro** | 10 € / شهر | 100k / شهر | 120 طلب/د | `+trust:history`, `+reputation:read` |
+| **Enterprise** | تواصل معنا | 5M / شهر | 600 طلب/د | `+governance:write`, `+sla:priority` |
+
+**نقاط النهاية:** `POST /api/keys/issue` (إصدار ذاتي للطبقة المجانية) · `GET /api/keys/me` · `POST /api/keys/revoke` · إدارية: `POST /api/keys/admin/upgrade` · `GET /api/keys/admin/list`. ترويسات الاستجابة: `X-WAB-Tier`, `X-WAB-Quota-Used`, `X-WAB-Quota-Limit`.
+
+### 3. 🏛️ خدمة Governance SaaS — `/governance`
+
+مساحات عمل تدقيق مقاومة للعبث للامتثال لقانون الذكاء الاصطناعي الأوروبي و GDPR. تصدير NDJSON وفق المادة 12 من قانون الذكاء الاصطناعي الأوروبي.
+
+| الخطة | السعر | المقاعد | فترة الاحتفاظ | الأحداث / شهر |
+|------|------|---------|---------------|----------------|
+| **Team** | 99 € / شهر | 5 | 90 يومًا | 100k |
+| **Business** | 499 € / شهر | 25 | 365 يومًا | 2M |
+| **Enterprise** | 2.5k+ € / شهر | 500 | 7 سنوات | 1B |
+
+**نقاط النهاية:** إدارية: `POST /api/governance-saas/workspaces` · للأعضاء: `GET /workspaces/:id` · `POST /workspaces/:id/members` · `POST /workspaces/:id/events` (يتطلب مفتاح API بنطاق `governance:write`) · `GET /workspaces/:id/events` · `GET /workspaces/:id/export` (بثّ NDJSON).
+
+### 4. 🕸️ التحقق من ترخيص شبكة المؤسسات — `/enterprise-mesh`
+
+تحقّق ترخيص مستضاف ذاتيًا بقدرات عمل دون اتصال مع تدوير مفاتيح بنمط JWKS. خدمة التوقيع مدفوعة / خارج المستودع.
+
+**نقاط النهاية:** `POST /api/enterprise-mesh/verify` · `GET /api/enterprise-mesh/jwks` · `POST /api/enterprise-mesh/heartbeat` · إدارية: `POST /api/enterprise-mesh/admin/register` · `POST /api/enterprise-mesh/admin/revoke`. تستخدم التوكنات توقيع Ed25519 منفصل مع تدوير `kid` عبر متغيّر البيئة `WAB_LICENSE_PUBLIC_KEYS` (JSON بصيغة `{kid → PEM | raw-b64u}`).
+
+### الأمان والسلامة
+
+- جميع نقاط الإدارة محميّة بـ `X-Admin-Token` ضدّ متغيّرات `WAB_*_ADMIN_TOKEN` (503 عند عدم التهيئة).
+- مفاتيح API تُخزَّن فقط كهاش SHA-256؛ صيغة السرّ `wabk_<keyId>_<random>` تُعاد مرّة واحدة فقط.
+- توكنات مساحة العمل تستخدم HMAC-SHA256 مع مقارنة بزمن ثابت.
+- نوافذ تحكم بالمعدّل منزلقة داخل العملية (60 ث). تتبّع الحصة يوميًا عبر UPSERT في `wab_api_usage`.
+- عناوين IP تُهاش بواسطة `IP_HASH_SALT` قبل التخزين.
+- 25 اختبار مخصّص في `tests/commercial-foundations.test.js`؛ مجموع اختبارات الحزمة الآن 428 / 428 ناجحة.
+
+---
+
+## 📄 الرخصة
+
+MIT — مجاني للاستخدام والتعديل والتوزيع.
+
+</div>
+