Protocollo Brain v2.3

# BRAIN.md — Il Protocollo Brain

**Versione**: 2.3 | **Ultimo aggiornamento**: 2026-08-25

Definisce cosa è un brain, come è strutturato, e come qualsiasi motore AI deve interagire
con esso. Agnostico rispetto alla piattaforma.

Questo file descrive il **protocollo**. Quello che riguarda la singola installazione —
dove si pubblica, che URL, che regole di postura — sta in `boot/domain.md`. In caso di
conflitto **vince `domain.md`**: è più vicino alla realtà della macchina.

---

## Cosa è un Brain

Un brain è un knowledge base personale. Non è il modello AI (quello è sostituibile), è la
conoscenza accumulata dall'utente: decisioni, relazioni, progetti, appunti, log.

Il brain è portabile, owned dall'utente, e cresce con ogni interazione.

---

## Struttura cartelle

```
brain/
├── boot/           Identità e sistema: chi sei, chi assisti, dove giri
├── wiki/           Entità strutturate
│   ├── people/
│   ├── companies/
│   └── projects/
├── diary/YYYY/     Log temporale (cosa è successo quando)
├── todo/           Task aperti
├── inbox/          Roba in arrivo da processare
├── public/         File destinati alla pubblicazione (vedi domain.md)
├── storage/        Temporanei, cache, binari, database
├── tools/          Script e librerie
├── shared/         Risorse della piattaforma (READ-ONLY)
└── .env            Credenziali (SEMPRE gitignored)
```

Se non sai dove mettere qualcosa, usa `storage/`. Non creare altre cartelle nella root.

### boot/ — Identità e sistema

| File | Contenuto | Chi lo scrive |
|------|-----------|---------------|
| `brain.md` | Questo protocollo (symlink a shared) | Piattaforma |
| `domain.md` | Regole dell'installazione (symlink a shared) | Piattaforma |
| `soul.md` | Chi sei: carattere, invarianti, come parli | Per-utente |
| `user.md` | Chi assisti: ruolo, contesto, come vuole essere aiutato | Per-utente |
| `local.yaml` | Slug, path, URL pubblici **di questo brain** | Piattaforma |
| `skills.yaml` | Registri e skill installate | Per-brain |

**I symlink di `boot/` vanno scritti in forma relativa** (`../../shared/core/system/BRAIN.md`).
Un symlink assoluto `/var/abchat/...` risolve sull'host ma **non dentro il container**, dove
`shared/` è montata altrove: il file sparisce dal boot senza nessun errore visibile.

L'agente DEVE leggere `boot/` a inizio sessione.

**Il boot ha un costo.** Tutto ciò che sta qui viene caricato a ogni sessione, prima del
primo messaggio. Quello che serve *a volte* non va nel boot: va in `wiki/`, dichiarato come
fonte da una skill. **Un file che nessuna skill dichiara come fonte non esiste** — e un boot
gonfio brucia la memoria prima che l'utente abbia parlato.

### shared/ — Risorse della piattaforma

`shared/` è **READ-ONLY**. L'agente non modifica, non crea, non cancella nulla lì dentro.
Se serve uno strumento che non c'è, lo crea in `tools/lib/` del proprio brain. Se c'è già
in `shared/`, lo usa senza duplicarlo.

### public/ — dipende dall'installazione

**Non dare per scontato che scrivere in `public/` pubblichi qualcosa.** Su alcune
installazioni la cartella è servita sul web aperto; su altre serve un publish esplicito che
produce un link a scadenza, e finché non lo fai il file non è raggiungibile da nessuno.

**Leggi `boot/domain.md` e `boot/local.yaml` prima di dire a qualcuno che una pagina è
online**, e verifica l'URL invece di comporlo a memoria. In nessun caso mettere in `public/`
password, token o dati personali.

### inbox/ — Messaggi in arrivo

Riceve messaggi e file da elaborare. I `msg-*.json` sono notifiche strutturate
(`from_name`, `subject`, `body`, `sent_at`). I file caricati dall'utente finiscono qui:
l'agente li processa quando glielo chiede.

---

## Scrittura nel brain

### Frontmatter YAML obbligatorio

Ogni file `.md` in `wiki/` e `diary/` DEVE avere frontmatter:

```yaml
---
date: '2026-03-02'
type: diary
created_at: '2026-03-02 14:30:00'
created_with: nome-agente
tags:
  - diary
---
```

| Campo | Descrizione |
|-------|-------------|
| `date` | Data del contenuto |
| `type` | person, company, project, diary, log, todo, pattern |
| `created_at` | Timestamp creazione |
| `created_with` | Nome del TUO agente — non copiarlo dagli esempi |
| `tags` | Lista; il primo tag corrisponde al type |

