docs: publish English public documentation

docs/general/pi-configuration.md

@@ -1,6 +1,10 @@
-# Configurazione dei modelli in Pi: built-in, utente, progetto
+# Local Pi model configuration
 
-Pi (il coding agent che orchestra il workflow NL→SQL) può risolvere un `provider/model` in tre modi diversi. Non sono alternativi: coesistono, e la scelta di quale usare dipende da **quanto è standard l'endpoint** e da **quanto deve essere ampia la visibilità** del modello (tutti i progetti vs. un progetto solo).
+Pi orchestrates the NL-to-SQL workflow and resolves built-in models and OpenAI-compatible providers
+declared in the local catalog. ThothII applies a stricter rule than Pi: code in
+`harness/.pi/extensions/` cannot register a provider or custom model. Endpoints, protocols,
+compatibility settings, and model identifiers belong exclusively in the local files
+`deploy/pi/models.json` and `deploy/pi/settings.json`.
 
 > **ThothII operator note:** ThothII runs Pi only in Docker Compose. Paths under
 > `~/.pi/agent/` in this document describe Pi's container-side behavior. Operators edit
@@ -8,60 +12,66 @@ Pi (il coding agent che orchestra il workflow NL→SQL) può risolvere un `provi
 > the protected host credential file selected by `PI_AUTH_FILE`; they do not edit files inside
 > the running container.
 
-## Credenziali nel backend container
+## Credentials in the backend container
 
-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
-hosted non mappato o un secret mancante/non sicuro fallisce prima dello spawn con errore sanitizzato.
+In production, configure one generic source: the `THT_SECRETS_FILE` bundle with the
+`THT_MODEL_API_KEY` entry, which is the default for the unified distribution, or
+`THT_MODEL_API_KEY_FILE` as an absolute secret-file path. Do not put the key value in `.env`.
+For each process, `PiProcessManager` rereads and validates the source, normalizes the selected
+provider, and passes only the appropriate native variable to the Pi child
+(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, and so on). It removes the
+generic path, keys for unselected providers, and the old `PI_PROVIDER_API_KEY` from the child
+environment. For a custom provider, the backend derives the variable name from the declarative
+`apiKey` field in `models.json`; a literal value means the catalog is self-contained. Provider-name
+exceptions are not compiled into the code. A missing or insecure secret fails before spawn with a
+sanitized error.
 
-La sorgente generica supporta soltanto provider con una singola chiave: `ant-ling`, `anthropic`,
-`cerebras`, `deepseek`, `fireworks`, `github-copilot`, `google` (anche tramite alias `gemini`),
-`google-vertex` in modalità API key, `groq`, `huggingface`, `kimi-coding`, `minimax`, `minimax-cn`,
+The generic source supports only single-key providers: `ant-ling`, `anthropic`,
+`cerebras`, `deepseek`, `fireworks`, `github-copilot`, `google` (including the `gemini` alias),
+`google-vertex` in API-key mode, `groq`, `huggingface`, `kimi-coding`, `minimax`, `minimax-cn`,
 `mistral`, `moonshotai`, `moonshotai-cn`, `nvidia`, `openai`, `opencode`, `opencode-go`,
-`openrouter`, `together`, `vercel-ai-gateway`, `xai`, i quattro provider `xiaomi*`, `zai` e
+`openrouter`, `together`, `vercel-ai-gateway`, `xai`, the four `xiaomi*` providers, `zai`, and
 `zai-coding-cn`.
 
-I provider composti `amazon-bedrock`, `azure-openai-responses`, `cloudflare-workers-ai` e
-`cloudflare-ai-gateway` non sono rappresentabili da un solo file. La selezione fallisce prima
-dello spawn (anche durante l'elenco modelli); tutte le credenziali ambientali AWS, Azure e
-Cloudflare restano comunque rimosse. Servirà una futura configurazione dedicata per provider per
-supportare questi bundle senza ambiguità.
+The composite providers `amazon-bedrock`, `azure-openai-responses`, `cloudflare-workers-ai`, and
+`cloudflare-ai-gateway` cannot be represented by one file. Selection fails before spawn, including
+when models are listed. AWS, Azure, and Cloudflare environment credentials are still removed. A
+future provider-specific configuration will be needed to support these bundles unambiguously.
 
-## I tre livelli di provenienza di un modello
+## Model sources
 
-### 1. Built-in (compilato dentro Pi)
+### 1. Built-in (compiled into Pi)
 
-Pi viene distribuito con un elenco di modelli già noti (`models.generated.js` dentro il pacchetto `@earendil-works/pi-ai`): Anthropic, OpenAI, Google, e anche provider di terze parti con API pubblica ben nota come DeepSeek. Per questi **non serve alcuna configurazione**: bastano le credenziali (env var o `pi auth`).
+Pi ships with a list of known models (`models.generated.js` in the `@earendil-works/pi-ai` package):
+Anthropic, OpenAI, Google, and third-party providers with well-known public APIs such as DeepSeek.
+These require **no configuration** beyond credentials, provided through an environment variable or
+`pi auth`.
 
-`deepseek/deepseek-v4-pro` è così: è nella build di Pi perché `api.deepseek.com` è un'API pubblica documentata, non un endpoint interno.
+`deepseek/deepseek-v4-pro` is one of these models. It is included in Pi because `api.deepseek.com`
+is a documented public API, not an internal endpoint.
 
-### 2. `models.json` a livello utente (`~/.pi/agent/models.json`)
+### 2. User-level `models.json` (`~/.pi/agent/models.json`)
 
-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).
+For an **OpenAI-compatible** endpoint that is not built in but needs no special transport logic,
+declare it with its baseUrl, apiKey, and model list. This file exists **only at user level**; there is
+no project-level equivalent, and `./.pi/models.json` is not read.
 
-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.
+In ThothII-managed installations, the file must be entirely declarative. ThothII recursively
+rejects any JSON value that starts with `!`, including values inside `headers`, `models`,
+`modelOverrides`, `compat`, arrays, or fields it does not yet know. Pi 0.80.3 would treat that
+prefix as a shell command when making a request, so managed model catalogs do not allow it. The
+returned error is fixed and contains no command, path, or 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 `!`.
+For secrets, use an environment reference such as `"$ZAI_API_KEY"` or `"${ZAI_API_KEY}"`. The
+backend can populate the native variable for the selected provider by reading
+`THT_MODEL_API_KEY_FILE`, or from the `THT_SECRETS_FILE` bundle (`THT_MODEL_API_KEY`). Credentials
+can also come from the protected file mounted through `PI_AUTH_FILE`, with `apiKey` omitted from
+`models.json`. There is no direct secret-file reference syntax in `models.json`. With `THT_MODEL_*`
+sources, ThothII reads the file and turns it into the Pi child's environment variable; `PI_AUTH_FILE`
+is mounted instead as a protected Pi credential store. For a literal leading exclamation mark, Pi's
+declarative syntax is `$!`, not `!`.
 
-Esempio reale in uso su questa macchina — GLM (provider `zai`):
+Real example in use on this machine: GLM (provider `zai`):
 
 ```json
 {
@@ -84,113 +94,113 @@ Esempio reale in uso su questa macchina — GLM (provider `zai`):
 }
 ```
 
-Essendo a livello utente, GLM è visibile da **qualsiasi progetto**.
+Because it is user-level, GLM is visible to **every project**.
 
-### 3. Estensione (`.pi/extensions/*.js`, utente o progetto)
+### Extension providers: not allowed in ThothII
 
-Quando l'endpoint richiede codice — ad esempio conversione di eventi (thinking→text), un `streamSimple` custom, o comunque logica che un file dichiarativo non può esprimere — serve un'estensione Pi che chiama `pi.registerProvider(...)`. Le estensioni possono vivere sia in `~/.pi/agent/extensions/` (tutti i progetti) sia in `<progetto>/.pi/extensions/` (solo quel progetto, se Pi viene lanciato con quella cwd).
+Pi technically supports providers registered by JavaScript extensions, but ThothII does not use
+that capability. Project extensions are reserved for the workflow and gates; they must not contain
+`registerProvider(...)`. An endpoint that cannot be described by the OpenAI-compatible catalog is
+not supported by this installation until the declarative contract is extended generically.
 
-Esempio reale — il provider AritmoLab (Qwen), interno all'ospedale, usato solo da ThothII: [harness/.pi/extensions/aritmolab-provider.js](../../harness/.pi/extensions/aritmolab-provider.js).
+## Summary table (current machine state)
 
-## Tabella riassuntiva (stato attuale di questa macchina)
-
-| Modello | Livello | Perché | Visibilità |
+| Model | Level | Why | Visibility |
 |---|---|---|---|
-| `deepseek/deepseek-v4-pro` | Built-in Pi | API pubblica nota, già nella build | Tutti i progetti |
-| `zai/glm-5.2` | `~/.pi/agent/models.json` | Endpoint OpenAI-compatible custom (z.ai), nessuna logica speciale | Tutti i progetti |
-| `aritmolab/qwen3.6-35b-a3b` | Estensione di progetto | Endpoint interno ospedaliero + conversione eventi thinking→text custom | Solo ThothII (cwd=`harness/`) |
+| `deepseek/deepseek-v4-pro` | Built-in Pi | Known public API, already in the build | All projects |
+| `zai/glm-5.3` | `deploy/pi/models.json` | Custom OpenAI-compatible endpoint | ThothII installation |
+| `local-qwen/qwen3.6-35b-a3b` | `deploy/pi/models.json` | Locally configured OpenAI-compatible endpoint | ThothII installation |
 
-## Come scegliere il livello giusto per un nuovo modello
+## Choosing the right level for a new model
 
-1. **L'endpoint è un'API pubblica già nota a Pi?** → niente da fare, verifica con `pi --list-models`.
-2. **È OpenAI-compatible, nessuna logica custom, e deve essere visibile ovunque?** → `~/.pi/agent/models.json`.
-3. **Serve codice custom (auth non standard, conversione eventi, trasporto non-OpenAI) oppure deve restare visibile a un solo progetto?** → estensione, in `~/.pi/agent/extensions/` (globale) o `<progetto>/.pi/extensions/` (locale).
+1. **Is the endpoint a public API already known to Pi?** Enable the exact identifier in `deploy/pi/settings.json`.
+2. **Is it OpenAI-compatible but not built in?** Declare it in `deploy/pi/models.json`, then enable it in `deploy/pi/settings.json`.
+3. **Does it require provider-specific transport code?** Do not add a provider-specific extension. The provider is unsupported until a generic declarative capability exists.
 
 ---
 
-## Ambito utente vs. progetto — riepilogo generale
+## User versus project scope: general summary
 
-Oltre ai modelli, Pi carica altre risorse da due alberi paralleli: `~/.pi/agent/` (utente) e `<cwd>/.pi/` (progetto, risolto in base alla directory da cui viene lanciato `pi`).
+In addition to models, Pi loads other resources from two parallel trees: `~/.pi/agent/` (user) and
+`<cwd>/.pi/` (project, resolved from the directory where `pi` is launched).
 
 | File/Directory | Livello utente | Livello progetto | Auto-discovery | Precedenza |
 |---|---|---|---|---|
-| `models.json` | `~/.pi/agent/models.json` | non supportato | no | solo utente |
-| `settings.json` | `~/.pi/agent/settings.json` | `./.pi/settings.json` | no | progetto sovrascrive utente |
-| `extensions/` | `~/.pi/agent/extensions/` | `./.pi/extensions/` | sì (`.ts`/`.js`) | uniti (progetto + utente) |
-| `prompts/` | `~/.pi/agent/prompts/` | `./.pi/prompts/` | sì (`.md`) | uniti |
-| `themes/` | `~/.pi/agent/themes/` | `./.pi/themes/` | sì (`.json`) | progetto preferito |
-| `skills/` | `~/.pi/agent/skills/` | `./.pi/skills/` | sì (`.md`) | uniti |
+| `models.json` | `~/.pi/agent/models.json` | not supported | no | user only |
+| `settings.json` | `~/.pi/agent/settings.json` | `./.pi/settings.json` | no | project overrides user |
+| `extensions/` | `~/.pi/agent/extensions/` | `./.pi/extensions/` | yes (`.ts`/`.js`) | merged (project + user) |
+| `prompts/` | `~/.pi/agent/prompts/` | `./.pi/prompts/` | yes (`.md`) | merged |
+| `themes/` | `~/.pi/agent/themes/` | `./.pi/themes/` | yes (`.json`) | project preferred |
+| `skills/` | `~/.pi/agent/skills/` | `./.pi/skills/` | yes (`.md`) | merged |
 
-### Esempio reale: ThothII
+### Real example: ThothII
 
 ```
 harness/.pi/
 ├── extensions/
-│   ├── aritmolab-provider.js    ← provider LLM solo-progetto
-│   ├── tht-gate.js               ← gate human-in-the-loop
-│   ├── reserved-labels.mjs       ← utility condivisa (NON auto-caricata; .mjs ignorato)
-│   └── gate/                     ← modulo usato da tht-gate.js
-├── settings.json                 ← (opzionale) override delle impostazioni utente
+│   ├── tht-gate.js               # human-in-the-loop gate
+│   └── gate/
+│       ├── core/                 # shared gate enforcement and utilities
+│       ├── disambiguation/       # F1/F3 policy
+│       └── memory/               # F2/F8 policy
+├── settings.json                 # optional override of user settings
 └── themes/
-    └── thothii-mono.json         ← tema del progetto
+    └── thothii-mono.json         # project theme
 ```
 
-### Comportamento rispetto alla cwd
+### Behavior relative to cwd
 
-La directory da cui lanci `pi` determina quale `.pi/` di progetto viene trovata:
+The directory from which you launch `pi` determines which workflow extensions are found, but not
+which models ThothII makes available. The catalog is mounted in the container's Pi agent directory.
 
 ```bash
-# Da harness/ — trova harness/.pi/extensions/aritmolab-provider.js
+# From harness/: load the project gate and mounted local catalog
 cd /path/to/ThothII/harness
-pi --model aritmolab/qwen3.6-35b-a3b "..."
-
-# Dalla radice di ThothII — nessun .pi/ trovato lì o nei genitori, solo config utente
-cd /path/to/ThothII
-pi --model aritmolab/qwen3.6-35b-a3b "..."  # ❌ Error: model not found
+pi --model local-qwen/qwen3.6-35b-a3b "..."
 ```
 
-Il backend di ThothII (`PiProcessManager`, `list-models.ts`, `model-matrix.mjs`) lancia sempre `pi` con `cwd: harnessDir`, per questo Qwen è visibile in produzione.
+The ThothII backend always launches Pi with `cwd: harnessDir` for the workflow. Model availability
+continues to depend only on `models.json`, `settings.json`, and local credentials.
 
 ---
 
-## Trappola nell'auto-discovery: `.mjs` viene ignorato
+## Auto-discovery trap: `.mjs` is ignored
 
-Il pattern di auto-discovery delle estensioni in Pi è **`/\.(ts|js)$/`** — non include `.mjs`.
+Pi's extension auto-discovery pattern is **`/\.(ts|js)$/`**; it does not include `.mjs`.
 
 ```
 .pi/extensions/
-├── my-extension.js      ✅ auto-caricata
-├── my-extension.ts      ✅ auto-caricata
-├── my-extension.mjs     ❌ ignorata silenziosamente (non combacia col pattern)
-└── shared-module.mjs    ✅ va bene per moduli helper (deliberatamente non caricato come estensione)
+├── my-extension.js      ✅ auto-loaded
+├── my-extension.ts      ✅ auto-loaded
+├── my-extension.mjs     ❌ silently ignored (does not match the pattern)
+└── shared-module.mjs    ✅ suitable for helper modules (deliberately not loaded as an extension)
 ```
 
-Se serve un modulo condiviso importato da un'estensione, usa `.mjs` proprio per evitare che venga trattato come estensione a sé.
+If an extension imports a shared module, use `.mjs` so Pi does not treat it as an extension on its own.
 
 ---
 
 ## Verifica
 
-### Elenco modelli
+### List models
 ```bash
 pi --list-models
 ```
-Mostra i built-in + i modelli utente da `models.json`. **Non mostra** i provider registrati da estensione (come AritmoLab) — quelli vanno verificati con la cwd giusta.
+This shows built-in models and models declared in `models.json`.
 
-### Verifica che un'estensione sia caricata
+### Check the catalog used by the application
 ```bash
-cd harness   # o la cwd rilevante per il progetto
+cd harness   # or the project's relevant cwd
 pi --mode rpc
 # poi: {"type": "get_available_models", "id": "1"}
 ```
-La risposta RPC include tutti i modelli disponibili, inclusi quelli da estensione.
+The RPC response must include only built-in models or models declared in the local catalog.
 
 ---
 
 ## Troubleshooting
 
-| Problema | Causa | Soluzione |
+| Problem | Cause | Solution |
 |---|---|---|
-| `Model "X/Y" not found` lanciando da fuori progetto | Il modello è registrato da un'estensione locale, non visibile fuori dalla cwd giusta | Lancia `pi` dalla directory di progetto corretta (es. `harness/`) |
-| Estensione non caricata pur essendo nella cartella giusta | File `.mjs` invece di `.js`/`.ts` | Rinomina in `.js` |
-| Impostazioni di progetto non applicate | `settings.json` di progetto ha errori di sintassi, o si sta lanciando `pi` dalla cwd sbagliata | Valida il JSON, controlla la cwd |
+| `Model "X/Y" not found` | Provider/model missing from `models.json` or identifier missing from `enabledModels` | Fix the two local files and reload Pi |
+| Project settings not applied | Project `settings.json` has a syntax error, or `pi` is launched from the wrong cwd | Validate the JSON and check the cwd |