# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Cos'è questo repository Non è un progetto software: è un vault Obsidian gestito con il pattern **llm-wiki** (raw → wiki, sorgenti immutabili → pagine sintetizzate), applicato a un dominio di ingegneria meccanica. Non ci sono build/lint/test: l'unico "lavoro" è ingest di documenti grezzi e mantenimento delle pagine wiki. Il layer `.llm-wiki/` (project.json, file-snapshot.json, file-change-queue.json, history/) è gestito da un'app esterna che traccia le modifiche a `purpose.md`, `schema.md` e `wiki/*.md`. Non modificare questi file JSON a mano: si aggiornano da soli quando l'app rileva un cambiamento. ## I tre livelli 1. **`raw/`** — sorgenti immutabili. Non modificare mai un file dentro `raw/` dopo l'ingest: se un dato è sbagliato o mal estratto, la correzione va fatta nella pagina wiki (con nota sul problema), non nel raw. - `raw/sources/` — un sottocartella per documento sorgente (vedi convenzione sotto) - `raw/assets/` — immagini/scan/figure autonome non legate a un output MinerU 2. **`wiki/`** — pagine generate/curate da Claude, organizzate per tipo secondo `schema.md` (`entities/`, `concepts/`, `sources/`, `queries/`, `comparisons/`, `synthesis/`, più `index.md`, `log.md`, `overview.md`). 3. **`purpose.md` / `schema.md`** — regole. `purpose.md` definisce l'ambito e le domande guida del progetto; `schema.md` definisce come sono strutturate le pagine e le convenzioni di naming/frontmatter. Leggi entrambi prima di ogni sessione di ingest. ## Convenzione per `raw/sources/` Ogni documento sorgente vive in `raw/sources//`, dove `` è un kebab-case descrittivo (es. `iso-6336-gear-rating`, `catalogo-skf-cuscinetti-2024`). Dentro: - l'output originale così com'è (markdown + eventuali `images/`, `*_content_list.json`, ecc.) — **non spostare o rinominare i file interni** prodotti dal parser, altrimenti si rompono i link relativi alle immagini - se il documento arriva come PDF puro senza markdown, il PDF stesso Questa cartella è la unità minima di provenienza: ogni claim scritto in `wiki/` deve poter essere ricondotto a uno slug in `raw/sources/`. ## Ingest di un nuovo documento in `raw/` Quando trovi materiale nuovo (o non ancora processato) in `raw/sources/`: 1. **Identifica il tipo di documento**: norma/standard (ISO, UNI, DIN...), datasheet/catalogo produttore, paper/articolo tecnico, capitolo di libro, report interno, manuale. Il tipo guida quali pagine wiki creare (uno standard e un datasheet produttore, per esempio, diventano entity diverse con campi diversi). 2. **Valuta la qualità dell'estrazione** prima di fidarti del testo (vedi sezione MinerU sotto). Se il documento è scansionato o processato in modalità pipeline, non trattare l'OCR come verità assoluta senza controllo. 3. **Estrai entità e concetti**: componenti/materiali/norme/produttori → `wiki/entities/`; fenomeni, metodi di calcolo, teorie → `wiki/concepts/`; il documento stesso → una pagina in `wiki/sources/`. 4. **Segui `schema.md`** per frontmatter, naming e wikilink `[[slug]]`. Non inventare tipi di pagina o convenzioni diverse. 5. **Aggiorna `wiki/index.md`** (nuove voci) e **`wiki/log.md`** (una riga sotto la data odierna che descrive cosa hai ingerito e le pagine toccate). Questi due si aggiornano **ad ogni ingest**, senza bisogno che l'utente lo chieda. 6. Se il documento contraddice materiale già presente, segui la sezione "Contradiction Handling" di `schema.md` (nota sulla pagina concept/entity coinvolta, crea/aggiorna una query page, risolvi con una synthesis solo quando hai abbastanza evidenza). **`wiki/overview.md` non si aggiorna ad ogni ingest** (diventerebbe rumoroso e incoerente riscritto un documento alla volta). Aggiornalo solo a checkpoint più ampi: - l'utente lo chiede esplicitamente ("aggiorna l'overview"), - dopo un batch di più documenti correlati appena ingeriti, - quando emerge un cambiamento reale nella thesis/scope del progetto (vedi `purpose.md`). In quei casi riscrivi `overview.md` come sintesi corrente dello stato della wiki (cosa copre, cosa manca, thesis aggiornata), non come changelog — quello è il ruolo di `log.md`. ## Note su MinerU (backend "pipeline") Molti documenti in `raw/sources/` arrivano pre-processati con **MinerU in modalità pipeline** (parsing layout+OCR tradizionale, non VLM). Questo backend è più leggero ma ha limiti noti di cui tenere conto durante l'ingest: - **Ordine di lettura**: su layout multi-colonna o tabelle complesse l'ordine dei blocchi estratti può essere sbagliato. Se un paragrafo non ha senso nel punto in cui compare, verifica se appartiene a una colonna/sezione diversa prima di citarlo. - **Formule**: convertite in LaTeX via OCR, possono contenere simboli sbagliati (es. confusione tra `l`/`1`/`I`, apici/pedici persi, segni persi). Non riportare una formula tecnica in una pagina wiki senza controllo visivo minimo di plausibilità (unità di misura coerenti, termini noti). - **Tabelle**: rese come markdown/HTML, possono avere celle disallineate o merge di celle perse. Trattare i valori numerici tabellari come "da verificare" se la tabella sembra irregolare. - **Header/footer/note a piè di pagina**: a volte finiscono interfogliati nel corpo del testo. Non trattarli come parte del discorso principale. - **Immagini**: estratte come crop in `images/` e referenziate con path relativi nel `.md` — non toccare i path. Regola pratica: quando una pagina wiki riporta un dato numerico, una formula o una specifica tecnica presa da un documento in pipeline mode, se il punto è dubbio aggiungi una nota inline tipo `(da verificare: OCR pipeline mode, layout tabellare irregolare)` invece di ometterla silenziosamente o presentarla come certa. ### Checklist import da output MinerU grezzo Un output MinerU tipico (cartella `/auto/`) contiene molti file: solo una parte va copiata in `raw/sources//`. **Tenere:** - `.md` — testo - `_content_list.json` (o `_v2`, sceglierne **uno solo**) — blocchi strutturati con `page_idx`/`img_path`, utile per citare pagine - `images/` — cartella intera, referenziata dal `.md` con path relativi tipo `images/.jpg` - `_origin.pdf` — opzionale, solo se vuoi poter riaprire il PDF originale per verificare formule/tabelle dubbie (spesso decine di MB: valuta se vale lo spazio) **Scartare** (debug/intermedi della pipeline, senza valore per la wiki, spesso centinaia di MB in totale): - `_layout.pdf`, `_span.pdf` — PDF di debug con overlay dei bounding box - `_middle.json` — struttura intermedia pre-assemblaggio, ridondante rispetto a `content_list.json` - `_model.json` — output grezzo dei modelli di detection **Passaggi:** 1. Crea `raw/sources//` (lo slug identifica il documento, es. `costruzioni-di-macchine-9` — non serve rispecchiare il nome file originale) 2. Copia dentro solo i file "da tenere", eliminando il livello intermedio `auto/` 3. **Non rinominare** `images/` né i file interni copiati: i path relativi (`images/.jpg`) non dipendono dal nome della cartella padre, quindi rinominare la cartella-slug è sicuro, rinominare i singoli file è inutile e rischioso se non si aggiornano anche i riferimenti nel `.md`/`.json`. ## Regole generali - Non modificare mai i file dentro `raw/`. - Non modificare i file JSON dentro `.llm-wiki/`. - Ogni pagina wiki nuova va aggiunta a `wiki/index.md`; ogni sessione di lavoro va loggata in `wiki/log.md`. - Usa `[[wikilink]]` per collegare le pagine tra loro, non link markdown relativi. - Lingua di default per le pagine wiki: italiano (i nomi di tipo/frontmatter restano in inglese come da `schema.md`, es. `type: entity`).