@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,142 @@
+---
+title: "FAQ"
+description: "الأسئلة الشائعة حول Agent-Native - ما هو، ومن هو، وما الذي يمكنك إنشاؤه، وكيف يعمل."
+---
+
+# FAQ
+
+الأسئلة الشائعة حول الوكيل الأصلي، منظمة من "أنا أبحث فقط" إلى "أقوم بتوصيل المصادقة الآن."
+
+## الأساسيات {#general}
+
+### ما هو الوكيل الأصلي؟ {#what-is-agent-native}
+
+Agent-native هو إطار عمل لبناء التطبيقات حيث يكون وكيل الذكاء الاصطناعي وسطح المنتج المحيط به شريكين متساويين. يمكن أن يبدأ هذا السطح كعميل بلا رأس بإجراء مخصص واحد، أو ينمو ليصبح دردشة غنية، أو يصبح UI كاملاً. الثابت هو أن الوكلاء والبشر يتشاركون نفس actions وقاعدة البيانات والحالة. راجع [What Is Agent-Native?](/docs/what-is-agent-native) للحصول على الشرح الكامل.
+
+### لمن هذا؟ {#who-is-this-for}
+
+Agent-native مخصص للأشخاص الذين يريدون تطبيقًا حقيقيًا ووكيل AI للعمل من نفس البيانات وactions. المسارات الشائعة هي:
+
+- **استخدم تطبيقًا مستضافًا** إذا كنت تريد البريد أو التقويم أو النماذج أو الخطة أو أي قالب نهائي آخر بدون إعداد - ابدأ من [template gallery](/templates).
+- **ابدأ بالدردشة** إذا كنت تريد تطبيقًا أساسيًا يمكن للمستخدمين التحدث إليه على الفور، ثم قم بتوسيع نطاقه إلى actions والشاشات - ابدأ بـ [Getting Started](/docs/getting-started) أو [Chat](/docs/template-chat).
+- **ابدأ بـ primitive-first** إذا كنت تريد إجراءً واحدًا وحلقة وكيل تطبيق بدون رأس قبل الالتزام بـ UI - ابدأ بـ [Getting Started](/docs/getting-started).
+- **تفرع القالب وتخصيصه** إذا كنت تريد توصيل منتج SaaS الخاص بك بالمصادقة وقاعدة البيانات وUI والوكيل actions بالفعل - راجع [Templates](/docs/cloneable-saas).
+- **الإنشاء من الصفر** إذا كنت تريد أساسيات إطار العمل لمنتج جديد يستند إلى الوكيل - فابدأ بـ [Getting Started](/docs/getting-started).
+- **قم بتوصيل وكيل آخر أو أداة تعليمات برمجية أخرى** إذا كنت تريد أن يستخدم Claude أو ChatGPT أو Codex أو Cursor أو GitHub Copilot / VS Code تطبيقًا أصليًا للوكيل - راجع [External Agents](/docs/external-agents) و[Skills Guide](/docs/skills-guide).
+
+### كيف يختلف هذا عن إضافة الذكاء الاصطناعي إلى تطبيق موجود؟ {#how-is-this-different}
+
+تعمل معظم التطبيقات على تشغيل الذكاء الاصطناعي كفكرة لاحقة لا يمكنها في الواقع القيام بأشياء في التطبيق. في تطبيق الوكيل الأصلي، يكون الوكيل مواطنًا من الدرجة الأولى يشترك في نفس actions وقاعدة البيانات والحالة مثل UI، لذا يمكنه فعل أي شيء يمكن أن تفعله الأزرار - وتعديل التعليمات البرمجية الخاصة بالتطبيق. انظر [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder).
+
+```an-diagram title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI."
+{
+  "html": "<div class=\"diagram-vs\"><div class=\"diagram-col\"><span class=\"diagram-pill warn\">Bolted-on AI</span><div class=\"diagram-node\">Chat sidebar</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>separate AI world<br><small class=\"diagram-muted\">can't touch the app</small></div><div class=\"diagram-box diagram-muted\">App UI &amp; data</div></div><div class=\"diagram-divider\" aria-hidden=\"true\"></div><div class=\"diagram-col\"><span class=\"diagram-pill ok\">Agent-native</span><div class=\"diagram-row2\"><div class=\"diagram-node\">UI</div><div class=\"diagram-node\">Agent</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>shared actions, DB &amp; state</div></div></div>",
+  "css": ".diagram-vs{display:flex;align-items:stretch;gap:18px;flex-wrap:wrap}.diagram-vs .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:center;flex:1;min-width:200px}.diagram-vs .diagram-row2{display:flex;gap:8px}.diagram-vs .diagram-arrow{font-size:20px;line-height:1}.diagram-vs .diagram-divider{width:1px;align-self:stretch;background:currentColor;opacity:.15}"
+}
+```
+
+### هل هو مفتوح المصدر؟ {#is-this-open-source}
+
+نعم. الإطار وجميع القوالب مفتوحة المصدر. يمكنك تشغيل كل شيء محليًا، أو الاستضافة الذاتية، أو استخدام سحابة Builder.io للاستضافة المُدارة والتعاون وميزات الفريق.
+
+### كم تبلغ التكلفة؟ {#how-much}
+
+إطار العمل نفسه مجاني. التكاليف التي ستراها عمليًا:
+
+- **استخدام الذكاء الاصطناعي.** يمكنك إحضار مفتاح API الخاص بك (Anthropic، OpenAI، وما إلى ذلك) والدفع لموفر النموذج مباشرة. ليس هناك أي ترميز من جانبنا.
+- **الاستضافة.** أيًا كان ما يتقاضاه مضيفك. تعمل معظم القوالب بشكل جيد على المستويات المجانية (Netlify وVercel وCloudflare) لأحمال العمل الصغيرة.
+
+إذا كنت تفضل عدم إدارة أي من هذا، فإن الإصدار المستضاف على `agent-native.com` (الذي يديره Builder.io) يجمع الاستدلال والاستضافة في خطة لكل مقعد.
+
+### هل يمكنني استضافة هذا بنفسي؟ {#can-i-self-host}
+
+نعم. اختر أي مضيف يقوم بتشغيل Node - Netlify، وVercel، وCloudflare، وAWS، وDeno Deploy، والخادم الخاص بك - وأي قاعدة بيانات SQL (Postgres، SQLite، Turso، D1). تم تصميم الإطار ليكون محمولاً. انظر [Deployment](/docs/deployment).
+
+### ما هي نماذج الذكاء الاصطناعي التي يدعمها؟ {#what-models}
+
+Anthropic Claude وOpenAI (عائلة GPT-5) وGoogle Gemini وأي مزود يتحدث شكل OpenAI API (بما في ذلك النماذج المحلية عبر Ollama). يمكنك تكوين النموذج في الإعدادات؛ التبديل هو تغيير في التكوين، وليس إعادة كتابة التعليمات البرمجية. المسار الأكثر اختبارًا لإطار العمل هو Claude، لذا فهذه هي التوصية الافتراضية.
+
+### هل أحتاج إلى معرفة الذكاء الاصطناعي/تعلم الآلة؟ {#do-i-need-to-know-ai}
+
+لا. أنت لا تقوم بتدريب النماذج، أو الضبط الدقيق، أو التعامل مع التضمينات. أنت تنشئ تطبيق ويب عاديًا - وفي الإصدار المستضاف، بالكاد تنشئ أي شيء على الإطلاق. يعالج إطار العمل تكامل الوكيل: توجيه الرسائل، تشغيل actions، حالة المزامنة.
+
+### هل يمكنني ترحيل تطبيق موجود إلى الوكيل الأصلي؟ {#can-i-use-existing-code}
+
+يمكنك ذلك، ولكن الوكيل الأصلي يعمل بشكل أفضل عند إنشائه من الألف إلى الياء. يجب أن تكون البنية - قاعدة البيانات المشتركة، ومزامنة الاستقصاء، وactions، وحالة التطبيق - متكاملة طوال الوقت. البدء من القالب وتخصيصه هو المسار الموصى به. فكر في الأمر مثل التحول من سطح المكتب أولاً إلى الهاتف المحمول أولاً: يمكنك التعديل التحديثي، ولكن إنشاء المحتوى الأصلي هو الأفضل.
+
+## النماذج وما يمكنك إنشاؤه {#templates}
+
+### ما هي النماذج المتاحة؟ {#what-templates-are-available}
+
+يأتي إطار العمل مع قوالب جاهزة للإنتاج بما في ذلك [Chat](/docs/template-chat)، و[Mail](/docs/template-mail)، و[Calendar](/docs/template-calendar)، و[Forms](/docs/template-forms)، و[Plan](/docs/template-plan) (الخطط المرئية وملخصات العلاقات العامة)، و[Analytics](/docs/template-analytics)، و[Dispatch](/docs/template-dispatch)، والمزيد. كل منها عبارة عن تطبيق كامل مع UI والوكيل actions ومخطط قاعدة البيانات وتعليمات الذكاء الاصطناعي الجاهزة للاستخدام. راجع [Templates](/docs/cloneable-saas) للحصول على الكتالوج الكامل.
+
+### هل يمكنني تخصيص النماذج؟ {#can-i-customize-templates}
+
+هذا هو بيت القصيد. قم بتفرع القالب وتخصيصه عن طريق سؤال الوكيل. "إضافة حقل أولوية إلى النماذج." "الاتصال بمثيل Salesforce الخاص بنا." "قم بتغيير نظام الألوان ليتناسب مع علامتنا التجارية." يقوم الوكيل بتعديل الرمز، ويتطور تطبيقك بمرور الوقت.
+
+### هل يمكنني إنشاء شيء لا تغطيه النماذج؟ {#build-from-scratch}
+
+نعم. إذا كنت تريد تطبيقًا أساسيًا للدردشة، فقم بتشغيل `npx @agent-native/core@latest create my-chat-app --template chat`؛ يمكنك الحصول على سلاسل محادثات متينة، وactions، والمصادقة، وحالة وقت التشغيل المدعومة بـ SQL، ومساحة لإضافة شاشاتك الخاصة. إذا كنت تريد أصغر تطبيق للإجراء أولاً بدون UI، فقم بتشغيل `npx @agent-native/core@latest create my-agent --headless`. راجع [Getting Started](/docs/getting-started)، و[Pure-Agent Apps](/docs/pure-agent-apps)، و[Chat](/docs/template-chat).
+
+### هل يمكنني تجربته بدون تفرع القالب؟ {#try-with-a-skill}
+
+نعم - قم بتثبيت مهارة في وكيل الترميز الذي تستخدمه بالفعل بأمر واحد دون الحاجة إلى أي دعم. راجع [Skills Guide](/docs/skills-guide#app-backed-skills) للاطلاع على الإرشادات التفصيلية.
+
+## قدرات الوكيل {#agent-capabilities}
+
+### هل يستطيع الوكيل تعديل كود التطبيق حقًا؟ {#can-the-agent-modify-code}
+
+نعم، وهي ميزة. يمكن للوكيل تحرير المكونات والمسارات والأنماط وactions بأمان. أنت تطلب "إضافة مخطط تحليل جماعي" ويقوم الوكيل بإنشائه. أنت تطلب "الاتصال بحساب Stripe الخاص بنا" ويقوم الوكيل بكتابة عملية التكامل. كل شيء هو عبارة عن تعليمات برمجية عادية يتم تتبعها بواسطة Git، لذا من السهل التراجع عن التغييرات السيئة.
+
+### هل يمكن للمستخدمين التحدث إلى الوكيل من خارج التطبيق؟ {#external-channels}
+
+نعم. يعمل نفس الوكيل في UI على الويب الخاص بك، وفي Slack، وفي Telegram، عبر البريد الإلكتروني، ومن وكلاء آخرين (عبر [A2A](/docs/a2a-protocol)). إنه نفس الوكيل بنفس الذاكرة ونفس actions، تم الوصول إليه للتو من خلال قنوات مختلفة. انظر [Messaging the agent](/docs/messaging).
+
+### هل يمكن للوكلاء التحدث مع بعضهم البعض؟ {#can-agents-talk-to-each-other}
+
+نعم، عبر [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). يحصل كل تطبيق أصلي للوكيل تلقائيًا على نقطة نهاية A2A. من تطبيق البريد، يمكنك وضع علامة على وكيل التحليلات للاستعلام عن البيانات. يكتشف الوكيل ما هو الوكلاء الآخرون المتاحون، ويستدعيهم عبر البروتوكول، ويعرض النتائج في UI. ليست هناك حاجة إلى تكوين — يتم إنشاء بطاقة الوكيل تلقائيًا من actions الخاص بنموذجك.
+
+### ما الذي يمكن للوكيل رؤيته في التطبيق؟ {#what-can-the-agent-see}
+
+يعرف الوكيل دائمًا ما يشاهده المستخدم حاليًا. يكتب UI حالة التنقل إلى قاعدة البيانات عند كل تغيير للمسار - أي طريقة عرض مفتوحة، وأي عنصر محدد. يقرأ الوكيل هذا قبل اتخاذ الإجراء. إذا كان البريد الإلكتروني مفتوحًا، فسيعرف الوكيل أي بريد إلكتروني. إذا تم تحديد شريحة، يعرف الوكيل أي شريحة. انظر [Context Awareness](/docs/context-awareness).
+
+## أسئلة التطوير {#development}
+
+### ما هي أدوات ترميز الذكاء الاصطناعي التي تعمل مع الوكيل الأصلي؟ {#which-ai-tools-work}
+
+أي أداة ترميز تعمل بالذكاء الاصطناعي تقرأ تعليمات المشروع. يستخدم إطار العمل AGENTS.md كمعيار عالمي ويقوم تلقائيًا بإنشاء روابط رمزية لأدوات محددة:
+
+- **رمز Claude** — يقرأ CLAUDE.md (مرتبط بـ AGENTS.md بواسطة إعداد CLI)
+- **المؤشر** — يقرأ AGENTS.md مباشرة، أو `.cursorrules` (الموقع القديم للمؤشر) إذا كان موجودًا في مشروعك
+- **Windsurf** — يقرأ .windsurfrules (مرتبط بـ AGENTS.md بواسطة إعداد CLI)
+- **Codex وGemini وآخرون** — يعملون عبر لوحة الوكلاء المضمنة
+- **Builder.io** — وكيل مستضاف على السحابة مع إمكانية التحرير المرئي والتعاون
+
+### هل يمكنني استخدام قاعدة البيانات الخاصة بي؟ {#can-i-use-my-own-database}
+
+نعم. قم بتعيين `DATABASE_URL` وسيكتشفه الإطار تلقائيًا. تتضمن قواعد البيانات المدعومة SQLite، وPostgres (Neon، وSupabase، وplain)، وTurso (libSQL)، وCloudflare D1. كل SQL لا تعرف لهجة من خلال Drizzle ORM — نفس الرمز يعمل في كل مكان.
+
+### أين يمكنني النشر؟ {#where-can-i-deploy}
+
+في أي مكان. يعمل الخادم على Nitro، والذي يتم تجميعه لأي هدف نشر: Node.js، وCloudflare Workers/Pages، وNetlify، وVercel، وDeno Deploy، وAWS Lambda، وBun. يمكنك أيضًا استخدام استضافة Builder.io لعمليات النشر المُدارة. انظر [Deployment guide](/docs/deployment).
+
+## الهندسة المعمارية {#architecture}
+
+### لماذا SSE بالإضافة إلى الاقتراع بدلاً من WebSockets؟ {#why-polling-not-websockets}
+
+يوفر SSE نفس العملية لكتابة مسار فوري للمتصفح، ويظل استطلاع عداد الإصدار خفيف الوزن هو البديل لأنه يعمل في كل بيئة نشر - بما في ذلك بيئة بدون خادم وبيئة الحافة، حيث قد لا تكون المقابس الدائمة متاحة. انظر [Key Concepts — Live sync](/docs/key-concepts#polling-sync).
+
+```an-diagram title="SSE first, polling fallback" summary="Same-process writes stream instantly; a version-counter poll keeps serverless, edge, and cross-process writes convergent."
+{
+  "html": "<div class=\"diagram-transport\"><div class=\"diagram-box\" data-rough>DB write</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">SSE<br><small class=\"diagram-muted\">/_agent-native/events &middot; instant</small></div><div class=\"diagram-node\">Poll<br><small class=\"diagram-muted\">/_agent-native/poll &middot; universal fallback</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Browser refetch</div></div>",
+  "css": ".diagram-transport{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-transport .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-transport .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+### لماذا لا يستطيع UI الاتصال بـ LLM مباشرة؟ {#why-no-inline-llm-calls}
+
+الذكاء الاصطناعي غير حتمي، لذلك تحتاج إلى تدفق المحادثة لتقديم التعليقات والتكرار - وليس أزرار طلقة واحدة - ويمتلك الوكيل بالفعل قاعدة التعليمات البرمجية والتعليمات وskills والسجل الذي تفتقر إليه المكالمة المضمنة. إن توجيه كل شيء عبر الوكيل هو أيضًا ما يتيح تشغيل التطبيق من Slack أو Telegram أو وكيل آخر. انظر [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge).
+
+### لماذا هذا إطار عمل وليس مكتبة؟ {#why-framework-not-library}
+
+تعمل قاعدة البيانات المشتركة والمزامنة المباشرة ونظام actions وحالة التطبيق فقط لأنها متصلة معًا من الألف إلى الياء — يتفاعل UI مع تغييرات الوكيل على الفور، ويتواصل الوكلاء، ويفهم الوكيل ما يبحث عنه المستخدم. مكتبة تمنحك قطعًا؛ هذه هي الهندسة المعمارية. انظر [Key Concepts](/docs/key-concepts).

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

@@ -0,0 +1,122 @@
+---
+title: "تحميل الملفات"
+description: "قم بتكوين مساحة تخزين تحميل الملفات — احتياطي SQL للمطورين، أو Builder.io أو موفري الخدمة المخصصين للإنتاج."
+---
+
+# تحميلات الملفات
+
+يوفر إطار العمل تجريدًا لتحميل الملفات والذي يقوم بتوجيه التحميلات من خلال موفر قابل للتكوين. تستدعي القوالب `uploadFile()` وتستعيد URL — واجهة التخزين الخلفية قابلة للتبديل دون تغيير رمز التطبيق.
+
+## كيفية العمل {#how-it-works}
+
+تنتقل طلبات التحميل إلى `POST /_agent-native/file-upload`، والتي ترسلها إلى الموفر النشط. يمكنك التحقق من الموفر الذي تم تكوينه في `GET /_agent-native/file-upload/status`.
+
+ترتيب حل الموفر هو:
+
+1. **الموفرون المسجلون بواسطة المستخدم** — مقدمو الخدمة المخصصون المسجلون عبر `registerFileUploadProvider()`
+2. **موفر Builder.io** — مدمج، يتم تنشيطه تلقائيًا عند اتصال Builder.io
+3. **الاحتياطي SQL** — يخزن الملفات بتنسيق base64 في قاعدة البيانات (مناسب للتطوير، وليس للإنتاج)
+
+```an-diagram title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. The SQL fallback always exists so uploads work with zero setup."
+{
+  "html": "<div class=\"diagram-upload\"><div class=\"diagram-box\" data-rough>uploadFile()<br><small class=\"diagram-muted\">POST /_agent-native/file-upload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-step\"><span class=\"diagram-pill accent\">1</span><div class=\"diagram-node\">User-registered<br><small class=\"diagram-muted\">registerFileUploadProvider() — S3, R2, GCS…</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><div class=\"diagram-node\">Builder.io<br><small class=\"diagram-muted\">auto when connected — CDN-served</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill warn\">3</span><div class=\"diagram-node\">SQL fallback<br><small class=\"diagram-muted\">base64 in DB — dev only</small></div></div></div></div>",
+  "css": ".diagram-upload{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-upload .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-upload .diagram-step{display:flex;align-items:center;gap:8px}.diagram-upload .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The upload endpoint" method="POST" path="/_agent-native/file-upload"
+{
+  "method": "POST",
+  "path": "/_agent-native/file-upload",
+  "summary": "Upload a file through the active provider and get back a public URL.",
+  "description": "Dispatches to the first configured provider in resolution order. Check the active provider at `GET /_agent-native/file-upload/status`.",
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "{ url, id?, provider } — the public URL and which provider handled it." }
+  ]
+}
+```
+
+## الافتراضي: SQL الاحتياطي {#sql-fallback}
+
+عند عدم تكوين أي موفر، يتم تخزين الملفات كبيانات base64 في قاعدة بيانات SQL عبر نظام الموارد. يعمل هذا بشكل خارج الصندوق للتطوير المحلي ولكن لا يوصى به للإنتاج - فالملفات الكبيرة تؤدي إلى تضخم قاعدة البيانات ولا يوجد CDN.
+
+يتم تسجيل تحذير لمرة واحدة عند استخدام الإجراء الاحتياطي.
+
+## استضافة Builder.io {#builder-hosting}
+
+عندما يكون تطبيقك متصلاً بـ Builder.io، يتم توجيه تحميلات الملفات تلقائيًا إلى استضافة أصول Builder. يتم تقديم الملفات من CDN دون الحاجة إلى تكوين. هذا هو إعداد الإنتاج الموصى به.
+
+## موفرو الخدمة المخصصون {#custom-providers}
+
+قم بتسجيل موفر مخصص في مكون إضافي للخادم لاستخدام أي واجهة تخزين خلفية (S3، Cloudflare R2، GCS، وما إلى ذلك):
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## تحميل API {#upload-api}
+
+واجهة `FileUploadProvider`:
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+استخدم `uploadFile()` من `@agent-native/core/file-upload` في actions أو رمز الخادم:
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL fallback yourself, or skip
+}
+```

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

@@ -0,0 +1,153 @@
+---
+title: "الإطارات"
+description: "إطار التطوير المحلي، ولوحة الوكيل المضمنة، والإطار السحابي - الطرق التي يعمل بها وكيل الذكاء الاصطناعي جنبًا إلى جنب مع تطبيقك."
+---
+
+# الإطارات
+
+يتم تشغيل كل تطبيق أصلي للوكيل مع وكيل AI بجوار التطبيق UI. **الإطار** هو
+المجمّع الذي يستضيف كليهما: فهو يعرض تطبيقك ويمنح الوكيل مكانًا
+الدردشة والتشغيل وتحرير التعليمات البرمجية (في التطوير). هناك ثلاثة إطارات، تتشارك في وقت تشغيل واحد:
+
+- **لوحة الوكيل المضمنة** — يتم تضمينها داخل كل تطبيق من `@agent-native/core`.
+  هذا هو الشريط الجانبي الذي يعرضه تطبيقك بنفسه، أثناء التطوير والإنتاج.
+- **إطار التطوير المحلي** — غلاف رفيع يقوم بتحميل تطبيقك قيد التشغيل في إطار iframe
+  ويضيف نفس لوحة الوكيل بالإضافة إلى محطة CLI المدمجة بجانبها. مستخدم
+  للتطوير المحلي للقوالب في هذا الريبو.
+- **إطار سحابي Builder.io** — إطار مُدار ومستضاف بالتعاون،
+  التحرير المرئي وتشغيل الوكيل الموازي.
+
+رمز تطبيقك متطابق بغض النظر عن الإطار الذي يستضيفه. يتحدث الوكيل
+إلى تطبيقك من خلال نفس actions وحالة التطبيق في كل حالة.
+
+```an-diagram title="Three frames, one runtime" summary="Your app and the agent panel are the same in every frame; only the wrapper around them changes."
+{
+  "html": "<div class=\"diagram-frames\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Embedded panel</span><small class=\"diagram-muted\">ships in every app · dev + prod</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Local dev frame</span><small class=\"diagram-muted\">app in an iframe + panel + CLI terminal</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Builder.io cloud frame</span><small class=\"diagram-muted\">hosted: collaboration · visual edit · parallel runs</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Same runtime<br><small class=\"diagram-muted\">your app · actions · application state</small></div></div>",
+  "css": ".diagram-frames{display:flex;flex-direction:column;gap:10px;align-items:stretch}.diagram-frames .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-frames .diagram-arrow{font-size:22px;line-height:1;align-self:center}"
+}
+```
+
+## لوحة الوكيل المضمنة {#embedded-agent}
+
+اللوحة المضمنة هي الشريط الجانبي للوكيل الذي يعرضه تطبيقك. يأتي مع
+`@agent-native/core` - لا توجد حزمة منفصلة لتثبيتها - وهي نفسها
+مكون في التطوير والإنتاج.
+
+- تم التصدير بتنسيق `AgentPanel` من `@agent-native/core/client`، مع
+  متغير الإنتاج فقط `ProductionAgentPanel`.
+- يوفر سطح الدردشة / CLI / مساحة العمل الكامل، بحيث يظل إدخال الوكيل قيد التشغيل
+  مكدس الملحن المشترك المستخدم في أي مكان آخر في إطار العمل.
+- يقرأ `application_state.navigation` في كل دورة، لذا فهو يعرف بالفعل أي منها
+  العرض الذي تتواجد فيه والأشياء المحددة - لا يتعين عليك إعادة شرح "هذا".
+
+### أوضاع أداة التطبيق مقابل الكود {#tool-modes}
+
+تعمل اللوحة في أحد وضعي الأداة:
+
+- **وضع التطبيق** — يمتلك الوكيل فقط الأدوات الخاصة بتطبيقك: actions أنت
+  محدد باستخدام `defineAction`، بالإضافة إلى التنقل والسياق. لا يوجد نظام ملفات أو
+  الوصول إلى الصدفة. وهذا ما يحصل عليه المستخدمون النهائيون.
+- **وضع الكود** — يضيف أدوات الترميز المشتركة (`bash`، `read`، `edit`، `write`)
+  والوصول إلى قاعدة البيانات أعلى أدوات التطبيق، حتى يتمكن الوكيل من تغيير التطبيق
+  المصدر الخاص. تكون طلبات التعليمات البرمجية محظورة: عندما تتطلب الرسالة رمزًا
+  (`type: "code"`) ولم يتم توصيل أي إطار قادر على تشغيل التعليمات البرمجية، تعرض اللوحة
+  مربع حوار يوضح أن تغييرات التعليمات البرمجية تحتاج إلى Agent Native Desktop أو Builder؛
+  عندما يكون الإطار متصلاً، يتم توجيه الطلب إليه وإلى وكيل التعليمات البرمجية
+  يظهر المؤشر أثناء عمله (`useSendToAgentChat`). بالنسبة للملف الأساسي
+  قائمة أدوات الترميز وعقود UI المشتركة، راجع
+  [Agent-Native Code UI](/docs/code-agents-ui).
+
+```an-diagram title="Code-request gating" summary="A code-typed message needs a code-capable frame. With one connected, the request routes there; without one, the panel explains code changes need Desktop or Builder."
+{
+  "html": "<div class=\"diagram-gate\"><div class=\"diagram-node\" data-rough>message<br><small class=\"diagram-muted\">type: \\\"code\\\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>code-capable frame connected?</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">yes &rarr; route to frame, show code-agent indicator</div><div class=\"diagram-pill warn\">no &rarr; dialog: needs Desktop or Builder</div></div></div>",
+  "css": ".diagram-gate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-gate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-gate .diagram-arrow{font-size:22px;line-height:1}.diagram-gate .center{text-align:center}"
+}
+```
+
+"وضع التعليمات البرمجية" هو تبديل قدرة الوكيل - وهو يختلف عن وضع مطور البيئة
+(`NODE_ENV` / Vite). ربط العميل هو `useCodeMode()`. (انظر
+[Compatibility notes](#compatibility) للأسماء المستعارة المتوافقة مع الخلف.)
+
+في إطار التطوير المحلي، يقوم ترس الإعدادات بالتبديل بين هذه الأوضاع. التبديل
+يُخفي وضع Code off الشريط الجانبي الخاص بالإطار ويعرض وكيل التطبيق داخل التطبيق
+الشريط الجانبي داخل إطار iframe بدلاً من ذلك، حتى تتمكن من معاينة ما يراه المستخدمون بالضبط.
+
+## محطة متكاملة وتبديل CLI {#cli-terminal}
+
+تتضمن اللوحة قيد التطوير محطة طرفية مضمنة (`AgentTerminal`، أيضًا
+من `@agent-native/core/client`) مدعومًا بخادم PTY. يمكنك تشغيل
+ترميز CLI بجوار التطبيق مباشرةً والتبديل بينهما؛ تتم إعادة تشغيل الجهاز
+باستخدام CLI المحدد.
+
+تأتي CLI المدعومة من سجل CLI الأساسي
+(`packages/core/src/terminal/cli-registry.ts`). يُسمح فقط بهذه الأوامر
+للنشر - يتحقق خادم PTY من صحة الأمر المطلوب مقابل السجل
+القائمة المسموح بها لمنع الحقن:
+
+| CLI           | الأمر      | تثبيت الحزمة                |
+| ------------- | ---------- | --------------------------- |
+| رمز Claude    | `claude`   | `@anthropic-ai/claude-code` |
+| Builder.io    | `builder`  | (مدمج)                      |
+| Codex         | `codex`    | `@openai/codex`             |
+| الجوزاء CLI   | `gemini`   | `@google/gemini-cli`        |
+| الرمز المفتوح | `opencode` | `opencode-ai`               |
+
+إذا لم يتم العثور على CLI المحدد في `PATH`، فستعود الوحدة الطرفية إلى تشغيلها
+من خلال `npx --yes <install-package>@latest` (حيث توجد حزمة التثبيت). ال
+الأمر الافتراضي هو `claude`. قم بتبديل CLIs من إعدادات لوحة الوكيل في أي
+الوقت.
+
+## إطار سحابي Builder.io {#cloud-frame}
+
+يوفر [Builder.io](https://www.builder.io) إطارًا مُدارًا يستضيف
+نفس التطبيق ونفس لوحة الوكيل، في السحابة:
+
+- التعاون في الوقت الفعلي — يمكن لعدة مستخدمين المشاهدة والتفاعل في الوقت نفسه.
+- التحرير المرئي والأدوار والأذونات.
+- تنفيذ الوكيل الموازي لتكرار أسرع.
+- مناسب للاستخدام الجماعي، حيث يتشارك الجميع في بيئة مستضافة واحدة.
+
+طلبات التعليمات البرمجية من مسار اللوحة المضمنة إلى إطار Builder بنفس الطريقة
+إنهم يوجهون إلى إطار التطوير المحلي، لذا فإن سلوك dev-vs-prod أعلاه هو
+متسق في كليهما.
+
+## وقت التشغيل APIs {#runtime-apis}
+
+تأتي هذه العناصر مع `@agent-native/core` وهي ما يستخدمه تطبيقك للتحدث مع
+الوكيل، بغض النظر عن الإطار الذي يستضيفه:
+
+1. **إرسال رسالة** — يرسل `sendToAgentChat()` رسالة إلى الوكيل. ال
+   يغلفه خطاف `useSendToAgentChat()` ببوابة طلب الكود الموصوفة
+   أعلاه ويعيد عنصر `codeRequiredDialog` لعرضه. انظر
+   [Drop-in Agent](/docs/drop-in-agent) للاستخدام الكامل والخيارات.
+2. **حالة الجيل** — يتتبع `useAgentChatGenerating()` وقت وجود الوكيل
+   قيد التشغيل، لذا يمكن لـ UI إظهار التقدم دون استقصاء الوكيل مباشرةً.
+3. **مزامنة الاستقصاء** — تحافظ المزامنة المدعومة بقاعدة البيانات على ذاكرات التخزين المؤقت UI محدثة عندما يكون الوكيل
+   يغير البيانات أو حالة التطبيق.
+4. **نظام العمل** — يرسل `pnpm action <name>` إلى نفس الشخص القابل للاستدعاء
+   actions يستدعي الوكيل كأدوات، لذا يمكنك القيام بأي شيء يمكن للوكيل القيام به
+   النص البرمجي.
+
+## تشغيله {#running}
+
+تعد لوحة الوكيل المضمنة جزءًا من كل تطبيق - قم ببناء قالب وهي
+هناك بالفعل:
+
+```bash
+npx @agent-native/core@latest create my-app --template mail --standalone
+cd my-app
+pnpm dev
+```
+
+إطار التطوير المحلي (حزمة `@agent-native/frame` الخاصة في مستودع الإطار) عبارة عن حزمة أدوات داخلية لم يتم نشرها على npm. يقوم بتحميل خادم تطوير التطبيق النشط في إطار iframe وتثبيت اللوحة المضمنة بجانبه، وتحديد التطبيق عبر معلمة الاستعلام `app`. تتطلب محطة CLI المتكاملة سطح المكتب Agent Native، الذي يوفر الكود المحلي والوصول إلى PTY لاحتياجات المحطة؛ وبدون ذلك، تعرض اللوحة سطح الدردشة وتطلب منك فتح سطح المكتب لاستخدام CLI.
+
+## ملاحظات التوافق {#compatibility}
+
+كان مفهوم "وضع التعليمات البرمجية" يُسمى سابقًا "وضع التطوير"، لذا فإن القليل منه متوافق مع الإصدارات السابقة
+تستمر الأسماء. يمكنك تجاهل هذه الأمور إلا إذا كنت تحافظ على التكامل الأقدم
+الكود:
+
+- متغير البيئة `AGENT_MODE` الأساسي، `/_agent-native/agent-chat/mode`
+  نقطة النهاية (التي لا يزال مفتاح الحمولة الخاص بها هو `devMode`)، و`agent-chat.mode`
+  مفتاح الإعدادات لم يتغير.
+- يظل `useDevMode()` كاسم مستعار مهمل لـ `useCodeMode()`.

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

@@ -0,0 +1,199 @@
+---
+title: "الخطوات الأولى"
+description: "قم بإنشاء تطبيق وكيل، وافهم التعليمات، وskills، وactions، ثم شاهد الوكيل وهو يستدعي الإجراء الأول."
+---
+
+# البدء
+
+توفر تطبيقات Agent-Native لوكيل الذكاء الاصطناعي وUI نفس actions والبيانات
+الحالة. يتم إنشاء الوكيل الأساسي من التعليمات التي ترشده، skills التي تعلم
+السلوك القابل للتكرار، وactions الذي يتيح له القيام بعمل حقيقي.
+
+**هل تريد تطبيقًا كاملاً للبدء منه؟** استنساخ أحد نماذجنا الغنية —
+[Chat](/docs/template-chat), [Mail](/docs/template-mail),
+[Calendar](/docs/template-calendar), [Content](/docs/template-content),
+[Analytics](/docs/template-analytics)، و[many more](/docs/cloneable-saas) —
+كل تطبيق كامل المواصفات تقوم بتخصيصه.
+
+هل تريد البناء من الصفر؟ الخيار الوحيد أمامك هو ما إذا كنت تريد UI —
+كل شيء بعد (كتابة التعليمات، إضافة skills، تعريف actions، التشغيل
+الوكيل) هو نفسه في كلتا الحالتين.
+
+```an-file-tree title="A basic Agent-Native agent"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, rules, tone, and the map of what the agent can do" },
+    { "path": ".agents/skills/customer-research/SKILL.md", "note": "a reusable playbook the agent loads when the task matches" },
+    { "path": "actions/summarize-week.ts", "note": "typed code the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks can run" }
+  ]
+}
+```
+
+هذا صحيح سواء بدأت بالدردشة UI، أو وكيل بلا رأس، أو تطبيق كامل.
+يغير UI السطح؛ التعليمات، skills، وactions تعطي الوكيل
+التوجيه والسلوك.
+
+## 1. أنشئ تطبيقك
+
+ستحتاج إلى [Node.js 22+](https://nodejs.org) و[pnpm](https://pnpm.io).
+
+قم بتشغيل `create` بدون أي علامات وسيسألك عن الطريقة التي تريد البدء بها (قالب كامل،
+الدردشة أو مقطوعة الرأس) قبل أي شيء آخر:
+
+```bash
+npx @agent-native/core@latest create my-app
+```
+
+أو قم بتمرير علامة لتخطي المطالبة:
+
+**هل تريد UI؟** ابدأ من قالب الدردشة. تحصل على وكيل عامل بالإضافة إلى
+دردشة قابلة للتخصيص UI، وكل إجراء تضيفه يظهر فيها تلقائيًا:
+
+```bash
+npx @agent-native/core@latest create my-app --template chat
+```
+
+**فقط البدائي بلا رأس؟** ابدأ بلا رأس — نفس actions والوكيل
+حلقة، بدون غلاف UI:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+ثم قم بالتثبيت من المجلد الذي قمت بإنشائه:
+
+```bash
+cd my-agent # or my-app if you chose the Chat template
+pnpm install
+```
+
+من الآن فصاعدًا، أصبح الاثنان متطابقين.
+
+## 2. أضف إجراءً
+
+الإجراء هو عملية واحدة يمكن لوكيلك — وUI — الاتصال بها. كلا السقالات
+اشحن بهذا المثال:
+
+```an-annotated-code title="أول action لك"
+{
+  "filename": "actions/hello.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"قل مرحبًا من الوكيل المحلي.\",\n  schema: z.object({\n    name: z.string().default(\"world\"),\n  }),\n  http: { method: \"GET\" },\n  readOnly: true,\n  run: async ({ name }) => {\n    return { message: `Hello, ${name}!` };\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "وصف الأداة", "note": "يقرأ الوكيل `description` ليقرر متى يستدعيه كأداة." },
+    { "lines": "6-8", "label": "عقد typed", "note": "يتحقق zod `schema` واحد من الإدخال من كل سطح: الوكيل، UI، HTTP، MCP وA2A." },
+    { "lines": "9", "label": "HTTP verb", "note": "Opt this action into an auto-mounted HTTP endpoint." },
+    { "lines": "10", "label": "Read-only", "note": "`readOnly` marks the action as safe to call without approval and cacheable for queries." },
+    { "lines": "11-13", "label": "One implementation", "note": "The `run` body is the single source of truth that every surface executes." }
+  ]
+}
+```
+
+استبدل `hello` بالعملية الحقيقية الأولى في مجالك. قمت بتعريفه مرة واحدة؛
+يلتقطه كل سطح.
+
+استخدم `AGENTS.md` للحصول على إرشادات يجب تطبيقها في كل دورة. استخدم مهارة عندما
+إلى سير عمل أو إجراء مجال قابل لإعادة الاستخدام. استخدم الإجراء عندما يكون
+يحتاج الوكيل إلى طريقة مكتوبة وقابلة للاختبار لقراءة البيانات أو كتابتها أو الاتصال بـ API أو
+إجراء الموافقة.
+
+## 3. قم بتشغيله
+
+استدعاء الإجراء مباشرة:
+
+```bash
+pnpm action hello --name Steve
+```
+
+أو اطلب من الوكيل أن يتصل بك:
+
+```bash
+pnpm agent "Call the hello action for Steve and explain what happened."
+```
+
+إذا بدأت من قالب الدردشة، فقم بتشغيل التطبيق واستخدم نفس الوكيل في
+المتصفح - يمكنه بالفعل استدعاء كل إجراء تحدده:
+
+```bash
+pnpm dev
+```
+
+يمكن الآن الوصول إلى هذا الإجراء الواحد من خلال الدردشة UI، وCLI، وHTTP، وMCP، وA2A،
+المهام المجدولة، وwebhooks. حدد مرة واحدة، اتصل من أي مكان.
+
+```an-diagram title="One action, every surface" summary="A single defineAction file fans out to every consumer with no extra wiring."
+{
+  "html": "<div class=\"diagram-fan\"><div class=\"diagram-box\" data-rough>defineAction</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-surfaces\"><span class=\"diagram-pill\">Chat UI</span><span class=\"diagram-pill\">CLI</span><span class=\"diagram-pill\">HTTP</span><span class=\"diagram-pill\">MCP</span><span class=\"diagram-pill\">A2A</span><span class=\"diagram-pill\">Scheduled jobs</span><span class=\"diagram-pill\">Webhooks</span></div></div>",
+  "css": ".diagram-fan{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fan .diagram-surfaces{display:flex;flex-wrap:wrap;gap:8px;max-width:420px}.diagram-fan .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## تم بناء الحالة في
+
+لا يعني مقطوع الرأس أنه عديم الجنسية. Actions، الجلسات، حالة التطبيق، المواضيع،
+سجل التشغيل وبيانات الاعتماد كلها موجودة في SQL. محليًا، هذا هو SQLite في
+`data/app.db`; in production you set `DATABASE_URL`. See
+[Deployment](/docs/deployment).
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Headless is still a real app.** The app-agent loop persists sessions, threads, runs, settings, and credentials in SQL — it is not a stateless prompt. You can add a UI later without touching your actions or state."
+}
+```
+
+## تخصيص UI
+
+إذا بدأت من قالب الدردشة، فإن UI متاح لك لتحريره. الدردشة نفسها
+هو مسار صغير مبني على مكون `<AgentChatSurface>`:
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-full" />;
+}
+```
+
+- **`app/routes/_index.tsx`** — صفحة الدردشة. تغيير الاقتراحات، فارغ
+  الحالة والتخطيط.
+- **`app/root.tsx`** — غلاف التطبيق. أضف مساراتك وشاشاتك الخاصة حول
+  الوكيل.
+- أسقط الوكيل في أي شاشة باستخدام `<AgentSidebar>`، واعمل عليه يدويًا من
+  مع `sendToAgentChat()`، أو قم بتشغيل الإجراء مباشرة باستخدام
+  `useActionMutation()`.
+
+راجع [Drop-in Agent](/docs/drop-in-agent) للتعرف على مجموعة المكونات الكاملة، و
+[Native Chat UI](/docs/native-chat-ui) لعرض نتائج الإجراء على هيئة جداول
+المخططات والبطاقات المكتوبة بدلاً من النص العادي.
+
+**بدأت بدون رأس وتريد UI لاحقًا؟** قالب الدردشة _هو_ UI على الطريق المنحدر —
+طبقة `app/` (جهاز التوجيه React + Vite) هي بالضبط ما تمثله السقالة مقطوعة الرأس
+يترك. أنظف خطوة هي البدء (أو إعادة السقالة) من الدردشة
+قالب; يتم ترحيل حالة `actions/` والوكيل وحالة SQL دون تغيير. انظر
+[Agent Surfaces](/docs/agent-surfaces) لكل سطح بينهما.
+
+## بنية المشروع
+
+```text
+my-app/
+  actions/         # Agent-callable actions
+  app/             # React frontend (UI templates only; omitted when headless)
+  server/          # Nitro API server (routes, plugins)
+  AGENTS.md        # Always-on agent instructions
+  .agents/         # Skills the agent can pull in when relevant
+  data/app.db      # Local SQLite state when DATABASE_URL is unset
+```
+
+## إلى أين ستتجه بعد ذلك
+
+- **[Key Concepts](/docs/key-concepts)** — البنية الأساسية: SQL، actions،
+  المزامنة والوعي بالسياق.
+- **[Actions](/docs/actions)** — الإجراء الكامل API: المخططات، وHTTP، والمصادقة، و
+  الموافقة.
+- **[Agent Surfaces](/docs/agent-surfaces)** — بدون رأس، دردشة، عربة جانبية مدمجة،
+  والتطبيق الكامل.
+- **[Drop-in Agent](/docs/drop-in-agent)** — أضف دردشة الوكيل إلى أي تطبيق React.
+- **[Deployment](/docs/deployment)** — ضع تطبيقك على نطاقك الخاص.
+- **[FAQ](/docs/faq)** — أسئلة حول الإعداد والمنتج.