netgescon-day0/docs/support/RETE-DOCS-E-AGENT-OPERATIVITA.md

Rete docs e agent - operativita condivisa

Scopo

Questo manuale definisce come distribuire i manuali di sviluppo e i runbook su tutte le macchine della rete.

La strategia ha due fasi compatibili:

• fase 0: condivisione LAN immediata di docs/ con NFS, senza dipendere subito da Gitea;
• fase 1: sincronizzazione Git/Gitea come sorgente autorevole versionata.

Decisione operativa

Da ora in avanti:

• docs/ non e solo documentazione locale del workspace, ma memoria distribuita del gruppo di lavoro;
• finche tutte le macchine non sono collegate a Gitea, la prima condivisione avviene via cartella LAN NFS;
• Gitea resta il canale ufficiale finale per propagare manuali, indici e runbook su tutta la rete;
• ogni macchina che ospita agent o servizi deve poter leggere una copia aggiornata di docs/;
• gli agent devono coordinarsi a partire da indice e runbook, non da ricostruzione manuale del contesto.

Architettura minima consigliata

Livello 0 - share LAN provvisorio ma operativo

Macchina capofila della rete:

• nodo capofila attuale: 192.168.0.200
• espone una share NFS di sola lettura o lettura/scrittura per docs/;
• mantiene anche una piccola area condivisa per scripts/ai/, exchange/ e moduli selezionati;
• diventa il punto comune da cui tutte le altre macchine montano i manuali.

Uso consigliato:

1. una macchina Day0 funge da sorgente LAN iniziale;
2. le altre macchine montano la share in un path fisso, per esempio /srv/netgescon/docs-mirror;
3. ogni workspace locale punta a quel mount per leggere i manuali, gli indici e gli script di supporto.
4. la cartella exchange/ serve per handoff, messaggi, allegati e materiale di appoggio tra macchine.

Livello 1 - sorgente autorevole

• repository netgescon-day0
• remote origin -> ssh://git@192.168.0.53:2222/michele/netgescon-day0.git
• branch operativo main

Livello 2 - mirror docs sulle macchine di rete

Ogni macchina tecnica puo usare uno di questi modelli:

1. checkout completo del repository Day0
2. mirror leggero con sparse checkout di docs/ e scripts/ai/

Il secondo modello e preferibile per macchine di supporto, agent dedicati e nodi che non devono eseguire tutta l applicazione.

Livello 3 - agent e servizi

Ogni agent deve sapere prima di tutto:

1. dove si trova il mirror docs/
2. qual e il commit corrente del mirror
3. quale indice leggere per trovare il cantiere attivo
4. dove riportare il risultato quando finisce

Procedura standard per aggiungere una macchina

Modalita A - prima di Gitea, con share LAN NFS

1. scegliere una macchina capofila che ospita il repository Day0 aggiornato;
2. esportare in rete una cartella condivisa che contiene almeno:
   • docs/
   • scripts/ai/
   • exchange/
   • eventuali moduli di lavoro selezionati
3. montare la share sulla macchina nuova in un path stabile;
4. creare un workspace locale che punti a quel mount condiviso;
5. leggere almeno:
   • docs/README.md
   • docs/00-INDICE-LAVORO-DISTRIBUITO.md
   • docs/support/CONTINUITA-SVILUPPO-AGENT.md
6. assegnare alla macchina un ruolo esplicito.

Modalita B - dopo il collegamento a Gitea

1. verificare accesso Git a Gitea dalla macchina
2. creare il mirror docs con lo script scripts/ai/bootstrap_docs_mirror.sh
3. leggere almeno:
   • docs/README.md
   • docs/00-INDICE-LAVORO-DISTRIBUITO.md
   • docs/support/CONTINUITA-SVILUPPO-AGENT.md
4. assegnare alla macchina un ruolo esplicito
5. aprire o aggiornare il runbook del cantiere che quella macchina seguira

Ruoli macchina gia previsti

.53 - Gitea + update server interno

Ruolo:

• sorgente Git della rete
• primo relay della documentazione distribuita
• nodo update interno per manifest e pacchetti

Runbook principale:

• docs/support/UPDATE-SERVER-53-RUNBOOK-2026-05.md

Nodi app/demo/prod

Ruolo:

• consumare aggiornamenti applicativi
• poter leggere i runbook di supporto senza dipendere dalla singola sessione agent

