OmniRoute/docs/i18n/sw/CLAUDE.md

# CLAUDE.md (Kiswahili)

🌐 **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) · 🇮🇳 [mr](../mr/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) · 🇮🇳 [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)

---

Hii faili inatoa mwongozo kwa Claude Code (claude.ai/code) unapofanya kazi na msimbo katika hifadhi hii.

## Mwanzo wa Haraka

```bash
npm install                    # Sakinisha deps (inasanifisha .env kutoka .env.example)
npm run dev                    # Seva ya maendeleo katika http://localhost:20128
npm run build                  # Ujenzi wa uzalishaji (Next.js 16 standalone)
npm run lint                   # ESLint (makosa 0 yanatarajiwa; onyo ni ya awali)
npm run typecheck:core         # Ukaguzi wa TypeScript (inapaswa kuwa safi)
npm run typecheck:noimplicit:core  # Ukaguzi mkali (hakuna implicit any)
npm run test:coverage          # Jaribio la kitengo + lango la kufunika (75/75/75/70 — taarifa/mstari/funzioni/matengo)
npm run check                  # lint + jaribio pamoja
npm run check:cycles           # Gundua utegemezi wa mzunguko
```

### Kuendesha Majaribio

```bash
# Faili moja la jaribio (mwanzo wa jaribio la asili la Node.js — majaribio mengi)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (seva ya MCP, autoCombo, cache)
npm run test:vitest

# Suite zote
npm run test:all
```

Kwa matrix kamili ya majaribio, angalia `CONTRIBUTING.md` → "Kuendesha Majaribio". Kwa usanifu wa kina, angalia `AGENTS.md`.

---

## Mradi kwa Muonekano

**OmniRoute** — proxy/router ya AI iliyounganishwa. Kipengele kimoja, watoa huduma 160+, auto-fallback.

| Tabaka        | Mahali                  | Kusudi                                                                   |
| ------------- | ----------------------- | ------------------------------------------------------------------------ |
| API Routes    | `src/app/api/v1/`       | Next.js App Router — maeneo ya kuingia                                   |
| Handlers      | `open-sse/handlers/`    | Usindikaji wa maombi (chat, embeddings, nk)                              |
| Executors     | `open-sse/executors/`   | Usambazaji wa HTTP maalum kwa mtoa huduma                                |
| Translators   | `open-sse/translator/`  | Mabadiliko ya muundo (OpenAI↔Claude↔Gemini)                              |
| Transformer   | `open-sse/transformer/` | API za majibu ↔ Kukamilisha Chat                                         |
| Services      | `open-sse/services/`    | Uelekeo wa combo, mipaka ya viwango, caching, nk                         |
| Database      | `src/lib/db/`           | Moduli za eneo la SQLite (faili 45+, uhamasishaji 55)                    |
| Domain/Policy | `src/domain/`           | Injini ya sera, sheria za gharama, mantiki ya fallback                   |
| MCP Server    | `open-sse/mcp-server/`  | Zana 37 (30 msingi + 3 kumbukumbu + 4 ujuzi), usafirishaji 3, ~13 maeneo |
| A2A Server    | `src/lib/a2a/`          | Itifaki ya wakala ya JSON-RPC 2.0                                        |
| Skills        | `src/lib/skills/`       | Mfumo wa ujuzi unaoweza kupanuliwa                                       |
| Memory        | `src/lib/memory/`       | Kumbukumbu ya mazungumzo ya kudumu                                       |

Monorepo: `src/` (programu ya Next.js 16), `open-sse/` (nafasi ya injini ya utiririshaji), `electron/` (programu ya desktop), `tests/`, `bin/` (kiingilio cha CLI).

---

## Mchakato wa Ombi

```
Client → /v1/chat/completions (Njia ya Next.js)
  → CORS → Uthibitisho wa Zod → uthibitisho? → ukaguzi wa sera → ulinzi wa kuingiza maelekezo
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → ukaguzi wa cache → kikomo cha kiwango → mwelekeo wa combo?
      → resolveComboTargets() → handleSingleModel() kwa kila lengo
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → jaribu tena w/ backoff
    → tafsiri ya majibu → mkondo wa SSE au JSON
    → Ikiwa ni API za Majibu: responsesTransformer.ts TransformStream
```

