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](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.