Quando un contenuto non è stato prodotto lavorando ma **importato o ricostruito** (da un
archivio mail, da un altro brain, da una distillazione), aggiungi `source:` con la
provenienza. Serve a non citare come vissuto ciò che è ereditato.

### index.yaml — indice di cartella

Ogni cartella può avere un `index.yaml`: elenco dei file con i loro metadati e regole di
validazione. Lo genera il tooling della piattaforma — **l'agente non lo scrive a mano.**

### Naming

| Tipo | Pattern | Dove |
|------|---------|------|
| Diary/Log | `YYYY-MM-DD-slug.md` | `diary/YYYY/` |
| Persone | `nome-cognome.md` | `wiki/people/` |
| Aziende | `slug-name.md` | `wiki/companies/` |
| Progetti | `slug/index.md` | `wiki/projects/` |
| TODO | `YYYY-MM-DD-slug.md` | `todo/` |

Tutto lowercase con trattini. Mai spazi, mai underscore, mai CamelCase.

### Strumenti di scrittura

La piattaforma fornisce strumenti che garantiscono frontmatter, naming e indici corretti.
L'agente DEVE usarli per scrivere in `wiki/`, `diary/` e `todo/`. Non scrivere a mano in
quelle cartelle bypassando il tooling.

### Wiki-Links

`[[wiki/people/mario-rossi|Mario Rossi]]`, `[[wiki/projects/mio-progetto|Progetto]]`.

---

## Protocolli operativi

### Post-Action Protocol

Dopo ogni azione significativa (email, task completato, deploy, call):

1. Aggiorna il progetto in `wiki/projects/` con stato e data
2. Aggiorna persone e aziende se ci sono info nuove
3. Crea un log in `diary/`
4. Se l'utente ha corretto una tua bozza, cattura il pattern

Non è opzionale.

### Auto-checkpoint

**Quando:** task logico completato, cambio di argomento, azione esterna eseguita, lavoro
significativo non salvato.

**Quando no:** a metà di un'operazione, dopo sola lettura, se l'ultimo checkpoint è recente
e non è cambiato niente.

### Email

Mostra la bozza, aspetta conferma esplicita, poi invia. Mai una mail senza approvazione.

### Project-first — il lavoro vive nei progetti, non in chat

Ogni task non banale appartiene a un progetto. Il progetto è l'unità di memoria: tiene
contesto, fonti, storia, deliverable. La chat è effimera, il progetto resta. Senza progetto
il lavoro non ha dove accumularsi e il brain riparte da zero a ogni richiesta.

- Deduci il progetto attivo dal contesto. Se non ci riesci, chiedi — ma prova prima.
- Il lavoro ricorrente o multi-step **è** un progetto. Proponilo *prima* di farlo.
- Logga sempre col tag del progetto attivo. Mai lavoro orfano.

### Onboarding

Quando `boot/soul.md` e `boot/user.md` contengono ancora i placeholder (`[AGENT_NAME]`,
`> ONBOARDING: non ancora completato`), sei in modalità onboarding.

È una **conversazione**, non un form: una o due domande per volta, reagisci alle risposte,
specchia la lingua dell'utente. Conosci la persona → riempi `user.md`. Plasma l'agente →
riempi `soul.md`. Salva via tooling man mano, togliendo i placeholder. Non deve finire in
una sessione: una persona conosciuta a metà batte uno sconosciuto.

Se l'installazione prevede un **runway** (`wiki/projects/runway/`), quello è il percorso
che guida le prime settimane dopo l'onboarding: leggilo a inizio conversazione e segui le
sue istruzioni.

---

## Sicurezza

**Credenziali** — tutti i secret in `.env`, sempre gitignored. Mai token o password nei log:
usa `[REDACTED]`. Secret esposto per sbaglio: revoca immediata.

**GDPR** — iniziali per i dati sensibili (pazienti, candidati). Mai nomi completi,
indirizzi o dati clinici in chiaro nei log.

**Azioni distruttive** — mai senza conferma esplicita. Annuncia cosa farai, aspetta l'ok,
preferisci operazioni reversibili.

**Isolamento** — ogni brain ha il suo `.env`. I wrapper condivisi verificano le credenziali
prima di eseguire: niente credenziali significa errore chiaro e nessuna azione. I brain non
vedono i dati degli altri.

---

*Maintained by: Giobi*
*v1.0 (2026-02-27) — v2.0 (2026-03-02): agnostico, shared/, index.yaml, inbox — v2.1
(2026-03-03): entry point, minisite, isolamento — v2.2 (2026-06-05) — v2.3 (2026-08-25):
tolte le parti smentite dalla macchina (template inesistenti, `.index.yaml`, public/ come
web aperto, iniezione del boot), boot/ allineato ai file veri, symlink relativi, costo del
boot, `source:` nel frontmatter, onboarding raccordato al runway.*