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>

.gitignore

@@ -51,3 +51,6 @@ backups/*
 !backups/README.md
 # Automazioni operative locali (backup cifrati, playbook con dati sensibili)
 ops/
+
+# Grafo graphify: locale, si rigenera (docs/GRAFO.md)
+graphify-out/

AGENTS.md

@@ -18,7 +18,11 @@ usabile dallo smartphone anche da chi non è pratico.
    [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) vanno lette prima di toccare codice o schema.
 2. Verifica lo stato attuale del repository: commit recenti, modifiche non committate, lavoro
    introdotto da altri collaboratori o da altri assistenti.
-3. Non presumere che il progetto sia come l'hai lasciato nell'ultima sessione: la fonte di
+3. Se esiste `graphify-out/` (locale, non versionato), usalo per orientarti prima di cercare a
+   tappeto: `graphify query "..."` e `GRAPH_REPORT.md`. Non è fonte di verità e può essere
+   vecchio: controlla il commit riportato nel report e, se serve, rigeneralo
+   (vedi [docs/GRAFO.md](docs/GRAFO.md)).
+4. Non presumere che il progetto sia come l'hai lasciato nell'ultima sessione: la fonte di
    verità è il repository, non la cronologia della conversazione.
 
 Non implementare funzionalità non documentate: prima si documenta

CLAUDE.md

@@ -3,7 +3,8 @@
 Le regole di progetto stanno in @AGENTS.md: valgono integralmente e non sono ripetute qui —
 compresi i comandi (`npm run dev/lint/test`, supabase) e la checklist «Fine lavoro» da eseguire
 prima di dire che hai finito. La documentazione tecnica è indicizzata in
-[docs/README.md](docs/README.md); l'architettura in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+[docs/README.md](docs/README.md); l'architettura in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md);
+il grafo del repository (graphify) in [docs/GRAFO.md](docs/GRAFO.md).
 
 **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.

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                                                                   |