feat: config auto-detect, run default, inspect unificato

CONTRIBUTING.md

@@ -66,13 +66,13 @@ mypy toolkit/
 
 ```bash
 # Run completo su dataset di esempio
-python -m toolkit.cli.app run all --config project-example/dataset.yml
+python -m toolkit.cli.app run --config project-example/dataset.yml
 
 # Validate
 python -m toolkit.cli.app validate all --config project-example/dataset.yml
 
-# Inspect paths
-python -m toolkit.cli.app inspect paths --config project-example/dataset.yml
+# Inspect (default: summary con path info)
+python -m toolkit.cli.app inspect --config project-example/dataset.yml
 
 # Profile RAW (canonico: inspect config)
 python -m toolkit.cli.app inspect config -c project-example/dataset.yml -l raw -m profile
@@ -85,7 +85,7 @@ critica per il rilascio:
 
 | Marker | Cosa copre | Deve sempre passare |
 |---|---|---|
-| `core` | Contratto pubblico e percorso canonico — config, path contract, `run all`, `validate all`, end-to-end RAW→CLEAN→MART, run records, resume | ✅ Sì |
+| `core` | Contratto pubblico e percorso canonico — config, path contract, `run`, `validate all`, end-to-end RAW→CLEAN→MART, run records, resume | ✅ Sì |
 | `advanced` | Comportamenti secondari — read modes, extractors, plugin registry, profiling, artifact policy | ✅ Su release |
 | `compat` | Solo compatibilità legacy e shim di import deprecati | No (può decadere) |
 

README.md

@@ -19,11 +19,11 @@ chiaro tra ogni layer.
 
 ```bash
 pip install -e .[dev]
