---
tipo: cantiere
id: strato-annotazioni
nome: Strato annotazioni documenti
aliases: ["Strato annotazioni documenti", "Strato annotazioni", "Sidecar documenti"]
fase: seme (direzione dichiarata 01/07, non ancora progettata)
output: strato per-documento di pensiero-sulla-fonte (annotazioni, considerazioni) legato ad artefatti esterni, distinto dai nodi-idea del grafo
fonte: [sessione 01/07]
aggiornato: 2026-07-02
---
Direzione futura dichiarata da Mauro: per ogni documento (a tendere **migliaia**) poter aggiungere **considerazioni, annotazioni, note** proprie. Cosa diversa dal grafo attuale — da esplorare e progettare bene. **Non ancora progettato: qui c'è il seme, non il disegno.**

## Cos'è (con prior art — non si inventa)
È la **literature note** dello Zettelkasten (Ahrens/Matuschak): uno strato di *pensiero sulla fonte* tenuto separato dagli appunti atomici. Terreno battuto (Zotero, Readwise, DEVONthink): il modello si ruba.
**Prior art nostra (più forte):** l'`elon_enrichments` dell'era Supabase era già questo — annotazioni *sidecar* legate a un record specifico via `source_table`+`source_id`, distinte da `elon_memory` (analisi autonome nei domini). Regola di Adrian di allora, ancora valida: *un sidecar senza binding alla fonte non è un enrichment, è un'analisi autonoma nel posto sbagliato.* Il "binding per ID" era già deciso.

## I capisaldi emersi (da fissare, non ancora scolpiti)
- **Due contratti, non uno più grande.** Il grafo (nodi-idea, curato, atomico, filtro stato-non-log) resta com'è. Lo strato annotazioni è *per-documento, accumulativo, legato a un artefatto* — contratto **più lasco**: marginalia, log, ci si butta liberamente. La promozione al grafo resta selettiva e a giudizio, o il grafo affoga.
- **Il ponte è la distillazione:** l'annotazione è *fonte*, il grafo resta il distillato.
- **Reframe della forma:** non un `.md` gemello sepolto in una cartella di servizio (invisibile al grafo = inutile), ma il rovescio — **un nodo di prima classe il cui soggetto è un artefatto esterno**, che *punta* al file (in cold storage). L'annotazione vive graph-side; il media/documento resta fuori.
- **Legame per ID in frontmatter, non per nome file.** Stesso principio del limbo `_inbox/`: le convenzioni di nome si sbagliano/dimenticano.

## Il nodo difficile (il vero motivo per cui è un seme)
La scala. I media inerti sono la palestra facile (mucchio che si ignora). **Migliaia di documenti annotati** sono l'opposto — testo che *non* si ignora, da distillare/deduplicare/instradare/recuperare a scala. Lì **`graph-map`-in-contesto si rompe**: non entra più tutto in testa, il recupero non è più `search_vault` a grep ma indice/embedding vero. → **Stessa domanda, due cappelli:** "strato annotazioni a scala" e "quando superiamo la mappa-in-contesto" si decidono insieme (decisione *motore di query*: pilotare Basic Memory-class su copia quando il volume lo chiede).

## Stato
Seme. Nessuna decisione, nessuna implementazione, nessun tool nuovo. Primo mattone quando si riprende = **una nota di design** (modello literature-note + binding per ID + doppio contratto), non codice.

