fix: reject executable pi configuration

docs/contracts/thothctl-pi.md

@@ -36,6 +36,18 @@ file and verifies the absent/default state. Empty prior files are supported. The
 the actual host path from `PI_AUTH_FILE`; credentials remain in that protected host file and must
 never be passed as flags.
 
+Installation-managed Pi provider/model configuration is declarative only. Any JSON value beginning
+with `!` is rejected recursively in the complete `models.json` before it can supply management
+choices, and the exact selected provider/model and credential payload is checked again before the
+isolated smoke files are written. The API returns only the fixed
+`Pi provider/model configuration is invalid` message; rejected commands, paths, and secrets are
+never included. Use `$NAME`/`${NAME}` environment references in `models.json`, or omit `apiKey` and
+provide the selected credential through the protected `PI_AUTH_FILE`, `THT_MODEL_API_KEY_FILE`, or
+`THT_SECRETS_FILE` contract. A literal leading exclamation mark uses Pi's `$!` escape. Direct
+secret-file references are not a `models.json` feature: ThothII converts its managed key source to
+the provider-native child environment, while `PI_AUTH_FILE` is mounted as Pi's protected credential
+store.
+
 ## Supported Compose entry points and current image
 
 Use `thothctl start`, `stop`, `status`, `logs`, and `doctor` for ordinary installation lifecycle

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