Reorganize documentation and unify the AI assistant rules

Documentation:
- Add docs/README.md, the documentation index that AGENTS.md pointed to as the
  first file to read but which did not exist.
- One home per piece of information: the feature list stays in ROADMAP.md,
  CHANGELOG.md records only when something shipped, TODO.md only ongoing work.
  Reconcile the entries that had drifted (CSI was both done and pending;
  pagelle, badge social and serie were missing from the roadmap).
- Rewrite DATABASE.md as tables: add giocatori_squadra (already created by a
  migration) and profili_giocatore (planned in DD-016), fix the wrong heading
  levels, drop the duplicated roadmap.
- DESIGN_DECISIONS.md: move the index to the top and sort it, extract the
  template into _template-dd.md.
- ARCHITECTURE.md becomes the technical reference; CLAUDE.md no longer
  duplicates it.
- Add docs/EFFICIENZA_CLOUD.md with the rules previously kept in mem/,
  separating what the code enforces from the goals not yet implemented.
- Fix statements the code contradicted: mutations use setQueryData rather than
  invalidateQueries, and scout_sessioni and giocatori_squadra are not read by
  the code yet.
- Track the v1.0 modules with no spec in docs/modules/ from TODO.md.

AI assistants:
- AGENTS.md is the single source of the rules, now including the technical
  constraints only Claude Code knew about (generated files, Vite plugins, data
  access) and an end-of-work checklist that applies to every assistant.
- CLAUDE.md and .cursor/rules/crapp.mdc point to AGENTS.md instead of
  restating it.
