docs: documentazione MkDocs completa + fix build + verifica OpenCV dinamica

- Aggiunti docs/ (9 pagine MkDocs, tema Material) + mkdocs.yml
- Fix mkdocs.yml: repo_url -> git.enne2.net, tasklist (era taskbuttons),
  fence Mermaid via helper locale mermaid_fence.py (def_fence_mermaid
  rimosso da pymdown-extensions moderne)
- Documentate le nuove funzionalità: agy_create_verified (generazione
  verificata con verifica OpenCV DINAMICA generata dall'LLM), workflow
  vocale a 2 fasi (vocalPlanningMode), chiavi config context/webSearch
- tools.md ora documenta 14 tool; vocal-workflow.md include l'overlay di
  conferma piano; configuration.md include vocalPlanningMode
- .gitignore: esclusi site/ e __pycache__/
- Build MkDocs verificata (site/ generato correttamente)

docs/configuration.md

@@ -0,0 +1,87 @@
+# Sistema di Configurazione
+
+L'estensione `agy-pi` implementa un sistema di configurazione gerarchico e persistente, progettato per garantire massima sicurezza ed elasticità sia in ambienti locali che server.
+
+---
+
+## File di Configurazione (`config.json`)
+
+Le impostazioni vengono memorizzate nel file JSON:
+`~/.config/agy-pi/config.json`
+
+!!! security "Sicurezza e Permessi"
+    Il file `config.json` viene creato con permessi restrittivi `0600` (leggibile e modificabile unicamente dall'utente proprietario del processo) per prevenire l'accesso non autorizzato alle chiavi API memorizzate.
+
+---
+
+## Gerarchia delle Risoluzione Chiavi
+
+Quando un modulo o un tool dell'estensione richiede un valore di configurazione (es. `geminiApiKey`), l'estensione segue questa priorità:
+
+```mermaid
+graph TD
+    ENV[1. Variabili d'Ambiente System/Shell] -->|Se assente| CONFIG[2. File ~/.config/agy-pi/config.json]
+    CONFIG -->|Se assente| SECRET[3. File ~/.agy-chat/gemini-key]
+    SECRET -->|Se assente| DEFAULT[4. Valore Default di Fabbrica CONFIG_DEFAULTS]
+```
+
+---
+
+## Tabella delle Opzioni di Configurazione
+
+| Chiave | Tipo | Default | Descrizione |
+|---|---|---|---|
+| `geminiApiKey` | `string` | `undefined` | Chiave API Google Gemini (usata per STT, TTS e Web Search grounding). |
+| `enne2ApiKey` | `string` | `undefined` | Bearer token opzionale per l'autenticazione verso il proxy `ai.enne2.net`. |
+| `sttBackend` | `string` | `"gemini"` | Backend per la trascrizione vocale: `"gemini"` \| `"enne2"`. |
+| `sttUrl` | `string` | `"https://ai.enne2.net"` | URL endpoint base per il backend STT enne2. |
+| `sttModel` | `string` | `"gemma4:E4B"` | Identificativo modello per il backend STT enne2. |
+| `sttMaxDuration` | `number` | `120` | Durata massima della registrazione audio in secondi. |
+| `ttsBackend` | `string` | `"gemini"` | Backend per la sintesi vocale: `"gemini"` \| `"enne2"`. |
+| `ttsNotify` | `boolean` | `true` | Abilita o disabilita le notifiche acustiche/vocali automatiche a fine trascrizione. |
+| `ttsModel` | `string` | `"gemini-2.5-flash-preview-tts"` | Modello Gemini dedicato al Text-To-Speech. |
+| `agyBin` | `string` | `"agy"` | Percorso assoluto o nome del binario eseguibile `agy`. |
+| `agyDefaultModel` | `string` | `undefined` | Modello predefinito per le chiamate ad `agy` (es. `Gemini 3.1 Pro (High)`). |
+| `agyTimeoutMs` | `number` | `180000` | Timeout generale in millisecondi per l'esecuzione di `agy` (3 minuti). |
+| `contextInject` | `boolean` | `true` | Iniezione automatica del contesto dell'agente nel prompt `agy`. |
+| `contextTokens` | `number` | `1500` | Budget massimo di token allocato per il blocco di contesto iniettato. |
+| `webSearch` | `string` | `"auto"` | Modalità ricerca web (Strada A): `"auto"` \| `"on"` \| `"off"`. |
+| `vocalPlanningMode` | `boolean` | `true` | Workflow vocale a 2 fasi: piano + conferma in overlay prima di eseguire. |
+
+---
+
+## Esempio di File `config.json`
+
+```json
+{
+  "sttBackend": "gemini",
+  "sttUrl": "https://ai.enne2.net",
+  "sttModel": "gemma4:E4B",
+  "sttMaxDuration": 120,
+  "ttsBackend": "gemini",
+  "ttsNotify": true,
+  "ttsModel": "gemini-2.5-flash-preview-tts",
+  "agyTimeoutMs": 180000,
+  "contextInject": true,
+  "contextTokens": 1500,
+  "webSearch": "auto",
+  "vocalPlanningMode": true,
+  "geminiApiKey": "AIzaSyD-EXAMPLE_KEY_STRING_HERE"
+}
+```
+
+---
+
+## Variabili d'Ambiente Mappate
+
+Le seguenti variabili di ambiente sovrascrivono la configurazione quando presenti:
+
+```bash
+export GEMINI_API_KEY="AIzaSy..."
+export ENNE2_API_KEY="sk-..."
+export AGY_STT_BACKEND="enne2"    # oppure "gemini"
+export AGY_STT_URL="https://ai.enne2.net"
+export AGY_STT_MODEL="gemma4:E4B"
+export AGY_BIN="/home/utente/.local/bin/agy"
+export AGY_TTS_NOTIFY="0"         # disabilita notifiche TTS
+```