@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,294 @@
+---
+title: "قابلية الملاحظة"
+description: "تتبعات الوكيل، وعمليات التقييم، والتعليقات، وتجارب A/B، ولوحة التحكم المضمنة - كل ذلك بدون أي تكوين."
+---
+
+# إمكانية ملاحظة الوكيل
+
+يحصل كل تطبيق أصلي للوكيل على إمكانية المراقبة خارج الصندوق. تعمل عمليات التتبع والتقييمات التلقائية وتعليقات المستخدمين وتجارب A/B بدون تكوين - حيث تظل جميع البيانات موجودة في قاعدة بيانات SQL الخاصة بالتطبيق.
+
+تغطي هذه الصفحة مقاييس *جودة*الوكيل: التتبعات والتكلفة والتقييمات والتعليقات المخزنة في قاعدة بياناتك. بالنسبة لتحليلات _product_ (أحداث تطبيقك التي تتدفق إلى PostHog/Mixpanel/Amplitude)، راجع [Tracking](/docs/tracking).
+
+## ثلاثة أشياء تسمى "التقييمات"/"قابلية الملاحظة" — ما الذي أريده؟ {#which}
+
+من السهل الخلط بين هذه الصفحات الثلاث. اختر السؤال الذي تطرحه:
+
+| الصفحة                                                           | السؤال الذي يجيب عليه                                  | عند تشغيله                          | قلق            |
+| ---------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------- | -------------- |
+| **تقييمات إمكانية الملاحظة** (هذه الصفحة، علامة التبويب _Evals_) | "كيف كان أداء عمليات الإنتاج الحقيقية؟"                | سلبي، بعد كل جولة (عينة القاضي LLM) | الجودة         |
+| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`)                    | "هل يفعل الوكيل الشيء الصحيح بشأن هذا الإدخال الثابت؟" | بوابة CI/نشر نشطة وحتمية            | الجودة         |
+| **[Observational Memory](/docs/observational-memory)**           | "هل يظل هذا الخيط الطويل رخيصًا وداخل النافذة؟"        | ضغط الخلفية على المواضيع الطويلة    | التكلفة/السياق |
+
+تسجل كل من إمكانية المراقبة وبوابة تقييم CI _الجودة_ ولكن من طرفين متعاكسين - تسجيل سلبي لاحق لحركة المرور الحقيقية مقابل عمليات فحص النجاح/الفشل النشطة على المدخلات الثابتة. ذاكرة الملاحظة لا علاقة لها بالجودة؛ يتعلق الأمر بتكلفة الرمز المميز وضغط نافذة السياق.
+
+## ما يتم التقاطه تلقائيًا {#captured}
+
+عندما يرسل المستخدم رسالة، يسجل الإطار تلقائيًا:
+
+- **استخدام الرمز المميز** — الإدخال والإخراج وذاكرة التخزين المؤقت للقراءة والكتابة في ذاكرة التخزين المؤقت
+- **التكلفة** — يتم حسابها من أعداد الرموز المميزة وتسعير النماذج
+- **زمن الوصول** — إجمالي المدة والوقت لكل استدعاء للأداة
+- **استدعاءات الأداة** — التي تم استدعاء actions، وحالة النجاح/الخطأ، والمدة
+- **التقييمات التلقائية** — يتم حساب 5 نقاط جودة بعد كل جولة
+
+لا يلزم إجراء تغييرات على التعليمات البرمجية. يتم ربط الأجهزة بـ `production-agent.ts` بشفافية.
+
+```an-diagram title="Every run feeds the loop" summary="One agent run produces a trace, automated scores, and a feedback hook — all stored in the app's own SQL and surfaced on the dashboard. Experiments split traffic across config variants."
+{
+  "html": "<div class=\"obs-loop\"><div class=\"diagram-node\">Agent run<br><small class=\"diagram-muted\">production-agent.ts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Captured automatically</span><small class=\"diagram-muted\">tokens &middot; cost &middot; latency &middot; tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Traces &amp; spans</div><div class=\"diagram-box\">Evals (5 scorers + LLM judge)</div><div class=\"diagram-box\">Feedback &amp; frustration index</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Dashboard<br><small class=\"diagram-muted\">scoped to the signed-in user</small></div></div>",
+  "css": ".obs-loop{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.obs-loop .diagram-col{display:flex;flex-direction:column;gap:8px}.obs-loop .diagram-arrow{font-size:22px;line-height:1}.obs-loop .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## لوحة التحكم {#dashboard}
+
+أضف لوحة التحكم إلى أي قالب بمسار واحد:
+
+```tsx
+// app/routes/observability.tsx
+import { ObservabilityDashboard } from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+```
+
+يتم تحديد نطاق كافة البيانات للمستخدم الذي قام بتسجيل الدخول؛ لا يوجد عرض إداري عبر المستخدمين اليوم.
+
+تحتوي لوحة التحكم على 5 علامات تبويب:
+
+| علامة التبويب | ما يعرضه                                                                                        |
+| ------------- | ----------------------------------------------------------------------------------------------- |
+| **نظرة عامة** | المقاييس الرئيسية - التشغيل، والتكلفة، ووقت الاستجابة، ومعدل نجاح الأداة، والرضا، ودرجة التقييم |
+| **المحادثات** | تتبع القائمة مع الانتقال إلى النطاقات الفردية (agent_run، llm_call، tool_call)                  |
+| **التقييمات** | نتائج التقييم الآلي حسب المعايير والاتجاهات مع مرور الوقت                                       |
+| **التجارب**   | قائمة اختبار A/B مع شارات الحالة، ونتائج متغيرة مع فواصل الثقة                                  |
+| **التعليقات** | إبداء الإعجاب لأعلى/لأسفل، تصنيف الفئات، درجات الإحباط                                          |
+
+## تعليقات المستخدم {#feedback}
+
+### تعليقات صريحة
+
+تظهر أزرار إبهام لأعلى/لأسفل مضمنة في كل رسالة وكيل في الدردشة UI. يؤدي الإبهام لأسفل إلى فتح نافذة منبثقة للفئة (غير دقيقة، غير مفيدة، أداة خاطئة، بطيئة جدًا). يتم توصيل هذا إلى `AssistantChat.tsx` تلقائيًا.
+
+### تعليقات ضمنية (مؤشر الإحباط)
+
+يحسب إطار العمل مؤشر الإحباط (0-100) من إشارات المحادثة:
+
+| إشارة                | الوزن | ما يكتشفه                              |
+| -------------------- | ----- | -------------------------------------- |
+| إعادة الصياغة        | 30%   | يكرر المستخدم رسائل مشابهة             |
+| إعادة محاولة الأنماط | 20%   | "حاول مرة أخرى"، "لا، هذا خطأ"         |
+| الهجر                | 20%   | تنتهي الجلسة بعد وقت قصير من الاستجابة |
+| المشاعر              | 15%   | أنماط اللغة السلبية                    |
+| اتجاه الطول          | 15%   | تناقص طول الرسالة                      |
+
+تفسير النتيجة: 0-20 = صحي، 20-40 = احتكاك، 40-60 = غير راض، 60+ = جلسة معطلة.
+
+## التقييمات الآلية {#evals}
+
+يتم تشغيل خمسة مسجلين محددين بعد كل تشغيل للعميل:
+
+| المعايير            | ما يقيسه                                                  | نطاق النتائج |
+| ------------------- | --------------------------------------------------------- | ------------ |
+| `tool_success_rate` | % من استدعاءات الأداة بدون أخطاء                          | 0-1          |
+| `step_efficiency`   | يعاقب تكرارات LLM المفرطة لعمليات التشغيل باستخدام الأداة | 0-1          |
+| `latency_score`     | تمت التسوية مقابل 10 ثوانٍ/خط الأساس للأداة               | 0-1          |
+| `cost_efficiency`   | تمت التسوية مقابل خط الأساس للتكلفة                       | 0-1          |
+| `error_recovery`    | هل تعافى الوكيل من أخطاء الأداة؟                          | 0 أو 1       |
+
+### LLM-كقاضي (اختياري)
+
+تمكين التقييم المستند إلى LLM لعينات من خلال إعداد `evalSampleRate`:
+
+```ts
+import { putSetting } from "@agent-native/core/settings";
+
+await putSetting("observability-config", {
+  enabled: true,
+  evalSampleRate: 0.05, // 5% of runs
+});
+```
+
+تستخدم المعايير المخصصة قواعد اللغة الطبيعية:
+
+```ts
+const criteria = {
+  name: "helpfulness",
+  description: "Was the response helpful and complete?",
+  rubric: "0.0 = unhelpful, 0.5 = partially helpful, 1.0 = fully resolved",
+};
+```
+
+## تجارب أ/ب {#experiments}
+
+اختبر نماذج مختلفة، أو درجات حرارة، أو تكوينات وكيل:
+
+```ts
+// Create via API
+POST /_agent-native/observability/experiments
+{
+  "name": "model-a-vs-b",
+  "variants": [
+    { "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
+    { "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
+  ],
+  "metrics": ["cost", "latency", "satisfaction"]
+}
+
+// Start the experiment
+PUT /_agent-native/observability/experiments/:id
+{ "status": "running" }
+```
+
+استخدم معرفات الطراز الحقيقية التي يقبلها محركك بدلاً من `<your-model-id>` / `<other-model-id>` (تتغير أسماء الطرازات كثيرًا - تحقق من الموفر/المحرك الخاص بك لمعرفة المعرفات الحالية). تعمل حلقة الوكيل تلقائيًا على حل متغير المستخدم وتطبيق تجاوز التكوين. تستخدم المهمة تجزئة متسقة — يحصل المستخدم نفسه دائمًا على نفس المتغير.
+
+```an-diagram title="Consistent-hash variant assignment" summary="Each user hashes to a stable variant, the loop applies that variant's config override, and results roll up per variant with confidence intervals."
+{
+  "html": "<div class=\"exp\"><div class=\"diagram-node\">User id<br><small class=\"diagram-muted\">consistent hash</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill\">control &middot; 50%</span><small class=\"diagram-muted\">config override A</small></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">treatment &middot; 50%</span><small class=\"diagram-muted\">config override B</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Results per variant<br><small class=\"diagram-muted\">cost &middot; latency &middot; satisfaction</small></div></div>",
+  "css": ".exp{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.exp .diagram-col{display:flex;flex-direction:column;gap:8px}.exp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.exp .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## التكوين {#config}
+
+يتم تخزين كافة الإعدادات في مفتاح `observability-config`:
+
+```ts
+{
+  enabled: true,           // Master switch
+  capturePrompts: false,   // Store prompt content in traces
+  captureToolArgs: false,  // Store action input arguments
+  captureToolResults: false, // Store action results
+  evalSampleRate: 0,       // 0-1, fraction of runs to LLM-judge
+  exporters: []            // OTLP export targets
+}
+```
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Content is **redacted by default** — only token counts, costs, and timing are stored. `capturePrompts`, `captureToolArgs`, and `captureToolResults` are opt-in; turn them on only when you need prompt/argument content for debugging."
+}
+```
+
+## نقاط نهاية API {#api}
+
+جميعها مثبتة تلقائيًا في `/_agent-native/observability/`:
+
+| الطريقة | المسار                     | الغرض                               |
+| ------- | -------------------------- | ----------------------------------- |
+| GET     | `/`                        | نظرة عامة على الإحصائيات            |
+| GET     | `/traces`                  | سرد ملخصات التتبع                   |
+| GET     | `/traces/:runId`           | تتبع التفاصيل (الملخص + الامتدادات) |
+| GET     | `/traces/:runId/evals`     | تقييمات التشغيل                     |
+| POST    | `/feedback`                | إرسال تعليقات                       |
+| GET     | `/feedback`                | إدراج التعليقات                     |
+| GET     | `/feedback/stats`          | تجميع التعليقات                     |
+| GET     | `/satisfaction`            | نتائج الرضا                         |
+| GET     | `/evals/stats`             | إحصائيات التقييم                    |
+| POST    | `/experiments`             | إنشاء تجربة                         |
+| GET     | `/experiments`             | سرد التجارب                         |
+| GET     | `/experiments/:id`         | الحصول على تفاصيل التجربة           |
+| PUT     | `/experiments/:id`         | تحديث التجربة                       |
+| POST    | `/experiments/:id/results` | حساب النتائج                        |
+| GET     | `/experiments/:id/results` | الحصول على النتائج                  |
+
+تدعم جميع نقاط النهاية `?since=N` (الطابع الزمني مللي ثانية) ومعلمات الاستعلام `?limit=N`.
+
+## التصدير إلى منصات خارجية {#export}
+
+أرسل آثارًا إلى Langfuse، أو Datadog، أو Grafana، أو أي واجهة خلفية متوافقة مع OTel:
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  exporters: [
+    {
+      type: "otlp",
+      endpoint: "https://cloud.langfuse.com/api/public/otel",
+      headers: { Authorization: "Bearer sk-..." },
+    },
+  ],
+});
+```
+
+يصدر إطار العمل امتدادات اصطلاحات دلالية `gen_ai.*` متوافقة مع مواصفات OpenTelemetry GenAI.
+
+## امتدادات القياس عن بعد المفتوحة {#otel}
+
+بشكل منفصل عن تكوين `exporters` أعلاه (الذي يشحن التتبعات الداخلية إلى نقطة نهاية OTLP)، يمكن لحلقة الوكيل أيضًا إصدار **امتدادات OpenTelemetry المباشرة** لكل تشغيل واستدعاء نموذج واستدعاء أداة — بحيث يرى المضيف الذي يقوم بالفعل بتشغيل مجمع OTel نشاط الوكيل جنبًا إلى جنب مع بقية آثاره الموزعة.
+
+هذه الطبقة **اختيارية ولا يمكن تشغيلها افتراضيًا**:
+
+- `@opentelemetry/api` هي **تبعية اختيارية**. إذا لم يتم تثبيته، فإن المساعدين يتدهورون إلى عدم إجراء عمليات صامتة - لا يوجد شيء هنا على الإطلاق يدخل في حلقة الوكيل.
+- حتى عندما تكون حزمة واجهة برمجة التطبيقات \_ موجودة، فإنها تشحن أداة تتبع افتراضية بدون تشغيل. تصبح الامتدادات حقيقية فقط بمجرد قيام **المضيف بتسجيل `TracerProvider`** (عبر `@opentelemetry/sdk-node` أو ما شابه ذلك). لا يعتمد إطار العمل عمدًا **لا** على حزم SDK/المصدرين الثقيلة أو يقوم بتسجيل الموفر نفسه - يتم الاشتراك في الأجهزة من خلال تطبيق التضمين.
+
+لذا فإن التكلفة عند عدم توصيل OTel هي بضع قراءات للخصائص المخزنة مؤقتًا لكل مكالمة. لتشغيله، قم بتثبيت حزمة API بالإضافة إلى SDK الخاص بك وقم بتسجيل المزود عند بدء تشغيل الخادم بنفس الطريقة التي تفعلها مع أي خدمة Node أخرى.
+
+تصدر حلقة الوكيل ثلاثة أنواع من الامتداد:
+
+| امتداد      | متى                         | السمات                                                            |
+| ----------- | --------------------------- | ----------------------------------------------------------------- |
+| `agent.run` | مرة واحدة لكل وكيل          | `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model` |
+| `tool.call` | مرة واحدة لكل استدعاء إجراء | `tool.name`، بالإضافة إلى حالة النجاح/الخطأ                       |
+| `llm.call`  | لكل مكالمة نموذجية          | التوقيت + حالة موافق/خطأ                                          |
+
+تم الانتهاء من الامتدادات بحالة OK/ERROR وتسجيل رسالة الخطأ عند الفشل. يتم تقليم قيم السمات الصفرية/الحارسة حتى لا تزدحم الامتدادات بالضوضاء. تعتبر طبقة OTel هذه إضافة بحتة إلى جداول `agent_trace_spans` / `agent_trace_summaries` الداخلية التي تعمل على تشغيل لوحة المعلومات أعلاه - وكلاهما يتم إنتاجهما من نفس أحداث التشغيل.
+
+## الإبلاغ عن الأخطاء (Sentry) {#sentry}
+
+يتم الإبلاغ عن الأخطاء من جانب الخادم التي تهرب من معالجات التوجيه Nitro إلى Sentry عند تكوين DSN. بدونها، لا توجد عمليات لـ SDK بصمت، لذلك من الآمن ترك env vars بدون ضبط في dev. يمكن أن تنتقل أحداث المتصفح والخادم إلى نفس مشروع Sentry؛ قم بتقسيمها إلى مشاريع منفصلة فقط عندما تريد الفصل التشغيلي للملكية أو الحجم أو الحصص أو توجيه التنبيه.
+
+| السطح              | SDK               | إنف فار                                                           | ملاحظات                                                                          |
+| ------------------ | ----------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| المتصفح / SPA      | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`، أو `SENTRY_CLIENT_DSN`، أو `SENTRY_DSN` | يلتقط الأخطاء التي لم تتم معالجتها ومسارات التنقل لتغيير المسار في العميل.       |
+| خادم Nitro         | `@sentry/node`    | `SENTRY_SERVER_DSN` أو `SENTRY_DSN`                               | يلتقط استجابات 5xx وأخطاء دورة حياة Nitro. مستخدم لكل طلب.                       |
+| `agent-native` CLI | `@sentry/node`    | _hardcoded_                                                       | تقارير الأعطال من الإصدار الثنائي CLI المنشور؛ غير قابل للتكوين بواسطة المستخدم. |
+
+### التكوين من جانب الخادم {#sentry-config}
+
+قم بتعيين `SENTRY_SERVER_DSN` أو `SENTRY_DSN` المشترك في بيئة النشر (لوحة تحكم Netlify، أسرار Cloudflare، وما إلى ذلك). يقوم إطار العمل تلقائيًا بتثبيت المكون الإضافي Nitro الذي:
+
+1. استدعاء `Sentry.init` مرة واحدة عند بدء التشغيل (غير فعال - آمن للاتصال من مكونات إضافية متعددة).
+2. حل مشكلة المستخدم عبر `getSession(event)` في كل طلب API/إطار العمل وإرفاق `id` / `email` / `username` بالإضافة إلى علامة `orgId` بنطاق عزل Sentry لكل طلب. يتم تخطي مسارات الأصول الثابتة لتجنب زيارات قاعدة البيانات الإضافية.
+3. يلتقط كل مسار إطار عمل 5xx مع علامات `route` و`method` و`userAgent` القابلة للبحث.
+
+المقابض الاختيارية:
+
+- `SENTRY_SERVER_TRACES_SAMPLE_RATE` (عائم `0`–`1`) — الاشتراك في تتبع الأداء. الإعدادات الافتراضية هي `0` (الأخطاء فقط). يتم تثبيت القيم غير الصالحة على `0`.
+- `AGENT_NATIVE_RELEASE` — يتجاوز علامة `release`. الإعدادات الافتراضية هي `agent-native-server@<core-version>`.
+
+### القوالب
+
+يرث كل قالب هذا تلقائيًا - ولا يوجد شيء لاستيراده. بالنسبة لتطبيقات SSR، يقوم الخادم بإدخال برنامج نصي صغير لتكوين المتصفح عندما يكون `SENTRY_CLIENT_DSN` أو `VITE_SENTRY_CLIENT_DSN` أو `SENTRY_DSN` المشترك متاحًا في وقت التشغيل، لذلك لا يقتصر التقاط المتصفح على بيئة وقت البناء Vite. يمكن للنماذج التي تريد سلوكًا مخصصًا (علامات إضافية، DSN مختلفة لكل قالب، Sentry الذي يمكن تعطيله بشدة) أن تتجاوزها عن طريق تصدير المكون الإضافي الخاص بها من `server/plugins/sentry.ts`:
+
+```ts
+// server/plugins/sentry.ts
+import { createSentryPlugin } from "@agent-native/core/server";
+export default createSentryPlugin();
+```
+
+إن DSN المضمن في CLI مقصود - فالاحتياجات الثنائية المنشورة لتعطل هاتف المنزل بغض النظر عن البيئة التي تديره. لا تقوم وحدة الخادم أبدًا بترميز DSN بشكل ثابت لأنها تعمل داخل بيئات العملاء حيث يقرر المشغلون ما إذا كان يجب أن تصل الأخطاء إلى Sentry على الإطلاق.
+
+### الخصوصية وPII {#privacy}
+
+يتم تهيئة كل من الخادم وCLI باستخدام `sendDefaultPii: false` وخطاف `beforeSend` الذي يزيل:
+
+- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
+- `request.cookies`
+- `user.ip_address` (يتم جمعها تلقائيًا بدون موافقة)
+- `contexts.runtime_env` (لقطة بيئة العملية)
+- أي حدث يكون نوع استثناء المستوى الأعلى له هو `ValidationError` (يتم التعامل معه على أنه رفض متوقع لإدخال المستخدم، وليس خطأ).
+
+يتم الاحتفاظ بحقول الهوية التي تم تعيينها بشكل صريح عبر `setUser({ id, email, username })`.
+
+## ما هي الخطوة التالية
+
+- [**Tracking**](/docs/tracking) — تحليلات المنتج (PostHog، Mixpanel، Amplitude) لأحداث تطبيقك الخاصة
+- [**Actions**](/docs/actions) — العمليات التي تظهر كاستدعاءات أداة في التتبع
+- [**Security**](/docs/security) — تحديد نطاق البيانات ومعالجة بيانات الاعتماد

