docs: documenta i contratti di inspect paths e schema-diff

README.md

@@ -221,6 +221,70 @@ Per il percorso base:
 - `inspect schema-diff` confronta i principali segnali di schema RAW tra gli anni configurati
 - `--dry-run` valida config e SQL senza eseguire la pipeline
 
+### `inspect paths` vs `inspect schema-diff`
+
+I due comandi sono entrambi read-only, ma hanno scopi diversi:
+
+- `inspect paths`: helper operativo per notebook, script locali e CI
+- `inspect schema-diff`: helper diagnostico per capire drift e incoerenze del RAW tra anni
+
+Usa `inspect paths` quando ti serve sapere:
+
+- dove il toolkit scrive RAW, CLEAN, MART e run records per un dataset/anno
+- qual e' il `root` effettivo risolto dalla config
+- se esiste gia` un `latest_run`
+- quali hint RAW sono disponibili (`encoding`, `delim`, `decimal`, `skip`, `suggested_read_path`, `suggested_read_exists`)
+
+Usa `inspect schema-diff` quando ti serve sapere:
+
+- se il RAW cambia tra anni in numero o nomi colonne
+- se i profile hints cambiano tra anni
+- se ci sono warning di sniffing o drift da esplicitare prima del `clean`
+
+Contratto operativo minimo:
+
+- input comune: `--config dataset.yml`
+- `inspect paths` puo` essere scoped su un singolo anno con `--year`
+- `inspect schema-diff` lavora sugli anni configurati nel dataset
+- nessuno dei due modifica artefatti o lancia layer della pipeline
+
+`--json` e' il formato raccomandato quando il chiamante e':
+
+- CI
+- notebook che vogliono evitare path logic duplicata
+- script locali che leggono programmaticamente il payload
+
+Output garantito di `inspect paths`:
+
+- `dataset`, `year`, `config_path`, `root`
+- blocco `paths` con:
+  - `raw.dir|manifest|metadata|validation`
+  - `clean.dir|output|manifest|metadata|validation`
+  - `mart.dir|outputs|manifest|metadata|validation`
+  - `run_dir`
+- blocco `raw_hints` con:
+  - `primary_output_file`
+  - `suggested_read_path`
+  - `suggested_read_exists`
+  - `encoding`
+  - `delim`
+  - `decimal`
+  - `skip`
+  - `warnings`
+- blocco `latest_run` se esiste, altrimenti `null`
+
+Output garantito di `inspect schema-diff`:
+
+- `dataset`, `config_path`, `years`
+- `entries` con i principali segnali RAW per anno
+- `comparisons` tra anni consecutivi
+
+Regola pratica:
+
+- CI e effective root: `inspect paths --json`
+- onboarding notebook o script repo dataset: `inspect paths --json`
+- debug schema drift su fonti multi-anno: `inspect schema-diff --json`
+
 Esempi:
 
 ```bash
@@ -257,6 +321,12 @@ Helper ufficiale per evitare path logic duplicata nei notebook:
 toolkit inspect paths --config dataset.yml --year 2024 --json
 ```
 
+`inspect schema-diff` non sostituisce `inspect paths`:
+
+- non nasce per trovare i path runtime
+- nasce per confrontare hints e colonne RAW tra anni configurati
+- ha senso quando stai definendo `clean.read`, validando una fonte instabile o spiegando un drift nella nota metodologica del dataset
+
 Ruoli stabili degli output:
 
 - `metadata.json`: payload ricco del layer

docs/notebook-contract.md

@@ -32,6 +32,59 @@ Nota pratica:
 
 - `inspect paths` restituisce path assoluti della macchina locale: e' pensato per notebook e script nello stesso ambiente, non come formato portabile tra macchine diverse.
 
+## Contratto operativo di `inspect paths`
+
+`inspect paths` e' il comando da usare quando il problema e':
+
+- trovare i path runtime gia` risolti dal toolkit
+- evitare di ricostruire a mano `root/data/...`
+- leggere l'ultimo run disponibile per un anno
+- recuperare i principali hint RAW senza aprire a mano i metadata
+
+Input minimo:
+
+- `--config dataset.yml`
+- opzionale `--year` per restringere il payload a un solo anno
+
+Output garantito in `--json`:
+
+- `dataset`, `year`, `config_path`, `root`
+- `paths.raw` con `dir`, `manifest`, `metadata`, `validation`
+- `paths.clean` con `dir`, `output`, `manifest`, `metadata`, `validation`
+- `paths.mart` con `dir`, `outputs`, `manifest`, `metadata`, `validation`
+- `paths.run_dir`
+- `raw_hints` con:
+  - `primary_output_file`
+  - `suggested_read_path`
+  - `suggested_read_exists`
+  - `encoding`
+  - `delim`
+  - `decimal`
+  - `skip`
+  - `warnings`
+- `latest_run`
+
+Regola pratica:
+
+- notebook e script locali: usa sempre `inspect paths --json`
+- CI che deve validare `effective_root` o path contract: usa `inspect paths --json`
+- se non passi `--year`, il payload puo` essere una lista multi-anno
+
+## Differenza rispetto a `inspect schema-diff`
+
+`inspect schema-diff` non e' un helper per notebook.
+
+Serve invece quando vuoi:
+
+- confrontare schema e hints RAW tra anni configurati
+- capire se una fonte multi-anno ha drift di colonne o profile hints
+- decidere se `clean.read` o una nota metodologica devono esplicitare un caveat
+
+In breve:
+
+- `inspect paths`: "dove sono gli artefatti e quale runtime path contract posso usare?"
+- `inspect schema-diff`: "il RAW cambia tra anni e quanto cambia?"
+
 Regola pratica:
 
 - il toolkit produce