Njia za API zinafuata muundo thabiti: `Njia → CORS preflight → Uthibitisho wa Zod → Uthibitisho wa hiari (extractApiKey/isValidApiKey) → Utekelezaji wa sera ya ufunguo wa API → Delegation ya Handler (open-sse)`. Hakuna middleware ya kimataifa ya Next.js — kukatiza ni maalum kwa njia.

**Mwelekeo wa combo** (`open-sse/services/combo.ts`): mikakati 14 (kipaumbele, uzito, kujaza-kwanza, mzunguko, P2C, nasibu, inayotumika kidogo, iliyoboreshwa kwa gharama, inayojua kurekebisha, nasibu kali, auto, lkgp, iliyoboreshwa kwa muktadha, relay ya muktadha). Kila lengo linaita `handleSingleModel()` ambayo inazunguka `handleChatCore()` na usimamizi wa makosa ya kila lengo na ukaguzi wa circuit breaker. Tazama `docs/routing/AUTO-COMBO.md` kwa alama za Auto-Combo za sababu 9 na `docs/architecture/RESILIENCE_GUIDE.md` kwa tabaka 3 za uhimilivu.

---

## Hali ya Uhimilivu wa Wakati

OmniRoute ina mitambo mitatu inayohusiana lakini tofauti ya kushindwa kwa muda. Hifadhi upeo wao tofauti unapofanya ufuatiliaji wa tabia ya mwelekeo. Tazama
[chati ya uhimilivu ya tabaka 3](./docs/diagrams/exported/resilience-3layers.svg)
(chanzo: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))
kwa ramani ya haraka.

### Mzigo wa Circuit wa Mtoa

**Upeo**: mtoa mzima, mfano `glm`, `openai`, `anthropic`.

**Madhumuni**: kusitisha kutuma trafiki kwa mtoa ambaye anashindwa mara kwa mara katika
ngazi ya upstream/service, ili mtoa mmoja asiye na afya usichelewesha kila ombi.

**Utekelezaji**:

