@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ar-SA/agent-teams.md

@@ -0,0 +1,171 @@
+---
+title: "فرق الوكلاء"
+description: "يعمل مفوضو الوكلاء الرئيسيون مع الوكلاء الفرعيين الذين يعملون في سلاسل الرسائل الخاصة بهم ويظهرون كشرائح معاينة مباشرة مضمنة في الدردشة."
+---
+
+# فرق الوكلاء
+
+إن دردشة الوكيل هي **منسقة** وليست كتلة واحدة. عندما يقوم الوكيل الرئيسي بمهمة من الأفضل أن يمتلكها أحد المتخصصين - "اكتب هذه الرسالة الإلكترونية بصوتي"، "قم بإجراء تحليل BigQuery"، "مراجعة العلاقات العامة هذه" - فإنه يولد وكيلًا فرعيًا في سلسلة الرسائل والأدوات والسياق الخاصة به. يظهر الوكيل الفرعي كمعاينة مباشرة **شريحة** مضمنة في الدردشة الرئيسية؛ انقر عليه لفتح المحادثة الكاملة كعلامة تبويب.
+
+يحافظ هذا على تركيز الموضوع الرئيسي، ويسمح للوكلاء الفرعيين بالعمل بالتوازي، ويمنحك مسار تدقيق نظيف لأي عمل مفوض.
+
+يتم تشغيل فرق الوكلاء على مدير التشغيل الأساسي: حيث يتم بث الأحداث واستمرارها، ويتم نشر عمليات الإلغاء عبر SQL، وتظل المهام على قيد الحياة عند البدء البارد بدون خادم.
+
+## النموذج العقلي {#mental-model}
+
+- **الدردشة الرئيسية** — المنسق. يقرأ طلبك، المندوبين. نادرًا ما يؤدي العمل الشاق بحد ذاته.
+- **الوكلاء الفرعيون** — يتم تشغيلهم باستخدام سلسلة الرسائل الخاصة بهم، وموجه النظام الخاص بهم، ومجموعة الأدوات الخاصة بهم. يتم تعيين كل منها إلى ملف تعريف "الوكيل المخصص" في [workspace](/docs/workspace).
+- **الرقائق** — بطاقة المعاينة الغنية التي تظهر مضمنة في الدردشة الرئيسية، وتعرض الخطوة الحالية للوكيل الفرعي، ومخرجات البث، والملخص النهائي. تم طيها بشكل افتراضي؛ يتم توسيعه إلى المحادثة الكاملة عند النقر.
+- **المراسلة ثنائية الاتجاه** — يمكن للوكيل الرئيسي إرسال متابعات إلى وكيل فرعي قيد التشغيل؛ يمكن للوكيل الفرعي الرد على الرسائل عندما يصل إلى نقطة غامضة.
+
+تستمر حالة الوكيل الفرعي في جدول `application_state` SQL (ضمن `agent-task:<taskId>`)، لذلك تظل المهام قادرة على البقاء على قيد الحياة مع عمليات التشغيل الباردة بدون خادم والعمل عبر عمليات متعددة.
+
+```an-diagram title="Orchestrator and specialists" summary="The main chat delegates to sub-agents that run in their own threads and report back as inline chips."
+{
+  "html": "<div class=\"at-orc\"><div class=\"diagram-card main\"><span class=\"diagram-pill accent\">Main chat</span><small class=\"diagram-muted\">orchestrator &mdash; reads your request, delegates</small></div><div class=\"at-fan\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"at-subs\"><div class=\"diagram-box\">Code review<br><small class=\"diagram-muted\">own thread &amp; prompt</small></div><div class=\"diagram-box\">BigQuery analysis<br><small class=\"diagram-muted\">own tools</small></div><div class=\"diagram-box\">Email in voice<br><small class=\"diagram-muted\">own context</small></div></div></div><div class=\"diagram-pill\">each appears inline as a live chip &#8635;</div></div>",
+  "css": ".at-orc{display:flex;flex-direction:column;align-items:center;gap:12px}.at-orc .diagram-card{padding:14px 18px;display:flex;flex-direction:column;gap:4px;align-items:center}.at-orc .at-fan{display:flex;flex-direction:column;align-items:center;gap:8px}.at-orc .diagram-arrow{font-size:22px}.at-orc .at-subs{display:flex;gap:12px;flex-wrap:wrap;justify-content:center}.at-orc .diagram-box{text-align:center}"
+}
+```
+
+## متى يتم إنشاء وكيل فرعي {#when-to-spawn}
+
+تفرخ عند المهمة:
+
+- يحتاج إلى **موجه نظام** مختلف (صوت أو نغمة متخصصة، على سبيل المثال، "مراجعة الكود").
+- يحتوي على سلسلة أدوات **طويلة الأمد** من شأنها تلويث السياق الرئيسي.
+- يمكن تشغيله **بالتوازي** مع الأعمال الأخرى التي يقوم بها الوكيل الرئيسي.
+- مملوكة من قبل **فريق مختلف** لديه بالفعل ملف تعريف وكيل مخصص.
+
+لا تلجأ إلى عمل تافه لمرة واحدة - قم باستدعاء الإجراء مباشرة.
+
+## استدعاء وكيل فرعي {#invoking}
+
+ثلاث طرق لبدء وكيل فرعي، من الأقل إلى الأكثر وضوحًا:
+
+### 1. `@mention` وكيل مخصص {#mention}
+
+يكتب المستخدم `@agent-name` في مؤلف الدردشة. تظهر قائمة منسدلة للوكلاء الفرعيين لمساحة العمل. يؤدي اختيار واحدة إلى إدراج شريحة؛ عند الإرسال، يقوم الوكيل الرئيسي بتفويض الرسالة إلى ذلك الوكيل الفرعي.
+
+يعيش الوكلاء المخصصون في مساحة العمل في `agents/<slug>.md` - ملف Markdown مع المادة الأمامية YAML. راجع [Custom Agents](/docs/workspace#custom-agents) لمعرفة التنسيق.
+
+### 2. يقوم الوكيل الرئيسي بالتفويض تلقائيًا {#auto-delegate}
+
+يمنح إطار العمل الوكيل الرئيسي أداة `agent-teams`. عندما يقرر النموذج أن المهمة تناسب ملف تعريف وكيل فرعي مسجل، فإنه يستدعي الأداة باستخدام `action: "spawn"` ومعلمة `agent` اختيارية لتسمية ملف تعريف من `agents/*.md`. تظهر شريحة؛ يعمل الوكيل الفرعي. ينتظر الوكيل الرئيسي (أو يتحرك بالتوازي) ويدمج النتيجة عندما ينتهي الوكيل الفرعي.
+
+مجموعة إجراءات `agent-teams` الكاملة هي:
+
+| الإجراء       | الغرض                                    |
+| ------------- | ---------------------------------------- |
+| `spawn`       | ابدأ مهمة وكيل فرعي جديدة                |
+| `status`      | التحقق من تقدم الوكيل الفرعي قيد التشغيل |
+| `read-result` | احصل على مخرجات الوكيل الفرعي النهائية   |
+| `send`        | مراسلة وكيل فرعي قيد التشغيل             |
+| `list`        | عرض كافة المهام للمستخدم الحالي          |
+
+### 3. تفرخ برمجي {#programmatic-spawn}
+
+بالنسبة لعمليات التكامل على مستوى إطار العمل، استخدم `spawnTask()` من `@agent-native/core/server`:
+
+```ts
+import { spawnTask } from "@agent-native/core/server";
+
+const task = await spawnTask({
+  description: "Draft an outreach email to this lead",
+  instructions: "Match Steve's voice from memory/MEMORY.md.",
+  ownerEmail: user.email,
+  systemPrompt: mailAgentSystemPrompt,
+  actions: mailActions,
+  // Pass either apiKey or engine — engine takes precedence.
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional if engine is provided
+  parentSend: emit, // streaming sender for the parent chat response
+});
+```
+
+لن تستدعي معظم أكواد التطبيق هذا مباشرة - حيث يقوم إطار العمل بذلك تحت غطاء `@mentions` ولأداة `agent-teams`. يمكنك الوصول إلى `spawnTask()` فقط عندما تقوم بتوصيل نقطة دخول جديدة (على سبيل المثال، زر يبدأ مهمة خلفية تعمل كوكيل فرعي).
+
+## دورة حياة المهمة {#lifecycle}
+
+```an-diagram title="What spawnTask() does" summary="Each spawn creates a thread, persists state to SQL, and streams chip events through to completion."
+{
+  "html": "<div class=\"at-life\"><div class=\"diagram-box\"><code>spawnTask()</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">create thread</span><small class=\"diagram-muted\">new row in <code>chat_threads</code>, description as first message</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">persist state</span><small class=\"diagram-muted\"><code>agent-task:&lt;id&gt;</code> &rarr; <code>application_state</code>, status=running</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">stream</span><small class=\"diagram-muted\"><code>agent_task_started</code> &rarr; chip appears; <code>agent_task_step</code> &rarr; chip updates live</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">complete</span><small class=\"diagram-muted\">status=completed, write summary + preview, emit <code>agent_task_done</code></small></div></div>",
+  "css": ".at-life{display:flex;flex-direction:column;align-items:stretch;gap:6px;max-width:560px}.at-life .diagram-card{display:flex;flex-direction:column;gap:3px;padding:10px 14px}.at-life .diagram-box{align-self:flex-start}.at-life .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+في أي وقت، يمكن للوكيل الأصلي استئناف الوكيل الفرعي من خلال المتابعة عبر `sendToTask(taskId, message)`. إذا كانت أخطاء الوكيل الفرعي، فإن `markTaskErrored(taskId, reason)` يسجل الفشل ويظهره للمستخدم.
+
+ميزة المراسلة ثنائية الاتجاه متينة. تتم متابعات الوالدين لتشغيل الوكلاء الفرعيين
+يتم تسليمها خلال دورة حياة المهمة؛ إذا لم يتمكن الوكيل الفرعي من استهلاكها في
+الخطوة الحالية، يجب أن تظل في قائمة الانتظار ويتم تطبيقها في مكان آمن
+نقطة الاستمرار. يمكن للوكلاء الفرعيين أيضًا الرد عندما يحتاجون إلى توضيح
+بدلاً من الحظر بشكل غير مرئي.
+
+## حالة مهمة القراءة {#reading-state}
+
+من رمز الخادم أو actions آخر:
+
+```ts
+import { getTask, listTasks } from "@agent-native/core/server";
+
+const task = await getTask(taskId); // single task
+const tasks = await listTasks(); // all tasks for the user (sorted newest first)
+```
+
+الحقول الرئيسية `AgentTask`:
+
+```ts
+interface AgentTask {
+  taskId: string;
+  threadId: string;
+  description: string;
+  status: "running" | "completed" | "errored";
+  preview: string; // short one-liner for the chip
+  summary: string; // full summary once completed
+  currentStep: string; // latest step label (updated while running)
+  createdAt: number;
+  // Additional fields: parentThreadId, name, updatedAt, startedAt,
+  // completedAt, runId, error
+}
+```
+
+## ملفات تعريف الوكيل المخصصة {#profiles}
+
+يتم تعيين الوكلاء الفرعيين إلى ملفات تعريف الوكلاء المخصصة — ملفات Markdown في `agents/<slug>.md` في مساحة العمل التي تظهر في القائمة المنسدلة `@mention` وتعمل كأهداف للتفويض. تمتلك [Workspace — Custom Agents](/docs/workspace#custom-agents) التنسيق الكامل (frontmatter، `tools`، `delegate-default`، تجاوزات النموذج).
+
+## حارس عمق التفويض {#depth-guard}
+
+يمكن للوكلاء الفرعيين إنشاء وكلاء فرعيين، وهو ما يمثل مخاطرة جامحة/تكلفة: يمكن أن تنتشر سلسلة غير محدودة من التفويضات إلى أجل غير مسمى. يفرض إطار العمل حدًا أقصى **على عمق التفويض**، من جانب الخادم، بشكل مستقل عن أي حماية على مستوى الأداة.
+
+الدردشة ذات المستوى الأعلى هي العمق `0`. العامل الفرعي الذي يولده هو العمق `1`؛ قد يظهر هذا العامل الفرعي مرة أخرى (العمق `2`)؛ تم رفض النشر الذي من شأنه إنشاء وكيل فرعي للعمق `3` **. الحد الأقصى الافتراضي هو **2\*\*.
+
+```an-diagram title="Delegation depth guard (default cap 2)" summary="Each level may spawn one deeper until the cap; a spawn past it is refused server-side."
+{
+  "html": "<div class=\"at-depth\"><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 0</span><strong>Top-level chat</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 1</span><strong>Sub-agent</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card warn\"><span class=\"diagram-pill warn\">depth 2</span><strong>Sub-agent's sub-agent</strong><small class=\"diagram-muted\">at the cap &mdash; may NOT spawn</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">depth 3</span><strong>Refused</strong><small class=\"diagram-muted\">server-side error</small></div></div>",
+  "css": ".at-depth{display:flex;flex-direction:column;gap:8px}.at-depth .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.at-depth .rung-1,.at-depth .diagram-card:nth-child(2){margin-inline-start:24px}.at-depth .diagram-card:nth-child(3){margin-inline-start:48px}.at-depth .diagram-card:nth-child(4){margin-inline-start:72px}"
+}
+```
+
+التنفيذ محيط: يعمل كل وكيل فرعي داخل `AsyncLocalStorage` الذي يسجل عمقه الخاص، وبالتالي فإن أي `spawnTask` يتم الوصول إليه بشكل انتقالي من هذا التشغيل يقرأ عمق الأصل الخاص به ويرفض بمجرد الوصول إلى الحد الأقصى - حتى لو تم تسليم أداة `agent-teams` إلى وكيل فرعي لا ينبغي أن يحصل عليها. يتم عرض القرار على أنه `evaluateSubagentDepth(parentDepth)` نقي وقابل للاختبار بالوحدة. يُرجع النشر المرفوض خطأً واضحًا: _"تم الوصول إلى الحد الأقصى لعمق التفويض (الحد الأقصى N)؛ لا يمكن نشر وكيل فرعي آخر."_
+
+### تهيئة الحد الأقصى {#depth-guard-config}
+
+تجاوز الإعداد الافتراضي في وقت النشر باستخدام `AGENT_NATIVE_MAX_SUBAGENT_DEPTH`:
+
+| القيمة           | التأثير                                                                                                                                  |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| _(إلغاء الضبط)_  | الحد الأقصى الافتراضي لـ `2`.                                                                                                            |
+| `0`              | **لا يجوز إنشاء أي وكلاء فرعيين** — يقوم وكيل المستوى الأعلى بكل العمل.                                                                  |
+| `1`…`16`         | أن هناك مستويات عديدة للتفويض.                                                                                                           |
+| غير صالح / `>16` | تعود القيمة غير الصحيحة / السالبة / NaN إلى `2`؛ أي شيء أعلى من `16` يتم تثبيته على `16` لذا لا يمكن للخطأ المطبعي تعطيل الحماية مطلقًا. |
+
+```bash
+AGENT_NATIVE_MAX_SUBAGENT_DEPTH=1   # sub-agents allowed, but they can't sub-delegate
+```
+
+عندما يصل الوكيل الفرعي إلى الحد الأقصى أو أقل منه، يقوم إطار العمل بإدخال سطر في سياق وقت التشغيل الخاص به لإخباره بمدى عمقه وما إذا كان يمكنه تفويض المزيد، وبالتالي ينفق النموذج ميزانيته بشكل مناسب.
+
+## ما هي الخطوة التالية
+
+- [**Workspace — Custom Agents**](/docs/workspace#custom-agents) — تنسيق الملف الشخصي
+- [**A2A Protocol**](/docs/a2a-protocol) — عندما يعيش "الوكيل الفرعي" في تطبيق مختلف تمامًا
+- [**Actions**](/docs/actions) — الأدوات التي يستدعيها الوكيل الفرعي

package/corpus/core/docs/content/locales/ar-SA/agent-web-surfaces.md

@@ -0,0 +1,161 @@
+---
+title: "موقع الوكيل العام"
+description: "اجعل المسارات العامة قابلة للزحف، وقابلة للقراءة، والاستشهاد بها، ويمكن استدعاؤها اختياريًا بواسطة الوكلاء — robots.txt، وllms.txt، ومرايا تخفيض السعر، وJSON-LD، وسطح MCP العام."
+---
+
+# موقع الوكيل العام
+
+تجعل شبكة الوكيل العام مسارات Agent-Native العامة سهلة على الوكلاء للزحف إليها وقراءتها والاستشهاد بها والاتصال بها. الهدف ليس جعل نقطة نهاية كل تطبيق عامة. الهدف هو نشر سطح عام نظيف للصفحات العامة بالفعل، مع الاحتفاظ بالبيانات الخاصة والوصول إلى الأدوات خلف ضوابط واضحة.
+
+موقع المستندات هو التنفيذ المرجعي. واليوم يتم شحنه:
+
+- `/robots.txt` مع سياسة الزاحف التي تسمح بالاسترداد ولكنها لا تسمح بالتدريب بشكل افتراضي.
+- `/sitemap.xml` مع URLs الأساسية المطلقة و`lastmod` عندما يعرضها الملف المصدر.
+- `/llms.txt` و`/llms-full.txt` لاكتشاف المحتوى المناسب للوكلاء.
+- مرايا Markdown مثل `/docs/getting-started.md`.
+- استجابات `Accept: text/markdown` لصفحات المستندات العامة بعد إنشاء الإنتاج.
+- JSON-LD للمؤسسة الأساسية وموقع الويب والبيانات الوصفية للصفحة.
+- تدقيق CLI (`npx @agent-native/core@latest audit-agent-web`) يتحقق من كل ما سبق.
+
+يؤدي إعداد `publicMcp: true` أيضًا إلى كشف actions التي تم اختيارها كنقطة نهاية MCP عامة، مما يسمح للوكلاء الخارجيين بالاتصال بهم مباشرة (راجع [MCP Protocol](/docs/mcp-protocol)).
+
+```an-diagram title="What a public route publishes" summary="A public route fans out into agent-friendly representations. Reading the route is separate from calling tools — tool access stays opt-in."
+{
+  "html": "<div class=\"diagram-web\"><div class=\"diagram-box\" data-rough>Public route<br><small class=\"diagram-muted\">derived from route access settings</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">robots.txt</span><span class=\"diagram-pill\">sitemap.xml</span><span class=\"diagram-pill\">llms.txt</span><span class=\"diagram-pill\">.md mirror</span><span class=\"diagram-pill\">JSON-LD</span><span class=\"diagram-pill\">text/markdown</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col gate\"><span class=\"diagram-pill warn\">Tools stay private</span><small class=\"diagram-muted\">publicMcp + publicAgent.expose required</small></div></div>",
+  "css": ".diagram-web{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-web .diagram-arrow{font-size:22px;line-height:1}.diagram-web .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}.diagram-web .gate{display:flex;flex-direction:column;gap:4px;align-items:flex-start}"
+}
+```
+
+## التكوين {#config}
+
+أضف `agentWeb` ضمن تكوين تطبيق مساحة العمل الحالي (في `package.json` لتطبيقك ضمن مفتاح `agent-native` - أو `workspace.agentWeb` أو `agentWeb` أو `root.agentWeb` بشكل مكافئ). لا تزال قائمة المسارات العامة مستمدة من إعدادات الوصول إلى المسار الخاصة بالتطبيق؛ يتحكم `agentWeb` في كيفية تمثيل هذا السطح العام للوكلاء.
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin/*"],
+      "agentWeb": {
+        "discoverable": true,
+        "markdownTwins": true,
+        "llmsTxt": true,
+        "jsonLd": true,
+        "publicAgentCard": true,
+        "publicMcp": false,
+        "crawlerPolicy": "discoverable-no-training",
+        "crawlers": {
+          "training": "disallow",
+          "search": "allow",
+          "userTriggered": "allow",
+          "codingAgents": "allow",
+          "autonomousAgents": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+بالنسبة لمعظم التطبيقات، اترك الإعدادات الافتراضية كما هي. إذا كان التطبيق يحتوي على أي مسار عام، فسيتم تشغيل `discoverable` بشكل افتراضي. سياسة الزاحف الافتراضية هي "قابلة للاكتشاف وغير قابلة للتدريب": يُسمح بالبحث والاسترجاع بواسطة المستخدم ووكلاء الترميز ووكلاء التصفح المستقلين؛ برامج زحف التدريب غير مسموح بها.
+
+## توجيه مصدر الحقيقة {#route-source}
+
+يتبع اكتشاف ويب الوكيل نموذج الوصول إلى المسار:
+
+- تكشف التطبيقات العامة عن كل مسار باستثناء `protectedPaths`.
+- تكشف التطبيقات الداخلية عن `publicPaths` فقط.
+- يمكن للوكلاء قراءة صفحات المشاركة العامة والنماذج.
+- لا يتم تضمين البيانات الخاصة المرسلة ولوحات التحكم التي تمت مصادقتها وحالة المستخدم/المؤسسة مطلقًا لمجرد أن الصفحة القريبة عامة.
+
+يؤدي هذا إلى إبقاء التطبيقات المختلطة طبيعية. يمكن لتطبيق النماذج الكشف عن صفحة نموذج عامة والحفاظ على خصوصية عمليات الإرسال. يمكن لتطبيق المحتوى أن يكشف المنشورات المنشورة ويحافظ على خصوصية المحرر. يمكن لموقع المستندات أن يكشف كل شيء باستثناء أدوات الإدارة.
+
+## الصفحات العامة ليست أدوات عامة {#public-tools}
+
+الوصول إلى الصفحة العامة والوصول إلى الأداة العامة منفصلان. كون المسار عامًا فقط يعني أن الوكلاء يمكنهم قراءة هذا المسار مثل HTML، وMarkdown، وإدخالات خريطة الموقع، وإدخالات llms، والبيانات المنظمة.
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "**A public page is not a public tool.** Making a route crawlable never exposes an action. Tool access requires an explicit `publicAgent.expose` opt-in on the action *and* `publicMcp: true` on the app."
+}
+```
+
+للكشف عن إجراء من خلال بروتوكول الوكيل العام، يجب أن يتم تمكين الإجراء:
+
+```an-annotated-code title="Opting one safe action onto the public surface"
+{
+  "filename": "actions/search-docs.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Search published docs\",\n  readOnly: true,\n  publicAgent: {\n    expose: true,\n    readOnly: true,\n    requiresAuth: false,\n    isConsequential: false,\n    title: \"Search published docs\",\n  },\n  run: async (args) => {\n    // ...\n  },\n});",
+  "annotations": [
+    { "lines": "4", "label": "Explicit opt-in", "note": "Without `publicAgent.expose === true`, the action never appears on any public agent surface — no matter how public its routes are." },
+    { "lines": "5-7", "label": "Self-describe safety", "note": "Mark it read-only, declare whether it needs auth, and flag whether it is consequential. Public MCP excludes consequential/write actions unless policy explicitly allows them." }
+  ]
+}
+```
+
+يظل `agentWeb.publicMcp` `false` بشكل افتراضي. عند تمكين MCP العام، يجب أن يعرض الخادم فقط actions مع `publicAgent.expose === true`، ويجب أن يستمر في استبعاد التبعية أو كتابة actions ما لم يسمح الإجراء وسياسة المصادقة بذلك صراحة.
+
+## ملفات وقت البناء {#build-time}
+
+تقوم أدوات إطار العمل المساعدة في `@agent-native/core/agent-web` بإنشاء الملفات الشائعة من قائمة صفحات واحدة:
+
+```ts
+import {
+  buildAgentWebStaticFiles,
+  normalizeAgentWebConfig,
+} from "@agent-native/core/agent-web";
+
+const config = normalizeAgentWebConfig(
+  { crawlerPolicy: "discoverable-no-training" },
+  { hasPublicRoutes: true },
+);
+
+const files = buildAgentWebStaticFiles({
+  siteName: "My Agent-Native App",
+  siteUrl: "https://example.com",
+  description: "Public docs for my app.",
+  config,
+  pages: [
+    {
+      path: "/docs",
+      title: "Docs",
+      description: "Start here.",
+      markdown: "# Docs\n\nStart here.\n",
+      markdownPath: "/docs/getting-started.md",
+      lastmod: new Date(),
+    },
+  ],
+});
+```
+
+يمكن لتطبيقات Vite استخدام `createAgentWebVitePlugin` من `@agent-native/core/vite` لكتابة هذه الملفات إلى `public` أو `dist` أو `dist/client` أو `dist/server/public` أو `build/client` أثناء إنشاءات الإنتاج.
+
+## تدقيق الموقع {#audit}
+
+استخدم تدقيق CLI مقابل موقع منشور أو خادم إنتاج محلي:
+
+```bash
+npx @agent-native/core@latest audit-agent-web --url https://www.agent-native.com
+```
+
+يقوم التدقيق بالتحقق من:
+
+- SSR-HTML المرئي.
+- URLs الأساسية.
+- JSON-LD.
+- سياسة `robots.txt` وخريطة الموقع المطلقة URL.
+- إدخالات خريطة الموقع المطلقة.
+- `/llms.txt` و`/llms-full.txt`.
+- مرايا Markdown.
+- `Accept: text/markdown`.
+- لا توجد عمليات حظر غير مقصودة 401/403 لوكلاء مستخدم استرداد الوكيل المشترك.
+
+تخرج عملية التدقيق من الصفر إذا كان السطح العام المطلوب مفقودًا.
+
+## ما هي الخطوة التالية
+
+- [**Actions**](/docs/actions) — كيفية تفعيل actions في بروتوكول الوكيل العام
+- [**MCP Protocol**](/docs/mcp-protocol) — سطح MCP الذي يتيحه `publicMcp: true`
+- [**Deployment**](/docs/deployment) — حيث تتم كتابة هذه الملفات الثابتة أثناء عمليات الإنشاء

package/corpus/core/docs/content/locales/ar-SA/audit-log.md

@@ -0,0 +1,111 @@
+---
+title: "سجل التدقيق"
+description: "سجل دائم وملحق فقط لمن قام بتغيير بيانات التطبيق ومتى وما إذا كان أنت أو الوكيل - يتم التقاطه تلقائيًا في خط الإجراء."
+---
+
+# سجل التدقيق
+
+يحصل كل تطبيق وكيل أصلي على سجل تدقيق خارج الصندوق: سجل متين وكامل ومخصص للوصول وملحق فقط **من قام بتغيير بيانات التطبيق ومتى وأين و- متى كان الوكيل - وفي أي تشغيل.** يتم الالتقاط تلقائيًا في خط الإجراء؛ لم تكتب أي رمز لذلك.
+
+نظرًا لأن الوكيل يمكنه تغيير البيانات نيابةً عنك، فإن السؤال الرئيسي الذي يجيب عليه سجل التدقيق هنا ليس فقط "من قام بتحرير هذا السجل" - بل **"هل كان هذا أنا أم الوكيل، وما هو السبب وراء ذلك؟"** لا يمكن لأي نظام آخر في إطار العمل الإجابة على ذلك.
+
+## التدقيق مقابل إمكانية الملاحظة مقابل التتبع {#which}
+
+تسجل ثلاثة أنظمة "ما حدث" لثلاثة أسباب مختلفة. اختر السؤال الذي تطرحه:
+
+| النظام                                   | السؤال الذي يجيب عليه                               | الإخلاص                            | الجمهور                       |
+| ---------------------------------------- | --------------------------------------------------- | ---------------------------------- | ----------------------------- |
+| **سجل التدقيق** (هذه الصفحة)             | "من قام بتغيير هذا السجل، ومتى، وهل كان هو الوكيل؟" | **كامل ومتين وذو نطاق محدد**       | المستخدم، المشرف، الوكيل نفسه |
+| **[Observability](/docs/observability)** | "لماذا فعل الوكيل ذلك، وما هي التكلفة؟"             | قياس المدى عن بعد                  | المطور                        |
+| **[Tracking](/docs/tracking)**           | "كيف يستخدم الأشخاص المنتج؟"                        | أطلق النار وانسى إلى SaaS الخارجية | PM / النمو                    |
+
+يعد سجل التدقيق الذي يتم أخذ عينات منه أو شحنه إلى موفر التحليلات عديم الفائدة - بيت القصيد هو أنه كامل ومحلي وقابل للاستعلام عنه. لذا فهو نظام فرعي خاص به، وليس نمطًا من النظامين الآخرين.
+
+## ما يتم التقاطه تلقائيًا {#captured}
+
+عند تشغيل أي إجراء **متغير** (أي شيء ليس `GET` للقراءة فقط)، يُلحق إطار العمل صفًا واحدًا بـ `agent_audit_log` مع:
+
+- **الإجراء** — اسم الإجراء (على سبيل المثال، `delete-recording`).
+- **الممثل** — `agent`، أو `human`، أو `system`، بالإضافة إلى البريد الإلكتروني للممثل — تتم ملؤه **حتى بالنسبة لمكالمات الوكيل**، بحيث تحصل على "الوكيل، الذي يعمل لصالح alice@، ...".
+- **تشغيل الرابط** — العامل `threadId` / `turnId` الذي قام بتشغيل الاستدعاء (استدعاء أداة)، لذا فإن الطفرة تتتبع مرة أخرى إلى المنعطف الدقيق للوكيل.
+- **السطح** — `tool` (الوكيل)، أو `frontend`، أو `http`، أو `cli`، أو `mcp`، أو `a2a`.
+- **النتيجة** — `success`، أو `error` (مع رمز خطأ)، أو `denied` (تم حظره بواسطة بوابة موافقة بشرية).
+- **المدخلات** — وسيطات الاستدعاء، بقيم على شكل بيانات الاعتماد [redacted](#privacy).
+- **الهدف والمالك** — المورد الذي تم تغييره بواسطة الإجراء، والمستخدم في [scope reads](#reading).
+
+لا حاجة إلى أسلاك — يتم ربط خطافات الالتقاط بـ `defineAction` بشفافية. يتم تخطي actions للقراءة فقط، ويتم تخطي بعض إطارات العمل عالية التردد actions (مزامنة حالة التطبيق، وأشعة السياق السينية، والتنقل) افتراضيًا لتجنب إغراق السجل.
+
+## أعلن عن الإجراء الذي تغير {#target}
+
+افتراضيًا، يتم تحديد نطاق الحدث إلى **الممثل** — حيث ترى تغييراتك وتغييرات الوكيل نيابةً عنك. لإجراء تغيير على مورد _shared_ يظهر أيضًا في مسار **المالك**، ولتسمية الأحداث حسب المورد، قم بإعلان `target`:
+
+```ts
+export default defineAction({
+  description: "Delete a recording.",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    target: (args, result) => ({
+      type: "recording",
+      id: args.id,
+      // Optional — defaults to the actor. Set when editing someone else's resource.
+      ownerEmail: result?.ownerEmail,
+      visibility: "org",
+    }),
+    summary: (args) => `Deleted recording ${args.id}`,
+  },
+  run: async (args, ctx) => {
+    /* ...delete... */
+  },
+});
+```
+
+كل شيء في `audit` اختياري. الحد الأدنى للإضافة المفيدة هو `target: () => ({ type, id })`.
+
+### ضبط الالتقاط {#tuning}
+
+| الخيار               | التأثير                                                 |
+| -------------------- | ------------------------------------------------------- |
+| `audit.target`       | قم بتسمية الحدث بالمورد والنطاق الذي تمت قراءته لمالكه. |
+| `audit.summary`      | سطر قصير يمكن قراءته للحدث.                             |
+| `audit.onRead`       | تدقيق **قراءة** حساسة (الوصول السري، التصدير المجمع).   |
+| `audit.enabled`      | القبض على قوات `true`؛ يختار `false` طفرة صاخبة.        |
+| `audit.recordInputs` | يتخطى `false` التقاط الوسائط (المنقحة بالفعل).          |
+
+## قراءة المسار {#reading}
+
+تتوفر قراءتان actions للوكيل **و** الواجهة الأمامية في كل تطبيق، ويتم تحديد نطاقهما في SQL للمتصل - ولا يُرجعان أبدًا صفوف مستأجر آخر:
+
+- **`list-audit-events`** — التصفية حسب `targetType` / `targetId`، `actorKind` (`agent` | `human` | `system`)، `status`، `threadId` / `turnId`، `action`، `sinceMs`، و`limit`.
+- **`get-audit-event`** — حدث واحد حسب المعرف، بما في ذلك حمولة الإدخال المنقحة الخاصة به.
+
+أنشئ خلاصة نشاط أو سطر "من قام بتغيير هذا" عن طريق استدعاء `list-audit-events` من UI باستخدام `useActionQuery` — لا تكتب أبدًا يدويًا أي جلب إلى جدول التدقيق:
+
+```tsx
+import { useActionQuery } from "@agent-native/core/client";
+
+const { data } = useActionQuery("list-audit-events", {
+  targetType: "recording",
+  targetId: recordingId,
+});
+// data.events → [{ action, actorKind, actorEmail, turnId, status, summary, createdAt }, …]
+```
+
+يمكن للوكيل استدعاء نفس الإجراء - اسأله "ما الذي قمت بتغييره في هذا التسجيل؟" ويجيب من الدرب.
+
+## الخصوصية والاحتفاظ {#privacy}
+
+- **التنقيح** — قبل تخزين أي مدخلات، تتم إزالة المفاتيح والقيم على شكل بيانات الاعتماد (الرموز المميزة، والأسرار، وكلمات المرور، والسلاسل الحاملة) واقتطاع الحمولات كبيرة الحجم. لا يصبح سجل التدقيق أبدًا مخزنًا ثانويًا للأسرار. احتفظ بنص `summary` خاليًا من البيانات الحساسة أيضًا.
+- **إلحاق فقط** — لا يوجد إجراء تحديث أو حذف لصفوف التدقيق. الحذف الوحيد هو عملية تطهير الاحتفاظ، مما يجعل السجل جديرًا بالثقة باعتباره مسارًا للتدقيق.
+- **عزل المستأجر** — يتم تحديد نطاق القراءات وفقًا لهوية المتصل ومؤسسته؛ بدون هوية، لا شيء يطابق.
+
+التكوين عبر البيئة:
+
+- `AGENT_NATIVE_AUDIT_RETENTION_DAYS` — مدة الاحتفاظ بالصفوف (افتراضي `365`؛ `0` = الاحتفاظ للأبد).
+- `AGENT_NATIVE_AUDIT_ENABLED=false` — مفتاح الإيقاف العام.
+
+## ما هي الخطوة التالية
+
+- [**Actions**](/docs/actions) — خط التماس `defineAction` الذي يحدث فيه الالتقاط
+- [**Human-in-the-Loop Approvals**](/docs/human-approval) — actions، مسجل كـ `denied`
+- [**Security & Data Scoping**](/docs/security) — يقرأ تدقيق نموذج الملكية إعادة الاستخدام
+- [**Observability**](/docs/observability) — القياس عن بعد الذي يديره الوكيل ("ما حدث" الآخر)