@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ar-SA/plan-plugin.md

@@ -0,0 +1,200 @@
+---
+title: "المكون الإضافي للخطة والسوق"
+description: "قم بتثبيت خطة Agent-Native skills (/visual-plan، /visual-recap) بالإضافة إلى موصل Plan MCP المستضاف كرمز Claude أو مكون إضافي Codex، أو باستخدام CLI العام. كيفية عمل التحديثات وما إذا كنت بحاجة إلى إرسال أي شيء."
+---
+
+# المكون الإضافي للخطة والسوق
+
+يأتي تطبيق Agent-Native **Plan** كحزمة واحدة قابلة للتثبيت. يؤدي التثبيت الفردي إلى إضافة أمر الشرطة المائلة للخطة skills ** و** إلى موصل Plan MCP المستضاف، حتى يتمكن الوكيل من إنشاء الخطط ويمكن لـ skills نشرها مباشرة في تطبيق الخطة.
+
+## ما تحصل عليه {#what-you-get}
+
+تمنحك عملية التثبيت الواحدة ما يلي:
+
+- **اثنان skills** — `/visual-plan` (نقطة الدخول الأساسية) و`/visual-recap`.
+- **موصل Plan MCP** — مسجل في التطبيق المستضاف على `https://plan.agent-native.com` (نقطة نهاية MCP `https://plan.agent-native.com/_agent-native/mcp`، اسم الخادم `plan`).
+
+```an-diagram title="Three routes, one bundle" summary="The universal CLI, Claude Code plugin, and Codex plugin all install the same two skills plus the hosted Plan connector."
+{
+  "html": "<div class=\"diagram-routes\"><div class=\"diagram-col\"><div class=\"diagram-node\">Universal CLI<br><small class=\"diagram-muted\">skills add visual-plan</small></div><div class=\"diagram-node\">Claude Code plugin<br><small class=\"diagram-muted\">/plugin install</small></div><div class=\"diagram-node\">Codex plugin<br><small class=\"diagram-muted\">codex plugin add</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">/visual-plan</span><span class=\"diagram-pill accent\">/visual-recap</span><small class=\"diagram-muted\">two skills</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Plan MCP connector<br><small class=\"diagram-muted\">plan.agent-native.com/_agent-native/mcp</small></div></div>",
+  "css": ".diagram-routes{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-routes .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-routes .diagram-arrow{font-size:22px;line-height:1}.diagram-routes .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}.diagram-routes .center .diagram-pill{margin:2px}"
+}
+```
+
+افتراضيًا، يقوم كل من skills بالنشر على تطبيق الخطة المستضاف - حيث يقومان بإنشاء خطة عبر
+موصل MCP ويسلمك رابطًا أو خطة مضمنة للمراجعة. إنهم لا يتخلصون أبدًا
+خطة Markdown/ASCII المضمنة في الدردشة باعتبارها التسليم. إذا كانت أداة الخطة
+إرجاع `needs auth`، أو `Unauthorized`، أو `Session terminated`، وإعادة المصادقة
+الموصل بدلاً من الرجوع إلى الإخراج المضمن. رموز الوصول هي
+طويلة الأمد (افتراضي لمدة 30 يومًا، وتحديث متدرج لمدة 365 يومًا)، لذلك يجب أن يكون هذا نادرًا؛
+عندما يحدث ذلك، يكون الإصلاح الخفيف هو:
+
+```bash
+npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
+```
+
+يقوم `reconnect` بالبحث عن الموصل وتحديثه بواسطة URL للموضع المحلي المحدد
+العميل — لا حاجة إلى إعادة التثبيت. ابدأ سلسلة Codex جديدة بعد إعادة الاتصال لذلك
+يتم إعادة تحميل سجل الأداة. في رمز Claude، المعادل هو `/mcp` →
+**المصادقة / إعادة الاتصال**، أو نفس الأمر مع `--client claude-code`.
+
+الاستثناء صريح **وضع خصوصية الملفات المحلية**. عندما لا تطلب قاعدة بيانات
+يكتب `AGENT_NATIVE_PLANS_MODE=local-files` أو يضبطه، ويجب ألا يتصل skills
+موصل الخطة MCP. يكتبون `plans/<slug>/plan.mdx` بالإضافة إلى اختياري
+`canvas.mdx`، و`prototype.mdx`، و`.plan-state.json`، ثم قم بالمعاينة محليًا باستخدام:
+
+```bash
+npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
+```
+
+يؤدي هذا إلى بدء جسر مضيف محلي صغير وفتح الخطة UI مقابل المضيف المحلي
+المجلد. (يدير `plan local preview` مسارًا محليًا لخادم تطوير الخطة بدلاً من ذلك، و
+`plan local preview --out preview.html` عبارة عن فتحة هروب قديمة تكتب
+ملف HTML ثابت مستقل. يتم قبول `plan serve` كاسم مستعار قصير لـ
+`plan local serve`.)
+
+بعض الأخطاء التي تستحق المعرفة في وضع الملفات المحلية:
+
+- **استخدم متصفح Chromium.** يحظر Safari صفحة خطة HTTPS المستضافة من
+  قراءة جسر المضيف المحلي `http://127.0.0.1` (محتوى مختلط / خاص
+  الشبكة)، لذلك تظل الصفحة معلقة في "تحميل الخطة". على نظام التشغيل macOS `--open` بالفعل
+  يفضل Chrome/Chromium/Edge/Brave؛ إذا تم فتح Safari على أية حال، فأعد فتح الملف المطبوع
+  URL في متصفح Chromium.
+- **تم كتابة URL المقدم إلى `plans/<slug>/.plan-url`** (تجاوز بـ
+  `--url-file`). يمكن للوكيل ذو الخلفية أو بدون رأس قراءة هذا الملف بدلاً من
+  إلغاء stdout `serve` طويل الأمد. تعامل معه كملف رمزي محلي و
+  لا ترتكبها.
+- **التحقق بدون مراقبة** في حالة عدم توفر متصفح:
+  يبدأ `npx @agent-native/core@latest plan local verify --dir plans/<slug>`
+  الجسر، يتحقق من الاختبار المبدئي للشبكة الخاصة وحمولة JSON، ويطبع
+  التشخيص، والخروج من الصفر عند الفشل - لا حاجة إلى عيون بشرية.
+- **قم بتشغيل `plan local check` أولاً.** فهو يتحقق من صحة MDX مقابل الخطة
+  مخطط كتلة العارض (بما في ذلك الحقول المطلوبة مثل عنصر `checklist`
+  سؤال `id`/`label` و`question-form` `id`/`title`/`mode`)، إذن التأليف
+  تظهر الأخطاء قبل تسليم المتصفح بدلاً من أن تكون أداة التحميل متوقفة.
+
+بالنسبة للمجلدات الموجودة في الريبو الحالي، يتضمن المسار المحلي المباشر `?path=...` لذلك
+يمكن لتطبيق Plan المحلي الاحتفاظ بتحريرات المتصفح محفوظة في مجلد الريبو. الخطة
+يستخدم التطبيق `apps.plan.roots[0].path` في `agent-native.json` كمكان افتراضي
+لحفظ الخطط المحلية التي تم الترويج لها، والرجوع إلى `plans/`.
+
+يؤدي هذا إلى إبقاء محتوى الخطة خارج قاعدة بيانات خطة Agent-Native. المشاركة المستضافة،
+لن تكون التعليقات ولقطات الشاشة وسجل الخطة متاحة إلا إذا قمت بذلك صراحةً
+النشر لاحقًا.
+
+```an-diagram title="Hosted vs. local-files mode" summary="By default skills publish through the connector; local-files mode writes MDX to disk and previews via a localhost bridge instead."
+{
+  "html": "<div class=\"diagram-modes\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Default · hosted</span><strong>Publish to the Plan app</strong><small class=\"diagram-muted\">MCP connector &rarr; hosted DB &rarr; share links, comments, history, screenshots</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">Local-files privacy</span><strong>Write MDX to disk</strong><small class=\"diagram-muted\">plan.mdx + canvas.mdx + prototype.mdx &rarr; localhost bridge &rarr; hosted Plan UI reads local source. No DB writes until <code>publish-visual-plan</code>.</small></div></div>",
+  "css": ".diagram-modes{display:flex;gap:14px;flex-wrap:wrap}.diagram-modes .diagram-card{flex:1 1 260px;display:flex;flex-direction:column;gap:6px;padding:16px 18px}"
+}
+```
+
+يحتوي Agent Native Desktop على مسار مزامنة ملف محلي منفصل للخطط المستضافة:
+يمكن لتطبيق سطح المكتب عكس خطة مستضافة لملفات MDX المحلية واستيراد التعديلات مرة أخرى
+بدون استنساخ تطبيق الخطة أو تشغيل CLI. يحافظ سير العمل هذا على الاستضافة
+تخطيط قاعدة البيانات كمصدر للحقيقة؛ استخدم وضع خصوصية الملفات المحلية عند الهدف
+لا تتم كتابة خطة قاعدة بيانات.
+
+> يحمل المكون الإضافي (`agent-native-visual-plans`) معرف التطبيق `visual-plans`، ولهذا السبب فإن اسم المكون الإضافي Claude Code واسم المكون الإضافي Codex كلاهما `agent-native-visual-plans`. اسم العرض لتطبيق الخطة هو "Agent-Native Plan".
+
+## تثبيت المسارات {#install}
+
+هناك ثلاث طرق. **مسار CLI العالمي** هو الذي نوصي به افتراضيًا، لأنه يقوم بتثبيت skills **و** الذي يتيح لك اختيار الوضع المستضاف أو الملفات المحلية أو الاستضافة الذاتية في تدفق واحد. مسارات المكونات الإضافية مخصصة للمضيفين الذين لديهم نظام مكون إضافي/سوق من الدرجة الأولى ويستخدمون الخطط المستضافة بشكل افتراضي.
+
+### مسار المهارة العالمي (أي مضيف MCP) {#universal}
+
+يعمل مع أي مضيف - Claude Code، وCodex، وCursor، وCline، وGoose، وتطبيقات ChatGPT المخصصة MCP، وClaude Cowork، وأي شيء آخر متوافق مع MCP. يقوم Agent-Native CLI بتثبيت كل من skills، وتسجيل موصل الخطة المستضافة MCP، ** وتشغيل المصادقة للعميل (العملاء) المحليين المحددين في نفس الخطوة **، بحيث لا يصل استدعاء الأداة الأول إلى جدار OAuth:
+
+```bash
+npx @agent-native/core@latest skills add visual-plan
+```
+
+يؤدي هذا إلى تثبيت `visual-plan` بالإضافة إلى مهارة `visual-recap` المصاحبة، ثم تسجيل موصل `plan`، ثم تشغيل المصادقة (مطالبة OAuth بالمشاركة المستضافة/المدعومة بالحساب). إشارات مفيدة:
+
+- `--client codex|claude-code|claude-code-cli|cowork|all` — أي الوكلاء المحليين سيكتبون تهيئة MCP لهم (`all` الافتراضي).
+- `--no-connect` - تسجيل الموصل دون المصادقة؛ قم بتشغيل `npx @agent-native/core@latest connect https://plan.agent-native.com --client all` لاحقًا، أو اختر `--client` الأضيق.
+- `--mode hosted|local-files|self-hosted` - اختر المشاركة المستضافة، أو ملفات MDX المحلية بالكامل، أو تطبيق الخطة الخاص بك.
+- `--mcp-url <url>` — قم بتوجيه الموصل إلى أصل مخصص (نفق ngrok، أو خادم تطوير محلي، أو نشر مستضاف ذاتيًا) بدلاً من المصدر الافتراضي المستضاف.
+- `--with-github-action` - اكتب أيضًا إجراء PR Visual Recap GitHub (راجع [PR Visual Recap](/docs/pr-visual-recap)).
+
+تقدم عمليات التثبيت التفاعلية أيضًا إجراء PR Visual Recap عندما لا يكون هناك سير عمل
+حاضر. قل نعم لإضافتها أثناء إعداد المهارة، أو قم بتشغيل الأمر أعلاه لاحقًا
+مع `--with-github-action`. بعد كتابة سير العمل، قم بتشغيل:
+
+```bash
+npx @agent-native/core@latest recap setup
+npx @agent-native/core@latest recap doctor
+```
+
+يقوم `recap setup` بتكوين أسرار إجراء GitHub ومتغيراته حيثما أمكن ذلك،
+ويتحقق `recap doctor` من سير العمل، ورمز النشر المحلي، وGitHub repo
+الوصول، وتكوين Actions المطلوب. بعد انتهاء التثبيت، أعد التشغيل أو
+أعد تحميل العميل الوكيل حتى يتم تحميل skills الجديد والأدوات، ثم قم بتشغيله
+`/visual-plan`.
+
+> ملاحظة: يقوم `npx skills@latest add BuilderIO/agent-native --skill visual-plan` (Vercel/open Skills CLI) بتثبيت **التعليمات فقط** - ولا يسجل موصل MCP. استخدم Agent-Native CLI أعلاه عندما تريد توصيل الموصل أيضًا.
+
+### رمز Claude (مكون إضافي) {#claude-code}
+
+إن مستودع `BuilderIO/agent-native` العام هو في حد ذاته سوق للمكونات الإضافية لـ Claude Code، لذا يمكنك إضافته مباشرة - دون الحاجة إلى خطوة إنشاء. داخل رمز Claude:
+
+```text
+/plugin marketplace add BuilderIO/agent-native
+/plugin install agent-native-visual-plans@agent-native-apps
+/reload-plugins
+/mcp        # authenticate the Plan connector (one OAuth approval)
+```
+
+يضيف `/plugin install` كلاً من الخطة skills وتكوين **URL فقط** MCP (لا توجد أسرار في الحزمة)؛ `/mcp` → **المصادقة** تكمل مصافحة OAuth. استخدم المسار CLI العالمي بدلاً من ذلك عندما تريد ملفات محلية أو وضع الاستضافة الذاتية.
+
+> يُسمى كتالوج السوق `agent-native-apps` والمكون الإضافي للخطة هو `agent-native-visual-plans`، لذا يكون هدف التثبيت دائمًا هو `agent-native-visual-plans@agent-native-apps`.
+
+### Codex (مكون إضافي) {#codex}
+
+نفس الريبو هو سوق المكونات الإضافية Codex. قم بإضافته، وتثبيت المكون الإضافي، ثم قم بمصادقة الموصل:
+
+```bash
+codex plugin marketplace add BuilderIO/agent-native
+codex plugin add agent-native-visual-plans@agent-native-apps
+codex mcp login plan   # OAuth in the browser
+```
+
+بعد التثبيت، **ابدأ سلسلة Codex جديدة** حتى يتم تحميل الأدوات skills وMCP في الجلسة. يشحن البرنامج المساعد موصل URL فقط (`[mcp_servers.plan]` → `https://plan.agent-native.com/_agent-native/mcp`)؛ يقوم `codex mcp login plan` بتشغيل التدفق OAuth. يعمل مسار CLI العالمي أعلاه أيضًا مع Codex (`npx @agent-native/core@latest skills add visual-plan --client codex`) إذا كنت تفضل أمرًا واحدًا يتم تثبيته والمصادقة عليه معًا، أو عندما تريد الملفات المحلية أو وضع الاستضافة الذاتية.
+
+> **عمليات التثبيت الأقدم:** إذا كان التكوين الخاص بك لا يزال يحتوي على إدخال `agent-native-plans` يشير إلى نفس URL، أو تشغيل `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex` لـ Codex، أو نفس الأمر مع هدفك `--client`، فسيتم دمجه في اسم `plan` المتعارف عليه.
+
+## التحديثات {#updates}
+
+يقوم البرنامج الإضافي بتوجيه التحديث التلقائي - لا يمكنك إعادة تعبئة السوق أو إعادة إضافته لتغييرات روتينية في المهارات:
+
+- **Claude Code** — يقوم إدخال السوق بتعيين `autoUpdate: true` ويستخدم المكون الإضافي إصدار الالتزام-SHA، لذلك يسحب كود Claude الإصدارات الجديدة من الريبو عند بدء التشغيل؛ قم بتشغيل `/reload-plugins` للتنشيط. كل دفعة إلى فرع الريبو الافتراضي تصل إلى المستخدمين المثبتين تلقائيًا.
+- **Codex** — يقوم المكون الإضافي `version` بتضمين تجزئة محتوى لنقطة النهاية skills وMCP المجمعة (على سبيل المثال، `1.0.0+codex.<hash>`)، لذا فإن أي تغيير في المهارة أو نقطة النهاية يؤدي إلى إصدار جديد. تعمل الترقية التلقائية لبدء التشغيل Codex على إعادة تثبيت أسواق git التي تم تكوينها من تلقاء نفسها؛ ما عليك سوى **بدء موضوع جديد** لمتابعة التغيير. ليست هناك حاجة إلى دليل `codex plugin marketplace upgrade` للتحديثات الروتينية.
+- **مسار CLI العالمي** — قم بتشغيل `npx @agent-native/core@latest skills status visual-plan` للتحقق من مجلدات المهارات المنسوخة، أو `npx @agent-native/core@latest skills update visual-plan` لتحديثها في مكانها. لا تزال إعادة تشغيل `skills add visual-plan` تعمل عندما تريد أيضًا إعادة تسجيل/مصادقة الموصل. يقوم `@latest` دائمًا بسحب skills الحالي من حزمة `@agent-native/core` المنشورة.
+
+يشير الموصل إلى تطبيق **مستضاف**، وبالتالي فإن actions لتطبيق Plan وسطح الأداة المباشرة يعكسان دائمًا الإصدار المنشور بغض النظر عن وقت تثبيتك؛ فقط تعليمات المهارات المجمعة تتبع آليات التحديث المذكورة أعلاه.
+
+> **المشرفون:** يتم إنشاء حزمة السوق (`.claude-plugin/`، `.agents/plugins/`) من الخطة الأساسية skills بواسطة `pnpm sync:plan-marketplace` وتم التحقق منها في CI بواسطة `pnpm guard:plan-marketplace`، وبالتالي فإن السوق المنشورة تتطابق دائمًا مع الخطة الأساسية skills. قم بتحرير المهارة، وتشغيل `pnpm sync:plan-marketplace`، والالتزام.
+
+## هل تحتاج إلى إرسال أي شيء؟ {#submission}
+
+**لا يلزم تقديم أو مراجعة لتوزيع هذا أو تثبيته.** `BuilderIO/agent-native` هو سوق git عام مستضاف ذاتيًا، لذلك يضيفه المستخدمون مباشرة باستخدام الأوامر المذكورة أعلاه على **كل من Claude Code وCodex** — بدون طلب أو موافقة. لا يحتاج مسار CLI العالمي إلى سوق على الإطلاق.
+
+قابلية الاكتشاف الاختيارية، إذا كنت تريد قائمة عامة:
+
+- **Claude Code** على سوق مجتمعي يمكنك _اختياريًا_ الإرسال إليه للإدراج (الإرسال بالإضافة إلى المراجعة التلقائية). يتم إدراج السوق الرسمي المنسق من قبل Anthropic وفقًا لتقدير Anthropic - ولا يوجد تطبيق مفتوح للخدمة الذاتية. ولا يلزم استخدام أي منهما لأوامر التثبيت المذكورة أعلاه.
+- **Codex** يحتوي على كتالوج المكونات الإضافية المنسق بواسطة OpenAI (قائمة السماح مغلقة، مصدرها شراكة وليس تقديم خدمة ذاتية). لا تحتاج أسواق git المستضافة ذاتيًا ومسار CLI إلى إرسال للعمل.
+
+باختصار: قم بشحنه كسوق git مستضاف ذاتيًا/عامًا ويقوم المستخدمون بتثبيته مباشرةً؛ أرسل إلى كتالوج منسق فقط إذا كنت تريد إدراجه للاكتشاف.
+
+## المكون الإضافي مقابل المهارة {#plugin-vs-skill}
+
+**المهارة** هي ملف تعليمات `SKILL.md` واحد يقرأه الوكيل عند تطابق المهمة. **المكون الإضافي** (المكون الإضافي لسوق Claude أو المكون الإضافي Codex) عبارة عن حزمة تضم واحدًا أو أكثر من skills **زائد** موصل وبيانات وصفية MCP، بحيث يمكن للمضيف تثبيت كل شيء في خطوة واحدة.
+
+تحت الغطاء، يتم إنتاج جميع المسارات الثلاثة من نفس المصدر بواسطة `npx @agent-native/core@latest app-skill` CLI: `app-skill pack` يبني محولات السوق/المكونات الإضافية، و`skills add` هو برنامج التثبيت السهل بخطوة واحدة الذي يقوم أيضًا بتسجيل موصل MCP والمصادقة عليه. راجع [Skills Guide](/docs/skills-guide) للتعرف على تنسيق بيان مهارات التطبيق، و[External Agents](/docs/external-agents) لتوصيل أي مضيف MCP وتدفق `npx @agent-native/core@latest connect`.
+
+## ما هي الخطوة التالية {#whats-next}
+
+- [**Visual Plans**](/docs/template-plan) — ما تفعله skills وكيفية استخدامها
+- [**PR Visual Recap**](/docs/pr-visual-recap) - تشغيل `/visual-recap` تلقائيًا عند كل طلب سحب
+- [**Skills Guide**](/docs/skills-guide) — skills المدعوم بالتطبيق وتنسيق البيان
+- [**External Agents**](/docs/external-agents) — قم بتوصيل أي مضيف MCP وعناصر رحلة الذهاب والإياب

