COACHINT: tutorial

Versione 0.20 · ottobre 2026 · per gli amici del PoC e i coach

[NOME ORGANIZZATORE] indica chi gestisce la prova: sostituiscilo prima di condividere questo tutorial.

In una frase: COACHINT legge i dati di allenamento dell'atleta, impara cosa è normale per lui o per lei e ogni settimana dice cosa è cambiato e perché conta. Per la prova, ogni amico entra nella propria pagina, i dati arrivano dall'export dell'orologio, da Polar o da Intervals.icu, e il digest arriva ogni mattina su Telegram o per email.

Da dove partire:

• Sei un amico nella prova: leggi le sezioni da 1 a 3, poi la 6 (come mandare i tuoi dati) e la 8 (il digest quotidiano).
• Vuoi usarlo sul tuo computer, o gestisci la prova: comincia da Preparazione: installare uv qui sotto.
• Gestisci la prova (l'admin): leggi tutto; le sezioni da 6 a 10 hanno una parte Se gestisci la prova.

L'app si può usare in italiano: scegli IT alla voce Language del Menu in alto (parte già in italiano se il browser è in italiano). Le note possono essere in italiano o in inglese.

Preparazione: installare uv

Serve solo per usare COACHINT sul tuo computer (sezione 2C) o per ospitarlo (sezione 9). Gli amici che usano la propria pagina nel browser possono saltare questa parte.

COACHINT si installa e si avvia con uv, un unico programma che installa la versione giusta di Python e tutto ciò che serve a COACHINT. Non devi installare Python da solo. Serve anche git per scaricare il codice (su Windows, da https://git-scm.com; su macOS, esegui xcode-select --install se git manca).

macOS (nel Terminale):

curl -LsSf https://astral.sh/uv/install.sh | sh

Con Homebrew puoi invece eseguire brew install uv.

Linux (in un terminale):

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Oppure, con winget: winget install --id=astral-sh.uv -e.

Poi chiudi e riapri il terminale, così trova il nuovo comando, e verifica che funzioni:

uv --version

Stampa un numero di versione, per esempio uv 0.8.17. Se dice che il comando non esiste, apri una nuova finestra del terminale; su un server, esegui una volta source ~/.local/bin/env. Per aggiornare uv in seguito: uv self update (se l'hai installato con Homebrew o winget, aggiornalo da lì).

1. Cosa vedrai

• A sinistra, il gruppo, ordinato da chi ha più bisogno di attenzione: Attention (attenzione), Monitor (da tenere d'occhio) o Stable (stabile). Il gruppo lo vede solo l'admin: un amico vede solo la propria pagina (sezione 2).
• A destra, l'atleta selezionato, con:
  • Ask about your data, la chat, subito sotto il nome: chiedi quello che vuoi sulla settimana, con parole tue;
  • i segnali della settimana, ognuno con i numeri che lo giustificano;
  • Load and recovery (carico e recupero): carico settimanale e frequenza cardiaca a riposo, HRV o sonno, entrambi rispetto al range abituale dell'atleta;
  • le attività della settimana, le sue note, gare ed eventi, cibo e calorie, il digest come arriva su Telegram o per email, e i digest passati (gare e digest passati all'inizio sono nascosti: spuntali in Account, Tiles on the page).

Ogni sezione è un riquadro: la riga del titolo dice cosa c'è dentro (5 activities · 78 km, 2 notes) e un tocco la apre o la chiude. This week e Load and recovery partono aperte; la pagina ricorda cosa apri o chiudi. Expand all e Collapse all (Espandi tutto, Comprimi tutto), sopra il primo riquadro, li aprono o li chiudono tutti insieme. I puntini a sinistra del titolo di un riquadro lo spostano: trascinali con il mouse o con un dito, o selezionali e premi le frecce su e giù. L'ordine resta con il tuo account (nel browser per l'admin e la demo online), e Usual order (Ordine abituale) rimette i riquadri come prima. Spostare i riquadri è una prova: potrebbe sparire se nessuno lo usa.

Ogni numero viene dallo storico dell'atleta stesso. Niente è confrontato con norme generiche e niente è una diagnosi medica.

2. Aprire l'app

Ci sono tre modi. Gli amici nella prova usano il primo.

A. La tua pagina (amici nella prova)

[NOME ORGANIZZATORE] ti manda, in privato, un link, un nome utente (il tuo nome, per esempio marco) e una password.

1. Apri il link. Il browser chiede nome utente e password: scrivi quelli che hai ricevuto. Il browser può ricordarli.
2. Vedi i tuoi dati, in una colonna. Nessun altro nella prova li vede, a meno che tu sia in un gruppo: un allenatore che segue il tuo gruppo li vede dopo che hai accettato, e in un gruppo che condivide i membri che hanno accettato si vedono tra loro, ma solo dopo che accetti anche tu, nella tua pagina Sharing. Lì puoi anche scegliere i tuoi allenatori, in My coaches (più sotto). [NOME ORGANIZZATORE], come admin, vede tutti.
3. La prima volta, una riga in cima propone How to read this (come leggere la pagina), una breve visita guidata: illumina una parte della pagina alla volta (il gruppo, i quattro numeri, i segnali della settimana, la chat, le note, la scelta della settimana), oscura il resto e la spiega in un riquadro; Next (Avanti) e Back (Indietro) la percorrono, Skip the tour (Salta la guida) o Esc la chiude. Chiudi la riga con ✕; la visita resta nel Menu.

Allenatori che si allenano anche loro. Un allenatore può essere anche atleta. Un interruttore nella barra in alto mostra My training (il mio allenamento), la tua pagina esattamente come un atleta vede la sua, e My athletes (i miei atleti), gli atleti che ti hanno scelto come allenatore e le persone che vedi tramite i gruppi che segui (con la chat da coach per chi alleni). La pagina ricorda quale hai usato l'ultima volta. L'interruttore compare solo quando tieni qui il tuo allenamento: fino ad allora Keep my own training (tieni anche i miei allenamenti) nel Menu ti dà i tuoi dati, vuoti, poi Import aggiunge i file dell'orologio. Nessuno li vede finché non entri in un gruppo e accetti di condividere, nella tua pagina Sharing, come ogni atleta.

Funziona anche sul telefono: la stessa pagina in una colonna, con la settimana in alto e una barra in basso: Athletes (Atleti, il gruppo, per l'admin e gli allenatori), Overview (Panoramica, la pagina dell'atleta), Ask (Chiedi, porta alla chat) e Menu, che si apre dal fondo dello schermo. I segnali della settimana si scorrono di lato.

Installala come app sul telefono. COACHINT va nella schermata Home del telefono come un'app: la sua icona in bianco e nero, a schermo intero, senza le barre del browser. È la stessa pagina, quindi dati, accesso e impostazioni sono gli stessi, e non c'è niente da scaricare da uno store.

• Android (Chrome, Edge o Samsung Internet): apri il link, entra, poi apri il Menu, tocca Install app (Installa l'app con la pagina in italiano) e conferma. Se il pulsante non c'è, usa il menu ⋮ del browser: Installa app o Aggiungi a schermata Home.
• iPhone e iPad (Safari): apri il link in Safari ed entra. Tocca Condividi (il quadrato con la freccia), poi Aggiungi alla schermata Home, poi Aggiungi. Install app nel Menu mostra gli stessi passi.
• Android, da un file dell'app: se [NOME ORGANIZZATORE] ti ha mandato COACHINT.apk (o un link di test di Google Play), aprilo sul telefono e installalo. Per un APK, Android ti chiede di permettere al browser o all'app dei file di installare app sconosciute: consentilo, installa, poi toglilo di nuovo. È lo stesso COACHINT, quindi entra come al solito.

Da quel momento apri COACHINT dalla sua icona. Resti dentro per 14 giorni, poi ti richiede l'accesso: lascia che il gestore di password del telefono ricordi la tua password.

Tieni la password per te. Se la perdi o pensi che qualcun altro la conosca, chiedi a [NOME ORGANIZZATORE] una password nuova: quella vecchia smette subito di funzionare.

La pagina di accesso, e registrarti da solo. Il link apre la pagina di accesso di COACHINT: due righe su cosa fa COACHINT, Leggi la guida (il manuale semplice) e il riquadro Accedi, che prende nome utente e password che ti ha mandato [NOME ORGANIZZATORE], o quelli che hai creato tu. Chi è nuovo preme Crea un account sotto il riquadro, che apre il modulo di registrazione (lì Accedi torna indietro): scegli un nome utente (lettere minuscole, cifre e trattini, come marco-rossi; è quello con cui entri), il tuo nome se vuoi che gli altri lo vedano e una password di almeno 12 caratteri, scritta due volte, poi premi Continua alle condizioni. Se il sito mostra la casella Email (facoltativa), puoi dare il tuo indirizzo: COACHINT ti manda un link per confermarlo, e poi Password dimenticata? sotto Accedi manda un link per scegliere una nuova password (funziona per un'ora). Nessun altro vede il tuo indirizzo. Senza email, se dimentichi la password, [NOME ORGANIZZATORE] ne imposta una nuova. Nella maggior parte dei siti un nuovo account aspetta poi l'approvazione di [NOME ORGANIZZATORE]: fino ad allora vedi In attesa di approvazione, quindi accedi di nuovo più tardi. La pagina parla italiano, inglese, spagnolo, francese e tedesco (link in fondo). Se [NOME ORGANIZZATORE] l'ha attivato, Accedi con Google ti porta su Google, dove scegli il tuo account Google; la prima volta Google chiede se condividere il tuo nome con COACHINT (non la tua email). Se sei nuovo, lo stesso pulsante crea il tuo account. Alcuni siti mostrano anche (o invece) Accedi con Auth0, dove entri con email e password. Gli script possono ancora mandare nome utente e password a ogni richiesta (HTTP basic auth).

Le condizioni d'uso. La prima volta, prima di vedere qualsiasi dato, il sito mostra le condizioni d'uso e l'informativa privacy: cosa viene raccolto, perché, chi lo vede, dove va e come farlo cancellare. Leggile (c'è il link Italiano), spunta le due caselle (una accetta le condizioni, l'altra dà il consenso esplicito al trattamento dei tuoi dati sulla salute, che la legge chiede a parte) e scegli Accetto. Se ti stai registrando, non viene salvato niente su di te finché non accetti; se non accetti, non resta nulla. Quando le condizioni cambiano ti vengono richieste alla visita successiva. Il pulsante Terms nella barra in alto le mostra di nuovo, e Sign out chiude la tua sessione su COACHINT (un browser collegato a Google resta collegato lì).

Chi si registra parte con una pagina vuota e in nessun gruppo: aggiungi i tuoi dati con Import (sezione 5) e chiedi a [NOME ORGANIZZATORE] di aggiungerti a un gruppo se ti alleni con altri.

B. La copia online della demo (solo per dare un'occhiata)

[NOME ORGANIZZATORE] può condividere una copia online della demo: un link che si apre nel browser, con i dati di esempio e senza installare nulla. Se la apri con l'accesso a claude.ai, l'interruttore LLM (Claude) legge le note e scrive la frase di apertura del digest con Claude, sul tuo account Claude e senza chiave API. Le note aggiunte lì restano nel tuo browser, e così le valutazioni Useful / Dismiss che dai ai Past digests di esempio (uno per ciascuno degli ultimi 7 giorni dei dati di esempio). Una barra Play sotto la barra in alto permette di provare i ruoli: scegli Admin, il trainer Elena, Anna, un'atleta che allena anche (con l'interruttore My training / My athletes), o uno degli altri atleti, e la pagina mostra ciò che quella persona vede. Come admin, apri Admin per cambiare ruoli, gruppi e chi può usare la chiave LLM; come atleta, apri Sharing per accettare (o smettere di accettare) di condividere con il Run club e guarda cambiare chi vede chi; come Giulia, apri Sharing per vedere i suoi due allenatori in My coaches (Elena tramite il suo gruppo, Anna che ha scelto lei) e aggiungerne o toglierne uno; come trainer, vedi che i gruppi seguiti si leggono ma non si modificano. Come atleta (o admin) puoi anche aggiungere, modificare o togliere un'attività (sezione 3, Aggiungere un'attività a mano), e modificare o togliere note, cibo, gare e digest passati dell'esempio; restano anch'essi nel tuo browser. Il team lì è inventato, le modifiche restano nel tuo browser e Start over le azzera. Per crearne una tua copia, esegui coachint export samples/ (oppure coachint export mio-gruppo/): viene scritto un solo file, coachint-demo.html, che si apre con un doppio clic e si può mandare per email.

C. Sul tuo computer

Servono uv e git (vedi Preparazione: installare uv qui sopra). Poi scarica il codice e avvia l'app:

git clone https://github.com/drugilsberg/coachint-workspace.git
cd coachint-workspace
uv sync
source .venv/bin/activate    # Windows: .venv\Scripts\activate
coachint app samples/

Con l'ambiente attivato puoi scrivere i comandi coachint … di questa guida così come sono. Senza attivarlo, metti uv run davanti: uv run coachint app samples/.

Poi apri http://localhost:8000 nel browser. Per fermare l'app, premi Ctrl+C nel terminale. Questa versione non ha login: risponde solo sul tuo computer, e nessun dato esce dalla tua macchina a meno che tu non attivi un LLM (sezione 10).

3. Un giro dello schermo

Cosa si può cliccare. La pagina usa ovunque la stessa regola. I quattro numeri in cima alla pagina di un atleta aprono i loro grafici. La riga del titolo di un riquadro (con ⌄ a destra) apre o chiude quella sezione. Una riga atleta con › apre quell'atleta. Il testo sottolineato e i pulsanti fanno qualcosa: i suggerimenti sotto la chat, Route & splits ›, Use your own API key. La settimana nella barra in alto (con ⌄) apre un calendario. Le schede piatte dentro un riquadro (contatori, segnali, grafici) mostrano solo dati. Nel digest, le pastiglie tratteggiate In the message: sono l'immagine dei pulsanti che l'atleta riceve su Telegram o per email, non pulsanti di questa pagina.

Barra in alto

A sinistra c'è il logo di COACHINT: C, h e i in un solo tratto. COAC + HINT: coaching intelligence, e un suggerimento (hint) del tuo coach. Lo stesso logo è l'icona della scheda del browser e compare nelle pagine di accesso.

Nel Menu ci sono:

L'indirizzo nel browser tiene l'atleta e la settimana, per esempio …/#anna/2026-09-06. Ricaricando la pagina, o mandando quel link a qualcuno che può vedere lo stesso atleta, si apre la stessa vista.

Pannello del gruppo (admin, allenatori, gruppi condivisi)

I tre contatori dicono quanti atleti richiedono attenzione, vanno monitorati o sono stabili. Ogni scheda atleta elenca i motivi e un punteggio (score). Il punteggio è la somma dei segnali attivi, pesati per importanza, e cresce quando più segnali capitano insieme o quando una gara importante è vicina.

Per i nuovi atleti compaiono altre due etichette:

• No data (nessun dato): l'atleta esiste ma non ha ancora file. La sua pagina elenca cosa importare, con un pulsante Import files. Non viene contato nei totali.
• Learning (sta imparando): ci sono meno di circa 5 settimane di dati. Una barra mostra a che punto è la baseline (per esempio 23 of about 35 days, 23 giorni su circa 35). I segnali compaiono già, ma migliorano man mano che arrivano dati.

Sul telefono, il gruppo e un atleta sono due schermate: tocca un atleta per aprire la sua pagina, e All athletes (Tutti gli atleti, o Athletes nella barra in basso) torna all'elenco. Sul computer il gruppo resta visibile mentre scorri la pagina di un atleta.

Quattro numeri in cima

Sotto la chat, quattro riquadri mostrano la settimana dell'atleta in breve: Training load (Carico di allenamento: il carico di questa settimana, quello abituale e i chilometri, con le ultime 12 settimane in piccole barre, questa settimana in nero), Resting HR, HRV e Sleep (l'ultimo valore e il range abituale, con le ultime settimane in una piccola linea). Un punto rosso vuol dire che quel numero ha un segnale Watch questa settimana, un punto giallo Keep an eye on. Clicca un riquadro per aprire il suo grafico sotto Load and recovery. Compaiono solo i numeri per cui l'atleta ha dati.

Segnali ("This week")

Ogni scheda dice cosa è successo, rispetto a cosa. Per esempio: "Load this week is +37% vs your usual (last 4 weeks)", cioè il carico di questa settimana è il 37% sopra il solito delle ultime 4 settimane. Un triangolo rosso (Watch) vuol dire da seguire da vicino, un occhio giallo (Keep an eye on) vuol dire da guardare, una spunta verde (Going well) vuol dire che qualcosa sta andando bene. Il colore nella pagina vuol dire sempre una di queste cose, o la partenza e l'arrivo di un percorso; tutto il resto è in bianco, nero e grigio.

Carico e recupero

• Carico settimanale (Weekly training load): in nero la settimana corrente, in grigio le 11 precedenti. La linea tratteggiata è il carico abituale dell'atleta nelle ultime 4 settimane.
• Recupero: scegli Resting HR (frequenza a riposo), HRV o Sleep (sonno) in alto a destra nel grafico (solo quelli per cui l'atleta ha dati). La fascia colorata è il range abituale dell'atleta. Una linea che resta fuori dalla fascia per diversi giorni è un segnale di recupero.

Passa il mouse (o tocca) una barra o un punto per vedere il valore esatto; su una linea, una sottile riga verticale e un punto seguono il puntatore.

Calendario

Calendar (Calendario), sotto il nome dell'atleta, mostra ogni attività e gara in un mese, o in una settimana con Week (Settimana), con ← e → per spostarlo. Sul telefono il mese mostra un'icona per voce: tocca un giorno per elencarle. Ogni attività mostra sport e distanza (o tempo); premila per aprirne i dettagli in Activities this week, nella settimana in cui cade. Premi una gara per vederne luogo, distanza e quanto manca, e Edit (Modifica) per cambiarla (quando il riquadro Races and events è mostrato). Premi un giorno per aggiungerci un'attività (Add activity apre il solito modulo) o una gara (Add race, Aggiungi gara: nome, priorità, luogo, distanza), con la data già inserita. I giorni bordati sono la settimana mostrata dalla pagina. I riquadri nascosti non nascondono nulla nel calendario.

Piano di allenamento

Make a training plan (Crea un piano di allenamento), sotto la chat (o Training plan, Piano di allenamento, nel calendario, o Plan from this day, Pianifica da questo giorno, su qualsiasi giorno del calendario da oggi fino a un anno avanti), prepara una bozza da 1 a 12 settimane da quel giorno. Un allenatore che guarda il calendario di un atleta sceglie solo i giorni da oggi in poi: quelli prima sono in grigio. Scegli il giorno di Start (Inizio) e quante settimane (fino a 12), scrivi se vuoi cosa desideri ("4 sedute a settimana, il lungo la domenica") e premi Make a draft (Crea una bozza). Con un modello la bozza nasce dai tuoi dati e dalle tue parole, e le sue motivazioni sono controllate come una risposta della chat (May stray from the data, Potrebbe allontanarsi dai dati, quando un numero non è nei tuoi dati); senza modello ripete la tua settimana tipica delle ultime 4 settimane, un po' più leggera quando i segnali di questa settimana chiedono attenzione, e lascia liberi i giorni di gara.

Ogni seduta si può cambiare: giorno, sport, intensità, titolo, minuti, chilometri, ripetute (ripetizioni × minuti di lavoro / minuti di recupero) e note; il cestino ne toglie una e Add session (Aggiungi seduta) ne aggiunge una. Le sedute restano in ordine di data: una nuova data sposta la seduta al suo posto, e una trascinata dalla maniglia (o spostata con le frecce) prende il giorno della seduta sotto. Undo (Annulla, o Ctrl+Z) toglie l'ultima seduta aggiunta, tolta o spostata, l'ultima bozza o l'ultimo cambio di inizio. Save to calendar (Salva nel calendario) le mette nel calendario con il bordo tratteggiato: le sedute pianificate non contano mai nel carico né nei segnali. Un allenatore prepara un piano dalla chat dell'allenatore e lo scarica, oppure preme Send to the athlete (Invia all'atleta): il piano compare in cima alla pagina dell'atleta finché non preme Open the plan (Apri il piano), lo cambia se vuole e preme Save to calendar (Salva nel calendario), oppure lo rifiuta con Decline (Rifiuta). Solo chi allena l'atleta può inviarne uno; inviarlo di nuovo sostituisce il piano precedente.

Standard workouts (Allenamenti standard) nella finestra del piano elenca sedute provate dalla scienza dello sport, ognuna con lo studio da cui viene: il 4×4 norvegese, il 30-30 alla velocità del VO2max, la soglia, la corsa facile e il lungo, 30/15 e 4×8 min in bici, il Tabata, una serie alla velocità critica di nuoto e la forza pesante per chi fa endurance. Add to plan (Aggiungi al piano) ne mette una nella bozza al primo giorno libero, da cambiare come ogni altra seduta. Il pulsante con il quaderno su una seduta (Save to my workouts, Salva nei miei allenamenti) la tiene in My workouts (I miei allenamenti), così un allenatore prepara i suoi modelli una volta e li aggiunge al piano di qualsiasi atleta. Ognuno dei tuoi è privato finché non scegli chi lo vede: i tuoi allenatori, le tue connessioni (i tuoi atleti e i tuoi gruppi) o tutti su COACHINT. Quello che altri condividono con te compare in Shared with you (Condivisi con te): aggiungilo a un piano, o Copy to my workouts (Copia nei miei allenamenti) per cambiarlo.

Per metterlo sull'orologio: Garmin workouts (.zip) (Allenamenti Garmin) contiene un allenamento FIT per seduta. Estrai i file, collega l'orologio con il suo cavo, copia i file .fit in GARMIN/NewFiles, scollegalo: li trovi in Allenamento, Allenamenti. Il calendario di Garmin Connect non si può riempire da qui (l'API di Garmin è solo per aziende approvate). Gli orologi Polar accettano solo allenamenti pianificati creati in Polar Flow o inviati dai partner di Polar, quindi per Polar usa Calendar file (.ics) (File del calendario) nel calendario del telefono e imposta le sedute come obiettivi di allenamento in Polar Flow. Il file del calendario funziona con qualsiasi app di calendario.

Per mandare il piano come messaggio, premi Send by email (Invia per email: si apre la tua app di posta con il piano già scritto) o Send by Telegram (Invia su Telegram: Telegram si apre per scegliere la chat); sul telefono Share… (Condividi…) offre tutte le tue app. Il messaggio elenca una seduta per riga, con le note sotto. Parte dalla tua email o dal tuo Telegram: COACHINT non invia niente e non tiene nessun indirizzo.

L'hai seguito? Nel calendario una seduta pianificata passata ha la spunta quando un'attività del suo giorno, dello stesso tipo di sport, l'ha fatta, ed è barrata quando nessuna l'ha fatta. Sotto la griglia, Plan followed (Piano seguito) conta le sedute fatte e la quota del tempo pianificato. Premi una seduta pianificata per vedere quale attività l'ha fatta (Open the activity, Apri l'attività); in Done by (Fatta con) scegline un'altra tra i giorni vicini, o Not done (Non fatta). La demo online ha un piano di esempio per le ultime due settimane dei suoi dati.

Attività della settimana: percorso, profilo e parziali

Il riquadro Activities this week (attività della settimana) elenca ogni allenamento della settimana con distanza, tempo, passo (o velocità) e frequenza cardiaca media. Un allenamento arrivato da un file dell'orologio, da un export o da Intervals.icu mostra Route & splits: toccalo per aprire

• il percorso, disegnato su uno sfondo semplice (punto verde: partenza, punto rosso: arrivo, con la scala);
• passo, frequenza cardiaca o altitudine lungo la distanza (scegli in alto a destra: Pace, Heart rate, Elevation; il passo più veloce sta più in alto);
• i parziali (Splits), una riga per chilometro, i più veloci in nero.

Un allenamento scritto in un file CSV o aggiunto a mano ha solo i totali, quindi non ha percorso. Nel gruppo di esempio, i lunghi della domenica di Anna ce l'hanno.

Show street map mette sotto il percorso una mappa di OpenStreetMap. Solo allora il tuo browser chiede a OpenStreetMap la mappa di quella zona (vede il tuo indirizzo IP e la zona, nient'altro); la scelta resta salvata nel tuo browser, e Hide street map la spegne. Nella copia demo online la mappa stradale può non caricarsi; il percorso è disegnato comunque.

Privacy: un percorso mostra dove una persona si allena, e spesso dove abita. Tu vedi i tuoi percorsi interi; un allenatore o un membro del gruppo li vede senza i primi e gli ultimi 200 metri. Download my data include i tuoi percorsi (activities.json).

Aggiungere un'attività a mano

Per una seduta che nessun orologio ha registrato (un corso in palestra, una nuotata senza orologio, un giro con la bici di un amico), apri Activities this week (attività della settimana) e premi Add activity (aggiungi attività). Scegli lo sport: Run (corsa), Trail run (trail), Walk (camminata), Hike (escursione), Swim (nuoto), Ride (bici), Strength (forza), HIIT oppure Other (altro, poi scrivi lo sport, es. yoga). Ogni modulo chiede il giorno, l'ora di inizio e la durata, e se vuoi frequenza cardiaca media e massima, kcal, un commento, l'Equipment (attrezzatura: scarpe, bici; parte da quella predefinita per lo sport, scelta in Menu, Account, Default equipment (Attrezzatura predefinita), altrimenti dall'ultima usata) e il Workout (l'allenamento previsto, su più righe: incolla quello che ha scritto il coach o la chat). Commenti, allenamenti e note tengono gli a capo: Invio inizia una nuova riga. Poi ogni sport aggiunge i suoi campi:

• Corsa: distanza in km e dislivello (metri di salita).
• Trail: distanza e dislivello.
• Camminata: distanza in km e dislivello.
• Escursione: distanza e dislivello.
• Nuoto: distanza in metri, la piscina (25, 33 o 50 m, oppure acque libere) e le vasche nuotate; se lo lasci vuoto, il modulo le calcola dalla distanza e scrive circa quando la distanza non è un numero intero di vasche.
• Bici: distanza, dislivello e potenza media in watt.
• All'aperto (corsa, trail, camminata, escursione, bici) c'è anche un campo facoltativo Weather (meteo), es. 28 °C, ventoso.
• Forza: gli esercizi, una riga ciascuno (nome, serie, ripetizioni, kg); Add exercise aggiunge una riga.
• HIIT: giri, lavoro e recupero in secondi; lascia vuota la durata e viene calcolata da questi.

Effort (RPE 1–10) (sforzo percepito: quanto è stata dura tutta la seduta, 1 molto facile, 10 al massimo; una breve spiegazione è sotto il campo) è ciò che dà alla seduta un carico di allenamento quando manca la frequenza cardiaca, quindi la pagina chiede uno dei due. L'attività poi conta come una importata: nel carico settimanale e nei segnali, nelle calorie bruciate (nel trail ogni 100 m di dislivello contano come un km in più), nelle risposte della chat, e il suo commento è letto come una nota. La sua riga dice added by hand (aggiunta a mano); aprila con Details (dettagli) per vedere cosa hai scritto, Edit (modifica) per cambiarla, e Remove this activity (togli questa attività) per toglierla. Se dopo arriva il file dell'orologio della stessa seduta, il file prende il suo posto e tiene sforzo, commento ed esercizi. La stessa seduta scritta due volte è rifiutata. Aggiungere un'attività funziona nell'app, sulla tua pagina e nella copia demo online. Nella demo resta nel tuo browser, conta nell'elenco, nel carico e nei chilometri della settimana, nelle calorie bruciate e nelle note che dà il suo commento, mentre gli altri segnali restano quelli dei dati di esempio (il motore dei segnali gira sul server); la data deve essere un giorno che i dati di esempio hanno.

Curioso di sapere da dove viene una stima? Una piccola riga Sources (fonti) sta sotto il campo dello sforzo, il grafico del carico, la nota sulle calorie del riquadro Cibo e calorie e il tuo peso e la tua altezza: cliccala per vedere gli studi dietro ogni numero (anche il README li elenca).

Correggere un'attività importata

Gli orologi sbagliano: una fascia scivolata, un giro continuato in macchina, uno stop dimenticato. Apri una tua attività con Details (dettagli) e premi Edit (modifica): si apre lo stesso modulo con i numeri del dispositivo già compilati. Sport, data e ora di inizio restano (danno il nome alla seduta); cambia durata, distanza, frequenza cardiaca, sforzo, kcal o commento e premi Save changes (salva le modifiche). Da lì carico, segnali, calorie e chat usano i tuoi numeri, una sincronizzazione successiva della stessa seduta non li annulla, e la riga dice edited by hand (modificata a mano). Percorso, parziali e profilo vengono ancora dal dispositivo, quindi un piccolo avviso nel modulo e nei dettagli dice che potrebbero non corrispondere più. Undo my edits (annulla le mie modifiche) riporta i numeri del dispositivo.

Ogni attività dell'elenco della settimana si apre con Details (dettagli), anche una senza percorso né parziali, e ognuna ha una matita (modifica) e un cestino (Remove this activity, togli questa attività) in fondo alla riga, gli stessi pulsanti che sono sotto Details. Una che hai inserito tu viene eliminata. Una importata (una seduta registrata due volte, un orologio lasciato acceso) smette di contare nel carico, nei segnali, nelle calorie e nelle note, e passa in Removed by you (tolte da te) in fondo al riquadro: una sincronizzazione successiva non la riporta, e Bring back (riporta) sì, con le correzioni che aveva. Resta in Download my data (removed-workouts.csv).

Note e digest

I commenti agli allenamenti e le note giornaliere, in italiano o in inglese, vengono letti per cogliere dolore, malattia, stress, motivazione e sensazioni buone. Il riquadro Digest as sent mostra il digest come il messaggio che riceve l'atleta: i 3 punti principali, quanti altri ce ne sono nell'app, la prossima gara e i pulsanti di risposta.

Aggiungere una nota

Apri il riquadro Notes, last 2 weeks, scrivi la nota sopra l'elenco, scegli il giorno (uno qualsiasi delle ultime due settimane) e premi Add note. La nota viene letta subito: una nota come "mi fa male il ginocchio dal km 8" aggiunge un segnale Pain mentioned (dolore citato), fa salire l'atleta nella classifica del gruppo e compare nel digest. Con l'interruttore LLM acceso, il modello legge la nota e riscrive la frase di apertura del digest.

Ogni nota ha Edit (modifica: cambia le parole, poi Save, salva) e Remove (togli), e segnali e digest si aggiornano subito. Una nota scritta da te viene cambiata o eliminata davvero. Una mandata da Intervals.icu è segnata from Intervals.icu: la tua modifica viene tenuta a parte e una sincronizzazione successiva non la annulla (Undo my edits riporta le sue parole), e una tolta non torna. Il commento di un allenamento è segnato comment on an activity (commento a un'attività), con Open the activity (apri l'attività): cambialo con Edit di quell'attività.

• Nella tua pagina o nell'app su un computer, la nota viene salvata con i dati dell'atleta (notes.csv).
• Nella copia online della demo, la nota viene salvata solo nel tuo browser. Remove la cancella.

Fare domande sui tuoi dati

Subito sotto il nome dell'atleta, Ask about your data risponde a domande sulla settimana che stai guardando, in qualsiasi lingua: "Come ho dormito?", "Perché la FC a riposo è alta?", "Quanto manca alla gara?". Le risposte arrivano nella lingua scelta nel menu, a meno che tu non scriva chiaramente in un'altra. Tocca uno dei suggerimenti o scrivi la tua domanda. Può suggerire cosa cambiare nell'allenamento, in base ai tuoi dati. Le risposte non sono consigli medici, come ricorda la riga sotto la chat. How answers work (come funzionano le risposte), lì sotto, dice quale modello risponde e cosa può usare.

• Con un modello, la risposta arriva a parole, nella tua lingua, usando solo i tuoi dati fino a quella settimana. Ogni numero e ogni data della risposta vengono confrontati con i tuoi dati. Se ne cita uno che non c'è, la risposta viene comunque mostrata, con una riga ambra Potrebbe allontanarsi dai dati sotto: toccala per vedere cosa non si trova nei tuoi dati, e controlla quei numeri prima di fidarti.
• Quale modello risponde: la tua chiave API, se ne hai salvata una; altrimenti la chiave dell'admin, se [NOME ORGANIZZATORE] l'ha condivisa con te per i test; altrimenti il modello aperto. La riga sotto ogni risposta dice quale.
• Senza nessun modello, la risposta sono subito le righe dei tuoi dati.
• Un amico può fare domande solo sui propri dati. Le domande che non usano la tua chiave sono limitate a 30 all'ora.
• La risposta cita solo numeri presenti nei tuoi dati, quindi una domanda che richiede un calcolo nuovo ("il mio passo medio negli ultimi 3 mesi") riceve invece le righe più vicine.
• Nella copia online della demo risponde la tua chiave, se l'hai aggiunta (sotto). Altrimenti risponde Claude sul tuo account claude.ai, con gli stessi controlli; aperta come semplice file, fuori da claude.ai, le risposte sono le righe dei dati che corrispondono.

Usare la tua chiave API

Apri Use your own API key sotto la chat, scegli Anthropic o OpenAI, incolla la chiave (la sezione 10 spiega dove prenderla) e premi Save key. Puoi anche scrivere il nome di un modello; altrimenti si usa Claude Opus 5.5 o gpt-5-mini. La chiave viene salvata con i tuoi dati sul server, leggibile solo dal proprietario del server, e non viene più mostrata: la pagina dice solo il fornitore e gli ultimi 4 caratteri. Le domande le paghi al tuo fornitore, e non c'è limite orario. Remove it cancella la chiave. Lo stesso riquadro è nel pannello Account. Save key prima chiede al tuo fornitore se la chiave funziona (una verifica gratuita, nessuna domanda spesa): una chiave che rifiuta, o un nome di modello che non conosce, non viene salvata e il riquadro lo dice. Funziona anche su un sito ospitato senza nessun modello dell'admin.

Nella copia online della demo non c'è un server: la chiave resta solo in quella scheda del browser, finché non la chiudi, e le domande vanno direttamente dal tuo browser ad Anthropic o OpenAI. Alcuni siti che mostrano la demo bloccano queste chiamate; in quel caso la risposta lo dice, e la tua chiave funziona comunque sull'app ospitata.

Il tuo account e la foto profilo

Account nel Menu apre la tua foto profilo e la tua chiave API. Scegli uno dei dodici avatar, oppure Upload a photo (JPEG, PNG o WebP): la pagina la ritaglia a quadrato e la rimpicciolisce prima di inviarla. La tua immagine compare accanto al tuo nome nella lista e sulla tua pagina, a te e alle persone che vedono i tuoi dati. Remove picture torna alle tue iniziali. L'immagine è inclusa in Download my data e viene cancellata con il tuo account. Nella copia online della demo resta nel tuo browser.

Sotto Tiles on the page (Riquadri nella pagina) scegli quali riquadri mostra la tua pagina: Races and events, Food and calories, Digest as sent e Past digests. Gare e digest passati all'inizio sono nascosti: spuntali per vederli. Un riquadro nascosto è solo nascosto: i suoi dati restano, e i segnali, il conto alla rovescia della gara e la chat continuano a usarli. La scelta è salvata con il tuo account e ti segue su ogni dispositivo; per l'admin, e nella copia online della demo, resta nel browser.

Se tieni qui il tuo allenamento, Body (corpo) nello stesso pannello contiene il tuo peso e la tua altezza; Save weight and height li salva. Il peso stima le calorie bruciate da un allenamento quando né l'orologio né il modulo dell'attività le danno (70 kg finché non lo indichi); è lo stesso peso del riquadro Cibo e calorie, quindi cambiarlo in uno dei due posti cambia entrambi. L'altezza è tenuta per una stima del metabolismo a riposo che arriverà più avanti.

Chat dell'allenatore

Un allenatore che guarda uno dei suoi atleti trova Coach chat about Anna al posto della chat dell'atleta. Usa gli stessi dati e lo stesso controllo dei numeri, ma parla a te dell'atleta ("Come adatto la prossima settimana di Anna?", "Di cosa dovrei chiedere ad Anna?") e dà suggerimenti da allenatore. La conversazione è tua: la vedi solo tu, l'atleta no, e la ritrovi la volta dopo (Start a new conversation la cancella). Risponde con la tua chiave, o con quella dell'admin se te l'ha concessa, come la chat. Se l'atleta smette di condividere con te, non la vedi più; se se ne va, viene cancellata. Nella copia online della demo, gioca come l'allenatrice Elena per provarla; lì la conversazione resta nel tuo browser.

Sotto la chat dell'allenatore, Private notes (note private) è un riquadro per quello che vuoi ricordare dell'atleta: cosa avete concordato, cosa tenere d'occhio. Scrivi tutte le righe che ti servono e premi Save notes (salva note). Le vedi solo tu: l'atleta no, e nemmeno i suoi altri allenatori. Sono nel download dei tuoi dati e vengono cancellate se l'atleta se ne va.

Gare ed eventi

Il riquadro Gare ed eventi (nascosto all'inizio: spuntalo in Account, Tiles on the page) elenca le gare per cui ti alleni, dalla più vicina, ognuna con la sua priorità (A l'obiettivo della stagione, B una gara importante, C una gara di allenamento), la data e quanto manca. La prossima fa il conto alla rovescia in cima alla tua pagina, e nelle due settimane prima di una gara A i segnali pesano di più (e un calo del carico è letto come scarico pre-gara).

• Aggiungine una a mano: scrivi il nome e la data, scegli la priorità e, se vuoi, il luogo, la distanza in km e un link alla pagina dell'evento, poi premi Aggiungi evento. Il nome apre il link in una nuova scheda. Modifica e Togli cambiano o tolgono una gara.
• Cerca: scrivi parte del nome di una gara nota (Maratona di Firenze, Maratona di Roma, UTMB) e premi Cerca. I risultati vengono da Wikidata, un database aperto e gratuito; Usa compila nome, luogo, link e, quando Wikidata la conosce, la data della prossima edizione. Controlla la data sulla pagina dell'evento, poi premi Aggiungi evento. A Wikidata vanno solo le parole che hai scritto. Le gare locali più piccole di solito non ci sono: scrivile tu.
• Chi vede i tuoi dati vede anche le tue gare; solo tu le cambi. Sono in Download my data e vengono cancellate con il tuo account. Nella copia demo online quello che aggiungi resta nel tuo browser, e la ricerca funziona solo nell'app.

Scheda atleta

Scheda, accanto a Calendario sotto il tuo nome, apre la tua scheda atleta: un posto fuori dalla dashboard per quello che un allenatore deve sapere oltre ai dati di allenamento. Ha tre sezioni:

• Storia clinica: patologie, interventi, allergie, farmaci e altre note sulla salute, con una data se vuoi (dal, al).
• Infortuni, malattie e pause: ognuno con il giorno in cui è iniziato e, quando è finito, il giorno in cui è finito.
• Risultati passati: la data e la gara, se sei arrivato (o ti sei ritirato, o non sei partito), la distanza e il dislivello, il tuo tempo e il tempo obiettivo, la posizione assoluta e di categoria, le condizioni e un link alla pagina dei risultati. Dalle tue gare… ne compila uno da una gara passata in Gare ed eventi.

Premi il pulsante per aggiungere sotto una sezione, compila il modulo e premi Aggiungi; Modifica e Togli cambiano o tolgono una voce. Ogni sezione ha il suo menu di chi la legge: Privata: solo tu (come partono tutte), I tuoi allenatori (quelli che hai scelto e gli allenatori di un gruppo con cui condividi), I tuoi collegamenti (anche le persone con cui sei collegato o in un gruppo) o Tutti su COACHINT (anche chiunque abbia fatto l'accesso e trovi il tuo profilo nella pagina Persone). La storia clinica e gli infortuni sono dati sulla salute: non vanno oltre I tuoi allenatori, e la prima volta che condividi una delle due l'app ti chiede il consenso; scegliere di nuovo Privata: solo tu lo ritira, e condividere più avanti lo chiede di nuovo. I risultati passati puoi mostrarli a chi vuoi.

La tua chat legge tutta la scheda per risponderti; la chat di chiunque altro legge solo le sezioni che lo raggiungono. La scheda è in Download my data e viene cancellata con il tuo account. Sul sito ospitato l'admin non la apre. Nella copia online della demo Giulia condivide storia clinica e infortuni con i suoi allenatori e tiene privati i risultati; gioca come Elena o Anna per vedere cosa vede un allenatore. Quello che cambi lì resta nel tuo browser.

Novità: cosa condividono i tuoi contatti

Oltre alle persone che vedono già la tua pagina, scegli tu chi vede le tue attività e le tue gare. Nella pagina Persone, sotto Chi vede cosa fai, scegli un livello per Le tue attività e per Le tue gare ed eventi: Privata: solo tu (all'inizio), I tuoi allenatori, I tuoi collegamenti o Tutti su COACHINT. Tutti vuol dire chiunque abbia fatto l'accesso e trovi il tuo profilo, quindi serve Visibile; i visitatori senza accesso non vedono mai niente, e nemmeno l'admin del sito. Di un'attività gli altri vedono data, sport, tempo e distanza, mai frequenza cardiaca, note o percorso.

Il riquadro Novità, l'ultimo della tua pagina (puoi nasconderlo sotto Riquadri nella pagina in Account), elenca, dal più recente, le attività delle ultime due settimane, le gare del prossimo anno e i risultati dell'ultimo anno che i tuoi contatti (i tuoi allenatori, i tuoi atleti, le persone con cui sei collegato o in un gruppo) ti lasciano vedere. Premi un nome, o Bio accanto a qualcuno nella pagina Persone, per aprire la sua scheda Bio: chi è, la bio che ha scritto su di sé, le sezioni della scheda atleta che condivide con te e cos'altro ti mostra. Bio nella pagina di un atleta apre la stessa scheda per l'atleta e i suoi allenatori, con anche lo sport, la frequenza cardiaca a riposo e massima e le prossime gare. Scrivi la tua bio in Account > La tua bio e scegli chi la legge (i tuoi collegamenti, se non scegli un altro livello): un allenatore può presentarsi lì ai suoi atleti. Nella demo online Luca mostra le sue attività ai suoi collegamenti e le sue gare a tutti, Giulia le sue attività ai suoi allenatori e le sue gare ai suoi collegamenti, e Anna i suoi risultati a tutti: gioca come Anna per vedere le Novità piene, o come Marta per vedere cosa vede un estraneo sulla scheda di Luca.

Sotto ogni voce, premi Applaudi per mostrare apprezzamento (premi di nuovo per toglierlo) e Commenta per leggere i commenti e scriverne uno; chi vede la voce li legge, con i nomi. Puoi togliere i tuoi commenti, e qualsiasi commento sulle tue attività, gare e risultati; questi compaiono nelle tue Novità appena qualcuno applaude o commenta. Nella demo Anna ed Elena hanno già applaudito l'ultima corsa di Luca.

Notifiche, segnalazioni e blocchi

Le Notifiche, nel menu, elencano chi ha applaudito o commentato ciò che condividi e chi ha chiesto di collegarsi, dalla più recente; un numero accanto al menu dice quante sono nuove (i nuovi messaggi hanno il loro numero su Messaggi). Premine una per andarci. Se ricevi il riepilogo giornaliero su Telegram o via email, le notifiche arrivano anche lì, con i tuoi nuovi messaggi, come nomi e cosa è successo, mai cosa dice un commento o un messaggio; togli la spunta nel pannello per fermarle. Nella demo, gioca come Luca per vedere il commento di Anna e due applausi.

Accanto a ogni commento e a ogni messaggio di qualcun altro c'è Segnala, e ogni scheda nella pagina Persone ha Segnala e Blocca. Una segnalazione arriva all'amministratore del sito con il tuo motivo e, per un commento o un messaggio, solo quel testo; Bloccalo anche è spuntato. Bloccare qualcuno vuol dire che nessuno dei due scrive all'altro, lo trova, o vede, applaude o commenta ciò che l'altro condivide, e in una conversazione di gruppo nessuno legge l'altro. Non chiude nessun allenamento né gruppo: togli un allenatore in Condivisione, o lascia il gruppo. Persone che hai bloccato, nella pagina Persone, ha Sblocca. L'amministratore vede le segnalazioni aperte nel pannello di amministrazione e può togliere il commento o il messaggio, o chiudere la segnalazione.

Cibo e calorie

La scheda Cibo e calorie mostra, per un giorno, cosa hai mangiato (Mangiate), cosa hanno bruciato gli allenamenti di quel giorno (Bruciate negli allenamenti) e la Differenza, con proteine, carboidrati e grassi quando li hai inseriti. Questa settimana qui sotto elenca ogni giorno della settimana che stai guardando; tocca un giorno, o sceglilo con Giorno, per vederlo.

• Registrare un cibo: scegli il pasto se vuoi, scrivi il cibo, la quantità e le kcal (proteine, carboidrati e grassi sono facoltativi) e premi Aggiungi cibo. Modifica riempie il modulo con una voce per correggerla (Salva le modifiche), Togli la toglie di nuovo.
• Cercare un codice a barre: scrivi le cifre sotto il codice a barre in Cifre del codice a barre e premi Cerca (o Invio). In Chrome su Android, Scansiona un codice a barre le legge da una foto; su iPhone, scrivile. Calorie, proteine, carboidrati e grassi del prodotto arrivano da Open Food Facts, un database alimentare libero e gratuito, per porzione (o per 100 g). Controllali con la confezione, poi premi Aggiungi cibo; la voce è segnata "da Open Food Facts". A Open Food Facts viene mandato solo il codice a barre.
• Scansionare un'etichetta: per un prodotto che il codice a barre non trova, Scansiona un'etichetta ti fa scattare una foto sul telefono. Fai una foto nitida della tabella nutrizionale: un modello più piccolo ed economico del tuo fornitore (Claude Haiku con una chiave Anthropic, gpt-5-mini con una chiave OpenAI) la legge e compila il modulo. Controlla i numeri con l'etichetta (se dà i valori per 100 g, cambiali per quello che hai mangiato), poi premi Aggiungi cibo. Niente viene salvato finché non lo fai, e la foto non viene conservata. Usa la tua chiave API, o quella dell'admin o il modello aperto come la chat; se quel modello non legge le foto, la scheda lo dice e compili il modulo a mano.
• Bruciate è il numero che il tuo orologio, o Strava, Polar o Intervals.icu, ha mandato per ogni allenamento. Se manca, è stimato da sport, tempo o distanza e dal tuo peso, e segnato con un *: imposta Il tuo peso (kg) sotto la settimana per avere stime tue (70 kg finché non lo fai).
• Le calorie bruciate contano solo gli allenamenti registrati, non quello che il corpo consuma a riposo, quindi la differenza non è un bilancio energetico completo. Non è un consiglio medico o dietetico.
• Chi vede i tuoi dati (il tuo allenatore, i membri del gruppo con cui condividi) vede anche il tuo registro del cibo; solo tu lo cambi. È in Download my data e viene cancellato con il tuo account. Nella copia online della demo, Anna e Luca hanno due settimane di pasti di esempio; quello che aggiungi resta nel tuo browser, e lì codici a barre ed etichette non si possono cercare.

4. Un giro sul gruppo di esempio

I dati di esempio sono inventati e ogni atleta ha una storia che il motore dovrebbe cogliere.

Anna: preparazione alla maratona, carico che sale troppo in fretta. Al 4 ottobre il carico è salito del 37% dopo tre settimane di aumenti. La frequenza a riposo e l'HRV sono fuori dal suo range da 5 giorni, dorme poco e martedì ha scritto "slept badly, rough week at work" (ho dormito male, settimana pesante al lavoro). Stato: Attention.

Giulia: dolore, poi silenzio. Ha scritto "mi fa male il ginocchio dal km 8" e non si allena da 6 giorni, a due settimane dalla gara. Stato: Attention.

Luca: va tutto bene. Corre a un passo migliore, a parità di frequenza cardiaca, rispetto alle settimane precedenti, e ha scritto "legs felt great" (gambe ottime). Stato: Stable, con un segnale positivo.

Tornare indietro nel tempo

Premi ← quattro volte (oppure scegli il 6 settembre 2026 dal pulsante della settimana, o apri http://localhost:8000/#anna/2026-09-06). Sono tutti Stable: la crescita di Anna non è ancora iniziata. Poi premi → una settimana alla volta e guarda i segnali comparire man mano che il suo carico sale. È il modo migliore per mostrare come funziona il sistema.

5. Usare i propri dati

Crea una cartella per ogni atleta dentro una cartella del gruppo, per esempio mio-gruppo/marco/. Solo profile.json è obbligatorio.

Un profile.json minimo:

{
  "name": "Marco",
  "sport": "running",
  "hr_rest": 48,
  "hr_max": 186,
  "events": [{"name": "Maratona di Roma", "date": "2027-03-21", "priority": "A"}]
}

Poi esegui coachint app mio-gruppo/.

Il pulsante Import

Puoi fare tutto anche dall'app: premi Import, scegli un atleta (l'admin può anche scegliere New athlete…, nuovo atleta), poi Choose files oppure trascina i file nel riquadro tratteggiato. L'app accetta:

• file FIT, TCX e GPX da un orologio o da un'app, anche compressi (.gz);
• un intero export .zip da Garmin Connect, Strava o Polar Flow (sezione 6);
• workouts.csv, wellness.csv o notes.csv con le colonne della tabella sopra.

Le righe e le sessioni già presenti non vengono aggiunte due volte. Un file che il motore non sa leggere viene rifiutato e non viene salvato nulla. Ogni file deve stare sotto i 20 MB: per un export più grande, l'admin usa coachint import (sezione 6).

Import e note vengono salvati nella cartella che hai aperto. Per lasciare intatti i dati di esempio, creane prima una copia con coachint sample mia-demo/ e apri quella.

Un nuovo atleta senza file mostra No data, e uno con meno di circa 5 settimane di storico mostra Learning: prima di allora la baseline non è affidabile e i segnali sul carico restano in silenzio. Se la stessa sessione arriva da più fonti (per esempio un file FIT, l'export Garmin e Intervals.icu), viene contata una volta sola.

6. Portare i dati dal tuo orologio (Garmin, Polar, Strava)

COACHINT non entra mai nel tuo account Garmin, Strava o Polar. Ogni atleta porta i propri dati, in uno di questi modi:

Perché non le API di Strava o di Garmin? I termini di Strava non permettono l'uso con l'AI né di mostrare i dati a un coach, e le API di Garmin sono aperte solo ad aziende approvate. Un export è la tua copia dei tuoi dati, quindi puoi condividerla.

Se sei un atleta

Export di Garmin Connect:

1. Accedi a garmin.com, apri il tuo account, poi Gestione dati → Esporta i tuoi dati (Data Management → Export Your Data) e premi Richiedi esportazione dati.
2. Garmin ti manda per email un link per scaricarlo (può volerci qualche ora, a volte qualche giorno). Scarica il .zip.
3. Mandalo a [NOME ORGANIZZATORE] in privato (una cartella condivisa o un link al file, non una chat di gruppo) oppure, se sta sotto i 20 MB, aggiungilo tu con Import nella tua pagina.

Archivio Strava:

1. Su strava.com apri Impostazioni → Il mio account → Scarica o elimina il tuo account (Settings → My Account → Download or Delete Your Account), poi Richiedi il tuo archivio.
2. Strava ti manda per email un .zip. Mandalo come per Garmin, o importalo nella tua pagina se sta sotto i 20 MB.

Dall'archivio Strava COACHINT tiene il file originale di ogni attività, più la descrizione, la nota privata e lo sforzo percepito, che diventano i tuoi commenti e l'RPE.

Polar:

1. [NOME ORGANIZZATORE] ti manda un link di consenso. Aprilo, accedi a Polar Flow e accetta.
2. Il browser arriva poi su una pagina che può mostrare un errore o niente: è normale. Copia l'indirizzo intero dalla barra degli indirizzi e mandalo a [NOME ORGANIZZATORE].
3. Se Polar ti chiede di accettare la condivisione dei dati, fallo in Polar Flow, in Impostazioni.

Da quel momento i tuoi allenamenti (con i file FIT), il sonno e il Nightly Recharge (HRV e frequenza cardiaca notturni) arrivano ogni giorno. Per smettere, dillo a [NOME ORGANIZZATORE], che rimuove il collegamento e cancella la chiave. I dati di questa strada sono attribuiti a Polar e condivisi solo con il tuo permesso.

Al posto del collegamento puoi mandare il tuo export di Polar Flow (da account.polar.com, Download your data), come per Garmin.

Singoli file: quasi tutte le app esportano un'attività come FIT, TCX o GPX. Aggiungili con Import nella tua pagina.

Se gestisci la prova

Importa un export o singoli file per un atleta (una cartella come friends/marco, oppure coachint.db/marco nel database della prova, sezione 9):

coachint import friends/marco export_12345.zip      # archivio Strava, export Garmin o Polar (riconosciuto da solo)
coachint import friends/marco run.fit ride.tcx.gz   # singoli file di attività

• Di un export si tengono gli ultimi 365 giorni (--days 0 tiene tutto). Importare di nuovo lo stesso export non aggiunge nulla.
• Dall'export Garmin COACHINT tiene i riepiloghi delle attività, i file FIT originali, il sonno, la frequenza a riposo e l'HRV.
• Un import può scrivere al massimo 200 MB, e non si importa nulla se sul disco restano meno di 200 MB liberi (l'hosting gratuito ha circa 1 GB in tutto).

Polar, una volta sola: registra un client gratuito su https://admin.polaraccesslink.com con un qualsiasi account Polar Flow, annota il suo indirizzo di redirect e imposta COACHINT_POLAR_CLIENT_ID, COACHINT_POLAR_CLIENT_SECRET e, se ne hai registrato uno, COACHINT_POLAR_REDIRECT_URI (in ~/coachint.env sul server). Poi, per ogni atleta:

coachint polar connect friends/marco                    # stampa il link di consenso da mandare a Marco
coachint polar connect friends/marco --code '<indirizzo>' # l'indirizzo su cui è arrivato il browser di Marco
coachint polar sync friends/                            # tutti gli atleti collegati; pianificalo ogni giorno, come intervals sync
coachint polar disconnect friends/marco                 # quando Marco lascia: revoca l'accesso, cancella il token

Il token viene salvato, leggibile solo da te, insieme ai dati dell'atleta (polar.json nella sua cartella, oppure nel database) e non finisce mai su Git. La licenza di Polar chiede di citare Polar come fonte, di condividere i dati di un atleta solo con il suo permesso e di cancellare il token quando lascia.

Gli export di Garmin, Strava e Polar finora sono stati provati solo su file sintetici: il primo export vero di un amico è la vera prova. Se uno viene rifiutato, tieni il file e avvisa [NOME ORGANIZZATORE].

7. Collegare Intervals.icu (niente più file a mano)

Se usi Intervals.icu, COACHINT può scaricare direttamente attività e dati di benessere, con la tua chiave. L'orologio continua a sincronizzarsi con Intervals.icu come sempre e COACHINT prende i dati nuovi ogni 10 minuti. Per chi usa Garmin è il modo per avere aggiornamenti quotidiani.

Se sei un atleta

1. In Intervals.icu apri Settings → Developer Settings.
2. Annota il tuo athlete ID (ha la forma i12345) e crea una API key.
3. In COACHINT apri il Menu, premi Importa e compila ID atleta e Chiave API sotto Intervals.icu. Premi Collega.
4. COACHINT verifica la chiave con Intervals.icu e importa subito gli ultimi 180 giorni (può volerci un minuto). Poi la finestra dice Collegato come i12345 e quando è stata fatta l'ultima sincronizzazione.

Come configurarlo sotto Intervals.icu nella finestra Importa ti guida in questi passi uno alla volta, indicando ogni casella.

Da quel momento i dati nuovi arrivano da soli, ogni 10 minuti; Sincronizza ora li prende subito. Scollega dimentica la chiave; spunta prima Togli anche quello che ha portato per cancellare anche le attività e il benessere importati. La chiave resta con i tuoi dati, leggibile solo dal server, e la pagina non la mostra più. Trattala come una password; cancellarla in Intervals.icu scollega anche COACHINT.

Se gestisci la prova

Gli atleti si collegano da soli nell'app (sopra); sul server non serve configurare niente, e l'app sincronizza ogni 10 minuti tutti quelli collegati finché è accesa (COACHINT_SYNC_MINUTES lo cambia, 0 lo spegne). Per collegare qualcuno dalla riga di comando, invece, per ogni atleta (una cartella con un profile.json, come nella sezione 5, oppure coachint.db/marco nel database):

coachint intervals connect friends/marco    # chiede ID e chiave, li verifica online e li salva
coachint intervals sync friends/            # scarica i dati nuovi di tutti gli atleti collegati

• La chiave viene salvata insieme ai dati dell'atleta (intervals.json nella sua cartella, oppure nel database), leggibile solo da te e mai inserita in Git.
• La prima sincronizzazione scarica gli ultimi 180 giorni, abbastanza storico per la baseline. Le successive scaricano solo i giorni dall'ultima volta, più una settimana per cogliere le modifiche tardive a commenti, RPE e benessere.
• Le attività diventano allenamenti (tempo, distanza, frequenza cardiaca, RPE e la descrizione come tuo commento). Il benessere dà frequenza a riposo, HRV e sonno, e i suoi commenti diventano note. Una sessione che arriva anche da un file o da un export viene contata una volta sola.
• Le attività arrivate su Intervals.icu da Strava vengono saltate e mai salvate, perché i termini di Strava non permettono questo uso. Collega l'orologio direttamente a Intervals.icu (Garmin, COROS, Suunto, Polar, Wahoo…) così i dati arrivano dal dispositivo.

I dati sincronizzati dalla riga di comando si vedono la volta successiva che la pagina viene caricata; quelli sincronizzati dall'app si vedono subito.

8. Ricevere il digest ogni giorno (Telegram o email)

Ogni mattina, ogni atleta della prova riceve il proprio digest su Telegram o per email. Sotto ogni avviso ci sono due pulsanti: Useful (utile) e Dismiss (ignora). Ogni tocco viene salvato, così impariamo quali avvisi aiutano davvero e possiamo regolare gli altri.

Se sei un atleta

Telegram (consigliato):

1. Apri il bot della prova ([NOME ORGANIZZATORE] ti manda il link) e premi Avvia (Start).
2. Il bot risponde con il tuo chat id. Manda quel numero a [NOME ORGANIZZATORE].
3. Dalla mattina dopo, il digest arriva in quella chat. Tocca Useful o Dismiss sotto ogni avviso. Il pulsante scelto riceve una ✓, e puoi cambiare idea toccando l'altro.

Email: dai il tuo indirizzo email. Ogni avviso ha i link Useful e Dismiss: il link apre una piccola pagina e la scelta viene salvata quando premi Confirm.

Nell'app: ogni digest resta anche sulla tua pagina, sotto l'anteprima del digest, in Past digests (nascosto all'inizio: spuntalo in Account, Tiles on the page): dal più recente, ciascuno con Useful e Dismiss sotto i suoi avvisi (le stesse risposte di Telegram o dell'email) e Open this week per vedere segnali e grafici di quella settimana, e Delete this digest (elimina questo digest) per toglierne uno dall'elenco (se ne vanno il testo e le tue risposte; il messaggio Telegram o email resta). Un allenatore o un membro del gruppo che vede i tuoi dati legge anche i tuoi digest passati, ma solo tu li valuti. Restano per circa sei mesi (l'organizzatore può cambiarlo), sono in Download my data e se ne vanno quando elimini il tuo account. Se non vuoi né Telegram né email, dillo: puoi ricevere il digest solo nell'app.

Se gestisci la prova

1. Crea il bot. In Telegram scrivi a @BotFather, manda /newbot e copia il token che ti dà.

2. Elenca chi riceve cosa in un subscribers.json accanto al database o alla cartella del gruppo (parti da subscribers.example.json nel repository):

{"subscribers": [
  {"athlete": "coachint.db/marco", "telegram": "123456789"},
  {"athlete": "coachint.db/sara", "email": "sara@example.com"}
]}

Con le cartelle, scrivi "athlete": "friends/marco". Una voce senza telegram né email, come {"athlete": "coachint.db/luca"}, riceve il digest solo nell'app: ogni digest resta comunque sulla pagina dell'atleta in Past digests. Quanto a lungo si tengono i digest (quelli inviati e le copie nell'app) si sceglie con COACHINT_DIGEST_DAYS; 183 giorni se non lo imposti.

3. Controlla i messaggi senza mandare nulla:

coachint send subscribers.json --dry-run

4. Avvia il bot. Risponde a /start, salva i tocchi sui pulsanti e manda i digest ogni giorno all'ora scelta:

export COACHINT_TELEGRAM_TOKEN="123456:ABC..."
coachint bot subscribers.json --send-at 07:30

Tienilo acceso su un computer che resta acceso; sul server (sezione 9) gira come servizio. I tocchi arrivano a COACHINT solo mentre il bot è acceso, e Telegram tiene i tocchi non letti per 24 ore. Pianifica coachint intervals sync friends/ e coachint polar sync friends/ poco prima dell'ora di invio, così il digest include i dati della notte.

Applausi, commenti, richieste di collegamento e nuovi messaggi che una persona non ha visto nell'app escono sugli stessi canali con coachint notify (nomi e cosa è successo, mai il testo); lancialo da cron ogni pochi minuti:

coachint notify subscribers.json --dry-run

5. Guarda cosa aiuta:

coachint feedback

Mostra, per ogni tipo di avviso, quante volte è stato mandato, giudicato utile, ignorato o lasciato senza risposta.

L'email richiede anche un account di posta in uscita (COACHINT_SMTP_HOST, COACHINT_SMTP_USER, COACHINT_SMTP_PASSWORD, …). I link Useful e Dismiss richiedono una pagina di feedback raggiungibile dagli atleti: sul server, imposta COACHINT_FEEDBACK_SECRET e il sito la serve; sul tuo computer, esegui coachint feedback-server. Tutte le impostazioni sono nel README. Senza la pagina di feedback, le email partono senza i link.

L'elenco degli iscritti e le risposte (salvate nel database, oppure in coachint-delivery.sqlite con le cartelle) contengono dati personali. Tienili sulla macchina della prova; non finiscono mai su Git. Ogni digest parte al massimo una volta al giorno; se l'invio fallisce, viene ritentato alla volta successiva.

9. Mettere l'app online per gli amici (admin)

Questa sezione è per chi gestisce la prova. La guida completa passo per passo è deploy/README.md nel repository; qui c'è la versione breve.

Dove gira

L'hosting consigliato è il piano gratuito di alwaysdata: niente carta di credito, server a Parigi (i dati restano nell'UE), 1 GB di disco e accesso SSH. La stessa macchina fa girare l'app web, le sincronizzazioni quotidiane e il bot Telegram. La guida spiega perché gli altri hosting gratuiti non vanno bene, e un'alternativa su un computer di casa.

In breve: registrati, clona il repository via SSH con una deploy key in sola lettura, installalo con uv (uv sync --extra encrypt, senza permessi di root), scrivi ~/coachint.env con python3 ~/coachint/deploy/setup_env.py (fa qualche domanda, genera le password e le chiavi che lasci vuote e scrive il file leggibile solo da te; salva nel tuo password manager la password di admin e la chiave del database che mostra), poi aggiungi un sito di tipo User program che esegue deploy/serve.py sul database, con Force HTTPS attivo.

Su un tuo server, con Docker o Podman. Su un piccolo server in affitto, un computer di casa o un NAS, il Dockerfile e il compose.yaml del repository fanno lo stesso in un container, con i dati su un volume che resta tra un aggiornamento e l'altro. Scrivi le impostazioni con python3 deploy/setup_env.py ./coachint.env, crea il database con docker compose run --rm app coachint db migrate /app/samples /data/coachint.db, poi avvialo con docker compose up -d. Per raggiungerlo da internet: su un server nel cloud, docker compose --profile https up -d aggiunge un certificato HTTPS gratuito per il tuo dominio; su un computer di casa (un Raspberry Pi, un NAS), docker compose --profile tunnel up -d lo pubblica con un Cloudflare Tunnel gratuito, senza aprire nulla sul router (Cloudflare però vede il traffico, e il sito è giù quando la macchina è spenta). La guida confronta le due strade. Ogni comando coachint di questa sezione diventa allora docker compose exec app coachint ..., con /data/coachint.db al posto di ~/coachint.db. Passo per passo in deploy/README.md (in inglese), sezione Containers. Per un piccolo server nel cloud da Hetzner (circa 7 euro al mese più IVA, in Germania o Finlandia), deploy/HETZNER.md (in inglese) accompagna in tutto, dalla creazione del server a HTTPS, backup e aggiornamenti.

Un database per la prova

Sul server tutti i dati della prova stanno in un solo file, ~/coachint.db: profilo, allenamenti, benessere e note di ogni atleta, il suo login, la sua chiave API, i collegamenti a Intervals.icu e Polar e le risposte ai digest. È cifrato con la COACHINT_DB_KEY che setup_env.py ha messo in ~/coachint.env; conservane una copia nel tuo password manager, perché senza la chiave nessuno può leggere i dati, neanche tu. Il sito non parte su un database non cifrato. Crealo dai campioni (o dalle cartelle che hai già), poi aggiungi ogni amico:

~/coachint/deploy/run.sh coachint db migrate ~/coachint/samples ~/coachint.db   # o la tua cartella, come ~/data
~/coachint/deploy/run.sh coachint add-athlete ~/coachint.db "Marco Rossi" --hr-rest 48 --hr-max 186
~/coachint/deploy/run.sh coachint db info ~/coachint.db                          # chi c'è e quanti dati ha

add-athlete stampa l'id dell'atleta (marco-rossi): è il suo nome utente e il nome dopo coachint.db/ in ogni comando, come coachint import ~/coachint.db/marco-rossi export.zip. Ogni comando di questa guida che accetta una cartella accetta allo stesso modo il database. db migrate legge soltanto le cartelle; tienile finché il sito non funziona dal database. Il file viene creato leggibile solo da te; tienine una copia altrove con coachint db backup ~/coachint.db ~/coachint-backup.db (cifrata con la stessa chiave; vedi deploy/README.md). Un database creato prima della cifratura si converte con coachint db encrypt.

Password: una per te, una per ogni persona

• La tua password di admin è COACHINT_ADMIN_PASSWORD in ~/coachint.env. Con qualsiasi nome utente mostra tutti gli atleti e permette di aggiungerne di nuovi. Usa almeno 12 caratteri: il sito rifiuta password più corte e il segnaposto del modello, e non parte su un indirizzo pubblico senza.
• Ogni amico e ogni allenatore ha il proprio login: apri Admin e clicca Make password accanto al nome. Il pannello mostra il nome utente (l'id dell'atleta, marco-rossi, o dell'allenatore) e una nuova password casuale, una volta sola. Via SSH, per gli atleti, funziona anche:

~/coachint/deploy/run.sh coachint password ~/coachint.db/marco-rossi

Stampa il nome utente (l'id dell'atleta, marco-rossi) e una nuova password casuale. Mandali a Marco in privato, con l'indirizzo del sito (https://ACCOUNT.alwaysdata.net). Esegui di nuovo lo stesso comando per dare una password nuova: quella vecchia smette di funzionare. Aggiungi --ask per scrivere tu la password invece di generarla. Un amico senza password non può entrare.

La password è salvata come hash con salt nel database (o nella cartella dell'amico come login.json), leggibile solo da te. Alle password sbagliate il sito risponde circa una volta al secondo, quindi indovinarle è lento.

Il pannello admin: allenatori, gruppi e la tua chiave LLM

Admin nel Menu apre una pagina con tutto ciò che riguarda le persone, in schede (People, Groups, Reports, AI usage, Change log; un numero su una scheda conta ciò che ti aspetta):

• People: ogni atleta e allenatore, i ruoli, se ha una password (New password, Block sign-in), quante domande al mese può fare sulla tua chiave LLM e di chi vede i dati.
• Add trainer: scrivi un nome; l'allenatore riceve subito una password. Gli atleti si aggiungono con Import.
• Roles: spunta Athlete, Trainer o entrambi. Un atleta che allena anche riceve la spunta Trainer e tiene i propri dati; un allenatore che inizia ad allenarsi riceve la spunta Athlete e una propria cartella di dati vuota (può farlo anche da solo, da My training), tenendo password, chiavi e chat da coach. Chi ha i propri dati resta atleta (Delete athlete and data toglie entrambi), e ognuno tiene almeno un ruolo.
• Groups: aggiungi i membri e gli allenatori che seguono il gruppo. Spunta Members can see each other per un gruppo che condivide (per esempio amici che si allenano insieme). Accanto a ogni membro c'è scritto se ha accettato (shares) o no (hasn't agreed): lo decide lui nella sua pagina Sharing, tu non puoi decidere al suo posto.
• Your LLM key: un numero di domande al mese permette alla chat di quella persona di usare il tuo modello COACHINT_LLM sulla tua chiave. Oltre il limite la chat torna al modello aperto fino al mese dopo. Vuoto vuol dire spento.
• Delete athlete and data: il link sotto il nome di una persona, per un amico che se ne va. Scrivi il suo id per confermare, poi cancella i suoi allenamenti, le note, la password, la chiave API salvata e le connessioni Polar e Intervals.icu (prima viene revocato l'accesso Polar), i digest che gli sono stati inviati e il suo posto in ogni gruppo. Non si può annullare. Se riceve il digest quotidiano, toglilo anche da ~/subscribers.json; le copie del database fatte prima contengono ancora i suoi dati finché non le cancelli.
• Change log: ogni modifica fatta qui, nella lingua della pagina, dalla più recente, con l'ora: persone aggiunte o cancellate, ruoli, password create o bloccate, gruppi, permessi sulla chiave. Registra solo nomi e id, mai password, chiavi o dati di salute.

La pagina Sharing di ogni amico mostra i suoi gruppi, chi può vedere i suoi dati gli interruttori per condividerli con gli allenatori e con i membri di un gruppo, Download my data (uno zip di file CSV con tutto ciò che conserviamo su di te) e Withdraw consent and delete my account, che cancella account e dati dopo che hai scritto il tuo id. Elenca gli altri membri di un gruppo solo se li puoi vedere comunque (avete accettato entrambi, o sei l'allenatore del gruppo), così un gruppo non serve a scoprire chi altro ne fa parte.

My coaches (i miei allenatori). Un atleta può avere più di un allenatore. In cima a Sharing, My coaches li elenca: gli allenatori che hai scelto tu e gli allenatori dei tuoi gruppi con cui hai accettato di condividere (through, tramite, il nome del gruppo). Scegli un allenatore in Select coach (gli allenatori in un gruppo con te e quelli che si sono resi visibili) e premi Ask to coach me: quando accetta, nella sua pagina People, è il tuo consenso perché veda i tuoi dati, senza cambiarli, e ti trova in My athletes, con la chat da coach. La ✕ accanto a un allenatore che hai scelto lo toglie, e smette subito di vedere i tuoi dati; la ✕ accanto a una richiesta ancora in attesa la ritira. Solo tu puoi aggiungere o togliere i tuoi allenatori; l'admin li vede nel pannello Admin (Coaches they picked) ma non può cambiarli.

People: trovare atleti e allenatori e collegarsi. People nel Menu è dove atleti e allenatori si trovano. Lì il tuo profilo (sport, luogo, una riga su di te) è privato finché non spunti Discoverable e premi Save profile; allora gli altri possono trovarti, vedendo solo quella scheda, mai i tuoi allenamenti. Scrivi un nome, uno sport o un luogo e premi Search: trovi solo le persone visibili. Accanto a ciascuna, Ask to coach me chiede a un allenatore di allenarti, Offer to coach (per gli allenatori) si offre di allenare un atleta e Invite to group invita un atleta in un gruppo che gestisci. Non succede nulla finché l'altra persona non preme Accept in Waiting for you: accettare un allenatore è il tuo consenso perché veda i tuoi dati, e accettare un invito in un gruppo condivide con i suoi allenatori (e con i membri, se la condivisione è attiva), cosa che puoi fermare in Sharing. Decline e Withdraw lasciano cadere una richiesta. Suggestions elenca fino a cinque persone visibili con cui hai in comune un gruppo, uno sport o un luogo. Chi è in un gruppo con te può mandarti una richiesta anche se non sei visibile. Make group crea un gruppo tuo: un allenatore lo segue come allenatore, quello di un atleta ha la condivisione attiva, per invitare compagni di allenamento; Leave ti fa uscire da un gruppo, e chi l'ha creato può premere Delete group. Nella demo online, gioca Anna per accettare l'offerta dell'allenatrice Elena.

Messages: scrivere ad allenatori, atleti e gruppi. Messages nella barra in alto (sul telefono, nella barra in basso) elenca le tue conversazioni, dalla più recente; il numero sopra dice quanti messaggi non hai letto. Ognuno dei tuoi gruppi ha una conversazione per i suoi membri e allenatori. Per scrivere a una persona, sceglila sotto l'elenco e premi New message: puoi scrivere alle persone con cui sei collegato (i tuoi allenatori, gli atleti che alleni, i membri con cui condividi) e a chiunque sia in un gruppo con te. Scrivi e premi Send (o Ctrl+Invio). Solo chi è nella conversazione la legge; uscire da un gruppo nasconde la sua conversazione. Nella demo online, gioca Giulia per leggere il Run club e la sua allenatrice Anna.

Chi può fare cosa

Registrazione con Google o Auth0 e condizioni d'uso

Invece di creare una password per ogni amico, puoi farli registrare da soli: nella pagina di accesso con nome utente e password (attivo di default, niente da configurare), con il loro account Google, con Auth0 (piano gratuito, regione UE) o con un altro provider OpenID Connect.

• Google (deploy/GOOGLE.md, in inglese, circa 10 minuti, gratis): in Google Cloud descrivi l'app nella schermata di consenso, crea un client OAuth di tipo Web application con il redirect URI https://ACCOUNT.alwaysdata.net/auth/callback e copia client id e secret in ~/coachint.env (deploy/setup_env.py te li chiede). Finché l'app è in Testing, possono accedere solo gli account Google che elenchi come utenti di test (fino a 100): aggiungi lì gli indirizzi dei tuoi amici.
• Auth0 (deploy/AUTH0.md, in inglese), per gli amici che preferiscono email e password: crea un'applicazione Auth0 con la stessa callback e copia dominio, client id e secret in ~/coachint.env. I due pulsanti possono stare insieme sulla pagina.

Entrambi richiedono un session secret casuale in ~/coachint.env. Le password continuano a funzionare.

• Con un server SMTP e COACHINT_PUBLIC_URL in ~/coachint.env, la registrazione chiede un'email facoltativa (confermata da un link) e la pagina di accesso offre Password dimenticata?. A chi non ha un'email confermata dai una nuova password con New password in Admin (o coachint password).
• Chi si registra diventa un atleta in nessun gruppo, con una pagina vuota. In Admin la sua riga dice Signs in with Google (o Auth0); puoi renderlo allenatore, aggiungerlo ai gruppi, bloccarlo con Block sign-in o cancellarlo come chiunque altro. Make password dopo un blocco lo fa rientrare.
• Approvare i nuovi account. Di default (COACHINT_SIGNUP=approve) chi si registra aspetta: vede In attesa di approvazione finché non premi Approva sulla sua riga in Admin (il pannello dice quando qualcuno aspetta). Elimina atleta e dati lo rifiuta. Se ha confermato un'email, COACHINT gli scrive che è dentro. COACHINT_SIGNUP=on salta l'approvazione.
• Al massimo COACHINT_SIGNUP_LIMIT persone (20 di default) possono registrarsi da sole; COACHINT_SIGNUP=off chiude le registrazioni e lascia dentro chi c'è già.
• Condizioni d'uso: tutti tranne te le accettano prima di vedere i dati, e di nuovo quando cambia la versione; il pannello admin mostra quale versione ha accettato ciascuno. Ogni accettazione scrive anche una riga nel registro delle modifiche, che resta dopo la cancellazione di una persona come prova del suo consenso. Il testo nel codice è una bozza rivista sui punti principali di GDPR e Codice del consumo ma non da un avvocato: completa le parti tra [parentesi quadre] (chi gestisce la prova, l'hosting, per quanto si conservano i dati) e falla controllare. Per usare un testo tuo, metti terms_en.md e terms_it.md in una cartella e imposta COACHINT_TERMS_DIR; cambia la riga della versione in cima per chiederle di nuovo a tutti.
• Si conservano solo l'id Auth0 e un nome visualizzato, mai l'indirizzo email. Sign out chiude la sessione sul sito, non su Auth0. Un amico che ha già una password e poi usa Auth0 ottiene un secondo account vuoto: dai a ciascuno un solo modo di entrare.

Condividere l'app per telefono con la prova

L'app per telefono è il sito ospitato stesso: gli amici la installano dal browser (sezione 2, A), quindi non c'è niente da compilare, nessuno store, nessun account sviluppatore e nessun costo, e quando aggiorni il sito ogni telefono riceve la nuova versione alla successiva apertura dell'app. Serve solo il sito su https (Force HTTPS di alwaysdata, Caddy o il tunnel). Per invitare qualcuno mandagli in privato l'indirizzo del sito, il nome utente e la password (o digli di registrarsi con Google) e la sezione 2 di questo tutorial. Dettagli in deploy/README.md, Phone app.

Alcuni amici su Android preferiscono un file dell'app. Puoi crearlo dal sito con Bubblewrap, lo strumento gratuito di Google, e mandare l'APK in privato, oppure offrirlo con il test interno di Google Play (quota una tantum per l'account sviluppatore Play); deploy/README.md, Android app file, ha i comandi e le due impostazioni che tolgono la barra dell'indirizzo. Su iPhone, per la prova, la strada è l'app nella schermata Home: una versione per App Store o TestFlight richiede un account sviluppatore Apple a pagamento e un accesso tutto suo.

Prima di metterci i dati veri degli amici

La revisione di sicurezza è in deploy/SECURITY.md. Cosa lascia aperto, e cosa fare:

• Chiedi il consenso a ogni amico per tenere i suoi dati di salute sul server e, se attivi un LLM, per mandare le sue note e i suoi numeri al fornitore dell'LLM (sezione 10). Il modello aperto o ospitato nell'UE evita il secondo punto.
• Una nota può provare a influenzare l'LLM. I numeri del digest vengono comunque controllati sui dati, ma le etichette possono essere falsate.
• I dati sul server sono cifrati con COACHINT_DB_KEY (conserva la chiave nel tuo password manager: senza, i dati sono persi), ma chi entra nell'account può leggere la chiave: proteggi l'account alwaysdata con l'autenticazione a due fattori e tieni la password di admin per te.
• Lascia attivo Force HTTPS, perché la password viaggia con ogni richiesta.
• I link di feedback nelle email valgono 30 giorni: in quel tempo chiunque riceva un digest inoltrato può valutarne gli avvisi (nient'altro).
• I backup del piano gratuito durano pochi giorni: tieni una tua copia di ~/data e del file di feedback. Quando un amico se ne va e lo cancelli in Admin, cancella anche le copie fatte prima.
• ~/coachint.db, ~/coachint.env e ~/subscribers.json contengono segreti o dati personali: tienili leggibili solo da te e fuori da Git (il database viene creato così).

Per aggiornare il codice: cd ~/coachint && git pull && ~/.local/bin/uv sync --locked --no-dev --extra encrypt (aggiungi --extra anthropic se l'avevi installato), poi riavvia il sito (e il bot) dal pannello di alwaysdata.

10. Usarla con un LLM (Claude o OpenAI)

Senza LLM tutto funziona offline: le note vengono lette con regole a parole chiave. Con un LLM, le note vengono lette dal modello, che capisce modi di dire che le regole non colgono. Il modello scrive anche una breve frase di apertura per il digest e risponde alle domande nella chat (sezione 3). I numeri vengono controllati sui dati: se la frase del digest cita un numero che non c'è nei dati, viene scartata automaticamente; una risposta della chat viene invece mostrata con un avviso.

Puoi usare Anthropic (Claude) oppure OpenAI (GPT), con la tua chiave API. Scegline uno; i passi sono qui sotto. Sul server, metti le stesse variabili in ~/coachint.env invece di scrivere export.

Opzione A: Anthropic Claude

Passo 1: ottenere una chiave API

1. Vai su https://console.anthropic.com e accedi (o crea un account).
2. Apri Settings → API Keys, poi Create Key. Copia la chiave, che inizia con sk-ant-.
3. Aggiungi un po' di credito in Billing. La demo ne usa pochissimo.

La chiave è come una password. Non metterla in file che condividi o che finiscono su Git.

Passo 2: installare l'SDK di Anthropic

uv sync --extra anthropic

Passo 3: impostare la chiave e avviare l'app

macOS / Linux:

export ANTHROPIC_API_KEY="sk-ant-..."
export COACHINT_LLM=anthropic
coachint app samples/ --llm

Windows (PowerShell):

$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:COACHINT_LLM = "anthropic"
coachint app samples/ --llm

Il terminale stampa Using model: claude-opus-5-5 e nel Menu compare l'interruttore LLM (claude-opus-5-5). Accendilo: la pagina si ricarica con le note lette da Claude e una frase di apertura in cima al digest.

Scegliere il modello

Il modello predefinito è Claude Opus 5.5 (claude-opus-5-5). Per provarne un altro, imposta COACHINT_MODEL prima di avviare l'app, per esempio:

export COACHINT_MODEL=claude-sonnet-5-5

Opzione B: OpenAI

Passo 1: ottenere una chiave API

1. Vai su https://platform.openai.com e accedi (o crea un account). L'abbonamento a ChatGPT non include l'accesso alle API: le API si pagano a parte.
2. Apri API keys (dal tuo profilo o dalla Dashboard), poi Create new secret key. Copia la chiave, che inizia con sk-.
3. Aggiungi un po' di credito in Settings → Billing. La demo ne usa pochissimo.

Passo 2: impostare la chiave e avviare l'app

Non serve installare altro. macOS / Linux:

export OPENAI_API_KEY="sk-..."
export COACHINT_LLM=openai
coachint app samples/ --llm

Windows (PowerShell):

$env:OPENAI_API_KEY = "sk-..."
$env:COACHINT_LLM = "openai"
coachint app samples/ --llm

Il terminale stampa Using model: gpt-5-mini e nel Menu compare l'interruttore LLM (gpt-5-mini).

Scegliere il modello

Il modello predefinito è gpt-5-mini, veloce ed economico. Per usarne un altro disponibile sul tuo account, imposta COACHINT_MODEL, per esempio:

export COACHINT_MODEL=gpt-5

Cosa viene mandato al fornitore del modello

La chat manda le domande al modello che risponde (la tua chiave, quella dell'admin o il modello aperto; vedi la sezione 3). Con l'interruttore acceso, l'app manda ad Anthropic o a OpenAI il testo di ogni nota e il testo del digest (spiegazioni dei segnali, numeri, nome della gara). Ogni domanda nella chat manda la domanda, le ultime domande e risposte e un riassunto dei dati di quell'atleta: totali settimanali, sedute delle ultime 4 settimane, FC a riposo, HRV e sonno giorno per giorno delle ultime 2 settimane, note e prossima gara. La chat usa un modello ogni volta che ce n'è uno configurato, anche con l'interruttore spento. Scansiona un'etichetta manda la foto dell'etichetta (rimpicciolita nel browser) allo stesso fornitore della chat (il suo modello più economico), e nient'altro. Cerca manda a Open Food Facts solo le cifre del codice a barre, e la ricerca di una gara manda a Wikidata solo le parole scritte. I file degli allenamenti e i dati grezzi non vengono mandati. Con l'interruttore spento, nulla esce dalla macchina. Con atleti veri, usa l'LLM solo con il loro consenso (vedi il documento MVP, §14, e la sezione 9).

Alternativa: un modello aperto

Per tenere tutto in locale, o ospitato nell'UE, puoi usare un modello aperto dietro un endpoint compatibile con OpenAI, per esempio Ollama:

ollama pull qwen2.5:0.5b
export COACHINT_LLM=open COACHINT_OPEN_BASE_URL=http://localhost:11434/v1 COACHINT_OPEN_MODEL=qwen2.5:0.5b
coachint app samples/ --llm

Chi paga le domande della chat (admin)

Sul server, metti queste variabili in ~/coachint.env:

• COACHINT_OPEN_BASE_URL e COACHINT_OPEN_MODEL (più COACHINT_OPEN_API_KEY se il servizio la chiede): il modello aperto risponde a ogni amico che non ha una chiave sua.
• COACHINT_PLAN_WEEKS (facoltativa): la durata massima di un piano di allenamento, in settimane. Vuota vale 12; può arrivare a 52.
• COACHINT_CHAT_TOKENS (facoltativa): la lunghezza massima di una risposta della chat, in token. Vuota vale 1024; alzala se le risposte si interrompono a metà frase, abbassala per spendere meno. Vale per il modello aperto e per Claude; i modelli OpenAI tengono il loro limite.
• In Admin, la colonna Your LLM key: chi ha un numero lì usa il tuo modello COACHINT_LLM, sulla tua chiave, fino a quel numero di domande al mese.
• COACHINT_AI_DAILY_ATHLETE e COACHINT_AI_DAILY_COACH (facoltative): domande all'IA al giorno per persona sulle tue chiavi (il modello aperto e il tuo modello, mai la chiave personale). Vuote valgono 10 per un atleta e 20 per un allenatore; 0 vuol dire nessun limite.
• COACHINT_AI_BUDGET (facoltativa): quanto possono spendere in un mese le chiavi del sito, in dollari USA. Admin > AI usage mostra ogni chiamata con i suoi token e il costo stimato, avvisa al 50% e all'80%, e raggiunto il budget rispondono solo le chiavi personali fino al mese dopo. COACHINT_AI_PRICES aggiunge il prezzo di un modello che l'app non conosce, come mistral-small-3.2=0.15/0.35 per milione di token in entrata e in uscita.

11. Le stesse cose dal terminale

coachint digest samples/anna --as-of 2026-10-04    # il digest di un atleta
coachint group samples/ --as-of 2026-10-04         # la classifica del gruppo
coachint chat samples/anna --as-of 2026-10-04      # domande sui dati di un atleta (riga vuota per uscire)
coachint import friends/marco export.zip           # export Garmin, Strava o Polar, o file .fit/.tcx/.gpx
coachint intervals sync friends/                   # scarica i dati nuovi da Intervals.icu
coachint polar sync friends/                       # scarica i dati nuovi da Polar
coachint password friends/marco                    # il login di Marco all'app online
coachint add-athlete friends/ "Marco Rossi"        # un nuovo atleta
coachint db migrate friends/ coachint.db           # sposta le cartelle degli atleti in un database
coachint db encrypt coachint.db secure.db          # copia cifrata con COACHINT_DB_KEY (db decrypt: al contrario)
coachint db backup coachint.db backup.db           # copia di un database in uso, stessa chiave
coachint db info coachint.db                       # chi c'è in un database
coachint send subscribers.json --dry-run           # i digest del giorno, senza mandarli
coachint feedback                                  # quali avvisi sono stati utili

Anche digest, group, chat, send e bot accettano --llm. Un database funziona ovunque funzioni una cartella: coachint group coachint.db, coachint digest coachint.db/anna.

12. Risoluzione dei problemi

COACHINT è un PoC. I segnali sono inviti a guardare meglio, non diagnosi. Se dolore o malattia persistono, rivolgiti a un medico o a un fisioterapista.