# Ripresa dell'installazione guidata Stato al 28 settembre: revisione documentale in sei passi richiesta dall'utente; raccolta interattiva dei parametri durante il setup superata. R1/R2 confermate, `grill-with-docs` e `/to-spec` conclusi, piano di test confermato dall'utente. Il riferimento consolidato è il [PRD dell'installazione guidata](2026-09-27-guided-installation-prd.md). La [specifica derivata](2026-09-28-document-first-installation-spec.md) è pubblicata su Gitea come [Spec: installazione da documenti verificati e distribuzione Docker Hub](https://git.tylconsulting.it/mptyl/ThothII/issues/42), con etichetta `ready-for-agent`. `/to-tickets` è completato: la [scomposizione approvata](2026-09-28-installation-ticket-breakdown.md) collega le issue #43–#54, con dipendenze native verificate e parent invariata. Prossimo passo: `/implement` su #43 o #46, inizialmente senza blocchi. Nessun codice applicativo è stato implementato in questi passaggi. ## Base di lavoro Branch `codex/guided-standalone-install`, commit iniziale `67ee5262`. Il branch conserva il setup guidato e i controlli workspace incompleti, separati dal rilascio server. Il piano del 14 settembre descrive il precedente percorso manuale; le decisioni qui registrate aggiornano l'obiettivo del lavoro ripreso. ## Decisioni confermate il 27 settembre 2026 - Destinatario: una persona capace di installare Docker, clonare un repository e compilare i valori richiesti, senza conoscere l'architettura di ThothII. - Risultato: almeno un workspace utilizzabile per una domanda reale, attraverso due traguardi espliciti: piattaforma installata e workspace pronto. La procedura guida le decisioni umane necessarie e può essere ripresa senza ricominciare. - Collaudo in tre tappe distinte e ordinate: prima Windows, poi Linux Omarchy su PC Intel, infine macOS. Non attribuire a una piattaforma gli esiti ottenuti su un'altra. - Distribuzione ordinaria tramite immagini applicative precompilate pubblicate su Docker Hub; build e pubblicazione fanno parte del progetto. L'installazione locale configura e inizializza lo stack senza compilare; l'alternativa da sorgente resta esplicitamente disponibile. Anche il comando host deve essere fornito precompilato nel percorso ordinario. La creazione/caricamento degli esempi resta un'integrazione prevista, con l'implementazione del relativo sottoprogetto ancora rinviata. ## Vincoli già documentati Il precedente piano prevedeva clone Gitea e build locale; la decisione successiva li mantiene come alternativa al percorso precompilato Docker Hub. Restano Docker Compose e, su Windows, Ubuntu WSL2 con integrazione Docker Desktop. Il workspace descriptor contiene identità ed Evidence; configurazione database e metadati appartengono al Metadata Catalog. L'Installation Model Catalog appartiene all'installazione. ## Revisione del 28 settembre — prevale sul percorso interattivo La preparazione e le verifiche precedono l'esecuzione, nell'ordine richiesto: 1. Preparare il repository workspace predefinito con i tre esempi oppure uno ad hoc. 2. Verificare formalmente e, per quanto possibile, sostanzialmente i documenti workspace. 3. Verificare le precondizioni dell'host e dei componenti previsti. 4. Predisporre i documenti locali YAML/.env con i parametri dell'applicazione. 5. Verificarne completezza, correttezza e coerenza con i workspace. 6. Eseguire il setup dai documenti verificati, scaricando le immagini Docker Hub e creando lo stack, senza domande sui parametri. Template ed esempi commentati e guide IT/EN accompagnano ogni fase. Le verifiche devono essere ripetibili prima di creare i container. Pi è incluso in `core`, non deve essere installato sull'host; i suoi controlli runtime avvengono dopo l'avvio. I binding database restano di competenza del Catalog, con un input locale preparatorio distinto dai descriptor workspace v4. L'utente conferma che le immagini Docker Hub oggi non esistono: occorre un comando di produzione/pubblicazione per il manutentore, poi verificare il pull degli artefatti pubblicati prima di collaudare l'installazione precompilata sui PC. La preparazione del rilascio non è un compito dell'utente installatore. R1/R2 confermate: esempi ancora rinviati e primo collaudo con repository ad hoc; controlli runtime elencati prima ed eseguiti obbligatoriamente dopo la creazione dello stack. Nessun controllo non eseguito conta come superato. ## Aspetti da tradurre nella specifica tecnica - Quali template e documenti locali preparare, verificare e applicare, senza raccogliere parametri durante l'esecuzione. - Come distinguere validazione documentale, controlli preventivi esterni e controlli runtime, mantenendo i contratti delle superfici amministrative esistenti. - Criteri dettagliati di verifica, ripresa dopo errori e accettazione per ogni tappa. ## Sottoprogetto esempi: requisiti definiti, implementazione rinviata Su richiesta dell'utente l'implementazione dei database di esempio viene rinviata; la definizione dei requisiti dell'installazione prosegue indipendentemente. Branch dedicato: `codex/benchmark-examples`, creato da `67ee5262`, con documentazione consolidata nel commit `08a5db55`. Il PRD approvato è `docs/plans/2026-09-27-example-databases-prd.md` su quel branch. Il PRD conserva D1–D8: Financial, European Football e F1, tre workspace separati, dati PostgreSQL e schema commentato, Evidence curate e domande di accompagnamento senza SQL target, contenuti italiano/inglese. CLI scaricabile dal repository pubblico degli esempi Gitea gestito da TYL Consulting, collegato dal repository pubblico ThothII. Selezione di uno, due o tre esempi dopo il setup, oppure come ultimo passo facoltativo dello stesso setup; pacchetti PostgreSQL già verificati ove redistribuibili. La copia del repository potrà essere indipendente, senza storia e collegamenti Git all'originale, oppure scaricata con accesso al repository pubblico in sola lettura. Workspace ed Evidence locali restano modificabili. Preparazione e verifiche sono responsabilità del progetto; all'utente vengono sottoposte solo ambiguità non risolvibili dalle fonti. Chi installa dovrà trovare gli esempi pronti all'uso. Il caricatore, il supporto alla cartella `examples/` e alla copia autonoma sono da implementare. Finché il sottoprogetto è rinviato, il setup non deve offrirli come funzionalità disponibili. Il requisito di un workspace utilizzabile resta valido: per il collaudo si dovrà usare un workspace/database realmente disponibile. ## Verifiche da completare Riesecuzione e fallimenti intermedi del setup; requisiti HTTPS per il repository workspace; test dedicati dei nuovi comandi; distinzione fra stato della piattaforma e Workspace Readiness; collaudo reale completo secondo l'ordine concordato. ## Riscontro sul setup corrente - CLI guidata e pagine amministrative esistenti sono già il percorso previsto dal piano del 14 settembre; non è richiesto un nuovo installer grafico. - `setup --complete` prepara autenticazione e modelli, build, migrazioni Catalog, avvio, workspace pull, test Pi e doctor. Non configura binding DB, sincronizzazione dei metadati e preprocessing (`tools/tht/internal/setup/run.go:60`). Il messaggio finale corrente «ThothII is ready» deve essere allineato al traguardo verificato. - I modelli sono oggi preimpostati, senza selettore del provider nel Request (`tools/tht/internal/setup/files.go:449`). - La riesecuzione rifiuta file di configurazione esistenti con contenuto diverso; non equivale ancora a una ripresa guidata delle tappe tecniche e umane (`tools/tht/internal/setup/files.go:107`). La specifica deve prevedere stato delle tappe e gestione delle correzioni, senza sovrascrivere personalizzazioni. ## Round installazione I1–I3 del 27 settembre — storico superato dove indicato La revisione del 28 settembre sopra prevale su I1/I2: nessun rinvio di parametri obbligatori al setup e nessuna raccolta tramite questionario. Il testo seguente conserva il contesto della decisione precedente e non è il comportamento richiesto per la nuova procedura. I3 resta valido per riuso dei contenuti e curation esplicita. L'utente conferma «tutto come da te suggerito», dopo il chiarimento sulla CLI locale interattiva: domande condizionate alle risposte, configurazioni precompilate, credenziali protette, verifica delle connessioni, possibilità di rinviare una configurazione e ripresa senza ricominciare. La CLI guida alle pagine amministrative esistenti per il workspace e ne verifica il completamento. | ID | Decisione | Scelta approvata | | --- | --- | --- | | I1 | Primo avvio senza repository/workspace disponibile | Consentire di completare il solo traguardo «piattaforma installata» e riprendere in seguito la configurazione del workspace. Il percorso complessivo resta incompleto fino al primo workspace utilizzabile e alla domanda reale. Nessuna dipendenza dalla futura disponibilità degli esempi. | | I2 | Scelta dei modelli durante il setup | Selezione guidata di provider e modello tra configurazioni supportate/precompilate, chiedendo le credenziali necessarie; percorso avanzato per configurazioni personalizzate. Embedding locale preconfigurato come scelta iniziale. | | I3 | Preparazione di descrizioni ed Evidence | Riutilizzare i contenuti già curati. Proporre la generazione AI delle descrizioni mancanti come scelta esplicita, con revisione umana, invece di avviarla automaticamente. Guidare alle pagine amministrative necessarie e registrare il punto di ripresa. | Le Evidence sono opzionali nel contratto del workspace: non introdurre un obbligo generale di crearle per completare l'installazione. La specifica deve rispettare i controlli di Workspace Readiness su connessione, schema e indicizzazione, distinguendo assenza lecita di Evidence da configurazione incompleta o incoerente. Per le decisioni correnti e i criteri di accettazione fa fede il PRD revisionato al 28 settembre, senza attestare che siano già implementati.