docs(skill): audit live rndt-explorer — fix sort rotti, nuovo workflow data journalist

aborruso · claude · aborruso · commit 36b5402f3cd7 · 2026-07-17T22:51:37.000+02:00
Verifiche contro l'API reale (2026-07-17): - workflows #3/#4: dateDescending (non ordina) → apiso_Modified_dt:desc - rimosso apiso_PublicationDate_dt (campo inesistente) - sort su title ora funziona (API cambiata): aggiornati search-syntax, codelists.py (commento), knowledge/known-issues - output-formats: documentato compact (+ resources vuoto → get) - SKILL: v1.0, installazione PyPI, --timeout - nuovo workflow 7 (download, licenza, citazione fonte) verificato end-to-end su record ISPRA; sanity numbers aggiornati - README: esempio conversazionale data journalist + nota resources Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
diff --git a/LOG.md b/LOG.md
@@ -1,5 +1,18 @@
 # LOG
 
+## 2026-07-17 (skill audit)
+
+- **Audit live della skill `rndt-explorer`** (comandi eseguiti contro l'API reale). Esito: struttura a 4 fasi solida, 4 punti stale corretti:
+  - `workflows.md` #3/#4 usavano `--sort dateDescending` (che NON ordina, riconfermato live) → sostituito con `apiso_Modified_dt:desc` + warning.
+  - `workflows.md` citava `apiso_PublicationDate_dt` → campo inesistente (verificato su record reale), rimosso; lista campi data corretta.
+  - **Scoperta: il sort su `title` ora funziona** (`title:asc` ordina alfabeticamente) — l'API è cambiata rispetto a maggio-giugno, quando dava "Fielddata is disabled". Aggiornati `search-syntax.md`, `codelists.py` (commento), `knowledge/api/known-issues.md`. I campi garantiti sortable restano `_s`/`_dt`/`_i`.
+  - `output-formats.md` non menzionava `compact` → aggiunta sezione dedicata (incl. `resources: []` → serve `get`).
+  - SKILL.md: frontmatter v0.1→1.0, installazione da PyPI in compatibility, opzioni globali `--timeout`/`--base-url`.
+  - **Nuovo workflow 7 per data journalist** (verificato end-to-end live su record ISPRA "Popolazione rischio alluvioni"): compact+isOpendata → `search --id` per link con dctype → `get` per licenza/ente/data (citazione fonte) → `ogr2ogr` dal WFS. Note oneste: enclosure raro, `isOpendata` a volte generico, download spesso dietro portali regionali.
+  - Sanity numbers aggiornati al 2026-07-17 (catalogo 23.580→23.632).
+  - Aggiunti `apiso_CRS`, `apiso_Format_s`, `isOpendata` ai campi utili di `search-syntax.md` (per operatori GIS).
+- 55/55 test, ruff e mypy verdi (unica modifica codice: commento in `codelists.py`).
+
 ## 2026-07-17
 
 - **Valutazione readiness produzione v0.1.0** in `docs/evaluation-v0.1.0.md`: codice production-grade, gap tutti infrastrutturali (no CI, no mypy, metadata PyPI incompleti, manca `py.typed` e CHANGELOG). Roadmap verso v1.0 inclusa.
diff --git a/README.md b/README.md
@@ -85,6 +85,10 @@ openrndt --format compact search --q "catasto" --num 3
 # {"id":"…","title":"…","org":"Comune di Torino","type":"service","category":null,"updated":"…","resources":["WMS"]}
 ```
 
+Se `resources` è `[]` il record non linka servizi fruibili: recupera il
+dettaglio con `get <id>` e guarda `_source.links_s` (spesso il download è
+dietro un portale dell'ente, non un link diretto).
+
 ## Esempi di conversazione con un'AI
 
 openrndt è pensato per essere **pilotato da un assistente AI**. Non devi imparare la
@@ -202,6 +206,26 @@ openrndt search --q "frane AND isOpendata:*" --num 10
 > Regione Toscana ai rilievi con drone dell'emergenza alluvione 2023 in
 > Emilia-Romagna. Te li elenco con la licenza di ciascuno?
 
+### «Devo scaricare i dati e citare la fonte in un articolo»
+
+> **Tu:** Sto scrivendo un articolo sul rischio alluvioni. Mi servono i dati,
+> la licenza d'uso e come citare la fonte.
+
+L'AI cerca fra gli open data e recupera licenza ed ente dal dettaglio:
+
+```bash
+openrndt --format compact search --q "alluvioni AND isOpendata:*" --num 30
+openrndt search --id "ispra_rm:01IdroHazard_DT" \
+  | jq -r '.results[0].links[] | select(.dctype != null) | "\(.dctype)\t\(.href)"'
+openrndt get "ispra_rm:01IdroHazard_DT" \
+  | jq '{licenza: ._source.isOpendata, ente: ._source.EnteResponsabile_s}'
+```
+
+> **AI:** **ISPRA** pubblica *Popolazione a rischio alluvioni* con licenza
+> **CC-BY-4.0**: puoi riusarlo citando la fonte (es. "Fonte: ISPRA — Popolazione
+> a rischio alluvioni, CC-BY 4.0"). I dati sono esposti come WFS: te li scarico
+> in GeoPackage con `ogr2ogr`, pronti per QGIS o per un'analisi tabellare.
+
 ## Uso come libreria Python
 
 ```python
diff --git a/knowledge/api/known-issues.md b/knowledge/api/known-issues.md
@@ -13,8 +13,8 @@ Tutti i punti seguenti sono stati verificati empiricamente contro l'API di produ
 | Comportamento documentato | Comportamento reale | Compensazione in openrndt |
 |---------------------------|---------------------|---------------------------|
 | Il parametro `dataCategory` filtra per categoria. | Non filtra: ritorna sempre il catalogo intero. | `--data-category` è tradotto nella clausola Lucene `q=keywords_s:VAL` (`OR` per valori multipli). |
-| `sort=dateDescending` / `dateAscending` ordinano per data. | Ignorati: ordine identico fra loro. | `discover --what sort_values` marca i valori rotti; la sintassi funzionante è `campo:asc\|desc` su campo sortable (es. `apiso_Modified_dt:desc`). |
-| — | Ordinare su un campo `text` analizzato (es. `title` nudo) dà errore Elasticsearch "Fielddata is disabled". | Documentato nelle codelist; usare i campi `_s`/`_dt`/`_i`. |
+| `sort=dateDescending` / `dateAscending` ordinano per data. | Ignorati: ordine identico fra loro (riconfermato 2026-07-17). | `discover --what sort_values` marca i valori rotti; la sintassi funzionante è `campo:asc\|desc` su campo sortable (es. `apiso_Modified_dt:desc`). |
+| — | Ordinare su un campo `text` analizzato (es. `title` nudo) dava errore Elasticsearch "Fielddata is disabled"; **dal 2026-07-17 risulta funzionare** (`title:asc` ordina alfabeticamente — comportamento API cambiato). | Documentato nelle codelist; i campi garantiti sortable restano `_s`/`_dt`/`_i`. |
 | Esiste una data di pubblicazione ordinabile. | Non esiste; `apiso_CreationDate_dt` è spesso null o fittizia (es. 2012-01-01). | Proxy consigliato per "più recenti": `apiso_Modified_dt:desc` (issue #4 del repository). |
 | L'endpoint CSW supporta `SortBy` (INSPIRE Discovery Services v3.1). | `SortBy` ignorato: non conforme. | Nessuna: documentato (issue #5 del repository). |
 | Item inesistente → errore HTTP. | Risponde `200` con body `{"found": false}`. | `get_item` controlla `found` e solleva `ItemNotFoundError`. |
diff --git a/knowledge/log.md b/knowledge/log.md
@@ -2,6 +2,7 @@
 
 ## 2026-07-17
 
+* **Update**: [api/known-issues.md](/api/known-issues.md), [skill.md](/skill.md) — audit live della skill rndt-explorer: il sort su `title` ora funziona (API cambiata), `dateDescending` riconfermato rotto; skill aggiornata (workflow corretti, campo `apiso_PublicationDate_dt` inesistente rimosso, formato compact documentato, nuovo workflow data journalist).
 * **Update**: [project.md](/project.md) — versione 1.0.0, roadmap produzione completata (`CHANGELOG.md` nel repository).
 * **Update**: [conventions/testing.md](/conventions/testing.md), [conventions/error-handling.md](/conventions/error-handling.md) — coverage 89%→99% (17 test nuovi, `tests/test_output.py`); bug reale trovato e corretto: `--format` invalido produceva un traceback, ora messaggio leggibile + exit 2.
 * **Update**: [cli/index.md](/cli/index.md), [conventions/error-handling.md](/conventions/error-handling.md), [architecture.md](/architecture.md) — documentata la nuova opzione globale `--timeout` (stesso pattern di `--base-url`, override in `config.py`).
diff --git a/knowledge/skill.md b/knowledge/skill.md
@@ -24,5 +24,5 @@ La skill `rndt-explorer` (in `skills/rndt-explorer/` nel repository) insegna a u
 | `references/search-syntax.md` | Sintassi Lucene con esempi verificati. |
 | `references/result-structure.md` | Struttura del JSON di risposta. |
 | `references/output-formats.md` | Guida ai formati (vedi anche [la convenzione](/conventions/output-formats.md)). |
-| `references/workflows.md` | Flussi tipici end-to-end. |
+| `references/workflows.md` | Flussi tipici end-to-end, incluso il workflow per data journalist (dati scaricabili, licenza, citazione fonte). |
 | `references/ogc-services.md` | Esplorazione WMS/WFS/WCS/WMTS con GDAL/OGR. |
diff --git a/skills/rndt-explorer/SKILL.md b/skills/rndt-explorer/SKILL.md
@@ -15,9 +15,10 @@ description: >
 license: MIT
 compatibility: >
   Richiede la CLI openrndt (comandi: search, get, discover).
+  Installazione: `uv tool install openrndt` (da PyPI) oppure `uvx openrndt`.
 metadata:
   author: ondata
-  version: "0.1"
+  version: "1.0"
 ---
 
 # RNDT Explorer — esplorazione guidata del catalogo
@@ -38,6 +39,12 @@ openrndt --format compact search … # NDJSON: 1 riga/record, per scremare a bas
 Il formato `compact` (solo per `search`) emette una riga JSON per record con i
 campi ad alto segnale — `id`, `title`, `org`, `type`, `category`, `updated`, `resources` —
 ideale per individuare il record giusto prima di chiedere il dettaglio con `get`.
+Se `resources` è `[]` il record non linka servizi fruibili: fai `get <id>` e
+guarda `_source.links_s`.
+
+Altre opzioni globali (sempre PRIMA del comando): `--timeout <secondi>` per il
+timeout HTTP per singolo tentativo (default 30s; con i retry il caso peggiore è
+~3x — utile abbassarlo se il portale è lento), `--base-url` per un mirror.
 
 Tutti i comandi hanno `--help`. La skill segue 4 fasi.
 
@@ -184,7 +191,8 @@ interrogabili con GetFeatureInfo, download vettoriale con `ogr2ogr`. Guida in
 
 [`references/workflows.md`](./references/workflows.md) raccoglie sequenze
 testate live (catasto per provincia, WMS di un tema INSPIRE, dataset di un
-ente, aggiornamenti recenti per categoria, export CSV, sanity check con i
+ente, aggiornamenti recenti per categoria, export CSV, dati scaricabili con
+licenza e citazione della fonte per data journalist, sanity check con i
 totali attesi).
 
 ## Output e parsing
diff --git a/skills/rndt-explorer/references/output-formats.md b/skills/rndt-explorer/references/output-formats.md
@@ -2,7 +2,8 @@
 
 `openrndt` ha due livelli di formato:
 
-1. **Formato del comando CLI** (`--format` globale): `json` (default), `table`, `csv`.
+1. **Formato del comando CLI** (`--format` globale): `json` (default), `table`,
+   `csv`, `compact` (NDJSON, solo per `search`).
    Controlla come la CLI stampa il risultato.
 2. **Formato della risposta API** (`-f` interno, gestito automaticamente):
    `json`, `atom`, `csv`, `kml`, ecc. Non esposto direttamente nella CLI MVP —
@@ -13,11 +14,26 @@
 | Scenario                                          | Formato consigliato |
 |---------------------------------------------------|---------------------|
 | Pipeline `\| jq`, scripting Python/Bash            | `json` (default)    |
+| Scremare molti risultati a basso costo di token (agenti) | `compact`     |
 | Mostrare risultati in chat all'utente             | `table`             |
 | Esportare in foglio di calcolo                     | `csv`               |
 | Recuperare XML ISO 19139 per validatori INSPIRE   | `openrndt get <id> --xml` |
 | Generare pagina HTML del metadato                  | `openrndt get <id> --html` |
 
+## `compact` — NDJSON per agenti (solo `search`)
+
+Una riga JSON per record con i soli campi ad alto segnale: `id`, `title`,
+`org`, `type`, `category`, `updated`, `resources`.
+
+```bash
+openrndt --format compact search --q "frane AND isOpendata:*" --num 30
+```
+
+- `resources` elenca i tipi di servizio/download fruibili (`WMS`, `WFS`,
+  `download`, …). Se è `[]` il record non linka servizi: per i dettagli fai
+  `get <id>` e guarda `_source.links_s`.
+- `get --format compact` (come `csv`) è rifiutato: il dettaglio non è tabellare.
+
 ## Esempi
 
 ```bash
diff --git a/skills/rndt-explorer/references/search-syntax.md b/skills/rndt-explorer/references/search-syntax.md
@@ -32,12 +32,15 @@ Lista completa in [`result-structure.md`](./result-structure.md). I più ricorre
 - `apiso_Type_s` (tipo risorsa: `dataset`, `service`, ecc.)
 - `PuntoDiContattoEmail_s` (email contatto)
 - `AmbitoTerritoriale_s` (Regionale/Nazionale/Locale)
+- `isOpendata` (licenza open data: `isOpendata:*` per tutti gli open data)
+- `apiso_CRS` (sistema di riferimento, es. `apiso_CRS:"EPSG:4326"` — utile per operatori GIS)
+- `apiso_Format_s` (formati disponibili, es. `Shapefile`, `GeoTIFF`, `GML`)
 
 ## Esempi verificati live
 
 ```bash
 # Tema INSPIRE
-openrndt search --q 'INSPIRETheme_s:Idrografia' --num 5         # → 845 totali
+openrndt search --q 'INSPIRETheme_s:Idrografia' --num 5         # → 863 totali (2026-07-17)
 
 # Ente (forma breve)
 openrndt search --q 'contact_organizations_s:"Agenzia delle Entrate"' --num 5
@@ -92,8 +95,11 @@ Limiti noti:
   nell'XML ISO (`gmd:CI_Date dateType=publication`) ma non è un campo indicizzato
   ordinabile. Il proxy disponibile è `apiso_Modified_dt` (dateStamp del metadato).
   `apiso_CreationDate_dt` è spesso `null` o fittizio (`2012-01-01`): inaffidabile.
-- Ordinare per un campo `text`/analizzato (es. `title` nudo) dà errore
-  Elasticsearch *"Fielddata is disabled"*: usa un campo keyword.
+- Il sort su `title` (campo text) in passato dava errore Elasticsearch
+  *"Fielddata is disabled"*; **riverificato il 2026-07-17: ora funziona**
+  (`title:asc` ordina alfabeticamente — il comportamento dell'API è cambiato).
+  I campi *garantiti* sortable restano comunque quelli `_s`/`_dt`/`_i`:
+  su altri campi text non c'è garanzia.
 - Il servizio **CSW** (`/csw`) ignora del tutto `<ogc:SortBy>`: non ordina per
   nessuna proprietà. Dettagli e implicazioni INSPIRE in `ref/rest-api-rndt.md`.
 
diff --git a/skills/rndt-explorer/references/workflows.md b/skills/rndt-explorer/references/workflows.md
@@ -50,17 +50,21 @@ openrndt --format json search \
 ```bash
 openrndt --format table search \
   --q 'contact_organizations_s:"Agenzia delle Entrate"' \
-  --num 20 --sort dateDescending
+  --num 20 --sort 'apiso_Modified_dt:desc'
 ```
 
+> ⚠️ Non usare `--sort dateDescending`: documentato sul RNDT ma **ignorato**
+> dall'API (verificato live, riconfermato 2026-07-17). Il sort reale è
+> `campo:asc|desc` — vedi [`search-syntax.md`](./search-syntax.md).
+
 ## 4. Aggiornamenti recenti
 
 > "Dataset modificati nel 2024, dal più recente."
 
 ```bash
 openrndt --format json search \
   --time "2024-01-01/2024-12-31" \
-  --sort dateDescending \
+  --sort 'apiso_Modified_dt:desc' \
   --num 30
 ```
 
@@ -70,12 +74,15 @@ openrndt --format json search \
 > 2. Il campo top-level `updated` di ogni risultato riflette la data di
 >    reindicizzazione del catalogo (uguale per tutti), non la data del dataset.
 >    Per ordinare/filtrare per "data del dataset" usare i campi `_source`:
->    - `apiso_RevisionDate_dt` — data di revisione del metadato
->    - `apiso_CreationDate_dt` — data di creazione del metadato
->    - `apiso_PublicationDate_dt` — data di pubblicazione
+>    - `apiso_Modified_dt` — dateStamp del metadato (il proxy più affidabile)
+>    - `apiso_RevisionDate_dt` — data di revisione della risorsa (spesso null)
+>    - `apiso_CreationDate_dt` — data di creazione (spesso null o fittizia)
 >    - `timeperiod_nst[].begin_dt`/`end_dt` — copertura temporale dei dati
 >      (è il campo su cui agisce il parametro `--time`)
 >
+>    Non esiste un campo `apiso_PublicationDate_dt` (verificato live 2026-07-17):
+>    la data `publication` sta solo nell'XML ISO, non è indicizzata.
+>
 > Workaround per "inlandWaters revisionati nel 2024":
 >
 > ```bash
@@ -98,15 +105,57 @@ xmllint --noout meta.xml && echo "XML valido"
 openrndt --format csv search --q "ortofoto" --num 100 > ortofoto.csv
 ```
 
+## 7. Dati scaricabili, licenza e citazione della fonte (data journalist)
+
+> "Mi servono i dati sulla popolazione a rischio alluvioni, con licenza che
+> ne permetta il riuso, e devo citare la fonte."
+
+```bash
+# 1. cerca solo open data, scrematura veloce con compact:
+#    la colonna `resources` dice subito cosa offre ogni record
+openrndt --format compact search --q "alluvioni AND isOpendata:*" --num 30
+# {"id":"ispra_rm:01IdroHazard_DT","title":"Popolazione rischio alluvioni - Dataset",...,"resources":["WFS","WMS"]}
+
+# 2. URL dei servizi con il tipo (usa `search --id`, che espone rel/dctype)
+openrndt --format json search --id "ispra_rm:01IdroHazard_DT" \
+  | jq -r '.results[0].links[] | select(.dctype != null) | "\(.dctype)\t\(.href)"'
+# WMS   https://sdi.isprambiente.it/geoserver/nz1/wms?...
+# WFS   https://sdi.isprambiente.it/geoserver/nz1/wfs?...
+
+# 3. licenza, ente e data per la citazione della fonte
+openrndt --format json get "ispra_rm:01IdroHazard_DT" \
+  | jq '{licenza: ._source.isOpendata, ente: ._source.EnteResponsabile_s,
+         aggiornato: ._source.apiso_Modified_dt}'
+# → CC-BY-4.0, ISPRA, 2015-02-13
+
+# 4. dal WFS ai dati tabellari (GeoPackage, apribile anche in QGIS)
+ogr2ogr -f GPKG alluvioni.gpkg "WFS:https://sdi.isprambiente.it/geoserver/nz1/wfs" <feature_type>
+```
+
+Note verificate live (2026-07-17):
+
+- `resources: []` nel compact è frequente: il record non linka servizi
+  fruibili. In quel caso fai `get` e guarda `_source.links_s` — spesso il
+  download è dietro un portale regionale (es. Geoscopio Toscana), non un
+  link diretto.
+- Il download diretto (`rel=enclosure` / `dctype=download`) è raro: la
+  maggior parte dei dataset si prende via WFS (vettoriale) con `ogr2ogr` —
+  vedi [`ogc-services.md`](./ogc-services.md).
+- `isOpendata` può valere una licenza precisa (`"CC BY 4.0"`) o un generico
+  `"opendata"`: per la licenza esatta guarda anche
+  `_source.apiso_AccessConstraints_s`.
+
 ## Risultati di riferimento (sanity check)
 
-Numeri ottenuti live al 2026-05-27 — utili per accorgersi di regressioni:
+Numeri ottenuti live al 2026-07-17 — utili per accorgersi di regressioni
+(cambiano nel tempo: il catalogo cresce):
 
 | Query                                                              | `total` atteso |
 |--------------------------------------------------------------------|---------------:|
-| `--q "catasto"`                                                    | 8.814          |
-| `--data-category planningCadastre`                                 | 11.351         |
-| `--data-category "planningCadastre,boundaries"`                    | 11.720         |
-| `--q 'INSPIRETheme_s:Idrografia'`                                  | 845            |
+| `--q "catasto"`                                                    | 8.827          |
+| `--data-category planningCadastre`                                 | 11.659         |
+| `--data-category "planningCadastre,boundaries"`                    | 12.046         |
+| `--q 'INSPIRETheme_s:Idrografia'`                                  | 863            |
 | `--q 'contact_organizations_s:"Agenzia delle Entrate"'`            | 7.699          |
-| catalogo completo (`--q "*"` o nessun filtro)                      | 23.580         |
+| `--q 'title:"carta geologica"'`                                    | 154            |
+| catalogo completo (nessun filtro)                                  | 23.632         |
diff --git a/src/openrndt/codelists.py b/src/openrndt/codelists.py
@@ -35,9 +35,11 @@
 # IMPORTANTE (verificato live): il meccanismo reale è `campo:asc|desc` su un campo
 # Elasticsearch *sortable* (keyword `_s`, data `_dt`, intero `_i`). I valori
 # "amichevoli" `dateDescending`/`dateAscending` documentati sulla pagina ufficiale
-# NON ordinano (su RNDT restituiscono ordine identico fra loro → ignorati).
-# Ordinare per un campo `text`/analizzato (es. `title` nudo) dà errore Elasticsearch
-# "Fielddata is disabled". Non esiste un campo data-di-pubblicazione ordinabile.
+# NON ordinano (su RNDT restituiscono ordine identico fra loro → ignorati;
+# riconfermato 2026-07-17). Il sort su `title` (campo text) in passato dava errore
+# "Fielddata is disabled", ma dal 2026-07-17 risulta funzionare: i campi garantiti
+# sortable restano `_s`/`_dt`/`_i`. Non esiste un campo data-di-pubblicazione
+# ordinabile.
 SORT_VALUES: dict[str, str] = {
     "apiso_Modified_dt:desc": "Per data: ultimi metadati modificati per primi (proxy migliore per 'più recenti').",
     "apiso_Modified_dt:asc": "Per data: metadati modificati meno di recente per primi.",
