snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ar/developers/extend/apps/getting-started/concepts.mdx

@@ -0,0 +1,102 @@
+---
+title: المفاهيم
+description: كيفية عمل تطبيقات Twenty — نموذج الكيان، العزل (sandboxing)، ودورة حياة التثبيت.
+icon: sitemap
+---
+
+تطبيقات Twenty هي حزم TypeScript توسّع مساحة عملك بكائنات مخصّصة، ومنطق، ومكوّنات واجهة مستخدم (UI)، وقدرات ذكاء اصطناعي. تعمل على منصة Twenty مع عزل كامل وضوابط الأذونات.
+
+## كيف تعمل التطبيقات
+
+التطبيق عبارة عن مجموعة من **الكيانات** يتم إعلانها باستخدام دوال `defineEntity()` من حزمة `twenty-sdk`. يكتشف SDK هذه التصريحات عبر تحليل AST وقت البناء وينتج **ملف بيان** — وصفًا كاملًا لما يضيفه تطبيقك إلى مساحة العمل. تتحقق هذه الدوال من تكوينك وقت البناء وتوفّر إكمالًا تلقائيًا في بيئة التطوير وأمان الأنواع.
+
+```
+your-app/
+├── src/
+│   ├── application-config.ts    ← defineApplication (required, one per app)
+│   ├── roles/                   ← defineRole
+│   ├── objects/                 ← defineObject
+│   ├── fields/                  ← defineField
+│   ├── logic-functions/         ← defineLogicFunction
+│   ├── front-components/        ← defineFrontComponent
+│   ├── skills/                  ← defineSkill
+│   ├── agents/                  ← defineAgent
+│   ├── views/                   ← defineView
+│   ├── navigation-menu-items/   ← defineNavigationMenuItem
+│   └── page-layouts/            ← definePageLayout
+├── public/                      ← Static assets (images, icons)
+└── package.json
+```
+
+<Note>
+  **تنظيم الملفات متروك لك.** يعتمد اكتشاف الكيانات على AST — يعثر SDK على استدعاءات `export default defineEntity(...)` بغض النظر عن مكان وجود الملف. بنية المجلدات أعلاه هي اصطلاح وليست متطلبًا.
+</Note>
+
+## أنواع الكيانات
+
+| كيان                   | الغرض                                                                               | وثائق                                                                                                             |
+| ---------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| **تطبيق**              | هوية التطبيق، الدور الافتراضي، والمتغيرات                                           | [تهيئة التطبيق](/l/ar/developers/extend/apps/config/application)                                                       |
+| **دور**                | مجموعات الأذونات للكائنات والحقول                                                   | [الأدوار والأذونات](/l/ar/developers/extend/apps/config/roles)                                                         |
+| **الكائن**             | أنواع سجلات مخصّصة مع حقول                                                          | [الكائنات](/l/ar/developers/extend/apps/data/objects)                                                                  |
+| **الحقل**              | إضافة حقول إلى الكائنات من تطبيقات أخرى                                             | [توسيع الكائنات](/l/ar/developers/extend/apps/data/extending-objects)                                                  |
+| **علاقة**              | روابط ثنائية الاتجاه بين الكائنات                                                   | [العلاقات](/l/ar/developers/extend/apps/data/relations)                                                                |
+| **دالة منطقية**        | TypeScript على جانب الخادم مع مشغّلات                                               | [الوظائف المنطقية](/l/ar/developers/extend/apps/logic/logic-functions)                                                 |
+| **مهارة**              | تعليمات قابلة لإعادة الاستخدام لوكلاء الذكاء الاصطناعي                              | [المهارات والوكلاء](/l/ar/developers/extend/apps/logic/skills-and-agents)                                              |
+| **وكيل**               | مساعدو الذكاء الاصطناعي بموجهات مخصّصة                                              | [المهارات والوكلاء](/l/ar/developers/extend/apps/logic/skills-and-agents)                                              |
+| **موفر الاتصال**       | بيانات اعتماد OAuth لواجهات برمجة التطبيقات التابعة لجهات خارجية                    | [الاتصالات](/l/ar/developers/extend/apps/logic/connections)                                                            |
+| **عرض**                | عروض قوائم السجلات المكوّنة مسبقًا                                                  | [العروض](/l/ar/developers/extend/apps/layout/views)                                                                    |
+| **عنصر قائمة التنقّل** | عناصر الشريط الجانبي المخصّصة                                                       | [عناصر قائمة التنقّل](/l/ar/developers/extend/apps/layout/navigation-menu-items)                                       |
+| **تخطيط الصفحة**       | علامات التبويب وعناصر الواجهة في صفحة تفاصيل السجل                                  | [تخطيطات الصفحات](/l/ar/developers/extend/apps/layout/page-layouts)                                                    |
+| **مكوّن أمامي**        | واجهة مستخدم React معزولة داخل Twenty                                               | [المكوّنات الأمامية](/l/ar/developers/extend/apps/layout/front-components)                                             |
+| **التبعيات المشتركة**  | التبعيات المشتركة بين مكوّنات الواجهة الأمامية للتطبيق، والمُعرَّفة في package.json | [التبعيات المشتركة](/l/ar/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
+| **عنصر قائمة الأوامر** | إجراءات سريعة ومدخلات Cmd+K                                                         | [عناصر قائمة الأوامر](/l/ar/developers/extend/apps/layout/command-menu-items)                                          |
+
+## العزل
+
+* **الدوال المنطقية** تعمل في عمليات Node.js معزولة على الخادم. لا تصل إلى البيانات إلا من خلال عميل API مكتوب الأنواع، الذي يعمل إما بصفة الشخص الذي بدأ التشغيل أو بصفة التطبيق نفسه. راجع [صلاحيات الوصول التي تستخدمها الاستدعاءات](/l/ar/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
+* **المكوّنات الأمامية** تعمل ضمن Web Workers باستخدام Remote DOM — معزولة عن الصفحة الرئيسية لكنها تعرض عناصر DOM الأصلية (وليس iframes). تتواصل مع Twenty عبر واجهة API للمضيف تعتمد تمرير الرسائل.
+* **الأذونات** تُطبَّق على مستوى واجهة API. يتم إدخال رمزي تشغيل، وكلاهما مشتق من الدور المُعلن باستخدام `defineApplicationRole()`؛ ويُقيَّد الرمز الافتراضي بشكل أكبر بما يستطيع الشخص الذي بدأ التشغيل القيام به كلما كان هناك شخص وراء التشغيل.
+
+## دورة حياة التطبيق
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Development                                             │
+│   npx create-twenty-app → yarn twenty dev (live sync)   │
+├─────────────────────────────────────────────────────────┤
+│ Build & Deploy                                          │
+│   yarn twenty dev:build → yarn twenty app:publish        │
+├─────────────────────────────────────────────────────────┤
+│ Install flow                                            │
+│   upload → [pre-install] → metadata migration →         │
+│   generate SDK → [post-install] → … → [uninstall]       │
+├─────────────────────────────────────────────────────────┤
+│ Publish                                                 │
+│   npm publish → appears in Twenty marketplace           │
+└─────────────────────────────────────────────────────────┘
+```
+
+* **`yarn twenty dev`** — يراقب ملفات المصدر لديك ويزامن التغييرات مباشرةً إلى خادم Twenty متصل. يُعاد توليد عميل API مضبوط الأنواع تلقائيًا عند تغيّر المخطط.
+* **`yarn twenty dev:build`** — يجمّع TypeScript، ويضمّن الدوال المنطقية والمكوّنات الأمامية باستخدام esbuild، وينتج ملف بيان.
+* **خطّافات ما قبل/ما بعد التثبيت وإلغاء التثبيت** — دوال اختيارية تعمل أثناء التثبيت أو مباشرة قبل الإزالة. راجع [خطّافات التثبيت](/l/ar/developers/extend/apps/config/install-hooks) للتفاصيل.
+
+## الخطوات التالية
+
+<CardGroup cols={2}>
+  <Card title="التهيئة" icon="screwdriver-wrench" href="/l/ar/developers/extend/apps/config/overview">
+    هوية التطبيق، الدور الافتراضي، وخطّافات التثبيت وإلغاء التثبيت.
+  </Card>
+  <Card title="بيانات" icon="database" href="/l/ar/developers/extend/apps/data/overview">
+    الكائنات، الحقول، والعلاقات ثنائية الاتجاه.
+  </Card>
+  <Card title="المنطق" icon="bolt" href="/l/ar/developers/extend/apps/logic/overview">
+    دوال منطقية، مهارات، وكلاء، واتصالات OAuth.
+  </Card>
+  <Card title="التخطيط" icon="table-columns" href="/l/ar/developers/extend/apps/layout/overview">
+    العروض، التنقّل، تخطيطات الصفحات، ومكوّنات الواجهة الأمامية.
+  </Card>
+  <Card title="العمليات" icon="rocket" href="/l/ar/developers/extend/apps/operations/overview">
+    سطر الأوامر (CLI)، الاختبار، المستودعات البعيدة (remotes)، التكامل المستمر (CI)، ونشر تطبيقك.
+  </Card>
+</CardGroup>

packages/twenty-docs/l/ar/developers/extend/apps/getting-started/local-server.mdx

@@ -0,0 +1,87 @@
+---
+title: الخادم المحلي
+description: إدارة خادم Twenty المحلي المستند إلى Docker — بدء التشغيل، الإيقاف، الترقية، مثيل اختبار متوازٍ، وإعداد SDK اليدوي.
+icon: server
+---
+
+## إدارة الخادم المحلي
+
+استخدم `yarn twenty docker:*` للتحكّم في حاوية Twenty المحلية:
+
+| أمر                                    | ماذا يفعل                                          |
+| -------------------------------------- | -------------------------------------------------- |
+| `yarn twenty docker:start`             | بدء تشغيل الخادم (يسحب الصورة إذا لزم الأمر)       |
+| `yarn twenty docker:start 2.2.0`       | بدء إصدار محدد من الخادم                           |
+| `yarn twenty docker:start --port 3030` | بدء التشغيل على منفذ مخصّص                         |
+| `yarn twenty docker:stop`              | إيقاف الخادم (مع الحفاظ على البيانات)              |
+| `yarn twenty docker:status`            | عرض عنوان URL والإصدار وبيانات اعتماد تسجيل الدخول |
+| `yarn twenty docker:logs`              | بث سجلات الخادم                                    |
+| `yarn twenty docker:reset`             | مسح البيانات والبدء من جديد                        |
+| `yarn twenty docker:upgrade`           | سحب أحدث صورة `twenty-app-dev`                     |
+| `yarn twenty docker:upgrade 2.2.0`     | الترقية إلى إصدار محدد                             |
+
+تظل البيانات محفوظة عبر عمليات إعادة التشغيل في وحدتي تخزين Docker (`twenty-app-dev-data` لـ PostgreSQL، و`twenty-app-dev-storage` للملفات). استخدم `reset` لمسح كل شيء.
+
+## تثبيت إصدار الخادم
+
+عند عدم تمرير أي إصدار، يقوم `docker:start` باشتقاق الإصدار من النطاق `engines.twenty` في ملف `package.json` لتطبيقك — وهو نفس النطاق الذي يتحقق منه الخادم عند تثبيت تطبيقك. يشغّل أحدث صورة منشورة لـ `twenty-app-dev` التي تُلبي هذا النطاق، مع الرجوع إلى `latest` عندما يكون الحقل غير موجودًا أو لا يتطابق أي إصدار منشور:
+
+```json filename="package.json"
+{
+  "engines": {
+    "twenty": ">=2.2.0"
+  }
+}
+```
+
+مرِّر إصدارًا بشكلٍ صريح لتجاوز النطاق لتشغيلٍ واحد فقط: `yarn twenty docker:start 2.3.0`. إذا كانت هناك حاوية موجودة بالفعل على إصدار مختلف، يقوم `docker:start` بترقيتها في مكانها (مع إعادة إنشاء الحاوية مع الحفاظ على وحدات تخزين بياناتك).
+
+## ترقية صورة الخادم
+
+يقوم `yarn twenty docker:upgrade` بسحب أحدث صورة، ومقارنة التجزئات، ولا يعيد إنشاء الحاوية إلا إذا حدث تغيير فعلي. تظل وحدات التخزين محفوظة — ويتم استبدال الحاوية فقط. إذا تم سحب صورة جديدة وكانت الحاوية تعمل، فستبدأ عملية الترقية تلقائيًا حاوية جديدة؛ شغّل بعد ذلك `yarn twenty docker:start` للانتظار حتى تصبح سليمة.
+
+```bash filename="Terminal"
+yarn twenty docker:upgrade            # Latest
+yarn twenty docker:upgrade 2.2.0      # Specific version
+```
+
+تحقّق من الإصدار الجاري باستخدام `yarn twenty docker:status` (يعرض قيمة `APP_VERSION` المضمنة في الحاوية).
+
+## تشغيل مثيل اختبار متوازٍ
+
+مرّر `--test` إلى أي أمر `docker:*` لإدارة مثيل ثانٍ معزول تمامًا — مفيد لاختبارات التكامل أو للتجربة من دون لمس بيانات التطوير الرئيسية لديك:
+
+| أمر                                 | ماذا يفعل                                 |
+| ----------------------------------- | ----------------------------------------- |
+| `yarn twenty docker:start --test`   | بدء مثيل الاختبار (المنفذ الافتراضي 2021) |
+| `yarn twenty docker:stop --test`    | إيقافه                                    |
+| `yarn twenty docker:status --test`  | عرض حالته                                 |
+| `yarn twenty docker:logs --test`    | بث سجلاته                                 |
+| `yarn twenty docker:reset --test`   | مسح بياناته                               |
+| `yarn twenty docker:upgrade --test` | ترقية صورته                               |
+
+يملك مثيل الاختبار حاويته الخاصة (`twenty-app-dev-test`) ووحدات التخزين الخاصة به (`twenty-app-dev-test-data`، `twenty-app-dev-test-storage`) وتهيئته — ويعمل جنبًا إلى جنب مع مثيلك الرئيسي بدون تعارضات. اجمع `--test` مع `--port` لتجاوز المنفذ 2021.
+
+## إعداد يدوي (بدون أداة توليد الهيكل)
+
+تجاوز أداة توليد الهيكل إذا كنت تضيف SDK إلى مشروع قائم:
+
+```bash filename="Terminal"
+yarn add twenty-sdk twenty-client-sdk
+```
+
+أضِف النص البرمجي إلى `package.json`:
+
+```json filename="package.json"
+{
+  "scripts": {
+    "twenty": "twenty"
+  }
+}
+```
+
+يمكنك الآن تشغيل `yarn twenty dev`، و`yarn twenty docker:start`، والبقية.
+
+<Note>
+لا تثبّت `twenty-sdk` عالميًا — ثبِّته لكل مشروع بحيث يستخدم كل تطبيق إصداره الخاص.
+</Note>

packages/twenty-docs/l/ar/developers/extend/apps/getting-started/project-structure.mdx

@@ -0,0 +1,79 @@
+---
+title: هيكل المشروع
+description: ما الذي يوجد داخل تطبيق Twenty المُهيكل مسبقًا — الملفات والمجلدات، وما الذي يفعله كلٌّ منها.
+icon: folder-tree
+---
+
+يبدو التطبيق الجديد الذي يتم إنشاؤه بواسطة `npx create-twenty-app` كما يلي:
+
+```text filename="my-twenty-app/"
+my-twenty-app/
+  package.json
+  src/
+    application-config.ts                   # Required — your app's entry point
+    default-role.ts                         # Permissions for logic functions
+    constants/
+      universal-identifiers.ts              # Auto-generated UUIDs and metadata
+    front-components/
+      main-page.tsx                         # Welcome page component
+    navigation-menu-items/
+      main-page.navigation-menu-item.ts     # Sidebar entry for the welcome page
+    page-layouts/
+      main-page.page-layout.ts              # Standalone page hosting the component
+    __tests__/
+      application-config.test.ts            # Unit test
+      global-setup.ts                       # Integration test setup (sync + uninstall)
+      schema.integration-test.ts            # Integration test against a live server
+  .github/workflows/
+    ci.yml                                  # Lint, typecheck, unit + integration tests
+    cd.yml                                  # Deploy + install on push to main
+    publish.yml                             # Publish to npm on version tags (with provenance)
+  public/
+    logo.svg                                # Static assets
+  vitest.config.ts                          # Integration test runner config
+  vitest.unit.config.ts                     # Unit test runner config
+  tsconfig.json, tsconfig.spec.json
+  .nvmrc, .yarnrc.yml, .oxlintrc.json
+  README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md
+```
+
+## الملفات الرئيسية
+
+| ملف / مجلد                                                                 | الغرض                                                                                                        |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `src/application-config.ts`                                                | **مطلوب.** ملف الإعداد الرئيسي لتطبيقك.                                                                      |
+| `src/default-role.ts`                                                      | دور افتراضي يتحكّم بما يمكن لدوال المنطق الوصول إليه.                                                        |
+| `src/constants/universal-identifiers.ts`                                   | معرّفات UUID وبيانات تعريف يتم توليدها تلقائيًا (اسم العرض، الوصف).                                          |
+| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | صفحة ترحيب مبدئية: مكوّن واجهة أمامية يتم تقديمه بواسطة مخطط صفحة مستقل، يمكن الوصول إليه من الشريط الجانبي. |
+| `src/__tests__/`                                                           | اختبار وحدة بالإضافة إلى اختبار تكامل (مع إعداده العام) يقوم بمزامنة التطبيق مع خادم حقيقي.                  |
+| `public/`                                                                  | أصول ثابتة (صور، خطوط) تُقدَّم مع تطبيقك.                                                                    |
+| `AGENTS.md` / `CLAUDE.md`                                                  | إرشادات لوكلاء برمجة الذكاء الاصطناعي الذين يعملون على التطبيق.                                              |
+| `CHANGELOG.md` / `SETUP.md`                                                | سجل بأبرز التغييرات وتعليمات الإعداد للتطوير المحلي.                                                         |
+
+<Note>
+**تنظيم الملفات متروك لك.** المجلدات المذكورة أعلاه هي أعراف متَّبعة — يكتشف SDK الكيانات عبر تحليل AST على استدعاءات `export default defineEntity(...)` بغض النظر عن مكان وجود الملف.
+</Note>
+
+## التبعيات
+
+ينبغي أن تكون حزمتا SDK الخاصتان بـ Twenty ضمن `devDependencies`، وليس ضمن `dependencies`:
+
+```json filename="package.json"
+{
+  "dependencies": {},
+  "devDependencies": {
+    "twenty-client-sdk": "2.20.0",
+    "twenty-sdk": "2.20.0",
+    "twenty-ui": "1.0.0-alpha.1"
+  }
+}
+```
+
+تقوم أداة إنشاء الهيكل بتثبيت الحزمتين `twenty-sdk` و `twenty-client-sdk` على إصدارها الخاص — حافظ على تزامنهما عند الترقية.
+
+* توفّر **`twenty-sdk`** أداة `twenty` CLI وأدوات البناء/إنشاء الهياكل (scaffolding). يعمل فقط أثناء التطوير ووقت البناء، ولا يتم استيراده أبدًا في وقت تشغيل تطبيقك المنشور.
+* يتم استيراد **`twenty-client-sdk`** بواسطة كود تطبيقك (`CoreApiClient`، `MetadataApiClient`، `RestApiClient`)؛ لكن Twenty توفّره في وقت التشغيل — حيث تحصل عليه دوال المنطق من طبقة SDK مُولَّدة، وتحصل عليه مكوّنات الواجهة من وحدات يتم تقديمها من الخادم. يُستخدَم الإصدار المثبّت لديك فقط لفحص الأنواع (typechecking) ولبناء النشر (deploy-time build)، لذا لا يلزم أبدًا أن يتم تضمينه في حزمة النشر.
+
+الاحتفاظ بأي من الحزمتين ضمن `dependencies` يؤدي إلى سحبها داخل حزمة وقت تشغيل التطبيق المثبّت، حيث تكون عبئًا زائدًا بلا فائدة. يُطلق `twenty dev:build` تحذيرًا عندما تكون أيٌّ منهما ما تزال مدرجة ضمن `dependencies`.
+
+أضِف تبعيات وقت التشغيل الخاصة بتطبيقك (المكتبات التي تستوردها دوال المنطق لديك فعلًا في وقت التشغيل) ضمن `dependencies` كالمعتاد. حافظ على الشجرة خفيفة: تُثبَّت `dependencies` في طبقة وقت التشغيل بحد أقصى 250MB بعد فك الضغط، وتفشل عملية المزامنة أو التثبيت بخطأ في حجم الاعتمادات عند تجاوز ذلك — تنتمي مكتبات واجهة المستخدم وأدوات التطوير إلى `devDependencies`.

packages/twenty-docs/l/ar/developers/extend/apps/getting-started/quick-start.mdx

@@ -0,0 +1,166 @@
+---
+title: البدء السريع
+icon: rocket
+description: أنشئ أول تطبيق Twenty خلال دقائق.
+---
+
+## المتطلبات الأساسية
+
+* **Node.js 24.5+** — [تنزيل](https://nodejs.org/)
+* **Yarn 4** — يأتي مع Node.js عبر Corepack. قم بتمكينه: `corepack enable`
+* **Docker** — [تنزيل](https://www.docker.com/products/docker-desktop/). مطلوب لتشغيل خادم Twenty محليًا. تخطَّ ذلك إذا كان لديك Twenty يعمل في مكان آخر.
+
+يتكوّن إنشاء تطبيق Twenty من ثلاث مراحل. تقوم أداة توليد الهيكل بدمجها في أمر واحد لمسار الاستخدام المثالي، لكن كل مرحلة تمثّل مفهومًا منفصلًا — وعند حدوث فشل، فإن معرفة المرحلة التي أنت فيها تُخبرك بما ينبغي إصلاحه.
+
+| المرحلة             | ماذا تفعل                          | الأداة                              | النتيجة                         |
+| ------------------- | ---------------------------------- | ----------------------------------- | ------------------------------- |
+| **1. تهيئة الهيكل** | توليد الشفرة المصدرية للتطبيق      | `npx create-twenty-app`             | مشروع TypeScript على القرص      |
+| **2. تشغيل خادم**   | بدء تشغيل خادم Twenty للمزامنة معه | Docker + `yarn twenty docker:start` | مثيل Twenty قيد التشغيل         |
+| **3. مزامنة**       | قم بمزامنة شفرتك مباشرةً مع الخادم | `yarn twenty dev`                   | تظهر تغييراتك في واجهة المستخدم |
+
+---
+
+## المرحلة 1 — تهيئة هيكل مشروعك
+
+أنشئ تطبيقًا جديدًا من القالب:
+
+```bash filename="Terminal"
+npx create-twenty-app@latest my-twenty-app
+```
+
+أداة التهيئة غير تفاعلية: يصبح اسم الدليل هو اسم التطبيق. مرِّر `--display-name` و`--description` لتخصيص البيانات الوصفية المُولَّدة (يمكنك أيضًا تعديلها لاحقًا في `src/constants/universal-identifiers.ts`). يُنشئ هذا مشروع TypeScript في `my-twenty-app/` يتضمّن ملف بداية `application-config.ts`، ودورًا افتراضيًا، وسير عمل CI/CD، واختبار تكامل.
+
+**بعد هذه المرحلة:** سيكون لديك الشفرة المصدرية لتطبيق على جهازك. ليس قيد التشغيل بعد — وهذه هي المرحلة 2.
+
+---
+
+## المرحلة 2 — تشغيل خادم Twenty محلي
+
+يحتاج تطبيقك إلى خادم Twenty للمزامنة معه. الخادم هو مثيل Twenty كامل — واجهة مستخدم، واجهة برمجة تطبيقات GraphQL، PostgreSQL — يعمل محليًا داخل Docker. ترفع شفرتك المحلية تعريفاتها إلى ذلك الخادم، مما يجعلها تظهر في واجهة المستخدم.
+
+يقوم مُنشئ الهياكل بتشغيل مثيل لك: مع تشغيل Docker، يسحب صورة `twentycrm/twenty-app-dev`، ويبدأها على المنفذ `2020`، ويُجري مصادقة أداة CLI على مساحة العمل التجريبية المهيأة مسبقًا (`tim@apple.dev`) — دون الحاجة إلى تسجيل الدخول.
+
+للاتصال بخادم Twenty موجود بدلاً من ذلك، مرِّر الخيار `--url \<your-server-url>`. تُجري الخوادم البعيدة المصادقة باستخدام OAuth: يفتح المتصفح حتى تتمكن من تسجيل الدخول والنقر على **Authorize**، مما يمنح أداة CLI حق الوصول إلى مساحة عملك. (يمكنك أيضًا اختيار استخدام OAuth محليًا باستخدام `--authentication-method oauth` — سجِّل الدخول باستخدام `tim@apple.dev` / `tim@apple.dev`.)
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/login.png" alt="شاشة تسجيل الدخول إلى Twenty" />
+</div>
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/authorize.png" alt="شاشة تفويض واجهة الأوامر (CLI) الخاصة بـ Twenty" />
+</div>
+
+ستؤكّد الطرفية أن كل شيء قد تم إعداده.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="تم إنشاء هيكل التطبيق بنجاح" />
+</div>
+
+**بعد هذه المرحلة:** لديك خادم Twenty قيد التشغيل على [http://localhost:2020](http://localhost:2020)، مع تفويض CLI لديك للمزامنة معه.
+
+<Note>
+إذا لم يكن Docker مثبتًا أو قيد التشغيل، فستخبرك أداة توليد الهيكل بأمر البدء المناسب لنظام التشغيل لديك. عند تشغيل Docker، يمكنك المتابعة باستخدام `yarn twenty docker:start` — لا حاجة لإعادة إنشاء الهيكل.
+</Note>
+
+---
+
+## المرحلة 3 — مزامنة تغييراتك
+
+هذه هي الحلقة الداخلية التي ستقضي معظم وقتك فيها.
+
+```bash filename="Terminal"
+cd my-twenty-app
+yarn twenty dev
+```
+
+يراقب هذا المجلد `src/`، ويُعيد البناء عند كل تغيير، ويزامن الناتج إلى الخادم. حرّر ملفًا، واحفظه، وخلال بضع ثوانٍ سينعكس التغيير على الخادم. سترى لوحة حالة مباشرة في الطرفية.
+
+للحصول على مخرجات أكثر تفصيلاً (سجلات البناء، طلبات المزامنة، تتبعات الأخطاء)، أضِف `--verbose`.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/dev.png" alt="مخرجات الطرفية في وضع التطوير" />
+</div>
+
+افتح [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). يفترض أن ترى تطبيقك ضمن **Your Apps**.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="قائمة &#x22;Your Apps&#x22; تعرض &#x22;My twenty app&#x22;" />
+</div>
+
+انقر **My twenty app** لعرض **تسجيل التطبيق** — وهو سجل على مستوى الخادم يصف تطبيقك (الاسم، المعرّف، بيانات اعتماد OAuth، المصدر). يمكن تثبيت تسجيل واحد عبر عدة مساحات عمل على الخادم نفسه.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="تفاصيل تسجيل التطبيق" />
+</div>
+
+انقر **View installed app** لعرض التثبيت في مساحة العمل. تعرض علامة التبويب **About** الإصدار وخيارات الإدارة.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="التطبيق المثبت" />
+</div>
+
+**بعد هذه المرحلة:** لديك دورة تطوير حيّة. حرّر أي ملف في `src/` وسيظهر في واجهة المستخدم.
+
+### مزامنة لمرة واحدة لـ CI والبرامج النصية
+
+استخدم `plan` و`apply` لتشغيل نفس خط الأنابيب مرة واحدة، بدون أداة مراقبة (watcher):
+
+```bash filename="Terminal"
+yarn twenty plan   # preview the metadata changes without applying them
+yarn twenty apply  # show the plan, then apply it
+```
+
+| أمر                 | السلوك                                                                                                                                   | متى يُستخدم                                                                 |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `yarn twenty dev`   | يراقب ويعيد المزامنة عند كل تغيير. يستمر في العمل حتى توقفه.                                                                             | تطوير محلي تفاعلي.                                                          |
+| `yarn twenty apply` | بناء واحد + مزامنة واحدة، يخرج برمز `0` عند النجاح، و`1` عند الفشل. يطلب تأكيدًا عند إجراء تغييرات مدمِّرة (مرِّر `--force` لتجاوز ذلك). | CI، وخطافات ما قبل الالتزام، ووكلاء الذكاء الاصطناعي، وسير عمل مكتوب بنصوص. |
+| `yarn twenty plan`  | يبني تغييرات البيانات الوصفية ويطبعها **من دون تطبيقها**.                                                                                | فحص ما الذي سيُغيِّره التزامن قبل تطبيقه.                                   |
+
+جميع الأوضاع تحتاج إلى جهة بعيدة موثَّقة. راجع قسم [المزامنة والاستعادة](/l/ar/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) للحصول على مزيد من المعلومات حول `plan`.
+
+<Note>
+الأوامر `yarn twenty dev --once` و`yarn twenty dev --once --dry-run` هي أسماء بديلة مهملة للأمرين `yarn twenty apply` و`yarn twenty plan`.
+</Note>
+
+### خيارات وضع التطوير
+
+| خيار                                  | الوصف                                                                                |
+| ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `--force`                             | تطبيق التغييرات المدمِّرة (الحذف) بدون تأكيد.                                        |
+| `--debounceMs \<ms>` | اضبط مهلة إزالة الارتداد لتغييرات الملفات بالميلي ثانية (القيمة الافتراضية: `1000`). |
+| `--verbose` / `--debug`               | إظهار سجلات إنشاء تفصيلية، وطلبات المزامنة، وتتبع الأخطاء.                           |
+
+## ما الذي يمكنك بناؤه
+
+تتكون التطبيقات من **كيانات** — يُعرَّف كل منها كملف TypeScript يحتوي على `export default` واحد:
+
+| كيان                   | ماذا يفعل                                                                                     |
+| ---------------------- | --------------------------------------------------------------------------------------------- |
+| **الكائنات والحقول**   | نماذج بيانات مخصّصة (بطاقة بريدية، فاتورة، إلخ) بحقول ذات أنواع محددة                         |
+| **الوظائف المنطقية**   | TypeScript على جانب الخادم يتم تشغيله عبر مسارات HTTP، أو جداول cron، أو أحداث قاعدة البيانات |
+| **المكوّنات الأمامية** | مكوّنات React تُعرَض داخل واجهة مستخدم Twenty (اللوحة الجانبية، الودجات، قائمة الأوامر)       |
+| **المهارات والوكلاء**  | قدرات الذكاء الاصطناعي — تعليمات قابلة لإعادة الاستخدام ومساعدون مستقلون ذاتيًا               |
+| **طرق العرض والتنقّل** | طرق عرض قوائم مُعدّة مسبقًا وعناصر قائمة الشريط الجانبي                                       |
+| **تخطيطات الصفحات**    | صفحات تفاصيل سجلات مخصصة تتضمن علامات تبويب وعناصر واجهة                                      |
+
+مرجع كامل: [المفاهيم](/l/ar/developers/extend/apps/getting-started/concepts).
+
+## الخطوات التالية
+
+<CardGroup cols={2}>
+  <Card title="التهيئة" icon="screwdriver-wrench" href="/l/ar/developers/extend/apps/config/overview">
+    هوية التطبيق، الدور الافتراضي، خطّافات التثبيت وإلغاء التثبيت، والأصول العامة.
+  </Card>
+  <Card title="بيانات" icon="database" href="/l/ar/developers/extend/apps/data/overview">
+    الكائنات، الحقول، والعلاقات ثنائية الاتجاه.
+  </Card>
+  <Card title="المنطق" icon="bolt" href="/l/ar/developers/extend/apps/logic/overview">
+    الوظائف المنطقية، المهارات، الوكلاء، واتصالات OAuth.
+  </Card>
+  <Card title="التخطيط" icon="table-columns" href="/l/ar/developers/extend/apps/layout/overview">
+    العروض، التنقل، تخطيطات الصفحات، ومكوّنات الواجهة الأمامية.
+  </Card>
+  <Card title="العمليات" icon="rocket" href="/l/ar/developers/extend/apps/operations/overview">
+    سطر الأوامر (CLI)، الاختبار، الوجهات البعيدة، التكامل المستمر (CI)، ونشر تطبيقك.
+  </Card>
+</CardGroup>

packages/twenty-docs/l/ar/developers/extend/apps/getting-started/scaffolding.mdx

@@ -0,0 +1,63 @@
+---
+title: إنشاء القوالب
+description: أنشئ ملفات الكيانات بشكل تفاعلي باستخدام yarn twenty dev:add — بما في ذلك الكائنات والحقول والعروض والدوال المنطقية والمزيد.
+icon: wand-magic-sparkles
+---
+
+بدلًا من إنشاء ملفات الكيانات يدويًا، استخدم أداة القوالب التفاعلية:
+
+```bash filename="Terminal"
+yarn twenty dev:add
+```
+
+ستطلب منك اختيار نوع الكيان وتُرشدك عبر الحقول المطلوبة، ثم تُنشئ ملفًا جاهزًا للاستخدام يحتوي على `universalIdentifier` ثابت واستدعاء `defineEntity()` الصحيح.
+
+يمكنك أيضًا تمرير نوع الكيان مباشرة لتخطي المطالبة الأولى:
+
+```bash filename="Terminal"
+yarn twenty dev:add object
+yarn twenty dev:add logicFunction
+yarn twenty dev:add frontComponent
+```
+
+## أنواع الكيانات المتاحة
+
+| نوع الكيان               | أمر                                        | الملف المُولَّد                                           |
+| ------------------------ | ------------------------------------------ | --------------------------------------------------------- |
+| كائن                     | `yarn twenty dev:add object`               | `src/objects/\<name>.ts`                 |
+| الحقل                    | `yarn twenty dev:add field`                | `src/fields/\<name>.ts`                  |
+| دالة منطقية              | `yarn twenty dev:add logicFunction`        | `src/logic-functions/\<name>.ts`         |
+| مكوّن أمامي              | `yarn twenty dev:add frontComponent`       | `src/front-components/\<name>.tsx`       |
+| دور                      | `yarn twenty dev:add role`                 | `src/roles/\<name>.ts`                   |
+| مهارة                    | `yarn twenty dev:add skill`                | `src/skills/\<name>.ts`                  |
+| وكيل                     | `yarn twenty dev:add agent`                | `src/agents/\<name>.ts`                  |
+| عرض                      | `yarn twenty dev:add view`                 | `src/views/\<name>.ts`                   |
+| عنصر قائمة التنقّل       | `yarn twenty dev:add navigationMenuItem`   | `src/navigation-menu-items/\<name>.ts`   |
+| تخطيط الصفحة             | `yarn twenty dev:add pageLayout`           | `src/page-layouts/\<name>.ts`            |
+| علامة تبويب تخطيط الصفحة | `yarn twenty dev:add pageLayoutTab`        | `src/page-layout-tabs/\<name>.ts`        |
+| عنصر قائمة الأوامر       | `yarn twenty dev:add commandMenuItem`      | `src/command-menu-items/\<name>.ts`      |
+| حقل العرض                | `yarn twenty dev:add viewField`            | `src/view-fields/\<name>.ts`             |
+| موفر الاتصال             | `yarn twenty dev:add connectionProvider`   | `src/connection-providers/\<name>.ts`    |
+| نوع نشاط الجدول الزمني   | `yarn twenty dev:add timelineActivityType` | `src/timeline-activity-types/\<name>.ts` |
+
+## ما الذي تُنشئه أداة القوالب
+
+لكل نوع كيان قالب خاص به. على سبيل المثال، يسأل `yarn twenty dev:add object` عن:
+
+1. **الاسم (مفرد)** — مثل `invoice`
+2. **الاسم (جمع)** — مثل `invoices`
+3. **التسمية (مفرد)** — تُستمد تلقائيًا من الاسم (مثل `Invoice`)
+4. **التسمية (جمع)** — تُملأ تلقائيًا (مثل `Invoices`)
+5. **إنشاء عرض وعنصر تنقّل؟** — إذا أجبت بنعم، فستُنشئ أداة القوالب أيضًا عرضًا مطابقًا ورابط شريط جانبي للكائن الجديد.
+
+أنواع الكيانات الأخرى لها مطالبات أبسط — فمعظمها يطلب اسمًا فقط.
+
+نوع الكيان `field` أكثر تفصيلاً: يطلب اسم الحقل وتسمية الحقل ونوعه (من قائمة بكل أنواع الحقول المتاحة مثل `TEXT` و`NUMBER` و`SELECT` و`RELATION` وغيرها)، ومعرّف `universalIdentifier` للكائن الهدف.
+
+## مسار خرج مخصّص
+
+استخدم العلم `--path` لوضع الملف المُولَّد في موقع مخصّص:
+
+```bash filename="Terminal"
+yarn twenty dev:add logicFunction --path src/custom-folder
+```

packages/twenty-docs/l/ar/developers/extend/apps/getting-started/troubleshooting.mdx

@@ -0,0 +1,14 @@
+---
+title: استكشاف الأخطاء وإصلاحها
+description: مشكلات التشغيل الأول الشائعة — Docker، إصدار Node، Yarn، والتبعيات.
+icon: wrench
+---
+
+* **أخطاء Docker** — تأكّد من أن Docker Desktop (أو الـ daemon) قيد التشغيل قبل `yarn twenty docker:start`. ستعرض رسالة الخطأ أمر البدء المناسب لنظام التشغيل لديك.
+* **إصدار Node غير صحيح** — تحتاج إلى 24.5+ (`engines.node: ^24.5.0`). تحقّق باستخدام `node -v`.
+* **Yarn 4 غير موجود** — شغّل `corepack enable`.
+* **تبعيات تالفة** — `rm -rf node_modules && yarn install`.
+* **أخطاء `twenty-sdk` بعد الترقية إلى v2.8.0** — تم نقله من `dependencies` إلى `devDependencies` في الإصدار v2.8.0. انظر إلى [بنية المشروع → التبعيات](/l/ar/developers/extend/apps/getting-started/project-structure#dependencies).
+* **`twenty dev:build` يُصدر تحذيرًا بشأن `twenty-client-sdk` تحت `dependencies`** — يتم توفيره في وقت التشغيل بواسطة Twenty، لذلك يجب نقله إلى `devDependencies` جنبًا إلى جنب مع `twenty-sdk`. انظر إلى [بنية المشروع → التبعيات](/l/ar/developers/extend/apps/getting-started/project-structure#dependencies).
+
+هل علِقت؟ اطلب المساعدة على [خادم Twenty على Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).