@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ar-SA/creating-templates.md

@@ -0,0 +1,411 @@
+---
+title: "إنشاء النماذج"
+description: "كيفية إنشاء ونشر قوالب تطبيقات الوكيل الأصلية الخاصة بك."
+---
+
+# إنشاء النماذج
+
+النماذج عبارة عن تطبيقات متكاملة ومتشعبة للوكلاء الأصليين تعمل على حل سير العمل الحقيقي. تم إنشاء قوالب الطرف الأول بنفس سطح إطار العمل الذي تستخدمه: مسارات React لـ UI، وDrizzle SQL للبيانات، وactions للعمليات، وموارد مساحة العمل لسلوك الوكيل، ومزامنة الاستقصاء بحيث يظل الوكيل وUI متوازيين.
+
+نموذج جيد:
+
+- يعمل على حل سير عمل واحد من البداية إلى النهاية، باستخدام بيانات أولية مفيدة أو تدفق في حالة فارغة.
+- يخزن الحالة الدائمة في ملفات SQL، وليس ملفات JSON.
+- يحدد عمليات التطبيق على أنها `defineAction()` actions.
+- يكشف التنقل والاختيار من خلال حالة التطبيق.
+- يتم شحن `AGENTS.md` واضح بالإضافة إلى skills المركز لسير العمل غير الواضح.
+- تسجيل خطوات الإعداد لمقدمي الخدمة والأسرار المطلوبة.
+- يعمل كتطبيق مستقل وكجزء من مساحة عمل متعددة التطبيقات.
+
+## البدء من الدردشة {#start-from-chat}
+
+استخدم نموذج الدردشة عندما تريد تطبيقًا مبسطًا مع توصيلات إطار العمل الموجودة بالفعل:
+
+```bash
+npx @agent-native/core@latest create my-template --template chat --standalone
+```
+
+بالنسبة لمساحة عمل تحتوي على تطبيقات متعددة، قم بتشغيل المنتقي وقم بتضمين الدردشة مع أي قوالب مجال تريدها:
+
+```bash
+npx @agent-native/core@latest create my-platform
+```
+
+تمنحك الدردشة مصادقة وسلاسل محادثات متينة وموارد مدعومة بـ SQL وأدوات وحالة التطبيق وactions ومزامنة الاستقصاء. يمكنك إضافة نموذج المجال والمنتج UI.
+
+إذا لم تكن تنشئ قالب UI قابلاً لإعادة الاستخدام بعد، فاستخدم المنحدر بدون رأس في [Getting Started](/docs/getting-started#1-create-your-app): حدد إجراءً واحدًا، وقم بتشغيله باستخدام `pnpm agent`، وأضف UI لاحقًا عندما يحتاج سير العمل إلى سطح متين.
+
+## هيكل المشروع {#project-structure}
+
+يتبع كل قالب نفس التنسيق العام:
+
+```an-file-tree title="Template project layout"
+{
+  "title": "my-template/",
+  "entries": [
+    { "path": "app/", "note": "React frontend" },
+    { "path": "app/root.tsx", "note": "HTML shell and providers" },
+    { "path": "app/routes/", "note": "React Router file routes" },
+    { "path": "app/components/", "note": "Template UI" },
+    { "path": "app/hooks/", "note": "UI state and data hooks" },
+    { "path": "actions/", "note": "defineAction operations — the single source of truth" },
+    { "path": "server/db/schema.ts", "note": "Drizzle schema" },
+    { "path": "server/plugins/db.ts", "note": "additive migrations" },
+    { "path": "server/plugins/", "note": "startup integrations" },
+    { "path": "server/routes/api/", "note": "custom routes only when actions are not enough" },
+    { "path": "shared/types.ts", "note": "shared client/server types" },
+    { "path": ".agents/skills/", "note": "<skill>/SKILL.md — agent guidance for complex workflows" },
+    { "path": "AGENTS.md", "note": "template-specific agent instructions" },
+    { "path": "package.json" },
+    { "path": "react-router.config.ts" },
+    { "path": "vite.config.ts" }
+  ]
+}
+```
+
+لا تقم بإضافة دليل `data/` لحالة التطبيق. تنتمي بيانات التطبيق الدائمة إلى SQL، ويقرأها UI من خلال actions أو معالجات الخادم المكتوبة.
+
+تربط المناطق الأربع لكل قالب معًا من خلال سطح عمل مشترك واحد وقاعدة بيانات SQL واحدة - الوكيل وUI شريكان متساويان في نفس العمليات:
+
+```an-diagram title="How a template's four areas connect" summary="The UI and the agent both reach SQL through the same actions; application state and polling sync keep them aligned."
+{
+  "html": "<div class=\"diagram-tmpl\"><div class=\"diagram-col\"><div class=\"diagram-node\">React UI<br><small class=\"diagram-muted\">app/routes · components</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">AGENTS.md · skills</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\">defineAction()</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL via Drizzle<br><small class=\"diagram-muted\">additive schema</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">Polling sync</div></div>",
+  "css": ".diagram-tmpl{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-tmpl .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-tmpl .diagram-arrow{font-size:22px;line-height:1}.diagram-tmpl .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## بيانات النموذج في SQL {#data-models}
+
+حدد جداول المجال باستخدام إطار العمل المساعد Drizzle بحيث تظل المخططات قابلة للنقل عبر SQLite، وPostgres، وD1، وTurso، وSupabase، وNeon، والواجهات الخلفية المدعومة الأخرى:
+
+```ts
+// server/db/schema.ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  status: text("status", {
+    enum: ["draft", "active", "archived"],
+  })
+    .notNull()
+    .default("draft"),
+  sortOrder: integer("sort_order").notNull().default(0),
+  ...ownableColumns(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export const projectShares = createSharesTable("project_shares");
+```
+
+يجب أن تكون تغييرات المخطط إضافية. إضافة الجداول والأعمدة من خلال `runMigrations()` في `server/plugins/db.ts`؛ لا تستخدم مطلقًا SQL أو `drizzle-kit push` أو إعادة تسمية الجداول أو إسقاط الأعمدة.
+
+لقراءة التطبيق وكتابته، استخدم منشئ الاستعلامات والمشغلات المحمولة Drizzle من `drizzle-orm`. لا تكتب رمز المنتج باستخدام SQL الخام عندما يتمكن Drizzle من التعبير عن الاستعلام، ولا تستورد من `drizzle-orm/sqlite-core` أو `drizzle-orm/pg-core` في القوالب.
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'draft',
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      visibility TEXT NOT NULL DEFAULT 'private',
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+استخدم مستندات [Database](/docs/database) و[Security](/docs/security) قبل إضافة المخططات التي تحتوي على بيانات المستخدم أو بيانات المؤسسة.
+
+## حدد العمليات كـ Actions {#actions}
+
+Actions هي المصدر الوحيد لحقيقة سلوك التطبيق. يستدعيها الوكيل كأدوات، وتستدعيها الواجهة الأمامية من خلال الخطافات، ويمكن للتطبيقات الأخرى الوصول إليها من خلال MCP/A2A.
+
+```an-annotated-code title="actions/create-project.ts"
+{
+  "filename": "actions/create-project.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { getDb } from \"../server/db/index.js\";\nimport { nanoid } from \"nanoid\";\nimport { z } from \"zod\";\nimport * as schema from \"../server/db/schema\";\n\nexport default defineAction({\n  description: \"Create a project.\",\n  schema: z.object({\n    title: z.string().min(1).describe(\"Project title\"),\n  }),\n  run: async ({ title }, ctx) => {\n    const db = getDb();\n    const id = nanoid();\n    await db.insert(schema.projects).values({\n      id,\n      title,\n      ownerEmail: ctx.userEmail,\n      orgId: ctx.orgId,\n    });\n    return { id, title };\n  },\n});",
+  "annotations": [
+    { "lines": "2", "note": "`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`." },
+    { "lines": "8", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this action as a tool." },
+    { "lines": "9-11", "label": "عقد typed", "note": "One zod `schema` validates input from the agent, the UI, HTTP, MCP, and A2A." },
+    { "lines": "18-19", "label": "Scoped write", "note": "Stamp `ownerEmail` / `orgId` from `ctx` so the row is correctly scoped for sharing and access checks." }
+  ]
+}
+```
+
+استخدم `http: { method: "GET" }` أو `readOnly: true` لـ actions للقراءة فقط. استخدم `parallelSafe: true` فقط لتحويل actions الآمن للتشغيل بشكل متزامن مع استدعاءات أداة التشغيل نفسها. استخدم `toolCallable: false` لنطاق الانفجار العالي actions الذي لا ينبغي تشغيله من أدوات وضع الحماية.
+
+## قم ببناء UI {#ui}
+
+توجد المسارات في `app/routes/` وتستخدم توجيه الملفات React Router v7. الاستعلام عن البيانات من خلال معالجات actions أو API، وجعل الطفرات متفائلة بشكل افتراضي.
+
+```tsx
+import { useActionMutation, useActionQuery } from "@agent-native/core/client";
+
+export default function ProjectsPage() {
+  const { data: projects = [] } = useActionQuery("list-projects", {});
+  const create = useActionMutation("create-project");
+
+  return (
+    <button onClick={() => create.mutate({ title: "Launch plan" })}>
+      New project ({projects.length})
+    </button>
+  );
+}
+```
+
+قم بتوصيل المزامنة المباشرة مرة واحدة بالقرب من غلاف التطبيق حتى يتم تحديث ذاكرة التخزين المؤقت للاستعلام React عندما يقوم الوكيل أو علامة تبويب أخرى أو إجراء بتغيير البيانات:
+
+```tsx
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+export function AppSync() {
+  const queryClient = useQueryClient();
+  useDbSync({ queryClient });
+  return null;
+}
+```
+
+**الوعد الأصلي للوكيل: تظهر كتابات الوكيل في UI بدون تحديث يدوي. ** `useActionQuery` هو المسار السهل - يتم إعادة جلب كل خطاف عندما يصدر إجراء متحور `source: "action"`. إذا وصلت إلى `useQuery` الأولي باستخدام مفتاح مخصص (على سبيل المثال، مساعد عميل منخفض المستوى يقرأ حالة التكامل)، فقم بطي العداد لكل مصدر في queryKey للتحديثات المستهدفة:
+
+```tsx
+import { useChangeVersions } from "@agent-native/core/client";
+
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({
+  queryKey: ["dashboard", id, v],
+  queryFn: () => fetchDashboard(id),
+  placeholderData: (prev) => prev, // no flicker on refetch
+});
+```
+
+المصادر الشائعة: `"action"` (كل إجراء وكيل ناجح - الإجراء الاحتياطي الموثوق به)، `"app-state"`، `"settings"`، بالإضافة إلى أي مصدر موارد مخصص يصدره متجرك عبر `recordChange`. شاهد مهارة `real-time-sync` للتعرف على النمط الكامل.
+
+## أضف حالة التطبيق {#application-state}
+
+حالة التطبيق هي الطريقة التي يعرف بها الوكيل ما يراه المستخدم. على الأقل أضف:
+
+- خطاف UI يكتب حالة `navigation` الدلالية عند تغيير المسارات أو السجلات المحددة أو علامات التبويب النشطة أو تحديدات المحرر.
+- إجراء `view-screen` يقرأ تلك الحالة ويعيد لقطة الشاشة الحالية.
+- إجراء `navigate` يكتب أمر `navigate` لمرة واحدة ليستهلكه UI.
+
+استخدم `useAgentRouteState` للربط UI حتى تظل عمليات الكتابة في حالة التطبيق، وقراءة الأوامر على مستوى علامة التبويب، والحذف بعد القراءة، وحماية الأوامر المكررة متسقة:
+
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      selectedId: searchParams.get("id"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+    navigateOptions: { replace: true, flushSync: true },
+  });
+}
+```
+
+احتفظ بعوامل التصفية القابلة للمشاركة في معلمات استعلام URL. يعرضها إطار العمل للوكيل باسم `<current-url>` ويمكن للوكيل المدمج تغييرها باستخدام `set-search-params`؛ يجب أن يحمل `navigation` المعرفات الدلالية والأسماء المستعارة، وليس نسخة ثانية من سلسلة الاستعلام الكاملة.
+
+للتنقل في التطبيق، فضل أمر `navigate` الذي يتضمن نفس المصدر
+`path` عندما يكون URL معروفًا. ولا تكتب أيضًا `__set_url__` لنفس الحركة؛
+هذا المفتاح محجوز لأدوات إطار العمل URL وتغييرات مرشح URL فقط.
+
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the UI.",
+  schema: z.object({
+    view: z.enum(["home", "project"]),
+    projectId: z.string().optional(),
+    path: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
+```
+
+راجع [Context Awareness](/docs/context-awareness) للتعرف على النمط الكامل.
+
+## استخدم مسارات API باعتدال {#api-routes}
+
+يُفضل actions لعمليات التطبيق. قم بإنشاء مسارات Nitro مخصصة فقط للأسطح التي لا يمكن أن تكون actions نظيفة:
+
+- تحميل ملف أو تدفق ثنائي.
+- الصفحات العامة المجهولة وwebhooks.
+- استدعاءات OAuth ومعالجات البروتوكول الخاصة بالموفر.
+- المحتوى العام الذي يعرضه الخادم.
+
+يجب على المسارات المخصصة التي تلامس البيانات القابلة للملكية استدعاء `getSession(event)` والتفاف عمل قاعدة البيانات في `runWithRequestContext({ userEmail, orgId }, fn)` قبل استخدام مساعدي الوصول.
+
+## اكتب تعليمات الوكيل {#write-agents-md}
+
+`AGENTS.md` هي خريطة الوكيل لتطبيقك - ملف صغير قابل للتصفح مع
+سطر الغرض، والقواعد الأساسية، ومفاتيح حالة التطبيق، وجدول الإجراءات، وskills
+الفهرس:
+
+```markdown
+# My Template
+
+One workspace for projects, tasks, and notes.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes; schema is additive.
+- Use `view-screen` before acting on "this project" if the screen is unclear.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                  |
+| ---------------- | ------------------------ |
+| `list-projects`  | List accessible projects |
+| `create-project` | Create a project         |
+```
+
+قم بتحديث `AGENTS.md` كلما أضفت إجراءً جديدًا أو مسارًا أو مفتاح حالة أو متكررًا
+سير العمل. [Writing Agent Instructions](/docs/writing-agent-instructions) هو
+الدليل الكامل — كيفية إبقاء `AGENTS.md` قابلاً للتصفح، وما ينتمي إلى كل من العناصر الأربعة
+أسطح الإرشادات وكيفية صياغة المهارات وأوصاف الأدوات حتى يكون الوكيل
+يقوم بتشغيلها بشكل موثوق.
+
+## أضف Skills {#skills}
+
+استخدم skills للأنماط التفصيلية التي من شأنها تضخم `AGENTS.md`: API الخاصة بالموفر، أو تنسيقات الاستيراد/التصدير، أو تدفقات التحرير المعقدة، أو مصطلحات المجال.
+
+```markdown
+---
+name: project-imports
+description: How to import projects from the legacy CSV export.
+---
+
+# Project Imports
+
+Use this skill when the user uploads a legacy project CSV.
+
+## Rules
+
+- Validate required columns before creating rows.
+- Use `create-project` for each project so ownership and sync are correct.
+- Save rejected rows as a note attached to the import summary.
+```
+
+قم بتخزين القالب skills في `.agents/skills/<name>/SKILL.md`. إذا كان من المفترض أن يتمكن المستخدمون من تعديل الإرشادات في وقت التشغيل، فاعرضها من خلال موارد مساحة العمل أيضًا.
+
+## تسجيل خطوات الإعداد {#onboarding}
+
+إذا كان القالب يحتاج إلى مفتاح API أو اتصال OAuth أو حساب الموفر، فقم بتسجيل خطوة الإعداد بدلاً من دفن المتطلبات في README.
+
+```ts
+// server/plugins/onboarding.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+export default defineNitroPlugin(() => {
+  registerOnboardingStep({
+    id: "github",
+    title: "Connect GitHub",
+    description: "Needed to import repositories and pull requests.",
+    order: 100,
+    methods: [
+      {
+        id: "token",
+        kind: "form",
+        primary: true,
+        label: "Save token",
+        payload: {
+          fields: [
+            { key: "GITHUB_TOKEN", label: "GitHub token", secret: true },
+          ],
+        },
+      },
+    ],
+    isComplete: () => !!process.env.GITHUB_TOKEN,
+  });
+});
+```
+
+راجع [Onboarding & API Keys](/docs/onboarding).
+
+## اجعلها جاهزة للاستخدام في مساحة العمل {#workspace-ready}
+
+يجب أن تتلاءم القوالب بشكل طبيعي مع [Multi-App Workspaces](/docs/multi-app-workspace)، ويتم تنسيقها عادةً بواسطة [Dispatch](/docs/dispatch).
+
+قائمة التحقق:
+
+- قم بتثبيت A2A من خلال البرنامج الإضافي للدردشة مع وكيل إطار العمل أو `mountA2A()` حتى تتمكن التطبيقات الشقيقة من الاتصال بوكيلك.
+- احتفظ بأوصاف بطاقة الوكيل محددة بدرجة كافية حتى تتمكن Dispatch من توجيه العمل بدقة.
+- قم بتسجيل الأسرار/الإعداد المطلوبة حتى يظهر الإعداد في الشريط الجانبي ويمكن لـ Dispatch إدارة بيانات الاعتماد المشتركة.
+- احتفظ بالتعليمات الشاملة في مساحة العمل `AGENTS.md` أو موارد مساحة العمل، ولا يتم نسخها في كل تطبيق.
+- استخدم مساعدي المشاركة/الوصول لجميع الموارد القابلة للملكية حتى تظل مساحات العمل على مستوى المؤسسة معزولة.
+
+## نشر نموذج {#publishing}
+
+قبل المشاركة:
+
+1. قم بتشغيل `pnpm install` و`pnpm typecheck` واختبارات القالب.
+2. تحقق من أنه يعمل مع عدم تكوين مفاتيح الموفر الاختيارية.
+3. تحقق من المصادقة والمشاركة وعزل البيانات الخاصة بمستخدمين.
+4. يتطلب المستند env vars وخطوات الإعداد.
+5. قم بتضمين أمثلة أو صفوف أولية من خلال عمليات الترحيل الإضافية، وليس ملفات بيانات وقت التشغيل المتعقبة.
+
+يمكن إنشاء قوالب المجتمع من مستودع GitHub:
+
+```bash
+npx @agent-native/core@latest create my-app --template github:user/repo
+```
+
+## المساهمة في إطار العمل monorepo {#contributing}
+
+### اختبر تغييرات إطار العمل غير المنشورة {#test-unpublished-framework-changes}
+
+عندما تعمل داخل إطار عمل monorepo وتحتاج إلى إنشاء
+مساحة العمل لاستخدام تغييرات الحزمة أو القالب غير المنشورة، قم بتشغيل الإنشاء باستخدام
+علامة الحزمة المحلية:
+
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
+```
+
+تربط مساحة العمل التي تم إنشاؤها `@agent-native/core` المحلي و
+حزم `@agent-native/dispatch`، لذلك تتغير إلى Core APIs، ومساحة عمل Dispatch
+يمكن اختبار السلوك أو قوالب الطرف الأول قبل النشر. الحزمة
+تنشئ البرامج النصية `prepack` `dist` قبل الارتباط، مما يحافظ على ما تم إنشاؤه
+تشير مساحة العمل إلى مخرجات البناء الحالية.

package/corpus/core/docs/content/locales/ar-SA/cross-app-sso.md

@@ -0,0 +1,185 @@
+---
+title: "التطبيقات المشتركة SSO"
+description: "قم بتسجيل الدخول مرة واحدة عبر كل تطبيق مستضاف للوكيل الأصلي عبر اتحاد الهوية مع Dispatch باعتباره مرجع الهوية - الاشتراك لكل تطبيق، ويمكن عكسه باستخدام env var واحد."
+---
+
+# التطبيقات المشتركة SSO
+
+يُدير كل تطبيق مستضاف في `*.agent-native.com` عملية النشر الخاصة به من خلال **متجر المستخدم المنفصل الخاص به**. لا يشارك `mail.agent-native.com` و`calendar.agent-native.com` قاعدة بيانات أو جدول جلسة أو مجال ملف تعريف الارتباط. لذلك، لا يمكن أن يكون "تسجيل الدخول مرة واحدة، واستخدام كل تطبيق" ملف تعريف ارتباط مشترك - يجب أن يكون **اتحاد الهوية**، حيث يعمل [Dispatch](/docs/dispatch) كمرجع هوية لمساحة العمل.
+
+هذا هو نفس مبدأ الثقة الأساسي [A2A](/docs/a2a-protocol) و[External Agents](/docs/external-agents) الذي يستخدمه بالفعل - `A2A_SECRET` الموقع JWT والذي تم التحقق منه عند حد الطلب - والذي يتم تطبيقه على مسار تسجيل الدخول البشري بدلاً من مكالمات وكيل إلى وكيل.
+
+> **النشر الموحد مقابل النشر لكل مجال.** إذا كنت تستضيف جميع التطبيقات في مصدر واحد (`your-agents.com/mail`، `your-agents.com/calendar`)، فستحصل بالفعل على تسجيل دخول مشترك عبر مجال ملف تعريف ارتباط واحد - لا حاجة إلى اتحاد. يعد Cross-App SSO ضروريًا فقط عند تشغيل التطبيقات على مجالات منفصلة. انظر [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+
+## ماذا ولماذا {#what-why}
+
+تعني مخازن المستخدم لكل تطبيق أنه لا يوجد مكان واحد يمكن أن يعيش فيه ملف تعريف ارتباط المتصفح ويثق به كل تطبيق. بدلاً من ذلك، يقوم نموذج الاتحاد بتسمية تطبيق واحد — **Dispatch** — باعتباره سلطة الهوية. يمكن لأي تطبيق آخر تفويض "من هو هذا الشخص؟" إلى Dispatch، احصل على تأكيد موقع قصير الأمد من البريد الإلكتروني الذي تم التحقق منه للمستخدم، ثم **اربطه بحسابه المحلي عبر البريد الإلكتروني**.
+
+قاعدة الربط ضيقة وإضافية عن عمد:
+
+- **مستخدم البريد الإلكتروني الحالي نفسه → مرتبط.** تتم مطابقة الحساب المحلي بالبريد الإلكتروني الذي تم التحقق منه وإعادة استخدامه كما هو. لا **يتم تعديله أو إعادة تسميته أو حذفه مطلقًا** — طبقة الاتحاد تقرأه فقط وتعقد جلسة له.
+- **بريد إلكتروني جديد → تم إنشاؤه.** يتم إنشاء حساب محلي جديد لهذا البريد الإلكتروني الذي تم التحقق منه، ثم يتم إنشاء جلسة محلية عادية.
+
+يؤدي هذا إلى جعل عملية الطرح آمنة على الرغم من تسجيل خروج الأشخاص. **من المتوقع تسجيل الخروج.** عندما يقوم أحد التطبيقات بتشغيل هذا، تنتهي الجلسات الحالية ويعيد المستخدمون المصادقة من خلال Dispatch. لكنهم دائمًا ما يقومون بتسجيل الدخول مرة أخرى إلى **نفس الحساب المطابق للبريد الإلكتروني، مع الحفاظ على جميع بياناتهم سليمة**، لأن صفوف الهوية لا تتم إضافتها إلا إلى\_ — ولا يتم تدميرها أو إعادة تسميتها أو إعادة تعيينها مطلقًا.
+
+## كيفية العمل {#how-it-works}
+
+يعد التدفق بمثابة تفويض قياسي ← رمز مميز موقّع ← إعادة توجيه رد الاتصال، حيث يكون البريد الإلكتروني هو الشيء الوحيد الذي يتجاوز حدود الثقة.
+
+```an-diagram title="Identity federation flow" summary="Dispatch authenticates the human and returns a short-lived signed assertion of one thing — the verified email. The app links by email and mints its own local session."
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>Client app</strong><small class=\"diagram-muted\">own user store</small></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill\">authorize</span></div><div class=\"diagram-card\" data-rough><strong>Dispatch</strong><small class=\"diagram-muted\">identity authority</small><span class=\"diagram-pill accent\">authenticates human</span></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill accent\">302 + signed JWT</span></div><div class=\"diagram-card\" data-rough><strong>App callback</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">JIT-link by email</span><span class=\"diagram-pill ok\">mint local session</span></div></div>",
+  "css": ".diagram-sso{display:flex;align-items:stretch;gap:12px;flex-wrap:wrap}.diagram-sso .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px}.diagram-sso .diagram-step{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px}.diagram-sso .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+1. **التطبيق → إرسال (تفويض).** يرسل التطبيق المستخدم إلى سلطة الهوية:
+
+   ```
+   GET https://dispatch.agent-native.com/_agent-native/identity/authorize
+       ?app=<requesting-app>
+       &redirect_uri=<app-callback-url>
+       &state=<csrf-state>
+   ```
+
+   ```an-api title="الهوية تأذن بنقطة النهاية"
+   {
+     "method": "GET"،
+     "المسار": "/_agent-native/identity/authorize"،
+     "summary": "تقوم شركة Dispatch (سلطة الهوية) بالمصادقة على المستخدم وإعادة التوجيه مرة أخرى باستخدام رمز هوية موقّع"،
+     "auth": "جلسة الإرسال (تسجيل الدخول التفاعلي إذا لم يكن هناك)"،
+     "المعلمات": [
+       { "name": "app"، "in": "query"، "type": "string"، "required": true، "description": "معرف التطبيق الطالب." },
+       { "name": "redirect_uri"، "in": "query"، "type": "string"، "required": true، "description": "رد اتصال التطبيق URL. تم التحقق من صحته مقابل قائمة مسموح بها صارمة (`*.agent-native.com` أو مضيف محلي بشكل افتراضي)." },
+       { "name": "state"، "in": "query"، "type": "string"، "required": true، "description": "تكررت حالة CSRF مرة أخرى عند إعادة التوجيه."
+     ],
+     "الردود": [
+       { "status": "302"، "description": "يُعيد التوجيه إلى `redirect_uri` حاملاً هوية `A2A_SECRET` قصيرة العمر JWT (`scope: \"identity\"`، `exp` ≥ دقيقتين) بالإضافة إلى `state` الأصلية." },
+       { "status": "400"، "description": "فشل التحقق من القائمة المسموح بها `redirect_uri` (أصل مشترك، `//host` مرتبط بالمخطط، أو لاحقة غير مدرجة)."
+     ]
+   }
+   ```
+
+2. **يقوم Dispatch بالمصادقة على الإنسان.** إذا كان المستخدم لديه بالفعل جلسة Dispatch، فهذا أمر شفاف. إذا لم يكن الأمر كذلك، تعرض Dispatch معلومات تسجيل الدخول العادية الخاصة بها (البريد الإلكتروني/كلمة المرور، Google، وما إلى ذلك - راجع [Authentication](/docs/authentication)). Dispatch هو مجرد تطبيق عادي للوكيل الأصلي هنا؛ لا يقوم بتشغيل وضع مصادقة خاص.
+
+3. **Dispatch → التطبيق (رمز الهوية المميز).** تتحقق Dispatch من صحة `redirect_uri` مقابل القائمة المسموح بها الصارمة وتعيد التوجيه 302 مرة أخرى إلى `redirect_uri` للتطبيق الذي يحمل هوية موقعة **`A2A_SECRET` JWT ** قصيرة العمر \*\*. تكون مطالبات الرمز المميز في حدها الأدنى عمدًا:
+
+   | مطالبة       | المعنى                                                                           |
+   | ------------ | -------------------------------------------------------------------------------- |
+   | `sub`        | معرف مستخدم ثابت في سلطة الهوية                                                  |
+   | `email`      | البريد الإلكتروني **الذي تم التحقق منه** الخاص بالمستخدم — مفتاح الانضمام الوحيد |
+   | `name`       | الاسم المعروض (غير موثوق، لـ UI فقط)                                             |
+   | `org_domain` | مجال مساحة العمل/المؤسسة، عند وجوده                                              |
+   | `scope`      | `"identity"` دائمًا — يسمح هذا الرمز المميز بتسجيل الدخول فقط                    |
+   | `exp`        | **≥ دقيقتين** من الإصدار                                                         |
+
+4. **يتحقق التطبيق من روابط JIT عبر البريد الإلكتروني.** يتحقق التطبيق من توقيع الرمز المميز باستخدام `A2A_SECRET` الخاص به، ويتحقق من `scope: "identity"` و`exp`، ثم ينفذ **الربط في الوقت المناسب تمامًا عن طريق البريد الإلكتروني الذي تم التحقق منه**:
+   - في حالة وجود مستخدم محلي لديه هذا البريد الإلكتروني → أعد استخدامه دون تغيير.
+   - إذا لم يكن الأمر كذلك، قم بإنشاء مستخدم محلي لهذا البريد الإلكتروني.
+
+5. **ينشئ التطبيق جلسة محلية عادية.** من هنا فصاعدًا، يكون لدى المستخدم جلسة محلية عادية في المتجر الخاص بهذا التطبيق - كل فحص وصول موجود، ونطاق المؤسسة، وحارس الإجراءات يعمل تمامًا كما كان من قبل. الاتحاد حدث فقط عند الباب الأمامي.
+
+### الاشتراك {#opt-in}
+
+يشارك التطبيق **فقط** عندما يتم تعيين متغير البيئة هذا عند نشره:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+- **Set** → يعرض التطبيق خيار **"تسجيل الدخول باستخدام Agent-Native"** الذي يقوم بتشغيل التدفق أعلاه. ولا يزال تسجيل الدخول المحلي المباشر (البريد الإلكتروني/كلمة المرور، Google) يعمل بجانبه.
+- **إلغاء الضبط (افتراضي)** → **عدم تغيير السلوك.** يقوم التطبيق بالمصادقة تمامًا كما كان يفعل من قبل؛ مسار رمز الاتحاد خامل. لا يوجد أي تغيير في المخطط ولا يوجد أي شيء لترحيله، لذا فإن تشغيل المتغير أو إيقافه يمكن عكسه بالكامل في أي وقت.
+
+## الأمان {#security}
+
+يعتمد النموذج بأكمله على بعض الضمانات الصغيرة المتعمدة:
+
+- **رمز مميز موقّع قصير الأمد.** تأكيد الهوية هو `A2A_SECRET` موقع JWT مع انتهاء صلاحية ** 2 دقيقة ** و`scope: "identity"`. فهو يسمح بتسجيل دخول واحد ولا يمكن إعادة تشغيله لفترة طويلة أو إعادة استخدامه للوصول إلى API/A2A.
+- **القائمة المسموح بها لـ `redirect_uri` الصارمة.** يقوم Dispatch فقط بإعادة التوجيه إلى `*.agent-native.com` أو المضيف المحلي بشكل افتراضي. يتم رفض أهداف إعادة التوجيه التعسفية والنسبية للمخطط (`//host`) وعبر الأصل، لذلك لا يمكن تحويل السلطة إلى أوراكل لإعادة التوجيه المفتوح أو استخراج الرمز المميز.
+- **انضمام البريد الإلكتروني فقط من رمز مميز تم التحقق منه.** الشيء _الوحيد_ الذي يتجاوز حدود الثقة هو البريد الإلكتروني الذي تم التحقق منه في رمز مميز موقّع. لا يقبل التطبيق معرف المستخدم أو الدور أو عضوية المؤسسة أو أي حالة مميزة من السلك - فهو يستمد كل شيء محليًا من الحساب المطابق.
+- **كتابة الهوية الإضافية فقط.** يؤدي الارتباط إما إلى إعادة استخدام حساب بريد إلكتروني موجود دون تغيير أو إدراج حساب جديد. لا يحدث أي تحديث أو إعادة تسمية أو إعادة تعيين أو حذف لصفوف الهوية على هذا المسار على الإطلاق.
+- **إيقاف التشغيل بشكل افتراضي.** مع إلغاء تعيين `AGENT_NATIVE_IDENTITY_HUB_URL`، تصبح الميزة بأكملها خاملة.
+
+```an-callout
+{
+  "tone": "success",
+  "body": "**Safe to enable, safe to revert.** Identity writes are **additive only** — an existing same-email account is reused untouched, and a new email just inserts a fresh row. There is no schema change and nothing to migrate, so flipping `AGENT_NATIVE_IDENTITY_HUB_URL` on or off is fully reversible at any time, per app."
+}
+```
+
+الرابط في الوقت المناسب هو قرار واحد مُعتمد بالكامل على البريد الإلكتروني الذي تم التحقق منه:
+
+```an-diagram title="JIT-link decision" summary="Linking is keyed on the verified email and is additive only — existing accounts are reused unchanged, new emails create a fresh local user."
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>Verified email<br><small class=\"diagram-muted\">from signed identity JWT</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-branch\"><div class=\"diagram-box\" data-rough>Local user exists?<span class=\"diagram-pill ok\">yes &rarr; reuse unchanged</span><span class=\"diagram-pill accent\">no &rarr; create local user</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Mint normal local session</div></div></div>",
+  "css": ".diagram-jit{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-node{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-jit .diagram-branch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-box{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-jit .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## الاستضافة الذاتية {#self-hosting}
+
+يمكن أن يكون أي نشر لـ Dispatch بمثابة مركز الهوية - فأنت لست مقيدًا بـ `dispatch.agent-native.com`. قم بتعيين `AGENT_NATIVE_IDENTITY_HUB_URL` على كل تطبيق عميل للإشارة إلى مثيل Dispatch الخاص بك:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**إعادة توجيه القائمة المسموح بها.** يقوم المحور (Dispatch) بالتحقق من صحة `redirect_uri` على نقطة نهاية التفويض قبل إصدار رمز مميز. تم تكوين القائمة المسموح بها في `templates/dispatch/server/lib/identity-sso.ts`:
+
+- **الافتراضي:** `*.agent-native.com` والمضيف المحلي فقط (ثابت `DEFAULT_ALLOWED_HOST_SUFFIXES`).
+- **توسيعها:** قم بتعيين متغير البيئة `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` على نشر Dispatch بقائمة مفصولة بفواصل من لواحق المضيف الإضافية:
+
+  ```باش
+  # السماح بالنطاقات الفرعية yourcompany.com بالإضافة إلى النطاقات الافتراضية
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".yourcompany.com,.staging.yourcompany.com"
+  ```
+
+  تتم تسوية كل إدخال إلى لاحقة مسبوقة بنقطة (`.yourcompany.com`)، لذا فإن التحقق من اللاحقة كافٍ والأقل عرضة للتلاعب — لا توجد قائمة لكل تطبيق للحفاظ على المزامنة. يتم تصفية الإدخالات التي قد تطابق كل شيء (فارغة أو `.` فقط).
+
+- **المضيف المحلي** مسموح به دائمًا للتطوير المحلي للتطبيقات من جانب العميل بغض النظر عن `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`.
+
+بدون `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`، يمكن لـ Dispatch المستضاف ذاتيًا فقط إصدار الرموز المميزة للتطبيقات الموجودة على `*.agent-native.com`. قم بتعيين env var في نشر Dispatch لإلغاء تأمين النطاقات الأخرى.
+
+## دليل تشغيل Canary {#canary-rollout}
+
+التحويل والتراجع هما **متغير بيئة واحد لكل عملية نشر للتطبيق**. اطرح تطبيقًا واحدًا في كل مرة، ثم تحقق منه، ثم قم بالتوسيع. لا تقم بتعيين المتغير على كل تطبيق مرة واحدة.
+
+**1. انشر الكود — لا يوجد تغيير في السلوك.**
+قم بشحن الإصدار إلى كل تطبيق باستخدام `AGENT_NATIVE_IDENTITY_HUB_URL` **غير محدد في كل مكان**. تأكد من أن عمليات تسجيل الدخول العادية لا تزال تعمل على بعض التطبيقات.
+
+**2. تمكين الكناري على تطبيق ONE في المرة الواحدة.**
+تعيين على عملية نشر واحدة فقط:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+اترك بيئة كل التطبيقات الأخرى بدون تعيين. أعد النشر/أعد التشغيل حتى يلتقط المتغير.
+
+**3. التحقق من الكناري (قائمة المراجعة).**
+
+- سجل **الخروج** من التطبيق.
+- تظهر شاشة تسجيل الدخول الآن **"تسجيل الدخول باستخدام Agent-Native"**. انقر عليه.
+- يتم نقلك إلى **Dispatch** وإكمال تسجيل الدخول (أو المرور مباشرة إذا قمت بتسجيل الدخول هناك بالفعل).
+- تمت إعادة توجيهك ** مرة أخرى إلى التطبيق، وقمت بتسجيل الدخول ** — وهو **نفس الحساب الموجود مسبقًا** (نفس البريد الإلكتروني) الذي كان لديك من قبل، وليس حسابًا جديدًا.
+- **بيانات التطبيق سليمة** — سجلاتك الحالية وإعداداتك ونطاق مؤسستك كما كانت تمامًا.
+- **لا تزال عمليات تسجيل الدخول المباشرة الحالية تعمل** — يستمر عمل البريد الإلكتروني/كلمة المرور وتسجيل الدخول إلى Google جنبًا إلى جنب مع SSO.
+
+في حالة فشل أي عملية فحص، انتقل مباشرة إلى الخطوة 4 (التراجع) — فهي عملية فورية وآمنة للبيانات.
+
+**4. قم بتوسيع كل تطبيق على حدة.**
+بمجرد التحقق من تطبيق واحد، كرر الخطوات من 2 إلى 3 للتطبيق التالي - مع ضبط `AGENT_NATIVE_IDENTITY_HUB_URL` على عملية نشر واحدة في كل مرة. لا يتم تمكين الدُفعات مطلقًا.
+
+**5. التراجع = إلغاء تعيين env var عند نشر هذا التطبيق.**
+للتراجع عن أي تطبيق، **قم بإزالة `AGENT_NATIVE_IDENTITY_HUB_URL` من بيئة ذلك التطبيق وأعد نشره/أعد تشغيله.** يعود التطبيق فورًا إلى سلوك المصادقة السابق الخاص به. لا يوجد **لا يوجد تغيير في البيانات للتراجع عنه** — تمت إضافة صفوف الهوية فقط، كما أن إلغاء تعيين المتغير يجعل مسار الاتحاد خاملًا مرة أخرى. تعتبر عمليات الاستبدال والتراجع لكل تطبيق مستقلة وقابلة للعكس.
+
+> يقوم الطرح بتسجيل خروج المستخدمين عند تمكين كل تطبيق (يقومون بإعادة المصادقة عبر Dispatch)، ولكنهم دائمًا ما يقومون بتسجيل الدخول مرة أخرى إلى **نفس الحساب المطابق للبريد الإلكتروني مع الحفاظ على البيانات**، لأنه لا يتم إتلاف صفوف الهوية أو إعادة تسميتها أبدًا، بل تتم إضافتها فقط.
+
+## ذات صلة {#related}
+
+- [Authentication](/docs/authentication) — أوضاع المصادقة المحلية، والجلسات، والمؤسسات، ومتغير البيئة `A2A_SECRET`.
+- [A2A Protocol](/docs/a2a-protocol) — نموذج الثقة JWT المُوقع، الذي يتم التحقق منه عند الحدود والذي يُعاد استخدامه.
+- [External Agents](/docs/external-agents) — نفس نمط الهوية الموقع `A2A_SECRET` المطبق على اتصالات الوكيل والروابط العميقة.
+- [Dispatch](/docs/dispatch) — مرجع هوية مساحة العمل ومركز التوجيه.
+- [Security & Data Scoping](/docs/security) — كتابة البيانات الإضافية فقط وتحديد النطاق لكل حساب.
+- [Multi-App Workspaces](/docs/multi-app-workspace) — النشر الموحد أحادي المصدر الذي يتجنب SSO عبر النطاقات تمامًا.