Macchina mini AI banca/contabilita

Ruolo:

• stream tecnico dedicato a riconciliazione movimenti bancari e scritture contabili
• supporto a matching, classificazione e proposte operative

Nota:

• prima di renderla operativa a pieno titolo, va creato un runbook dedicato a input, output, fonti dati e criteri di validazione.
• per il cantiere banca/contabilita esiste ora un primo runbook operativo in docs/INTEGRAZIONE-CONTABILE.md con la procedura validata di import Fucino su 0016.
• runbook dedicato chiamata .202: docs/support/MINI-AI-202-RICONCILIAZIONE-RUNBOOK.md.

Modus operandi di gruppo

1. ogni cantiere deve avere un documento indice o runbook esplicito
2. ogni avanzamento che diventa utile per altri deve essere scritto in docs/
3. gli agent non devono inventarsi workflow locali scollegati da Gitea
4. se due macchine lavorano sullo stesso stream, si sincronizzano via repository e non tramite copia manuale di file
5. prima di iniziare una nuova implementazione si legge l indice distribuito

Regola pratica per KB e passaggi di consegne

Quando un incidente di rete/applicazione viene chiuso o un cantiere cambia fase:

1. aggiornare prima il runbook o il documento guida nel repository Day0;
2. aggiungere o aggiornare il passaggio di consegne del cantiere interessato;
3. sincronizzare poi docs/ verso la .53 con scripts/ai/sync_docs_to_53.sh;
4. solo dopo considerare il KB centrale allineato per gli altri agent.

Nota operativa:

• il KB centrale sulla .53 va trattato come layer di retrieval e memoria condivisa;
• la prova di verita resta sempre il documento versionato nel repository, non una nota rimasta solo dentro una sessione o una macchina.

Sequenza pratica di lavoro condiviso

Fase 0 - rete locale senza Gitea

1. una sola macchina aggiorna il repository Day0 autorevole della LAN
2. quella macchina espone la share NFS di docs/ e scripts/ai/
3. le altre macchine montano la share nello stesso path logico
4. ogni agent legge l indice distribuito dalla stessa share
5. quando una procedura cambia, si aggiorna prima il repository Day0 della macchina capofila

Fase 1 - rete con Gitea attivo

1. definire il cantiere in docs/00-INDICE-LAVORO-DISTRIBUITO.md
2. fissare o aggiornare il runbook tecnico del cantiere
3. implementare nel repository Day0
4. commit + push su Gitea
5. pull o sync dei mirror sulle altre macchine
6. validazione locale della macchina che esegue il pezzo operativo
7. aggiornamento del runbook con esito, problemi e prossimo check

Script consigliato

Bootstrap share LAN NFS

Per preparare una macchina capofila o un client di rete senza Gitea usare:

bash bootstrap_docs_lan_share.sh server /home/michele/netgescon/netgescon-day0 192.168.0.0/24 /srv/netgescon/shared-docs "docs,scripts/ai,app,config,routes,resources,tests"
bash bootstrap_docs_lan_share.sh client 192.168.0.200:/srv/netgescon/shared-docs /srv/netgescon/shared-docs /home/utente/netgescon-lan-workspace

Comportamento atteso:

• lato server: prepara la cartella condivisa con docs/, scripts/ai/, exchange/ e moduli selezionati, genera la riga exports e i comandi exportfs
• lato client: monta la share, crea un workspace locale minimo e collega docs/, scripts/ai/, exchange/ e modules/ alla share di rete

Bootstrap mirror Git

Per creare o aggiornare un mirror leggero della documentazione su una macchina di rete usare:

bash scripts/ai/bootstrap_docs_mirror.sh /percorso/mirror-docs

Comportamento atteso:

• clone iniziale se il mirror non esiste
• sparse checkout di docs/ e scripts/ai/
• pull --ff-only se il mirror esiste gia
• stampa di remote, branch e commit corrente

Criterio di successo

Questa strategia puo dirsi attiva quando:

1. tutte le macchine agent leggono docs/ dalla stessa sorgente, inizialmente LAN e poi Git
2. l indice distribuito mostra i cantieri realmente in corso
3. la .53 puo essere istruita con runbook invece che con contesto orale disperso
4. i limiti di memoria della singola sessione vengono compensati da runbook e indici versionati