@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/hi-IN/cross-app-sso.md

@@ -0,0 +1,185 @@
+---
+title: "क्रॉस-ऐप SSO"
+description: "पहचान प्राधिकरण के रूप में डिस्पैच के साथ पहचान फेडरेशन के माध्यम से प्रत्येक होस्ट किए गए एजेंट-नेटिव ऐप में एक बार साइन इन करें - प्रति ऐप ऑप्ट-इन, एक एकल एनवी संस्करण के साथ प्रतिवर्ती।"
+---
+
+# क्रॉस-ऐप SSO
+
+`*.agent-native.com` पर प्रत्येक होस्ट किया गया ऐप अपने **स्वयं के अलग उपयोगकर्ता स्टोर** के साथ अपनी स्वयं की तैनाती चलाता है। `mail.agent-native.com` और `calendar.agent-native.com` एक डेटाबेस, एक सत्र तालिका या एक कुकी डोमेन साझा नहीं करते हैं। इसलिए "एक बार साइन इन करें, हर ऐप का उपयोग करें" एक साझा कुकी नहीं हो सकती - इसे **पहचान महासंघ** होना चाहिए, जिसमें [Dispatch](/docs/dispatch) कार्यक्षेत्र के लिए पहचान प्राधिकरण के रूप में कार्य करेगा।
+
+यह वही ट्रस्ट प्रिमिटिव [A2A](/docs/a2a-protocol) और [External Agents](/docs/external-agents) पहले से ही उपयोग किया जाता है - अनुरोध सीमा पर सत्यापित एक `A2A_SECRET`-हस्ताक्षरित JWT - एजेंट-टू-एजेंट कॉल के बजाय मानव साइन-इन पथ पर लागू किया जाता है।
+
+> **एकीकृत परिनियोजन बनाम प्रति-डोमेन परिनियोजन।** यदि आप सभी ऐप्स को एक ही मूल (`your-agents.com/mail`, `your-agents.com/calendar`) पर होस्ट करते हैं, तो आपको पहले से ही एक एकल कुकी डोमेन के माध्यम से साझा लॉगिन मिलता है - किसी फेडरेशन की आवश्यकता नहीं है। क्रॉस-ऐप SSO केवल तभी आवश्यक है जब ऐप्स अलग-अलग डोमेन पर चलते हों। [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment) देखें.
+
+## क्या और क्यों {#what-why}
+
+प्रति-ऐप उपयोगकर्ता स्टोर का मतलब है कि ब्राउज़र कुकी के लिए ऐसी कोई एक जगह नहीं है जिस पर हर ऐप भरोसा करता हो। फ़ेडरेशन मॉडल इसके बजाय एक ऐप को - **डिस्पैच** - पहचान प्राधिकारी के रूप में नाम देता है। कोई अन्य ऐप "यह व्यक्ति कौन है?" सौंप सकता है। भेजने के लिए, उपयोगकर्ता के सत्यापित ईमेल का एक अल्पकालिक हस्ताक्षरित दावा वापस प्राप्त करें, और फिर **उसे ईमेल द्वारा अपने स्थानीय खाते से लिंक करें**।
+
+लिंकिंग नियम जानबूझकर संकीर्ण और योगात्मक है:
+
+- **मौजूदा समान-ईमेल उपयोगकर्ता → लिंक किया गया।** स्थानीय खाते का सत्यापित ईमेल से मिलान किया जाता है और उसी रूप में पुन: उपयोग किया जाता है। इसे **कभी भी संशोधित, पुनर्नामित या हटाया नहीं गया** - फ़ेडरेशन परत केवल इसे पढ़ती है और इसके लिए एक सत्र तैयार करती है।
+- **नया ईमेल → बनाया गया।** उस सत्यापित ईमेल के लिए एक नया स्थानीय खाता बनाया जाता है, फिर एक सामान्य स्थानीय सत्र शुरू किया जाता है।
+
+यह लोगों को लॉग आउट करने के बावजूद रोलआउट को सुरक्षित बनाता है। **लॉगआउट अपेक्षित है।** जब कोई ऐप इसे चालू करता है, तो मौजूदा सत्र समाप्त हो जाते हैं और उपयोगकर्ता डिस्पैच के माध्यम से पुनः प्रमाणित होते हैं। लेकिन वे हमेशा अपने सभी डेटा बरकरार रखते हुए **उसी ईमेल-मिलान वाले खाते में वापस लॉग इन करते हैं**, क्योंकि पहचान पंक्तियाँ केवल कभी \_जोड़ी जाती हैं - कभी भी नष्ट नहीं की जाती हैं, उनका नाम नहीं बदला जाता है, या दोबारा इंगित नहीं किया जाता है।
+
+## यह कैसे काम करता है {#how-it-works}
+
+प्रवाह एक मानक अधिकृत → हस्ताक्षरित-टोकन → कॉलबैक रीडायरेक्ट है, जिसमें ईमेल ही एकमात्र ऐसी चीज है जो विश्वास सीमा को पार करती है।
+
+```an-diagram title="Identity federation flow" summary="Dispatch authenticates the human and returns a short-lived signed assertion of one thing — the verified email. The app links by email and mints its own local session."
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>Client app</strong><small class=\"diagram-muted\">own user store</small></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill\">authorize</span></div><div class=\"diagram-card\" data-rough><strong>Dispatch</strong><small class=\"diagram-muted\">identity authority</small><span class=\"diagram-pill accent\">authenticates human</span></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill accent\">302 + signed JWT</span></div><div class=\"diagram-card\" data-rough><strong>App callback</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">JIT-link by email</span><span class=\"diagram-pill ok\">mint local session</span></div></div>",
+  "css": ".diagram-sso{display:flex;align-items:stretch;gap:12px;flex-wrap:wrap}.diagram-sso .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px}.diagram-sso .diagram-step{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px}.diagram-sso .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+1. **ऐप → डिस्पैच (अधिकृत)।** ऐप उपयोगकर्ता को पहचान प्राधिकरण के पास भेजता है:
+
+   ```
+   GET https://dispatch.agent-native.com/_agent-native/identity/authorize
+       ?app=<requesting-app>
+       &redirect_uri=<app-callback-url>
+       &state=<csrf-state>
+   ```
+
+   ```an-api title='पहचान अधिकृत समापन बिंदु'
+   {
+     "विधि": "GET",
+     "पथ": "/_agent-native/identity/authorize",
+     "सारांश": "डिस्पैच (पहचान प्राधिकरण) मानव को प्रमाणित करता है और हस्ताक्षरित पहचान टोकन के साथ वापस रीडायरेक्ट करता है",
+     "auth": "डिस्पैच सत्र (यदि कोई नहीं है तो इंटरैक्टिव लॉगिन)",
+     "पैराम्स": [
+       { "नाम": "ऐप", "इन": "क्वेरी", "टाइप": "स्ट्रिंग", "आवश्यक": सत्य, "विवरण": "अनुरोध करने वाला ऐप पहचानकर्ता।" },
+       { "नाम": "रीडायरेक्ट_यूरी", "इन": "क्वेरी", "टाइप": "स्ट्रिंग", "आवश्यक": सत्य, "विवरण": "ऐप कॉलबैक URL। एक सख्त अनुमति सूची (`*.agent-native.com` या डिफ़ॉल्ट रूप से लोकलहोस्ट) के खिलाफ मान्य।" },
+       { "नाम": "राज्य", "में": "क्वेरी", "प्रकार": "स्ट्रिंग", "आवश्यक": सत्य, "विवरण": "CSRF स्थिति रीडायरेक्ट पर वापस प्रतिध्वनित हुई।" }
+     ],
+     "प्रतिक्रियाएँ": [
+       {"स्थिति": "302", "विवरण": "अल्पकालिक `A2A_SECRET`-हस्ताक्षरित पहचान JWT (`scope: \"identity\"`, `exp` ≤ 2 मिनट) और मूल `state` लेकर `redirect_uri` पर रीडायरेक्ट करता है।" },
+       {"स्थिति": "400", "विवरण": "`redirect_uri` विफल अनुमति सूची सत्यापन (क्रॉस-ओरिजिन, स्कीम-सापेक्ष `//host`, या असूचीबद्ध प्रत्यय)।" }
+     ]
+   }
+   ```
+
+2. **डिस्पैच मानव को प्रमाणित करता है।** यदि उपयोगकर्ता के पास पहले से ही डिस्पैच सत्र है, तो यह पारदर्शी है। यदि नहीं, तो डिस्पैच अपना सामान्य लॉगिन दिखाता है (ईमेल/पासवर्ड, Google, आदि - [Authentication](/docs/authentication) देखें)। यहां डिस्पैच केवल एक नियमित एजेंट-मूल ऐप है; यह कोई विशेष प्रमाणीकरण मोड नहीं चला रहा है।
+
+3. **डिस्पैच → ऐप (हस्ताक्षरित पहचान टोकन)।**डिस्पैच एक सख्त अनुमति सूची के खिलाफ `redirect_uri` को मान्य करता है और 302-रीडायरेक्ट को ऐप के `redirect_uri` पर अल्पकालिक **`A2A_SECRET`-हस्ताक्षरित पहचान JWT** के साथ वापस भेजता है। टोकन के दावे जानबूझकर न्यूनतम हैं:
+
+   | दावा         | अर्थ                                                        |
+   | ------------ | ----------------------------------------------------------- |
+   | `sub`        | पहचान प्राधिकारी पर स्थिर उपयोगकर्ता आईडी                   |
+   | `email`      | उपयोगकर्ता का **सत्यापित** ईमेल - एकमात्र सम्मिलित कुंजी    |
+   | `name`       | प्रदर्शन नाम (गैर-आधिकारिक, केवल UI के लिए)                 |
+   | `org_domain` | कार्यस्थान/संगठन डोमेन, जब मौजूद हो                         |
+   | `scope`      | हमेशा `"identity"` - यह टोकन केवल साइन-इन को अधिकृत करता है |
+   | `exp`        | **≤ 2 मिनट** अंक से                                         |
+
+4. **ऐप सत्यापित करता है और ईमेल द्वारा JIT-लिंक करता है।** ऐप अपने स्वयं के `A2A_SECRET` के साथ टोकन हस्ताक्षर को सत्यापित करता है, `scope: "identity"` और `exp` की जांच करता है, फिर **सत्यापित ईमेल द्वारा सख्ती से समय-समय पर लिंक करता है**:
+   - यदि उस ईमेल वाला कोई स्थानीय उपयोगकर्ता मौजूद है → इसे अपरिवर्तित पुन: उपयोग करें।
+   - यदि नहीं → उस ईमेल के लिए एक स्थानीय उपयोगकर्ता बनाएं।
+
+5. **ऐप एक सामान्य स्थानीय सत्र शुरू करता है।** यहां से उपयोगकर्ता के पास उस ऐप के अपने स्टोर में एक सामान्य स्थानीय सत्र होता है - प्रत्येक मौजूदा एक्सेस चेक, ऑर्ग स्कोपिंग और एक्शन गार्ड बिल्कुल पहले की तरह काम करता है। महासंघ केवल सामने के दरवाजे पर हुआ।
+
+### ऑप्ट इन करना {#opt-in}
+
+कोई ऐप **केवल** तभी भाग लेता है जब यह पर्यावरण चर उसके परिनियोजन पर सेट किया गया हो:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+- **सेट** → ऐप एक **"Agent-Native के साथ साइन इन करें"** विकल्प दिखाता है जो उपरोक्त प्रवाह को चलाता है। प्रत्यक्ष स्थानीय लॉगिन (ईमेल/पासवर्ड, Google) अभी भी इसके साथ काम करता है।
+- **अनसेट (डिफ़ॉल्ट)** → **शून्य व्यवहार परिवर्तन।** ऐप बिल्कुल वैसे ही प्रमाणित करता है जैसे उसने पहले किया था; फ़ेडरेशन कोड पथ निष्क्रिय है. कोई स्कीमा परिवर्तन नहीं है और माइग्रेट करने के लिए कुछ भी नहीं है, इसलिए वेरिएबल को चालू या बंद करना किसी भी समय पूरी तरह से उलटा हो सकता है।
+
+## सुरक्षा {#security}
+
+पूरा मॉडल जानबूझकर कुछ छोटी-छोटी गारंटियों पर टिका है:
+
+- **अल्पकालिक हस्ताक्षरित टोकन।** पहचान का दावा एक `A2A_SECRET`-हस्ताक्षरित JWT है जिसकी **≤ 2-मिनट** समाप्ति और `scope: "identity"` है। यह एकल साइन-इन को अधिकृत करता है और इसे लंबे समय तक दोबारा नहीं चलाया जा सकता है या API/A2A एक्सेस के लिए दोबारा उपयोग नहीं किया जा सकता है।
+- **सख्त `redirect_uri` अनुमति सूची।** डिस्पैच केवल डिफ़ॉल्ट रूप से `*.agent-native.com` या लोकलहोस्ट पर रीडायरेक्ट होता है। मनमाना, योजना-सापेक्ष (`//host`), और क्रॉस-ओरिजिन रीडायरेक्ट लक्ष्य अस्वीकार कर दिए जाते हैं, इसलिए प्राधिकरण को ओपन-रीडायरेक्ट या टोकन-एक्सफ़िल्ट्रेशन ऑरेकल में नहीं बदला जा सकता है।
+- **सत्यापित टोकन से केवल-ईमेल से जुड़ें।** विश्वास सीमा को पार करने वाली एकमात्र चीज़ हस्ताक्षरित टोकन में सत्यापित ईमेल है। ऐप उपयोगकर्ता आईडी, भूमिका, संगठन सदस्यता, या वायर से किसी भी विशेषाधिकार प्राप्त स्थिति को स्वीकार नहीं करता है - यह मिलान किए गए खाते से स्थानीय रूप से सब कुछ प्राप्त करता है।
+- **एडिटिव-ओनली आइडेंटिटी लिखता है।** लिंक करने से या तो मौजूदा समान-ईमेल खाते को अछूता पुन: उपयोग किया जाता है या एक नया डाला जाता है। इस पथ पर कभी भी पहचान पंक्तियों को अद्यतन, नाम बदलना, पुनः इंगित करना या हटाना नहीं होता है।
+- **डिफ़ॉल्ट रूप से बंद।** `AGENT_NATIVE_IDENTITY_HUB_URL` के अनसेट होने पर संपूर्ण सुविधा निष्क्रिय हो जाती है।
+
+```an-callout
+{
+  "tone": "success",
+  "body": "**Safe to enable, safe to revert.** Identity writes are **additive only** — an existing same-email account is reused untouched, and a new email just inserts a fresh row. There is no schema change and nothing to migrate, so flipping `AGENT_NATIVE_IDENTITY_HUB_URL` on or off is fully reversible at any time, per app."
+}
+```
+
+जस्ट-इन-टाइम लिंक एक एकल निर्णय है जो पूरी तरह से सत्यापित ईमेल पर कुंजीबद्ध है:
+
+```an-diagram title="JIT-link decision" summary="Linking is keyed on the verified email and is additive only — existing accounts are reused unchanged, new emails create a fresh local user."
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>Verified email<br><small class=\"diagram-muted\">from signed identity JWT</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-branch\"><div class=\"diagram-box\" data-rough>Local user exists?<span class=\"diagram-pill ok\">yes &rarr; reuse unchanged</span><span class=\"diagram-pill accent\">no &rarr; create local user</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Mint normal local session</div></div></div>",
+  "css": ".diagram-jit{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-node{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-jit .diagram-branch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-box{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-jit .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## स्वयं-होस्टिंग {#self-hosting}
+
+कोई भी डिस्पैच परिनियोजन पहचान केंद्र के रूप में काम कर सकता है - आप `dispatch.agent-native.com` तक सीमित नहीं हैं। अपने डिस्पैच इंस्टेंस को इंगित करने के लिए प्रत्येक क्लाइंट ऐप पर `AGENT_NATIVE_IDENTITY_HUB_URL` सेट करें:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**रीडायरेक्ट अनुमति सूची।** हब (डिस्पैच) टोकन जारी करने से पहले अधिकृत एंडपॉइंट पर `redirect_uri` को मान्य करता है। अनुमति सूची `templates/dispatch/server/lib/identity-sso.ts`:
+
+- **डिफ़ॉल्ट:** `*.agent-native.com` और केवल लोकलहोस्ट (`DEFAULT_ALLOWED_HOST_SUFFIXES` स्थिरांक)।
+- **इसे विस्तारित करना:** अतिरिक्त होस्ट प्रत्ययों की अल्पविराम से अलग की गई सूची के साथ डिस्पैच परिनियोजन पर `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` पर्यावरण चर सेट करें:
+
+  ```बैश
+  # डिफ़ॉल्ट के अलावा yourcompany.com उपडोमेन को अनुमति दें
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES='.yourcompany.com,.steasing.yourcompany.com'
+  ```
+
+  प्रत्येक प्रविष्टि को एक डॉट-प्रीफिक्स्ड प्रत्यय (`.yourcompany.com`) के लिए सामान्यीकृत किया जाता है, इसलिए एक प्रत्यय जांच पर्याप्त और कम से कम फ़ुटगन-प्रोन दोनों है - सिंक में रखने के लिए कोई प्रति-ऐप सूची नहीं है। ऐसी प्रविष्टियाँ जो हर चीज़ से मेल खाती हैं (खाली या केवल `.`) फ़िल्टर कर दी जाती हैं।
+
+- **लोकलहोस्ट** को `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` की परवाह किए बिना क्लाइंट-साइड ऐप्स के स्थानीय विकास के लिए हमेशा अनुमति दी जाती है।
+
+`IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` के बिना, एक स्व-होस्टेड डिस्पैच केवल `*.agent-native.com` पर ऐप्स को टोकन जारी कर सकता है। अन्य डोमेन को अनलॉक करने के लिए अपने डिस्पैच परिनियोजन पर env var सेट करें।
+
+## कैनरी रोलआउट रनबुक {#canary-rollout}
+
+कटओवर और रोलबैक **प्रति ऐप परिनियोजन के लिए एक एकल पर्यावरण चर** हैं। एक समय में एक ऐप रोल आउट करें, सत्यापित करें, फिर विस्तृत करें। हर ऐप पर एक साथ वेरिएबल सेट न करें।
+
+**1. कोड परिनियोजित करें - कोई व्यवहार परिवर्तन नहीं।**
+`AGENT_NATIVE_IDENTITY_HUB_URL` के साथ प्रत्येक ऐप पर रिलीज़ भेजें **हर जगह अनसेट**। पुष्टि करें कि सामान्य लॉगिन अभी भी कुछ ऐप्स पर काम करते हैं।
+
+**2. एक समय में ONE ऐप पर कैनरी सक्षम करें।**
+सेट, केवल एक परिनियोजन पर:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+हर दूसरे ऐप के वातावरण को अनसेट छोड़ दें। पुनः तैनात/पुनः प्रारंभ करें ताकि यह वेरिएबल को ग्रहण कर सके।
+
+**3. कैनरी सत्यापित करें (चेकलिस्ट).**
+
+- ऐप से **आउट** लॉग इन करें।
+- लॉगिन स्क्रीन अब **"Agent-Native के साथ साइन इन करें"** दिखाती है। इसे क्लिक करें.
+- आपको **डिस्पैच** पर ले जाया जाता है और इसका लॉगिन पूरा करें (या यदि पहले से ही वहां साइन इन है तो सीधे आगे बढ़ें)।
+- आपको **ऐप पर वापस भेज दिया गया है, लॉग इन** किया गया है - और यह **वही पहले से मौजूद खाता** (वही ईमेल) है जो आपके पास पहले था, नया नहीं।
+- **ऐप डेटा बरकरार है** - आपके मौजूदा रिकॉर्ड, सेटिंग्स और संगठन का दायरा बिल्कुल वैसा ही है जैसा वे थे।
+- **मौजूदा प्रत्यक्ष लॉगिन अभी भी काम करते हैं** - ईमेल/पासवर्ड और Google साइन-इन SSO के साथ काम करना जारी रखते हैं।
+
+यदि कोई जांच विफल हो जाती है, तो सीधे चरण 4 (रोलबैक) पर जाएं - यह तत्काल और डेटा-सुरक्षित है।
+
+**4. ऐप-दर-ऐप विस्तृत करें.**
+एक बार एक ऐप सत्यापित हो जाने पर, अगले ऐप के लिए चरण 2-3 दोहराएं - एक समय में एक परिनियोजन पर `AGENT_NATIVE_IDENTITY_HUB_URL` सेट करना। कभी भी बैच-सक्षम न करें.
+
+**5. रोलबैक = उस ऐप के परिनियोजन पर env var को अनसेट करें।**
+किसी भी ऐप को वापस लाने के लिए, **उस ऐप के वातावरण से `AGENT_NATIVE_IDENTITY_HUB_URL` को हटा दें और उसे पुनः तैनात/पुनः प्रारंभ करें।** ऐप तुरंत अपने पूर्व प्रमाणीकरण व्यवहार पर वापस आ जाता है। **पूर्ववत करने के लिए कोई डेटा परिवर्तन नहीं है** - पहचान पंक्तियाँ केवल कभी जोड़ी गई थीं, और वेरिएबल को अनसेट करने से फ़ेडरेशन पथ फिर से निष्क्रिय हो जाता है। प्रत्येक ऐप का कटओवर और रोलबैक स्वतंत्र और प्रतिवर्ती है।
+
+> प्रत्येक ऐप सक्षम होने पर रोलआउट उपयोगकर्ताओं को लॉग आउट कर देता है (वे डिस्पैच के माध्यम से पुनः प्रमाणीकरण करते हैं), लेकिन वे हमेशा ** डेटा बरकरार रखते हुए उसी ईमेल-मिलान वाले खाते में वापस लॉग इन करते हैं**, क्योंकि पहचान पंक्तियां कभी नष्ट नहीं होती हैं या उनका नाम नहीं बदला जाता है - केवल जोड़ा जाता है।
+
+## संबंधित {#related}
+
+- [Authentication](/docs/authentication) - स्थानीय प्रमाणीकरण मोड, सत्र, संगठन, `A2A_SECRET` env संस्करण।
+- [A2A Protocol](/docs/a2a-protocol) - हस्ताक्षरित-JWT, सीमा-पर-सत्यापित विश्वास मॉडल यह पुन: उपयोग करता है।
+- [External Agents](/docs/external-agents) - वही `A2A_SECRET`-हस्ताक्षरित पहचान पैटर्न एजेंट कनेक्शन और डीप लिंक पर लागू होता है।
+- [Dispatch](/docs/dispatch) - कार्यक्षेत्र पहचान प्राधिकरण और रूटिंग हब।
+- [Security & Data Scoping](/docs/security) - केवल-योगात्मक डेटा लिखना और प्रति-खाता स्कोपिंग।
+- [Multi-App Workspaces](/docs/multi-app-workspace) - एकीकृत एकल-मूल परिनियोजन जो क्रॉस-डोमेन SSO से पूरी तरह बचता है।

package/corpus/core/docs/content/locales/hi-IN/database.md

@@ -0,0 +1,183 @@
+---
+title: "डेटाबेस"
+description: "एक पोर्टेबल SQL डेटाबेस को अपने एजेंट-नेटिव ऐप से कनेक्ट करें और प्रदाता-अज्ञेयवादी Drizzle कोड लिखें।"
+---
+
+# डेटाबेस
+
+एजेंट-नेटिव ऐप्स [Drizzle ORM](https://orm.drizzle.team) का उपयोग करते हैं और पोर्टेबल SQL बैकएंड का समर्थन करते हैं। स्थानीय विकास से परे किसी भी चीज़ के लिए, `DATABASE_URL` सेट करके एक सतत SQL डेटाबेस - Postgres, libSQL/Turso, या कोई अन्य Drizzle-संगत बैकएंड कनेक्ट करें। जब वह वेरिएबल अनसेट हो जाता है, तो ऐप एक शून्य-कॉन्फिग स्थानीय SQLite फ़ाइल पर वापस आ जाता है ताकि आप तुरंत विकास शुरू कर सकें।
+
+```an-diagram title="One schema, many backends" summary="App code uses the framework's dialect-agnostic helpers. The dialect is auto-detected from DATABASE_URL at runtime; unset means a local SQLite file."
+{
+  "html": "<div class=\"diagram-db\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">@agent-native/core/db/schema</span><small class=\"diagram-muted\">table · text · integer · real · now</small><small class=\"diagram-muted\">+ Drizzle query DSL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>DATABASE_URL<br><small class=\"diagram-muted\">dialect auto-detected</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Postgres<br><small class=\"diagram-muted\">Neon · Supabase</small></span><span class=\"diagram-pill\">libSQL / Turso</span><span class=\"diagram-pill\">Cloudflare D1</span><span class=\"diagram-pill warn\">SQLite file<br><small class=\"diagram-muted\">unset = local dev only</small></span></div></div>",
+  "css": ".diagram-db{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-db .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-db .diagram-arrow{font-size:22px;line-height:1}.diagram-db .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+}
+```
+
+## स्थानीय डिफ़ॉल्ट: SQLite फ़ाइल {#default-sqlite}
+
+जब `DATABASE_URL` सेट नहीं होता है, तो ऐप `data/app.db` पर एक SQLite डेटाबेस बनाता है। यह स्थानीय विकास के लिए शून्य-कॉन्फ़िगरेशन डिफ़ॉल्ट है - किसी सेटअप की आवश्यकता नहीं है। यह केवल विकास के लिए है; उत्पादन के लिए, `DATABASE_URL` को लगातार SQL डेटाबेस पर सेट करें।
+
+तैनात ऐप्स के लिए उस स्थानीय फ़ाइल पर भरोसा न करें। कंटेनर, सर्वर रहित फ़ंक्शन और पूर्वावलोकन वातावरण अपने फ़ाइल सिस्टम को रीसेट कर सकते हैं, जिसका अर्थ है कि स्थानीय SQLite फ़ाइल पुनरारंभ के बीच गायब हो सकती है। उत्पादन उपयोग से पहले `DATABASE_URL` को लगातार होस्ट किए गए डेटाबेस पर सेट करें।
+
+## उत्पादन डेटाबेस कनेक्ट करना {#production}
+
+होस्ट किए गए डेटाबेस को कनेक्ट करने के लिए अपनी `.env` फ़ाइल या परिनियोजन-प्रदाता वातावरण में `DATABASE_URL` सेट करें। टरसो की आवश्यकता नहीं है; जो भी Drizzle-संगत SQL बैकएंड आपकी तैनाती के लिए उपयुक्त हो, उसका उपयोग करें:
+
+```bash
+# Neon Postgres
+DATABASE_URL=postgres://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/mydb?sslmode=require
+
+# Supabase Postgres
+DATABASE_URL=postgres://postgres.xxxx:pass@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+
+# Plain Postgres
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+
+# Turso (libSQL)
+DATABASE_URL=libsql://my-db-org.turso.io
+DATABASE_AUTH_TOKEN=your-token
+```
+
+फ्रेमवर्क URL से बोली का स्वतः पता लगाता है और तदनुसार Drizzle को कॉन्फ़िगर करता है। अंतर्निहित एडाप्टर Postgres URLs, libSQL/Turso URLs, SQLite फ़ाइल URLs और क्लाउडफ्लेयर D1 बाइंडिंग को कवर करते हैं। सामान्य उत्पादन विकल्पों में नियॉन, सुपाबेस, टुर्सो/libSQL, सादा Postgres, टिकाऊ SQLite, और उपलब्ध होने पर Builder.io-प्रबंधित वातावरण शामिल हैं।
+
+## Builder.io प्रबंधित डेटाबेस {#builder-managed}
+
+_योजनाबद्ध (अभी तक उपलब्ध नहीं):_ Builder.io से कनेक्ट होने पर, आपका ऐप स्वचालित रूप से प्रावधानित प्रबंधित डेटाबेस का उपयोग करने में सक्षम होगा, बिना किसी कनेक्शन स्ट्रिंग की आवश्यकता के।
+
+## डीबी क्लाइंट कहां रहता है {#db-client}
+
+प्रत्येक टेम्पलेट `@agent-native/core/db` से `createGetDb(schema)` को कॉल करके एक आलसी, सिंगलटन Drizzle क्लाइंट बनाता है। विहित स्थान `server/db/index.ts` है:
+
+```ts
+// server/db/index.ts
+import { createGetDb } from "@agent-native/core/db";
+import * as schema from "./schema.js";
+
+export const getDb = createGetDb(schema);
+```
+
+इस टेम्पलेट-स्थानीय पथ से `getDb` आयात करें - मार्गों में `../../server/db/index.js`, actions में `../server/db/index.js` - सीधे `@agent-native/core` के बजाय। मुख्य निर्यात एक सामान्य अलिखित उदाहरण लौटाता है; टेम्पलेट का `getDb()` आपके स्कीमा प्रकारों को वहन करता है। actions और कस्टम रूट प्रत्येक इसे कैसे आयात करते हैं, इसके लिए [Server](/docs/server#request-context) देखें।
+
+## बोली-अज्ञेयवादी स्कीमा और प्रश्न {#schema}
+
+ऐप डेटाबेस कोड को Drizzle की स्कीमा और क्वेरी DSL का उपयोग करना चाहिए ताकि यह सभी प्रदाताओं पर चल सके। उत्पाद कोड में कभी भी SQLite-केवल सिंटैक्स (`INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`) या Postgres-केवल सिंटैक्स न लिखें।
+
+`@agent-native/core/db/schema` से फ्रेमवर्क के स्कीमा हेल्पर्स का उपयोग करें:
+
+```ts
+import { table, text, integer, real, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  priority: integer("priority").notNull().default(0),
+  weight: real("weight"),
+  done: integer("done", { mode: "boolean" }).notNull().default(false),
+  ownerEmail: text("owner_email").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+| सहायक     | उद्देश्य                                                          |
+| --------- | ----------------------------------------------------------------- |
+| `table`   | एक तालिका परिभाषित करें - `pgTable` या `sqliteTable` को प्रतिनिधि |
+| `text`    | टेक्स्ट कॉलम, `{ enum: [...] }` का समर्थन करता है                 |
+| `integer` | पूर्णांक स्तंभ, `{ mode: "boolean" }` मैप्स Postgres बूलियन       |
+| `real`    | फ्लोट कॉलम - SQLite पर `real`, Postgres पर `double precision`     |
+| `now`     | `.default(now())` के लिए द्वंद्व-अज्ञेयवादी वर्तमान टाइमस्टैम्प   |
+
+उपरोक्त `tasks` तालिका प्रत्येक बैकएंड पर समान कॉलम को परिभाषित करती है:
+
+```an-schema title="The tasks table" summary="Defined once with the framework helpers; the dialect is chosen at runtime from DATABASE_URL."
+{
+  "entities": [
+    {
+      "id": "tasks",
+      "name": "tasks",
+      "note": "Domain table. Add owner_email (or ...ownableColumns()) so SQL-level scoping can filter rows to the authenticated user.",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true, "nullable": false },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "priority", "type": "integer", "nullable": false, "note": "default 0" },
+        { "name": "weight", "type": "real", "nullable": true },
+        { "name": "done", "type": "integer (boolean mode)", "nullable": false, "note": "default false; maps to a Postgres boolean" },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "enables data scoping" },
+        { "name": "created_at", "type": "text", "nullable": false, "note": "default now()" }
+      ]
+    }
+  ]
+}
+```
+
+कभी भी सीधे `drizzle-orm/sqlite-core` या `drizzle-orm/pg-core` से आयात न करें। हमेशा `@agent-native/core/db/schema` का उपयोग करें।
+
+उपयोगकर्ता-सामना वाले डेटा को संग्रहीत करने वाली तालिकाओं में एक `owner_email` कॉलम शामिल होना चाहिए ताकि फ्रेमवर्क का SQL-स्तरीय स्कोपिंग प्रमाणित उपयोगकर्ता के लिए पंक्तियों को फ़िल्टर कर सके - [Security](/docs/security#data-scoping) देखें। तालिकाएँ जो अन्य उपयोगकर्ताओं या संगठनों के साथ साझा करने का भी समर्थन करती हैं, उन्हें इसके बजाय `...ownableColumns()` फैलाना चाहिए, जो एक कॉल में `owner_email`, `org_id`, और `visibility` जोड़ता है - [Sharing](/docs/sharing#building) देखें।
+
+पढ़ने और लिखने के लिए, Drizzle के क्वेरी बिल्डर और `drizzle-orm` के पोर्टेबल ऑपरेटरों का उपयोग करें:
+
+```ts
+import { and, desc, eq } from "drizzle-orm";
+import { getDb } from "../server/db/index.js";
+import { tasks } from "../server/db/schema.js";
+
+const db = getDb();
+
+const openTasks = await db
+  .select()
+  .from(tasks)
+  .where(and(eq(tasks.ownerEmail, userEmail), eq(tasks.done, false)))
+  .orderBy(desc(tasks.createdAt));
+
+await db.update(tasks).set({ done: true }).where(eq(tasks.id, taskId));
+```
+
+## कच्चे SQL एस्केप हैच {#raw-sql}
+
+रॉ SQL डिफ़ॉल्ट ऐप-कोड API नहीं है। इसका उपयोग केवल एडिटिव माइग्रेशन, स्वास्थ्य जांच, सावधानीपूर्वक समीक्षा की गई उन्नत क्वेरीज़ के लिए करें जिन्हें Drizzle व्यक्त नहीं कर सकता है, या एकमुश्त रखरखाव के लिए। इसे मानकीकृत और बोली-अज्ञेयवादी रखें। Drizzle स्कीमा में टाइमस्टैम्प के लिए, `.default(now())` को प्राथमिकता दें; माइग्रेशन SQL के लिए, `runMigrations()` का उपयोग करें ताकि फ्रेमवर्क-समर्थित संगतता पुनर्लेखन और बोली-गेटेड कथन केंद्रीकृत रहें।
+
+ऐसे मामलों के लिए जहां आपको वास्तव में Drizzle क्वेरी के अलावा कच्चे SQL की आवश्यकता है:
+
+- `getDbExec()` - Postgres के लिए `?` पैरामीटर को `$1` में स्वचालित रूप से परिवर्तित करता है
+- `isPostgres()` - रनटाइम बोली जांच
+- `intType()` - वर्तमान बोली के लिए सही पूर्णांक प्रकार लौटाता है
+
+## माइग्रेशन और स्कीमा अपडेट {#migrations}
+
+होस्ट किए गए वातावरण में, एकाधिक परिनियोजन पूर्वावलोकन, शाखाएं और उत्पादन सर्वर एक ही अंतर्निहित डेटाबेस साझा करते हैं। इसलिए, डेटा हानि और सेवा व्यवधान से बचने के लिए डेटाबेस स्कीमा अपडेट को सख्त बाधाओं का पालन करना चाहिए।
+
+### "शून्य विनाशकारी परिवर्तन" नियम
+
+सभी डेटाबेस स्कीमा अद्यतन **सख्ती से योगात्मक** होने चाहिए।
+
+- **टेबल या कॉलम न गिराएं।**
+- **टेबल या कॉलम का नाम न बदलें।** किसी कॉलम या टेबल का नाम बदलना एक बूंद की तरह दिखता है + Drizzle के लिए अनुक्रम बनाएं, जो आपके मौजूदा उत्पादन डेटा को स्थायी रूप से हटा देगा।
+- यदि किसी कॉलम का नाम बदलने या बदलने की आवश्यकता है, तो पुराने कॉलम के साथ नया कॉलम जोड़ें, अपने एप्लिकेशन कोड को पढ़ने/लिखने दोनों के लिए अपडेट करें, डेटा को माइग्रेट करें, और पुराने कॉलम को केवल तभी हटाएं जब कोई सक्रिय तैनाती इसे संदर्भित न कर रही हो।
+
+> [!WARNING]
+> **कभी भी उत्पादन डेटाबेस के विरुद्ध `drizzle-kit push` न चलाएं।**
+> टेम्प्लेट डेटाबेस स्कीमा केवल ऐप-विशिष्ट डोमेन तालिकाओं को परिभाषित करते हैं; वे केंद्रीय फ्रेमवर्क तालिकाओं (`user`, `session`, `application_state`, आदि) को परिभाषित नहीं करते हैं। यदि आप उत्पादन के विरुद्ध `drizzle-kit push` चलाते हैं, तो Drizzle इन फ्रेमवर्क तालिकाओं को "स्कीमा में नहीं" के रूप में पहचानेगा और उन्हें छोड़ने का प्रयास करेगा, जिससे तत्काल सिस्टम-व्यापी विफलता और डेटा हानि होगी।
+
+### सुरक्षित प्रवासन पथ
+
+सीधे पुश करने के बजाय, स्कीमा परिवर्तन को एप्लिकेशन स्टार्टअप पर निष्पादित SQL माइग्रेशन के माध्यम से लागू किया जाना चाहिए। फ्रेमवर्क के `runMigrations()` हेल्पर को लागू करके सर्वर प्लगइन (उदाहरण के लिए, `server/plugins/db.ts`) के भीतर एडिटिव माइग्रेशन लागू करें:
+
+```an-annotated-code title="An additive migration plugin"
+{
+  "filename": "server/plugins/db.ts",
+  "language": "ts",
+  "code": "import { runMigrations } from \"@agent-native/core/db\";\n\nexport default runMigrations(\n  [\n    {\n      version: 1,\n      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,\n    },\n    {\n      // Dialect-gated: runs only on the matching backend. Omit the other key\n      // to make it a no-op on that dialect.\n      version: 2,\n      sql: {\n        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,\n        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only\n      },\n    },\n  ],\n  { table: \"my_app_migrations\" },\n);",
+  "annotations": [
+    { "lines": "6-7", "label": "Additive only", "note": "`ADD COLUMN IF NOT EXISTS` is safe to re-run and never drops data. Renames look like drop+create to Drizzle, so add-then-migrate instead." },
+    { "lines": "13-16", "label": "Dialect gating", "note": "Pass an object keyed by dialect to run different SQL per backend. Make the other key a no-op (`SELECT 1`) for Postgres-only or SQLite-only features." },
+    { "lines": "19", "label": "Per-app version table", "note": "Each app tracks its own applied versions so migrations are idempotent across restarts and instances." }
+  ]
+}
+```
+
+## पर्यावरण चर {#environment-variables}
+
+| वेरिएबल               | उद्देश्य                                                                                      |
+| --------------------- | --------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`        | स्थायी SQL कनेक्शन स्ट्रिंग (अनसेट = स्थानीय SQLite, जो केवल स्थानीय विकास के लिए टिकाऊ है)   |
+| `DATABASE_AUTH_TOKEN` | उन प्रदाताओं के लिए प्रामाणिक टोकन जिन्हें एक अलग टोकन की आवश्यकता होती है, जैसे Turso/libSQL |