# PRD — Installazione di ThothII da documenti verificati Creato: 2026-09-27. Revisione: 2026-09-28. Stato: requisiti e chiarimenti R1/R2 approvati; `grill-with-docs` e `/to-spec` conclusi. Specifica pubblicata su Gitea con etichetta `ready-for-agent`; implementazione non iniziata. Branch: `codex/guided-standalone-install`. La [specifica derivata](2026-09-28-document-first-installation-spec.md) raccoglie user story, decisioni implementative e collaudi. Il piano di test è stato confermato dall'utente e la specifica è pubblicata nell'issue [Spec: installazione da documenti verificati e distribuzione Docker Hub](https://git.tylconsulting.it/mptyl/ThothII/issues/42). La [scomposizione approvata](2026-09-28-installation-ticket-breakdown.md) è pubblicata nelle issue #43–#54 con dipendenze native. Il prossimo passaggio è `/implement` sui ticket senza blocchi, inizialmente validazione workspace e rilascio Docker Hub. Questo documento consolida le decisioni della [ripresa del progetto](2026-09-27-guided-installation-resumption.md) e aggiorna il [piano standalone del 14 settembre](2026-09-14-manual-standalone-installation.md) per l'esperienza guidata. Conserva architettura, protezione dei segreti e contratti del prodotto; modifica il percorso operativo e l'ordine dei collaudi. La successiva precisazione dell'utente rende la distribuzione di immagini precompilate su Docker Hub parte della prima versione del percorso ordinario, superando il precedente rinvio. La revisione del 28 settembre sostituisce la raccolta interattiva dei parametri: si preparano prima i documenti, li si verifica anche più volte, poi si esegue il setup. Prevale sulle precedenti decisioni I1/I2 dove consentivano configurazioni obbligatorie rinviate o richieste durante l'installazione. ## Obiettivo e destinatario Una persona capace di installare Docker, clonare un repository e fornire le proprie credenziali deve poter predisporre con calma i documenti necessari e rendere utilizzabile almeno un workspace, senza conoscere l'architettura interna. Template commentati, esempi compilati e documentazione passo per passo spiegano cosa inserire nei file YAML e nei file protetti `.env` o equivalenti. DWH e provider LLM possono essere esterni; non si promette un funzionamento offline. La CLI offre preparazione dei template, verifiche ripetibili e applicazione dei documenti già verificati. Il setup non raccoglie parametri, non apre questionari e non completa silenziosamente documenti incompleti. L'utente corregge i documenti prima di eseguirlo. Le pagine amministrative rimangono disponibili per l'uso e la manutenzione successivi, senza diventare una scorciatoia per rinviare parametri obbligatori dell'installazione. Il percorso predefinito scarica da Docker Hub le immagini applicative già compilate: il computer dell'utente svolge configurazione, inizializzazione dei servizi e dei database, avvio e verifiche. L'installazione da sorgente resta disponibile come scelta esplicita alternativa. Nessuna compilazione dell'applicazione, neppure all'interno di un container locale, è richiesta dal percorso ordinario. ## Decisioni approvate | Area | Comportamento richiesto | | --- | --- | | Distribuzione predefinita | Creare, collaudare e pubblicare su Docker Hub le immagini applicative precompilate; il setup le scarica e le avvia senza build locale. | | Alternativa da sorgente | Conservare un percorso esplicito di build dai sorgenti, documentato e verificato, con configurazione e funzionalità equivalenti. | | Due traguardi | Mostrare separatamente piattaforma installata e workspace pronto. | | Preparazione anticipata | Repository workspace e documenti applicativi predisposti prima dell'esecuzione; template, esempi e guida alla compilazione. | | Setup senza domande | Consuma documenti già verificati, mostra avanzamento ed errori e non chiede valori mancanti. | | Modelli | Provider, modelli, usi, endpoint e riferimenti alle credenziali descritti nei documenti prima del setup; configurazioni di esempio supportate e commentate. | | Embedding | Configurazione locale precompilata come percorso ordinario. | | Ripresa | Correggere i documenti, ripetere le verifiche e riprendere l'esecuzione senza questionari né perdita del lavoro completato. | | Workspace | Preparare prima repository e descriptor conformi; dichiarare separatamente i parametri di collegamento ai database secondo i contratti ThothII. | | Contenuti | Riutilizzare descrizioni/Evidence curate; nessuna generazione AI implicita per completare un documento. Eventuali attività di curation restano esplicite. | | Evidence | Opzionali nel contratto; se configurate devono essere valide e utilizzabili. | | Collaudi | Prima Windows, poi Omarchy su PC Intel, infine macOS, in tre tappe distinte. | ## Rilascio e distribuzione delle immagini La creazione e pubblicazione delle immagini appartengono al processo di rilascio del progetto. Il sottoprogetto installazione comprende quindi anche una procedura riproducibile per costruire, verificare e pubblicare queste immagini su Docker Hub; non basta aggiungere un'opzione di pull senza fornire immagini utilizzabili. **Stato iniziale dichiarato dall'utente il 28 settembre:** le immagini applicative ThothII su Docker Hub non sono disponibili. Prima di collaudare l'installazione precompilata su un PC Windows o Linux occorre produrle, pubblicarle e verificarne il download. Questa dipendenza è bloccante per quel collaudo, non viene aggirata usando immagini costruite soltanto nella cache della macchina di test. Il progetto deve fornire un comando di produzione e pubblicazione, mantenuto nel repository e documentato per il manutentore. Il comando riceve revisione/versione, namespace Docker Hub e architetture, costruisce e verifica le immagini proprietarie, le pubblica e produce il manifest di rilascio con digest e artefatti compatibili. Il nome e la sintassi saranno fissati nella specifica; il comando non è ancora implementato. Le credenziali di pubblicazione appartengono al manutentore e non entrano nei documenti dell'utente che installerà ThothII. La sequenza di rilascio è: produzione e controlli, pubblicazione su Docker Hub, verifica del pull del rilascio pubblicato, quindi collaudo della procedura sui sistemi destinatari. Questa fase del manutentore precede i sei passi dell'utente. Il pacchetto distribuito deve comprendere tutto ciò che serve all'installazione: immagini applicative, manifest Compose/configurazione di avvio, migrazioni e risorse di inizializzazione, oltre al comando operatore o al suo bootstrap. Il numero delle immagini segue i servizi dell'architettura corrente: non è richiesto accorpare tutto in un singolo container. I servizi di terze parti mantengono immagini compatibili con lo stack, senza ricostruirli sul computer dell'utente. Nell'architettura corrente le immagini proprietarie da pubblicare sono `core` e `frontend`; PostgreSQL, Qdrant e Ollama usano immagini upstream. Le attività `catalog-migrate` e `workspace-maintenance` riusano la stessa immagine release di `core`. Il pacchetto di installazione include anche le risorse oggi montate dal checkout, fra cui `docker/catalog-db-init.sql` e `docker/embedding-model-init.sh`. Il download del modello embedding, la creazione dei volumi/database e le migrazioni restano attività di inizializzazione locale, distinte dalla compilazione. Ogni rilascio identifica una versione coerente di immagini, CLI e configurazione; il manifest registra riferimenti verificabili, inclusi i digest delle immagini. Il setup riporta la versione installata e non combina automaticamente componenti incompatibili tramite tag mobili. Nomi e namespace Docker Hub saranno definiti nella specifica di pubblicazione; non sono presunti già esistenti. Il percorso ordinario deve poter partire dal pacchetto di rilascio senza richiedere il checkout dei sorgenti applicativi o strumenti di compilazione. Anche l'eventuale CLI nativa deve essere distribuita già compilata per gli host supportati; nascondere una compilazione di `tht` nel bootstrap non soddisfa il requisito. L'installazione pubblica non richiede credenziali di pubblicazione Docker Hub. Le immagini non includono credenziali dell'installazione, dati personali, workspace dell'operatore o i database di esempio preinstallati. Configurazione e dati persistenti vengono creati localmente nei percorsi e volumi dell'installazione. Il supporto iniziale Windows/WSL2 e Omarchy richiede immagini Linux amd64; per la tappa macOS Apple Silicon servono immagini Linux arm64 e un bootstrap host adeguato. La pubblicazione dichiara solo le architetture effettivamente verificate, rispettando l'ordine dei collaudi concordato. La modalità sorgente costruisce gli stessi componenti a partire da una revisione esplicita, documenta i prerequisiti aggiuntivi e usa gli stessi contratti di configurazione, persistenza e migrazione. Un errore di download da Docker Hub non deve attivarla automaticamente: l'utente può correggere il problema e riprovare, oppure scegliere consapevolmente l'alternativa da sorgente. ## Percorso dell'utente Prima dei sei passi sono disponibili guida, template e strumenti di verifica già compilati. Git e gli strumenti minimi necessari per acquisire i documenti sono esplicitati nella guida; la verifica completa dell'host rimane al passo 3. I primi controlli documentali non devono richiedere l'avvio di ThothII o dei suoi container. ### 1. Preparazione del repository dei workspace L'utente prepara una copia del repository predefinito con Financial, European Football e F1, oppure un repository ad hoc a partire da un template documentato. Il repository predefinito contiene definizioni, documentazione, Evidence e riferimenti ai pacchetti dati; il clone non equivale ad aver già creato i database PostgreSQL. La disponibilità effettiva del percorso predefinito dipende dal sottoprogetto esempi. Si preservano le scelte già approvate sulla copia autonoma o sull'accesso in sola lettura all'originale; workspace ed Evidence locali restano modificabili. La preparazione non richiede diritti di push al repository pubblico e non sostituisce un repository già configurato senza una scelta esplicita. ### 2. Verifica dei documenti dei workspace Un comando dedicato verifica sintassi YAML, versione/schema ThothII, campi richiesti, tipi, identificatori, unicità, corrispondenza fra catalogo e directory, descriptor referenziati, percorsi e file Evidence dove configurati. La verifica è ripetibile sui file locali prima che Docker o ThothII siano in esecuzione. La verifica sostanziale copre ciò che è dimostrabile dai documenti: coerenza dei riferimenti, esistenza e leggibilità dei contenuti, conformità delle Evidence e assenza di contraddizioni rilevabili. Non pretende di certificare automaticamente la verità delle regole di dominio o interrogare database non ancora creati. Ogni errore identifica documento, campo e, quando disponibile, riga, con indicazione della correzione. L'utente modifica i documenti e ripete il controllo. Le Evidence restano opzionali: assenza dichiarata ed Evidence configurate ma invalide sono condizioni diverse. I controlli incrociati che richiedono i parametri applicativi vengono completati al passo 5. ### 3. Verifica delle precondizioni Verificare sistema/architettura, Docker e Compose, accesso al daemon, risorse e spazio richiesti, percorsi e permessi, porte previste, accesso ai servizi esterni e al registry per quanto valutabile. Su Windows verificare Ubuntu WSL2 e integrazione Docker Desktop. I requisiti dipendenti da valori scelti al passo 4 sono ricontrollati al 5. Distinguere componenti necessari sull'host da componenti inclusi nelle immagini: Pi appartiene a `core`, non è un prerequisito da installare separatamente sul PC. Presenza e versione di Pi sono verificate nel rilascio; il funzionamento effettivo nel container è verificato al passo 6. Lo stesso principio vale per le dipendenze applicative già incluse. Go, Python, Node e compilatori non sono prerequisiti host del percorso precompilato. ### 4. Preparazione dei parametri applicativi L'utente compila i documenti locali usando template commentati ed esempi: descriptor di installazione, configurazione dei modelli e riferimenti ai file protetti `.env` o equivalenti. Sono espliciti campi obbligatori, opzionali, default e condizioni in cui un parametro serve. La preparazione può svolgersi in più sessioni senza avviare il setup o i servizi applicativi. I documenti definiscono versione del rilascio, percorsi/volumi, profilo e accesso, repository/workspace selezionati, provider/modelli per i rispettivi usi, endpoint, embedding, parametri di collegamento ai database e riferimenti ai segreti. La configurazione dei modelli deriva dall'Installation Model Catalog, senza un secondo catalogo del setup. L'embedding locale ha un esempio precompilato. Il descriptor workspace v4 continua a contenere identità ed Evidence: non vi si inseriscono campi database o modelli estranei al contratto. I binding database sono predisposti in un input locale separato, da specificare, e applicati al Metadata Catalog durante il setup mediante i suoi servizi; non diventano una seconda autorità runtime. La configurazione server/Omics rimane fuori dal perimetro. I segreti non entrano nel repository pubblico, nei log o nei rapporti di verifica. Per le credenziali tecniche interne un comando preparatorio può generare file protetti prima delle verifiche, senza questionario né richiesta durante il setup. Le selezioni degli esempi e le eventuali operazioni facoltative sono dichiarate prima dell'esecuzione. Le pagine amministrative restano disponibili dopo l'avvio per modifiche e curation, non per raccogliere valori obbligatori dimenticati. ### 5. Verifica dei parametri applicativi Un comando ripetibile controlla completezza e correttezza dei documenti, sintassi e compatibilità dei valori, riferimenti ai segreti, modelli/usi/default, collegamenti workspace/database, configurazione Compose, disponibilità del rilascio nel registry e compatibilità delle architetture. Completa i controlli incrociati dei passi 2 e 3. Quando fattibile senza creare lo stack, verifica raggiungibilità, autenticazione e compatibilità delle dipendenze esterne con operazioni circoscritte; la documentazione spiega le prove effettuate, inclusi eventuali accessi a provider a consumo. Non cambia dati applicativi né esegue migrazioni o importazioni. Il rapporto distingue `superato`, `errore`, `avviso` e `non ancora verificabile`, senza trasformare assenza di verifica in successo. I controlli che richiedono lo stack sono elencati prima e obbligatori al passo 6, secondo R2 approvata. Un errore formale o una configurazione obbligatoria mancante blocca l'esecuzione. Il risultato identifica i documenti e la revisione del repository esaminati. Una modifica successiva invalida i controlli dipendenti: il setup non deve applicare file diversi da quelli verificati senza ricontrollarli. Segreti e loro valori non vengono copiati nel rapporto. ### 6. Setup esecutivo Il setup ricontrolla l'ammissibilità del piano verificato, scarica le immagini del rilascio da Docker Hub, crea reti/volumi/container e inizializza i database applicativi. Esegue migrazioni, applicazione della configurazione e dei binding, sincronizzazione e preparazione necessaria dei workspace secondo i contratti esistenti. Quando disponibili e selezionati, crea e carica i database di esempio dal relativo pacchetto. Non pone domande su provider, modelli, percorsi, credenziali o altri parametri. Se trova un valore mancante o incoerente, si ferma con una diagnosi e rimanda alla correzione dei documenti e alla loro verifica; non apre un wizard di riparazione. Le conferme dei contratti di dominio non vengono aggirate: la specifica deve distinguere operazioni predisponibili nel piano da attività umane residue senza reinserire la raccolta dei parametri durante l'installazione. Esegue i controlli disponibili solo a runtime: salute dei servizi, Pi, modello embedding effettivamente caricato, collegamenti dalla rete dei container, Catalog e preparazione dei workspace. Mostra separatamente piattaforma avviata e workspace pronto, più eventuali verifiche funzionali ancora da svolgere. Il collaudo completo include una domanda reale con revisione umana, senza SQL target di benchmark. ## Documentazione di accompagnamento Le guide italiana e inglese seguono esattamente i sei passi. Per ciascuno indicano input, file da predisporre, template ed esempio compilato, comando di verifica, esito atteso, errori comuni e passaggio successivo. Un elenco dei documenti e dei segreti necessari consente di raccogliere le informazioni in anticipo. Le istruzioni distinguono manutentore del rilascio e utente installatore, host e container, controlli locali e runtime. Il percorso sorgente è esplicitamente alternativo; un download fallito non ne provoca l'attivazione automatica. ## Avanzamento, errori e ripresa La procedura conserva l'installazione di riferimento, gli input verificati, i passaggi completati, l'ultimo errore e il prossimo passo, senza conservare segreti nello stato di avanzamento. Alla ripresa verifica lo stato reale: una vecchia spunta non prova che servizio, credenziale o indice siano ancora validi. Correggere un endpoint o una credenziale non impone di rifare tutto il setup. La specifica deve definire quali verifiche dipendenti vanno ripetute, preservando configurazioni, workspace, sessioni e contenuti non coinvolti nella modifica. Le modifiche manuali vengono riconosciute e spiegate, non cancellate implicitamente. La ripresa riguarda le tappe della procedura: non promette una ripresa interna di operazioni che non la supportano, come il preprocessing corrente. In questi casi il passaggio viene rieseguito in modo coerente con il suo contratto. Un fallimento riporta fase, causa comprensibile, correzione consigliata e modalità di ripresa. Distinguere problemi dell'host, dei servizi locali e delle dipendenze esterne. Un provider o DWH indisponibile non annulla una verifica valida della piattaforma, ma impedisce di dichiarare il percorso complessivo pronto. ## Criteri di accettazione | Scenario | Esito verificabile | | --- | --- | | Rilascio Docker Hub | Immagini costruite e pubblicate con versione, digest e architetture dichiarate; avvio verificato usando quanto effettivamente scaricato dal registry. | | Installazione precompilata | Su host senza toolchain e senza sorgenti applicativi, il setup scarica le immagini e completa configurazione/avvio senza compilare né invocare build locali. | | Risorse di avvio | Compose, migrazioni e inizializzazione non dipendono da file presenti soltanto in un checkout dei sorgenti. | | Download fallito | Errore comprensibile e ripetibile; nessuna build da sorgente avviata implicitamente. | | Modalità sorgente | Scelta esplicita ancora funzionante, con gli stessi contratti di configurazione e persistenza del rilascio precompilato. | | Preparazione documentale | Template e guida consentono di predisporre tutti i YAML e file protetti necessari prima dell'esecuzione. | | Ordine dei passi | Repository, verifica workspace, precondizioni, parametri applicativi, verifica parametri, setup esecutivo. | | Verifica workspace senza stack | Il passo 2 funziona senza Docker attivo o applicazione installata e senza toolchain host aggiuntive. | | Controlli ripetibili | Ripetere i controlli non crea container, non migra DB e non modifica i documenti dell'utente. | | Completezza prima del setup | Un campo obbligatorio mancante blocca l'esecuzione, indicando file/campo e correzione; nessuna domanda interattiva. | | Input modificati | I controlli dipendenti sono invalidati o ripetuti; nessuna applicazione di input diversi da quelli verificati. | | Setup non interattivo | Con documenti completi il passo 6 termina senza richiedere input da terminale; un errore non apre un questionario. | | Verifiche sostanziali | Il rapporto distingue prove eseguite da controlli non ancora possibili; non certifica verità di dominio o servizi non verificati. | | Modello configurato | Credenziali/endpoint verificati e selezione valida per gli usi richiesti. | | Credenziale errata | Diagnosi senza esporre il segreto, correzione nel file protetto e nuova verifica prima della ripresa. | | Interruzione e riavvio | La procedura ricontrolla gli input e riprende dall'avanzamento verificato senza nuove domande sui parametri. | | Contenuti esistenti | Descrizioni curate ed Evidence locali preservate; nessuna generazione o sovrascrittura silenziosa. | | Evidence assenti | Nessun blocco dovuto alla sola assenza quando non sono configurate. | | Workspace pronto | Connessione, schema e preparazione necessaria verificati; domanda reale completata con revisione umana. | | Riesecuzione | Nessuna duplicazione, azzeramento di dati o perdita delle personalizzazioni. | | Stop/start | Accesso e workspace utilizzabile persistono; i problemi esterni sono segnalati separatamente. | | Segreti | Assenti da log, riepiloghi, file pubblici e stato di avanzamento. | Il dettaglio dei controlli e i test automatici devono rispettare le API e i contratti attuali; i test di portabilità e il collaudo con servizi reali restano distinti. La prima tappa usa Windows x64/WSL2, la seconda Linux Omarchy x64, la terza macOS Apple Silicon, coerentemente con le architetture già previste dal progetto. Gli esiti di una tappa non valgono come collaudo delle successive. ## Sottoprogetto degli esempi L'implementazione rimane rinviata, come confermato con R1. I requisiti sono conservati sul branch `codex/benchmark-examples`, commit `08a5db55`. Il setup non offre come disponibili CLI, database o modalità di copia del repository non ancora implementati. Il percorso richiesto ora parte dal repository predefinito oppure da quello ad hoc. Il primo collaudo utilizza un repository ad hoc; il percorso predefinito completo arriverà con il sottoprogetto esempi. Quando disponibili e selezionati nei documenti, creazione e caricamento dei database avvengono nell'installazione dell'utente a partire dai pacchetti dati verificati, senza compilare l'applicazione o incorporare quei database nelle immagini. Il percorso ad hoc può essere collaudato con workspace/database disponibili. La disponibilità di immagini Docker Hub è invece un prerequisito esplicito di ogni collaudo del percorso precompilato. ## Confini della specifica successiva La verifica del codice ha individuato questi punti di integrazione concreti: - `compose.yaml` costruisce oggi `core` e `frontend`; i servizi di manutenzione usano l'immagine core locale. `setup --complete` esegue una build (`tools/tht/internal/setup/run.go:77`) e `scripts/install-tht.sh:84` compila la CLI tramite Docker se non riceve un artefatto già costruito. Il percorso ordinario deve sostituire entrambi i comportamenti con artefatti del rilascio. La CI `.github/workflows/container-multiarch.yml` verifica già entrambe le architetture Linux; occorre aggiungere la pubblicazione Docker Hub e la verifica dei pacchetti effettivamente distribuiti. - I parser workspace (`backend/src/workspaces/catalog.ts:52`, `schema.ts:382`) verificano i documenti senza dipendenze dal runtime, ma non sono oggi un comando preinstallazione nativo. Devono essere resi disponibili negli strumenti precompilati preservando gli stessi contratti, senza richiedere Node sul PC. - La configurazione database è applicata al descriptor runtime dal Catalog (`backend/src/catalog/runtime-binding.ts:33`). Serve un input locale preparatorio e un percorso di applicazione al Catalog, senza cambiare il significato del workspace v4 o creare due autorità persistenti per i binding. - `config.Load` contiene verifiche riutilizzabili su YAML e file ambiente (`tools/tht/internal/config/installation.go:100`); il `doctor` corrente combina controlli documentali e runtime (`tools/tht/internal/doctor/report.go:97`). La specifica deve separarli per rendere disponibili i gate dei passi 2, 3 e 5. - L'ammissione della sessione controlla modello, preprocessing e servizi necessari (`backend/src/routes/sessions.ts:438`); il preprocessing richiede un database associato e una sincronizzazione corrente. Le descrizioni generate dall'AI non costituiscono un requisito generale: possono essere già disponibili descrizioni curate o commenti della sorgente. Riferimento: [contratto di preprocessing](../contracts/workspace-preprocessing-cli.md). La specifica tecnica dovrà definire build/pubblicazione Docker Hub, pacchetto di rilascio e bootstrap precompilato, selezione esplicita del percorso sorgente, template e documenti locali, validatori senza runtime, applicazione dei parametri al Catalog, esecuzione senza questionari, stato/ripresa e verifiche dei due traguardi. Nomi dei comandi di preparazione/verifica/pubblicazione e formato dello stato sono dettagli da progettare, non funzionalità esistenti attestate da questo PRD. ## Chiarimenti approvati del 28 settembre | ID | Scelta | Decisione approvata | | --- | --- | --- | | R1 | Disponibilità dei tre esempi al primo rilascio | Conservare il rinvio del sottoprogetto e collaudare prima il percorso con repository ad hoc; introdurre il percorso predefinito completo quando gli esempi sono disponibili. | | R2 | Controlli impossibili prima della creazione dello stack | Bloccare gli errori rilevabili prima; elencare i controlli runtime non ancora eseguibili e renderli obbligatori al passo 6, senza contarli come superati preventivamente. | Approvazione: «ok per le tue proposte. dopodichè procedi con to-spec». Il principio dei sei passi resta invariato. Non rientrano in questo lavoro un nuovo installer grafico, la riscrittura delle superfici amministrative, il supporto multi-repository, la distribuzione dei database di esempio o modifiche al deployment server/Omics.