docs: define example database subproject and defer implementation

CONTEXT.md

@@ -118,6 +118,15 @@ ritrovamento di una card tramite un collegamento non ne implica l'approvazione.
 espliciti, che contribuisce alla consultazione di contenuti pertinenti. La sua
 rimozione non comporta la cancellazione delle card collegate.
 
+## Esempi didattici
+
+**Example workspace** — Un workspace destinato alla pratica con ThothII, associato
+a dati di esempio, schema descritto ed Evidence curate, pronto per iniziare una sessione.
+
+**Practice question** — Una domanda di accompagnamento a un Example workspace,
+proposta come spunto per il percorso human in the loop e priva di soluzione attesa.
+_Avoid_: Solved Question, caso di valutazione del benchmark.
+
 ## Evidence
 
 **Context specialist** — La persona competente sul dominio che redige e cura il

docs/plans/2026-09-27-benchmark-examples.md

@@ -0,0 +1,175 @@
+# Tre esempi locali per l'installazione guidata
+
+Stato: nota esplorativa conservata; requisiti definiti nel PRD e implementazione
+rinviata su richiesta dell'utente.
+Requisiti correnti e decisioni aperte sono ora raccolti nel
+[PRD dei database di esempio](2026-09-27-example-databases-prd.md), che prevale
+su questa nota esplorativa in caso di divergenza.
+Branch: `codex/benchmark-examples`, derivato da `codex/guided-standalone-install`
+al commit `67ee5262`. Collegamento al progetto installazione:
+`docs/plans/2026-09-27-guided-installation-resumption.md` sul branch di origine.
+
+## Requisiti dell'utente
+
+- Tre database pubblicamente scaricabili da BIRD o altro benchmark, con evidence.
+- Tre livelli di complessità crescente; preferenza per dati in CSV.
+- Esempi da implementare in locale.
+- Caricamento opzionale tramite CLI dal repository dei workspace: selezione di
+  uno, due o tutti e tre i database, dopo il setup; integrazione nel setup da valutare.
+- Dati, schema PostgreSQL commentato ed Evidence disponibili per ogni esempio.
+- Domande in un documento di accompagnamento per esercitarsi, senza SQL target.
+- Collaudo in tre tappe: Windows, Linux Omarchy, macOS.
+
+### Criterio chiarito dall'utente
+
+ThothII viene usato con human in the loop: questo progetto non serve a misurarlo
+contro un benchmark. I benchmark sono soltanto fonti di database e documentazione.
+Numero di domande, gold SQL, percentuali di correttezza e copertura delle annotazioni
+per domanda non sono criteri di selezione o di accettazione.
+Le domande sono invece utili come materiale didattico: il prodotto le include in
+un documento separato dalle Evidence, senza soluzioni SQL o valutazione automatica.
+
+Si cercano complessità relazionale e semantica e documentazione sostanziale da
+curare come Source Evidence: significati, regole aziendali, formule, codifiche,
+granularità e relazioni. Documenti non collegati ai quesiti del benchmark contano
+quanto quelli collegati. DDL, righe di esempio e numero di file da soli non
+dimostrano una buona documentazione di dominio. Dopo il confronto delle alternative,
+il trio per cui l'utente richiede ora la procedura è Financial, European Football e F1.
+
+## Dataset proposti
+
+California Schools è escluso per richiesta dell'utente. European Football è richiesto;
+l'utente ha inoltre chiesto di valutare Spider 2.0 e la disponibilità di evidence.
+La proposta corrente comprende Financial e European Football da BIRD e F1 da
+Spider 2.0-Lite. Shopify, QuickBooks e Workday restano alternative documentate.
+I livelli sono una progressione didattica proposta per ThothII.
+
+| Livello | Database | Motivo | Fonti per le Evidence |
+| --- | --- | --- | --- |
+| Primo percorso | BIRD `financial` | Conti, clienti, prestiti e movimenti | Codifiche di dominio e regole nelle annotazioni BIRD |
+| Intermedio | BIRD `european_football_2` | Campionati, squadre, giocatori e partite | Stagioni, significato degli indicatori e aggregazioni nelle annotazioni BIRD |
+| Avanzato | Spider 2.0-Lite `f1` | Stagioni, gare, piloti, giri, pit stop e cambi di posizione; 29 tabelle dichiarate | Documenti di dominio sui sorpassi e sui tipi di giro, da curare e integrare dove insufficienti |
+
+Revisione Hugging Face BIRD osservata:
+`f65faf4ae3b638c1fa6df1d3370c8d92c8366301`.
+
+Le evidence BIRD comprendono spiegazioni di codici, significati di colonne e regole di
+calcolo. Sono annotazioni legate alle domande; richiedono adattamento e revisione
+per diventare Source Evidence di ThothII. Non sono già un archivio ThothII pronto.
+
+Le definizioni dbt sono fonti da curare, non Evidence Unit già importate in ThothII.
+Non contare ogni descrizione di colonna come un'evidence distinta. I file tecnici
+delle librerie dbt non rientrano nel materiale semantico del database.
+Revisione Spider2 osservata: `cafb867313aab4e674652054198f383cf4018943`.
+
+Le ricerche motivate e le alternative sono in
+`docs/research/2026-09-27-spider2-lite-evidence-candidates.md` e
+`docs/research/2026-09-27-spider2-dbt-evidence-candidates.md`.
+
+## Fonti e formati
+
+- [Dataset ufficiale e licenza dichiarata CC BY-SA 4.0](https://huggingface.co/datasets/birdsql/bird_mini_dev).
+- [Domande PostgreSQL, evidence e SQL di riferimento](https://huggingface.co/datasets/birdsql/bird_mini_dev/blob/f65faf4ae3b638c1fa6df1d3370c8d92c8366301/data/mini_dev_pg-00000-of-00001.json).
+- [Istruzioni ufficiali e pacchetto database](https://github.com/bird-bench/mini_dev).
+- [Pacchetto completo indicato dalla dataset card](https://drive.google.com/file/d/13VLWIwpw5E3d5DUkMvzw7hvHE67a4XkG/view?usp=sharing).
+- [Archivio ZIP collegato dal repository ufficiale](https://bird-bench.oss-cn-beijing.aliyuncs.com/minidev.zip):
+  risposta HEAD 200, 800943648 byte al controllo; contenuto non ancora scaricato né
+  confrontato con il pacchetto aggiornato della dataset card.
+
+I CSV `database_description` descrivono schema e valori, non contengono le righe
+delle tabelle. I dati sono forniti come database SQLite e materiale per PostgreSQL/
+MySQL. Proposta: mantenere PostgreSQL come destinazione locale e, se utile, produrre
+CSV riproducibili insieme a DDL, tipi e vincoli. Non usare CSV senza schema come
+unica rappresentazione del database. Conservare provenienza, versione, attribuzione
+e licenza con gli artefatti derivati.
+
+Fonti Spider 2.0-Lite per F1:
+
+- [Istruzioni per scaricare i database SQLite locali](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md).
+- [Schema e metadati F1](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/f1).
+- [Classificazione dei sorpassi](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/f1_overtake.md).
+- [Tipi di giro](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/lap_type.md).
+
+I tre database sorgente sono SQLite. Esportazione CSV e caricamento PostgreSQL
+dovranno preservare tipi, relazioni, granularità e contenuto dei dati selezionati.
+I file sono stati individuati negli archivi; i dati completi non sono stati scaricati
+né convertiti durante la progettazione.
+
+## Proposta di download e caricamento PostgreSQL
+
+Questa sezione risponde alla richiesta di fattibilità e non autorizza né attesta
+un'implementazione già eseguita.
+
+### Destinazione
+
+Il Compose include `catalog-db`, PostgreSQL 17.6, con volume `catalog-data` e database
+`thothii_catalog`. Quest'ultimo ospita le informazioni applicative del Catalog e
+la persistenza Memory. Proposta per le installazioni dimostrative: riutilizzare lo
+stesso servizio PostgreSQL, creando tre database separati, con nomi da finalizzare:
+`example_financial`, `example_football`, `example_f1`. Ogni database avrà un solo
+schema applicativo, un workspace associato e un ruolo di interrogazione in sola
+lettura. L'importazione userà un ruolo distinto con permessi di scrittura.
+
+La creazione degli esempi deve essere una manutenzione esplicita rieseguibile, non
+un'aggiunta affidata unicamente agli script di inizializzazione del volume PostgreSQL.
+Le migrazioni Catalog e i suoi ruoli runtime rimangono separati dal caricatore.
+La condivisione del servizio implica condivisione di risorse, volume e gestione
+backup; non equivale a isolamento fra istanze PostgreSQL indipendenti.
+
+### Sequenza prevista
+
+1. Selezione esplicita di uno, due o tre esempi, anche dopo il primo setup.
+2. Manifest versionato per ciascun esempio: URL ufficiali, revisione/checksum,
+   file nell'archivio, fonti documentali, licenze e versione della conversione.
+   Cache dei pacchetti comuni per evitare download duplicati.
+3. Download ed estrazione dei SQLite e della documentazione. BIRD: descrizioni CSV
+   e annotazioni evidence, conservando il contesto necessario a interpretarle.
+   F1: metadati dello schema e documenti di dominio. Nessuna generazione automatica
+   di nuove regole presentate come se fossero evidence originali.
+4. Ispezione dello schema e dei dati effettivi; conversione SQLite verso DDL
+   PostgreSQL e CSV, con mapping espliciti per tipi, date, booleani, valori null,
+   identificatori e colonne prive di tipo. Rilevare PK/FK presenti e distinguere
+   relazioni documentate o proposte da quelle effettivamente vincolate nella sorgente.
+5. Caricamento in database di preparazione dedicati; creazione degli indici e
+   vincoli verificati, confronto delle righe e dei valori e controlli relazionali.
+   Un fallimento lascia l'esempio non pronto senza sostituire una versione funzionante.
+6. Pubblicazione dei database validati e registrazione dei binding nel Catalog;
+   creazione dei workspace e sincronizzazione degli schemi via servizi esistenti.
+7. Importazione separata: descrizioni nel Catalog; documenti e regole nelle Source
+   Evidence del workspace, con provenienza. Le Evidence restano artefatti del
+   modulo Evidence; la proiezione ricercabile appartiene a Qdrant.
+8. Revisione umana/consolidamento delle Evidence e delle relazioni proposte,
+   preprocessing e controlli di utilizzabilità. La disponibilità dei file scaricati
+   non equivale a un workspace pronto.
+
+Il processo conserva stato e versioni per riprendere dopo errori, evita duplicazioni
+e non sovrascrive Evidence curate o dati esistenti durante una normale riesecuzione.
+Download ed elaborazione devono usare componenti containerizzati, mantenendo il
+percorso Windows/WSL2 senza richiedere Python o Node aggiuntivi sull'host.
+
+## Decisione architetturale aperta
+
+Gli ADR 0001 e 0003 e il glossario corrente prevedono un database per workspace.
+La richiesta di un workspace con tre database richiede quindi una scelta esplicita.
+Proposta: un pacchetto/repository di esempi con tre workspace indipendenti, ognuno
+associato al proprio database. Nessuna modifica multi-database è approvata finora.
+
+## Lavoro previsto dopo la definizione
+
+1. Fissare versione e checksum dei dati, ispezionare schema, tipi, chiavi e
+   documentazione di dominio; definire percorsi dimostrativi di complessità crescente.
+2. Preparare il caricamento locale selettivo dei tre dataset, con dati e ruoli
+   distinti dal Catalog applicativo, ripresa e riesecuzione senza duplicazioni.
+3. Preparare descriptor e Source Evidence con provenienza per ogni esempio;
+   esplicitare ciò che è documentato e ciò che richiede una decisione del curatore.
+4. Registrare binding nel Catalog, sincronizzare schema e predisporre il percorso
+   di revisione/consolidamento e preprocessing dei workspace selezionati.
+5. Integrare nel setup la scelta opzionale dei dataset e mostrare per ciascuno
+   caricamento, configurazione, Evidence e stato di utilizzabilità.
+6. Verificare tutte le sette selezioni non vuote dei tre esempi, la riesecuzione e
+   gli errori di download/importazione. Collaudare una domanda reale per ciascun
+   esempio installato, poi arresto e riavvio, prima su Windows.
+
+La selezione opzionale comprende anche la possibilità di installare ThothII senza
+esempi. Nessun download massivo, caricamento database o implementazione del setup
+è stato eseguito durante questa proposta.

docs/plans/2026-09-27-example-databases-prd.md

@@ -0,0 +1,402 @@
+# PRD — Database di esempio per ThothII
+
+Data: 2026-09-27. Stato: requisiti D1–D8 approvati tramite `grill-with-docs`;
+implementazione rinviata su richiesta dell'utente; non iniziata.
+Branch di progettazione: `codex/benchmark-examples`.
+
+Il branch conserva la progettazione per una ripresa successiva. La definizione
+della procedura di installazione prosegue separatamente su
+`codex/guided-standalone-install`; non deve presumere che la CLI o i database di
+esempio descritti qui siano già disponibili.
+
+Questo PRD raccoglie i requisiti correnti e sostituisce, in caso di divergenza,
+le proposte nella [nota esplorativa](2026-09-27-benchmark-examples.md).
+Gli aspetti tecnici da verificare prima del rilascio sono distinti dalle decisioni
+di prodotto approvate e non attestano funzionalità già implementate.
+
+## Problema e risultato desiderato
+
+Chi installa ThothII deve poter scegliere e caricare uno, due o tre database di
+esempio, ottenendo dati reali, schema commentato, Evidence disponibili e un documento
+di domande per esercitarsi. Il percorso deve funzionare anche dopo l'installazione,
+senza obbligare a reinstallare ThothII o a conoscere la sua architettura interna.
+
+La distribuzione avviene dal repository dei workspace: oltre alle definizioni dei
+workspace, il repository ospita una cartella `examples/` con la CLI e quanto serve
+a scaricare e predisporre gli esempi su richiesta. Il normale aggiornamento del
+repository non deve eseguire importazioni.
+
+Il repository pubblico ThothII su `git.tylconsulting.it` deve rimandare al repository
+pubblico dedicato agli esempi, ospitato su Gitea e gestito da TYL Consulting.
+L'URL esatto di destinazione resta da definire; non si presume che debba coincidere
+con l'istanza Gitea del repository ThothII. README e documentazione di installazione
+devono rendere reperibili CLI, workspace e istruzioni dal repository principale.
+
+ThothII ha un processo human in the loop. Le domande sono spunti didattici, senza
+risposte SQL da riprodurre, punteggi, classifiche o confronto automatico col benchmark.
+
+## Requisiti confermati
+
+| ID | Requisito |
+| --- | --- |
+| R1 | Tre esempi: BIRD Financial, BIRD European Football, Spider 2.0-Lite F1. |
+| R2 | Selezione di uno, due o tutti e tre; gli esempi sono facoltativi. |
+| R3 | Caricare dati e schema PostgreSQL, inclusi commenti di tabelle e colonne. |
+| R4 | Accompagnare ogni esempio con le Evidence disponibili e la loro provenienza, curate prima del rilascio e indicizzate durante il caricamento. |
+| R5 | Fornire le domande disponibili in un documento leggibile per esercitarsi. |
+| R6 | Escludere gli SQL target dei benchmark dal prodotto distribuito agli utenti. |
+| R7 | Verificare esplicitamente la conversione dei tipi e dei valori verso PostgreSQL. |
+| R8 | Distribuire una CLI attraverso il repository dei workspace, nella cartella degli esempi. |
+| R9 | Consentire il caricamento tramite CLI autonoma dopo l'installazione e richiamare la stessa procedura come ultimo passo facoltativo del setup. |
+| R10 | Collaudare Windows, poi Omarchy, infine macOS, in tre passaggi separati. |
+| R11 | Distribuire pacchetti PostgreSQL già convertiti e verificati, con ricetta di conversione riproducibile. Valutare conversione locale solo per fonti non redistribuibili. |
+| R12 | Concludere con workspace subito utilizzabili: dati, commenti, Evidence curate, metadati sincronizzati e indicizzazione completata. |
+| R13 | La procedura deve prevedere una copia indipendente del repository degli esempi, senza memoria Git dell'originale, oppure uno scaricamento con accesso al repository pubblico in sola lettura. Workspace ed Evidence locali restano modificabili; nessuna credenziale o operazione di scrittura verso l'originale. |
+
+DDL, comandi di importazione e controlli tecnici SQL fanno parte del caricatore;
+R6 riguarda le soluzioni alle domande dei benchmark.
+
+## Perimetro dei tre esempi
+
+| Esempio | Percorso didattico | Materiale semantico disponibile |
+| --- | --- | --- |
+| Financial | Iniziale | Descrizioni BIRD, codifiche, annotazioni Evidence associate ai quesiti. |
+| European Football | Intermedio | Descrizioni BIRD, significato degli indicatori e annotazioni Evidence. |
+| F1 | Avanzato | Metadati Spider 2.0-Lite e documenti di dominio, fra cui sorpassi e tipi di giro. |
+
+Questa progressione è didattica, non una misura delle prestazioni di ThothII.
+La maggiore complessità di F1 non implica una copertura semantica completa:
+le lacune vanno dichiarate nel materiale di accompagnamento.
+
+Le fonti sono SQLite e documentazione separata. I CSV BIRD delle descrizioni non
+sono i dati delle tabelle. La dimensione PostgreSQL, inclusi indici e spazio
+temporaneo di caricamento, deve essere misurata durante la preparazione; non si
+deduce dalla sola dimensione SQLite. Le misure sorgente sono nella
+[ricerca sulle dimensioni](../research/2026-09-27-example-database-sizes.md).
+
+## Architettura di riferimento
+
+ThothII include già il servizio PostgreSQL `catalog-db`; il database applicativo
+è `thothii_catalog`. Il progetto propone di usare la stessa istanza per tre database
+di esempio distinti, senza mescolare le loro tabelle con quelle applicative.
+
+Il contratto corrente associa un database a un workspace: il pacchetto contiene
+quindi tre workspace, ciascuno con il proprio database e un singolo schema
+applicativo. Non è previsto un cambiamento verso workspace multi-database.
+
+La CLI di importazione usa credenziali di caricamento separate dalle credenziali
+in sola lettura con cui ThothII interroga gli esempi. Non riutilizza il ruolo runtime
+del Metadata Catalog per creare o caricare database. I segreti restano locali,
+fuori dal repository, dai manifest pubblici e dai log.
+
+Il PostgreSQL interno non richiede l'esposizione di una porta sull'host: il
+caricatore deve poter operare nella rete dello stack. Una connessione a un server
+PostgreSQL alternativo è un'eventuale estensione, non un requisito iniziale.
+
+## Distribuzione e contenuti
+
+Struttura illustrativa, da adattare alle convenzioni del repository prescelto:
+
+```text
+thoth-workspaces.yaml
+examples/
+  README.md
+  cli/
+  manifests/
+    financial.yaml
+    european-football.yaml
+    f1.yaml
+  docs/
+    financial-practice.md
+    european-football-practice.md
+    f1-practice.md
+example-financial/
+  workspace.yaml
+  evidence/
+    source/
+    curated/
+example-football/...
+example-f1/...
+```
+
+La Source Evidence rimane nel percorso canonico `<workspace-id>/evidence`;
+il documento di esercitazione è esterno al corpus delle Evidence. Il solo fatto
+di trovarsi nel repository non deve rendere le domande regole di dominio ricercabili.
+
+**Adeguamento necessario in ThothII:** il lettore attuale considera workspace tutte
+le directory alla radice, eccetto `workspace-docs`, e ne verifica la corrispondenza
+con il catalogo. Una nuova `examples/` non è quindi accettata automaticamente.
+Il sottoprogetto deve estendere esplicitamente questo contratto per riconoscerla
+come directory ausiliaria, preservando la validazione dei veri workspace;
+non deve registrarla come workspace fittizio. Riferimenti:
+`backend/src/workspaces/git-repository.ts:212` e
+`backend/src/workspaces/registry.ts:515`.
+
+Nel repository Git risiedono CLI, manifest, documentazione e definizioni dei
+workspace. Gli archivi voluminosi dei dati sono scaricati su richiesta da URL
+versionati, con checksum, cache e attribuzioni. Il luogo di pubblicazione dei
+pacchetti derivati dipende dalla decisione sulla modalità di conversione e dai
+diritti di redistribuzione delle singole fonti: la licenza del codice di un
+benchmark non prova da sola la licenza di tutti i dati inclusi.
+
+Ogni manifest identifica almeno: esempio e workspace, versione del pacchetto,
+revisioni e URL delle fonti, file da estrarre, checksum, licenze/attribuzioni,
+versione della conversione, compatibilità PostgreSQL/ThothII, inventario degli
+artefatti e risultati attesi dei controlli. Versioni e nomi non sono ricavati
+silenziosamente da un riferimento mobile come `main`.
+
+La verifica delle fonti del 2026-09-27 ha rilevato CC BY-SA 4.0 nella dataset card
+BIRD e MIT per software/documentazione nel repository Spider2. Questo non chiarisce
+da solo la redistribuibilità di ciascun database fornito negli archivi esterni:
+per i tre dump PostgreSQL lo stato è ancora da verificare, non un divieto accertato.
+Registrare licenza dichiarata, fonte e stato della verifica separatamente per dati,
+descrizioni, Evidence, domande e codice. La verifica sulla versione esatta è una
+condizione di pubblicazione dei pacchetti; la conversione locale rimane l'eccezione
+prevista da D2. Fonti: [card BIRD](https://huggingface.co/datasets/birdsql/bird_mini_dev),
+[repository BIRD](https://github.com/bird-bench/mini_dev),
+[licenza Spider2](https://github.com/xlang-ai/Spider2/blob/main/LICENSE) e
+[download Spider2-Lite](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md).
+
+## Schema commentato e conversione
+
+Per ogni database si prepara un contratto di conversione per tabella e colonna,
+fondato sull'ispezione sia dello schema sia dei valori effettivi. Non basta
+tradurre il tipo dichiarato da SQLite, che può contenere valori eterogenei.
+
+| Area | Regola di accettazione |
+| --- | --- |
+| Interi e identificatori | Range compatibili, nessun overflow; i codici con zeri iniziali restano codici. |
+| Decimali e floating point | Precisione e scala dichiarate; nessun arrotondamento silenzioso. |
+| Date e orari | Formato, granularità e timezone documentati; non inventare una timezone. |
+| Durate | Non confonderle con orari del giorno; rappresentazione e unità esplicite. |
+| Booleani e categorie | Conversione solo con codifiche verificate; distinguere sconosciuto e falso. |
+| Null e testo | Distinguere NULL, stringa vuota e sentinelle; preservare Unicode, virgole e newline. |
+| Colonne senza tipo o miste | Profilazione completa e decisione esplicita; errore comprensibile se non conformi. |
+| Identificatori SQL | Mapping stabile e quoting coerente per maiuscole, parole riservate e caratteri speciali. |
+| PK, FK e indici | Separare vincoli presenti, relazioni documentate e relazioni inferite; verificare prima di imporre. |
+| Contenuti strutturati | Conservare il significato di XML/JSON/testi complessi senza trasformazioni non documentate. |
+
+Ogni cambiamento rispetto alla sorgente compare in un rapporto di conversione.
+Per casi anomali non sono ammessi scarto di righe o sostituzione con NULL senza
+una regola esplicita e verificata. I controlli confrontano conteggi e valori
+normalizzati per tabella; un solo confronto dei conteggi non basta.
+
+Le descrizioni disponibili diventano veri `COMMENT ON TABLE` e
+`COMMENT ON COLUMN` nel database PostgreSQL, mantenendo provenienza e segnalando
+le descrizioni mancanti. Eventuali integrazioni redazionali sono distinte dalle
+descrizioni originali. Questi commenti devono essere visibili anche nel Metadata
+Catalog usato da ThothII; la sola presenza dei commenti in PostgreSQL non soddisfa
+il requisito se la sincronizzazione del Catalog li ignora.
+
+Il percorso esiste già: `backend/src/catalog/schema-introspector.ts:84` e `:106`
+leggono `pg_description`; `metadata-snapshot.ts:52` applica la precedenza
+descrizione curata, descrizione generata, commento sorgente. Il collaudo deve
+considerare questa precedenza: non cancellare una descrizione curata per far
+apparire un commento importato.
+
+## Evidence e documento di esercitazione
+
+Le fonti documentali e le annotazioni Evidence sono raccolte senza introdurre
+regole inventate. Un'annotazione specifica di una domanda conserva il contesto
+necessario: non diventa automaticamente una regola valida per tutto il database.
+Duplicati e conflitti vengono riconciliati conservando i riferimenti originali.
+
+L'archivio distingue Source Evidence e Curated Evidence nel formato supportato
+da ThothII. La curation avviene prima del rilascio: il pacchetto contiene le fonti
+e le unità curate, con riferimenti verificabili e lacune dichiarate. I file originali
+non vengono presentati come Evidence già revisionate. Qdrant contiene la proiezione
+ricercabile, non sostituisce l'archivio delle Evidence. L'utente finale può modificare
+e arricchire la curation, ma non deve completarla per iniziare a usare l'esempio.
+
+Il documento di esercitazione contiene domande disponibili, fonte e identificativo,
+raggruppamento tematico, eventuali note sui limiti dei dati e riferimenti utili.
+Non contiene soluzioni SQL né risposte attese per il confronto automatico.
+Se necessario, si adattano i riferimenti ai nomi PostgreSQL, rendendo riconoscibile
+la modifica. Guide, domande e contenuti semantici curati sono disponibili in italiano
+e inglese, conservando gli originali e rendendo riconoscibili le traduzioni;
+gli identificatori SQL restano invariati. Le rappresentazioni linguistiche di una
+stessa Evidence non devono duplicarne il risultato nella ricerca.
+
+Gli archivi originali possono includere SQL target. L'estrazione per il prodotto
+ammette solo i campi necessari a schema, documentazione, Evidence e domande;
+gli SQL target non entrano nei workspace, negli indici o nei documenti didattici.
+
+## Comportamento della CLI
+
+L'interfaccia esatta sarà definita dopo le decisioni di questo PRD. Le capacità
+richieste sono: elencare gli esempi e i prerequisiti, scegliere un sottoinsieme,
+scaricare/verificare, caricare, collegare i workspace e mostrare lo stato per esempio.
+
+1. Individuare l'installazione e verificare compatibilità, servizi e spazio.
+2. Risolvere i manifest e mostrare cosa verrà caricato per gli esempi scelti.
+3. Scaricare solo i pacchetti necessari; riutilizzare gli archivi condivisi in cache.
+4. Verificare ed estrarre il pacchetto PostgreSQL già convertito; l'eventuale
+   conversione locale eccezionale deve essere dichiarata dal manifest.
+5. Caricare in un database di preparazione e verificarne dati, tipi, vincoli e commenti.
+6. Rendere disponibile il database verificato e registrare il binding nel Catalog.
+7. Sincronizzare metadati, importare le Evidence già curate ed eseguire
+   consolidamento/preprocessing per rendere il workspace subito utilizzabile.
+8. Fornire un riepilogo per esempio, il documento con le domande e il prossimo passo.
+
+Lo stato deve distinguere almeno dati caricati, metadati sincronizzati, Evidence
+disponibili, indicizzazione completata e workspace pronto. Un download concluso
+non equivale a un esempio utilizzabile. Se gli esempi hanno esiti diversi, il
+riepilogo deve mostrare successi e fallimenti separatamente.
+
+La riesecuzione della stessa versione non duplica dati e non sovrascrive le
+Evidence modificate dall'utente. Un errore non sostituisce un database funzionante;
+lo stato permette di riprendere dalle fasi completate. Il preprocessing corrente
+non è internamente resumable: in caso di errore quella fase viene rieseguita.
+Aggiornamento di versione, ripristino e rimozione distruttiva richiedono operazioni
+esplicite distinte dalla normale installazione e sono esclusi dalla prima versione
+della CLI, che comprende elenco/selezione, installazione, verifica e ripresa dopo errore.
+
+L'integrazione deve usare le API esistenti per creazione del database nel Catalog,
+binding e secret store (`backend/src/routes/catalog-databases.ts`), con
+autenticazione e permessi appropriati. La sincronizzazione dello schema è un
+run distinto, con conferma esplicita (`backend/src/routes/catalog-schema.ts:189`
+e `:223`): il progetto deve definire come presentare o gestire quella conferma
+senza aggirarne il contratto. `workspace preprocess run` ed Evidence consolidate
+sono già disponibili come CLI, ma non creano binding o credenziali per conto del
+caricatore. Si veda [il contratto preprocessing](../contracts/workspace-preprocessing-cli.md).
+
+## Collaudo e condizioni di completamento
+
+- Ogni esempio ha un inventario verificato di schema, dati, commenti, Evidence e domande.
+- Il repository con `examples/` supera la validazione e mantiene i controlli
+  sulle directory dei workspace; nessun file della CLI viene eseguito dal pull.
+- Tutte le sette selezioni non vuote producono esclusivamente gli esempi scelti.
+- La selezione di nessun esempio non ostacola l'installazione di ThothII.
+- Si verificano conversione dei valori, vincoli, commenti e propagazione al Catalog.
+- Il ruolo di interrogazione può leggere i dati e non può modificarli.
+- Interruzione del download, checksum errato, errore d'importazione e spazio
+  insufficiente producono uno stato recuperabile e non danneggiano esempi esistenti.
+- Ripetere un'installazione completata non altera dati né curation locale.
+- La copia indipendente non contiene storia Git o relazione di fork dell'originale,
+  né remote verso di esso; mantiene versione, checksum, licenze e attribuzioni.
+- Il percorso di download non richiede credenziali di scrittura verso il repository
+  pubblico e non esegue push. In entrambe le modalità l'utente può modificare
+  workspace ed Evidence locali e continuare a usarli dopo il riavvio.
+- Una sessione reale può interrogare ciascun esempio, con Evidence reperibili;
+  non è richiesto riprodurre l'SQL di un benchmark.
+- Ogni workspace risulta subito utilizzabile anche dopo riavvio; le Evidence
+  curate sono effettivamente reperibili e non solo presenti sul filesystem.
+- Primo rilascio verificato su Windows/WSL2 e Docker Desktop; secondo su Omarchy;
+  terzo su macOS. Nessuna dichiarazione di supporto a una tappa non ancora verificata.
+
+La proposta è eseguire conversione/caricamento in container, senza introdurre
+Python o Node obbligatori sull'host dell'utente. Il metodo di avvio/download della
+CLI resta da precisare in base alla scelta dei pacchetti.
+
+## Decisioni approvate con grill-with-docs
+
+Approvazione dell'utente del 2026-09-27: «ok a tutto», riferita a D1, D2 e D3.
+Nel round successivo l'utente approva D4 con precisazione della distribuzione Gitea,
+D5 e D7. Dopo il chiarimento approva anche D6, ribadendo che chi installa deve
+trovare tutto pronto, e aggiunge D8 sulla copia autonoma o sul download in sola lettura.
+
+| ID | Decisione | Esito approvato |
+| --- | --- | --- |
+| D1 | Quando proporre il caricamento? | CLI autonoma dopo il setup, richiamabile anche come ultimo passo facoltativo dello stesso setup. |
+| D2 | Dove convertire le sorgenti verso PostgreSQL? | Preparare e verificare pacchetti PostgreSQL versionati nella fase di rilascio; la CLI dell'utente scarica e carica. Conservare la ricetta di conversione riproducibile. Se una fonte non è redistribuibile, valutarne la conversione locale. |
+| D3 | Quanto deve essere pronto l'esempio dopo il caricamento? | Dati, commenti e Evidence curate in anticipo, già sincronizzate e indicizzate, per consentire subito una sessione; curation successiva resta disponibile all'utente. |
+| D4 | Repository di distribuzione | Il repository pubblico ThothII su git.tylconsulting.it rimanda a un repository pubblico dedicato agli esempi su Gitea gestito da TYL Consulting. Per installazioni con un repository proprio, il curatore integra i contenuti degli esempi in quel repository. Nessun nuovo supporto multi-repository in questo sottoprogetto. |
+| D5 | Lingua dei contenuti | Guide, domande e contenuti semantici curati in italiano e inglese; originali conservati, traduzioni riconoscibili e identificatori SQL invariati. Nessuna duplicazione della stessa Evidence nella ricerca. |
+| D6 | Preparazione e verifica delle Evidence | Il progetto prepara e controlla i contenuti; all'utente vengono sottoposte solo ambiguità o conflitti non risolvibili dalle fonti, con una proposta concreta. Chi installa riceve tutto pronto e non deve revisionare le Evidence per iniziare. |
+| D7 | Prima versione della CLI | Elenco/selezione, installazione, verifica e ripresa dopo errore. Aggiornamento di versione, reset e disinstallazione rimandati; nessuna sostituzione automatica di esempi modificati. |
+| D8 | Copia autonoma e sola lettura | Copia indipendente senza storia/remote/relazione di fork dell'originale, oppure scaricamento dal repository pubblico in sola lettura. Il limite riguarda la scrittura sul repository originale: workspace ed Evidence locali rimangono modificabili. Versioni, licenze e attribuzioni sono conservate. |
+
+La risposta «1» dell'utente conferma per D8 la sola lettura remota e la modificabilità locale.
+Nome e URL del repository destinazione saranno definiti prima della pubblicazione.
+Interfaccia CLI, autenticazione e custodia dei segreti saranno definite nella
+specifica tecnica coerentemente con i contratti esistenti. Le verifiche tecniche
+e dei diritti sulle fonti sono lavoro del progetto e non domande demandate all'utente.
+
+## Contesto del secondo round e chiarimento D6
+
+La verifica locale ha individuato il repository PSD privato, mentre i template
+generici riportano un URL esemplificativo. Non è stato individuato un repository
+concreto già destinato agli esempi. L'installazione supporta una sola sorgente Git:
+la scelta di un repository per gli esempi non deve sostituire implicitamente il
+repository già configurato in un'installazione esistente.
+
+D6 riguarda la verifica del significato delle Evidence adattate dalle fonti:
+per esempio, un'annotazione riferita a una singola domanda non può diventare una
+regola generale senza supporto documentale. Non riguarda la scrittura da zero delle
+Evidence da parte dell'utente o una revisione a ogni installazione.
+
+Chiarimento approvato per D6: il progetto prepara i contenuti, ne
+controlla provenienza, coerenza e adattamento a PostgreSQL; all'utente vengono
+sottoposte solo ambiguità o conflitti non risolvibili dalle fonti, con una proposta
+concreta. I punti irrisolti restano segnalati ed esclusi dalle regole pubblicate
+come verificate. L'utilizzatore finale riceve il materiale già curato.
+
+## D8 — Copia del repository e permessi
+
+Richiesta dell'utente: «fork del repository senza memoria dell'originale, o lo
+scarico in locale ma senza diritti di scrittura». Il risultato deve restare pronto
+all'uso e non richiedere un lavoro di curation a chi installa.
+
+La proposta tecnica per la copia indipendente è estrarre un rilascio verificato
+senza la directory `.git` originaria; se il runtime richiede Git, inizializzare
+una nuova storia locale, senza remote verso l'originale né associazione di fork
+sulla piattaforma. Un fork ordinario che conserva storia e relazione col repository
+originario non soddisfa questo significato di indipendenza. L'eventuale pubblicazione
+in un repository personale è un'operazione separata, non implicita nell'installazione.
+
+Versione del pacchetto, checksum, licenze e attribuzioni rimangono nel manifest e
+nella documentazione: l'assenza di memoria Git non elimina la provenienza dei dati
+e delle Evidence. Nessun aggiornamento automatico deve sovrascrivere una copia
+personalizzata.
+
+Per il percorso di download, la scelta approvata è accesso anonimo in sola
+lettura al repository pubblico, senza credenziali di scrittura e senza operazioni
+di push. File e archivio locale delle Evidence restano modificabili dall'utente.
+Il filesystem locale non è reso globalmente in sola lettura.
+
+**Adeguamento necessario nel runtime:** la copia senza `.git` non è oggi una sorgente
+completa per ThothII. Il lettore richiede `HEAD` e file committati
+(`backend/src/workspaces/git-repository.ts:198`); il refresh esegue fetch del branch
+da `origin` e rifiuta checkout sporchi o divergenze (`:467–485`). Il solo `git init`
+senza remote non completa quindi il percorso corrente.
+
+La specifica deve prevedere una sorgente locale autonoma, oppure una nuova copia
+Git locale usata come sorgente del checkout gestito: eventuali riferimenti Git
+interni all'installazione non devono puntare al repository pubblico originale.
+Il backend già accetta percorsi Git locali assoluti/file URL (`:60–64`), ma setup,
+configurazione e aggiornamento devono supportare coerentemente il percorso scelto.
+Le due modalità devono funzionare senza chiedere all'utente di configurare Git.
+
+Il download HTTPS anonimo è compatibile con il consumo remoto del backend; va
+verificato anche nel bootstrap dell'installazione. Il checkout gestito non è la
+cartella da sporcare con modifiche manuali: la procedura deve rendere esplicita una
+copia locale modificabile dei workspace e gestirne l'attivazione senza push verso
+l'originale. L'archivio locale delle Evidence è già separato e modificabile.
+Riferimenti: `docs/contracts/workspace-evidence-v3.md:218` e il contratto delle
+Evidence curate. I controlli di integrità del checkout non vanno disabilitati per
+ottenere la modificabilità richiesta.
+
+## Passaggio alla specifica tecnica
+
+La definizione dei requisiti è conclusa con D1–D8. La specifica dovrà tradurli in
+questi blocchi verificabili, prima dell'implementazione:
+
+1. Contratto del repository: cartella `examples/`, distribuzione pubblica e copia
+   autonoma o accesso remoto in sola lettura, con personalizzazioni locali persistenti.
+2. Preparazione dei tre pacchetti: fonti e diritti verificati, conversione di
+   schema/dati/tipi, commenti, Evidence curate e materiale didattico bilingue.
+3. CLI: download, verifica, importazione isolata, binding, sincronizzazione e
+   indicizzazione, stato e ripresa dopo errore, senza push verso l'originale.
+4. Integrazione facoltativa nel setup, collegamenti fra repository e documentazione.
+5. Collaudo Windows, successivamente Omarchy, infine macOS.
+
+## Riferimenti
+
+- [BIRD mini-dev: dati e documentazione](https://github.com/bird-bench/mini_dev).
+- [Dataset card BIRD](https://huggingface.co/datasets/birdsql/bird_mini_dev).
+- [Spider 2.0-Lite: download e formati](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite).
+- [Ricerca sui candidati e sulle Evidence](../research/2026-09-27-spider2-lite-evidence-candidates.md).
+- [Contratto workspace/Evidence](../contracts/workspace-evidence-v3.md),
+  [modulo Evidence](../evidence.md), [glossario](../../CONTEXT.md),
+  [ADR 0001 — Metadata Catalog](../adr/0001-postgres-metadata-catalog.md),
+  [ADR 0003 — binding locali](../adr/0003-installation-local-database-bindings.md).

docs/research/2026-09-27-example-database-sizes.md

@@ -0,0 +1,49 @@
+# Dimensioni dei sei database candidati
+
+Verifica del 27 settembre 2026 tramite lettura HTTP Range della directory centrale
+degli archivi ZIP ufficiali. I valori sono le dimensioni non compresse dichiarate
+per i singoli file, non il consumo misurato dopo importazione in PostgreSQL.
+GB e MB sono decimali: 1 GB = 1.000.000.000 byte.
+
+| Database | Formato | Byte | GB | MB |
+| --- | --- | ---: | ---: | ---: |
+| Financial, BIRD Mini-Dev | SQLite | 71.294.976 | 0,071295 | 71,295 |
+| European Football, BIRD Mini-Dev | SQLite | 597.754.880 | 0,597755 | 597,755 |
+| F1, Spider 2.0-Lite | SQLite | 74.940.416 | 0,074940 | 74,940 |
+| Shopify, Spider 2.0-DBT, shopify001 | DuckDB iniziale | 19.935.232 | 0,019935 | 19,935 |
+| QuickBooks, Spider 2.0-DBT, quickbooks001 | DuckDB iniziale | 50.606.080 | 0,050606 | 50,606 |
+| Workday, Spider 2.0-DBT, workday001 | DuckDB iniziale | 28.323.840 | 0,028324 | 28,324 |
+| Totale | | 842.855.424 | 0,842855 | 842,855 |
+
+## Provenienza
+
+- [BIRD Mini-Dev ZIP](https://bird-bench.oss-cn-beijing.aliyuncs.com/minidev.zip),
+  collegato dal [repository ufficiale](https://github.com/bird-bench/mini_dev).
+  Archivio: 800.943.648 byte; Last-Modified 20 giugno 2024.
+  Entry: `minidev/MINIDEV/dev_databases/financial/financial.sqlite` e
+  `minidev/MINIDEV/dev_databases/european_football_2/european_football_2.sqlite`.
+- [Spider database locali](https://drive.google.com/file/d/1coEVsCZq-Xvj9p2TnhBFoFTsY-UoYGmG/view),
+  collegati dal [README Lite](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md).
+  Archivio: 456.643.204 byte; entry `f1.sqlite`.
+- [DBT_start_db.zip](https://drive.google.com/file/d/1N3f7BSWC4foj-V-1C9n8M2XmgV7FOcqL/view),
+  collegato dal [README DBT](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/README.md).
+  Archivio: 377.819.033 byte; Last-Modified 19 dicembre 2024.
+  Entry: `shopify001/shopify.duckdb`, `quickbooks001/quickbooks.duckdb`,
+  `workday001/workday.duckdb`.
+
+I pesi degli archivi completi non sono quelli dei soli database selezionati:
+contengono anche altri esempi. Non sommarli alla tabella salvo voler conservare
+localmente tutti i pacchetti originali.
+
+Per confronto, l'archivio ufficiale `dbt_gold.zip` contiene file corrispondenti di
+22.032.384 byte (Shopify), 54.013.952 byte (QuickBooks) e 28.848.128 byte (Workday).
+Sono versioni di risultato del benchmark, non la base scelta per la tabella e non
+una previsione del consumo finale di ThothII.
+
+## Limiti
+
+Il totale esclude descrizioni, Evidence, CSV esportati, indici aggiuntivi, log,
+PostgreSQL, Qdrant, immagini Docker e modelli locali. La conversione può modificare
+sensibilmente l'occupazione. Non sono state estratte tutte le tabelle né contate
+le righe: il peso del file non prova che tutte le tabelle documentate siano popolate.
+La complessità di schema e dominio non implica grandi volumi nei dati dimostrativi.

docs/research/2026-09-27-spider2-dbt-evidence-candidates.md

@@ -0,0 +1,117 @@
+# Candidati Spider 2.0-DBT con documentazione di dominio
+
+Ricerca del 27 settembre 2026. Obiettivo: scegliere un database locale complesso,
+con materiale da curare come Source Evidence di ThothII. Non vengono usate
+domande del benchmark, SQL attesi o punteggi come criterio di selezione.
+
+## Raccomandazione
+
+**Shopify è il candidato da verificare per primo**, perché combina commercio,
+pagamenti, rimborsi, inventario e ordini con documentazione dei significati e
+delle misure. Offre inoltre un dominio diverso dal Financial BIRD già proposto.
+QuickBooks è una valida alternativa se si preferisce la contabilità; Workday
+se si preferiscono personale e storia organizzativa. Questa priorità è una
+valutazione per il progetto, non una classificazione ufficiale Spider.
+
+| Progetto Spider 2.0-DBT | Tabelle sorgente dichiarate | Coppie tabella/colonna descritte e distinte | Database locale indicato dal profilo |
+| --- | ---: | ---: | --- |
+| Shopify, `shopify001` | 34 | 578 | `shopify.duckdb` |
+| QuickBooks, `quickbooks001` | 40 | 426 | `quickbooks.duckdb` |
+| Workday, `workday001` | 21 | 436 | `workday.duckdb` |
+
+Conteggi ricavati analizzando i rispettivi YAML `sources[].tables[]` e le
+descrizioni delle colonne; **non sono un'ispezione delle tabelle materializzate
+nei file DuckDB**. Alcune tabelle possono essere opzionali. Shopify ha 581
+dichiarazioni di colonna, ma tre sono duplicate: `order.total_shipping_price_set`,
+`order_line.tax_code`, `order_line_refund.subtotal_set`. I conteggi comprendono
+anche metadati tecnici e riferimenti `doc(...)`: **non equivalgono a un numero
+di Evidence Unit**. Sono esclusi i pacchetti di utilità generica dbt.
+Fonti: [Shopify schema](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/dbt_packages/shopify_source/models/src_shopify.yml),
+[QuickBooks schema](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/dbt_packages/quickbooks_source/models/src_quickbooks.yml),
+[Workday schema](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/models/staging/src_workday.yml).
+
+## Shopify: commercio e operazioni
+
+Lo schema documenta ordini e righe d'ordine, clienti, prodotti e varianti,
+transazioni, rimborsi, rettifiche, spedizioni, imposte, sconti, inventario,
+sedi e checkout abbandonati. Le descrizioni specificano sia la granularità
+delle entità sia il significato dei campi. Esempi di materiale semanticamente
+utile: il subtotale è dopo gli sconti e prima di spedizione, imposte e mance;
+`processed_at` è la data usata nei report analitici; l'ID API dell'ordine è
+distinto dal numero mostrato al cliente; valuta del negozio e valuta presentata
+al cliente hanno ruoli distinti. Le tre dichiarazioni duplicate richiedono
+normalizzazione prima dell'importazione documentale.
+[Dizionario sorgente](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/dbt_packages/shopify_source/models/src_shopify.yml).
+
+Il progetto aggiunge definizioni di modelli analitici, inclusi ordini, coorti
+clienti e aggregazioni giornaliere del negozio; il solo `models/shopify.yml`
+ne dichiara 10. Sono modelli dbt, da tenere distinti dalle 34 sorgenti e dalle
+tabelle fisiche effettivamente disponibili. Queste definizioni sono un secondo
+livello di materiale per Evidence su granularità e metriche.
+[Modelli analitici](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/models/shopify.yml).
+
+Il profilo indica esplicitamente DuckDB, percorso `./shopify.duckdb`, schema
+`main`. Non è necessario collegare un negozio Shopify reale per leggere il
+database distribuito dal progetto.
+[Profilo](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/profiles.yml).
+
+## QuickBooks: contabilità e documenti commerciali
+
+Le 40 sorgenti dichiarate coprono conti, clienti, fornitori, fatture e righe,
+pagamenti, depositi, acquisti, ordini, note di credito, trasferimenti e
+registrazioni contabili. Il dizionario definisce classificazioni dei conti e
+tipi delle righe fattura, distinguendo elementi di vendita, descrizione,
+sconto e subtotale.
+[Dizionario sorgente](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/dbt_packages/quickbooks_source/models/src_quickbooks.yml).
+
+La documentazione del libro mastro contiene una regola esplicita utile come
+Evidence: l'importo aumenta il conto quando il tipo di movimento corrisponde
+al lato di incremento del conto, e lo diminuisce altrimenti. Definisce inoltre
+importi convertiti e saldi progressivi. `models/quickbooks.yml` dichiara 29
+modelli tra intermedi e analitici: non sono 29 ulteriori tabelle sorgente
+garantite. I due file di documentazione contengono complessivamente 120 blocchi
+`docs` (68 nel progetto, 52 nel pacchetto sorgente); anche qui sono definizioni
+da selezionare e curare, non 120 Evidence Unit già validate.
+[Modelli e regole contabili](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/models/quickbooks.yml),
+[glossario progetto](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/models/docs.md),
+[glossario sorgente](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/dbt_packages/quickbooks_source/models/docs.md).
+
+Il profilo usa `./quickbooks.duckdb`.
+[Profilo](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/profiles.yml).
+
+## Workday: personale, ruoli e storia organizzativa
+
+Le sorgenti documentate comprendono lavoratori, posizioni, famiglie
+professionali, organizzazioni, assegnazioni e diverse tabelle storiche.
+Il glossario contiene 409 blocchi `docs`; molti sono definizioni brevi di
+attributi, non regole articolate. Fra i concetti documentati figurano FTE
+retribuito e lavorato, stato attivo/cessato, compensi, date di assunzione e
+appartenenze organizzative. La complessità temporale e organizzativa è
+interessante, ma il glossario da solo non giustifica chiamarlo il candidato
+con più Evidence di qualità.
+[Sorgenti](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/models/staging/src_workday.yml),
+[glossario](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/models/docs.md).
+
+Il profilo usa `./workday.duckdb`.
+[Profilo](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/profiles.yml).
+
+## Download e prossimo controllo prima della scelta definitiva
+
+Il README ufficiale fornisce due download Google Drive. Lo script di setup
+attende `DBT_start_db.zip` e `dbt_gold.zip`, estrae i file DuckDB e li distribuisce
+nei progetti e nella suite di riferimento. Per ThothII va scelto consapevolmente
+il contenuto da usare come esempio: non occorre importare il meccanismo di
+valutazione del benchmark. Questa ricerca verifica la pubblicazione del
+percorso di download e la configurazione locale; **non verifica il download
+integrale, dimensioni, righe, licenza dei singoli dati o schema fisico**.
+[README](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/README.md),
+[setup ufficiale](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/setup.py).
+
+Prima di promettere il pacchetto di installazione occorre scaricare il
+candidato, confrontare tabelle e colonne reali con la documentazione,
+verificare copertura delle entità e consistenza dei dati, e scegliere quali
+definizioni diventino Source Evidence. Per PostgreSQL la conversione proposta
+è schema esplicito più dati esportati; CSV sarebbe un formato derivato.
+Vanno preservati tipi numerici, date, valute, valori nulli e contenuti
+strutturati eventualmente presenti, adattando le sole trasformazioni
+necessarie. Non è ancora stato implementato o testato alcun convertitore.

docs/research/2026-09-27-spider2-lite-evidence-candidates.md

@@ -0,0 +1,86 @@
+# Alternative Spider 2.0-Lite per database dimostrativi con Evidence
+
+Verifica del 27 settembre 2026. Il criterio è complessità del database e qualità
+della documentazione di dominio da curare in ThothII, non prestazioni sul benchmark
+né numero di domande pubblicate. Nessun database è stato installato.
+
+## Metodo e limiti
+
+Ispezionati DDL, metadati per tabella e documenti ufficiali in
+[Spider2](https://github.com/xlang-ai/Spider2), revisione osservata
+`cafb867313aab4e674652054198f383cf4018943`. I conteggi sotto sono delle tabelle
+dichiarate nei DDL e delle colonne nei JSON, non un'ispezione dei file SQLite.
+La [procedura ufficiale](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md)
+offre un archivio dei database locali. I database cloud seguono un percorso diverso.
+
+## Candidati locali
+
+| Database | Tabelle / colonne nei metadati | Materiale semantico riscontrato | Valutazione |
+| --- | --- | --- | --- |
+| `E_commerce` | 11 / 70 | Documento RFM; documentazione originale Olist da integrare | Il più coerente dei candidati Lite esaminati per una demo aziendale, ma complessità media |
+| `complex_oracle` | 10 / 140 | Proiezione vendite e conversioni valutarie; dizionario originale Oracle SH da confrontare | Buon caso analitico, meno esteso relazionalmente |
+| `oracle_sql` | 38 / 124 | Documento sul rapporto vendite/media mobile e finestre temporali | Molte tabelle, documentazione semantica allegata troppo parziale |
+| `AdventureWorks` | 13 / 120 | Documentazione originale Microsoft, da riallineare al sottoinsieme Spider | Non confondere questo estratto con l'intero AdventureWorks |
+
+Conteggi ricavati dai DDL e JSON ufficiali: [E_commerce](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/E_commerce),
+[complex_oracle](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/complex_oracle),
+[oracle_sql](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/oracle_sql),
+[AdventureWorks](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/AdventureWorks).
+In tutti i JSON di questi quattro candidati, gli array `description` controllati
+sono vuoti: tipi e righe di esempio non costituiscono da soli un dizionario di dominio.
+
+### E_commerce
+
+Comprende ordini, righe d'ordine, pagamenti, recensioni, prodotti, clienti, venditori,
+geolocalizzazione e lead. Il [documento RFM](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/RFM.md)
+definisce recency, frequency, monetary e undici segmenti con regole di assegnazione.
+Sono fonti concrete di formule e regole, da rivedere e collegare allo schema.
+
+La [fonte originale Olist](https://www.kaggle.com/olistbr/brazilian-ecommerce/metadata)
+fornisce CSV e spiega una distinzione utile: `customer_id` identifica il cliente
+nel contesto dell'ordine, mentre `customer_unique_id` permette di riconoscere acquisti
+ripetuti della stessa persona. La distribuzione Olist di base contiene nove file;
+non equivale automaticamente alle undici tabelle Spider, che includono i lead.
+
+### complex_oracle
+
+Il [documento allegato](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/projection_calculation.md)
+descrive proiezione mensile delle vendite, crescita rispetto all'anno precedente,
+conversione in USD e gestione di cambi mancanti. Lo schema ha vendite e costi con
+dimensioni prodotto, cliente, calendario, canale, promozione e geografia.
+
+Nomi e struttura sono riconducibili al [Sales History di Oracle](https://github.com/oracle-samples/db-sample-schemas/tree/main/sales_history).
+Il suo script `sh_create.sql` contiene 88 commenti `COMMENT ON TABLE/COLUMN` e la
+distribuzione comprende CSV. È materiale aggiuntivo utile, ma ogni corrispondenza
+con lo schema Spider, incluse estensioni come `currency`, va verificata: non si
+deve importare la documentazione dell'originale come se descrivesse automaticamente
+ogni adattamento Spider.
+
+### oracle_sql
+
+Le tabelle coprono magazzino, ordini, confezioni annidate, vendite mensili e altri
+sottodomini eterogenei. Il [documento di calcolo](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/calculation_method.md)
+tratta tre aspetti: rapporto fra vendite e media mobile centrata, finestre di dodici
+mesi e limiti temporali per evitare effetti ai bordi. Questo non documenta in modo
+completo le altre parti del database: sconsigliato come scelta basata sulla sola
+abbondanza di tabelle.
+
+## Alternativa cloud con documentazione più ricca
+
+`ga4` offre tre documenti complementari: [dizionario degli eventi](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/ga4_obfuscated_sample_ecommerce.events.md),
+[dimensioni e metriche](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/ga4_dimensions_and_metrics.md)
+e [categorie delle pagine](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/ga4_page_category.md).
+Coprono campi annidati, classificazione dei canali e regole di interpretazione;
+sono più vicini al requisito semantico. Tuttavia la
+[distribuzione Spider è BigQuery](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/bigquery/ga4):
+molte tabelle sono partizioni giornaliere dello stesso schema logico. Il conteggio
+fisico non è una misura utile di complessità relazionale. Esportazione locale e
+adattamento PostgreSQL sarebbero lavoro aggiuntivo, non un semplice import SQLite.
+
+## Esito
+
+Nessuno dei quattro candidati SQLite esaminati combina da solo schema molto esteso
+e documentazione di dominio completa già pronta. Per cercare una scelta più forte,
+confrontare con i progetti Spider 2.0-DBT nella ricerca separata
+`2026-09-27-spider2-dbt-evidence-candidates.md`. I modelli documentati di dbt non
+vanno confusi con tabelle fisiche già presenti, né le librerie di utility con Evidence.