Onboarding cinematic · spec F-1 (post-gate 10 giu)

Decisione founder F-1 (2026-05-26 sera) verbatim: "subito dopo vede il sistema e l'onboarding viene fatto volando da un pianeta all'altro con un anello di percentuale di completamento e le varie domande semplici per farsi dare tutti i dati e le informazioni utili".

Status: spec scritta 2026-05-27. Implementazione tecnica posticipata al 15 giugno 2026 (MVP+ market-ready), dopo il gate del 10 giugno (MVP + 5 paganti). Il founder ha esplicitamente classificato F-1 come "ultimo nell'ordine di esecuzione, post gate 10 giu se serve sacrificare". Per i primi 5 paganti basta l'onboarding chiavi-in-mano umano (F-3).

Stima implementazione: 16-24 ore (R3F flight choreography + state machine + form sector-aware + persistenza progressiva). Owner: Gregorio (R3F) + Loris (contenuti domande settoriali).

Vision

Subito dopo signup e pagamento, il cliente non vede una pagina di setup classica con form lunghi. Vede il sistema in funzione: il sistema solare Multiverbe, vivo, in alto un anello di completamento all'X%, e una telecamera che lo porta automaticamente sul primo pianeta del suo tier. Lì compaiono 2-4 domande semplici, lui risponde, l'anello attorno al pianeta si riempie, la telecamera vola sul pianeta successivo. Quando tutti i pianeti del tier hanno l'anello pieno, l'anello globale arriva a 100% e il sistema dice "Sei dentro. Adesso lavoro per te."

Non è un wizard a schermate. È un tour cinematografico nel prodotto.

Differenze rispetto all'onboarding chiavi-in-mano umano (F-3)

Aspetto	F-3 · chiavi-in-mano umano	F-1 · cinematic flight-tour
Quando	Day 1 dal pagamento, 60 minuti con Loris/founder via Meet	Immediatamente al primo login post-pagamento (e già durante trial 10gg per primer)
Chi conduce	Persona reale, voce, condivisione schermo	Solo il sistema · zero umani
Profondità setup	Brand memory completa, sito generato, configurazioni avanzate	Dati base, preferenze settoriali, 60 secondi al primo "wow"
Costo per cliente	~60 min di Loris/founder	Zero marginale
Quando si applica	Tutti i clienti paganti (decisione F-3)	Tutti i clienti paganti + trial users
Coesistenza	F-1 è il primo contatto self-serve · F-3 è la sessione approfondita successiva	I due si rinforzano · F-1 prepara F-3

Sono complementari: F-1 abbatte la paura iniziale e fa vedere il prodotto vivo, F-3 trasforma quella prima impressione in setup professionale.

Architettura tecnica

Stack

R3F + drei (già in uso per il sistema solare · vedi canon/05-stack.md e skill multiverbe-r3f-patterns)
CameraRig esistente in frontend/multiverbe-app/src/components/3d/CameraRig.tsx (gestisce già spring damp3 fly-to per click pianeta · ri-uso il pattern)
State machine onboarding con Zustand store dedicato useOnboardingStore (NON useDashboardStore, separato per chiarezza · si auto-distrugge al completamento)
Form sector-aware: SetupWizardV2 esistente fornisce gli schemi per macro categoria · ri-uso sectors-fallback.ts + useSectors.ts
Persistenza progressiva: ogni risposta scrive subito su workspaces.onboarding_progress jsonb (resume se chiude e riapre)

State machine (semplificato)

states:
  intro          // 3 secondi · "Benvenuto" + zoom-out sistema solare
  fly_to_planet  // CameraRig fly-to verso pianeta[i] · 1.8s
  ask_questions  // form 2-4 domande overlay accanto al pianeta · attende input
  fill_ring      // anello pianeta si riempie · 0.6s · haptic success
  next_planet    // i++ · loop a fly_to_planet
  complete       // tutti i pianeti pieni · anello globale a 100% · fly-out su sistema completo
  exit           // 1s di "Sei dentro." · navigazione automatica a /home

Numero pianeti = useTierPlanets().unlocked.length (3 per Starter, 5 per Pro, 6 per Business).

Anello di completamento

Anello globale in top-center: <ProgressRing percent={completedPlanets / totalPlanets * 100} /> SVG component (riusa Osservatorio palette). 12 step di 360/12 = 30° per step su Starter (3 pianeti × 4 domande = 12 step).

Anelli per pianeta: ognuno è renderizzato in R3F come <ringGeometry> attorno al <Pianeta> esistente. Riempimento via shader uniform uFillProgress 0 → 1. Stesso shader del ring di Sales (Pianeta.tsx linea 122) generalizzato.

Form sector-aware integrato visivamente

Le domande appaiono come glass overlay accanto al pianeta, NON come modal o sheet. Mantiene la metafora "il sistema lavora attorno a te". Pattern stile PlanetDashboard esistente (glass material identico a PlanetSidebar).

Per ogni pianeta del tier, 2-4 domande specifiche per macro settore. Esempi:

Pianeta Web (tutti i tier):

"Hai già un sito o lo creiamo da zero?" (dropdown: nessuno / Wix / WordPress / altro)
"Il dominio è già tuo?" (Sì / No)
"Tre parole che descrivono il tuo brand?" (input libero)
"Mostra il logo se ce l'hai." (upload opzionale)

Pianeta Booking (tutti i tier · domande adattive per settore):

Ristorazione: "Coperti totali per turno?" + "Hai due turni di servizio?"
Parrucchieri: "Durata media servizio principale?" + "Quanti collaboratori prendono prenotazioni?"
Studi pro: "Vuoi che i clienti prenotino direttamente?" (booking pubblico vs interno)

Pianeta CRM (tutti i tier):

