docs: comprehensive docs review + i18n sync

- Fix .gitignore: add a2a-server.md, auto-combo.md, mcp-server.md, new-features/ to whitelist
- Rewrite FEATURES.md: 18 sections covering v2.0.12 state (Playground, Themes, CLI Agents, Media, API Keys, Audit Log)
- API_REFERENCE.md: add ACP Agents endpoints (/api/acp/agents GET/POST/DELETE)
- Sync all 6 root docs to 29 i18n directories (174 files)
- Remove stale git-tracked docs (adr/, i18n-tasks/)

docs/i18n/it/ARCHITECTURE.md

@@ -1,71 +1,71 @@
-# Architettura OmniRoute
+# OmniRoute Architecture
 
-🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md)
+🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md)
 
-_Ultimo aggiornamento: 2026-02-18_
+_Last updated: 2026-03-04_
 
-## Sintesi
+## Executive Summary
 
-OmniRoute è un gateway di routing AI locale e un dashboard basato su Next.js.
-Fornisce un singolo endpoint compatibile con OpenAI (`/v1/*`) e instrada il traffico attraverso più provider upstream con traduzione, fallback, aggiornamento dei token e monitoraggio dell'utilizzo.
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-Funzionalità principali:
+Core capabilities:
 
-- Superficie API compatibile con OpenAI per CLI/strumenti (28 provider)
-- Traduzione di richieste/risposte tra formati di fornitori
-- Fallback combo modello (sequenza multi-modello)
-- Fallback a livello di account (più account per fornitore)
-- Gestione della connessione del provider OAuth + chiave API
-- Generazione di incorporamento tramite `/v1/embeddings` (6 fornitori, 9 modelli)
-- Generazione di immagini tramite `/v1/images/generations` (4 fornitori, 9 modelli)
-- Pensa all'analisi dei tag (`<think>...</think>`) per i modelli di ragionamento
-- Sanificazione della risposta per una rigorosa compatibilità con l'SDK OpenAI
-- Normalizzazione dei ruoli (sviluppatore→sistema, sistema→utente) per compatibilità tra provider
-- Conversione dell'output strutturato (json_schema → Gemini ResponseSchema)
-- Persistenza locale per provider, chiavi, alias, combo, impostazioni, prezzi
-- Monitoraggio dell'utilizzo/costo e registrazione delle richieste
-- Sincronizzazione cloud opzionale per la sincronizzazione multi-dispositivo/stato
-- Lista consentita/lista bloccata IP per il controllo dell'accesso API
-- Gestione intelligente del budget (passthrough/automatico/personalizzato/adattivo)
-- Iniezione rapida del sistema globale
-- Monitoraggio della sessione e rilevamento delle impronte digitali
-- Limitazione tariffaria migliorata per account con profili specifici del fornitore
-- Modello di interruttore automatico per la resilienza del fornitore
-- Protezione gregge antituono con bloccaggio mutex
-- Cache di deduplicazione delle richieste basata su firma
-- Livello dominio: disponibilità del modello, regole di costo, politica di fallback, politica di blocco
-- Persistenza dello stato del dominio (cache write-through SQLite per fallback, budget, blocchi, interruttori automatici)
-- Motore di policy per la valutazione centralizzata delle richieste (blocco → budget → fallback)
-- Richiedi telemetria con aggregazione della latenza p50/p95/p99
-- ID di correlazione (X-Request-Id) per la traccia end-to-end
-- Registrazione del controllo di conformità con rinuncia per chiave API
-- Quadro di valutazione per la garanzia della qualità LLM
-- Dashboard dell'interfaccia utente di resilienza con stato dell'interruttore automatico in tempo reale
-- Provider OAuth modulari (12 moduli individuali in `src/lib/oauth/providers/`)
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers)
+- Policy engine for centralized request evaluation (lockout → budget → fallback)
+- Request telemetry with p50/p95/p99 latency aggregation
+- Correlation ID (X-Request-Id) for end-to-end tracing
+- Compliance audit logging with opt-out per API key
+- Eval framework for LLM quality assurance
+- Resilience UI dashboard with real-time circuit breaker status
+- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`)
 
-Modello runtime primario:
+Primary runtime model:
 
-- I percorsi dell'app Next.js in `src/app/api/*` implementano sia le API del dashboard che le API di compatibilità
-- Un core SSE/routing condiviso in `src/sse/*` + `open-sse/*` gestisce l'esecuzione, la traduzione, lo streaming, il fallback e l'utilizzo del provider
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
 
-## Ambito e confini
+## Scope and Boundaries
 
-### Nell'ambito
+### In Scope
 
-- Runtime del gateway locale
-- API di gestione della dashboard
-- Autenticazione del provider e aggiornamento del token
-- Richiedi traduzione e streaming SSE
-- Stato locale + persistenza dell'utilizzo
-- Orchestrazione opzionale della sincronizzazione cloud
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-### Fuori portata
+### Out of Scope
 
-- Implementazione del servizio cloud dietro `NEXT_PUBLIC_CLOUD_URL`
-- SLA/piano di controllo del fornitore esterno al processo locale
-- Gli stessi binari CLI esterni (Claude CLI, Codex CLI, ecc.)
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
 
-## Contesto del sistema di alto livello
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -81,8 +81,8 @@ flowchart LR
         API[V1 Compatibility API\n/v1/*]
         DASH[Dashboard + Management API\n/api/*]
         CORE[SSE + Translation Core\nopen-sse + src/sse]
-        DB[(db.json)]
-        UDB[(usage.json + log.txt)]
+        DB[(storage.sqlite)]
+        UDB[(usage tables + log artifacts)]
     end
 
     subgraph Upstreams[Upstream Providers]
@@ -113,151 +113,152 @@ flowchart LR
     DASH --> CLOUD
 ```
 
-## Componenti runtime principali
+## Core Runtime Components
 
-## 1) API e livello di routing (percorsi dell'app Next.js)
+## 1) API and Routing Layer (Next.js App Routes)
 
-Directory principali:
+Main directories:
 
-- `src/app/api/v1/*` e `src/app/api/v1beta/*` per API di compatibilità
-- `src/app/api/*` per le API di gestione/configurazione
-- Successivamente riscrive nella mappa `next.config.mjs` `/v1/*` in `/api/v1/*`
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Percorsi di compatibilità importanti:
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts`: include modelli personalizzati con `custom: true`
-- `src/app/api/v1/embeddings/route.ts`: generazione di incorporamenti (6 fornitori)
-- `src/app/api/v1/images/generations/route.ts` — generazione di immagini (4+ fornitori incluso Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts`: chat dedicata per provider
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts`: incorporamenti dedicati per provider
-- `src/app/api/v1/providers/[provider]/images/generations/route.ts`: immagini dedicate per provider
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
 - `src/app/api/v1beta/models/[...path]/route.ts`
 
-Domini di gestione:
+Management domains:
 
-- Autenticazione/impostazioni: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Provider/connessioni: `src/app/api/providers*`
-- Nodi fornitore: `src/app/api/provider-nodes*`
-- Modelli personalizzati: `src/app/api/provider-models` (GET/POST/DELETE)
-- Catalogo modelli: `src/app/api/models/catalog` (OTTIENI)
-- Configurazione proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- Providers/connections: `src/app/api/providers*`
+- Provider nodes: `src/app/api/provider-nodes*`
+- Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
+- Model catalog: `src/app/api/models/route.ts` (GET)
+- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
 - OAuth: `src/app/api/oauth/*`
-- Chiavi/alias/combo/prezzi: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
-- Utilizzo: `src/app/api/usage/*`
-- Sincronizzazione/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- Aiutanti degli strumenti CLI: `src/app/api/cli-tools/*`
-- Filtro IP: `src/app/api/settings/ip-filter` (GET/PUT)
-- Budget pensato: `src/app/api/settings/thinking-budget` (GET/PUT)
-- Richiesta di sistema: `src/app/api/settings/system-prompt` (GET/PUT)
-- Sessioni: `src/app/api/sessions` (GET)
-- Limiti di velocità: `src/app/api/rate-limits` (GET)
-- Resilienza: `src/app/api/resilience` (GET/PATCH): profili dei fornitori, interruttore automatico, stato limite di velocità
-- Ripristino della resilienza: `src/app/api/resilience/reset` (POST): ripristina gli interruttori + tempi di recupero
-- Statistiche cache: `src/app/api/cache/stats` (OTTIENI/ELIMINA)
-- Disponibilità del modello: `src/app/api/models/availability` (GET/POST)
-- Telemetria: `src/app/api/telemetry/summary` (OTTIENI)
-- Budget: `src/app/api/usage/budget` (OTTIENI/POST)
-- Catene di fallback: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Controllo di conformità: `src/app/api/compliance/audit-log` (GET)
-- Valutazioni: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Politiche: `src/app/api/policies` (GET/POST)
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
+- Budget: `src/app/api/usage/budget` (GET/POST)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Policies: `src/app/api/policies` (GET/POST)
 
-## 2) SSE + Nucleo di traduzione
+## 2) SSE + Translation Core
 
-Principali moduli di flusso:
+Main flow modules:
 
-- Voce: `src/sse/handlers/chat.ts`
-- Orchestrazione principale: `open-sse/handlers/chatCore.ts`
-- Adattatori di esecuzione del provider: `open-sse/executors/*`
-- Rilevamento formato/configurazione provider: `open-sse/services/provider.ts`
-- Analisi/risoluzione del modello: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Logica di fallback dell'account: `open-sse/services/accountFallback.ts`
-- Registro delle traduzioni: `open-sse/translator/index.ts`
-- Trasformazioni del flusso: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-- Estrazione/normalizzazione dell'utilizzo: `open-sse/utils/usageTracking.ts`
-- Pensa al parser dei tag: `open-sse/utils/thinkTagParser.ts`
-- Gestore di incorporamento: `open-sse/handlers/embeddings.ts`
-- Incorporamento del registro dei provider: `open-sse/config/embeddingRegistry.ts`
-- Gestore di generazione di immagini: `open-sse/handlers/imageGeneration.ts`
-- Registro del fornitore di immagini: `open-sse/config/imageRegistry.ts`
-- Sanificazione della risposta: `open-sse/handlers/responseSanitizer.ts`
-- Normalizzazione del ruolo: `open-sse/services/roleNormalizer.ts`
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-Servizi (logica aziendale):
+Services (business logic):
 
-- Selezione/punteggio dell'account: `open-sse/services/accountSelector.ts`
-- Gestione del ciclo di vita del contesto: `open-sse/services/contextManager.ts`
-- Applicazione del filtro IP: `open-sse/services/ipFilter.ts`
-- Monitoraggio della sessione: `open-sse/services/sessionManager.ts`
-- Richiedi deduplicazione: `open-sse/services/signatureCache.ts`
-- Inserimento prompt del sistema: `open-sse/services/systemPrompt.ts`
-- Gestione intelligente del budget: `open-sse/services/thinkingBudget.ts`
-- Routing del modello con caratteri jolly: `open-sse/services/wildcardRouter.ts`
-- Gestione dei limiti di velocità: `open-sse/services/rateLimitManager.ts`
-- Interruttore automatico: `open-sse/services/circuitBreaker.ts`
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
 
-Moduli del livello di dominio:
+Domain layer modules:
 
-- Disponibilità del modello: `src/lib/domain/modelAvailability.ts`
-- Regole di costo/budget: `src/lib/domain/costRules.ts`
-- Politica di riserva: `src/lib/domain/fallbackPolicy.ts`
-- Risolutore combinato: `src/lib/domain/comboResolver.ts`
-- Politica di blocco: `src/lib/domain/lockoutPolicy.ts`
-- Motore delle politiche: `src/domain/policyEngine.ts` — blocco centralizzato → budget → valutazione fallback
-- Catalogo codici errore: `src/lib/domain/errorCodes.ts`
-- ID richiesta: `src/lib/domain/requestId.ts`
-- Timeout recupero: `src/lib/domain/fetchTimeout.ts`
-- Richiedi telemetria: `src/lib/domain/requestTelemetry.ts`
-- Conformità/controllo: `src/lib/domain/compliance/index.ts`
-- Corridore di valutazione: `src/lib/domain/evalRunner.ts`
-- Persistenza dello stato del dominio: `src/lib/db/domainState.ts` — SQLite CRUD per catene di fallback, budget, cronologia dei costi, stato di blocco, interruttori automatici
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
+- Combo resolver: `src/lib/domain/comboResolver.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
+- Eval runner: `src/lib/domain/evalRunner.ts`
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-Moduli provider OAuth (12 file singoli in `src/lib/oauth/providers/`):
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-- Indice del registro: `src/lib/oauth/providers/index.ts`
-- Singoli fornitori: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
-- Involucro sottile: `src/lib/oauth/providers.ts` — riesporta da singoli moduli
+- Registry index: `src/lib/oauth/providers/index.ts`
+- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-## 3) Livello di persistenza
+## 3) Persistence Layer
 
-DB di stato primario:
+Primary state DB (SQLite):
 
-- `src/lib/localDb.ts`
-- file: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` quando impostato, altrimenti `~/.omniroute/db.json`)
-- entità: providerConnections, providerNodes, modelAliases, combo, apiKeys, impostazioni, prezzi, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
+- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
+- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
+- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
+- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
 
-DB di utilizzo:
+Usage persistence:
 
-- `src/lib/usageDb.ts`
-- file: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-- segue la stessa policy di directory di base di `localDb` (`DATA_DIR`, quindi `XDG_CONFIG_HOME/omniroute` quando impostato)
-- scomposto in sottomoduli focalizzati: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts`
+- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
+- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
+- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- legacy JSON files are migrated to SQLite by startup migrations when present
 
-DB dello stato del dominio (SQLite):
+Domain State DB (SQLite):
 
-- `src/lib/db/domainState.ts`: operazioni CRUD per lo stato del dominio
-- Tabelle (create in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Schema cache write-through: le mappe in memoria sono autorevoli in fase di esecuzione; le mutazioni vengono scritte in modo sincrono su SQLite; lo stato viene ripristinato dal DB all'avvio a freddo
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
 
-## 4) Superfici di autenticazione e sicurezza
+## 4) Auth + Security Surfaces
 
-- Autenticazione cookie dashboard: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- Generazione/verifica della chiave API: `src/shared/utils/apiKey.ts`
-- I segreti del provider sono persistenti nelle voci `providerConnections`
-- Supporto proxy in uscita tramite `open-sse/utils/proxyFetch.ts` (env vars) e `open-sse/utils/networkProxy.ts` (configurabile per provider o globale)
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
 
-## 5) Sincronizzazione nel cloud
+## 5) Cloud Sync
 
-- Inizializzazione pianificazione: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
-- Attività periodica: `src/shared/services/cloudSyncScheduler.ts`
-- Percorso di controllo: `src/app/api/sync/cloud/route.ts`
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
 
-## Ciclo di vita della richiesta (`/v1/chat/completions`)
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -304,7 +305,7 @@ sequenceDiagram
     Stream->>Usage: extract usage + persist history/log
 ```
 
-## Combo + Flusso di fallback dell'account
+## Combo + Account Fallback Flow
 
 ```mermaid
 flowchart TD
@@ -334,9 +335,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Le decisioni di fallback sono guidate da `open-sse/services/accountFallback.ts` utilizzando codici di stato ed euristica dei messaggi di errore.
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics.
 
-## Ciclo di vita dell'onboarding OAuth e dell'aggiornamento dei token
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -366,9 +367,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-L'aggiornamento durante il traffico in tempo reale viene eseguito all'interno di `open-sse/handlers/chatCore.ts` tramite l'esecutore `refreshCredentials()`.
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
 
-## Ciclo di vita della sincronizzazione cloud (Abilita/Sincronizza/Disabilita)
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -400,9 +401,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-La sincronizzazione periodica viene attivata da `CloudSyncScheduler` quando il cloud è abilitato.
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
 
-## Modello dei dati e mappa di archiviazione
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -503,14 +504,14 @@ erDiagram
     }
 ```
 
-File di archiviazione fisica:
+Physical storage files:
 
-- stato principale: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` quando impostato, altrimenti `~/.omniroute/db.json`)
-- statistiche di utilizzo: `${DATA_DIR}/usage.json`
-- righe di registro della richiesta: `${DATA_DIR}/log.txt`
-- sessioni di debug traduttore/richiesta opzionali: `<repo>/logs/...`
+- primary runtime DB: `${DATA_DIR}/storage.sqlite`
+- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
+- structured call payload archives: `${DATA_DIR}/call_logs/`
+- optional translator/request debug sessions: `<repo>/logs/...`
 
-## Topologia di distribuzione
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -522,8 +523,8 @@ flowchart LR
     subgraph ContainerOrProcess[OmniRoute Runtime]
         Next[Next.js Server\nPORT=20128]
         Core[SSE Core + Executors]
-        MainDB[(db.json)]
-        UsageDB[(usage.json/log.txt)]
+        MainDB[(storage.sqlite)]
+        UsageDB[(usage tables + log artifacts)]
     end
 
     subgraph External[External Services]
@@ -541,241 +542,242 @@ flowchart LR
     Next --> SyncCloud
 ```
 
-## Mappatura dei moduli (critica per la decisione)
+## Module Mapping (Decision-Critical)
 
-### Itinerario e moduli API
+### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API di compatibilità
-- `src/app/api/v1/providers/[provider]/*`: percorsi dedicati per provider (chat, incorporamenti, immagini)
-- `src/app/api/providers*`: CRUD del fornitore, convalida, test
-- `src/app/api/provider-nodes*`: gestione personalizzata dei nodi compatibili
-- `src/app/api/provider-models`: gestione del modello personalizzato (CRUD)
-- `src/app/api/models/catalog`: API del catalogo modelli completo (tutti i tipi raggruppati per fornitore)
-- `src/app/api/oauth/*`: flussi OAuth/codice dispositivo
-- `src/app/api/keys*`: ciclo di vita della chiave API locale
-- `src/app/api/models/alias`: gestione alias
-- `src/app/api/combos*`: gestione combo fallback
-- `src/app/api/pricing`: il prezzo sostituisce il calcolo dei costi
-- `src/app/api/settings/proxy`: configurazione proxy (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: test di connettività proxy in uscita (POST)
-- `src/app/api/usage/*`: API di utilizzo e log
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronizzazione cloud e aiutanti rivolti al cloud
-- `src/app/api/cli-tools/*`: scrittori/controllori di configurazione CLI locale
-- `src/app/api/settings/ip-filter`: lista consentita/lista bloccata IP (GET/PUT)
-- `src/app/api/settings/thinking-budget`: configurazione del budget del token pensante (GET/PUT)
-- `src/app/api/settings/system-prompt`: prompt di sistema globale (GET/PUT)
-- `src/app/api/sessions`: elenco sessioni attive (GET)
-- `src/app/api/rate-limits`: stato limite tariffa per account (GET)
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `src/app/api/providers*`: provider CRUD, validation, testing
+- `src/app/api/provider-nodes*`: custom compatible node management
+- `src/app/api/provider-models`: custom model management (CRUD)
+- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
+- `src/app/api/oauth/*`: OAuth/device-code flows
+- `src/app/api/keys*`: local API key lifecycle
+- `src/app/api/models/alias`: alias management
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-### Nucleo di routing ed esecuzione
+### Routing and Execution Core
 
-- `src/sse/handlers/chat.ts`: analisi delle richieste, gestione delle combo, ciclo di selezione dell'account
-- `open-sse/handlers/chatCore.ts`: traduzione, invio dell'esecutore, gestione di nuovi tentativi/aggiornamenti, impostazione del flusso
-- `open-sse/executors/*`: comportamento di rete e formato specifico del provider
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-### Registro di traduzione e convertitori di formato
+### Translation Registry and Format Converters
 
-- `open-sse/translator/index.ts`: registro e orchestrazione dei traduttori
-- Richiedi traduttori: `open-sse/translator/request/*`
-- Traduttori di risposta: `open-sse/translator/response/*`
-- Costanti di formato: `open-sse/translator/formats.ts`
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-### Persistenza
+### Persistence
 
-- `src/lib/localDb.ts`: configurazione/stato persistente
-- `src/lib/usageDb.ts`: cronologia di utilizzo e registri delle richieste in sequenza
+- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
+- `src/lib/localDb.ts`: compatibility re-export for DB modules
+- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
 
-## Copertura dell'esecutore del provider (modello strategico)
+## Provider Executor Coverage (Strategy Pattern)
 
-Ogni provider dispone di un esecutore specializzato che estende `BaseExecutor` (in `open-sse/executors/base.ts`), che fornisce la creazione di URL, la costruzione di intestazioni, nuovi tentativi con backoff esponenziale, hook di aggiornamento delle credenziali e il metodo di orchestrazione `execute()`.
+Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.
 
-| Esecutore testamentario | Fornitore/i                                                                                                                                                  | Movimentazione speciale                                                          |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
-| `DefaultExecutor`       | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configurazione URL/intestazione dinamica per provider                            |
-| `AntigravityExecutor`   | Google Antigravità                                                                                                                                           | ID progetto/sessione personalizzati, analisi Riprova dopo                        |
-| `CodexExecutor`         | Codice OpenAI                                                                                                                                                | Inserisce istruzioni di sistema, forza lo sforzo di ragionamento                 |
-| `CursorExecutor`        | Cursore IDE                                                                                                                                                  | Protocollo ConnectRPC, codifica Protobuf, firma della richiesta tramite checksum |
-| `GithubExecutor`        | Copilota GitHub                                                                                                                                              | Aggiornamento del token Copilot, intestazioni che imitano VSCode                 |
-| `KiroExecutor`          | AWS CodeWhisperer/Kiro                                                                                                                                       | Formato binario AWS EventStream → conversione SSE                                |
-| `GeminiCLIExecutor`     | Gemelli CLI                                                                                                                                                  | Ciclo di aggiornamento del token OAuth di Google                                 |
+| Executor              | Provider(s)                                                                                                                                                  | Special Handling                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider                               |
+| `AntigravityExecutor` | Google Antigravity                                                                                                                                           | Custom project/session IDs, Retry-After parsing                      |
+| `CodexExecutor`       | OpenAI Codex                                                                                                                                                 | Injects system instructions, forces reasoning effort                 |
+| `CursorExecutor`      | Cursor IDE                                                                                                                                                   | ConnectRPC protocol, Protobuf encoding, request signing via checksum |
+| `GithubExecutor`      | GitHub Copilot                                                                                                                                               | Copilot token refresh, VSCode-mimicking headers                      |
+| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                       | AWS EventStream binary format → SSE conversion                       |
+| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                   | Google OAuth token refresh cycle                                     |
 
-Tutti gli altri provider (inclusi i nodi compatibili personalizzati) utilizzano `DefaultExecutor`.
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
-## Matrice di compatibilità del fornitore
+## Provider Compatibility Matrix
 
-| Fornitore             | Formato         | Aut.                    | Flusso           | Non streaming | Aggiornamento token | API di utilizzo          |
-| --------------------- | --------------- | ----------------------- | ---------------- | ------------- | ------------------- | ------------------------ |
-| Claudio               | claude          | Chiave API/OAuth        | ✅               | ✅            | ✅                  | ⚠️ Solo amministratore   |
-| Gemelli               | gemelli         | Chiave API/OAuth        | ✅               | ✅            | ✅                  | ⚠️ Console cloud         |
-| Gemelli CLI           | gemelli-cli     | OAuth                   | ✅               | ✅            | ✅                  | ⚠️ Console cloud         |
-| Antigravità           | antigravità     | OAuth                   | ✅               | ✅            | ✅                  | ✅ API quota completa    |
-| OpenAI                | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| Codice                | risposte-openai | OAuth                   | ✅ forzato       | ❌            | ✅                  | ✅ Limiti tariffari      |
-| Copilota GitHub       | openai          | OAuth + token copilota  | ✅               | ✅            | ✅                  | ✅Istantanee delle quote |
-| Cursore               | cursore         | Checksum personalizzato | ✅               | ✅            | ❌                  | ❌                       |
-| Kiro                  | Kiro            | AWS SSO OIDC            | ✅ (EventStream) | ❌            | ✅                  | ✅ Limiti di utilizzo    |
-| Qwen                  | openai          | OAuth                   | ✅               | ✅            | ✅                  | ⚠️ Su richiesta          |
-| iFlow                 | openai          | OAuth (base)            | ✅               | ✅            | ✅                  | ⚠️ Su richiesta          |
-| OpenRouter            | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| GLM/Kimi/MiniMax      | claude          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| Ricerca profonda      | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| Groq                  | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| xAI (Grok)            | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| Maestrale             | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| Perplessità           | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| Insieme AI            | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| Fuochi d'artificio AI | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| Cerebri               | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| Coerenza              | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
-| NVIDIA NIM            | openai          | Chiave API              | ✅               | ✅            | ❌                  | ❌                       |
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| iFlow            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 
-## Copertura della traduzione del formato
+## Format Translation Coverage
 
-I formati sorgente rilevati includono:
+Detected source formats include:
 
 - `openai`
 - `openai-responses`
 - `claude`
 - `gemini`
 
-I formati di destinazione includono:
+Target formats include:
 
-- Chat/risposte OpenAI
-- Claudio
-- Busta Gemini/Gemini-CLI/Antigravità
+- OpenAI chat/Responses
+- Claude
+- Gemini/Gemini-CLI/Antigravity envelope
 - Kiro
-- Cursore
+- Cursor
 
-Le traduzioni utilizzano **OpenAI come formato hub**: tutte le conversioni passano attraverso OpenAI come formato intermedio:
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
 
 ```
 Source Format → OpenAI (hub) → Target Format
 ```
 
-Le traduzioni vengono selezionate dinamicamente in base alla forma del payload di origine e al formato di destinazione del provider.
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Ulteriori livelli di elaborazione nella pipeline di traduzione:
+Additional processing layers in the translation pipeline:
 
-- **Sanificazione delle risposte**: rimuove i campi non standard dalle risposte in formato OpenAI (sia in streaming che non in streaming) per garantire la rigorosa conformità dell'SDK
-- **Normalizzazione del ruolo**: converte `developer` → `system` per target non OpenAI; unisce `system` → `user` per i modelli che rifiutano il ruolo di sistema (GLM, ERNIE)
-- **Estrazione tag Think**: analizza i blocchi `<think>...</think>` dal contenuto nel campo `reasoning_content`
-- **Output strutturato**: converte OpenAI `response_format.json_schema` in `responseMimeType` di Gemini + `responseSchema`
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
-## Endpoint API supportati
+## Supported API Endpoints
 
-| Punto finale                                       | Formato                  | Gestore                                                                  |
-| -------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------ |
-| `POST /v1/chat/completions`                        | Chatta OpenAI            | `src/sse/handlers/chat.ts`                                               |
-| `POST /v1/messages`                                | Messaggi di Claude       | Stesso gestore (rilevato automaticamente)                                |
-| `POST /v1/responses`                               | Risposte OpenAI          | `open-sse/handlers/responsesHandler.ts`                                  |
-| `POST /v1/embeddings`                              | Incorporamenti OpenAI    | `open-sse/handlers/embeddings.ts`                                        |
-| `GET /v1/embeddings`                               | Elenco dei modelli       | Percorso API                                                             |
-| `POST /v1/images/generations`                      | Immagini OpenAI          | `open-sse/handlers/imageGeneration.ts`                                   |
-| `GET /v1/images/generations`                       | Elenco dei modelli       | Percorso API                                                             |
-| `POST /v1/providers/{provider}/chat/completions`   | Chatta OpenAI            | Dedicato per provider con convalida del modello                          |
-| `POST /v1/providers/{provider}/embeddings`         | Incorporamenti OpenAI    | Dedicato per provider con convalida del modello                          |
-| `POST /v1/providers/{provider}/images/generations` | Immagini OpenAI          | Dedicato per provider con convalida del modello                          |
-| `POST /v1/messages/count_tokens`                   | Conteggio gettoni Claude | Percorso API                                                             |
-| `GET /v1/models`                                   | Elenco modelli OpenAI    | Percorso API (chat + incorporamento + immagine + modelli personalizzati) |
-| `GET /api/models/catalog`                          | Catalogo                 | Tutti i modelli raggruppati per fornitore + tipo                         |
-| `POST /v1beta/models/*:streamGenerateContent`      | Nativo dei Gemelli       | Percorso API                                                             |
-| `GET/PUT/DELETE /api/settings/proxy`               | Configurazione proxy     | Configurazione proxy di rete                                             |
-| `POST /api/settings/proxy/test`                    | Connettività proxy       | Endpoint di test di integrità/connettività proxy                         |
-| `GET/POST/DELETE /api/provider-models`             | Modelli personalizzati   | Gestione modelli personalizzati per fornitore                            |
+| Endpoint                                           | Format             | Handler                                              |
+| -------------------------------------------------- | ------------------ | ---------------------------------------------------- |
+| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                           |
+| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                         |
+| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`              |
+| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                    |
+| `GET /v1/embeddings`                               | Model listing      | API route                                            |
+| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`               |
+| `GET /v1/images/generations`                       | Model listing      | API route                                            |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation         |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation         |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation         |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                            |
+| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models) |
+| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                            |
+| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                          |
+| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint              |
+| `GET/POST/DELETE /api/provider-models`             | Custom Models      | Custom model management per provider                 |
 
-## Gestore di bypass
+## Bypass Handler
 
-Il gestore di bypass (`open-sse/utils/bypassHandler.ts`) intercetta le richieste "usa e getta" note dalla CLI di Claude (ping di riscaldamento, estrazioni di titoli e conteggi di token) e restituisce una **risposta falsa** senza consumare token del provider upstream. Questo viene attivato solo quando `User-Agent` contiene `claude-cli`.
+The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`.
 
-## Richiedi la pipeline del registratore
+## Request Logger Pipeline
 
-Il logger delle richieste (`open-sse/utils/requestLogger.ts`) fornisce una pipeline di registrazione del debug in 7 fasi, disabilitata per impostazione predefinita, abilitata tramite `ENABLE_REQUEST_LOGS=true`:
+The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
 
 ```
 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
 → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
 ```
 
-I file vengono scritti in `<repo>/logs/<session>/` per ogni sessione di richiesta.
+Files are written to `<repo>/logs/<session>/` for each request session.
 
-## Modalità di fallimento e resilienza
+## Failure Modes and Resilience
 
-## 1) Disponibilità dell'account/fornitore
+## 1) Account/Provider Availability
 
-- Tempo di recupero dell'account del provider in caso di errori temporanei/velocità/autenticazione
-- fallback dell'account prima di fallire la richiesta
-- fallback del modello combinato quando il percorso del modello/provider corrente è esaurito
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-## 2) Scadenza del token
+## 2) Token Expiry
 
-- controllo preliminare e aggiornamento con nuovo tentativo per i provider aggiornabili
-- Nuovo tentativo 401/403 dopo il tentativo di aggiornamento nel percorso principale
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-## 3) Sicurezza dello streaming
+## 3) Stream Safety
 
-- controller di flusso in grado di riconoscere la disconnessione
-- flusso di traduzione con scarico di fine flusso e gestione `[DONE]`
-- fallback della stima dell'utilizzo quando mancano i metadati di utilizzo del provider
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-## 4) Degrado della sincronizzazione cloud
+## 4) Cloud Sync Degradation
 
-- Sono emersi errori di sincronizzazione ma il runtime locale continua
-- Lo scheduler ha una logica che consente di riprovare, ma l'esecuzione periodica attualmente chiama la sincronizzazione a tentativo singolo per impostazione predefinita
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-## 5) Integrità dei dati
+## 5) Data Integrity
 
-- Migrazione/riparazione della forma DB per chiavi mancanti
-- protezioni di reimpostazione JSON corrotte per localDb e UsageDb
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-## Osservabilità e segnali operativi
+## Observability and Operational Signals
 
-Origini della visibilità in runtime:
+Runtime visibility sources:
 
-- registri della console da `src/sse/utils/logger.ts`
-- aggregati di utilizzo per richiesta in `usage.json`
-- accesso testuale sullo stato della richiesta `log.txt`
-- log di richiesta/traduzione approfonditi opzionali in `logs/` quando `ENABLE_REQUEST_LOGS=true`
-- Endpoint di utilizzo del dashboard (`/api/usage/*`) per il consumo dell'interfaccia utente
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- textual request status log in `log.txt` (optional/compat)
+- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true`
+- dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
-## Confini sensibili alla sicurezza
+## Security-Sensitive Boundaries
 
-- Il segreto JWT (`JWT_SECRET`) protegge la verifica/firma dei cookie della sessione del dashboard
-- Il fallback della password iniziale (`INITIAL_PASSWORD`, predefinito `123456`) deve essere sovrascritto nelle distribuzioni reali
-- Il segreto HMAC della chiave API (`API_KEY_SECRET`) protegge il formato della chiave API locale generata
-- I segreti del provider (chiavi/token API) vengono mantenuti nel DB locale e devono essere protetti a livello di file system
-- Gli endpoint di sincronizzazione cloud si basano sull'autenticazione della chiave API e sulla semantica dell'ID macchina
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
+- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
+- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
+- Cloud sync endpoints rely on API key auth + machine id semantics
 
-## Matrice di ambiente e runtime
+## Environment and Runtime Matrix
 
-Variabili d'ambiente utilizzate attivamente dal codice:
+Environment variables actively used by code:
 
-- App/autenticazione: `JWT_SECRET`, `INITIAL_PASSWORD`
-- Spazio di archiviazione: `DATA_DIR`
-- Comportamento del nodo compatibile: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Override opzionale della base di archiviazione (Linux/macOS quando `DATA_DIR` non impostato): `XDG_CONFIG_HOME`
-- Hashing di sicurezza: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Registrazione: `ENABLE_REQUEST_LOGS`
-- URL di sincronizzazione/cloud: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-- Proxy in uscita: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` e varianti minuscole
-- Flag funzionalità SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Supporti piattaforma/runtime (non configurazione specifica dell'app): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
+- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Logging: `ENABLE_REQUEST_LOGS`
+- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
+- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants
+- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
 
-## Note architettoniche conosciute
+## Known Architectural Notes
 
-1. `usageDb` e `localDb` ora condividono la stessa policy di directory di base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) con la migrazione dei file legacy.
-2. `/api/v1/route.ts` restituisce un elenco di modelli statici e non è la fonte principale dei modelli utilizzata da `/v1/models`.
-3. Il registro delle richieste scrive intestazioni/corpo completi quando abilitato; considera la directory dei log come sensibile.
-4. Il comportamento del cloud dipende dalla corretta `NEXT_PUBLIC_BASE_URL` e dalla raggiungibilità dell'endpoint cloud.
-5. La directory `open-sse/` viene pubblicata come `@omniroute/open-sse` **pacchetto area di lavoro npm**. Il codice sorgente lo importa tramite `@omniroute/open-sse/...` (risolto da Next.js `transpilePackages`). I percorsi dei file in questo documento utilizzano ancora il nome della directory `open-sse/` per coerenza.
-6. I grafici nel dashboard utilizzano **Recharts** (basati su SVG) per visualizzazioni analitiche accessibili e interattive (grafici a barre sull'utilizzo del modello, tabelle di suddivisione dei fornitori con percentuali di successo).
-7. I test E2E utilizzano **Playwright** (`tests/e2e/`), eseguiti tramite `npm run test:e2e`. I test unitari utilizzano **Node.js test runner** (`tests/unit/`), eseguiti tramite `npm run test:plan3`. Il codice sorgente in `src/` è **TypeScript** (`.ts`/`.tsx`); l'area di lavoro `open-sse/` rimane JavaScript (`.js`).
-8. La pagina Impostazioni è organizzata in 5 schede: Sicurezza, Routing (6 strategie globali: riempimento prima, round robin, p2c, casuale, meno utilizzato, ottimizzato in termini di costi), Resilienza (limiti di velocità modificabili, interruttore automatico, policy), AI (budget pensato, prompt di sistema, cache dei prompt), Avanzate (proxy).
+1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
+2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
+3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
+4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
+5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
+6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
+7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
+8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
 
-## Lista di controllo per la verifica operativa
+## Operational Verification Checklist
 
-- Costruisci dalla fonte: `npm run build`
-- Crea immagine Docker: `docker build -t omniroute .`
-- Avviare il servizio e verificare:
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`
-- L'URL di base di destinazione della CLI deve essere `http://<host>:20128/v1` quando `PORT=20128`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`