ThothII/docs/plans/2026-09-27-guided-installation-resumption.md

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. La specifica derivata è pubblicata su Gitea come Spec: installazione da documenti verificati e distribuzione Docker Hub, con etichetta ready-for-agent. /to-tickets è completato: la scomposizione approvata 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.