From be4273622325781ce8ff09e3a7e086da91f64fa8 Mon Sep 17 00:00:00 2001
From: Harwinder <hssekhon93@hotmail.com>
Date: Thu, 7 May 2026 18:44:41 -0400
Subject: [PATCH] Document session filter and auto-toggle flags in USAGE

---
 USAGE.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/USAGE.md b/USAGE.md
index 8aa2b2b..8f25fc9 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -75,6 +75,11 @@ python main.py --backtest --journal                # Last 10 trades printed
 python main.py --backtest --journal-csv trades.csv # Full journal to CSV
 python main.py --backtest --regime-filter          # Skip choppy/ranging bars
 python main.py --backtest --regime-filter --regime-min-adx 35
+python main.py --backtest --session-filter         # Trade only 07-16 UTC
+python main.py --backtest --session-filter --session-start 8 --session-end 17
+python main.py --backtest --auto-session-filter    # Reactive session toggle
+python main.py --backtest --auto-session-filter --auto-session-lookback 15 \
+                          --auto-session-threshold-pct -0.5
 ```
 
 ### Regime filter
@@ -84,6 +89,30 @@ regimes and loses in chop. `--regime-filter` gates entries on H4 ADX:
 signals only fire when ADX ≥ `--regime-min-adx` (default 30). Sweet spot is
 ADX 30–35; tighter cuts trades faster than it improves quality.
 
+### Session filter
+
+`--session-filter` restricts entries to a UTC hour window (default 07-16,
+covering London + NY). Diagnostic on 2025-11 → 2026-05 showed 47% WR /
++127 pips inside that window vs 0% WR / -571 pips outside it. Override
+bounds with `--session-start` (inclusive) and `--session-end` (exclusive).
+
+Tradeoff: it's regime-specific medicine. In trending regimes (e.g. 2024)
+it cuts winning off-hours trades and gives back ~33% of the edge. Ships
+**default off** because the pure regime filter still wins cumulative
+across the 2024 / 2023 / 2026 windows.
+
+### Auto session toggle
+
+`--auto-session-filter` is a reactive variant: it tracks the rolling mean
+`pnl_pct` over the last N closed trades (`--auto-session-lookback`,
+default 10) and activates the 07-16 UTC window only when that mean drops
+below `--auto-session-threshold-pct` (default `-0.3`). Releases
+automatically once expectancy recovers.
+
+Less aggressive than the manual flag — preserves more trend edge but
+reacts slowly because the deque must fill with losses before kicking in.
+Use this when you don't want to manually toggle the regime medicine.
+
 ### Execution model
 
 | Aspect             | Behavior                                                          |