-toolkit run full -c dataset.yml
-toolkit inspect summary -c dataset.yml
+toolkit run -c dataset.yml
+toolkit inspect -c dataset.yml
 ```
 
-Se `toolkit` non è nel PATH: `python -m toolkit.cli.app run all -c dataset.yml`
+Se `toolkit` non è nel PATH: `python -m toolkit.cli.app run -c dataset.yml`
 
 ## Pipeline: tre livelli
 
@@ -53,14 +53,19 @@ La CI di `dataset-incubator` carica su GCS dopo ogni run validato.
 ## CLI — comandi essenziali
 
 | Comando | Cosa fa |
-|---|---|
-| `toolkit run all --config dataset.yml` | Prima esecuzione completa |
-| `toolkit run clean --config dataset.yml` | Solo layer CLEAN |
-| `toolkit run mart --config dataset.yml` | Solo layer MART |
-| `toolkit inspect summary --config dataset.yml` | Stato ultimo run |
-| `toolkit inspect paths --config dataset.yml --year 2023` | Path assoluti degli output |
+|---|---|---|
+| `toolkit run` | Esecuzione completa RAW→CLEAN→MART |
+| `toolkit run raw` | Solo layer RAW |
+| `toolkit run clean` | Solo layer CLEAN |
+| `toolkit run mart` | Solo layer MART |
+| `toolkit inspect` | Stato ultimo run (riassunto) |
+| `toolkit inspect config --diff` | Schema-diff RAW tra anni |
+| `toolkit inspect runs --resume` | Riprendi run interrotto |
 | `toolkit scout <URL>` | Esplora fonte esterna (HTTP/CKAN/SDMX) |
 
+`--config` è opzionale: se omesso, toolkit cerca `dataset.yml` nella directory corrente.
+Se passi uno slug (es. `terna-electricity-by-source`), lo risolve nel workspace.
+
 📖 **Reference completo**: `toolkit --help`
 
 ## Configurazione (`dataset.yml`)
@@ -121,11 +126,11 @@ Config IDE (`.mcp.json`):
 ## FAQ — problemi comuni
 
 | Problema | Soluzione |
-|---|---|
+|---|---|---|
 | `toolkit: command not found` | Usa `python -m toolkit.cli.app` |
 | Run interrotto | `toolkit inspect runs --resume -c dataset.yml` |
 | Schema diverso tra anni | `toolkit inspect config -c dataset.yml --diff` |
-| Dove sono i parquet? | `toolkit inspect paths --config dataset.yml --year <anno>` |
+| Dove sono i parquet? | `toolkit inspect -c dataset.yml` (mostra path nel riassunto) |
 
 ## Sviluppo
 

docs/advanced-workflows.md

@@ -4,8 +4,8 @@ Questa nota raccoglie i flussi e le opzioni del toolkit che restano supportati,
 
 Percorso canonico:
 
-- `toolkit run full --config dataset.yml`
-- `toolkit inspect summary -c dataset.yml`
+- `toolkit run --config dataset.yml`
+- `toolkit inspect -c dataset.yml`
 - `toolkit inspect config -c dataset.yml`
 - notebook locali che leggono output e metadata sotto `root/data/...`
 
@@ -19,9 +19,9 @@ Questa categoria include anche tooling di supporto che non va confuso con il run
 
 Regola pratica:
 
-- se stai eseguendo un dataset per la prima volta, parti da `toolkit run all`
+- se stai eseguendo un dataset per la prima volta, parti da `toolkit run`
 - se hai cambiato fonte, anni, extractor, `dataset.yml` o il perimetro del RAW,
-  torna a `toolkit run all`
+  torna a `toolkit run`
 - se hai cambiato `clean.sql` o la logica `clean.read`, riparti da
   `toolkit run clean` e poi `toolkit run mart`
 - se hai toccato solo SQL `mart`, preferisci `toolkit run mart`
@@ -36,9 +36,9 @@ Matrice minima:
 
 | Tipo di modifica | Comando consigliato |
 |---|---|
-| prima esecuzione del dataset | `toolkit run all --config dataset.yml` |
-| cambio fonte o perimetro anni | `toolkit run all --config dataset.yml` |
-| cambio `dataset.yml` con impatto su input/layer | `toolkit run all --config dataset.yml` |
+| prima esecuzione del dataset | `toolkit run --config dataset.yml` |
+| cambio fonte o perimetro anni | `toolkit run --config dataset.yml` |
+| cambio `dataset.yml` con impatto su input/layer | `toolkit run --config dataset.yml` |
 | cambio `clean.sql` o `clean.read` | `toolkit run clean --config dataset.yml` poi `toolkit run mart --config dataset.yml` |
 | cambio solo `mart.sql` | `toolkit run mart --config dataset.yml` |
 | cambio solo tabella multi-anno | `toolkit run mart --config dataset.yml` |
@@ -52,7 +52,7 @@ il layer che stai rieseguendo.
 
 In pratica:
 
-- non trattare `run all` come default per ogni modifica minima
+- non trattare `run` come default per ogni modifica minima
 - non cancellare gli output locali "per pulizia" se non hai cambiato il loro perimetro
 - usa i rerun parziali quando il punto di ingresso corretto è chiaro
 - usa `resume` per recovery, non come scorciatoia generica a metà sviluppo

docs/feature-stability.md

@@ -6,14 +6,13 @@ Questa matrice serve a chiarire cosa il toolkit considera percorso canonico, cos
 |---|---|---|
 | `query` | stable | query SQL su parquet (path o dataset.yml + layer) |
 | `parquet_preview(sql=...)` | stable | API core per SQL arbitrario su parquet |
-| `run all` | stable | percorso canonico |
+| `run` | stable | percorso canonico |
 | `validate all` | stable | percorso canonico |
-| `inspect summary` | stable | percorso canonico |
+| `inspect` | stable | percorso canonico |
 | path contract di `dataset.yml` | stable | percorso canonico |
 | output `raw/clean/mart/_runs` | stable | percorso canonico |
-| `inspect paths` | stable | helper per notebook e repo dataset |
 | `inspect runs --resume` | supported / advanced | debug operativo e recovery |
-| `inspect profile` | supported / advanced | diagnostica su RAW sporchi o ambigui |
+| `inspect config --mode profile` | supported / advanced | diagnostica su RAW sporchi o ambigui |
 | `run raw\|clean\|mart` | supported / advanced | debug e re-run parziali |
 | `scout` | stable | esplorazione URL esterni, probe e routing automatico |
 | `scout --scaffold` | stable | probe + scaffold candidate dataset (dataset.yml, SQL, README) |
@@ -28,7 +27,7 @@ Questa matrice serve a chiarire cosa il toolkit considera percorso canonico, cos
 Lettura equivalente a livello package:
 
 - core runtime: `toolkit.raw`, `toolkit.clean`, `toolkit.mart`, `toolkit.scout`, `toolkit.cli` (`run`, `validate`, `inspect`)
-- advanced tooling: `inspect runs --resume`, run parziali, `inspect profile`, `inspect config --diff`
+- advanced tooling: `inspect runs --resume`, run parziali, `inspect config --mode profile`, `inspect config --diff`
 - compatibility only: config legacy e alias storici
 
 Sorgenti builtin supportate dal runtime canonico: `local_file`, `http_file`, `http_post_file`, `ckan`, `sdmx`, `sparql`. Il runtime può conservare `.xlsx` e `.xls` in RAW e leggerli in CLEAN — il file originale resta l'artefatto sorgente.

docs/notebook-contract.md

@@ -19,21 +19,21 @@ Ruoli dei file:
 
 - `metadata.json`: payload ricco del layer. Contiene input, output, `config_hash`, summary di validazione e campi specifici del layer.
 - run record in `data/_runs/...`: stato del run (`run_id`, layer, validations, status), utile per `status` e `resume`.
-- `inspect paths --json`: helper read-only per notebook e script locali; restituisce i path assoluti utili del runtime, incluso `latest_run`.
+- `inspect --json` (o `inspect --config dataset.yml --json`): helper read-only per notebook e script locali; restituisce i path assoluti utili del runtime, incluso `latest_run`.
 
 Per evitare duplicazione di path logic nei notebook:
 
 - leggi `dataset.yml`
-- usa `toolkit inspect paths --config dataset.yml --year <year> --json`
+- usa `toolkit inspect --json --config dataset.yml --year <year>`
 - poi apri parquet, metadata, manifest, validation e run record dai path restituiti
 
 Nota pratica:
 
-- `inspect paths` restituisce path assoluti della macchina locale: è pensato per notebook e script nello stesso ambiente, non come formato portabile tra macchine diverse.
+- `inspect --json` restituisce path assoluti della macchina locale: è pensato per notebook e script nello stesso ambiente, non come formato portabile tra macchine diverse.
 
-## Contratto operativo di `inspect paths`
+## Contratto operativo di `inspect --json`
 
-`inspect paths` è il comando da usare quando il problema è:
+`inspect --json` è il comando da usare quando il problema è:
 
 - trovare i path runtime già risolti dal toolkit
 - evitare di ricostruire a mano `root/data/...`
@@ -65,8 +65,8 @@ Output garantito in `--json`:
 
 Regola pratica:
 
-- notebook e script locali: usa sempre `inspect paths --json`
-- CI che deve validare `effective_root` o path contract: usa `inspect paths --json`
+- notebook e script locali: usa sempre `inspect --json`
+- CI che deve validare `effective_root` o path contract: usa `inspect --json`
 - se non passi `--year`, il payload può essere una lista multi-anno
 
 ## Differenza rispetto a `inspect config --diff`
@@ -81,7 +81,7 @@ Serve invece quando vuoi:
 
 In breve:
 
-- `inspect paths`: "dove sono gli artefatti e quale runtime path contract posso usare?"
+- `inspect --json`: "dove sono gli artefatti e quale runtime path contract posso usare?"
 - `inspect config --diff`: "il RAW cambia tra anni e quanto cambia?"
 
 Regola pratica:

scripts/smoke_install_cli.py

@@ -44,9 +44,9 @@ def main() -> int:
 
         _run([str(toolkit_cmd), "--help"], cwd=repo_root, env=env)
         _run([str(toolkit_cmd), "run", "--help"], cwd=repo_root, env=env)
-        _run([str(toolkit_cmd), "inspect", "profile", "--help"], cwd=repo_root, env=env)
+        _run([str(toolkit_cmd), "inspect", "--help"], cwd=repo_root, env=env)
         _run(
-            [str(toolkit_cmd), "run", "all", "--dry-run", "-c", "examples/dataset_min.yml"],
+            [str(toolkit_cmd), "run", "--dry-run", "-c", "examples/dataset_min.yml"],
             cwd=repo_root,
             env=env,
         )

tests/helpers.py

@@ -151,7 +151,12 @@ def make_dataset_yml(
         "dataset:",
         f'  name: "{name}"',
         f"  years: [{yml_years_str}]",
-        "raw: {}",
+        "raw:",
+        "  sources:",
+        "    - type: local_file",
+        "      args:",
+        '        path: "."',
+        '        filename: "dummy.csv"',
     ]
 
     if clean_sql is not None: