# Analytics workflow

## Query read-only

Sequenza consigliata:

1. `analytics_status`
2. `analytics_summary`
3. `analytics_models`
4. `analytics_events`
5. `analytics_sessions`, solo se serve dettaglio sessioni senza contenuti

Per `analytics_sessions`, omettere `include_technical` conserva l'elenco legacy non filtrato. Passare `false` restituisce solo sessioni principali conversazionali con messaggi; passare `true` restituisce tutte le sessioni.

## Scan

Usare `analytics_scan` quando:

- l'utente chiede dati aggiornati;
- una sorgente non compare;
- l'ultimo scan e' vecchio;
- un adapter e' stato appena aggiunto o corretto.

Preferire scan mirati:

```json
{ "sources": ["codex"], "dry_run": true }
```

Poi scan reale solo se il piano e' corretto:

```json
{ "sources": ["codex"], "dry_run": false }
```

Dopo uno scan, usare `analytics_scan_details` per il run appena eseguito oppure per l'ultimo run
completato. I dettagli espongono solo severita', codice, occorrenze e ID file privacy-safe.
`info` e' diagnostico e non rende allarmante uno scan sano; `warning` indica record recuperabili;
`error` identifica file non importabili e ritentabili.

## Sorgenti

Usare solo source canoniche:

```text
codex
copilot
claude
cursor
antigravity
hook_log
```

## Output atteso

Ogni risposta deve distinguere:

- dati osservati;
- warning;
- dati non disponibili;
- azione consigliata.

Non inventare token, modelli o eventi non presenti nei log locali.

## Contatori messaggi

- `sessions.message_count` conta esclusivamente i messaggi conversazionali.
- `user_message_count` e `assistant_message_count` sono contatori conversazionali per ruolo; il primo e' il KPI funzionale dell'attivita' utente.
- Le metriche Codex `token_count` restano in `message_metrics` con `metadata_json.metric_kind="telemetry"`, ma non incrementano i contatori conversazionali della sessione.
- Nei tool aggregati, `messages` e' il KPI funzionale e deve contare solo messaggi utente principali.
- `analytics_scan.messages_upserted` e' un contatore tecnico del run di import, non un totale funzionale giornaliero.