diff --git a/brain/codebase/pi-model-selection.md b/brain/codebase/pi-model-selection.md
new file mode 100644
index 00000000..153ff3e6
--- /dev/null
+++ b/brain/codebase/pi-model-selection.md
@@ -0,0 +1,10 @@
+# Pi model selection
+
+- `get_available_models` restituisce tutti i modelli con autenticazione/configurazione disponibile; non applica `settings.json.enabledModels`.
+- Il selettore web usa l'intersezione esatta tra catalogo RPC e `enabledModels`, preservando l'ordine configurato e confrontando `provider/model`.
+- In produzione `PI_PROVIDER` può essere assente: il provider corrente vive in `/data/settings/settings.json`; l'enumerazione Pi deve quindi essere provider-neutral e usare il profilo montato per l'autenticazione.
+- Lo spawn di enumerazione deve comunque passare da `buildPiChildEnv({})` per rimuovere credenziali ambientali e metadati dei secret.
+- `local-qwen` è un provider custom locale esplicito; non richiede la chiave generica dei provider hosted. Provider sconosciuti e composti restano fail-closed.
+- Il profilo Pi live è montato da `/home/chirone/thothii-data/pi-config` a `/home/thoth/.pi`; non leggere né stampare mai i valori di `auth.json`.
+- Le worktree non contengono `deploy/thothii.env` perché è ignorato: per un rebuild dalla worktree rendere disponibile quel file senza copiarne o stamparne il contenuto.
+- La directory host `pi-config` può essere non attraversabile dall'utente di sviluppo. Per una patch autorizzata, concedere accesso minimo temporaneo, usare `apply_patch`, poi ripristinare subito owner e mode e verificarli.
diff --git a/brain/index.md b/brain/index.md
index e9e66fef..4b3f8e4d 100644
--- a/brain/index.md
+++ b/brain/index.md
@@ -1,4 +1,5 @@
 # Brain
 
 - [[codebase/datamart-builder-deployment-gotchas]]
+- [[codebase/pi-model-selection]]
 - [[codebase/workflow-ui-contracts]]