cx-viewer 1.0.0

package/concepts/ar/Tool-TaskStop.md

@@ -0,0 +1,32 @@
+# TaskStop
+
+## التعريف
+
+إيقاف مهمة خلفية قيد التشغيل.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `task_id` | string | لا | معرف المهمة الخلفية المراد إيقافها |
+| `shell_id` | string | لا | مهمل، استخدم `task_id` بدلاً منه |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- إنهاء المهام طويلة التشغيل التي لم تعد مطلوبة
+- إلغاء المهام الخلفية التي بدأت بالخطأ
+
+## ملاحظات
+
+- يُرجع حالة نجاح أو فشل
+- معامل `shell_id` مهمل، يجب استخدام `task_id`
+
+## النص الأصلي
+
+<textarea readonly>
+- Stops a running background task by its ID
+- Takes a task_id parameter identifying the task to stop
+- Returns a success or failure status
+- Use this tool when you need to terminate a long-running task
+</textarea>

package/concepts/ar/Tool-TaskUpdate.md

@@ -0,0 +1,123 @@
+# TaskUpdate
+
+## التعريف
+
+تحديث حالة أو محتوى أو علاقات التبعية لمهمة معينة في قائمة المهام.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `taskId` | string | نعم | معرف المهمة المراد تحديثها |
+| `status` | enum | لا | الحالة الجديدة: `pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | لا | العنوان الجديد |
+| `description` | string | لا | الوصف الجديد |
+| `activeForm` | string | لا | نص بصيغة المضارع المستمر يُعرض أثناء التنفيذ |
+| `owner` | string | لا | المسؤول الجديد عن المهمة (اسم agent) |
+| `metadata` | object | لا | بيانات وصفية للدمج (تعيين القيمة إلى null لحذف المفتاح) |
+| `addBlocks` | string[] | لا | قائمة معرفات المهام المحظورة بواسطة هذه المهمة |
+| `addBlockedBy` | string[] | لا | قائمة معرفات المهام السابقة التي تحظر هذه المهمة |
+
+## تدفق الحالات
+
+```
+pending → in_progress → completed
+```
+
+يمكن الانتقال إلى `deleted` من أي حالة، مما يزيل المهمة نهائياً.
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- تعيين المهمة كـ `in_progress` عند بدء العمل
+- تعيين المهمة كـ `completed` بعد إنجاز العمل
+- تعيين علاقات التبعية بين المهام
+- تحديث محتوى المهمة عند تغيير المتطلبات
+
+**قواعد مهمة:**
+- لا تعيّن المهمة كـ `completed` إلا عند إنجازها بالكامل
+- عند مواجهة أخطاء أو عوائق، أبقِ الحالة `in_progress`
+- لا يجوز تعيين `completed` عند فشل الاختبارات أو عدم اكتمال التنفيذ أو وجود أخطاء غير محلولة
+
+## ملاحظات
+
+- قبل التحديث يجب الحصول على أحدث حالة للمهمة عبر TaskGet لتجنب البيانات القديمة
+- بعد إكمال المهمة استدعِ TaskList للبحث عن المهمة التالية المتاحة
+
+## النص الأصلي
+
+<textarea readonly>Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call TaskList to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to `deleted` permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **addBlocks**: Mark tasks that cannot start until this one completes
+- **addBlockedBy**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: `pending` → `in_progress` → `completed`
+
+Use `deleted` to permanently remove a task.
+
+## Staleness
+
+Make sure to read a task's latest state using `TaskGet` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+```json
+{"taskId": "1", "status": "in_progress"}
+```
+
+Mark task as completed after finishing work:
+```json
+{"taskId": "1", "status": "completed"}
+```
+
+Delete a task:
+```json
+{"taskId": "1", "status": "deleted"}
+```
+
+Claim a task by setting owner:
+```json
+{"taskId": "1", "owner": "my-name"}
+```
+
+Set up task dependencies:
+```json
+{"taskId": "2", "addBlockedBy": ["1"]}
+```
+</textarea>

package/concepts/ar/Tool-TeamCreate.md

@@ -0,0 +1,38 @@
+# TeamCreate
+
+## التعريف
+
+ينشئ فريقاً جديداً لتنسيق عمل عدة agent معاً. تتيح الفرق التنفيذ المتوازي للمهام من خلال قائمة مهام مشتركة وتبادل الرسائل بين الـ agent.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `team_name` | string | نعم | اسم الفريق الجديد |
+| `description` | string | لا | وصف الفريق / الغرض منه |
+| `agent_type` | string | لا | نوع / دور قائد الفريق |
+
+## ما يتم إنشاؤه
+
+- **ملف إعداد الفريق**: `~/.claude/teams/{team-name}/config.json` — يخزن قائمة الأعضاء والبيانات الوصفية
+- **دليل قائمة المهام**: `~/.claude/tasks/{team-name}/` — قائمة المهام المشتركة لجميع أعضاء الفريق
+
+يوجد تطابق 1:1 بين الفرق وقوائم المهام.
+
+## سير عمل الفريق
+
+1. **TeamCreate** — إنشاء الفريق وقائمة مهامه
+2. **TaskCreate** — تحديد المهام للفريق
+3. **Agent** (مع `team_name` + `name`) — توليد أعضاء ينضمون إلى الفريق
+4. **TaskUpdate** — تعيين المهام للأعضاء عبر `owner`
+5. يعمل الأعضاء على المهام ويتواصلون عبر **SendMessage**
+6. إيقاف تشغيل الأعضاء عند الانتهاء، ثم **TeamDelete** لتنظيف الموارد
+
+## الأدوات ذات الصلة
+
+| الأداة | الغرض |
+|--------|--------|
+| `TeamDelete` | حذف الفريق ومجلدات المهام |
+| `SendMessage` | التواصل بين الـ agent داخل الفريق |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | إدارة قائمة المهام المشتركة |
+| `Agent` | توليد أعضاء ينضمون إلى الفريق |

package/concepts/ar/Tool-TeamDelete.md

@@ -0,0 +1,30 @@
+# TeamDelete
+
+## التعريف
+
+يحذف فريقاً ومجلدات المهام المرتبطة به عند اكتمال عمل التعاون متعدد الـ agent. يُعدّ هذا الأداة المقابلة لـ TeamCreate في مرحلة التنظيف.
+
+## السلوك
+
+- يحذف مجلد الفريق: `~/.claude/teams/{team-name}/`
+- يحذف مجلد المهام: `~/.claude/tasks/{team-name}/`
+- يمسح سياق الفريق من الجلسة الحالية
+
+**مهم**: سيفشل TeamDelete إذا كان الفريق لا يزال يضم أعضاء نشطين. يجب إيقاف تشغيل الأعضاء أولاً بشكل سلس عبر طلبات إيقاف التشغيل في SendMessage.
+
+## الاستخدام النموذجي
+
+يُستدعى TeamDelete في نهاية سير عمل الفريق:
+
+1. اكتمال جميع المهام
+2. إيقاف تشغيل الأعضاء عبر `SendMessage` مع `shutdown_request`
+3. **TeamDelete** يحذف مجلدات الفريق والمهام
+
+## الأدوات ذات الصلة
+
+| الأداة | الغرض |
+|--------|--------|
+| `TeamCreate` | إنشاء فريق جديد وقائمة مهامه |
+| `SendMessage` | التواصل مع الأعضاء / إرسال طلبات إيقاف التشغيل |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | إدارة قائمة المهام المشتركة |
+| `Agent` | توليد أعضاء ينضمون إلى الفريق |

package/concepts/ar/Tool-WebFetch.md

@@ -0,0 +1,55 @@
+# WebFetch
+
+## التعريف
+
+جلب محتوى صفحة ويب من عنوان URL محدد، وتحويل HTML إلى markdown، ومعالجة المحتوى باستخدام نموذج ذكاء اصطناعي وفقاً للـ prompt.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `url` | string (URI) | نعم | عنوان URL الكامل المراد جلبه |
+| `prompt` | string | نعم | وصف المعلومات المراد استخلاصها من الصفحة |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- الحصول على محتوى صفحات الويب العامة
+- الاطلاع على التوثيق عبر الإنترنت
+- استخلاص معلومات محددة من صفحات الويب
+
+**غير مناسب للاستخدام:**
+- عناوين URL التي تتطلب مصادقة (Google Docs، Confluence، Jira، GitHub إلخ) — يجب البحث أولاً عن أداة MCP مخصصة
+- عناوين GitHub URL — يُفضل استخدام `gh` CLI
+
+## ملاحظات
+
+- يجب أن يكون URL كاملاً وصالحاً
+- يتم ترقية HTTP تلقائياً إلى HTTPS
+- قد يتم تلخيص النتائج عندما يكون المحتوى كبيراً جداً
+- يتضمن ذاكرة مؤقتة ذاتية التنظيف مدتها 15 دقيقة
+- عند إعادة توجيه URL إلى مضيف مختلف، تُرجع الأداة عنوان URL المُعاد توجيهه ويجب إعادة الطلب بالعنوان الجديد
+- إذا كانت أداة web fetch مقدمة من MCP متاحة، يُفضل استخدامها
+
+## النص الأصلي
+
+<textarea readonly>IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service (e.g. Google Docs, Confluence, Jira, GitHub). If so, you MUST use ToolSearch first to find a specialized tool that provides authenticated access.
+
+- Fetches content from a specified URL and processes it using an AI model
+- Takes a URL and a prompt as input
+- Fetches the URL content, converts HTML to markdown
+- Processes the content with the prompt using a small, fast model
+- Returns the model's response about the content
+- Use this tool when you need to retrieve and analyze web content
+
+Usage notes:
+  - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions.
+  - The URL must be a fully-formed valid URL
+  - HTTP URLs will be automatically upgraded to HTTPS
+  - The prompt should describe what information you want to extract from the page
+  - This tool is read-only and does not modify any files
+  - Results may be summarized if the content is very large
+  - Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL
+  - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.
+  - For GitHub URLs, prefer using the gh CLI via Bash instead (e.g., gh pr view, gh issue view, gh api).
+</textarea>

package/concepts/ar/Tool-WebSearch.md

@@ -0,0 +1,58 @@
+# WebSearch
+
+## التعريف
+
+تنفيذ استعلامات محرك البحث، وإرجاع نتائج البحث للحصول على أحدث المعلومات.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `query` | string | نعم | استعلام البحث (حرفان على الأقل) |
+| `allowed_domains` | string[] | لا | تضمين نتائج من هذه النطاقات فقط |
+| `blocked_domains` | string[] | لا | استبعاد نتائج من هذه النطاقات |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- الحصول على أحدث المعلومات التي تتجاوز تاريخ قطع معرفة النموذج
+- البحث عن الأحداث الجارية وأحدث البيانات
+- البحث عن أحدث التوثيق التقني
+
+## ملاحظات
+
+- تُرجع نتائج البحث بتنسيق روابط markdown
+- بعد الاستخدام يجب إضافة قسم "Sources:" في نهاية الاستجابة مع قائمة عناوين URL ذات الصلة
+- يدعم تصفية النطاقات (تضمين/استبعاد)
+- يجب استخدام السنة الحالية في استعلامات البحث
+- متاح فقط في الولايات المتحدة
+
+## النص الأصلي
+
+<textarea readonly>
+- Allows Claude to search the web and use the results to inform responses
+- Provides up-to-date information for current events and recent data
+- Returns search result information formatted as search result blocks, including links as markdown hyperlinks
+- Use this tool for accessing information beyond Claude's knowledge cutoff
+- Searches are performed automatically within a single API call
+
+CRITICAL REQUIREMENT - You MUST follow this:
+  - After answering the user's question, you MUST include a "Sources:" section at the end of your response
+  - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)
+  - This is MANDATORY - never skip including sources in your response
+  - Example format:
+
+    [Your answer here]
+
+    Sources:
+    - [Source Title 1](https://example.com/1)
+    - [Source Title 2](https://example.com/2)
+
+Usage notes:
+  - Domain filtering is supported to include or block specific websites
+  - Web search is only available in the US
+
+IMPORTANT - Use the correct year in search queries:
+  - The current month is March 2026. You MUST use this year when searching for recent information, documentation, or current events.
+  - Example: If the user asks for "latest React docs", search for "React documentation" with the current year, NOT last year
+</textarea>

package/concepts/ar/Tool-Write.md

@@ -0,0 +1,39 @@
+# Write
+
+## التعريف
+
+كتابة المحتوى إلى نظام الملفات المحلي. إذا كان الملف موجوداً بالفعل فسيتم الكتابة فوقه.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `file_path` | string | نعم | المسار المطلق للملف (يجب أن يكون مسار مطلق) |
+| `content` | string | نعم | المحتوى المراد كتابته |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- إنشاء ملفات جديدة
+- عند الحاجة لإعادة كتابة محتوى الملف بالكامل
+
+**غير مناسب للاستخدام:**
+- تعديل محتوى جزئي في الملف — يجب استخدام Edit
+- لا ينبغي إنشاء ملفات توثيق (*.md) أو README بشكل استباقي، إلا إذا طلب المستخدم ذلك صراحة
+
+## ملاحظات
+
+- إذا كان الملف الهدف موجوداً بالفعل، يجب قراءته أولاً عبر Read وإلا سيفشل
+- يكتب فوق كامل محتوى الملف الموجود
+- يُفضل استخدام Edit لتحرير الملفات الموجودة، Write فقط لإنشاء ملفات جديدة أو إعادة الكتابة الكاملة
+
+## النص الأصلي
+
+<textarea readonly>Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.</textarea>

package/concepts/ar/Tool-executeCode.md

@@ -0,0 +1,41 @@
+# executeCode (mcp__ide__executeCode)
+
+## التعريف
+
+تنفيذ كود Python في Jupyter kernel الخاص بملف notebook الحالي.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `code` | string | نعم | كود Python المراد تنفيذه |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- تنفيذ الكود في بيئة Jupyter notebook
+- اختبار مقتطفات الكود
+- تحليل البيانات والحسابات
+
+**غير مناسب للاستخدام:**
+- تنفيذ الكود خارج بيئة Jupyter — يجب استخدام Bash
+- تعديل الملفات — يجب استخدام Edit أو Write
+
+## ملاحظات
+
+- هذه أداة MCP (Model Context Protocol)، مقدمة من تكامل IDE
+- يُنفذ الكود في Jupyter kernel الحالي، والحالة تستمر بين الاستدعاءات
+- ما لم يطلب المستخدم صراحة، يجب تجنب تعريف المتغيرات أو تعديل حالة kernel
+- تُفقد الحالة بعد إعادة تشغيل kernel
+
+## النص الأصلي
+
+<textarea readonly>Execute python code in the Jupyter kernel for the current notebook file.
+    
+    All code will be executed in the current Jupyter kernel.
+    
+    Avoid declaring variables or modifying the state of the kernel unless the user
+    explicitly asks for it.
+    
+    Any code executed will persist across calls to this tool, unless the kernel
+    has been restarted.</textarea>

package/concepts/ar/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## التعريف
+
+الحصول على معلومات التشخيص اللغوي من VS Code، بما في ذلك أخطاء الصياغة وأخطاء الأنواع وتحذيرات lint وغيرها.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `uri` | string | لا | عنوان URI للملف. إذا لم يُحدد يتم الحصول على معلومات التشخيص لجميع الملفات |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- فحص مشاكل الصياغة والأنواع وlint وغيرها من المشاكل الدلالية في الكود
+- التحقق بعد تحرير الكود من عدم إدخال أخطاء جديدة
+- بديل لأوامر Bash لفحص جودة الكود
+
+**غير مناسب للاستخدام:**
+- تشغيل الاختبارات — يجب استخدام Bash
+- فحص أخطاء وقت التشغيل — يجب استخدام Bash لتنفيذ الكود
+
+## ملاحظات
+
+- هذه أداة MCP (Model Context Protocol)، مقدمة من تكامل IDE
+- متاحة فقط في بيئة VS Code / IDE
+- يُفضل استخدام هذه الأداة بدلاً من أوامر Bash لفحص مشاكل الكود
+
+## النص الأصلي
+
+<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/ar/Tools.md

@@ -0,0 +1,67 @@
+# نظرة عامة على أدوات Claude Code
+
+يوفر Claude Code مجموعة من الأدوات المدمجة للنموذج عبر آلية tool_use في Anthropic API. تحتوي مصفوفة `tools` في كل طلب MainAgent على تعريفات JSON Schema الكاملة لهذه الأدوات، ويستدعيها النموذج في الاستجابة عبر كتل محتوى `tool_use`.
+
+فيما يلي فهرس مصنف لجميع الأدوات.
+
+## نظام الوكلاء
+
+| الأداة | الغرض |
+|--------|--------|
+| [Task](Tool-Task.md) | بدء وكيل فرعي (SubAgent) لمعالجة المهام المعقدة متعددة الخطوات |
+| [TaskOutput](Tool-TaskOutput.md) | الحصول على مخرجات المهام الخلفية |
+| [TaskStop](Tool-TaskStop.md) | إيقاف مهمة خلفية قيد التشغيل |
+| [TaskCreate](Tool-TaskCreate.md) | إنشاء عنصر في قائمة المهام المنظمة |
+| [TaskGet](Tool-TaskGet.md) | الحصول على تفاصيل المهمة |
+| [TaskUpdate](Tool-TaskUpdate.md) | تحديث حالة المهمة والتبعيات وغيرها |
+| [TaskList](Tool-TaskList.md) | عرض جميع المهام |
+
+## عمليات الملفات
+
+| الأداة | الغرض |
+|--------|--------|
+| [Read](Tool-Read.md) | قراءة محتوى الملفات (يدعم النصوص والصور وPDF وJupyter notebook) |
+| [Edit](Tool-Edit.md) | تحرير الملفات عبر استبدال نصي دقيق |
+| [Write](Tool-Write.md) | كتابة أو الكتابة فوق الملفات |
+| [NotebookEdit](Tool-NotebookEdit.md) | تحرير خلايا Jupyter notebook |
+
+## البحث
+
+| الأداة | الغرض |
+|--------|--------|
+| [Glob](Tool-Glob.md) | البحث عن الملفات بمطابقة أنماط أسماء الملفات |
+| [Grep](Tool-Grep.md) | البحث في محتوى الملفات باستخدام ripgrep |
+
+## الطرفية
+
+| الأداة | الغرض |
+|--------|--------|
+| [Bash](Tool-Bash.md) | تنفيذ أوامر shell |
+
+## الويب
+
+| الأداة | الغرض |
+|--------|--------|
+| [WebFetch](Tool-WebFetch.md) | جلب محتوى صفحات الويب ومعالجته بالذكاء الاصطناعي |
+| [WebSearch](Tool-WebSearch.md) | استعلامات محرك البحث |
+
+## التخطيط والتفاعل
+
+| الأداة | الغرض |
+|--------|--------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | الدخول في وضع التخطيط لتصميم خطة التنفيذ |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | الخروج من وضع التخطيط وتقديم الخطة لموافقة المستخدم |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | طرح أسئلة على المستخدم للتوضيح أو اتخاذ القرارات |
+
+## الإضافات
+
+| الأداة | الغرض |
+|--------|--------|
+| [Skill](Tool-Skill.md) | تنفيذ المهارات (slash command) |
+
+## تكامل IDE
+
+| الأداة | الغرض |
+|--------|--------|
+| [getDiagnostics](Tool-getDiagnostics.md) | الحصول على معلومات التشخيص اللغوي من VS Code |
+| [executeCode](Tool-executeCode.md) | تنفيذ الكود في Jupyter kernel |

package/concepts/ar/ToolsFirst.md

@@ -0,0 +1,77 @@
+# لماذا تُدرج الأدوات أولاً؟
+
+في لوحة السياق بـ cc-viewer، **تظهر Tools قبل System Prompt والMessages**. يعكس هذا الترتيب بدقة **تسلسل بادئة KV-Cache في Anthropic API**.
+
+## تسلسل بادئة KV-Cache
+
+عندما تبني Anthropic API الـ KV-Cache، تقوم بتسلسل السياق في بادئة وفق هذا **الترتيب الثابت**:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+هذا يعني أن **Tools تأتي قبل System Prompt في بداية بادئة الـ cache تماماً**.
+
+## لماذا تمتلك Tools وزناً أعلى في الـ Cache من System؟
+
+في مطابقة بادئة KV-Cache، **المحتوى الأسبق أكثر أهمية** — أي تغيير يُبطل كل ما يليه:
+
+1. **مطابقة البادئة تبدأ من البداية**: يقارن KV-Cache الطلب الحالي بالبادئة المخزنة token بـ token من البداية. فور اكتشاف عدم تطابق، يُبطَل كل المحتوى اللاحق.
+
+2. **تغيير Tools = إبطال كامل للـ cache**: بما أن Tools تأتي أولاً، فأي تغيير في تعريفات الأدوات (حتى إضافة أو حذف MCP tool واحدة) **يكسر البادئة من البداية تماماً**، مما يُبطل كل الـ System Prompt والMessages المخزنة.
+
+3. **تغيير System = إبطال cache الـ Messages**: يقع System Prompt في المنتصف، لذا تؤثر تغييراته فقط على جزء الـ Messages الذي يليه.
+
+4. **تغيير Messages = يؤثر فقط على الذيل**: Messages تأتي في النهاية، لذا إضافة رسائل جديدة تُبطل فقط جزءاً صغيراً في النهاية — يبقى cache الـ Tools والـ System سليماً.
+
+## التأثير العملي
+
+| نوع التغيير | تأثير الـ Cache | السيناريو النموذجي |
+|-------------|----------------|---------------------|
+| إضافة/حذف Tool | **إبطال كامل** | اتصال/انقطاع MCP server، تفعيل/تعطيل إضافة IDE |
+| تغيير System Prompt | فقدان cache الـ Messages | تعديل CLAUDE.md، حقن system reminder |
+| إضافة رسالة جديدة | زيادة طرفية فقط | تدفق المحادثة الطبيعي (الأكثر شيوعاً، الأقل تكلفة) |
+
+لهذا السبب يُعد `tools_change` في [CacheRebuild](CacheRebuild.md) أغلى أسباب إعادة البناء في الغالب — لأنه يكسر سلسلة البادئة من الأمام تماماً.
+
+## لماذا توضع تعريفات الأدوات قبل "الدماغ"؟
+
+من منظور التخزين المؤقت، وجود Tools في المقدمة هو حقيقة تقنية. لكن من منظور التصميم المعرفي، هذا الترتيب منطقي بنفس القدر — **الأدوات هي اليدان والقدمان، وSystem Prompt هو الدماغ**.
+
+قبل التصرف، يحتاج الشخص إلى إدراك الأطراف والأدوات المتاحة له. الرضيع لا يفهم أولاً قواعد العالم (System) ثم يتعلم الإمساك — بل يدرك أولاً أن لديه يدين وقدمين، ثم يفهم القواعد تدريجياً من خلال التفاعل مع البيئة. وبالمثل، يحتاج نموذج LLM إلى معرفة الأدوات التي يمكنه استدعاؤها (قراءة الملفات، كتابة الكود، البحث، تنفيذ الأوامر) قبل تلقي تعليمات المهمة (System Prompt)، ليتمكن من تقييم "ماذا يمكنني أن أفعل" و"كيف يجب أن أفعل ذلك" بدقة عند معالجة التعليمات.
+
+لو كان الترتيب معكوساً — إخبار النموذج أولاً "مهمتك إعادة هيكلة هذه الوحدة"، ثم إخباره "لديك أدوات Read وEdit وBash" — سيفتقر النموذج إلى معلومات حاسمة عن حدود قدراته عند فهم المهمة، مما قد ينتج خططاً غير واقعية أو يتجاهل أساليب متاحة.
+
+**اعرف أوراقك قبل أن تقرر كيف تلعبها.** هذا هو المنطق المعرفي وراء وضع Tools قبل System.
+
+## لماذا توجد أدوات MCP أيضاً في هذا الموضع؟
+
+أدوات MCP (Model Context Protocol)، مثل الأدوات المدمجة، توضع في بداية منطقة Tools. فهم موقع MCP في السياق يساعد في تقييم فوائده وتكاليفه الحقيقية.
+
+### مزايا MCP
+
+- **توسيع القدرات**: يتيح MCP للنماذج الوصول إلى خدمات خارجية (استعلامات قواعد البيانات، استدعاءات API، عمليات IDE، التحكم بالمتصفح، إلخ)، متجاوزاً حدود الأدوات المدمجة
+- **نظام بيئي مفتوح**: يمكن لأي شخص تنفيذ خادم MCP؛ يكتسب النموذج قدرات جديدة دون إعادة التدريب
+- **التحميل عند الطلب**: يمكن توصيل/فصل خوادم MCP بشكل انتقائي حسب السيناريو، مع تركيب مرن لمجموعات الأدوات
+
+### تكاليف MCP
+
+- **قاتل التخزين المؤقت**: يتم ربط تعريف JSON Schema لكل أداة MCP في بداية بادئة KV-Cache. إضافة أو إزالة أداة MCP واحدة = **إبطال التخزين المؤقت بالكامل من البداية**. التوصيل/الفصل المتكرر لخوادم MCP يقلل بشكل كبير من معدل إصابة التخزين المؤقت
+- **تضخم البادئة**: مخططات أدوات MCP عادة أكبر من الأدوات المدمجة (أوصاف مفصلة للمعاملات، قيم تعداد، إلخ). العديد من أدوات MCP يزيد بشكل ملحوظ عدد الرموز في منطقة Tools، مما يقلص مساحة السياق المتاحة للرسائل
+- **عبء التأخير**: تتطلب استدعاءات أدوات MCP اتصالاً بين العمليات (JSON-RPC عبر stdio/SSE)، وهو أبطأ بمرتبة من استدعاءات الدوال المدمجة
+- **مخاطر الاستقرار**: خوادم MCP هي عمليات خارجية قد تتعطل أو تنتهي مهلتها أو تعيد تنسيقات غير متوقعة، مما يتطلب معالجة أخطاء إضافية
+
+### توصيات عملية
+
+| السيناريو | التوصية |
+|-----------|---------|
+| محادثات طويلة، تفاعل متكرر | تقليل عدد أدوات MCP لحماية استقرار بادئة التخزين المؤقت |
+| مهام قصيرة، عمليات لمرة واحدة | استخدام أدوات MCP بحرية؛ التأثير على التخزين المؤقت محدود |
+| إضافة/إزالة متكررة لخوادم MCP | كل تغيير يؤدي إلى إعادة بناء كاملة للتخزين المؤقت؛ النظر في تثبيت مجموعة الأدوات |
+| مخططات أدوات كبيرة الحجم | تقليص الأوصاف والتعدادات لتقليل استهلاك رموز البادئة |
+
+في لوحة Context في cc-viewer، تُعرض أدوات MCP إلى جانب الأدوات المدمجة في منطقة Tools، مما يوفر رؤية واضحة لحجم مخطط كل أداة ومساهمتها في بادئة التخزين المؤقت.

package/concepts/ar/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# تلوث السياق في Translate API
+
+## الخلفية
+
+يتضمن CC-Viewer ميزة ترجمة مدمجة (`POST /api/translate`) تعمل بواسطة Anthropic Messages API. في التنفيذ المبكر، كانت طلبات الترجمة تعيد استخدام بيانات المصادقة المخزنة مؤقتاً من جلسة Claude Code — بما في ذلك رؤوس `x-api-key` و `authorization`. تسبب هذا في مشكلة خفية لكنها خطيرة: كانت نتائج الترجمة تعيد في كثير من الأحيان محتوى غير ذي صلة.
+
+## السبب الجذري
+
+### الفرق الجوهري بين طريقتي المصادقة
+
+يدعم Anthropic API طريقتين للمصادقة:
+
+| الطريقة | الرأس | المصدر النموذجي | الخصائص |
+|---------|-------|-----------------|---------|
+| مفتاح API | `x-api-key: sk-ant-...` | متغير البيئة / Console | عديم الحالة، كل طلب مستقل |
+| رمز OAuth | `authorization: Bearer sessionToken` | تسجيل دخول اشتراك Claude Code | مرتبط بالجلسة، يحتفظ الخادم بارتباط السياق |
+
+الفرق الجوهري: **مفاتيح API عديمة الحالة** — كل طلب مستقل تماماً؛ بينما **رموز جلسة OAuth ذات حالة** — يربط خادم Anthropic الطلبات التي تستخدم نفس الرمز بنفس سياق الجلسة.
+
+### سلسلة التلوث
+
+عندما يستخدم Claude Code تسجيل دخول OAuth بالاشتراك، يبدو تدفق المصادقة كالتالي:
+
+```
+المحادثة الرئيسية لـ Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                              ↑
+طلب ترجمة CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+نظراً لأن طلبات الترجمة أعادت استخدام نفس رمز الجلسة، فقد يربط خادم Anthropic طلبات الترجمة بسياق المحادثة الرئيسية لـ Claude Code. يؤدي هذا إلى:
+
+1. **تأثر نتائج الترجمة بسياق المحادثة الرئيسية**: موجه النظام لطلب الترجمة هو "أنت مترجم"، لكن سياق الخادم لا يزال يحتوي على سجل محادثات Claude Code، مما قد يتداخل مع النموذج
+2. **تعطل المحادثة الرئيسية بسبب طلبات الترجمة**: قد يتم حقن محتوى طلبات الترجمة (أجزاء نصوص واجهة المستخدم) في سياق المحادثة الرئيسية، مما يتسبب في انحراف استجابات Claude Code
+3. **سلوك غير متوقع**: نظراً لأن تلوث السياق هو سلوك من جانب الخادم، لا يمكن للعميل اكتشافه أو التحكم فيه
+
+## الدروس المستفادة
+
+- **رموز جلسة OAuth ليست "مجرد مفتاح API آخر"** — فهي تحمل حالة من جانب الخادم، وإعادة استخدامها تعني مشاركة السياق
+- **يجب أن تستخدم استدعاءات الخدمات الداخلية مصادقة مستقلة وعديمة الحالة** لتجنب الارتباط بجلسات المستخدمين
+
+## المراجع
+
+- [Anthropic API Authentication Docs](https://docs.anthropic.com/en/api/getting-started)
+- [Claude Code Authentication](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code)
+- [Anthropic Bans Subscription OAuth in Third-Party Apps](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/)
+- [Claude Code Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/)