readme

README.md

@@ -152,16 +152,22 @@ Exit code:
 - `1` — cel puțin un FAIL
 - `2` — input invalid/lipsă
 
-### Workflow de corectare iterativă (când apare o alertă greșită live)
+### Două corpus-uri, două scopuri
 
-Scenariu: ai rulat o sesiune live, ai văzut pe chart o culoare pe care bot-ul n-a detectat-o (sau a detectat greșit).
+| Corpus | Unde se salvează | Cum se populează | Folosit de |
+|---|---|---|---|
+| `samples/` | frame complet la fiecare **schimbare de culoare** detectată | automat de `atm run` | `atm label` + `atm dryrun` |
+| `logs/fires/` | screenshot adnotat la fiecare alertă BUY/SELL, `/ss` manual, **interval automat `/3`** | manual sau scheduler | `atm validate-calibration` |
 
-1. **În timpul sesiunii**, când observi o culoare nouă pe chart, trimite `/ss` în Telegram. Asta salvează un screenshot în `logs/fires/` cu timestamp.
+**Flow A — calibrare fină cu screenshots automate (`/3`)**
-2. **După sesiune**, deschizi `samples/calibration_labels.json` și adaugi o intrare nouă pentru fiecare screenshot relevant:
+
+Util când vrei să acumulezi repede frame-uri din culori reale, fără să aștepți schimbări de culoare.
+
+1. **În sesiunea live**, trimite `/3` în Telegram → bot-ul face screenshot automat la 3 minute și îl salvează în `logs/fires/*_ss.png`. Oprești cu `/stop`.
+2. **După sesiune**, adaugi intrări în `samples/calibration_labels.json` pentru fiecare screenshot relevant, cu culoarea pe care ai văzut-o TU pe chart:
    ```json
    {"path": "logs/fires/20260420_151234_ss.png", "expected": "dark_green", "note": "văzut live, ratat de bot"}
    ```
-   Câmpul `expected` = culoarea pe care TU ai văzut-o pe chart (nu ce a zis bot-ul).
 3. **Rulează validarea:**
    ```bash
    atm validate-calibration samples/calibration_labels.json
@@ -173,6 +179,27 @@ Scenariu: ai rulat o sesiune live, ai văzut pe chart o culoare pe care bot-ul n
      - **Fix complet:** la următoarea sesiune live completă, rulezi `atm calibrate` de la zero pe Windows, cu **disciplina cele 3 reguli critice de mai sus** (rightmost dot, pixel static pentru canary, în timpul unei sesiuni active).
 5. **Acumulezi mai multe samples în timp.** Obiectiv: 2-3 intrări per culoare în `calibration_labels.json`. Cu cât fișierul are mai multe etichete, cu atât calibrarea următoare e validată mai solid.
 
+**Flow B — gate de precizie pe corpus de schimbări de culoare**
+
+`atm run` salvează automat în `samples/` un frame complet la fiecare schimbare de culoare detectată. După sesiune:
+
+```powershell
+atm label samples     # UI Tk — etichetezi fiecare frame cu culoarea reală văzută pe chart
+atm dryrun samples    # replay prin detector + FSM; exit 0 dacă precision=100%, recall≥95%
+```
+
+Dacă gate-ul pică, ajustezi `tolerance` per culoare în TOML sau corectezi eșantioanele nepotrivite, apoi rulezi iar `atm dryrun` până trece.
+
+### Workflow de corectare iterativă (când apare o alertă greșită live)
+
+Scenariu: ai rulat o sesiune live, ai văzut pe chart o culoare pe care bot-ul n-a detectat-o (sau a detectat greșit).
+
+1. **În timpul sesiunii** — două opțiuni pentru a captura dovezi:
+   - `/ss` în Telegram → un screenshot instant în `logs/fires/`
+   - `/3` în Telegram → screenshots automate la 3 min în `logs/fires/` (util dacă nu ești la monitor continuu); oprești cu `/stop`
+2. **După sesiune**, adaugi intrările relevante în `samples/calibration_labels.json` cu culoarea corectă și rulezi `atm validate-calibration` (Flow A de mai sus).
+3. Dacă apar FAIL-uri, aplici fix tactic în TOML sau recalibrezi complet.
+
 ### Exemplu real — incidentul 2026-04-17
 
 La 20:53 s-a afișat un dark_red pe chart dar bot-ul l-a citit ca light_red (alertă ratată). Root cause: calibrarea anterioară (`2026-04-16-0703.toml`) a fost făcută dând click pe dot-uri istorice (mai întunecate), nu pe dot-ul activ din dreapta.
@@ -286,6 +313,8 @@ atm dryrun samples    # replay prin detector + FSM; exit 0 dacă precision=100%,
 
 Dacă gate-ul pică, ajustezi `tolerance` per culoare în `configs/<current>.toml`, sau recalibrezi eșantioanele care n-au potrivit. Rulezi iar `atm dryrun` până trece. **Numai atunci ai încredere în semnalele live.**
 
+Pentru calibrare fină a clasificării de culori (Flow A cu `/3`), vezi secțiunea **Validare offline a calibrării** de mai sus.
+
 Evidență trade-uri:
 
 ```powershell