@agent-native/core 0.93.0 → 0.94.0

package/docs/content/key-concepts.mdx

@@ -11,11 +11,9 @@ How agent-native apps work under the hood — the principles and the architectur
 
 Every agent-native app is three things working together:
 
-> **Agent** — Autonomous AI that reads data, writes data, runs actions, and modifies code. Customizable with skills and instructions.
->
-> **Application** — The product surface around the agent. This may start as chat, add native inline results, grow into a small control plane, or become a full React UI with dashboards, flows, and visualizations.
->
-> **Computer** — Database, browser, code execution. Agents work directly with SQL and built-in tools; MCP servers are optional add-ons, not the foundation.
+- **Agent** — Autonomous AI that reads data, writes data, runs actions, and modifies code. Customizable with skills and instructions.
+- **Application** — The product surface around the agent. This may start as chat, add native inline results, grow into a small control plane, or become a full React UI with dashboards, flows, and visualizations.
+- **Computer** — Database, browser, code execution. Agents work directly with SQL and built-in tools; MCP servers are optional add-ons, not the foundation.
 
 <Diagram id="doc-block-t1f7pj" title="Agent, application, and computer" summary="Three layers working together over one shared SQL store. The agent and the application both read and write the same data.">
 
@@ -278,8 +276,7 @@ Why not call an LLM inline?
 
 When the agent needs to do something complex — call an API, process data, query the database — it runs an **action**. Actions are TypeScript files in `actions/` that export a default `defineAction()`:
 
-```ts
-// actions/fetch-data.ts
+```ts filename="actions/fetch-data.ts"
 import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
@@ -379,9 +376,8 @@ A _frame_ is the environment that hosts the agent next to your app — locally t
 
 Agent-native apps include an embedded agent panel that provides the AI agent alongside the app UI. This is what makes the architecture work: the agent needs a computer (database, browser, code execution), and the app needs the agent for AI work.
 
-> **Embedded Agent Panel** — Chat and optional CLI terminal built into every app. Supports Claude Code, Codex, Gemini, OpenCode, and Builder.io. Runs locally. Free and open source.
->
-> **Cloud** — Deploy to any cloud with real-time collaboration, visual editing, roles and permissions. Best for teams.
+- **Embedded Agent Panel** — Chat and optional CLI terminal built into every app. Supports Claude Code, Codex, Gemini, OpenCode, and Builder.io. Runs locally. Free and open source.
+- **Cloud** — Deploy to any cloud with real-time collaboration, visual editing, roles and permissions. Best for teams.
 
 ## Context awareness {#context-awareness}
 
@@ -452,14 +448,11 @@ Adopting the framework is valuable mostly because of what you stop having to bui
 
 That's the "and everything else" you'd otherwise be gluing together yourself.
 
-## Deep dives {#deep-dives}
-
-For detailed guidance on specific patterns:
+## What's next {#deep-dives}
 
