Aggiunge --help completo a genera.py, grafico.py e pulisci.sh; riscrive CLAUDE.md

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

CLAUDE.md

@@ -2,17 +2,34 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Stato
+Generatore di CSV `t_ms,T_C,dT_C` (temperatura di un sensore IR che si scalda e si raffredda, con rumore realistico). [docs/SPEC.md](docs/SPEC.md) è l'unica fonte di verità su output, modello, CLI, errori e controlli di accettazione: leggila per intero prima di cambiare il comportamento. Documentazione, commenti e messaggi di errore sono in italiano.
 
-[genera.py](genera.py) è lo script unico (`python genera.py config.toml --seed 42` nell'ambiente `.venv`, creato con `uv venv`; scrive in `output/`). [grafico.py](grafico.py) disegna un CSV di output (script separato, dipende da matplotlib; `genera.py` resta con solo numpy); `genera.py` implementa [docs/SPEC.md](docs/SPEC.md), unica fonte di verità su output, modello, CLI, errori e controlli di accettazione. Leggila per intero prima di scrivere codice. Documentazione, commenti e messaggi di errore sono in italiano.
+## Comandi
 
-## File
+Ambiente `.venv` nel progetto (numpy per `genera.py`, in più matplotlib per `grafico.py`):
 
-- [config.toml](config.toml): esempio e unica fonte dei valori numerici. Le unità sono nei suffissi delle chiavi (`_s`, `_ms`, `_c`, `_hz`).
+```bash
+uv venv .venv && uv pip install numpy matplotlib
+.venv/bin/python genera.py config.toml --seed 42    # scrive output/gen_42.csv
+.venv/bin/python grafico.py -o g.png                # grafico dell'ultimo CSV in output/
+./pulisci.sh                                        # svuota output/
+```
 
-## Vincoli facili da perdere
+`--help` di ogni script (testo in `DESCRIZIONE`/`EPILOGO` per `genera.py`) elenca le chiavi di `config.toml` per gruppo: va aggiornato insieme a `CHIAVI`.
+
+Non ci sono test automatici: la verifica è sui controlli di §5 di SPEC.md, su più seed (vedi gotcha).
+
+## Mappa del codice
+
+- [genera.py](genera.py), script unico: `leggi_config` (valida `CHIAVI`) → `genera` → `scrivi`. Dentro `genera`: `perturba` (variabilità per corsa di istanti, ampiezze e `k` dei gradini), `eccesso` (gradini + raffreddamento), `salti` / `eventi` (disturbi Poisson in riscaldamento e raffreddamento), poi filtro del sensore, rumore, quantizzazione.
+- [config.toml](config.toml): unica fonte dei valori numerici; unità nei suffissi (`_s`, `_ms`, `_c`, `_hz`).
+- [grafico.py](grafico.py): script separato, non importa `genera.py`.
+
+## Gotcha
 
 - `ΔT` = T − ambiente, calcolato **dopo** rumore e quantizzazione di entrambi i canali, mai dalla T vera.
-- Nessun valore numerico nello script: chiave mancante ⇒ exit 1.
-- Un solo `numpy.random.Generator` seminato da `--seed`, così stesso seed + stessa config ⇒ file identico.
-- Verifica l'implementazione con i controlli di §5 di SPEC.md sulla config d'esempio.
+- Nessun valore numerico nello script: ogni chiave nuova di `config.toml` va aggiunta anche a `CHIAVI` in `genera.py` (chiave mancante ⇒ exit 1) e descritta in SPEC.md e nell'epilogo di `--help`.
+- Un solo `numpy.random.Generator` seminato da `--seed`: stesso seed + stessa config ⇒ file identico. Cambiare numero o ordine delle estrazioni casuali cambia i file di ogni seed.
+- Tutto ciò che sembra "fisso" nelle curve (salti, picco, istanti) è casuale per seed: non esistono istanti programmati.
+- Gli intervalli di §5 di SPEC.md (picco, `T`/`ΔT` finali) sono empirici su ~40 seed: se cambi `config.toml` (gradini, durata, salti, k) ricalcolali e aggiornali.
+- `uv run genera.py` usa un ambiente a parte nella cache di uv, non `.venv`; i comandi del progetto sono quelli con `.venv/bin/python`.