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

# Onboarding studente Mattone: la procedura completa

> Guida completa ai sei step obbligatori per attivare un nuovo studente su Mattone: dall'anagrafica Notion fino alla verifica finale con smoke test.

L'onboarding **non è una sequenza rigida uguale per tutti**: prima ci sono i **preliminari comuni** (Fase 0), poi si sceglie il **percorso giusto** in base al tipo di studente. All'interno del ramo operativo, però, l'ordine dei sei step conta: ogni step costruisce le fondamenta del successivo (Conduit non legge le prenotazioni senza il PMS, il PMS non sa quali appartamenti gestire senza l'anagrafica Notion).

<Warning>
  **GATE DI ATTIVAZIONE CONDUIT, a chi fa l'onboarding.** **Non attivare il workspace Conduit** di uno studente se non ha **entrambe** queste cose:

  1. **Contratto "Servizio AI Ospiti" FIRMATO.**
  2. **Carta a file nella piattaforma** (metodo di pagamento aggiunto dallo studente).

  Se manca **anche solo una** delle due → **NON attivare il workspace. Nessuna eccezione.** Dove si verifica: `contract_signed = true` e **presenza della carta** (metodo di pagamento) nella piattaforma / area billing dello studente. Dettagli nello [Step 3 · Conduit](/onboarding/3-conduit).
</Warning>

<Warning>
  Dentro il ramo operativo, l'ordine non è casuale, saltare uno step rompe ciò che viene dopo. Ma un pezzo che lo studente "per ora non fa" si segna **"non ora"**, non si cancella.
</Warning>

## Fase 0, Preliminari (comuni a tutti, prima di ogni integrazione)

Da fare **sempre**, prima di collegare qualsiasi cosa:

<Steps>
  <Step title="Contratti & amministrazione">Contratto firmato, dati di fatturazione e aspetti amministrativi a posto. Per chi attiva **Conduit**: l'attivazione richiede **contratto firmato + carta a file** (entrambi gate). Il contratto è l'**Addendum "Servizio AI Ospiti"** (Mattone.co LLC ↔ studente), firmato **prima** dell'attivazione, regola canone €9/Listing/mese, Costi a Consumo, durata minima 12 mesi e addebito ricorrente su carta. Vedi [Step 3 · Conduit](/onboarding/3-conduit) e, per il mancato pagamento, [Mancato pagamento](/delivery/mancato-pagamento).</Step>
  <Step title="Account piattaforma">Account su `app.mattone.co`, accesso allo studente, profilo con i `tools_access` giusti.</Step>
  <Step title="Preliminari e allineamento">Cosa vuole lo studente, quali tool userà, quali gestionali/immobili ha. Da qui si sceglie il percorso.</Step>
</Steps>

## Poi: percorsi diversi per tipo di studente

Non tutti partono dallo stesso punto. Scegli il ramo in base al profilo:

| Profilo studente                            | Da dove parte     | Step successivi                                                    |
| ------------------------------------------- | ----------------- | ------------------------------------------------------------------ |
| **Marketing-first** (vuole lead)            | GHL / Marketing   | prima GHL (lead, ROAS); Kross/Conduit solo quando gestisce affitti |
| **Operations-first** (già gestisce affitti) | Kross → Conduit   | anagrafica Notion → PMS Kross → Conduit; marketing dopo (o mai)    |
| **Full**                                    | percorso completo | tutti i sei step nell'ordine sotto                                 |
| **Revenue/pricing**                         | PriceLabs         | collega PriceLabs; il resto secondo il caso                        |

<Tip>I **passaggi custom** (numeri, fee, link nelle skill; PMS diverso da Kross; presenza/assenza di smart-lock o Stripe) si adattano per singolo studente: cambia la **config**, non la procedura.</Tip>

## Passi facili da dimenticare (ma che contano)

* **Accesso al Meta Business Manager (BM)**: chiedilo **presto**. Serve per abilitare la **WABA** (WhatsApp ufficiale) **e** per le **campagne marketing**. Meglio farsi dare accesso al **BM dello studente** (come partner, per ID, mai la password). Vedi [WABA / Meta BM](/integrazioni/waba/panoramica).
* **GHL (marketing)**: si crea un **nuovo Sub-Account** per lo studente, si **importa il nostro Snapshot** (workflow/pipeline/funnel), si **double-checka**, poi si crea il **PIT** e si collega. Vedi [PIT & location](/integrazioni/ghl/pit-location).
* **Operations** (gestione operativa: pulizie, revenue/EBITDA): si collega al gestionale quando serve la parte operativa/finanziaria. ⚠️ Collegamento Operations↔Kross **in verifica per tutti gli studenti** → fai sempre il test. Vedi [Operations](/integrazioni/operations/panoramica).
* **Reconciliation** (riconciliazione bancaria, Revolut): opzionale, per chi vuole quadrare gli incassi. **In miglioramento**. Vedi [Reconciliation](/integrazioni/operations/reconciliation).

