agent-wiki-ui/docs/adr/0007-schema-wiki-per-query-con-immagini.md

ADR-0007 — Schema di una wiki interrogabile, con immagini (prototipo)

• Stato: Proposta
• Data: 2026-10-15
• Collegato a: ADR-0006 (l'app mostra le immagini citate nella risposta)

Contesto

agent-wiki-ui è il terminale di chat per interrogare una wiki mantenuta da un motore (Claude Code, Codex), per esempio una wiki di studio o di documentazione tecnica: pagine markdown, un indice, un catalogo JSON delle figure con i metadati e una cartella di immagini. Per rispondere in modo strutturato — meglio di un RAG, che recupera frammenti di testo e perde le relazioni — il motore deve sapere dove cercare (indice → pagina → tabella o figura) e come citare un'immagine perché la chat la stampi. Oggi questo sapere sta in un file scritto per una sola wiki. Non esiste uno standard: la cartella delle immagini e il formato del catalogo cambiano da wiki a wiki, ed è un prototipo.

Criteri di decisione

1. Un solo posto per i percorsi delle immagini, senza duplicarli a mano.
2. Le mappe sono derivate dal catalogo (si rigenerano), non scritte a mano.
3. Nessuna cartella o nome di file imposti: la wiki dichiara la sua struttura.
4. Degrado sicuro: un percorso sbagliato dà [alt] nella chat (ADR-0006), mai un errore.
5. Nessun codice nell'app: la logica sta nelle istruzioni al motore e negli script della wiki.
6. Pochi campi minimi, perché lo standard possa nascere dall'uso.

Opzioni considerate

Opzione	Esito	Motivo
Solo RAG sul testo (embedding di search_text)	Scartata come unica via	Perde la struttura che rende affidabile la risposta: dato → pagina unica, avvertenze, difetti noti, figura → file. Resta come ripiego (ricerca testuale).
L'app legge il catalogo e inserisce le immagini nelle risposte	Scartata	Lega l'app a un formato non standard e duplica la scelta delle figure, che il motore fa già leggendo la domanda.
Schema in tre parti, letto dal motore; l'app stampa	Scelta	Conserva la struttura, non tocca l'app, si adatta a wiki diverse.

Decisione

Una wiki interrogabile ha tre parti. Il formato è una convenzione consigliata, non un requisito dell'app.

1. Indice (index.md): catalogo delle pagine, una riga per pagina, - [[pagina]] — sintesi. Una pagina con figure aggiunge in coda gli id del catalogo: · figure: fig-026, fig-027. L'indice non elenca le figure una per una e non contiene percorsi di file.
2. Catalogo delle figure (JSON, nome e posizione dichiarati nello schema della wiki). Campi minimi per figura:
   • id stabile, label (ad es. «Figura 26»);
   • caption_printed (testo della fonte, alla lettera) e, a parte, ogni testo generato dall'immagine, contrassegnato come non verificato;
   • location (sezione e riga nella fonte);
   • panels[] con file e path (relativo alla cartella del catalogo) e una descrizione;
   • quality: flags e review_notes. Indici facoltativi per sezione, composto, tipo e concetto. L'ordine di preferenza per trovare una figura è: indice dell'indice → pagina → figures nel frontmatter → indici del catalogo → ricerca testuale.
3. Istruzioni per le query: un file CLAUDE.md (per Codex AGENTS.md) in una cartella dedicata sotto la radice della wiki, da cui si avvia l'app. Si aggiunge a quello della radice e prevale su di esso. Impone la sola lettura, instrada le domande per tipo verso l'indice giusto e fissa le regole per le immagini.

Regole per le immagini nella risposta:

• Il percorso si ricava da catalogo e path, si verifica che esista e si scrive relativo alla radice della wiki, senza .. (l'app lo cerca nella sua cartella e poi nelle superiori, ADR-0006).
• Subito sotto: didascalia stampata alla lettera, posizione nella fonte, link alla nota della figura; una riga di avvertenza se flags o review_notes.
• Ciò che deriva dall'immagine (descrizioni, valori letti da un grafico) si dichiara non verificato. Massimo 3-4 immagini per risposta.

Percorsi derivati. Se il catalogo ha percorsi relativi alla propria cartella, la wiki genera con uno script una mappa figura → percorso dalla radice → pagine che la citano (per esempio colonne in più di figure-indice.md). Lo script, e un controllo in fase di lint che ogni percorso della mappa esista, sono della wiki, non di questo repo.

Chi fa cosa

Parte	Compito
Wiki	Mantiene indice, catalogo e immagini; rigenera la mappa; controlla che i percorsi esistano
Motore	Instrada la domanda, legge indici e pagine, sceglie le figure, scrive il markdown con l'immagine e la didascalia
App	Stampa il markdown; mostra l'immagine se il file esiste, altrimenti [alt]

Conseguenze

Positive: una risposta ripercorre indice → pagina → figura invece di cercare frammenti; i percorsi stanno in un solo posto e si rigenerano; l'app non cambia; wiki diverse adottano lo stesso modello cambiando pochi campi. Negative: il rispetto dello schema dipende dal motore che segue le istruzioni (può sbagliare percorso: l'app lo mostra come [alt]); la wiki deve mantenere lo script e il controllo dei percorsi; lo standard è provvisorio.

Da verificare

• Che Claude Code, avviato dalla cartella dedicata, legga e rispetti sia il file di quella cartella sia quello della radice (prova con la chat reale su una wiki di esempio).
• L'equivalente per Codex (AGENTS.md) e come si comporta con le immagini nei suoi comandi.
• Se il campo minimo path debba diventare un percorso dalla radice nel catalogo stesso, eliminando la mappa derivata.

Riferimenti

• Uso con le immagini: README.md, sezione «Immagini nelle risposte».