cyber-tesi/CLAUDE.md

# CLAUDE.md — Schema della LLM Wiki

Schema: struttura, convenzioni, workflow. Leggilo all'inizio di ogni sessione. Utente e LLM lo fanno evolvere insieme; ogni modifica va registrata in `log.md`.

## Ruoli
- **Utente**: sceglie cosa ingerire, pone le domande, decide cosa conta.
- **LLM**: scrive e mantiene la wiki (pagine, link, indice, log, coerenza). L'utente non modifica `wiki/` a mano.
- Lingua: **italiano**. Titoli di fonti e termini tecnici restano nella lingua originale (l'Abstract della tesi è in inglese).

## Dominio
Tesi magistrale in Chimica Industriale (Università di Bologna, Dipartimento "Toso Montanari"), a.a. 2025-2026: **"Sintesi e caratterizzazione di copolimeri bottle brush foto-elettro attivi"**. Candidata: Aurora Luzi. Relatore: Dr. Stefano Scurti.

- **Tema:** semiconduttori polimerici emissivi π-coniugati con architettura bottle brush: scheletro DPP-3HT (polimerizzazione ossidativa con Fe(III)) e catene laterali di PCL ottenute per ROP dell'ε-caprolattone da gruppi OH pendenti.
- **Research question** (dall'Abstract e dal cap. 2): una architettura bottle brush può superare l'ACQ (Aggregation-Caused Quenching) allo stato solido, mantenendo l'integrità elettrochimica del core DPP?
- Risultati dichiarati nell'Abstract: il PCL agisce da spaziatore sterico e mantiene emissione nel rosso allo stato solido; il bandgap elettrochimico cresce linearmente con la % di DPP incorporato.

## Fonti (`raw/`, SOLA LETTURA — mai modificare, rinominare o cancellare)
| Percorso | Contenuto |
|---|---|
| `raw/tesi.md` | Sorgente canonico (1432 righe; aggiornato il 2026-10-13 alla nuova versione `tesi_new.docx`). Cap. 1 Introduzione (r.66), 2 Scopo (r.545), 3 Procedure sperimentali (r.562), 4 Discussione dei risultati (r.714), 5 Conclusioni (r.1298); bibliografia in fondo (r.1312) |
| `raw/immagini/` | 80 file figura (nomi = hash) |
| `raw/immagini.json` | Catalogo di 79 figure logiche: pannelli, didascalia stampata e generata, testo visibile, composti, concetti, contesto, qualità |
| `raw/bibliografia.json` | 60 riferimenti parsati con righe e sezioni di citazione; `text` è la fonte di verità, gli altri campi sono euristici |
| `raw/fonti/NN-cognome-anno.md` | Una scheda per riferimento (citazione verificata, DOI, abstract, frasi della tesi in cui è citato) |

I numeri di riga (`md_line`, `cited_in_md_lines`…) riferiscono `raw/tesi.md` e sono stabili perché `raw/` è immutabile: sono il localizzatore standard.

Convenzioni di `tesi.md`: decimali con la virgola; codici composto con il punto (`3.1b`); formule in `$...$`; citazioni `<sup>[N](#ref-N)</sup>`; apici/pedici in HTML. Anchor `#ref-N` e `#_TocNNN` non funzionano in Obsidian: nella wiki si traducono in wikilink.

## Architettura
```
CLAUDE.md   index.md   log.md
raw/                      immutabile (vedi sopra)
scripts/gen_figures.py    genera wiki/figures/ da raw/immagini.json
scripts/gen_bibliografia.py  genera wiki/bibliografia.md da raw/bibliografia.json
scripts/lint.py          controlli meccanici (link, orfane, frontmatter, numeri non in tesi.md)
wiki/
  overview.md             sintesi evolutiva, research question, risultati
  tesi.md                 mappa capitolo/sezione → pagine wiki (unica pagina "source" della tesi)
  dati.md                 indice «grandezza → pagina» con intervalli di valori (aggiornarlo a ogni nuova tabella)
  bibliografia.md         i 60 riferimenti (GENERATA dallo script), con link alle schede raw/fonti/
  concepts/               meccanismi, ROP, ACQ, bottle brush, π-stacking, ciclovoltammetria…
  compounds/              un file per composto numerato (composto-32.md) o polimero/campione
  techniques/             NMR, FT-IR, GPC, UV-Vis, fluorescenza, DSC, CV: condizioni usate nella tesi
  figures/                note GENERATE dallo script (una per figura, non modificare a mano)
  analyses/               query salvate; difetti-noti.md
```
Niente pagine `source` per capitolo (duplicherebbero la tesi) e niente `entities/` generica.

## Convenzioni pagine
- File `kebab-case.md`. Composti: `composto-32.md` con `aliases` (nome, codice come `3.1b`). Figure: `fig-026.md`.
- Link: wikilink `[[nome-file]]`, `[[nome|testo]]` per alias. Riferimenti bibliografici: `[[01-bao-2020|1]]` (link alla scheda in `raw/fonti/`; usare il numero della tesi).
- Frontmatter YAML:
```yaml
---
title: Titolo leggibile
type: concept | compound | technique | analysis | overview | figure
tags: [tag1, tag2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
tesi_loc: "§4.2 r.812-840"      # dove la tesi sostiene il contenuto
refs: [3, 12]                   # numeri della bibliografia citati (opzionale)
figures: ["fig-026"]            # opzionale
status: draft | stable
---
```
- **Ogni affermazione non banale cita la posizione**: `(§4.2, Fig. 27, r.812)` e, se serve, il riferimento `[[01-bao-2020|1]]`. Niente affermazioni non riconducibili a `raw/`.
- Inferenze dell'LLM marcate _(inferenza)_. Se non sai, dillo; non inventare fonti o dati.
- Ogni pagina termina con `## Collegamenti`. Nessuna pagina orfana. Crea una pagina concetto solo se serve a ≥2 sezioni/figure o è centrale.

## Regole sui dati scientifici
- **Copia alla lettera**: valori, unità, condizioni (T, P, solvente, tempo, carico, resa/conversione), formule LaTeX, formule chimiche, nomi di composti e sigle (DPP, 3HT, ROP, PCL, ACQ, CV, GPC…) restano come nella tesi. Non tradurre, riassumere, convertire o arrotondare dati sperimentali. Decimali con la virgola come in `tesi.md`; eccezioni: Abstract, dati NMR, liste, DOI.
- **Procedure sperimentali (cap. 3):** non riscriverle; la wiki rimanda al paragrafo (`tesi_loc`) e riporta solo i dati necessari alla pagina.
- **Sospetti errori di estrazione** (formula, tabella, valore): confronta con la fonte originale se disponibile, **segnala e non correggere**. Valori da condizioni diverse non vanno confrontati senza dirlo.
- **Sicurezza:** niente procedure di sintesi pericolose oltre quanto riporta la tesi; riporta i pericoli noti dei reagenti se citati.

## Figure
- `wiki/figures/*.md` e `wiki/bibliografia.md` sono **derivate**: `python scripts/gen_figures.py` le rigenera da `raw/immagini.json`, riportando ogni campo (didascalie, descrizioni e testo visibile per pannello, composti, concetti, contesto, righe di citazione, note di revisione) senza riassumere. Eccezione alla regola "solo l'LLM scrive in `wiki/`"; non modificarle a mano, correggi `raw/immagini.json` solo se l'utente lo chiede e poi rigenera.
- **Attendibilità:** solo `caption_printed` è testo della tesi. Descrizioni, `visible_text` e didascalia generata derivano dall'immagine e non sono verificati: valori letti da grafici o schemi (rese, picchi, potenziali) vanno confermati sull'immagine/tesi prima di riusarli.
- Le pagine concept/compound/technique richiamano le figure con `[[fig-026]]` o con l'embed `![[immagini/<file>]]` (da `panels[].embed`). Le figure con `flags` o `review_notes` (Figure 26, 27, 29, 58, 63, 66, 67, 69 hanno discrepanze didascalia/testo) vanno citate con l'avvertenza.
- `compounds` nel catalogo sono numeri della tesi; `concepts` sono slug candidati, non nomi definitivi: crea la pagina solo se la regola dei ≥2 usi è soddisfatta.

## Regole di organizzazione dei dati
- Pagine sopra ~1.500 parole vanno spezzate per argomento (es. `ciclovoltammetria` = metodo; i risultati in `cv-risultati`).
- Una tabella o un dato sta in **una sola pagina**: quella dove la tesi lo discute (per es. Tab. 5 in `dpp-2`, Tab. 14-15 in `cv-risultati`). Le altre pagine rimandano con wikilink; fanno eccezione i riepiloghi comparativi (es. in `uv-vis-fluorescenza`), che citano la tabella di origine.
- Le pagine riorganizzano per argomento, non per capitolo, senza eliminare informazioni: procedure con quantità in tabella, condizioni, assegnazioni e ragionamenti della tesi restano, con `tesi_loc` e righe.
- Composti sperimentali: `dpp-1`, `dpp-2`, `copolimeri-3a-3b-3c`, `bottle-brush-3-x`. La numerazione dei composti del cap. 1 (1-48) è un'altra: non confonderle.

## Difetti noti della tesi
Raccolti in `wiki/analyses/difetti-noti.md` (una sola pagina; le altre rimandano lì): bibliografia con voce 44 duplicata della 1; voci 20, 22, 36, 54 incomplete; DOI errati nelle voci 47, 48 (corretto 10.1080/15583720802231833) e 49; voci 47, 49, 54 non identificabili; segnaposto "paragrafo XX (XX)" in 4.4.4 (risolto nella versione del 2026-10-13); discrepanze figura/testo sopra elencate.

## Workflow

### Ingest (per capitolo, non per fonte)
Ordine: Abstract/Introduzione/Scopo (concepts, research question) → Procedure sperimentali (compounds, techniques) → Discussione (dati, overview) → Conclusioni → bibliografia.
1. Leggi per intero il capitolo/sezione in `raw/tesi.md` e le figure collegate (`sections[].figure_ids`).
2. Dopo il primo capitolo, discuti 3–5 takeaway e chiedi cosa enfatizzare; poi procedi a blocchi senza chiedere ogni volta.
3. Crea/aggiorna `concepts/`, `compounds/`, `techniques/`; segnala discrepanze in `analyses/difetti-noti.md`.
4. Aggiorna `wiki/tesi.md` (mappa), `overview.md` se la sintesi cambia, `bibliografia.md` se tocchi riferimenti.
5. Rigenera le figure se `raw/immagini.json` è cambiato.
6. Aggiorna `index.md` e appendi a `log.md`.

### Query
Leggi `index.md` e le pagine rilevanti (non rileggere `raw/` se la wiki basta); rispondi in italiano con citazioni `[[...]]` e `tesi_loc`; proponi di salvare in `analyses/` le risposte durevoli; log `query`.

### Lint (su richiesta o ogni ~10 ingest)
Esegui `python scripts/lint.py` (link rotti, pagine orfane, frontmatter, coerenza `figures`/`refs` con il corpo, numeri non presenti in `raw/tesi.md`, slug concetto candidati). Poi controlli semantici a mano: contraddizioni, valori che non tornano con `raw/tesi.md`, pagine oltre ~1.500 parole da spezzare. Riporta; le correzioni meccaniche (spaziatura, frontmatter) si applicano subito, il resto dopo conferma. Log `lint`.

## index.md e log.md
- `index.md`: catalogo per categoria (Overview, Tesi e bibliografia, Concetti, Composti, Tecniche, Figure, Analisi), voci `- [[pagina]] — riga di sintesi`, ordine alfabetico, conteggi aggiornati. Le 79 figure non si elencano una per una: una riga con link alla cartella e il conteggio per tipo.
- `log.md`: append-only, mai riscrivere le voci vecchie. Prefisso `## [YYYY-MM-DD] tipo | titolo` con tipo ∈ `setup, ingest, query, lint, schema`. Parsing: `grep "^## \[" log.md | tail -5`.

## Regole d'oro
- Mai modificare `raw/`. Mai inventare dati, fonti o citazioni.
- Prima di cancellare o rinominare pagine chiedi conferma e aggiorna i link in entrata.
- Cambi allo schema: proponi, attendi ok, poi registra in `log.md` (tipo `schema`).
- Lavoro proporzionato: nessuna pagina "per dopo".