@agent-native/core 0.87.0 → 0.90.1

package/docs/content/locales/ar-SA/data-programs.mdx

@@ -0,0 +1,329 @@
+---
+title: "برامج البيانات"
+description: "نصوص JS مخزَّنة يكتبها الـ agent، تقوم بجلب البيانات وربطها وتجميعها على الخادم، وتُخزَّن مؤقتًا في SQL، وتُعرض عبر لوحات الـ dashboard — الحل الوسط للبيانات الحية بين استعلام run-code لمرة واحدة و action مُبرمَج مسبقًا لمزود معين."
+search: "data program emit rows schema providerFetch dashboard panel program source refresh TTL viewer-scoped cache save-data-program run-data-program"
+---
+
+# برامج البيانات
+
+**برنامج البيانات (data program)** هو نص JS مسمّى ومخزَّن يكتبه الـ agent، يقوم بجلب البيانات أو ربطها أو تصفيتها أو تجميعها — عبر واجهات provider APIs باستخدام `providerFetch` / `providerFetchAll` / `providerSearchAll`، أو بيانات الـ app عبر `appAction`، أو ملفات workspace المستندة إلى Resources — ويستدعي `emit(rows, schema)` مرة واحدة بالضبط مع النتيجة. تُخزَّن النتيجة مؤقتًا في SQL، ويمكن لأي مكوّن رسم بياني/جدول عرضها، مع التحديث وفق سياسة تختارها بدلاً من إعادة الجلب في كل زيارة للصفحة.
+
+يتوفر تلقائيًا أينما كان [`run-code`](/docs/actions) متاحًا — لا حاجة لتثبيته أو إعداده لكل app. إذا كان run-code مفعّلًا بالفعل في تطبيقك، فإن `save-data-program`، و`preview-data-program`، و`run-data-program`، و`list-data-programs`، و`get-data-program`، و`delete-data-program` هي بالفعل actions مسجَّلة.
+
+<Diagram id="doc-block-dp-overview" title={"من استعلام مؤقت إلى لوحة حية"} summary={"يتحول نص run-code إلى برنامج مخزَّن بمجرد أن يستدعي emit(); يمكن لأي لوحة dashboard الارتباط به، وبعدها تتولى سياسة التخزين المؤقت/التحديث الأمر."}>
+
+```html
+<div class="dp-flow">
+  <div class="diagram-card" data-rough>
+    <span class="diagram-pill">run-code script</span
+    ><small class="diagram-muted">providerFetch, joins, aggregation</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel">
+    <span class="diagram-pill accent">emit(rows, schema)</span
+    ><small class="diagram-muted"
+      >save-data-program dry-runs, then persists</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    data_program_runs<br /><small class="diagram-muted"
+      >cached per (program, params, viewer)</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">لوحة Dashboard</span
+    ><small class="diagram-muted"><code>source: "program"</code></small>
+  </div>
+</div>
+```
+
+```css
+.dp-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dp-flow .diagram-card,
+.dp-flow .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
+  min-width: 180px;
+}
+.dp-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## لماذا يوجد هذا {#why}
+
+بدون برنامج بيانات مخزَّن، عادةً ما ينتهي "بناء عرض حي لـ X" في أحد مكانين سيئين:
+
+- **action مبرمَجة مسبقًا لكل نوع مزود/شكل استعلام.** هشّة، ولا يمكنها توقّع الخصائص المخصصة لكل عميل، أو ربط عبر مزودين مختلفين، أو فلتر عشوائي لم تفكر في دعمه.
+- **إعادة تشغيل منطق الجلب/الربط ذاته من الصفر في كل زيارة للصفحة.** بطيء، ويستهلك من جديد نفس حصة API الخاصة بالمزود كلما نظر أحدهم إلى رسم بياني.
+
+برنامج البيانات هو الحل الوسط: اكتب منطق الجلب/الربط/التجميع مرة واحدة كـ `run-code` عادي، احفظه، ودع سياسة التخزين المؤقت والتحديث تقرر عدد المرات التي يحتاج فيها فعليًا لإعادة التشغيل.
+
+## متى تستخدم واحدًا {#when-to-use-one}
+
+| الحالة                                                                                                                                  | الحل الأنسب                                                                         |
+| --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| يوجد بالفعل action من الدرجة الأولى لتجميع قياسي (فلتر `hubspot-deals` جاهز، مقياس مدمج)                                                | الـ action الموجودة — لا تُغلّفها ببرنامج                                           |
+| سؤال دردشة لمرة واحدة لن تنظر إليه مجددًا                                                                                               | استخدم `run-code` بسيط أو `provider-api-request` — أجب مباشرة، ولا تُخزّن شيئًا     |
+| يحتاج امتداد (extension) إلى أداة تفاعلية صغيرة لكل مستخدم بواجهتها الخاصة                                                              | [الامتدادات (Extensions)](/docs/extensions) — لا تملك برامج البيانات واجهة خاصة بها |
+| تحتاج مجموعة بيانات إلى فلتر خاصية عشوائي، أو بحث IN على قيم مخصصة، أو ربط بين مزودَين، **و**سيرغب أحدهم في رؤيتها مجددًا ببيانات حديثة | برنامج بيانات                                                                       |
+| يجب أن تعرض لوحة dashboard تلك النتيجة المرتبطة/المجمّعة وتتحدث وفق سياسة التخزين المؤقت                                                | برنامج بيانات مرتبط بلوحة `"program"`                                               |
+
+مقارنة مع الخيارات الأخرى على شاكلة run-code:
+
+|                                            | `run-code` لمرة واحدة      | action مبرمَجة مسبقًا لمزود                   | برنامج بيانات                                           |
+| ------------------------------------------ | -------------------------- | --------------------------------------------- | ------------------------------------------------------- |
+| **يستمر بين الاستدعاءات**                  | لا                         | غير قابل للتطبيق (هو نفسه الكود المصدري)      | نعم — سطر مخزَّن + تخزين مؤقت للنتيجة                   |
+| **النتيجة تُخزَّن مؤقتًا/تُحدَّث**         | لا، يُعاد تشغيله في كل مرة | لا يوجد تخزين مؤقت مدمج                       | نعم — `refreshMode`/`refreshTtlMs`                      |
+| **يتعامل مع فلاتر/روابط عشوائية**          | نعم، لكن تُهمَل بعد ذلك    | لا — محدود بما يكشفه schema الخاص بالـ action | نعم — لا يزال كودًا عاديًا                              |
+| **قابل للربط بلوحة dashboard**             | لا                         | فقط إذا بُني مصدر لوحة خصيصًا لذلك            | نعم — المصدر العام `"program"`                          |
+| **يتطلب نشرًا (deploy)**                   | لا                         | نعم (action جديدة = تغيير في الكود)           | لا — يُنشئه الـ agent وقت التشغيل                       |
+| **بيانات الاعتماد المستخدَمة عند القراءة** | بيانات المستدعي            | بيانات المستدعي                               | **بيانات المُشاهِد**، تُحل لكل عملية قراءة (انظر أدناه) |
+
+## سير عمل الكتابة {#authoring-workflow}
+
+1. **اصنع نموذجًا أوليًا في الدردشة أولاً.** اكتب منطق الجلب/الربط/التجميع كنص `run-code` عادي وتأكد من أنه يعيد الصفوف المتوقعة.
+2. **عدّله ليستدعي `emit(rows, schema?)` مرة واحدة بالضبط** في النهاية، بدلاً من إعادة النتيجة أو طباعتها.
+3. **احفظه** باستخدام `save-data-program`. هذا **يُجري تشغيلًا تجريبيًا (dry-run) للكود باستخدام `defaultParams` قبل الحفظ** ويرفض الحفظ بخطأ منظّم إذا فشل، بحيث لا يُخزَّن أبدًا برنامج معطوب. عند النجاح، تُعاد `{ programId, rowCount, columns, sampleRows }` — اعتبر ذلك دليلًا على أن البرنامج ينتج الصفوف المتوقعة قبل إخبار المستخدم بأنه جاهز.
+4. **اربط لوحة dashboard به**، أو استدعِ `run-data-program` مباشرة من مسار القراءة الخاص بك. لا يوجد أي ربط خاص بلوحات المعلومات مدمج في هذه البنية الأساسية نفسها — مصدر لوحة `"program"` الخاص بقالب analytics (أدناه) هو أحد أشكال التبني، وليس نمطًا إلزاميًا.
+5. **كرّر التجربة دون حفظ** عبر `preview-data-program({ code, params? })` — نفس مسار التشغيل التجريبي، دون سطر مخزَّن.
+
+### مثال واقعي
+
+لنفترض أن تطبيقًا يريد جدولًا حيًّا لـ"تذاكر الدعم عالية القيمة الأخيرة" مصدره مزود دعم، ومُصفًّى وفق عتبة لا تكشفها أي action مدمجة:
+
+```ts
+// The program's stored `code` — ordinary run-code, with one emit() call.
+const minValue = Number(params.minValue || 5000);
+
+const tickets = await providerFetchAll("acme-support", "/v1/tickets", {
+  query: { status: "open" },
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "next_cursor",
+    maxPages: 10,
+  },
+});
+
+const rows = (tickets.items || [])
+  .filter((t) => Number(t.contract_value || 0) >= minValue)
+  .map((t) => ({
+    ticket_id: t.id,
+    subject: t.subject,
+    account: t.account_name,
+    contract_value: Number(t.contract_value || 0),
+    opened_at: t.created_at,
+  }));
+
+emit(rows, [
+  { name: "ticket_id", type: "string" },
+  { name: "subject", type: "string" },
+  { name: "account", type: "string" },
+  { name: "contract_value", type: "number" },
+  { name: "opened_at", type: "string" },
+]);
+```
+
+حفظه:
+
+```ts
+await appAction("save-data-program", {
+  name: "high-value-open-tickets",
+  title: "High-Value Open Tickets",
+  description:
+    "Open support tickets above a configurable contract-value threshold.",
+  code: "/* the script above */",
+  defaultParams: { minValue: 5000 },
+  refreshMode: "ttl",
+  refreshTtlMs: 300_000,
+});
+```
+
+تحمل الاستجابة `{ programId, rowCount, columns, sampleRows }` — إثبات إتمام التشغيل التجريبي. من هناك، يعيد `run-data-program({ programId, params: { minValue: 10000 } })` تشغيله بعتبة مختلفة (أو يقدّم التخزين المؤقت)، ويمكن لأي لوحة dashboard الارتباط بـ `programId` بنفس الطريقة.
+
+## سطح الصندوق الرملي (sandbox) {#sandbox-surface}
+
+يعمل برنامج البيانات عبر نفس صندوق `executeSandboxCode` الرملي تمامًا الذي يستخدمه `run-code` — لا يوجد أي كود جديد خاص بالصندوق الرملي أو بيانات الاعتماد أو SSRF أو الحصص لهذه البنية الأساسية. يحصل على نفس المتغيرات العامة (`providerFetch`، `providerFetchAll`، `providerSearchAll`، `appAction`، `webFetch`، مساعدات Resources من نوع `workspace*`) بالإضافة إلى إضافتين من مقدمة صغيرة يحقنها الإطار (framework):
+
+- **`params`** — كائن عام **مجمَّد (frozen)** يحمل معاملات هذا التشغيل (`defaultParams` مدمجة مع ما تم تمريره إلى `run-data-program` أو واصف اللوحة). قراءته آمنة؛ تعديله يطلق خطأ.
+- **`emit(rows, schema?)`** — استدعِ هذا **مرة واحدة بالضبط**، في النهاية. الاستدعاء الثاني يطلق خطأ. يجب أن تكون `rows` مصفوفة من كائنات عادية (plain objects). `schema`، إن وُفّرت، تكون `{ name: string, type: string }[]`؛ وإن حُذفت يُستنتج من أول 50 صفًا (يكون العمود `"json"` إذا اختلفت الصفوف في النوع الأساسي ضمن العيّنة، وإلا فهو `"number"` / `"string"` / `"boolean"`). يبقى `console.log` حرًّا تمامًا لأغراض التصحيح — يلتقط المُشغِّل مخرجات stdout/stderr مجتمعة ولا يزيل سوى السطر الدال (sentinel) الذي يكتبه `emit()` عند تحليل النتيجة.
+
+الحدود المفروضة على كل تشغيل (غير قابلة للتهيئة لكل برنامج على حدة):
+
+| الحد                                                     | القيمة                                                                                                                                               |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| أقصى عدد صفوف يمكن إرسالها                               | 10,000 — تُحذف الصفوف الزائدة، `truncated: true`                                                                                                     |
+| أقصى حجم للنتيجة المُرسَلة                               | 4 ميبيبايت — تُحذف الصفوف من النهاية لتلائم الحد؛ صفّ واحد يتجاوز الحد يُعد فشلًا صارمًا من نوع `result_too_large`، إذ لا يوجد ما يمكن اقتطاعه بأمان |
+| أقصى عدد برامج نشطة (غير مؤرشفة) لكل تطبيق               | 200 — أرشِف غير المستخدَمة لتحرير مساحة                                                                                                              |
+| الحد الأدنى لمدة التحديث (TTL)                           | 60,000 مللي ثانية                                                                                                                                    |
+| عدد صفوف التشغيل المحفوظة لكل (برنامج، معاملات، مُشاهِد) | أحدث 5 — تُنظَّف الأقدم تلقائيًا مع كل عملية كتابة                                                                                                   |
+
+الاقتطاع دائمًا صريح (`truncated: true` في النتيجة) — لا يحدث إسقاط صامت أبدًا.
+
+## المعاملات وربط لوحة dashboard {#params-and-panel-binding}
+
+يمكن للبرامج الإعلان عن `paramsSchema` اختياري (JSON Schema يصف المعاملات المقبولة) و`defaultParams`. تتبنى لوحة dashboard مصدر `"program"` بوضع واصف JSON صغير في حقل الاستعلام الخاص باللوحة بدلاً من سلسلة استعلام:
+
+```json
+{ "programId": "dp_a1b2c3d4e5f6", "params": { "minValue": 10000 } }
+```
+
+تُعرض اللوحة عبر نفس مكونات الرسم البياني/الجدول تمامًا التي يستخدمها أي مصدر لوحة آخر — لا تتلقى سوى `{ rows, schema }` دائمًا. ربط لوحة ببرنامج هو ببساطة تحديد "أي برنامج مخزَّن، وبأي تجاوزات للمعاملات"؛ لا يوجد أي مسار تنفيذ خاص بلوحات المعلومات مكرَّر في مكان آخر.
+
+## دلالات التحديث ومدة الصلاحية (TTL) والتخزين المؤقت {#refresh-and-caching}
+
+لكل زوج `(programId, paramsHash)` سجل تشغيل خاص به في `data_program_runs`، ويضم `paramsHash` **المُشاهِد** أيضًا وليس المعاملات فقط (انظر قسم الأمان لمعرفة السبب). ما يحدث في كل قراءة:
+
+| الحالة                                                                            | السلوك                                                                                                                                                           |
+| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| تخزين مؤقت حديث (أحدث من `refreshTtlMs`، أو `refreshMode: "manual"` مع نجاح سابق) | يعيد الصفوف المخزَّنة مؤقتًا فورًا، `cacheHit: true`                                                                                                             |
+| التخزين المؤقت أقدم من مدة الصلاحية                                               | يُعاد تنفيذه بشكل متزامن — بميزانية 25 ثانية للقراءات المُطلَقة من عرض اللوحة، و120 ثانية لاستدعاءات الـ agent/اليدوية — ويستبدل التخزين المؤقت عند النجاح       |
+| `refreshMode: "manual"`                                                           | لا يتحدّث تلقائيًا أبدًا؛ فقط `forceRefresh: true` صريح (أو action تحديث يدوي من الواجهة) يعيد تشغيله                                                            |
+| لا يوجد تخزين مؤقت بعد                                                            | يُنفَّذ بشكل متزامن مثل أول جلب عادي                                                                                                                             |
+| برنامج `background: true`، دون تخزين مؤقت حديث                                    | يقدّم آخر تشغيل ناجح فورًا مع `stale: true` ويُدرج تنفيذًا خلفيًا معمِّرًا في قائمة الانتظار (ميزانية 10 دقائق)؛ استدعاء لاحق يُنهي النتيجة بمجرد اكتمال التنفيذ |
+| برنامج خلفي لا يزال قيد التشغيل، ودون نجاح سابق                                   | فشل `background_pending` — اعرض حالة صريحة "لا تزال قيد الحساب"، وليس نتيجة فارغة أبدًا                                                                          |
+| فشل التنفيذ (انتهاء مهلة، خطأ في الصندوق الرملي، شكل `emit()` غير صالح)           | فشل منظّم `{ code, message }`؛ إذا وُجد نجاح سابق، يُرفَق كـ `lastGoodRun` بحيث يمكن للوحة عرض بيانات قديمة بدلاً من أن تبقى فارغة                               |
+| البرنامج مؤرشَف (حذف ناعم عبر `delete-data-program`)                              | فشل صريح `archived` — لا تظهر أبدًا لوحة فارغة صامتة                                                                                                             |
+
+استخدم `background: true` فقط للبرامج التي تتجاوز باستمرار مهلة الواجهة الأمامية — روابط ضخمة متعددة المزودين، ترقيم صفحات عميق. يجب أن يبقى كل شيء آخر في الواجهة الأمامية: أبسط في التفكير ويقدّم بيانات حديثة أسرع.
+
+### لماذا يُحدَّد نطاق التخزين المؤقت وفق المُشاهِد {#per-viewer-cache}
+
+يحل `providerFetch` داخل أي برنامج المصادقة باستخدام **سياق الطلب الخاص بالمُشاهِد المستدعي نفسه** — وليس سياق مؤلف البرنامج أبدًا. هذا صحيح سواء جاء الاستدعاء من الـ agent، أو من استدعاء `run-data-program`، أو من لوحة dashboard يشاهدها زميل في الفريق. يمكن لمشاهدَين مختلفين يشغّلان نفس البرنامج بنفس المعاملات الحصول شرعيًا على نتيجتين مختلفتين: أحدهما لديه مفتاح HubSpot مُعدّ والآخر ليس لديه، أو تختلف أذونات المزود على مستوى الصف حسب الشخص.
+
+لهذا السبب، يضم `hashDataProgramParams` هوية المستدعي إلى مفتاح التخزين المؤقت إلى جانب المعاملات المُوحَّدة الشكل. هذا الأمر مهم بشكل خاص في **لوحات المعلومات المشتركة**: لو كان التخزين المؤقت مفهرَسًا بالمعاملات فقط، لكان أول شخص يشاهد لوحة يحدد بصمت ما سيراه كل مشاهد آخر، بمن فيهم مشاهد لا يملك بيانات الاعتماد التي أنتجت تلك النتيجة المخزَّنة مؤقتًا. تحديد النطاق حسب المُشاهِد يعني أن زميلًا في الفريق يفتقر إلى بيانات اعتماد سيرى خطأ المصادقة الخاص به على تلك اللوحة، وليس بيانات شخص آخر.
+
+## نموذج الأمان {#security}
+
+<Callout id="doc-block-dp-security" tone="success">
+
+**لا تصل رموز (tokens) المزوّد الخام إلى النموذج أو المتصفح أبدًا.** الشيء الوحيد الذي يغادر الصندوق الرملي هو `{ rows, schema }` الذي ينتجه استدعاء `emit()` — نفس حدود الثقة المطبَّقة على أي تنفيذ run-code آخر وأي مصدر لوحة dashboard آخر.
+
+</Callout>
+
+- **من جانب الخادم فقط.** يُنفَّذ كود برنامج البيانات حصريًا داخل `executeSandboxCode` على الخادم. لا يُرسَل إلى المتصفح أو النموذج لا الكود المصدري المخزَّن ولا أي بيانات اعتماد يلمسها — يُرسَل فقط الصفوف/schema المُرسَلة وبيانات وصفية مضغوطة عن التشغيل (عدد الصفوف، الأعمدة، صفوف عيّنة).
+- **بيانات الاعتماد هي دائمًا بيانات المُشاهِد المستدعي، وليست أبدًا بيانات المؤلف الأصلي للبرنامج.** انظر [دلالات التحديث ومدة الصلاحية والتخزين المؤقت](#per-viewer-cache) أعلاه لمعرفة سبب تحديد ذلك أيضًا لمفتاح التخزين المؤقت.
+- **`allowPublic: false` هو ثابت صارم، وليس قيمة افتراضية.** تُسجَّل برامج البيانات في سجل المشاركة بنفس طريقة [الامتدادات](/docs/extensions#security)، مع تعطيل المشاركة العامة. سيسمح برنامج عام لأي مستخدم موثَّق بتشغيل كود مخزَّن عشوائي تحت رمزه الخاص — مشاركة برنامج محصورة بمؤسستك، وتعني دائمًا فقط "يمكن لزملاء الفريق مشاهدة نتيجته المخزَّنة مؤقتًا وتشغيل إعادة تنفيذ"، وليس أبدًا أن "الإنترنت العام يمكنه تنفيذه."
+- **لا يمكن استدعاء actions التغيير والتنفيذ كأدوات من جسر الامتداد/iframe المعزول.** `save-data-program`، و`preview-data-program`، و`run-data-program`، و`delete-data-program` جميعها `toolCallable: false` — فقط الـ agent أو مسار قراءة من جانب الخادم يمكنه استدعاؤها، ولا يمكن أبدًا لـ iframe امتداد ضمن جلسة الفاتح استدعاؤها. `list-data-programs` و`get-data-program` للقراءة فقط ومحدَّدة النطاق بنفس مساعدات المشاركة المستخدَمة لأي مورد قابل للامتلاك (ownable) آخر.
+- **البرامج محدَّدة النطاق بالتطبيق الذي أنشأها.** تمرير `appId` إلى عملية بحث يعني أن برنامجًا أُنشئ في تطبيق واحد غير قابل للتشغيل من دردشة agent تطبيق آخر في نشر قاعدة بيانات مشتركة، حتى لو كان المستدعي يملك خلاف ذلك وصولًا على مستوى الصف (مالك/مؤسسة/مشاركة) إليه.
+- **اربط أو شاهد فقط برنامجًا تثق به.** بما أن التنفيذ يستخدم دائمًا بيانات اعتماد المُشاهِد نفسه، فإن مشاهدة نتيجة برنامج مشترك تشبه تمامًا فتح امتداد شخص آخر — الثقة يجب أن تكون في الكود نفسه، وليس فقط في منح الوصول.
+
+## مثال Risk Meeting العملي {#risk-meeting-example}
+
+يتضمن قالب analytics دراسة حالة عملية وقابلة للتشغيل: يقوم action الـ `ensure-risk-meeting-dashboard` بتثبيت برنامجَي بيانات بشكل متكرر الأثر (idempotent) بالإضافة إلى لوحة "Risk Meeting" ذات لوحتين، موضّحًا ثلاثة أمور لا يمكن لـ action مبرمَجة مسبقًا توقّعها لكل عميل.
+
+<FileTree
+  id="doc-block-dp-risk-meeting-files"
+  title={"مثبّت Risk Meeting"}
+  entries={[
+    {
+      path: "templates/analytics/actions/ensure-risk-meeting-dashboard.ts",
+      note: "action متكررة الأثر: تُحدّث كلا البرنامجين بالاسم الثابت، ثم لوحة المعلومات بالمعرّف",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-cohort.js",
+      note: "حمولة برنامج مخزَّنة — نص JS خام، وليس ملف مصدر بناء (build)",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-pylon-early-warning.js",
+      note: "برنامج الإنذار المبكر المكمّل",
+    },
+  ]}
+/>
+
+**`risk-meeting-cohort.js`** — يبحث عن مجموعة قابلة للتهيئة من صفقات CRM بخاصية `risk_status` عشوائية (بحث IN على قيم مخصصة لا يمكن لـ action جاهزة توقّعه)، ويحل شركة كل صفقة عبر بحث ارتباط مُجزّأ (batched)، ويحل نطاق (domain) كل شركة، ويجلب معنويات حساب من مزوّد ثانٍ غير مرتبط، ويربط الاثنين حسب النطاق:
+
+```js
+// params: { riskStatuses?: string[], enterpriseOnly?: boolean }
+const riskStatuses = params.riskStatuses?.length
+  ? params.riskStatuses
+  : ["On the Radar", "Churn Risk", "Confirmed Churn", "No Save Attempted"];
+
+// 1. Arbitrary property IN-search — not expressible through a canned filter.
+const dealSearch = await providerFetchAll("crm-provider", "/deals/search", {
+  method: "POST",
+  body: {
+    filterGroups: [
+      {
+        filters: [
+          { propertyName: "risk_status", operator: "IN", values: riskStatuses },
+        ],
+      },
+    ],
+  },
+  itemsPath: "results",
+  pagination: {
+    cursorBodyPath: "after",
+    nextCursorPath: "paging.next.after",
+    maxPages: 20,
+  },
+});
+
+// 2-3. Batched deal -> company -> domain resolution (elided here; see the
+// real seed file for the full batching helper).
+
+// 4. A second, unrelated provider — zero bespoke glue action required.
+const accounts = await providerFetchAll("support-provider", "/accounts", {
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "pagination.cursor",
+    maxPages: 20,
+  },
+});
+
+// 5. Join + emit.
+const rows = dealSearch.items.map((deal) => ({
+  deal_id: deal.id,
+  risk_status: deal.properties.risk_status,
+  arr: Number(deal.properties.total_contract_value || 0),
+  // ...domain lookup + sentiment join...
+}));
+
+emit(rows, [
+  { name: "deal_id", type: "string" },
+  { name: "risk_status", type: "string" },
+  { name: "arr", type: "number" },
+]);
+```
+
+**`risk-meeting-pylon-early-warning.js`** — العرض المكمّل: الحسابات التي حُددت بالفعل كمعرَّضة للخطر بحسب معنويات الدعم والتي **لم تظهر بعد** في مجموعة CRM أعلاه. هذه الفجوة — إشارة دعم تسبق إشارة CRM — تتطلب استبعاد مجموعة مزوّد واحد من مجموعة مزوّد آخر، وهو بالضبط نوع منطق المجموعات عبر المزودين الذي لا يمكن لأي action خاصة بمزوّد واحد التعبير عنه.
+
+يُثبَّت البرنامجان ويُحافَظ عليهما محدَّثين بواسطة `ensure-risk-meeting-dashboard`، والذي:
+
+- يُحدّث كل برنامج حسب `name` الثابت الخاص به، بحيث تؤدي إعادة تشغيل المثبّت إلى تحديث نفس الصفوف بدلاً من تكرارها.
+- لا يتطلب بيانات اعتماد CRM/الدعم وقت التثبيت — تُحل مصادقة المزوّد حسب المُشاهِد فقط عندما تُعرض لوحة فعليًا أو يُستدعى `run-data-program`، بما يتسق مع تحديد نطاق التخزين المؤقت حسب المُشاهِد أعلاه.
+- يبني لوحة معلومات ذات لوحتين تستخدم لوحاتها `source: "program"`، مرتبطة بمعرّف كل برنامج.
+
+راجع skill المسمّاة `data-programs` للحصول على الكود الكامل الموضَّح بالتعليقات.
+
+## كيف تتبنى تطبيقات أخرى مصدر اللوحة {#adopting-the-panel-source}
+
+مصدر لوحة dashboard من نوع `"program"` هو أحد أشكال تبنّي هذه البنية الأساسية، مُنفَّذ بالكامل في طبقة استعلام اللوحات الخاصة بالتطبيق المضيف نفسه — لا يوجد أي شيء خاص بلوحات المعلومات مدمج في `@agent-native/core/data-programs` نفسها. تطبيق قالب analytics هو مرجع مفيد لربط تطبيقك الخاص:
+
+- يحمل عمود `sql` الخاص باللوحة واصف JSON صغير — `{ programId, params? }` — بدلاً من سلسلة استعلام.
+- يستدعي عرض اللوحة `runDataProgram` مع `triggeredBy: "panel_view"` وهوية المُشاهِد الحالي، بحيث يُطبَّق التخزين المؤقت حسب المُشاهِد وحل بيانات الاعتماد تلقائيًا.
+- عند النجاح، تحصل اللوحة على `{ rows, schema }` — بنفس الشكل الذي يعيده أي مصدر لوحة آخر، بحيث يتدفق دون تعديل عبر مكونات الرسم البياني/الجدول الحالية.
+- عند الفشل، يُفضَّل `lastGoodRun` على لوحة معطوبة كلما وُجد؛ فقط عند عدم وجود نجاح سابق تعرض اللوحة خطأً منظّمًا (مع نص أكثر ودّية لرموز شائعة مثل `access_denied`، و`archived`، و`background_pending`).
+
+يمكن لأي تطبيق تنفيذ نفس التبنّي للوحات المعلومات/الجداول الخاصة به: استدعِ `run-data-program` (أو `runDataProgram` مباشرة إذا كنت ضمن نفس عملية الخادم) من مسار القراءة الخاص بك، ومرِّر `rows`/`schema` المُعادة إلى مكونات العرض الخاصة بك.
+
+## مستندات ذات صلة {#related}
+
+- [الامتدادات](/docs/extensions) — البنية الأساسية للتطبيقات المصغّرة المعزولة التي تشارك برامج البيانات معها وضعية أمان ونموذج مشاركة، لكن بواجهة خاصة بها.
+- [Actions](/docs/actions) — قواعد `run-code` والمتغيرات العامة للصندوق الرملي (`providerFetch`، `appAction`، إلخ) التي بُنيت عليها برامج البيانات.
+- [المشاركة والخصوصية](/docs/sharing) — نموذج المشاركة الداخلي للمؤسسة، وغير العام أبدًا، الذي تستخدمه برامج البيانات.
+- [الأمان](/docs/security) — ثوابت الإطار الخاصة بمعالجة بيانات الاعتماد وتحديد نطاق الوصول.

package/docs/content/locales/ar-SA/deployment.mdx

@@ -384,24 +384,23 @@ openssl rand -hex 32
 ## أدوات وكيل الإنتاج {#production-agent-tools}
 
 يحصل وكلاء الإنتاج على أدوات إطار العمل actions بالإضافة إلى أدوات إطار العمل المسجلة للتطبيق من
-المكون الإضافي للدردشة مع الوكيل. يتم تمكين عمليات الكتابة في قاعدة البيانات افتراضيًا لأن قاعدة البيانات الأولية
-يتم تحديد نطاق الأدوات ليشمل المستخدم/المؤسسة التي تمت مصادقتها، ولكن يمكن لمالكي التطبيق تضييق نطاق
-السطح عندما يجب أن يكون النشر أكثر رأيًا:
+المكون الإضافي للدردشة مع الوكيل. يتم تمكين فحص SQL افتراضيًا، بينما تمر
+عمليات الكتابة عبر actions التطبيق المكتوبة ما لم يشترك التطبيق صراحة في أدوات الكتابة الخام:
 
 ```ts
 // server/plugins/agent-chat.ts
 export default createAgentChatPlugin({
-  // Default: "write" (also true)
+  // Default: "read"
   databaseTools: "read", // "write" | "read" | "off"
   extensionTools: false,
 });
 ```
 
-- `databaseTools: "write"` — افتراضي. يسجل `db-schema`، `db-query`،
-  `db-exec`، و`db-patch`. يتم تحديد نطاق عمليات الكتابة للمستخدم/المؤسسة الحالية و
-  تم حظر تغييرات المخطط.
-- `databaseTools: "read"` — يُسجل `db-schema` و`db-query` فقط؛ وكلاء
-  افحص البيانات باستخدام SQL ولكن يجب استخدام التطبيق المكتوب actions للكتابة.
+- `databaseTools: "read"` — افتراضي. يُسجل `db-schema` و`db-query` فقط؛
+  يفحص الوكلاء البيانات باستخدام SQL ويجب أن يستخدموا actions التطبيق المكتوبة للكتابة.
+- `databaseTools: "write"` أو `true` — يسجل أيضًا `db-exec` و`db-patch`
+  للصيانة الخام المقصودة. يتم تحديد نطاق عمليات الكتابة للمستخدم/المؤسسة الحالية
+  ويتم حظر تغييرات المخطط.
 - `databaseTools: "off"` أو `false` — يزيل أدوات قاعدة البيانات الأولية من
   سطح الوكيل، لذا فإن actions الخاص بالتطبيق هو المسار الوحيد للوصول إلى البيانات.
 - `extensionTools: false` — يزيل إدارة امتداد إطار العمل actions و

package/docs/content/locales/ar-SA/extensions.mdx

@@ -34,7 +34,7 @@ description: "التطبيقات المصغرة التي ينشئها المست
     <div class="ext-helpers">
       <span class="diagram-pill">appAction</span
       ><span class="diagram-pill">appFetch</span
-      ><span class="diagram-pill">dbQuery / dbExec</span
+      ><span class="diagram-pill">dbQuery</span
       ><span class="diagram-pill">extensionData</span
       ><span class="diagram-pill">extensionFetch</span>
     </div>
@@ -227,7 +227,7 @@ description: "التطبيقات المصغرة التي ينشئها المست
 | `appAction(name, params)`                        | اتصل بأي من قوالب المضيف actions                                 | `appAction('list-emails', { view: 'inbox' })`             |
 | `appFetch(path, options)`                        | استدعاء نقاط نهاية إطار العمل المسموح بها ضمن `/_agent-native/*` | `appFetch('/_agent-native/application-state/navigation')` |
 | `dbQuery(sql, args)`                             | القراءة من SQL (يتم تحديد نطاقها تلقائيًا للمستخدم)              | `dbQuery('SELECT id, name FROM tools')`                   |
-| `dbExec(sql, args)`                              | اكتب إلى SQL                                                     | `dbExec('INSERT INTO ...')`                               |
+| `dbExec(sql, args)`                              | Legacy trusted SQL writes for editor/admin extensions            | Prefer `appAction` for app data writes                    |
 | `extensionFetch(url, options)`                   | اضغط على APIs الخارجية من خلال وكيل آمن به أسرار                 | `extensionFetch('https://api.github.com/user')`           |
 | `extensionData.set(collection, id, data, opts?)` | استمرار البيانات لكل ملحق (نطاق المستخدم/المؤسسة)                | `extensionData.set('notes', id, { text: '...' })`         |
 | `extensionData.list(collection, opts?)`          | قائمة العناصر المستمرة                                           | `extensionData.list('notes', { scope: 'all' })`           |
@@ -397,7 +397,7 @@ extensions/
 
 - يتوفر `extensionData` لحالة وقت التشغيل الصغيرة ما لم يتم تعطيله.
 - يجب إدراج مكالمات `appAction` بوضوح في `permissions.appActions`.
-- تم حظر `dbQuery` و`dbExec` و`extensionFetch` في الوقت الحالي.
+- تم حظر `dbQuery` و`extensionFetch` في الوقت الحالي.
 - يعرض التحديث المدعوم من SQL والحذف والمشاركة والمحفوظات actions رسالة مفادها
   يشير مرة أخرى إلى ملف الإدخال المحلي.
 
@@ -430,6 +430,8 @@ extensions/
 
 القاعدة الأساسية: **إذا كان ذلك لمستخدم واحد أو لفريق واحد، فهو امتداد. ** إذا كان كل مستخدم للقالب يريد الحصول عليه، قم بشحنه كميزة حقيقية.
 
+لجلب بيانات مخصص يجب أن يغذّي رسومًا بيانية وجداولًا أصلية بدلاً من واجهة أداة مخصصة، راجع [برامج البيانات](/docs/data-programs) — نص `run-code` مخزَّن وقابل للتحديث ترتبط به لوحات dashboard مباشرة، دون أي iframe امتداد.
+
 ## الأمان {#security}
 
 <Callout id="doc-block-frp4nq" tone="success">
@@ -444,7 +446,7 @@ extensions/
 - **الحقن السري من جانب الخادم** عبر قالب `${keys.NAME}` — قيمة المفتاح الفعلية لا تصل أبدًا إلى المتصفح.
 - **أسرار النطاق المقفل** — يرتبط كل مفتاح بالقائمة المسموح بها URL؛ يرفض الوكيل الطلبات المقدمة إلى المضيفين الآخرين.
 - **حماية الشبكة الخاصة** — لا يمكن للملحقات الوصول إلى العناوين الداخلية.
-- **المصادقة مطلوبة** — يتم تشغيل الإضافات فقط للمستخدمين الذين قاموا بتسجيل الدخول، ويتم تحديد نطاق مكالمات `dbQuery` / `dbExec` تلقائيًا.
+- **المصادقة مطلوبة** — يتم تشغيل الإضافات فقط للمستخدمين الذين قاموا بتسجيل الدخول، ويتم تحديد نطاق مكالمات `dbQuery` تلقائيًا.
 
 ## بعض الأشياء التي يجب معرفتها حول التسمية {#naming-back-compat}
 

package/docs/content/locales/ar-SA/key-concepts.mdx

@@ -240,19 +240,16 @@ export const forms = table("forms", {
 ```
 
 ```bash
-# الإجراءات الأساسية للفحص السريع لقاعدة البيانات والصيانة لمرة واحدة
+# الإجراءات الأساسية للفحص السريع لقاعدة البيانات
 pnpm action db-schema                                       # show all tables
 pnpm action db-query --sql "SELECT * FROM forms"
-pnpm action db-exec --sql "UPDATE forms SET status = ? WHERE id = ?" --args '["closed","form-1"]'
-# يُرسل find/replace الجراحي في عمود نصي كبير فرقًا وليس القيمة بأكملها
-pnpm action db-patch --table documents --column content \
-  --where "id='doc-1'" --find "old heading" --replace "new heading"
 ```
 
-يتيح البرنامج الإضافي للدردشة مع وكيل الإنتاج إمكانية كتابة قاعدة البيانات الأولية بشكل افتراضي
-(`databaseTools: "write"`) حتى يتمكن الوكلاء من إصلاح البيانات المملوكة للتطبيق دون الانتظار
-إجراء مكتوب جديد. يتم تحديد نطاق عمليات الكتابة هذه للمستخدم/المؤسسة التي تمت مصادقتها. تعيين
-`databaseTools: "read"` للاحتفاظ بفحص `db-schema` / `db-query` فقط، أو
+يقوم البرنامج الإضافي للدردشة مع وكيل الإنتاج بتعيين أدوات SQL الخام إلى القراءة فقط افتراضيًا
+(`databaseTools: "read"`)، لذلك يفحص الوكلاء بيانات التطبيق باستخدام `db-schema` /
+`db-query` ويجرون عمليات الكتابة عبر actions التطبيق المكتوبة. عيّن
+`databaseTools: "write"` (أو `true`) فقط لأسطح الصيانة المقصودة التي يجب أن تعرض
+`db-exec` / `db-patch` ذات النطاق؛ أو عيّن
 `databaseTools: "off"` / `false` للمطالبة بالتطبيق المكتوب actions لجميع البيانات
 الوصول.
 
@@ -440,6 +437,7 @@ A _frame_ هي البيئة التي تستضيف الوكيل بجوار تطب
 
 - **[Dispatch](/docs/dispatch)** — مستوى التحكم في مساحة العمل: البريد الوارد المشترك، وخزينة الأسرار، والمهام المجدولة، والمنسق الذي يفوض التطبيقات المتخصصة عبر A2A.
 - **[Extensions](/docs/extensions)** — تطبيقات Alpine.js المصغرة في وضع الحماية التي ينشئها الوكيل في وقت التشغيل، بدون تغييرات في المصدر أو عمليات ترحيل.
+- **[برامج البيانات](/docs/data-programs)** — نصوص `run-code` مخزَّنة يكتبها الوكيل، تغذي لوحات dashboard بنتيجة مخزَّنة مؤقتًا وقابلة للتحديث بدلاً من action مبرمَجة مسبقًا لمزوّد معين.
 - **[A2A Protocol](/docs/a2a-protocol)** — كيف تكتشف التطبيقات الموجودة في مساحة العمل نفسها وتتصل ببعضها البعض عبر JSON-RPC.
 
 ## ما تحصل عليه مجانًا {#what-you-get-for-free}

package/docs/content/locales/ar-SA/real-time-collaboration.mdx

@@ -256,11 +256,8 @@ export default createCollabPlugin({
 ### 4. استخدم ربط العميل
 
 ```ts
-import {
-  useCollaborativeDoc,
-  emailToColor,
-  emailToName,
-} from "@agent-native/core/client";
+import { useCollaborativeDoc } from "@agent-native/core/client";
+import { emailToColor, emailToName } from "@agent-native/toolkit/collab-ui";
 
 const TAB_ID = generateTabId(); // or Math.random().toString(36)
 
@@ -362,12 +359,14 @@ pnpm action edit-document --id doc123 --find "delete me" --replace ""
 
 ```ts
 import {
-  PresenceBar,
-  LiveCursorOverlay,
-  RemoteSelectionRings,
   useCollaborativeDoc,
   usePresence,
 } from "@agent-native/core/client/collab";
+import {
+  PresenceBar,
+  LiveCursorOverlay,
+  RemoteSelectionRings,
+} from "@agent-native/toolkit/collab-ui";
 ```
 
 يظل مساعدو وجود الوكيل من جانب الخادم في حزمة التعاون ذات المستوى الأدنى:
@@ -453,7 +452,7 @@ setPresence({ cursor: { x: 0.4, y: 0.7 }, selection: "#hero" });
 يعرض المؤشرات عن بعد كتسميات ذات موضع مطلق فوق عنصر الحاوية:
 
 ```tsx
-import { LiveCursorOverlay } from "@agent-native/core/client";
+import { LiveCursorOverlay } from "@agent-native/toolkit/collab-ui";
 
 // cursor positions stored as { x, y } normalized 0–1 under presence.cursor
 <div ref={containerRef} style={{ position: "relative" }}>
@@ -473,7 +472,7 @@ import { LiveCursorOverlay } from "@agent-native/core/client";
 يعرض حلقات مخطط تفصيلي ملونة + علامات أسماء على عناصر محددة عن بعد:
 
 ```tsx
-import { RemoteSelectionRings } from "@agent-native/core/client";
+import { RemoteSelectionRings } from "@agent-native/toolkit/collab-ui";
 
 <div ref={containerRef} style={{ position: "relative" }}>
   {content}

package/docs/content/locales/ar-SA/sharing.mdx

@@ -93,9 +93,10 @@ description: "المشاركة بأسلوب Google-Docs، المضمنة في إ
 - **الشرائح** — التشكيلات
 - **التصميم** — التصاميم والأصول
 - **المقاطع** — تسجيلات الشاشة (نمط المنوال)
+- **Plan** — visual plans and PR recaps
 - **النماذج** — تعريفات النماذج
 - **التقويم** — الأحداث وروابط الحجز
-- **التحليلات** — لوحات المعلومات (يتم طرحها — راجع `AGENTS.md` لنموذج التحليلات)
+- **التحليلات** — dashboards, saved analyses, and tokenized session replays
 - **الإضافات** — تطبيقات صغيرة في وضع الحماية (راجع [Extensions](/docs/extensions#sharing))
 
 يستخدم كل واحد من هؤلاء نفس مساعد مخطط `ownableColumns()`، ونفس إجراء `share-resource`، ونفس `<ShareButton>` UI. انتقل من قالب إلى آخر وسيبدو مربع حوار المشاركة متطابقًا.
@@ -136,15 +137,22 @@ import { ShareButton } from "@agent-native/core/client";
 
 يقوم إطار العمل بتثبيت actions تلقائيًا في كل قالب - يستدعيها الوكيل كأدوات، ويستدعيها UI من خلال `useActionQuery` / `useActionMutation`:
 
-| الإجراء                   | ماذا يفعل                                                                                          |
-| ------------------------- | -------------------------------------------------------------------------------------------------- |
-| `share-resource`          | منح مستخدم أو مؤسسة حق الوصول إلى دور محدد. يتحكم `notify` الاختياري في إشعارات البريد الإلكتروني. |
-| `unshare-resource`        | إبطال الوصول لمستخدم أو مؤسسة.                                                                     |
-| `list-resource-shares`    | إظهار الرؤية الحالية بالإضافة إلى جميع المنح الصريحة.                                              |
-| `set-resource-visibility` | قم بالتغيير إلى `private`، أو `org`، أو `public`.                                                  |
+| الإجراء                      | ماذا يفعل                                                                                          |
+| ---------------------------- | -------------------------------------------------------------------------------------------------- |
+| `share-resource`             | منح مستخدم أو مؤسسة حق الوصول إلى دور محدد. يتحكم `notify` الاختياري في إشعارات البريد الإلكتروني. |
+| `unshare-resource`           | إبطال الوصول لمستخدم أو مؤسسة.                                                                     |
+| `list-resource-shares`       | إظهار الرؤية الحالية بالإضافة إلى جميع المنح الصريحة.                                              |
+| `set-resource-visibility`    | قم بالتغيير إلى `private`، أو `org`، أو `public`.                                                  |
+| `create-agent-resource-link` | Mint a temporary read-only `agent_access` URL for a registered agent-readable resource.            |
 
 أخبر الوكيل "بمشاركة هذا التصميم مع فريق التسويق كمحررين" وسيقوم باستدعاء `share-resource` مقابل نفس نقطة النهاية التي يستخدمها UI. تظهر النتيجة في مربع حوار المشاركة في العرض التالي.
 
+## Agent-readable share links {#agent-readable-links}
+
+Human share links should also work for agents when the resource is a document-like artifact: plans, documents, decks, designs, analytics dashboards, saved analyses, clips, and similar "things you would send to a person." Public links expose a small SSR discovery script that points at structured JSON. Private resources use a short-lived `agent_access` token scoped to exactly one resource.
+
+Register the resource with `agentReadable`, add a read-only JSON context endpoint, inject the SSR discovery script with `renderAgentReadableResourceDiscoveryScript()`, and let agents call `create-agent-resource-link` when they need a temporary private URL. The endpoint must return data only when the row is `public` or `verifyScopedAgentAccessToken()` accepts the token for that exact `resourceKind` and `resourceId`.
+
 ## إنشاءه في قالب جديد {#building}
 
 إذا كنت تقوم بإنشاء قالب (راجع [Creating Templates](/docs/creating-templates))، فإن مشاركة الأسلاك تكون قصيرة. إضافتان إلى مخططك: