Commit iniziale

.gitignore

@@ -0,0 +1,23 @@
+# stato locale dell'app llm-wiki (hash/timestamp di sync, non contenuto)
+# la cartella resta nel repo (.gitkeep) cosi' un clone fresco la ritrova gia' pronta
+.llm-wiki/*
+!.llm-wiki/.gitkeep
+
+# preferenze Obsidian locali (workspace, plugin UI, non contenuto della wiki)
+.obsidian/*
+!.obsidian/.gitkeep
+
+# scarti tipici di un output MinerU non ancora ripulito prima dell'ingest
+# (vedi CLAUDE.md: da non copiare in raw/sources/, ma per sicurezza li ignoriamo
+# nel caso finiscano nel repo prima della pulizia)
+*_layout.pdf
+*_span.pdf
+*_middle.json
+*_model.json
+**/auto/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+*.tmp
+~$*

AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+Le istruzioni operative per questo repository sono in [CLAUDE.md](./CLAUDE.md) — leggilo prima di lavorare qui.
+
+Questo file esiste solo perché alcuni agent (es. Codex CLI) cercano `AGENTS.md` invece di `CLAUDE.md`; il contenuto è identico, tenuto in un solo posto per evitare che i due file divergano.

CLAUDE.md

@@ -0,0 +1,84 @@
+# 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`).

purpose.md

@@ -0,0 +1,33 @@
+# Project Purpose
+
+## Goal
+
+<!-- Cosa stai cercando di capire o costruire, in ambito ingegneria meccanica? Es: "Costruire una base di conoscenza su dimensionamento di ingranaggi e cuscinetti per un progetto di riduttore" -->
+
+## Key Questions
+
+<!-- Le domande concrete che guidano l'ingest: cosa deve poter rispondere questa wiki? Es: "Quali norme ISO si applicano al calcolo di durata di un cuscinetto a rulli?" -->
+
+1.
+2.
+3.
+
+## Scope
+
+**In scope:**
+- <!-- es. componenti/norme/materiali/fenomeni specifici da coprire -->
+
+**Out of scope:**
+- <!-- es. argomenti adiacenti volutamente esclusi, per non disperdere l'ingest -->
+
+## Domain conventions
+
+- **Lingua pagine wiki:** italiano (default, vedi CLAUDE.md)
+- **Fonti tipiche:** norme (ISO/UNI/DIN...), datasheet/cataloghi produttore, paper, manuali — spesso pre-processate con MinerU in modalità pipeline (vedi CLAUDE.md per i limiti di questo backend)
+- **Unità di misura:** <!-- es. SI, salvo dove la fonte usa unità imperiali -->
+
+## Thesis
+
+<!-- La tua ipotesi/conclusione corrente, da aggiornare man mano che l'ingest procede -->
+
+> TBD

schema.md

@@ -0,0 +1,91 @@
+# Wiki Schema
+
+## Raw Layer
+
+- `raw/sources/<slug-documento>/` — one subfolder per source document, kebab-case slug (e.g. `iso-6336-gear-rating`, `catalogo-skf-cuscinetti-2024`). Contains the document as produced by ingestion (MinerU markdown output + `images/` + json sidecars, or a bare PDF). Never rename or move files inside a source folder — relative image links depend on the original layout.
+- `raw/assets/` — standalone images/scans/figures not tied to a specific ingested document.
+- Files under `raw/` are immutable once ingested. If extracted content is wrong (OCR error, bad table), fix it in the wiki page with a note — never edit the raw file.
+- Every claim in `wiki/` must be traceable to a slug in `raw/sources/`.
+
+## Page Types
+
+| Type | Directory | Purpose |
+|------|-----------|---------|
+| entity | wiki/entities/ | Named things (people, tools, organizations, datasets) |
+| concept | wiki/concepts/ | Ideas, techniques, phenomena, frameworks |
+| source | wiki/sources/ | Papers, articles, talks, books, blog posts |
+| query | wiki/queries/ | Open questions under active investigation |
+| comparison | wiki/comparisons/ | Side-by-side analysis of related entities |
+| synthesis | wiki/synthesis/ | Cross-cutting summaries and conclusions |
+| overview | wiki/ | High-level project summary (one per project) |
+
+## Naming Conventions
+
+- Files: `kebab-case.md`
+- Entities: match official name where possible (e.g., `openai.md`, `gpt-4.md`)
+- Concepts: descriptive noun phrases (e.g., `chain-of-thought.md`)
+- Sources: `author-year-slug.md` (e.g., `wei-2022-cot.md`)
+- Queries: question as slug (e.g., `does-scale-improve-reasoning.md`)
+
+## Frontmatter
+
+All pages must include YAML frontmatter:
+
+```yaml
+---
+type: entity | concept | source | query | comparison | synthesis | overview
+title: Human-readable title
+tags: []
+related: []
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+Source pages also include:
+```yaml
+authors: []
+year: YYYY
+url: ""
+venue: ""
+```
+
+Any page that draws on a source processed via OCR/layout extraction (e.g. MinerU pipeline mode) should reference it and, where a specific fact is uncertain (garbled formula, misaligned table, ambiguous reading order), mark it inline rather than presenting it as verified:
+
+```yaml
+raw_source: raw-slug          # slug in raw/sources/ this page is derived from
+confidence: high | medium | low
+```
+
+Use `confidence: low` or `medium` for any numeric value, formula, or spec pulled from a document with known extraction issues, until it's been cross-checked.
+
+## Index Format
+
+`wiki/index.md` lists all pages grouped by type. Each entry:
+```
+- [[page-slug]] — one-line description
+```
+
+## Log Format
+
+`wiki/log.md` records activity in reverse chronological order:
+```
+## YYYY-MM-DD
+
+- Action taken / finding noted
+```
+
+## Cross-referencing Rules
+
+- Use `[[page-slug]]` syntax to link between wiki pages
+- Every entity and concept should appear in `wiki/index.md`
+- Queries link to the sources and concepts they draw on
+- Synthesis pages cite all contributing sources via `related:`
+
+## Contradiction Handling
+
+When sources contradict each other:
+1. Note the contradiction in the relevant concept or entity page
+2. Create or update a query page to track the open question
+3. Link both sources from the query page
+4. Resolve in a synthesis page once sufficient evidence exists

wiki/index.md

@@ -0,0 +1,13 @@
+# Wiki Index
+
+## Entities
+
+## Concepts
+
+## Sources
+
+## Queries
+
+## Comparisons
+
+## Synthesis

wiki/log.md

@@ -0,0 +1,5 @@
+# Research Log
+
+## 2026-07-15
+
+- Project created

wiki/overview.md

@@ -0,0 +1,10 @@
+---
+type: overview
+title: Project Overview
+tags: []
+related: []
+---
+
+# Overview
+
+<!-- Provide a high-level summary of what this wiki covers and its current state. Update regularly as understanding deepens. -->