From 95b8bcfe966829f4ce9ebbcab8f7745a5f035e20 Mon Sep 17 00:00:00 2001
From: AdrianoDev <adrianodalpastro@tielogic.com>
Date: Fri, 1 May 2026 00:04:50 +0200
Subject: [PATCH] docs(V2): aggiorna README con override URL .env, layout src,
 quality gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Aggiunte caratteristiche: override URL upstream da DERIBIT_URL_*, BYBIT_URL_*, ecc.
- Aggiunto badge qualità: 259 test, mypy clean, ruff clean
- Aggiunta sezione layout src/cerbero_mcp/
- Documentate quirk SDK su override URL (Bybit pybit endpoint, Alpaca trading-only)
- Linkato anche il plan oltre alla spec

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 43 +++++++++++++++++++++++++++++++++++++------
 1 file changed, 37 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 8a1766e..80adfe6 100644
--- a/README.md
+++ b/README.md
@@ -15,8 +15,12 @@ sul token bearer fornito dal client.
   `Authorization: Bearer <TOKEN>`: lo stesso container serve entrambi gli
   ambienti senza riavvii
 - **Configurazione interamente in `.env`**: nessun file JSON di credenziali
-  separato
+  separato; le URL upstream (live/testnet) di ciascun exchange sono
+  override-abili tramite variabili dedicate (`DERIBIT_URL_*`,
+  `BYBIT_URL_*`, `HYPERLIQUID_URL_*`, `ALPACA_URL_*`)
 - **Documentazione interattiva** OpenAPI/Swagger esposta a `/apidocs`
+- **Qualità verificata**: 259 test (unit + integration + smoke), mypy
+  pulito, ruff pulito
 
 ## Avvio rapido (sviluppo, senza Docker)
 
@@ -156,12 +160,29 @@ PORT=9000 TESTNET_TOKEN="$TESTNET_TOKEN" bash tests/smoke/run.sh
 
 ```bash
 uv sync
-uv run pytest                   # tutta la suite
+uv run pytest                   # tutta la suite (259 test attesi)
 uv run pytest tests/unit -v     # solo unit
-uv run ruff check src/
+uv run pytest tests/integration -v
+uv run ruff check src/ tests/
 uv run mypy src/cerbero_mcp
 ```
 
+Tutti e quattro i comandi devono ritornare verde prima di committare.
+
+### Layout sorgenti
+
+```
+src/cerbero_mcp/
+├── __main__.py            # entrypoint cerbero-mcp
+├── settings.py            # Pydantic Settings (legge .env)
+├── auth.py                # middleware bearer → request.state.environment
+├── server.py              # build_app() + Swagger + middleware + handlers
+├── client_registry.py     # cache lazy {(exchange, env): client}
+├── routers/               # un file per exchange (deribit, bybit, ...)
+├── exchanges/             # logica per-exchange: client + tools
+└── common/                # indicators, options, microstructure, stats, ...
+```
+
 ## Migrazione da V1 (1.x → 2.0.0)
 
 Per chi è in produzione su V1:
@@ -193,10 +214,12 @@ formati incompatibili tra V1 e V2 — tenere backup separati.
 
 ## Architettura
 
-Spec di progettazione completa in
-[`docs/superpowers/specs/2026-04-30-V2.0.0-unified-image-token-routing-design.md`](docs/superpowers/specs/2026-04-30-V2.0.0-unified-image-token-routing-design.md).
+Spec di progettazione e plan di implementazione completi in:
 
-Riepilogo:
+- [`docs/superpowers/specs/2026-04-30-V2.0.0-unified-image-token-routing-design.md`](docs/superpowers/specs/2026-04-30-V2.0.0-unified-image-token-routing-design.md)
+- [`docs/superpowers/plans/2026-04-30-V2.0.0-unified-image-token-routing.md`](docs/superpowers/plans/2026-04-30-V2.0.0-unified-image-token-routing.md)
+
+Riepilogo del flusso runtime:
 
 ```
 Bot → Authorization: Bearer <TESTNET|MAINNET>_TOKEN
@@ -210,6 +233,14 @@ Bot → Authorization: Bearer <TESTNET|MAINNET>_TOKEN
    Tool function (logica pura) → exchange API
 ```
 
+### Override URL upstream
+
+L'override delle URL upstream da `.env` è completo per Deribit e
+Hyperliquid. Per Bybit funziona tramite l'attributo `endpoint` interno di
+pybit (workaround documentato nel client). Per Alpaca l'override è
+applicato al solo trading endpoint: gli endpoint dati
+(`data.alpaca.markets`) restano quelli predefiniti dell'SDK.
+
 ## Licenza
 
 Privato.