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)
2026-08-11 00:47:23 +02:00
parent a81000912a
commit 2137150da3
12 changed files with 946 additions and 0 deletions
@@ -0,0 +1,88 @@
+# Comandi Slash & Scorciatoie da Tastiera
+
+`agy-pi` mette a disposizione un ricco set di comandi slash interattivi e scorciatoie globali per interagire con l'estensione direttamente dal terminale di `pi`.
+
+---
+
+## Comandi Slash (Slash Commands)
+
+### Gestione Conversazione agy
+
+| Comando | Descrizione | Sintassi / Esempio |
+|---|---|---|
+| `/agy` | Invia un prompt diretto al subagent `agy` | `/agy Spiega la teoria della relatività` |
+| `/agy:new` | Forza la creazione di una nuova conversazione pulita | `/agy:new` |
+| `/agy:list` | Mostra l'ID della conversazione agy attiva | `/agy:list` |
+| `/agy:reset` | Azzera l'ID conversazione salvato in locale | `/agy:reset` |
+
+---
+
+### Configurazione & Diagnostica TUI
+
+#### `/agy:config`
+Gestisce le opzioni di configurazione salvate in `~/.config/agy-pi/config.json`.
+
+- `/agy:config`: Mostra l'elenco completo di tutte le opzioni con i valori attuali e le descrizioni.
+- `/agy:config get <chiave>`: Stampa il valore di una singola chiave.
+- `/agy:config set <chiave> <valore>`: Modifica il valore di una chiave e salva su disco.
+- `/agy:config reset`: Ripristina le impostazioni predefinite di fabbrica.
+
+#### `/agy:key` (Dialog TUI Overlay)
+Apre una finestra di dialogo grafica in sovrimpressione nel terminale (`pi-tui` overlay) per inserire o modificare la chiave API Gemini:
+
+```
+┌────────────────────────────────────────────────────────┐
+│ 🔑 Chiave API Gemini                                   │
+│ Attuale: AIza...yfDY                                   │
+│                                                        │
+│ Nuova chiave: •••••••••••••••••••••••••••••••••••••    │
+│                                                        │
+│ Digita la chiave • Enter conferma • Esc annulla        │
+└────────────────────────────────────────────────────────┘
+```
+- Input mascherato per prevenire il leak della chiave sul terminale o nella cronologia.
+- Salva contemporaneamente la chiave in `~/.config/agy-pi/config.json` e in `~/.agy-chat/gemini-key` (permessi `0600`).
+
+#### `/agy:status` (Diagnostica TUI Overlay)
+Mostra una dashboard grafica centrata con lo stato di salute dell'estensione:
+
+```
+┌────────────────────────────────────────────────────────┐
+│ 📊 Stato agy-pi                                        │
+│                                                        │
+│ Binario agy: trovato /home/enne2/.local/bin/agy        │
+│ Versione: agy version 1.4.2                            │
+│ Chiave Gemini: ✅ valida                               │
+│ Chiave (mask): AIza...yfDY                             │
+│ Modello attivo: Gemini 3.1 Pro (High)                  │
+│ Backend STT: gemini                                    │
+│ Notifiche TTS: true                                    │
+│                                                        │
+│ Ultimo errore: (nessuno)                               │
+│                                                        │
+│ Enter o Esc per chiudere                               │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+### Registrazione Vocale & TTS
+
+| Comando | Descrizione |
+|---|---|
+| `/agy:record` | Avvia o ferma la registrazione vocale (equivalente al tasto **F12**). |
+| `/agy:record:stop` | Ferma la registrazione attiva ed elabora l'audio. |
+| `/agy:record:cancel` | Annulla la registrazione corrente senza inviare prompt. |
+| `/agy:speak <testo>` | Sintetizza ed esegue l'audio del testo specificato via Gemini TTS. |
+| `/agy:vocal [on\|off\|status]` | Attiva (`on`), disattiva (`off`) o mostra lo stato (`status`) del feedback vocale automatico TTS. |
+
+---
+
+## Scorciatoie da Tastiera (Keybindings)
+
+### Tasto `F12` — Registrazione Vocale Toggle
+- **Primo tocco (`F12`)**: Avvia la registrazione audio tramite `ffmpeg`, riproduce il suono sci-fi *Power Up* e mostra la barra di stato live `🔴 REGISTRAZIONE... MM:SS / MM:SS`.
+- **Secondo tocco (`F12`)**: Interrompe la registrazione, riproduce il suono *Deactivate*, ottimizza l'audio (soppressione silenzio), invia la traccia a Gemini per la trascrizione e trasmette il prompt risultante a `pi`.
+
+### Tasto `Esc` / `Escape` — Annullamento Registrazione
+- Durante una registrazione audio attiva, premere `Esc` o `Escape` abortisce immediatamente il processo `ffmpeg`, rimuove il file temporaneo, riproduce il tono acustico di cancellazione e cancella l'indicatore di stato.