@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/hi-IN/evals.md

@@ -0,0 +1,155 @@
+---
+title: "सीआई इवल गेट"
+description: " *.eval.ts परीक्षण मामले लिखें जो वास्तविक एजेंट को निश्चित इनपुट के विरुद्ध चलाते हैं, कंपोज़ेबल स्कोरर के साथ आउटपुट स्कोर करते हैं, और गेट सीआई/थ्रेसहोल्ड पर तैनात करते हैं।"
+---
+
+# सीआई इवल गेट
+
+इवल्स एक प्रथम श्रेणी परीक्षण आदिम है: आप एक संकेत और आपके द्वारा अपेक्षित व्यवहार की घोषणा करते हैं, रनर **वास्तव में उस इनपुट के खिलाफ एजेंट लूप** चलाता है, कंपोज़ेबल स्कोरर के साथ आउटपुट को स्कोर करता है, और यदि कोई भी मामला इसकी सीमा से नीचे स्कोर करता है तो गैर-शून्य से बाहर निकल जाता है। वह गैर-शून्य निकास `agent-native eval` को एक ड्रॉप-इन CI परिनियोजन गेट बनाता है।
+
+यह [Observability](/docs/observability) में पोस्ट-हॉक स्कोरिंग का पूरक है:
+
+- **अवलोकन का स्तर** (`observability/evals.ts`) - _"यह वास्तविक दौड़ कैसे हुई?"_ निष्क्रिय, नमूना, निशान के बगल में रहता है।
+- **`*.eval.ts` (यह आदिम)** - _"क्या एजेंट इस निश्चित इनपुट पर सही काम करता है?"_ सक्रिय, नियतात्मक, CLI के माध्यम से चलने वाला एक सीआई गेट।
+
+रनर मौजूदा रजिस्ट्री से एक प्रदाता-अज्ञेयवादी इंजन/मॉडल का समाधान करता है - कोई भी मॉडल हार्डकोड नहीं होता है - इसलिए ऐप जिस भी इंजन के लिए कॉन्फ़िगर किया गया है, वही सूट उसके विरुद्ध चलता है।
+
+```an-diagram title="From fixed input to deploy gate" summary="The runner actually runs the agent loop on each case, scores the output, and exits non-zero if any scorer falls below threshold — making it a drop-in CI gate."
+{
+  "html": "<div class=\"eval-flow\"><div class=\"diagram-node\">*.eval.ts<br><small class=\"diagram-muted\">prompt + expected behavior</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Run the agent loop<br><small class=\"diagram-muted\">real engine/model</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Scorers<br><small class=\"diagram-muted\">every one must pass threshold</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box ok\">exit 0 &rarr; deploy</div><div class=\"diagram-box warn\">exit 1 &rarr; block</div></div></div>",
+  "css": ".eval-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.eval-flow .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.eval-flow .diagram-col{display:flex;flex-direction:column;gap:8px}.eval-flow .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## एक मूल्यांकन लिखना {#writing}
+
+एक `*.eval.ts` फ़ाइल को ऐप में कहीं भी छोड़ें (या एक `evals/*.ts` फ़ाइल)। प्रत्येक फ़ाइल `export default defineEval(...)` (या उनमें से एक सरणी निर्यात करती है):
+
+```ts
+// evals/greeting.eval.ts
+import { defineEval, contains, llmJudge } from "@agent-native/core/eval";
+
+export default defineEval({
+  name: "greets the user by name",
+  input: { prompt: "Say hi to Ada." },
+  threshold: 0.7, // per-scorer pass bar; default 0.5
+  scorers: [
+    contains("Ada"),
+    llmJudge({ criteria: "friendliness", rubric: "1.0 = warm greeting" }),
+  ],
+});
+```
+
+ईवल तभी पास होता है जब **प्रत्येक** स्कोरर सीमा को पूरा करता है। कुंजी `defineEval` फ़ील्ड:
+
+| फ़ील्ड      | प्रकार                | नोट्स                                                       |
+| ----------- | --------------------- | ----------------------------------------------------------- |
+| `name`      | स्ट्रिंग              | आवश्यक. रिपोर्ट में दिखाया गया है.                          |
+| `input`     | `{ prompt, history }` | आवश्यक `prompt`; `{ role, text }` मोड़ से पहले वैकल्पिक।    |
+| `scorers`   | `Scorer[]`            | आवश्यक है, कम से कम एक।                                     |
+| `threshold` | नंबर `0..1`           | प्रति-स्कोरर पास बार। डिफ़ॉल्ट `0.5`; CLI से अतिरंजित।      |
+| `run`       | फ़ंक्शन               | कस्टम सेटअप के लिए वैकल्पिक ओवरराइड (बीज डेटा, मल्टी-टर्न)। |
+
+स्कोरर्स को सौंपा गया एजेंट छोटा और परिवहन-अज्ञेयवादी है:
+
+```ts
+interface AgentRunOutput {
+  text: string; // concatenated assistant text
+  toolCalls: readonly string[]; // tool/action names, in call order
+  ok: boolean; // completed without a terminal error
+  error?: string;
+  runId: string;
+  durationMs: number;
+}
+```
+
+## अंतर्निहित स्कोरर {#built-in}
+
+`@agent-native/core/eval` से आयातित:
+
+| स्कोरर                   | स्कोर                                                                  | मॉडल? |
+| ------------------------ | ---------------------------------------------------------------------- | ----- |
+| `exactMatch(expected)`   | `1.0` यदि टेक्स्ट `expected` के बराबर है (छंटनी की गई, केस-असंवेदनशील) | नहीं  |
+| `contains(needles)`      | आवश्यक सबस्ट्रिंग का अंश मौजूद है (इसलिए आंशिक हिट सतह)                | नहीं  |
+| `usesTool(toolName)`     | `1.0` यदि एजेंट ने उस टूल/कार्रवाई को कम से कम एक बार लागू किया है     | नहीं  |
+| `llmJudge({ criteria })` | LLM-ए-जज ने प्राकृतिक-भाषा रूब्रिक के विरुद्ध स्कोर किया, → `0..1`     | हां   |
+
+`exactMatch` और `contains` एक वैकल्पिक `{ caseSensitive }` लें। `llmJudge` `{ criteria, rubric?, name?, scoreRange? }` लेता है - इसका आउटपुट `[0, 1]` के लिए सामान्यीकृत होता है, और जज मॉडल वही होता है जो धावक ने हल किया हो (हार्डकोडेड प्रदाता कभी नहीं)।
+
+## कस्टम स्कोरर: 4-चरणीय पाइपलाइन {#custom}
+
+`createScorer` मास्ट्रा-शैली 4-चरणीय पाइपलाइन से एक स्कोरर बनाता है। केवल `generateScore` आवश्यक है:
+
+```an-diagram title="The 4-step scorer pipeline" summary="preprocess and analyze default to identity; only generateScore is required. analyze can run plain JS or call an LLM judge via ctx."
+{
+  "html": "<div class=\"scorer\"><div class=\"diagram-card\"><span class=\"diagram-pill\">preprocess(run)</span><small class=\"diagram-muted\">transform the run/output &middot; optional</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">analyze(x, ctx)</span><small class=\"diagram-muted\">plain JS or LLM judge &middot; optional</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">generateScore(a)</span><small class=\"diagram-muted\">&rarr; 0..1 normalized &middot; <strong>required</strong></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">generateReason</span><small class=\"diagram-muted\">human-readable why &middot; optional</small></div></div>",
+  "css": ".scorer{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.scorer .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.scorer .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+```text
+preprocess(run)     → x          transform the run/output (optional)
+analyze(x, ctx)     → analysis   plain JS OR an LLM judge (optional)
+generateScore(a)    → 0..1       REQUIRED, normalized
+generateReason(...) → string     human-readable why (optional)
+```
+
+`preprocess` और `analyze` पहचान के लिए डिफ़ॉल्ट हैं (स्कोरर कच्चा `AgentRunOutput` देखता है)। `analyze` चरण को LLM-समर्थित स्कोरिंग के लिए प्रदाता-अज्ञेयवादी `judge()` सहायक के साथ एक `ctx` प्राप्त होता है:
+
+```ts
+import { createScorer, clamp01 } from "@agent-native/core/eval";
+
+// A scorer that rewards short, tool-using answers.
+const concise = createScorer({
+  name: "concise_with_tool",
+  analyze(run) {
+    return {
+      words: run.text.trim().split(/\s+/).length,
+      usedTool: run.toolCalls.length > 0,
+    };
+  },
+  generateScore({ words, usedTool }) {
+    if (!usedTool) return 0;
+    return clamp01(1 - Math.max(0, words - 40) / 200);
+  },
+  generateReason({ analysis }) {
+    return `${analysis.words} words, tool used: ${analysis.usedTool}`;
+  },
+});
+```
+
+## गेट चलाना {#cli}
+
+```bash
+agent-native eval                    # run every *.eval.ts; non-zero exit on failure
+agent-native eval billing            # only files whose path contains "billing"
+agent-native eval --json             # machine-readable report (for CI)
+agent-native eval --threshold 0.8    # override every eval's pass threshold (0..1)
+```
+
+कमांड मौजूदा ऐप के तहत `**/*.eval.ts` और `evals/*.ts` की खोज करता है, प्रत्येक इनपुट के लिए एजेंट चलाता है, इसे स्कोर करता है, एक पढ़ने योग्य तालिका (या JSON) प्रिंट करता है, और **यदि इसकी सीमा से नीचे कोई भी ईवल स्कोर है तो गैर-शून्य से बाहर निकल जाता है**।
+
+निकास कोड:
+
+| कोड | अर्थ                                                                |
+| --- | ------------------------------------------------------------------- |
+| `0` | सभी ईवल पास हो गए - _या_ कोई ईवल फाइल नहीं मिली (सीआई-अनुकूल)।      |
+| `1` | कम से कम एक ईवल ने सीमा से नीचे स्कोर किया, या सुइट में त्रुटि हुई। |
+| `2` | खराब तर्क (उदाहरण के लिए `[0, 1]` के बाहर `--threshold`)।           |
+
+### सीआई परिनियोजन गेट के रूप में {#ci}
+
+इसे उस पाइपलाइन में जोड़ें जो परिनियोजन से पहले चलती है:
+
+```yaml
+# .github/workflows/deploy.yml (excerpt)
+- run: npx agent-native eval --json
+```
+
+एक प्रतिगमन जो किसी भी स्कोरर को सीमा से नीचे गिरा देता है वह चरण विफल हो जाता है और तैनाती को अवरुद्ध कर देता है। बिना eval फ़ाइलों वाला ऐप `0` से बाहर निकल जाता है, इसलिए evals को अपनाना प्रति ऐप ऑप्ट-इन है।
+
+## आगे क्या
+
+- [**Observability**](/docs/observability) - वास्तविक उत्पादन रन (पूरक परत) की पोस्ट-हॉक स्कोरिंग
+- [**Actions**](/docs/actions) - उपकरण/actions जो `toolCalls` में दिखाई देते हैं
+- [**Agent Teams**](/docs/agent-teams) - उप-एजेंट एक eval व्यायाम कर सकते हैं

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

@@ -0,0 +1,360 @@
+---
+title: "एक्सटेंशन"
+description: "आपके उपयोगकर्ता आपके टेम्प्लेट के अंदर मिनी-ऐप्स बनाते हैं - एनालिटिक्स में एक कस्टम KPI टाइल, कैलेंडर में एक मीटिंग-तैयारी चेकलिस्ट, मेल में एक संपर्क CRM विजेट। कोई तैनाती नहीं, कोई कोड संपादन नहीं, कोई स्कीमा परिवर्तन नहीं।"
+---
+
+# एक्सटेंशन
+
+एक्सटेंशन **मिनी-ऐप्स हैं जिन्हें आपके उपयोगकर्ता आपके टेम्पलेट के अंदर बनाते हैं**।
+
+यदि आपने क्विकबुक ऑनलाइन का उपयोग किया है, तो आपने मॉडल देखा है: QBO एक मुख्य लेखांकन उत्पाद को शिप करता है, और छोटे कस्टम विजेट पर उपयोगकर्ता परत - एक कस्टम रिपोर्ट, एक पेरोल कैलकुलेटर, एक कर-नियम चेकर - जो एक ही ऐप के अंदर रहते हैं और एक ही डेटा का उपयोग करते हैं। एक्सटेंशन उस विचार का एजेंट-मूल संस्करण हैं, सिवाय इसके कि आपके उपयोगकर्ता कोई कोड नहीं लिखते हैं। वे जो चाहते हैं उसका वर्णन करते हैं और एजेंट उसे बनाता है।
+
+फ़्रेमिंग मायने रखती है: एक एक्सटेंशन सामान्य "आप जो चाहें करें" सैंडबॉक्स नहीं है। यह एक **मिनी-ऐप है जो एक विशिष्ट टेम्पलेट** का विस्तार करता है - मेल, एनालिटिक्स, कैलेंडर, क्लिप्स, डिज़ाइन - और उस टेम्पलेट के actions और डेटा का उपयोग करता है। एक मेल एक्सटेंशन ईमेल पढ़ता है. एक एनालिटिक्स एक्सटेंशन डैशबोर्ड के मेट्रिक्स को पढ़ता है। एक कैलेंडर एक्सटेंशन खुले ईवेंट पर कार्य करता है। वे मेजबान उत्पाद का हिस्सा महसूस करते हैं क्योंकि वे मेजबान उत्पाद का हिस्सा हैं।
+
+तीन चीज़ें एक्सटेंशन को कार्यशील बनाती हैं:
+
+- **कोई कोड नहीं, कोई तैनाती नहीं।** एजेंट उन्हें लिखता है और वे कुछ ही सेकंड में लाइव हो जाते हैं। डेटाबेस में संग्रहीत, रेपो में नहीं।
+- **टेम्पलेट के डेटा तक पूर्ण पहुंच।** एक्सटेंशन उसी actions को कॉल कर सकते हैं जिसे एजेंट कॉल करता है - मेल में `list-emails`, स्लाइड्स में `list-decks`, क्लिप्स में `list-recordings` - इसलिए उनके पास वह सब कुछ है जो होस्ट ऐप के पास है।
+- **अंतर्निहित भंडारण।** प्रत्येक एक्सटेंशन का अपना प्रति-उपयोगकर्ता / प्रति-संगठन कुंजी-मूल्य स्टोर होता है, इसलिए यह आपके द्वारा नई SQL तालिका जोड़े बिना स्थिति को बचा सकता है।
+
+यदि किसी टेम्प्लेट को उपयोगकर्ता-लिखित एक्सटेंशन को उजागर नहीं करना चाहिए, तो सेट करें
+`createAgentChatPlugin()` पर `extensionTools: false`। वह
+एजेंट-फेसिंग एक्सटेंशन actions और शेष को छोड़ते समय त्वरित मार्गदर्शन
+ऐप एजेंट बरकरार।
+
+```an-diagram title="The sandbox bridge" summary="Extension HTML runs in an isolated iframe and reaches the host only through a fixed set of bridge helpers — every call is scoped and access-checked."
+{
+  "html": "<div class=\"ext-bridge\"><div class=\"diagram-card sandbox\" data-rough><span class=\"diagram-pill warn\">Sandboxed iframe</span><small class=\"diagram-muted\">Alpine.js HTML &middot; no host cookies, session, or DOM</small><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\">extensionData</span><span class=\"diagram-pill\">extensionFetch</span></div></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Host template<br><small class=\"diagram-muted\">actions, auto-scoped SQL</small></div><div class=\"diagram-box\">Secret proxy<br><small class=\"diagram-muted\"><code>${keys.NAME}</code>, domain-locked</small></div><div class=\"diagram-box\">External APIs<br><small class=\"diagram-muted\">via extensionFetch only</small></div></div></div>",
+  "css": ".ext-bridge{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ext-bridge .sandbox{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.ext-bridge .ext-helpers{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}.ext-bridge .diagram-col{display:flex;flex-direction:column;gap:8px}.ext-bridge .diagram-arrow{font-size:24px}"
+}
+```
+
+एक्सटेंशन को **स्थानीय फ़ाइल मोड में रेपो-समर्थित** भी किया जा सकता है। उस वर्कफ़्लो में,
+`agent-native.json` एक `extensions` फ़ोल्डर घोषित करता है, प्रत्येक एक्सटेंशन में एक
+`extension.json` मेनिफ़ेस्ट प्लस एक HTML प्रविष्टि फ़ाइल, और ऐप उन्हें प्रस्तुत करता है
+फ़ाइलें उसी सैंडबॉक्स के माध्यम से। फ़ाइल-समर्थित एक्सटेंशन को परिवर्तित करके संपादित किया जाता है
+रेपो फ़ाइलें; डेटाबेस-समर्थित एक्सटेंशन रनटाइम क्रिएट/एडिट/शेयर
+अनुभव नीचे वर्णित है।
+
+## एक त्वरित गैलरी {#gallery}
+
+असली एक्सटेंशन जो लोग वास्तव में बनाएंगे, उन्हें उस टेम्पलेट के आधार पर समूहीकृत किया जाएगा जिसमें वे रहते हैं। प्रत्येक एक केंद्रित चीज़ है - स्विस-सेना चाकू नहीं।
+
+### मेल
+
+एक उपयोगकर्ता `priya@acme.com` से एक ईमेल पढ़ रहा है। किस प्रकार का विजेट यहीं मदद करेगा?
+
+- **संपर्क नोट्स** - उपयोगकर्ता जिसे भी ईमेल कर रहा है, उसके लिए एक स्टिकी-नोट पैड पिन किया गया है। उस संपर्क के लिए नोट्स लोड करता है, उपयोगकर्ता को और अधिक लिखने देता है।
+- **इस व्यक्ति के साथ हाल के थ्रेड** - खुले संपर्क के साथ पिछले पांच थ्रेड की एक छोटी सूची, इनबॉक्स दृश्य से अलग।
+- **CRM संवर्धन** - संपर्क की कंपनी का आकार, अंतिम बैठक की तारीख, या आपके CRM से खुले सौदे खींचता है।
+- **मीटिंग शेड्यूलर शॉर्टकट** - "अगले सप्ताह समय ढूंढें" को एक-क्लिक "ये स्लॉट भेजें" विजेट में बदल देता है।
+
+स्केच - संपर्क नोट्स (जिसे आप ईमेल कर रहे हैं उससे जुड़ा एक नोट सहेजता है):
+
+```html
+<div
+  class="p-4"
+  x-data="{
+    contactEmail: window.slotContext?.contactEmail,
+    note: '',
+    async init() {
+      if (!this.contactEmail) return;
+      const saved = await extensionData.get('notes', this.contactEmail);
+      if (saved) this.note = JSON.parse(saved.data).text;
+    },
+    async save() {
+      await extensionData.set('notes', this.contactEmail, { text: this.note });
+    }
+  }"
+>
+  <p class="text-xs text-muted-foreground mb-2" x-text="contactEmail"></p>
+  <textarea
+    x-model="note"
+    @blur="save()"
+    class="w-full rounded-md border bg-background p-2 text-sm"
+    rows="4"
+    placeholder="Notes about this contact..."
+  ></textarea>
+</div>
+```
+
+### एनालिटिक्स
+
+एक उपयोगकर्ता डैशबोर्ड को देख रहा है। कौन सी टाइल गायब है?
+
+- **कस्टम KPI बॉक्स** - एक मीट्रिक के लिए एक बड़ी संख्या जो एक अंतर्निहित पैनल नहीं है। "परीक्षण इस सप्ताह शुरू हुआ," "MRR डेल्टा बनाम पिछले महीने।"
+- **लक्ष्य ट्रैकर** - उपयोगकर्ता द्वारा चुने गए मीट्रिक को खींचता है और उपयोगकर्ता द्वारा टाइप किए गए लक्ष्य के विरुद्ध प्रगति दिखाता है।
+- **शीर्ष ग्राहक लीडरबोर्ड** - ग्राहक तालिका के साथ एक मीट्रिक जोड़ता है, शीर्ष 10 में रैंक करता है।
+
+स्केच - कस्टम KPI बॉक्स (एनालिटिक्स टेम्पलेट के `appAction` प्रश्नों में से एक को कॉल करता है):
+
+```html
+<div
+  class="p-4"
+  x-data="{
+  value: null,
+  async init() {
+    const result = await appAction('query-agent-native-analytics', {
+      metric: 'trials_started',
+      range: '7d'
+    });
+    this.value = result?.total ?? 0;
+  }
+}"
+>
+  <p class="text-xs uppercase tracking-wider text-muted-foreground">
+    Trials this week
+  </p>
+  <p class="text-3xl font-bold mt-1" x-text="value ?? '—'"></p>
+</div>
+```
+
+### कैलेंडर
+
+उपयोगकर्ता के पास एक ईवेंट खुला है। उस पल में क्या मदद मिलेगी?
+
+- **मीटिंग तैयारी चेकलिस्ट** - खुले कार्यक्रम के लिए एजेंडा आइटम, उपस्थित लोगों और पूर्व थ्रेड सारांश को स्वचालित रूप से लोड करता है।
+- **यात्रा का समय** - "मिशन स्थान पर आपकी अगली बैठक तक आपके पास 35 मिनट हैं।"
+- **समयक्षेत्र सहायक** — एक नज़र में प्रत्येक सहभागी के स्थानीय समय में मीटिंग का समय दिखाता है।
+
+### क्लिप
+
+एक उपयोगकर्ता स्क्रीन रिकॉर्डिंग की समीक्षा कर रहा है। उस दृश्य को क्या बढ़ाता है?
+
+- **एक्शन आइटम एक्सट्रैक्टर** - क्लिप ट्रांसक्रिप्ट पढ़ता है (एजेंट इसे `appAction` के माध्यम से लाता है), कार्यों को सूचीबद्ध करता है।
+- **ऑटो-शेयर** — एक-क्लिक "इस क्लिप के लिंक को मेरे #रिकॉर्डिंग Slack चैनल पर पोस्ट करें।"
+- **हाइलाइट रील** - एजेंट द्वारा बनाए गए अध्यायों को खींचता है और उन्हें त्वरित नेविगेशन मेनू में बदल देता है।
+
+### डिज़ाइन
+
+एक उपयोगकर्ता के पास ड्राफ्ट अल्पाइन/Tailwind पेज खुला है। प्रोटोटाइपिंग लूप को क्या सुचारू करेगा?
+
+- **ब्रांड रंग नमूना** — उपयोगकर्ता के ब्रांड कॉन्फिगरेशन से पैलेट निकाला गया, किसी रंग को संपादक में कॉपी करने के लिए क्लिक करें।
+- **एसेट पिकर** - उपयोगकर्ता द्वारा अपलोड की गई छवियों को सूचीबद्ध करता है, क्लिक करने पर URL को हटा देता है।
+- **स्पेसिंग इंस्पेक्टर** - सक्रिय पेज द्वारा उपयोग किए जाने वाले गैप/पैडिंग/मार्जिन टोकन को दिखाता है, ताकि उपयोगकर्ता लगातार बना रह सके।
+
+इन सभी में पैटर्न: एक्सटेंशन **उस पल** के बारे में हैं जब उपयोगकर्ता होस्ट टेम्पलेट के अंदर होता है। एजेंट को पहले से ही पता है कि कौन सा संपर्क, कौन सा डैशबोर्ड, कौन सा ईवेंट, कौन सा क्लिप - एक्सटेंशन उस संदर्भ का उपयोग करता है।
+
+## उपयोगकर्ता इसे कैसे बनाता है {#building}
+
+सरल पथ:
+
+1. **साइडबार में "नया एक्सटेंशन"** पर क्लिक करें (या बस चैट में पूछें)।
+2. **एक वाक्य में बताएं कि आप क्या चाहते हैं।** "मैं जिस संपर्क को ईमेल कर रहा हूं उसके लिए एक स्टिकी-नोट पैड।" "परीक्षण के लिए एक KPI बॉक्स इस सप्ताह शुरू हुआ।"
+3. **एजेंट इसे लिखता है और यह आपकी एक्सटेंशन सूची में उपयोग के लिए तैयार दिखाई देता है।**
+
+संपादित करने के लिए कोई फ़ाइल नहीं, कोई परिनियोजन नहीं। एजेंट सही सहायकों (`appAction`, `extensionData`, `extensionFetch`) को चुनता है और Alpine.js HTML लिखता है।
+
+यदि एक्सटेंशन को API कुंजी - CRM टोकन, एक मौसम API - की आवश्यकता होती है, तो एजेंट आपको बताता है कि क्या जोड़ना है और कहां जोड़ना है। कुंजियाँ एन्क्रिप्टेड रूप में संग्रहित की जाती हैं और विशिष्ट डोमेन पर लॉक की जाती हैं।
+
+यदि आप बाद में कुछ बदलना चाहते हैं, तो बस इतना कहें: "मेरे संपर्क नोट्स में एक खोज बॉक्स जोड़ें।" एजेंट HTML को उसके स्थान पर संपादित करता है - पूरी चीज़ का कोई पुनर्जनन नहीं।
+
+प्रत्येक परिवर्तन संस्करणित है। देखने के लिए एक्सटेंशन व्यूअर का इतिहास नियंत्रण खोलें
+सहेजे गए संस्करण, पिछले संस्करण से अंतर का निरीक्षण करें, और एक पुनर्स्थापित करें
+स्वामित्व बदले बिना पुराना नाम/विवरण/आइकन/सामग्री स्नैपशॉट या
+साझा करना।
+
+## एक एक्सटेंशन क्या कर सकता है {#capabilities}
+
+iframe सैंडबॉक्स के अंदर, प्रत्येक एक्सटेंशन में `window` पर ये सहायक होते हैं:
+
+| सहायक                                            | उद्देश्य                                                                | उदाहरण                                                    |
+| ------------------------------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------- |
+| `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 ...')`                               |
+| `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' })`           |
+| `extensionData.get(collection, id, opts?)`       | एकल आइटम प्राप्त करें                                                   | `extensionData.get('notes', 'note-1')`                    |
+| `extensionData.remove(collection, id, opts?)`    | कोई मौजूदा आइटम हटाएं                                                   | `extensionData.remove('notes', 'note-1')`                 |
+
+आधारभूत तीन नियम:
+
+- **`dbQuery` की तुलना में `appAction` को प्राथमिकता दें।** Actions टेम्पलेट की आधिकारिक सतह हैं - वे आपके लिए एक्सेस कंट्रोल, स्कोपिंग और सत्यापन संभालते हैं। कच्चे SQL तक तभी पहुंचें जब कोई कार्रवाई उपयुक्त न हो।
+- **टेम्पलेट डेटा के लिए `appAction` का उपयोग करें।** एक्सटेंशन `appFetch` फ्रेमवर्क `/_agent-native/*` एंडपॉइंट तक सीमित है; टेम्पलेट `/api/*` मार्ग iframe ब्रिज द्वारा अवरुद्ध हैं।
+- **नई तालिकाएँ बनाने के बजाय `extensionData` को प्राथमिकता दें।** प्रत्येक एक्सटेंशन को अपना अलग कुंजी-मूल्य स्टोर मिलता है। कोई स्कीमा नहीं, कोई माइग्रेशन नहीं. उपयोगकर्ता के संगठन के साथ साझा करने के लिए `{ scope: 'org' }`, निजी के लिए `'user'` (डिफ़ॉल्ट) सेट करें।
+
+```html
+<script>
+  // Private to me
+  await extensionData.set('notes', 'note-1', { title: 'My note' });
+
+  // Shared with my org
+  await extensionData.set('notes', 'team-note', { title: 'Team note' }, { scope: 'org' });
+
+  // List everything visible to me (mine + org)
+  const all = await extensionData.list('notes', { scope: 'all' });
+</script>
+```
+
+बाहरी APIs `extensionFetch` से गुजरते हैं, जो कॉल सर्वर-साइड को प्रॉक्सी करता है और `${keys.NAME}` टेम्पलेट के माध्यम से रहस्यों को प्रतिस्थापित करता है:
+
+```html
+<script>
+  const res = await extensionFetch('https://api.github.com/user', {
+    headers: { Authorization: 'Bearer ${keys.GITHUB_TOKEN}' },
+  });
+</script>
+```
+
+वास्तविक कुंजी कभी भी ब्राउज़र तक नहीं पहुंचती है। प्रत्येक कुंजी डोमेन की अनुमति सूची में बंद है, इसलिए लीक हुआ एक्सटेंशन इसे कहीं और नहीं ले जा सकता है।
+
+## स्लॉट - होस्ट UI के अंदर एक एक्सटेंशन डालना {#slots}
+
+ऊपर दी गई गैलरी बताती है कि एक एक्सटेंशन क्या करता है। स्लॉट वर्णन करते हैं कि यह कहां दिखाई देता है।
+
+डिफ़ॉल्ट रूप से, एक एक्सटेंशन एक्सटेंशन सूची में अपने स्वयं के पृष्ठ पर रहता है - इसे एक छोटे ऐप की तरह खोलें। यह डैशबोर्ड, कैलकुलेटर और स्टैंडअलोन विजेट के लिए ठीक है।
+
+लेकिन सबसे अधिक QBO-आकार का उपयोग मामला अलग है: उपयोगकर्ता चाहता है कि उनका विजेट टेम्पलेट के UI के अंदर पिन हो - मेल के साइडबार में संपर्क जानकारी के तहत, एक एनालिटिक्स डैशबोर्ड के कोने में, एक कैलेंडर ईवेंट के दाईं ओर। **स्लॉट** इसी के लिए हैं।
+
+एक स्लॉट एक नामित विजेट क्षेत्र है जो एक टेम्पलेट शिप करता है:
+
+| टेम्पलेट       | उदाहरण स्लॉट                   | यह कहां दिखाई देता है                         |
+| -------------- | ------------------------------ | --------------------------------------------- |
+| **मेल**        | `mail.contact-sidebar.bottom`  | प्रत्येक ईमेल थ्रेड पर संपर्क जानकारी के नीचे |
+| **एनालिटिक्स** | `analytics.dashboard.tiles`    | डैशबोर्ड के अंतर्निर्मित पैनलों के साथ        |
+| **कैलेंडर**    | `calendar.event-detail.bottom` | खुले इवेंट के नीचे                            |
+| **क्लिप**      | `clips.right-panel.tabs`       | क्लिप समीक्षा पैनल में एक नया टैब             |
+
+जब कोई एक्सटेंशन **स्लॉट में इंस्टॉल** किया जाता है, तो होस्ट संबंधित संदर्भ - संपर्क का ईमेल, डैशबोर्ड आईडी, इवेंट आईडी - को आईफ्रेम में धकेलता है। उपयोगकर्ता क्या देख रहा है यह जानने के लिए एक्सटेंशन `window.slotContext` पढ़ता है।
+
+```an-diagram title="Slots push context into the widget" summary="The host template owns named slots; installing an extension into one feeds it window.slotContext for whatever the user is currently viewing."
+{
+"html": "<div class=\"slot\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Mail thread</span><small class=\"diagram-muted\">slot <code>mail.contact-sidebar.bottom</code></small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box accent\"><code>window.slotContext</code><br><small class=\"diagram-muted\">{ contactEmail }</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Contact notes</span><small class=\"diagram-muted\">loads notes for that contact &mdash; same widget, different context</small></div></div>",
+"css": ".slot{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.slot .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px;min-width:180px}.slot .diagram-arrow{font-size:22px}"
+}
+
+```
+
+### एक ठोस उदाहरण
+
+गैलरी से संपर्क-नोट्स एक्सटेंशन की कल्पना करें। अपने आप में, यह एक स्टैंडअलोन विजेट है। इसे मेल संपर्क साइडबार के अंदर प्रदर्शित करने के लिए:
+
+1. एक बार एक्सटेंशन बनाएं। `window.slotContext.contactEmail` का उपयोग करें ताकि यह पता चल सके कि उपयोगकर्ता किस संपर्क पर है।
+2. इसे वह स्थान बताएं जिसे यह भर सकता है: `add-extension-slot-target { extensionId, slotId: "mail.contact-sidebar.bottom" }`.
+3. इसे इंस्टॉल करें: `install-extension { extensionId, slotId: "mail.contact-sidebar.bottom" }`.
+
+अगली बार जब आप कोई ईमेल थ्रेड खोलते हैं, तो आपका स्टिकी-नोट पैड संपर्क जानकारी के ठीक नीचे होता है - जिस व्यक्ति को आप ईमेल कर रहे हैं उसके नोट्स से भरा होता है। किसी भिन्न थ्रेड पर स्विच करें, _उस_ संपर्क लोड के लिए नोट्स। एक ही विस्तार, अलग संदर्भ, कोई पुनर्लेखन नहीं।
+
+व्यवहार में आप उन तीन आदेशों को हाथ से नहीं चलाते हैं। बस "इस विजेट को मेरे संपर्क साइडबार पर पिन करें" कहें और एजेंट आपके लिए लक्ष्य + इंस्टॉल संभालता है।
+
+> **स्लॉट एक _अतिरिक्त_ क्षमता है, कोई पूर्वावश्यकता नहीं।** बहुत सारे उपयोगी एक्सटेंशन कभी भी एक स्लॉट में इंस्टॉल नहीं होते हैं - वे अपने पेज पर खुशी से रहते हैं। जब विजेट को होस्ट टेम्पलेट में उपयोगकर्ता जो देख रहा है उसके बगल में होना चाहिए तो स्लॉट तक पहुंचें।
+
+स्लॉट्स पर गहन विवरण के लिए - उन्हें अपने टेम्पलेट में कैसे घोषित करें, संदर्भ अनुबंध कैसे काम करता है, इंस्टॉल का दायरा कैसे बढ़ाया जाता है - `extension-points` कौशल देखें। `.agents/skills/` के तहत प्रत्येक मचान टेम्पलेट के अंदर Skills जहाज; वे कैसे काम करते हैं, इसके लिए [Skills Guide](/docs/skills-guide) देखें।
+
+## स्थानीय फ़ाइल एक्सटेंशन {#local-file-extensions}
+
+स्थानीय फ़ाइल मोड किसी कार्यक्षेत्र को रेपो में एक्सटेंशन रखने देता है:
+
+```text
+extensions/
+  doc-status/
+    extension.json
+    index.html
+```
+
+```json
+{
+  "id": "doc-status",
+  "name": "Doc Status",
+  "description": "Shows metadata for the selected Content file.",
+  "entry": "index.html",
+  "slots": ["content.sidebar.bottom"],
+  "permissions": {
+    "appActions": ["list-documents"],
+    "extensionData": true
+  }
+}
+```
+
+`agent-native.json` में संबंधित ऐप में फ़ोल्डर जोड़ें:
+
+```json
+{
+  "apps": {
+    "content": {
+      "mode": "local-files",
+      "roots": [{ "name": "Docs", "path": "docs", "extensions": [".mdx"] }],
+      "components": "components",
+      "extensions": "extensions"
+    }
+  }
+}
+```
+
+ऐप फ़ाइल-समर्थित एक्सटेंशन को डेटाबेस-समर्थित एक्सटेंशन और रेंडर के साथ सूचीबद्ध करता है
+उन्हें सामान्य सैंडबॉक्स आईफ्रेम के माध्यम से। `extension.json`
+एक्सटेंशन को मिलान `ExtensionSlot`s में ऑटो-माउंट करें; कोई प्रति-उपयोगकर्ता नहीं है
+SQL स्थानीय एक्सटेंशन के लिए पंक्ति स्थापित करें।
+
+स्थानीय एक्सटेंशन में सख्त v1 अनुमति मॉडल होता है:
+
+- `extensionData` अक्षम होने तक छोटी रनटाइम स्थिति के लिए उपलब्ध है।
+- `appAction` कॉल को `permissions.appActions` में स्पष्ट रूप से सूचीबद्ध किया जाना चाहिए।
+- `dbQuery`, `dbExec`, और `extensionFetch` अभी के लिए अवरुद्ध हैं।
+- SQL-समर्थित अपडेट, डिलीट, शेयर और इतिहास actions एक संदेश लौटाता है
+  स्थानीय प्रविष्टि फ़ाइल की ओर वापस इंगित करता है।
+
+जब उपयोगकर्ताओं को विजेट बनाना/साझा/संपादित करना हो तो डेटाबेस-समर्थित एक्सटेंशन का उपयोग करें
+रनटाइम. जब एक्सटेंशन रेपो-फर्स्ट
+कार्यस्थान और बाकी के साथ समीक्षा योग्य, पैच करने योग्य और संस्करणित होना चाहिए
+फ़ाइलें.
+
+## साझा करना {#sharing}
+
+एक्सटेंशन उस उपयोगकर्ता के लिए निजी होते हैं जिसने उन्हें डिफ़ॉल्ट रूप से बनाया है। साझा करने के लिए:
+
+- **संगठन-दृश्य** — संगठन में हर कोई इसे देख और उपयोग कर सकता है।
+- **प्रति-उपयोगकर्ता अनुदान** — विशिष्ट लोगों को दर्शक/संपादक/व्यवस्थापक के रूप में आमंत्रित करें।
+
+साझा एक्सटेंशन के अपने स्वयं के URL होते हैं और दस्तावेज़, डेक और डैशबोर्ड के समान शेयर संवाद में प्लग होते हैं। स्लॉट इंस्टॉल हमेशा व्यक्तिगत होते हैं - किसी एक्सटेंशन को साझा करने का मतलब है कि अन्य लोग इसे इंस्टॉल कर सकते हैं; यह इसे उनके UI पर ऑटो-पिन नहीं करता है।
+
+## एक्सटेंशन बनाम ऐप कोड संपादित करना {#vs-app-code}
+
+फ्रेमवर्क एजेंट को ऐप के स्रोत कोड को सीधे संपादित करने देता है - घटक, मार्ग, शैलियाँ। तो इसके बजाय आपको एक्सटेंशन के लिए कब पहुंचना चाहिए?
+
+|                               | एक्सटेंशन                                        | ऐप कोड संपादित करें                                |
+| ----------------------------- | ------------------------------------------------ | -------------------------------------------------- |
+| **द्वारा निर्मित**            | एजेंट (या उपयोगकर्ता) रनटाइम पर                  | एजेंट स्रोत फ़ाइलों को संपादित कर रहा है           |
+| **संग्रहीत**                  | डेटाबेस                                          | गिट रिपोजिटरी                                      |
+| **एक निर्माण की आवश्यकता है** | नहीं                                             | हां                                                |
+| **एक तैनाती की आवश्यकता है**  | नहीं                                             | हां                                                |
+| **दायरा**                     | एक उपयोगकर्ता (या संगठन के साथ साझा किया गया)    | संपूर्ण उत्पाद, प्रत्येक उपयोगकर्ता                |
+| **के लिए सर्वोत्तम**          | व्यक्तिगत विजेट, कस्टम KPI, प्रति-टीम उपयोगिताएँ | मुख्य विशेषताएं जो सभी उपयोगकर्ताओं तक पहुंचती हैं |
+
+सामान्य नियम: **यदि यह एक उपयोगकर्ता या एक टीम के लिए है, तो यह एक एक्सटेंशन है।** यदि टेम्पलेट के प्रत्येक उपयोगकर्ता को यह मिलना चाहिए, तो इसे एक वास्तविक सुविधा के रूप में शिप करें।
+
+## सुरक्षा {#security}
+
+```an-callout
+{ "tone": "success", "body": "**The raw secret never reaches the browser.** `extensionFetch` substitutes `${keys.NAME}` server-side and each key is locked to a URL allowlist, so even a leaked extension can't exfiltrate it elsewhere." }
+```
+
+एक्सटेंशन सैंडबॉक्स वाले iframe में चलते हैं:
+
+- **मूल ऐप की कुकीज़, सत्र और DOM से पृथक**।
+- **सर्वर-साइड गुप्त इंजेक्शन** `${keys.NAME}` टेम्पलेट के माध्यम से - वास्तविक कुंजी मान कभी भी ब्राउज़र तक नहीं पहुंचता है।
+- **डोमेन-लॉक रहस्य** - प्रत्येक कुंजी एक URL अनुमति सूची से बंधी है; प्रॉक्सी अन्य होस्ट के अनुरोधों को अस्वीकार कर देता है।
+- **निजी-नेटवर्क सुरक्षा** — एक्सटेंशन आंतरिक पते तक नहीं पहुंच सकते।
+- **प्रमाणीकरण आवश्यक** - एक्सटेंशन केवल लॉग-इन उपयोगकर्ताओं के लिए चलते हैं, और `dbQuery` / `dbExec` कॉल ऑटो-स्कोप हैं।
+
+## नामकरण के बारे में जानने योग्य कुछ बातें {#naming-back-compat}
+
+यदि आप SQL या स्रोत के बारे में सोच रहे हैं, तो आपको "एक्सटेंशन" और "टूल" नामों का मिश्रण दिखाई देगा। त्वरित डिकोडर:
+
+- उपयोगकर्ता-सामना करने वाले आदिम को "टूल्स" कहा जाता था। यह अब **एक्सटेंशन** है।
+- भौतिक SQL तालिकाएँ (`tools`, `tool_data`, `tool_shares`, `tool_slots`, `tool_slot_installs`) अपने मूल नाम रखती हैं - तालिका का नाम बदलना एक विनाशकारी माइग्रेशन है, और फ्रेमवर्क विनाशकारी माइग्रेशन नहीं भेजता है।
+- Drizzle / TypeScript निर्यात नए नामों का उपयोग करते हैं: `extensions`, `extensionData`, `extensionShares`, `extensionSlots`, `extensionSlotInstalls`।
+- एक्सटेंशन के आईफ्रेम के अंदर, विहित सहायक `extensionFetch` और `extensionData` हैं। पुराने नाम `toolFetch` और `toolData` अभी भी ठीक हैं, इसलिए पुराना एक्सटेंशन HTML काम करता रहता है।
+
+आप इसे सामान्य उपयोग में भी नहीं देख पाएंगे, लेकिन एजेंट के पास "LLM टूल्स" नामक एक तीसरी संबंधित अवधारणा है - एक मॉडल मोड़ पर फ़ंक्शन-कॉल सतह क्षेत्र (`defineAction`, MCP, आदि के माध्यम से परिभाषित)। वे फ़ंक्शन-कॉलिंग आदिम हैं, उपयोगकर्ता-सामना करने वाले विजेट नहीं। जब यह पृष्ठ "एक्सटेंशन" कहता है, तो इसका अर्थ उपयोगकर्ता-सामना करने वाला विजेट है; जब अन्य दस्तावेज़ `defineAction` के साथ "टूल" कहते हैं, तो यह LLM अवधारणा है।
+
+## आगे क्या है
+
+- [**Templates**](/docs/cloneable-saas) - होस्ट ऐप्स एक्सटेंशन विस्तारित होते हैं
+- [**Actions**](/docs/actions) - वे ऑपरेशन जो एक्सटेंशन `appAction` के माध्यम से कॉल करता है
+- [**Sharing & Privacy**](/docs/sharing) - एक्सटेंशन दृश्यता, संगठन साझाकरण और प्रति-उपयोगकर्ता अनुदान कैसे काम करते हैं
+- [**Onboarding & API Keys**](/docs/onboarding) - सेटिंग्स UI में रहस्य कैसे सामने आते हैं
+- [**Security**](/docs/security) - फ्रेमवर्क का डेटा स्कोपिंग और एक्सेस मॉडल