- Remove the five .cursor/*.md files, which Cursor never loaded.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.cursor/architecture-summary.md

@@ -1,37 +0,0 @@
-# Architecture Summary
-
-Frontend
-
-- React
-- TanStack Start
-- Tailwind
-- TypeScript
-
-Backend
-
-- Supabase
-
-Hosting
-
-- Vercel
-
-Repository
-
-- GitHub
-
-Branch
-
-- main
-- develop
-
-Documentazione
-
-- docs/
-
-Database
-
-- Supabase
-
-Storage
-
-- Supabase Storage

.cursor/coding-style.md

@@ -1,12 +0,0 @@
-# Coding Style
-
-Preferenze del progetto.
-
-- Utilizzare TypeScript.
-- Preferire funzioni piccole.
-- Evitare duplicazione di codice.
-- Utilizzare componenti React riutilizzabili.
-- Commentare solamente il codice realmente complesso.
-- Preferire nomi descrittivi.
-- Non introdurre librerie senza reale necessità.
-- Mantenere la struttura esistente del progetto.

.cursor/crapp-context.md

@@ -1,22 +0,0 @@
-# CrAPP Context
-
-CrAPP è una Progressive Web App dedicata alla gestione di una squadra di pallavolo amatoriale.
-
-L'obiettivo principale NON è solamente registrare dati.
-
-L'obiettivo è ridurre il lavoro amministrativo degli amministratori e aumentare il coinvolgimento dei giocatori attraverso gamification, statistiche e strumenti intelligenti.
-
-Quando implementi nuove funzionalità:
-
-- privilegia semplicità
-- mantieni la coerenza dell'interfaccia
-- evita duplicazioni
-- leggi sempre la documentazione presente in `docs/`
-
-Prima di scrivere codice consulta:
-
-- README
-- ROADMAP
-- DATABASE
-- ARCHITECTURE
-- il modulo interessato in `docs/modules`

.cursor/development-workflow.md

@@ -1,11 +0,0 @@
-# Development Workflow
-
-Ogni nuova funzionalità segue questo flusso.
-
-1. Discussione funzionale.
-2. Documento in `docs/modules`.
-3. Progettazione database.
-4. Implementazione su branch `develop`.
-5. Test.
-6. Merge su `main`.
-7. Deploy automatico tramite Vercel.

.cursor/project-rules.md

@@ -1,29 +0,0 @@
-# Project Rules
-
-Queste regole devono essere rispettate per qualsiasi modifica al progetto.
-
-## Regole generali
-
-- Non modificare il branch `main` direttamente.
-- Tutte le nuove funzionalità vengono sviluppate su `develop`.
-- Prima di implementare una funzionalità leggere sempre la documentazione presente in `docs/`.
-- Non creare codice duplicato.
-- Riutilizzare sempre componenti già esistenti quando possibile.
-- Mantenere uno stile coerente con il progetto.
-
-## Database
-
-- Non modificare il database senza creare una nuova migration Supabase.
-- Non eliminare tabelle esistenti senza esplicita richiesta.
-- Preferire nuove tabelle rispetto all'aggiunta di molte colonne quando il modulo è indipendente.
-
-## Componenti
-
-- Preferire componenti piccoli e riutilizzabili.
-- Evitare componenti con responsabilità multiple.
-
-## Documentazione
-
-Ogni nuova funzionalità deve essere documentata prima dell'implementazione.
-
-La documentazione tecnica si trova nella cartella `docs/`.

.cursor/rules/crapp.mdc

@@ -0,0 +1,16 @@
+---
+description: Regole di progetto CrAPP
+alwaysApply: true
+---
+
+Prima di qualsiasi modifica leggi @AGENTS.md e seguine le regole: sono vincolanti e valgono
+per intero.
+
+- Non implementare funzionalità non documentate in `docs/`.
+- Lavora su `develop`, mai direttamente su `main`.
+- Codice, commenti e documentazione in italiano.
+
+Non aggiungere regole in questo file: una regola nuova va in `AGENTS.md`, che leggono anche
+Claude Code e Codex. Vale per qualsiasi aggiunta o modifica — regola, funzionalità, decisione,
+schema database: prima di considerare finito il lavoro esegui la checklist «Fine lavoro» di
+`AGENTS.md`.

AGENTS.md

@@ -1,231 +1,127 @@
-# AGENTS.md
+# AGENTS.md — CrAPP
-
+
-# CrAPP - AI Development Guide
+Regole che qualsiasi assistente AI (Claude Code, Codex, Cursor, ChatGPT o altri) deve seguire
-
+quando lavora su questo progetto. **È l'unica fonte delle regole**: `CLAUDE.md` e
-Questo documento definisce le regole che qualsiasi assistente AI (Cursor, Claude Code, Codex, ChatGPT o altri) deve seguire quando lavora su questo progetto.
+`.cursor/rules/` rimandano qui, non ripetono nulla.
-
+
----
+> **Qualsiasi cosa venga aggiunta o modificata — una regola, una funzionalità, una decisione,
-
+> una tabella — va registrata nei file di riferimento del progetto prima di considerare il
-# Obiettivo del progetto
+> lavoro finito**, indipendentemente dall'assistente con cui è stata fatta. Vedi
-
+> [Fine lavoro](#fine-lavoro-cosa-aggiornare-sempre): non è un passaggio opzionale.
-CrAPP è una Progressive Web App sviluppata per digitalizzare completamente la gestione di una squadra di pallavolo.
+
-
+CrAPP è una Progressive Web App per la gestione di una squadra di pallavolo amatoriale (CRAP
-L'obiettivo principale è:
+Volley). Obiettivi e principi in [docs/VISION.md](docs/VISION.md), architettura in
-
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
-- ridurre il lavoro amministrativo degli amministratori;
+
-- aumentare il coinvolgimento dei giocatori;
+**Codice, commenti, nomi di variabili e documentazione sono in italiano**: mantieni questa
-- centralizzare tutte le informazioni della squadra;
+convenzione.
-- utilizzare l'intelligenza artificiale solo quando porta un reale beneficio.
+
-
+## Prima di modificare il codice
----
+
-
+Leggere sempre, nell'ordine:
-# Prima di modificare il codice
+
-
+1. [docs/README.md](docs/README.md) — indice della documentazione
-Prima di implementare qualsiasi modifica leggere sempre:
+2. [docs/VISION.md](docs/VISION.md)
-
+3. [docs/ROADMAP.md](docs/ROADMAP.md)
-1. docs/README.md
+4. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
-2. docs/VISION.md
+5. [docs/DATABASE.md](docs/DATABASE.md)
-3. docs/ROADMAP.md
+6. [docs/DESIGN_DECISIONS.md](docs/DESIGN_DECISIONS.md)
-4. docs/ARCHITECTURE.md
+7. [docs/TODO.md](docs/TODO.md)
-5. docs/DATABASE.md
+8. il documento del modulo interessato in [docs/modules/](docs/modules/)
-6. docs/DESIGN_DECISIONS.md
+
-7. docs/TODO.md
+**Non implementare funzionalità non documentate** (DD-002).
-8. il documento interessato in docs/modules/
+
-
+## Workflow
-Non implementare funzionalità non documentate.
+
-
+```
----
+idea → progettazione → documento in docs/modules/ → database → implementazione su develop
-
+→ test → merge su main → deploy automatico Vercel
-# Workflow di sviluppo
+```
-
+
-Ogni nuova funzionalità segue sempre questo processo.
+- `main` = produzione, sempre funzionante: **non si modifica direttamente**. Qualsiasi
-
+  modifica deve mantenere l'app perfettamente funzionante.
-Idea
+- `develop` = sviluppo e preview; tutte le nuove implementazioni nascono qui.
-
+
-↓
+## Vincoli tecnici da non violare
-
+
-Progettazione
+- `src/routeTree.gen.ts` e `src/integrations/supabase/{client.ts,types.ts}` sono **generati**:
-
+  non modificarli a mano.
-↓
+- **Non ri-aggiungere** i plugin Vite (devtools, tanstackStart, viteReact, tailwind,
-
+  tsconfig-paths, nitro) già inclusi da `@lovable.dev/vite-tanstack-config` in
-Documentazione
+  `vite.config.ts`: l'app si rompe.
-
+- Nessun accesso al database dai componenti: solo tramite i moduli in `src/lib/`, così il
-↓
+  backend resta sostituibile in un solo punto (DD-013).
-
+- Efficienza cloud: niente polling, cache lunga, e dopo una mutazione `setQueryData` invece di
-Database
+  `invalidateQueries`. Regole complete in [docs/EFFICIENZA_CLOUD.md](docs/EFFICIENZA_CLOUD.md).
-
+- Badge e statistiche si calcolano a runtime, non si persistono (DD-007); la gamification
-↓
+  resta equa tra ruoli (DD-008): niente metriche che favoriscano attaccanti o liberi.
-
+- L'app deve poter girare su Node.js + PostgreSQL standard: niente servizi esclusivi
-Implementazione
+  Lovable/Vercel (DD-001, DD-013, [docs/PORTABILITA.md](docs/PORTABILITA.md)).
-
+
-↓
+## Database
-
+
-Test
+- Non eliminare tabelle esistenti.
-
+- Non modificare lo schema senza creare una migration in `supabase/migrations/`.
-↓
+- Preferire una nuova tabella all'aggiunta di molte colonne, quando il modulo è indipendente.
-
+- Preferire strutture scalabili; evitare duplicazione dei dati.
-Merge su main
+- Riferimento: [docs/DATABASE.md](docs/DATABASE.md), da aggiornare nella stessa modifica che
-
+  cambia lo schema.
-↓
+
-
+## Codice e componenti
-Deploy automatico
+
-
+- TypeScript, funzioni piccole, nomi descrittivi.
----
+- Componenti piccoli, riutilizzabili, a responsabilità singola.
-
+- Nessuna duplicazione: riusare sempre i componenti e i moduli esistenti.
-# Git
+- Commentare solo il codice realmente complesso.
-
+- Nessuna nuova dipendenza senza reale necessità; mantenere la struttura esistente.
-Il repository utilizza due branch principali.
+- Le dipendenze si installano con **bun**; `bunfig.toml` impone `minimumReleaseAge = 24h` come
-
+  guardia supply-chain: aggiungere un pacchetto a `minimumReleaseAgeExcludes` richiede
-## main
+  conferma esplicita dell'utente.
-
+
-Versione stabile.
+## Interfaccia
-
+
-Qualsiasi modifica deve mantenere l'app perfettamente funzionante.
+Stile coerente con l'esistente: semplice, moderna, pulita, veloce, ottimizzata per
-
+smartphone, poche schermate e pochi click (DD-005). Riusare i componenti in
-## develop
+`src/components/crapp/` (`ui-bits.tsx` per `PageHeader`, `Section`, `StatTile`) e le primitive
-
+shadcn in `src/components/ui/`.
-Branch utilizzato per lo sviluppo delle nuove funzionalità.
+
-
+## Fine lavoro: cosa aggiornare sempre
-Tutte le nuove implementazioni devono essere realizzate qui.
+
-
+Il lavoro **non è finito** finché non è registrato dove va. Vale per tutti gli assistenti allo
----
+stesso modo: chi fa la modifica aggiorna i file, chiunque la stia facendo e da qualunque
-
+strumento. Un cambiamento che vive solo nel codice o solo nella chat è un cambiamento perso.
-# Architettura
+
-
+| Cosa hai aggiunto o cambiato | Dove va registrato |
-Frontend
+|---|---|
-
+| Una **regola** per gli assistenti (convenzione, divieto, vincolo di lavoro) | **Questo file, e solo questo.** Mai in `CLAUDE.md` o `.cursor/rules/`: rimandano qui, e una regola scritta lì la vedrebbe un assistente solo |
-- React
+| Una **funzionalità** | `docs/modules/<modulo>.md` (**prima** di scrivere il codice), poi `docs/ROADMAP.md` e `docs/CHANGELOG.md` |
-- TypeScript
+| Una **decisione** architetturale o di prodotto | `docs/DESIGN_DECISIONS.md`, formato `DD-XXX` (copiare `docs/_template-dd.md`) e aggiungerla all'indice in cima |
-- TanStack Start
+| Una **modifica allo schema** del database | una migration in `supabase/migrations/` **e** `docs/DATABASE.md`, nella stessa modifica |
-- Tailwind CSS
+| Lavoro iniziato, sospeso o concluso | `docs/TODO.md` e `PROJECT_STATE.md` |
-
+| Un **comando** o uno script nuovo | `docs/ARCHITECTURE.md` (sezione Comandi) e `CLAUDE.md` |
-Backend
+
-
+Quale informazione vive in quale file — e perché non va duplicata altrove — è spiegato in
-- Supabase
+[docs/README.md](docs/README.md).
-
+
-Hosting
+## Cosa l'AI non deve fare
-
-- Vercel
-
-Repository
-
-- GitHub
-
----
-
-# Database
-
-Il database utilizza Supabase.
-
-Regole:
-
-- non eliminare tabelle esistenti;
-- non modificare lo schema senza creare una migration;
-- preferire strutture scalabili;
-- evitare duplicazione dei dati.
-
-Fare sempre riferimento a:
-
-docs/DATABASE.md
-
----
-
-# Componenti
-
-Preferire:
-
-- componenti piccoli;
-- componenti riutilizzabili;
-- responsabilità singola;
-- codice semplice da mantenere.
-
-Evitare duplicazioni.
-
----
-
-# Interfaccia
-
-Lo stile dell'app deve rimanere coerente.
-
-Principi:
-
-- semplice;
-- moderna;
-- pulita;
-- veloce;
-- ottimizzata per smartphone;
-- poche schermate;
-- pochi click.
-
----
-
-# Documentazione
-
-Ogni nuova funzionalità deve essere documentata prima dello sviluppo.
-
-La documentazione dei moduli si trova in:
-
-docs/modules/
-
-Aggiornare sempre, quando necessario:
-
-- ROADMAP.md
-- CHANGELOG.md
-- TODO.md
-- DATABASE.md (se il database cambia)
-- DESIGN_DECISIONS.md (se si prende una decisione architetturale importante)
----
-
-# Struttura della documentazione
-
-La cartella `docs/` rappresenta la documentazione ufficiale del progetto.
-
-## Documenti principali
-
-- README.md → panoramica del progetto
-- VISION.md → obiettivi e filosofia
-- ROADMAP.md → evoluzione prevista
-- ARCHITECTURE.md → architettura tecnica
-- DATABASE.md → struttura del database
-- DESIGN_DECISIONS.md → registro delle decisioni di progetto
-- CHANGELOG.md → cronologia delle modifiche
-- TODO.md → attività pianificate
-
-## Moduli
-
-La cartella `docs/modules/` contiene una specifica funzionale per ogni modulo dell'applicazione.
-
-Ogni nuovo modulo deve essere progettato e documentato prima dell'implementazione.
----
-
-# Regole
-
-L'AI non deve:
 
 - introdurre librerie senza necessità;
 - modificare il database senza motivazione;
 - eliminare funzionalità esistenti;
 - modificare il comportamento dell'app senza richiesta esplicita.
 
-L'AI deve:
+## Cosa l'AI deve fare
 
 - spiegare le modifiche importanti;
 - mantenere compatibilità con il codice esistente;
 - privilegiare la semplicità;
 - riutilizzare i componenti esistenti.
 
----
+## Filosofia
 
-# Filosofia del progetto
+Prima di scrivere codice, chiedersi sempre:
 
-Prima di scrivere codice chiedersi sempre:
+- questa modifica rende CrAPP più semplice?
-
+- riduce il lavoro degli amministratori?
-Questa modifica rende CrAPP più semplice?
+- migliora l'esperienza dei giocatori?
-
+- è coerente con la documentazione?
-Riduce il lavoro degli amministratori?
-
-Migliora l'esperienza dei giocatori?
-
-È coerente con la documentazione?
-
-Se almeno una risposta è negativa, rivalutare la soluzione proposta.

CLAUDE.md

@@ -1,54 +1,21 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Le regole di progetto stanno in @AGENTS.md: valgono integralmente e non sono ripetute qui.
+La documentazione tecnica è indicizzata in [docs/README.md](docs/README.md); l'architettura
+in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
-CrAPP — PWA per la gestione di una squadra di pallavolo amatoriale (CRAP Volley). Codice, commenti, nomi di variabili e documentazione sono **in italiano**: mantieni questa convenzione.
+**Non aggiungere regole in questo file.** Una regola nuova va in `AGENTS.md`, che leggono
-
+anche Codex e Cursor; scritta qui la vedrebbe solo Claude Code. Vale per qualsiasi aggiunta o
-## Regole di progetto
+modifica: prima di dire che hai finito, esegui la checklist «Fine lavoro» di `AGENTS.md`.
-
-[AGENTS.md](AGENTS.md) contiene le regole vincolanti per gli assistenti AI. In sintesi:
-
-- **Document-first**: nessuna funzionalità va implementata se non è già documentata in [docs/](docs/) (in particolare `docs/modules/<modulo>.md`). Leggi il documento del modulo prima di scrivere codice.
-- Lavora sul branch `develop`, mai direttamente su `main` (`main` = produzione, deploy automatico Vercel).
-- Dopo una modifica aggiorna, quando pertinente: `docs/ROADMAP.md`, `docs/CHANGELOG.md`, `docs/TODO.md`, `docs/DATABASE.md` (se cambia lo schema), `docs/DESIGN_DECISIONS.md` (decisioni architetturali, formato DD-XXX con indice in fondo al file), `PROJECT_STATE.md`.
-- Nessuna nuova dipendenza senza reale necessità; riusa i componenti esistenti.
-- Il DB si modifica solo con una nuova migration in `supabase/migrations/`; non eliminare tabelle.
-- [docs/PORTABILITA.md](docs/PORTABILITA.md) / DD-001 / DD-013: l'app deve poter girare su Node.js + PostgreSQL standard. Evita servizi esclusivi Lovable/Vercel.
 
 ## Comandi
 
 ```bash
-npm run dev      # vite dev su http://localhost:8080
+npm run dev       # vite dev su http://localhost:8080
-npm run build    # build di produzione (nitro)
+npm run build     # build di produzione (nitro)
-npm run lint     # eslint (include prettier come regola)
+npm run lint      # eslint (include prettier come regola)
-npm run format   # prettier --write .
+npm run format    # prettier --write .
+npm run test      # suite di test (test/); npm run test:all per quella completa
 ```
 
-Non esiste una suite di test automatici: la verifica è manuale via `npm run dev` + `npm run lint`.
+Verifica minima prima di consegnare: `npm run lint` + `npm run test`.
-
-Le dipendenze sono installate con **bun** (`bun.lock`, `bunfig.toml`). `bunfig.toml` impone `minimumReleaseAge = 24h` come guardia supply-chain: aggiungere un pacchetto a `minimumReleaseAgeExcludes` richiede conferma esplicita dell'utente.
-
-## Architettura
-
-**Stack**: React 19 + TanStack Start (SSR) + Vite 8 + Tailwind 4 + Radix/shadcn, Supabase come backend, Vercel per l'hosting.
-
-- **Routing**: file-based in [src/routes/](src/routes/); `src/routeTree.gen.ts` è generato — non modificarlo a mano.
-- **Configurazione Vite**: [vite.config.ts](vite.config.ts) usa `@lovable.dev/vite-tanstack-config`, che include già devtools, tanstackStart, viteReact, tailwind, tsconfig-paths, nitro e l'alias `@` → `src/`. **Non ri-aggiungere questi plugin** o l'app si rompe.
-- **Entry point server**: [src/server.ts](src/server.ts) avvolge l'entry di TanStack Start per intercettare gli errori SSR che h3 trasforma silenziosamente in un 500 JSON, e renderizza `renderErrorPage()`. [src/start.ts](src/start.ts) registra i middleware globali (error handler, CSRF sui server functions, `attachSupabaseAuth`).
-- **Supabase**: `src/integrations/supabase/client.ts` (browser/SSR, chiave publishable — file generato) e `client.server.ts` (`supabaseAdmin`, solo server). `types.ts` è generato dallo schema.
-
-**Livello dati** — tutta la logica di dominio sta in [src/lib/](src/lib/), un file per modulo (`presenze`, `eventi`, `pagelle`, `mvp-voti`, `palloni`, `cacche`, `badges`, `scout-*`, `infortuni`, …). Il pattern ricorrente:
-
-- ogni modulo esporta hook TanStack Query (`useX`) con `staleTime` lungo e mutation che invalidano la propria chiave;
-- le funzioni pure di calcolo sono separate dagli hook (es. `palloni-core.ts` vs `palloni.ts`, `mediePagelle()` vs `usePagelle()`);
-- [src/lib/rosa.ts](src/lib/rosa.ts) è l'aggregatore: compone tutti gli hook e restituisce la rosa completa con le statistiche derivate, **senza query aggiuntive** rispetto a quelle già in cache. Le route consumano `useRosa()`, non i singoli moduli.
-
-Vincoli di efficienza cloud (vedi `mem/`): niente polling, cache lunga, aggregati precalcolati.
-
-**Badge e statistiche** sono calcolati a runtime dai dati, non persistiti (DD-007). La gamification deve restare equa tra ruoli (DD-008): niente metriche che favoriscano attaccanti o liberi.
-
-La rosa è tuttora **hardcoded** in `src/lib/crapp-data.ts` (`rosaCSI`); la migrazione verso la tabella `giocatori_squadra` (migration `20260828170400_m1_giocatori_squadra.sql`) è in corso — vedi DD-015 e DD-016.
-
-## UI
-
-Componenti condivisi in [src/components/crapp/](src/components/crapp/) (`ui-bits.tsx` per `PageHeader`, `Section`, `StatTile`), primitive shadcn in `src/components/ui/`, animazioni in `src/components/motion/`. Mobile-first (DD-005): poche schermate, pochi click.

docs/ARCHITECTURE.md

@@ -1,71 +1,105 @@
 # Architettura del progetto
 
-## Frontend
+Come è fatta CrAPP: stack, organizzazione del codice, flusso di sviluppo. È il documento di
+riferimento tecnico — `CLAUDE.md` non ripete questi contenuti, li richiama.
 
-- React 19
+## Stack
-- TypeScript
-- TanStack Start
-- Vite
-- Tailwind CSS
-- Radix UI
 
----
+| Livello | Tecnologie |
+|---|---|
+| Frontend | React 19, TypeScript, TanStack Start (SSR), Vite 8, Tailwind CSS 4, Radix UI / shadcn |
+| Backend | Supabase (PostgreSQL, Auth, Storage) |
+| Hosting | Vercel |
+| Versionamento | Git, GitHub |
 
-## Backend
+Le dipendenze sono installate con **bun** (`bun.lock`, `bunfig.toml`). `bunfig.toml` impone
-
+`minimumReleaseAge = 24h` come guardia supply-chain: aggiungere un pacchetto a
-- Supabase
+`minimumReleaseAgeExcludes` richiede conferma esplicita.
-
----
-
-## Hosting
-
-- Vercel
-
----
-
-## Versionamento
-
-- Git
-- GitHub
-
----
-
-## Branch
-
-- main → Produzione
-- develop → Sviluppo
-
----
 
 ## Struttura del progetto
 
+```
 src/
+  components/   componenti condivisi (crapp/, ui/, motion/)
+  routes/       routing file-based
+  lib/          logica di dominio, un file per modulo
+  integrations/ client Supabase e integrazioni esterne
+  hooks/
+  assets/
+supabase/       migration SQL
+test/           suite di test (unit, integration, end-to-end)
+docs/           documentazione ufficiale
+```
 
-- components/
+## Punti fermi
-- routes/
-- lib/
-- integrations/
-- hooks/
-- assets/
 
-supabase/
+- **Routing**: file-based in `src/routes/`. `src/routeTree.gen.ts` è **generato**, non si
+  modifica a mano.
+- **Configurazione Vite**: `vite.config.ts` usa `@lovable.dev/vite-tanstack-config`, che
+  include già devtools, tanstackStart, viteReact, tailwind, tsconfig-paths, nitro e l'alias
+  `@` → `src/`. **Non ri-aggiungere questi plugin**: l'app si rompe.
+- **Entry point server**: `src/server.ts` avvolge l'entry di TanStack Start per intercettare
+  gli errori SSR che h3 trasformerebbe in un 500 JSON silenzioso, e renderizza
+  `renderErrorPage()`. `src/start.ts` registra i middleware globali (error handler, CSRF sui
+  server functions, `attachSupabaseAuth`).
+- **Supabase**: `src/integrations/supabase/client.ts` (browser/SSR, chiave publishable — file
+  generato) e `client.server.ts` (`supabaseAdmin`, solo server). `types.ts` è generato dallo
+  schema.
 
-docs/
+## Livello dati
 
----
+Tutta la logica di dominio sta in `src/lib/`, un file per modulo (`presenze`, `eventi`,
+`pagelle`, `mvp-voti`, `palloni`, `cacche`, `badges`, `scout-*`, `infortuni`, …). Il pattern
+ricorrente:
 
-## Flusso di sviluppo
+- ogni modulo esporta hook TanStack Query (`useX`); i default globali stanno in
+  `src/router.tsx` (`staleTime` 5 min, `gcTime` 30 min, `refetchOnWindowFocus/Mount/Reconnect`
+  disattivati, `retry: 1`);
+- dopo una mutazione la cache si aggiorna con `setQueryData`, **non** con
+  `invalidateQueries`: invalidare provoca una rilettura e costa una query in più (unica
+  eccezione oggi: `scout-live.ts`);
+- le funzioni pure di calcolo sono separate dagli hook (es. `palloni-core.ts` vs
+  `palloni.ts`, `mediePagelle()` vs `usePagelle()`);
+- `src/lib/rosa.ts` è l'aggregatore: compone tutti gli hook e restituisce la rosa completa
+  con le statistiche derivate, **senza query aggiuntive** rispetto a quelle già in cache. Le
+  route consumano `useRosa()`, non i singoli moduli.
 
-develop
+Nessun accesso al database dai componenti: solo attraverso i moduli in `src/lib/`, così il
+backend resta sostituibile in un solo punto (DD-013, [PORTABILITA.md](PORTABILITA.md)).
 
-↓
+Vincoli di efficienza cloud — niente polling, cache lunga, `setQueryData` invece di
+`invalidateQueries` — in [EFFICIENZA_CLOUD.md](EFFICIENZA_CLOUD.md).
 
-Test
+Badge e statistiche sono calcolati a runtime dai dati, non persistiti (DD-007). La
+gamification deve restare equa tra ruoli (DD-008).
 
-↓
+La rosa è tuttora **hardcoded** in `src/lib/crapp-data.ts` (`rosaCSI`); la migrazione verso
+la tabella `giocatori_squadra` è in corso — vedi DD-015 e DD-016.
 
-Merge su main
+## UI
 
-↓
+Componenti condivisi in `src/components/crapp/` (`ui-bits.tsx` per `PageHeader`, `Section`,
+`StatTile`), primitive shadcn in `src/components/ui/`, animazioni in
+`src/components/motion/`. Mobile-first (DD-005): poche schermate, pochi click.
 
-Deploy automatico su Vercel
+## Comandi
+
+```bash
+npm run dev       # vite dev su http://localhost:8080
+npm run build     # build di produzione (nitro)
+npm run lint      # eslint (include prettier come regola)
+npm run format    # prettier --write .
+npm run test      # test unit (veloci, senza rete né database)
+npm run test:integration  # route server vere
+npm run test:e2e          # percorsi sull'app servita
+npm run test:all          # tutto
+```
+
+## Branch e flusso di sviluppo
+
+- `main` → produzione, deploy automatico su Vercel.
+- `develop` → sviluppo; si lavora qui, mai direttamente su `main` (DD-003).
+
+```
+develop → test → merge su main → deploy automatico su Vercel
+```

docs/CHANGELOG.md

@@ -1,10 +1,10 @@
 # Changelog
 
-Tutte le modifiche significative del progetto vengono registrate in questo documento.
+Tutte le modifiche significative del progetto vengono registrate in questo documento, in
+ordine dalla più recente. L'elenco delle funzionalità disponibili e previste non si ripete
+qui: sta in [ROADMAP.md](ROADMAP.md).
 
----
+## Versione attuale — agosto 2026
-
-## Versione attuale
 
 ### Test
 
@@ -18,7 +18,7 @@ Tutte le modifiche significative del progetto vengono registrate in questo docum
 - Classifica e risultati ufficiali letti dal portale Livescore CSI Bologna
   (stagione 2025/26, Campionato Open Misto Eccellenza, Girone B).
 - La pagina Campionato non usa più dati dimostrativi.
-- Dettagli e limiti in `docs/modules/collegamento-csi.md`.
+- Dettagli e limiti in [modules/collegamento-csi.md](modules/collegamento-csi.md).
 
 ### Infrastruttura
 
@@ -28,17 +28,7 @@ Tutte le modifiche significative del progetto vengono registrate in questo docum
 - Deploy automatico tramite Vercel.
 - Branch main e develop.
 
----
+## Versione 1.0 — luglio 2026
 
-## Funzionalità implementate
+Prima versione usata dalla squadra. Funzionalità incluse: vedi
-
+[ROADMAP.md § Versione 1.0](ROADMAP.md#versione-10--rilasciata).
-- Gestione squadra
-- Calendario
-- Presenze
-- Scout Live
-- Badge
-- Obiettivi di squadra
-- Pagelle
-- Badge social
-- Serie di presenze
-- Notifiche intelligenti

docs/DATABASE.md

@@ -1,159 +1,60 @@
 # Database CrAPP
 
-## Obiettivo
+Struttura del database Supabase (PostgreSQL) e ruolo di ogni tabella. Lo schema autoritativo
+sono le migration in `supabase/migrations/`: **una tabella nuova va documentata qui nella
+stessa modifica che la crea**. Le funzionalità future stanno in [ROADMAP.md](ROADMAP.md),
+non in questo file.
 
-Questo documento descrive la struttura del database Supabase e il ruolo di ogni tabella.
+## Anagrafica e utenti
 
----
+| Tabella | Scopo | Note |
+|---|---|---|
+| `giocatori_squadra` | Anagrafica operativa della squadra, con ID testuali (`g1`…`gN`), dati gestiti dagli admin (nome, cognome, numero, ruolo) e collegamento all'account (`auth_user_id`). | Introdotta dalla migration `m1_giocatori_squadra`, già popolata (17 giocatori) ma **non ancora letta dal codice**: la rosa arriva tuttora da `src/lib/crapp-data.ts`, che resta il fallback anche dopo il passaggio. Destinata a diventare la source of truth. Vedi DD-015 e DD-016. |
+| `giocatori` | Anagrafica giocatori con UUID. | Presente ma **non usata** dal codice attuale: la convergenza è rinviata (DD-012, DD-014). |
+| `profili_giocatore` | Dati personali, metadati del documento d'identità, certificato medico e path dei file, in relazione 1:1 con `giocatori_squadra`. | **Prevista** per la v1.1 (DD-016), non ancora creata. |
+| `user_roles` | Ruoli applicativi (es. amministratore, giocatore). | |
 
-# Utenti
+`giocatori_squadra` / `giocatori` sono usate da: Squadra, Profili, Presenze, Scout, Badge, Pagelle.
 
-## giocatori
+## Eventi e presenze
 
-Contiene l'anagrafica dei giocatori.
+| Tabella | Scopo | Note |
+|---|---|---|
+| `eventi_app` | Eventi gestionali utilizzati dall'app. | Modello in uso dal codice attuale. |
+| `risposte_presenze` | Risposte dei giocatori agli eventi. | Modello in uso dal codice attuale. |
+| `eventi` | Calendario generale: allenamenti, partite, eventi della squadra. | Modello "nuovo" con autenticazione e vincoli, non ancora adottato (DD-014). |
+| `presenze` | Presenze agli eventi. | Come sopra (DD-014). |
 
-Utilizzato da:
+## Scout
 
-- Squadra
+| Tabella | Scopo | Note |
-- Profili
+|---|---|---|
-- Presenze
+| `scout_sessioni` | Sessioni di Scout Live: una sessione corrisponde a una partita. | **Non ancora usata dal codice**: oggi lo stato della sessione vive in `localStorage` (`src/lib/scout-live.ts`, `scout-store.ts`) e sul database finiscono solo le azioni in `scout_live`. |
-- Scout
+| `scout_live` | Eventi registrati durante lo Scout Live. | Serve esclusivamente per statistiche di squadra, mai per classifiche individuali (DD-008). |
-- Badge
-- Pagelle
 
----
+## Votazioni
 
-## user_roles
+| Tabella | Scopo | Note |
+|---|---|---|
+| `mvp_voti` | Voti MVP assegnati a fine partita. | |
+| `pagelle_voti` | Voti anonimi assegnati ai giocatori. | Usati per il voto medio. |
+| `badge_social_voti` | Voti social per i badge. | |
 
-Definisce i ruoli applicativi.
+## Turni e notifiche
 
-Esempi:
+| Tabella | Scopo | Note |
+|---|---|---|
+| `turni_palloni` | Gestione dei turni palloni. | |
+| `push_subscriptions` | Dispositivi registrati per le notifiche Push. | |
+| `promemoria_push` | Storico dei promemoria inviati. | |
 
-- amministratore
+## Funzioni speciali
-- giocatore
 
----
+| Tabella | Scopo | Note |
+|---|---|---|
+| `cacche_partita` | Sondaggio prepartita. | Usato per statistiche e badge segreti. |
 
-# Eventi
+## Badge
 
-## eventi
+Non esiste una tabella dedicata: i badge vengono **calcolati a runtime** dall'applicazione a
-
+partire dai dati esistenti (DD-007).
-Calendario generale.
-
-Comprende:
-
-- allenamenti
-- partite
-- eventi della squadra
-
----
-
-## eventi_app
-
-Eventi gestionali utilizzati dall'app.
-
----
-
-# Presenze
-
-## presenze
-
-Gestisce le presenze agli eventi.
-
----
-
-## risposte_presenze
-
-Memorizza le risposte dei giocatori.
-
----
-
-# Scout
-
-## scout_sessioni
-
-Sessioni di Scout Live.
-
-Una sessione corrisponde ad una partita.
-
----
-
-## scout_live
-
-Eventi registrati durante lo Scout Live.
-
-Serve esclusivamente per statistiche di squadra.
-
----
-
-# Votazioni
-
-## mvp_voti
-
-Voti MVP assegnati a fine partita.
-
----
-
-## pagelle_voti
-
-Voti anonimi assegnati ai giocatori.
-
-Utilizzati per il voto medio.
-
----
-
-## badge_social_voti
-
-Voti social per i badge.
-
----
-
-# Badge
-
-Attualmente i badge vengono calcolati dall'applicazione.
-
-Non esiste una tabella dedicata.
-
----
-
-# Turni
-
-## turni_palloni
-
-Gestione dei turni palloni.
-
----
-
-# Notifiche
-
-## push_subscriptions
-
-Dispositivi registrati per le notifiche Push.
-
----
-
-## promemoria_push
-
-Storico dei promemoria inviati.
-
----
-
-# Funzioni speciali
-
-## cacche_partita
-
-Sondaggio prepartita.
-
-Utilizzato per statistiche e badge segreti.
-
----
-
-# Moduli futuri
-
-Da implementare
-
-- Certificati medici
-- Tesseramenti CSI
-- Database allenamenti
-- AI Allenamenti
-- Integrazione CSI

docs/DESIGN_DECISIONS.md

@@ -12,6 +12,36 @@ Serve a rispondere a domande del tipo:
 
 ---
 
+## Indice
+
+**Accettate**
+
+| ID | Titolo |
+|---|---|
+| [DD-001](#dd-001--crapp-deve-restare-indipendente-da-lovable) | Indipendenza da Lovable |
+| [DD-002](#dd-002--sviluppo-document-first) | Sviluppo document-first |
+| [DD-003](#dd-003--due-branch-main-stabile-develop-per-il-lavoro) | Branch main / develop |
+| [DD-004](#dd-004--ogni-versione-aggiunge-non-riscrive) | Ogni versione aggiunge, non riscrive |
+| [DD-005](#dd-005--mobile-first-pochi-click-pochi-schermi) | Mobile-first |
+| [DD-006](#dd-006--intelligenza-artificiale-solo-se-porta-beneficio-reale) | AI solo se utile |
+| [DD-007](#dd-007--badge-calcolati-dallapp-non-salvati-nel-database) | Badge calcolati, non in DB |
+| [DD-008](#dd-008--gamification-equa-tra-ruoli) | Gamification equa tra ruoli |
+| [DD-009](#dd-009--tesseramento-csi-manuale-in-v11-integrazione-api-in-v20) | CSI manuale v1.1, API v2.0 |
+| [DD-010](#dd-010--profilo-giocatore-niente-storico-certificati-in-v1) | Niente storico certificati v1 |
+| [DD-011](#dd-011--autenticazione-reale-prima-del-profilo-amministrativo-completo) | Auth reale prima del profilo |
+| [DD-012](#dd-012--non-migrare-gli-id-giocatore-in-v11) | Non migrare ID in v1.1 |
+| [DD-013](#dd-013--portabilità-lapp-non-deve-dipendere-da-servizi-esclusivi) | Portabilità dello stack |
+| [DD-016](#dd-016--schema-dati-profilo-giocatore-v11-f0) | Schema dati Profilo Giocatore v1.1 |
+
+**In valutazione**
+
+| ID | Titolo |
+|---|---|
+| [DD-014](#dd-014--convergenza-schema-database-eventi-e-presenze) | Convergenza schema DB |
+| [DD-015](#dd-015--rosa-anagrafica-da-codice-hardcoded-a-database) | Rosa da hardcoded a DB |
+
+---
+
 ## Come usare questo registro
 
 Ogni decisione segue lo stesso schema:
@@ -39,6 +69,11 @@ Ogni decisione segue lo stesso schema:
 - scelte estetiche minori;
 - bugfix o correzioni puntuali.
 
+**Come registrare una nuova decisione**
+
+Copiare [`_template-dd.md`](_template-dd.md) in fondo al documento, assegnare il primo ID
+libero e aggiungerlo all'indice.
+
 ---
 
 ## Decisioni accettate
@@ -442,57 +477,3 @@ Il profilo v1.1 può agganciarsi agli ID attuali; la migrazione rosa può essere
 In parallelo o subito dopo il rollout auth.
 
 ---
-
-## Template per nuove decisioni
-
-Copiare questo blocco in fondo al documento quando serve registrare una nuova scelta.
-
----
-
-### DD-XXX — [Titolo breve della decisione]
-
-**Data:**  
-**Stato:** Accettata · In valutazione · Sostituita · Obsoleta
-
-**Contesto**  
-[Quale problema stavamo risolvendo?]
-
-**Decisione**  
-[Cosa abbiamo scelto?]
-
-**Alternative scartate**  
-- [Alternativa 1] → [perché no]  
-- [Alternativa 2] → [perché no]
-
-**Conseguenze**  
-[Cosa cambia per utenti, admin e team di sviluppo]
-
-**Riesame**  
-[Quando o in quali condizioni rivedere la decisione]
-
----
-
-## Indice rapido
-
-| ID | Titolo | Stato |
-|---|---|---|
-| DD-001 | Indipendenza da Lovable | Accettata |
-| DD-002 | Sviluppo document-first | Accettata |
-| DD-003 | Branch main / develop | Accettata |
-| DD-004 | Ogni versione aggiunge, non riscrive | Accettata |
-| DD-005 | Mobile-first | Accettata |
-| DD-006 | AI solo se utile | Accettata |
-| DD-007 | Badge calcolati, non in DB | Accettata |
-| DD-008 | Gamification equa tra ruoli | Accettata |
-| DD-009 | CSI manuale v1.1, API v2.0 | Accettata |
-| DD-010 | Niente storico certificati v1 | Accettata |
-| DD-011 | Auth reale prima del profilo | Accettata |
-| DD-012 | Non migrare ID in v1.1 | Accettata |
-| DD-013 | Portabilità dello stack | Accettata |
-| DD-016 | Schema dati Profilo Giocatore v1.1 | Accettata |
-| DD-014 | Convergenza schema DB | In valutazione |
-| DD-015 | Rosa da hardcoded a DB | In valutazione |
-
----
-
-*Ultimo aggiornamento: 28 agosto 2026*

docs/EFFICIENZA_CLOUD.md

@@ -0,0 +1,36 @@
+# Efficienza cloud
+
+Regola di progetto: CrAPP gira su un piano cloud minimo (Supabase + Vercel) per ~17 utenti.
+Query, traffico e invocazioni vanno tenuti al minimo **per costruzione**, non ottimizzati dopo.
+
+## Regole da rispettare
+
+1. **Niente polling**: mai `refetchInterval` verso il database. Per sincronizzare più schede
+   aperte si usano `BroadcastChannel` o gli eventi di `storage`.
+2. **Cache lunga e passiva**: i default del `QueryClient` stanno in `src/router.tsx`
+   (`staleTime` 5 min, `gcTime` 30 min, `refetchOnWindowFocus/Mount/Reconnect` disattivati,
+   `retry: 1`). Non alzare la frequenza di refetch modulo per modulo.
+3. **Dopo una mutazione si aggiorna la cache con `setQueryData`**, non con
+   `invalidateQueries`: invalidare costa una rilettura. Unica eccezione oggi:
+   `src/lib/scout-live.ts`.
+4. **Scout Live**: scrive solo chi sta segnando; gli altri leggono dati già salvati.
+5. **Write once, read many**: statistiche, badge e classifiche si calcolano una volta e non
+   si ricalcolano a ogni apertura di pagina. I badge restano calcolati a runtime dai dati già
+   in cache, senza query aggiuntive (DD-007): `src/lib/rosa.ts` aggrega ciò che è già stato
+   letto.
+6. **Push solo per eventi importanti**: convocazioni, promemoria allenamento/partita, turno
+   palloni, esito finale.
+7. **Niente funzionalità pesanti**: foto, video, chat.
+8. **Indici** sui campi usati per filtri e relazioni in ogni nuova migration.
+
+## Obiettivi non ancora attuati
+
+Questi punti sono stati definiti come direzione, ma **non sono implementati**: non descrivono
+il comportamento attuale.
+
+- **Dati CSI**: sincronizzazione periodica server-side salvata su una tabella locale, con
+  l'app che legge solo dal database interno. Oggi la lettura è live dal portale a ogni
+  richiesta, tramite `/api/public/csi` (vedi [modules/collegamento-csi.md](modules/collegamento-csi.md)).
+- **Aggregati persistiti**: uno schema con `statistiche_aggregate` e `classifica_csi` è stato
+  ipotizzato ma non esiste; nessuna di quelle tabelle è in `supabase/migrations/`. Va valutato
+  con una decisione dedicata, perché tocca DD-007 (badge e statistiche calcolati a runtime).

docs/README.md

@@ -0,0 +1,44 @@
+# Documentazione CrAPP
+
+Indice della documentazione ufficiale del progetto. Ogni file risponde a una domanda
+precisa: se l'informazione che cerchi non è nel file indicato, probabilmente non esiste
+ancora e va **prima documentata** (vedi [DD-002](DESIGN_DECISIONS.md#dd-002--sviluppo-document-first)).
+
+## Dove sta cosa
+
+| Documento | Risponde a |
+|---|---|
+| [VISION.md](VISION.md) | Perché esiste CrAPP, quali principi deve rispettare una funzionalità |
+| [ROADMAP.md](ROADMAP.md) | Cosa è fatto e cosa è previsto, versione per versione |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | Com'è fatta l'app: stack, struttura del codice, flusso di sviluppo |
+| [DATABASE.md](DATABASE.md) | Quali tabelle esistono, a cosa servono, chi le usa |
+| [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md) | Perché abbiamo scelto così, cosa abbiamo escluso e quando riaprire la scelta |
+| [PORTABILITA.md](PORTABILITA.md) | Cosa lega l'app a un fornitore e cosa no, come spostarla su server proprio |
+| [EFFICIENZA_CLOUD.md](EFFICIENZA_CLOUD.md) | Come tenere basso il consumo cloud: cache, query, push |
+| [TODO.md](TODO.md) | A cosa si sta lavorando adesso |
+| [CHANGELOG.md](CHANGELOG.md) | Cosa è cambiato e quando |
+| [modules/](modules/) | Specifica funzionale di ogni modulo, una per file |
+
+Le regole vincolanti per gli assistenti AI stanno in [AGENTS.md](../AGENTS.md);
+lo stato corrente del lavoro in [PROJECT_STATE.md](../PROJECT_STATE.md).
+
+## Ordine di lettura
+
+Prima di modificare il codice, nell'ordine: questo indice → `VISION.md` → `ROADMAP.md` →
+`ARCHITECTURE.md` → `DATABASE.md` → `DESIGN_DECISIONS.md` → `TODO.md` → il documento del
+modulo interessato in `modules/`.
+
+## Regole di manutenzione
+
+Ogni informazione ha **una sola casa**, per evitare che le copie divergano:
+
+- l'elenco delle funzionalità (fatte e previste) sta solo in `ROADMAP.md`;
+- `CHANGELOG.md` registra *quando* qualcosa è stato rilasciato, non ripete l'elenco;
+- `TODO.md` contiene solo il lavoro in corso o imminente, e rimanda alla roadmap;
+- lo schema del database sta solo in `DATABASE.md`, allineato alle migration in
+  `supabase/migrations/`: una tabella nuova si documenta nella stessa modifica che la crea;
+- le motivazioni stanno solo in `DESIGN_DECISIONS.md`, in voci `DD-XXX`; per aggiungerne
+  una si copia [\_template-dd.md](_template-dd.md).
+
+Convenzioni di scrittura: un solo titolo `#` per file (le sezioni interne partono da `##`),
+niente `---` come riempitivo tra i paragrafi, tabelle al posto degli elenchi ripetitivi.

docs/ROADMAP.md

@@ -1,16 +1,21 @@
 # Roadmap
 
-## Versione 1.0
+Elenco unico delle funzionalità di CrAPP, fatte e previste. È la fonte di riferimento per
+il *cosa*: `CHANGELOG.md` registra *quando* una voce è stata rilasciata, `TODO.md` cosa si
+sta facendo adesso.
+
+## Versione 1.0 — rilasciata
 
 - [x] Gestione squadra
 - [x] Calendario
 - [x] Presenze
+- [x] Serie di presenze
 - [x] Scout Live
 - [x] Badge
+- [x] Badge social
+- [x] Pagelle
 - [x] Obiettivi di squadra
-- [x] Notifiche Push
+- [x] Notifiche Push (promemoria intelligenti)
-
----
 
 ## Versione 1.1
 
@@ -19,16 +24,12 @@
 - [ ] Dashboard amministratore
 - [ ] Download CSV dati
 
----
-
 ## Versione 1.2
 
 - [ ] Database esercizi
 - [ ] AI Allenamenti
 - [ ] Archivio allenamenti
 
----
-
 ## Versione 2.0
 
 - [x] Collegamento CSI (stagione 2025/26)
@@ -36,11 +37,11 @@
 - [x] Risultati campionato
 - [ ] Calendario ufficiale
 
----
-
 ## Idee future
 
 - [ ] Gestione quote
 - [ ] Calendario Google
 - [ ] Backup automatici
-- [ ] Analisi statistiche avanzate
+- [ ] Analisi statistiche avanzate
+- [ ] Widget meteo
+- [ ] Analisi Scout con AI

docs/TODO.md

@@ -1,30 +1,35 @@
 # TODO
 
+Solo il lavoro in corso o imminente. L'elenco completo delle funzionalità previste sta in
+[ROADMAP.md](ROADMAP.md); le idee non ancora valutate pure.
+
 ## In corso
 
 - Documentazione tecnica del progetto.
 
----
-
 ## Prossimo
 
-- Certificati medici.
+- Certificati medici (roadmap v1.1).
-- Gestione tesseramenti CSI.
+- Gestione tesseramenti CSI (roadmap v1.1).
 
----
+## Debito di documentazione
+
+Moduli v1.0 in produzione senza scheda in [modules/](modules/) — DD-002 ne prevede la
+retro-documentazione: Presenze, Scout Live, Badge, Pagelle, MVP, Palloni, Obiettivi di
+squadra, Notifiche, Serie di presenze, Infortuni (`src/lib/infortuni.ts`, usato ma non
+documentato in nessun punto).
+
+Non documentate nemmeno le route API pubbliche in `src/routes/api/public/` (`csi`,
+`promemoria-palloni`, `push-config`, `push-messaggio`, `push-subscribe`,
+`sollecita-presenze`).
+
+## Manutenzione ricorrente
+
+- Collegamento CSI: aggiornare `project_id` e `team_id` a inizio stagione 2026/27
+  (vedi [modules/collegamento-csi.md](modules/collegamento-csi.md)).
 
 ## Backlog
 
-- AI Allenamenti.
+- AI Allenamenti (roadmap v1.2).
-- Dashboard amministratore.
+- Dashboard amministratore (roadmap v1.1).
-- Collegamento CSI: aggiornare `project_id` e `team_id` per la stagione 2026/27
+- Backup automatici (roadmap, idee future).
-  (base implementata, vedi `docs/modules/collegamento-csi.md`).
-
----
-
-## Idee
-
-- Gestione quote.
-- Widget meteo.
-- Analisi Scout con AI.
-- Backup automatici.

docs/VISION.md

@@ -6,8 +6,6 @@ CrAPP nasce con un obiettivo semplice:
 
 Digitalizzare completamente la gestione di una squadra di pallavolo, eliminando il maggior numero possibile di attività manuali e aumentando il coinvolgimento dei giocatori attraverso strumenti moderni e intuitivi.
 
----
-
 ## Principi del progetto
 
 Ogni funzionalità sviluppata deve rispettare almeno uno di questi principi:
@@ -18,8 +16,6 @@ Ogni funzionalità sviluppata deve rispettare almeno uno di questi principi:
 - Automatizzare le attività ripetitive.
 - Sfruttare l'intelligenza artificiale solo quando porta un reale beneficio.
 
----
-
 ## Filosofia
 
 CrAPP deve essere:
@@ -31,8 +27,6 @@ CrAPP deve essere:
 - Accessibile da smartphone
 - Utilizzabile anche da persone poco esperte
 
----
-
 ## Obiettivo finale
 
 Diventare il punto di riferimento per la gestione quotidiana della squadra, sostituendo chat, fogli Excel e strumenti separati con un'unica applicazione.

docs/_template-dd.md

@@ -0,0 +1,20 @@
+### DD-XXX — [Titolo breve della decisione]
+
+**Data:**  
+**Stato:** Accettata · In valutazione · Sostituita · Obsoleta
+
+**Contesto**  
+[Quale problema stavamo risolvendo?]
+
+**Decisione**  
+[Cosa abbiamo scelto?]
+
+**Alternative scartate**  
+- [Alternativa 1] → [perché no]  
+- [Alternativa 2] → [perché no]
+
+**Conseguenze**  
+[Cosa cambia per utenti, admin e team di sviluppo]
+
+**Riesame**  
+[Quando o in quali condizioni rivedere la decisione]

docs/modules/profilo-giocatore.md

@@ -1,4 +1,4 @@
-# Profilo Giocatore
+# Modulo — Profilo Giocatore
 
 ## Obiettivo
 
@@ -6,11 +6,9 @@ Il modulo "Profilo Giocatore" raccoglie tutte le informazioni personali, amminis
 
 L'obiettivo è centralizzare in un'unica schermata tutti i dati necessari sia al giocatore sia agli amministratori, eliminando la gestione tramite chat, documenti cartacei e fogli Excel.
 
----
+## Utenti
 
-# Utenti
+### Giocatore
-
-## Giocatore
 
 Può:
 
@@ -20,9 +18,7 @@ Può:
 - aggiornare i documenti
 - caricare le immagini richieste
 
----
+### Amministratore
-
-## Amministratore
 
 Può:
 
@@ -31,11 +27,9 @@ Può:
 - esportare i dati necessari al tesseramento CSI
 - verificare lo stato di completamento dei profili
 
----
+## Flusso utente
 
-# Flusso utente
+### Primo accesso
-
-## Primo accesso
 
 1. Login tramite Google oppure Email.
 2. Selezione del proprio giocatore.
@@ -43,23 +37,13 @@ Può:
 
 Se il profilo non è completo compare automaticamente un widget di completamento.
 
----
+## Home
-
-# Home
 
 Il giocatore visualizza un widget dedicato.
 
-## Completa il tuo profilo
+### Completa il tuo profilo
 
-Viene mostrata una barra di avanzamento.
+Viene mostrata una barra di avanzamento (esempio: *Profilo completato — 85%*), composta dalle seguenti sezioni.
-
-Esempio
-
-Profilo completato
-
-85%
-
-La barra è composta dalle seguenti sezioni.
 
 - Dati personali
 - Documento di identità
@@ -68,32 +52,20 @@ La barra è composta dalle seguenti sezioni.
 
 Quando tutte le sezioni sono complete il widget scompare automaticamente.
 
----
+## Profilo
-
-# Profilo
 
 Il profilo viene suddiviso in cinque aree.
 
-## Dati Giocatore
+### Dati Giocatore
 
-Contiene.
+**Dati squadra** — solo lettura, gestiti esclusivamente dagli amministratori.
-
-### Dati squadra
-
-Solo lettura.
 
 - Nome
 - Cognome
 - Numero di maglia
 - Ruolo
 
-Questi dati sono gestiti esclusivamente dagli amministratori.
+**Dati personali** — modificabili dal giocatore.
-
----
-
-### Dati personali
-
-Modificabili dal giocatore.
 
 - Data di nascita
 - Luogo di nascita
@@ -101,9 +73,7 @@ Modificabili dal giocatore.
 - Telefono
 - Email
 
----
+### Documento di identità
-
-## Documento di identità
 
 Campi.
 
@@ -118,9 +88,7 @@ Upload.
 - Foto fronte
 - Foto retro
 
----
+### Certificato medico
-
-## Certificato medico
 
 Campi.
 
@@ -134,21 +102,15 @@ Il giocatore può aggiornare liberamente sia la data sia il file.
 
 Lo storico non viene mantenuto nella prima versione.
 
----
+### Foto tessera
-
-## Foto tessera
 
 Upload di una fotografia formato tessera.
 
 Utilizzata dagli amministratori per il tesseramento CSI.
 
----
+### Statistiche
 
-## Statistiche
+Sezione già presente. Contiene.
-
-Sezione già presente.
-
-Contiene.
 
 - Presenze
 - Voto medio
@@ -156,17 +118,13 @@ Contiene.
 - Serie
 - Altre statistiche disponibili
 
----
+### Badge
-
-## Badge
 
 Sezione già presente.
 
 Contiene tutti i badge ottenuti e quelli ancora da sbloccare.
 
----
+### Impostazioni
-
-## Impostazioni
 
 Contiene.
 
@@ -174,9 +132,7 @@ Contiene.
 - Preferenze notifiche
 - Impostazioni applicazione
 
----
+## Dashboard amministratore
-
-# Dashboard amministratore
 
 Gli amministratori dispongono di una schermata dedicata.
 
@@ -194,9 +150,7 @@ Azioni disponibili.
 - Scarica documento
 - Scarica foto tessera
 
----
+## Esportazione CSI
-
-# Esportazione CSI
 
 Gli amministratori possono esportare un file CSV contenente esclusivamente i dati richiesti per il tesseramento.
 
@@ -215,51 +169,26 @@ Campi esportati.
 - Data emissione
 - Data scadenza
 
----
+## Completamento profilo
-
-# Completamento profilo
 
 Ogni sezione contribuisce alla percentuale di completamento.
 
-## Pesi
+| Sezione | Peso |
-
+|---|---|
-Dati personali
+| Dati personali | 30% |
-
+| Documento di identità | 30% |
-30%
+| Certificato medico | 30% |
-
+| Foto tessera | 10% |
-Documento di identità
-
-30%
-
-Certificato medico
-
-30%
-
-Foto tessera
-
-10%
 
 Quando tutte le sezioni risultano complete il profilo raggiunge il 100%.
 
----
+## Permessi
 
-# Permessi
+**Giocatore** — può modificare esclusivamente il proprio profilo.
 
-## Giocatore
+**Amministratore** — può visualizzare tutti i profili, scaricare tutti i documenti ed esportare i dati.
 
-Può modificare esclusivamente il proprio profilo.
+## Versione 1
-
-## Amministratore
-
-Può visualizzare tutti i profili.
-
-Può scaricare tutti i documenti.
-
-Può esportare i dati.
-
----
-
-# Versione 1
 
 - Profilo giocatore
 - Completamento profilo
@@ -270,12 +199,10 @@ Può esportare i dati.
 - Dashboard amministratore
 - Esportazione CSV CSI
 
----
+## Versioni future
-
-# Versioni future
 
 - Storico certificati medici
 - Gestione documenti aggiuntivi
 - Consensi privacy
 - Firma digitale
-- Verifica automatica documenti
+- Verifica automatica documenti

mem/features/cloud-efficienza.md

@@ -1,14 +0,0 @@
----
-name: Efficienza Cloud
-description: Regole per minimizzare query, traffico e invocazioni Cloud (piano 20 crediti/mese, 17 utenti)
-type: feature
----
-- Nessun polling (`refetchInterval`) verso il database; sincronizzazione locale via BroadcastChannel/storage dove possibile.
-- QueryClient globale: staleTime 5 min, gcTime 30 min, refetchOnWindowFocus/Mount/Reconnect disattivati, retry 1.
-- Dopo una mutazione aggiornare la cache con `setQueryData`, non `invalidateQueries` (evita riletture).
-- Scout live: scrive solo l'utente che segna; gli altri leggono dati già salvati.
-- Statistiche, badge e classifiche: "write once, read many" — calcolate e salvate una volta a fine partita, mai ricalcolate a ogni apertura pagina.
-- Dati CSI: sincronizzazione periodica server-side salvata su tabella locale; l'app legge solo dal database interno.
-- Push solo per eventi importanti: convocazioni, promemoria allenamento/partita, turno palloni, esito finale.
-- Niente foto/video/chat o funzionalità pesanti.
-- Schema target: team_id, eventi, presenze, azioni_scout, statistiche_aggregate, classifica_csi, notifiche, con indici sui campi di filtro/relazione.

mem/features/portabilita.md

@@ -1,16 +0,0 @@
----
-name: Portabilità su Node.js + PostgreSQL
-description: Vincolo di architettura — l'app deve girare su un normale server Node.js con PostgreSQL, senza servizi esclusivi Lovable Cloud
-type: constraint
----
-L'app deve restare completamente portabile: ogni funzionalità deve poter girare su un normale server Node.js con PostgreSQL.
-
-Regole:
-- Accesso ai dati solo tramite i moduli in `src/lib/*.ts`; i componenti non parlano mai direttamente col database.
-- Vietato usare funzionalità proprietarie Lovable/Supabase non self-hostable (edge functions proprietarie, auth Lovable come unico login, storage proprietario). `src/integrations/lovable/*` resta opzionale e non importato.
-- SQL standard PostgreSQL nelle migrazioni; niente estensioni esclusive del provider.
-- Configurazione solo via variabili d'ambiente standard; niente valori hardcoded.
-- Job pianificati sempre richiamabili con un semplice HTTP POST, così funzionano con qualsiasi scheduler.
-- Web push implementato con Web Crypto (compatibile Node 18+), non con SDK proprietari.
-
-Dettaglio e guida di migrazione: `docs/PORTABILITA.md`.

mem/index.md

@@ -1,2 +1,4 @@
-- [Efficienza Cloud](mem://features/cloud-efficienza) — Regole anti-consumo: niente polling, cache lunga, aggregati precalcolati, sync CSI server-side
+Le regole di progetto non vivono più qui: sono in `docs/`.
-- [Portabilità](mem://features/portabilita) — L'app deve girare su Node.js + PostgreSQL standard, nessun servizio esclusivo Lovable Cloud
+
+- Efficienza cloud → `docs/EFFICIENZA_CLOUD.md`
+- Portabilità → `docs/PORTABILITA.md`