- Darasa kuu: `src/shared/utils/circuitBreaker.ts`
- Nyaya za lango la mazungumzo/utekelezaji: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`
- API ya hali ya wakati: `src/app/api/monitoring/health/route.ts`
- Vifungashio vya pamoja: `open-sse/services/accountFallback.ts`
- Jedwali la hali lililohifadhiwa: `domain_circuit_breakers`

**Hali**:

- `CLOSED`: trafiki ya kawaida inaruhusiwa.
- `OPEN`: mtoa amezuiwa kwa muda; wito hupata jibu la mtoa-circuit-open
  au mwelekeo wa combo unakosa lengo lingine.
- `HALF_OPEN`: muda wa kurekebisha umepita; ruhusu ombi la uchunguzi. Mafanikio yanakamilisha
  breaker, kushindwa kunafungua tena.

**Defaults** (`open-sse/config/constants.ts`):

- Watoa wa OAuth: kigezo `3`, muda wa kurekebisha `60s`.
- Watoa wa ufunguo wa API: kigezo `5`, muda wa kurekebisha `30s`.
- Watoa wa ndani: kigezo `2`, muda wa kurekebisha `15s`.

Ni lazima tu hali za kushindwa za kiwango cha mtoa zifanye kazi ya breaker ya mtoa:

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

Usiweke breaker ya mtoa mzima kwa makosa ya kawaida ya akaunti/ufunguo/model kama vile
mambo mengi ya `401`, `403`, au `429`. Hayo kwa kawaida yanahusiana na kupoa kwa muunganisho au kufungwa kwa mfano. Mtoa wa ufunguo wa API wa jumla `403` unapaswa kuwa na uwezo wa kupona isipokuwa ikitambulika
kama kosa la mwisho la mtoa/akaunti.

Breaker hutumia urejeleaji wa polepole, sio kipima muda cha nyuma. Wakati `OPEN` inakoma, kusoma kama
`getStatus()`, `canExecute()`, na `getRetryAfterMs()` kunarejesha hali kuwa
`HALF_OPEN`, ili dashibodi na wajenzi wa wagombea wa combo wasiendelee kuondoa mtoa aliyeisha muda milele.

### Kupoa kwa Muunganisho

**Upeo**: muunganisho mmoja wa mtoa/akaunti/ufunguo.

**Madhumuni**: kupita kwa muda ufunguo mmoja mbaya/akaunti huku ikiruhusu muunganisho mingine kwa
mtoa huyo kuendelea kutumikia maombi.

**Utekelezaji**:

- Njia ya kuandika/update: `src/sse/services/auth.ts::markAccountUnavailable()`
- Uchaguzi wa akaunti/kuchuja: `src/sse/services/auth.ts::getProviderCredentials...`
- Hesabu ya kupoa: `open-sse/services/accountFallback.ts::checkFallbackError()`
- Mipangilio: `src/lib/resilience/settings.ts`

Sehemu muhimu kwenye muunganisho wa mtoa:

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

Wakati wa uchaguzi wa akaunti, muunganisho unakosa wakati:

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

Kupoa pia ni polepole: wakati `rateLimitedUntil` iko nyuma, muunganisho unakuwa
unaweza tena. Kwa matumizi ya mafanikio, `clearAccountError()` inafuta `testStatus`,
`rateLimitedUntil`, sehemu za makosa, na `backoffLevel`.

Tabia ya msingi ya kupoa muunganisho:

- Msingi wa kupoa wa OAuth: `5s`.
- Msingi wa kupoa wa ufunguo wa API: `3s`.
- Ufunguo wa API `429` unapaswa kupendelea vidokezo vya kujaribu tena vya upstream (`Retry-After`, vichwa vya kurekebisha, au
  maandiko ya kurekebisha yanayoweza kuchambuliwa) inapopatikana.
- Kushindwa kwa kurudi nyuma mara kwa mara hutumia urejeleaji wa kuongezeka:

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

Mlinzi wa kuzuia thundering-herd unazuia kushindwa kwa wakati mmoja kwenye muunganisho huo huo kutoka
kuongeza muda wa kupoa mara kwa mara au kuongezeka mara mbili kwa `backoffLevel`.

Hali za mwisho si kupoa. `banned`, `expired`, na `credits_exhausted` zinakusudiwa kubaki zisipatikane hadi
kuhifadhi au mipangilio kubadilika au opereta akizirekebisha. Usifute hali za mwisho kwa hali ya kupoa ya muda.

### Kufungwa kwa Mfano

**Upeo**: mtoa + muunganisho + mfano.

**Madhumuni**: kuepuka kuzima muunganisho mzima wakati mfano mmoja tu haupatikani au
umewekwa kikomo kwa muunganisho huo.

Mifano:

- Watoa wa quota kwa mfano wanaorejelea `429`.
- Watoa wa ndani wanaorejelea `404` kwa mfano mmoja uliokosekana.
- Kushindwa kwa ruhusa ya mfano/mode maalum wa mtoa kama vile modes za Grok zilizochaguliwa.

Kufungwa kwa mfano kunaishi katika `open-sse/services/accountFallback.ts` na inaruhusu muunganisho huo huo kuendelea kutumikia mifano mingine.

### Mwongozo wa Ufuatiliaji

- Ikiwa funguo zote za mtoa zimeachwa, angalia hali ya breaker ya mtoa na kila
  muunganisho wa `rateLimitedUntil`/`testStatus`.
- Ikiwa mtoa anaonekana kuondolewa milele baada ya dirisha la kurekebisha, angalia ikiwa msimbo
  unasoma `state` halisi badala ya kutumia `getStatus()`/`canExecute()`.
- Ikiwa funguo moja ya mtoa inashindwa lakini zingine zinapaswa kufanya kazi, pendelea kupoa kwa muunganisho badala ya breaker ya mtoa.
- Ikiwa mfano mmoja tu unashindwa, pendelea kufungwa kwa mfano badala ya kupoa kwa muunganisho.
- Ikiwa hali inapaswa kujiokoa yenyewe, inapaswa kuwa na alama ya wakati wa baadaye/muda wa kurekebisha na njia ya
  kusoma inayorejesha hali iliyokwisha muda. Hali za kudumu zinahitaji mabadiliko ya mikopo
  au mipangilio kwa mkono.

## Misingi Muhimu

### Mtindo wa Kanuni

- **Spaces 2**, semicolons, double quotes, upana wa herufi 100, es5 trailing commas (inasimamiwa na lint-staged kupitia Prettier)
- **Maaliko**: nje → ndani (`@/`, `@omniroute/open-sse`) → ya uhusiano
- **Majina**: faili=camelCase/kebab, vipengele=PascalCase, constants=UPPER_SNAKE
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = kosa kila mahali; `no-explicit-any` = onyo katika `open-sse/` na `tests/`
- **TypeScript**: `strict: false`, lengo ES2022, moduli esnext, resolution bundler. Prefer explicit types.

### Hifadhidata

- **Daima** pitia moduli za eneo `src/lib/db/` — **kamwe** usiandike SQL safi katika njia au wakala
- **Kamwe** usiongeze mantiki katika `src/lib/localDb.ts` (safi ya re-export tu)
- **Kamwe** usi-import barrel kutoka `localDb.ts` — badala yake, import moduli maalum za `db/`
- DB singleton: `getDbInstance()` kutoka `src/lib/db/core.ts` (WAL journaling)
- Migrations: `src/lib/db/migrations/` — faili za SQL zenye toleo, idempotent, zitekelezwe katika muamala

### Kushughulikia Makosa

- jaribu/catch na aina maalum za makosa, log na muktadha wa pino
- Kamwe usifanye makosa katika SSE streams — tumia ishara za kukatisha kwa usafishaji
- Rudisha msimamo sahihi wa HTTP (4xx/5xx)

### Usalama

- **Kamwe** usitumie `eval()`, `new Function()`, au eval iliyodhaniwa
- Thibitisha kila ingizo kwa kutumia Zod schemas
- Ficha akidi wakati wa kupumzika (AES-256-GCM)
- Orodha ya vichwa vya juu ya denylist: `src/shared/constants/upstreamHeaders.ts` — panua sanitize, Zod schemas, na vipimo vya kitengo vinavyolingana unapohariri
- **Akidi za umma za juu** (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web keys zilizochukuliwa kutoka kwa CLIs za umma): **LAZIMA** ziwe zimeingizwa kupitia `resolvePublicCred()` kutoka `open-sse/utils/publicCreds.ts` — **kamwe** kama maandiko ya herufi. Tazama `docs/security/PUBLIC_CREDS.md` kwa muundo wa lazima.
- **Majibu ya makosa** (HTTP / SSE / executor / MCP handler): **LAZIMA** ipitie `buildErrorBody()` au `sanitizeErrorMessage()` kutoka `open-sse/utils/error.ts` — **kamwe** usiweke `raw err.stack` au `raw err.message` katika mwili wa majibu. Tazama `docs/security/ERROR_SANITIZATION.md`.
- **Amri za shell zilizojengwa kutoka kwa mabadiliko**: unapoitisha `exec()`/`spawn()` na skripti inayohitaji thamani za wakati wa kukimbia, zipitisheni kupitia chaguo la `env` (imekimbizwa kiotomatiki) — **kamwe** usiingize mabadiliko yasiyoaminika/ya nje katika mwili wa skripti. Rejelea: `src/mitm/cert/install.ts::updateNssDatabases`.
- **Maktaba salama kwa default** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): pendelea Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink kuliko utekelezaji wa kawaida kila wakati unapoongeza uso mpya wa usalama.

---

## Mifano ya Marekebisho ya Kawaida

### Kuongeza Mtoa Huduma Mpya

1. Jisajili katika `src/shared/constants/providers.ts` (Zod-validated wakati wa kupakia)
2. Ongeza mtendaji katika `open-sse/executors/` ikiwa mantiki maalum inahitajika (panua `BaseExecutor`)
3. Ongeza mtafsiri katika `open-sse/translator/` ikiwa si muundo wa OpenAI
4. Ongeza usanidi wa OAuth katika `src/lib/oauth/constants/oauth.ts` ikiwa ni msingi wa OAuth — ikiwa CLI ya juu inatoa client_id/secret ya umma, ingiza kupitia `resolvePublicCred()` (tazama `docs/security/PUBLIC_CREDS.md`), **kamwe** kama maandiko
5. Jisajili mifano katika `open-sse/config/providerRegistry.ts`
6. Andika vipimo katika `tests/unit/` (jumuisha uthibitisho wa umbo la publicCreds ikiwa umeongeza default mpya iliyounganishwa)

### Kuongeza Njia Mpya ya API

1. Unda directory chini ya `src/app/api/v1/your-route/`
2. Unda `route.ts` na wakala wa `GET`/`POST`
3. Fuata muundo: CORS → uthibitisho wa mwili wa Zod → uthibitisho wa hiari → ugawaji wa wakala
4. Wakala huenda katika `open-sse/handlers/` (import kutoka hapo, si inline)
5. Majibu ya makosa yanatumia `buildErrorBody()` / `errorResponse()` kutoka `open-sse/utils/error.ts` (imekimbizwa kiotomatiki — kamwe usiweke `raw err.stack` au `raw err.message` katika mwili). Tazama `docs/security/ERROR_SANITIZATION.md`.
6. Ongeza vipimo — ikiwa ni pamoja na angalau uthibitisho mmoja kwamba majibu ya makosa hayavuji nyaraka za stack (`!body.error.message.includes("at /")`)

### Kuongeza Moduli Mpya ya DB

1. Unda `src/lib/db/yourModule.ts` — import `getDbInstance` kutoka `./core.ts`
2. Export kazi za CRUD kwa ajili ya jedwali lako la eneo
3. Ongeza uhamasishaji katika `src/lib/db/migrations/` ikiwa jedwali mpya zinahitajika
4. Re-export kutoka `src/lib/localDb.ts` (ongeza kwenye orodha ya re-export tu)
5. Andika vipimo

### Kuongeza Zana Mpya ya MCP

1. Ongeza ufafanuzi wa zana katika `open-sse/mcp-server/tools/` na muundo wa ingizo la Zod + wakala wa async
2. Jisajili katika seti ya zana (imeunganishwa na `createMcpServer()`)
3. Teua kwa upeo unaofaa
4. Andika vipimo (kuitisha zana kunarekodiwa kwenye jedwali la `mcp_audit`)

### Kuongeza Ujuzi Mpya wa A2A

1. Unda ujuzi katika `src/lib/a2a/skills/` (5 tayari zipo: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. Ujuzi unapata muktadha wa kazi (jumbe, metadata) → unarudisha matokeo yaliyoandaliwa
3. Jisajili katika `A2A_SKILL_HANDLERS` katika `src/lib/a2a/taskExecution.ts`
4. Funua katika `src/app/.well-known/agent.json/route.ts` (Kadi ya Wakala)
5. Andika vipimo katika `tests/unit/`
6. Andika katika `docs/frameworks/A2A-SERVER.md` jedwali la ujuzi

### Kuongeza Wakala Mpya wa Cloud

1. Unda darasa la wakala katika `src/lib/cloudAgent/agents/` ukipanua `CloudAgentBase` (3 tayari zipo: codex-cloud, devin, jules)
2. Tekeleza `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`
3. Jisajili katika `src/lib/cloudAgent/registry.ts`
4. Ongeza usimamizi wa OAuth/akidi ikiwa inahitajika (`src/lib/oauth/providers/`)
5. Vipimo + andika katika `docs/frameworks/CLOUD_AGENT.md`

### Kuongeza Guardrail Mpya / Eval / Ujuzi / Tukio la Webhook

- Guardrail: `src/lib/guardrails/` → docs: `docs/security/GUARDRAILS.md`
- Eval suite: `src/lib/evals/` → docs: `docs/frameworks/EVALS.md`
- Ujuzi (sandbox): `src/lib/skills/` → docs: `docs/frameworks/SKILLS.md`
- Tukio la Webhook: `src/lib/webhookDispatcher.ts` → docs: `docs/frameworks/WEBHOOKS.md`

## Hati ya Marejeleo

Kwa mabadiliko yoyote yasiyo ya kawaida, soma uchambuzi unaofanana kwanza:

| Eneo                                             | Hati                                                              |
| ------------------------------------------------ | ----------------------------------------------------------------- |
| Usafiri wa repo                                  | `docs/architecture/REPOSITORY_MAP.md`                             |
| Muktadha                                         | `docs/architecture/ARCHITECTURE.md`                               |
| Marejeleo ya uhandisi                            | `docs/architecture/CODEBASE_DOCUMENTATION.md`                     |
| Auto-Combo (alama 9, mikakati 14)                | `docs/routing/AUTO-COMBO.md`                                      |
| Ustahimilivu (mekaniki 3)                        | `docs/architecture/RESILIENCE_GUIDE.md`                           |
| Kurudi kwa mantiki                               | `docs/routing/REASONING_REPLAY.md`                                |
| Mfumo wa ujuzi                                   | `docs/frameworks/SKILLS.md`                                       |
| Mfumo wa kumbukumbu (FTS5 + Qdrant)              | `docs/frameworks/MEMORY.md`                                       |
| Wakala wa wingu                                  | `docs/frameworks/CLOUD_AGENT.md`                                  |
| Miongozo (PII / sindikizo / maono)               | `docs/security/GUARDRAILS.md`                                     |
| Akreditivu za umma za juu (Gemini/n.k.)          | `docs/security/PUBLIC_CREDS.md`                                   |
| Usafi wa ujumbe wa makosa                        | `docs/security/ERROR_SANITIZATION.md`                             |
| Tathmini                                         | `docs/frameworks/EVALS.md`                                        |
| Uzingatiaji / ukaguzi                            | `docs/security/COMPLIANCE.md`                                     |
| Webhooks                                         | `docs/frameworks/WEBHOOKS.md`                                     |
| Mchakato waidhinisha                             | `docs/architecture/AUTHZ_GUIDE.md`                                |
| Usiri (TLS / alama ya vidole)                    | `docs/security/STEALTH_GUIDE.md`                                  |
| Itifaki za wakala (A2A / ACP / Wingu)            | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`                        |
| Seva ya MCP                                      | `docs/frameworks/MCP-SERVER.md`                                   |
| Seva ya A2A                                      | `docs/frameworks/A2A-SERVER.md`                                   |
| Marejeleo ya API + OpenAPI                       | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
| Katalogi ya wasambazaji (iliyoundwa kiotomatiki) | `docs/reference/PROVIDER_REFERENCE.md`                            |
| Mchakato wa kutolewa                             | `docs/ops/RELEASE_CHECKLIST.md`                                   |