-- [What Is Agent-Native?](/docs/what-is-agent-native) — the vision and philosophy
-- [Context Awareness](/docs/context-awareness) — navigation state, view-screen, navigate commands
-- [Skills Guide](/docs/skills-guide) — framework skills, domain skills, creating custom skills
-- [Native Chat UI](/docs/native-chat-ui) — action-declared tables, charts, and BYO runtime posture
-- [Agent Surfaces](/docs/agent-surfaces) — chat, native inline UI, full app pages, embedded sidecar, automation, and external-agent paths
-- [A2A Protocol](/docs/a2a-protocol) — agent-to-agent communication
-- [Multi-App Workspace](/docs/multi-app-workspace) — host many apps in one monorepo with shared auth, skills, components, and credentials
+- [**What Is Agent-Native?**](/docs/what-is-agent-native) — the vision and philosophy behind these rules
+- [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen, and navigate commands in depth
+- [**Skills Guide**](/docs/skills-guide) — framework skills, domain skills, and creating custom skills
+- [**Native Chat UI**](/docs/native-chat-ui) — action-declared tables, charts, and BYO runtime posture
+- [**Agent Surfaces**](/docs/agent-surfaces) — chat, native inline UI, full app pages, embedded sidecar, automation, and external-agent paths
+- [**A2A Protocol**](/docs/a2a-protocol) — agent-to-agent communication

package/docs/content/local-file-mode.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Local File Mode"
-description: "Run agent-native apps with local Markdown, MDX, and other repo files as the source of truth - including Obsidian-style MDX docs with custom components."
+description: "Run agent-native apps with local Markdown, MDX, and other repo files as the source of truth - including a repo-native MDX docs workflow with custom components."
 ---
 
 # Local File Mode
@@ -16,16 +16,16 @@ Content editor, and saving writes back to the selected file. The same files can
 also be edited by Codex, Claude Code, the Agent-Native sidebar agent, or a normal
 editor.
 
-For Content, this makes the product feel like open-source Obsidian for MDX:
-your docs live as files, while the app adds a visual editor, agent actions,
-shareable copies, and rich interactive MDX components.
+For Content, this makes the product a repo-native MDX docs tool: your docs
+live as files, while the app adds a visual editor, agent actions, shareable
+copies, and rich interactive MDX components.
 
 Use Local File Mode when you want a repo-first workflow:
 
 - a docs repo with `docs/*.mdx`
 - a blog with `blog/*.mdx`
 - resources such as positioning, messaging, or team notes in `resources/*.md`
-- a personal Obsidian-style knowledge base with a richer MDX editor
+- a personal knowledge base with a richer MDX editor
 - docs that need interactive custom MDX blocks generated from local React code
 - app artifacts that should be easy for coding agents to inspect and patch
 
@@ -276,8 +276,7 @@ install snippets, or framework-specific code blocks.
 
 For example, add an interactive component next to your content:
 
-```tsx
-// components/ImpactCounter.tsx
+```tsx filename="components/ImpactCounter.tsx"
 import { useState } from "react";
 
 export function ImpactCounter({
@@ -449,7 +448,7 @@ For v1, local extensions are intentionally conservative:
 - raw SQL helpers and external `extensionFetch` are disabled
 - slot targets are declared in `extension.json`, not installed through SQL
 
-This gives local workspaces an Obsidian-like plugin surface without letting an
+This gives local workspaces a lightweight plugin surface without letting an
 arbitrary repo file inherit every capability of a database-backed extension.
 
 ## How Apps Use It
@@ -523,3 +522,10 @@ AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION=true
 Only set that for a trusted single-tenant deployment where everyone who can use
 the app is allowed to read and write the configured files. For normal hosted,
 multi-user apps, use database mode and SQL-backed sharing.
+
+## What's next
+
+- [**Database**](/docs/database) — the SQL-backed mode this page contrasts with
+- [**Sharing**](/docs/sharing) — the standard document-sharing model that database-mode copies use
+- [**Extensions**](/docs/extensions) — the SQL-backed extension model that local extensions intentionally simplify
+- [**Creating Templates**](/docs/creating-templates) — adopting the same local-artifact pattern in a new app

package/docs/content/locales/ar-SA/actions.mdx

@@ -11,7 +11,7 @@ Actions هي المصدر الوحيد للحقيقة لأي شيء يفعله
 - **خطافات Typesafe React** — `useActionQuery("name")` و`useActionMutation("name")` في الواجهة الأمامية، الأنواع المستنتجة من المخطط.
 - **استدعاءات العميل الحتمية** — `callAction("name", params)` عندما لا يكون الخطاف مناسبًا.
 - **نقل إطار العمل** — يتم تركيبه تلقائيًا بواسطة إطار العمل خلف تلك الخطافات وهو متاح لعملاء HTTP الخارجيين.
-- **أداة MCP** — مكشوفة لتطبيقات Claude وChatGPT المخصصة MCP وClaude Desktop/Code وCursor وCodex وأي عميل MCP آخر.
+- **أداة MCP** — مكشوفة لتطبيقات Claude وChatGPT المخصصة MCP وClaude Desktop/Code وCursor وCodex وأي مضيف MCP آخر.
 - **أداة A2A** — يتم استدعاؤها بواسطة تطبيقات الوكيل الأصلية الأخرى عبر A2A.
 - **أمر CLI** — `pnpm action <name>` للبرمجة النصية وحلقات التطوير.
 
@@ -560,7 +560,7 @@ export default defineAction({
 });
 ```
 
-احتفظ بـ `link` كبديل لعملاء CLI وغير UI MCP؛ وهو أيضًا هدف إطلاق التضمين. جسر التضمين - جلسة بدء التضمين الموقعة، والزرع مقابل عرض الإطار المتحكم فيه، والجسر المضيف `ui/*`، وCSP، وتثبيت الارتفاع - مملوك لشركة [External Agents](/docs/external-agents#mcp-app-bridge).
+احتفظ بـ `link` كبديل لـ CLI ومضيفي MCP بدون واجهة مستخدم؛ وهو أيضًا هدف إطلاق التضمين. جسر التضمين - جلسة بدء التضمين الموقعة، والزرع مقابل عرض الإطار المتحكم فيه، والجسر المضيف `ui/*`، وCSP، وتثبيت الارتفاع - مملوك لشركة [External Agents](/docs/external-agents#mcp-app-bridge).
 
 ## قياسي actions {#standard-actions}
 

package/docs/content/locales/ar-SA/agent-native-toolkit.mdx

@@ -97,9 +97,9 @@ coherent kit instead of exposing package boundaries in the app.
 
 - [UI Primitives](/docs/toolkit-ui) cover shared shadcn-style primitives under
   `@agent-native/toolkit/ui/*`.
-- [App Adapters](/docs/toolkit-app-adapters) show how apps wrap Toolkit pieces
+- [App Adapters](/docs/toolkit-ui#app-adapters) show how apps wrap Toolkit pieces
   through local `@/components/*` adapters.
-- [Shell & Hooks](/docs/toolkit-shell-hooks) cover header actions, mobile hooks,
+- [Shell & Hooks](/docs/toolkit-ui#shell-hooks) cover header actions, mobile hooks,
   toasts, and small app-shell helpers.
 - [Component API](/docs/components) remains the lower-level reference for the
   public React exports.

package/docs/content/locales/ar-SA/agent-surfaces.mdx

@@ -139,8 +139,7 @@ pnpm install
 
 ثم حدد العملية الدائمة:
 
-```ts
-// actions/summarize-week.ts
+```ts filename="actions/summarize-week.ts"
 import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
@@ -494,12 +493,11 @@ export function AppShell({ children }) {
 نتائج الأدوات عندما تحتاج الدردشة إلى UI، وإضافة شاشات كاملة فقط عند المستخدمين
 تحتاج إلى تصفح الكائنات الثابتة أو مقارنتها أو تكوينها أو التعاون عليها.
 
-## المستندات ذات الصلة {#related-docs}
+## الخطوات التالية {#related-docs}
 
-- [Actions](/docs/actions) — حدد عملية مقطوعة الرأس مرة واحدة.
-- [Native واجهة الدردشة](/docs/native-chat-ui) — عرض نتائج الإجراءات المكتوبة في الدردشة.
-- [Drop-in Agent](/docs/drop-in-agent) — قم بتثبيت الدردشة أو الشريط الجانبي أو أسطح اللوحات.
-- [Component API](/docs/components) — مقطوعات الدردشة/الملحن React ذات المستوى الأدنى.
-- [Embedding SDK](/docs/embedding-sdk) — أضف Agent-Native إلى تطبيق موجود.
-- [External Agents](/docs/external-agents) — توصيل الأجهزة المضيفة المتوافقة مع MCP بأحد التطبيقات.
-- [A2A Protocol](/docs/a2a-protocol) — استدعاء الوكلاء من الوكلاء الآخرين.
+- [**Actions**](/docs/actions) — عرّف العملية مرة واحدة؛ كل سطح أعلاه يستدعي العملية نفسها
+- [**Native Chat UI**](/docs/native-chat-ui) — اعرض نتائج actions كجداول ومخططات وبطاقات في الدردشة
+- [**Generative UI**](/docs/generative-ui) — أنشئ واجهة مستخدم مؤقتة أو دائمة ضمن بيئة معزولة داخل الدردشة
+- [**Automation-First Apps**](/docs/pure-agent-apps) — النمط الكامل دون متصفح للوظائف وقوائم الانتظار والبرامج النصية والوكلاء الخارجيين
+- [**External Agents**](/docs/external-agents) — صِل المضيفين المتوافقين مع MCP بتطبيق
+- [**A2A Protocol**](/docs/a2a-protocol) — استدعِ الوكلاء من تطبيقات Agent-Native أخرى

package/docs/content/locales/ar-SA/agent-teams.mdx

@@ -239,6 +239,7 @@ interface AgentTask {
   summary: string; // full summary once completed
   currentStep: string; // latest step label (updated while running)
   createdAt: number;
+  delegationDepth?: number; // 1 for a direct sub-agent, 2 for a sub-agent of that sub-agent, etc.
   // Additional fields: parentThreadId, name, updatedAt, startedAt,
   // completedAt, runId, error
 }

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

@@ -15,7 +15,7 @@ description: "تكامل أفضل للمصادقة مع البريد الإلك
 - **جهاز التحكم عن بعد MCP OAuth:** معيار OAuth 2.1 لمضيفي MCP مثل Claude Code وموصلات ChatGPT.
 - **مخصص:** قم بإحضار المصادقة الخاصة بك عبر رد الاتصال `getSession`.
 
-<Diagram id="doc-block-5y2l0x" title={"ثلاث طرق في جلسة واحدة"} summary={"يقوم كل زوار المستعرض وعملاء MCP الآليين والموفرين المخصصين بالتوصل إلى نفس AuthSession الذي يقرأه النطاق النهائي."}>
+<Diagram id="doc-block-5y2l0x" title={"ثلاث طرق في جلسة واحدة"} summary={"يقوم كل زوار المستعرض ومضيفي MCP والموفرين المخصصين بالتوصل إلى نفس AuthSession الذي يقرأه النطاق النهائي."}>
 
 ```html
 <div class="auth-modes">

package/docs/content/locales/ar-SA/components.mdx

@@ -472,10 +472,12 @@ function WorkspaceResources() {
 ```ts
 import { defineAction } from "@agent-native/core/action";
 import { completeText } from "@agent-native/core/server";
+import { z } from "zod";
 
 export default defineAction({
   description: "Classify a short message",
-  run: async ({ body }: { body: string }) => {
+  schema: z.object({ body: z.string() }),
+  run: async ({ body }) => {
     const result = await completeText({
       systemPrompt: "Return exactly one label.",
       input: body,
@@ -490,3 +492,11 @@ export default defineAction({
 استخدم `sendToAgentChat({ background: true, openSidebar: false })` بدلاً من ذلك عندما
 يحتاج العمل إلى أدوات، أو حالة، أو إمكانية التدقيق، أو توجيه المستخدم، أو الخطوات المتعددة
 الاستدلال.
+
+## ما التالي {#whats-next}
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — ثبّت `<AgentSidebar>` و`<AgentPanel>` مع شرح إرشادي يبدأ بالبرنامج التعليمي
+- [**Native Chat UI**](/docs/native-chat-ui) — عقد نتيجة الإجراء وراء عناصر واجهة البيانات وأدوات العرض المخصصة
+- [**Actions**](/docs/actions) — ‏`defineAction()` والمخططات وسطح الإجراءات الذي تستدعيه هذه المكونات
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — تفاصيل ربط التعاون ومكونات الحضور
+- [**Sharing**](/docs/sharing) — توصيل `<ShareButton>` و`<ShareDialog>` للموارد القابلة للامتلاك

package/docs/content/locales/ar-SA/creating-templates.mdx

@@ -44,7 +44,6 @@ npx @agent-native/core@latest create my-platform
 <FileTree
   id="doc-block-15r9qt6"
   title={"بنية مشروع ال template"}
-  title="my-template/"
   entries={[
     {
       path: "app/",
@@ -172,8 +171,7 @@ npx @agent-native/core@latest create my-platform
 
 حدد جداول المجال باستخدام إطار العمل المساعد Drizzle بحيث تظل المخططات قابلة للنقل عبر SQLite، وPostgres، وD1، وTurso، وSupabase، وNeon، والواجهات الخلفية المدعومة الأخرى:
 
-```ts
-// server/db/schema.ts
+```ts filename="server/db/schema.ts"
 import {
   table,
   text,
@@ -204,8 +202,7 @@ export const projectShares = createSharesTable("project_shares");
 
 لقراءة التطبيق وكتابته، استخدم منشئ الاستعلامات والمشغلات المحمولة Drizzle من `drizzle-orm`. لا تكتب رمز المنتج باستخدام SQL الخام عندما يتمكن Drizzle من التعبير عن الاستعلام، ولا تستورد من `drizzle-orm/sqlite-core` أو `drizzle-orm/pg-core` في القوالب.
 
-```ts
-// server/plugins/db.ts
+```ts filename="server/plugins/db.ts"
 import { runMigrations } from "@agent-native/core/db";
 
 export default runMigrations(
@@ -349,8 +346,7 @@ export function useNavigationState() {
 `path` عندما يكون URL معروفًا. ولا تكتب أيضًا `__set_url__` لنفس الحركة؛
 هذا المفتاح محجوز لأدوات إطار العمل URL وتغييرات مرشح URL فقط.
 
-```ts
-// actions/navigate.ts
+```ts filename="actions/navigate.ts"
 import { defineAction } from "@agent-native/core/action";
 import { writeAppState } from "@agent-native/core/application-state";
 import { z } from "zod";

package/docs/content/locales/ar-SA/cross-app-sso.mdx

@@ -9,7 +9,11 @@ description: "قم بتسجيل الدخول مرة واحدة عبر كل تط
 
 هذا هو نفس مبدأ الثقة الأساسي [A2A](/docs/a2a-protocol) و[External Agents](/docs/external-agents) الذي يستخدمه بالفعل - `A2A_SECRET` الموقع JWT والذي تم التحقق منه عند حد الطلب - والذي يتم تطبيقه على مسار تسجيل الدخول البشري بدلاً من مكالمات وكيل إلى وكيل.
 
-> **النشر الموحد مقابل النشر لكل مجال.** إذا كنت تستضيف جميع التطبيقات في مصدر واحد (`your-agents.com/mail`، `your-agents.com/calendar`)، فستحصل بالفعل على تسجيل دخول مشترك عبر مجال ملف تعريف ارتباط واحد - لا حاجة إلى اتحاد. يعد Cross-App SSO ضروريًا فقط عند تشغيل التطبيقات على مجالات منفصلة. انظر [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+<Callout tone="info">
+
+**النشر الموحد مقابل النشر لكل مجال.** إذا كنت تستضيف جميع التطبيقات في مصدر واحد (`your-agents.com/mail`، `your-agents.com/calendar`)، فستحصل بالفعل على تسجيل دخول مشترك عبر مجال ملف تعريف ارتباط واحد - لا حاجة إلى اتحاد. يعد Cross-App SSO ضروريًا فقط عند تشغيل التطبيقات على مجالات منفصلة. انظر [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+
+</Callout>
 
 ## ماذا ولماذا {#what-why}
 
@@ -86,15 +90,17 @@ description: "قم بتسجيل الدخول مرة واحدة عبر كل تط
 
 </Diagram>
 
-1. **التطبيق → إرسال (تفويض).** يرسل التطبيق المستخدم إلى سلطة الهوية:
+1. **التطبيق → Dispatch (التفويض).** ينشئ مسار `GET /_agent-native/identity/login` في التطبيق (وهو المسار الذي يرتبط به زر «تسجيل الدخول باستخدام Agent-Native») إعادة التوجيه ويرسل المستخدم إلى جهة الهوية:
 
-   ```
+   ```http
    GET https://dispatch.agent-native.com/_agent-native/identity/authorize
        ?app=<requesting-app>
        &redirect_uri=<app-callback-url>
        &state=<csrf-state>
    ```
 
+   `redirect_uri` هو مسار `GET /_agent-native/identity/callback` الخاص بهذا التطبيق — وهو المسار الذي يستقبل الرمز الموقّع في الخطوة 3.
+
 <Endpoint id="cross-app-sso-identity-authorize-ar-sa" title={"الهوية تأذن بنقطة النهاية"} method="GET" path="/_agent-native/identity/authorize" summary={"تقوم شركة Dispatch (سلطة الهوية) بالمصادقة على المستخدم وإعادة التوجيه مرة أخرى باستخدام رمز هوية موقّع"} auth={"جلسة الإرسال (تسجيل الدخول التفاعلي إذا لم يكن هناك)"} params={[
   {
     "name": "app",
@@ -143,7 +149,7 @@ description: "قم بتسجيل الدخول مرة واحدة عبر كل تط
    | `scope`      | `"identity"` دائمًا — يسمح هذا الرمز المميز بتسجيل الدخول فقط                    |
    | `exp`        | **≥ دقيقتين** من الإصدار                                                         |
 
-4. **يتحقق التطبيق من روابط JIT عبر البريد الإلكتروني.** يتحقق التطبيق من توقيع الرمز المميز باستخدام `A2A_SECRET` الخاص به، ويتحقق من `scope: "identity"` و`exp`، ثم ينفذ **الربط في الوقت المناسب تمامًا عن طريق البريد الإلكتروني الذي تم التحقق منه**:
+4. **يتحقق التطبيق ويربط الحساب في الوقت المناسب عبر البريد الإلكتروني.** يتحقق مسار `GET /_agent-native/identity/callback` في التطبيق من توقيع الرمز المميز باستخدام `A2A_SECRET` الخاص به، ويتحقق من `scope: "identity"` و`exp`، ثم ينفذ **الربط في الوقت المناسب حصريًا عبر البريد الإلكتروني المتحقق منه**:
    - في حالة وجود مستخدم محلي لديه هذا البريد الإلكتروني → أعد استخدامه دون تغيير.
    - إذا لم يكن الأمر كذلك، قم بإنشاء مستخدم محلي لهذا البريد الإلكتروني.
 
@@ -290,9 +296,13 @@ AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
 **5. التراجع = إلغاء تعيين env var عند نشر هذا التطبيق.**
 للتراجع عن أي تطبيق، **قم بإزالة `AGENT_NATIVE_IDENTITY_HUB_URL` من بيئة ذلك التطبيق وأعد نشره/أعد تشغيله.** يعود التطبيق فورًا إلى سلوك المصادقة السابق الخاص به. لا يوجد **لا يوجد تغيير في البيانات للتراجع عنه** — تمت إضافة صفوف الهوية فقط، كما أن إلغاء تعيين المتغير يجعل مسار الاتحاد خاملًا مرة أخرى. تعتبر عمليات الاستبدال والتراجع لكل تطبيق مستقلة وقابلة للعكس.
 
-> يقوم الطرح بتسجيل خروج المستخدمين عند تمكين كل تطبيق (يقومون بإعادة المصادقة عبر Dispatch)، ولكنهم دائمًا ما يقومون بتسجيل الدخول مرة أخرى إلى **نفس الحساب المطابق للبريد الإلكتروني مع الحفاظ على البيانات**، لأنه لا يتم إتلاف صفوف الهوية أو إعادة تسميتها أبدًا، بل تتم إضافتها فقط.
+<Callout tone="info">
+
+يقوم الطرح بتسجيل خروج المستخدمين عند تمكين كل تطبيق (يقومون بإعادة المصادقة عبر Dispatch)، ولكنهم دائمًا ما يقومون بتسجيل الدخول مرة أخرى إلى **نفس الحساب المطابق للبريد الإلكتروني مع الحفاظ على البيانات**، لأنه لا يتم إتلاف صفوف الهوية أو إعادة تسميتها أبدًا، بل تتم إضافتها فقط.
+
+</Callout>
 
-## ذات صلة {#related}
+## الخطوات التالية {#whats-next}
 
 - [Authentication](/docs/authentication) — أوضاع المصادقة المحلية، والجلسات، والمؤسسات، ومتغير البيئة `A2A_SECRET`.
 - [A2A Protocol](/docs/a2a-protocol) — نموذج الثقة JWT المُوقع، الذي يتم التحقق منه عند الحدود والذي يُعاد استخدامه.

package/docs/content/locales/ar-SA/deployment.mdx

@@ -452,3 +452,11 @@ export default createAgentChatPlugin({
 ## نشر المثيلات المتعددة {#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).
+
+## الخطوات التالية
+
+- [**Database**](/docs/database#production) — اختر قاعدة بيانات SQL دائمة قبل أول نشر للإنتاج
+- [**Security**](/docs/security) — قائمة تحقق الإنتاج والعلامات الاختيارية المشار إليها في هذه الصفحة
+- [**Authentication**](/docs/authentication) — بيانات اعتماد OAuth ومتغيرات البيئة لوضع المصادقة الذي تختاره
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — نموذج مساحة العمل وراء بنية `deploy` ذات الأصل الواحد
+- [**Frames**](/docs/frames) — لوحة الوكيل المضمنة مقارنةً بإطار Builder.io السحابي لتعديلات واجهة الإنتاج

package/docs/content/locales/ar-SA/external-agents.mdx

@@ -136,13 +136,8 @@ ChatGPT: استخدم مساحة عمل حيث توجد موصلات MCP الم
 تغييرات البيانات التعريفية لتطبيق MCP. إذا كان لا يزال لديك موصلات قديمة لكل تطبيق
 ممكّن جنبًا إلى جنب مع Dispatch أو تحديث أو إعادة توصيل كل موصل قديم؛ التحديث
 لا يقوم Dispatch بإعادة كتابة تقويم/بريد ChatGPT أو Claude المخزن مؤقتًا/البريد/إلخ.
-لقطات. النطاقات هي:
-
-| النطاق      | ما يتيحه                                                          |
-| ----------- | ----------------------------------------------------------------- |
-| `mcp:read`  | أدوات للقراءة فقط واكتشاف الأدوات/الموارد                         |
-| `mcp:write` | الصياغة والتحديث وغيرها من تعديلات actions                        |
-| `mcp:apps`  | تطبيقات MCP المضمّنة، والمخططات، ولوحات المعلومات، والمسودات، وUI |
+لقطات. نطاقات `mcp:read` / `mcp:write` / `mcp:apps` هي نفسها الموضحة في
+[OAuth القياسي لـ MCP البعيد](#standard-oauth) أدناه.
 
 يستخدم كل من Cursor وGoose وPostman وMCPJam وVS Code GitHub Copilot نفس جهاز التحكم عن بعد
 MCP URL من خلال خادم MCP الخاص بهم UI عندما يدعم تصميمهم OAuth عن بعد

package/docs/content/locales/ar-SA/key-concepts.mdx

@@ -11,11 +11,9 @@ description: "كيفية عمل تطبيقات الوكيل الأصلية: acti
 
 يتكون كل تطبيق وكيل أصلي من ثلاثة أشياء تعمل معًا:
 
-> **Agent** — الذكاء الاصطناعي المستقل الذي يقرأ البيانات، ويكتب البيانات، ويشغل actions، ويعدل التعليمات البرمجية. قابلة للتخصيص باستخدام skills والتعليمات.
->
-> **التطبيق** — سطح المنتج حول العامل. قد يكون هذا الإجراء فقط في البداية، أو دردشة غنية، أو مستوى تحكم صغير، أو واجهة React كامل مع لوحات المعلومات، وعمليات التدفق، والمرئيات.
->
-> **الكمبيوتر** — قاعدة البيانات، المتصفح، تنفيذ التعليمات البرمجية. يعمل الوكلاء مباشرةً باستخدام SQL والأدوات المضمنة؛ خوادم MCP هي إضافات اختيارية وليست أساسية.
+- **Agent** — الذكاء الاصطناعي المستقل الذي يقرأ البيانات، ويكتب البيانات، ويشغل actions، ويعدل التعليمات البرمجية. قابلة للتخصيص باستخدام skills والتعليمات.
+- **التطبيق** — سطح المنتج حول العامل. قد يكون هذا الإجراء فقط في البداية، أو دردشة غنية، أو مستوى تحكم صغير، أو واجهة React كامل مع لوحات المعلومات، وعمليات التدفق، والمرئيات.
+- **الكمبيوتر** — قاعدة البيانات، المتصفح، تنفيذ التعليمات البرمجية. يعمل الوكلاء مباشرةً باستخدام SQL والأدوات المضمنة؛ خوادم MCP هي إضافات اختيارية وليست أساسية.
 
 <Diagram id="doc-block-u19iga" title={"الوكيل والتطبيق والكمبيوتر"} summary={"ثلاث طبقات تعمل معًا في متجر SQL واحد مشترك. يقوم كل من الوكيل والتطبيق بقراءة وكتابة نفس البيانات."}>
 
@@ -279,8 +277,7 @@ sendToAgentChat({
 
 عندما يحتاج الوكيل إلى القيام بشيء معقد - استدعاء API ومعالجة البيانات والاستعلام عن قاعدة البيانات - فإنه يقوم بتشغيل **إجراء**. Actions هي ملفات TypeScript في `actions/` والتي تقوم بتصدير `defineAction()` الافتراضي:
 
-```ts
-// actions/fetch-data.ts
+```ts filename="actions/fetch-data.ts"
 import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
@@ -384,9 +381,8 @@ A _frame_ هي البيئة التي تستضيف الوكيل بجوار تطب
 
 تتضمن تطبيقات الوكيل الأصلية لوحة وكيل مضمنة توفر وكيل الذكاء الاصطناعي إلى جانب التطبيق UI. وهذا ما يجعل البنية تعمل: يحتاج الوكيل إلى جهاز كمبيوتر (قاعدة بيانات، ومتصفح، وتنفيذ التعليمات البرمجية)، ويحتاج التطبيق إلى الوكيل لعمل الذكاء الاصطناعي.
 
-> **Embedded Agent Panel** — الدردشة ومحطة CLI الاختيارية المدمجة في كل تطبيق. يدعم كود Claude، وCodex، وGemini، وOpenCode، وBuilder.io. يعمل محليا. مجاني ومفتوح المصدر.
->
-> **السحابة** — النشر على أي سحابة من خلال التعاون في الوقت الفعلي والتحرير المرئي والأدوار والأذونات. الأفضل للفرق.
+- **Embedded Agent Panel** — الدردشة ومحطة CLI الاختيارية المدمجة في كل تطبيق. يدعم كود Claude، وCodex، وGemini، وOpenCode، وBuilder.io. يعمل محليا. مجاني ومفتوح المصدر.
+- **السحابة** — النشر على أي سحابة من خلال التعاون في الوقت الفعلي والتحرير المرئي والأدوار والأذونات. الأفضل للفرق.
 
 ## الوعي بالسياق {#context-awareness}
 
@@ -458,14 +454,11 @@ A _frame_ هي البيئة التي تستضيف الوكيل بجوار تطب
 
 هذا هو "وكل شيء آخر" الذي كنت ستلصقه معًا بنفسك.
 
-## الغوص العميق {#deep-dives}
-
-للحصول على إرشادات تفصيلية حول أنماط محددة:
+## الخطوات التالية {#deep-dives}
 
-- [What Is Agent-Native?](/docs/what-is-agent-native) — الرؤية والفلسفة
-- [Context Awareness](/docs/context-awareness) — حالة التنقل، شاشة العرض، أوامر التنقل
-- [Skills Guide](/docs/skills-guide) — إطار العمل skills، المجال skills، إنشاء skills مخصص
-- [Native واجهة الدردشة](/docs/native-chat-ui) — الجداول والرسوم البيانية التي تم الإعلان عنها، وموقف وقت التشغيل BYO
-- [Agent Surfaces](/docs/agent-surfaces) - دردشة غنية بدون رأس، وعربة جانبية مضمنة، ومسارات التطبيق الكامل
-- [A2A Protocol](/docs/a2a-protocol) — الاتصال من وكيل إلى وكيل
-- [Multi-App Workspace](/docs/multi-app-workspace) — استضافة العديد من التطبيقات في جهاز monorepo واحد مع مصادقة مشتركة وskills والمكونات وبيانات الاعتماد
+- [**What Is Agent-Native?**](/docs/what-is-agent-native) — الرؤية والفلسفة وراء هذه القواعد
+- [**Context Awareness**](/docs/context-awareness) — حالة التنقل وأمرا view-screen وnavigate بالتفصيل
+- [**Skills Guide**](/docs/skills-guide) — skills الإطار والمجال وإنشاء skills مخصصة
+- [**Native Chat UI**](/docs/native-chat-ui) — جداول ومخططات معلنة بواسطة actions ودعم أوقات التشغيل التي توفرها بنفسك
+- [**Agent Surfaces**](/docs/agent-surfaces) — الدردشة والواجهة الأصلية المضمنة وصفحات التطبيق الكاملة والواجهة الجانبية المضمنة والأتمتة ومسارات الوكلاء الخارجيين
+- [**A2A Protocol**](/docs/a2a-protocol) — الاتصال من وكيل إلى وكيل

package/docs/content/locales/ar-SA/multi-tenancy.mdx

@@ -17,7 +17,7 @@ description: "يعد كل تطبيق أصلي للوكيل متعدد المست
 - **تبديل المؤسسة** — تتعقب الجلسة المؤسسة النشطة (`session.orgId`)، ويؤدي تبديلها إلى تغيير البيانات التي يراها المستخدم والوكيل.
 - **عزل البيانات لكل مؤسسة** — يتم تحديد نطاق كل استعلام تلقائيًا ليشمل المؤسسة النشطة.
 
-إذا كنت تقوم بتقييم الوكيل الأصلي لـ CRM، أو متتبع المشروع، أو صندوق بريد الدعم، أو أي أداة فريق، فإن الأساس متعدد المستأجرين موجود بالفعل. جميع قوالب الطرف الأول متعددة المستأجرين — راجع [Cloneable SaaS templates](/docs/cloneable-saas) للحصول على القائمة.
+إذا كنت تقوم بتقييم الوكيل الأصلي لـ CRM، أو متتبع المشروع، أو صندوق بريد الدعم، أو أي أداة فريق، فإن الأساس متعدد المستأجرين موجود بالفعل. جميع قوالب الطرف الأول متعددة المستأجرين — راجع [القوالب](/docs/cloneable-saas) للحصول على القائمة.
 
 <Diagram id="doc-block-1junwhj" title={"عضوية المنظمة وعزلها"} summary={"ينضم المستخدمون إلى المؤسسات باسم owner/admin/member. يحمل كل صف قابل للتملك org_id للمستأجر الذي يمتلكه، ولا يتسرب أي صف عبر الحدود."}>
 
@@ -117,8 +117,8 @@ description: "يعد كل تطبيق أصلي للوكيل متعدد المست
 
 هذا هو نفس المسار المستخدم لتحديد النطاق لكل مستخدم. بالنسبة للميكانيكا على مستوى SQL، وعقد `ownableColumns()`، وحراس `accessFilter` / `resolveAccess` / `assertAccess`, راجع [Security → Data Scoping](/docs/security#data-scoping) - المصدر الوحيد للحقيقة لمسار تحديد النطاق.
 
-## المستندات ذات الصلة {#related}
+## الخطوات التالية {#related}
 
-- [Authentication](/docs/authentication#organizations) — الجلسات ومقدمو الخدمات الاجتماعية وسطح إدارة المؤسسة
-- [Security → Data Scoping](/docs/security#data-scoping) — العزل على مستوى SQL، وعقد `ownableColumns()`، ووحدات حماية الوصول
-- [Multi-App Workspace](/docs/multi-app-workspace) — استضافة العديد من تطبيقات الوكيل الأصلية في monorepo واحد مع مصادقة مشتركة وRBAC
+- [**Authentication**](/docs/authentication#organizations) — الجلسات ومقدمو الخدمات الاجتماعية وسطح إدارة المؤسسة
+- [**Security — Data Scoping**](/docs/security#data-scoping) — العزل على مستوى SQL وعقد `ownableColumns()` ووحدات حماية الوصول
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — استضافة العديد من تطبيقات Agent-Native في monorepo واحد مع مصادقة مشتركة وRBAC

package/docs/content/locales/ar-SA/notifications.mdx

@@ -113,6 +113,7 @@ await notify(
 | `inbox`   | الاستمرار في الجدول `notifications`؛ يحرك الجرس UI | تشغيل دائمًا — جزء من البدائي.                                |
 | `webhook` | POST JSON إلى URL التي تم تكوينها                  | تم تعيين `NOTIFICATIONS_WEBHOOK_URL` env var عند بدء التشغيل. |
 
+تُسجَّل قنوات البريد الإلكتروني وSlack والـ webhook دائمًا إلى جانب صندوق الوارد. يفضّل التسليم عنوان URL أو المستلمين المحددين في بيانات الإشعار، ثم يعود إلى متغير البيئة المطابق. وإذا لم يُضبط أي منهما، فلا تنفّذ تلك القناة شيئًا عند الإرسال.
 تعمل قناة webhook على حل مراجع `${keys.NAME}` في كل من URL و`NOTIFICATIONS_WEBHOOK_AUTH` مقابل [secrets](/docs/security) المخصص للمالك، لذلك لا تدخل القيمة الأولية مطلقًا في سياق الوكيل. يتم فرض قوائم URL المسموح بها لكل مفتاح - نفس القاعدة التي تستخدمها أداة `web-request` للتشغيل الآلي.
 
 <Diagram id="doc-block-knshu4" title={"القنوات وخطورتها"} summary={"البريد الوارد قيد التشغيل دائمًا؛ يحتاج خطاف الويب إلى env var؛ يتم تسجيل القنوات المخصصة عند بدء التشغيل. تؤدي درجة الخطورة إلى تصميم الشارة ويتم تمريرها إلى كل قناة."}>
@@ -203,7 +204,7 @@ await notify(
 
 قم بتسجيل قناة مخصصة من أي مكون إضافي للخادم.
 
-```ts
+```ts filename="server/plugins/notifications-slack-ops.ts"
 import { registerNotificationChannel } from "@agent-native/core/notifications";
 
 registerNotificationChannel({
@@ -274,15 +275,15 @@ interface NotificationMeta {
 
 تم تركيبه على `/_agent-native/notifications/*` بواسطة البرنامج الإضافي للمسارات الأساسية. يتم تحديد نطاق كافة المسارات إلى البريد الإلكتروني للجلسة التي تمت مصادقتها.
 
-| الطريقة  | المسار                                              |
-| -------- | --------------------------------------------------- |
-| `GET`    | `/_agent-native/notifications?unread=true&limit=50` |
-| `GET`    | `/_agent-native/notifications/count`                |
-| `POST`   | `/_agent-native/notifications/:id/read`             |
-| `POST`   | `/_agent-native/notifications/read-all`             |
-| `DELETE` | `/_agent-native/notifications/:id`                  |
+| الطريقة  | المسار                                                         |
+| -------- | -------------------------------------------------------------- |
+| `GET`    | `/_agent-native/notifications?unread=true&limit=50&before=ISO` |
+| `GET`    | `/_agent-native/notifications/count`                           |
+| `POST`   | `/_agent-native/notifications/:id/read`                        |
+| `POST`   | `/_agent-native/notifications/read-all`                        |
+| `DELETE` | `/_agent-native/notifications/:id`                             |
 
-<Endpoint id="doc-block-1beurdp" title={"قائمة الإشعارات"} summary={"The route behind listNotifications() — scoped to the authenticated session's email."} method="GET" path={"/_agent-native/notifications?unread=true&limit=50"} summary={"قم بإدراج الإشعارات الأخيرة للمستخدم الحالي"} auth={"Authenticated session; results are scoped to the session's email."} params={[
+<Endpoint id="doc-block-1beurdp" title={"قائمة الإشعارات"} method="GET" path={"/_agent-native/notifications?unread=true&limit=50&before=ISO"} summary={"قم بإدراج الإشعارات الأخيرة للمستخدم الحالي"} auth={"Authenticated session; results are scoped to the session's email."} params={[
   {
     "name": "unread",
     "in": "query",
@@ -296,6 +297,13 @@ interface NotificationMeta {
     "type": "number",
     "required": false,
     "description": "Max rows to return."
+  },
+  {
+    "name": "before",
+    "in": "query",
+    "type": "string",
+    "required": false,
+    "description": "مؤشر زمني بتنسيق ISO — يعيد الإشعارات التي أُنشئت قبل هذا الوقت، لاستخدامه في ترقيم الصفحات."
   }
 ]} responses={[
   {
@@ -308,7 +316,7 @@ interface NotificationMeta {
 
 ## مكون UI {#ui}
 
-```tsx
+```tsx filename="app/components/HeaderBar.tsx"
 import { NotificationsBell } from "@agent-native/core/client/notifications";
 
 export function HeaderBar() {

package/docs/content/locales/ar-SA/processors.mdx

@@ -51,8 +51,11 @@ description: "حلقة المراقبة الداخلية/خطافات الدرا
 
 </Diagram>
 
-> [!WARNING]
-> المعالج هو **تكوين**، وليس أداة، وليس إجراءً، وليس تأليفًا DSL. تقوم المعالجات فقط بمراقبة وتعديل حالة نطاق الدفق الخاصة بها و`abort()`. ولا تحدد أبدًا سلوك التطبيق، أو تستبدل actions, أو تظهر للنموذج. تنتمي عمليات التطبيق إلى [actions](/docs/actions).
+<Callout id="doc-block-proc1cfg" tone="warning">
+
+المعالج هو **تكوين**، وليس أداة، وليس إجراءً، وليس تأليفًا DSL. تقوم المعالجات فقط بمراقبة وتعديل حالة نطاق الدفق الخاصة بها و`abort()`. ولا تحدد أبدًا سلوك التطبيق، أو تستبدل actions, أو تظهر للنموذج. تنتمي عمليات التطبيق إلى [actions](/docs/actions).
+
+</Callout>
 
 ## الخطافات {#hooks}
 
@@ -133,10 +136,13 @@ await runAgentLoop({
 
 **الحمل الصفري عند عدم الاستخدام.** تقوم الحلقة ببناء سلسلة المعالج فقط عند توفير معالج واحد على الأقل؛ عند حذف `processors` أو تركه فارغًا، لن يتم تشغيل أي من أكواد التماس وتكون الحلقة بدون تغيير بايت مقابل بايت. تعمل الخطافات بترتيب التسجيل وقد تكون متزامنة أو غير متزامنة.
 
-> [!NOTE]
-> يعتبر التماس على مستوى الحلقة هو ما يمكن تسليمه اليوم ويمكن استدعاؤه مباشرة بواسطة الوكلاء الفرعيين، A2A، MCP، والاختبارات. يعد ربط `processors` من خلال معالج الدردشة HTTP (بحيث يمكن لمحلل كل طلب تهيئتها دون الاتصال بـ `runAgentLoop` مباشرة) بمثابة توصيلات ملائمة لم يتم توصيلها بعد - قم بتكوين المعالجات في موقع الاتصال `runAgentLoop` في الوقت الحالي.
+<Callout id="doc-block-proc1note" tone="info">
+
+يعتبر التماس على مستوى الحلقة هو ما يمكن تسليمه اليوم ويمكن استدعاؤه مباشرة بواسطة الوكلاء الفرعيين، A2A، MCP، والاختبارات. يعد ربط `processors` من خلال معالج الدردشة HTTP (بحيث يمكن لمحلل كل طلب تهيئتها دون الاتصال بـ `runAgentLoop` مباشرة) بمثابة توصيلات ملائمة لم يتم توصيلها بعد - قم بتكوين المعالجات في موقع الاتصال `runAgentLoop` في الوقت الحالي.
+
+</Callout>
 
-## ذات صلة
+## ما التالي
 
 - [**Durable Resume**](/docs/durable-resume) — كيف تتغلب الحلقة على الانقطاعات دون إعادة تشغيل التأثيرات الجانبية المكتملة.
 - [**Custom Agents & Teams**](/docs/agent-teams) — يقوم الوكلاء الفرعيون بتشغيل نفس الحلقة ويمكنهم حمل المعالجات الخاصة بهم.