docs: README dettagliato MinerU + CLAUDE.md aggiornato per pipeline Stage 1+2

README.md: sezione MinerU espansa con requisiti di sistema, installazione
(pip/conda/Docker), CLI completo con tutti i flag, tabella comparativa
backend (pipeline/hybrid-auto-engine/vlm-auto-engine), configurazione
avanzata, struttura output e limitazioni note.

CLAUDE.md: aggiornato diagramma pipeline, input RICHIESTO/RACCOMANDATO,
comandi con --force e --skip-optimize, architettura chunker/md_optimizer.

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

CLAUDE.md

@@ -19,11 +19,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 Pipeline RAG su documenti accademici. La conversione PDF → Markdown è delegata a **MinerU** (tool esterno). Questo repository si occupa solo di: pulizia Markdown, chunking, vettorizzazione e retrieval/generazione.
 
 ```
-MinerU (esterno) → sources/<stem>/auto/<stem>.md
+MinerU (esterno) → sources/<stem>/auto/
                         ↓
-                   /prepare-md  (pulizia)
-                        ↓
-                   chunker.py   (chunking adattivo)
+                   chunker.py   (Stage 1: _clean.md  +  Stage 2: chunks.json)
                         ↓
                    ingest.py    (embedding → ChromaDB)
                         ↓
@@ -36,7 +34,7 @@ MinerU (esterno) → sources/<stem>/auto/<stem>.md
 
 - **Venv:** Usa `.venv/bin/python`. Mai `pip`/`python` di sistema.
 - **Niente LLM nella pipeline:** chunking e pulizia devono essere rule-based e riproducibili.
-- **Input immutabile:** Non modificare mai `sources/<stem>/auto/<stem>.md` direttamente — usare `/prepare-md` che lavora su una copia.
+- **Input immutabile:** Non modificare mai i file originali in `sources/<stem>/auto/`. Il `chunker.py` scrive solo `_clean.md` (prodotto derivato) nella stessa cartella e `chunks.json` in `chunks/<stem>/`.
 
 ---
 
@@ -45,9 +43,10 @@ MinerU (esterno) → sources/<stem>/auto/<stem>.md
 MinerU produce una cartella per ogni documento. Posizionarla in `sources/`:
 
 ```
-sources/<stem>/auto/<stem>.md                    ← Markdown principale (input pipeline)
-sources/<stem>/auto/<stem>_content_list_v2.json  ← struttura ricca (chunk, bbox, tipo)
-sources/<stem>/auto/<stem>_middle.json           ← dati intermedi di layout
+sources/<stem>/auto/<stem>_content_list_v2.json  ← struttura ricca (tipo, livello, bbox)  [RICHIESTO]
+sources/<stem>/auto/<stem>_model.json            ← label di layout (doc_title, abstract…) [RACCOMANDATO]
+sources/<stem>/auto/<stem>.md                    ← Markdown grezzo (non usato dalla pipeline)
+sources/<stem>/auto/<stem>_middle.json           ← dati intermedi (non usato)
 sources/<stem>/auto/images/                      ← immagini estratte
 ```
 
@@ -61,9 +60,18 @@ sources/<stem>/auto/images/                      ← immagini estratte
 # Setup
 python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
 
-# Chunking (legge sources/<stem>/auto/<stem>.md)
+# Chunking unificato: Stage 1 (_clean.md) + Stage 2 (chunks.json)
 .venv/bin/python chunks/chunker.py --stem <stem>
-.venv/bin/python chunks/chunker.py                    # tutti gli stem
+.venv/bin/python chunks/chunker.py                         # tutti gli stem in sources/
+.venv/bin/python chunks/chunker.py --stem <stem> --force   # rigenera tutto
+.venv/bin/python chunks/chunker.py --stem <stem> --skip-optimize  # salta Stage 1
+
+# Solo Stage 1 (se serve rigenerare solo il _clean.md)
+.venv/bin/python chunks/md_optimizer.py --stem <stem> --force
+
+# Verifica e correzione chunk
+.venv/bin/python chunks/verify_chunks.py --stem <stem>
+.venv/bin/python chunks/fix_chunks.py --stem <stem>
 
 # Vettorizzazione (richiede Ollama attivo)
 .venv/bin/python ingestion/ingest.py --stem <stem>
@@ -71,7 +79,7 @@ python -m venv .venv && source .venv/bin/activate && pip install -r requirements
 
 # RAG interattivo
 .venv/bin/python rag.py --stem <stem>
-.venv/bin/python retrieve.py --stem <stem>            # retrieval puro, senza LLM
+.venv/bin/python retrieve.py --stem <stem>                 # retrieval puro, senza LLM
 ```
 
 ---
@@ -82,10 +90,13 @@ python -m venv .venv && source .venv/bin/activate && pip install -r requirements
 
 | File | Responsabilità |
 |------|---------------|
-| `chunker.py` | Chunking adattivo del Markdown; legge `structure_profile.json` per scegliere la strategia |
-| `config.py` | Parametri: `TARGET_CHARS`, `OVERLAP_SENTENCES`, `CHUNK_TOLERANCE`, `STRATEGY_OVERRIDES` |
-| `verify_chunks.py` | Verifica qualità chunk (copertura, lunghezze, overlap) |
-| `fix_chunks.py` | Correzioni post-chunking |
+| `chunker.py` | Entry point unificato: chiama `md_optimizer` (Stage 1) poi esegue il chunking (Stage 2) |
+| `md_optimizer.py` | Modulo Stage 1: `_content_list_v2.json` + `_model.json` → `<stem>_clean.md` |
+| `config.py` | Tutti i parametri: `MAX_CHARS`, `MIN_CHARS`, `OVERLAP_SENTENCES`, `FRONTMATTER_HEADINGS`, `SOMMARIO_PATTERNS`, label sets model.json |
+| `verify_chunks.py` | Verifica qualità chunk (lunghezze, frasi spezzate, prefissi) |
+| `fix_chunks.py` | Correzioni post-chunking (merge incompleti, split lunghi) |
+
+`md_optimizer.py` è generico rispetto al documento: usa le strutture comuni di tutti gli output MinerU (`_content_list_v2.json` e `_model.json`) senza dipendere da pattern testuali lingua-specifici. I parametri documento-specifici (es. `FRONTMATTER_HEADINGS` per documenti italiani) sono in `config.py`.
 
 Output: `chunks/<stem>/chunks.json`, `chunks/<stem>/meta.json`, `chunks/<stem>/report.json`