docs: document full and embedded rendering with server authentication

docs/contracts/portal-shell-adapter-v1.md

@@ -24,6 +24,9 @@ shell:
 
 Se `shell` o `mode` sono omessi, la modalità è embedded. L'adapter embedded
 predefinito è `omics-portal`; un nome sconosciuto è un errore di configurazione.
+Questi default sono normalizzati dal CLI prima della proiezione. Nel browser,
+shell interamente omessa ha gli stessi default, ma un oggetto `shell` parziale
+senza `mode` o `defaultLocale` viene rifiutato: non scrivere proiezioni a mano.
 Full non istanzia adapter. `defaultLocale` inizializza full; in embedded il locale
 proviene dal portale. L'autenticazione si configura separatamente dalla shell.
 
@@ -59,9 +62,11 @@ L'integrazione monta React nel documento Django, non in un iframe.
 | Tema | `data-bs-theme` su `html` | osservazione limitata a quell'attributo |
 | Fullscreen | stato effettivo del documento | evento del browser, inclusa uscita con Esc |
 
-L'attributo `lang` storicamente fisso a `en` nel template base non deve essere
-usato come surrogato della lingua selezionata. Leggere il valore renderizzato dal
-server evita anche di anticipare un cambio lingua prima che il form abbia successo.
+Il template Omics aggiornato allinea anche `html lang` alla lingua Django, ma
+la fonte dell'adapter rimane `select.omics-language-select[data-lang]`. Leggere
+il valore renderizzato evita di anticipare un cambio lingua prima che il form
+abbia successo. Cambiare soltanto `select.value` o `data-lang` senza il normale
+reload non è un trasporto runtime implementato per la lingua.
 
 L'assenza del contesto host atteso produce un errore di integrazione; non abilita
 controlli locali. Non si introducono eventi `ready/state`, handshake, timeout,
@@ -76,7 +81,7 @@ essere letti dai componenti applicativi.
 | Lingua | selettore locale | selettore Omics, normale reload Django |
 | Tema | toggle locale light/dark | stato Omics |
 | Fullscreen | controllo locale, stato reale | controllo Omics, stato reale |
-| Login/logout | autenticazione ThothII configurata | autenticazione Omics esistente |
+| Login/logout | ThothII local/OIDC; upstream non offre logout locale | autenticazione Omics esistente |
 | Nome utente | header ThothII | header Omics |
 | Rotellina amministrativa | mai | eventuale comando del portale |
 
@@ -87,6 +92,12 @@ principal header normalizzati al backend ThothII. La UI usa `/me`; non effettua
 un secondo login. Un altro portale deve soddisfare anche questo contratto server,
 oltre a fornire una nuova implementazione dell'adapter UI.
 
+Il [contratto upstream](../install/authentication-upstream.md) specifica header,
+origine, rete e configurazioni incompatibili. Lo snapshot non può contenere
+`authenticated`, utente, ruoli, cookie o token; un evento browser non autorizza
+una richiesta API. Il prefisso API viene configurato separatamente prima del
+caricamento React, non viene dedotto dall'adapter.
+
 Il logout del portale segue la sua navigazione. Una perdita di accesso rilevata
 dal server chiude lo stato protetto; un 403 di una singola operazione non equivale
 automaticamente a logout. La riconnessione degli eventi e il ritorno alla pagina
@@ -102,9 +113,23 @@ rimane quella registrata nel manifest, secondo ADR 0022.
 
 Un nuovo adapter può usare un diverso documento o trasporto, ma deve rispettare
 la stessa sottoscrizione e mantenere la conoscenza del portale nella propria
-implementazione. Non occorre implementare ora iframe o un secondo portale.
+implementazione. Oggi `ShellProvider` istanzia direttamente `OmicsPortalAdapter`:
+per sostituirlo aggiornare quel punto e i nomi accettati in
+`tools/tht/internal/config/shell.go` e `frontend/src/api/runtime-config.ts`.
+Non è disponibile il caricamento dinamico di classi da una stringa YAML.
+Non occorre implementare ora iframe o un secondo portale.
+
+La nuova implementazione deve pubblicare uno snapshot iniziale completo, poi gli
+aggiornamenti; segnalare contesto invalido; liberare tutti i listener alla
+disiscrizione. Locale ben formato ma non tradotto significa fallback inglese;
+locale assente/malformato e tema diverso da light/dark sono errori di integrazione.
+Non cambiare componenti applicativi o workflow per aggiungere selettori specifici
+del nuovo portale.
 
 Verificare snapshot prima/dopo il montaggio, tema, fullscreen con Esc, cleanup,
 contesto host mancante, assenza di header ThothII embedded, accesso singolo,
 locale dopo reload e compatibilità del prefisso API. Full deve funzionare senza
 alcun elemento Omics presente.
+
+Vedere anche [architettura del rendering](../architecture/application-shell.md)
+e [matrice di accettazione](../testing/authentication-manual-acceptance.md).