---

## Kupima

| Nini                    | Amri                                                                    |
| ----------------------- | ----------------------------------------------------------------------- |
| Vipimo vya kitengo      | `npm run test:unit`                                                     |
| Faili moja              | `node --import tsx/esm --test tests/unit/file.test.ts`                  |
| Vitest (MCP, autoCombo) | `npm run test:vitest`                                                   |
| E2E (Playwright)        | `npm run test:e2e`                                                      |
| Protokali E2E (MCP+A2A) | `npm run test:protocols:e2e`                                            |
| Mfumo                   | `npm run test:ecosystem`                                                |
| Lango la kufunika       | `npm run test:coverage` (75/75/75/70 — taarifa/mstari/funzo/mat branch) |
| Ripoti ya kufunika      | `npm run coverage:report`                                               |

**Kanuni ya PR**: Ikiwa unabadilisha msimbo wa uzalishaji katika `src/`, `open-sse/`, `electron/`, au `bin/`, lazima uweke au uboreshe vipimo katika PR hiyo hiyo.

**Upendeleo wa tabaka la mtihani**: kitengo kwanza → uunganisho (moduli nyingi au hali ya DB) → e2e (UI/mchakato tu). Fanya urekebishaji wa bug kama vipimo vya kiotomatiki kabla au pamoja na suluhisho.

