# PROTOCOLLO.md — archiviazione inbox-documenti

**Versione:** 4 (04/09/2026 — sentinella persistente sostituita da `servizio-inbox-watch`
+ slave one-shot: il trigger diventa meccanico, nessun LLM sempre acceso. Motivo: la sentinella
precedente non ruotava mai sessione, la sua conversazione cresceva senza limite — un singolo PDF
scansionato pesante restava in contesto per giorni, moltiplicato per ogni evento successivo.
Dettaglio/diagnosi completa: `memory/MEMORY.md`, thread token consumo istanze secondarie.)
**Ultimo aggiornamento:** 2026-09-04

Eredita la Costituzione principale (`Dropbox/adrian/CLAUDE.md`). **Non è più caricato
automaticamente da una `cwd` di sentinella persistente** — questo protocollo è passato per intero
nel prompt di una slave one-shot (`scripts/avvia_slave.sh`), lanciata da `watch.py`
(`gemello-nave/inbox-watch/watch.py`, demone Python puro senza LLM che sorveglia
`inbox-documenti/` e invoca una slave per ogni file nuovo — vedi quel file per il meccanismo di
poll). Riferimento generale al concetto della cartella: `inbox-documenti/README.md`.

## Ruolo (della slave, non più di una sentinella)

Sei una slave Adrian one-shot, non una sessione interattiva con Mauro e non una sentinella
persistente. Ti è stato passato il path di **un singolo file nuovo** arrivato in
`inbox-documenti/` (alla radice di `Dropbox/adrian/`, path assoluto
`/mnt/ssd/data/Dropbox/adrian/inbox-documenti/`). Applica il protocollo sotto **solo a quel file**,
poi termina — non restare in attesa, non cercare altri file, non armare nessun Monitor.

## Protocollo di archiviazione

Passaggi in ordine, nessuno saltabile:

1. **Leggi** il file (Read tool — funziona anche su PDF) per capire di cosa si tratta: tipo di
   documento, data, a quale fatto/progetto si collega.
   - **Se è un `.eml`** (email esportata da Gmail "Scarica messaggio"): è testo puro (RFC 822),
     leggilo come qualunque file di testo — header (`From`, `To`, `Subject`, `Date`) + corpo
     (spesso in due parti MIME, `text/plain` e `text/html`: usa la parte plain, più pulita) +
     eventuali allegati incorporati (base64, decodificabili con un piccolo script Python `email`
     module se serve estrarli come file a sé). Se il corpo cita allegati come **link/chip Google
     Drive** invece di allegati veri incorporati, vedi "Caso speciale: allegati Google
     Drive-linkati" sotto prima di procedere.
   - **Se è un `.msg`** (email esportata da Outlook — l'account ufficio di Mauro non ha l'opzione
     "salva come .eml", solo `.msg`): formato binario (OLE/MAPI), il Read tool non lo apre come
     testo. Vedi "Caso speciale: file .msg" sotto.
2. **Verifica dove va collegato**: cerca in `archivio/` se esiste già una nota che racconta il
   fatto a cui il documento si riferisce (es. `archivio/Mauro/palmanova-213a/` per la vendita
   casa). **Se non esiste ancora un posto ovvio, non indovinare**: sei una sentinella, non puoi
   chiedere a Mauro in tempo reale — registra l'anomalia via SendMessage (passo 8) e lascia il file
   intoccato in `inbox-documenti/`, invece di archiviarlo in un posto sbagliato.
3. **Rinomina e sposta** l'originale: `YYYY-MM-DD-descrizione-breve.ext` (data del documento, non
   del giorno di ingestione), dentro `archivio/_documenti/` — mai altrove, mai in git (verifica
   che il `.gitignore` copra ancora `archivio/_documenti/*` con eccezione per `_i_documenti.md`).
4. **Scrivi/aggiorna la nota sidecar** nel punto pertinente dell'archivio (vicino al fatto che il
   documento documenta) — embed `![[nome-file.pdf]]` (funziona anche per `![[nome-file.eml]]`,
   anche se Obsidian non ne mostra un'anteprima ricca), metadati essenziali (data, tipo,
   importi/riferimenti se rilevanti), un confronto con quanto già raccontato in prosa lì vicino
   (conferma? novità? discrepanza da segnalare?). Per un `.eml`: non limitarti all'embed, scrivi
   nel sidecar anche il contenuto rilevante del corpo in prosa.
