docs: README + DEPLOYMENT con stato CI/CD funzionante

README aggiunge sezione 'CI/CD pipeline' che descrive i 5 job e i tag
image. DEPLOYMENT espande sez. 1 con dettagli runner Gitea (network
gitea_gitea-internal, image runner-images, label ubuntu-latest) e
configurazione secret user-level REGISTRY_TOKEN con scope write:package.

DEPLOYMENT.md

@@ -23,19 +23,44 @@ Watchtower per il rollover automatico delle versioni.
 
 ## 1. Pipeline CI/CD (Gitea Actions)
 
-`.gitea/workflows/ci.yml` ad ogni push su `main` esegue, in sequenza:
+`.gitea/workflows/ci.yml` ad ogni push su `main` esegue 5 job:
 
-1. **lint** (`ruff check`) — gating
+1. **lint** (`ruff check services/`) — gating, 0 violations.
-2. **typecheck** (`mypy mcp_common`) — gating su mcp_common, warn-only sui servizi
+2. **typecheck** (`mypy services/common/src/mcp_common`) — gating sul
-3. **test** (`pytest services/`) — gating, 455 test
+   modulo comune, warn-only sui servizi.
-4. **build-and-push** — solo su push a `main`:
+3. **test** (`pytest services/`) — gating, 478 test verdi.
-   - Logga al registry `git.tielogic.xyz` con `secrets.GITEA_TOKEN`
+4. **validate-config** — `docker compose config -q` su `docker-compose.yml`
-   - Builda `docker/base.Dockerfile` (cache)
+   e `docker-compose.prod.yml` + `caddy validate --config Caddyfile`.
-   - Builda e pusha `gateway` + 6 servizi MCP con tag:
+5. **build-and-push** — solo su push a `main` (skip su PR):
-     - `:latest` (mobile, Watchtower polla questo)
+   - `docker login git.tielogic.xyz` con `${{ secrets.REGISTRY_TOKEN }}`
-     - `:sha-XXXXXXX` (immutabile, per rollback puntuali)
+     (PAT scope `write:package`, configurato user-level su Gitea).
+   - Builda e pusha **8 image** al registry con tag `:latest` + `:sha-X`:
+     - `git.tielogic.xyz/adriano/cerbero-mcp/base`
+     - `git.tielogic.xyz/adriano/cerbero-mcp/gateway`
+     - `git.tielogic.xyz/adriano/cerbero-mcp/mcp-{deribit,bybit,hyperliquid,alpaca,macro,sentiment}`
+   - Cache Docker buildx via registry stesso (`buildcache:<name>` per ognuna)
+     → run successivi 5-10× più veloci.
 
-Le PR fanno girare solo lint+typecheck+test, niente build/push.
+Le PR fanno girare solo `lint`+`typecheck`+`test`+`validate-config`,
+niente build/push (gating per merge).
+
+### Setup runner Gitea
+
+Il runner act_runner deve girare:
+- Sulla stessa Docker network di Gitea (`gitea_gitea-internal` o equivalente)
+  altrimenti `actions/checkout@v4` non risolve `gitea:3000` per il clone.
+- Con bind di `/var/run/docker.sock` per buildare image dai workflow.
+- Image dei job mappata a `docker.gitea.com/runner-images:ubuntu-22.04`
+  (default Gitea, contiene docker CLI + buildx + git + curl + node).
+- Label: almeno `ubuntu-latest` (usato dal workflow). Altre label
+  (`tielogic-ci`, `ubuntu-22.04`, ecc.) opzionali.
+
+### Setup secret REGISTRY_TOKEN
+
+Crea un Personal Access Token Gitea con scope `write:package` (User
+Settings → Applications → Generate Token). Aggiungilo come secret a
+livello user (User Settings → Secrets → New Secret) con nome
+`REGISTRY_TOKEN`. Tutti i tuoi repo ereditano il secret automaticamente.
 
 ## 2. Setup iniziale del VPS
 

README.md

@@ -53,7 +53,29 @@ OI history. **Nuovi**: `get_funding_arb_spread` (opportunità arb compatte),
 `get_liquidation_heatmap` (heuristic da OI delta + funding extreme),
 `get_cointegration_pairs` (Engle-Granger su coppie crypto).
 
-## Avvio locale
+## CI/CD pipeline
+
+Pipeline Gitea Actions in `.gitea/workflows/ci.yml` esegue ad ogni push
+su `main`:
+
+1. **lint** — `ruff check services/`
+2. **typecheck** — `mypy mcp_common` (gating) + servizi (warn-only)
+3. **test** — `pytest services/` (478 test)
+4. **validate-config** — sintassi compose + Caddyfile
+5. **build-and-push** — solo su `main`: builda e pusha 8 image al
+   container registry Gitea (`git.tielogic.xyz/adriano/cerbero-mcp/*`)
+   con tag `:latest` + `:sha-XXXXXXX` per rollback puntuali.
+
+Le PR fanno girare solo i 4 job di gating (lint/test/validate). Il job
+`build-and-push` è skippato.
+
+Sul VPS produzione, **Watchtower** polla il registry ogni 5 min e
+auto-aggiorna i container quando il digest del tag `:latest` cambia.
+
+Vedi [`DEPLOYMENT.md`](DEPLOYMENT.md) per setup runner, secret
+`REGISTRY_TOKEN`, deploy VPS, smoke test, rollback.
+
+## Avvio locale (dev)
 
 ```bash
 docker compose up -d
@@ -67,11 +89,7 @@ Vedi `secrets/*.json` e variabili `*_TESTNET` / `ALPACA_PAPER` in
 
 ### Deploy su VPS pubblica (`cerbero-mcp.tielogic.xyz`)
 
-Vedi [`DEPLOYMENT.md`](DEPLOYMENT.md) per la guida completa: pipeline CI/CD
+Vedi [`DEPLOYMENT.md`](DEPLOYMENT.md) per il runbook completo end-to-end.
-(Gitea Actions → registry → Watchtower auto-update), setup VPS step-by-step,
-rollback, smoke test post-deploy.
-
-
 
 Il gateway Caddy è configurato per:
 - TLS automatico via Let's Encrypt (richiede DNS A/AAAA che punti al