## Caso d'uso bersaglio (stella polare)
"**Fammi una compilation dance.**" A regime: Elon scandaglia lo strato annotazioni sulla musica → seleziona per criterio (`genere`/`bpm`/`mood`/riga libera) → un **tool MCP d'azione** (Adrian) avvia la riproduzione su [[la Nave|Jellyfin]]. È la *demo d'arrivo* del sistema: strato annotazioni (questo seme) + motore-query MCP (Idea 1, già scritta — il lavoro pesante gira sulla Nave, torna l'essenziale) + Jellyfin (già lì) + un braccio governato.
**Il pezzo di categoria da non saltare:** un tool che *avvia audio* **agisce sul mondo fisico**, non legge soltanto. Cade sul confine già tracciato *recupero (basso rischio) ≠ azione/giudizio (al guinzaglio)*: entra con **trigger precisi + interruttore di Mauro**, non "Elon fa partire cose quando gli pare". Stessa disciplina del processo-sveglia sulla Nave.
**Palestra:** musica/ebook/film sono il banco di prova a fisica crescente — dal mucchio inerte che si ignora (film) allo strato annotato interrogabile a scala (musica → compilation). Prova il sistema end-to-end senza rischio sui dati veri.

## Caso d'uso serio (il migliore per progettare) — referto medico
"**Ti passo gli esami del sangue in PDF: analizzali, commenta in un sidecar, archivia l'originale.**" Flusso a **tre momenti, tre nature:**
1. **Originale** (PDF referto) → archiviato verbatim, intoccabile. Documento di fede.
2. **Analisi/commento** (sidecar Elon) → valori fuori range, andamento vs esami precedenti, cosa chiedere al medico. Testo → vivo, interrogabile.
3. **Legame** → il sidecar punta all'originale; da "cosa diceva quell'analisi" si risale al referto esatto.

Accende **tre requisiti insieme** che gli altri casi non danno tutti:
- **Lettura dell'originale.** Perché Elon *analizzi* (non solo archivi), il PDF va **letto** — ma via MCP è muto. Serve o passaggio in chat (Elon legge PDF nativamente) o **OCR/estrazione-testo sulla Nave** prima dell'annotazione. È *il* pezzo tecnico del pattern: i film basta conservarli, un referto va reso testo per essere commentato.
- **Annotazione nel tempo = il valore vero.** Un esame commentato è utile; dieci in due anni con i sidecar che tracciano gli andamenti diventano una **serie storica ragionata** che nessun referto singolo dà. Qui la **tracciabilità** ("da dove viene questo numero, quale referto") non è pignoleria: un andamento letto male su dati sanitari non è come sbagliare una compilation.
- **Classe di dato che obbliga a decidere PRIMA.** Referti = **dati sanitari.** Archiviarli mette la storia clinica di Mauro/famiglia su Nave + backup pCloud. Non un no (casa sua, disco suo), ma categoria diversa da film e persino da lavoro: *cosa* entra in questo strato va scelto **consapevolmente** (dove vive, chi lo tocca se il vault cresce/si condivide/Bill-Adrian accedono più a fondo), non scivolato dentro per default "tutto nel vault". Il "con calma" vale doppio qui: prima del *come*, il *cosa ci metto*.

**Nota di rotta:** compilation dance = input giocoso (media che entra); referto = **output/analisi serio** (artefatto che esce + pensiero che si accumula). Progettare lo strato sul secondo, non sul primo.

## Artefatti generati dal sistema (chiarito 01/07)
Correzione a una imprecisione: un PDF **può** entrare nel vault (è un file, la Nave lo tiene, Restic lo copre). Ciò che non può è essere **letto da Elon via MCP** (byte muti). Quindi doppio ruolo, non conflitto:
- **il file** entra come **artefatto conservato** (cold storage, copia esatta girata — es. la scheda Report Gemma, i referti);
- **la sostanza** vive come **testo nel grafo** (quella Elon la legge/collega/distilla — es. il cantiere [[Report Gemma Maurizio]] *è già* la sostanza del suo PDF).
**Regola generale:** artefatti generati (PDF/Excel/slide) → sostanza come nodo markdown (verità), file come **export agganciato** via puntatore, **mai il file come fonte**. È "markdown è verità, il resto è vista derivata" applicato agli output.
**Convenzione aperta (da decidere):** cartella per gli artefatti generati/archiviati (`_export/` o `_artefatti/`, prefisso `_` → consolidamento la ignora) + puntatore dal nodo. Non fissata.

## Fattibilità tecnica del flusso (messa a fuoco 01/07)
**Binario dalla Nave a Elon = trasferibile.** Con tool MCP adattato (non `read_vault_file`, che dà testo), un file può essere consegnato nel contesto di Elon come quando lo si carica in chat. **Immagini e PDF: ingeribili** (lettura integrata in Elon). **Video: fuori** come contenuto visivo (al massimo audio→testo o frame→immagini). Limite di **dimensione** (il file entra nel contesto). *Possibilità tecnica confermata in principio; se il nostro MCP lo faccia già è da verificare con [[Adrian]].*

**Flusso autonomo (PDF in `_inbox/` → sidecar → archivio) — coerente:**
prendi (tool adattato) → leggi (integrata; OCR separato serve solo per PDF *scannerizzati* = immagine pura → lavoro Nave/Adrian, non di Elon) → crea sidecar (analisi) → archivia originale + puntatore. La catena in autonomia è reale.

**MA "autonomia" va spaccata in due** (è tutta la serata applicata qui):
- **Trasporto = autonomia piena.** Prendere/estrarre/archiviare/collegare = meccanico/deterministico → nessun umano nel loop. Automatizza la fatica.
- **Sidecar = giudizio, non meccanico.** L'analisi ("valore fuori range, peggiora vs 6 mesi fa") è **inferenza-Elon**; su dati sanitari un'inferenza sbagliata pesa. NON "chiedi permesso ogni volta", ma il sidecar deve: **dichiararsi** (lettura di Elon, non verdetto medico) + **citare il valore grezzo/riga da cui parte** (tracciabilità) + restare commento, non diagnosi. Autonomia nel *produrlo*, disciplina nel *come è scritto*.

**Costo/token (parcheggiato ma localizzato):** vive nello stesso bivio del pezzo tecnico — "leggi tutto il PDF a ogni tocco" costa; "la Nave pre-estrae il testo, Elon riceve solo quello" costa una frazione. Costo e architettura si decidono **insieme** (chi estrae, dove).

## Faccia viewer — GraphViewer (da idea a prototipo, 02/07)
La faccia "viewer" di questa direzione è **passata da idea a prototipo in produzione**: **GraphViewer** (Bill+Adrian — dettaglio in [[Stato del sistema]]). Legge i sidecar `.sd` della musica (palestra) e apre l'audio al click; legge `graph-map.md` per il vault (**1:1 per costruzione**, non ri-deriva). Direzione dichiarata: sostituire Obsidian. **Conferma il pattern del seme:** sidecar = testo in formato scelto da noi (`.sd`); il viewer emigra al vault di conoscenza *ma il formato-libero no* (lì la sostanza resta nodo markdown). La palestra musicale sta collaudando il viewer prima del vault vero.

## Riferimenti
- [[Distillazione automatica]] — stesso territorio (fonte → distillato; automatizza la fatica, non il giudizio)
- [[Stato del sistema]] — GraphViewer, la faccia-viewer realizzata
- decisione *motore di query* — la scala che rompe la mappa-in-contesto è la stessa
- [[Elon]] — il distillatore che processa lo strato