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/troubleshooting.md

@@ -0,0 +1,67 @@
+# Troubleshooting & Diagnostica
+
+Guida alla risoluzione dei problemi comuni durante l'utilizzo dell'estensione `agy-pi`.
+
+---
+
+## 1. Strumento Diagnostico Integrato (`/agy:status`)
+
+Prima di procedere con la ricerca manuale dei guasti, esegui il comando slash dentro `pi`:
+
+```
+/agy:status
+```
+
+L'overlay TUI diagnostico verificherà automaticamente:
+- Esistenza e versione dell'eseguibile `agy`.
+- Presenza e validità della chiave API Gemini.
+- Backend STT e stato notifiche TTS attivi.
+- Ultimo messaggio di errore registrato nei log di `agy`.
+
+---
+
+## 2. Problemi Frequenti e Soluzioni
+
+### A. Binario `agy` non trovato (`bash: agy: command not found`)
+- **Causa**: Il binario `agy` non si trova nel `PATH` di sistema o nell'ubicazione standard `~/.local/bin/agy`.
+- **Soluzione**: Imposta il percorso esplicito dell'eseguibile:
+  ```
+  /agy:config set agyBin /percorso/assoluto/a/agy
+  ```
+
+### B. Registrazione vocale F12 fallita o senza audio
+- **Causa 1**: `ffmpeg` non è installato nel sistema.
+  - **Soluzione**: Installa `ffmpeg` tramite il package manager della tua distribuzione (es. `sudo apt install ffmpeg`).
+- **Causa 2**: Nessun parlato rilevato (`audioHasSpeech` ritorna errore).
+  - **Soluzione**: Verifica il microfono e alza il livello di guadagno di PulseAudio/ALSA.
+- **Causa 3**: Mancanza dell'utility di riproduzione audio PulseAudio (`paplay`).
+  - **Soluzione**: Installa `pulseaudio-utils` oppure lascia che il sistema usi il fallback automatico `aplay` / `ffplay`.
+
+### C. Errore API Gemini o Key Mancante (`HTTP 401` / `HTTP 403`)
+- **Causa**: La chiave API Gemini non è stata inserita o è scaduta.
+- **Soluzione**: Apri l'overlay grafico per configurare la chiave in modo sicuro:
+  ```
+  /agy:key
+  ```
+
+### D. Immagine generata non trovata (`IMAGE_PATH` assente)
+- **Causa**: `agy` ha completato l'operazione ma non ha restituito il pattern `IMAGE_PATH` o il modello non ha generato un file su disco.
+- **Soluzione**: Aumenta il timeout di generazione portando `agyTimeoutMs` a 300000 (5 minuti) o imposta `stateless: true`.
+
+### E. Errore HTTP 413 (`Payload Too Large`) durante la trascrizione audio
+- **Causa**: File audio di grandi dimensioni inviato in formato WAV grezzo.
+- **Soluzione**: L'estensione converte automaticamente i WAV in formato **Opus/OGG** (`libopus` a 16kbps). Assicurati che `ffmpeg` sia compilato con supporto a `libopus` o `libmp3lame`.
+
+---
+
+## 3. Ispezione dei Log
+
+I log dettagliati delle interazioni della CLI `agy` sono memorizzati in:
+
+`~/.gemini/antigravity-cli/log/`
+
+Per visualizzare l'ultimo errore di sistema:
+
+```bash
+ls -t ~/.gemini/antigravity-cli/log/* | head -1 | xargs tail -n 50
+```