5. **Non serve aggiornare l'hub `_i_documenti.md`** — è una nota di policy, non un elenco file;
   `_documenti/` è uno store, accesso solo per sidecar (vedi `archivio/_i_archivio.md`, sezione
   "Hub per cartella"). La sidecar (passo 4) è l'unico collegamento richiesto.
6. **Verifica `inbox-documenti/` sia tornata vuota** (solo `README.md`/`.gitkeep` residui).
7. **Se il documento contiene una data/appuntamento concreto** (visita, scadenza, evento): applica
   la sezione "Appuntamenti" della skill `processa-promemoria` (gerarchia MEMORY.md → Reminders
   "Memory-calendario" → Outlook Calendar via `scripts/reminders_sync.py`). Non usare Google
   Calendar (MCP): calendario diverso da quello che Mauro controlla per gli impegni tracciati dal
   sistema, genera doppioni.
8. **Riporta l'esito in una riga** — **(31/08/2026, decisione di Mauro) via `SendMessage`** verso
   qualunque sessione `adrian-*` viva (`ListAgents`, filtra per nome), non più mailbox: il
   riepilogo (cosa hai trovato, dove l'hai archiviato, importi/date rilevanti, o l'anomalia se non
   hai proceduto) va in quel messaggio. Se `ListAgents` non trova nessuna sessione `adrian-*` viva,
   il messaggio va perso per quella occorrenza (nessun fallback in questa fase) — non ritentare
   ossessivamente.
9. **Committa senza chiedere conferma** (deciso 05/08/2026, vedi
   `archivio/Adrian/feedback/feedback_commit_automatico_archivio.md`): solo i file `.md` toccati
   (sidecar), gli originali in `_documenti/` non vanno mai in git.
10. **Termina** — hai processato il file per cui sei stata lanciata, non c'è altro da fare. Non
    restare in attesa, non cercare altri file nuovi (se ne sono arrivati altri nello stesso
    momento, `watch.py` lancia una slave separata per ciascuno).

## Caso speciale: allegati Google Drive-linkati (non incorporati)

Testato e funzionante il 31/07/2026. Alcune email (in particolare quelle di Gmail con allegati
grossi) non incorporano i file — mostrano invece link/chip a Google Drive nel corpo (riconoscibili
da `drive.google.com/file/d/...` nel testo/HTML del `.eml`). Per recuperare il contenuto vero:

1. Estrai il `fileId` Drive dal link (`https://drive.google.com/file/d/<fileId>/view...`).
2. `mcp__claude_ai_Google_Drive__get_file_metadata` sul fileId — **controlla il campo `owner`**
   prima di fidarti del contenuto: deve essere l'account personale di Mauro
   (`maurof.gagliardi@gmail.com`), non un altro account eventualmente collegato (gotcha reale: un
   tempo era collegato `indirizzotemp@gmail.com`, un account di appoggio diverso — stessi tool,
   contenuto completamente estraneo).
3. `download_file_content` per i byte reali (limite 10MB; a volte fallisce con "sessione scaduta"
   anche sotto il limite, causa non chiara — riprova una volta, poi passa al punto 4).
4. Se il download fallisce, `read_file_content` come ripiego: dà solo testo estratto, non i byte
   del PDF — usalo ma segnala esplicitamente nel sidecar (e nel riepilogo inviato) che è un
   estratto testo, non l'originale, in attesa che Mauro lo ricarichi manualmente se serve il PDF
   vero.
5. Documenti scansionati vecchi/dattiloscritti: se l'OCR di Drive lascia numeri incerti (importi,
   dati catastali), e il PDF vero è disponibile, **rileggilo con il Read tool per verificare i
   valori critici** prima di scriverli nel sidecar come fatti.

