@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,332 @@
+---
+title: "المصادقة"
+description: "تكامل أفضل للمصادقة مع البريد الإلكتروني/كلمة المرور ومقدمي الخدمات الاجتماعية والمؤسسات وبيانات اعتماد حامل MCP."
+---
+
+# المصادقة
+
+تستخدم التطبيقات الأصلية للوكيل [Better Auth](https://better-auth.com) للمصادقة من خلال تصميم الحساب أولاً. يقوم المستخدمون بإنشاء حساب عند الزيارة الأولى ويحصلون على هوية حقيقية من اليوم الأول.
+
+## نظرة عامة {#overview}
+
+يتم تكوين المصادقة تلقائيًا عبر `autoMountAuth(app)` في البرنامج الإضافي لخادم المصادقة. هناك ثلاثة أوضاع:
+
+- **الافتراضي:** مصادقة أفضل باستخدام البريد الإلكتروني/كلمة المرور + مقدمي خدمات التواصل الاجتماعي. تظهر صفحة الإعداد عند الزيارة الأولى.
+- **جهاز التحكم عن بعد MCP OAuth:** معيار OAuth 2.1 لمضيفي MCP مثل Claude Code وموصلات ChatGPT.
+- **مخصص:** قم بإحضار المصادقة الخاصة بك عبر رد الاتصال `getSession`.
+
+```an-diagram title="Three ways in, one session" summary="Browser visitors, programmatic MCP clients, and custom providers all resolve to the same AuthSession that downstream scoping reads."
+{
+  "html": "<div class=\"auth-modes\"><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Default</span><strong>Better Auth</strong><small class=\"diagram-muted\">email/password &middot; Google &middot; GitHub</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Remote MCP OAuth</span><strong>OAuth 2.1 + PKCE</strong><small class=\"diagram-muted\">Claude Code, ChatGPT connectors</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Custom</span><strong>getSession callback</strong><small class=\"diagram-muted\">Clerk &middot; Auth0 &middot; Firebase</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill ok\">AuthSession</span><small class=\"diagram-muted\">email &middot; orgId &middot; orgRole</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Request context &amp; data scoping</div></div>",
+  "css": ".auth-modes{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.auth-modes .diagram-col{display:flex;flex-direction:column;gap:10px}.auth-modes .diagram-card{display:flex;flex-direction:column;gap:4px;padding:10px 12px}.auth-modes .diagram-arrow{font-size:22px;line-height:1}.auth-modes .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+تدفق المتصفح هو نفس تدفق المصادقة الأفضل في كل مكان - لا يوجد **تجاوز مصادقة التطوير**، ولا يعود `getSession()` أبدًا إلى حارس `local@localhost`. ما يتغير بين البيئات هو احتكاك الاشتراك، وليس جدار تسجيل الدخول:
+
+| البيئة                  | سلوك التحميل الأول                                                                     | التحقق من البريد الإلكتروني                                |
+| ----------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| **التطوير المحلي**      | إنشاء حساب مطور سريعًا تلقائيًا وتسجيل دخولك (بدون جدار تسجيل الدخول)                  | يتم تخطيه افتراضيًا (وفي حالة عدم وجود مزود بريد إلكتروني) |
+| **سؤال وجواب / معاينة** | اشتراك عادي، ولكن يمكن تخطي عملية التحقق حتى لا ينتظر المختبرون وصول البريد الإلكتروني | التخطي باستخدام `AUTH_SKIP_EMAIL_VERIFICATION=1`           |
+| **الإنتاج**             | تسجيل/تسجيل مصادقة أفضل عادي                                                           | مطلوب (عند تكوين موفر البريد الإلكتروني)                   |
+
+تقوم بعض الأعلام بضبط هذا؛ التفاصيل الكاملة موجودة في جدول [Environment Variables](#environment-variables):
+
+- `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1` — استخدم صفحة التسجيل العادية في حساب التطوير المحلي بدلاً من حساب التطوير التلقائي.
+- `AUTH_DISABLED=true` - تخطي تسجيل الدخول/الاشتراك بالكامل وتشغيل كل طلب كمستخدم مشترك واحد (التطوير المحلي / المعاينات / العروض التوضيحية فقط، لا يتم الإنتاج مطلقًا مع مستخدمين حقيقيين).
+- `AUTH_MODE=local` - يؤثر فقط على هوية CLI/الوكيل (التي يعمل بها مستخدم التطوير `pnpm action`)؛ إنه **ليس** تجاوزًا لتسجيل الدخول إلى المتصفح.
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "`AUTH_DISABLED=true` runs **every request as one shared user**. Use it only for local dev, previews, or demos — never in production with real users, where it would expose all data to anyone."
+}
+```
+
+## مصادقة أفضل (افتراضي) {#better-auth}
+
+بشكل افتراضي، تقوم Better Auth بتشغيل المصادقة. ويقدم:
+
+- تسجيل البريد الإلكتروني/كلمة المرور وتسجيل الدخول
+- مقدمو الخدمات الاجتماعية (Google، وGitHub، وأكثر من 35 آخرين)
+- المؤسسات ذات الأدوار والدعوات
+- رموز JWT للوصول إلى API وA2A
+- دعم الرمز المميز للعملاء الآليين
+
+تم تثبيت مسارات المصادقة الأفضل على `/_agent-native/auth/ba/*`. يوفر إطار العمل أيضًا نقاط نهاية متوافقة مع الإصدارات السابقة:
+
+- `GET /_agent-native/auth/session` — احصل على الجلسة الحالية
+- `POST /_agent-native/auth/login` — تسجيل الدخول بالبريد الإلكتروني/كلمة المرور
+- `POST /_agent-native/auth/register` — إنشاء حساب
+- `POST /_agent-native/auth/logout` — تسجيل الخروج
+
+## مجالات ملفات تعريف الارتباط {#cookie-realms}
+
+يتبع مجال ملف تعريف الارتباط للجلسة شكل النشر، لذا فإن التطبيقات التي تشترك في
+تسجيل الدخول إلى قاعدة البيانات/مشاركة الأصل والتطبيقات التي لا تظل معزولة:
+
+| شكل النشر                                      | مجال ملفات تعريف الارتباط                                                                                                    |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| تطبيق مستقل                                    | معزولة لكل تطبيق بواسطة سبيكة (`APP_NAME`، أو اسم الحزمة في المطور المحلي)؛ بادئة `an` مستقرة في الإنتاج                     |
+| وضع مساحة العمل (`AGENT_NATIVE_WORKSPACE=1`)   | عالم مشترك واحد - تشترك تطبيقات مساحة العمل في الأصل وقاعدة البيانات                                                         |
+| النطاقات الفرعية المخصصة لقاعدة البيانات نفسها | اشتراك في ملفات تعريف الارتباط المشتركة مع `COOKIE_DOMAIN`                                                                   |
+| استضافة الطرف الأول (`*.agent-native.com`)     | مساحة اسم معزولة لكل تطبيق (لكل تطبيق قاعدة بيانات مصادقة خاصة به)؛ يتم تجاهل `COOKIE_DOMAIN=.agent-native.com` بشكل افتراضي |
+
+يحتوي كل من التطبيقات المستضافة من الطرف الأول على قاعدة بيانات مصادقة خاصة به، لذا فإن تسجيل الدخول عبر التطبيقات
+يمر عبر [Cross-App SSO](/docs/cross-app-sso) بدلاً من ملف تعريف الارتباط المشترك.
+يجب أن توفر عمليات النشر هذه `APP_NAME` أو تطبيق مشتق URL (`APP_URL`, `URL`,
+`DEPLOY_PRIME_URL`، أو `DEPLOY_URL`)؛ وإلا فسيفشل بدء التشغيل بدلاً من السقوط
+الرجوع إلى اسم `an_session` المشترك. لمشاركة قاعدة بيانات مصادقة واحدة عن قصد
+عبر النطاقات الفرعية، قم بتعيين `AGENT_NATIVE_SHARE_COOKIE_DOMAIN=1` جنبًا إلى جنب مع
+`COOKIE_DOMAIN`.
+
+## حسابات ضمان الجودة {#qa-accounts}
+
+تتخطى عمليات التطوير والاختبارات المحلية التحقق من البريد الإلكتروني للتسجيل بشكل افتراضي، لذا
+إنشاء حسابات بريد إلكتروني/كلمات مرور حقيقية دون انتظار البريد الوارد. للقوة
+التحقق محليًا أثناء اختبار هذا التدفق، قم بتعيين `AUTH_SKIP_EMAIL_VERIFICATION=0`.
+
+بالنسبة لبيئات ضمان الجودة المستضافة حيث يحتاج المختبرون إلى حسابات حقيقية ولكن لا ينبغي عليهم الانتظار
+عند تسليم البريد الإلكتروني، قم بتعيين:
+
+```bash
+AUTH_SKIP_EMAIL_VERIFICATION=1
+```
+
+عند تعيين هذه العلامة، لا يتطلب الاشتراك بالبريد الإلكتروني/كلمة المرور بريدًا إلكترونيًا
+لم يتم إرسال التحقق والبريد الإلكتروني للتحقق من الاشتراك. استخدمه فقط من أجل ضمان الجودة
+أو معاينة البيئات، وتسمية حسابات الاختبار بعنوان `+qa`
+(`name+qa@example.com`) حتى يسهل التعرف عليها.
+
+## مقدمو الخدمات الاجتماعية {#social-providers}
+
+قم بتعيين متغيرات البيئة لتمكين تسجيل الدخول الاجتماعي. تكتشفها المصادقة الأفضل تلقائيًا:
+
+```bash
+# Google OAuth
+GOOGLE_SIGN_IN_CLIENT_ID=your-low-scope-sign-in-client-id
+GOOGLE_SIGN_IN_CLIENT_SECRET=your-low-scope-sign-in-client-secret
+
+# Backwards-compatible fallback, and provider OAuth credentials for templates
+# that connect to Google APIs such as Gmail or Calendar.
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-client-secret
+
+# GitHub OAuth
+GITHUB_CLIENT_ID=your-client-id
+GITHUB_CLIENT_SECRET=your-client-secret
+```
+
+تعرض النماذج التي تستخدم `createGoogleAuthPlugin()` صفحة "تسجيل الدخول باستخدام Google". يعالج رد الاتصال Google OAuth الارتباط العميق للجوال للتطبيقات الأصلية تلقائيًا.
+
+يُفضل `GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET` للوضع العادي
+تسجيل الدخول للتطبيق. يجب أن يطلب هذا العميل نطاقات الهوية فقط. احتفظ
+`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` لعمليات تكامل المنتجات التي تحتاج إلى
+نطاقات Google API، أو كبديل قديم عندما لا يتم تقسيم النشر
+حتى الآن. يجب أن تستخدم تطبيقات البريد والتقويم عملاء المزودين الخاصين بها OAuth لذلك
+لا تؤثر شاشات الموافقة واسعة النطاق على تسجيل الدخول العام إلى التطبيق.
+
+### توقيع الحالة OAuth {#oauth-state-secret}
+
+قم بتعيين `OAUTH_STATE_SECRET` على قيمة عشوائية تزيد عن 32 حرفًا في الإنتاج، بحيث تكون مظاريف الحالة OAuth (Google وAtlassian وZoom) موقعة بـ HMAC بمفتاح مخصص مستقل عن أي سر لجهة خارجية. راجع [Security — OAuth State Signing](/docs/security#oauth-state) للاطلاع على المتطلبات الكاملة ونموذج التهديد.
+
+## المنظمات {#organizations}
+
+يوفر إطار العمل نظامًا تنظيميًا مدمجًا. هذه هي وحدة `org/` الخاصة بإطار العمل - والمدعومة بجداول `organizations` و`org_members` - وليست مكونًا إضافيًا لمؤسسة Better Auth، والذي لم يتم تسجيله عمدًا. يدعم كل تطبيق:
+
+- إنشاء المنظمات
+- دعوة الأعضاء بأدوار (`owner`، `admin`، `member`)
+- تبديل المؤسسة النشطة
+- تحديد نطاق البيانات لكل مؤسسة عبر أعمدة `org_id`
+
+يتم تعقب المؤسسة النشطة في الجلسة باسم `session.orgId`، ويؤدي تبديل المؤسسات إلى تغيير البيانات التي يراها المستخدم والوكيل. يحدث تحديد نطاق البيانات نفسه في أسفل المكدس - راجع [Security & Data Scoping](/docs/security#data-scoping) للتعرف على خط أنابيب `session.orgId → AGENT_ORG_ID → SQL` الكامل ووحدات حماية الوصول. تغطي مستندات [Multi-Tenancy](/docs/multi-tenancy) سطح إدارة المؤسسة.
+
+## رموز حامل MCP الثابتة {#access-tokens}
+
+`ACCESS_TOKEN` و`ACCESS_TOKENS` ليسا بمثابة مصادقة للمتصفح ولا يجعلان التطبيق خاصًا. وتظل فقط بمثابة بيانات اعتماد حامل ثابتة لعملاء MCP/connect الذين لا يمكنهم استخدام تدفق OAuth.
+
+```bash
+# Single token
+ACCESS_TOKEN=my-secret-token
+
+# Multiple tokens
+ACCESS_TOKENS=token1,token2,token3
+```
+
+لا يؤدي تكوين هذه المتغيرات أبدًا إلى عرض صفحة تسجيل دخول مميزة للزائرين. يظل تسجيل الدخول عبر الويب على Better Auth أو موفر `getSession` المخصص لديك.
+
+## جهاز التحكم عن بعد MCP OAuth {#remote-mcp-oauth}
+
+يمكن أن تعمل نقطة نهاية MCP لكل تطبيق كمورد MCP قياسي محمي. يمكن تكوين العملاء القادرين على OAuth باستخدام MCP URL البعيد فقط:
+
+```text
+https://mail.agent-native.com/_agent-native/mcp
+```
+
+تقوم طلبات MCP غير المصادق عليها بإرجاع تحدي `WWW-Authenticate` الذي يشير إلى `/.well-known/oauth-protected-resource`. يكتشف العميل بعد ذلك بيانات تعريف OAuth الخاصة بالتطبيق، ويسجل عميلًا عامًا ديناميكيًا، ويفتح صفحة ترخيص التطبيق، ويتبادل رمز التفويض مع PKCE للوصول إلى الرموز المميزة وتحديثها.
+
+```an-diagram title="Remote MCP OAuth handshake" summary="An OAuth-capable client bootstraps from just the MCP URL — challenge, discovery, dynamic registration, then a PKCE code exchange."
+{
+  "html": "<div class=\"mcp-flow\"><div class=\"diagram-node\">1 &middot; MCP request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node warn\">2 &middot; 401 challenge<br><small class=\"diagram-muted\">WWW-Authenticate</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">3 &middot; Discover metadata<br><small class=\"diagram-muted\">.well-known</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">4 &middot; Register client<br><small class=\"diagram-muted\">dynamic, public</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">5 &middot; Authorize + PKCE<br><small class=\"diagram-muted\">code exchange</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">6 &middot; Access + refresh<br><small class=\"diagram-muted\">audience-bound</small></div></div>",
+  "css": ".mcp-flow{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.mcp-flow .diagram-node{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.mcp-flow .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+يتم توقيع رموز الوصول باستخدام `A2A_SECRET` عند تعيينها، وإلا مع `BETTER_AUTH_SECRET`. وهي تحمل هوية المستخدم/المؤسسة الموقعة ونطاقات `mcp:read` و/أو `mcp:write` و/أو `mcp:apps`، وهي مرتبطة بالجمهور بمورد MCP الدقيق URL. يتم تخزين رموز التحديث فقط كتجزئة ويتم تدويرها عند كل تحديث. يتم تشغيل استدعاءات الأدوات وقراءات موارد تطبيقات MCP داخل نفس سياق الطلب مثل المستخدم الذي قام بتسجيل الدخول؛ لا يتلقى إطار iframe لتطبيق MCP المضمن رموز OAuth الأولية أبدًا.
+
+يكتب `npx @agent-native/core@latest connect <url> --client claude-code` إدخال URL فقط MCP لهذا التدفق القياسي. بالنسبة للعملاء الذين لا يمكنهم تنفيذ MCP OAuth عن بعد، استخدم صفحة الاتصال أو البديل `npx @agent-native/core@latest connect --token <token>` لكتابة إدخال صريح للرمز المميز للحامل.
+
+## إحضار المصادقة الخاصة بك {#byoa}
+
+قم بتمرير رد اتصال `getSession` مخصص لاستخدام أي موفر مصادقة (Clerk، Auth0، Firebase، وما إلى ذلك):
+
+```ts
+// server/plugins/auth.ts
+import { createAuthPlugin } from "@agent-native/core/server";
+
+export default createAuthPlugin({
+  getSession: async (event) => {
+    // Your custom auth logic here
+    const session = await myAuthProvider.verify(event);
+    if (!session) return null;
+    return { email: session.email };
+  },
+  publicPaths: ["/api/webhooks"],
+});
+```
+
+## تطبيقات مساحة العمل العامة {#public-workspace-apps}
+
+تعتبر تطبيقات مساحة العمل داخلية بشكل افتراضي. للسماح للزائرين المجهولين بتحميل ملف عام
+الموقع مع الاحتفاظ بصفحات الإدارة خلف المصادقة، قم بإعلان الوصول إلى المسار
+`apps/<id>/package.json`:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin"]
+    }
+  }
+}
+```
+
+بالنسبة للشكل المعكوس، احتفظ بالجمهور الداخلي الافتراضي واعرضه فقط
+صفحات عامة محددة:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "publicPaths": ["/", "/share"]
+    }
+  }
+}
+```
+
+يستخدم `publicPaths` و`protectedPaths` مطابقة البادئات، لذا فإن `"/admin"` أيضًا
+يغطي `"/admin/users"`. تفتح هذه الإعدادات التنقل في الصفحة فقط. الإطار
+لا تزال المسارات (`/_agent-native/*`) ومسارات API المخصصة (`/api/*`) بحاجة إلى مصادقة
+ما لم يضيف التطبيق هذه البادئات بشكل صريح إلى
+`createAuthPlugin({ publicPaths: [...] })`.
+
+## الجلسة API {#session-api}
+
+كائن الجلسة الذي تم إرجاعه بواسطة `getSession(event)` له هذا الشكل:
+
+```ts
+interface AuthSession {
+  email: string; // User's email (primary identifier)
+  userId?: string; // Better Auth user ID
+  token?: string; // Session token
+  name?: string; // Display name from the auth provider, when available
+  image?: string; // Profile image from the auth provider, when available
+  orgId?: string; // Active organization ID
+  orgRole?: string; // Role in active org (owner/admin/member)
+}
+```
+
+على العميل، استخدم الخطاف `useSession()`:
+
+```ts
+import { useSession } from "@agent-native/core/client";
+
+function MyComponent() {
+  const { session, isLoading } = useSession();
+  if (isLoading) return <p>Loading...</p>;
+  if (!session) return <p>Not signed in</p>;
+  return <p>Hello, {session.email}</p>;
+}
+```
+
+## تسجيل الدخول باستخدام Return URL {#sign-in-return-url}
+
+النماذج التي تحتوي على **صفحات عامة** (مشاركة الروابط والتضمينات وصفحات التسويق) غالبًا ما تحتاج إلى CTA داخل الصفحة والذي يطلب من المشاهدين المجهولين تسجيل الدخول وإعادتهم إلى الصفحة التي كانوا فيها. يوفر إطار العمل نقطة دخول واحدة لهذا:
+
+```
+/_agent-native/sign-in?return=<same-origin-path>
+```
+
+عندما يصل عارض مجهول إلى URL، يتم عرض صفحة تسجيل الدخول الخاصة بإطار العمل. بعد تسجيل الدخول بنجاح (أي تدفق — الرمز المميز أو البريد الإلكتروني/كلمة المرور أو Google OAuth)، يتم تحويل العارض إلى `return`.
+
+تم التحقق من صحة المعلمة `return` باعتبارها **مسارًا من نفس الأصل**. مراجع مسار الشبكة (`//evil.com/...`)، وURLs المطلقة، ومخططات `data:` / `javascript:`، وأحرف التحكم المضمنة كلها تعود إلى `/`. تتم إعادة إنشاء المسار الذي تم التحقق من صحته من المحلل اللغوي URL، ولم يتم تكراره مرة أخرى من الإدخال.
+
+**من مكون React:**
+
+```tsx
+import { Button } from "@/components/ui/button";
+
+function SignInCta() {
+  const onClick = () => {
+    const ret = window.location.pathname + window.location.search;
+    window.location.href =
+      "/_agent-native/sign-in?return=" + encodeURIComponent(ret);
+  };
+  return <Button onClick={onClick}>Sign in</Button>;
+}
+```
+
+### المسارات الخاصة ذات الإشارات المرجعية
+
+عندما ينتقل مستخدم مجهول مباشرة إلى مسار خاص مثل `/dashboard`، فإن إطار العمل يخدم بالفعل صفحة تسجيل الدخول في URL - بعد تسجيل الدخول الناجح، تتم إعادة تحميل الصفحة ويصل المستخدم إلى `/dashboard`. لا حاجة إلى معالجة خاصة؛ يعمل هذا مع الرمز المميز والبريد الإلكتروني/كلمة المرور و**و**Google OAuth.
+
+### خلف الكواليس: Google OAuth
+
+يربط كلا التدفقين (نقطة الدخول `/_agent-native/sign-in` الصريحة وحالة المسار ذي الإشارة المرجعية) الإرجاع URL خلال حالة OAuth. الولاية موقعة بـ HMAC، لذا لا يمكن تزويرها أثناء النقل. في رد الاتصال، تتم إعادة التحقق من صحة الإرجاع URL باعتباره نفس الأصل قبل إعادة التوجيه - لذلك لا يزال من غير الممكن تحويل مفتاح التوقيع المسرب إلى أوراكل إعادة توجيه مفتوحة.
+
+إذا كان القالب الخاص بك يلتف حول `/_agent-native/google/auth-url` مباشرةً (على سبيل المثال، تقوم قوالب البريد والتقويم بذلك لتوسيع النطاقات)، فاقبل استعلام `?return=<path>` وأعد توجيهه عبر نموذج كائن الخيارات `encodeOAuthState`:
+
+```ts
+const returnUrl = getQuery(event).return;
+const state = encodeOAuthState({
+  redirectUri,
+  desktop,
+  returnUrl: typeof returnUrl === "string" ? returnUrl : undefined,
+});
+```
+
+يقوم مسار `/_agent-native/google/auth-url` الافتراضي بذلك تلقائيًا - ولا يتم التجاوز إلا إذا كان القالب الخاص بك يحتاج إلى معالجة OAuth مخصصة.
+
+## متغيرات البيئة {#environment-variables}
+
+| متغير                                   | الغرض                                                                                                                                                                    |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `BETTER_AUTH_SECRET`                    | مفتاح التوقيع لمصادقة أفضل (يتم إنشاؤه تلقائيًا إذا لم يتم تعيينه)                                                                                                       |
+| `AUTH_SKIP_EMAIL_VERIFICATION`          | قم بالتعيين على `1` في بيئات ضمان الجودة/المعاينة للسماح بمتابعة عمليات الاشتراك في البريد الإلكتروني/كلمة المرور دون التحقق؛ يتم تخطي التطوير/الاختبار المحلي افتراضيًا |
+| `AUTH_DISABLED`                         | اضبط على `true` أو `1` لتخطي تسجيل الدخول/الاشتراك؛ يتم تشغيل جميع الطلبات كمستخدم واحد مشترك (للتطوير/المعاينة المحلية فقط - وليس للإنتاج مع مستخدمين حقيقيين)          |
+| `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT` | اضبط على `1` لتعطيل تسجيل الدخول التلقائي للمضيف المحلي في قاعدة بيانات جديدة للمطورين                                                                                   |
+| `AUTH_MODE`                             | يحل `local` هوية CLI/الوكيل فقط (الذي يعمل عليه مستخدم التطوير `pnpm action`)؛ لا تقم أبدًا بتجاوز تسجيل الدخول إلى المتصفح                                              |
+| `COOKIE_DOMAIN`                         | الاشتراك في ملفات تعريف الارتباط للجلسة المشتركة عبر النطاقات الفرعية لقاعدة البيانات نفسها (راجع [Cookie Realms](#cookie-realms))                                       |
+| `AGENT_NATIVE_WORKSPACE`                | يتم تشغيل `1` في وضع مساحة العمل — نطاق جلسة مشتركة واحدة عبر تطبيقات مساحة العمل                                                                                        |
+| `AGENT_NATIVE_SHARE_COOKIE_DOMAIN`      | قم بالتعيين باستخدام `COOKIE_DOMAIN` لمشاركة قاعدة بيانات مصادقة واحدة عبر النطاقات الفرعية للطرف الأول                                                                  |
+| `OAUTH_STATE_SECRET`                    | مفتاح HMAC مخصص لمظاريف حالة OAuth (راجع [Security — OAuth State Signing](/docs/security#oauth-state))                                                                   |
+| `GOOGLE_SIGN_IN_CLIENT_ID`              | معرف عميل Google OAuth المفضل لتسجيل الدخول إلى التطبيق                                                                                                                  |
+| `GOOGLE_SIGN_IN_CLIENT_SECRET`          | سر Google OAuth المفضل منخفض النطاق لتسجيل الدخول إلى التطبيق                                                                                                            |
+| `GOOGLE_CLIENT_ID`                      | الإجراء الاحتياطي القديم لتسجيل الدخول إلى Google، ومعرف العميل OAuth للموفر لعمليات تكامل Google API                                                                    |
+| `GOOGLE_CLIENT_SECRET`                  | الإجراء الاحتياطي القديم لتسجيل الدخول إلى Google، وسر الموفر OAuth لعمليات تكامل Google API                                                                             |
+| `GITHUB_CLIENT_ID`                      | تمكين GitHub OAuth                                                                                                                                                       |
+| `GITHUB_CLIENT_SECRET`                  | GitHub OAuth سر                                                                                                                                                          |
+| `ACCESS_TOKEN`                          | الحامل الاحتياطي الثابت لعملاء MCP/connect؛ ليست مصادقة المتصفح                                                                                                          |
+| `ACCESS_TOKENS`                         | احتياطيات حامل ثابت مفصولة بفواصل لعملاء MCP/connect؛ ليست مصادقة المتصفح                                                                                                |
+| `A2A_SECRET`                            | السر المشترك للتحقق من هوية A2A عبر التطبيقات الموقعة بواسطة JWT، وتوقيع رمز الوصول MCP OAuth، عند وجوده،                                                                |

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

@@ -0,0 +1,268 @@
+---
+title: "الأتمتة"
+description: "عمليات التشغيل التلقائي المجدولة والمشغلة بالحدث مع ظروف اللغة الطبيعية"
+---
+
+# الأتمتة
+
+**الأتمتة** هي قاعدة: _عندما يحدث X، افعل Y_ — موصوفة باللغة الطبيعية. ينفذ الوكيل التعليمات، بحيث يكون للتشغيل الآلي حق الوصول إلى كل إجراء وأداة وخادم MCP الذي يمكن للوكيل استخدامه في الدردشة التفاعلية.
+
+توسّع عمليات التشغيل الآلي [recurring jobs](/docs/recurring-jobs) من خلال **مشغلات الأحداث** و**شروط اللغة الطبيعية** و**HTTP** الصادرة عبر أداة `web-request`. إنهم يستخدمون نفس تنسيق الملف `jobs/<name>.md` والتخزين وسير العمل "إنشاء ثلاث طرق" كمهام متكررة - راجع [Recurring Jobs](/docs/recurring-jobs#job-file) للتعرف على التنسيق المشترك. تغطي هذه الصفحة فقط ما هو جديد في عمليات التشغيل الآلي المستندة إلى الأحداث.
+
+```an-diagram title="When X happens, do Y" summary="An event fires on the bus, an optional natural-language condition gates it, and the agent runs the automation body with full tool access."
+{
+  "html": "<div class=\"auto-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Event</span><small class=\"diagram-muted\"><code>calendar.booking.created</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Condition</span><small class=\"diagram-muted\">Haiku checks: &ldquo;email ends with @builder.io&rdquo;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">Agent runs the body</span><small class=\"diagram-muted\">actions &middot; web-request &middot; MCP &middot; sub-agents</small></div></div>",
+  "css": ".auto-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.auto-flow .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px;min-width:180px}.auto-flow .diagram-arrow{font-size:22px}"
+}
+```
+
+## نوعان من المشغلات {#trigger-types}
+
+| اكتب       | يتم تشغيله عند                               | حقل المفتاح       |
+| ---------- | -------------------------------------------- | ----------------- |
+| `schedule` | يتطابق تعبير cron (مثل المهام المتكررة)      | `schedule` (كرون) |
+| `event`    | يتم إطلاق حدث مطابق في ناقل أحداث إطار العمل | `event` (الاسم)   |
+
+يمكن أن تتضمن مشغلات الأحداث `condition` — سلسلة باللغة الطبيعية يتم تقييمها بواسطة Haiku مقابل حمولة الحدث قبل الإرسال. إذا لم يتطابق الشرط، فسيتم تخطي التشغيل التلقائي بصمت.
+
+## إنشاء عمليات التشغيل الآلي {#creating}
+
+### من خلال سؤال الوكيل
+
+> "عندما يحجز شخص ما اجتماعًا باستخدام بريد إلكتروني @builder.io، أرسل لي رسالة على Slack."
+
+يكتشف الوكيل الأحداث المتاحة، ويؤكد الخطة، ويكتب لك الأتمتة.
+
+### من الإعدادات UI
+
+تظهر عمليات التشغيل التلقائي في لوحة الإعدادات. يمكن للمستخدمين عرضها وتمكينها/تعطيلها وحذفها هناك.
+
+المسار الثالث - كتابة ملف `jobs/<name>.md` يدويًا عبر `resourcePut` - يعمل تمامًا كما هو الحال مع [recurring jobs](/docs/recurring-jobs#creating). للحصول على أتمتة تعتمد على الحدث، يمكنك إضافة المادة الأمامية لمشغل الحدث أدناه إلى نفس الملف. تقوم المهمة التي يتم تشغيلها بواسطة حدث بتعيين `schedule: ""` وتوفر `triggerType: event` واسم `event` و`condition` اختياري:
+
+```an-annotated-code title="An event-triggered automation"
+{
+  "filename": "jobs/slack-on-builder-booking.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"\"\nenabled: true\ntriggerType: event\nevent: calendar.booking.created\ncondition: \"attendee email ends with @builder.io\"\nmode: agentic\ndomain: calendar\nrunAs: creator\n---\nSend a Slack message to #sales with the booking details.\nUse the web-request tool to POST to ${keys.SLACK_WEBHOOK}.",
+  "annotations": [
+    { "lines": "2", "label": "No cron", "note": "Event triggers set `schedule` to `\"\"` — the cron field stays empty." },
+    { "lines": "4-5", "label": "The trigger", "note": "`triggerType: event` plus the `event` name subscribes this automation to the bus." },
+    { "lines": "6", "label": "Gate", "note": "An optional natural-language `condition`, evaluated by Haiku against the payload before dispatch." },
+    { "lines": "12", "label": "Server-side secret", "note": "`${keys.SLACK_WEBHOOK}` is resolved server-side — the raw value never enters the agent's context." }
+  ]
+}
+```
+
+## الأتمتة الأمامية {#frontmatter}
+
+تشارك عمليات التشغيل الآلي كل حقل في [recurring-jobs frontmatter table](/docs/recurring-jobs#frontmatter). تتحكم هذه الحقول الإضافية في مشغلات الأحداث وشروطها ووضع التنفيذ:
+
+| الحقل         | اكتب                             | الافتراضي    | الوصف                                                                                                                                                               |
+| ------------- | -------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `triggerType` | `"schedule"` \| `"event"`        | `"schedule"` | كيفية تشغيل الأتمتة                                                                                                                                                 |
+| `event`       | سلسلة                            | _(اختياري)_  | اسم الحدث المطلوب الاشتراك فيه (مشغّلات الحدث فقط)                                                                                                                  |
+| `condition`   | سلسلة                            | _(اختياري)_  | تم تقييم حالة اللغة الطبيعية قبل الإرسال                                                                                                                            |
+| `mode`        | `"agentic"` \| `"deterministic"` | `"agentic"`  | حلقة الوكيل الكاملة. (`"deterministic"` محجوز ولكن لم يتم تنفيذه بعد — يتم تخطي عمليات الأتمتة التي تقوم بتعيينه. استخدم `"agentic"` لجميع عمليات الأتمتة الحالية.) |
+| `domain`      | سلسلة                            | _(اختياري)_  | علامة التجميع (البريد، التقويم، المقاطع، إلخ.)                                                                                                                      |
+
+بالنسبة لمشغل الحدث، `schedule` هو `""` (فارغ)؛ بالنسبة لمشغل الجدول الزمني فإنه يحمل تعبير cron. يكتب المرسل أيضًا نفس حقول `lastRun` / `lastStatus` / `lastError` المُدارة التي يكتبها المجدول، بالإضافة إلى حالة `"skipped"` عندما يتم تقييم الشرط إلى خطأ.
+
+## حافلة الأحداث {#event-bus}
+
+تقوم عمليات التكامل بتسجيل الأحداث في وقت تحميل الوحدة. تقوم الحافلة بالتحقق من صحة الحمولات مقابل تعريفات [Standard Schema](https://standardschema.dev) وإرسالها إلى المشتركين.
+
+### الأحداث المضمنة {#built-in-events}
+
+| الحدث                  | المصدر                                          |
+| ---------------------- | ----------------------------------------------- |
+| `test.event.fired`     | يدوي / إجراء `manage-automations`=اختبار الحريق |
+| `agent.turn.completed` | دردشة الوكيل                                    |
+| `calendar.*`           | تكامل التقويم                                   |
+| `clip.*`               | تكامل المقاطع                                   |
+| `mail.*`               | تكامل البريد                                    |
+
+اتصل بـ `manage-automations` مع `action=list-events` من الوكيل لرؤية جميع الأحداث المسجلة مع الأوصاف ومخططات الحمولة للقالب الحالي.
+
+### إصدار أحداث مخصصة {#emitting-events}
+
+قم بتسجيل نوع الحدث في مكون إضافي للخادم، ثم قم بإصداره من actions أو معالجات خطاف الويب:
+
+```ts
+import { registerEvent, emit } from "@agent-native/core/event-bus";
+import { z } from "zod";
+
+// Register the event type (once, at module load)
+registerEvent({
+  name: "order.completed",
+  description: "A customer completed an order",
+  payloadSchema: z.object({
+    orderId: z.string(),
+    customerEmail: z.string(),
+    total: z.number(),
+  }),
+  example: {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+});
+
+// Emit the event (from an action, webhook handler, etc.)
+emit(
+  "order.completed",
+  {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+  { owner: "steve@builder.io" },
+);
+```
+
+`owner` في نطاقات البيانات التعريفية المنبعثة التي تطلق عمليات التشغيل الآلي - يتم تقييم عمليات التشغيل الآلي المملوكة لنفس المستخدم (أو عمليات التشغيل الآلي المشتركة) فقط.
+
+## الشروط {#conditions}
+
+الشروط هي سلاسل باللغة الطبيعية يتم تقييمها بواسطة Claude Haiku مقابل حمولة الحدث. هذا تصنيف نعم/لا، وليس مهمة إنشاء.
+
+- **شرط فارغ أو مفقود** = غير مشروط (يتم تفعيله دائمًا).
+- يتم حفظ النتائج (SHA-256 للحالة + الحمولة) باستخدام ذاكرة تخزين مؤقت TTL مدتها 5 دقائق وذاكرة تخزين مؤقت LRU مكونة من 500 إدخال.
+- يتم اقتطاع الحمولة إلى 4000 حرف قبل إرسالها إلى Haiku.
+- في حالة فشل API، يتم تقييم الحالة إلى `false` (الافتراضي الآمن - يتم تخطي التنفيذ التلقائي).
+
+أمثلة على الشروط:
+
+- `"attendee email ends with @builder.io"`
+- `"the order total is greater than $100"`
+- `"the message contains the word 'urgent'"`
+
+## أداة طلب الويب {#web-request}
+
+تستخدم عمليات التشغيل الآلي أداة `web-request` لـ HTTP الصادرة. وهو يدعم العناصر النائبة `${keys.NAME}` في URL والرؤوس والنص:
+
+```
+POST to ${keys.SLACK_WEBHOOK}
+
+Headers: {"Authorization": "Bearer ${keys.API_TOKEN}"}
+
+Body: {"text": "New booking from ${attendeeEmail}"}
+```
+
+يتم حل العناصر النائبة **من جانب الخادم** بعد أن يرسل الوكيل استدعاء الأداة — لا تدخل القيمة السرية الأولية مطلقًا في سياق الوكيل.
+
+### المعلمات {#web-request-params}
+
+| المعلمة      | اكتب  | الافتراضي | الوصف                                             |
+| ------------ | ----- | --------- | ------------------------------------------------- |
+| `url`        | سلسلة | —         | URL كامل. قد يحتوي على مراجع `${keys.NAME}`.      |
+| `method`     | سلسلة | `GET`     | طريقة HTTP (GET، POST، PUT، PATCH، DELETE، HEAD). |
+| `headers`    | سلسلة | `{}`      | كائن JSON للرؤوس. قد يحتوي على `${keys.NAME}`.    |
+| `body`       | سلسلة | —         | نص الطلب. قد يحتوي على `${keys.NAME}`.            |
+| `timeout_ms` | الرقم | 15000     | المهلة بالمللي ثانية (30000 كحد أقصى).            |
+
+## المفاتيح {#keys}
+
+المفاتيح هي أسرار مخصصة تم إنشاؤها بواسطة المستخدمين أو الوكيل لاستخدام التشغيل الآلي (على سبيل المثال، `SLACK_WEBHOOK`، `HUBSPOT_API_KEY`). وهي تختلف عن الأسرار المسجلة (`registerRequiredSecret`) من حيث أنها لا تحتوي على بيانات وصفية محددة في القالب أو خطوة إعداد.
+
+- تم الإنشاء عبر الإعدادات UI أو `/_agent-native/secrets/adhoc` API.
+- يمكن أن يحتوي كل مفتاح على **قائمة مسموح بها URL** تقيد المصادر التي يمكن إرسال المفتاح إليها (المطابقة على مستوى الأصل).
+- لا يتم عرض القيمة الأولية مطلقًا للذكاء الاصطناعي - تظهر فقط العناصر النائبة `${keys.NAME}` في سياق الوكيل.
+- يرجع القرار من نطاق المستخدم إلى نطاق مساحة العمل، حتى يتمكن المستخدمون من تجاوز المفاتيح المشتركة.
+
+## أدوات الوكيل {#agent-tools}
+
+يتم الوصول إلى كافة عمليات التشغيل الآلي من خلال أداة `manage-automations` واحدة باستخدام معلمة `action`:
+
+| الإجراء       | الغرض                                                               |
+| ------------- | ------------------------------------------------------------------- |
+| `list-events` | اكتشف جميع الأحداث المسجلة مع الأوصاف ومخططات الحمولة               |
+| `list`        | سرد جميع عمليات الأتمتة ذات الحالة؛ التصفية حسب المجال أو التمكين   |
+| `define`      | إنشاء آلية جديدة (الاسم، نوع المشغل، الحدث، الحالة، النص)           |
+| `update`      | تحديث آلية موجودة (ممكّنة، الحالة، النص)                            |
+| `delete`      | حذف عملية تلقائية (يتم التأكيد دائمًا مع المستخدم أولاً)            |
+| `fire-test`   | قم بإصدار حدث `test.event.fired` للتحقق من صحة عمليات التشغيل الآلي |
+
+أداة إضافية: `web-request` — HTTP للخارج مع استبدال `${keys.NAME}`.
+
+## نقاط نهاية API {#api}
+
+| نقطة النهاية                           | الطريقة | الوصف                                              |
+| -------------------------------------- | ------- | -------------------------------------------------- |
+| `/_agent-native/automations`           | GET     | سرد جميع عمليات التشغيل التلقائي (التي تم تحليلها) |
+| `/_agent-native/automations/fire-test` | POST    | أصدر حدث `test.event.fired`                        |
+| `/_agent-native/secrets/adhoc`         | GET     | قائمة المفاتيح المخصصة (بدون قيم)                  |
+| `/_agent-native/secrets/adhoc`         | POST    | إنشاء أو تحديث مفتاح مخصص                          |
+| `/_agent-native/secrets/adhoc/:name`   | DELETE  | حذف مفتاح مخصص                                     |
+
+```an-api title="Fire a test event"
+{
+  "method": "POST",
+  "path": "/_agent-native/automations/fire-test",
+  "summary": "Emit a test.event.fired event to validate event-triggered automations",
+  "description": "Confirm an automation's wiring and condition without waiting for a real provider event. Equivalent to the `manage-automations` action `fire-test`.",
+  "responses": [
+    { "status": "200", "description": "Event emitted; matching automations are dispatched through the normal condition + ownership path." }
+  ]
+}
+```
+
+## كيف يعمل الإرسال {#dispatch}
+
+```an-diagram title="The dispatch path" summary="From a fired event to a completed agent run, gated by ownership scope and the natural-language condition."
+{
+  "html": "<div class=\"disp\"><div class=\"diagram-box accent\">event fired on the bus</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">match</span><small class=\"diagram-muted\">load enabled automations subscribed to this event name</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">scope</span><small class=\"diagram-muted\">keep only those owned by the event's owner (or shared)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">condition</span><small class=\"diagram-muted\">Haiku yes/no on the payload &mdash; false &rarr; <code>skipped</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">run</span><small class=\"diagram-muted\"><code>runAgentLoop</code> with body as prompt, payload as context, 5-min timeout</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code></small></div></div>",
+  "css": ".disp{display:flex;flex-direction:column;gap:6px;max-width:540px}.disp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.disp .diagram-box{align-self:flex-start}.disp .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+## مثال {#example}
+
+**المستخدم:** "عندما يقوم شخص ما بالحجز باستخدام بريد إلكتروني @builder.io، أرسل لي رسالة على Slack."
+
+**تدفق الوكيل:**
+
+1. استدعاء `manage-automations` باستخدام `action=list-events` — العثور على `calendar.booking.created`.
+2. تأكيد الخطة مع المستخدم.
+3. استدعاء `manage-automations` مع `action=define`:
+   - `name`: `slack-on-builder-booking`
+   - `trigger_type`: `event`
+   - `event`: `calendar.booking.created`
+   - `condition`: `attendee email ends with @builder.io`
+   - `mode`: `agentic`
+   - `domain`: `calendar`
+   - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`
+4. يتم حفظ التشغيل الآلي باسم `jobs/slack-on-builder-booking.md` ويبدأ الاستماع على الفور.
+
+## مزيد من الأمثلة {#more-examples}
+
+### الإخطار عبر الرد التلقائي على الويب عند التعليق على الخطة
+
+اسأل وكيل الخطة: _"عندما يضيف شخص ما تعليقًا بشريًا على الخطة، POST a
+إشعار بخطاف الويب الخاص بي."_
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is human or resolutionTarget is null"
+mode: agentic
+domain: plan
+enabled: true
+---
+
+POST to ${keys.NOTIFY_WEBHOOK} with a JSON body:
+{"title": "<plan title>", "excerpt": "<comment excerpt>", "author": "<author email or null>", "url": "<app base url + path>"}
+```
+
+قم بتعيين `NOTIFY_WEBHOOK` على أي نقطة نهاية HTTP — خطاف ويب وارد Slack، وهو خطاف عام
+خدمة إعلام، أو جهاز استقبال مخصص. تقوم أداة `web-request` بحل المشكلة
+`${keys.NOTIFY_WEBHOOK}` من جانب الخادم؛ لا يظهر URL الخام أبدًا في
+السياق. انظر [Visual Plans — Events and notifications](/docs/template-plan#events)
+للاطلاع على مرجع الحمولة النافعة `plan.commented` الكامل وجميع أحداث الخطة الأربعة.
+
+## ما هي الخطوة التالية
+
+- [**Recurring Jobs**](/docs/recurring-jobs) — تعيد عمليات التشغيل الآلي التي يتم تشغيلها بالجدول الزمني استخدام نفس المجدول
+- [**Actions**](/docs/actions) — يمكن للأتمتة استدعاء أي إجراء مسجل عبر حلقة الوكيل
+- [**Security**](/docs/security) — التحقق من صحة الإدخال والمعالجة السرية
+- [**Visual Plans — Events**](/docs/template-plan#events) — مرجع التخطيط للأحداث ووصفات التشغيل الآلي