docs: describe read-only workspace runtime configuration

docs/guida-utente.md

@@ -26,7 +26,6 @@ thoth-workspaces.yaml              ← catalogo: elenco dei workspace
 <id-workspace>/workspace.yaml      ← descrittore del workspace (schema v3)
 <id-workspace>/evidence/           ← (facoltativo) documenti di contesto, es. *.md
 <id-workspace>/schema/annotations.yaml   ← (facoltativo) join logici curati a mano (P5)
-workspace-docs/<id-workspace>/     ← generato dall'applicazione, non va editato
 ```
 
 - Il **catalogo** `thoth-workspaces.yaml` è un semplice elenco:
@@ -100,11 +99,10 @@ Cosa cambia rispetto ai vecchi workspace (se ne avevi uno):
 
 1. **Git è la fonte di verità.** Descriptor, catalogo ed Evidence si modificano solo con un
    *commit* + *push* e poi un *pull* dell'installazione.
-2. **Niente segreti nel repository.** Endpoint, token, certificati e password vivono solo nei file
-   di installazione protetti (fuori da Git).
-3. **I file `workspace-docs/` sono generati** dall'applicazione: non modificarli a mano.
-4. **Solo schema v3.** I descrittori v1/v2 vengono rifiutati prima dell'attivazione.
-5. **L'applicazione non fa push di contenuti curati.** L'operatore che cura il repository lavora in
+2. **Niente segreti nel repository.** Password, token, chiavi private e URL firmati vengono inseriti
+   a runtime nella gestione Workspace e conservati cifrati dal backend.
+3. **Solo schema v3.** I descrittori v1/v2 vengono rifiutati prima dell'attivazione.
+4. **L'applicazione non fa push di contenuti curati.** L'operatore che cura il repository lavora in
    un clone autore separato.
 
 ---
@@ -160,10 +158,39 @@ Note importanti:
 
 ### 2.2 Applicazione web — gestione workspace
 
-Per i workspace **già pronti** (`ready`) la pagina workspace è **in sola lettura**:
-*Pull/Sync*, *Validate*, *Test* dell'installazione, *Export*, riepilogo Evidence e la guida Git per
-il curatore. Il modulo di bootstrap modificabile compare solo per gli slot del catalogo in stato
-`configuration_required`.
+La gestione Workspace ha due livelli distinti.
+
+**Livello 1 — repository.** La parte iniziale spiega che il sorgente del workspace vive in una
+directory separata, viene pubblicato dal curatore su un repository ospitato da un server Git come
+GitHub, GitLab o Gitea, e viene letto da ThothII in sola lettura. Mostra host, repository, branch,
+revisione attiva e stato dell'ultimo aggiornamento.
+
+- **Update workspace repository** non richiede la selezione di un workspace. Il backend esegue il
+  fetch/pull del branch configurato direttamente nel checkout gestito da ThothII, valida l'intera
+  revisione candidata e la attiva in modo atomico. Se la validazione fallisce, conserva la
+  revisione precedente. Non modifica il sorgente remoto e non salva contenuti nella GUI.
+- Per creare un workspace locale, prepara una directory sorgente con catalogo, `workspace.yaml` e
+  le sottodirectory previste; quindi validala, esegui commit e push dal clone autore. ThothII non
+  offre comandi di creazione, modifica o pubblicazione del sorgente.
+
+**Livello 2 — workspace selezionato.** Questi comandi sono isolati perché richiedono prima la
+selezione del workspace.
+
+- **Validate workspace** verifica nuovamente catalogo, descrittore, Evidence e invarianti della
+  revisione attiva selezionata. Non contatta il DWH e non modifica file.
+- **Save runtime secrets** sostituisce alla cieca i valori compilati. I campi dipendono dal
+  trasporto DWH e dall'autenticazione Evidence dichiarati; il backend restituisce solo lo stato
+  configurato/mancante.
+- **Forget** elimina dal vault cifrato il singolo secret indicato. Le sessioni o operazioni future
+  che lo richiedono restano bloccate finché non viene inserito di nuovo.
+- **Test connections** materializza temporaneamente i secret necessari, contatta i servizi dati
+  configurati per quel workspace e rimuove i file temporanei alla fine. Non esporta né pubblica
+  nulla.
+
+Il repository Git remoto e le relative credenziali sono impostazioni di installazione. I secret
+runtime DWH/Evidence sono invece persistenti nel vault cifrato del backend e non nel local storage
+della GUI. La GUI è soltanto l'interfaccia: dopo l'invio cancella i valori dai campi e non può
+rileggerli.
 
 ---