---
name: doc-infografica
description: "Genera infografiche professionali usando Gemini AI e le salva come PNG. Usa questa skill quando l'utente chiede di creare un'infografica, diagramma visivo, visual per documenti o presentazioni, immagine generata da AI per report. Triggera quando l'utente menziona: infografica, visual, diagramma illustrato, immagine per documento, Gemini immagine, processo visivo, flusso illustrato, schema grafico. NON usare per grafici dati puri (bar/pie chart)."
---

# doc-infografica — Generazione Infografiche con Gemini AI

Genera infografiche professionali con Google Gemini AI per documenti, presentazioni e report.

## Prerequisiti

- **GEMINI_API_KEY**: variabile d'ambiente con la chiave API Google AI Studio
- **Node.js 18+**: per lo script TypeScript

Verifica:
```bash
echo $GEMINI_API_KEY  # deve stampare la chiave
```

## Workflow

### 1. Raccogli la descrizione

Se `$ARGUMENTS` contiene una descrizione:
- Usala direttamente
Altrimenti:
- Chiedi all'utente cosa deve mostrare l'infografica
- Chiedi il tipo: processo, confronto, timeline, architettura, KPI, pricing

### 2. Classifica il tipo

Identifica automaticamente il tipo di infografica dalla descrizione:

| Parole chiave | Tipo |
|---------------|------|
| step, fasi, flusso, processo, workflow | `processo` |
| vs, confronto, comparazione, alternativa | `confronto` |
| timeline, roadmap, piano, mesi, trimestri | `timeline` |
| architettura, componenti, sistema, struttura | `architettura` |
| KPI, metriche, numeri, dashboard, risultati | `kpi` |
| prezzo, pricing, pacchetti, offerta economica | `pricing` |

### 3. Scegli lo stile

Presenta i 5 stili (vedi `doc-offerta/references/style-catalog.md`):

1. Corporate Dark
2. Modern Light (default)
3. Minimal
4. Elegant Gold
5. Tech Blue

Se `--style <nome>` e' in `$ARGUMENTS`, usa quello.

### 4. Costruisci il prompt

Prendi il template appropriato da `doc-offerta/references/prompt-templates.md`:
- Inietta la descrizione dell'utente
- Inietta il "Gemini style prompt" dello stile scelto
- Lingua: italiano (default) o come specificato con `--lang`

### 5. Chiama Gemini API

```bash
npx tsx doc-production/scripts/generate-infografica.ts \
  --prompt "il prompt completo" \
  --style modern-light \
  --output ./output/ \
  --name "nome-infografica"
```

Lo script:
1. Chiama `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent`
2. Payload: `responseModalities: ["image", "text"]`
3. Estrae l'immagine dalla risposta (base64 → PNG)
4. Salva in `./output/nome-infografica.png`

### 6. Gestisci errori e retry

| Errore | Azione |
|--------|--------|
| 400 Bad Request | Semplifica il prompt |
| 429 Rate Limit | Attendi 30s, riprova (max 3) |
| Safety block | Riformula senza termini problematici |
| Solo testo, nessuna immagine | Aggiungi "Generate an image, do not just describe it" |
| 3 fallimenti consecutivi | Genera SVG programmatico come fallback |

### 7. Fallback SVG (quando Gemini non funziona)

Per infografiche con testo preciso (KPI, numeri, nomi):

```typescript
// Genera SVG programmatico con Node.js
const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900">
  <rect width="100%" height="100%" fill="${style.background}"/>
  <!-- elementi SVG generati dinamicamente -->
</svg>`;

// Salva come .svg (apribile in browser e importabile in Word)
fs.writeFileSync('./output/infografica-fallback.svg', svg);
```

### 8. Consegna

Mostra:
```
Infografica generata: ./output/nome-infografica.png
Dimensioni: 1600x900 px
Tipo: [processo/confronto/timeline/architettura/kpi/pricing]
Stile: [nome stile]
Modello: gemini-2.5-flash-image
```

## Modelli Gemini disponibili

| Modello | Flag `--model` | Qualita | Velocita |
|---------|---------------|---------|----------|
| gemini-2.5-flash-image | `flash` (default) | Buona | 15-30s |
| gemini-2.5-pro-preview | `pro` | Alta | 30-90s |

## Esempio d'uso

```
> /doc-infografica processo di onboarding cliente in 4 fasi: Contatto iniziale, Analisi requisiti, Proposta, Kick-off --style elegant-gold

Tipo rilevato: processo (4 step)
Stile: Elegant Gold

Genero con Gemini (gemini-2.5-flash-image)...
✓ Infografica generata: ./output/onboarding-cliente.png

Per inserirla in un documento, usa /doc-offerta con il marker:
<!-- infografica: processo onboarding 4 fasi -->
```

## Uso in batch (chiamata da /doc-offerta)

Quando invocata da `/doc-offerta`, riceve parametri strutturati:
```bash
npx tsx doc-production/scripts/generate-infografica.ts \
  --prompt "..." --style "..." --output "./output/infografiche/" --name "infografica-03"
```

Non chiede conferme — genera e salva direttamente.