@agent-native/core 0.88.0 → 0.90.1

package/docs/content/locales/hi-IN/data-programs.mdx

@@ -0,0 +1,329 @@
+---
+title: "डेटा प्रोग्राम"
+description: "एजेंट द्वारा लिखी गई और सहेजी गई JS स्क्रिप्ट जो सर्वर-साइड डेटा फ़ेच, जॉइन और एग्रीगेट करती है, SQL में कैश होती है, और dashboard पैनल द्वारा रेंडर होती है — एक-बार की run-code क्वेरी और हार्डकोडेड provider action के बीच का लाइव-डेटा मध्य मार्ग।"
+search: "data program emit rows schema providerFetch dashboard panel program source refresh TTL viewer-scoped cache save-data-program run-data-program"
+---
+
+# डेटा प्रोग्राम
+
+एक **डेटा प्रोग्राम (data program)** एक नामित, सहेजा गया, एजेंट द्वारा लिखा गया JS स्क्रिप्ट है जो डेटा फ़ेच, जॉइन, फ़िल्टर या एग्रीगेट करता है — `providerFetch` / `providerFetchAll` / `providerSearchAll` के ज़रिए provider APIs, `appAction` के ज़रिए app डेटा, या Resources-बैक्ड workspace फ़ाइलें — और परिणाम के साथ बिल्कुल एक बार `emit(rows, schema)` कॉल करता है। परिणाम SQL में कैश होता है और कोई भी chart/table कंपोनेंट इसे रेंडर कर सकता है, जो हर पेज व्यू पर नहीं बल्कि आपकी चुनी हुई पॉलिसी पर रिफ्रेश होता है।
+
+जहाँ भी [`run-code`](/docs/actions) उपलब्ध है वहाँ यह अपने आप उपलब्ध हो जाता है — प्रति app इसे माउंट या कॉन्फ़िगर करने की कोई ज़रूरत नहीं है। अगर आपके app में पहले से run-code सक्षम है, तो `save-data-program`, `preview-data-program`, `run-data-program`, `list-data-programs`, `get-data-program`, और `delete-data-program` पहले से ही रजिस्टर्ड actions हैं।
+
+<Diagram id="doc-block-dp-overview" title={"एडहॉक क्वेरी से लाइव पैनल तक"} summary={"एक run-code स्क्रिप्ट emit() कॉल करते ही एक सहेजे गए प्रोग्राम में बदल जाती है; कोई भी dashboard पैनल इससे बाइंड हो सकता है और उसके बाद कैश/रिफ्रेश पॉलिसी संभाल लेती है।"}>
+
+```html
+<div class="dp-flow">
+  <div class="diagram-card" data-rough>
+    <span class="diagram-pill">run-code script</span
+    ><small class="diagram-muted">providerFetch, joins, aggregation</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel">
+    <span class="diagram-pill accent">emit(rows, schema)</span
+    ><small class="diagram-muted"
+      >save-data-program dry-runs, then persists</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    data_program_runs<br /><small class="diagram-muted"
+      >cached per (program, params, viewer)</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">डैशबोर्ड पैनल</span
+    ><small class="diagram-muted"><code>source: "program"</code></small>
+  </div>
+</div>
+```
+
+```css
+.dp-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dp-flow .diagram-card,
+.dp-flow .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
+  min-width: 180px;
+}
+.dp-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## यह क्यों मौजूद है {#why}
+
+एक सहेजे गए डेटा प्रोग्राम के बिना, "X का लाइव व्यू बनाओ" अक्सर दो खराब जगहों में से किसी एक पर खत्म होता है:
+
+- **प्रति vendor/क्वेरी-आकार एक हार्डकोडेड action।** नाज़ुक, और यह हर ग्राहक की कस्टम प्रॉपर्टीज़, provider-पार जॉइन, या किसी मनमाने फ़िल्टर का अनुमान नहीं लगा सकता जिसके बारे में आपने सोचा ही नहीं।
+- **हर पेज व्यू पर वही फ़ेच/जॉइन लॉजिक शुरू से फिर चलाना।** धीमा, और हर बार जब कोई chart देखता है तो वही provider API कोटा फिर से खर्च होता है।
+
+डेटा प्रोग्राम बीच का रास्ता है: फ़ेच/जॉइन/एग्रीगेशन लॉजिक को एक बार सामान्य `run-code` के रूप में लिखें, इसे सहेजें, और यह तय करने दें कैश और रिफ्रेश पॉलिसी को कि इसे वास्तव में कितनी बार फिर से चलाने की ज़रूरत है।
+
+## इसका उपयोग कब करें {#when-to-use-one}
+
+| स्थिति                                                                                                                                                       | अपनाएँ                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| किसी स्टैंडर्ड रोलअप के पास पहले से ही एक फर्स्ट-क्लास action है (पहले से बना `hubspot-deals` फ़िल्टर, कोई बिल्ट-इन मेट्रिक)                                 | मौजूदा action — इसे किसी प्रोग्राम में न लपेटें                               |
+| एक बार का चैट सवाल जिसे आप फिर कभी नहीं देखेंगे                                                                                                              | सीधा `run-code` या `provider-api-request` — सीधे जवाब दें, कुछ भी सहेजें नहीं |
+| किसी एक्सटेंशन को अपनी खुद की UI के साथ एक छोटा, प्रति-यूज़र इंटरैक्टिव विजेट चाहिए                                                                          | [एक्सटेंशन](/docs/extensions) — डेटा प्रोग्राम की अपनी कोई UI नहीं होती       |
+| किसी कोहॉर्ट को मनमाना प्रॉपर्टी फ़िल्टर, कस्टम वैल्यूज़ पर IN-सर्च, या दो providers के बीच जॉइन चाहिए, **और** कोई इसे ताज़ा डेटा के साथ फिर से देखना चाहेगा | डेटा प्रोग्राम                                                                |
+| एक dashboard पैनल को वह जॉइन/एग्रीगेट किया गया परिणाम दिखाना है और कैश नीति के अनुसार रिफ्रेश करना है                                                        | `"program"` पैनल से बाइंड किया गया डेटा प्रोग्राम                             |
+
+अन्य run-code-आकार के विकल्पों से तुलना:
+
+|                                                 | एक-बार का `run-code`              | हार्डकोडेड provider action                           | डेटा प्रोग्राम                                      |
+| ----------------------------------------------- | --------------------------------- | ---------------------------------------------------- | --------------------------------------------------- |
+| **कॉल्स के बीच बना रहता है**                    | नहीं                              | लागू नहीं (यह खुद सोर्स कोड है)                      | हाँ — सहेजी गई पंक्ति + परिणाम कैश                  |
+| **परिणाम कैश/रिफ्रेश होता है**                  | नहीं, हर बार फिर चलता है          | कोई बिल्ट-इन कैशिंग नहीं                             | हाँ — `refreshMode`/`refreshTtlMs`                  |
+| **मनमाने फ़िल्टर/जॉइन संभालता है**              | हाँ, पर बाद में फेंक दिया जाता है | नहीं — action के schema द्वारा उजागर किए गए तक सीमित | हाँ — यह अब भी सामान्य कोड है                       |
+| **dashboard पैनल से बाइंड करने योग्य**          | नहीं                              | तभी जब उसके लिए एक पैनल सोर्स बनाया गया हो           | हाँ — जेनेरिक `"program"` सोर्स                     |
+| **डिप्लॉय की ज़रूरत है**                        | नहीं                              | हाँ (नया action = कोड बदलाव)                         | नहीं — रनटाइम पर एजेंट द्वारा बनाया गया             |
+| **रीड के समय इस्तेमाल होने वाली क्रेडेंशियल्स** | कॉलर की                           | कॉलर की                                              | **व्यूअर की**, प्रति-रीड हल की जाती है (नीचे देखें) |
+
+## लेखन वर्कफ़्लो {#authoring-workflow}
+
+1. **पहले चैट में प्रोटोटाइप बनाएँ।** फ़ेच/जॉइन/एग्रीगेशन लॉजिक को एक सामान्य `run-code` स्क्रिप्ट की तरह लिखें और पुष्टि करें कि यह अपेक्षित पंक्तियाँ लौटाता है।
+2. **इसे बदलें ताकि यह अंत में परिणाम लौटाने या प्रिंट करने के बजाय बिल्कुल एक बार `emit(rows, schema?)` कॉल करे।**
+3. **इसे `save-data-program` से सहेजें।** यह सहेजने से पहले **`defaultParams` के साथ कोड का dry-run चलाता है** और अगर यह विफल होता है तो एक स्ट्रक्चर्ड एरर के साथ सेव को अस्वीकार कर देता है, ताकि कोई टूटा हुआ प्रोग्राम कभी सहेजा न जाए। सफल होने पर यह `{ programId, rowCount, columns, sampleRows }` लौटाता है — उपयोगकर्ता को यह बताने से पहले कि यह तैयार है, इसे इस बात के प्रमाण के रूप में लें कि प्रोग्राम अपेक्षित पंक्तियाँ बनाता है।
+4. **किसी dashboard पैनल को इससे बाइंड करें**, या अपने खुद के रीड पाथ से सीधे `run-data-program` कॉल करें। इस प्रिमिटिव में खुद कोई dashboard-विशिष्ट वायरिंग बिल्ट-इन नहीं है — analytics टेम्पलेट का `"program"` पैनल सोर्स (नीचे) एक अपनाने का उदाहरण है, कोई अनिवार्य पैटर्न नहीं।
+5. **बिना सहेजे इटरेट करें** `preview-data-program({ code, params? })` के ज़रिए — वही dry-run पाथ, कोई सहेजी गई पंक्ति नहीं।
+
+### एक व्यावहारिक उदाहरण
+
+मान लीजिए एक app किसी सपोर्ट provider से एक लाइव "हाल के उच्च-मूल्य वाले सपोर्ट टिकट्स" टेबल चाहता है, जो किसी ऐसे थ्रेशोल्ड से फ़िल्टर हो जिसे कोई बिल्ट-इन action उजागर नहीं करता:
+
+```ts
+// The program's stored `code` — ordinary run-code, with one emit() call.
+const minValue = Number(params.minValue || 5000);
+
+const tickets = await providerFetchAll("acme-support", "/v1/tickets", {
+  query: { status: "open" },
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "next_cursor",
+    maxPages: 10,
+  },
+});
+
+const rows = (tickets.items || [])
+  .filter((t) => Number(t.contract_value || 0) >= minValue)
+  .map((t) => ({
+    ticket_id: t.id,
+    subject: t.subject,
+    account: t.account_name,
+    contract_value: Number(t.contract_value || 0),
+    opened_at: t.created_at,
+  }));
+
+emit(rows, [
+  { name: "ticket_id", type: "string" },
+  { name: "subject", type: "string" },
+  { name: "account", type: "string" },
+  { name: "contract_value", type: "number" },
+  { name: "opened_at", type: "string" },
+]);
+```
+
+इसे सहेजना:
+
+```ts
+await appAction("save-data-program", {
+  name: "high-value-open-tickets",
+  title: "High-Value Open Tickets",
+  description:
+    "Open support tickets above a configurable contract-value threshold.",
+  code: "/* the script above */",
+  defaultParams: { minValue: 5000 },
+  refreshMode: "ttl",
+  refreshTtlMs: 300_000,
+});
+```
+
+प्रतिक्रिया में `{ programId, rowCount, columns, sampleRows }` होता है — dry-run के पूर्ण होने का प्रमाण। वहाँ से, `run-data-program({ programId, params: { minValue: 10000 } })` इसे एक अलग थ्रेशोल्ड के लिए फिर चलाता है (या कैश देता है), और एक dashboard पैनल उसी तरह `programId` से बाइंड हो सकता है।
+
+## सैंडबॉक्स सतह {#sandbox-surface}
+
+एक डेटा प्रोग्राम बिल्कुल उसी `executeSandboxCode` सैंडबॉक्स के ज़रिए चलता है जिससे `run-code` चलता है — इस प्रिमिटिव के लिए कोई नया सैंडबॉक्सिंग, क्रेडेंशियल, SSRF, या कोटा कोड मौजूद नहीं है। इसे वही ग्लोबल्स मिलते हैं (`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`, `webFetch`, `workspace*` Resources हेल्पर्स) साथ ही फ्रेमवर्क द्वारा इंजेक्ट किए गए एक छोटे प्रील्यूड से दो अतिरिक्त चीज़ें:
+
+- **`params`** — इस रन के लिए params रखने वाला एक **फ़्रोज़न** ग्लोबल ऑब्जेक्ट (`defaultParams` को `run-data-program` या पैनल डिस्क्रिप्टर को पास की गई चीज़ के साथ मर्ज किया गया)। इसे पढ़ना ठीक है; इसे म्यूटेट करना एरर फेंकता है।
+- **`emit(rows, schema?)`** — इसे अंत में **बिल्कुल एक बार** कॉल करें। दूसरी कॉल एरर फेंकती है। `rows` सामान्य ऑब्जेक्ट्स का एक array होना चाहिए। `schema`, जब दिया जाए, `{ name: string, type: string }[]` होता है; जब छोड़ दिया जाए तो यह पहली 50 पंक्तियों से अनुमानित होता है (यदि सैंपल में पंक्तियाँ primitive type पर असहमत हों तो कॉलम `"json"` होता है, अन्यथा `"number"` / `"string"` / `"boolean"`)। डिबगिंग के लिए `console.log` पूरी तरह मुक्त रहता है — रनर मिले-जुले stdout/stderr को कैप्चर करता है और परिणाम पार्स करते समय केवल वह सेंटिनल लाइन हटाता है जो `emit()` लिखता है।
+
+हर रन पर लागू होने वाली सीमाएँ (प्रति-प्रोग्राम कॉन्फ़िगर करने योग्य नहीं):
+
+| सीमा                                                  | मान                                                                                                                                                                         |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| अधिकतम emit की गई पंक्तियाँ                           | 10,000 — इससे आगे की पंक्तियाँ हटा दी जाती हैं, `truncated: true`                                                                                                           |
+| अधिकतम emit किए गए परिणाम का आकार                     | 4 MiB — फ़िट करने के लिए अंत से पंक्तियाँ हटाई जाती हैं; सीमा से बड़ी एक भी पंक्ति एक कठोर `result_too_large` विफलता है, क्योंकि छोटा करने के लिए कुछ भी सुरक्षित नहीं बचता |
+| प्रति app अधिकतम सक्रिय (गैर-आर्काइव्ड) प्रोग्राम     | 200 — जगह खाली करने के लिए अप्रयुक्त प्रोग्राम आर्काइव करें                                                                                                                 |
+| न्यूनतम रिफ्रेश TTL                                   | 60,000 ms                                                                                                                                                                   |
+| प्रति (प्रोग्राम, params, व्यूअर) रखी गई रन पंक्तियाँ | नवीनतम 5 — पुरानी पंक्तियाँ हर लेखन पर अपने आप हटा दी जाती हैं                                                                                                              |
+
+ट्रंकेशन हमेशा स्पष्ट होता है (परिणाम में `truncated: true`) — कभी भी चुपचाप छोड़ा नहीं जाता।
+
+## Params और dashboard पैनल बाइंडिंग {#params-and-panel-binding}
+
+प्रोग्राम एक वैकल्पिक `paramsSchema` (स्वीकृत params बताने वाला JSON Schema) और `defaultParams` घोषित कर सकते हैं। एक dashboard पैनल के क्वेरी फ़ील्ड में क्वेरी स्ट्रिंग के बजाय एक छोटा JSON डिस्क्रिप्टर रखकर `"program"` पैनल सोर्स अपनाता है:
+
+```json
+{ "programId": "dp_a1b2c3d4e5f6", "params": { "minValue": 10000 } }
+```
+
+पैनल बिल्कुल उन्हीं chart/table कंपोनेंट्स के ज़रिए रेंडर होता है जिनसे कोई भी अन्य पैनल सोर्स होता है — इसे हमेशा केवल `{ rows, schema }` वापस मिलता है। किसी पैनल को किसी प्रोग्राम से बाइंड करना बस इतना ही है कि "कौन सा सहेजा गया प्रोग्राम, किन params ओवरराइड्स के साथ"; कहीं और कोई डुप्लिकेट dashboard-विशिष्ट execution पाथ मौजूद नहीं है।
+
+## रिफ्रेश, TTL, और कैशिंग सिमेंटिक्स {#refresh-and-caching}
+
+हर `(programId, paramsHash)` जोड़े का `data_program_runs` में अपना खुद का रन इतिहास होता है, और `paramsHash` केवल params ही नहीं बल्कि **व्यूअर** को भी शामिल करता है (कारण के लिए सुरक्षा सेक्शन देखें)। हर रीड पर क्या होता है:
+
+| स्थिति                                                                                 | व्यवहार                                                                                                                                                                                          |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| ताज़ा कैश (`refreshTtlMs` से नया, या `refreshMode: "manual"` के साथ पहले की कोई सफलता) | कैश की गई पंक्तियाँ तुरंत लौटाता है, `cacheHit: true`                                                                                                                                            |
+| कैश TTL से पुराना है                                                                   | सिंक्रोनसली फिर से एक्ज़ीक्यूट होता है — पैनल-व्यू से ट्रिगर हुए रीड्स के लिए 25s का बजट, एजेंट/मैनुअल कॉल्स के लिए 120s — और सफलता पर कैश बदल देता है                                           |
+| `refreshMode: "manual"`                                                                | कभी अपने आप रिफ्रेश नहीं होता; केवल स्पष्ट `forceRefresh: true` (या UI का मैनुअल-रिफ्रेश action) इसे फिर चलाता है                                                                                |
+| अभी तक कोई कैश नहीं                                                                    | एक सामान्य पहली फ़ेच की तरह सिंक्रोनसली एक्ज़ीक्यूट होता है                                                                                                                                      |
+| `background: true` प्रोग्राम, कोई ताज़ा कैश नहीं                                       | तुरंत `stale: true` के साथ आखिरी अच्छा रन देता है और एक टिकाऊ बैकग्राउंड एक्ज़ीक्यूशन को क्यू में डालता है (10-मिनट का बजट); एक बाद की कॉल एक्ज़ीक्यूशन पूरा होने पर परिणाम को अंतिम रूप देती है |
+| बैकग्राउंड प्रोग्राम अभी भी चल रहा है, पहले कोई सफलता नहीं                             | `background_pending` विफलता — एक स्पष्ट "अभी भी गणना हो रही है" स्थिति दिखाएँ, कभी खाली परिणाम नहीं                                                                                              |
+| एक्ज़ीक्यूशन विफल होता है (टाइमआउट, सैंडबॉक्स एरर, गलत `emit()` आकार)                  | एक स्ट्रक्चर्ड `{ code, message }` विफलता; अगर पहले की कोई सफलता मौजूद है, तो इसे `lastGoodRun` के रूप में जोड़ा जाता है ताकि पैनल खाली होने के बजाय पुराना डेटा दिखा सके                        |
+| प्रोग्राम आर्काइव किया गया (`delete-data-program` के ज़रिए सॉफ्ट-डिलीट)                | स्पष्ट `archived` विफलता — कभी चुपचाप खाली पैनल नहीं                                                                                                                                             |
+
+`background: true` का इस्तेमाल केवल उन प्रोग्रामों के लिए करें जो नियमित रूप से फ़ोरग्राउंड टाइमआउट से आगे निकल जाते हैं — बड़े मल्टी-provider जॉइन्स, गहरी पेजिनेशन। बाकी सब कुछ फ़ोरग्राउंड में ही रहना चाहिए: यह समझने में आसान है और तेज़ी से ताज़ा डेटा देता है।
+
+### कैश व्यूअर के अनुसार सीमित क्यों है {#per-viewer-cache}
+
+किसी प्रोग्राम के अंदर `providerFetch` **कॉल करने वाले व्यूअर के अपने रिक्वेस्ट कॉन्टेक्स्ट** का उपयोग करके ऑथ हल करता है — कभी प्रोग्राम के लेखक का नहीं। यह सच है चाहे कॉल एजेंट से आए, `run-data-program` कॉल से आए, या किसी टीममेट द्वारा देखे जा रहे dashboard पैनल से आए। एक ही प्रोग्राम को एक ही params के साथ चलाने वाले दो अलग-अलग व्यूअर वैध रूप से दो अलग परिणाम पा सकते हैं: एक के पास कॉन्फ़िगर्ड HubSpot key है और दूसरे के पास नहीं, या row-स्तर की provider अनुमतियाँ व्यक्ति के अनुसार अलग हैं।
+
+इसी वजह से, `hashDataProgramParams` कैनोनिकलाइज़्ड params के साथ-साथ कॉलर की पहचान को भी कैश-की में शामिल करता है। यह **शेयर्ड dashboards** के लिए सबसे ज़्यादा मायने रखता है: अगर कैश केवल params से की-ड होता, तो पैनल देखने वाला पहला व्यक्ति चुपचाप तय कर देता कि हर अन्य व्यूअर क्या देखेगा, उन व्यूअर्स समेत जिनके पास वे क्रेडेंशियल्स नहीं हैं जिन्होंने वह कैश किया गया परिणाम बनाया। प्रति-व्यूअर स्कोपिंग का मतलब है कि क्रेडेंशियल न रखने वाला टीममेट उस पैनल पर किसी और का डेटा नहीं बल्कि अपनी खुद की ऑथ एरर देखता है।
+
+## सुरक्षा मॉडल {#security}
+
+<Callout id="doc-block-dp-security" tone="success">
+
+**रॉ provider टोकन कभी भी मॉडल या ब्राउज़र तक नहीं पहुँचते।** सैंडबॉक्स से बाहर निकलने वाली एकमात्र चीज़ `{ rows, schema }` है जो एक `emit()` कॉल बनाता है — बाकी हर run-code एक्ज़ीक्यूशन और हर अन्य dashboard पैनल सोर्स जैसी ही ट्रस्ट बाउंड्री।
+
+</Callout>
+
+- **केवल सर्वर-साइड।** एक डेटा प्रोग्राम का कोड विशेष रूप से सर्वर पर `executeSandboxCode` के अंदर ही चलता है। न तो सहेजा गया सोर्स और न ही इसके द्वारा छुई गई कोई क्रेडेंशियल ब्राउज़र या मॉडल को भेजी जाती है — केवल emit की गई पंक्तियाँ/schema और संक्षिप्त रन मेटाडेटा (row count, columns, sample rows) ही भेजे जाते हैं।
+- **क्रेडेंशियल्स हमेशा कॉल करने वाले व्यूअर की होती हैं, कभी प्रोग्राम के मूल लेखक की नहीं।** यह कैश-की को भी क्यों तय करता है, इसके लिए ऊपर [रिफ्रेश, TTL, और कैशिंग सिमेंटिक्स](#per-viewer-cache) देखें।
+- **`allowPublic: false` एक कठोर invariant है, कोई डिफ़ॉल्ट नहीं।** डेटा प्रोग्राम शेयरिंग रजिस्ट्री में उसी तरह रजिस्टर होते हैं जैसे [एक्सटेंशन](/docs/extensions#security), पब्लिक शेयरिंग बंद रखते हुए। एक पब्लिक प्रोग्राम किसी भी ऑथेंटिकेटेड उपयोगकर्ता को अपने खुद के टोकन के तहत मनमाना सहेजा गया कोड चलाने देगा — किसी प्रोग्राम को शेयर करना आपके org तक सीमित है, और इसका मतलब हमेशा सिर्फ यही है कि "टीममेट्स इसके कैश किए गए परिणाम को देख सकते हैं और फिर से रन ट्रिगर कर सकते हैं," कभी यह नहीं कि "सामान्य इंटरनेट इसे चला सकता है।"
+- **म्यूटेट करने और एक्ज़ीक्यूट करने वाली actions सैंडबॉक्स्ड एक्सटेंशन/iframe ब्रिज से टूल के रूप में कॉल करने योग्य नहीं हैं।** `save-data-program`, `preview-data-program`, `run-data-program`, और `delete-data-program` सभी `toolCallable: false` हैं — केवल एजेंट या एक सर्वर-साइड रीड पाथ ही इन्हें कॉल कर सकता है, कभी ओपनर के सेशन के तहत कोई एक्सटेंशन iframe नहीं। `list-data-programs` और `get-data-program` रीड-ओनली हैं और किसी भी अन्य ownable रिसोर्स की तरह उन्हीं शेयरिंग हेल्पर्स के ज़रिए एक्सेस-स्कोप्ड हैं।
+- **प्रोग्राम उस app तक सीमित हैं जिसने उन्हें बनाया।** किसी लुकअप को `appId` पास करने का मतलब है कि एक app में बनाया गया प्रोग्राम शेयर्ड-डेटाबेस डिप्लॉयमेंट में किसी दूसरे app के एजेंट चैट से रन करने योग्य नहीं है, भले ही कॉलर के पास अन्यथा row-स्तर (owner/org/share) एक्सेस मौजूद हो।
+- **केवल उसी प्रोग्राम से बाइंड करें या देखें जिस पर आप भरोसा करते हैं।** क्योंकि एक्ज़ीक्यूशन हमेशा व्यूअर की अपनी क्रेडेंशियल्स का उपयोग करता है, किसी शेयर्ड प्रोग्राम का परिणाम देखना बिल्कुल किसी और का एक्सटेंशन खोलने जैसा है — भरोसा कोड पर करें, केवल एक्सेस ग्रांट पर नहीं।
+
+## Risk Meeting कार्यशील उदाहरण {#risk-meeting-example}
+
+analytics टेम्पलेट में एक ठोस, चलाने योग्य केस स्टडी शामिल है: `ensure-risk-meeting-dashboard` action दो डेटा प्रोग्राम और एक दो-पैनल "Risk Meeting" dashboard को इडेम्पोटेंटली इंस्टॉल करता है, यह दिखाते हुए कि तीन चीज़ें एक हार्डकोडेड action हर ग्राहक के लिए अनुमानित नहीं कर सकता।
+
+<FileTree
+  id="doc-block-dp-risk-meeting-files"
+  title={"Risk Meeting इंस्टॉलर"}
+  entries={[
+    {
+      path: "templates/analytics/actions/ensure-risk-meeting-dashboard.ts",
+      note: "इडेम्पोटेंट action: दोनों प्रोग्रामों को स्थिर नाम से अपडेट करता है, फिर dashboard को id से",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-cohort.js",
+      note: "सहेजा गया प्रोग्राम पेलोड — सादा JS टेक्स्ट, कोई बिल्ड सोर्स फ़ाइल नहीं",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-pylon-early-warning.js",
+      note: "पूरक अर्ली-वार्निंग प्रोग्राम",
+    },
+  ]}
+/>
+
+**`risk-meeting-cohort.js`** — एक मनमाने `risk_status` प्रॉपर्टी (एक कस्टम वैल्यूज़ पर IN-सर्च जिसे कोई तैयार action अनुमानित नहीं कर सकता) से CRM deals का एक कॉन्फ़िगर करने योग्य कोहॉर्ट खोजता है, बैच्ड एसोसिएशन लुकअप के ज़रिए हर deal की कंपनी हल करता है, हर कंपनी का डोमेन हल करता है, दूसरे, असंबंधित provider का account sentiment फ़ेच करता है, और डोमेन से दोनों को जॉइन करता है:
+
+```js
+// params: { riskStatuses?: string[], enterpriseOnly?: boolean }
+const riskStatuses = params.riskStatuses?.length
+  ? params.riskStatuses
+  : ["On the Radar", "Churn Risk", "Confirmed Churn", "No Save Attempted"];
+
+// 1. Arbitrary property IN-search — not expressible through a canned filter.
+const dealSearch = await providerFetchAll("crm-provider", "/deals/search", {
+  method: "POST",
+  body: {
+    filterGroups: [
+      {
+        filters: [
+          { propertyName: "risk_status", operator: "IN", values: riskStatuses },
+        ],
+      },
+    ],
+  },
+  itemsPath: "results",
+  pagination: {
+    cursorBodyPath: "after",
+    nextCursorPath: "paging.next.after",
+    maxPages: 20,
+  },
+});
+
+// 2-3. Batched deal -> company -> domain resolution (elided here; see the
+// real seed file for the full batching helper).
+
+// 4. A second, unrelated provider — zero bespoke glue action required.
+const accounts = await providerFetchAll("support-provider", "/accounts", {
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "pagination.cursor",
+    maxPages: 20,
+  },
+});
+
+// 5. Join + emit.
+const rows = dealSearch.items.map((deal) => ({
+  deal_id: deal.id,
+  risk_status: deal.properties.risk_status,
+  arr: Number(deal.properties.total_contract_value || 0),
+  // ...domain lookup + sentiment join...
+}));
+
+emit(rows, [
+  { name: "deal_id", type: "string" },
+  { name: "risk_status", type: "string" },
+  { name: "arr", type: "number" },
+]);
+```
+
+**`risk-meeting-pylon-early-warning.js`** — पूरक व्यू: वे accounts जो सपोर्ट sentiment द्वारा पहले से ही जोखिम भरे चिह्नित हैं लेकिन ऊपर वाले CRM कोहॉर्ट में **अभी तक** नहीं दिखे। यह अंतर — CRM सिग्नल से आगे निकलता सपोर्ट सिग्नल — एक provider के कोहॉर्ट को दूसरे से बाहर रखने की ज़रूरत रखता है, जो ठीक उसी तरह का provider-पार सेट लॉजिक है जिसे कोई सिंगल-vendor action व्यक्त नहीं कर सकता।
+
+दोनों प्रोग्राम `ensure-risk-meeting-dashboard` द्वारा इंस्टॉल किए जाते हैं और अपडेट रखे जाते हैं, जो:
+
+- हर प्रोग्राम को उसके स्थिर `name` से अपडेट करता है, ताकि इंस्टॉलर को फिर से चलाने पर वही पंक्तियाँ डुप्लिकेट होने के बजाय अपडेट हों।
+- इंस्टॉल के समय किसी CRM/सपोर्ट क्रेडेंशियल की ज़रूरत नहीं होती — provider ऑथ प्रति-व्यूअर तभी हल होता है जब कोई पैनल वास्तव में रेंडर होता है या `run-data-program` कॉल किया जाता है, जो ऊपर बताए गए प्रति-व्यूअर कैश स्कोपिंग के अनुरूप है।
+- एक दो-पैनल dashboard बनाता है जिसके पैनल `source: "program"` इस्तेमाल करते हैं, जो हर प्रोग्राम के id से बाइंड होते हैं।
+
+पूरी तरह से एनोटेटेड सोर्स के लिए `data-programs` skill देखें।
+
+## अन्य apps पैनल सोर्स को कैसे अपनाते हैं {#adopting-the-panel-source}
+
+`"program"` dashboard पैनल सोर्स इस प्रिमिटिव को अपनाने का एक उदाहरण है, जो पूरी तरह से होस्ट app की अपनी पैनल-क्वेरी लेयर में लागू किया गया है — `@agent-native/core/data-programs` में खुद कुछ भी dashboard-विशिष्ट बिल्ट-इन नहीं है। analytics टेम्पलेट का इम्प्लीमेंटेशन आपके अपने को वायर करने के लिए एक उपयोगी संदर्भ है:
+
+- पैनल का `sql` कॉलम क्वेरी स्ट्रिंग के बजाय एक छोटा JSON डिस्क्रिप्टर — `{ programId, params? }` — रखता है।
+- किसी पैनल को रेंडर करना `triggeredBy: "panel_view"` और वर्तमान व्यूअर की पहचान के साथ `runDataProgram` कॉल करता है, ताकि प्रति-व्यूअर कैश और क्रेडेंशियल रिज़ॉल्यूशन अपने आप लागू हो जाए।
+- सफलता पर, पैनल को `{ rows, schema }` मिलता है — बिल्कुल वही आकार जो हर अन्य पैनल सोर्स लौटाता है, ताकि यह मौजूदा chart/table कंपोनेंट्स से बिना किसी बदलाव के प्रवाहित हो सके।
+- विफलता पर, जब भी कोई `lastGoodRun` मौजूद हो तो उसे टूटे हुए पैनल पर प्राथमिकता दी जाती है; केवल तब जब पहले की कोई सफलता न हो, पैनल एक स्ट्रक्चर्ड एरर दिखाता है (आम कोड्स जैसे `access_denied`, `archived`, और `background_pending` के लिए ज़्यादा दोस्ताना टेक्स्ट के साथ)।
+
+कोई भी app अपने खुद के dashboards/tables के लिए यही तरीका अपना सकता है: अपने खुद के रीड पाथ से `run-data-program` (या अगर वही सर्वर प्रोसेस के अंदर हैं तो सीधे `runDataProgram`) कॉल करें, और लौटाए गए `rows`/`schema` को अपने खुद के रेंडरिंग कंपोनेंट्स को सौंप दें।
+
+## संबंधित दस्तावेज़ {#related}
+
+- [एक्सटेंशन](/docs/extensions) — वह सैंडबॉक्स्ड mini-app प्रिमिटिव जिसके साथ डेटा प्रोग्राम एक सुरक्षा मुद्रा और शेयरिंग मॉडल साझा करते हैं, पर अपनी खुद की UI के साथ।
+- [Actions](/docs/actions) — वे `run-code` कन्वेंशन्स और सैंडबॉक्स ग्लोबल्स (`providerFetch`, `appAction`, आदि) जिन पर डेटा प्रोग्राम बने हैं।
+- [शेयरिंग और प्राइवेसी](/docs/sharing) — वह org-आंतरिक, कभी पब्लिक न होने वाला शेयरिंग मॉडल जो डेटा प्रोग्राम इस्तेमाल करते हैं।
+- [सुरक्षा](/docs/security) — फ्रेमवर्क के क्रेडेंशियल-हैंडलिंग और एक्सेस-स्कोपिंग invariants।

package/docs/content/locales/hi-IN/deployment.mdx

@@ -384,24 +384,23 @@ openssl rand -hex 32
 ## उत्पादन एजेंट उपकरण {#production-agent-tools}
 
 प्रोडक्शन एजेंटों को ऐप के पंजीकृत actions प्लस फ्रेमवर्क टूल मिलते हैं
-एजेंट चैट प्लगइन. कच्चे DB
-टूल्स का दायरा प्रमाणित उपयोगकर्ता/संगठन तक होता है, लेकिन ऐप मालिक इसे सीमित कर सकते हैं
-सतह जब तैनाती अधिक विचारशील होनी चाहिए:
+एजेंट चैट प्लगइन. SQL निरीक्षण डिफ़ॉल्ट रूप से सक्षम है; डेटाबेस writes
+typed app actions से गुजरते हैं, जब तक ऐप स्पष्ट रूप से raw write tools सक्षम न करे:
 
 ```ts
 // server/plugins/agent-chat.ts
 export default createAgentChatPlugin({
-  // Default: "write" (also true)
+  // Default: "read"
   databaseTools: "read", // "write" | "read" | "off"
   extensionTools: false,
 });
 ```
 
-- `databaseTools: "write"` - डिफ़ॉल्ट। रजिस्टर `db-schema`, `db-query`,
-  `db-exec`, और `db-patch`। लेखन का दायरा मौजूदा उपयोगकर्ता/संगठन और
-  स्कीमा परिवर्तन अवरुद्ध हैं।
-- `databaseTools: "read"` - केवल `db-schema` और `db-query` पंजीकृत करता है; एजेंट
-  SQL के साथ डेटा का निरीक्षण करें लेकिन लिखने के लिए टाइप किए गए ऐप actions का उपयोग करना होगा।
+- `databaseTools: "read"` - डिफ़ॉल्ट। केवल `db-schema` और `db-query` पंजीकृत करता है;
+  एजेंट SQL से डेटा देखते हैं लेकिन writes के लिए typed app actions का उपयोग करते हैं।
+- `databaseTools: "write"` या `true` - deliberate raw SQL maintenance के लिए
+  `db-exec` और `db-patch` भी पंजीकृत करता है। writes मौजूदा उपयोगकर्ता/संगठन
+  तक scoped रहते हैं और schema changes blocked रहते हैं।
 - `databaseTools: "off"` या `false` - कच्चे डेटाबेस टूल को हटा देता है
   एजेंट सतह इसलिए ऐप का actions ही एकमात्र डेटा एक्सेस पथ है।
 - `extensionTools: false` - फ्रेमवर्क एक्सटेंशन-प्रबंधन actions को हटा देता है और

package/docs/content/locales/hi-IN/extensions.mdx

@@ -34,7 +34,7 @@ description: "आपके उपयोगकर्ता आपके टेम
     <div class="ext-helpers">
       <span class="diagram-pill">appAction</span
       ><span class="diagram-pill">appFetch</span
-      ><span class="diagram-pill">dbQuery / dbExec</span
+      ><span class="diagram-pill">dbQuery</span
       ><span class="diagram-pill">extensionData</span
       ><span class="diagram-pill">extensionFetch</span>
     </div>
@@ -227,7 +227,7 @@ iframe सैंडबॉक्स के अंदर, प्रत्येक
 | `appAction(name, params)`                        | किसी भी होस्ट टेम्पलेट के actions पर कॉल करें                           | `appAction('list-emails', { view: 'inbox' })`             |
 | `appFetch(path, options)`                        | `/_agent-native/*` के अंतर्गत अनुमत फ़्रेमवर्क एंडपॉइंट को कॉल करें     | `appFetch('/_agent-native/application-state/navigation')` |
 | `dbQuery(sql, args)`                             | SQL से पढ़ें (उपयोगकर्ता के लिए ऑटो-स्कोप)                              | `dbQuery('SELECT id, name FROM tools')`                   |
-| `dbExec(sql, args)`                              | SQL को लिखें                                                            | `dbExec('INSERT INTO ...')`                               |
+| `dbExec(sql, args)`                              | Legacy trusted SQL writes for editor/admin extensions                   | Prefer `appAction` for app data writes                    |
 | `extensionFetch(url, options)`                   | रहस्यों के साथ एक सुरक्षित प्रॉक्सी के माध्यम से बाहरी APIs को हिट करें | `extensionFetch('https://api.github.com/user')`           |
 | `extensionData.set(collection, id, data, opts?)` | प्रति-एक्सटेंशन डेटा जारी रखें (उपयोगकर्ता/संगठन का दायरा)              | `extensionData.set('notes', id, { text: '...' })`         |
 | `extensionData.list(collection, opts?)`          | मौजूदा आइटमों की सूची बनाएं                                             | `extensionData.list('notes', { scope: 'all' })`           |
@@ -397,7 +397,7 @@ SQL स्थानीय एक्सटेंशन के लिए पंक
 
 - `extensionData` अक्षम होने तक छोटी रनटाइम स्थिति के लिए उपलब्ध है।
 - `appAction` कॉल को `permissions.appActions` में स्पष्ट रूप से सूचीबद्ध किया जाना चाहिए।
-- `dbQuery`, `dbExec`, और `extensionFetch` अभी के लिए अवरुद्ध हैं।
+- `dbQuery` और `extensionFetch` अभी के लिए अवरुद्ध हैं।
 - SQL-समर्थित अपडेट, डिलीट, शेयर और इतिहास actions एक संदेश लौटाता है
   स्थानीय प्रविष्टि फ़ाइल की ओर वापस इंगित करता है।
 
@@ -430,6 +430,8 @@ SQL स्थानीय एक्सटेंशन के लिए पंक
 
 सामान्य नियम: **यदि यह एक उपयोगकर्ता या एक टीम के लिए है, तो यह एक एक्सटेंशन है।** यदि टेम्पलेट के प्रत्येक उपयोगकर्ता को यह मिलना चाहिए, तो इसे एक वास्तविक सुविधा के रूप में शिप करें।
 
+कस्टम डेटा फ़ेचिंग के लिए जो किसी कस्टम विजेट UI के बजाय नेटिव charts और tables को डेटा दे, [डेटा प्रोग्राम](/docs/data-programs) देखें — एक सहेजा गया, रिफ्रेश करने योग्य `run-code` स्क्रिप्ट जिससे dashboard पैनल सीधे बाइंड होते हैं, बिना किसी एक्सटेंशन iframe के।
+
 ## सुरक्षा {#security}
 
 <Callout id="doc-block-frp4nq" tone="success">
@@ -444,7 +446,7 @@ SQL स्थानीय एक्सटेंशन के लिए पंक
 - **सर्वर-साइड गुप्त इंजेक्शन** `${keys.NAME}` टेम्पलेट के माध्यम से - वास्तविक कुंजी मान कभी भी ब्राउज़र तक नहीं पहुंचता है।
 - **डोमेन-लॉक रहस्य** - प्रत्येक कुंजी एक URL अनुमति सूची से बंधी है; प्रॉक्सी अन्य होस्ट के अनुरोधों को अस्वीकार कर देता है।
 - **निजी-नेटवर्क सुरक्षा** — एक्सटेंशन आंतरिक पते तक नहीं पहुंच सकते।
-- **प्रमाणीकरण आवश्यक** - एक्सटेंशन केवल लॉग-इन उपयोगकर्ताओं के लिए चलते हैं, और `dbQuery` / `dbExec` कॉल ऑटो-स्कोप हैं।
+- **प्रमाणीकरण आवश्यक** - एक्सटेंशन केवल लॉग-इन उपयोगकर्ताओं के लिए चलते हैं, और `dbQuery` कॉल ऑटो-स्कोप हैं।
 
 ## नामकरण के बारे में जानने योग्य कुछ बातें {#naming-back-compat}
 

package/docs/content/locales/hi-IN/key-concepts.mdx

@@ -239,20 +239,17 @@ export const forms = table("forms", {
 ```
 
 ```bash
-# त्वरित डेटाबेस निरीक्षण और एकमुश्त रखरखाव के लिए मुख्य कार्रवाइयां
+# त्वरित डेटाबेस निरीक्षण के लिए मुख्य कार्रवाइयां
 pnpm action db-schema                                       # show all tables
 pnpm action db-query --sql "SELECT * FROM forms"
-pnpm action db-exec --sql "UPDATE forms SET status = ? WHERE id = ?" --args '["closed","form-1"]'
-# बड़े टेक्स्ट कॉलम पर सर्जिकल find/replace - एक अंतर भेजता है, संपूर्ण मान नहीं
-pnpm action db-patch --table documents --column content \
-  --where "id='doc-1'" --find "old heading" --replace "new heading"
 ```
 
-प्रोडक्शन एजेंट चैट प्लगइन डिफ़ॉल्ट रूप से कच्चे डेटाबेस को लिखने में सक्षम बनाता है
-(`databaseTools: "write"`) ताकि एजेंट बिना प्रतीक्षा किए ऐप-स्वामित्व वाले डेटा को ठीक कर सकें
-नया टाइप किया गया कार्य। उन लेखों का दायरा प्रमाणित उपयोगकर्ता/संगठन तक होता है। सेट करें
-`databaseTools: "read"` केवल `db-schema` / `db-query` निरीक्षण रखने के लिए, या
-सभी डेटा के लिए `databaseTools: "off"` / `false` टाइप किए गए ऐप actions की आवश्यकता है
+production agent chat plugin raw SQL tools को default रूप से read-only रखता है
+(`databaseTools: "read"`), इसलिए agent app data को `db-schema` / `db-query`
+से inspect करते हैं और writes typed app actions से करते हैं। `databaseTools: "write"`
+(या `true`) केवल उन maintenance surfaces के लिए सेट करें जिन्हें scoped
+`db-exec` / `db-patch` भी चाहिए; सभी data access के लिए typed app actions
+require करने हेतु `databaseTools: "off"` / `false` सेट करें
 पहुँच.
 
 ## एजेंट चैट ब्रिज {#agent-chat-bridge}
@@ -437,6 +434,7 @@ UI इसे मार्ग परिवर्तन पर लिखता ह
 
 - **[Dispatch](/docs/dispatch)** - कार्यक्षेत्र नियंत्रण विमान: साझा इनबॉक्स, रहस्य वॉल्ट, निर्धारित कार्य, और एक ऑर्केस्ट्रेटर जो A2A पर विशेषज्ञ ऐप्स को सौंपता है।
 - **[Extensions](/docs/extensions)** - सैंडबॉक्स्ड Alpine.js मिनी-ऐप्स एजेंट रनटाइम पर बनाता है, कोई स्रोत परिवर्तन या माइग्रेशन नहीं।
+- **[डेटा प्रोग्राम](/docs/data-programs)** - एजेंट द्वारा लिखी गई सहेजी गई `run-code` स्क्रिप्ट्स जो dashboard पैनलों को हार्डकोडेड provider action के बजाय एक कैश्ड, रिफ्रेश करने योग्य परिणाम देती हैं।
 - **[A2A Protocol](/docs/a2a-protocol)** - एक ही कार्यक्षेत्र में ऐप्स JSON-RPC पर एक-दूसरे को कैसे खोजते हैं और कॉल करते हैं।
 
 ## आपको मुफ़्त में क्या मिलता है {#what-you-get-for-free}

package/docs/content/locales/hi-IN/real-time-collaboration.mdx

@@ -260,11 +260,8 @@ export default createCollabPlugin({
 ### 4. क्लाइंट हुक का उपयोग करें
 
 ```ts
-import {
-  useCollaborativeDoc,
-  emailToColor,
-  emailToName,
-} from "@agent-native/core/client";
+import { useCollaborativeDoc } from "@agent-native/core/client";
+import { emailToColor, emailToName } from "@agent-native/toolkit/collab-ui";
 
 const TAB_ID = generateTabId(); // or Math.random().toString(36)
 
@@ -366,12 +363,14 @@ pnpm action edit-document --id doc123 --find "delete me" --replace ""
 
 ```ts
 import {
-  PresenceBar,
-  LiveCursorOverlay,
-  RemoteSelectionRings,
   useCollaborativeDoc,
   usePresence,
 } from "@agent-native/core/client/collab";
+import {
+  PresenceBar,
+  LiveCursorOverlay,
+  RemoteSelectionRings,
+} from "@agent-native/toolkit/collab-ui";
 ```
 
 सर्वर-साइड एजेंट उपस्थिति सहायक निम्न-स्तरीय सहयोग पैकेज में रहते हैं:
@@ -457,7 +456,7 @@ setPresence({ cursor: { x: 0.4, y: 0.7 }, selection: "#hero" });
 दूरस्थ कर्सर को एक कंटेनर तत्व पर बिल्कुल स्थित लेबल के रूप में प्रस्तुत करता है:
 
 ```tsx
-import { LiveCursorOverlay } from "@agent-native/core/client";
+import { LiveCursorOverlay } from "@agent-native/toolkit/collab-ui";
 
 // cursor positions stored as { x, y } normalized 0–1 under presence.cursor
 <div ref={containerRef} style={{ position: "relative" }}>
@@ -477,7 +476,7 @@ import { LiveCursorOverlay } from "@agent-native/core/client";
 दूरस्थ रूप से चयनित तत्वों पर रंगीन आउटलाइन रिंग + नाम टैग प्रस्तुत करता है:
 
 ```tsx
-import { RemoteSelectionRings } from "@agent-native/core/client";
+import { RemoteSelectionRings } from "@agent-native/toolkit/collab-ui";
 
 <div ref={containerRef} style={{ position: "relative" }}>
   {content}