"Quanti contatti hai oggi nel tuo strumento attuale?" (range slider)
"Vuoi che importiamo da Excel/Outlook/altro?" (sì → upload form successivo)

Pianeta Content (Pro+):

"Su quali canali pubblichi oggi?" (multi-select Instagram/Facebook/LinkedIn/TikTok)
"Tono di voce: formale, casuale, o ironico?"

Pianeta Sales (Pro+):

"Hai venditori esterni?" (numero · 0-5+)
"Fai cold outreach via email oggi?"

Pianeta Marketing (Business only):

"Stai facendo ads oggi?" (Google, Meta, LinkedIn, TikTok · multi-select)
"Budget mensile orientativo?" (range)

Le domande vengono lette da sectors-fallback.ts (esteso con field onboarding_questions: OnboardingQuestion[]) o da DB se la tabella sectors.onboarding_questions_json viene aggiunta.

Skip e ripresa

Skip pianeta: ogni overlay ha "Salta · lo configuriamo dopo". Riempie comunque l'anello al 50% (skip rilevato).
Pausa: cliente chiude tab → state machine persiste su workspaces.onboarding_progress jsonb. Al re-login: prompt "Continui da dove avevi lasciato?" con preview dei pianeti già completati.
Saltare tutto: link discreto in basso "Vado direttamente alla dashboard". Apre confirm dialog "Sicuro? L'AI lavora meglio se sa di te. Puoi sempre riprendere dalle Impostazioni." → se conferma, redirect /home con onboarding_status: skipped.

Performance

R3F: la scena di onboarding è la stessa di NucleoSphere.tsx con visiblePlanets = unlocked tier. Niente shader aggiuntivi rispetto a F-2.
Animazione anello: SVG nel DOM in overlay top-center · zero costo R3F.
Form overlay: DOM puro · zero drawcall aggiuntivo.
Target FPS: 60 desktop, 30+ mobile (allineato al canon multiverbe-r3f-patterns).
Tempo medio onboarding: 3 minuti per Starter (3 pianeti × ~50 secondi), 4 minuti per Pro (5 pianeti), 5 minuti per Business (6 pianeti).

Edge case

Tier downgrade in corso: se cliente downgrade da Pro a Starter mentre l'onboarding è a metà di un pianeta gated (es. Content), il sistema chiude quel pianeta e salta al successivo, l'anello globale ricalcola al volo.
Mobile: scena 3D resta full-screen come desktop · l'overlay form passa in bottom-sheet (pattern già usato in PlanetDashboard mobile).
Reduced motion: se prefers-reduced-motion, il CameraRig fa cut secco invece di fly-to. Stesso pattern NucleoSphere.tsx linea 75.
Errore form sector mai scelto: se il cliente arriva senza aver completato SetupWizardV2 (vecchio onboarding pre-rebuild), parte un blocco "Prima dimmi che settore sei" prima del flight-tour. Riusa il chat-based sector detection AI fallback (skill multiverbe-sector-onboarding).

Metriche di successo

Metrica	Target	Soglia critica
Tasso di completamento onboarding cinematic	≥ 70%	< 50%
Time to first wow (al primo "ah figo!" intuibile dal click sul primo pianeta)	< 60 secondi	> 120 secondi
Skip rate complessivo	< 15%	> 30%
Mobile completion vs desktop	desktop -10% accettabile	mobile < 50% del desktop
Frame rate medio durante fly-to	> 50 fps desktop · > 28 fps mobile	< 30 fps desktop

Da loggare in entity_interactions con planet = 'cross' e interaction_type = 'onboarding_flight_step'.

Roadmap implementazione

Fase A (chiusa 2026-05-27 · documentale):

✅ Spec dettagliata in questo file
✅ Decisione formalizzata in decisions-log v58/v59

Fase B (target 11-15 giugno 2026, 16-24h):

[ ] B1 (3h) · useOnboardingStore Zustand + types state machine
[ ] B2 (4h) · OnboardingFlight.tsx skeleton con CameraRig ri-uso + intercept onSelectChange
[ ] B3 (5h) · 6 schemi onboarding_questions per macro categoria · estensione sectors-fallback.ts
[ ] B4 (4h) · OnboardingQuestionOverlay.tsx glass material posizionato accanto al pianeta corrente
[ ] B5 (3h) · ProgressRing globale top-center + ring per pianeta R3F shader uniform
[ ] B6 (2h) · persistenza progressiva su workspaces.onboarding_progress + resume flow
[ ] B7 (2h) · skip e abort flows + reduced-motion fallback + mobile bottom-sheet
[ ] B8 (1h) · loggin metrics entity_interactions cross-planet

Fase B PR: branch dedicato feat/onboarding-cinematic-flight, worktree separato, drift detector hard gate (qualsiasi nuova colonna workspaces.onboarding_progress richiede rigen types/supabase.ts nella stessa PR).

Open questions per founder (pre fase B)

Onboarding cinematic anche per il trial 10gg? Si attiva al primo login del trial (prima del pagamento), oppure solo dopo pagamento (per non "bruciare" il momento wow su utenti free)?
Numero domande per pianeta: scelgo io 2-4 per pianeta o vuoi una review prima della fase B?
Voce narrante audio? Posso aggiungere un narratore (founder voice cloned o stock male italian voice) che guida la flight con micro-frasi tipo "Adesso voliamo sul tuo Pianeta Web". Add-on opzionale.
Brand video opener (5 secondi): vuoi un breve intro brand prima del flight-tour, oppure va dritto sul sistema solare?

Last update: 2026-05-27 · creazione · F-1 fase A chiusa (documentale). Owner: Gregorio (architettura R3F) + Loris (contenuti domande settoriali) + Claude (implementazione assistita). Skill di riferimento: multiverbe-r3f-patterns · multiverbe-sector-onboarding.