ingegneria-meccanica/CLAUDE.md

# 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/<slug-documento>/`, dove `<slug-documento>` è 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 `<nome>/auto/`) contiene molti file: solo una parte va copiata in `raw/sources/<slug>/`.

**Tenere:**
- `<nome>.md` — testo
- `<nome>_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/<hash>.jpg`
- `<nome>_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/<slug-kebab-case>/` (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/<hash>.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`).