# Ingegneria Meccanica — Wiki

Vault Obsidian gestito con il pattern **llm-wiki**: i documenti grezzi vanno in `raw/`, un agente (Claude Code o Codex) li legge e costruisce/aggiorna le pagine in `wiki/`. Le regole operative per l'agente sono in [CLAUDE.md](./CLAUDE.md) (e [AGENTS.md](./AGENTS.md) per Codex); questo README è la guida rapida per l'umano che aggiunge materiale.

## Struttura

```
purpose.md        # ambito e domande guida del progetto
schema.md          # convenzioni delle pagine wiki (tipi, frontmatter, naming)
raw/
├── sources/        # un documento = una sottocartella
└── assets/         # immagini/scan sciolte, non legate a un documento
wiki/
├── entities/       # componenti, materiali, norme, produttori
├── concepts/       # fenomeni, metodi di calcolo, teorie
├── sources/         # una pagina di sintesi per ogni documento in raw/sources
├── queries/        # domande aperte
├── comparisons/    # confronti tra entità/concetti
├── synthesis/       # sintesi trasversali
├── index.md         # indice di tutte le pagine
├── log.md            # log cronologico delle sessioni di ingest
└── overview.md        # stato attuale del progetto (aggiornato a checkpoint, non ad ogni ingest)
```

## Come caricare un nuovo documento

1. Crea una cartella in `raw/sources/` con uno slug kebab-case che identifica il documento (es. `iso-6336-gear-rating`, `catalogo-skf-cuscinetti-2024` — non serve rispecchiare il nome del file originale).
2. Mettici dentro il documento (PDF, markdown, testo — quello che hai).
3. Se hai solo immagini sciolte non legate a un documento specifico (foto, schemi disegnati a mano), vanno in `raw/assets/`, non in `raw/sources/`.
4. Apri il progetto con Claude Code o Codex e chiedi di fare l'ingest del nuovo documento (es. "ingerisci il documento in raw/sources/iso-6336-gear-rating"). L'agente crea/aggiorna le pagine in `wiki/` seguendo `schema.md`.

Non modificare mai un file dentro `raw/` dopo averlo caricato: è la fonte immutabile. Se un dato risulta sbagliato, la correzione va fatta nella pagina wiki, non nel raw.

## Documenti processati con MinerU

Se un PDF è stato passato attraverso **MinerU** (in particolare la modalità **pipeline**, non VLM), l'output è una cartella con molti file — solo una parte va copiata in `raw/sources/<slug>/`:

**Tieni:**
- `<nome>.md` — il testo
- `<nome>_content_list.json` (uno solo tra questo e la `_v2`) — blocchi con numero di pagina, utile per citare le fonti
- `images/` — l'intera cartella, così com'è: il `.md` la referenzia con path relativi (`images/<hash>.jpg`)
- `<nome>_origin.pdf` — facoltativo, tienilo solo se vuoi poter riaprire il PDF originale per verificare a occhio formule/tabelle dubbie (spesso pesa decine di MB)

**Scarta** (file di debug interni a MinerU, senza valore per la wiki, spesso centinaia di MB in totale):
- `_layout.pdf`, `_span.pdf`
- `_middle.json`
- `_model.json`

**Passaggi pratici:**
1. Crea `raw/sources/<slug-kebab-case>/`
2. Copia dentro solo i file "da tenere" sopra, eliminando l'eventuale cartella intermedia `auto/`
3. Puoi rinominare liberamente la cartella-slug; **non serve e non conviene** rinominare i file interni o `images/` — i riferimenti sono path relativi e restano validi finché la struttura interna non cambia

L'estrazione in modalità pipeline può contenere errori (ordine di lettura su layout multi-colonna, formule OCR imprecise, tabelle disallineate): l'agente ne è a conoscenza (vedi CLAUDE.md) e segnala i punti dubbi invece di darli per certi, ma vale la pena tenere sotto mano il PDF originale per i casi più critici.

## Dettagli

Per le convenzioni di frontmatter/naming delle pagine vedi [schema.md](./schema.md); per l'ambito del progetto vedi [purpose.md](./purpose.md); per il workflow completo dell'agente vedi [CLAUDE.md](./CLAUDE.md).