@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,236 @@
+---
+title: "التتبع والتحليلات"
+description: "تحليلات من جانب الخادم مع موفري خدمات قابلين للتوصيل — PostHog، أو Mixpanel، أو Amplitude، أو خطاف الويب المخصص"
+---
+
+# تتبع التحليلات
+
+وظيفة واحدة، وجهات متعددة. اتصل بـ `track()` من أي رمز من جانب الخادم - actions والمكونات الإضافية ومسارات الخادم - ويتم إرسال الحدث إلى كل مزود تحليلات مسجل. لا توجد تبعيات SDK، ولا توجد نصوص برمجية من جانب العميل، ولا يوجد حظر. يتوفر نفس `track()` أيضًا في [browser/app code](#client) ويوجه إلى نفس مقدمي الخدمة.
+
+هذه هي تحليلات _product_ — تتدفق أحداث تطبيقك إلى PostHog/Mixpanel/Amplitude. للحصول على مقاييس جودة_الوكيل (التتبعات والتكلفة والتقييمات والملاحظات) المخزنة في قاعدة البيانات الخاصة بك، راجع [Observability](/docs/observability).
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "order.completed",
+  { total: 49.99, items: 3 },
+  { userId: "steve@builder.io" },
+);
+```
+
+```an-diagram title="One track() call, every provider" summary="Server and client callers hit the same registry, which fans every event out to all active providers in parallel."
+{
+  "html": "<div class=\"trk\"><div class=\"diagram-col\"><div class=\"diagram-node\">Server code<br><small class=\"diagram-muted\">actions &middot; plugins &middot; routes</small></div><div class=\"diagram-node\">Browser code<br><small class=\"diagram-muted\">POST /_agent-native/track</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Provider registry</span><small class=\"diagram-muted\">fan-out, fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">PostHog</div><div class=\"diagram-box\">Mixpanel</div><div class=\"diagram-box\">Amplitude</div><div class=\"diagram-box\">Webhook</div></div></div>",
+  "css": ".trk{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.trk .diagram-col{display:flex;flex-direction:column;gap:8px}.trk .diagram-arrow{font-size:22px;line-height:1}.trk .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## الموفرون المضمنون {#built-in}
+
+قم بتعيين env var ويقوم الموفر بالتسجيل التلقائي عند بدء تشغيل الخادم. لا توجد تغييرات مطلوبة في التعليمات البرمجية.
+
+| المزود                  | إنف فار                                                                                              |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| ما بعد الهوج            | `POSTHOG_API_KEY` (مطلوب)، `POSTHOG_HOST` (اختياري، الإعداد الافتراضي هو `https://us.i.posthog.com`) |
+| ميكسبانيل               | `MIXPANEL_TOKEN`                                                                                     |
+| السعة                   | `AMPLITUDE_API_KEY`                                                                                  |
+| الرد التلقائي على الويب | `TRACKING_WEBHOOK_URL` (مطلوب)، `TRACKING_WEBHOOK_AUTH` (رأس `Authorization` اختياري)                |
+
+يمكن لموفرين متعددين أن يكونوا نشطين في وقت واحد. كل حدث يذهب إلى كل منهم.
+
+## API {#api}
+
+### `track(name, properties?, meta?)` {#track}
+
+قم بتشغيل حدث التحليلات. المعجبون لجميع مقدمي الخدمة المسجلين.
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "steve@builder.io" },
+);
+```
+
+### `identify(userId, traits?)` {#identify}
+
+تحديد المستخدم مع السمات. يتم إرسالها إلى مقدمي الخدمة الذين يدعمونها (PostHog، Mixpanel، Amplitude، webhook).
+
+```ts
+import { identify } from "@agent-native/core/tracking";
+
+identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+```
+
+هل تحتاج إلى واجهة خلفية مخصصة، أو سجل الموفر API، أو الأجزاء الداخلية المجمعة/المفردة؟ انظر [Advanced: custom providers & internals](#advanced) في النهاية.
+
+## استخدام المسار () في القوالب {#templates}
+
+استدعاء `track()` من معالجات الإجراءات لتسجيل نشاط المستخدم أو الوكيل:
+
+```ts
+// actions/create-project.ts
+import { defineAction } from "@agent-native/core/action";
+import { track } from "@agent-native/core/tracking";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Create a new project.",
+  schema: z.object({
+    name: z.string(),
+    template: z.string().optional(),
+  }),
+  run: async ({ name, template }, ctx) => {
+    const project = await db
+      .insert(projects)
+      .values({ name, template })
+      .returning();
+
+    track("project.created", { name, template }, { userId: ctx.userEmail });
+
+    return { ok: true, projectId: project[0].id };
+  },
+});
+```
+
+يتم تجاهل مكالمات التتبع — فهي تعود فورًا ولا تمنع استجابة الإجراء مطلقًا.
+
+## التتبع من جانب العميل {#client}
+
+يعمل `track()` أيضًا من خلال رمز المتصفح/التطبيق. قم باستيراد توأم العميل من `@agent-native/core/client` وقم بتسميته بنفس الطريقة - فهو ينشر الحدث إلى مسار إطار العمل في `POST /_agent-native/track`، والذي يعيد توجيهه إلى موفري جانب الخادم المسجلين **نفسهم** (PostHog، Mixpanel، Amplitude، webhook). لا يتم شحن أي تحليلات SDK إلى المتصفح ولا يتم الكشف عن مفاتيح الموفر من جانب العميل.
+
+```an-api title="The client tracking route"
+{
+  "method": "POST",
+  "path": "/_agent-native/track",
+  "summary": "Forward a browser event to the registered server-side providers",
+  "auth": "Session required + same-origin/CSRF marker (set automatically by the client helper). Not an open analytics relay.",
+  "params": [
+    { "name": "name", "in": "body", "type": "string", "required": true, "description": "Event name. Capped at 200 characters." },
+    { "name": "properties", "in": "body", "type": "object", "description": "Event properties (~16KB cap). `source: \"client\"` and the active `org_id` are added server-side." }
+  ],
+  "description": "Identity is resolved **server-side** from the session — browser code never passes a `userId`. Fire-and-forget: never blocks the UI, never throws, swallows network errors. Oversized or malformed payloads are rejected."
+}
+```
+
+```ts
+import { track } from "@agent-native/core/client";
+
+// e.g. inside a click handler or effect
+track("checkout.completed", { total: 49.99, items: 3 });
+```
+
+الاختلافات الرئيسية عن [server `track()`](#track):
+
+- **لا توجد وسيطة هوية.** يتم إسناد الحدث من جانب الخادم إلى المستخدم الذي قام بتسجيل الدخول (والمؤسسة النشطة، مثل `org_id` في `properties`). لا يمر رمز المتصفح أبدًا بـ `userId`.
+- **`source: "client"`** إلى خصائص كل حدث حتى تتمكن من التمييز بين الأحداث التي أنشأها العميل وأحداث الخادم.
+- **أطلق النار وانسى.** لا يؤدي ذلك أبدًا إلى حظر UI، ولا يؤدي مطلقًا إلى رمي أخطاء الشبكة أو ابتلاعها.
+- **تمت المصادقة عليه، للطرف الأول فقط.** يتطلب المسار جلسة وعلامة CSRF من نفس المصدر (يتم تعيينها تلقائيًا بواسطة المساعد)، لذلك لا يمكن استخدامه كترحيل تحليلات مفتوح. يبلغ الحد الأقصى لـ `name` 200 حرف و`properties` يصل إلى 16 كيلو بايت تقريبًا؛ يتم رفض الحمولات كبيرة الحجم أو المشوهة.
+
+يختلف هذا عن القياس عن بعد للمتصفح الداخلي لإطار العمل (`trackEvent()` / مشاهدات الصفحة التلقائية - راجع [Browser defaults](#browser-defaults) أدناه)، والذي يدعم تحليلات المنتج الخاصة بـ Agent Native. استخدم `track()` لأحداث التحليلات الخاصة بتطبيقك والتي يجب أن تصل إلى مقدمي الخدمة الذين تم تكوينهم.
+
+## متقدم: الموفرون المخصصون والداخليون {#advanced}
+
+تحتاج معظم التطبيقات فقط إلى `track()` / `identify()` وموفر مدمج. بقية السطح - تسجيل موفري الخدمة المخصصين، واجهة `TrackingProvider`، الأجزاء الداخلية المجمعة، والقياس عن بعد للمتصفح الخاص بإطار العمل - موجود أدناه.
+
+<details>
+<summary><strong>سجل مقدم الخدمة API والواجهة والأجزاء الداخلية والإعدادات الافتراضية للمتصفح</strong></summary>
+
+### `registerTrackingProvider(provider)` {#register}
+
+قم بتسجيل موفر مخصص لأي واجهة تحليلية خلفية.
+
+```ts
+import { registerTrackingProvider } from "@agent-native/core/tracking";
+
+registerTrackingProvider({
+  name: "my-analytics",
+  track(event) {
+    // Send event to your backend
+    fetch("https://analytics.example.com/events", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(event),
+    }).catch(() => {});
+  },
+  identify(userId, traits) {
+    // Optional — link user identity to future events
+  },
+  flush() {
+    // Optional — called on graceful shutdown
+  },
+});
+```
+
+### `flushTracking()` {#flush}
+
+مسح كافة مقدمي الخدمات. اتصل قبل إنهاء العملية للتأكد من إرسال الأحداث المعلقة.
+
+```ts
+import { flushTracking } from "@agent-native/core/tracking";
+
+await flushTracking();
+```
+
+### `unregisterTrackingProvider(name)` {#unregister}
+
+قم بإزالة الموفر بالاسم. يُرجع `true` إذا تم العثور على الموفر وإزالته.
+
+### `listTrackingProviders()` {#list}
+
+إرجاع أسماء كافة مقدمي الخدمة المسجلين.
+
+### واجهة TrackingProvider {#provider-interface}
+
+```ts
+interface TrackingProvider {
+  name: string;
+  track(event: TrackingEvent): void | Promise<void>;
+  identify?(
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+interface TrackingEvent {
+  name: string;
+  properties?: Record<string, unknown>;
+  timestamp?: string;
+  userId?: string;
+}
+```
+
+يلزم فقط `name` و`track`. يعد كل من `identify` و`flush` اختياريين — قم بتنفيذهما إذا كانت الواجهة الخلفية لديك تدعم هوية المستخدم والتسليم المجمع.
+
+### كيفية العمل {#internals}
+
+- **HTTP المجمعة** — يقوم الموفرون المضمنون بوضع الأحداث في قائمة الانتظار وتدفقها كل 10 ثوانٍ أو عندما يتراكم 50 حدثًا، أيهما يأتي أولاً. يؤدي هذا إلى تقليل الطلبات الصادرة دون فقدان البيانات.
+- **لا توجد تبعيات SDK** — يستخدم جميع موفري الخدمة المضمنين `fetch()` الخام. لا يوجد PostHog SDK، ولا Mixpanel SDK، ولا Amplitude SDK. يحافظ على إطار العمل خفيف الوزن.
+- **التسليم بأفضل جهد** — يتم اكتشاف أخطاء الموفر وتسجيلها. لا يؤدي فشل تكامل التحليلات إلى تعطل المتصل أو حظر معالجة الطلب.
+- **المفرد العام** — يستخدم السجل مفتاح `Symbol.for` على `globalThis`، لذا تشترك مثيلات الرسم البياني ESM المتعددة (وضع التطوير Vite + Nitro، الارتباطات الرمزية) في مجموعة موفر واحدة.
+
+### الإعدادات الافتراضية للمتصفح {#browser-defaults}
+
+يغطي هذا القياس الداخلي لإطار العمل - ويتعلق معظمه بالمساهمين في إطار العمل ومؤلفي النماذج المتقدمة.
+
+تستدعي جذور القالب `configureTracking()` مرة واحدة عند بدء التشغيل. تتضمن أحداث المتصفح المرسلة باستخدام `trackEvent()` تلقائيًا سياق التطبيق/القالب بالإضافة إلى اتصال LLM الحالي عندما يتمكن التطبيق من حل المشكلة:
+
+- `llm_connection` — تسمية الموفر التي تمت تسويتها مثل `builder`، أو `anthropic`، أو `openai`، أو `google`، أو `none`
+- `llm_engine` — معرف المحرك، على سبيل المثال `builder` أو `ai-sdk:openai`
+- `llm_model` — النموذج المحدد/الافتراضي عندما يكون معروفًا
+- `llm_connection_source` — `app_secrets`، أو `settings`، أو `env`
+- `llm_connection_configured` — ما إذا كان اتصال LLM متاحًا
+
+يتتبع إطار العمل أيضًا `builder connect clicked` من Connect Builder CTAs، ومسارات الاتصال Builder من جانب الخادم لتتبع أحداث دورة الحياة التي بدأت/نجحت/فشلت. يتم استدعاء `configureTracking()` تلقائيًا بواسطة إطار العمل؛ لا تحتاج إلى استدعائه في رمز القالب الخاص بك.
+
+</details>
+
+## ما هي الخطوة التالية
+
+- [**Actions**](/docs/actions) — حيث تنشأ معظم مكالمات التتبع
+- [**Server Plugins**](/docs/server) — يعمل `registerBuiltinProviders()` في البرنامج الإضافي للمسارات الأساسية عند بدء التشغيل
+- [**Secrets**](/docs/security) - إدارة مفاتيح API لموفري التتبع

package/docs/content/locales/ar-SA/using-your-agent.md

@@ -0,0 +1,71 @@
+---
+title: "استخدام الوكيل الخاص بك"
+description: "الحلقة اليومية للعمل مع الوكيل: فهو يرى ما تنظر إليه، وتقوم بتوجيهه، وتضمينه، واستخدام UI-light، والمشاركة في التحرير بجانبه."
+---
+
+# استخدام الوكيل الخاص بك
+
+الفكرة المحددة وراء Agent-Native هي أن الوكيل وUI **شريكان متساويان** — راجع [What Is Agent-Native?](/docs/what-is-agent-native) لمعرفة السبب. يتناول هذا القسم النصف الآخر من هذا الوعد: ما تشعر به عند العمل فعليًا مع الوكيل بمجرد تثبيته بجوار تطبيقك.
+
+هناك خط اتصال بسيط. يرى الوكيل ما تنظر إليه، وتوجهه نحو ما تريد، ويمكنك **تضمينه** في أي مكان، ويمكنك الانتقال بالكامل **UI-light** عندما يكون ذلك مناسبًا بشكل أفضل، ويمكنك **المشاركة في تحرير** نفس المستندات في نفس الوقت. كل منها عبارة عن صفحة في هذا القسم.
+
+```an-diagram title="The day-to-day loop" summary="Five ways of working with a docked agent — each is a page in this section."
+{
+  "html": "<div class=\"diagram-loop\"><div class=\"diagram-card\"><strong>Sees</strong><small class=\"diagram-muted\">your view &amp; selection</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Direct</strong><small class=\"diagram-muted\">@-mentions &amp; voice</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Embed</strong><small class=\"diagram-muted\">drop into any app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>UI-light</strong><small class=\"diagram-muted\">chat is the product</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">Co-edit</span><small class=\"diagram-muted\">live, side by side</small></div></div>",
+  "css": ".diagram-loop{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-loop .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:130px;flex:1}.diagram-loop .diagram-arrow{align-self:center;font-size:22px;line-height:1}"
+}
+```
+
+## يرى ما تنظر إليه {#it-sees}
+
+الوكيل ليس غافلًا عن شاشتك. افتح بريدًا إلكترونيًا ويعرف أي موضوع. حدد مخططًا ويعرف أي مخطط. قم بتمييز فقرة ويمكنها العمل على هذا النطاق فقط. وهذا الوعي المشترك هو ما يتيح لك قول "الرد على هذا" أو "تلخيص التحديد" دون توضيح السياق في كل مرة.
+
+يعمل هذا لأن التنقل والتحديد الحالي موجودان في `application_state` SQL، والذي يقرأه الوكيل كجزء من سياقه. يمكن للوكيل أيضًا استعادة نفس الحالة - فتح عرض، وتحديد صف - بحيث تشاهده وهو يعمل في UI الحقيقي بدلاً من النص.
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Shared awareness is two-way.** You and the agent both read and write `application_state`, so \"reply to this\" or \"summarize the selection\" just works — and when the agent navigates, the real UI moves with it."
+}
+```
+
+← [**Context Awareness**](/docs/context-awareness) — حالة التنقل، وشاشة العرض، وأوامر التنقل، وكيف يظل الوكيل متزامنًا مع شاشتك.
+
+## أنت تقوم بتوجيهه {#you-direct-it}
+
+في أغلب الأحيان، تقوم بتوجيه الوكيل عن طريق الكتابة في الدردشة. هناك شيئان يجعلان ذلك أسرع.
+
+**الإشارات.** ضع علامة على وكيل مخصص، أو وكيل متصل، أو ملف باستخدام `@` لسحبه إلى المحادثة - "اسمح لـ `@analytics` بسحب أرقام الأسبوع الماضي، ثم قم بصياغة الملخص." الإشارات هي كيفية الوصول إلى المتخصص المناسب أو إرفاق السياق الصحيح دون مغادرة الملحن.
+
+**الصوت.** الملحن لديه ميكروفون. قم بإملاء طلب بدلاً من كتابته، مع خيارات الموفر التي تتراوح بين النسخ المستضاف لـ Builder وإحضار مفتاحك الخاص إلى خيار احتياطي للمتصفح.
+
+← [**Agent Mentions**](/docs/agent-mentions) — `@` - الوكلاء المخصصون والوكلاء المتصلون والملفات في الدردشة.
+← [**Voice Input**](/docs/voice-input) — الإملاء في مؤلف الدردشة وكيفية توجيه النسخ.
+
+## قمت بتضمينه {#you-embed-it}
+
+الوكيل ليس تطبيقًا منفصلاً يمكنك الانتقال إليه. إنه يأتي كمجموعة من مكونات React - شريط جانبي، ولوحة أولية، ومكالمة `sendToAgentChat()` - التي تضعها في أي تطبيق. اعرض `<AgentSidebar>` لمنح كل شاشة وكيلًا قابلاً للتبديل، أو قم بتوصيل زر لتسليم مهمة معينة إلى الدردشة بدلاً من تشغيل مكالمة LLM لمرة واحدة.
+
+← [**Drop-in Agent**](/docs/drop-in-agent) - قم بتثبيت `<AgentPanel>` و`<AgentSidebar>` و`sendToAgentChat()` في أي تطبيق React.
+← [**Agent Surfaces**](/docs/agent-surfaces) - اختر ما إذا كان سير العمل يجب أن يكون بدون رأس، أو الدردشة أولاً، أو مضمنًا، أو تطبيقًا كاملاً.
+
+## يمكنك استخدام UI-light {#ui-light}
+
+لا يحتاج كل تطبيق إلى لوحة تحكم كاملة. عندما يكون الوكيل هو المنتج، يمكنك تخطي معظم UI المخصصة: افتح التطبيق، واطلب ما تريد، واترك الوكيل يقوم بالباقي. لا يزال لدى الوكيل سطح الإدارة الخاص به - السجل ومساحة العمل والإعدادات - ولكن التفاعل الأساسي هو المحادثة وليس النقرات.
+
+← [**Pure-Agent Apps**](/docs/pure-agent-apps) — التطبيقات التي يكون فيها الوكيل هو المنتج بالكامل.
+
+## يمكنك المشاركة في التحرير معه {#you-co-edit}
+
+عندما تعمل أنت والوكيل على نفس المستند، لا تتناوبان. من خلال التعاون في الوقت الفعلي، يتم بث تعديلات الوكيل جنبًا إلى جنب مع تعديلاتك - مؤشرات مباشرة، بدون استبدال - بنفس الطريقة التي يقوم بها زميل الفريق. يمكنك الاستمرار في الكتابة أثناء العمل، وسيرى التغييرات فور حدوثها.
+
+← [**Real-Time Collaboration**](/docs/real-time-collaboration) — تحرير تعاوني متعدد المستخدمين باستخدام المؤشرات المباشرة وتحريرات الوكيل في نفس المستند.
+
+## ما هي الخطوة التالية {#whats-next}
+
+- [**Context Awareness**](/docs/context-awareness) — يعرف الوكيل ما تنظر إليه
+- [**Agent Mentions**](/docs/agent-mentions) - قم بتوجيهه باستخدام إشارات `@`
+- [**Voice Input**](/docs/voice-input) — قم بتوجيهه عن طريق التحدث
+- [**Drop-in Agent**](/docs/drop-in-agent) - قم بتضمينه في أي تطبيق React
+- [**Pure-Agent Apps**](/docs/pure-agent-apps) - انتقل إلى UI عندما يكون الوكيل هو المنتج
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — تحرير نفس المستند معًا

package/docs/content/locales/ar-SA/voice-input.md

@@ -0,0 +1,81 @@
+---
+title: "الإدخال الصوتي"
+description: "الإملاء الصوتي في مؤلف دردشة الوكيل — Builder Gemini وموفرو BYOK والاحتياطي لحديث الويب في المتصفح."
+---
+
+# الإدخال الصوتي
+
+يحتوي كل تطبيق أصلي للوكيل على ميكروفون في مؤلف الدردشة. انقر فوقه، وتحدث، وسيتم نسخ كلماتك إلى الموجه. مفيد على الهاتف المحمول، ومفيد للمطالبات الطويلة، ومفيد عندما تكون يديك على شيء آخر.
+
+يتعامل إطار العمل مع كل هذا تلقائيًا. يحصل المستخدمون المتصلون بـ Builder على Gemini Flash-Lite المستضاف على Builder افتراضيًا؛ وإلا يمكن للمستخدمين إحضار مفتاح الموفر الخاص بهم أو العودة إلى التعرف على الكلام في المتصفح.
+
+## كيفية العمل {#how-it-works}
+
+يسجل زر صوت الملحن الصوت في المتصفح، ثم يختار الموفر:
+
+1. **Builder Gemini Flash-Lite (افتراضي عند اتصال Builder).** يقوم المتصفح بنشر الصوت إلى `/_agent-native/transcribe-voice`، الذي يقوم بالتوصيل من خلال Builder.io باستخدام Gemini Flash-Lite. لا يلزم وجود مفتاح Google API.
+2. **موفرو الخدمات السحابية BYOK.** يمكن للمستخدمين اختيار Google Gemini أو Groq Whisper أو OpenAI Whisper من الإعدادات. يحل المسار الأسرار المشفرة على نطاق المستخدم قبل بيانات اعتماد النشر المشتركة.
+3. **كلام الويب للمتصفح API (احتياطي).** في حالة عدم توفر موفر خادم، يمكن للمؤلف استخدام ميزة التعرف على الكلام المضمنة في المتصفح. يعمل في المتصفحات المستندة إلى Chromium (Chrome وEdge وArc) وSafari. أقل دقة؛ تيارات حية.
+
+يتم تخزين اختيار الموفر في حالة التطبيق ضمن `voice-transcription-prefs` بحيث يمكن للمستخدم فرض `"auto"` (افتراضي - يختار أفضل موفر متاح)، `"builder-gemini"`، `"builder"`، `"gemini"`، `"groq"`، `"openai"`، أو `"browser"` في إعدادات الشريط الجانبي.
+
+```an-diagram title="Voice transcription provider fallback" summary="The composer records audio, then walks server providers in order, dropping to the browser Web Speech API only when no server provider is available."
+{
+  "html": "<div class=\"diagram-voice\"><div class=\"diagram-node\">Mic button<br><small class=\"diagram-muted\">records webm/opus</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill accent\">1 &middot; Builder Gemini</div><small class=\"diagram-muted\">default when Builder connected</small><div class=\"diagram-pill\">2 &middot; BYOK cloud</div><small class=\"diagram-muted\">Gemini &middot; Groq &middot; OpenAI Whisper</small></div><div class=\"diagram-arrow diagram-warn\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box diagram-warn\" data-rough>3 &middot; Browser Web Speech<br><small class=\"diagram-muted\">fallback on 400 &middot; streams live</small></div></div>",
+  "css": ".diagram-voice{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-voice .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-voice .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+المسار **من نفس المصدر فقط** — يتم رفض المشاركات عبر المواقع، لذا لا يتمكن المهاجم من نسخ أرصدة النسخ من صفحة خارجية.
+
+## تمكين الموفرين {#enabling-providers}
+
+Builder هو المسار الأسهل: قم بتوصيل Builder.io من الإعدادات وسيصبح الموفر الافتراضي Builder Gemini Flash-Lite. بالنسبة لموفري BYOK، أضف المفتاح المطابق في الإعدادات → مفاتيح API.
+
+### لكل مستخدم (موصى به لـ SaaS)
+
+يقوم المستخدم بتعيين المفتاح الخاص به عبر إعدادات الشريط الجانبي للوكيل UI. يتم تخزينه باعتباره سرًا مشفرًا على مستوى المستخدم (عبر `readAppSecret`). يدفع كل مستخدم مقابل النسخ الخاص به؛ تكلفة صفر للمضيف.
+
+### مشتركة (للأدوات الداخلية)
+
+قم بتعيين `GEMINI_API_KEY` أو `GROQ_API_KEY` أو `OPENAI_API_KEY` كمتغير بيئة أو في الجدول `settings`. يقوم النسخ النصي لكل مستخدم بالنقر على المفتاح المشترك.
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Credential resolution order:** the route checks the user's own encrypted secret first, then the shared deployment key. A power user with their own key always overrides the shared one. If neither exists, the route returns a 400 the composer recognizes and silently falls back to browser Web Speech."
+}
+```
+
+## الطريق {#route}
+
+```an-api title="Voice transcription route"
+{
+  "method": "POST",
+  "path": "/_agent-native/transcribe-voice",
+  "summary": "Transcribe a recorded audio clip into prompt text",
+  "auth": "Active session (Better Auth cookie). Same-origin only.",
+  "description": "The composer POSTs the recorded clip here; the route resolves a provider and returns the transcribed text. You should not call this directly.",
+  "params": [
+    { "name": "audio", "in": "body", "type": "file", "required": true, "description": "The recorded clip, webm/opus by default. Max 25 MB." },
+    { "name": "provider", "in": "body", "type": "string", "required": false, "description": "Optional override, e.g. gemini, groq, openai, builder." }
+  ],
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "Transcription succeeded", "example": "{ \"text\": \"reply to Sara that I'll be there by 3\" }" },
+    { "status": "400", "description": "No server provider configured — the composer recognizes this and falls back to Web Speech", "example": "{ \"error\": \"no_provider\" }" }
+  ]
+}
+```
+
+لست بحاجة إلى استدعاء هذا مباشرة، فالملحن هو من يفعل ذلك. إذا كنت تقوم بإنشاء سطح إدخال مخصص، فأعد أولاً استخدام أجزاء العميل الملحن/الصوت المشتركة من `@agent-native/core/client`. تعامل مع هذا المسار باعتباره حد النقل منخفض المستوى للمساعدين المخصصين الذين يحتاجون إلى إرسال صوت متعدد الأجزاء.
+
+## تخصيص الموفر {#customizing}
+
+حقل الموفر هو مفتاح حالة تطبيق عادي، بحيث يمكن للوكيل تغييره عند الطلب (`"use the browser speech recognizer instead"`). إذا كنت تقوم بإنشاء قالب بمتطلبات مختلفة - على سبيل المثال، نشر Whisper محليًا - قم بتبديل معالج المسار عن طريق تسجيل مسار `transcribe-voice` الخاص بك قبل أن يقوم إطار العمل بتثبيت المسار الافتراضي.
+
+## ما هي الخطوة التالية
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — الملحن الذي يعرض زر الصوت
+- [**Onboarding**](/docs/onboarding) — تسجيل مفاتيح الموفر كخطوات إعداد
+- [**Security & Data Scoping**](/docs/security) — كيفية تخزين الأسرار المشفرة لكل مستخدم

package/docs/content/locales/ar-SA/what-is-agent-native.md

@@ -0,0 +1,202 @@
+---
+title: "ما هو Agent-Native؟"
+description: "لماذا تبدو معظم تطبيقات الذكاء الاصطناعي نصف مبنية، وما الذي يجعل التطبيق أصليًا بالفعل، وكيف تبدو تجربتك اليومية نتيجة لذلك."
+---
+
+# ما هو Agent-Native؟
+
+Agent-native هو وسيلة لبناء البرامج حيث يكون وكيل الذكاء الاصطناعي وسطح المنتج المحيط به **شركاء متساويين**. يمكن أن يكون هذا السطح وكيلًا بلا رأس مع إجراء مخصص واحد، أو دردشة غنية، أو UI كامل. الجزء المهم هو أن الوكلاء والبشر يتشاركون نفس actions وقاعدة البيانات والحالة.
+
+إذا كنت تتذكر شيئًا واحدًا فقط من هذه الصفحة، فتذكر هذا: معظم تطبيقات الذكاء الاصطناعي اليوم تتوقف بخطوة واحدة عن أن تكون مفيدة، وهذه الفجوة هي أكبر خطأ في هذا المجال في الوقت الحالي.
+
+## كيف يبدو الأمر كمستخدم {#what-it-looks-like}
+
+تصور عامل الخلفية أو البريد الوارد أو التقويم أو منشئ النماذج أو لوحة معلومات التحليلات. في بعض الأحيان لا توجد شاشة مخصصة حتى الآن: يمكنك تشغيل إجراء واحد أو مطالبة وكيل تطبيق مقطوعة الرأس. في بعض الأحيان تكون الشاشة الأولى عبارة عن دردشة: تسأل عما تريد، ويرشد الوكيل عملية الإعداد، ويعرض جدولاً أو مخططًا، ويفتح عرض التطبيق الصحيح. في بعض الأحيان يتم إرساء الدردشة على الجانب الأيمن من التطبيق الكامل. عبر هذه الأشكال، يمكنك:
+
+- **ابدأ بالعملية الحقيقية.** يمكن تنفيذ إجراء واحد دائم من CLI، وHTTP، وMCP، وA2A، وحلقة وكيل التطبيق، ولاحقًا UI.
+- **انقر على أي شيء تنقر عليه عادةً عندما يكون هناك UI.** جميع الأزرار، والقوائم، ولوحات المعلومات، واختصارات لوحة المفاتيح — كلها تستدعي نفس العمليات التي يمكن للوكيل الاتصال بها.
+- **أو اسأل فقط.** اكتب "الرد على رسالة البريد الإلكتروني الواردة من سارة والتي تفيد بأنني سأكون هناك بحلول الساعة 3" في الوكيل. فهو يفتح سلسلة الرسائل الصحيحة، ويصوغ الرد، ويعرضه لك للموافقة عليه - تمامًا كما لو كنت قد فعلت ذلك يدويًا.
+- **شاهد ما تراه.** افتح رسالة بريد إلكتروني، وسيعرف الوكيل أي منها. حدد مخططًا، وسيعرف الوكيل أي مخطط. قم بتمييز فقرة واضغط على Cmd+I، وسيعمل الوكيل على تلك الفقرة فقط.
+- **شاهد العمل.** أثناء قيام الوكيل بالأشياء - فتح طرق العرض، وتحرير المسودات، وتشغيل التقارير - يتم تحديث UI في الوقت الفعلي. يمكنك إيقافه أو إعادة توجيهه أو توليه بالماوس في أي لحظة.
+- **قم بتوجيهها كزميل في الفريق.** قدم تعليقات، وأضف مهمة أخرى إلى قائمة الانتظار، وقم بتحرير تعليماتها، وقم بمراجعة ما فعلته بالأمس. إنه يتذكر، ويتحسن في سير عملك بمرور الوقت.
+
+هذه هي التجربة التي تم تصميم Agent-Native من أجلها. إليك الآن سبب عدم وصول معظم المنتجات إلى هذا الهدف.
+
+## لماذا تفشل معظم "تطبيقات الذكاء الاصطناعي" (مبدأ السلم) {#the-ladder}
+
+هناك تقدم يتسلقه معظم الفرق، يشبه إلى حد كبير السلم، ويتوقف معظم الفرق عن درجة واحدة مبكرًا.
+
+### الدرجة 1 — استدعاء LLM واحد (النمط المضاد) {#rung-one}
+
+يرسل مربع النص مطالبة، ويقوم الذكاء الاصطناعي بإرجاع سلسلة، وتقوم أنت بعرضها. ربما مع الدوار. لا توجد طريقة للمستخدم لتصحيح المسار، ولا توجد طريقة للذكاء الاصطناعي لاتخاذ إجراء، ولا توجد طريقة لمعرفة ما حدث أو سببه.
+
+ترى هذا في كل مكان: "ميزات الذكاء الاصطناعي" التي هي في الأساس زر "تلخيص" مثبت بمنتج SaaS. إنهم يبدون مثيرين للإعجاب في العروض التوضيحية ويكسرون اللحظة التي يصبح فيها الواقع فوضويًا. هذا ليس منتجا. هذه لعبة.
+
+### الدرجة 2 - محادثة باستخدام الأدوات {#rung-two}
+
+الآن يستطيع الذكاء الاصطناعي _فعل الأشياء_. فهو يحتوي على أدوات - "مسودة البريد الإلكتروني"، و"البحث في جهات الاتصال"، و"تشغيل الاستعلام" - وواجهة دردشة حيث تعمل أمامك، وتعرض استدعاءات الأداة والنتائج أثناء التقدم. هذا هو الشكل الذي تبدو عليه Claude وChatGPT وCursor أسفل الغطاء.
+
+هذه خطوة حقيقية للأعلى. ولكن في حد ذاتها، فهي لا تزال بمثابة نافذة للدردشة. لا يوجد UI مناسب. لا توجد لوحات معلومات، ولا قوائم، ولا نماذج، ولا اختصارات لوحة المفاتيح، ولا تعاون الفريق. إذا أصبح الذكاء الاصطناعي مشوشًا، فستكون عالقًا في إعادة الكتابة بدلاً من مجرد النقر على الزر الأيمن. ويكافح غير المطورين لإنجاز عمل حقيقي بهذا التنسيق.
+
+### الدرجة 3 — الوكيل + UI كشركاء متساوين {#rung-three}
+
+هذا هو الوكيل الأصلي. يمكنك إضافة تطبيق حقيقي كامل الميزات حول الوكيل - والأهم من ذلك، أن كل إجراء يمكن للوكيل اتخاذه هو أيضًا زر في UI، وكل زر ينقر عليه المستخدم يعمل بنفس المنطق الذي يستخدمه الوكيل. تنفيذ واحد، طريقتان.
+
+ثلاثة أشياء تتغير عندما تصل إلى الدرجة 3:
+
+- **لقد توقفت عن إضافة الأزرار إلى برنامج الدردشة الآلي. لقد أضفت وكيلاً إلى أحد التطبيقات.** وهذا منتج عالي الجودة على كلا الجانبين.
+- **يتمتع الوكيل بسياق حقيقي.** فهو يرى ما تنظر إليه، وما حددته، وما فعلته للتو. فهو يكتب إلى نفس قاعدة البيانات التي يقرأ منها UI، لذلك يظهر عمله على الفور.
+- **يمكن للوكلاء الخارجيين استخدامه أيضًا.** يمكن لتطبيقات الوكيل الأصلية الأخرى استدعاء actions لهذا الشخص عبر [A2A protocol](/docs/a2a-protocol). يمكن لرمز Claude وتطبيقات Codex وChatGPT المخصصة MCP والمؤشر ومضيفي MCP الآخرين تشغيله باعتباره [MCP server](/docs/mcp-protocol). تطبيق واحد، ونقاط دخول متعددة.
+
+هذه هي الدرجة 3. هذا هو الوكيل الأصلي.
+
+```an-diagram title="The Ladder Principle" summary="Most teams stop at rung 1 or 2. Agent-native is rung 3 — a real app and a real agent over one shared action surface."
+{
+  "html": "<div class=\"diagram-ladder\"><div class=\"diagram-card rung rung-3\"><span class=\"diagram-pill accent\">Rung 3 · agent-native</span><strong>Agent + UI as equal partners</strong><small class=\"diagram-muted\">One action surface. Every agent tool is also a button; every button runs the same logic the agent uses.</small></div><div class=\"diagram-card rung rung-2\"><span class=\"diagram-pill\">Rung 2</span><strong>A chat with tools</strong><small class=\"diagram-muted\">The agent can act — but it is still just a chat window. No dashboards, lists, or shortcuts.</small></div><div class=\"diagram-card rung rung-1\"><span class=\"diagram-pill warn\">Rung 1</span><strong>A single LLM call</strong><small class=\"diagram-muted\">Prompt in, string out. Impressive in a demo; breaks the moment reality gets messy.</small></div></div>",
+  "css": ".diagram-ladder{display:flex;flex-direction:column;gap:14px}.diagram-ladder .rung{display:flex;flex-direction:column;gap:6px;padding:16px 18px}.diagram-ladder .rung-2{margin-inline-end:48px}.diagram-ladder .rung-1{margin-inline-end:96px}"
+}
+```
+
+راجع [Key Concepts — Protocols](/docs/key-concepts#protocols) لمعرفة كيفية تعليق كل هذا على نفس تعريف الإجراء.
+
+## لماذا يحتاج كل وكيل إلى UI {#why-every-agent-needs-a-ui}
+
+حتى عندما يقوم الوكيل بكل المهام الثقيلة، لا يزال البشر بحاجة إلى:
+
+- **شاهد ما يفعله** — التقدم، والمخرجات المتوسطة، وما تم لمسه
+- **توجيه الأمر** — تقديم تعليقات، ومقاطعة، ووضع المهمة التالية في قائمة الانتظار
+- **إدارتها** — تعديل تعليماتها، skills، الذاكرة، المهام المجدولة، الحسابات المتصلة
+- **فحص العمل** — مراجعة المسودات وسجل التدقيق والتراجع عن الأخطاء
+- **مشاركة نتائجه** — لوحات المعلومات، والتقارير، والنماذج، والروابط لإرسالها إلى أعضاء الفريق
+
+على الأقل، "UI للوكيل" عبارة عن لوحة تحكم لإمكانية المراقبة والإدارة. كحد أقصى، إنه تطبيق SaaS كامل مع تضمين الوكيل كطيار مساعد. يعتبر كلا الطرفين وكيلًا أصليًا، ويمكن أن ينمو السطح من أحدهما دون إعادة كتابته.
+
+ليس عليك اختيار شكل مقدمًا. يمكن للوكيل أن يعمل بلا رأس، أو يجلس خلف محادثة غنية، أو يعيش داخل تطبيق كامل حول نفس سطح الإجراء - راجع [Agent Surfaces](/docs/agent-surfaces) للتعرف على الأشكال الملموسة وAPI.
+
+## لماذا يستفيد كل تطبيق من الوكيل {#why-every-app-benefits-from-an-agent}
+
+الجانب الآخر لا يقل أهمية. تستمر منتجات SaaS الحالية في الوصول إلى نفس الجدار: 80% مما تحتاجه يعمل بشكل رائع، و20% لا يمكنك تغييره. نادرًا ما تؤدي إضافة شريط جانبي للدردشة إلى حل هذه المشكلة - عادةً لا تتمكن الدردشة فعليًا من _فعل_ الأشياء التي يستطيع UI القيام بها.
+
+الوكيل الأصلي يقلب ذلك. نظرًا لأن كل إجراء في التطبيق يتم تعريفه مرة واحدة ويتم عرضه كزر وأداة وكيل، يمكن للوكيل القيام بكل ما تستطيع الأزرار فعله - وأكثر - دون الحاجة إلى "عالم ذكاء اصطناعي" منفصل للمحافظة عليه. تصبح اللغة الطبيعية مدخلاً من الدرجة الأولى إلى جانب النقرات.
+
+الحجة ليست "الوكلاء يستبدلون UI." إنه "**الوكلاء ينتمون إلى داخل التطبيقات، مع وجود UI في الأعلى، كشركاء متساوين**." حتى التطبيق الذي يكون فيه الوكيل هو المنتج لا يزال يحتاج إلى UI ليتمكن البشر من الإشراف عليه وتهيئته وتوجيهه - راجع [Agent Surfaces — Headless](/docs/agent-surfaces#headless).
+
+## الوكيل + تكافؤ UI {#agent-ui-parity}
+
+هذا هو المبدأ المحدد.
+
+> **من UI** — انقر على الأزرار، واملأ النماذج، وتنقل بين طرق العرض. يكتب UI إلى قاعدة البيانات؛ يرى الوكيل النتائج.
+>
+> **من الوكيل** — لغة طبيعية، وكلاء آخرون عبر A2A، Slack، Telegram. يكتب الوكيل إلى قاعدة البيانات؛ يتم تحديث UI تلقائيًا.
+
+```an-diagram title="One system, two ways in" summary="The agent and the UI write to the same actions and the same database. Whatever one does, the other sees."
+{
+  "html": "<div class=\"diagram-parity\"><div class=\"diagram-col\"><div class=\"diagram-node\">Human<br><small class=\"diagram-muted\">clicks, forms, shortcuts</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">natural language · A2A · Slack</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defined once</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">SQL database</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">UI updates live</div></div>",
+  "css": ".diagram-parity{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-parity .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-parity .diagram-arrow{font-size:22px;line-height:1}.diagram-parity .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+عندما يقوم الوكيل بإنشاء مسودة بريد إلكتروني، تظهر في UI. عند النقر فوق "إرسال"، يعلم الوكيل أنه تم إرساله. لا يوجد "عالم وكيل" منفصل و"عالم UI" - إنه نظام واحد. راجع [Key Concepts](/docs/key-concepts) للتعرف على البنية التي تجعل هذا العمل.
+
+## التخصيص مخصص عادةً للأدوات الكهربائية {#workspace-customization}
+
+السبب الذي يجعل الأدوات مثل Claude تبدو قوية للغاية ليس النموذج - بل **طبقة التخصيص**: تعليمات لكل مشروع، وskills، والذاكرة، والوكلاء الفرعيين، والخدمات المتصلة. يمكنك تشكيل الوكيل وفقًا لقاعدة التعليمات البرمجية الخاصة بك وتفضيلاتك وفريقك.
+
+يمنح Agent-native كل مستخدم نفس طبقة التخصيص - دون مغادرة التطبيق مطلقًا. يأتي كل تطبيق مزودًا بـ **مساحة عمل** شخصية حيث يمكنك (أو أي شخص في فريقك) القيام بما يلي:
+
+- تحرير القواعد على مستوى الفريق التي يقرأها كل وكيل
+- اسمح للوكيل بتذكر التفضيلات تلقائيًا أثناء تصحيحها
+- اكتب أدلة إرشادية قابلة لإعادة الاستخدام كأوامر `/slash`
+- الاحتفاظ بالوكلاء الفرعيين المخصصين لمهام محددة (التي يتم استدعاؤها باستخدام `@mentions`)
+- جدولة المهام ليتم تشغيلها على cron (على سبيل المثال، "كل صباح يوم اثنين، تلخيص الأسبوع الماضي")
+- ربط الخدمات الخارجية (Gmail، Stripe، Slack، APIs الداخلية) عبر خوادم MCP لكل مستخدم
+
+التطور: يتم تخزين كل شيء في قاعدة البيانات، وليس في نظام الملفات. لا توجد بيئة تطوير للتدوير، ولا توجد حاوية لكل مستخدم. يحصل كل مستخدم على مساحة العمل الكاملة الخاصة به - الذاكرة الشخصية، والاتصالات الشخصية، وskills الشخصية - مجانًا بشكل أساسي، لأنها كلها عبارة عن صفوف في جدول. وهذا ما يجعل المرونة على مستوى الكود Claude قابلة للتطبيق داخل منتج SaaS حقيقي متعدد المستأجرين.
+
+راجع [Workspace](/docs/workspace) للتعرف على المفهوم الكامل.
+
+## ما الذي يجعلها مختلفة {#what-makes-it-different}
+
+| النهج                                             | الوصف                                                                                                                                             |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **التطبيقات التقليدية المدعمة بالذكاء الاصطناعي** | الذكاء الاصطناعي هو فكرة لاحقة. يقتصر على الإكمال التلقائي أو الملخصات أو الشريط الجانبي للدردشة الذي لا يمكنه فعل أي شيء في التطبيق.             |
+| **واجهات الدردشة/الوكلاء النقية**                 | قوية ولكن لا يمكن الوصول إليها. لا توجد لوحات معلومات، ولا سير عمل، ولا استمرار. ولا يمكن لغير المطورين استخدامها بشكل فعال.                      |
+| **رمز Claude / Codex لـ SaaS**                    | رائعة للمطورين على أجهزتهم الخاصة. لا يتم ترجمته إلى SaaS متعدد المستأجرين — لا يمكن توسيع قاعدة تعليمات برمجية واحدة لكل مستخدم في مربع التطوير. |
+| **تطبيقات الوكيل الأصلية**                        | الوكيل مواطن من الدرجة الأولى. فهو يشترك في نفس قاعدة البيانات، ونفس الحالة، ويمكنه فعل كل ما يمكن أن يفعله UI - والعكس صحيح.                     |
+
+## تطوير الفريق بأكمله {#whole-team-development}
+
+الوكيل الأصلي ليس مخصصًا للمطورين فقط. نظرًا لأن الوكيل يمكنه تعديل التعليمات البرمجية الخاصة بالتطبيق، فإن تطوير التطبيق يتوقف عن كونه نشاطًا مخصصًا للمطورين فقط:
+
+- **يقوم المصممون** بتحديث التصميمات مباشرة في التطبيق قيد التشغيل من خلال الوكيل
+- **يضيف مديرو المنتجات** الوظائف ويحدثون التدفقات من خلال وصفها
+- **QA** يختبر التطبيق ويطلب من الوكيل إصلاح العطل
+- **يساهم أي شخص في الفريق** من خلال اللغة الطبيعية
+
+الرؤية: عدد أقل من عمليات التسليم، وشخص واحد يقوم بعمل فريق صغير.
+
+## الشوكة والتخصيص {#fork-and-customize}
+
+تتبع التطبيقات الأصلية للوكيل نموذج الشوكة والتخصيص. تبدأ من **القالب** — التقويم، والمحتوى، والشرائح، والتحليلات، والبريد، والمقاطع، والتصميم، والنماذج، والإرسال — وتجعله خاصًا بك. كل منتج عبارة عن منتج SaaS كامل وفعال يمكنك تفرعه بالجملة، وليس سقالة فارغة:
+
+1. اختر نموذجًا على [agent-native.com/templates](/templates)
+2. استخدمه فورًا كتطبيق مستضاف (مثل mail.agent-native.com)
+3. افصلها عندما تريد التخصيص — "ربط حساب Stripe الخاص بنا"، "أضف مخططًا جماعيًا"
+4. يقوم الوكيل بتعديل الكود ليتناسب مع احتياجاتك
+5. انشر تفرعك على المجال الخاص بك - أو ابقَ على موقع agent-native.com
+
+نظرًا لأنه _your_ التطبيق، وليس بنية تحتية مشتركة، يمكن للوكيل تطوير التعليمات البرمجية بأمان. يستمر تطبيقك في التحسن أثناء استخدامه. راجع [Templates](/docs/cloneable-saas) للحصول على القصة الكاملة.
+
+لست مستعدًا لتقسيم قالب كامل؟ يمكنك أيضًا تجربة Agent-Native عن طريق إضافة **مهارة** إلى وكيل الترميز الذي تستخدمه بالفعل — قم بتثبيت مهارة الخطط باستخدام `npx @agent-native/core@latest skills add visual-plan`. انظر [Skills Guide](/docs/skills-guide#app-backed-skills).
+
+## العوامل القابلة للتركيب {#composable-agents}
+
+يمكن لتطبيقات الوكيل الأصلية التحدث مع بعضها البعض. من داخل تطبيق البريد، يمكنك وضع علامة على وكيل التحليلات للاستعلام عن البيانات وتضمين النتيجة في مسودة بريد إلكتروني. يكتشف الوكلاء الوكلاء الآخرين المتاحين، ويتبادلون العمل فيما بينهم، ويعرضون النتائج في UI الذي تتواجد فيه بالفعل.
+
+يتم تشغيل هذا بواسطة [A2A](/docs/a2a-protocol) و[MCP](/docs/mcp-protocol) تحت الغطاء - نفس التعريف، وأسطح متعددة - ولكن كمستخدم، كل ما عليك معرفته هو "يمكنني أن أطلب المساعدة من أي من تطبيقاتي في أي شيء يمكن لأي منهم القيام به."
+
+## كيف يبدو هذا في الكود؟ {#what-does-it-look-like-in-code}
+
+إذا كنت تقوم بإنشاء تطبيق وكيل أصلي أو توسيعه، فإليك النمط المركزي: كل عملية في التطبيق عبارة عن **إجراء** — محدد مرة واحدة، ومتاح لكل من الوكيل وUI.
+
+```an-annotated-code title="One action, defined once"
+{
+  "filename": "actions/reply-to-email.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"Reply to an email thread\",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    // db and schema come from your app's server/db setup\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this as a tool." },
+    { "lines": "6", "label": "عقد typed", "note": "One zod `schema` validates input from **every** surface — agent, UI, HTTP, MCP, and A2A." },
+    { "lines": "7-10", "label": "One implementation", "note": "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this." }
+  ]
+}
+```
+
+```tsx
+// In any React component — same action, called from a button
+const { mutate } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+```tsx
+// And the agent panel mounted anywhere in your app
+import { AgentSidebar } from "@agent-native/core/client";
+
+<AgentSidebar />;
+```
+
+إجراء واحد، والعديد من الأسطح: يسميه الوكيل كأداة، ويسميه UI كطفرة آمنة للكتابة، ويمكن لـ [native chat](/docs/native-chat-ui) تقديم نتائج واضحة لعناصر واجهة المستخدم، ويصل إليها الوكلاء الخارجيون عبر [A2A](/docs/a2a-protocol)، ويطلق عليها مضيفو MCP من خلال [MCP server](/docs/mcp-protocol) للتطبيق، اختياريًا باستخدام موارد MCP Apps UI وجهاز التحكم عن بعد القياسي MCP OAuth يتم التعامل معها بواسطة الإطار. راجع [Actions](/docs/actions) للحصول على المرجع الكامل.
+
+## ما هي الخطوة التالية {#whats-next}
+
+- [**Getting Started**](/docs/getting-started) - ابدأ بإجراء واحد، أو اختر قالبًا، أو قم بتثبيت مهارة
+- [**Agent Surfaces**](/docs/agent-surfaces) - اختر الدردشة بدون رأس أو الدردشة الغنية أو السيارة الجانبية المضمنة أو التطبيق الكامل
+- [**Key Concepts**](/docs/key-concepts) — البنية: SQL، actions، مزامنة الاستقصاء، الوعي بالسياق، إمكانية النقل
+- [**Templates**](/docs/cloneable-saas) — نماذج كمنتجات كاملة تمتلكها
+- [**Workspace**](/docs/workspace) — طبقة التخصيص لكل مستخدم (skills، الذاكرة، التعليمات، MCP) المدعومة بـ SQL، وليس الملفات
+- [**Dispatch**](/docs/dispatch) — مستوى التحكم في مساحة العمل: قبو الأسرار، Slack، صندوق البريد الإلكتروني، التفويض عبر التطبيقات
+- [**Extensions**](/docs/extensions) — تطبيقات صغيرة في وضع الحماية ينشئها الوكيل على الفور دون تغيير التعليمات البرمجية
+- [**Drop-in Agent**](/docs/drop-in-agent) - قم بتثبيت `<AgentPanel>` في أي تطبيق React