From 1771936ab9f3f6e0648e3cc0d03bf1fc4253bf4c Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Wed, 15 Jul 2026 18:10:07 +0200 Subject: [PATCH] Aggiunge README con guida rapida per il caricamento dei documenti Include una sezione dedicata al flusso di import degli output MinerU (cosa tenere/scartare, come strutturare raw/sources). --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..26694b5 --- /dev/null +++ b/README.md @@ -0,0 +1,58 @@ +# 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//`: + +**Tieni:** +- `.md` — il testo +- `_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/.jpg`) +- `_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//` +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).