**Sera ya kufunika ya Copilot**: Wakati PR inabadilisha msimbo wa uzalishaji na kufunika iko chini ya 75% (taarifa/mstari/funzo) au 70% (mata branch), usiweke tu ripoti — ongeza au boresha vipimo, rudisha lango la kufunika, kisha omba uthibitisho. Jumuisha amri zilizotekelezwa, faili za mtihani zilizobadilishwa, na matokeo ya mwisho ya kufunika katika ripoti ya PR.

---

## Mchakato wa Git

```bash
# Kamwe usiweke moja kwa moja kwenye main
git checkout -b feat/your-feature
git commit -m "feat: eleza mabadiliko yako"
git push -u origin feat/your-feature
```

**Viambatisho vya tawi**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

**Muundo wa commit** (Conventional Commits): `feat(db): ongeza circuit breaker` — maeneo: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

**Husky hooks**:

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

---

## Mazingira

- **Muda wa kukimbia**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, Moduli za ES
- **TypeScript**: 5.9+, lengo ES2022, moduli esnext, ufumbuzi wa bundler
- **Majina ya njia**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
- **Bandari ya kawaida**: 20128 (API + dashibodi kwenye bandari moja)
- **Direktori ya data**: `DATA_DIR` env var, inarudiwa kwa `~/.omniroute/`
- **Vigezo muhimu vya env**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
- Mipangilio: `cp .env.example .env` kisha tengeneza `JWT_SECRET` (`openssl rand -base64 48`) na `API_KEY_SECRET` (`openssl rand -hex 32`)

