feat: batch reads CSV via DuckDB; bump v0.2.0

- DuckDB core dep: batch input via read_csv (delimiter autodetect from
  header, --decimal for comma, '-' = stdin), cells kept as raw strings
- library: export read_csv_file/resolve_column/rows_to_geojson
- README badges + IGM service link + default-format docs
- verto-explorer skill v1.1 + docs/skill install guide
- OpenSpec change batch-duckdb-csv archived

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aborruso

.gitignore

@@ -24,3 +24,6 @@ tmp.md
 # Caches
 .pytest_cache/
 .ruff_cache/
+
+# Reference material (e.g. third-party manuals, not for redistribution)
+ref/

LOG.md

@@ -1,5 +1,19 @@
 # LOG
 
+## 2026-06-08 — v0.2.0 — batch legge il CSV con DuckDB
+
+- `batch` ora legge il CSV di input via **DuckDB** (dipendenza core aggiunta): autodetect del delimitatore (`,`, `;`, tab, `|`) rilevato dalla **riga di header**, nuova opzione `--decimal` (`.` default, `,` per CSV italiani tipo `12,4924`), supporto **stdin** (`-`) e stdout (default senza `--out`).
+- Niente formati spaziali: l'idea iniziale (export GPKG/FGB/GeoParquet/SHP via estensione spatial) è stata abbandonata dopo una sonda empirica — driver `Parquet` assente, FGB riordina le feature, GeoParquet nativo tagga CRS84 invece dell'EPSG. Si usa DuckDB solo per I/O CSV robusto.
+- Bug risolto: con `decimal_separator=','` lo sniffer di DuckDB sceglie la virgola come delimitatore su righe tutte-numeriche → rilevo io il delimitatore dall'header escludendo la virgola, poi `read_csv` con `delim` esplicito.
+- Regressione risolta (lettura tipizzata riformattava le colonne attributo, es. `19.90`→`19.9`, `1000,50`→`1000.5`): ora `read_csv` con `all_varchar=true` tiene ogni cella come stringa grezza; la virgola→punto è normalizzata **solo** sulle colonne x/y dentro `batch`.
+- Allineamento libreria↔CLI: esportati `read_csv_file`, `resolve_column`, `rows_to_geojson` in `openverto/__init__.py` così il workflow di `batch` è riproducibile da `import openverto`.
+- README: badge (PyPI/GitHub/DeepWiki/MIT/Newsletter) stile opensdmx + link al servizio IGM Verto Online + sezione formato CSV di default.
+- Test: +6 offline (delimitatore `;`, celle grezze preservate, header numerico-regression, stdin, colonna mancante, alias). 22 passati, ruff pulito, wheel ok.
+- Skill `verto-explorer` aggiornata (v1.1) con la lettura DuckDB; nuova guida d'installazione skill `docs/skill/README.md` (stile opensdmx, `npx skills add ondata/openverto`), linkata dal README.
+- Manuale ufficiale IGM scaricato in `ref/` (PDF + markdown via `lit`).
+- Gestito con OpenSpec: change `batch-duckdb-csv` (ex `duckdb-spatial-export`, ridimensionata).
+- TODO: bump versione + eventuale release (dipendenza core nuova).
+
 ## 2026-06-08 — v0.1.1
 
 - Subrelease patch: aggiunta sezione `Examples:` nel docstring di **ogni** sottocomando CLI (`systems`, `convert`, `inspect`, `detect`, `targets`, `roundtrip`, `batch`, `geojson`, `cache`, `doctor`) — almeno un esempio utile per LLM, sul modello di `opensdmx`.

README.md

@@ -1,11 +1,19 @@
 # openverto
 
