diff --git a/docs/research/2026-08-23-legacy-thothai-metadata-capabilities.md b/docs/research/2026-08-23-legacy-thothai-metadata-capabilities.md
new file mode 100644
index 00000000..26d2825b
--- /dev/null
+++ b/docs/research/2026-08-23-legacy-thothai-metadata-capabilities.md
@@ -0,0 +1,361 @@
+# Inventario delle funzionalità legacy di gestione metadati di ThothAI
+
+Data: 2026-08-23
+
+Issue: `mptyl/ThothII#6`
+
+Fonte primaria: repository legacy annidato `Thoth/ThothAI`, commit
+`55855de0f18e5cb4bc72f0a2ab0a7317995186dd`.
+
+## Sintesi
+
+La parità funzionale richiesta a ThothII comprende un catalogo dei database, l'inventario
+completo di tabelle, colonne e relazioni fisiche, metadati descrittivi modificabili, relazioni
+logiche, introspezione dello schema, generazione AI di descrizioni, scope, ERD Mermaid,
+documentazione ed esportazioni operative. La UI Django Admin è soltanto l'interfaccia legacy:
+non è un requisito architetturale da riprodurre.
+
+Il flusso AI per le descrizioni è volutamente semplice e va mantenuto tale:
+
+1. l'AI scrive nel campo `generated_comment` della tabella o colonna;
+2. l'utente seleziona gli elementi desiderati;
+3. un'azione copia il testo generato nel campo descrittivo canonico, sovrascrivendolo.
+
+Nel codice esaminato **non esiste un'azione inversa che copi la descrizione canonica in
+`generated_comment`**. Le due azioni inverse presenti sulle colonne copiano invece il nome
+originale nel nome espanso e viceversa. Non risultano proposal, versioni, diff o workflow di
+approvazione: aggiungerli non sarebbe parità con ThothAI.
+
+La parità deve essere di capacità e comportamento utile, non dei difetti del legacy. In
+particolare non vanno replicate esportazioni di password, SQL costruito con identificatori non
+quotati, job in thread daemon, incoerenze CSV e azioni admin non funzionanti.
+
+## 1. Modello dati legacy
+
+### Database
+
+`SqlDb` contiene:
+
+- identità e connessione (`name`, host, tipo motore, nome database, porta, schema, utente e
+  password);
+- configurazione SSH e ambiente (`dev`, `test`, `prod`);
+- lingua per database, scope testuale e JSON, ERD Mermaid, direttive e report GDPR;
+- stato e log separati per generazione commenti tabella/colonna, introspezione, scope, ERD,
+  documentazione e GDPR.
+
+Evidenze: `/Thoth/ThothAI/backend/thoth_core/models.py:298-350`,
+`/Thoth/ThothAI/backend/thoth_core/models.py:355-439`.
+
+I motori dichiarati sono sette: Informix, MariaDB, MySQL, Oracle, PostgreSQL, SQL Server e
+SQLite (`/Thoth/ThothAI/backend/thoth_core/models.py:116-123`).
+
+Il modello `Workspace` collega un solo `SqlDb`; contiene inoltre configurazioni degli agenti e
+duplica parte degli stati operativi (`/Thoth/ThothAI/backend/thoth_core/models.py:731-754`,
+`/Thoth/ThothAI/backend/thoth_core/models.py:847-877`).
+
+### Tabelle e colonne
+
+`SqlTable` contiene nome, descrizione canonica, commento generato e riferimento al database
+(`/Thoth/ThothAI/backend/thoth_core/models.py:454-465`).
+
+`SqlColumn` contiene nome originale, nome espanso, formato dati normalizzato, descrizione
+canonica, commento generato, descrizione dei valori e indicazioni PK/FK testuali
+(`/Thoth/ThothAI/backend/thoth_core/models.py:468-485`).
+
+La cancellazione usa le cascade Django: database → tabelle → colonne e relazioni. Nei modelli
+non sono definite unicità composte per database/tabella/colonna. Ogni database ha un solo
+campo `schema`; tabelle e colonne non portano una propria identità di schema. Questi limiti
+non devono diventare vincoli del nuovo catalogo.
+
+### Relazioni
+
+`Relationship` collega tabella e colonna sorgente a tabella e colonna destinazione
+(`/Thoth/ThothAI/backend/thoth_core/models.py:488-503`). Il metodo
+`update_pk_fk_fields` ricostruisce stringhe descrittive PK/FK sulle colonne coinvolte
+(`/Thoth/ThothAI/backend/thoth_core/models.py:505-526`).
+
+Il form admin verifica che le due tabelle appartengano allo stesso database e che ogni colonna
+appartenga alla tabella selezionata
+(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:19-165`).
+
+Per ThothII occorre distinguere:
+
+- struttura fisica importata dal database, da trattare come inventario non modificabile;
+- descrizioni e metadati semantici, modificabili con CRUD completo;
+- relazioni logiche aggiunte dall'utente, modificabili con CRUD completo.
+
+Questa separazione conserva le capacità utili del legacy senza permettere che la UI alteri o
+falsifichi accidentalmente lo schema fisico osservato.
+
+## 2. Capacità esposte dal Django Admin
+
+La registrazione degli admin fornisce il CRUD Django standard per database, tabelle, colonne e
+relazioni (`/Thoth/ThothAI/backend/thoth_core/admin.py:13-24`). Oltre al CRUD, le azioni
+specifiche sono le seguenti.
+
+### Database
+
+L'admin di `SqlDb` espone:
+
+- export/import CSV;
+- scansione delle tabelle, creazione delle relazioni e introspezione completa;
+- validazione FK e inferenza di relazioni candidate;
+- test della connessione;
+- duplicazione della configurazione;
+- generazione commenti AI per tabelle e colonne;
+- generazione sincrona o asincrona di scope, ERD e documentazione;
+- report GDPR;
+- export della struttura e script SQL dei commenti.
+
+Evidenza: `/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:237-274`.
+
+I campi di configurazione, contenuto e stato sono esposti in fieldset distinti
+(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:275-462`). In ThothII i segreti di
+connessione non devono essere campi ordinari del catalogo né essere restituiti dalle API di
+gestione metadati.
+
+### Tabelle
+
+L'admin delle tabelle permette export/import CSV, introspezione colonne, validazione e pulizia
+PK/FK, copia del commento AI nella descrizione, generazione commenti sincrona/asincrona e
+download dello script SQL (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqltable.py:133-150`).
+
+L'azione di applicazione AI opera solo sulle righe selezionate, ignora commenti generati vuoti
+e sovrascrive direttamente `description`
+(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqltable.py:165-190`).
+
+### Colonne
+
+L'admin delle colonne permette export/import CSV, copia del commento AI nella descrizione,
+copia bidirezionale fra nome originale e nome espanso, validazione FK e generazione AI sulle
+colonne selezionate (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:167-196`).
+
+L'applicazione AI sovrascrive `column_description` soltanto per le colonne selezionate con
+`generated_comment` valorizzato
+(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:219-245`). Le azioni inverse riguardano
+esclusivamente i due campi nome
+(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:247-261`).
+
+### Relazioni
+
+L'admin delle relazioni offre il CRUD standard, filtri e ricerca, export/import e dichiara
+un'azione per aggiornare i campi PK/FK
+(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:219-245`). L'ultima azione è però un
+difetto: `RelationshipAdmin` non implementa il metodo dichiarato; esiste soltanto il metodo
+statico sul model. La capacità da conservare è la ricostruzione coerente degli indicatori, non
+l'azione admin rotta.
+
+## 3. Introspezione e riconciliazione dello schema
+
+Il factory del database manager associa i sette motori ai rispettivi adapter e gestisce anche
+il tunnel SSH (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:77-227`).
+
+L'introspezione legacy:
+
+- riduce i tipi nativi a un insieme generico limitato, con fallback `VARCHAR`
+  (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:237-266`);
+- legge e crea le colonne mancanti, ma non aggiorna tipo o commento di quelle già note
+  (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:269-351`);
+- crea le tabelle mancanti e aggiorna la descrizione di quelle esistenti
+  (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:431-481`);
+- legge le foreign key fisiche, crea al bisogno colonne mancanti e crea relazioni assenti
+  (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:484-641`);
+- esegue l'intero processo nell'ordine tabelle → colonne → relazioni
+  (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:718-891`).
+
+Il comportamento è additivo: gli oggetti scomparsi dal database sorgente non sono eliminati o
+marcati come obsoleti. Per ThothII la capacità richiesta è una scansione completa e
+riconciliabile, con provenienza, data dell'osservazione e stato degli oggetti rimossi o cambiati;
+non la semantica incompleta del refresh legacy.
+
+L'inferenza di relazioni candidate combina convenzioni sui nomi, individuazione euristica delle
+PK e campionamento dei valori, con soglia di corrispondenza del 70%
+(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:605-801`). Deve rimanere una proposta
+esplicita da convalidare, non essere confusa con una foreign key fisica.
+
+## 4. Generazione AI delle descrizioni
+
+### Tabelle
+
+La generazione procede in batch da dieci, utilizza lingua e contesto del database, schema
+osservato, descrizioni disponibili e fino a cinque righe di esempio; il risultato JSON aggiorna
+soltanto `table.generated_comment`
+(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:181-267`,
+`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:269-482`).
+
+### Colonne
+
+La generazione usa contesto della tabella, nomi delle colonne selezionate ed esempi reali, e
+scrive soltanto `column.generated_comment`
+(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:185-280`,
+`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:283-487`).
+
+Provider e modello AI provengono dalla configurazione globale del backend; la lingua è invece
+per database (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/comment_generation_utils.py:156-219`).
+
+### Comportamento di parità da implementare
+
+Il contratto funzionale minimo è esattamente questo:
+
+- due campi per elemento: descrizione canonica e commento generato;
+- comando AI su elementi selezionati o su un insieme più ampio esplicitamente scelto;
+- scrittura/sovrascrittura del solo commento generato;
+- azione separata, su selezione dell'utente, che copia il generato nel canonico;
+- nessuna proposta persistente aggiuntiva, diff obbligatorio, approvazione multilivello o
+  versionamento del testo.
+
+Non è stata trovata una copia `descrizione → commento generato`. Se si desiderasse in futuro,
+sarebbe una nuova capacità, non parità legacy.
+
+## 5. Scope, Mermaid e documentazione
+
+### Scope
+
+La generazione dello scope raccoglie nomi e descrizioni di tabelle e colonne, nome e lingua del
+database, richiede JSON al modello e persiste sia il JSON sia una resa Markdown. Se il JSON non
+è valido conserva il testo grezzo e svuota `scope_json`
+(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_db_scope.py:25-163`).
+
+### ERD Mermaid
+
+L'ERD è prodotto dall'AI usando tabelle, colonne, PK/FK e relazioni. Il codice estrae un blocco
+Mermaid oppure usa la risposta grezza e la salva in `SqlDb.erd`, senza una validazione
+sintattica o semantica preventiva
+(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_erd.py:18-145`).
+
+Il rendering attivo usa un servizio Mermaid locale: health check, POST a `/svg` o `/png`,
+timeout e file temporanei
+(`/Thoth/ThothAI/backend/thoth_ai_backend/mermaid_utils.py:29-72`,
+`/Thoth/ThothAI/backend/thoth_ai_backend/mermaid_utils.py:281-464`). Il servizio Express espone
+`/health`, `/svg` e `/png` ed applica un limite al body
+(`/Thoth/ThothAI/docker/mermaid-service/src/server.js:13-23`,
+`/Thoth/ThothAI/docker/mermaid-service/src/server.js:70-115`). È distribuito come servizio
+Compose autonomo con health check
+(`/Thoth/ThothAI/docker-compose.yml:184-201`).
+
+La vista ERD renderizza il Mermaid memorizzato in SVG tramite tale servizio e poi elimina il
+file temporaneo (`/Thoth/ThothAI/backend/thoth_ai_backend/views.py:227-288`).
+
+### Documento del database
+
+La documentazione HTML combina scope, relazioni, tabelle e colonne. Per le descrizioni usa il
+campo canonico e, quando vuoto, il commento generato
+(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:35-188`).
+
+Il processo di generazione chiede all'AI il diagramma Mermaid, lo salva nell'ERD e costruisce
+deterministicamente l'HTML corrente; l'HTML generato non incorpora il diagramma
+(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:767-922`). La UI espone il
+documento del database del workspace corrente e le route per HTML/PDF ed ERD/PDF
+(`/Thoth/ThothAI/backend/thoth_ai_backend/views.py:86-179`,
+`/Thoth/ThothAI/backend/thoth_ai_backend/urls.py:179-188`).
+
+Per la parità ThothII servono quindi contenuto documentale strutturato, sorgente Mermaid
+persistita e rendering locale. La validazione Mermaid prima della pubblicazione è una
+correzione necessaria, non un cambiamento di scopo.
+
+## 6. Export e comandi operativi
+
+Le capacità utili rilevate sono:
+
+- CSV di tabelle e colonne selezionate
+  (`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:150-195`);
+- export CSV generico dei modelli e della struttura completa
+  (`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:198-261`,
+  `/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:399-569`);
+- script SQL dei commenti per PostgreSQL, SQL Server, MySQL e MariaDB
+  (`/Thoth/ThothAI/backend/thoth_core/admin_utils/sql_comment_script.py:25-316`);
+- comandi `generate_scope` e `generate_documentation`, indirizzabili per workspace, database o
+  tutti i database (`/Thoth/ThothAI/backend/thoth_core/management/commands/generate_scope.py:12-89`,
+  `/Thoth/ThothAI/backend/thoth_core/management/commands/generate_documentation.py:12-89`);
+- export globale e per workspace
+  (`/Thoth/ThothAI/backend/thoth_core/management/commands/export_models.py:19-64`,
+  `/Thoth/ThothAI/backend/thoth_core/management/commands/export_workspace.py:19-96`);
+- aggiornamento delle descrizioni colonna da CSV per workspace
+  (`/Thoth/ThothAI/backend/thoth_ai_backend/management/commands/update_column_descriptions.py:24-92`).
+
+I comandi di importazione dalla produzione legacy sono deliberatamente esclusi da questo
+inventario di parità: costituiscono un progetto CLI `tht` separato, con mapping, validazione e
+cutover propri.
+
+## 7. Esecuzioni asincrone e stato
+
+Scope, ERD, documentazione e commenti possono essere lanciati in background. Il legacy crea
+thread daemon e memorizza task id, stato e log sui modelli
+(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_scope.py:21-62`,
+`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_erd.py:21-30`,
+`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_documentation.py:21-30`,
+`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_table_comments.py:39-87`).
+
+La capacità da mantenere è: operazione lunga non bloccante, esclusione di esecuzioni
+confliggenti, stato osservabile e log. Il meccanismo daemon non è durevole, non permette
+recovery o cancellazione e non deve essere replicato letteralmente.
+
+## 8. Difetti e comportamenti da non replicare
+
+| Area | Evidenza legacy | Decisione di parità |
+|---|---|---|
+| Segreti negli export | L'export struttura include `password` in chiaro (`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:516-559`); l'export generico serializza tutti i campi (`/Thoth/ThothAI/backend/thoth_core/management/commands/export_models.py:19-64`). | Escludere sempre credenziali e segreti. |
+| SQL euristico | Il campionamento per inferire FK interpola identificatori senza quoting e usa query costruite come stringhe (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:697-750`). | Usare adapter sicuri, quoting per dialetto e query read-only con limiti. |
+| Refresh incompleto | L'introspezione aggiunge oggetti ma non riconcilia rimozioni e non aggiorna tutte le proprietà (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:318-351`, `/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:459-481`). | Scansioni versionate e stato drift/removed. |
+| Relazioni denormalizzate | L'aggiornamento ricostruisce stringhe PK/FK solo sulle colonne partecipanti e non ripulisce esplicitamente valori obsoleti (`/Thoth/ThothAI/backend/thoth_core/models.py:505-526`). | Derivare indicatori dalle relazioni correnti. |
+| Azione relazione rotta | L'admin dichiara `update_pk_fk_fields` ma non lo implementa (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:219-245`). | Esporre un comando applicativo testato. |
+| CSV colonne incoerente | L'header ha sei colonne, le righe ne emettono otto incluse PK/FK (`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:165-195`). | Contratto CSV versionato e testato. |
+| Comando export rotto | `export_single_model` usa l'app label `toth_be` e un attributo non definito (`/Thoth/ThothAI/backend/thoth_core/management/commands/export_single_model.py:19-67`). | Non portare il comando; sostituirlo con export catalogo coerente. |
+| Batch AI colonne | Un batch usa la prima tabella selezionata come contesto per tutte le colonne (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:230-268`). | Raggruppare sempre per database e tabella. |
+| Contesto AI tabelle | Il fallback al commento generato è calcolato ma non incluso nel dataframe finale (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:485-525`). | Costruire il contesto dal valore effettivamente visibile. |
+| Duplicazione DB | Duplica configurazione e vector DB, azzerando soltanto una data di aggiornamento (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:514-569`). | Se mantenuta, duplicare soltanto metadati esplicitamente scelti, mai segreti o stati. |
+| Scope non JSON | Il generatore intercetta internamente il JSON non valido, mentre l'azione può comunque mostrare successo (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_db_scope.py:92-192`). | Stato `failed` o `needs_review`, senza falso successo. |
+| Mermaid non validato | La risposta AI viene salvata dopo la sola estrazione del blocco (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_erd.py:88-121`). | Validare prima di pubblicare e conservare l'errore di rendering. |
+| HTML non escapato | I valori descrittivi sono interpolati direttamente nell'HTML (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:35-188`). | Escape/sanitizzazione obbligatori. |
+| Job daemon | I task sono thread in-process (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_scope.py:21-62`). | Esecuzione durevole o almeno recuperabile, con idempotenza. |
+| Script MySQL | I commenti colonna usano `ALTER ... MODIFY COLUMN` basandosi sul tipo normalizzato (`/Thoth/ThothAI/backend/thoth_core/admin_utils/sql_comment_script.py:244-316`). | Generare solo con tipo nativo completo oppure bloccare l'export rischioso. |
+
+Il modulo contiene anche un helper verso `mermaid.ink`, ma non risultano call site nel tree
+legacy; il percorso attivo è il servizio locale. Non va quindi considerata una dipendenza
+funzionale da conservare.
+
+## 9. Baseline di parità per il Metadata Catalog di ThothII
+
+### Necessario
+
+- database gestiti derivati dalla configurazione dei workspace;
+- inventario completo del database, anche oltre il sottoinsieme usato dal workflow core;
+- scansione di tabelle, colonne, chiavi e relazioni fisiche con drift osservabile;
+- descrizioni canoniche e commenti AI separati per tabelle e colonne;
+- generazione AI selettiva e copia selettiva AI → descrizione, senza workflow aggiuntivo;
+- CRUD dei metadati semantici e delle relazioni logiche;
+- scope strutturato, documento generale strutturato ed ERD Mermaid;
+- servizio locale per validazione/rendering Mermaid in SVG/PNG/PDF;
+- test connessione, inferenza/validazione delle relazioni e operazioni lunghe con stato/log;
+- export CSV sicuro e script SQL commenti solo quando il dialetto può essere ricostruito senza
+  perdita;
+- API e UI dedicate, separate dal workflow NL→SQL;
+- pubblicazione esplicita e controllata del sottoinsieme utile al core/Qdrant.
+
+### Estensione, non requisito di parità iniziale
+
+- analisi e report GDPR;
+- importazione dei dati da installazioni ThothAI in produzione, da progettare come iniziativa
+  CLI `tht` separata.
+
+### Esplicitamente escluso
+
+- replica del Django Admin o del suo modello di permessi implicito;
+- modifica manuale della struttura fisica osservata;
+- memorizzazione o export di password nel catalogo;
+- dipendenza del workflow SQL dalla disponibilità della nuova UI;
+- proposal/versioning/diff per i commenti AI;
+- copia descrizione → commento AI, non presente nelle fonti;
+- difetti tecnici e comportamenti insicuri elencati sopra.
+
+## Conclusione
+
+ThothAI fornisce già il perimetro funzionale di un catalogo metadati, ma lo realizza mescolando
+configurazione di connessione, inventario fisico, contenuti semantici, job e UI nel modello
+Django. ThothII può raggiungere la parità separando questi aspetti e mantenendo invariato il
+workflow SQL: il catalogo gestisce l'intero database, mentre il core continua a consumare
+soltanto il sottoinsieme dichiarato dal workspace e pubblicato nel proprio indice Qdrant.
+
+La regola di Q6 è semplice e verificata nelle fonti: generazione nel campo AI, selezione
+esplicita dell'utente, copia nel campo canonico. Ogni meccanismo ulteriore sarebbe una nuova
+funzionalità e non è necessario per la parità.