README: uso con il frontend agent-wiki-ui; figure incorporate come immagini Markdown

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 14:43:40 +02:00
1 parent b9affd9bef
commit 8785d7429d
@@ -16,7 +16,7 @@ Sola lettura. Italiano.
 1. Leggi la nota `wiki/figures/fig-NNN.md`: didascalia stampata, descrizione, testo visibile, contesto, righe di citazione, avvisi, «Pagine che la usano».
 2. **Apri il file immagine**: il nome è nell'embed `![[immagini/<hash>.<ext>]]` della nota, il percorso reale è `raw/immagini/<hash>.<ext>`. Per figure a più pannelli apri tutti i pannelli rilevanti. Usa lo strumento di lettura immagini del tuo agente.
 3. Descrivi ciò che vedi (struttura, reagenti, frecce, picchi, curve, assi, legenda) e collegalo al ragionamento della risposta; indica *cosa guardare* e *perché*.
-4. Cita sempre il percorso `raw/immagini/<hash>.<ext>` e la nota `[[fig-NNN]]` perché l'utente possa aprirla.
+4. Cita sempre il percorso `raw/immagini/<hash>.<ext>` e la nota `[[fig-NNN]]` perché l'utente possa aprirla, e **incorpora l'immagine** nella risposta con `![descrizione](raw/immagini/<hash>.<ext>)` (percorso relativo alla radice del repo): le interfacce che mostrano le immagini locali la visualizzano, le altre mostrano il testo alternativo.

 ## Attendibilità
 - Solo `caption_printed` è testo della tesi. Descrizioni, `visible_text` e didascalie generate derivano dall'immagine e non sono verificate.
@@ -1 +1,5 @@
 .obsidian/workspace.json
