@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ar-SA/workspace.md

@@ -0,0 +1,323 @@
+---
+title: "مساحة العمل"
+description: "تخصيص Claude على مستوى التعليمات البرمجية لكل مستخدم — skills، الذاكرة، التعليمات، الوكلاء المخصصون، المهام المجدولة، خوادم MCP — مدعومة بـ SQL، وليس نظام ملفات."
+---
+
+# مساحة العمل
+
+> **ما هو مستند مساحة العمل؟** تغطي هذه الصفحة **طبقة التخصيص** — ما هي مساحة العمل. للحصول على شكل النشر (مونوريبو واحد، العديد من التطبيقات) راجع [Multi-App Workspaces](/docs/multi-app-workspace)؛ بالنسبة للحوكمة (من يراجع ويوافق ويمتلك ماذا) راجع [Workspace Governance](/docs/workspace-management).
+
+يأتي كل تطبيق وكيل أصلي مزودًا بـ **مساحة عمل**: طبقة التخصيص التي تجعل الوكيل ملكًا لك. فهو يحتوي على تعليمات الفريق (`AGENTS.md`)، والتعلم المشترك (`LEARNINGS.md`)، والذاكرة المنظمة الشخصية (`memory/MEMORY.md`)، وskills الذي يسحبه الوكيل عند الطلب، والوكلاء الفرعيين المخصصين، والمهام المجدولة، وخوادم MCP المتصلة — كل ما تتوقعه من إعداد Claude Code / Codex.
+
+التطور: ** إنها صفوف SQL، وليست ملفات نظام الملفات. ** يحصل كل مستخدم على مساحة العمل الخاصة به المخزنة في قاعدة البيانات. لا يوجد صندوق تطوير لتدويره، ولا توجد حاوية لكل مستخدم، ولا توجد ملفات لتحميلها. يمكن أن توفر SaaS متعددة المستأجرين لكل مستخدم وكيلًا قابلاً للتخصيص بالكامل مجانًا بشكل أساسي، لأن كل ذلك عبارة عن صفوف - الذاكرة الشخصية، وخوادم MCP الشخصية، وskills الشخصية، والوكلاء الفرعيين الشخصيين - وتستضيف قاعدة التعليمات البرمجية المشتركة كل منهم في وقت واحد.
+
+```an-diagram title="A Claude-Code workspace, but stored in SQL" summary="The same customization layer — instructions, skills, memory, agents, jobs, MCP — except every file is a row in a shared multi-tenant database."
+{
+  "html": "<div class=\"ws-map\"><div class=\"diagram-card cc\"><span class=\"diagram-pill warn\">Claude Code / Codex</span><small class=\"diagram-muted\">~/.claude/ on a local disk</small><div class=\"ws-files\"><span class=\"diagram-box\">CLAUDE.md</span><span class=\"diagram-box\">skills/</span><span class=\"diagram-box\">memory</span><span class=\"diagram-box\">mcp.json</span></div><small class=\"diagram-muted\">one codebase per developer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card an\"><span class=\"diagram-pill accent\">Agent-native workspace</span><small class=\"diagram-muted\">rows in one SQL database</small><div class=\"ws-rows\"><span class=\"diagram-pill\">AGENTS.md</span><span class=\"diagram-pill\">skills/&hellip;</span><span class=\"diagram-pill\">memory/&hellip;</span><span class=\"diagram-pill\">mcp-servers/&hellip;</span></div><small class=\"diagram-muted\">one codebase, many users, scoped <code>u:&lt;email&gt;:&hellip;</code></small></div></div>",
+  "css": ".ws-map{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ws-map .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:220px}.ws-map .ws-files,.ws-map .ws-rows{display:flex;flex-wrap:wrap;gap:6px;margin:4px 0}.ws-map .diagram-arrow{font-size:24px}"
+}
+```
+
+| رمز Claude / Codex                     | مساحة عمل الوكيل الأصلية                         |
+| -------------------------------------- | ------------------------------------------------ |
+| الملفات الموجودة على القرص المحلي لديك | الصفوف في قاعدة بيانات SQL المشتركة              |
+| قاعدة تعليمات برمجية واحدة لكل مطور    | قاعدة تعليمات برمجية واحدة والعديد من المستخدمين |
+| يحتاج إلى صندوق تطوير أو حاوية         | يتم تشغيله على أي مضيف بدون خادم/حافة            |
+| التخصيص في `~/.claude/`                | التخصيص لكل مستخدم، `u:<email>:…` محدد النطاق    |
+| `CLAUDE.md` / skills لكل مشروع         | `AGENTS.md` لكل تطبيق + موارد ذاكرة مساحة العمل  |
+| تكوين MCP في ملف JSON                  | تكوين MCP في JSON _أو_ الإعدادات UI، لكل نطاق    |
+
+نفس الإمكانيات. اقتصاد مختلف. راجع [Templates](/docs/cloneable-saas) لمعرفة سبب أهمية ذلك بالنسبة إلى SaaS.
+
+## نظرة عامة {#overview}
+
+تحتوي الموارد على ثلاثة نطاقات لوقت التشغيل:
+
+- **شخصي** — مخصص لمستخدم واحد (بريده الإلكتروني). مناسب للتفضيلات والملاحظات والسياق لكل مستخدم.
+- **مشتركة / مؤسسة** — مرئية لجميع المستخدمين في التطبيق أو المؤسسة. مناسب لتعليمات التطبيق/الفريق، وskills، والتكوين المشترك.
+- **مساحة العمل** — الإعدادات الافتراضية العامة الموروثة المُدارة من Dispatch Resources. جيد لحقائق الشركة، وتحديد المواقع، وإرشادات العلامة التجارية، وحواجز الحماية العالمية، وskills على مستوى مساحة العمل، وخوادم MCP المشتركة. تقرأ التطبيقات هذه في وقت التشغيل؛ ولا يتم نسخها في كل تطبيق.
+
+تعرض لوحة Workspace داخل التطبيق النطاقات الثلاثة جميعها. الموارد الشخصية والمشتركة/المؤسسة قابلة للتحرير هناك. تكون موارد نطاق مساحة العمل للقراءة فقط في لوحات التطبيق ويتم تحريرها مركزيًا من Dispatch، بحيث يرى كل تطبيق نفس الملفات الأساسية بدون خطوة مزامنة.
+
+المسارات الأساسية التي تتحكم في كيفية استخدام الوكيل لكل مورد:
+
+| مورد وقت التشغيل              | المسار                                  | كيفية استخدام الوكلاء لها                          |
+| ----------------------------- | --------------------------------------- | -------------------------------------------------- |
+| تعليمات الدرابزين             | `AGENTS.md` أو `instructions/<slug>.md` | تم تحميله في كل دورة في كل تطبيق يستقبله           |
+| skills العالمية               | `skills/<slug>/SKILL.md`                | مُدرج كمساحة عمل skills ويمكن قراءته عند الطلب     |
+| موارد العلامة التجارية/الشركة | `context/<slug>.md`                     | تم فهرسة كل منعطف، اقرأ عندما يكون ذلك مناسبًا     |
+| ملفات تعريف الوكيل المخصصة    | `agents/<slug>.md`                      | متاح كملفات تعريف وكيل محلي قابلة لإعادة الاستخدام |
+| خوادم HTTP MCP المشتركة       | `mcp-servers/<slug>.json`               | تم التحميل في سجل أداة MCP للتطبيقات الممنوحة      |
+
+تنطبق هذه المسارات عبر النطاقات الثلاثة كلها - مساحة العمل، والمؤسسة/التطبيق، والشخصية. يفوز النطاق الأحدث عند وجود نفس المسار على مستويات متعددة.
+
+```an-diagram title="Three scopes, one effective file" summary="The runtime resolves the same path across workspace, app, and personal scopes on read — the most specific scope wins."
+{
+  "html": "<div class=\"ws-stack\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Workspace</span><small class=\"diagram-muted\">company-wide defaults from Dispatch</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Organization / app</span><small class=\"diagram-muted\">team override for one app</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Personal</span><small class=\"diagram-muted\">per-user override &mdash; wins</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Effective <code>context/brand.md</code></div></div>",
+  "css": ".ws-stack{display:flex;flex-direction:column;align-items:flex-start;gap:8px}.ws-stack .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px;min-width:280px}.ws-stack .diagram-arrow{font-size:20px;align-self:center}.ws-stack code{font-size:.85em}.ws-stack .diagram-box{align-self:center;margin-top:4px}"
+}
+```
+
+## الخطوات الأولى: جولة تفصيلية مدتها دقيقة واحدة {#getting-started}
+
+قم بتغيير سلوك الوكيل خلال 60 ثانية.
+
+1. افتح علامة التبويب **مساحة العمل** → **مشتركة** → `AGENTS.md` (قم بإنشائها باستخدام `+` → **ملف** إذا كان مفقودًا).
+2. أضف قاعدة واحدة، على سبيل المثال:
+
+   ```تخفيض السعر
+   ## النغمة
+
+   كن موجزًا. ابدأ بالإجابة.
+   ```
+
+3. احفظ، وانتقل إلى **الدردشة**، واسأل عن أي شيء — يتبع الوكيل القاعدة الجديدة على الفور.
+
+```an-callout
+{ "tone": "info", "body": "No restart, no redeploy. `AGENTS.md` is read at the start of every turn, so an edit you save now changes the agent's behavior on the very next message." }
+```
+
+**الخطوات التالية، عندما تريدها:**
+
+- **Skills** (`+` → **Skill**) — ملفات إرشادية مركزة يتم استدعاؤها في الدردشة مع `/skill-name`.
+- **الوكلاء** (`+` → **الوكيل**) — شخصيات الوكيل الفرعي القابلة لإعادة الاستخدام التي تم استدعاؤها باستخدام `@agent-name`.
+- **المهام المجدولة** (`+` → **المهمة المجدولة**) — المطالبات التي يتم تشغيلها على cron. راجع [Recurring Jobs](/docs/recurring-jobs) لمعرفة الجداول الزمنية والمشغلات.
+- **الذاكرة** — تحافظ `LEARNINGS.md` المشتركة و`memory/MEMORY.md` الشخصية على السياق الدائم المتاح عبر المحادثات.
+
+## الموارد العالمية والمسارات الأساسية {#global-resources}
+
+تتم إدارة موارد نطاق مساحة العمل من صفحة **الموارد** الخاصة بـ Dispatch ويتم توريثها بواسطة التطبيقات في وقت التشغيل - لا توجد خطوة نسخ أو مزامنة. يدعم Dispatch نطاقين للمنح:
+
+- **جميع التطبيقات** — الموارد العامة التي يرثها كل تطبيق في مساحة العمل. يجب أن تكون معظم سياقات الشركات والعلامات التجارية والشخصيات وتحديد المواقع والرسائل وسياق الحماية **جميع التطبيقات**.
+- **التطبيقات المحددة** — الموارد الممنوحة لتطبيقات محددة لسياق أو أدوات خاصة بالتطبيق. استخدم هذه الأشياء باعتدال.
+
+يحدد المسار كيفية استخدام الوكيل لمورد ما (راجع الجدول في [Overview](#overview) أعلاه). هذا هو المكان المناسب للأشخاص الأساسيين، أو تحديد المواقع، أو المراسلة، أو حقائق الشركة، أو إرشادات العلامة التجارية، أو سياسات الدعم، أو أدوات skills المشتركة، أو أدوات HTTP MCP المشتركة التي يجب أن تستفيد منها العديد من التطبيقات.
+
+حزمة بداية مفيدة لمساحة عمل جديدة:
+
+```text
+context/company.md              # what the company does, ICP, products, links
+context/brand.md                # voice, visual identity, spelling, forbidden usage
+context/messaging.md            # positioning, value props, proof points, objections
+instructions/guardrails.md      # compliance, escalation, and approval rules
+skills/company-voice/SKILL.md   # on-demand guidance for customer-facing writing
+agents/<slug>.md                # reusable custom agent profiles
+```
+
+احتفظ بملفات `context/` واقعية وسهلة التصفح. ضع القواعد التي يجب أن تنطبق على كل منعطف في `instructions/guardrails.md`. استخدم `skills/company-voice/SKILL.md` عندما يتعين على الوكيل تحويل أو مراجعة النسخة بصوت الشركة عمدًا.
+
+لتجاوز الإعداد الافتراضي العام لتطبيق أو فريق واحد، قم بإنشاء مورد مشترك/مؤسسة في هذا التطبيق بنفس المسار. لتجاوزه لشخص واحد، قم بإنشاء مورد شخصي بنفس المسار. لا تقم بنسخ ملف مساحة العمل إلى كل تطبيق؛ يعمل وقت التشغيل على حل المكدس عند القراءة:
+
+```text
+workspace context/brand.md
+-> shared/app context/brand.md
+-> personal context/brand.md
+```
+
+اجعل ملفات `context/` قصيرة وواقعية — بضع نقاط يمكن للوكيل قراءتها:
+
+```text
+<!-- context/brand.md -->
+
+# Brand
+
+- Voice: direct, warm, concrete
+- Use: "workspace", "agent", "team"
+- Avoid: unsupported superlatives and vague AI claims
+```
+
+## لوحة مساحة العمل {#workspace-panel}
+
+تتضمن لوحة الوكيل علامة تبويب **مساحة العمل** بجانب Chat وCLI. يعرض شجرة منظمة في المجلد لجميع الموارد، ومحررًا مضمّنًا لأي ملف نصي (Markdown، JSON، YAML، نص عادي)، وتدفقات الإنشاء المكتوبة في القائمة `+` (الملفات، Skills، الوكلاء، المهام المجدولة). يمكن للمستخدمين تصفح الإعدادات الافتراضية لمساحة العمل الموروثة وإنشاء/تحرير/حذف الموارد الشخصية أو موارد المؤسسة.
+
+عندما تفتح موردًا، يعرض المحرر شريط **السياق الفعال** مع مكدس `workspace default -> organization/app override -> personal override`، حتى تتمكن من رؤية ما تم توريثه وسبب تنشيط التجاوز. يعرض Dispatch نفس النموذج من جانب مستوى التحكم: في صفحة **الموارد** استخدم **فعال في التطبيق**، أو قم بتوسيع **المكدس** في صف الموارد في مربع حوار **السياق** الخاص ببطاقة التطبيق.
+
+عند تمكين سياسة الموافقة على الإرسال، يؤدي إنشاء مورد **جميع التطبيقات** أو تحديثه أو حذفه إلى وضع طلب الموافقة في قائمة الانتظار بدلاً من التقديم على الفور. تعرض مربعات حوار الإنشاء/التحرير/الحذف معاينة للتأثير قبل الحفظ.
+
+انقر على أيقونة `?` في شريط أدوات مساحة العمل للانتقال مرة أخرى إلى هذه المستندات في أي وقت.
+
+## كيفية استخدام الوكيل للموارد {#how-the-agent-uses-resources}
+
+يدير وكيل التطبيق المدمج الموارد باستخدام أداة `resources` الموحدة: استخدم `action: "list"` أو `"read"` أو `"effective"` أو `"write"` أو `"promote"` أو `"delete"`. يمكن لوكلاء CLI/code الخارجيين استخدام أوامر `pnpm action resource-*` المكافئة.
+
+في بداية كل محادثة، يقرأ الوكيل تلقائيًا:
+
+### AGENTS.md والتعليمات {#agents-md}
+
+`AGENTS.md` هو مورد تعليمات يتم تصنيفه افتراضيًا ويتم تحميله في كل دورة من مساحة العمل، والمشتركة/المؤسسة، والنطاقات الشخصية بهذا الترتيب - مساحة العمل للإعدادات الافتراضية على مستوى الشركة، والمشتركة/التطبيق لقواعد الفريق، والشخصية للتفضيلات لكل مستخدم. الملفات الموجودة ضمن `instructions/` هي مستندات حاجز حماية منفصلة تنطبق أيضًا على كل منعطف (قواعد الامتثال، وسياسة التصعيد، وصوت العلامة التجارية) وتتبع نفس الأسبقية. تقوم كل من الدردشة العادية وعمليات التشغيل التي يتم تشغيلها بالتكامل بتحميلها قبل الاستجابة.
+
+```text
+AGENTS.md
+instructions/customer-support-guardrails.md
+instructions/legal-review-policy.md
+```
+
+### الموارد المرجعية {#reference-resources}
+
+يقع سياق الشركة القابل لإعادة الاستخدام ضمن `context/` (الشخصيات، وتحديد المواقع، وحقائق المنتج، وإرشادات العلامة التجارية، والملاحظات التنافسية). يرى الوكيل فهرسًا لهذه العناصر ويقرأ الملف ذي الصلة باستخدام أداة `resources` (`action: "read"`) عندما تعتمد المهمة عليها؛ استخدم `action: "effective"` لمعرفة ما إذا كان قد تم تجاوز الإعداد الافتراضي لمساحة العمل لتطبيق أو مستخدم.
+
+### الذاكرة {#memory}
+
+تحتوي مساحة العمل على سطحي ذاكرة حاليين:
+
+- `LEARNINGS.md` في نطاق **مشترك** للاصطلاحات والتصحيحات على مستوى المشروع والمعرفة الدائمة للفريق.
+- `memory/MEMORY.md` في نطاق **شخصي** للذاكرة المنظمة حول المستخدم الحالي.
+
+يقوم نظام الموارد أيضًا بزراعة `LEARNINGS.md` شخصي للتوافق مع مساحات العمل الأقدم، ولكن مسار التحميل المسبق للدردشة مشترك `LEARNINGS.md` بالإضافة إلى `memory/MEMORY.md` الشخصي.
+
+**ما يتم حفظه.** عند تصحيح الوكيل ("استخدم دائمًا X بدلاً من Y")، أو مشاركة تفضيل ("أفضل الإجابات المختصرة")، أو الكشف عن السياق ("يطلق فريقي على هذا اسم "طبقة الإرسال")، يلتقط الوكيل هذا التعلم حتى لا يكرر الخطأ أو يعيد السؤال. تتم عمليات التعلم على مستوى المشروع في `LEARNINGS.md` المشتركة؛ الذاكرة الخاصة بالمستخدم تندرج تحت `memory/`. توضح مهارة `capture-learnings` متى وكيف.
+
+**المكان المناسب.**
+
+| السطح              | النطاق               | تأليف                                   | اقرأ متى                                        |
+| ------------------ | -------------------- | --------------------------------------- | ----------------------------------------------- |
+| `AGENTS.md`        | مشتركة               | البشر / الوكيل عند الطلب                | كل منعطف                                        |
+| `LEARNINGS.md`     | مشتركة               | البشر / الوكيل عند الطلب                | كل دور (نسخة مشتركة فقط)                        |
+| `memory/MEMORY.md` | شخصي                 | الوكيل / البشر                          | كل منعطف                                        |
+| `instructions/…`   | مشتركة               | البشر / الوكيل عند الطلب                | كل منعطف                                        |
+| `skills/…`         | مشتركة               | البشر / الوكيل عند الطلب                | حسب الطلب (أمر `/slash`)                        |
+| `context/…`        | مشتركة               | البشر / الوكيل عند الطلب                | يتم فهرسة كل منعطف، اقرأ عندما يكون ذلك مناسبًا |
+| `mcp-servers/…`    | مساحة العمل / مشتركة | البشر عبر Dispatch أو مساحة عمل التطبيق | تحديث تكوين MCP                                 |
+
+يمكن للمستخدمين تحرير ملفات الذاكرة هذه مباشرة في علامة التبويب "مساحة العمل" - فهي موارد عادية. احذف السطور التي أخطأ فيها الوكيل، أو احتفظ بالتفضيلات الشخصية في `memory/MEMORY.md`، أو قم بترقية القواعد على مستوى الفريق إلى `AGENTS.md`.
+
+كل سطح من هذه الأسطح — `AGENTS.md`، skills، الذاكرة، الوكلاء المخصصون، خوادم MCP — هو نفس شكل المورد الأساسي: `path` + `scope` + `content`، ويتم التعامل معه وحله بنفس الطريقة.
+
+```an-schema title="The workspace resource model" summary="One resource shape backs every workspace file. The runtime keys it by path and scope and resolves the effective value on read."
+{
+  "entities": [
+    {
+      "id": "resource",
+      "name": "workspace resource",
+      "note": "A single file in a user's workspace — instructions, skill, memory, agent, MCP config, or job.",
+      "fields": [
+        { "name": "path", "type": "string", "note": "Canonical path, e.g. AGENTS.md, skills/<slug>/SKILL.md" },
+        { "name": "scope", "type": "workspace | shared | personal", "note": "Which level this row lives at" },
+        { "name": "owner", "type": "string", "nullable": true, "note": "u:<email> for personal scope" },
+        { "name": "content", "type": "text", "note": "Markdown / JSON / YAML body" }
+      ]
+    }
+  ]
+}
+```
+
+## Skills {#skills}
+
+Skills هي ملفات موارد Markdown ضمن مسار `skills/` (يفضل `skills/<name>/SKILL.md`) والتي تمنح الوكيل معرفة المجال عند الطلب، والتي يتم استدعاؤها في الدردشة مع `/skill-name`. قم بإضافتها من علامة التبويب "مساحة العمل"، أو في وضع "الرمز"، من `.agents/skills/`.
+
+اطلع على [Skills Guide](/docs/skills-guide) — المصدر الوحيد لتنسيق المهارات ونطاقها واكتشافها وتأليفها.
+
+## الوكلاء المخصصون {#custom-agents}
+
+الوكلاء المخصصون عبارة عن ملفات تعريف وكيل فرعي محلية قابلة لإعادة الاستخدام ومخزنة كموارد Markdown ضمن `agents/*.md`. هذا هو الموقع الأساسي لتنسيق الوكيل المخصص.
+
+استخدمها عندما تريد مندوبًا مركّزًا باسمه الخاص، ووصفه، وتفضيلاته النموذجية، ومجموعة التعليمات الخاصة به. على عكس skills، لا يعد الوكلاء المخصصون توجيهًا سلبيًا — فهم شخصيات تشغيلية يمكن للوكيل الرئيسي استدعاؤها من خلال إشارات `@` أو عن طريق تحديدهم أثناء نشر الوكيل الفرعي.
+
+### تنسيق الوكيل {#agent-format}
+
+يستخدم الوكلاء المخصصون المادة الأمامية YAML بالإضافة إلى تعليمات Markdown:
+
+```an-annotated-code title="A custom agent profile"
+{
+  "filename": "agents/design.md",
+  "language": "markdown",
+  "code": "---\nname: Design\ndescription: >-\n  Reviews layouts, interaction patterns, and product UX decisions.\nmodel: inherit\ntools: inherit\ndelegate-default: false\n---\n\n# Role\n\nYou are a focused design agent.\n\n## Responsibilities\n\n- Review layouts and interaction flows\n- Suggest stronger visual direction\n- Be concise and opinionated",
+  "annotations": [
+    { "lines": "2", "label": "@mention handle", "note": "`name` is what appears in the `@`-dropdown and what the main agent delegates to." },
+    { "lines": "3-4", "label": "When to delegate", "note": "The `description` is what the orchestrator reads to decide this profile fits a task." },
+    { "lines": "5", "label": "Model", "note": "`inherit` reuses the main agent's model. Override only when the profile clearly needs a different one." },
+    { "lines": "6", "note": "`tools: inherit` for now — the field is reserved for future per-agent tool policies." }
+  ]
+}
+```
+
+الاصطلاحات الموصى بها:
+
+- قم بتخزين الوكلاء المخصصين في `agents/<slug>.md`
+- استخدم `model: inherit` ما لم يكن الملف الشخصي يحتاج بوضوح إلى نموذج مختلف
+- احتفظ بـ `tools: inherit` في الوقت الحالي؛ الحقل محجوز لسياسات الأداة المستقبلية
+
+### الوكلاء البعيدون مقابل الوكلاء المخصصون {#remote-vs-custom-agents}
+
+يوجد نوعان من الوكلاء في Workspace:
+
+- **الوكلاء المخصصون** — ملفات التعريف المحلية في `agents/*.md`، والتي يتم تنفيذها داخل التطبيق/وقت التشغيل الحالي
+- **الوكلاء المتصلون** — نظيرات A2A البعيدة الموصوفة بواسطة البيانات في `remote-agents/*.json` (لا يزال يتم التعرف على بيانات `agents/*.json` القديمة)
+
+استخدم الوكلاء المخصصين للتفويض داخل تطبيق واحد. استخدم الوكلاء المتصلين عندما تحتاج إلى الاتصال بتطبيق آخر عبر A2A.
+
+## @ وضع العلامات {#at-tagging}
+
+اكتب `@` في مدخلات الدردشة للإشارة إلى عناصر مساحة العمل. تظهر قائمة منسدلة عند المؤشر تعرض الوكلاء والملفات المطابقة. استخدم مفاتيح الأسهم للتنقل وEnter للاختيار. يظهر العنصر المحدد كشريحة مضمنة في الإدخال.
+
+عندما ترسل رسالة، يتم تمرير **الملفات/الموارد** كمراجع يمكن للوكيل قراءتها، ويعمل **الوكلاء المخصصون** محليًا باستخدام تعليمات ملفاتهم الشخصية، ويتم استدعاء **الوكلاء المتصلين** عبر A2A.
+
+## / أوامر الشرطة المائلة {#slash-commands}
+
+اكتب `/` في بداية السطر لاستدعاء إحدى المهارات. تعرض القائمة المنسدلة skills المتاحة بأسمائها وأوصافها؛ يؤدي تحديد واحدة إلى إضافة شريحة مضمنة ويتضمن محتواها كسياق عند إرسال الرسالة. إذا لم يتم تكوين skills، فإن القائمة المنسدلة ترتبط بهذه المستندات.
+
+## وضع الكود مقابل وضع التطبيق {#dev-vs-prod}
+
+يعمل نظام الموارد بشكل مماثل في كلا الوضعين. ما يختلف هو المصادر الإضافية المتاحة لوضع علامات `@` وأوامر `/`:
+
+| الميزة                 | وضع الكود                                                                                | وضع التطبيق                                             |
+| ---------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| @ وضع العلامات         | ملفات قاعدة التعليمات البرمجية + موارد مساحة العمل + الوكلاء المخصصون + الوكلاء المتصلون | موارد مساحة العمل + الوكلاء المخصصون + الوكلاء المتصلون |
+| / أوامر الشرطة المائلة | .agents/skills/ + المورد skills                                                          | المورد skills فقط                                       |
+| الوصول إلى ملف الوكيل  | نظام الملفات + الموارد                                                                   | الموارد فقط                                             |
+| لوحة مساحة العمل       | الوصول الكامل                                                                            | الوصول الكامل                                           |
+| AGENTS.md / الذاكرة    | متاح                                                                                     | متاح                                                    |
+
+## اتصالات مساحة العمل {#workspace-connections}
+
+تسمح اتصالات مساحة العمل للتطبيقات بمشاركة حساب الموفر نفسه (Slack، GitHub، HubSpot، وما إلى ذلك) دون تكرار بيانات الاعتماد. يسجل الاتصال هوية موفر الخدمة وتسميات الحساب والحالة والنطاقات ومنح التطبيقات ومراجع بيانات الاعتماد في SQL. تبقى الأسرار في مخزن بيانات الاعتماد؛ تشير الاتصالات فقط إلى أسماء مفاتيح الاعتماد مثل `SLACK_BOT_TOKEN`.
+
+راجع [Workspace Connections](/docs/workspace-connections) للتعرف على أمثلة التشغيل السريع والاتصال/المنح/بيانات الاعتماد API، وأمثلة Slack وHubSpot وGitHub الملموسة.
+
+---
+
+# المرجع
+
+## المورد API {#resource-api}
+
+يمكن إدارة الموارد من كود الخادم، actions، أو REST API.
+
+### الخادم API {#server-api}
+
+تم تثبيت نقاط النهاية REST تلقائيًا:
+
+| الطريقة  | نقطة النهاية                                  | الوصف                          |
+| -------- | --------------------------------------------- | ------------------------------ |
+| `GET`    | `/_agent-native/resources?scope=all`          | قائمة الموارد                  |
+| `GET`    | `/_agent-native/resources?scope=workspace`    | سرد موارد مساحة العمل الموروثة |
+| `GET`    | `/_agent-native/resources/tree?scope=all`     | الحصول على شجرة المجلدات       |
+| `GET`    | `/_agent-native/resources/effective?path=...` | إظهار مكدس الميراث الفعال      |
+| `POST`   | `/_agent-native/resources`                    | إنشاء مورد                     |
+| `GET`    | `/_agent-native/resources/:id`                | احصل على الموارد مع المحتوى    |
+| `PUT`    | `/_agent-native/resources/:id`                | تحديث أحد الموارد              |
+| `DELETE` | `/_agent-native/resources/:id`                | حذف مورد                       |
+| `POST`   | `/_agent-native/resources/upload`             | تحميل ملف كمورد                |
+
+### الإجراء API {#script-api}
+
+يستخدم الوكيل هذه actions المضمنة. يمكنك أيضًا الاتصال بهم من actions الخاص بك:
+
+```bash
+# List all resources
+pnpm action resource-list --scope all
+
+# Read a resource
+pnpm action resource-read --path "skills/my-skill/SKILL.md"
+
+# Read inherited workspace context managed by Dispatch
+pnpm action resource-read --scope workspace --path "context/brand.md"
+
+# Show workspace -> organization/app -> personal precedence for a path
+pnpm action resource-effective --path "context/brand.md"
+
+# Write a resource
+pnpm action resource-write --path "notes/meeting.md" --content "# Meeting Notes..."
+
+# Delete a resource
+pnpm action resource-delete --path "notes/old.md"
+```

package/docs/content/locales/ar-SA/writing-agent-instructions.md

@@ -0,0 +1,173 @@
+---
+title: "تعليمات وكيل الكتابة وSkills"
+description: "كيفية كتابة تعليمات رائعة للوكيل لتطبيق أو قالب أصلي للوكيل: AGENTS.md وskills وأوصاف الأدوات."
+---
+
+# تعليمات وكيل الكتابة وSkills
+
+يكون سلوك الوكيل في التطبيق الأصلي للوكيل جيدًا بقدر جودة الإرشادات التي تقدمها له. ثلاثة أسطح تحمل هذا التوجيه: `AGENTS.md` (الخريطة)، skills (الغوص العميق)، وأوصاف الإجراء/الأداة (كيف يختار الوكيل الأداة المناسبة). اكتب كل واحد منها لسرعة استرجاعها، وليس للنثر.
+
+```an-diagram title="Three authored surfaces + one runtime surface" summary="AGENTS.md and tool descriptions load every turn; skills load on demand; application_state is written live by your UI."
+{
+  "html": "<div class=\"diagram-surfaces\"><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>AGENTS.md</strong><small class=\"diagram-muted\">the map: purpose, core rules, state keys, action + skills index</small></div><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>Tool descriptions</strong><small class=\"diagram-muted\">drive tool selection — one precise sentence each</small></div><div class=\"diagram-card ondemand\" data-rough><span class=\"diagram-pill\">On demand</span><strong>Skills</strong><small class=\"diagram-muted\">deep how-to, loaded when the description fires</small></div><div class=\"diagram-card runtime\" data-rough><span class=\"diagram-pill ok\">Live</span><strong>application_state</strong><small class=\"diagram-muted\">written by your UI: navigation, selection, focus</small></div></div>",
+  "css": ".diagram-surfaces{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.diagram-surfaces .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+}
+```
+
+## اجعل AGENTS.md صغيرًا وقابلاً للمسح {#small-agents-md}
+
+يتم تحميل `AGENTS.md` كاتجاه. يجب أن يكون أصغر شيء يسمح للوكيل بالتصرف بشكل صحيح، مع دفع كل شيء بعمق إلى skills. استهدف هذه الأقسام وأشياء أخرى قليلة:
+
+- **سطر الغرض** — جملة واحدة توضح ماهية التطبيق وسير العمل الأساسي.
+- **القواعد الأساسية** — مجموعة من الثوابت التي يجب الاحتفاظ بها دائمًا (البيانات في SQL، والعمليات تمر عبر actions، ويمر الذكاء الاصطناعي عبر دردشة الوكيل، وتكون تغييرات المخطط إضافية). رصاصات قصيرة وضرورية.
+- **مفاتيح حالة التطبيق** — مفاتيح `navigation`/التحديد/التركيز التي يقرأها الوكيل لمعرفة ما ينظر إليه المستخدم وشكله.
+- **جدول الإجراءات** — جدول مضغوط يتضمن اسم الإجراء والغرض.
+- **فهرس Skills** — قائمة بـ skills الموجودة ومتى يجب قراءة كل منها.
+
+إذا تجاوز القسم الشاشة، فهو ينتمي إلى مهارة. يجيب `AGENTS.md` على "ما هذا التطبيق وماذا يمكنني أن أفعل"، وليس "كيف أفعل الشيء الصعب بالضبط".
+
+```markdown
+# Projects App
+
+One workspace for projects, tasks, and notes. Agent and UI share the same SQL
+data and the same actions.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes.
+- All AI work goes through the agent chat; never call an LLM inline.
+- Schema changes are additive only.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                     |
+| ---------------- | --------------------------- |
+| `list-projects`  | List accessible projects    |
+| `create-project` | Create a project            |
+| `update-project` | Rename or archive a project |
+
+## Skills
+
+- `project-imports` — read before importing legacy CSV exports.
+- `sharing` — read before exposing a project to other users.
+```
+
+## AGENTS.md أحادي المصدر {#single-source}
+
+احتفظ بملف تعليمات أساسي واحد: `AGENTS.md`. إذا كان العميل يتوقع `CLAUDE.md`، فاجعله رابطًا رمزيًا إلى `AGENTS.md` بدلاً من نسخة ثانية. ينجرف ملفان تم الاحتفاظ بهما يدويًا، وينتهي الأمر بالوكيل بقواعد متناقضة. مصدر واحد للحقيقة، مرتبط عند الحاجة.
+
+## يجب على المادة الأمامية SKILL.md أن تقول ما يقوله AND عندما {#skill-frontmatter}
+
+إن `description` هو الشيء الوحيد الذي يراه العميل عند اتخاذ قرار بشأن قراءة المهارة أم لا. يجب أن تجيب على سؤالين: ما الذي تغطيه المهارة، ومتى يتم تفعيلها. لن يتم إطلاق الوصف الذي يصف الموضوع فقط.
+
+```markdown
+---
+name: project-imports
+description: >-
+  How to import projects from the legacy CSV export. Use when the user uploads
+  a project CSV or asks to migrate projects from the old system.
+---
+```
+
+- ابدأ بالقدرة، ثم أضف عبارة صريحة **"استخدم عندما..."**.
+- كن انتهازيًا بعض الشيء، فالإفراط في التحفيز يتفوق على المهارة التي لا يتم تحميلها أبدًا.
+- اجعلها أقل من 40 كلمة تقريبًا؛ ويتم تحميله في سياق كل محادثة.
+
+## الإفصاح التدريجي {#progressive-disclosure}
+
+اكتب `SKILL.md` كطبقة بسيطة يجب معرفتها: القاعدة، وكيفية القيام بذلك، وقائمة ما يجب فعله/لا تفعله، والمؤشرات. أرسل الأمثلة الطويلة، ومراجع الحقول الشاملة، والمراوغات API، وجداول حالة الحافة إلى ملفات `references/` التي يقرأها الوكيل فقط عندما يحتاج إليها.
+
+```text
+.agents/skills/project-imports/
+├── SKILL.md            # rule + happy path + do/don't
+└── references/
+    └── csv-format.md   # full column spec, encodings, edge cases
+```
+
+يؤدي ذلك إلى إبقاء السطح الذي يتم تحميله دائمًا صغيرًا ويسمح بقياس العمق دون انتفاخ السياق. راجع [Skills Guide](/docs/skills-guide) للحصول على تنسيق المهارات الكاملة.
+
+## اكتب جداول موجهة نحو العمل {#action-tables}
+
+يقوم الوكيل بمسح الجداول بشكل أسرع من النثر. تفضل جدول الأسماء للغرض على الفقرات التي تصف كل عملية. الأمر نفسه ينطبق على مفاتيح الحالة، وأنواع الحقول، وأي مجموعة قابلة للإحصاء. تتميز الجداول بأنها قابلة للتصفح والتغيير ويسهل الحفاظ على مزامنتها عند إضافة إجراء.
+
+## اكتب وصفًا واضحًا للأداة {#tool-descriptions}
+
+أوصاف الإجراءات هي أوصاف للأدوات — فهي تحدد اختيار الأداة. اجعل كل واحدة جملة دقيقة ذات غرض واحد:
+
+- قل ما يفعله وما يعود به، وليس كيفية تنفيذه.
+- قم بوصف كل معلمة في `.describe()` الخاصة بها حتى يقوم الوكيل بتعبئتها بشكل صحيح.
+- مسؤولية واحدة لكل إجراء. إذا كان الوصف يحتاج إلى "وأيضًا..."، قم بتقسيمه.
+- ضع علامة للقراءة فقط على actions (`readOnly: true` أو `http: { method: "GET" }`) حتى يعرف الوكيل أن الاتصال بحرية آمن.
+
+```ts
+defineAction({
+  description: "Create a project. Returns the new project id and title.",
+  schema: z.object({
+    title: z.string().min(1).describe("Project title shown in the sidebar"),
+  }),
+  // ...
+});
+```
+
+## Skills ضد actions {#skills-vs-actions}
+
+Skills وactions متكاملان. المهارة هي التوجيه الذي يقرأه الوكيل؛
+الإجراء هو رمز يمكن للوكيل تشغيله.
+
+| الحاجة                                                                          | استخدام               |
+| ------------------------------------------------------------------------------- | --------------------- |
+| يحتاج الوكيل إلى اتباع سير العمل، أو السياسة، أو قائمة التحقق، أو قواعد التقييم | **المهارة**           |
+| يحتاج الوكيل إلى أمثلة أو مواد مرجعية أو قواعد خاصة بالمجال                     | **المهارة**           |
+| يحتاج الوكيل إلى قراءة بيانات التطبيق أو كتابتها                                | **الإجراء**           |
+| يحتاج الوكيل إلى الاتصال بـ API خارجي أو إجراء موافقة                           | **الإجراء**           |
+| يقوم الوكيل باستدعاء العملية الصحيحة ولكن بطريقة خاطئة                          | تحسين **المهارة**     |
+| لا يمكن للوكيل استدعاء العملية بشكل موثوق                                       | تحسين **الإجراء**     |
+| يختار الوكيل الأداة الخاطئة                                                     | تحسين **وصف الإجراء** |
+
+تستخدم معظم الميزات الحقيقية كلا من: توضح المهارة كيفية التعامل مع المهمة، و
+يوفر الإجراء العملية المكتوبة. على سبيل المثال، مهارة `invoice-review`
+يمكنه شرح سياسة المراجعة وقواعد التصعيد، بينما `list-invoices`،
+يقوم كل من `flag-invoice` و`approve-invoice` actions بعمليات القراءة والكتابة الفعلية.
+
+## اخبزها في مكان مضاد للتصنيع وتحقق منها قبل الانتهاء منها {#anti-fabrication}
+
+يجب أن تجعل تعليمات التطبيق الصدق والتحقق هو السلوك الافتراضي:
+
+- **لا تقم بالتلفيق أبدًا.** إذا لم يتم العثور على البيانات أو فشل الإجراء، فقل ذلك واسترد عافيتك — لا تخترع نتائج أو تدعي النجاح. اقرأ القيمة الحقيقية من خلال إجراء أو استعلام قبل الإبلاغ عنها.
+- **تحقق قبل إعلان الانتهاء.** بعد التغيير، قم بتأكيده من خلال إعادة القراءة (أعد الاستعلام عن الصف، وأعد قراءة الشاشة عبر `view-screen`) بدلاً من افتراض نجاح الكتابة.
+- **الاسترداد، لا تستسلم.** في حالة وجود خطأ قابل للاسترداد (استعلام فاشل، جلب عابر)، أعد محاولة الإدخال أو أصلحه بدلاً من التخلي عن المهمة. أبقِ هذا منفصلاً عن قاعدة مكافحة التلفيق - لا تخلط بين "لا تختلق الأشياء" و"توقف عند الخطأ الأول".
+
+ضع هذه القواعد الأساسية في `AGENTS.md` بحيث تنطبق على كل منعطف.
+
+## الأسطح الأربعة التي يراها العميل {#four-surfaces}
+
+يقع كل جزء من الإرشادات التي تقوم بتأليفها في أحد الأسطح الأربعة. إن معرفة السطح المطلوب استخدامه يمنع التكرار ووضع التفاصيل في غير محلها:
+
+| السطح                    | من يكتبها                        | عندما يتم تحميله                               | ما الذي ينتمي إليه                                                |
+| ------------------------ | -------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- |
+| تعليمات `AGENTS.md`      | أنت (المطور)                     | كل منعطف، كتوجيه                               | الغرض، القواعد الأساسية، مفاتيح الحالة، فهرس الإجراء، فهرس skills |
+| Skills (`SKILL.md`)      | أنت (المطور)                     | عند الطلب عندما يقرر الوكيل أن المهارة ذات صلة | كيفية تنفيذ نمط معين خطوة بخطوة، وقوائم المهام المحظورة           |
+| أوصاف الإجراء (الأدوات)  | أنت (المطور)                     | كل منعطف، كقائمة الأدوات                       | ما يفعله الإجراء، وما يُرجعه، ودلالات المعلمات                    |
+| سياق `application_state` | رمز UI الخاص بك (في وقت التشغيل) | كل منعطف، كحالة التطبيق المباشر                | التنقل الحالي، التحديد، الكائن الذي تم التركيز عليه، URL          |
+
+**التشخيص السريع:**
+
+- "يستمر الوكيل في السؤال عن السجل الذي يجب التصرف عليه حتى عندما يكون مفتوحًا" → الإصلاح: اكتب معرف العنصر الحالي في `application_state` (مفتاح `navigation`) من UI. هذه فجوة `application_state`، وليست فجوة مهارات.
+- "يستدعي الوكيل الإجراء الخاطئ أو يسيء استخدام المعلمة" → الإصلاح: تحسين `description` و`.describe()` للإجراء على المعلمة. هذا إصلاح لوصف الأداة، وليس مهارة.
+
+## ماذا يحدث وأين {#what-goes-where}
+
+- **AGENTS.md** — ينطبق على التطبيق بأكمله، في كل دورة: الغرض، والقواعد الأساسية، ومفاتيح الحالة، وفهرس الإجراء، وفهرس skills.
+- **Skills** — طريقة عمل قابلة لإعادة الاستخدام لنمط معين، ويتم تحميلها عند الطلب. ينطبق على جميع العاملين في التطبيق.
+- **الذاكرة (`memory/MEMORY.md`)** — التفضيلات والتصحيحات لكل مستخدم، وليس توجيهات المؤلف.
+
+## ما هي الخطوة التالية {#whats-next}
+
+- [Skills Guide](/docs/skills-guide) — تنسيق ملف المهارات، وإطار العمل skills، وskills المدعوم بالتطبيق.
+- [Creating Templates](/docs/creating-templates) — كيف يتناسب `AGENTS.md` وskills مع القالب القابل للشحن.
+- [The four-area checklist](/docs/key-concepts#four-area-checklist) — نموذج المناطق الأربع الذي يجب أن تلبيه كل ميزة.