@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,268 @@
+---
+title: "स्वचालन"
+description: "प्राकृतिक-भाषा स्थितियों के साथ इवेंट-ट्रिगर और शेड्यूल किए गए ऑटोमेशन"
+---
+
+# स्वचालन
+
+एक **स्वचालन** एक नियम है: _जब एक्स होता है, तो Y_ करें - प्राकृतिक भाषा में वर्णित है। एजेंट निर्देशों को निष्पादित करता है, इसलिए ऑटोमेशन के पास प्रत्येक क्रिया, टूल और MCP सर्वर तक पहुंच होती है जिसे एजेंट इंटरैक्टिव चैट में उपयोग कर सकता है।
+
+ऑटोमेशन `web-request` टूल के माध्यम से **इवेंट ट्रिगर्स**, **प्राकृतिक-भाषा स्थितियों**, और **आउटबाउंड HTTP** के साथ [recurring jobs](/docs/recurring-jobs) का विस्तार करते हैं। वे आवर्ती नौकरियों के रूप में समान `jobs/<name>.md` फ़ाइल प्रारूप, भंडारण और "तीन तरीके बनाएं" वर्कफ़्लो का उपयोग करते हैं - साझा प्रारूप के लिए [Recurring Jobs](/docs/recurring-jobs#job-file) देखें। यह पृष्ठ केवल इवेंट-संचालित ऑटोमेशन के लिए जो नया है उसे कवर करता है।
+
+```an-diagram title="When X happens, do Y" summary="An event fires on the bus, an optional natural-language condition gates it, and the agent runs the automation body with full tool access."
+{
+  "html": "<div class=\"auto-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Event</span><small class=\"diagram-muted\"><code>calendar.booking.created</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Condition</span><small class=\"diagram-muted\">Haiku checks: &ldquo;email ends with @builder.io&rdquo;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">Agent runs the body</span><small class=\"diagram-muted\">actions &middot; web-request &middot; MCP &middot; sub-agents</small></div></div>",
+  "css": ".auto-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.auto-flow .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px;min-width:180px}.auto-flow .diagram-arrow{font-size:22px}"
+}
+```
+
+## दो ट्रिगर प्रकार {#trigger-types}
+
+| प्रकार     | फ़ायर तब होता है जब                                       | कुंजी फ़ील्ड       |
+| ---------- | --------------------------------------------------------- | ------------------ |
+| `schedule` | एक क्रॉन एक्सप्रेशन मेल खाता है (आवर्ती नौकरियों के समान) | `schedule` (क्रोन) |
+| `event`    | एक मेल खाता इवेंट फ्रेमवर्क इवेंट बस पर उत्सर्जित होता है | `event` (नाम)      |
+
+इवेंट ट्रिगर्स में `condition` शामिल हो सकता है - प्रेषण से पहले इवेंट पेलोड के विरुद्ध हाइकू द्वारा मूल्यांकन की गई एक प्राकृतिक-भाषा स्ट्रिंग। यदि स्थिति मेल नहीं खाती है, तो स्वचालन चुपचाप छोड़ दिया जाता है।
+
+## ऑटोमेशन बनाना {#creating}
+
+### एजेंट से पूछकर
+
+> "जब कोई @builder.io ईमेल से मीटिंग बुक करता है, तो मुझे Slack में संदेश भेजें।"
+
+एजेंट उपलब्ध घटनाओं का पता लगाता है, योजना की पुष्टि करता है, और आपके लिए स्वचालन लिखता है।
+
+### सेटिंग्स UI से
+
+ऑटोमेशन सेटिंग पैनल में दिखाई देते हैं। उपयोगकर्ता उन्हें वहां देख सकते हैं, सक्षम/अक्षम कर सकते हैं और हटा सकते हैं।
+
+तीसरा पथ - `resourcePut` के माध्यम से हाथ से `jobs/<name>.md` फ़ाइल लिखना - ठीक उसी तरह काम करता है जैसे यह [recurring jobs](/docs/recurring-jobs#creating) के लिए करता है। इवेंट-संचालित ऑटोमेशन के लिए आप नीचे दिए गए इवेंट-ट्रिगर फ्रंटमैटर को उसी फ़ाइल में जोड़ते हैं। एक इवेंट-ट्रिगर जॉब `schedule: ""` सेट करता है और `triggerType: event`, एक `event` नाम और एक वैकल्पिक `condition` प्रदान करता है:
+
+```an-annotated-code title="An event-triggered automation"
+{
+  "filename": "jobs/slack-on-builder-booking.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"\"\nenabled: true\ntriggerType: event\nevent: calendar.booking.created\ncondition: \"attendee email ends with @builder.io\"\nmode: agentic\ndomain: calendar\nrunAs: creator\n---\nSend a Slack message to #sales with the booking details.\nUse the web-request tool to POST to ${keys.SLACK_WEBHOOK}.",
+  "annotations": [
+    { "lines": "2", "label": "No cron", "note": "Event triggers set `schedule` to `\"\"` — the cron field stays empty." },
+    { "lines": "4-5", "label": "The trigger", "note": "`triggerType: event` plus the `event` name subscribes this automation to the bus." },
+    { "lines": "6", "label": "Gate", "note": "An optional natural-language `condition`, evaluated by Haiku against the payload before dispatch." },
+    { "lines": "12", "label": "Server-side secret", "note": "`${keys.SLACK_WEBHOOK}` is resolved server-side — the raw value never enters the agent's context." }
+  ]
+}
+```
+
+## स्वचालन फ्रंटमैटर {#frontmatter}
+
+ऑटोमेशन [recurring-jobs frontmatter table](/docs/recurring-jobs#frontmatter) में हर फ़ील्ड को साझा करता है। ये अतिरिक्त फ़ील्ड इवेंट ट्रिगर्स, शर्तों और निष्पादन मोड को नियंत्रित करते हैं:
+
+| फ़ील्ड        | प्रकार                           | डिफ़ॉल्ट     | विवरण                                                                                                                                                                                    |
+| ------------- | -------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `triggerType` | `"schedule"` \| `"event"`        | `"schedule"` | ऑटोमेशन कैसे सक्रिय होता है                                                                                                                                                              |
+| `event`       | स्ट्रिंग                         | _(वैकल्पिक)_ | सदस्यता के लिए ईवेंट का नाम (केवल ईवेंट ट्रिगर्स)                                                                                                                                        |
+| `condition`   | स्ट्रिंग                         | _(वैकल्पिक)_ | प्रेषण से पहले प्राकृतिक-भाषा की स्थिति का मूल्यांकन किया गया                                                                                                                            |
+| `mode`        | `"agentic"` \| `"deterministic"` | `"agentic"`  | पूर्ण एजेंट लूप. (`"deterministic"` आरक्षित है लेकिन अभी तक लागू नहीं किया गया है - इसे सेट करने वाले ऑटोमेशन को छोड़ दिया गया है। सभी मौजूदा ऑटोमेशन के लिए `"agentic"` का उपयोग करें।) |
+| `domain`      | स्ट्रिंग                         | _(वैकल्पिक)_ | ग्रुपिंग टैग (मेल, कैलेंडर, क्लिप आदि)                                                                                                                                                   |
+
+ईवेंट ट्रिगर के लिए, `schedule` `""` (खाली) है; शेड्यूल ट्रिगर के लिए इसमें क्रॉन एक्सप्रेशन होता है। डिस्पैचर वही प्रबंधित `lastRun` / `lastStatus` / `lastError` फ़ील्ड भी लिखता है जो शेड्यूलर लिखता है, साथ ही जब कोई शर्त गलत पर मूल्यांकन करती है तो एक `"skipped"` स्थिति भी लिखता है।
+
+## इवेंट बस {#event-bus}
+
+एकीकरण मॉड्यूल लोड समय पर घटनाओं को पंजीकृत करता है। बस [Standard Schema](https://standardschema.dev) परिभाषाओं के अनुसार पेलोड को मान्य करती है और ग्राहकों को भेजती है।
+
+### अंतर्निहित ईवेंट {#built-in-events}
+
+| घटना                   | स्रोत                                              |
+| ---------------------- | -------------------------------------------------- |
+| `test.event.fired`     | मैनुअल / `manage-automations` क्रिया=अग्नि-परीक्षण |
+| `agent.turn.completed` | एजेंट चैट                                          |
+| `calendar.*`           | कैलेंडर एकीकरण                                     |
+| `clip.*`               | क्लिप एकीकरण                                       |
+| `mail.*`               | मेल एकीकरण                                         |
+
+वर्तमान टेम्पलेट के विवरण और पेलोड स्कीमा के साथ सभी पंजीकृत घटनाओं को देखने के लिए एजेंट से `action=list-events` के साथ `manage-automations` पर कॉल करें।
+
+### कस्टम ईवेंट उत्सर्जित करना {#emitting-events}
+
+सर्वर प्लगइन में एक ईवेंट प्रकार पंजीकृत करें, फिर इसे actions या वेबहुक हैंडलर से उत्सर्जित करें:
+
+```ts
+import { registerEvent, emit } from "@agent-native/core/event-bus";
+import { z } from "zod";
+
+// Register the event type (once, at module load)
+registerEvent({
+  name: "order.completed",
+  description: "A customer completed an order",
+  payloadSchema: z.object({
+    orderId: z.string(),
+    customerEmail: z.string(),
+    total: z.number(),
+  }),
+  example: {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+});
+
+// Emit the event (from an action, webhook handler, etc.)
+emit(
+  "order.completed",
+  {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+  { owner: "steve@builder.io" },
+);
+```
+
+उत्सर्जित मेटाडेटा स्कोप में `owner` जो ऑटोमेशन सक्रिय करता है - केवल उसी उपयोगकर्ता (या साझा ऑटोमेशन) के स्वामित्व वाले ऑटोमेशन का मूल्यांकन किया जाता है।
+
+## शर्तें {#conditions}
+
+स्थितियाँ प्राकृतिक भाषा के तार हैं जिनका मूल्यांकन इवेंट पेलोड के विरुद्ध Claude Haiku द्वारा किया जाता है। यह हाँ/नहीं वर्गीकरण है, कोई पीढ़ीगत कार्य नहीं।
+
+- **खाली या गायब स्थिति** = बिना शर्त (हमेशा सक्रिय)।
+- परिणामों को 5 मिनट के TTL और 500-एंट्री LRU कैश के साथ याद किया जाता है (SHA-256 स्थिति + पेलोड)।
+- हाइकु पर भेजने से पहले पेलोड को 4000 अक्षरों तक छोटा कर दिया जाता है।
+- API विफलता पर, स्थिति `false` (सुरक्षित डिफ़ॉल्ट - स्वचालन छोड़ दिया गया है) का मूल्यांकन करती है।
+
+शर्तों के उदाहरण:
+
+- `"attendee email ends with @builder.io"`
+- `"the order total is greater than $100"`
+- `"the message contains the word 'urgent'"`
+
+## वेब-अनुरोध उपकरण {#web-request}
+
+ऑटोमेशन आउटबाउंड HTTP के लिए `web-request` टूल का उपयोग करते हैं। यह URL, हेडर और बॉडी में `${keys.NAME}` प्लेसहोल्डर्स का समर्थन करता है:
+
+```
+POST to ${keys.SLACK_WEBHOOK}
+
+Headers: {"Authorization": "Bearer ${keys.API_TOKEN}"}
+
+Body: {"text": "New booking from ${attendeeEmail}"}
+```
+
+एजेंट द्वारा टूल कॉल जारी करने के बाद प्लेसहोल्डर्स का समाधान **सर्वर-साइड** किया जाता है - कच्चा गुप्त मान कभी भी एजेंट के संदर्भ में प्रवेश नहीं करता है।
+
+### पैरामीटर {#web-request-params}
+
+| पैरामीटर     | प्रकार   | डिफ़ॉल्ट | विवरण                                                         |
+| ------------ | -------- | -------- | ------------------------------------------------------------- |
+| `url`        | स्ट्रिंग | —        | पूर्ण URL। इसमें `${keys.NAME}` संदर्भ शामिल हो सकते हैं।     |
+| `method`     | स्ट्रिंग | `GET`    | HTTP विधि (GET, POST, PUT, PATCH, DELETE, HEAD).              |
+| `headers`    | स्ट्रिंग | `{}`     | हेडर का JSON ऑब्जेक्ट। इसमें `${keys.NAME}` शामिल हो सकता है। |
+| `body`       | स्ट्रिंग | —        | अनुरोध निकाय. इसमें `${keys.NAME}` शामिल हो सकता है।          |
+| `timeout_ms` | संख्या   | 15000    | मिलीसेकंड में टाइमआउट (अधिकतम 30000).                         |
+
+## कुंजियाँ {#keys}
+
+कुंजियाँ स्वचालित उपयोग के लिए उपयोगकर्ताओं या एजेंट द्वारा बनाए गए तदर्थ रहस्य हैं (उदाहरण के लिए `SLACK_WEBHOOK`, `HUBSPOT_API_KEY`)। वे पंजीकृत रहस्यों (`registerRequiredSecret`) से इस मायने में भिन्न हैं कि उनमें कोई टेम्पलेट-परिभाषित मेटाडेटा या ऑनबोर्डिंग चरण नहीं है।
+
+- सेटिंग्स UI या `/_agent-native/secrets/adhoc` API के माध्यम से बनाया गया।
+- प्रत्येक कुंजी में एक **URL अनुमति सूची** हो सकती है जो यह प्रतिबंधित करती है कि कुंजी किस मूल स्रोत पर भेजी जा सकती है (मूल-स्तर मिलान)।
+- कच्चा मूल्य कभी भी AI के संपर्क में नहीं आता है - केवल `${keys.NAME}` प्लेसहोल्डर एजेंट के संदर्भ में दिखाई देते हैं।
+- रिज़ॉल्यूशन उपयोगकर्ता के दायरे से कार्यक्षेत्र के दायरे में वापस आ जाता है, इसलिए उपयोगकर्ता साझा कुंजियों को ओवरराइड कर सकते हैं।
+
+## एजेंट उपकरण {#agent-tools}
+
+सभी स्वचालन परिचालनों को `action` पैरामीटर के साथ एक एकल `manage-automations` टूल के माध्यम से एक्सेस किया जाता है:
+
+| कार्रवाई      | उद्देश्य                                                                               |
+| ------------- | -------------------------------------------------------------------------------------- |
+| `list-events` | विवरण और पेलोड स्कीमा के साथ सभी पंजीकृत घटनाओं की खोज करें                            |
+| `list`        | सभी ऑटोमेशन को स्थिति के साथ सूचीबद्ध करें; डोमेन के अनुसार फ़िल्टर करें या सक्षम करें |
+| `define`      | एक नया स्वचालन बनाएं (नाम, ट्रिगर प्रकार, घटना, स्थिति, मुख्य भाग)                     |
+| `update`      | मौजूदा स्वचालन (सक्षम, स्थिति, मुख्य भाग) को अद्यतन करें                               |
+| `delete`      | स्वचालन हटाएं (हमेशा पहले उपयोगकर्ता से पुष्टि करें)                                   |
+| `fire-test`   | ऑटोमेशन को सत्यापित करने के लिए एक `test.event.fired` ईवेंट का उत्सर्जन करें           |
+
+अतिरिक्त उपकरण: `web-request` - `${keys.NAME}` प्रतिस्थापन के साथ आउटबाउंड HTTP।
+
+## API समापन बिंदु {#api}
+
+| अंतबिंदु                               | विधि   | विवरण                                       |
+| -------------------------------------- | ------ | ------------------------------------------- |
+| `/_agent-native/automations`           | GET    | सभी ऑटोमेशन की सूची बनाएं (पार्स किए गए)    |
+| `/_agent-native/automations/fire-test` | POST   | एक `test.event.fired` ईवेंट उत्सर्जित करें  |
+| `/_agent-native/secrets/adhoc`         | GET    | तदर्थ कुंजियाँ सूचीबद्ध करें (कोई मान नहीं) |
+| `/_agent-native/secrets/adhoc`         | POST   | तदर्थ कुंजी बनाएं या अपडेट करें             |
+| `/_agent-native/secrets/adhoc/:name`   | DELETE | एक तदर्थ कुंजी हटाएं                        |
+
+```an-api title="Fire a test event"
+{
+  "method": "POST",
+  "path": "/_agent-native/automations/fire-test",
+  "summary": "Emit a test.event.fired event to validate event-triggered automations",
+  "description": "Confirm an automation's wiring and condition without waiting for a real provider event. Equivalent to the `manage-automations` action `fire-test`.",
+  "responses": [
+    { "status": "200", "description": "Event emitted; matching automations are dispatched through the normal condition + ownership path." }
+  ]
+}
+```
+
+## डिस्पैच कैसे काम करता है {#dispatch}
+
+```an-diagram title="The dispatch path" summary="From a fired event to a completed agent run, gated by ownership scope and the natural-language condition."
+{
+  "html": "<div class=\"disp\"><div class=\"diagram-box accent\">event fired on the bus</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">match</span><small class=\"diagram-muted\">load enabled automations subscribed to this event name</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">scope</span><small class=\"diagram-muted\">keep only those owned by the event's owner (or shared)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">condition</span><small class=\"diagram-muted\">Haiku yes/no on the payload &mdash; false &rarr; <code>skipped</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">run</span><small class=\"diagram-muted\"><code>runAgentLoop</code> with body as prompt, payload as context, 5-min timeout</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code></small></div></div>",
+  "css": ".disp{display:flex;flex-direction:column;gap:6px;max-width:540px}.disp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.disp .diagram-box{align-self:flex-start}.disp .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+## उदाहरण {#example}
+
+**उपयोगकर्ता:** "जब कोई @builder.io ईमेल से बुकिंग करता है, तो मुझे Slack में संदेश भेजें।"
+
+**एजेंट प्रवाह:**
+
+1. `action=list-events` के साथ `manage-automations` को कॉल करता है - `calendar.booking.created` पाता है।
+2. उपयोगकर्ता के साथ योजना की पुष्टि करता है।
+3. `action=define` के साथ `manage-automations` को कॉल करता है:
+   - `name`: `slack-on-builder-booking`
+   - `trigger_type`: `event`
+   - `event`: `calendar.booking.created`
+   - `condition`: `attendee email ends with @builder.io`
+   - `mode`: `agentic`
+   - `domain`: `calendar`
+   - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`
+4. स्वचालन को `jobs/slack-on-builder-booking.md` के रूप में सहेजा गया है और तुरंत सुनना शुरू हो जाता है।
+
+## अधिक उदाहरण {#more-examples}
+
+### जब किसी योजना पर टिप्पणी की जाती है तो वेबहुक के माध्यम से सूचित करें
+
+योजना एजेंट से पूछें: _"जब कोई किसी योजना पर मानवीय टिप्पणी जोड़ता है, तो POST a
+मेरे वेबहुक के लिए अधिसूचना।"_
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is human or resolutionTarget is null"
+mode: agentic
+domain: plan
+enabled: true
+---
+
+POST to ${keys.NOTIFY_WEBHOOK} with a JSON body:
+{"title": "<plan title>", "excerpt": "<comment excerpt>", "author": "<author email or null>", "url": "<app base url + path>"}
+```
+
+`NOTIFY_WEBHOOK` को किसी भी HTTP एंडपॉइंट पर सेट करें - एक Slack इनकमिंग वेबहुक, एक सामान्य
+अधिसूचना सेवा, या एक कस्टम रिसीवर। `web-request` उपकरण हल करता है
+`${keys.NOTIFY_WEBHOOK}` सर्वर-साइड; कच्चा URL एजेंट के
+संदर्भ. [Visual Plans — Events and notifications](/docs/template-plan#events)
+संपूर्ण `plan.commented` पेलोड संदर्भ और सभी चार योजना आयोजनों के लिए।
+
+## आगे क्या है
+
+- [**Recurring Jobs**](/docs/recurring-jobs) - शेड्यूल-ट्रिगर ऑटोमेशन उसी शेड्यूलर का पुन: उपयोग करते हैं
+- [**Actions**](/docs/actions) - ऑटोमेशन एजेंट लूप के माध्यम से किसी भी पंजीकृत कार्रवाई को कॉल कर सकता है
+- [**Security**](/docs/security) - इनपुट सत्यापन और गुप्त हैंडलिंग
+- [**Visual Plans — Events**](/docs/template-plan#events) - ईवेंट संदर्भ और स्वचालन व्यंजनों की योजना बनाएं

package/docs/content/locales/hi-IN/blueprint-installer.md

@@ -0,0 +1,83 @@
+---
+title: "ब्लूप्रिंट इंस्टॉलर"
+description: "एजेंट-नेटिव ऐड स्टडआउट के लिए एक क्यूरेटेड Markdown इंटीग्रेशन रेसिपी प्रिंट करता है - इसे अपने कोडिंग एजेंट में पाइप करें, जो आपके लाइव रेपो के विरुद्ध परिवर्तन लागू करता है।"
+---
+
+# ब्लूप्रिंट इंस्टालर
+
+> **यह किसके लिए है:** मेजबान लेखक और एक प्रदाता, चैनल जोड़ने वाले इंटीग्रेटर्स
+> सैंडबॉक्स बैकएंड, या किसी रेसिपी को उनके कोडिंग एजेंट में डालकर रेपो पर कार्रवाई।
+
+`agent-native add` एक गूंगा स्कैफ़ोल्डर नहीं है जो आपके लिए फ़ाइलें लिखता है। यह स्टडआउट करने के लिए एक क्यूरेटेड Markdown _इंटीग्रेशन ब्लूप्रिंट_ उत्सर्जित करता है। आप उस ब्लूप्रिंट को अपने स्वयं के कोडिंग एजेंट (Claude कोड, Codex,…) में पाइप करते हैं, जो पूरे संदर्भ के साथ लाइव रेपो के विरुद्ध परिवर्तनों को लागू करता है।
+
+यह एजेंट-लागू-परिवर्तन, फ़ाइल सिस्टम-फर्स्ट हाउस शैली में फिट बैठता है: फ्रेमवर्क नुस्खा प्रदान करता है (स्पर्श करने के लिए कैनोनिकल फ़ाइलें, सम्मान करने के नियम, सत्यापन चरण), और कोडिंग एजेंट संपादन करता है।
+
+```bash
+agent-native add provider stripe | claude
+agent-native add channel discord  | codex
+```
+
+```an-diagram title="add prints a recipe; your coding agent applies it" summary="agent-native emits a Markdown blueprint to stdout (diagnostics to stderr); you pipe it into Claude Code or Codex, which edits your live repo with full context."
+{
+  "html": "<div class=\"diagram-bp\"><div class=\"diagram-node\" data-rough>agent-native add<br><small class=\"diagram-muted\">&lt;kind&gt; &lt;name|URL&gt;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Markdown blueprint<br><small class=\"diagram-muted\">stdout · files to touch · rules · Verify</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>Coding agent<br><small class=\"diagram-muted\">claude · codex</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">edits your live repo</div></div>",
+  "css": ".diagram-bp{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bp .diagram-arrow{font-size:22px;line-height:1}.diagram-bp .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## प्रयोग {#usage}
+
+```bash
+agent-native add <kind> <name>            # print a curated blueprint
+agent-native add <kind> <https://docs…>   # research-and-integrate from a URL
+agent-native add --list                   # list available kinds and blueprints
+```
+
+- एक खाली **नाम** `blueprints/<kind>/<name>.md` से एक क्यूरेटेड ब्लूप्रिंट का समाधान करता है।
+- ए **URL** एक नाम के बजाय उस तरह के लिए एक सामान्य _शोध-और-एकीकृत_ ब्लूप्रिंट उत्सर्जित करता है, जिसमें URL अनुसंधान प्रारंभिक बिंदु के रूप में एम्बेडेड होता है (URL एक शोध बीज है, एक ज्ञात नुस्खा नहीं)।
+- ब्लूप्रिंट **stdout** पर जाता है; डायग्नोस्टिक्स stderr पर जाता है, इसलिए `… | claude` केवल ब्लूप्रिंट प्राप्त करता है।
+
+## सीडेड ब्लूप्रिंट {#seeded}
+
+`agent-native add --list` दिखाता है कि बॉक्स में क्या भेजा गया है:
+
+| प्रकार     | नाम       | यह क्या सेट करता है                                                                |
+| ---------- | --------- | ---------------------------------------------------------------------------------- |
+| `provider` | `stripe`  | एक प्रदाता को `provider-api` सब्सट्रेट (कैटलॉग/दस्तावेज़/अनुरोध तिकड़ी) से जोड़ें। |
+| `channel`  | `discord` | एक `PlatformAdapter` इनबाउंड वेबहुक चैनल लागू करें और इसे पंजीकृत करें।            |
+| `sandbox`  | `docker`  | डॉकर कंटेनर में `run-code` चलाने के लिए `SandboxAdapter` सीम लागू करें।            |
+| `action`   | `crud`    | Zod स्कीमा (N के ऊपर एक `update`) के साथ एक एकल बहु-सतह `defineAction` जोड़ें।     |
+
+प्रत्येक ब्लूप्रिंट स्व-निहित है: इसे पढ़ने वाले कोडिंग एजेंट को छूने के लिए फ़ाइलें मिलती हैं, फ्रेमवर्क नियमों का सम्मान किया जाता है (actions सत्य का एकल स्रोत है, कभी भी हार्डकोड रहस्य नहीं, स्वामित्व योग्य डेटा का दायरा, `packages/*` स्रोत के लिए एक परिवर्तन जोड़ें), और एक ठोस **सत्यापित करें** अनुभाग।
+
+## URL → अनुसंधान ब्लूप्रिंट {#url}
+
+जब आप URL पास करते हैं तो इस प्रकार के लिए कोई क्यूरेटेड नुस्खा नहीं होता है (या एक नया एकीकरण चाहते हैं), `add` बीज के रूप में URL के साथ एक सामान्य "शोध-और-एकीकृत" ब्लूप्रिंट उत्सर्जित करता है:
+
+```bash
+agent-native add provider https://docs.example.com/api | claude
+```
+
+जेनरेट किया गया ब्लूप्रिंट कोडिंग एजेंट को वास्तविक एंडपॉइंट, ऑथ मॉडल, पेलोड आकार और हस्ताक्षर/सत्यापन आवश्यकताओं के लिए URL (और इसे लिंक करने वाले पेज) लाने के लिए कहता है - प्रशिक्षण डेटा से अनुमान लगाने के लिए _नहीं_ - फिर लागू करें और सत्यापित करें। इसमें प्रकार-विशिष्ट मार्गदर्शन भी होता है (उदाहरण के लिए एक `provider` URL को `provider-api` सब्सट्रेट की ओर ले जाया जाता है; एक `channel` URL को `PlatformAdapter` की ओर ले जाया जाता है)।
+
+## अपना स्वयं का खाका जोड़ना {#authoring}
+
+Markdown फ़ाइल को `packages/core/blueprints/<kind>/<name>.md` में छोड़ें। प्रकार उपनिर्देशिका है; नाम `.md` के बिना फ़ाइल नाम है। इसे स्वचालित रूप से उठाया जाता है - `--list`, नाम रिज़ॉल्यूशन, और कैटलॉग सभी निर्देशिका को रनटाइम पर पढ़ते हैं। इसे पंजीकृत करने के लिए किसी कोड परिवर्तन की आवश्यकता नहीं है।
+
+ब्लूप्रिंट `.md` फ़ाइलें `package.json` `files` में `blueprints` प्रविष्टि के माध्यम से प्रकाशित पैकेज में भेजी जाती हैं, इसलिए वे अंतिम उपयोगकर्ताओं के लिए `node_modules/@agent-native/core/blueprints/**` पर हल होती हैं।
+
+प्रत्येक ब्लूप्रिंट को बिना किसी अन्य संदर्भ के कोडिंग एजेंट के लिए एक निर्देश सेट के रूप में लिखें। एक अच्छे ब्लूप्रिंट में:
+
+1. **एक-पंक्ति लक्ष्य** और "आप एक एजेंट-नेटिव ऐप में एक कोडिंग एजेंट हैं, इन्हें वास्तविक स्रोत परिवर्तन के रूप में लागू करें" फ़्रेमिंग।
+2. **पहले पढ़ें** - सटीक फ़ाइलें जो अनुबंध हैं।
+3. **स्पर्श करने योग्य फ़ाइलें** — ठोस पथ और प्रत्येक परिवर्तन क्या करता है।
+4. **फ्रेमवर्क नियमों का सम्मान** - actions-प्रथम, कोई हार्डकोडेड रहस्य नहीं, स्वामित्व योग्य डेटा का दायरा, प्रकाशन योग्य-पैकेज स्रोत के लिए एक परिवर्तन जोड़ें।
+5. **सत्यापित करें** - टाइपचेक, एक केंद्रित `*.spec.ts`, और एक एंड-टू-एंड चेक।
+
+> [!TIP]
+> मौजूदा प्रकार के तहत एक नए क्यूरेटेड ब्लूप्रिंट को किसी कोड की आवश्यकता नहीं है - लेकिन यदि आप एक बिल्कुल नई तरह की निर्देशिका बनाते हैं, तो वह प्रकार स्वचालित रूप से `--list` में भी दिखाई देता है।
+
+## आगे क्या
+
+- [**Sandbox Adapters**](/docs/sandbox-adapters) - सीम `add sandbox docker` ब्लूप्रिंट लक्ष्य
+- [**Actions**](/docs/actions) - सत्य का एकमात्र स्रोत जिस पर प्रत्येक खाका निर्मित होता है
+- [**External Agents**](/docs/external-agents) - उस कोडिंग एजेंट को कनेक्ट करना जिसमें आप ब्लूप्रिंट पाइप करते हैं

package/docs/content/locales/hi-IN/cli-adapters.md

@@ -0,0 +1,129 @@
+---
+title: "CLI एडाप्टर"
+description: "एजेंट को एक मानक एडाप्टर इंटरफ़ेस के माध्यम से किसी भी CLI टूल (gh, ffmpeg, स्ट्राइप) तक संरचित पहुंच प्रदान करें - एडेप्टर गाइड में शामिल दो एडाप्टर सीमों में से एक।"
+---
+
+# CLI एडाप्टर
+
+> **यह कहां फिट बैठता है:** CLI एडेप्टर दो एडेप्टर सीमों में से एक हैं
+> ढांचा। विहित मार्गदर्शिका [Adapters](/docs/sandbox-adapters) है, जो
+> इस सीम और `run-code` सैंडबॉक्स सीम दोनों को कवर करता है - जिसमें साझा भी शामिल है
+> किनारा/सर्वर रहित बाधा। यह पृष्ठ CLI पक्ष के लिए त्वरित संदर्भ है।
+
+एक CLI एडाप्टर एक एकल कमांड-लाइन टूल (`gh`, `ffmpeg`, `stripe`, `aws`) को लपेटता है ताकि एजेंट इसे खोज सके, जांच सके कि यह इंस्टॉल है या नहीं, और इसे लगातार stdout/stderr/exit-code परिणाम के साथ चला सकता है। इस सीम के बिना, प्रत्येक स्क्रिप्ट CLI को इनवॉइस करने और उसके आउटपुट को पार्स करने के तरीके को फिर से खोजती है।
+
+```an-diagram title="CLI adapter → registry → action surface" summary="ShellCliAdapter wraps a binary; CliRegistry collects adapters for discovery; defineAction exposes one call on the agent + UI action surface."
+{
+  "html": "<div class=\"diagram-cli\"><div class=\"diagram-node\" data-rough>gh · ffmpeg · stripe<br><small class=\"diagram-muted\">command-line tools</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>ShellCliAdapter<br><small class=\"diagram-muted\">isAvailable · execute</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>CliRegistry<br><small class=\"diagram-muted\">describe() for discovery</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">defineAction</div></div>",
+  "css": ".diagram-cli{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-cli .diagram-arrow{font-size:22px;line-height:1}.diagram-cli .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## इंटरफ़ेस {#the-interface}
+
+प्रत्येक CLI एडाप्टर `CliAdapter` को कार्यान्वित करता है:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+## शेलक्लिएडाप्टर {#shell-adapter}
+
+अधिकांश CLI के लिए आपको कस्टम क्लास की आवश्यकता नहीं है - `ShellCliAdapter` किसी भी बाइनरी को समझदार डिफ़ॉल्ट के साथ लपेटता है:
+
+```ts
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const gh = new ShellCliAdapter({
+  command: "gh",
+  description: "GitHub CLI — manage repos, PRs, issues, and releases",
+});
+
+const ffmpeg = new ShellCliAdapter({
+  command: "ffmpeg",
+  description: "Audio/video processing and transcoding",
+  timeoutMs: 120_000, // 2 min for long encodes
+  env: { STRIPE_API_KEY: process.env.STRIPE_SECRET_KEY! },
+});
+```
+
+विकल्प: `command` (आवश्यक), `description` (आवश्यक), `name` (`command` पर डिफ़ॉल्ट), `env` (`process.env` के साथ विलय), `cwd` (`process.cwd()` पर डिफ़ॉल्ट), और `timeoutMs` (डिफ़ॉल्ट `30000`).
+
+कस्टम ऑथ, आउटपुट पार्सिंग, या प्री/पोस्ट प्रोसेसिंग के लिए, `ShellCliAdapter` का उपयोग करने के बजाय सीधे `CliAdapter` लागू करें।
+
+## रजिस्ट्री {#registry}
+
+`CliRegistry` एडेप्टर एकत्र करता है ताकि एजेंट पता लगा सके कि रनटाइम पर क्या उपलब्ध है:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({ command: "gh", description: "GitHub CLI" }),
+);
+
+cliRegistry.list(); // all registered
+await cliRegistry.listAvailable(); // only installed
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+## actions से उपयोग करना {#from-actions}
+
+CLI कॉल को एक्शन सतह पर प्रदर्शित करने के लिए इसे `defineAction` में लपेटें - जब कोड सर्वर एक्शन सतह के अंदर चलता है तो `defineAction` की आवश्यकता होती है; अन्यथा सीधे `scripts/` फ़ाइल में एडॉप्टर का उपयोग करें। किसी कार्रवाई में कभी भी `process.exit` को कॉल न करें; इसके बजाय एक त्रुटि डालें।
+
+```ts
+// actions/list-prs.ts
+import { defineAction } from "@agent-native/core/action";
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+import { z } from "zod";
+
+const gh = new ShellCliAdapter({ command: "gh", description: "GitHub CLI" });
+
+export default defineAction({
+  description: "List open pull requests via the GitHub CLI.",
+  schema: z.object({}),
+  async run() {
+    if (!(await gh.isAvailable())) {
+      throw new Error("GitHub CLI not installed. Run: brew install gh");
+    }
+    const result = await gh.execute([
+      "pr",
+      "list",
+      "--json",
+      "title,url,state",
+      "--limit",
+      "10",
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || "gh pr list failed");
+    }
+    return JSON.parse(result.stdout);
+  },
+});
+```
+
+## एज और सर्वर रहित {#edge-serverless}
+
+CLI एडेप्टर `node:child_process` का उपयोग करते हैं, जो एज/वर्कर रनटाइम (क्लाउडफ्लेयर वर्कर्स, नेटलिफाई एज फ़ंक्शंस) पर मौजूद नहीं है। मानक Node.js वातावरण में CLI एडाप्टर एंडपॉइंट और कार्य चलाएँ। यह बाधा सैंडबॉक्स सीम के साथ साझा की गई है - [Adapters](/docs/sandbox-adapters#edge-serverless) में पूरी चर्चा देखें।
+
+## आगे क्या है
+
+- [**Adapters**](/docs/sandbox-adapters) - दोनों एडाप्टर सीम के लिए कैनोनिकल गाइड।
+- [**Actions**](/docs/actions) - क्रिया सतह CLI एडेप्टर आमतौर पर लपेटे जाते हैं।