# 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
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
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