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

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

genera.py

@@ -5,6 +5,7 @@
 """Genera un CSV con T e ΔT = T − T_amb con rumore realistico (vedi docs/SPEC.md)."""
 
 import argparse
+import re
 import secrets
 import sys
 import tomllib
@@ -15,6 +16,56 @@ import numpy as np
 CARTELLA_OUTPUT = Path("output")
 GRIGLIA_MS = 5.0  # passo della griglia fine per il filtro del sensore
 
+DESCRIZIONE = """\
+Genera un CSV con la temperatura T di un sensore IR e la differenza dT = T - T_amb,
+con rumore, quantizzazione e jitter dei tempi simili a un sensore reale.
+
+T parte dalla temperatura ambiente, sale con uno o più gradini di riscaldamento e
+ridiscende con raffreddamento esponenziale fino a T_amb. Ogni corsa (seed) è diversa."""
+
+EPILOGO = """\
+esempi:
+  genera.py config.toml                    scrive output/gen_<seed>.csv, seed casuale
+  genera.py config.toml --seed 42          riproducibile: output/gen_42.csv
+  genera.py config.toml -o dati/prova.csv  percorso a scelta
+  genera.py config.toml -o - > out.csv     su stdout
+
+formato dell'output (separatore ',', fine riga '\\n'):
+  t_ms,T_C,dT_C
+  151,22.90,0.20
+  t_ms è intero; T_C e dT_C hanno due decimali. dT è calcolato dopo rumore e
+  quantizzazione di entrambi i canali (T e ambiente).
+
+cosa fa (in ordine):
+  1. tempi         t_i = t_(i-1) + dt_ms +/- jitter_ms, fino a durata_s
+  2. T vera        ambiente vero + gradini di riscaldamento con raffreddamento
+                   esponenziale, perturbati a caso a ogni corsa + disturbi a salto
+  3. sensore       filtro del 1° ordine (tau_sensore_s) su griglia fine da 5 ms
+  4. rumore di T   bianco (più forte a caldo) + deriva lenta, poi quantizzazione
+  5. ambiente, dT  ambiente con rumore e quantizzazione propri; dT = T - ambiente
+
+gruppi di chiavi di config.toml (unica fonte dei valori, unità nel suffisso:
+_s secondi, _ms millisecondi, _c gradi C, _hz 1/s; ogni chiave è obbligatoria):
+  tempi            durata_s, dt_ms, jitter_ms
+  ambiente         amb_inf_c, amb_A_c, amb_tau_s, amb_sigma_c, amb_passo_c
+  rumore di T      sigma_c, sigma_caldo_c, x_rif_c, wander_sigma_c, wander_tau_s, passo_T_c
+  gradini          t_impulsi_s, dT_impulsi_c ([] = nessun riscaldamento; stessa lunghezza),
+                   k_raffreddamento_hz, tau_sensore_s
+  variabilità      impulsi_jitter_t_s, impulsi_jitter_amp_rel, k_jitter_rel (0 = disattivata)
+  salti            salti_rate_hz, salti_media_c, salti_sigma_c, salti_tau_s, salti_x_min_c,
+                   salti_max_c (raffreddamento); salti_risc_rate_hz, salti_risc_media_c,
+                   salti_risc_sigma_c, salti_risc_tau_s (riscaldamento)
+
+codici di uscita:
+  0  ok
+  1  errore, con messaggio in italiano su stderr: file di configurazione illeggibile
+     o TOML non valido, chiave mancante, t_impulsi_s e dT_impulsi_c di lunghezza
+     diversa, file di uscita non scrivibile
+  2  argomenti della riga di comando non validi
+
+altri strumenti: grafico.py (disegna un CSV), pulisci.sh (svuota output/).
+documentazione: docs/SPEC.md (modello e controlli), docs/FUNZIONALITA.md (funzionalità)."""
+
 CHIAVI = [
     "durata_s", "dt_ms", "jitter_ms",
     "amb_inf_c", "amb_A_c", "amb_tau_s", "amb_sigma_c", "amb_passo_c",
@@ -26,6 +77,24 @@ CHIAVI = [
 ]
 
 
+class ParserIt(argparse.ArgumentParser):
+    """ArgumentParser con i messaggi d'errore più comuni in italiano (exit 2)."""
+
+    TRADUZIONI = [
+        (r"the following arguments are required: (.*)", r"manca l'argomento obbligatorio: \1"),
+        (r"unrecognized arguments: (.*)", r"argomenti non riconosciuti: \1"),
+        (r"argument (.*): invalid int value: (.*)", r"argomento \1: \2 non è un numero intero"),
+        (r"argument (.*): expected one argument", r"argomento \1: manca il valore"),
+    ]
+
+    def error(self, message):
+        for pattern, sostituzione in self.TRADUZIONI:
+            message = re.sub(pattern, sostituzione, message)
+        self.print_usage(sys.stderr)
+        print(f"{self.prog}: errore: {message}", file=sys.stderr)
+        sys.exit(2)
+
+
 def errore(msg):
     print(f"Errore: {msg}", file=sys.stderr)
     sys.exit(1)
@@ -149,10 +218,28 @@ def scrivi(f, t_ms, T, dT):
 
 
 def main():
-    ap = argparse.ArgumentParser(description="Genera un CSV con T e ΔT con rumore realistico.")
-    ap.add_argument("config", help="file di configurazione TOML")
-    ap.add_argument("-o", "--output", help="file CSV di uscita ('-' = stdout; default: output/gen_<seed>.csv)")
-    ap.add_argument("--seed", type=int, help="seme del generatore (default: casuale, stampato su stderr)")
+    ap = ParserIt(
+        prog="genera.py",
+        usage="genera.py [-h] [-o FILE] [--seed N] config",
+        description=DESCRIZIONE,
+        epilog=EPILOGO,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        add_help=False,
+    )
+    argomenti = ap.add_argument_group("argomenti")
+    opzioni = ap.add_argument_group("opzioni")
+    opzioni.add_argument("-h", "--help", action="help", help="mostra questo aiuto ed esce")
+    argomenti.add_argument("config", help="file di configurazione TOML (es. config.toml); tutte le chiavi sono obbligatorie")
+    opzioni.add_argument(
+        "-o", "--output", metavar="FILE",
+        help="file CSV di uscita; le cartelle mancanti vengono create. '-' scrive su stdout. "
+             "Default: output/gen_<seed>.csv",
+    )
+    opzioni.add_argument(
+        "--seed", type=int, metavar="N",
+        help="seme del generatore casuale: stesso seed e stessa configurazione danno lo stesso file. "
+             "Default: casuale, stampato su stderr",
+    )
     args = ap.parse_args()
 
     cfg = leggi_config(args.config)