@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,183 @@
+---
+title: "قاعدة البيانات"
+description: "قم بتوصيل قاعدة بيانات SQL المحمولة بتطبيق الوكيل الأصلي الخاص بك واكتب رمز Drizzle غير الموفر."
+---
+
+# قاعدة البيانات
+
+تستخدم التطبيقات الأصلية للوكيل [Drizzle ORM](https://orm.drizzle.team) وتدعم واجهات SQL الخلفية المحمولة. بالنسبة لأي شيء يتجاوز التطوير المحلي، قم بتوصيل قاعدة بيانات SQL المستمرة — Postgres، أو libSQL/Turso، أو واجهة خلفية أخرى متوافقة مع Drizzle — عن طريق تعيين `DATABASE_URL`. عند عدم تعيين هذا المتغير، يعود التطبيق إلى ملف SQLite المحلي بدون تكوين حتى تتمكن من البدء في التطوير على الفور.
+
+```an-diagram title="One schema, many backends" summary="App code uses the framework's dialect-agnostic helpers. The dialect is auto-detected from DATABASE_URL at runtime; unset means a local SQLite file."
+{
+  "html": "<div class=\"diagram-db\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">@agent-native/core/db/schema</span><small class=\"diagram-muted\">table · text · integer · real · now</small><small class=\"diagram-muted\">+ Drizzle query DSL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>DATABASE_URL<br><small class=\"diagram-muted\">dialect auto-detected</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Postgres<br><small class=\"diagram-muted\">Neon · Supabase</small></span><span class=\"diagram-pill\">libSQL / Turso</span><span class=\"diagram-pill\">Cloudflare D1</span><span class=\"diagram-pill warn\">SQLite file<br><small class=\"diagram-muted\">unset = local dev only</small></span></div></div>",
+  "css": ".diagram-db{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-db .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-db .diagram-arrow{font-size:22px;line-height:1}.diagram-db .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+}
+```
+
+## الافتراضي المحلي: ملف SQLite {#default-sqlite}
+
+عند عدم تعيين `DATABASE_URL`، يقوم التطبيق بإنشاء قاعدة بيانات SQLite على `data/app.db`. هذا هو التكوين الافتراضي للتطوير المحلي - لا يتطلب أي إعداد. إنه مخصص للتنمية فقط؛ للإنتاج، قم بتعيين `DATABASE_URL` على قاعدة بيانات SQL المستمرة.
+
+لا تعتمد على هذا الملف المحلي للتطبيقات المنشورة. قد تقوم الحاويات والوظائف بدون خادم وبيئات المعاينة بإعادة ضبط نظام الملفات الخاص بها، مما يعني أن ملف SQLite المحلي يمكن أن يختفي بين عمليات إعادة التشغيل. قم بتعيين `DATABASE_URL` على قاعدة بيانات مستضافة مستمرة قبل استخدام الإنتاج.
+
+## الاتصال بقاعدة بيانات الإنتاج {#production}
+
+قم بتعيين `DATABASE_URL` في ملف `.env` أو بيئة موفر النشر للاتصال بقاعدة بيانات مستضافة. تورسو غير مطلوب. استخدم أي واجهة خلفية SQL متوافقة مع Drizzle تناسب عملية النشر لديك:
+
+```bash
+# Neon Postgres
+DATABASE_URL=postgres://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/mydb?sslmode=require
+
+# Supabase Postgres
+DATABASE_URL=postgres://postgres.xxxx:pass@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+
+# Plain Postgres
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+
+# Turso (libSQL)
+DATABASE_URL=libsql://my-db-org.turso.io
+DATABASE_AUTH_TOKEN=your-token
+```
+
+يكتشف إطار العمل اللهجة تلقائيًا من URL ويقوم بتكوين Drizzle وفقًا لذلك. تغطي المحولات المدمجة Postgres URLs وlibSQL/Turso URLs وSQLite file URLs وروابط Cloudflare D1. تتضمن خيارات الإنتاج الشائعة Neon، وSupabase، وTurso/libSQL، وPostgres العادي، وSQLite المتين، والبيئات المُدارة بواسطة Builder.io عند توفرها.
+
+## قاعدة البيانات المُدارة Builder.io {#builder-managed}
+
+_مخطط (غير متاح بعد):_ عند الاتصال بـ Builder.io، سيتمكن تطبيقك من استخدام قاعدة بيانات مُدارة يتم توفيرها تلقائيًا، دون الحاجة إلى سلاسل اتصال.
+
+## أين يعيش عميل قاعدة البيانات {#db-client}
+
+يقوم كل قالب بإنشاء عميل Drizzle كسول ومفرد عن طريق استدعاء `createGetDb(schema)` من `@agent-native/core/db`. الموقع الأساسي هو `server/db/index.ts`:
+
+```ts
+// server/db/index.ts
+import { createGetDb } from "@agent-native/core/db";
+import * as schema from "./schema.js";
+
+export const getDb = createGetDb(schema);
+```
+
+قم باستيراد `getDb` من هذا المسار المحلي للقالب — `../../server/db/index.js` في المسارات، و`../server/db/index.js` في actions — بدلاً من `@agent-native/core` مباشرةً. يقوم التصدير الأساسي بإرجاع مثيل عام غير مكتوب؛ يحمل `getDb()` الخاص بالقالب أنواع المخططات الخاصة بك. راجع [Server](/docs/server#request-context) لمعرفة كيفية استيراد كل من actions والمسارات المخصصة له.
+
+## مخطط واستعلامات محايدة اللهجة {#schema}
+
+يجب أن يستخدم رمز قاعدة بيانات التطبيق مخطط Drizzle ويستعلم عن DSL حتى يمكن تشغيله عبر موفري الخدمة. لا تكتب أبدًا بناء جملة SQLite فقط (`INSERT OR REPLACE`، `AUTOINCREMENT`، `datetime('now')`) أو بناء جملة Postgres فقط في رمز المنتج.
+
+استخدم مساعدات مخطط إطار العمل من `@agent-native/core/db/schema`:
+
+```ts
+import { table, text, integer, real, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  priority: integer("priority").notNull().default(0),
+  weight: real("weight"),
+  done: integer("done", { mode: "boolean" }).notNull().default(false),
+  ownerEmail: text("owner_email").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+| المساعد   | الغرض                                                          |
+| --------- | -------------------------------------------------------------- |
+| `table`   | تحديد جدول — المفوضين إلى `pgTable` أو `sqliteTable`           |
+| `text`    | عمود النص، يدعم `{ enum: [...] }`                              |
+| `integer` | عمود صحيح، `{ mode: "boolean" }` يعين Postgres منطقيًا         |
+| `real`    | عمود عائم — `real` على SQLite، `double precision` على Postgres |
+| `now`     | الطابع الزمني الحالي الحيادي اللهجات لـ `.default(now())`      |
+
+يحدد الجدول `tasks` أعلاه نفس الأعمدة في كل واجهة خلفية:
+
+```an-schema title="The tasks table" summary="Defined once with the framework helpers; the dialect is chosen at runtime from DATABASE_URL."
+{
+  "entities": [
+    {
+      "id": "tasks",
+      "name": "tasks",
+      "note": "Domain table. Add owner_email (or ...ownableColumns()) so SQL-level scoping can filter rows to the authenticated user.",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true, "nullable": false },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "priority", "type": "integer", "nullable": false, "note": "default 0" },
+        { "name": "weight", "type": "real", "nullable": true },
+        { "name": "done", "type": "integer (boolean mode)", "nullable": false, "note": "default false; maps to a Postgres boolean" },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "enables data scoping" },
+        { "name": "created_at", "type": "text", "nullable": false, "note": "default now()" }
+      ]
+    }
+  ]
+}
+```
+
+لا تقم مطلقًا بالاستيراد من `drizzle-orm/sqlite-core` أو `drizzle-orm/pg-core` مباشرةً. استخدم دائمًا `@agent-native/core/db/schema`.
+
+يجب أن تتضمن الجداول التي تخزن البيانات التي تواجه المستخدم عمود `owner_email` حتى يتمكن نطاق مستوى SQL الخاص بإطار العمل من تصفية الصفوف للمستخدم المصادق عليه - راجع [Security](/docs/security#data-scoping). يجب أن تنشر الجداول التي تدعم أيضًا المشاركة مع مستخدمين أو مؤسسات أخرى `...ownableColumns()` بدلاً من ذلك، مما يضيف `owner_email`، و`org_id`، و`visibility` في مكالمة واحدة - راجع [Sharing](/docs/sharing#building).
+
+للقراءة والكتابة، استخدم منشئ الاستعلامات والمشغلات المحمولة Drizzle من `drizzle-orm`:
+
+```ts
+import { and, desc, eq } from "drizzle-orm";
+import { getDb } from "../server/db/index.js";
+import { tasks } from "../server/db/schema.js";
+
+const db = getDb();
+
+const openTasks = await db
+  .select()
+  .from(tasks)
+  .where(and(eq(tasks.ownerEmail, userEmail), eq(tasks.done, false)))
+  .orderBy(desc(tasks.createdAt));
+
+await db.update(tasks).set({ done: true }).where(eq(tasks.id, taskId));
+```
+
+## فتحات الهروب SQL الخام {#raw-sql}
+
+Raw SQL ليس رمز التطبيق الافتراضي API. استخدمه فقط لعمليات الترحيل الإضافية، أو فحوصات السلامة، أو الاستعلامات المتقدمة التي تمت مراجعتها بعناية والتي لا يمكن لـ Drizzle التعبير عنها، أو الصيانة لمرة واحدة. اجعلها ذات معلمات وحيادية اللهجة. بالنسبة للطوابع الزمنية في مخططات Drizzle، تفضل `.default(now())`؛ بالنسبة للترحيل SQL، استخدم `runMigrations()` بحيث تظل عمليات إعادة كتابة التوافق المدعومة بإطار العمل وتبقى البيانات المرتبطة باللهجات مركزية.
+
+بالنسبة للحالات التي تحتاج فيها حقًا إلى SQL خام خارج استعلامات Drizzle:
+
+- `getDbExec()` — التحويل التلقائي لمعلمات `?` إلى `$1` لـ Postgres
+- `isPostgres()` — التحقق من لهجة وقت التشغيل
+- `intType()` — يُرجع نوع العدد الصحيح للهجة الحالية
+
+## عمليات الترحيل وتحديثات المخطط {#migrations}
+
+في البيئات المستضافة، تشترك معاينات النشر والفروع وخادم الإنتاج المتعددة في نفس قاعدة البيانات الأساسية. ولذلك، يجب أن تتبع تحديثات مخطط قاعدة البيانات قيودًا صارمة لتجنب فقدان البيانات وانقطاع الخدمة.
+
+### قاعدة "صفر تغييرات مدمرة"
+
+يجب أن تكون جميع تحديثات مخطط قاعدة البيانات **إضافية تمامًا**.
+
+- **لا تقم بإسقاط الجداول أو الأعمدة.**
+- **لا تقم بإعادة تسمية الجداول أو الأعمدة.** تبدو إعادة تسمية عمود أو جدول على شكل إسقاط + إنشاء تسلسل إلى Drizzle، مما يؤدي إلى حذف بيانات الإنتاج الحالية نهائيًا.
+- إذا كان هناك حاجة إلى إعادة تسمية عمود أو استبداله، أضف العمود الجديد إلى جانب العمود القديم، وقم بتحديث رمز التطبيق الخاص بك للقراءة من/الكتابة إلى كليهما، وترحيل البيانات، وسحب العمود القديم فقط في إصدار لاحق بمجرد عدم الرجوع إليه في أي عمليات نشر نشطة.
+
+> [!WARNING]
+> **لا تقم مطلقًا بتشغيل `drizzle-kit push` على قاعدة بيانات الإنتاج.**
+> تحدد مخططات قاعدة بيانات القالب جداول المجال الخاصة بالتطبيق فقط؛ فهي لا تحدد جداول الإطار المركزي (`user`، `session`، `application_state`، وما إلى ذلك). إذا قمت بتشغيل `drizzle-kit push` مقابل الإنتاج، فسيكتشف Drizzle جداول إطار العمل هذه على أنها "غير موجودة في المخطط" وسيحاول إسقاطها، مما يتسبب في فشل فوري على مستوى النظام وفقدان البيانات.
+
+### مسار الهجرة الآمنة
+
+بدلاً من الدفع مباشرة، يجب تطبيق تغييرات المخطط عبر عمليات ترحيل SQL التي يتم تنفيذها عند بدء تشغيل التطبيق. قم بتنفيذ عمليات الترحيل الإضافية داخل مكون إضافي للخادم (على سبيل المثال، `server/plugins/db.ts`) عن طريق استدعاء مساعد `runMigrations()` الخاص بإطار العمل:
+
+```an-annotated-code title="An additive migration plugin"
+{
+  "filename": "server/plugins/db.ts",
+  "language": "ts",
+  "code": "import { runMigrations } from \"@agent-native/core/db\";\n\nexport default runMigrations(\n  [\n    {\n      version: 1,\n      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,\n    },\n    {\n      // Dialect-gated: runs only on the matching backend. Omit the other key\n      // to make it a no-op on that dialect.\n      version: 2,\n      sql: {\n        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,\n        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only\n      },\n    },\n  ],\n  { table: \"my_app_migrations\" },\n);",
+  "annotations": [
+    { "lines": "6-7", "label": "Additive only", "note": "`ADD COLUMN IF NOT EXISTS` is safe to re-run and never drops data. Renames look like drop+create to Drizzle, so add-then-migrate instead." },
+    { "lines": "13-16", "label": "Dialect gating", "note": "Pass an object keyed by dialect to run different SQL per backend. Make the other key a no-op (`SELECT 1`) for Postgres-only or SQLite-only features." },
+    { "lines": "19", "label": "Per-app version table", "note": "Each app tracks its own applied versions so migrations are idempotent across restarts and instances." }
+  ]
+}
+```
+
+## متغيرات البيئة {#environment-variables}
+
+| متغير                 | الغرض                                                                           |
+| --------------------- | ------------------------------------------------------------------------------- |
+| `DATABASE_URL`        | سلسلة اتصال SQL المستمرة (unset = SQLite المحلي، وهي متينة فقط للتطوير المحلي)  |
+| `DATABASE_AUTH_TOKEN` | رمز المصادقة المميز للموفرين الذين يحتاجون إلى رمز مميز منفصل، مثل Turso/libSQL |

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

@@ -0,0 +1,349 @@
+---
+title: "النشر"
+description: "انشر تطبيقات الوكيل الأصلية على أي نظام أساسي باستخدام إعدادات Nitro المسبقة - Node.js، وVercel، وNetlify، وCloudflare، وAWS، والمزيد."
+---
+
+# النشر
+
+تستخدم التطبيقات الأصلية للوكيل [Nitro](https://nitro.build) تحت الغطاء، مما يعني أنه يمكنك النشر على أي نظام أساسي بدون أي تغييرات في التكوين — فقط قم بتعيين إعداد مسبق.
+
+## قبل النشر: اختر قاعدة بيانات ثابتة {#persistent-database}
+
+يحتاج كل تطبيق منشور إلى قاعدة بيانات SQL مستمرة. في التطوير المحلي، يعود Agent-Native إلى ملف SQLite في `data/app.db`؛ وهو مناسب لجهازك، ولكنه ليس دائمًا في الحاويات أو المعاينات أو البيئات التي لا تحتوي على خادم حيث يمكن إعادة ضبط نظام الملفات.
+
+قم بتعيين `DATABASE_URL` في موفر النشر الخاص بك قبل ترقية التطبيق إلى مرحلة الإنتاج. يستخدم Agent-native Drizzle للمخطط والاستعلامات، وبالتالي تكون طبقة البيانات قابلة للنقل عبر واجهات SQL الخلفية المتوافقة مع Drizzle ويكتشف إطار العمل اللهجة تلقائيًا من URL. راجع [Database](/docs/database#production) للحصول على قائمة المحولات وتفاصيل اللهجات.
+
+استخدم `DATABASE_AUTH_TOKEN` فقط عندما يطلب موفر قاعدة البيانات رمزًا مميزًا منفصلاً، مثل Turso/libSQL. بالنسبة لمساحات العمل، تكتسب جميع التطبيقات الجذر `DATABASE_URL` افتراضيًا؛ قم بتعيين `<APP_NAME>_DATABASE_URL` عندما يجب أن يستخدم أحد التطبيقات قاعدة بيانات مختلفة.
+
+## نشر مساحة العمل: أصل واحد، تطبيقات متعددة {#workspace-deploy}
+
+إذا كان مشروعك [workspace](/docs/multi-app-workspace)، فيمكنك شحن كل تطبيق فيه إلى أصل واحد باستخدام أمر واحد:
+
+```bash
+npx @agent-native/core@latest deploy
+# https://your-agents.com/mail/*       → apps/mail
+# https://your-agents.com/calendar/*   → apps/calendar
+# https://your-agents.com/forms/*      → apps/forms
+```
+
+يتم إنشاء كل تطبيق باستخدام `APP_BASE_PATH=/<name>` و`VITE_APP_BASE_PATH=/<name>`، ثم يتم تجميعه للإعداد المسبق المستهدف Nitro. يعد Cloudflare Pages هو الإعداد المسبق الافتراضي ويستخدم عامل إرسال تم إنشاؤه في `dist/_worker.js`؛ يستخدم Netlify وظيفة واحدة لكل تطبيق في `.netlify/functions-internal/<app>-server` بالإضافة إلى عمليات إعادة التوجيه التي تم إنشاؤها؛ يكتب Vercel `.vercel/output` على مستوى مساحة العمل باستخدام Build Output API.
+
+```an-diagram title="One origin, many apps" summary="Each workspace app is built with its own base path and mounted under a path prefix on a single origin — so login and cross-app A2A are same-origin and free."
+{
+  "html": "<div class=\"diagram-ws\"><div class=\"diagram-panel\" data-rough><strong>https://your-agents.com</strong><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/mail/*</span><small class=\"diagram-muted\">apps/mail</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/calendar/*</span><small class=\"diagram-muted\">apps/calendar</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/forms/*</span><small class=\"diagram-muted\">apps/forms</small></div></div><div class=\"diagram-col wins\"><span class=\"diagram-pill ok\">shared login session</span><span class=\"diagram-pill ok\">zero-config cross-app A2A</span></div></div>",
+  "css": ".diagram-ws{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-ws .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:14px 16px}.diagram-ws .diagram-row{display:flex;align-items:center;gap:8px}.diagram-ws .wins{display:flex;flex-direction:column;gap:8px;align-items:flex-start}"
+}
+```
+
+يمنحك النشر بنفس المصدر فوزين كبيرين مجانًا:
+
+- **جلسة تسجيل الدخول المشتركة** — قم بتسجيل الدخول إلى أي تطبيق، حيث يتم تسجيل الدخول إلى كل تطبيق.
+- **A2A عبر التطبيقات ذات التكوين الصفري** — وضع العلامات على `@calendar` من البريد هو عملية جلب من نفس المصدر؛ لا يوجد CORS ولا يوجد توقيع JWT بين الأشقاء.
+
+انشر المخرجات باستخدام:
+
+```bash
+wrangler pages deploy dist
+```
+
+بالنسبة لعمليات النشر الموحدة لـ Netlify، استخدم الإعداد المسبق لـ Netlify:
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+بالنسبة لعمليات النشر الموحدة لـ Vercel، استخدم إعداد Vercel المسبق:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+عند تكوين أمر بناء الموفر، استخدم نفس الأمر مع `--build-only`. يجب أن يقوم Vercel بتشغيل `npx @agent-native/core@latest deploy --preset vercel --build-only`؛ يقوم الأمر بكتابة `.vercel/output` مباشرة، لذلك لا يلزم وجود `vercel.json` لتوجيه مساحة العمل.
+
+تتطلب إصدارات مساحة العمل المستضافة وجود `A2A_SECRET` في بيئة موفر النشر.
+يؤدي هذا إلى استئناف عمل Slack وwebhooks الداخلي وA2A عبر التطبيقات من خلال التوقيع
+معالجات الخلفية. لا تزال عمليات التحقق من العناصر المحلية `--build-only` تعمل بدونها.
+
+لا يزال النشر المستقل لكل تطبيق مدعومًا - فقط `cd apps/<name> && npx @agent-native/core@latest build` مثل سقالة مستقلة.
+
+## كيفية العمل {#how-it-works}
+
+عند تشغيل `npx @agent-native/core@latest build`، يقوم Nitro ببناء كل من العميل SPA والخادم API في `.output/`:
+
+```an-file-tree title="Build output"
+{
+  "entries": [
+    { "path": ".output/", "note": "self-contained — copy to any environment and run" },
+    { "path": ".output/public/", "note": "built SPA (static assets)" },
+    { "path": ".output/server/index.mjs", "note": "server entry point" },
+    { "path": ".output/server/chunks/", "note": "server code chunks" }
+  ]
+}
+```
+
+الإخراج مستقل بذاته - انسخ `.output/` إلى أي بيئة وقم بتشغيله.
+
+```an-diagram title="Build to deploy" summary="One source tree builds to a Nitro preset; the same self-contained output runs on Node, Vercel, Netlify, Cloudflare, AWS, or Deno. Every instance points at the same persistent DATABASE_URL."
+{
+  "html": "<div class=\"diagram-deploy\"><div class=\"diagram-box\" data-rough>App source</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">build</span><small class=\"diagram-muted\">Nitro preset</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Node.js</span><span class=\"diagram-pill\">Vercel</span><span class=\"diagram-pill\">Netlify</span><span class=\"diagram-pill\">Cloudflare</span><span class=\"diagram-pill\">AWS Lambda</span><span class=\"diagram-pill\">Deno</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Persistent DATABASE_URL<br><small class=\"diagram-muted\">shared by every instance</small></div></div>",
+  "css": ".diagram-deploy{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-deploy .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-deploy .diagram-arrow{font-size:22px;line-height:1}.diagram-deploy .diagram-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}"
+}
+```
+
+## ضبط الإعداد المسبق {#setting-the-preset}
+
+افتراضيًا، يتم إنشاء Nitro لـ Node.js. لاستهداف منصة مختلفة، قم بضبط الإعداد المسبق في `vite.config.ts`:
+
+```ts
+import { defineConfig } from "@agent-native/core/vite";
+
+export default defineConfig({
+  nitro: {
+    preset: "vercel",
+  },
+});
+```
+
+أو استخدم متغير البيئة `NITRO_PRESET` في وقت الإنشاء:
+
+```bash
+NITRO_PRESET=netlify npx @agent-native/core@latest build
+```
+
+## Node.js (افتراضي) {#nodejs}
+
+الإعداد المسبق الافتراضي. البناء والتشغيل:
+
+```bash
+npx @agent-native/core@latest build
+node .output/server/index.mjs
+```
+
+اضبط `PORT` لتكوين منفذ الاستماع (الافتراضي: `3000`).
+
+استخدم خط Node.js LTS الحالي لعمليات نشر الإنتاج. اعتبارًا من مايو 2026،
+هو Node.js 24؛ وصل Node.js 20 إلى نهاية العمر الافتراضي في 30 أبريل 2026 ولم يعد
+يتلقى تحديثات الأمان الأولية.
+
+### عامل الميناء {#docker}
+
+```dockerfile
+FROM node:24-slim AS build
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+FROM node:24-slim
+WORKDIR /app
+COPY --from=build /app/.output .output
+# data/ is a runtime-created SQLite directory — do not copy a dev DB into prod.
+# For production, set DATABASE_URL to a hosted Postgres or Turso instance.
+RUN mkdir -p /app/data
+ENV PORT=3000
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+## فيرسل {#vercel}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "vercel" },
+});
+```
+
+النشر عبر Vercel CLI أو git Push:
+
+```bash
+vercel deploy
+```
+
+بالنسبة لمساحة العمل، أنشئ كل تطبيق في حزمة Vercel Build Output API واحدة:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+بالنسبة لعمليات نشر Vercel Git، قم بتعيين أمر الإنشاء على:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel --build-only
+```
+
+ينسخ بناء مساحة العمل مخرجات Nitro `vercel` لكل تطبيق إلى الجذر `.vercel/output`، ويمنح كل وظيفة بيئة مسار التثبيت الخاصة بها، ويكتب تكوين المسار الذي يخدم التطبيقات في `/<app-id>`.
+
+## نيتليفي {#netlify}
+
+يعمل الإعداد المسبق Nitro `netlify` بشكل جيد، وفي الممارسة العملية، أعطانا عمليات تشغيل باردة أسرع بكثير من Cloudflare Pages (حوالي 200 مللي ثانية TTFB مقابل ~9s) للقوالب التي تتحدث إلى Postgres الخارجية (نيون). إما أن تقوم بضبط الإعداد المسبق في `vite.config.ts`:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "netlify" },
+});
+```
+
+...أو قم بتعيين `NITRO_PRESET=netlify` في وقت الإنشاء.
+
+بالنسبة لمساحة العمل، انشر كل تطبيق من موقع Netlify واحد عن طريق تشغيل:
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+يكتب بناء مساحة العمل الأصول الثابتة ضمن `dist/_workspace_static/` ويوجه كل تطبيق إلى وظيفة Netlify الخاصة به دون عمليات إعادة توجيه الأصول القسرية، لذلك يتم تقديم ملفات مثل `/mail/assets/...` بشكل ثابت قبل أن تتعامل وظيفة الخادم مع مسارات التطبيق.
+
+## صفحات Cloudflare {#cloudflare-pages}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "cloudflare_pages" },
+});
+```
+
+## AWS لامدا {#aws-lambda}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "aws_lambda" },
+});
+```
+
+## نشر دينو {#deno-deploy}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "deno_deploy" },
+});
+```
+
+## متغيرات البيئة {#environment-variables}
+
+### الإنشاء/وقت التشغيل {#env-runtime}
+
+| متغير                       | الوصف                                                                                                                                         |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                      | منفذ الخادم (Node.js فقط)                                                                                                                     |
+| `NITRO_PRESET`              | تجاوز الإعداد المسبق للإنشاء في وقت الإنشاء                                                                                                   |
+| `APP_BASE_PATH`             | قم بتثبيت التطبيق تحت بادئة (مثل `/mail`). يتم ضبطه تلقائيًا بواسطة `npx @agent-native/core@latest deploy`؛ اتركه بدون ضبط للوضع المستقل.     |
+| `AGENT_PROD_CODE_EXECUTION` | وضع تنفيذ كود الإنتاج الاختياري: `off` (افتراضي)، أو `sandboxed`، أو `trusted`. انظر [Production Code Execution](#production-code-execution). |
+
+متغيرات اتصال قاعدة البيانات (`DATABASE_URL`، `DATABASE_AUTH_TOKEN`، `<APP_NAME>_DATABASE_URL` لكل تطبيق) موجودة في [Database](/docs/database#production).
+
+### مطلوب في الإنتاج {#env-required-prod}
+
+يجب تعيين هذه الإعدادات قبل الترويج لتطبيق ما إلى عملية نشر حقيقية. القيم المفقودة إما مغلقة بشكل فاشل (يرفض إطار العمل البدء / يرفض التعامل مع الطلبات) أو تتراجع إلى سلوك أضعف مع تحذير عالٍ.
+
+| متغير                    | الوصف                                                                                                                                                                                                                                         |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`     | 32+ سلسلة عشوائية من الأحرف. علامات ملفات تعريف الارتباط الخاصة بالجلسة AND هي HMAC الاحتياطية لـ `OAUTH_STATE_SECRET` و`SECRETS_ENCRYPTION_KEY`. مطلوب بشدة: يتم تشغيل إطار العمل عند بدء التشغيل إذا كان مفقودًا في الإنتاج.                |
+| `BETTER_AUTH_URL`        | الأصل العام لهذا التطبيق (مثل `https://mail.example.com`). يُستخدم لمجال ملفات تعريف الارتباط وبناء إعادة التوجيه OAuth.                                                                                                                      |
+| `ANTHROPIC_API_KEY`      | مفتاح API لوكيل الإنتاج المضمن. **في عمليات النشر متعددة المستأجرين**، يرفض إطار العمل الرجوع إلى ذلك عندما لا يكون لدى المستخدم مفتاح لكل مستخدم — يلزم إحضار مفتاحك الخاص. تستخدمه عمليات التثبيت المستضافة ذاتيًا لمستأجر واحد كمفتاح عام. |
+| `OAUTH_STATE_SECRET`     | مفتاح HMAC مخصص لمظاريف الحالة OAuth (Google، وAtlassian، وZoom). يعود إلى `BETTER_AUTH_SECRET` عند عدم الضبط، ولكن يوصى باستخدام قيمة مخصصة حتى لا يؤدي تدوير إحداهما إلى إبطال الأخرى. الإنشاء عبر `openssl rand -hex 32`.                  |
+| `A2A_SECRET`             | تمت مشاركة HMAC للتطبيقات البينية A2A JSON-RPC. بدونها، كل نقطة نهاية A2A ونقطة النهاية ذاتية التشغيل `/_agent-native/integrations/process-task` ترجع 503 في الإنتاج.                                                                         |
+| `SECRETS_ENCRYPTION_KEY` | مفتاح AES-256-GCM لخزنة الأسرار المشفرة غير النشطة. يعود إلى `BETTER_AUTH_SECRET`. يفشل بشدة في الإنتاج عند عدم ضبط كليهما.                                                                                                                   |
+
+### المصادقة والهوية {#env-auth}
+
+تم توثيق بيانات اعتماد موفر OAuth (Google، GitHub)، والاحتياطيات لحامل MCP الثابتة (`ACCESS_TOKEN` / `ACCESS_TOKENS`)، وتبديلات التحقق من البريد الإلكتروني في [Authentication](/docs/authentication). قم بتعيينها هناك حسب وضع المصادقة الذي تختاره.
+
+### Webhooks الوارد {#env-webhooks}
+
+يتطلب كل تكامل للمراسلة سر التوقيع الخاص به في الإنتاج (يتم إغلاق المعالجات عند الطلبات المزورة عندما يكون السر مفقودًا). يتم سرد المتغيرات لكل تكامل في [Messaging](/docs/messaging) و[Security](/docs/security). بالنسبة للتطوير المحلي فقط، يختار `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` العودة إلى "التحذير والقبول" - ولا تقم بتعيينه مطلقًا في المنتج.
+
+### تكوين الأمان (الاشتراك) {#security-config}
+
+الافتراضيات صارمة. تعمل مجموعة من علامات الاشتراك على تخفيف السلوك (تتبعات مكدس تصحيح الأخطاء، webhooks التي لم يتم التحقق منها، مفتاح احتياطي على مستوى مساحة العمل، محول MCP متعدد المؤسسات لمحور MCP، عمليات الكتابة env-var في وقت التشغيل). تم توثيقهم مع مقايضاتهم الأمنية في [Security](/docs/security). لا تقم بتعيينها إلا إذا كنت تريد المسار المريح على وجه التحديد.
+
+### وراثة مساحة العمل .env {#env-inheritance}
+
+داخل مساحة العمل، يتم تحميل الجذر `.env` في كل تطبيق تلقائيًا، لذلك يلزم تعيين المفاتيح المشتركة مثل `ANTHROPIC_API_KEY` و`A2A_SECRET` و`BETTER_AUTH_SECRET` و`OAUTH_STATE_SECRET` مرة واحدة فقط. يفوز `apps/<name>/.env` لكل تطبيق في الصراع.
+
+### توليد أسرار قوية {#env-generate-secrets}
+
+بالنسبة لأي سر تم وضع علامة "32+ حرف عشوائي" (`BETTER_AUTH_SECRET`، `OAUTH_STATE_SECRET`، `A2A_SECRET`، `SECRETS_ENCRYPTION_KEY`)، قم بإنشاء قيم جديدة باستخدام:
+
+```bash
+openssl rand -hex 32
+```
+
+قم بتدويرها عن طريق استبدال env var في كل مثيل وإعادة النشر - تصبح مظاريف حالة الجلسات / OAuth الموقعة تحت المفتاح القديم غير صالحة، لذلك قد يحتاج المستخدمون إلى تسجيل الدخول مرة أخرى.
+
+## أدوات وكيل الإنتاج {#production-agent-tools}
+
+يحصل وكلاء الإنتاج على أدوات إطار العمل actions بالإضافة إلى أدوات إطار العمل المسجلة للتطبيق من
+المكون الإضافي للدردشة مع الوكيل. يتم تمكين عمليات الكتابة في قاعدة البيانات افتراضيًا لأن قاعدة البيانات الأولية
+يتم تحديد نطاق الأدوات ليشمل المستخدم/المؤسسة التي تمت مصادقتها، ولكن يمكن لمالكي التطبيق تضييق نطاق
+السطح عندما يجب أن يكون النشر أكثر رأيًا:
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  // Default: "write" (also true)
+  databaseTools: "read", // "write" | "read" | "off"
+  extensionTools: false,
+});
+```
+
+- `databaseTools: "write"` — افتراضي. يسجل `db-schema`، `db-query`،
+  `db-exec`، و`db-patch`. يتم تحديد نطاق عمليات الكتابة للمستخدم/المؤسسة الحالية و
+  تم حظر تغييرات المخطط.
+- `databaseTools: "read"` — يُسجل `db-schema` و`db-query` فقط؛ وكلاء
+  افحص البيانات باستخدام SQL ولكن يجب استخدام التطبيق المكتوب actions للكتابة.
+- `databaseTools: "off"` أو `false` — يزيل أدوات قاعدة البيانات الأولية من
+  سطح الوكيل، لذا فإن actions الخاص بالتطبيق هو المسار الوحيد للوصول إلى البيانات.
+- `extensionTools: false` — يزيل إدارة امتداد إطار العمل actions و
+  إرشادات سريعة (`create-extension`، `update-extension`، وما إلى ذلك) للتطبيقات التي
+  لا ترغب في أن يقوم الوكيل بإنشاء تطبيقات مصغرة في وضع الحماية.
+
+## تنفيذ كود الإنتاج {#production-code-execution}
+
+افتراضيًا، يعمل وكلاء الإنتاج بدون أدوات تنفيذ التعليمات البرمجية. يمكنهم استدعاء التطبيق actions، وأدوات قاعدة البيانات، وأدوات MCP، وأدوات المتصفح/الجلسة، وأدوات إطار العمل المسجلة الأخرى، لكنهم لا يحصلون على حق الوصول إلى نظام الملفات أو shell.
+
+يمكن لعمليات النشر المتوافقة مع العقدة الاشتراك في تنفيذ تعليمات برمجية للإنتاج من خلال البرنامج الإضافي لدردشة الوكيل أو تجاوز البيئة:
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  codeExecution: { production: "sandboxed" },
+});
+```
+
+الأوضاع المتاحة هي:
+
+- `off` — الإعداد الافتراضي. لم يتم تسجيل أي أدوات لتنفيذ التعليمات البرمجية في الإنتاج.
+- `sandboxed` — تسجيل `run-code`، وهو مشغل Node.js JavaScript معزول مع بيئة منقحة، ودليل مؤقت جديد، وحدود الإخراج/الوقت، وجسر مضيف محلي للأدوات المسجلة المدرجة في القائمة المسموح بها مثل `provider-api-request`، و`provider-api-docs`، و`provider-api-catalog`، و`web-request`، وجسر ملفات مساحة العمل المدعومة بالموارد. المستخدمة من قبل `workspaceRead` / `workspaceWrite`.
+- `trusted` — يقوم بتسجيل `run-code` بالإضافة إلى سجل أدوات الترميز الكامل (`bash`، `read`، `edit`، `write`). استخدم هذا فقط لعمليات النشر التي يتحكم فيها مستأجر واحد أو المشغل حيث يكون الوصول الكامل إلى المضيف مقصودًا.
+
+قم بتعيين `AGENT_PROD_CODE_EXECUTION=sandboxed` أو `AGENT_PROD_CODE_EXECUTION=trusted` لتجاوز خيار البرنامج الإضافي لنشر محدد دون تغيير التعليمات البرمجية. يفرض `AGENT_PROD_CODE_EXECUTION=off` إيقاف تنفيذ التعليمات البرمجية حتى عندما يمكّنه خيار البرنامج الإضافي.
+
+إن صندوق الحماية `run-code` عبارة عن عزل على مستوى العملية، وليس حاوية نظام تشغيل. فهو يزيل أسرار التطبيق من بيئة العمليات التابعة ويستخدم نموذج إذن Node عندما يكون متاحًا، ولكن الشبكة الصادرة لا يتم حظرها بواسطة Node نفسها؛ يجب أن تمر المكالمات التي تمت مصادقتها عبر مساعدي الجسر الذي تكشفه الأداة.
+
+## تحديث UI في الإنتاج {#updating-ui-in-production}
+
+تتمثل إحدى الميزات الأساسية للوكيل الأصلي في أنه يمكن للوكيل تعديل التعليمات البرمجية المصدر لتطبيقك - المكونات والمسارات والأنماط وactions. أثناء التطوير المحلي، يعمل هذا بسلاسة لأن الوكيل لديه حق الوصول الكامل إلى نظام الملفات.
+
+في نشر الإنتاج القياسي مع إيقاف [production code execution](#production-code-execution)، يتمتع الوكيل بإمكانية الوصول إلى أدوات التطبيق (actions، وقاعدة البيانات، وMCP) ولكن ليس إلى نظام الملفات. وهذا يعني أن الوكيل يمكنه قراءة البيانات وكتابتها، وتشغيل actions، والتفاعل مع الخدمات الخارجية - ولكن لا يمكنه تحرير مكونات React أو إضافة مسارات جديدة على مثيل منشور.
+
+### Builder.io: التحرير المرئي في الإنتاج {#builderio}
+
+يقوم [Builder.io](https://www.builder.io) بحل هذه المشكلة من خلال توفير بيئة سحابية مُدارة حيث يحتفظ الوكيل بالقدرة على تعديل UI لتطبيقك في الإنتاج. قم بتوصيل الريبو الخاص بك بـ Builder.io والمطالبة بتغييرات UI مباشرة - لا حاجة لإعادة النشر.
+
+**كيفية العمل:**
+
+1. قم بتوصيل الريبو الأصلي للوكيل الخاص بك إلى Builder.io
+2. يوفر Builder.io إطارًا سحابيًا مع الوكيل والتحرير المرئي والتعاون في الوقت الفعلي
+3. اطلب من الوكيل إجراء تغييرات على UI - حيث يقوم بتحرير المكونات والمسارات والأنماط بشكل مباشر
+4. يتم الالتزام بالتغييرات مرة أخرى في الريبو الخاص بك
+
+راجع [Frames](/docs/frames) لمعرفة المزيد حول لوحة الوكيل المضمنة مقابل خيارات الإطار السحابي.
+
+## نشر المثيلات المتعددة {#multi-instance}
+
+تقوم تطبيقات Agent-Native بتخزين جميع الحالات في SQL عبر Drizzle ومزامنة UI عبر [polling](/docs/key-concepts#polling-sync) مع قاعدة البيانات - لا توجد حالة نظام ملفات، ولا توجد جلسات ثابتة، ولا توجد ذاكرة تخزين مؤقت في الذاكرة. وهذا يعني أن عمليات النشر متعددة المثيلات وبدون خادم تعمل خارج الصندوق: قم بتوجيه كل مثيل إلى نفس `DATABASE_URL` وستتقارب تلقائيًا. انظر [Key Concepts — Data in SQL](/docs/key-concepts#data-in-sql) و[Portability](/docs/key-concepts#hosting-agnostic).