package/docs/content/locales/ar-SA/observational-memory.md

@@ -0,0 +1,77 @@
+---
+title: "ذاكرة الملاحظة"
+description: "ضغط الخلفية ثلاثي الطبقات (الخام الأخير → الملاحظات → الانعكاسات) الذي يحافظ على سلاسل العمليات الطويلة رخيصة الثمن ومستقرة في ذاكرة التخزين المؤقت دون لمس المحادثات القصيرة."
+---
+
+# ذاكرة الملاحظة
+
+يقوم مؤشر ترابط الوكيل طويل الأمد بتجميع نص ضخم: كل رسالة، وكل استدعاء أداة، وكل نتيجة. إن إعادة تشغيل هذا التاريخ بالكامل في النموذج عند كل منعطف أمر مكلف ويؤدي في النهاية إلى تفجير نافذة السياق. تعمل **ذاكرة المراقبة (OM)** على ضغط الجزء الأقدم من سلسلة طويلة في ملخص مؤرخ ومتعدد الطبقات بحيث يظل النموذج يعرف ما حدث - فقط بجزء بسيط من التكلفة الرمزية - بينما تظل أحدث المنعطفات حرفية.
+
+عملية OM تلقائية بالكامل ومخصصة للمالك. **لا تتأثر سلاسل الرسائل القصيرة**: حتى يتجاوز مؤشر الترابط عتبة الضغط الأولى، تكون OM غير قابلة للتشغيل ويكون السياق بايت مقابل بايت كما سيكون بدونه.
+
+## المستويات الثلاث {#tiers}
+
+يمثل OM خيطًا طويلًا مكونًا من ثلاث طبقات، من الأكثر تقطيرًا إلى الأحدث:
+
+| الطبقة                      | ما هو                                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------ |
+| **تأملات**                  | المستوى الأعلى، يتم تكثيفه من سجل المراقبة بمجرد أن يكبر. ملخص القوس الطويل.                           |
+| **الملاحظات**               | إدخالات كثيفة ومؤرخة تدمج مجموعة من الرسائل الأولية في سجل مضغوط لما حدث.                              |
+| **الرسائل الأولية الأخيرة** | يتم الاحتفاظ بآخر المنعطفات N **حرفيًا** — ولا يتم طيها مطلقًا — بحيث يرى الوكيل دائمًا السياق الأحدث. |
+
+```an-diagram title="Three tiers, distilled to recent" summary="The older prefix folds into dated observations and a long-arc reflection; only the most recent turns stay verbatim."
+{
+  "html": "<div class=\"om\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Reflections</span><small class=\"diagram-muted\">long-arc summary, condensed from the observation log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observations</span><small class=\"diagram-muted\">dense, dated entries folding stretches of raw messages</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Recent raw messages</span><small class=\"diagram-muted\">last N turns, kept <strong>verbatim</strong> — never folded</small></div></div>",
+  "css": ".om{display:flex;flex-direction:column-reverse;align-items:stretch;gap:8px}.om .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.om .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+في كل دورة، يقوم جانب القراءة بتجميع هذه العناصر في كتلة `[Observational Memory]` واحدة ذاتية التسمية والتي تحل محل البادئة القديمة الأولية، وتحافظ على نافذة الخام الحديثة سليمة، وتطلب من النموذج التعامل مع السجل المضغوط باعتباره موثوقًا (لا تقم بإعادة العمل المكتمل، وثق في القرارات والأسماء والتواريخ والحالة المسجلة).
+
+## كيفية عمل الضغط {#compaction}
+
+يتم تشغيل تمريرتين كخطوة **أطلق وانسى، أفضل جهد** _بعد_ منعطف نظيف، بحيث لا يضيفان أبدًا زمن انتقال إلى الاستجابة المرئية للمستخدم ويتم ابتلاع أي فشل:
+
+1. **المراقب** — بمجرد أن تتجاوز رسائل سلسلة المحادثات _unobserved_ عتبة رمز الملاحظة، يتم دمجها في إدخال مراقبة كثيف واحد.
+2. **العاكس** — بمجرد أن يتجاوز سجل المراقبة المستمرة حد رمز الانعكاس، يتم تكثيف الملاحظات في انعكاس عالي المستوى.
+
+```an-diagram title="Two best-effort passes after a clean turn" summary="Each pass no-ops below its threshold, so running the compactor every turn is cheap. Failures are swallowed and never add latency."
+{
+  "html": "<div class=\"om-pass\"><div class=\"diagram-node\">Clean turn ends<br><small class=\"diagram-muted\">fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observer</span><small class=\"diagram-muted\">unobserved tokens &gt; 30k? &rarr; fold into one observation</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Reflector</span><small class=\"diagram-muted\">observation log &gt; 40k? &rarr; condense into a reflection</small></div></div>",
+  "css": ".om-pass{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.om-pass .diagram-node,.om-pass .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.om-pass .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+كلاهما يمر بفترة عدم تنفيذ أقل من الحدود الخاصة بهما، لذا فإن استدعاء الضاغط بعد كل دورة يعد أمرًا رخيصًا. نظرًا لأن OM يستبدل البادئة الأولية المتطايرة بنص مضغوط ثابت، فإنه يحافظ أيضًا على المطالبة **ثابتة في ذاكرة التخزين المؤقت** عبر دورات سلسلة طويلة.
+
+تعيش بيانات OM في قاعدة بيانات SQL الخاصة بالتطبيق، والتي يتم تحديد نطاقها للمالك (والمؤسسة عند وجودها) - وهو نفس نموذج تحديد النطاق مثل بقية إطار العمل. ولا تتم مشاركته مطلقًا بين المستخدمين.
+
+## التكوين {#config}
+
+الافتراضيات متحفظة. يمكن للمشغل طلب الضغط في وقت النشر باستخدام متغيرات البيئة `AGENT_NATIVE_OM_*` (لا يلزم إعادة نشر رمز التطبيق)؛ دائمًا ما تعود القيمة غير الصالحة أو المفقودة إلى القيمة الافتراضية المسماة.
+
+| إنف فار                                       | الافتراضي | ما يتحكم فيه                                                                     |
+| --------------------------------------------- | --------- | -------------------------------------------------------------------------------- |
+| `AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD` | `30000`   | الرموز المميزة للرسائل غير الملحوظة التي تحفز المراقب على دمجها في ملاحظة واحدة. |
+| `AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD`  | `40000`   | رموز سجل المراقبة التي تؤدي إلى تكثيف العاكس في صورة انعكاس.                     |
+| `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`    | `12`      | كم عدد الرسائل الأحدث التي تظل حرفية (لا يتم دمجها أبدًا في ملاحظة).             |
+
+تحافظ أغطية إخراج المراقب والعاكس (4000/2000 رمزًا) على تمريرة ضغط واحدة من تلقاء نفسها مما يفسد الميزانية؛ يمكن ضبطها في التعليمات البرمجية عبر `resolveObservationalMemoryConfig({ ... })` ولكنها ليست مكشوفة للبيئة.
+
+> [!TIP]
+> خفض العتبات للضغط عاجلاً (خيوط طويلة أرخص، تلخيص أكثر قليلاً)؛ قم برفعها للحفاظ على المزيد من التاريخ الخام في السياق قبل ضغطه. قم بتعيين `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` على مستوى أعلى إذا كان سير العمل الخاص بك يحتاج إلى ذيل حرفي أطول.
+
+## عندما يبدأ {#when}
+
+يقوم OM فقط بتغيير سلوك سلاسل الرسائل الطويلة بما يكفي لإنتاج ملاحظة أو انعكاس واحد على الأقل. بشكل ملموس:
+
+- موضوع جديد أو قصير: لا توجد إدخالات OM حتى الآن → السياق هو النص العادي، دون تغيير.
+- خيط طويل تجاوز عتبة المراقبة: يتم استبدال البادئة الأقدم بكتلة `[Observational Memory]` المضغوطة، ويظل الذيل الخام الأخير حرفيًا، وينخفض استخدام الرمز المميز بشكل كبير.
+
+يُعد الحقن أفضل جهد وآمن للحدود - إذا تعذر العثور على نقطة قطع آمنة (على سبيل المثال، يوجد زوج معلق من استخدام الأداة/النتيجة عند حافة النافذة)، يقوم OM بحقن كتلة الذاكرة _additively_ بدون قطع بدلاً من المخاطرة بإسقاط نتيجة أداة معلقة.
+
+## ذات صلة
+
+- [**Using Your Agent**](/docs/using-your-agent) — حلقة العمل اليومية مع الوكيل بجوار تطبيقك.
+- [**Observability**](/docs/observability) — مقاييس الرمز المميز والتكلفة لكل عملية تشغيل، حيث تظهر مدخرات OM.
+- [**Custom Agents & Teams**](/docs/agent-teams) — تستفيد عمليات تشغيل الوكيل الفرعي الطويلة من نفس عملية الضغط.

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

@@ -0,0 +1,216 @@
+---
+title: "مفاتيح الإعداد وAPI"
+description: "قائمة التحقق من الإعداد للتهيئة التي يتم تشغيلها لأول مرة — مفاتيح API، وOAuth، واتصالات الموفر"
+---
+
+# التأهيل
+
+عندما تفتح تطبيقًا مبنيًا على إطار عمل الوكيل الأصلي لأول مرة، سترى
+**قائمة اختيار الإعداد** في الشريط الجانبي للوكيل. إنه يحافظ على إغلاق التكوين الذي يتم تشغيله لأول مرة
+إلى دردشة الوكيل: قم بتوصيل محرك الذكاء الاصطناعي، واختياريًا قم بتوجيه التطبيق إلى مشترك
+البنية الأساسية، وأضف مقدمي الخدمة فقط عندما تحتاج إليهم.
+
+```an-diagram title="The setup checklist" summary="Only Connect an AI engine is required. The panel tracks completion and auto-hides once everything required is done."
+{
+  "html": "<div class=\"ob\"><div class=\"diagram-card\"><span class=\"diagram-pill warn\">required</span><strong>Connect an AI engine</strong><small class=\"diagram-muted\">Connect Builder (one click) or paste an LLM key</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Database</strong><small class=\"diagram-muted\">set <code>DATABASE_URL</code></small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Authentication</strong><small class=\"diagram-muted\">OAuth / access token</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Email delivery</strong><small class=\"diagram-muted\">Resend / SendGrid</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">all required done &rarr; panel auto-hides</div></div>",
+  "css": ".ob{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.ob .diagram-card{display:flex;flex-direction:column;gap:3px;padding:12px 14px}.ob .diagram-arrow{font-size:22px}"
+}
+```
+
+## للمستخدمين النهائيين
+
+### ما ستراه
+
+- لوحة **إعداد** أعلى دردشة الوكيل مع قائمة تحقق مثل "Connect an AI"
+  المحرك"، "تسليم البريد الإلكتروني"، وما إلى ذلك.
+- يوضح العداد الموجود في الأعلى (على سبيل المثال، "1 من 4") عدد الخطوات الجاهزة.
+- تم توسيع الخطوة الحالية؛ تظهر الخطوات النهائية علامة الاختيار الخضراء والبقاء
+  يمكن قراءتها إذا قمت بفتحها.
+- تظهر الخطوات المطلوبة حبة حمراء صغيرة **مطلوبة**. تظل اللوحة مرئية
+  حتى اكتمال كل الخطوات المطلوبة.
+- بمجرد الانتهاء من كل ما هو مطلوب، تخفي اللوحة نفسها تلقائيًا.
+- يمكن طي اللوحة بأكملها بحيث تكون الشيفرون في أعلى اليمين، أو
+  مخفي بالكامل مع **إخفاء الإعداد** في الأسفل.
+
+### كيفية إكمال كل خطوة
+
+تقدم الخطوات واحدة أو أكثر من **الطرق** — طرق مختلفة لتحقيق نفس الهدف
+المتطلبات. يظهر المسار الأساسي أولاً؛ يتم الاحتفاظ بالمسارات الثانوية مضغوطة
+خلف المنتقي أو الكشف عندما تحتوي الخطوة على عدة موفري خدمات مكافئين.
+
+- **الاتصال بخدمة (نقرة واحدة)** — على سبيل المثال. _قم بتوصيل Builder_ بالجهاز المُدار
+  بوابة الذكاء الاصطناعي. انقر فوق الزر، وستفتح نافذة، وقم بتسجيل الدخول، وتغلق النافذة،
+  وتم وضع علامة اكتمال على الخطوة. لا توجد مفاتيح للنسخ.
+- **الصق مفتاح API أو املأ نموذجًا** — على سبيل المثال اختر موفر LLM وقاعدة البيانات
+  موفر OAuth، أو موفر البريد الإلكتروني، الصق القيمة (القيم)، وانقر على **حفظ**.
+  تستخدم الحقول السرية إدخال كلمة المرور، لذا لا تظهر القيمة على الشاشة. تم الحفظ
+  تنتقل القيم إلى `.env` المحلي (أو إعدادات مساحة العمل) - راجع
+  [Security](/docs/security) للمكان الذي يعيشون فيه.
+- **فتح رابط** — تشير بعض الخطوات إلى صفحة تسجيل الدخول أو المستندات. انقر
+  **تابع** وأكمل التدفق في علامة التبويب الجديدة.
+- **اسأل الوكيل** — توفر بضع خطوات خيار "السماح للوكيل بإعداده".
+  انقر عليه وسيقوم الوكيل بالرد عليك في الدردشة، ويرشدك خلال أي منها
+  الإعداد الخارجي (إنشاء بيانات اعتماد OAuth، وما إلى ذلك).
+
+### الخطوات المضمنة التي ستراها عادةً
+
+- **توصيل محرك الذكاء الاصطناعي** (مطلوب) — الخطوة الإلزامية الوحيدة. الاتصال
+  Builder لبوابة مُدارة بنقرة واحدة، أو افتح مفتاح الموفر الثانوي
+  منتقي ولصق مفتاح LLM الخاص بك.
+- **قاعدة البيانات** (اختياري) — قم بتعيين `DATABASE_URL` عندما تريد استخدام محدد
+  سلسلة اتصال قاعدة البيانات SQL.
+- **المصادقة** (اختياري) — تعمل حسابات البريد الإلكتروني/كلمة المرور المضمنة بواسطة
+  افتراضي. قم بإضافة OAuth أو تسجيل الدخول برمز الوصول فقط عندما تريد هذه المسارات.
+- **تسليم البريد الإلكتروني** (اختياري) — مفيد قبل النشر لإعادة تعيين كلمة المرور،
+  دعوات الفريق وإشعارات المشاركة. استخدم الموفر الذي تستخدمه بالفعل؛
+  يمكن تحقيق التنمية المحلية بدونها.
+
+يمكن للقوالب إضافة خطواتها الخاصة فوق هذه الخطوات - على سبيل المثال. قد يكون قالب CRM
+أضف "Connect Gmail"، وقد يضيف قالب المستندات "اختر مساحة عمل افتراضية". انظر
+[Authentication](/docs/authentication) للحصول على تفاصيل إعداد تسجيل الدخول.
+
+### الرجوع إلى قائمة التحقق
+
+إذا قمت بالضغط على **إخفاء الإعداد**، فستختفي اللوحة في جلسة المتصفح تلك.
+ستظهر الخطوات المطلوبة التي لم تكتمل بعد مرة أخرى عند التحميل التالي. مرة واحدة
+تم تنفيذ كل ما هو مطلوب، ويتم إخفاء اللوحة تلقائيًا نهائيًا - ولا يوجد شيء
+ما بقي للقيام به.
+
+## للمطورين
+
+إذا كنت تقوم بإنشاء نموذج، فعليك تسجيل خطوات الإعداد حتى تظهر في
+قائمة التحقق من الشريط الجانبي للمستخدم. يعالج الإطار العرض والإكمال
+التتبع والفصل - ما عليك سوى الإعلان عن الخطوة وكيف تتم
+راضي.
+
+النظام **مثبت تلقائيًا**. لا تحتاج القوالب إلى توصيل أي شيء للحصول عليها
+الخطوات الأربع المضمنة (LLM، قاعدة البيانات، المصادقة، البريد الإلكتروني). لإضافة تطبيق محدد
+الخطوات (Gmail، Slack، Notion، وما إلى ذلك)، اتصل بـ `registerOnboardingStep()` من
+المكون الإضافي للخادم.
+
+### المسارات المثبتة تلقائيًا
+
+جميع المسارات موجودة ضمن `/_agent-native/onboarding/`:
+
+| المسار                                              | الغرض                               |
+| --------------------------------------------------- | ----------------------------------- |
+| `GET /_agent-native/onboarding/steps`               | أدرج الخطوات مع حالة الإكمال        |
+| `POST /_agent-native/onboarding/steps/:id/complete` | وضع علامة على الخطوة مكتملة (تجاوز) |
+| `POST /_agent-native/onboarding/dismiss`            | رفض شعار الإعداد                    |
+| `POST /_agent-native/onboarding/reopen`             | مسح الرفض (إعادة إظهار اللوحة)      |
+| `GET /_agent-native/onboarding/dismissed`           | قراءة الفصل + العلامة الكاملة       |
+
+```an-api title="List onboarding steps"
+{
+  "method": "GET",
+  "path": "/_agent-native/onboarding/steps",
+  "summary": "List all registered steps with their completion status",
+  "description": "Drives the sidebar checklist — returns each step's id, title, methods, required flag, and whether `isComplete` currently passes.",
+  "responses": [
+    { "status": "200", "description": "Array of steps with completion status for the current user/app." }
+  ]
+}
+```
+
+### إضافة خطوة من القالب
+
+```an-annotated-code title="Registering a custom onboarding step"
+{
+  "filename": "server/plugins/my-onboarding.ts",
+  "language": "ts",
+  "code": "import { defineNitroPlugin } from \"@agent-native/core/server\";\nimport { registerOnboardingStep } from \"@agent-native/core/onboarding\";\nimport { listOAuthAccounts } from \"@agent-native/core/oauth-tokens\";\n\nexport default defineNitroPlugin(() => {\n  registerOnboardingStep({\n    id: \"gmail\",\n    order: 100,\n    title: \"Connect Gmail\",\n    description: \"Grant read/send access so the agent can work with email.\",\n    methods: [\n      {\n        id: \"oauth\",\n        kind: \"link\",\n        primary: true,\n        label: \"Sign in with Google\",\n        payload: { url: \"/_agent-native/google/auth-url?scope=mail\", external: false },\n      },\n      {\n        id: \"delegate\",\n        kind: \"agent-task\",\n        label: \"Let the agent set it up\",\n        badge: \"beta\",\n        payload: { prompt: \"Walk me through connecting Gmail. Set env vars as needed.\" },\n      },\n    ],\n    isComplete: async () => {\n      const accounts = await listOAuthAccounts(\"google\");\n      return accounts.length > 0;\n    },\n  });\n});",
+  "annotations": [
+    { "lines": "5", "label": "Auto-mounted", "note": "Register from a Nitro plugin — the framework handles rendering, completion tracking, and dismissal." },
+    { "lines": "7", "label": "Stable id", "note": "Re-registering with the same `id` after defaults load overrides a built-in step." },
+    { "lines": "12-19", "label": "Primary method", "note": "`primary: true` marks the big CTA. `kind: \"link\"` sends the user into the OAuth flow." },
+    { "lines": "20-26", "label": "Delegate path", "note": "`kind: \"agent-task\"` hands the setup to the agent chat with a prompt." },
+    { "lines": "28-31", "label": "Completion check", "note": "`isComplete` runs server-side. OAuth tokens live in the `oauth_tokens` store — check it, not `process.env.GMAIL_REFRESH_TOKEN`." }
+  ]
+}
+```
+
+### التحقق من اتصالات مساحة العمل أثناء الإعداد
+
+عند إنشاء قوالب تتفاعل مع الخدمات الخارجية (مثل Slack أو Google Workspace أو GitHub أو HubSpot)، يجب عليك التحقق مما إذا كانت مساحة العمل متصلة بالفعل ومنحت اتصال الموفر هذا بتطبيقك. وهذا يمنع المستخدمين من الاضطرار إلى تكرار بيانات الاعتماد (مثل مفاتيح API أو الرموز المميزة للتحديث) في متغيرات البيئة المحلية الخاصة بهم عند وجود اتصال مركزي مُدار.
+
+يمكنك التحقق من جاهزية الاتصال في رد الاتصال `isComplete` باستخدام كتالوج الاتصال APIs:
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+// Inside registerOnboardingStep:
+isComplete: async () => {
+  // Check if a managed workspace connection exists and is ready
+  const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+    appId: "mail",
+    templateUse: "mail",
+    provider: "gmail",
+  });
+  const connection = catalog.providers[0];
+
+  if (
+    connection?.readiness.status === "ready" &&
+    connection.workspaceConnection.grantState === "granted"
+  ) {
+    return true;
+  }
+
+  // Fall back to local environment variable check
+  return !!process.env.GMAIL_REFRESH_TOKEN;
+};
+```
+
+راجع وثائق [Workspace Connections](/docs/workspace-connections) للحصول على القائمة الكاملة لطرق كتالوج موفر الاتصال.
+
+### أنواع الطرق
+
+| النوع              | الحمولة                                               | يستخدم لـ                                        |
+| ------------------ | ----------------------------------------------------- | ------------------------------------------------ |
+| `link`             | `{ url, external? }`                                  | أرسل المستخدم إلى صفحة التدفق أو المستندات OAuth |
+| `form`             | `{ fields, writeScope? }`                             | اجمع env vars (المفاتيح، الأسرار، URLs)          |
+| `builder-cli-auth` | `{ scope: "llm" \| "browser" \| "image-generation" }` | Connect Builder (unlocks shared infra)           |
+| `agent-task`       | `{ prompt }`                                          | أرسل مطالبة إلى دردشة الوكيل للتعامل معها        |
+
+تشير علامة `primary: true` إلى الطريقة باعتبارها CTA الكبيرة لخطوتها.
+استخدم `badge: "soon"` بالإضافة إلى `disabled: true` عندما يكون مسار الإعداد مرئيًا
+قبل أن يصبح متاحًا.
+
+### الخطوات المضمنة
+
+| المعرف     | مطلوب | الوصف                                                      |
+| ---------- | ----- | ---------------------------------------------------------- |
+| `llm`      | نعم   | اتصال Builder أو مفتاح LLM للموفر                          |
+| `database` | لا    | قاعدة البيانات الافتراضية أو أي SQL `DATABASE_URL`         |
+| `auth`     | لا    | حسابات مدمجة، OAuth اختياري أو رمز وصول                    |
+| `email`    | لا    | إعادة إرسال أو SendGrid للبريد الإلكتروني الخاص بالمعاملات |
+
+يمكن تجاوز أي من هذه العناصر عن طريق إعادة التسجيل بنفس `id` بعد
+التحميل الافتراضي.
+
+### استخدام العميل
+
+اللوحة موجودة بالفعل داخل `<AgentPanel>`. لإنشاء تخطيط مخصص:
+
+```tsx
+import {
+  OnboardingPanel,
+  OnboardingBanner,
+  useOnboarding,
+} from "@agent-native/core/client/onboarding";
+
+function MySidebar() {
+  const { allComplete, dismissed, currentStepId } = useOnboarding();
+  if (allComplete || dismissed) return <Chat />;
+  return (
+    <>
+      <OnboardingPanel />
+      <Chat />
+    </>
+  );
+}
+```
+
+للحصول على معلومات أساسية عن مكان تخزين قيم الخطوات وكيفية التعامل مع الأسرار،
+راجع [Security](/docs/security). بالنسبة لنقاط اتصال مراسلة المستخدم النهائي (الدعوات،
+إعادة تعيين كلمة المرور) التي تعتمد على خطوة **تسليم البريد الإلكتروني**، راجع
+[Messaging](/docs/messaging).