Aggiunge tesi-narrate, regola di completezza delle risposte e diagrammi del README piu leggibili

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

README.md

@@ -22,14 +22,27 @@ La tesi è **«Sintesi e caratterizzazione di copolimeri bottle brush foto-elett
 
 ## Architettura
 
+_Il diagramma mostra i tre ingredienti del sistema e come arrivano alla risposta: le fonti (blu) vengono compilate nella wiki (verde); l'agente (rosa) legge la wiki e segue le regole (giallo) per produrre la risposta._
+
 ```mermaid
 flowchart LR
-    R["raw/<br/>fonti immutabili"] --> W["wiki/<br/>pagine collegate"]
-    W --> A["Agente LLM"]
-    S["CLAUDE.md + skill<br/>regole di consultazione"] --> A
-    A --> U["Risposta citata<br/>con figure"]
+    R["raw/<br/>fonti immutabili"] -->|"compilate in"| W["wiki/<br/>pagine collegate"]
+    W -->|"consultata da"| A["Agente LLM"]
+    S["CLAUDE.md + skill<br/>regole di consultazione"] -->|"guidano"| A
+    A -->|"produce"| U["Risposta citata<br/>con figure"]
+    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
+    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
+    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
+    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
+    classDef script fill:#e5e7eb,stroke:#374151,color:#111
+    class R fonte
+    class W wiki
+    class S regole
+    class A,U agente
 ```
 
+**Legenda colori (valida per tutti i diagrammi):** 🟦 fonti in `raw/` · 🟩 wiki in `wiki/` · 🟨 regole e skill · 🟪 agente e risposta · ⬜ script. Le frecce con etichetta indicano l'azione che collega due blocchi.
+
 | Livello | Cartella | Ruolo |
 |---|---|---|
 | Fonti | `raw/` | Tesi, riassunto, immagini, catalogo figure, bibliografia. Sola lettura. |
@@ -39,7 +52,7 @@ flowchart LR
 ```
 CLAUDE.md                schema di consultazione (regole RAG)
 AGENTS.md  GEMINI.md     puntatori a CLAUDE.md per Codex, Antigravity, Gemini CLI
-.agents/skills/          tesi-query, tesi-figure, tesi-dati, tesi-fonti
+.agents/skills/          tesi-query, tesi-figure, tesi-dati, tesi-fonti, tesi-narrate
 .claude/skills           link simbolico a .agents/skills (per Claude Code)
 index.md   log.md        catalogo delle pagine e registro delle modifiche
 raw/                     tesi.md, immagini/, immagini.json, bibliografia.json, fonti/, riassunto
@@ -57,20 +70,33 @@ scripts/                 gen_figures.py, gen_bibliografia.py, lint.py
    - «Confronta il band gap elettrochimico dei campioni bottle brush e mostrami i voltammogrammi.»
    - «Come si ottiene lo scheletro DPP-3HT? Mostrami lo schema di sintesi.»
    - «Chi ha proposto il meccanismo di formazione del DPP citato nella tesi?»
-3. Puoi invocare una skill per nome: `tesi-query` (domande generali), `tesi-figure` (immagini), `tesi-dati` (valori e tabelle esatti), `tesi-fonti` (bibliografia).
+3. Puoi invocare una skill per nome: `tesi-query` (domande generali), `tesi-figure` (immagini), `tesi-dati` (valori e tabelle esatti), `tesi-fonti` (bibliografia), `tesi-narrate` (briefing, spiegazione o lezione citati).
 
 La wiki è usata **in sola lettura**: l'agente non la modifica salvo richiesta esplicita. Lo schema di manutenzione (ingest, riallineamento, lint) resta nella cronologia git di `CLAUDE.md`, fino al commit `eb672df`.
 
 ## Come è costruito
 
+_Il diagramma segue il materiale dal documento originale alla wiki, in quattro passi da sinistra a destra._
+
 ```mermaid
 flowchart LR