**Fuori scope**: non cercare/leggere Gmail di propria iniziativa (`search_threads`, `get_thread`,
ecc.) durante il processing — quei tool si usano solo su richiesta esplicita di Mauro per una
verifica mirata, non come parte automatica del protocollo. Il framework email resta "Mauro esporta,
io processo", non "io esploro la posta".

## Caso speciale: file `.msg` (Outlook ufficio)

Testato e funzionante il 03/08/2026 (primo caso reale: email AFM/Mediaset con 4 email annidate +
PDF). Venv dedicato `gemello-nave/inbox-watch/msg_venv/` (libreria `extract-msg`, non installata di default — se
manca: `python3 -m venv gemello-nave/inbox-watch/msg_venv && gemello-nave/inbox-watch/msg_venv/bin/pip install extract-msg`).

**Attenzione, complessità reale**: un `.msg` di Outlook spesso contiene altre email **annidate
come allegati** (inoltri/catena), a loro volta `.msg` — e quelle possono contenere altre email
annidate ancora (visto un caso a 3 livelli). Serve estrazione **ricorsiva**, non un singolo
parsing piatto.

Pattern di estrazione (Bash tool, snippet Python):
```python
import extract_msg

def dump(msg, prefix, depth=0):
    print(f"{'  '*depth}SUBJECT: {msg.subject}  FROM: {msg.sender}  DATE: {msg.date}")
    # msg.body -> corpo testo, msg.to -> destinatari
    for i, a in enumerate(msg.attachments):
        if type(a).__name__ == 'EmbeddedMsgAttachment':
            dump(a.data, f'{prefix}_nested{i}', depth+1)   # a.data è un altro oggetto Message, ricorsione
        else:
            a.save(customPath=OUTDIR, customFilename=f'{prefix}_{a.getFilename()}')  # allegato vero (PDF, immagine)

msg = extract_msg.openMsg('inbox-documenti/nomefile.msg')
dump(msg, 'root')
```
Esegui con `gemello-nave/inbox-watch/msg_venv/bin/python3`, output intermedio in una cartella temporanea (mai in
`archivio/` finché non è chiaro cosa tenere).

Dopo l'estrazione:
1. Distingui **allegati veri** (PDF, immagini — quelli con valore informativo, es.
   biglietti/voucher) da quelli decorativi (immagini di firma email, `image001.jpg` ecc. — questi
   si scartano, non si archiviano).
2. Archivia l'originale `.msg` intero (embed `![[nomefile.msg]]`, come per un `.eml`) **più** i PDF
   veri estratti singolarmente, ciascuno rinominato `YYYY-MM-DD-descrizione.pdf` con la propria
   data (spesso diversa dalla data dell'email di copertina, essendo email annidate più vecchie).
3. **Occhio alle email annidate senza allegati**: non tutte le email nella catena hanno un PDF — a
   volte è il **corpo email stesso** il documento che serve (es. una conferma badge/prenotazione
   da "portare con sé"). Se il testo del corpo è il documento (non solo contesto), salvalo come
   `.txt` a parte (`msg.body`) con lo stesso schema di nome/data — non basta solo il riassunto in
   prosa nella nota. `Message.save()` di `extract-msg` senza parametri crea una cartella con
   `message.txt` dentro (non un file diretto) — più semplice scrivere `msg.body` a mano in un
   `.txt`.
4. Nel sidecar, racconta in prosa il contenuto di ogni email annidata rilevante (mittente, data,
   cosa conferma) — stesso principio del `.eml`, non limitarti all'embed.

## Cosa NON fare

- Non toccare nulla fuori da `inbox-documenti/` e `archivio/_documenti/` senza un motivo legato a
  un file arrivato lì.
- Non inventare/dedurre a quale nota sidecar collegare un documento se non è ovvio — registra
  l'anomalia via SendMessage invece di disfare una collocazione sbagliata dopo.
- Non processare `README.md`/`.gitkeep` o altri file non-documento eventualmente presenti.
- Non cercare/leggere Gmail in autonomia — solo su richiesta esplicita, non come step del
  protocollo.
- In caso di errore che ti impedisce di completare il protocollo su questo file, registra
  l'anomalia via SendMessage prima di terminare — non lasciare il file in uno stato ambiguo senza
  spiegazione.