docs(portfolio): documenta cartella portfolios, comandi, scope live e default PORT06

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -34,8 +34,15 @@ src/live/              → paper trading live multi-strategia
   cerbero_client.py    → client HTTP per Cerbero MCP (Deribit testnet)
   signal_engine.py     → squeeze + ML real-time (legacy ML01, ora in waste) + validazione OOS
   telegram_notifier.py → notifiche Telegram per trade
+src/portfolio/         → portafogli di prima classe (capitale-pool, backtest+live)
+  base.py              → SleeveSpec, Portfolio (.backtest), load_active_portfolio
+  weighting.py         → schemi pesi: equal/cap/inverse_vol/cluster_rp/manual
+  sleeves.py           → builder unificato equity-per-sleeve (fonte unica, parità report)
+  ledger.py            → PortfolioLedger: capitale/PnL/DD/persistenza+resume
+  runner.py            → PortfolioRunner live (data Cerbero v2, sizing, ribilancio)
 scripts/strategies/    → strategie con edge validato OOS: FADE (MR01/MR02/MR07),
                          HONEST (DIP01/TR01/ROT02), PAIRS (PR01), TSMOM + portafogli (PORT01/02/03)
+scripts/portfolios/    → definizioni PORT01-06 + report run()
 scripts/waste/         → strategie scartate (W01-W28 + famiglia squeeze SQ/MT/ML/AD/CM/PD)
 scripts/analysis/      → ricerca/validazione OOS fee-aware (strategy_research, oos_validation, ...)
 strategies.yml         → config multi-strategy paper trader
@@ -56,6 +63,9 @@ uv run python scripts/analysis/oos_validation.py               # perche' la fami
 uv run python scripts/analysis/report_families.py             # report per anno di tutte le famiglie
 uv run python scripts/analysis/validate_worker_pairs.py        # replay worker 2 gambe == backtest
 uv run python -m src.live.multi_runner                # paper trading live multi-strategia (strategie + pairs)
+uv run python scripts/portfolios/PORT06_master_shape.py   # report backtest portafoglio (default)
+uv run python -m src.portfolio.runner                      # paper trading a PORTAFOGLIO (capitale pool)
+uv run python scripts/analysis/smoke_portfolio.py          # smoke live data layer Cerbero v2
 docker compose up -d                                  # deploy Docker
 uv run pytest                                         # test
 ```
@@ -217,6 +227,15 @@ ma quei numeri sono backtest a leva 3x su 8 anni e includono anni eccezionali (e
 ETH 2024). Stima onesta: il target è *plausibile* su un portafoglio diversificato di
 queste fade, ma va confermato col paper trader live prima di rischiare capitale reale.
 
+## Portafogli
+
+- Un `Portfolio` è un oggetto di prima classe (`src/portfolio/`) con definizione (sleeve + schema pesi) e due facce sulla **STESSA** definizione: `.backtest()` (riusa il builder unico di `sleeves.py` → parità esatta con `report_families`) e live (`PortfolioRunner`: capitale pool condiviso, sizing per peso, ribilancio giornaliero, ledger aggregato in `data/portfolios/{code}/`).
+- **Schemi peso:** `equal` (default), `cap` (tetto per famiglia, es. pairs 33% — config raccomandata), `inverse_vol`, `cluster_rp` (equal fra cluster naturali poi inverse-vol intra-cluster), `manual`. Definiti in `weighting.py`; la chiave cap è la famiglia (PAIRS/FADE/HONEST/SHAPE/TSM).
+- **Default `portfolios.yml`:** PORT06 (master+shape), `weighting=cap pairs 0.33`, leva 2x, ribilancio 1D. Backtest PORT06: FULL Sharpe 6.07 / OOS Sharpe 8.19, DD 4.9% full / 2.3% OOS.
+- **Data layer Cerbero v2:** `get_historical_v2` unificato + `get_instruments` (naming robusto) + `get_ticker_batch`. Trading su Deribit.
+- **SCOPE LIVE v1:** il runner esegue gli sleeve con worker pronti = fade (MR01/02/07) + pairs (PR01) + shape (SH01, via `MLWorkerWrapper` con retraining). Gli sleeve **honest (DIP01/TR01/ROT02) e TSM01 sono SALTATI nel live** (nessun worker dedicato ancora) → restano solo nel backtest; il runner li logga come saltati e rinormalizza i pesi sugli sleeve eseguibili. Worker honest/TSM01 = fase 2.
+- **Limite noto:** al ribilancio le posizioni APERTE restano sul loro notional (non travasate); comportamento fedele al backtest daily-rebalanced entro il turnover infragiornaliero.
+
 ## Multi-Strategy Paper Trader
 
 Orchestratore che esegue N strategie in parallelo su dati live Cerbero, ognuna con €1000 USDC virtuali indipendenti.