# CLAUDE.md (मराठी)

🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇦🇿 [az](../az/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇩 [in](../in/CLAUDE.md) · 🇮🇹 [it](../it/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇧🇷 [pt-BR](../pt-BR/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇷🇺 [ru](../ru/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [ta](../ta/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇭 [th](../th/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md)

---

या फाइलमध्ये या रेपॉजिटरीमध्ये कोडवर काम करताना Claude Code (claude.ai/code) साठी मार्गदर्शन दिले आहे.

## जलद प्रारंभ

```bash
npm install                    # निर्भरता स्थापित करा (.auto-generates .env from .env.example)
npm run dev                    # विकास सर्व्हर http://localhost:20128 वर
npm run build                  # उत्पादन बिल्ड (Next.js 16 स्वतंत्र)
npm run lint                   # ESLint (0 त्रुटी अपेक्षित; चेतावण्या पूर्वीच आहेत)
npm run typecheck:core         # TypeScript तपासणी (स्वच्छ असावी)
npm run typecheck:noimplicit:core  # कठोर तपासणी (कोणतीही अप्रत्यक्ष नाही)
npm run test:coverage          # युनिट चाचण्या + कव्हरेज गेट (75/75/75/70 — विधान/रेषा/कार्ये/शाखा)
npm run check                  # lint + चाचणी एकत्रित
npm run check:cycles           # वर्तुळाकार अवलंबन शोधा
```

### चाचण्या चालवणे

```bash
# एकल चाचणी फाइल (Node.js स्थानिक चाचणी धावक — बहुतेक चाचण्या)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP सर्व्हर, autoCombo, कॅश)
npm run test:vitest

# सर्व सूट
npm run test:all
```

पूर्ण चाचणी मॅट्रिक्ससाठी, `CONTRIBUTING.md` पहा → "चाचण्या चालवणे". गहन आर्किटेक्चरसाठी, `AGENTS.md` पहा.

---

## प्रकल्पाचा आढावा

**OmniRoute** — एकत्रित AI प्रॉक्सी/राउटर. एक एंडपॉइंट, 160+ LLM प्रदाते, स्वयंचलित फॉलबॅक.

| स्तर          | स्थान                   | उद्देश                                                       |
| ------------- | ----------------------- | ------------------------------------------------------------ |
| API मार्ग     | `src/app/api/v1/`       | Next.js अॅप राउटर — प्रवेश बिंदू                             |
| हँडलर्स       | `open-sse/handlers/`    | विनंती प्रक्रिया (चॅट, एम्बेडिंग, इ.)                        |
| कार्यान्वयक   | `open-sse/executors/`   | प्रदाता-विशिष्ट HTTP वितरण                                   |
| भाषांतरक      | `open-sse/translator/`  | स्वरूप रूपांतरण (OpenAI↔Claude↔Gemini)                       |
| ट्रान्सफार्मर | `open-sse/transformer/` | प्रतिसाद API ↔ चॅट पूर्णता                                   |
| सेवा          | `open-sse/services/`    | कॉम्बो राउटिंग, दर मर्यादा, कॅशिंग, इ.                       |
| डेटाबेस       | `src/lib/db/`           | SQLite डोमेन मॉड्यूल (45+ फाइल, 55 स्थलांतर)                 |
| डोमेन/नीती    | `src/domain/`           | नीती इंजिन, खर्च नियम, फॉलबॅक लॉजिक                          |
| MCP सर्व्हर   | `open-sse/mcp-server/`  | 37 साधने (30 बेस + 3 मेमरी + 4 कौशल्य), 3 वाहने, ~13 स्कोप्स |
| A2A सर्व्हर   | `src/lib/a2a/`          | JSON-RPC 2.0 एजंट प्रोटोकॉल                                  |
| कौशल्य        | `src/lib/skills/`       | विस्तारणीय कौशल्य फ्रेमवर्क                                  |
| मेमरी         | `src/lib/memory/`       | कायमचे संवादात्मक मेमरी                                      |

मोनोरेपो: `src/` (Next.js 16 अॅप), `open-sse/` (स्ट्रीमिंग इंजिन कार्यक्षेत्र), `electron/` (डेस्कटॉप अॅप), `tests/`, `bin/` (CLI प्रवेश बिंदू).

---

## विनंती पाईपलाइन

```
Client → /v1/chat/completions (Next.js मार्ग)
  → CORS → Zod प्रमाणीकरण → auth? → धोरण तपासणी → प्रॉम्प्ट इंजेक्शन गार्ड
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → कॅश तपासणी → दर मर्यादा → कॉम्बो रूटिंग?
      → resolveComboTargets() → handleSingleModel() प्रति लक्ष्य
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() अपस्ट्रीम → retry w/ backoff
    → प्रतिसाद भाषांतर → SSE प्रवाह किंवा JSON
    → जर प्रतिसाद API: responsesTransformer.ts TransformStream
```

API मार्ग एक सुसंगत नमुना अनुसरण करतात: `Route → CORS प्रीफ्लाइट → Zod शरीर प्रमाणीकरण → वैकल्पिक auth (extractApiKey/isValidApiKey) → API की धोरण अंमलबजावणी → हँडलर प्रतिनिधित्व (open-sse)`. कोणताही जागतिक Next.js मिडलवेअर नाही — हस्तक्षेप मार्ग-विशिष्ट आहे.

**कॉम्बो रूटिंग** (`open-sse/services/combo.ts`): 14 रणनीती (प्राधान्य, वजनदार, भर-प्रथम, राउंड-रॉबिन, P2C, यादृच्छिक, कमी-उपयोग, खर्च-ऑप्टिमाइझ, रीसेट-ज्ञानी, कठोर-यादृच्छिक, स्वयंचलित, lkgp, संदर्भ-ऑप्टिमाइझ, संदर्भ-रिले). प्रत्येक लक्ष्य `handleSingleModel()` कॉल करते जे `handleChatCore()` ला प्रति-लक्ष्य त्रुटी हाताळणी आणि सर्किट ब्रेकर तपासणीसह लपवते. 9-फॅक्टर ऑटो-कॉम्बो स्कोअरिंगसाठी `docs/routing/AUTO-COMBO.md` पहा आणि 3 प्रतिकार स्तरांसाठी `docs/architecture/RESILIENCE_GUIDE.md` पहा.

---

## प्रतिकार रनटाइम स्थिती

OmniRoute कडे तीन संबंधित पण भिन्न तात्पुरत्या-अपयश यांत्रिके आहेत. रूटिंग वर्तन डिबग करताना त्यांचा व्याप्ती वेगळी ठेवा. एक झलक नकाशासाठी [3-लेयर प्रतिकार आरेख](./docs/diagrams/exported/resilience-3layers.svg) पहा (स्त्रोत: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd)).

### प्रदाता सर्किट ब्रेकर

**व्याप्ती**: संपूर्ण प्रदाता, उदा. `glm`, `openai`, `anthropic`.

**उद्दिष्ट**: अपस्ट्रीम/सेवा स्तरावर वारंवार अपयशी ठरलेल्या प्रदात्याकडे ट्रॅफिक पाठवणे थांबवणे, त्यामुळे एक अस्वस्थ प्रदाता प्रत्येक विनंतीला मंदावणार नाही.

**अंमलबजावणी**:

- मुख्य वर्ग: `src/shared/utils/circuitBreaker.ts`
- चॅट गेट/कार्यवाही वायरिंग: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`
- रनटाइम स्थिती API: `src/app/api/monitoring/health/route.ts`
- सामायिक रॅपर: `open-sse/services/accountFallback.ts`
- कायमस्वरूपी स्थिती टेबल: `domain_circuit_breakers`

**स्थिती**:

- `CLOSED`: सामान्य ट्रॅफिकची परवानगी आहे.
- `OPEN`: प्रदाता तात्पुरता ब्लॉक केलेला आहे; कॉलर्सना प्रदाता-सर्किट-ओपन प्रतिसाद मिळतो किंवा कॉम्बो रूटिंग दुसऱ्या लक्ष्याकडे वळते.
- `HALF_OPEN`: रीसेट टाइमआउट संपला आहे; एक प्रॉब विनंती परवानगी द्या. यशस्वी झाल्यास ब्रेकर बंद होतो, अपयशी झाल्यास पुन्हा उघडतो.

**डीफॉल्ट्स** (`open-sse/config/constants.ts`):

- OAuth प्रदाते: थ्रेशोल्ड `3`, रीसेट टाइमआउट `60s`.
- API-key प्रदाते: थ्रेशोल्ड `5`, रीसेट टाइमआउट `30s`.
- स्थानिक प्रदाते: थ्रेशोल्ड `2`, रीसेट टाइमआउट `15s`.

फक्त प्रदाता-स्तरीय अपयश स्थिती प्रदाता ब्रेकरला ट्रिप करायला हवी:

```ts
(408, 500, 502, 503, 504);
```

सामान्य खाते/की/मॉडेल त्रुटी जसे की बहुतेक `401`, `403`, किंवा `429` प्रकरणांसाठी संपूर्ण प्रदाता ब्रेकरला ट्रिप करू नका. त्या सामान्यतः कनेक्शन कूलडाऊन किंवा मॉडेल लॉकआउटमध्ये असतात. एक सामान्य API-key प्रदाता `403` पुनर्प्राप्त करण्यायोग्य असावा, जोपर्यंत तो एक टर्मिनल प्रदाता/खाते त्रुटी म्हणून वर्गीकृत केलेला नाही.

ब्रेकर आलसी पुनर्प्राप्ती वापरतो, पार्श्वभूमी टाइमर नाही. जेव्हा `OPEN` संपते, तेव्हा `getStatus()`, `canExecute()`, आणि `getRetryAfterMs()` सारख्या वाचनांनी स्थिती `HALF_OPEN` मध्ये ताजेतवाने करते, त्यामुळे डॅशबोर्ड आणि कॉम्बो उमेदवार बिल्डर्स एक कालबाह्य प्रदाता कायमचा वगळत नाहीत.

### कनेक्शन कूलडाऊन

**व्याप्ती**: एक प्रदाता कनेक्शन/खाते/की.

**उद्दिष्ट**: एक वाईट की/खाते तात्पुरते वगळताना त्याच प्रदाता साठी इतर कनेक्शनना विनंत्या सेवा देण्याची परवानगी देणे.

**अंमलबजावणी**:

- लेखा/अपडेट पथ: `src/sse/services/auth.ts::markAccountUnavailable()`
- खाते निवड/फिल्टरिंग: `src/sse/services/auth.ts::getProviderCredentials...`
- कूलडाऊन गणना: `open-sse/services/accountFallback.ts::checkFallbackError()`
- सेटिंग्ज: `src/lib/resilience/settings.ts`

प्रदाता कनेक्शनवरील महत्त्वाचे क्षेत्र:

```ts
rateLimitedUntil;
testStatus: "unavailable";
lastError;
lastErrorType;
errorCode;
backoffLevel;
```

खाते निवडताना, एक कनेक्शन वगळले जाते जेव्हा:

```ts
new Date(rateLimitedUntil).getTime() > Date.now();
```

कूलडाऊन देखील आलसी आहेत: जेव्हा `rateLimitedUntil` भूतकाळात असतो, तेव्हा कनेक्शन पुन्हा पात्र होते. यशस्वी वापरावर, `clearAccountError()` `testStatus`, `rateLimitedUntil`, त्रुटी क्षेत्र, आणि `backoffLevel` साफ करते.

डीफॉल्ट कनेक्शन कूलडाऊन वर्तन:

- OAuth बेस कूलडाऊन: `5s`.
- API-key बेस कूलडाऊन: `3s`.
- API-key `429` उपलब्ध असल्यास अपस्ट्रीम पुनर्प्रयत्न संकेत (`Retry-After`, रीसेट हेडर, किंवा पार्स करण्यायोग्य रीसेट मजकूर) प्राधान्य द्यावे.
- पुनरावृत्ती होणाऱ्या पुनर्प्राप्त होणाऱ्या अपयशांवर गुणाकार बॅकऑफ वापरला जातो:

```ts
baseCooldownMs * 2 ** failureIndex;
```

अँटी-थंडरिंग-हर्ड गार्ड एकाच कनेक्शनवरील समांतर अपयशांना कूलडाऊन वाढविण्यासाठी किंवा `backoffLevel` द्विगुणित करण्यापासून प्रतिबंधित करतो.

टर्मिनल स्थिती कूलडाऊन नाहीत. `banned`, `expired`, आणि `credits_exhausted` क्रेडेन्शियल्स/सेटिंग्ज बदलल्याशिवाय किंवा ऑपरेटरने त्यांना रीसेट केल्याशिवाय अनुपलब्ध राहण्याचा उद्देश आहे. तात्पुरत्या कूलडाऊन स्थितीसह टर्मिनल स्थिती ओव्हरराइट करू नका.

### मॉडेल लॉकआउट

**व्याप्ती**: प्रदाता + कनेक्शन + मॉडेल.

**उद्दिष्ट**: एकाच कनेक्शनसाठी फक्त एक मॉडेल अनुपलब्ध किंवा कोटा-सीमित असताना संपूर्ण कनेक्शन बंद करणे टाळणे.

उदाहरणे:

- प्रति-मॉडेल कोटा प्रदाते `429` परत करत आहेत.
- स्थानिक प्रदाते एक गहाळ मॉडेलसाठी `404` परत करत आहेत.
- प्रदाता-विशिष्ट मोड/मॉडेल परवानगी अपयश जसे की निवडलेले Grok मोड.

मॉडेल लॉकआउट `open-sse/services/accountFallback.ts` मध्ये राहते आणि त्याच कनेक्शनला इतर मॉडेल्स सेवा देण्याची परवानगी देते.

### डिबगिंग मार्गदर्शन

- जर प्रदाता साठी सर्व की वगळल्या गेल्या असतील, तर प्रदाता ब्रेकर स्थिती आणि प्रत्येक कनेक्शनच्या `rateLimitedUntil`/`testStatus` तपासा.
- जर रीसेट विंडो नंतर प्रदाता कायमचा वगळलेला दिसत असेल, तर तपासा की कोड कच्चा `state` वाचत आहे की `getStatus()`/`canExecute()` वापरत आहे.
- जर एक प्रदाता की अपयशी झाली पण इतर कार्य करायला हवे, तर प्रदाता ब्रेकरवर कनेक्शन कूलडाऊन प्राधान्य द्या.
- जर फक्त एक मॉडेल अपयशी झाली, तर कनेक्शन कूलडाऊनवर मॉडेल लॉकआउट प्राधान्य द्या.
- जर एक स्थिती स्वतः पुनर्प्राप्त होणे आवश्यक असेल, तर त्यात भविष्यकालीन टाइमस्टॅम्प/रीसेट टाइमआउट आणि एक वाचन पथ असावा जो कालबाह्य स्थिती ताजेतवाने करतो. कायमच्या स्थितींसाठी मॅन्युअल क्रेडेन्शियल किंवा कॉन्फिग बदल आवश्यक आहेत.

## मुख्य संकल्पना

### कोड शैली

- **2 जागा**, सेमीकोलन, डबल कोट्स, 100 वर्ण रुंदी, es5 ट्रेलिंग कॉमा (lint-staged द्वारे Prettier द्वारे लागू केले)
- **आयात**: बाह्य → अंतर्गत (`@/`, `@omniroute/open-sse`) → सापेक्ष
- **नावकरण**: फाइल्स=camelCase/kebab, घटक=PascalCase, स्थिरांक=UPPER_SNAKE
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = सर्वत्र त्रुटी; `no-explicit-any` = `open-sse/` आणि `tests/` मध्ये चेतावणी
- **TypeScript**: `strict: false`, लक्ष्य ES2022, मॉड्यूल esnext, रिझोल्यूशन बंडलर. स्पष्ट प्रकारांना प्राधान्य द्या.

### डेटाबेस

- **सर्व वेळ** `src/lib/db/` डोमेन मॉड्यूलद्वारे जा — **कधीही** मार्ग किंवा हँडलरमध्ये कच्चा SQL लिहू नका
- **कधीही** `src/lib/localDb.ts` मध्ये लॉजिक जोडू नका (फक्त पुनः-निर्यात स्तर)
- **कधीही** `localDb.ts` कडून बॅरल-आयात करू नका — त्याऐवजी विशिष्ट `db/` मॉड्यूल आयात करा
- DB सिंगलटन: `getDbInstance()` `src/lib/db/core.ts` कडून (WAL जर्नलिंग)
- स्थलांतर: `src/lib/db/migrations/` — आवृत्त SQL फाइल्स, आयडेम्पोटेंट, व्यवहारांमध्ये चालवा

### त्रुटी हाताळणी

- विशिष्ट त्रुटी प्रकारांसह try/catch, पिनो संदर्भासह लॉग करा
- SSE प्रवाहांमध्ये त्रुटी गिळू नका — स्वच्छतेसाठी abort सिग्नल वापरा
- योग्य HTTP स्थिती कोड परत करा (4xx/5xx)

### सुरक्षा

- **कधीही** `eval()`, `new Function()`, किंवा implied eval वापरू नका
- सर्व इनपुट Zod स्कीमासह प्रमाणित करा
- विश्रांतीत क्रेडेन्शियल्स एन्क्रिप्ट करा (AES-256-GCM)
- अपस्ट्रीम हेडर डिनायलिस्ट: `src/shared/constants/upstreamHeaders.ts` — संपादित करताना स्वच्छता, Zod स्कीमा, आणि युनिट चाचण्या समांतर ठेवा
- **सार्वजनिक अपस्ट्रीम क्रेडेन्शियल्स** (Gemini/Antigravity/Windsurf-शैली OAuth client_id/secret + Firebase वेब कीज सार्वजनिक CLIs कडून काढलेल्या): **आवश्यक** `resolvePublicCred()` द्वारे समाविष्ट करणे `open-sse/utils/publicCreds.ts` मध्ये — **कधीही** स्ट्रिंग लिटरल्स म्हणून नाही. अनिवार्य नमुन्यासाठी `docs/security/PUBLIC_CREDS.md` पहा.
- **त्रुटी प्रतिसाद** (HTTP / SSE / कार्यान्वयन / MCP हँडलर): **आवश्यक** `buildErrorBody()` किंवा `sanitizeErrorMessage()` द्वारे मार्गक्रमण करणे `open-sse/utils/error.ts` मध्ये — **कधीही** कच्चा `err.stack` किंवा `err.message` प्रतिसाद शरीरात ठेऊ नका. `docs/security/ERROR_SANITIZATION.md` पहा.
- **परिवर्तनीयांवरून तयार केलेले शेल कमांड**: जेव्हा `exec()`/`spawn()` कॉल करताना स्क्रिप्टमध्ये रनटाइम मूल्ये आवश्यक असतात, तेव्हा `env` पर्यायाद्वारे पास करा (स्वयंचलितपणे शेल-एस्केप केले) — **कधीही** अविश्वसनीय/बाह्य पथ स्क्रिप्ट शरीरात स्ट्रिंग-इंटरपोलेट करू नका. संदर्भ: `src/mitm/cert/install.ts::updateNssDatabases`.
- **सुरक्षित-डिफॉल्ट लायब्ररी** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): नवीन सुरक्षा-संवेदनशील पृष्ठभाग जोडताना कस्टम अंमलबजावणीऐवजी Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink यांना प्राधान्य द्या.

---

## सामान्य सुधारणा परिस्थिती

### नवीन प्रदाता जोडणे

1. `src/shared/constants/providers.ts` मध्ये नोंदणी करा (लोडवर Zod-प्रमाणित)
2. जर कस्टम लॉजिक आवश्यक असेल तर `open-sse/executors/` मध्ये कार्यान्वयन जोडा (`BaseExecutor` विस्तारित करा)
3. जर नॉन-OpenAI फॉरमॅट असेल तर `open-sse/translator/` मध्ये अनुवादक जोडा
4. जर OAuth-आधारित असेल तर `src/lib/oauth/constants/oauth.ts` मध्ये OAuth कॉन्फिग जोडा — जर अपस्ट्रीम CLI सार्वजनिक client_id/secret पाठवत असेल, तर `resolvePublicCred()` द्वारे समाविष्ट करा (पहा `docs/security/PUBLIC_CREDS.md`), **कधीही** लिटरल म्हणून नाही
5. `open-sse/config/providerRegistry.ts` मध्ये मॉडेल्स नोंदणी करा
6. `tests/unit/` मध्ये चाचण्या लिहा (जर तुम्ही नवीन समाविष्ट केलेल्या डिफॉल्टसाठी सार्वजनिकCreds आकाराचे प्रमाणित केले तर समाविष्ट करा)

### नवीन API मार्ग जोडणे

1. `src/app/api/v1/your-route/` अंतर्गत निर्देशिका तयार करा
2. `GET`/`POST` हँडलर्ससह `route.ts` तयार करा
3. नमुना अनुसरण करा: CORS → Zod शरीर प्रमाणन → वैकल्पिक प्रमाणीकरण → हँडलर प्रतिनिधित्व
4. हँडलर `open-sse/handlers/` मध्ये जातो (तिथून आयात करा, इनलाइन नाही)
5. त्रुटी प्रतिसाद `buildErrorBody()` / `errorResponse()` वापरतात `open-sse/utils/error.ts` कडून (स्वयंचलितपणे स्वच्छ केले — कधीही `err.stack` किंवा `err.message` कच्चा शरीरात ठेऊ नका). `docs/security/ERROR_SANITIZATION.md` पहा.
6. चाचण्या जोडा — कमीत कमी एक प्रमाणन समाविष्ट करा की त्रुटी प्रतिसाद स्टॅक ट्रेस लीक करत नाही (`!body.error.message.includes("at /")`)

### नवीन DB मॉड्यूल जोडणे

1. `src/lib/db/yourModule.ts` तयार करा — `./core.ts` कडून `getDbInstance` आयात करा
2. तुमच्या डोमेन टेबलसाठी CRUD कार्ये निर्यात करा
3. नवीन टेबल आवश्यक असल्यास `src/lib/db/migrations/` मध्ये स्थलांतर जोडा
4. `src/lib/localDb.ts` कडून पुनः-निर्यात करा (फक्त पुनः-निर्यात यादीत जोडा)
5. चाचण्या लिहा

### नवीन MCP साधन जोडणे

1. Zod इनपुट स्कीमा + असिंक्रोनस हँडलरसह `open-sse/mcp-server/tools/` मध्ये साधन व्याख्या जोडा
2. साधन सेटमध्ये नोंदणी करा (`createMcpServer()` द्वारे वायर्ड)
3. योग्य स्कोपमध्ये नियुक्त करा
4. चाचण्या लिहा (साधन आवाहन `mcp_audit` टेबलमध्ये लॉग केले जाते)

### नवीन A2A कौशल्य जोडणे

1. `src/lib/a2a/skills/` मध्ये कौशल्य तयार करा (5 आधीच अस्तित्वात आहेत: स्मार्ट-रूटिंग, कोटा-व्यवस्थापन, प्रदाता-शोध, खर्च-विश्लेषण, आरोग्य-रिपोर्ट)
2. कौशल्य कार्य संदर्भ प्राप्त करते (संदेश, मेटाडेटा) → संरचित परिणाम परत करते
3. `src/lib/a2a/taskExecution.ts` मध्ये `A2A_SKILL_HANDLERS` मध्ये नोंदणी करा
4. `src/app/.well-known/agent.json/route.ts` मध्ये उघडा (एजंट कार्ड)
5. `tests/unit/` मध्ये चाचण्या लिहा
6. `docs/frameworks/A2A-SERVER.md` कौशल्य टेबलमध्ये दस्तऐवजीकरण करा

### नवीन क्लाउड एजंट जोडणे

1. `src/lib/cloudAgent/agents/` मध्ये `CloudAgentBase` विस्तारित करणारा एजंट वर्ग तयार करा (3 आधीच अस्तित्वात आहेत: codex-cloud, devin, jules)
2. `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources` कार्यान्वित करा
3. `src/lib/cloudAgent/registry.ts` मध्ये नोंदणी करा
4. आवश्यक असल्यास OAuth/क्रेडेन्शियल्स हाताळणी जोडा (`src/lib/oauth/providers/`)
5. चाचण्या + `docs/frameworks/CLOUD_AGENT.md` मध्ये दस्तऐवजीकरण करा

### नवीन गार्डरेल / इव्हॅल / कौशल्य / वेबहुक इव्हेंट जोडणे

- गार्डरेल: `src/lib/guardrails/` → दस्तऐवज: `docs/security/GUARDRAILS.md`
- इव्हॅल सूट: `src/lib/evals/` → दस्तऐवज: `docs/frameworks/EVALS.md`
- कौशल्य (सँडबॉक्स): `src/lib/skills/` → दस्तऐवज: `docs/frameworks/SKILLS.md`
- वेबहुक इव्हेंट: `src/lib/webhookDispatcher.ts` → दस्तऐवज: `docs/frameworks/WEBHOOKS.md`

## संदर्भ दस्तऐवज

कोणत्याही महत्त्वाच्या बदलासाठी, आधी संबंधित गहन अभ्यास वाचा:

| क्षेत्र                                    | दस्तऐवज                                                           |
| ------------------------------------------ | ----------------------------------------------------------------- |
| रेपो नेव्हिगेशन                            | `docs/architecture/REPOSITORY_MAP.md`                             |
| आर्किटेक्चर                                | `docs/architecture/ARCHITECTURE.md`                               |
| अभियांत्रिकी संदर्भ                        | `docs/architecture/CODEBASE_DOCUMENTATION.md`                     |
| ऑटो-कॉम्बो (9-फॅक्टर स्कोअरिंग, 14 धोरणे)  | `docs/routing/AUTO-COMBO.md`                                      |
| टिकाऊपणा (3 यांत्रिके)                     | `docs/architecture/RESILIENCE_GUIDE.md`                           |
| विचारणाचे पुनरावलोकन                       | `docs/routing/REASONING_REPLAY.md`                                |
| कौशल्यांचे फ्रेमवर्क                       | `docs/frameworks/SKILLS.md`                                       |
| मेमरी प्रणाली (FTS5 + Qdrant)              | `docs/frameworks/MEMORY.md`                                       |
| क्लाउड एजंट्स                              | `docs/frameworks/CLOUD_AGENT.md`                                  |
| गार्डरेल्स (PII / इंजेक्शन / दृष्टिकोन)    | `docs/security/GUARDRAILS.md`                                     |
| सार्वजनिक अपस्ट्रीम प्रमाणपत्र (जेमिनी/इ.) | `docs/security/PUBLIC_CREDS.md`                                   |
| त्रुटी संदेश स्वच्छता                      | `docs/security/ERROR_SANITIZATION.md`                             |
| मूल्यांकन                                  | `docs/frameworks/EVALS.md`                                        |
| अनुपालन / ऑडिट                             | `docs/security/COMPLIANCE.md`                                     |
| वेबहुक्स                                   | `docs/frameworks/WEBHOOKS.md`                                     |
| अधिकृतता पाईपलाइन                          | `docs/architecture/AUTHZ_GUIDE.md`                                |
| गुप्तता (TLS / फिंगरप्रिंट)                | `docs/security/STEALTH_GUIDE.md`                                  |
| एजंट प्रोटोकॉल (A2A / ACP / क्लाउड)        | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`                        |
| MCP सर्व्हर                                | `docs/frameworks/MCP-SERVER.md`                                   |
| A2A सर्व्हर                                | `docs/frameworks/A2A-SERVER.md`                                   |
| API संदर्भ + OpenAPI                       | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
| प्रदाता कॅटलॉग (स्वयंचलित-निर्मित)         | `docs/reference/PROVIDER_REFERENCE.md`                            |
| रिलीज प्रवाह                               | `docs/ops/RELEASE_CHECKLIST.md`                                   |

---

## चाचणी

| काय                     | कमांड                                                          |
| ----------------------- | -------------------------------------------------------------- |
| युनिट चाचण्या           | `npm run test:unit`                                            |
| एकल फाइल                | `node --import tsx/esm --test tests/unit/file.test.ts`         |
| Vitest (MCP, autoCombo) | `npm run test:vitest`                                          |
| E2E (Playwright)        | `npm run test:e2e`                                             |
| प्रोटोकॉल E2E (MCP+A2A) | `npm run test:protocols:e2e`                                   |
| इकोसिस्टम               | `npm run test:ecosystem`                                       |
| कव्हरेज गेट             | `npm run test:coverage` (75/75/75/70 — विधान/रेषा/कार्ये/शाखा) |
| कव्हरेज रिपोर्ट         | `npm run coverage:report`                                      |

**PR नियम**: जर तुम्ही `src/`, `open-sse/`, `electron/`, किंवा `bin/` मध्ये उत्पादन कोड बदलला, तर तुम्हाला त्या PR मध्ये चाचण्या समाविष्ट करणे किंवा अद्यतनित करणे आवश्यक आहे.

**चाचणी स्तर प्राधान्य**: युनिट प्रथम → एकत्रीकरण (बहु-मॉड्यूल किंवा DB स्थिती) → e2e (UI/कार्यप्रवाह फक्त). बग पुनरुत्पादनांना स्वयंचलित चाचण्यांमध्ये कोडित करा, दुरुस्तीसह किंवा आधी.

**Copilot कव्हरेज धोरण**: जेव्हा PR उत्पादन कोड बदलतो आणि कव्हरेज 75% (विधान/रेषा/कार्ये) किंवा 70% (शाखा) खाली असते, तेव्हा फक्त अहवाल देऊ नका — चाचण्या जोडा किंवा अद्यतनित करा, कव्हरेज गेट पुन्हा चालवा, नंतर पुष्टीसाठी विचारा. चालवलेले कमांड, बदललेले चाचणी फाइल्स, आणि अंतिम कव्हरेज परिणाम PR अहवालात समाविष्ट करा.

---

## Git कार्यप्रवाह

```bash
# मुख्य शाखेत थेट कमिट करू नका
git checkout -b feat/your-feature
git commit -m "feat: describe your change"
git push -u origin feat/your-feature
```

**शाखा उपसर्ग**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

**कमिट स्वरूप** (परंपरागत कमिट्स): `feat(db): add circuit breaker` — स्कोप: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

**Husky हुक्स**:

- **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11`
- **pre-push**: `npm run test:unit`

---

## वातावरण

- **रनटाइम**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES मॉड्यूल
- **TypeScript**: 5.9+, लक्ष्य ES2022, मॉड्यूल esnext, रिझोल्यूशन बंडलर
- **पथ उपसर्ग**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
- **डीफॉल्ट पोर्ट**: 20128 (API + डॅशबोर्ड एकाच पोर्टवर)
- **डेटा निर्देशिका**: `DATA_DIR` env var, डीफॉल्ट `~/.omniroute/`
- **महत्त्वाचे env vars**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
- सेटअप: `cp .env.example .env` नंतर `JWT_SECRET` (`openssl rand -base64 48`) आणि `API_KEY_SECRET` (`openssl rand -hex 32`) तयार करा

---

## कठोर नियम

1. कधीही गुप्त माहिती किंवा प्रमाणपत्रे कमिट करू नका
2. कधीही `localDb.ts` मध्ये लॉजिक जोडू नका
3. कधीही `eval()` / `new Function()` / implied eval वापरू नका
4. कधीही थेट `main` मध्ये कमिट करू नका
5. कधीही मार्गांमध्ये कच्चा SQL लिहू नका — `src/lib/db/` मॉड्यूल वापरा
6. कधीही SSE प्रवाहांमध्ये चुकांना गुपचूप गिळून टाका
7. नेहमी Zod स्कीमासह इनपुटची पडताळणी करा
8. उत्पादन कोड बदलताना नेहमी चाचण्या समाविष्ट करा
9. कव्हरेज ≥75% (विधान, रेषा, कार्ये) / ≥70% (शाखा) राहिले पाहिजे. वर्तमान मोजलेले: ~82%.
10. स्पष्ट ऑपरेटर मंजुरीशिवाय Husky हुक्स (`--no-verify`, `--no-gpg-sign`) बायपास करू नका.
11. कधीही सार्वजनिक अपस्ट्रीम OAuth client_id/secret किंवा Firebase वेब कीज स्ट्रिंग लिटरल म्हणून समाविष्ट करू नका — नेहमी `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`) द्वारे जा. पहा `docs/security/PUBLIC_CREDS.md`.
12. कधीही HTTP / SSE / कार्यकारी प्रतिसादांमध्ये कच्चा `err.stack` / `err.message` परत करू नका — नेहमी `buildErrorBody()` किंवा `sanitizeErrorMessage()` (`open-sse/utils/error.ts`) द्वारे मार्गदर्शित करा. पहा `docs/security/ERROR_SANITIZATION.md`.
13. कधीही बाह्य पथ किंवा रनटाइम मूल्ये `exec()`/`spawn()` कडे पाठवलेल्या शेल स्क्रिप्टमध्ये स्ट्रिंग-इंटरपोलेट करू नका — त्याऐवजी `env` पर्यायाद्वारे पास करा. संदर्भ: `src/mitm/cert/install.ts::updateNssDatabases`.
14. कधीही CodeQL / Secret-Scanning अलर्ट नाकारू नका (a) वर दिलेल्या पॅटर्न दस्तऐवजांची तपासणी न करता, आणि (b) नकारात्मक टिप्पणीत तांत्रिक कारणाची नोंद न करता. उदाहरण: `js/stack-trace-exposure` कॉलसाइटवर उभा राहिला आहे जो आधीच `sanitizeErrorMessage()` द्वारे मार्गदर्शित आहे, हे एक ज्ञात CodeQL मर्यादा आहे (कस्टम सॅनिटायझर्स ओळखले जात नाहीत) — `docs/security/ERROR_SANITIZATION.md` संदर्भित करून `false positive` म्हणून नकारा.
15. कधीही चाइल्ड प्रक्रियांचा स्पॉन करणारे मार्ग (`/api/mcp/`, `/api/cli-tools/runtime/`) समाविष्ट करू नका `src/server/authz/routeGuard.ts` मध्ये `isLocalOnlyPath()` वर्गीकरणाशिवाय. लूपबॅक अंमलबजावणी कोणत्याही प्रमाणीकरण तपासणीपूर्वी अनिवार्यपणे होते — टनलद्वारे गळती झालेला JWT प्रक्रिया स्पॉनिंगला ट्रिगर करू शकत नाही. पहा `docs/security/ROUTE_GUARD_TIERS.md`.
16. AI सहाय्यक, LLM किंवा स्वयंचलित खात्याला श्रेय देणारे `Co-Authored-By` ट्रेलर्स कधीही समाविष्ट करू नका (उदा. "Claude", "GPT", "Copilot", "Bot" असलेली नावे; `anthropic.com` / `openai.com` / बॉट-मालकीच्या `noreply.github.com` पत्त्यांवरील ईमेल). असे ट्रेलर्स GitHub वर बॉट खात्यात कमिट अॅट्रिब्यूशन रूट करतात, PR इतिहासात खऱ्या लेखकाला (`diegosouzapw`) लपवतात. मानवी सहयोगी — upstream PR लेखक आणि OmniRoute मध्ये पोर्ट केले जाणारे issue रिपोर्टर सह — मानक `Co-authored-by: Name <email>` ट्रेलर्ससह श्रेय मिळवू शकतात आणि मिळावे; upstream-port वर्कफ्लो (`/port-upstream-features`, `/port-upstream-issues`) यावर अवलंबून आहेत.