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,77 @@
+# Panoramica di agy-pi
+
+<p align="center">
+  <img src="../assets/agy-pi-logo.jpg" alt="agy-pi logo" width="220"/>
+</p>
+
+**`agy-pi`** è un'estensione avanzata per **pi** (`@earendil-works/pi-coding-agent`) che integra **Google Antigravity CLI (`agy`)** e le API di **Gemini multimodale** come subagent autonomo e assistente multimodale dentro l'ambiente di pi.
+
+---
+
+## Il Problema & La Soluzione
+
+| Sfida | Soluzione offertata da `agy-pi` |
+|---|---|
+| **Limitazione Text-Only di pi** | `agy-pi` agisce da ponte multimodale: pi delega ad `agy` l'elaborazione di immagini, audio, video e compiti di ragionamento profondo. |
+| **Generazione & Editing Immagini** | Implementa formule narrative strutturate ([Soggetto]+[Azione]+[Stile], Keep+Change+Add+Render, Inpainting, Style Transfer, Composizione Multi-Immagine, Character Consistency). |
+| **Input Vocale Senza Mani** | Scorciatoia **F12** con registrazione microfono, indicatore TUI live, soppressione silenzio, feedback sonori sci-fi e trascrizione nativa via Gemini/enne2. |
+| **Multimodalità Ibrida (Voce + Tastiera)** | Integra automaticamente il testo presente nel campo editor di pi con il messaggio vocale registrato. |
+| **Context Lost in the Middle** | Sistema di Context Injection in 4 fasi (`<environment_snapshot>`, `<session_state>`, `<durable_memory>`, `<web_context>`) con token cap ed euristiche anti-ridondanza. |
+
+---
+
+## Caratteristiche Principali
+
+```mermaid
+graph TD
+    PI[pi Coding Agent] -->|Tool Call / Slash Command| EXT[agy-pi Extension]
+    
+    subgraph Core Features
+        EXT --> TOOLS[14 Specialized Tools]
+        EXT --> VOCAL[Workflow Vocale F12]
+        EXT --> CTX[Context Injection Engine]
+        EXT --> TUI[TUI Overlays /agy:key & /agy:status]
+    end
+    
+    TOOLS --> AGY_CLI[Google Antigravity CLI agy]
+    VOCAL --> GEMINI_STT[Gemini STT / enne2 STT]
+    VOCAL --> GEMINI_TTS[Gemini TTS / Feedbacks Sonori]
+    CTX --> MEMORY[Memory JSON & Web Search Grounding]
+```
+
+1. **Subagent Multimodale Avanzato**: Espone 14 strumenti specializzati riconosciuti dall'LLM di pi per generare, modificare ed analizzare asset multimediali, inclusa la **generazione verificata iterativa** (`agy_create_verified`) con verifica visione + OpenCV dinamico.
+2. **Sistema di Configurazione Persistente**: Configurazione via `/agy:config` salvata con permessi restrittivi `0600` in `~/.config/agy-pi/config.json`.
+3. **Interfaccia Grafica TUI**: Dialoghi interattivi in sovrimpressione (`/agy:key` per mascherare e gestire la chiave API Gemini e `/agy:status` per la diagnostica di sistema).
+4. **Modulo Vocale Sci-Fi Integrato**: Registrazione ad alte prestazioni via `ffmpeg`, rilevamento automatico del parlato (`volumedetect`), compressione `libopus`/`libmp3lame` e feedback acustici sintetizzati proceduralmente.
+
+---
+
+## Requisiti e Dipendenze
+
+- **Node.js**: >= 18.x / v22.x
+- **pi-coding-agent**: `@earendil-works/pi-coding-agent`
+- **Google Antigravity CLI (`agy`)**: Installato e autenticato in locale (es. `~/.local/bin/agy`).
+- **ffmpeg**: Necessario per il recording del microfono, la rimozione del silenzio e i feedback sonori procedurali.
+- **Utilità Audio System**: `paplay` (PulseAudio), `aplay` (ALSA) o `ffplay`.
+
+---
+
+## Installazione Rapida
+
+```bash
+# Installazione da repository locale
+pi install /percorso/a/agy-pi
+
+# Oppure test dinamico senza installazione permanente
+pi -e /percorso/a/agy-pi
+```
+
+Configura la chiave API Gemini per la trascrizione vocale e la ricerca web:
+
+```bash
+# Tramite overlay grafico dentro pi:
+/agy:key
+
+# Oppure via linea di comando:
+/agy:config set geminiApiKey AIzaSy...
+```