cc-viewer 1.2.0 → 1.2.2

package/README.md

@@ -72,9 +72,11 @@ Click the "Chat mode" button in the top right to parse Main Agent's full convers
 ### Translation
 
 - Thinking blocks and assistant messages support one-click translation
-- Powered by Claude Haiku API, supports both API key (`x-api-key`) and OAuth Bearer token authentication
+- Powered by Claude Haiku API, uses `x-api-key` authentication only (OAuth session tokens are excluded to prevent context pollution)
+- Automatically captures haiku model name from mainAgent requests; defaults to `claude-haiku-4-5-20251001`
 - Translation results are cached; click again to toggle back to the original text
 - Loading spinner animation shown during translation
+- (?) help icon on `authorization` header links to concept doc explaining context pollution
 
 ### Token Stats
 

package/cli.js

@@ -100,6 +100,13 @@ function removeCliJsInjection() {
 // === 主逻辑 ===
 
 const isUninstall = process.argv.includes('--uninstall');
+const isVersion = process.argv.includes('--v') || process.argv.includes('--version');
+
+if (isVersion) {
+  const pkg = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8'));
+  console.log(`cc-viewer v${pkg.version}`);
+  process.exit(0);
+}
 
 if (isUninstall) {
   const cliResult = removeCliJsInjection();

package/concepts/ar/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (مقارنة تزايدية لجسم الطلب)
+
+## الخلفية
+
+يعتمد MainAgent في Claude Code آلية إرسال السياق الكامل — حيث يحمل كل طلب سجل المحادثة الكامل وsystem prompt وتعريفات الأدوات وغيرها. هذا يعني أنه مع تقدم المحادثة يصبح جسم الطلب أكبر فأكبر، ومن الصعب تحديد "ما الجديد في هذه الجولة" عند عرض Body الخام مباشرة.
+
+Body Diff JSON صُمم لحل هذه المشكلة: يقارن تلقائياً بين طلبي MainAgent متتاليين ويستخلص الجزء التزايدي، مما يتيح لك رؤية المحتوى الجديد الفعلي في هذا الطلب بنظرة واحدة.
+
+## آلية العمل
+
+1. **تحديد طلبات MainAgent المتتالية**: يجب أن يكون الطلب الحالي من نوع MainAgent مع وجود طلب MainAgent سابق
+2. **مقارنة حقل بحقل**: يتم فحص جميع الحقول العلوية في جسم الطلب مع تخطي الخصائص الداخلية ذات البادئة `_`
+3. **استخلاص الفروقات الذكي**:
+   - الحقول الجديدة: تُعرض مباشرة
+   - الحقول المحذوفة: لا تُعرض (عادة لا تؤثر على الفهم)
+   - الحقول المتغيرة: تُعرض القيمة الحالية
+   - معالجة خاصة لمصفوفة `messages`: تُعرض فقط الرسائل الجديدة (لأن المحادثة العادية تعمل بنمط الإلحاق، والرسائل السابقة لا تتغير)
+4. **كشف تقلص جسم الطلب**: إذا كان جسم الطلب الحالي أصغر من السابق، فهذا يعني حدوث اقتطاع للسياق أو إعادة تعيين الجلسة، وفي هذه الحالة تُعرض رسالة توضيحية بدلاً من diff
+
+## السيناريوهات النموذجية
+
+في جولة محادثة عادية، يحتوي Body Diff JSON عادة على:
+- `messages`: رسالة أو رسالتان جديدتان (مدخلات المستخدم + رد المساعد من الجولة السابقة)
+
+إذا رأيت تغييرات في حقول مثل `system` أو `tools` أو `model` في الـ diff، فهذا يعني حدوث تغيير في التكوين في هذه الجولة، وهو غالباً سبب إعادة بناء الذاكرة المؤقتة.
+
+## طريقة الاستخدام
+
+- يُعرض Body Diff JSON في لوحة تفاصيل طلب MainAgent
+- انقر على العنوان للتوسيع/الطي
+- يدعم وضعي عرض JSON وText، بالإضافة إلى النسخ بنقرة واحدة
+- في **CC-Viewer → الإعدادات العامة** في الزاوية العلوية اليسرى، يمكنك تعيين "توسيع Body Diff JSON افتراضياً"

package/concepts/ar/CacheRebuild.md

@@ -0,0 +1,40 @@
+# Cache Rebuild (إعادة بناء الذاكرة المؤقتة)
+
+## الخلفية
+
+تقوم آلية prompt caching من Anthropic بتجميع system → tools → messages (حتى نقطة توقف الذاكرة المؤقتة) بالترتيب كمفتاح للذاكرة المؤقتة. عندما يتطابق مفتاح الذاكرة المؤقتة تماماً مع الطلب السابق، تُرجع الـ API قيمة `cache_read_input_tokens` (إصابة الذاكرة المؤقتة)؛ وعندما يتغير المفتاح، تُعيد الـ API إنشاء الذاكرة المؤقتة وتُرجع كمية كبيرة من `cache_creation_input_tokens`، أي إعادة بناء الذاكرة المؤقتة.
+
+إعادة بناء الذاكرة المؤقتة تعني رسوم tokens إضافية (سعر cache creation أعلى من cache read)، لذا فإن تحديد سبب إعادة البناء له قيمة مباشرة في تحسين التكاليف.
+
+## تصنيف أسباب إعادة بناء الذاكرة المؤقتة
+
+يحدد cc-viewer بدقة سبب إعادة بناء الذاكرة المؤقتة من خلال مقارنة body طلبي MainAgent المتتاليين:
+
+| reason | المعنى | طريقة التحديد |
+|--------|--------|---------------|
+| `ttl` | انتهاء صلاحية الذاكرة المؤقتة | مرور أكثر من 5 دقائق منذ آخر طلب MainAgent |
+| `system_change` | تغيير system prompt | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | تغيير تعريفات الأدوات | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | تبديل النموذج | `prev.model !== curr.model` |
+| `msg_truncated` | اقتطاع مكدس الرسائل | عدد رسائل الطلب الحالي أقل من السابق، عادة بسبب تجاوز نافذة السياق |
+| `msg_modified` | تعديل الرسائل التاريخية | عدم تطابق محتوى الرسائل السابقة (في الإلحاق العادي يجب أن تكون البادئة متطابقة تماماً) |
+| `key_change` | تغيير مفتاح غير معروف | احتياطي عندما لا تتطابق أي من الشروط أعلاه |
+
+## أولوية التحديد
+
+1. فحص الفاصل الزمني أولاً — إذا تجاوز 5 دقائق يُحدد مباشرة كـ `ttl` دون مقارنة body
+2. ثم فحص model وsystem وtools وmessages بالترتيب
+3. قد يتطابق طلب واحد مع أسباب متعددة (مثل تبديل النموذج + تغيير system prompt)، وفي هذه الحالة تحتوي مصفوفة `reasons` على جميع العناصر المتطابقة ويُعرض tooltip بأسطر متعددة
+
+## السيناريوهات الشائعة
+
+- **`ttl`**: توقف المستخدم عن العمل لأكثر من 5 دقائق ثم استأنف، وانتهت صلاحية الذاكرة المؤقتة طبيعياً
+- **`system_change`**: قام Claude Code بتحديث system prompt (مثل تحميل CLAUDE.md جديد أو تغيير تعليمات المشروع)
+- **`tools_change`**: اتصال/انقطاع خادم MCP أدى إلى تغيير قائمة الأدوات المتاحة
+- **`model_change`**: قام المستخدم بتبديل النموذج عبر أمر `/model`
+- **`msg_truncated`**: محادثة طويلة أدت إلى تفعيل إدارة نافذة السياق، وقام Claude Code باقتطاع الرسائل المبكرة
+- **`msg_modified`**: قام Claude Code بتعديل الرسائل التاريخية (مثل استبدال `/compact` للملخص المضغوط بالرسائل الأصلية)
+
+## العرض في cc-viewer
+
+في قائمة الطلبات، تعرض الطلبات التي حدثت فيها إعادة بناء الذاكرة المؤقتة مؤشراً بنقطة حمراء في سطر cache. يظهر tooltip عند تمرير الماوس يحتوي على وصف تفصيلي لسبب إعادة البناء (يدعم 18 لغة).

package/concepts/ar/MainAgent.md

@@ -0,0 +1,30 @@
+# MainAgent
+
+## التعريف
+
+MainAgent هو سلسلة الطلبات الرئيسية في Claude Code عندما لا يكون في وضع agent team. كل تفاعل بين المستخدم وClaude Code ينتج سلسلة من طلبات API، حيث تشكل طلبات MainAgent سلسلة المحادثة الأساسية — فهي تحمل system prompt الكامل وتعريفات الأدوات وسجل الرسائل.
+
+## طريقة التعرف
+
+في cc-viewer، يُعرَّف MainAgent من خلال `req.mainAgent === true`، ويتم تعيينه تلقائياً بواسطة `interceptor.js` عند التقاط الطلب.
+
+شروط التحديد (يجب استيفاؤها جميعاً):
+- جسم الطلب يحتوي على حقل `system` (system prompt)
+- جسم الطلب يحتوي على مصفوفة `tools` (تعريفات الأدوات)
+- يحتوي system prompt على نص مميز لـ "Claude Code"
+
+## الفرق عن SubAgent
+
+| الخاصية | MainAgent | SubAgent |
+|---------|-----------|----------|
+| system prompt | prompt رئيسي كامل لـ Claude Code | prompt مختصر مخصص للمهمة |
+| مصفوفة tools | تحتوي على جميع الأدوات المتاحة | عادة تحتوي فقط على الأدوات اللازمة للمهمة |
+| سجل الرسائل | يتراكم سياق المحادثة الكامل | يحتوي فقط على رسائل المهمة الفرعية |
+| سلوك التخزين المؤقت | يوجد prompt caching (TTL 5 دقائق) | عادة بدون تخزين مؤقت أو تخزين مؤقت صغير |
+
+## الأهمية في cc-viewer
+
+- **تتبع الذاكرة المؤقتة**: حالة prompt caching لطلبات MainAgent تؤثر مباشرة على التكاليف. من خلال مراقبة نسبة `cache_creation_input_tokens` إلى `cache_read_input_tokens` يمكن تحديد معدل إصابة الذاكرة المؤقتة
+- **تحليل فقدان الذاكرة المؤقتة**: عندما تظهر كمية كبيرة من cache creation (بدلاً من cache read) في طلبات MainAgent، فهذا يعني فقدان الذاكرة المؤقتة وإعادة بنائها، ويقوم cc-viewer بتمييز هذه الطلبات بمؤشر نقطة حمراء
+- **تحليل السلسلة الرئيسية**: تعكس تسلسل طلبات MainAgent عملية التفاعل الكاملة بين المستخدم وClaude Code، وهي البيانات الأساسية لتحليل سلوك الجلسة
+- **إعادة بناء الجلسة**: يعيد cc-viewer بناء عرض المحادثة (Chat Mode) من خلال سجل رسائل طلبات MainAgent

package/concepts/ar/Tool-AskUserQuestion.md

@@ -0,0 +1,54 @@
+# AskUserQuestion
+
+## التعريف
+
+طرح أسئلة على المستخدم أثناء التنفيذ، للحصول على توضيحات أو التحقق من الافتراضات أو طلب اتخاذ قرارات.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `questions` | array | نعم | قائمة الأسئلة (1-4 أسئلة) |
+| `answers` | object | لا | الإجابات التي جمعها المستخدم |
+| `annotations` | object | لا | ملاحظات لكل سؤال (مثل ملاحظات معاينة الاختيارات) |
+| `metadata` | object | لا | بيانات وصفية للتتبع والتحليل |
+
+كل كائن `question`:
+
+| الحقل | النوع | مطلوب | الوصف |
+|-------|-------|-------|-------|
+| `question` | string | نعم | نص السؤال الكامل، يجب أن ينتهي بعلامة استفهام |
+| `header` | string | نعم | تسمية قصيرة (12 حرفاً كحد أقصى)، تُعرض كشريحة تسمية |
+| `options` | array | نعم | 2-4 خيارات |
+| `multiSelect` | boolean | نعم | هل يُسمح بالاختيار المتعدد |
+
+كل كائن `option`:
+
+| الحقل | النوع | مطلوب | الوصف |
+|-------|-------|-------|-------|
+| `label` | string | نعم | نص عرض الخيار (1-5 كلمات) |
+| `description` | string | نعم | وصف الخيار |
+| `markdown` | string | لا | محتوى المعاينة (للمقارنة المرئية لتخطيطات ASCII ومقتطفات الكود وغيرها) |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- جمع تفضيلات أو متطلبات المستخدم
+- توضيح التعليمات الغامضة
+- الحصول على قرارات أثناء التنفيذ
+- تقديم خيارات اتجاهية للمستخدم
+
+**غير مناسب للاستخدام:**
+- السؤال "هل الخطة مقبولة؟" — يجب استخدام ExitPlanMode
+
+## ملاحظات
+
+- يمكن للمستخدم دائماً اختيار "Other" لتقديم إدخال مخصص
+- يُوضع الخيار الموصى به في المقام الأول مع إضافة "(Recommended)" في نهاية label
+- معاينة `markdown` تدعم فقط أسئلة الاختيار الفردي
+- الخيارات التي تحتوي على `markdown` تتحول إلى تخطيط جنباً إلى جنب
+- في وضع التخطيط، تُستخدم لتوضيح المتطلبات قبل تحديد الخطة
+
+## الأهمية في cc-viewer
+
+يظهر استدعاء AskUserQuestion في سجل الطلبات ككتلة محتوى `tool_use`، تحتوي على تعريفات الأسئلة والخيارات. تظهر إجابات المستخدم في سجل الرسائل للطلبات اللاحقة.

package/concepts/ar/Tool-Bash.md

@@ -0,0 +1,47 @@
+# Bash
+
+## التعريف
+
+تنفيذ أوامر shell، مع دعم إعداد مهلة اختيارية. يستمر دليل العمل بين الأوامر، لكن حالة shell (متغيرات البيئة وغيرها) لا تستمر.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `command` | string | نعم | أمر bash المراد تنفيذه |
+| `description` | string | لا | وصف مختصر للأمر |
+| `timeout` | number | لا | مهلة (بالمللي ثانية)، الحد الأقصى 600000، الافتراضي 120000 |
+| `run_in_background` | boolean | لا | هل يتم التشغيل في الخلفية |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- عمليات git (commit، push، branch إلخ)
+- أوامر إدارة الحزم مثل npm/yarn
+- عمليات docker
+- أوامر التجميع والبناء
+- عرض محتويات الدليل (`ls`)
+- أوامر النظام الأخرى التي تتطلب تنفيذ shell
+
+**غير مناسب للاستخدام:**
+- قراءة الملفات — يجب استخدام Read
+- البحث عن أسماء الملفات — يجب استخدام Glob
+- البحث في محتوى الملفات — يجب استخدام Grep
+- تحرير الملفات — يجب استخدام Edit
+- كتابة الملفات — يجب استخدام Write
+- إخراج المعلومات للمستخدم — الإخراج مباشرة في نص الاستجابة
+- العمليات طويلة التشغيل (dev server، وضع watch) — يُنصح بأن يشغلها المستخدم يدوياً
+
+## ملاحظات
+
+- المسارات التي تحتوي على مسافات يجب أن تُحاط بعلامات اقتباس مزدوجة
+- المخرجات التي تتجاوز 30000 حرف يتم اقتطاعها
+- نتائج الأوامر التي تعمل في الخلفية تُحصل عبر TaskOutput
+- يُفضل استخدام المسارات المطلقة وتجنب `cd`
+- الأوامر المستقلة يمكن استدعاء عدة Bash بالتوازي
+- الأوامر ذات التبعيات تُربط بـ `&&`
+- يتم تهيئة بيئة Shell من ملف profile الخاص بالمستخدم (bash أو zsh)
+
+## الأهمية في cc-viewer
+
+يظهر استدعاء Bash في سجل الطلبات كزوج من كتل محتوى `tool_use` (يحتوي على الأمر) و`tool_result` (يحتوي على المخرجات). يمكن استخدام مخرجات تنفيذ الأوامر لتحليل سلوك عمليات النموذج.

package/concepts/ar/Tool-Edit.md

@@ -0,0 +1,38 @@
+# Edit
+
+## التعريف
+
+تحرير الملفات عبر استبدال نصي دقيق. يستبدل `old_string` بـ `new_string` في الملف.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `file_path` | string | نعم | المسار المطلق للملف المراد تعديله |
+| `old_string` | string | نعم | النص الأصلي المراد استبداله |
+| `new_string` | string | نعم | النص الجديد بعد الاستبدال (يجب أن يختلف عن old_string) |
+| `replace_all` | boolean | لا | هل يتم استبدال جميع التطابقات، الافتراضي `false` |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- تعديل أجزاء محددة من الكود في ملفات موجودة
+- إصلاح الأخطاء وتحديث المنطق
+- إعادة تسمية المتغيرات (مع `replace_all: true`)
+- أي سيناريو يتطلب تعديلاً دقيقاً لمحتوى الملف
+
+**غير مناسب للاستخدام:**
+- إنشاء ملفات جديدة — يجب استخدام Write
+- إعادة كتابة واسعة النطاق — قد يتطلب Write للكتابة فوق الملف بالكامل
+
+## ملاحظات
+
+- يجب قراءة الملف أولاً عبر Read قبل الاستخدام، وإلا سيحدث خطأ
+- يجب أن يكون `old_string` فريداً في الملف، وإلا يفشل التحرير. إذا لم يكن فريداً، يجب توفير مزيد من السياق لجعله فريداً، أو استخدام `replace_all`
+- يجب الحفاظ على المسافة البادئة الأصلية (tab/مسافات) عند تحرير النص، ولا تُضمَّن بادئة أرقام الأسطر من مخرجات Read
+- يُفضل تحرير الملفات الموجودة بدلاً من إنشاء ملفات جديدة
+- يجب أن يختلف `new_string` عن `old_string`
+
+## الأهمية في cc-viewer
+
+يظهر استدعاء Edit في سجل الطلبات ككتلة محتوى `tool_use`، حيث يحتوي `input` على `old_string` و`new_string`، ويمكن استخدامه لتتبع التعديلات التي أجراها النموذج على الملفات.

package/concepts/ar/Tool-EnterPlanMode.md

@@ -0,0 +1,43 @@
+# EnterPlanMode
+
+## التعريف
+
+تحويل Claude Code إلى وضع التخطيط، لاستكشاف قاعدة الكود وتصميم الحلول قبل التنفيذ.
+
+## المعاملات
+
+لا توجد معاملات.
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- تنفيذ ميزات جديدة — تتطلب قرارات معمارية
+- وجود عدة حلول ممكنة — تتطلب اختيار المستخدم
+- تعديلات الكود تؤثر على السلوك أو البنية الحالية
+- تغييرات متعددة الملفات — قد تشمل أكثر من 2-3 ملفات
+- متطلبات غير واضحة — تحتاج استكشافاً أولاً لفهم النطاق
+- تفضيلات المستخدم مهمة — يمكن أن يكون للتنفيذ عدة اتجاهات معقولة
+
+**غير مناسب للاستخدام:**
+- إصلاحات سطر واحد أو أسطر قليلة (أخطاء إملائية، أخطاء واضحة)
+- المستخدم أعطى تعليمات محددة جداً
+- مهام البحث/الاستكشاف البحتة — يجب استخدام Task (نوع Explore)
+
+## السلوك في وضع التخطيط
+
+بعد الدخول في وضع التخطيط، يقوم Claude Code بـ:
+1. استخدام أدوات Glob وGrep وRead لاستكشاف قاعدة الكود بعمق
+2. فهم الأنماط والبنية المعمارية الحالية
+3. تصميم خطة التنفيذ
+4. تقديم الخطة للمستخدم للموافقة
+5. استخدام AskUserQuestion للتوضيح عند الحاجة
+6. الخروج عبر ExitPlanMode عندما تكون الخطة جاهزة
+
+## ملاحظات
+
+- تتطلب هذه الأداة موافقة المستخدم للدخول في وضع التخطيط
+- إذا لم تكن متأكداً من الحاجة للتخطيط، فضّل التخطيط — المواءمة المسبقة أفضل من إعادة العمل
+
+## الأهمية في cc-viewer
+
+يظهر استدعاء EnterPlanMode في سجل الطلبات ككتلة محتوى `tool_use`. بعد الدخول في وضع التخطيط، تتكون تسلسلات الطلبات عادة من استدعاءات أدوات استكشافية (Glob، Grep، Read) بشكل رئيسي، حتى يتم استدعاء ExitPlanMode.

package/concepts/ar/Tool-ExitPlanMode.md

@@ -0,0 +1,39 @@
+# ExitPlanMode
+
+## التعريف
+
+الخروج من وضع التخطيط وتقديم الخطة للمستخدم للموافقة. يُقرأ محتوى الخطة من ملف الخطة المكتوب مسبقاً.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `allowedPrompts` | array | لا | قائمة أوصاف الأذونات المطلوبة لخطة التنفيذ |
+
+كل عنصر في مصفوفة `allowedPrompts`:
+
+| الحقل | النوع | مطلوب | الوصف |
+|-------|-------|-------|-------|
+| `tool` | enum | نعم | الأداة المعنية، حالياً يُدعم فقط `Bash` |
+| `prompt` | string | نعم | وصف دلالي للعملية (مثل "run tests"، "install dependencies") |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- اكتملت الخطة في وضع التخطيط وجاهزة لتقديمها لموافقة المستخدم
+- يُستخدم فقط لمهام التنفيذ التي تتطلب كتابة كود
+
+**غير مناسب للاستخدام:**
+- مهام البحث/الاستكشاف البحتة — لا حاجة للخروج من وضع التخطيط
+- السؤال "هل الخطة مقبولة؟" — هذا بالضبط وظيفة هذه الأداة، لا تستخدم AskUserQuestion لذلك
+
+## ملاحظات
+
+- هذه الأداة لا تقبل محتوى الخطة كمعامل — تقرأ من ملف الخطة المكتوب مسبقاً
+- سيرى المستخدم محتوى ملف الخطة للموافقة
+- لا تستخدم AskUserQuestion قبل استدعاء هذه الأداة للسؤال "هل الخطة مقبولة"، فهذا تكرار
+- لا تذكر "الخطة" في الأسئلة، لأن المستخدم لا يرى محتوى الخطة قبل ExitPlanMode
+
+## الأهمية في cc-viewer
+
+يمثل استدعاء ExitPlanMode نهاية مرحلة التخطيط. في سجل الطلبات، تتحول الطلبات بعد هذا الاستدعاء عادة إلى عمليات تنفيذية (Edit، Write، Bash إلخ).

package/concepts/ar/Tool-Glob.md

@@ -0,0 +1,34 @@
+# Glob
+
+## التعريف
+
+أداة سريعة لمطابقة أنماط أسماء الملفات، تدعم قواعد الكود بأي حجم. تُرجع مسارات الملفات المطابقة مرتبة حسب وقت التعديل.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `pattern` | string | نعم | نمط glob (مثل `**/*.js`، `src/**/*.ts`) |
+| `path` | string | لا | دليل البحث، الافتراضي هو دليل العمل الحالي. لا تمرر "undefined" أو "null" |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- البحث عن الملفات بنمط اسم الملف
+- البحث عن جميع الملفات من نوع معين (مثل جميع ملفات `.tsx`)
+- تحديد موقع الملفات عند البحث عن تعريف فئة معينة (مثل `class Foo`)
+- يمكن إطلاق عدة استدعاءات Glob بالتوازي في رسالة واحدة
+
+**غير مناسب للاستخدام:**
+- البحث في محتوى الملفات — يجب استخدام Grep
+- الاستكشاف المفتوح الذي يتطلب جولات بحث متعددة — يجب استخدام Task (نوع Explore)
+
+## ملاحظات
+
+- يدعم صيغة glob القياسية: `*` يطابق مستوى واحد، `**` يطابق مستويات متعددة، `{}` يطابق خيارات متعددة
+- النتائج مرتبة حسب وقت التعديل
+- يُفضل استخدامه على أمر `find` في Bash
+
+## الأهمية في cc-viewer
+
+يظهر استدعاء Glob في سجل الطلبات كزوج من كتل محتوى `tool_use` / `tool_result`. يحتوي `tool_result` على قائمة مسارات الملفات المطابقة.

package/concepts/ar/Tool-Grep.md

@@ -0,0 +1,47 @@
+# Grep
+
+## التعريف
+
+أداة بحث قوية في المحتوى مبنية على ripgrep. تدعم التعبيرات النمطية وتصفية أنواع الملفات وأوضاع إخراج متعددة.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `pattern` | string | نعم | نمط بحث بتعبير نمطي |
+| `path` | string | لا | مسار البحث (ملف أو دليل)، الافتراضي هو دليل العمل الحالي |
+| `glob` | string | لا | تصفية أسماء الملفات (مثل `*.js`، `*.{ts,tsx}`) |
+| `type` | string | لا | تصفية نوع الملف (مثل `js`، `py`، `rust`)، أكثر كفاءة من glob |
+| `output_mode` | enum | لا | وضع الإخراج: `files_with_matches` (افتراضي)، `content`، `count` |
+| `-i` | boolean | لا | بحث غير حساس لحالة الأحرف |
+| `-n` | boolean | لا | عرض أرقام الأسطر (وضع content فقط)، الافتراضي true |
+| `-A` | number | لا | عدد الأسطر المعروضة بعد التطابق |
+| `-B` | number | لا | عدد الأسطر المعروضة قبل التطابق |
+| `-C` / `context` | number | لا | عدد الأسطر المعروضة قبل وبعد التطابق |
+| `head_limit` | number | لا | تحديد عدد نتائج الإخراج، الافتراضي 0 (بلا حدود) |
+| `offset` | number | لا | تخطي أول N نتيجة |
+| `multiline` | boolean | لا | تفعيل وضع المطابقة متعددة الأسطر، الافتراضي false |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- البحث عن سلاسل نصية أو أنماط محددة في قاعدة الكود
+- العثور على مواقع استخدام الدوال/المتغيرات
+- تصفية نتائج البحث حسب نوع الملف
+- إحصاء عدد التطابقات
+
+**غير مناسب للاستخدام:**
+- البحث عن الملفات بالاسم — يجب استخدام Glob
+- الاستكشاف المفتوح الذي يتطلب جولات بحث متعددة — يجب استخدام Task (نوع Explore)
+
+## ملاحظات
+
+- يستخدم صيغة ripgrep (وليس grep)، الأحرف الخاصة مثل الأقواس المعقوفة تحتاج إلى تهريب
+- وضع `files_with_matches` يُرجع مسارات الملفات فقط، وهو الأكثر كفاءة
+- وضع `content` يُرجع محتوى الأسطر المطابقة، مع دعم أسطر السياق
+- المطابقة متعددة الأسطر تتطلب تعيين `multiline: true`
+- يُفضل دائماً استخدام أداة Grep بدلاً من أمر `grep` أو `rg` في Bash
+
+## الأهمية في cc-viewer
+
+يظهر استدعاء Grep في سجل الطلبات كزوج من كتل محتوى `tool_use` / `tool_result`. يحتوي `tool_result` على نتائج البحث.

package/concepts/ar/Tool-NotebookEdit.md

@@ -0,0 +1,33 @@
+# NotebookEdit
+
+## التعريف
+
+استبدال أو إدراج أو حذف خلايا محددة في Jupyter notebook (ملفات .ipynb).
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `notebook_path` | string | نعم | المسار المطلق لملف notebook |
+| `new_source` | string | نعم | المحتوى الجديد للخلية |
+| `cell_id` | string | لا | معرف الخلية المراد تحريرها. في وضع الإدراج تُدرج الخلية الجديدة بعد هذا المعرف |
+| `cell_type` | enum | لا | نوع الخلية: `code` أو `markdown`. مطلوب في وضع الإدراج |
+| `edit_mode` | enum | لا | وضع التحرير: `replace` (افتراضي)، `insert`، `delete` |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- تعديل خلايا الكود أو markdown في Jupyter notebook
+- إضافة خلايا جديدة إلى notebook
+- حذف خلايا من notebook
+
+## ملاحظات
+
+- `cell_number` يبدأ من الصفر (0-indexed)
+- وضع `insert` يُدرج خلية جديدة في الموضع المحدد
+- وضع `delete` يحذف الخلية في الموضع المحدد
+- يجب أن يكون المسار مطلقاً
+
+## الأهمية في cc-viewer
+
+يظهر استدعاء NotebookEdit في سجل الطلبات ككتلة محتوى `tool_use`، تسجل عمليات التعديل المحددة على notebook.

package/concepts/ar/Tool-Read.md

@@ -0,0 +1,41 @@
+# Read
+
+## التعريف
+
+قراءة محتوى الملفات من نظام الملفات المحلي. يدعم الملفات النصية والصور وPDF وJupyter notebook.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `file_path` | string | نعم | المسار المطلق للملف |
+| `offset` | number | لا | رقم سطر البداية (للقراءة المجزأة للملفات الكبيرة) |
+| `limit` | number | لا | عدد الأسطر المقروءة (للقراءة المجزأة للملفات الكبيرة) |
+| `pages` | string | لا | نطاق صفحات PDF (مثل "1-5"، "3"، "10-20")، ينطبق فقط على PDF |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- قراءة ملفات الكود وملفات التكوين وغيرها من الملفات النصية
+- عرض ملفات الصور (Claude نموذج متعدد الوسائط)
+- قراءة مستندات PDF
+- قراءة Jupyter notebook (يُرجع جميع الخلايا مع مخرجاتها)
+- قراءة عدة ملفات بالتوازي للحصول على السياق
+
+**غير مناسب للاستخدام:**
+- قراءة الأدلة — يجب استخدام أمر `ls` في Bash
+- استكشاف مفتوح لقاعدة الكود — يجب استخدام Task (نوع Explore)
+
+## ملاحظات
+
+- يجب أن يكون المسار مطلقاً وليس نسبياً
+- يقرأ افتراضياً أول 2000 سطر من الملف
+- الأسطر التي تتجاوز 2000 حرف يتم اقتطاعها
+- المخرجات بتنسيق `cat -n`، أرقام الأسطر تبدأ من 1
+- ملفات PDF الكبيرة (أكثر من 10 صفحات) يجب تحديد معامل `pages`، بحد أقصى 20 صفحة في كل مرة
+- قراءة ملف غير موجود تُرجع خطأ (لا تتعطل)
+- يمكن استدعاء عدة Read بالتوازي في رسالة واحدة
+
+## الأهمية في cc-viewer
+
+يظهر استدعاء Read في سجل الطلبات كزوج من كتل محتوى `tool_use` (الاستدعاء) و`tool_result` (المحتوى المُرجع). يحتوي `tool_result` على المحتوى الفعلي للملف، ويمكن استخدامه لتحليل الملفات التي قرأها النموذج.

package/concepts/ar/Tool-Skill.md

@@ -0,0 +1,35 @@
+# Skill
+
+## التعريف
+
+تنفيذ مهارة (skill) في المحادثة الرئيسية. المهارات هي قدرات متخصصة يمكن للمستخدم استدعاؤها عبر أوامر slash (مثل `/commit`، `/review-pr`).
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `skill` | string | نعم | اسم المهارة (مثل "commit"، "review-pr"، "pdf") |
+| `args` | string | لا | معاملات المهارة |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- أدخل المستخدم أمر slash بتنسيق `/<skill-name>`
+- طلب المستخدم يتطابق مع وظيفة مهارة مسجلة
+
+**غير مناسب للاستخدام:**
+- أوامر CLI المدمجة (مثل `/help`، `/clear`)
+- مهارة قيد التشغيل بالفعل
+- اسم مهارة غير موجود في قائمة المهارات المتاحة
+
+## ملاحظات
+
+- بعد استدعاء المهارة تتوسع إلى prompt كامل
+- يدعم الأسماء المؤهلة بالكامل (مثل `ms-office-suite:pdf`)
+- قائمة المهارات المتاحة تُقدم في رسائل system-reminder
+- عند رؤية وسم `<command-name>` فهذا يعني أن المهارة محملة بالفعل، يجب التنفيذ مباشرة بدلاً من استدعاء هذه الأداة مرة أخرى
+- لا تذكر مهارة دون استدعاء الأداة فعلياً
+
+## الأهمية في cc-viewer
+
+يظهر استدعاء Skill في سجل الطلبات ككتلة محتوى `tool_use`. يؤثر prompt المهارة الموسع على system prompt أو محتوى الرسائل في الطلبات اللاحقة.

package/concepts/ar/Tool-Task.md

@@ -0,0 +1,53 @@
+# Task
+
+## التعريف
+
+بدء وكيل فرعي (SubAgent) لمعالجة المهام المعقدة متعددة الخطوات بشكل مستقل. الوكلاء الفرعيون هم عمليات فرعية مستقلة، لكل منها مجموعة أدوات وسياق مخصص.
+
+## المعاملات
+
+| المعامل | النوع | مطلوب | الوصف |
+|---------|-------|-------|-------|
+| `prompt` | string | نعم | وصف المهمة التي سينفذها الوكيل الفرعي |
+| `description` | string | نعم | ملخص مختصر من 3-5 كلمات |
+| `subagent_type` | string | نعم | نوع الوكيل الفرعي، يحدد مجموعة الأدوات المتاحة |
+| `model` | enum | لا | تحديد النموذج (sonnet / opus / haiku)، الافتراضي يرث من الأصل |
+| `max_turns` | integer | لا | الحد الأقصى لعدد الجولات |
+| `run_in_background` | boolean | لا | هل يعمل في الخلفية، المهام الخلفية تُرجع مسار output_file |
+| `resume` | string | لا | معرف الوكيل المراد استئنافه، يستمر من آخر تنفيذ |
+| `isolation` | enum | لا | وضع العزل، `worktree` ينشئ git worktree مؤقت |
+
+## أنواع الوكلاء الفرعيين
+
+| النوع | الغرض | الأدوات المتاحة |
+|-------|--------|----------------|
+| `Bash` | تنفيذ الأوامر، عمليات git | Bash |
+| `general-purpose` | مهام عامة متعددة الخطوات | جميع الأدوات |
+| `Explore` | استكشاف سريع لقاعدة الكود | جميع الأدوات باستثناء Task/Edit/Write/NotebookEdit/ExitPlanMode |
+| `Plan` | تصميم خطط التنفيذ | جميع الأدوات باستثناء Task/Edit/Write/NotebookEdit/ExitPlanMode |
+| `claude-code-guide` | أسئلة وأجوبة حول دليل استخدام Claude Code | Glob, Grep, Read, WebFetch, WebSearch |
+| `statusline-setup` | تكوين شريط الحالة | Read, Edit |
+
+## سيناريوهات الاستخدام
+
+**مناسب للاستخدام:**
+- المهام المعقدة التي تتطلب إنجازاً مستقلاً متعدد الخطوات
+- استكشاف قاعدة الكود والبحث المعمق (باستخدام نوع Explore)
+- العمل المتوازي الذي يتطلب بيئة معزولة
+- المهام طويلة المدة التي تحتاج للعمل في الخلفية
+
+**غير مناسب للاستخدام:**
+- قراءة مسار ملف محدد — استخدم Read أو Glob مباشرة
+- البحث في 2-3 ملفات معروفة — استخدم Read مباشرة
+- البحث عن تعريف فئة محددة — استخدم Glob مباشرة
+
+## ملاحظات
+
+- بعد اكتمال الوكيل الفرعي يُرجع رسالة واحدة، نتائجه غير مرئية للمستخدم ويحتاج الوكيل الرئيسي لنقلها
+- يمكن إطلاق عدة استدعاءات Task بالتوازي في رسالة واحدة لزيادة الكفاءة
+- يتم فحص تقدم المهام الخلفية عبر أداة TaskOutput
+- نوع Explore أبطأ من استدعاء Glob/Grep مباشرة، يُستخدم فقط عندما لا يكفي البحث البسيط
+
+## الأهمية في cc-viewer
+
+ينتج استدعاء Task سلسلة طلبات SubAgent، يمكن رؤية تسلسل طلبات فرعية مستقلة عن MainAgent في قائمة الطلبات. عادة ما تتميز طلبات SubAgent بـ system prompt مختصر وتعريفات أدوات أقل، مما يشكل تبايناً واضحاً مع MainAgent.