-    T["Tesi<br/>(docx / PDF)"] --> M["MinerU"]
-    M --> R["raw/<br/>testo, immagini,<br/>catalogo, bibliografia"]
-    R --> L["Ingest LLM<br/>per capitolo"]
-    L --> W["wiki/"]
+    T["1 Tesi<br/>docx / PDF"] -->|"estrazione"| M["2 MinerU"]
+    M -->|"Markdown + figure"| R["3 raw/<br/>testo, immagini,<br/>catalogo, bibliografia"]
+    R -->|"lettura per capitolo"| L["4 Ingest LLM"]
+    L -->|"scrive"| W["wiki/<br/>pagine per argomento"]
+    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
+    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
+    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
+    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
+    classDef script fill:#e5e7eb,stroke:#374151,color:#111
+    class T,R fonte
+    class M script
+    class L agente
+    class W wiki
 ```
 
+1. **Tesi:** il documento di partenza. 2. **MinerU:** lo converte in Markdown e ritaglia le figure. 3. **`raw/`:** raccoglie il risultato (testo, immagini, catalogo delle figure, bibliografia) e non si modifica più. 4. **Ingest:** un LLM legge `raw/` capitolo per capitolo e scrive la wiki.
+
 - **Estrazione con [MinerU](https://github.com/opendatalab/MinerU).** Strumento open source che converte documenti in Markdown strutturato, con tabelle, formule in LaTeX e figure ritagliate come file immagine. Il suo output è la base di `raw/tesi.md` (1446 righe) e di `raw/immagini/` (file con nome = hash). Il testo è stato poi riallineato alla versione Word della tesi con le convenzioni dello schema di manutenzione. _I parametri usati non sono registrati nel repository._
 - **Catalogo delle figure e bibliografia.** Un catalogo (`raw/immagini.json`) e 63 riferimenti (`raw/bibliografia.json`, schede in `raw/fonti/` con citazione verificata, DOI, abstract e frasi della tesi che li citano).
 - **Compilazione della wiki.** Un LLM legge la tesi capitolo per capitolo e scrive le pagine organizzate **per argomento**, con il localizzatore `tesi_loc` (sezione e righe di `raw/tesi.md`) in ogni pagina.
@@ -80,14 +106,26 @@ flowchart LR
 
 Schemi di sintesi, strutture, spettri e voltammogrammi non si trovano cercando parole, quindi ogni figura è stata resa ricercabile e collegata al testo.
 
+_Il diagramma mostra come i file immagine diventano schede ricercabili: due ingressi (le immagini e il testo della tesi) confluiscono nel catalogo, da cui uno script genera le schede._
+
 ```mermaid
 flowchart LR
-    F["File immagine<br/>da MinerU"] --> C["Catalogo<br/>immagini.json"]
-    T["raw/tesi.md<br/>righe e didascalie"] --> C
-    C --> G["gen_figures.py"]
-    G --> N["wiki/figures/<br/>una scheda per figura"]
+    F["1a File immagine<br/>da MinerU"] -->|"descritti"| C["2 Catalogo<br/>immagini.json"]
+    T["1b raw/tesi.md<br/>righe e didascalie"] -->|"collegate"| C
+    C -->|"letto da"| G["3 gen_figures.py"]
+    G -->|"genera"| N["4 wiki/figures/<br/>una scheda per figura"]
+    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
+    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
+    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
+    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
+    classDef script fill:#e5e7eb,stroke:#374151,color:#111
+    class F,T,C fonte
+    class G script
+    class N wiki
 ```
 
+1. **Ingressi:** i file immagine (1a) e il testo della tesi con posizione e didascalia di ogni figura (1b). 2. **Catalogo:** unisce descrizione, testo visibile, composti, concetti e righe di citazione per ogni figura. 3. **Script:** legge il catalogo. 4. **Schede:** una per figura, pronta da cercare e da incorporare in Obsidian.
+
 - **Figure logiche.** I file sono raggruppati in 80 figure della tesi e 11 del riassunto (una figura può avere più pannelli, quindi più file: per questo i conteggi di file e figure non coincidono). Id stabile `fig-NNN`, oppure `fig-x-<hash>` per gli schemi di §3.2 senza numero.
 - **Catalogo `raw/immagini.json`.** Per figura: posizione nella tesi, **didascalia stampata**, descrizione e testo visibile per pannello (scritti guardando l'immagine), composti, concetti, parole chiave, tipo (struttura, schema di reazione, meccanismo, spettro, voltammogramma, grafico, foto…), righe che la citano, confidenza e note di revisione.
 - **Revisione.** Una verifica indipendente segnala le discrepanze (es. didascalia che non descrive l'immagine: Fig. 26, 27, 29, 58, 66, 67, 69); sono segnalate, non corrette. Dopo ogni nuova versione della tesi le immagini sono state confrontate con il Word e quelle vecchie sostituite.
@@ -99,18 +137,38 @@ Solo la didascalia stampata è testo della tesi; il resto deriva dall'immagine e
 
 ## Come risponde a una domanda
 
+_Il diagramma va letto dall'alto in basso: l'agente prima cerca e legge, poi verifica, poi (solo se serve) guarda le figure, infine scrive._
+
 ```mermaid
 flowchart TD