---

## Kanuni Ngumu

1. Kamwe usiweke siri au akidi
2. Kamwe usiongeze mantiki kwenye `localDb.ts`
3. Kamwe usitumie `eval()` / `new Function()` / eval iliyodhaniwa
4. Kamwe usiweke moja kwa moja kwenye `main`
5. Kamwe usiandike SQL safi katika njia — tumia moduli za `src/lib/db/`
6. Kamwe usinyamaze makosa kwa kimya katika SSE streams
7. Daima thibitisha ingizo kwa kutumia Zod schemas
8. Daima jumuisha vipimo unapobadilisha msimbo wa uzalishaji
9. Kufunika lazima kubaki ≥75% (taarifa, mistari, funzo) / ≥70% (mata branch). Kiwango cha sasa kilichopimwa: ~82%.
10. Kamwe usipite Husky hooks (`--no-verify`, `--no-gpg-sign`) bila idhini ya wazi ya opereta.
11. Kamwe usiweke funguo za umma za OAuth client_id/secret au funguo za Firebase Web kama maandiko ya maandiko — daima pitia `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). Tazama `docs/security/PUBLIC_CREDS.md`.
12. Kamwe usirudishe `raw err.stack` / `err.message` katika HTTP / SSE / majibu ya mtendaji — daima pitia kupitia `buildErrorBody()` au `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). Tazama `docs/security/ERROR_SANITIZATION.md`.
13. Kamwe usiingize njia za nje au thamani za kukimbia katika scripts za shell zinazopitishwa kwa `exec()`/`spawn()` — pitisha kupitia chaguo la `env` badala yake. Kumbuka: `src/mitm/cert/install.ts::updateNssDatabases`.
14. Kamwe usikatae arifa za CodeQL / Secret-Scanning bila (a) kwanza kuangalia hati za muundo hapo juu kuona kama msaidizi anatumika, na (b) kurekodi sababu ya kiufundi katika maoni ya kukataa. Kiwango: `js/stack-trace-exposure` kilichoinuliwa kwenye maeneo ya wito ambayo tayari yanapitia `sanitizeErrorMessage()` ni ukomo unaojulikana wa CodeQL (wasafishaji wa kawaida hawatambuliwi) — kataa kama `false positive` ukirejelea `docs/security/ERROR_SANITIZATION.md`.
15. Kamwe usifichue njia zinazozalisha michakato ya watoto (`/api/mcp/`, `/api/cli-tools/runtime/`) bila uainishaji wa `isLocalOnlyPath()` katika `src/server/authz/routeGuard.ts`. Utekelezaji wa loopback unafanyika bila masharti kabla ya ukaguzi wowote wa uthibitisho — JWT iliyovuja kupitia tunnel haiwezi kuanzisha uzalishaji wa mchakato. Tazama `docs/security/ROUTE_GUARD_TIERS.md`.
16. Usijumuishe kamwe trailers `Co-Authored-By` zinazompa sifa msaidizi wa AI, LLM, au akaunti ya automation (mfano majina yenye "Claude", "GPT", "Copilot", "Bot"; barua pepe katika `anthropic.com` / `openai.com` / anwani za `noreply.github.com` zinazomilikiwa na bots). Trailers kama hizi huelekeza attribution ya commit kwa akaunti ya bot katika GitHub, zikificha mwandishi halisi (`diegosouzapw`) katika historia ya PR. Washirikiano wa kibinadamu — pamoja na waandishi wa PR za upstream na waripoti wa issues wanaohamishwa kwenda OmniRoute — WANAWEZA na WANAPASWA kupewa sifa kwa trailers za kawaida `Co-authored-by: Name <email>`; mtiririko wa kazi wa upstream-port (`/port-upstream-features`, `/port-upstream-issues`) hutegemea hii.