+[![PyPI version](https://img.shields.io/pypi/v/openverto)](https://pypi.org/project/openverto/)
+[![GitHub](https://img.shields.io/badge/github-ondata%2Fopenverto-blue?logo=github)](https://github.com/ondata/openverto)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ondata/openverto)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Newsletter](https://img.shields.io/badge/newsletter-ondata-FF6719?logo=substack)](https://ondata.substack.com/)
+
 > Tool sperimentale — aiutaci a testarlo [aprendo issue](https://github.com/ondata/openverto/issues) o inviando feedback.
 
-CLI e libreria Python per il servizio ufficiale **IGM Verto Online**: trasforma coordinate tra tutti i sistemi di riferimento italiani (Roma40, ED50, IGM95, ETRS89, RDN2008) **senza installare le griglie NTv2**, appoggiandosi al servizio autorevole dell'Istituto Geografico Militare.
+CLI e libreria Python per il servizio ufficiale **[IGM Verto Online](https://igmi.esercito.difesa.it/servizi/verto-online/)**: trasforma coordinate tra tutti i sistemi di riferimento italiani (Roma40, ED50, IGM95, ETRS89, RDN2008) **senza installare le griglie NTv2**, appoggiandosi al servizio autorevole dell'Istituto Geografico Militare.
 
 Pensato per essere **orchestrato da agenti AI**: output `--json`/`--jsonl`/`--csv`, non interattivo, pipeable, read-only. L'intelligenza sugli EPSG (`inspect`, `detect`, `targets`) è completamente **offline**.
 
+> **Meglio con un'AI.** openverto funziona benissimo da solo, ma **dà il meglio guidato da un agente AI**. Per un'esperienza interattiva — identificazione del sistema di origine, scelta di un target valido, conversione e verifica della copertura — abbinalo alla Agent Skill [`verto-explorer`](skills/verto-explorer/SKILL.md) inclusa nel repo. Vedi la [**guida d'installazione**](docs/skill/README.md) per i passi.
+
 ## Installazione
 
 Come strumento CLI (consigliato):
@@ -35,10 +43,26 @@ openverto inspect 3003
 # converti un CSV di punti Gauss-Boaga (colonne est/nord) in RDN2008/TM32
 openverto batch catasto.csv --from 3003 --to 6707 --e-col est --n-col nord --out out.csv
 
+# CSV all'italiana (delimitatore ; e virgola decimale), da stdin verso stdout
+cat comuni.csv | openverto batch - --from 4265 --to 6706 --decimal , --e-col lon --n-col lat
+
 # riproietta le geometrie di un GeoJSON
 openverto geojson aree.geojson --from 4230 --to 6706 --out out.geojson
 ```
 
+### Lettura del CSV (comando `batch`)
+
+Il CSV di input è letto con **DuckDB**: il **delimitatore** (`,`, `;`, tab, `|`) è
+rilevato automaticamente, non va dichiarato.
+
+- **Formato di default, nessuna opzione richiesta**: CSV con prima riga di
+  intestazione, separatore decimale **punto** (`12.4924`). Il delimitatore può
+  essere virgola o punto e virgola: viene riconosciuto da solo.
+- **CSV all'italiana**: per coordinate con la **virgola decimale** (`12,4924`)
+  aggiungi `--decimal ,`.
+- **stdin/stdout**: usa `-` come file per leggere da stdin; ometti `--out` per
+  scrivere su stdout.
+
 ## Formati di output
 
 Globale, con `-o/--output`:
@@ -58,7 +82,7 @@ openverto -o csv convert ...      # CSV
 |---|---|
 | `systems` | Elenco dei sistemi di riferimento supportati (EPSG + descrizione) |
 | `convert` | Converte una o più coordinate (`e n`, o `e,n` da stdin) |
-| `batch` | Converte un CSV in CSV o GeoJSON (auto-chunk a 32000, `--skip-invalid`) |
+| `batch` | Converte un CSV (letto con DuckDB: delimitatore auto, `--decimal`, `-`=stdin) in CSV o GeoJSON (auto-chunk a 32000, `--skip-invalid`) |
 | `geojson` | Riproietta le geometrie di un file GeoJSON |
 | `inspect` | Famiglia datum, ordine assi, unità, fuso, false easting di un EPSG |
 | `detect` | Indovina il sistema di origine di una coordinata dalla sua magnitudine |
@@ -91,6 +115,11 @@ ov.inspect(3003)
 ov.targets(3003)
 ov.detect(2300000, 4640000)           # {"kind": "projected", "candidate_epsg": [3004], ...}
 
+# lettura CSV robusta come la CLI (delimitatore auto; '-' = stdin)
+# le celle restano stringhe grezze: normalizza la virgola solo sulle colonne x/y
+header, records = ov.read_csv_file("comuni.csv", decimal=",")
+e_idx = ov.resolve_column(header, "lon", ov.geo.E_ALIASES)
+
 # salta le coordinate fuori griglia isolandole per bisezione
 results, skipped = ov.convert_skipping(coords, 3003, 6707)
 
@@ -111,7 +140,7 @@ Nessuna. Il servizio è libero e gratuito; i campi `utente`/`chiave` richiesti d
 
 ## Crediti
 
-Servizio dati: [IGM Verto Online](https://igmi.esercito.difesa.it/), Istituto Geografico Militare.
+Servizio dati: [IGM Verto Online](https://igmi.esercito.difesa.it/servizi/verto-online/), Istituto Geografico Militare.
 
 ## Licenza
 

docs/future-ideas.md

@@ -0,0 +1,85 @@
+# Future ideas
+
+## Export spaziale via DuckDB (input CSV/JSON/Parquet generico + output GIS con CRS)
+
+### Idea
+
+Dare in pasto a openverto un file tabellare **generico** (CSV, JSON, Parquet) in cui
+l'utente dichiara qual è la colonna X e quale la Y, far convertire le coordinate
+da Verto, e produrre in output un **file di punti in formato spaziale vero**
+(GeoPackage, FlatGeobuf, Shapefile, GeoParquet) con il **CRS corretto già scritto
+nel file**.
+
+Il modulo che fa il lavoro di lettura/scrittura è **DuckDB** (con estensione
+`spatial`).
+
+### Punto chiave (la tesi di tutto il design)
+
+**DuckDB fa SOLO I/O. Non riproietta nulla.** La conversione di coordinate resta
+esclusivamente di Verto. DuckDB:
+
+1. legge l'input (autodetect di delimitatori/tipi su CSV, parsing JSON anche
+   annidato, lettura Parquet);
+2. scrive l'output spaziale **etichettando** il CRS di destinazione sulle
+   coordinate **già convertite da Verto** — NON trasformandole.
+
+Concretamente l'export è qualcosa come:
+
+```sql
+COPY punti TO 'out.gpkg'
+  WITH (FORMAT GDAL, DRIVER 'GPKG', SRS 'EPSG:6706');
+```
+
+dove `SRS` è solo un'**etichetta**: i valori X/Y nella tabella sono quelli
+restituiti da Verto.
+
+**Perché NON usare `ST_Transform` di DuckDB.** L'estensione `spatial` espone
+`ST_Transform`/PROJ, e un futuro implementatore sarà tentato di usarlo
+scavalcando Verto. Sarebbe un errore che svuota di senso il progetto: Verto usa
+le **griglie ufficiali IGM**, che PROJ-senza-griglie non replica. Lo scarto è
+documentato in `LOG.md` e `docs/evaluation.md` (0.1–2.8 m). Quel divario è
+l'intera ragione per cui questa feature passa da Verto.
+
+### Posizionamento rispetto a `batch`/`geojson` esistenti
+
+Non è un duplicato di `batch`. È un'**estensione**:
+
+- `batch` oggi: legge CSV (colonne E/N), converte, output `table/json/jsonl/csv`
+  o GeoJSON costruito a mano.
+- nuovo: input più ampio (CSV "sporco", JSON, Parquet via DuckDB) e soprattutto
+  **output GIS reale** (GPKG/FGB/SHP/GeoParquet) con CRS embedded — cosa che oggi
+  openverto non sa fare.
+
+### Architettura (il pezzo non banale sta in mezzo)
+
+Non è una singola pipeline SQL. È:
+
+```
+DuckDB read  →  estrai X/Y  →  Verto convert (riusa chunking/bisezione di batch)
+             →  re-join delle coord convertite preservando TUTTI gli attributi
+                e l'ordine delle righe  →  DuckDB COPY TO (formato spaziale)
+```
+
+Il **re-join / preservazione attributi** in mezzo è la parte ingegneristica vera.
+`batch` + `rows_to_geojson` già fanno una parte di questo lavoro e sono il punto
+di partenza.
+
+### Decisioni (2026-06-08)
+
+- **Dipendenza**: DuckDB entra come **dipendenza core** (scelta dell'autore).
+  Nota: il core passa da 4 dipendenze pure-Python a includere un binario pesante;
+  install più pesante per tutti, ma feature sempre disponibile. Da rivalutare se
+  l'impatto sull'install/wheel risulta eccessivo.
+- **Comando**: **nuovo comando dedicato** (`export`/`spatial`), non estensione di
+  `batch`. Tiene `batch` semplice e separa le responsabilità.
+- **Output**: GPKG, FlatGeobuf, GeoParquet, Shapefile (tutti e quattro al primo
+  giro). GPKG come default naturale.
+- **Input**: **solo CSV** al primo giro (lettura robusta via DuckDB: autodetect
+  delimitatori/tipi). JSON e Parquet rimandati a iterazioni successive.
+
+### Domande ancora aperte
+
+- Nome esatto del comando: `export` vs `spatial` vs altro.
+- Shapefile: gestione limiti noti (nomi campo ≤10 char, tipi) — troncamento
+  automatico con warning?
+- Default driver dedotto dall'estensione del file di output (`.gpkg`→GPKG, ecc.)?

docs/skill/README.md

@@ -0,0 +1,70 @@
+# Install the verto-explorer skill
+
+The `verto-explorer` skill enables guided, interactive coordinate conversion
+between Italian reference systems directly in your AI coding agent, using the
+**[openverto](https://github.com/ondata/openverto)** CLI under the hood.
+
+Skills can be installed in many ways — refer to your agent's documentation for the
+available options. Here we use [skills](https://github.com/vercel-labs/skills), a
+convenient tool that installs a skill in a single step across multiple agents
+(Claude Code, OpenCode, GitHub Copilot, Codex, and more) in a unified way.
+
+## Prerequisites
+
+- The **openverto** CLI (`uv tool install openverto`) available on your PATH.
+- Node.js (v18+) — required only for the `npx skills` method below. Install it via
+  your system's package manager or from [nodejs.org](https://nodejs.org).
+
+## Installation
+
+Run:
+
+```bash
+npx skills add ondata/openverto --skill verto-explorer
+```
+
+### Step 1 — Select agents
+
+The installer fetches the skill from the repository and asks which agents to
+install it for. Several universal agents (including Claude Code) are enabled by
+default. If your agent is missing from the default list, scroll down to
+**Additional agents** to find and select it.
+
+### Step 2 — Choose installation scope (Global recommended)
+
+Choose between installing for the current project or globally (home directory,
+available across all projects). **Global** makes the skill available in every
+project.
+
+### Step 3 — Symlink (Recommended)
+
+Choose how the skill file is installed. We recommend **Symlink**: instead of
+copying the file, a symbolic link points to the original source, so any update to
+the skill is reflected immediately everywhere, with no need to reinstall.
+
+### Step 4 — Confirm
+
+Review and confirm with **Yes** to proceed.
+
+## Alternative: manual installation
+
+If you prefer not to use `npx skills`, you can download the skill folder directly
+and add it to your agent without Node.js. The skill is located at
+[`skills/verto-explorer/`](../../skills/verto-explorer/) in this repository —
+refer to your agent's documentation for how to register a local skill folder.
+
+## Update
+
+To update the skill to the latest version:
+
+```bash
+npx skills update verto-explorer
+```
+
+## Usage
+
+Once installed, use `/verto-explorer` in the selected agents to start a guided
+coordinate-conversion session using openverto.
+
+To explore the skill's full capabilities before or after installing, see the
+[skill definition](../../skills/verto-explorer/SKILL.md).

openspec/changes/archive/2026-06-08-batch-duckdb-csv/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-08

openspec/changes/archive/2026-06-08-batch-duckdb-csv/design.md

@@ -0,0 +1,63 @@
+## Context
+
+Il comando `batch` (`src/openverto/cli.py`) legge il CSV via
+`read_csv_file` in `geo.py`, che usa `csv.reader` e tratta ogni cella come
+stringa. Le colonne X/Y vengono poi convertite con `float(rec[idx].strip())`.
+Questo fallisce su due casi molto comuni nei dati italiani: delimitatore `;` e
+separatore decimale virgola (`12,4924`).
+
+DuckDB è ora una dipendenza del progetto e il suo `read_csv_auto` ha uno sniffer
+robusto che riconosce delimitatore e tipi, con un parametro esplicito per il
+separatore decimale.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- `batch` legge il CSV via DuckDB con autodetect del delimitatore.
+- Opzione per dichiarare il separatore decimale (default `.`, tipico alternativo
+  `,`).
+- Le colonne X/Y diventano numeriche già in lettura (niente `float()` su stringhe
+  con virgola).
+
+**Non-Goals:**
+
+- Nessun formato di output spaziale (GPKG/FGB/SHP/GeoParquet): abbandonati.
+- Nessun comando nuovo: si potenzia `batch`.
+- Nessun cambiamento all'output di `batch` (`e_out`/`n_out`, csv/geojson).
+- Nessun input non-CSV (JSON/Parquet) per ora.
+
+## Decisions
+
+**1. Lettura via `read_csv_auto`, restituendo `(header, records)` come oggi.**
+Il nuovo helper interroga DuckDB e produce la stessa struttura
+`(list[str], list[list[str]])` che `batch` già consuma, così a valle non cambia
+nulla (risoluzione colonne, skip, output). *Alternativa scartata*: riscrivere
+l'intera pipeline di `batch` in SQL — sovradimensionato e rischioso.
+
+**2. Separatore decimale come opzione esplicita, non autodetect.**
+DuckDB non indovina in modo affidabile la virgola decimale (ambigua col
+delimitatore). Si espone `--decimal` (default `.`) passato a `read_csv_auto`
+come `decimal_separator`. *Alternativa scartata*: euristica lato Python —
+fragile.
+
+**3. DuckDB sniffer al posto di `csv.Sniffer`.**
+Scelta dell'autore: usare DuckDB che è già una dipendenza e ha uno sniffer
+migliore. *Alternativa scartata*: `csv.Sniffer` + `str.replace(',', '.')` —
+eviterebbe la dipendenza ma è meno robusto e contro la richiesta esplicita.
+
+**4. Le celle restano restituite come stringhe verso `batch`.**
+Per non toccare l'output, il record passa a `batch` come stringhe; le sole
+colonne che contano numericamente (X/Y) sono garantite parse-abili perché
+DuckDB le ha già normalizzate (punto decimale) in lettura.
+
+## Risks / Trade-offs
+
+- **[Tipi vs stringhe] DuckDB tipizza, `batch` vuole stringhe** → si converte il
+  risultato DuckDB in stringhe preservando il valore; per i numeri si usa una
+  rappresentazione con punto decimale, così `float()` a valle non fallisce.
+- **[Peso dipendenza] DuckDB binario ~20 MB solo per leggere CSV** → accettato
+  esplicitamente dall'autore; lo sniffer robusto e l'uso già presente di DuckDB
+  giustificano la scelta.
+- **[NULL/celle vuote] DuckDB rende NULL le celle vuote** → mappare i NULL a
+  stringa vuota per non alterare l'output rispetto a oggi.

openspec/changes/archive/2026-06-08-batch-duckdb-csv/proposal.md

@@ -0,0 +1,40 @@
+## Why
+
+Il comando `batch` legge oggi il CSV con un `csv.reader` semplice: niente
+autodetect del delimitatore e nessuna gestione del separatore decimale. I CSV
+italiani/PA usano spessissimo `;` come delimitatore e la virgola come separatore
+decimale (es. `12,4924`), che oggi finiscono interpretati come testo e fanno
+fallire la conversione. Usare DuckDB per la lettura risolve entrambi i casi con
+uno sniffer robusto.
+
+## What Changes
+
+- `batch` legge il CSV tramite DuckDB (`read_csv_auto`) invece del `csv.reader`.
+- **Autodetect del delimitatore**: `,`, `;`, tab riconosciuti senza che l'utente
+  li dichiari.
+- Nuova opzione per indicare il **separatore decimale** (es. virgola), così le
+  colonne X/Y con `12,4924` vengono lette come numeri.
+- DuckDB entra come **dipendenza core**.
+- Nessun comando nuovo. Nessun formato spaziale. L'output di `batch`
+  (`e_out`/`n_out`, csv/geojson) resta invariato.
+
+## Capabilities
+
+### New Capabilities
+
+- `batch-csv-reading`: lettura robusta del CSV di input del comando `batch` via
+  DuckDB, con autodetect del delimitatore e separatore decimale configurabile,
+  preservando l'attuale risoluzione delle colonne e l'output.
+
+### Modified Capabilities
+
+<!-- Nessuna: non esistono spec in openspec/specs/. Il comportamento di output di batch non cambia. -->
+
+## Impact
+
+- **Dipendenze**: aggiunta di `duckdb` alle dipendenze core in `pyproject.toml`.
+- **Codice**: `src/openverto/geo.py` (`read_csv_file`) o un nuovo helper di
+  lettura passa a DuckDB; il comando `batch` in `src/openverto/cli.py` ottiene
+  l'opzione separatore decimale. La logica di conversione/skip resta invariata.
+- **Test**: nuovi test offline su delimitatore non standard e separatore
+  decimale virgola.