Documentazione del grafo graphify e graphify-out/ ignorato

Aggiunge docs/GRAFO.md (uso, rigenerazione, limiti), lo indicizza in
docs/README.md, richiama il grafo in AGENTS.md e CLAUDE.md e ignora
graphify-out/, che si rigenera.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs/GRAFO.md

@@ -0,0 +1,64 @@
+# Grafo della conoscenza (graphify)
+
+Mappa interrogabile del repository: codice, migrazioni SQL e documentazione, con le relazioni
+tra simboli, file e concetti. Serve a orientarsi in fretta («cosa chiama questa funzione?»,
+«quale decisione tocca questa tabella?»). **Non è fonte di verità**: se grafo e codice
+divergono, vale il codice.
+
+## Cosa c'è e dove
+
+Il grafo vive in `graphify-out/`, **locale e non versionato** (è in `.gitignore`): si rigenera,
+non si committa. Contiene `graph.json` (dati), `graph.html` (visualizzazione, si apre nel
+browser) e `GRAPH_REPORT.md` (nodi centrali, community, domande suggerite).
+
+| Parte            | Come è costruita                                | Costo                 |
+| ---------------- | ----------------------------------------------- | --------------------- |
+| Codice e SQL     | Analisi dell'AST, senza LLM                     | Gratis, secondi       |
+| Documentazione   | Estrazione semantica con agenti (`docs/`, ...)  | Token, qualche minuto |
+| Immagini e icone | Escluse di proposito: non dicono nulla di utile | Non estratte          |
+
+## Installazione
+
+Una tantum, per ogni sviluppatore. L'extra `[sql]` serve per le migrazioni in
+`supabase/migrations/`: senza, i 53+ file `.sql` non entrano nel grafo.
+
+```bash
+uv tool install "graphifyy[sql]"
+```
+
+La skill `/graphify` per Claude Code è già nel repo in `.claude/skills/graphify/`.
+Cursor e Codex non la leggono: lì si usa la CLI.
+
+## Uso quotidiano
+
+```bash
+graphify query "chi scrive in eventi_app?"   # domanda in linguaggio naturale
+graphify explain "Squadra"                   # un nodo e i suoi vicini
+graphify path "GestioneEventi" "eventi_app"  # percorso più breve tra due nodi
+```
+
+In Claude Code: `/graphify query "..."`, oppure leggere `graphify-out/GRAPH_REPORT.md`.
+
+## Quando rigenerarlo
+
+| Situazione                        | Comando                                                | Costo                         |
+| --------------------------------- | ------------------------------------------------------ | ----------------------------- |
+| Hai cambiato codice o migrazioni  | `graphify update .`                                    | Gratis                        |
+| Hai cambiato documenti in `docs/` | `/graphify . --update` (skill)                         | Token, solo i file modificati |
+| Grafo assente (clone nuovo)       | `graphify update .`, poi la riga sopra per i documenti | Come sopra                    |
+
+Il grafo riporta il commit da cui è stato costruito (`GRAPH_REPORT.md`, sezione «Graph
+Freshness»): confrontalo con `git rev-parse HEAD` per sapere se è vecchio.
+
+Attenzione: `graphify update .` da solo ricostruisce i `.md` come semplici strutture (titoli e
+sezioni) e **sovrascrive** i nodi semantici dei documenti. Dopo averlo lanciato su un grafo
+già completo, rilancia `/graphify . --update` per ripristinarli: la cache evita di pagare di
+nuovo i file invariati.
+
+## Limiti noti
+
+- Il report segnala archi su nodi inesistenti e archi multipli collassati, soprattutto nelle
+  migrazioni SQL e nei template GitHub: il grafo può essere incompleto in quei punti.
+- Un file letto solo in parte viene riprovato al giro successivo (`--update`).
+- `src/styles.css` e i file di configurazione (Dockerfile, `.toml`, `.lock`, `.env.example`)
+  non sono nel grafo. `.env.example` non va mai incluso.

docs/README.md

@@ -17,6 +17,7 @@ ancora e va **prima documentata** (vedi [DD-002](decisions/DD-002.md)).
 | [GLOSSARIO.md](GLOSSARIO.md)               | Cosa significano i termini del dominio (slot, rosa, convocati, CSI, pagelle…)                                       |
 | [OPERATIONS.md](OPERATIONS.md)             | Ambienti, variabili d'ambiente, migration, rilascio e allestimento di un ambiente nuovo (login Google, primo admin) |
 | [WORKER_EMAIL.md](WORKER_EMAIL.md)         | Come si installa, si gestisce e si diagnostica il worker che invia le notifiche per email                           |
+| [GRAFO.md](GRAFO.md)                       | Come orientarsi nel codice con il grafo graphify: uso, rigenerazione, limiti                                        |
 | [CHANGELOG.md](CHANGELOG.md)               | Cosa è cambiato e quando                                                                                            |
 | [archive/](archive/README.md)              | Materiale storico non più in uso: non è fonte di verità                                                             |
 | [modules/](modules/)                       | Specifica funzionale di ogni modulo, una per file                                                                   |