> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Mappa dei repo: dove vive cosa
> Quale repository contiene cosa, chi lo usa e per cosa. La regola in una riga: le procedure stanno qui, tutto ciò che ha un nome, un numero o un caso singolo sta nell'archivio privato.
**Questa guida è pubblica: la legge chiunque, e cancellare dopo non basta.** Niente nomi di persone o di aziende clienti, niente compensi, niente indirizzi interni, niente chiavi. Prima di scriverci dentro: [cosa ci va e cosa non ci va mai](/contribuire).
Quando devi scrivere qualcosa — una procedura, una nota su uno studente, una configurazione — la
prima domanda non è «come lo scrivo», è **«dove va a finire»**. Sbagliare posto ha due costi
diversi e opposti: scrivere una procedura nell'archivio privato vuol dire che nessuno la troverà
mai; scrivere il nome di un cliente qui dentro vuol dire pubblicarlo su internet, per sempre.
Questa pagina serve a non dover chiedere ogni volta.
## La regola in una riga
**Il «come si fa» sta su `mattone-docs`. Il «a chi è successo, quando, con quali dati» sta su `mattone-delivery-private`.**
Se la frase che stai per scrivere resta vera anche togliendo il nome, è una procedura: va qui.
Se senza il nome non vuol dire più niente, è un caso: va nell'archivio privato.
## I repo, in una tabella
| Repo | Cosa contiene | Chi lo usa, per cosa |
| - | - | - |
| **`mattone-docs`** (questo) | Documentazione e procedure generali: come si fa una cosa, guide, troubleshooting standard | Tutto il team, e chiunque su internet: è pubblicato su `docs.mattone.co` |
| **`mattone-delivery-private`** | La base privata del delivery: una scheda per studente, il registro delle chiavi, il diario, le note tecniche interne | Chi fa delivery, prima di toccare un singolo studente |
| **`mattone-delivery-brain`** | Sandbox privata del founder, spazio di lavoro libero | Solo lui. **Non è la fonte per il team** |
| **`mattone-platform`** | Il codice della piattaforma studenti (`app.mattone.co`) | Chi sviluppa, seguendo la skill dedicata |
| **`mattone-mcp-gateway`** | L'impianto che collega l'assistente AI di uno studente al suo PMS | Chi sviluppa le integrazioni |
| **`mattone-mcp-team`** | L'MCP Delivery: i tool con cui il team lavora a parole sui dati della piattaforma | Chi installa o aggiorna l'MCP Delivery |
| **`mattone-hq`** | Il codice del gestionale interno (soldi, rate, incassi, turni) | Chi sviluppa quel gestionale |
| **`mattone-sito-vetrina`** | Il template del sito vetrina one page che facciamo agli studenti | Chi produce i siti vetrina (team «Siti vetrina») |
| **`mattone-direct-booking-template`** | Il template del sito di prenotazione diretta degli studenti | Chi costruisce un sito direct booking |
| **`mattone-integrations-docs`** | **Archiviato dal 07/09/2026** — non si aggiorna, non ci si aprono PR | Nessuno. Se ti ci ritrovi dentro, hai sbagliato repo |
**I template dei siti degli studenti stanno nell'organizzazione GitHub `Mattone-co`** (dal 11/10/2026): `mattone-sito-vetrina`, `mattone-direct-booking-template` e il playbook `direct-booking-engine-skill`. Il repo del sito di uno studente si crea **lì, dal template, sempre privato**: niente trasferimenti su account personali. Il comando esatto è nel README di ogni template, sezione «Dove si crea il repo».
## Le due sedi che contano
### `mattone-docs` — la documentazione, pubblica
È **l'unica sede della documentazione**. Non esiste un secondo posto dove si scrivono procedure:
se una guida non è qui, per il team non esiste.
Ci va tutto quello che serve a **eseguire un lavoro** e che resta vero anche se lo legge un
estraneo: procedure e runbook, come si usa uno strumento, casistiche in forma anonima, alberi
diagnostici, criteri di lavoro. Non ci vanno nomi di studenti, chiavi, casi singoli.
Il dettaglio di cosa ci va e cosa no è scritto una volta sola, qui: [Prima di scrivere qui
dentro](/contribuire). Leggilo prima della prima PR, non dopo.
### `mattone-delivery-private` — l'archivio del delivery, privato
È dove vive tutto quello che su `mattone-docs` non può stare. Quattro cartelle, quattro scopi:
| Cartella | Cosa c'è | Chi la scrive |
| - | - | - |
| `studenti/` | Una scheda per studente, trovata dall'indice | in parte uno script, in parte le persone |
| `chiavi/` | Il registro delle chiavi: cos'è ciascuna, **dove sta**, chi la usa, come si cambia. Le chiavi di uno studente non stanno qui: stanno nel Vault della piattaforma | chi aggiunge o cambia una chiave |
| `diario/` | Cosa è cambiato, per quale studente, chi deve saperlo | chi chiude un intervento |
| `conoscenza/` | Note tecniche interne, troppo specifiche o troppo sensibili per stare su `docs.mattone.co` | chi scopre qualcosa che qui non può scrivere |
#### Com'è fatta una scheda studente
Una scheda ha una parte **scritta a mano** e una parte **scritta da uno script**, e le due non si
toccano:
* **Dalla platform** — chi è lo studente, che piano ha, cosa ha collegato. La scrive uno script
leggendo la piattaforma.
* **Chi è · Com'è configurato · Da sapere prima di toccarlo · Direzione strategica** — le scrivono
le persone. Sono il valore vero della scheda: quello che sai tu e che nessun sistema sa.
* **Storia** — si riempie da sola: ogni voce chiusa in piattaforma diventa una riga in cima, con un
marcatore invisibile che impedisce i doppioni. Se scrivi tu a mano la riga di una voce, cita il
suo id: lo script la riconosce e non ne aggiunge una seconda.
#### Le quattro regole dell'archivio privato
La scheda si trova dall'indice. **Niente file sciolti per cliente**: un file fuori dall'indice è un file che nessuno riaprirà.
È la piattaforma a dire chi è lo studente e cosa ha collegato. Se quel blocco è sbagliato, **si corregge in piattaforma** e si rilancia lo script — non si corregge la scheda, che al giro dopo tornerebbe com'era.
Non si scrive **solo** nella scheda. Una voce ha un responsabile, una data e una coda che la tiene d'occhio; un paragrafo in un file no. Nella scheda resta la storia: cosa è cambiato e quale voce era.
Il registro dice **cos'è** ogni chiave, **dove sta** e **chi la usa**. Per le chiavi di uno studente la risposta è sempre la stessa: il **Vault della piattaforma**, mai un repository — nemmeno questo. Si usano dal proprio MCP Delivery, senza vederle. Per ogni altra chiave, **dove va lo decide il founder**: se devi aggiungerne una, chiedi prima invece di scegliere tu.
**`mattone-delivery-brain` non è `mattone-delivery-private`.** Hanno tutti e due una cartella
`studenti/` e si somigliano abbastanza da confondere. Il primo è la sandbox personale del founder —
uno spazio di lavoro libero, non allineato, non la fonte per nessun altro. Il secondo è la base
condivisa del delivery. Se stai cercando la scheda di uno studente per lavorarci, è sempre il
secondo.
## I repo di codice
Non si toccano «al volo»: ognuno ha una regola che, se salti, si paga in produzione.
| Repo | Cosa sapere prima di aprirlo |
| - | - |
| **`mattone-platform`** | Si sviluppa **solo** seguendo la skill dedicata (regole di login e di deploy obbligatorie). Le PR le rivede il founder prima del merge: nessun merge in autonomia |
| **`mattone-mcp-gateway`** | ⚠️ Qui **il merge È il deploy**: la produzione si aggiorna da sola quando il ramo principale cambia. Non c'è un passaggio intermedio in cui accorgersi dell'errore |
| **`mattone-mcp-team`** | Il pezzo che ogni persona del team installa sul proprio Claude. Una modifica qui arriva sui computer di tutti |
| **`mattone-hq`** | Tocca numeri che poi qualcuno usa per pagare o per farsi pagare. Si verifica due volte |
| **`mattone-sito-vetrina`** | Template uguale per tutti con poche personalizzazioni. Niente numeri inventati e niente testimonianze finte: se lo studente parte da zero, quelle sezioni non esistono |
**Regola comune a tutti i repo Mattone: si lavora su un ramo e si apre una PR. Mai un commit
diretto sul ramo principale, mai un merge in autonomia.** Le PR le rivede il founder di persona
prima del merge.
## Come si decide dove scrivere, in tre domande
«Su un cliente con due appartamenti sullo stesso account il sync non partiva» → **sì**, è una procedura: `mattone-docs`.
«Su quel cliente lì il sync non partiva» → **no**, è un caso: archivio privato.
Compensi, tariffe, margini, importi, email, numeri di telefono, nomi di aziende clienti → archivio privato, **sempre**, anche di sfuggita, anche in un esempio.
Un token, una password, una chiave: **qui dentro mai**, in nessuna forma — nemmeno finta, nemmeno scaduta. Le chiavi di uno studente stanno nel Vault della piattaforma e si usano dal proprio MCP Delivery. Per qualunque altra chiave, chiedi dove va: non deciderlo da solo e non parcheggiarla qui «per intanto».
Il test finale è sempre lo stesso: **«se questa pagina finisse su LinkedIn domani, con il mio nome
sopra, mi darebbe fastidio?»**. Se la risposta è sì o anche solo forse, non va su `mattone-docs`.
## Da verificare
Due punti che questa pagina **non** afferma perché non sono stati verificati, e che vanno chiusi
prima di darli per buoni:
* **Quale repo serve quali indirizzi oltre a `app.mattone.co`.** Esistono repo distinti per l'area
commerciale e per il gestionale operativo, ma la corrispondenza esatta indirizzo → repo non è
stata misurata.
* **Il sito vetrina e la dashboard pubblica.** Ci sono due repo che si presentano entrambi come
«copia canonica». Prima di lavorarci, chiedi quale dei due è quello buono.
## Riferimenti
Cosa ci va, cosa non ci va mai, e cosa fare se l'hai già scritto
Il primo smistamento di un ticket per tema
Il collegamento con cui il team lavora a parole sui dati della piattaforma
Come si aggiorna e si pubblica una pagina
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.