fix: reject executable pi configuration

docs/general/pi-configuration.md

@@ -4,9 +4,11 @@ Pi (il coding agent che orchestra il workflow NL→SQL) può risolvere un `provi
 
 ## Credenziali nel backend container
 
-In produzione configurare una sola sorgente generica, `THT_MODEL_API_KEY_FILE`, come secret file
-assoluto e non il valore della chiave. `PiProcessManager` rilegge e valida il file per ogni processo,
-normalizza il provider selezionato e passa al solo child Pi la variabile nativa appropriata
+In produzione configurare una sola sorgente generica: il bundle `THT_SECRETS_FILE` con la voce
+`THT_MODEL_API_KEY` (predefinito della distribuzione unificata), oppure
+`THT_MODEL_API_KEY_FILE` come secret file assoluto. Non mettere il valore della chiave in `.env`.
+`PiProcessManager` rilegge e valida la sorgente per ogni processo, normalizza il provider
+selezionato e passa al solo child Pi la variabile nativa appropriata
 (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, ecc.). Il percorso generico,
 le chiavi di provider non selezionati e il vecchio `PI_PROVIDER_API_KEY` vengono rimossi dall'ambiente
 del child. Provider locali come `ollama`, `lmstudio` e `aritmolab` continuano senza chiave; un provider
@@ -37,6 +39,22 @@ Pi viene distribuito con un elenco di modelli già noti (`models.generated.js` d
 
 Per un endpoint **OpenAI-compatible** che non è tra i built-in — ma che non richiede nessuna logica di trasporto speciale — basta *dichiararlo*: baseUrl, apiKey, lista modelli. Questo file esiste **solo a livello utente**: non c'è un equivalente project-level (un `./.pi/models.json` non viene letto).
 
+Nelle installazioni gestite da ThothII il file deve essere interamente dichiarativo. ThothII
+rifiuta ricorsivamente qualsiasi valore JSON che inizi con `!`, anche dentro `headers`, `models`,
+`modelOverrides`, `compat`, array o campi non ancora conosciuti. Pi 0.80.3 tratterebbe quel prefisso
+come un comando shell al momento della richiesta; questa forma non è ammessa né dall'elenco gestito
+dei modelli né dallo smoke isolato. L'errore restituito è fisso e non include comando, percorso o
+secret.
+
+Per i secret usare un riferimento ambiente come `"$ZAI_API_KEY"` o `"${ZAI_API_KEY}"`. Il backend
+può popolare la variabile nativa del solo provider selezionato leggendo
+`THT_MODEL_API_KEY_FILE`, oppure dal bundle `THT_SECRETS_FILE` (`THT_MODEL_API_KEY`); in alternativa
+le credenziali possono arrivare dal file protetto montato con `PI_AUTH_FILE`, omettendo `apiKey` da
+`models.json`. Non esiste una sintassi di riferimento diretto a un secret file dentro
+`models.json`: con le sorgenti `THT_MODEL_*` il file viene letto da ThothII e trasformato nella
+variabile ambiente del child Pi; `PI_AUTH_FILE` viene invece montato come archivio credenziali Pi
+protetto. Per un punto esclamativo letterale iniziale, la sintassi Pi dichiarativa è `$!`, non `!`.
+
 Esempio reale in uso su questa macchina — GLM (provider `zai`):
 
 ```json