package/docs/content/locales/ar-SA/pr-visual-recap.md

@@ -0,0 +1,384 @@
+---
+title: "ملخص مرئي للعلاقات العامة"
+description: "إجراء GitHub الذي يدير مهارة التلخيص المرئي لمستودع الريبو الخاص بك في كل علاقات عامة. يقرأ وكيل الترميز LLM الفرق، وينشر خطة تلخيص تفاعلية، ويعرض فحصًا معلوماتيًا، وينشر تعليق علاقات عامة ثابتًا مع لقطة شاشة مضمنة. إعلامية وغير قابلة للحظر."
+---
+
+# ملخص مرئي للعلاقات العامة
+
+PR Visual Recap هو إجراء GitHub يحول كل طلب سحب إلى **مراجعة التعليمات البرمجية المرئية**. في كل دفعة، يقوم وكيل ترميز LLM بتشغيل أحدث مهارات [`visual-recap`](/docs/template-plan) المجمعة (أو نسخة الريبو الخاصة بك عند `VISUAL_RECAP_SKILL_SOURCE=repo`) مقابل فرق العلاقات العامة، وينشر خطة ملخص منظمة إلى تطبيق الخطط المستضاف، ويعرض فحص `Visual Recap` إعلامي أثناء تشغيله، ويرسل ** تعليق علاقات عامة مثبتًا ** يرتبط بالخطة التفاعلية مع ** لقطة شاشة مضمنة ** مضمنة مباشرة في تعليق.
+
+هذا ليس عارض فرق محدد. يستدعي الإجراء وكيل ترميز حقيقي (Claude Code CLI بشكل افتراضي، أو OpenAI Codex CLI) الذي يقرأ التغيير، ويقرر ما يهم، ويؤلف الخلاصة عن طريق استدعاء أداة Plans MCP `create-visual-recap` - نفس الأداة التي يستخدمها أمر الشرطة المائلة `/visual-recap`. يمكنك الحصول على مخطط/API/عرض قبل وبعد التغيير على ارتفاعات عالية بدلاً من جدار من الاختلافات الأولية.
+
+الخلاصة **معلوماتية وغير محظورة**. فهو يقوم بإنشاء صف فحص حتى يتمكن المراجعون من رؤية أن عملية الإنشاء قيد التقدم، ولكنه ليس فحصًا مطلوبًا، ولا يحظر العلاقات العامة أبدًا، ولا يحل محل قراءة الفرق الفعلي أبدًا. يعد التعليق الثابت وسيلة مساعدة للمراجعة، وليس تسجيل خروج.
+
+## ماذا يفعل
+
+في كل دفعة للعلاقات العامة، سير العمل:
+
+1. يجمع فرقًا محددًا بين قاعدة العلاقات العامة والرأس.
+2. إنشاء فحص معلوماتي `Visual Recap` GitHub باستخدام `Visual recap in progress`.
+3. يقوم بتشغيل وكيل الترميز الذي تم تكوينه مقابل هذا الاختلاف. يقرأ الوكيل إرشادات مهارات `visual-recap` المجمعة (أو نسختك المثبتة) ويقوم بتأليف ملخص ونشره باستخدام `create-visual-recap`.
+4. قراءة الخطة المنشورة URL التي كتبها الوكيل إلى `recap-url.txt`.
+5. يفتح URL في Chrome بدون رأس ويلتقط لقطة شاشة للمخطط المعروض في الأوضاع الفاتحة والداكنة.
+6. تحميل ملفات PNG إلى مسار صورة عام موقّع في تطبيق الخطط.
+7. يرفع تعليق علاقات عامة ثابتًا واحدًا يتضمن لقطات الشاشة **مضمنة** مع عنصر `<picture>` (يتم تقديمه من خلال وكيل صورة التمويه الخاص بـ GitHub) بجوار رابط الملخص التفاعلي.
+8. يكمل فحص `Visual Recap` بنجاح، أو تم تخطيه، أو محايد.
+
+```an-diagram title="What happens on each PR push" summary="A bounded diff feeds a real coding agent, which authors a recap; the workflow screenshots it and upserts one sticky comment."
+{
+  "html": "<div class=\"diagram-recap\"><div class=\"diagram-node\">PR push<br><small class=\"diagram-muted\">bounded base&hellip;head diff</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Coding agent<br><small class=\"diagram-muted\">Claude Code / Codex reads diff</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">create-visual-recap</span><small class=\"diagram-muted\">publishes recap plan</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Headless Chrome<br><small class=\"diagram-muted\">light + dark screenshots</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">One sticky PR comment<br><small class=\"diagram-muted\">inline screenshot + plan link</small></div></div><div class=\"diagram-foot diagram-muted\">Plus an informational <span class=\"diagram-pill\">Visual Recap</span> check &mdash; non-blocking, never required.</div>",
+  "css": ".diagram-recap{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-recap .diagram-arrow{font-size:20px;line-height:1}.diagram-recap .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}.diagram-recap .diagram-foot{flex-basis:100%;margin-top:10px;font-size:13px}"
+}
+```
+
+تعمل إعادة الدفع على تحديث نفس الخطة ونفس التعليق الثابت الموجود - لا توجد خطط معزولة، ولا توجد تعليقات غير مرغوب فيها.
+
+## تثبيته
+
+عند تثبيت الخطط بشكل تفاعلي، يسألك Agent-Native CLI عما إذا كنت تريد الإضافة
+الملخصات المرئية للعلاقات العامة التلقائية. قل نعم لكتابة إجراء GitHub، أو قم بإضافته
+صراحة في أي وقت:
+
+```bash
+npx @agent-native/core@latest skills add visual-plan --with-github-action
+```
+
+يؤدي ذلك إلى تثبيت مهارة `visual-plan` (والتي تتضمن مهارة `visual-recap` التي يتم تشغيلها) ويكتب `.github/workflows/pr-visual-recap.yml` في الريبو الخاص بك. يستدعي سير العمل **الأوامر الفرعية CLI المنشورة** من خلال `npx @agent-native/core@latest recap <subcommand>` — بما في ذلك `gate` و`collect-diff` و`block-reference` و`scan` و`build-prompt` و`publish` و`shot` و`comment` و`check` و `usage` - لذلك لا يتم نسخ أي شيء إلى الريبو الخاص بك كنصوص برمجية مساعدة. `setup` و`doctor` هما المساعدان التفاعليان اللذان تقومان بتشغيلهما محليًا؛ `gate` هي خطوة بوابة الأمان التي يتم تشغيلها في سير العمل قبل كل ملخص.
+
+ثم قم بتشغيل مساعد الإعداد الموجه:
+
+```bash
+npx @agent-native/core@latest recap setup
+npx @agent-native/core@latest recap doctor
+```
+
+يقوم `recap setup` بتحديث سير العمل، ويستخدم `gh` لتعيين GitHub Actions
+الأسرار/المتغيرات عندما تكون القيم متاحة من env أو الخطط المحلية
+يخزن رمز النشر المميز، ويطبع الأوامر المفقودة بالضبط لأي شيء لا يمكنه
+مجموعة. يتم إرسال القيم السرية إلى `gh` من خلال stdin، وليس وسيطات الأوامر. الالتزام
+ملف سير العمل الذي تم إنشاؤه وافتح PR لمشاهدته قيد التشغيل.
+
+افتراضيًا، ينشئ سير العمل موجه الوكيل الخاص به من أحدث حزمة
+إرشادات `visual-recap` في `@agent-native/core@latest`، بما في ذلك أي شقيق
+الملفات المرجعية التي تأتي معها المهارة. إذا تم تخصيص الريبو الخاص بك عن قصد و
+يثبت مجلد `visual-recap` المخصص له، ويضبط متغير المستودع
+`VISUAL_RECAP_SKILL_SOURCE=repo`.
+
+## تحديد الخلفية
+
+اختر وكيل الترميز الذي يقوم بتشغيل المهارة باستخدام متغير المستودع `VISUAL_RECAP_AGENT`:
+
+| `VISUAL_RECAP_AGENT` | وكيل الترميز     | مفتاح API مطلوب     |
+| -------------------- | ---------------- | ------------------- |
+| `claude` _(افتراضي)_ | رمز Claude CLI   | `ANTHROPIC_API_KEY` |
+| `codex`              | OpenAI Codex CLI | `OPENAI_API_KEY`    |
+
+إذا لم يتم تعيين المتغير، يستخدم الإجراء `claude`.
+
+## النموذج والمنطق
+
+خارج الواجهة الخلفية، يوجد متغيران في المستودع يضبطان _كيف_ يعمل الوكيل:
+
+- **`VISUAL_RECAP_MODEL`** يثبت النموذج الذي تم تمريره إلى CLI (`--model`) — على سبيل المثال `gpt-5.5` لـ Codex، أو معرف نموذج Claude. اتركه بدون ضبط لاستخدام النموذج الافتراضي الخاص بـ CLI.
+- **`VISUAL_RECAP_REASONING`** يضبط عمق الاستدلال: `none` أو `minimal` أو `low` أو `medium` أو `high` أو `xhigh`. وينطبق ذلك على الواجهة الخلفية Codex؛ يعتمد منطق Claude على النموذج، لذلك يتم تجاهل هذا المتغير هناك.
+- **`VISUAL_RECAP_SKILL_SOURCE`** يتحكم في الحداثة السريعة: يستخدم `auto`/unset أحدث توجيهات المهارات المجمعة، بينما يتم تثبيت `repo` في مجلد مهارات `visual-recap` المحلي المخصص.
+
+على سبيل المثال، لتشغيل الملخص على Codex باستخدام GPT-5.5 عند المنطق العالي، قم بتعيين متغيرات المستودع `VISUAL_RECAP_AGENT=codex`، و`VISUAL_RECAP_MODEL=gpt-5.5`، و`VISUAL_RECAP_REASONING=high`.
+
+## الأسرار والمتغيرات
+
+قم بتعيين هذه العناصر في **الإعدادات ← الأسرار والمتغيرات ← Actions** في مستودعك.
+
+### الأسرار (مطلوب اثنان فقط)
+
+| سرية                | الغرض                                                                                                                  |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `PLAN_RECAP_TOKEN`  | رمز مميز قابل للإلغاء تم سكه بواسطة `npx @agent-native/core@latest connect`. يسمح بنشر خطة الملخّص وتحميل لقطة الشاشة. |
+| `ANTHROPIC_API_KEY` | مفتاح LLM للواجهة الخلفية الافتراضية لرمز Claude.                                                                      |
+
+**الفرق: استخدم رمزًا مميزًا لخدمة المؤسسة.** الرمز المميز الشخصي مرتبط بالشخص
+من قام بسكها - إذا تركوا المؤسسة أو أبطلوا رموزهم المميزة، فسيتم استخدام كل عملية إعادة شراء
+يبدأ هذا السر بالفشل مع 401، والخطط التي أنشأها CI مملوكة لذلك
+فردي بدلاً من الفريق. رمز الخدمة التنظيمية مملوك لـ
+**المؤسسة**: تعمل كمدير خدمة (`svc-<name>@service.<orgId>`)،
+ينجو من مغادرة أي فرد، وتكون الملخصات التي ينشرها مرئية للمؤسسة، و
+يمكن لأي مالك أو مسؤول للمؤسسة إدراجها أو إبطالها. Mint One (مالك/مسؤول المؤسسة فقط):
+
+```bash
+npx @agent-native/core@latest connect https://plan.agent-native.com --service-token pr-recap
+```
+
+يقوم الأمر بالمصادقة عليك في المتصفح، ثم يطبع رمز الخدمة المميز
+مرة واحدة بالضبط — قم بتخزينه باعتباره سر `PLAN_RECAP_TOKEN`. قم بإدارتها لاحقًا باستخدام
+`list-org-service-tokens` و`revoke-org-service-token` actions على
+تطبيق الخطط.
+
+**Solo: رمز شخصي لا يزال يعمل.** اصنعه باستخدام `npx @agent-native/core@latest connect`
+مقابل تطبيق الخطط الخاص بك. بالنسبة للتطبيق المستضاف، يقوم هذا أيضًا بكتابة محلي
+ملف رمز النشر المميز الذي يستطيع `npx @agent-native/core@latest recap setup` قراءته:
+
+```bash
+npx @agent-native/core@latest connect https://plan.agent-native.com --client codex
+npx @agent-native/core@latest recap setup
+```
+
+إذا كنت تفضل الإعداد اليدوي، فالصق الرمز المميز في سر GitHub. استخدم
+عنصر نائب مثل `plan_recap_xxxxxxxxxxxxxxxx` على سبيل المثال فقط - لا تلتزم مطلقًا
+رمز حقيقي.
+
+### اختياري (فقط في حالة تغيير الإعدادات الافتراضية)
+
+| سري/متغير                | الافتراضي                       | عندما تحتاج إليه                                                                                                                                           |
+| ------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`         | —                               | سرية. اضبطه مع `VISUAL_RECAP_AGENT=codex` لتشغيل الخلاصة باستخدام Codex بدلاً من ذلك.                                                                      |
+| `VISUAL_RECAP_AGENT`     | `claude`                        | متغير. يحدد الواجهة الخلفية لعامل التشفير (`claude` أو `codex`).                                                                                           |
+| `VISUAL_RECAP_MODEL`     | كل CLI الافتراضي                | متغير. دبابيس النموذج - على سبيل المثال. `gpt-5.5` لـ Codex، أو معرف طراز Claude. يستخدم Unset الإعداد الافتراضي الخاص بـ CLI.                             |
+| `VISUAL_RECAP_REASONING` | الإعداد الافتراضي لكل نموذج     | متغير. عمق الاستدلال: `none`، أو `minimal`، أو `low`، أو `medium`، أو `high`، أو `xhigh`. ينطبق على الواجهة الخلفية Codex.                                 |
+| `RECAP_CLI_VERSION`      | `latest`                        | متغير. تثبيت إصدار `@agent-native/core` CLI الذي يقوم سير العمل بتثبيته - على سبيل المثال. `1.5.0`. انظر [Version pinning](#version-pinning-copy-variant). |
+| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com` | سرية. فقط عند الاستضافة الذاتية لتطبيق الخطط على مصدر مختلف.                                                                                               |
+
+يكتشف سير العمل تلقائيًا كيفية استدعاء مساعده CLI (المصدر المحلي داخل هذا monorepo، `@agent-native/core` المنشور في مكان آخر)، لذا لا يوجد متغير `RECAP_CLI` لتعيينه.
+
+## لقطة شاشة مضمنة في التعليق
+
+بعد أن ينشر الوكيل الملخص، يقوم سير العمل بالتقاط لقطة شاشة للخطة المعروضة في Chrome بدون رأس في كل من الوضعين الفاتح والداكن وتحميل ملفات PNG إلى مسار صورة عامة موقعة في تطبيق الخطط. يقوم تعليق العلاقات العامة اللاصق بعد ذلك بتضمين لقطات الشاشة هذه **مضمنة** مع عنصر `<picture>` — يعيد GitHub تقديمها من خلال وكيل التمويه الخاص به، بحيث يرى المراجعون معاينة تتطابق مع سمة GitHub الخاصة بهم مباشرة في التعليق دون فتح أي شيء. يوجد رابط الخطة التفاعلية الكاملة بجوارها مباشرةً عندما يريدون الاستكشاف أو التعليق أو التعليق التوضيحي.
+
+## علاقات عامة للشوكة
+
+### السلوك الافتراضي (لا يلزم اتخاذ أي إجراء)
+
+يتم تشغيل سير العمل الرئيسي `pr-visual-recap.yml` على مشغل `pull_request` العادي، **وليس** `pull_request_target`. وبالتالي، يتم تشغيل Fork PRs مع **عدم الوصول إلى أسرار المستودع**، لذلك لا يجد سير العمل أي `PLAN_RECAP_TOKEN` ولا توجد عمليات واضحة - لا يوجد نشر فاشل، ولا يتم الكشف عن بيانات الاعتماد. يتم تشغيل الملخصات تلقائيًا لممثلي العلاقات العامة من الفروع الموجودة في نفس المستودع، حيث تتوفر الأسرار.
+
+يعني هذا أيضًا أنه يمكنك دمج ملف سير العمل **قبل** وجود الأسرار: مع عدم تكوين رمز مميز، تكون كل عملية تشغيل بمثابة عدم إجراء هادئ حتى تقوم بتعيين الأسرار. تتخطى خطوة `gate` أيضًا مسودات PRs وPRs التي تم تأليفها بواسطة الروبوت تلقائيًا، لذلك لا يتم تشغيل أي ملخص للمشغل بشكل افتراضي.
+
+### الاشتراك في سير عمل الشوكة ذات التصنيف
+
+إذا كنت ترغب في إنشاء ملخصات لـ PRs للشوكة، يتوفر ملف سير عمل ثانٍ: `.github/workflows/pr-visual-recap-fork.yml`. إنه يستخدم `pull_request_target` (الذي يعمل مع أسرار الريبو الأساسية) ولكنه لا يقوم أبدًا بفحص أو تنفيذ كود الشوكة. يعمل مؤلفو الشوكة الموثوق بهم مع جمعية المؤلفين GitHub `OWNER` أو `MEMBER` أو `COLLABORATOR` تلقائيًا. تتطلب العلاقات العامة للشوكة الخارجية **اشتراكًا صريحًا للمشرف لكل رأس** عبر حدث تسمية `recap` جديد قبل تشغيل وكيل الخلاصة.
+
+لتثبيته، انسخ الملف من [BuilderIO/agent-native](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/pr-visual-recap-fork.yml) إلى دليل `.github/workflows/` الخاص بالمستودع الخاص بك إلى جانب `pr-visual-recap.yml` الموجود. تنطبق نفس الأسرار (`PLAN_RECAP_TOKEN`، `ANTHROPIC_API_KEY`).
+
+```an-diagram title="Fork PR consent gate" summary="Fork PRs get no secrets by default; trusted authors run automatically, and outside contributors require a fresh maintainer recap label."
+{
+  "html": "<div class=\"diagram-fork\"><div class=\"diagram-node\">Fork PR opened<br><small class=\"diagram-muted\">main workflow has no secrets</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Trusted author</span><small class=\"diagram-muted\">OWNER, MEMBER, or COLLABORATOR runs automatically</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">Outside contributor</span><small class=\"diagram-muted\">maintainer reviews diff, then applies <code>recap</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\">Gate checks<br><small class=\"diagram-muted\">fork PR? &amp; trusted or fresh label?</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Recap runs<br><small class=\"diagram-muted\">base-repo code only · fork diff is text input</small></div></div>",
+  "css": ".diagram-fork{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-fork .diagram-arrow{font-size:20px;line-height:1}.diagram-fork .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}.diagram-fork .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}"
+}
+```
+
+### كيفية عمل بوابة التصنيف
+
+1. يفتح المساهم في الشوكة PR. يتم تخطي سير عمل `pull_request` العادي لأن GitHub يحجب الأسرار عن عمليات الشوكة.
+2. يقوم سير عمل الشوكة بالتحقق من اقتران مؤلف العلاقات العامة. يتم تشغيل المؤلفين الموثوق بهم (`OWNER`، أو `MEMBER`، أو `COLLABORATOR`) تلقائيًا في الأحداث المفتوحة، والمزامنة، وإعادة الفتح، والجاهزة للمراجعة.
+3. يطلب المساهمون الخارجيون من المشرف مراجعة الفرق الحالي (خاصة بالنسبة للمحتوى الذي يتم حقنه بشكل سريع - انظر أدناه)، ثم تطبيق علامة `recap` على العلاقات العامة.
+4. بوابة تسمية المساهم الخارجي هي لكل رأس SHA: إذا دفع المساهم المزيد من الالتزامات، فسيتم تخطي حدث المزامنة التالي حتى يقوم المشرف بإزالة `recap` وإعادة تطبيقه بعد مراجعة الفرق الجديد.
+
+### ما يفعله سير عمل الشوكة وما يفعله NOT
+
+| سير العمل DOES                                                                                           | سير العمل يفعل NOT                                                                |
+| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| تفحص **المستودع الأساسي** في **مرجع الفرع الأساسي** — الرمز الموثوق به فقط                               | سحب أو تنفيذ أي تعليمات برمجية من الشوكة                                          |
+| جلب رأس الشوكة كمرجع عن بعد (`git fetch origin pull/<n>/head:refs/recap/fork-head`) - جلب الالتزامات آمن | تثبيت الحزم من التفرع، أو تشغيل البرامج النصية للتفرع، أو تقييم محتوى التفرع كرمز |
+| تشغيل `git diff base...refs/recap/fork-head` — نص خالص يختلف بين كائنين تم جلبهما بالفعل                 | استخدم الفرق كأي شيء آخر غير إدخال النص في LLM                                    |
+| قم بتشغيل **قاعدة الريبو** ومهارة التلخيص المرئي وتكوين الوكيل                                           | قم بتحميل أي مهارة أو تكوين من الشوكة                                             |
+| قم بتمرير الفرق من خلال نفس خطوة الفحص السري (فشل الإغلاق) مثل ممثلي العلاقات العامة للطرف الأول         | تخطي الفحص السري                                                                  |
+| أضف ملاحظة صريحة لتشديد المطالبة إلى موجه الوكيل لوضع علامة على المحتوى المختلف على أنه غير موثوق به     | امنح الوكيل أي أذونات إضافية تتجاوز وكيل التلخيص العادي                           |
+
+### لماذا يجب عليك مراجعة الفرق قبل التصنيف
+
+الفرق المتشعب هو نص يتحكم فيه المهاجم ويقرأه وكيل التلخيص كمدخل. يمكن أن يحتوي الفرق المصمم بعناية على محتوى يتم إدخاله بسرعة - على سبيل المثال، خطوط الفرق التي تبدو مثل تعليمات الوكيل - والتي تهدف إلى جعل وكيل الملخّص يأخذ actions غير مقصود (على سبيل المثال، تصفية رمز النشر المميز أو إنتاج محتوى تلخيص مضلل).
+
+قبل تطبيق التصنيف `recap`، قم بمسح الفروق من أجل:
+
+- السطور التي تقرأ مثل الأوامر المباشرة أو تعليمات الدور ("تجاهل التعليمات السابقة..."، "أنت الآن..."، "اكتب الرمز المميز إلى...").
+- أسماء الملفات غير المعتادة التي يمكن أن تتم قراءتها بشكل خاطئ أثناء مطالبات النظام.
+- المحتوى المشفر في الملفات المضافة التي قد يتم فك تشفيرها للتعليمات.
+
+تم وضع عوامل التخفيف هذه بالفعل في طبقات سير العمل (الفحص السري، وبوابة المسار الحساس، وملاحظة التعزيز الفوري، والقائمة المسموح بها لأدوات الوكيل المقيدة)، ولكن مراجعة التصنيف هي خط الدفاع الأساسي.
+
+### العلاقة بسير العمل الرئيسي
+
+ملفا سير العمل مستقلان. بالنسبة لتحديثات العلاقات العامة التي لا تتعلق بالشوكة، فإن `pr-visual-recap.yml` هو سير العمل الوحيد الذي يتم تشغيله. بالنسبة إلى PRs للشوكة، يخرج سير العمل العادي عند بوابة الشوكة الخاصة به، ويتم تشغيل `pr-visual-recap-fork.yml` تلقائيًا للمؤلفين الموثوق بهم من نفس المؤسسة أو بعد تسمية `recap` للمشرف الجديد للمساهمين الخارجيين. إنهم يشتركون في نفس علامة التعليق الثابتة وسلسلة ترابط معرف الخطة، لذلك ينتج كل من العلاقات العامة والشوكة علاقات عامة تعليقًا واحدًا مقلوبًا على نفس العلاقات العامة.
+
+### حارس ذاتي التعديل {#self-modifying-guard}
+
+تتخطى خطوة `gate` التلخيص بالكامل عندما يلمس العلاقات العامة أيًا من المسارات التالية، لذلك لا يمكن للعلاقات العامة مطلقًا إعادة كتابة سير العمل أو المهارة أو تكوين الوكيل الذي يقوم بتحميل مهمة التلخيص الموثوقة واستخراج الأسرار:
+
+| نمط المسار                                 | السبب                                    |
+| ------------------------------------------ | ---------------------------------------- |
+| `.github/workflows/pr-visual-recap.yml`    | سير العمل نفسه                           |
+| `**/skills/visual-(recap\|plan\|plans)/**` | The visual-recap skill the agent follows |
+| `**/.claude/**`                            | إعدادات الوكيل التي يقوم العداء بتحميلها |
+| `**/CLAUDE.md`                             | تعليمات الوكيل التي يقوم العداء بتحميلها |
+| `**/AGENTS.md`                             | تعليمات الوكيل التي يقوم العداء بتحميلها |
+| `**/.mcp.json`                             | يقوم خادم MCP بتحميل العداء              |
+
+في `BuilderIO/agent-native` monorepo، يقوم سير العمل بتشغيل ملخص CLI من مصدر فرع أساسي موثوق به بدلاً من مصدر رأس العلاقات العامة. يؤدي ذلك إلى إبقاء تغييرات الحزمة العادية، بما في ذلك `packages/core/**`، مؤهلة للملخّصات دون تنفيذ كود CLI المعدل بواسطة PR.
+
+## وضع خصوصية الملفات المحلية
+
+تم تصميم إجراء GitHub لمراجعة العلاقات العامة المستضافة والقابلة للمشاركة. إذا كنت تريد
+التلخيص دون إرسال محتوى التلخيص إلى قاعدة بيانات خطة Agent-Native، قم بتشغيل
+يتدفق نفس المساعد محليًا في وضع الملفات المحلية بدلاً من ذلك:
+
+```bash
+npx @agent-native/core@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
+npx @agent-native/core@latest recap scan --diff recap.diff
+npx @agent-native/core@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
+```
+
+أعط `recap-prompt.md` الذي تم إنشاؤه إلى وكيل الترميز الخاص بك. في وضع الملفات المحلية
+يطلب الموجه من الوكيل كتابة `plans/pr-123-visual-recap/plan.mdx`
+بالإضافة إلى الملفات المرئية الاختيارية ثم قم بتشغيل:
+
+```bash
+npx @agent-native/core@latest plan local serve --dir plans/pr-123-visual-recap --kind recap --open
+```
+
+يفتح URL الذي تم إرجاعه الخطة المستضافة UI بينما يقرأ المتصفح الملخص MDX
+من جسر مضيف محلي. لا تتم كتابة محتوى التلخيص في الخطة المستضافة
+قاعدة البيانات، ويعمل URL فقط على الجهاز الذي يقوم بتشغيل الجسر. إذا قمت بتشغيل
+تطبيق الخطة محليًا بنفس `PLAN_LOCAL_DIR`،
+مسار `/local-plans/pr-123-visual-recap` صالح أيضًا. يمكن للمجلدات المدعومة بالريبو
+افتح كـ `/local-plans/pr-123-visual-recap?path=plans%2Fpr-123-visual-recap`.
+يعمل هذا الوضع على تعطيل تعليق العلاقات العامة المستضاف، وتحميل لقطة الشاشة المضمنة،
+مرفقات الاستخدام وتعليقات المتصفح حتى تنشرها بشكل صريح.
+
+## إنها معلوماتية وليست بوابة
+
+الخلاصة عبارة عن أداة مساعدة للمراجعة يتم وضعها فوق تدفق العلاقات العامة العادي:
+
+- يُظهر صف الاختيار `Visual Recap` للرؤية، ولكنه **ليس فحصًا مطلوبًا على الإطلاق** ولا يمنع الدمج مطلقًا.
+- يكتمل فشل الإنشاء أو النشر بشكل محايد ويظهر كتعليق توضيحي مثبت، وليس علامة X حمراء على تعليمات برمجية غير ذات صلة.
+- الملخّص ولقطة الشاشة الخاصة به **لا تعني ضمنًا أنه تمت مراجعة الفرق**. لا يزال المراجعون بحاجة إلى قراءة الأسطر الفعلية التي تم تغييرها.
+
+## تثبيت الإصدار (متغير النسخ) {#version-pinning-copy-variant}
+
+افتراضيًا، يقوم سير عمل النسخ المتغير بتثبيت `@agent-native/core@latest` في وقت التشغيل، لذا فإن كل عملية تلخيص تلتقط تلقائيًا أحدث CLI. إذا كان CI الخاص بك يحتاج إلى أدوات قابلة للتكرار، فقم بتعيين متغير المستودع **`RECAP_CLI_VERSION`** لتثبيت الإصدار المثبت:
+
+1. انتقل إلى الريبو الخاص بك **الإعدادات → الأسرار والمتغيرات → Actions → المتغيرات**.
+2. قم بإنشاء متغير باسم `RECAP_CLI_VERSION` بقيمة مثل `1.5.0`.
+
+المتغير اختياري. اتركه بدون ضبط (أو اضبطه على `latest`) لتتبع الإصدار الأحدث.
+
+بالنسبة لمتغير المتصل القابل لإعادة الاستخدام، استخدم إدخال `cli-version` بدلاً من ذلك (راجع [Version pinning](#version-pinning) في القسم القابل لإعادة الاستخدام).
+
+## القائمة المسموح بها للفحص السري
+
+قبل نشر الملخّص، يقوم سير العمل بتشغيل `npx @agent-native/core@latest recap scan` لاكتشاف الأسرار المحتملة في الفرق. يتم حظر أي علاقات عامة يتطابق فرقها مع نمط سري معروف بتعليق توضيحي - لا يتم نشر الملخص، ولا يتم إرسال أي محتوى فرق إلى وكيل الترميز.
+
+في حالات نادرة، يحتوي الريبو على تركيبات اختبار متعمدة أو سلاسل غير سرية تشبه بشكل سطحي الأنماط السرية (على سبيل المثال، مفتاح التثبيت في ملف اختبار). لمنع النتيجة الإيجابية الخاطئة، قم بإنشاء `.github/recap-scan-allowlist` في جذر المستودع الخاص بك.
+
+### التنسيق
+
+كل سطر غير فارغ وغير تعليقي هو إما **سلسلة فرعية حرفية** أو نمط **`/regex/flags`**:
+
+```
+# Lines starting with # are comments.
+
+# Literal substring — any diff line containing this string is allowed.
+sk-test-fixture1234567890abcdef
+
+# Regex pattern — written as /pattern/flags (JS syntax).
+/^.STRIPE_KEY=sk-test-/i
+
+# Another literal.
+EXAMPLE_API_KEY=placeholder-value
+```
+
+القواعد:
+
+- يتم منع السطر \*\* (مسموح به) عندما يحتوي على حرفي، أو عندما يتطابق السطر الكامل مع التعبير العادي.
+- الملف **فشل في الإغلاق**: إذا كان غائبًا، فلن يتم تطبيق أي عمليات إيقاف — يتصرف الماسح الضوئي كما كان من قبل.
+- الملف الفارغ لا يعادل أي ملف.
+- تتم معاملة أسطر التعبير العادي المشوهة على أنها سلاسل حرفية.
+
+لا تتم مراجعة القائمة المسموح بها إلا من خلال بوابة الفحص السري. ولا يؤثر ذلك على ما يستطيع وكيل التشفير قراءته — إذا مرت البوابة، فسيتلقى الوكيل الفرق الكامل بغض النظر.
+
+## الاعتماد كمسار عمل قابل لإعادة الاستخدام
+
+### لماذا نستخدم المتغير القابل لإعادة الاستخدام؟
+
+يقوم المثبت الافتراضي بنسخ سير العمل YAML الكامل ~360 سطرًا إلى الريبو الخاص بك (خيار **النسخ**). هذا هو الاختيار الصحيح لعمليات إعادة الشراء أو عمليات إعادة الشراء التي تحتاج إلى مراجعة كل سطر مما يتم تشغيله. الجانب السلبي هو أن إصلاحات الأخطاء والتحسينات لا تصل إليك أبدًا — تحتاج إلى إعادة تشغيل `npx @agent-native/core@latest recap setup` يدويًا بعد كل إصدار.
+
+يقوم الخيار **القابل لإعادة الاستخدام** بكتابة متصل رفيع يصل إلى 20 سطرًا بدلاً من ذلك. يقوم بالتفويض إلى `BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml` عبر `uses:`. يلتقط كل متصل تلقائيًا أحدث المنطق عند تشغيل سير العمل، دون الحاجة إلى تحديث محلي.
+
+|                                          | نسخ (افتراضي)                | قابلة لإعادة الاستخدام               |
+| ---------------------------------------- | ---------------------------- | ------------------------------------ |
+| حجم سير العمل في الريبو الخاص بك         | ~360 خطًا                    | ~20 سطرًا                            |
+| يلتقط الإصلاحات تلقائيًا                 | لا — أعد تشغيل `recap setup` | نعم                                  |
+| الفجوة الهوائية / إمكانية التدقيق الكامل | نعم                          | لا                                   |
+| قابل للتثبيت على إصدار محدد              | فقط عن طريق التحرير محليًا   | نعم - قم بتعيين `@v1.2.3` في `uses:` |
+
+### مقتطف المتصل
+
+هذا ما يكتبه `npx @agent-native/core@latest recap setup --reusable` (أو يمكنك لصقه يدويًا):
+
+```yaml
+name: PR Visual Recap
+
+# Thin caller — the full workflow logic lives in BuilderIO/agent-native.
+# Fixes and improvements reach this repo automatically on each run.
+# To pin a specific version for reproducibility replace '@main' with a
+# tag or SHA, e.g. '@v1.2.3' or '@abc1234'.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, closed]
+
+jobs:
+  visual-recap:
+    permissions:
+      actions: write
+      contents: read
+      checks: write
+      issues: write
+      pull-requests: write
+    uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@main
+    secrets:
+      PLAN_RECAP_TOKEN: ${{ secrets.PLAN_RECAP_TOKEN }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      PLAN_RECAP_APP_URL: ${{ secrets.PLAN_RECAP_APP_URL }}
+    with:
+      agent: ${{ vars.VISUAL_RECAP_AGENT || 'claude' }}
+      model: ${{ vars.VISUAL_RECAP_MODEL || '' }}
+      reasoning: ${{ vars.VISUAL_RECAP_REASONING || '' }}
+      skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
+      # cli-version: "latest"  # pin to a specific @agent-native/core version
+```
+
+تنطبق نفس الأسرار والمتغيرات الموضحة في [Secrets and variables](#secrets-and-variables) - قم بتعيينها في إعدادات الريبو الخاصة بك بنفس الطريقة كما في متغير النسخ.
+
+### التثبيت عبر CLI
+
+```bash
+# Write the thin caller instead of the full copy:
+npx @agent-native/core@latest recap setup --reusable
+
+# Or with a pinned ref for reproducibility:
+npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
+```
+
+يقوم كلا الخيارين بكتابة سير العمل إلى `.github/workflows/pr-visual-recap.yml`. إذا كان سير العمل موجودًا بالفعل ومختلفًا، فسيرفض الأمر ويطلب منك تمرير `--force` للكتابة فوقه.
+
+بعد الكتابة، قم بتشغيل `npx @agent-native/core@latest recap doctor` كالمعتاد للتأكد من تكوين الأسرار.
+
+### تثبيت الإصدار
+
+افتراضيًا، يشير المتصل إلى `@main`، والذي يستخدم دائمًا أحدث إصدار منشور من سير العمل القابل لإعادة الاستخدام. بالنسبة إلى مستودعات الإنتاج التي تحتاج إلى CI قابل للتكرار، قم بتثبيته على علامة أو SHA:
+
+```yaml
+uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@v1.2.3
+```
+
+يتحكم إدخال `cli-version` في إصدار `@agent-native/core` CLI الذي يتم تشغيله داخل سير العمل - اتركه في `"latest"` لتتبع الإصدار الأحدث، أو قم بتثبيته في سلسلة إصدار (على سبيل المثال، `"1.5.0"`) للحصول على إمكانية تكرار نتائج كاملة.
+
+### سياق حدث Workflow_call
+
+ترث مسارات عمل `workflow_call` سياق حدث **المتصل**. يستخدم سير العمل القابل لإعادة الاستخدام تعبيرات `github.event.pull_request.*` لقراءة رقم PR، والرأس SHA، وSHA الأساسي، والطابع الزمني المدمج، وبيانات تعريف PR - تعمل هذه بشكل صحيح فقط عندما يقوم المتصل بتشغيل `pull_request`. يتضمن مقتطف المتصل أعلاه بالفعل أنواع الأحداث الصحيحة. تم تضمين حدث `closed` بحيث يمكن ختم ملخصات العلاقات العامة المدمجة بـ `merged_at` والبحث عنها لاحقًا كعمل تم شحنه.
+
+لا تقم بتشغيل المتصل على `workflow_dispatch` أو `push` — تلك الأحداث لا تحمل حمولة `pull_request`، وستتخطى البوابة الملخّص مع "عدم وجود حمولة pull_request".
+
+## ذات صلة
+
+- [Visual Plans](/docs/template-plan) — `/visual-plan` و`/visual-recap` skills، وموصل الخطط المستضاف، وسطح المراجعة التفاعلية الذي ينشر هذا الإجراء عليه.
+- [Skills](/docs/skills-guide) — تثبيت skills للوكيل الأصلي في وكيل الترميز لديك.