+
+# eseguibili di agent-wiki-ui copiati nella radice
+/agent-wiki-ui
+/agent-wiki-ui.exe
@@ -51,7 +51,7 @@ Le pagine **hub** hanno una sezione `## Struttura` con le sottopagine (es. `cicl
 ### 2. Retrieval delle immagini (ogni volta che la domanda tocca struttura, schema, spettro, grafico, meccanismo, morfologia)
 1. Individua le figure rilevanti da `figure-indice.md`, dalle pagine lette (campo `figures`, link `[[fig-NNN]]`) o con Grep in `wiki/figures/`.
 2. Leggi la nota `wiki/figures/fig-NNN.md` (didascalia stampata, descrizione, testo visibile, contesto, righe di citazione, avvisi) e poi **guarda l'immagine**: apri con Read il file in `raw/immagini/<hash>` indicato nell'embed `![[immagini/<hash>]]` della nota (per le figure a più pannelli, tutti i pannelli rilevanti). Le figure del riassunto sono `ris-fig-NN`.
-3. Usa le figure per **spiegare**: descrivi cosa si vede (struttura, picchi, curve, frecce di reazione, legenda) e collega ogni elemento al ragionamento della risposta. Cita sempre il percorso del file, così l'utente può aprirla: `raw/immagini/<hash>` (e la nota `[[fig-NNN]]`). Non limitarti a elencare i numeri di figura.
+3. Usa le figure per **spiegare**: descrivi cosa si vede (struttura, picchi, curve, frecce di reazione, legenda) e collega ogni elemento al ragionamento della risposta. Cita sempre il percorso del file, così l'utente può aprirla: `raw/immagini/<hash>` (e la nota `[[fig-NNN]]`). **Incorpora anche l'immagine nella risposta** con la sintassi Markdown `![descrizione](raw/immagini/<hash>.<ext>)` (percorso relativo alla radice del repo, senza spazi): le interfacce che mostrano le immagini locali (es. agent-wiki-ui) la visualizzano; le altre mostrano il testo alternativo. Non limitarti a elencare i numeri di figura.
 4. Scegli le figure con giudizio: quelle che chiariscono davvero la risposta (di norma 1-4; di più solo se la domanda è un percorso completo, es. l'intera sintesi). Se non c'è una figura utile, non forzarla.
 5. **Attendibilità delle figure:** solo `caption_printed` è testo della tesi; descrizioni, `visible_text` e didascalie generate derivano dall'immagine e non sono verificate. Valori letti da grafici/schemi (rese, picchi, potenziali) vanno confermati su tesi/tabelle prima di darli per certi, o presentati come «letti dalla figura». Figure con `flags`/`review_notes` (Fig. 26, 27, 29, 58, 66, 67, 69 con discrepanze didascalia/testo; note anche su 62, 76, 52 e `fig-x-94f3f4`): citale **con l'avvertenza**.

@@ -64,7 +64,7 @@ scripts/                 gen_figures.py, gen_bibliografia.py, lint.py

 ## Come si usa

-1. Clona il repository e aprilo con un agente a riga di comando: **Claude Code**, **Codex** o **Antigravity CLI**. Skill e file di schema (`CLAUDE.md`, `AGENTS.md`) vengono trovati da soli. Obsidian è facoltativo, serve solo per sfogliare la wiki.
+1. Clona il repository e aprilo con un agente a riga di comando (**Claude Code**, **Codex** o **Antigravity CLI**) oppure con il frontend grafico [agent-wiki-ui](#interfaccia-grafica-agent-wiki-ui). Skill e file di schema (`CLAUDE.md`, `AGENTS.md`) vengono trovati da soli. Obsidian è facoltativo, serve solo per sfogliare la wiki.
 2. Fai una domanda in italiano, per esempio:
   - «Perché il PCL evita l'ACQ allo stato solido?»
   - «Confronta il band gap elettrochimico dei campioni bottle brush e mostrami i voltammogrammi.»
@@ -74,6 +74,45 @@ scripts/                 gen_figures.py, gen_bibliografia.py, lint.py

 La wiki è usata **in sola lettura**: l'agente non la modifica salvo richiesta esplicita. Lo schema di manutenzione (ingest, riallineamento, lint) resta nella cronologia git di `CLAUDE.md`, fino al commit `eb672df`.

+## Interfaccia grafica (agent-wiki-ui)
+
+Per interrogare la wiki senza terminale si può usare **[agent-wiki-ui](https://santantonio.sytes.net/davide/agent-wiki-ui.git)** come frontend: un eseguibile C# (.NET 10, Windows e Linux) con una chat in stile claude.ai, che lancia **Claude Code** (`claude -p`) o **Codex** (`codex exec`) nella cartella in cui si trova l'eseguibile. _Antigravity non è ancora supportato dal frontend._
+
+```mermaid
+flowchart LR
+    U["Utente<br/>chat della GUI"] -->|"domanda"| G["agent-wiki-ui<br/>nella radice del repo"]
+    G -->|"claude -p / codex exec"| E["Motore<br/>Claude Code o Codex"]
+    E -->|"legge schema e skill"| S["CLAUDE.md / AGENTS.md<br/>.agents/skills/"]
+    E -->|"consulta"| W["wiki/ e raw/"]
+    E -->|"risposta in Markdown<br/>con immagini"| G
+    G -->|"testo e figure"| U
+    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
+    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
+    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
+    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
+    classDef script fill:#e5e7eb,stroke:#374151,color:#111
+    class U,E agente
+    class G script
+    class S regole
+    class W wiki
+```
+
+_Il frontend è un semplice contenitore: non ha logica propria sulla wiki. Passa la domanda al motore, che lavora nella radice del repo e quindi trova da solo schema, skill e wiki, poi mostra la risposta._
+
+**Come configurarlo**
+1. **Motore.** Installa e autentica `claude` e/o `codex` nel PATH (guida: `docs/INSTALL.md` nel [repository del frontend](https://santantonio.sytes.net/davide/agent-wiki-ui.git)).
+2. **Eseguibile.** Ottienilo dal repository del frontend (serve il .NET SDK 10 per compilarlo: `scripts/publish.sh` su Linux/macOS/WSL, `scripts/publish.ps1` su Windows; risultato in `dist/<sistema>/agent-wiki-ui[.exe]`).
+3. **Posizione.** Copia l'eseguibile **nella radice di questo repository**, accanto a `CLAUDE.md` e `AGENTS.md`. È fondamentale: il motore parte nella cartella dell'eseguibile, non in quella da cui lo avvii. Gli eseguibili in radice sono ignorati da git.
+4. **Avvio.** Doppio clic (Windows) o `./agent-wiki-ui` (Linux, serve X11 o XWayland). Senza argomenti si apre la chat; con argomenti funziona da riga di comando (`./agent-wiki-ui "domanda"`, `--engine codex` per Codex).
+
+**Cose da sapere**
+- **Modello e effort.** All'avvio e a ogni cambio di motore il frontend sceglie il modello più piccolo ed effort `low`, per risposte rapide ed economiche. Per le risposte **approfondite e complete** che questo schema richiede, scegli nel riquadro **Impostazioni** un modello più capace e un effort più alto. Le impostazioni non sono salvate su disco: vanno ripetute a ogni avvio.
+- **Figure.** Le risposte incorporano le immagini con `![descrizione](raw/immagini/<hash>.<ext>)`: il frontend le mostra se il file è locale e leggibile (png, jpg, gif, webp, bmp; fino a 20 MB). Gli URL web non vengono caricati.
+- **Sola lettura.** Il frontend lancia Codex con sandbox in sola lettura; Claude Code parte senza bypass dei permessi. Coerente con la wiki usata in sola lettura.
+- **Chat.** Una chat usa un solo motore; cambiare motore apre una nuova chat. Le conversazioni sono salvate su disco e l'ultima si riapre all'avvio. La risposta compare a fine generazione (nessuno streaming).
+- **Stato del frontend.** È un MVP dichiarato tale nel suo repository: i test automatici sono ancora da scrivere e la GUI non è provata su Windows nativo.
+- **Non verificato qui.** Non ho provato l'insieme frontend e questo repo: né l'avvio, né che Codex riesca a guardare le immagini in sola lettura.
+
 ## Come è costruito

 _Il diagramma segue il materiale dal documento originale alla wiki, in quattro passi da sinistra a destra._