Metnos offre due strumenti distinti. La pagina Settings della chat è l'interfaccia amministrativa corrente, aggiornata a ogni richiesta. runtime/observability.py produce invece un file HTML statico per una diagnosi locale. Il file non alimenta Settings, non si aggiorna da solo e non è una pagina servita dalla chat.

1. Un esempio in linguaggio naturale

Chiedi a Metnos con una richiesta come quella di questo esempio:

Mostrami dove posso controllare gli ultimi turni e lo stato dei servizi.

La risposta utile deve indicare anzitutto il percorso visibile nella chat: Settings > Attività > Turni per le richieste recenti e Settings > Sistema > Servizi per i servizi configurati. Se la domanda arriva da Telegram, il percorso va aperto nella chat web di Metnos: Telegram non incorpora le pagine amministrative.

Solo dopo questa istruzione pratica occorre spiegare API, registri o file. Il rendiconto statico è adatto a una diagnosi tecnica esplicitamente richiesta, non è il percorso ordinario per chi usa la chat.

2. Le due superfici

Le due superfici non vanno sommate in una descrizione unica. Settings usa rotte e modelli propri; il generatore statico è richiamato soltanto dalla sua CLI e non ha chiamanti nel server HTTP.

3. Settings nella chat

La pagina iniziale di Settings riassume versione e tempo di attività, turni delle ultime 24 ore, proposte, executor, scheduler, firme Safety e utenti. Le pagine di dettaglio separano le diverse domande operative:

Il registro in runtime/ui_surfaces.py è la descrizione canonica delle pagine visibili e del loro percorso. Tutor usa lo stesso registro: una modifica strutturale della UI richiede l'aggiornamento del registro, della guida di navigazione e dell'indice di Tutor.

4. Il rendiconto HTML statico

render_dashboard(out_path) interroga le sorgenti locali e compone un unico documento con CSS incorporato, senza JavaScript e senza WebSocket. Le sezioni appaiono in questo ordine: test, Mnestoma, associazioni, turni recenti, decisioni del Vaglio e scheduler.

Ogni raccoglitore gestisce separatamente una sorgente non disponibile. La pagina può quindi essere prodotta anche quando una sezione è vuota o in errore. Questo comportamento rende leggibile una fotografia parziale, ma non trasforma l'assenza di dati in prova del buon funzionamento del componente.

Il documento generato usa attualmente etichette italiane e lang="it". Non è una superficie localizzata della chat e non va presentato come tale.

5. Dati raccolti dal rendiconto

I limiti sono applicati dal generatore e non sono parametri della CLI: cinque file giornalieri al massimo per i turni, tre file per il Vaglio e limiti distinti per righe ed eventi. Per un'analisi completa occorre interrogare la sorgente autorizzata, non dedurre il totale dalla pagina.

6. Accesso, utenti e riservatezza

• Settings è una vista amministrativa dell'installazione. Il middleware ammette soltanto il ruolo admin; i riepiloghi possono comprendere più utenti. Non è una vista personale del singolo utente.
• Il rendiconto statico è anch'esso complessivo. Può contenere richieste, estratti delle risposte, identificativi dei mittenti e metadati delle associazioni appartenenti a utenti diversi.
• L'escape HTML non è un controllo di accesso. Il generatore sottopone a escape i testi dinamici prima di inserirli nel documento, ma il contenuto rimane leggibile a chi può aprire il file.
• L'oscuramento a monte non è una garanzia assoluta. I registri possono rimuovere credenziali riconosciute, ma il rendiconto va comunque trattato come dato riservato.
• Il file non imposta permessi propri. Eredita directory, proprietario e umask del processo che lo genera; non va collocato in una directory servita pubblicamente.
• Una fotografia resta sul disco. Rigenerarla sovrascrive il percorso scelto, ma non elimina copie spostate, backup o file prodotti con un altro --out.

7. Generazione e durata

Dalla radice dell'installazione, usando l'ambiente Python di Metnos:

PYTHONPATH=runtime ./.venv/bin/python -m observability render
PYTHONPATH=runtime ./.venv/bin/python -m observability render --out /percorso/scelto/dashboard.html

Il percorso predefinito è PATH_WORKSPACE/dashboard/index.html. Il comando restituisce il percorso scritto e termina. Non esiste un aggiornamento periodico incorporato: ora di generazione e contenuto restano invariati finché il comando non viene eseguito di nuovo.

Il file è un prodotto derivato. Per eliminarlo si può rimuovere il solo percorso di uscita dopo aver verificato che non sia usato da altri processi; le sorgenti operative non vengono eliminate con esso.

8. Verifiche e fonti canoniche

Le prove mirate del generatore statico sono in tests/runtime/runtime/test_observability.py. Verificano, fra l'altro, che nomi degli executor, richieste e risposte non possano introdurre markup attivo nel file. Le prove HTTP ed end-to-end controllano separatamente le pagine amministrative: non si usa un conteggio fisso, destinato a diventare obsoleto.

• runtime/http_routes_admin.py — dati e azioni delle pagine Settings;
• runtime/http_auth.py — confine di autenticazione delle rotte /admin;
• runtime/ui_surfaces.py — registro editoriale delle superfici visibili;
• runtime/observability.py — generatore del rendiconto statico;
• runtime/config.py — percorsi canonici dell'installazione.