-    Q["Domanda"] --> N["1 Naviga: indice, glossario,<br/>dati, campioni"]
+    Q["Domanda"] --> N["1 Naviga<br/>indice, glossario, dati, campioni"]
     N --> L["2 Legge le pagine intere<br/>e segue i link"]
-    L --> V["3 Verifica i valori su<br/>raw/tesi.md e i difetti noti"]
+    L --> V["3 Verifica i valori<br/>su raw/tesi.md e difetti noti"]
     V --> F{"Servono figure?"}
-    F -->|sì| G["4 Apre la scheda e<br/>guarda l'immagine"]
-    F -->|no| S
-    G --> S["5 Sintesi: tesi prima,<br/>poi conoscenza del modello"]
+    F -->|"sì"| G["4 Apre la scheda<br/>e guarda l'immagine"]
+    F -->|"no"| S
+    G --> S["5 Sintesi<br/>tesi prima, poi conoscenza del modello"]
     S --> O["Risposta con citazioni"]
+    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
+    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
+    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
+    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
+    classDef script fill:#e5e7eb,stroke:#374151,color:#111
+    class Q,O agente
+    class N,L,S,G agente
+    class V fonte
 ```
 
+Esempio illustrativo (non è una risposta registrata) con la domanda «Perché il PCL evita l'ACQ allo stato solido?»:
+
+| Passo | Cosa fa l'agente |
+|---|---|
+| 1 | Dall'indice individua le pagine su ACQ (`acq-e-stato-solido`), PCL (`rop-pcl`) e bottle brush. |
+| 2 | Le legge per intero e segue i link verso le sottopagine su aggregati H/J e caratterizzazione allo stato solido. |
+| 3 | Controlla i valori su `raw/tesi.md` alle righe indicate da `tesi_loc` e verifica che non ci siano difetti noti. |
+| 4 | Trova la figura pertinente, apre il file in `raw/immagini/` e ne descrive il contenuto. |
+| 5 | Spiega prima ciò che dice la tesi, con citazioni, poi il meccanismo con la conoscenza generale marcata. |
+
 - **Prima la tesi, poi l'integrazione.** I dati vengono dalla wiki e dalla tesi, con posizione (`§4.2, Tab. 14, r.812`) e riferimento bibliografico. La conoscenza generale del modello spiega perché e come, ed è marcata _(conoscenza generale)_; le deduzioni sono _(inferenza)_.
 - **Perimetro.** L'integrazione resta dentro gli argomenti della tesi; fuori perimetro l'agente dice che la tesi non li tratta.
 - **Fedeltà dei dati.** Valori, unità e condizioni copiati alla lettera; valori di condizioni diverse non sono confrontati senza avviso.