feat(cli): prepare and validate workspace documents offline

Reuse the runtime catalog and workspace parsers in a standalone helper paired with tht. Add document templates, safe diagnostics, local Evidence checks, native bundle builds, shared CLI fixtures and IT/EN preparation guides. Record the approved document-first specification and ticket breakdown. Refs #43.

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

@@ -0,0 +1,155 @@
+# 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.