## Il percorso operativo (ramo Operations/Full), in sei step

<Steps>
  <Step title="Anagrafica & Notion">
    Crea e allinea il registro appartamenti su Notion. Questo database è la fonte canonica per KB, listino prezzi e contratti. Tutto il resto dipende da qui.

    → [Vai allo Step 1](/onboarding/1-anagrafica-notion)
  </Step>

  <Step title="PMS, KrossBooking">
    Collega il PMS KrossBooking allo studente. Solo dopo questa connessione Conduit può leggere prenotazioni, dati ospite e stato check-in in tempo reale.

    → [Vai allo Step 2](/onboarding/2-pms-kross)
  </Step>

  <Step title="Conduit">
    Configura l'agente AI: crea la KB per-listing a partire da Notion, monta i custom tool (Kross, Shelly, Stripe) ciascuno con la sua skill, definisci i workflow e gestisci il canale telefonico/WABA.

    → [Vai allo Step 3](/onboarding/3-conduit)
  </Step>

  <Step title="Smart check-in">
    **Solo se lo studente ha una smart lock.** Configura l'apertura porta da link (Shelly relay o SwitchBot Smart Lock) e testa un'apertura reale prima di procedere.

    → [Vai allo Step 4](/onboarding/4-smart-checkin)
  </Step>

  <Step title="Pagamenti, Stripe">
    Collega Stripe con una **chiave a permessi minimi** (Restricted Key) in modo che Conduit possa generare link di pagamento per extra e upsell direttamente in chat con l'ospite.

    → [Vai allo Step 5](/onboarding/5-pagamenti-stripe)
  </Step>

  <Step title="Verifica finale">
    Prima di dichiarare lo studente attivo, esegui la checklist completa e lo smoke test. Ogni punto deve essere confermato leggendo i log reali, non solo guardando la UI.

    → [Vai allo Step 6](/onboarding/6-verifica-finale)
  </Step>
</Steps>

## Regole trasversali

Queste due regole si applicano a **tutti** gli step e a qualsiasi intervento futuro sullo studente.

**Leggi sempre i log.** L'interfaccia può mostrare "verde" anche quando qualcosa non funziona. Il log è l'unica prova che un'operazione è andata a buon fine. Apri il pannello log dopo ogni azione significativa.

**Ogni tool vuole la sua skill.** In Conduit, un custom tool senza la skill di prompting abbinata viene ignorato dall'agente. Non installare mai un tool senza configurare contestualmente la skill corrispondente.

## Stati studente & handoff (per lavorare in due, a turni)

Pensa a una **matrice passi × stato** per studente, non a una lista lineare: ogni passo ha il suo stato e persone diverse a turni riprendono da dove si è arrivati.

| Stato                         | Significato                                                                                                                            |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **non iniziato**              | nessuna connessione salvata                                                                                                            |
| **non ora / non applicabile** | lo studente per ora non fa questo pezzo → si passa al successivo, ma **lo step resta** nel checklist (segnato "non ora"), non sparisce |
| **in corso**                  | credenziali inserite, non ancora validate                                                                                              |
| **collegato**                 | connessione salvata (ma "connected" ≠ "funziona")                                                                                      |
| **verificato**                | testato dal vivo con auth/azione reale                                                                                                 |

<Warning>Il "non ora" **non è uno skip che perde il pezzo**: lo step resta visibile e ripescabile. Chi subentra deve vedere che quel passo è stato consapevolmente rimandato, non dimenticato.</Warning>

### Dipendenze di fase (passi distinti anche se sembrano lo stesso)

* **Kross caricato in piattaforma** ≠ **Kross collegato a Conduit**: il primo è le 3 credenziali salvate e validate nel Vault (fase PMS); il secondo è il montaggio dei tool nell'agente (fase Conduit, in un altro momento).
* I **custom tool** possono essere preparati **prima/indipendentemente** dal resto della fase Conduit.
* **Smart-lock** e **Stripe** sono condizionali: possono restare "non ora" a lungo senza bloccare gli altri.

**Dove si leggono oggi gli stati**: tabella `pms_integrations` (Supabase) per lo stato per-connettore, pagina **`/connessioni`** (vista studente), **Vault** per la presenza delle credenziali cifrate. Per capire **a che punto è** uno studente e **come riprenderlo** (handoff tra membri del team), vedi [Stato & continuazione](/onboarding/stato-e-continuazione).

<Warning>**GAP noto**: non esiste ancora un **tracker unico** (matrice passi×stato, con "non ora" e handoff) per il team delivery. Oggi lo si ricostruisce da `pms_integrations` + `/connessioni` + Vault. Da gestire lato piattaforma. Vista d'insieme volumi: [Delivery a volumi](/delivery/flusso-completo).</Warning>

<Note>
  Se rimani bloccato su uno qualsiasi degli step, consulta prima la pagina [Metodo di troubleshooting](/troubleshooting/metodo), descrive il processo sistematico per diagnosticare qualsiasi problema sulla piattaforma prima di escalare.
</Note>