ingegneria-meccanica/README.md

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 (e 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; per l'ambito del progetto vedi purpose.md; per il workflow completo dell'agente vedi CLAUDE.md.