# 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
```