From 56026e45a4024fcb9e384d026eddb63e77197988 Mon Sep 17 00:00:00 2001
From: astropuzzo <gianmarcospagnoli345@gmail.com>
Date: Wed, 29 Jul 2026 18:00:17 +0200
Subject: [PATCH 1/2] feat(onboarding): add guided first-run setup

---
 assets/i18n/en.json                           | 40 +++++++++++++++
 docs/CHANGELOG.md                             | 10 ++++
 docs/PIANO_READY_TO_SELL.md                   |  2 +
 dotnet/AstroForge.App/MainWindow.xaml         | 50 +++++++++++--------
 dotnet/AstroForge.App/MainWindow.xaml.cs      | 24 ++++++++-
 .../AstroForge.CrossPlatform/MainWindow.axaml | 42 ++++++++++++++--
 .../MainWindow.axaml.cs                       | 50 ++++++++++++++++++-
 scripts/check-ui-contract.ps1                 |  2 +
 version.json                                  |  4 +-
 9 files changed, 191 insertions(+), 33 deletions(-)

diff --git a/assets/i18n/en.json b/assets/i18n/en.json
index 999c286..08c2e11 100644
--- a/assets/i18n/en.json
+++ b/assets/i18n/en.json
@@ -438,4 +438,44 @@
   ,"Temperatura": "Temperature"
   ,"Tipo": "Type"
   ,"VERIFICA": "CHECK"
+  ,"+ Aggiungi Master Library": "+ Add Master Library"
+  ,"+ Singoli file": "+ Individual files"
+  ,"↑ Priorità": "↑ Priority"
+  ,"↓ Priorità": "↓ Priority"
+  ,"Camera, gain, offset e temperatura determinano gli abbinamenti.": "Camera, gain, offset and temperature determine matching."
+  ,"Collega le calibrazioni, importa le immagini e avvia la prima analisi. Nessun originale viene modificato.": "Connect calibrations, import images and start the first analysis. Original files are never modified."
+  ,"Collega librerie, importa immagini e avvia l’analisi": "Connect libraries, import images and start analysis"
+  ,"Collega una o più raccolte di Master. Camera, gain, offset e temperatura determinano gli abbinamenti.": "Connect one or more Master collections. Camera, gain, offset and temperature determine matching."
+  ,"Dark e Bias automatici": "Automatic Dark and Bias"
+  ,"facoltativa": "optional"
+  ,"Gli originali restano in sola lettura.": "Original files remain read-only."
+  ,"Gli originali restano sempre in sola lettura.": "Original files always remain read-only."
+  ,"Hai già una Master Library?": "Do you already have a Master Library?"
+  ,"Il programma leggerà gli header, ricostruirà le notti e proporrà Flat, Dark e Bias.": "The app will read headers, reconstruct observing nights and suggest Flat, Dark and Bias frames."
+  ,"Il programma leggerà gli header, ricostruirà le notti osservative e proporrà gli abbinamenti Flat, Dark e Bias.": "The app will read headers, reconstruct observing nights and suggest Flat, Dark and Bias matches."
+  ,"Immagini": "Images"
+  ,"IMMAGINI DEL PROGETTO": "PROJECT IMAGES"
+  ,"Importa le acquisizioni": "Import your acquisitions"
+  ,"In pochi passaggi colleghi le calibrazioni, importi le immagini e avvii la prima analisi. Nessun originale viene modificato.": "In a few steps you can connect calibrations, import images and start the first analysis. Original files are never modified."
+  ,"Master Library": "Master Library"
+  ,"MASTER LIBRARY": "MASTER LIBRARY"
+  ,"Non ce l’hai? Continua senza: potrai aggiungerla o crearne una in qualsiasi momento.": "Do not have one? Continue without it: you can add or create one at any time."
+  ,"Non ce l’hai? Continua senza: potrai aggiungerla o crearne una in seguito.": "Do not have one? Continue without it: you can add or create one later."
+  ,"Passo 1 · Calibrazioni": "Step 1 · Calibrations"
+  ,"Passo 2 · Immagini": "Step 2 · Images"
+  ,"Pronto per la prima analisi": "Ready for the first analysis"
+  ,"Puoi aggiungerne più di una e ordinarle per priorità.": "You can add more than one and order them by priority."
+  ,"Puoi aggiungerne più di una.": "You can add more than one."
+  ,"Raccoglie Dark e Bias riutilizzabili. Camera, gain, offset, temperatura ed esposizione determinano gli abbinamenti automatici.": "It contains reusable Dark and Bias frames. Camera, gain, offset, temperature and exposure determine automatic matching."
+  ,"Salta": "Skip"
+  ,"Scegli cartelle complete oppure singoli file FITS/XISF provenienti da qualsiasi software con header utilizzabili.": "Choose complete folders or individual FITS/XISF files from any software with usable headers."
+  ,"Scegli cartelle complete oppure singoli file. Sono accettati FITS e XISF provenienti da qualsiasi software, purché contengano metadati utilizzabili.": "Choose complete folders or individual files. FITS and XISF files from any software are accepted when they contain usable metadata."
+  ,"Scegli una cartella contenente Master Dark e Bias": "Choose a folder containing Master Dark and Bias frames"
+  ,"sessioni e calibrazioni": "sessions and calibrations"
+  ,"Sì, aggiungi libreria": "Yes, add a library"
+  ,"SORGENTI": "SOURCES"
+  ,"Una Master Library raccoglie Dark e Bias riutilizzabili. Il programma sceglie quelli compatibili usando camera, gain, offset, temperatura ed esposizione.": "A Master Library contains reusable Dark and Bias frames. The app selects compatible ones using camera, gain, offset, temperature and exposure."
+  ,"Continua senza libreria": "Continue without a library"
+  ,"Analizza ora": "Analyze now"
+  ,"Vai al progetto": "Go to project"
 }
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index f88cce8..658b095 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -1,5 +1,15 @@
 # AstroProject Forge — note di rilascio
 
+## 1.2.0 — 29 luglio 2026
+
+- Il primo avvio usa ora un setup rapido in quattro passaggi: introduzione, Master
+  Library facoltativa, importazione FITS/XISF e riepilogo.
+- Dal passaggio finale è possibile avviare immediatamente l'analisi del progetto.
+- La configurazione iniziale può essere riaperta in qualsiasi momento dal menu.
+- La Master Library è ora presentata come funzione principale, con descrizione,
+  conteggio e un comando di aggiunta ben visibile nel pannello Sorgenti.
+- Lo stesso flusso è disponibile nelle interfacce Windows, Linux e macOS.
+
 ## 1.1.2 — 28 luglio 2026
 
 - Anche gli aggiornamenti avviati dalle versioni precedenti mostrano ora una finestra
diff --git a/docs/PIANO_READY_TO_SELL.md b/docs/PIANO_READY_TO_SELL.md
index 908bb5a..1b71094 100644
--- a/docs/PIANO_READY_TO_SELL.md
+++ b/docs/PIANO_READY_TO_SELL.md
@@ -20,6 +20,8 @@ La stessa logica Core è usata dall'interfaccia Avalonia per Linux e macOS.
 - [x] Nomi e descrizioni per screen reader sui controlli principali.
 - [x] Focus tastiera ad alto contrasto.
 - [x] Avanzamento visibile per download e installazione degli aggiornamenti Windows.
+- [x] Setup rapido operativo al primo avvio, riapribile dal menu.
+- [x] Gestione Master Library evidenziata nel pannello Sorgenti.
 - [ ] Test manuale completo con Narrator su Windows.
 - [ ] Test manuale tastiera, VoiceOver e Orca sui pacchetti nativi.
 
diff --git a/dotnet/AstroForge.App/MainWindow.xaml b/dotnet/AstroForge.App/MainWindow.xaml
index c874fb0..260d894 100644
--- a/dotnet/AstroForge.App/MainWindow.xaml
+++ b/dotnet/AstroForge.App/MainWindow.xaml
@@ -119,6 +119,7 @@
                         <Button Click="ClearCache_Click" HorizontalContentAlignment="Stretch" Margin="0,0,0,6"><Grid><Grid.ColumnDefinitions><ColumnDefinition Width="34"/><ColumnDefinition/></Grid.ColumnDefinitions><TextBlock Text="↻" Foreground="{StaticResource Accent}" FontSize="18" VerticalAlignment="Center"/><StackPanel Grid.Column="1"><TextBlock Text="Rileggi i metadati" FontWeight="SemiBold"/><TextBlock Text="Forza una nuova lettura al prossimo controllo" Style="{StaticResource MutedText}" FontSize="10"/></StackPanel></Grid></Button>
                         <Button Command="{Binding ClearProjectCommand}" Click="CloseMore_Click" HorizontalContentAlignment="Stretch" BorderBrush="#71434A" Margin="0,0,0,12"><Grid><Grid.ColumnDefinitions><ColumnDefinition Width="34"/><ColumnDefinition/></Grid.ColumnDefinitions><TextBlock Text="×" Foreground="{StaticResource Danger}" FontSize="20" VerticalAlignment="Center"/><StackPanel Grid.Column="1"><TextBlock Text="Chiudi progetto" FontWeight="SemiBold"/><TextBlock Text="Rimuove i dati dall'app, non i file originali" Style="{StaticResource MutedText}" FontSize="10"/></StackPanel></Grid></Button>
                         <TextBlock Text="AIUTO" Style="{StaticResource Eyebrow}" Margin="4,0,4,8"/>
+                        <Button Click="OpenOnboarding_Click" HorizontalContentAlignment="Stretch" Margin="0,0,0,6"><Grid><Grid.ColumnDefinitions><ColumnDefinition Width="34"/><ColumnDefinition/></Grid.ColumnDefinitions><TextBlock Text="✦" Foreground="{StaticResource Accent}" FontSize="17" VerticalAlignment="Center"/><StackPanel Grid.Column="1"><TextBlock Text="Configurazione iniziale" FontWeight="SemiBold"/><TextBlock Text="Collega librerie, importa immagini e avvia l’analisi" Style="{StaticResource MutedText}" FontSize="10"/></StackPanel></Grid></Button>
                         <Button Click="OpenGuide_Click" HorizontalContentAlignment="Stretch" Margin="0,0,0,6"><Grid><Grid.ColumnDefinitions><ColumnDefinition Width="34"/><ColumnDefinition/></Grid.ColumnDefinitions><TextBlock Text="?" Foreground="{StaticResource Accent}" FontSize="18" FontWeight="Bold" VerticalAlignment="Center"/><StackPanel Grid.Column="1"><TextBlock Text="Guida rapida" FontWeight="SemiBold"/><TextBlock Text="Esempi passo per passo su GitHub" Style="{StaticResource MutedText}" FontSize="10"/></StackPanel></Grid></Button>
                         <Button Click="ReportIssue_Click" HorizontalContentAlignment="Stretch" Margin="0,0,0,6"><Grid><Grid.ColumnDefinitions><ColumnDefinition Width="34"/><ColumnDefinition/></Grid.ColumnDefinitions><TextBlock Text="!" Foreground="{StaticResource Warning}" FontSize="18" FontWeight="Bold" VerticalAlignment="Center"/><StackPanel Grid.Column="1"><TextBlock Text="Segnala un problema" FontWeight="SemiBold"/><TextBlock Text="Apre un modulo guidato su GitHub" Style="{StaticResource MutedText}" FontSize="10"/></StackPanel></Grid></Button>
                         <Button Click="OpenDiagnostics_Click" HorizontalContentAlignment="Stretch" Margin="0,0,0,6"><Grid><Grid.ColumnDefinitions><ColumnDefinition Width="34"/><ColumnDefinition/></Grid.ColumnDefinitions><TextBlock Text="◎" Foreground="{StaticResource Accent}" FontSize="18" VerticalAlignment="Center"/><StackPanel Grid.Column="1"><TextBlock Text="Diagnostica" FontWeight="SemiBold"/><TextBlock Text="Log ed esportazione del file di supporto" Style="{StaticResource MutedText}" FontSize="10"/></StackPanel></Grid></Button>
@@ -164,11 +165,20 @@
                         </ListBox.ItemTemplate>
                     </ListBox>
                     <StackPanel Grid.Row="3" Margin="0,16,0,0">
-                        <TextBlock Text="Librerie di calibrazione" Style="{StaticResource MetaLabel}" />
+                        <Border Style="{StaticResource Card}" Padding="13" Margin="0,0,0,9" Background="#162925" BorderBrush="#397A70">
+                            <StackPanel>
+                                <Grid><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition Width="Auto"/></Grid.ColumnDefinitions>
+                                    <StackPanel><TextBlock Text="MASTER LIBRARY" Style="{StaticResource Eyebrow}"/><TextBlock Text="Dark e Bias automatici" FontSize="16" FontWeight="SemiBold" Margin="0,4,0,0"/></StackPanel>
+                                    <Border Grid.Column="1" Background="#253D38" CornerRadius="10" Padding="9,4" VerticalAlignment="Center"><TextBlock Text="{Binding MasterLibraries.Count, StringFormat={}{0} collegate}" Foreground="{StaticResource Accent}" FontSize="10"/></Border>
+                                </Grid>
+                                <TextBlock Text="Collega una o più raccolte di Master. Camera, gain, offset e temperatura determinano gli abbinamenti." Style="{StaticResource MutedText}" TextWrapping="Wrap" FontSize="10" LineHeight="15" Margin="0,8,0,10"/>
+                                <Button Content="+ Aggiungi Master Library" Click="ChooseLibrary_Click" Style="{StaticResource PrimaryButton}" ToolTip="Scegli una cartella contenente Master Dark e Bias"/>
+                            </StackPanel>
+                        </Border>
                         <ListBox x:Name="MasterLibrariesList" ItemsSource="{Binding MasterLibraries}" SelectedItem="{Binding SelectedMasterLibrary}" Background="Transparent" BorderThickness="0" MaxHeight="170" ScrollViewer.HorizontalScrollBarVisibility="Disabled">
                             <ListBox.ItemTemplate><DataTemplate><Border Background="{StaticResource Bg2}" BorderBrush="{StaticResource Stroke}" BorderThickness="1" CornerRadius="8" Padding="8" Margin="0,0,0,5"><Grid><Grid.ColumnDefinitions><ColumnDefinition Width="22"/><ColumnDefinition/><ColumnDefinition Width="Auto"/></Grid.ColumnDefinitions><CheckBox IsChecked="{Binding Enabled}" VerticalAlignment="Center" ToolTip="Includi questa libreria nell'analisi"/><StackPanel Grid.Column="1"><TextBlock Text="{Binding Name}" FontWeight="SemiBold" TextTrimming="CharacterEllipsis"/><TextBlock Text="{Binding Path}" Style="{StaticResource MutedText}" FontSize="9" TextTrimming="CharacterEllipsis"/></StackPanel><StackPanel Grid.Column="2" Margin="7,0,0,0"><TextBlock Text="{Binding PriorityLabel}" Foreground="{StaticResource Accent}" FontSize="9" TextAlignment="Right"/><TextBlock Text="{Binding Status}" Style="{StaticResource MutedText}" FontSize="9" TextAlignment="Right"/></StackPanel></Grid></Border></DataTemplate></ListBox.ItemTemplate>
                         </ListBox>
-                        <Grid Margin="0,3,0,0"><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition/><ColumnDefinition/><ColumnDefinition/></Grid.ColumnDefinitions><Button Content="+" Click="ChooseLibrary_Click" ToolTip="Aggiungi libreria" Style="{StaticResource CompactIconButton}" Margin="0,0,3,0"/><Button Grid.Column="1" Content="−" Click="RemoveLibrary_Click" ToolTip="Rimuovi dal progetto" Style="{StaticResource CompactIconButton}" Margin="3,0"/><Button Grid.Column="2" Content="↑" Click="MoveLibraryUp_Click" ToolTip="Aumenta priorità" Style="{StaticResource CompactIconButton}" Margin="3,0"/><Button Grid.Column="3" Content="↓" Click="MoveLibraryDown_Click" ToolTip="Riduci priorità" Style="{StaticResource CompactIconButton}" Margin="3,0,0,0"/></Grid>
+                        <Grid Margin="0,3,0,0"><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition/><ColumnDefinition/></Grid.ColumnDefinitions><Button Content="Rimuovi" Click="RemoveLibrary_Click" ToolTip="Rimuovi dal progetto" Margin="0,0,3,0"/><Button Grid.Column="1" Content="↑ Priorità" Click="MoveLibraryUp_Click" ToolTip="Aumenta priorità" Margin="3,0"/><Button Grid.Column="2" Content="↓ Priorità" Click="MoveLibraryDown_Click" ToolTip="Riduci priorità" Margin="3,0,0,0"/></Grid>
                         <Button Content="Aggiorna stato librerie" Click="RefreshLibraries_Click" Margin="0,7,0,0" />
                         <Border Style="{StaticResource Card}" Padding="11" Margin="0,8,0,0" Background="{StaticResource RaisedSurface}">
                             <StackPanel>
@@ -694,35 +704,31 @@
                         <StackPanel x:Name="OnboardingStep1">
                     <TextBlock Text="Configurazione iniziale" Style="{StaticResource Eyebrow}"/>
                     <TextBlock Text="Prepara il primo progetto" FontSize="38" FontWeight="SemiBold" FontFamily="Segoe UI Variable Display" Margin="0,10,0,12"/>
-                    <TextBlock Text="Configura librerie di calibrazione, notte astronomica e sorgenti FITS/XISF." Style="{StaticResource MutedText}" FontSize="15" LineHeight="24" TextWrapping="Wrap" MaxWidth="650" HorizontalAlignment="Left"/>
+                    <TextBlock Text="In pochi passaggi colleghi le calibrazioni, importi le immagini e avvii la prima analisi. Nessun originale viene modificato." Style="{StaticResource MutedText}" FontSize="15" LineHeight="24" TextWrapping="Wrap" MaxWidth="650" HorizontalAlignment="Left"/>
                             <Grid Margin="0,28,0,0"><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition/><ColumnDefinition/></Grid.ColumnDefinitions>
-                    <Border Style="{StaticResource Card}" Margin="0,0,8,0" Background="#102725"><StackPanel><TextBlock Text="01" Style="{StaticResource Eyebrow}"/><TextBlock Text="Importa" FontSize="18" FontWeight="SemiBold" Margin="0,6,0,3"/><TextBlock Text="FITS e XISF" Style="{StaticResource MutedText}"/></StackPanel></Border>
-                    <Border Grid.Column="1" Style="{StaticResource Card}" Margin="4,0" Background="#101F2A"><StackPanel><TextBlock Text="02" Style="{StaticResource Eyebrow}"/><TextBlock Text="Verifica" FontSize="18" FontWeight="SemiBold" Margin="0,6,0,3"/><TextBlock Text="metadati e calibrazioni" Style="{StaticResource MutedText}"/></StackPanel></Border>
-                    <Border Grid.Column="2" Style="{StaticResource Card}" Margin="8,0,0,0" Background="#102725"><StackPanel><TextBlock Text="03" Style="{StaticResource Eyebrow}"/><TextBlock Text="Esporta" FontSize="18" FontWeight="SemiBold" Margin="0,6,0,3"/><TextBlock Text="progetto WBPP" Style="{StaticResource MutedText}"/></StackPanel></Border>
+                    <Border Style="{StaticResource Card}" Margin="0,0,8,0" Background="#102725"><StackPanel><TextBlock Text="01" Style="{StaticResource Eyebrow}"/><TextBlock Text="Master Library" FontSize="18" FontWeight="SemiBold" Margin="0,6,0,3"/><TextBlock Text="facoltativa" Style="{StaticResource MutedText}"/></StackPanel></Border>
+                    <Border Grid.Column="1" Style="{StaticResource Card}" Margin="4,0" Background="#101F2A"><StackPanel><TextBlock Text="02" Style="{StaticResource Eyebrow}"/><TextBlock Text="Immagini" FontSize="18" FontWeight="SemiBold" Margin="0,6,0,3"/><TextBlock Text="FITS e XISF" Style="{StaticResource MutedText}"/></StackPanel></Border>
+                    <Border Grid.Column="2" Style="{StaticResource Card}" Margin="8,0,0,0" Background="#102725"><StackPanel><TextBlock Text="03" Style="{StaticResource Eyebrow}"/><TextBlock Text="Analisi" FontSize="18" FontWeight="SemiBold" Margin="0,6,0,3"/><TextBlock Text="sessioni e calibrazioni" Style="{StaticResource MutedText}"/></StackPanel></Border>
                             </Grid>
                         </StackPanel>
                         <StackPanel x:Name="OnboardingStep2" Visibility="Collapsed">
-                    <TextBlock Text="Passo 1 · Librerie" Style="{StaticResource Eyebrow}"/>
-                    <TextBlock Text="Aggiungi Dark e Bias" FontSize="32" FontWeight="SemiBold" Margin="0,8,0,10"/>
-                    <TextBlock Text="Puoi aggiungere più librerie e ordinarle per priorità." Style="{StaticResource MutedText}" FontSize="14" LineHeight="22" TextWrapping="Wrap"/>
-                            <Border Style="{StaticResource Card}" Background="#102725" Margin="0,24,0,14"><Grid><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition Width="Auto"/></Grid.ColumnDefinitions><StackPanel><TextBlock Text="LIBRERIE COLLEGATE" Style="{StaticResource Eyebrow}"/><TextBlock Text="{Binding MasterLibraries.Count, StringFormat={}{0} configurate}" FontSize="21" FontWeight="SemiBold" Margin="0,6,0,0"/></StackPanel><Button Grid.Column="1" Content="+ Scegli cartella Master" Click="OnboardingChooseLibrary_Click" Style="{StaticResource PrimaryButton}"/></Grid></Border>
-                    <TextBlock Text="Le librerie possono essere modificate in seguito." Style="{StaticResource MutedText}" TextWrapping="Wrap"/>
+                    <TextBlock Text="Passo 1 · Calibrazioni" Style="{StaticResource Eyebrow}"/>
+                    <TextBlock Text="Hai già una Master Library?" FontSize="32" FontWeight="SemiBold" Margin="0,8,0,10"/>
+                    <TextBlock Text="Una Master Library raccoglie Dark e Bias riutilizzabili. Il programma sceglie quelli compatibili usando camera, gain, offset, temperatura ed esposizione." Style="{StaticResource MutedText}" FontSize="14" LineHeight="22" TextWrapping="Wrap"/>
+                            <Border Style="{StaticResource Card}" Background="#102725" BorderBrush="#397A70" Margin="0,24,0,14" Padding="20"><Grid><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition Width="Auto"/></Grid.ColumnDefinitions><StackPanel><TextBlock Text="MASTER LIBRARY" Style="{StaticResource Eyebrow}"/><TextBlock Text="{Binding MasterLibraries.Count, StringFormat={}{0} collegate}" FontSize="24" FontWeight="SemiBold" Margin="0,6,0,3"/><TextBlock Text="Puoi aggiungerne più di una e ordinarle per priorità." Style="{StaticResource MutedText}"/></StackPanel><Button Grid.Column="1" Content="Sì, aggiungi libreria" Click="OnboardingChooseLibrary_Click" Style="{StaticResource PrimaryButton}" Padding="20,11"/></Grid></Border>
+                    <TextBlock Text="Non ce l’hai? Continua senza: potrai aggiungerla o crearne una in qualsiasi momento." Style="{StaticResource MutedText}" TextWrapping="Wrap"/>
                         </StackPanel>
                         <StackPanel x:Name="OnboardingStep3" Visibility="Collapsed">
-                    <TextBlock Text="Passo 2 · Acquisizione" Style="{StaticResource Eyebrow}"/>
-                    <TextBlock Text="Imposta i valori mancanti" FontSize="32" FontWeight="SemiBold" Margin="0,8,0,10"/>
-                    <TextBlock Text="I valori predefiniti vengono usati solo quando il metadato non è disponibile." Style="{StaticResource MutedText}" TextWrapping="Wrap"/>
-                            <Grid Margin="0,24,0,0"><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition/><ColumnDefinition/></Grid.ColumnDefinitions>
-                                <StackPanel Margin="0,0,8,0"><TextBlock Text="Cambio notte (ora locale)" Style="{StaticResource MetaLabel}"/><TextBox Text="{Binding SessionBoundaryHour, UpdateSourceTrigger=PropertyChanged}" HorizontalContentAlignment="Center" Tag="Cambio notte (ora locale)"/></StackPanel>
-                                <StackPanel Grid.Column="1" Margin="4,0"><TextBlock Text="Gain predefinito" Style="{StaticResource MetaLabel}"/><TextBox Text="{Binding ProjectDefaultGain, UpdateSourceTrigger=PropertyChanged}" HorizontalContentAlignment="Center" Tag="Gain predefinito"/></StackPanel>
-                                <StackPanel Grid.Column="2" Margin="8,0,0,0"><TextBlock Text="Offset predefinito" Style="{StaticResource MetaLabel}"/><TextBox Text="{Binding ProjectDefaultOffset, UpdateSourceTrigger=PropertyChanged}" HorizontalContentAlignment="Center" Tag="Offset predefinito"/></StackPanel>
-                            </Grid>
-                            <Border Style="{StaticResource Card}" Background="#101F2A" Margin="0,22,0,0"><Grid><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition Width="Auto"/><ColumnDefinition Width="Auto"/></Grid.ColumnDefinitions><StackPanel><TextBlock Text="SORGENTI FITS / XISF" Style="{StaticResource Eyebrow}"/><TextBlock Text="{Binding SourcePaths.Count, StringFormat={}{0} sorgenti importate}" FontSize="20" FontWeight="SemiBold" Margin="0,5,0,0"/><TextBlock Text="N.I.N.A., ASIAIR, SGP, Voyager, SharpCap o altri software" Style="{StaticResource MutedText}" FontSize="10"/></StackPanel><Button Grid.Column="1" Content="+ File" Click="OnboardingAddFiles_Click" Margin="8,0,0,0"/><Button Grid.Column="2" Content="+ Cartelle" Click="OnboardingAddSource_Click" Margin="8,0,0,0"/></Grid></Border>
+                    <TextBlock Text="Passo 2 · Immagini" Style="{StaticResource Eyebrow}"/>
+                    <TextBlock Text="Importa le acquisizioni" FontSize="32" FontWeight="SemiBold" Margin="0,8,0,10"/>
+                    <TextBlock Text="Scegli cartelle complete oppure singoli file. Sono accettati FITS e XISF provenienti da qualsiasi software, purché contengano metadati utilizzabili." Style="{StaticResource MutedText}" FontSize="14" LineHeight="22" TextWrapping="Wrap"/>
+                            <Border Style="{StaticResource Card}" Background="#101F2A" BorderBrush="#3B607E" Margin="0,24,0,0" Padding="20"><Grid><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition Width="Auto"/><ColumnDefinition Width="Auto"/></Grid.ColumnDefinitions><StackPanel><TextBlock Text="IMMAGINI DEL PROGETTO" Style="{StaticResource Eyebrow}"/><TextBlock Text="{Binding SourcePaths.Count, StringFormat={}{0} sorgenti importate}" FontSize="24" FontWeight="SemiBold" Margin="0,5,0,3"/><TextBlock Text="Gli originali restano sempre in sola lettura." Style="{StaticResource MutedText}"/></StackPanel><Button Grid.Column="1" Content="+ Singoli file" Click="OnboardingAddFiles_Click" Margin="12,0,0,0" Padding="18,11"/><Button Grid.Column="2" Content="+ Cartelle" Click="OnboardingAddSource_Click" Style="{StaticResource PrimaryButton}" Margin="8,0,0,0" Padding="18,11"/></Grid></Border>
                         </StackPanel>
                         <StackPanel x:Name="OnboardingStep4" Visibility="Collapsed" HorizontalAlignment="Center" VerticalAlignment="Center" MaxWidth="590">
                             <Border Width="74" Height="74" CornerRadius="23" Background="{StaticResource AccentGradient}" HorizontalAlignment="Center" Effect="{StaticResource AccentGlow}"><TextBlock Text="✓" Foreground="#071411" FontSize="34" FontWeight="Bold" HorizontalAlignment="Center" VerticalAlignment="Center"/></Border>
-                    <TextBlock Text="Configurazione completata" FontSize="34" FontWeight="SemiBold" TextAlignment="Center" Margin="0,20,0,10"/>
-                    <TextBlock Text="Avvia l’analisi per costruire la mappa del progetto." Style="{StaticResource MutedText}" FontSize="14" LineHeight="22" TextWrapping="Wrap" TextAlignment="Center"/>
+                    <TextBlock Text="Pronto per la prima analisi" FontSize="34" FontWeight="SemiBold" TextAlignment="Center" Margin="0,20,0,10"/>
+                    <TextBlock Text="Il programma leggerà gli header, ricostruirà le notti osservative e proporrà gli abbinamenti Flat, Dark e Bias." Style="{StaticResource MutedText}" FontSize="14" LineHeight="22" TextWrapping="Wrap" TextAlignment="Center"/>
+                            <Grid Margin="0,22,0,0"><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition/></Grid.ColumnDefinitions><Border Style="{StaticResource Card}" Margin="0,0,5,0" Padding="14"><StackPanel><TextBlock Text="MASTER LIBRARY" Style="{StaticResource Eyebrow}"/><TextBlock Text="{Binding MasterLibraries.Count, StringFormat={}{0} collegate}" FontSize="18" FontWeight="SemiBold" Margin="0,5,0,0"/></StackPanel></Border><Border Grid.Column="1" Style="{StaticResource Card}" Margin="5,0,0,0" Padding="14"><StackPanel><TextBlock Text="SORGENTI" Style="{StaticResource Eyebrow}"/><TextBlock Text="{Binding SourcePaths.Count, StringFormat={}{0} importate}" FontSize="18" FontWeight="SemiBold" Margin="0,5,0,0"/></StackPanel></Border></Grid>
                         </StackPanel>
                     </Grid>
                     <Border Grid.Row="2" Background="#C9121C29" BorderBrush="#40536B" BorderThickness="0,1,0,0" CornerRadius="0,0,16,16">
diff --git a/dotnet/AstroForge.App/MainWindow.xaml.cs b/dotnet/AstroForge.App/MainWindow.xaml.cs
index 24428b4..fd6356a 100644
--- a/dotnet/AstroForge.App/MainWindow.xaml.cs
+++ b/dotnet/AstroForge.App/MainWindow.xaml.cs
@@ -221,6 +221,13 @@ private void ShowAbout_Click(object sender, RoutedEventArgs e)
     private void OpenManualDownload_Click(object sender, RoutedEventArgs e) =>
         OpenExternalUrl(_availableUpdate?.ReleaseNotesUrl ?? ReleasesUrl);
     private void ReportIssue_Click(object sender, RoutedEventArgs e) { MorePopup.IsOpen = false; OpenExternalUrl(IssueUrl); }
+    private void OpenOnboarding_Click(object sender, RoutedEventArgs e)
+    {
+        MorePopup.IsOpen = false;
+        _onboardingStep = 1;
+        UpdateOnboarding();
+        _viewModel.OpenOnboarding();
+    }
     private static void OpenExternalUrl(string url) => Process.Start(new ProcessStartInfo(url) { UseShellExecute = true });
     private async void CheckUpdates_Click(object sender, RoutedEventArgs e) => await CheckUpdatesAsync(true);
     private async Task CheckUpdatesAsync(bool interactive)
@@ -326,7 +333,12 @@ private void DensitySelector_SelectionChanged(object sender, System.Windows.Cont
     private void OnboardingBack_Click(object sender, RoutedEventArgs e) { _onboardingStep = Math.Max(1, _onboardingStep - 1); UpdateOnboarding(); }
     private void OnboardingNext_Click(object sender, RoutedEventArgs e)
     {
-        if (_onboardingStep == 4) { _viewModel.CompleteOnboarding(); return; }
+        if (_onboardingStep == 4)
+        {
+            _viewModel.CompleteOnboarding();
+            if (_viewModel.CanAnalyzeProject) Scan_Click(this, new RoutedEventArgs());
+            return;
+        }
         _onboardingStep++;
         UpdateOnboarding();
     }
@@ -338,7 +350,15 @@ private void UpdateOnboarding()
         OnboardingStep4.Visibility = _onboardingStep == 4 ? Visibility.Visible : Visibility.Collapsed;
         OnboardingProgress.Text = $"{_onboardingStep} / 4";
         OnboardingBackButton.Visibility = _onboardingStep > 1 ? Visibility.Visible : Visibility.Collapsed;
-        OnboardingNextButton.Content = _onboardingStep switch { 1 => "Inizia", 4 => "Vai al progetto", _ => "Continua" };
+        OnboardingNextButton.Content = _onboardingStep switch
+        {
+            1 => "Inizia",
+            2 when _viewModel.MasterLibraries.Count == 0 => "Continua senza libreria",
+            4 when _viewModel.CanAnalyzeProject => "Analizza ora",
+            4 => "Vai al progetto",
+            _ => "Continua"
+        };
+        ScheduleLocalization();
     }
     private void ApplyUiPreferences()
     {
diff --git a/dotnet/AstroForge.CrossPlatform/MainWindow.axaml b/dotnet/AstroForge.CrossPlatform/MainWindow.axaml
index 043e19d..52fcd4f 100644
--- a/dotnet/AstroForge.CrossPlatform/MainWindow.axaml
+++ b/dotnet/AstroForge.CrossPlatform/MainWindow.axaml
@@ -32,9 +32,8 @@
           <ListBox x:Name="SourcesList" ItemsSource="{Binding SourcePaths}" MaxHeight="180">
             <ListBox.ItemTemplate><DataTemplate><Border Classes="pathCard" Margin="0,0,0,5"><TextBlock Text="{Binding}" TextTrimming="CharacterEllipsis" ToolTip.Tip="{Binding}"/></Border></DataTemplate></ListBox.ItemTemplate>
           </ListBox>
-          <Border Height="1" Background="#243146"/>
-          <StackPanel><TextBlock Text="Librerie di calibrazione" Classes="eyebrow"/><TextBlock Text="Indipendenti dal progetto" Classes="muted" FontSize="11"/></StackPanel>
-          <Grid ColumnDefinitions="*,Auto,Auto,Auto" ColumnSpacing="5"><Button Content="+ Libreria" Click="AddLibrary_Click"/><Button Grid.Column="1" Content="↑" Click="MoveLibraryUp_Click"/><Button Grid.Column="2" Content="↓" Click="MoveLibraryDown_Click"/><Button Grid.Column="3" Content="−" Click="RemoveLibrary_Click"/></Grid>
+          <Border Classes="card" Background="#122824" BorderBrush="#397A70" Padding="13"><StackPanel Spacing="8"><Grid ColumnDefinitions="*,Auto"><StackPanel><TextBlock Text="MASTER LIBRARY" Classes="eyebrow"/><TextBlock Text="Dark e Bias automatici" FontSize="17" FontWeight="SemiBold"/></StackPanel><Border Grid.Column="1" Classes="count"><TextBlock Text="{Binding MasterLibraries.Count, StringFormat={}{0} collegate}"/></Border></Grid><TextBlock Text="Camera, gain, offset e temperatura determinano gli abbinamenti." Classes="muted" FontSize="10" TextWrapping="Wrap"/><Button Content="+ Aggiungi Master Library" Classes="primary" ToolTip.Tip="Scegli una cartella contenente Master Dark e Bias" Click="AddLibrary_Click"/></StackPanel></Border>
+          <Grid ColumnDefinitions="*,*,*" ColumnSpacing="5"><Button Content="Rimuovi" Click="RemoveLibrary_Click"/><Button Grid.Column="1" Content="↑ Priorità" Click="MoveLibraryUp_Click"/><Button Grid.Column="2" Content="↓ Priorità" Click="MoveLibraryDown_Click"/></Grid>
           <ListBox ItemsSource="{Binding MasterLibraries}" SelectedItem="{Binding SelectedMasterLibrary}" MaxHeight="170">
             <ListBox.ItemTemplate><DataTemplate><Border Classes="pathCard" Margin="0,0,0,5"><Grid ColumnDefinitions="Auto,*,Auto"><CheckBox IsChecked="{Binding Enabled}"/><StackPanel Grid.Column="1" Margin="7,0"><TextBlock Text="{Binding Name}" FontWeight="SemiBold"/><TextBlock Text="{Binding Path}" Classes="muted" FontSize="10" TextTrimming="CharacterEllipsis" ToolTip.Tip="{Binding Path}"/></StackPanel><TextBlock Grid.Column="2" Text="{Binding Status}" Foreground="#49D9CA"/></Grid></Border></DataTemplate></ListBox.ItemTemplate>
           </ListBox>
@@ -111,6 +110,7 @@
         <CheckBox Content="Riduci animazioni" ToolTip.Tip="Utile su PC meno potenti o se preferisci meno movimento" IsChecked="{Binding ReducedMotion}" Click="UiPreferenceChanged_Click"/>
         <Border Height="1" Background="#33445C" Margin="0,5"/>
         <TextBlock Text="Aiuto" Classes="eyebrow"/>
+        <Button Content="Configurazione iniziale" ToolTip.Tip="Collega librerie, importa immagini e avvia l’analisi" Click="OpenOnboarding_Click"/>
         <Button Content="Guida rapida" Click="OpenGuide_Click"/>
         <Button Content="Segnala un problema" Click="ReportIssue_Click"/>
         <Button Content="GitHub" Click="OpenRepository_Click"/>
@@ -119,8 +119,40 @@
         <Expander Header="Opzioni avanzate"><StackPanel Spacing="9" Margin="0,9,0,0"><TextBlock Text="Margine spazio esportazione (%)"/><NumericUpDown Value="{Binding ExportMarginPercent}" Minimum="0" Maximum="100"/><TextBlock Text="Riserva minima (GiB)"/><NumericUpDown Value="{Binding ExportMinimumReserveGiB}" Minimum="0" Maximum="1000"/><Button Content="Rileggi i metadati" ToolTip.Tip="Forza una nuova lettura alla prossima analisi" Click="ClearCache_Click"/><Button Content="Chiudi progetto" ToolTip.Tip="Rimuove i dati dall'app senza cancellare i file" Command="{Binding ClearProjectCommand}"/></StackPanel></Expander>
       </StackPanel></ScrollViewer>
     </Border>
-    <Border Grid.RowSpan="2" IsVisible="{Binding ShowOnboarding}" Background="#D9080C13" ZIndex="40">
-      <Border Classes="card" Width="680" MaxHeight="610" HorizontalAlignment="Center" VerticalAlignment="Center" Padding="30"><StackPanel Spacing="16"><TextBlock Text="Configurazione iniziale" Classes="eyebrow"/><TextBlock Text="Prepara il primo progetto" FontSize="30" FontWeight="SemiBold" TextWrapping="Wrap"/><TextBlock Text="Importa file FITS/XISF da qualunque software oppure gestisci soltanto la Libreria Master. Gli originali restano in sola lettura." Classes="muted" TextWrapping="Wrap"/><Grid ColumnDefinitions="*,*" ColumnSpacing="10"><Border Classes="note"><StackPanel Spacing="8"><TextBlock Text="1 · Importa" Classes="eyebrow"/><TextBlock Text="Aggiungi file o cartelle FITS/XISF." TextWrapping="Wrap"/><Grid ColumnDefinitions="*,*" ColumnSpacing="6"><Button Content="Aggiungi cartelle" Click="AddSources_Click"/><Button Grid.Column="1" Content="Aggiungi file" Click="AddFiles_Click"/></Grid></StackPanel></Border><Border Grid.Column="1" Classes="note"><StackPanel Spacing="8"><TextBlock Text="2 · Libreria Master" Classes="eyebrow"/><TextBlock Text="Aggiungi una o più librerie di calibrazione. Questa funzione non richiede un progetto." TextWrapping="Wrap"/><Button Content="Aggiungi libreria" Click="AddLibrary_Click"/></StackPanel></Border></Grid><TextBlock Text="Gain e Offset predefiniti vengono usati soltanto quando mancano nei metadati." Classes="muted" TextWrapping="Wrap"/><Grid ColumnDefinitions="*,Auto"><TextBlock Text="Nessun dato viene caricato online." Classes="muted" VerticalAlignment="Center"/><Button Grid.Column="1" Content="Continua" Classes="primary" Click="CompleteOnboarding_Click"/></Grid></StackPanel></Border>
+    <Border Grid.RowSpan="2" IsVisible="{Binding ShowOnboarding}" Background="#E3080C13" ZIndex="40">
+      <Border Classes="card" Width="760" MaxHeight="640" HorizontalAlignment="Center" VerticalAlignment="Center" Padding="0">
+        <Grid RowDefinitions="7,*,74">
+          <Border Background="#49D9CA" CornerRadius="14,14,0,0"/>
+          <Grid Grid.Row="1" Margin="34,28,34,18">
+            <StackPanel x:Name="OnboardingStep1" Spacing="14">
+              <TextBlock Text="Configurazione iniziale" Classes="eyebrow"/>
+              <TextBlock Text="Prepara il primo progetto" FontSize="34" FontWeight="SemiBold" TextWrapping="Wrap"/>
+              <TextBlock Text="Collega le calibrazioni, importa le immagini e avvia la prima analisi. Nessun originale viene modificato." Classes="muted" FontSize="14" TextWrapping="Wrap"/>
+              <Grid ColumnDefinitions="*,*,*" ColumnSpacing="9" Margin="0,15,0,0"><Border Classes="note"><StackPanel Spacing="5"><TextBlock Text="01" Classes="eyebrow"/><TextBlock Text="Master Library" FontSize="17" FontWeight="SemiBold"/><TextBlock Text="facoltativa" Classes="muted"/></StackPanel></Border><Border Grid.Column="1" Classes="note"><StackPanel Spacing="5"><TextBlock Text="02" Classes="eyebrow"/><TextBlock Text="Immagini" FontSize="17" FontWeight="SemiBold"/><TextBlock Text="FITS e XISF" Classes="muted"/></StackPanel></Border><Border Grid.Column="2" Classes="note"><StackPanel Spacing="5"><TextBlock Text="03" Classes="eyebrow"/><TextBlock Text="Analisi" FontSize="17" FontWeight="SemiBold"/><TextBlock Text="sessioni e calibrazioni" Classes="muted"/></StackPanel></Border></Grid>
+            </StackPanel>
+            <StackPanel x:Name="OnboardingStep2" IsVisible="False" Spacing="13">
+              <TextBlock Text="Passo 1 · Calibrazioni" Classes="eyebrow"/>
+              <TextBlock Text="Hai già una Master Library?" FontSize="30" FontWeight="SemiBold" TextWrapping="Wrap"/>
+              <TextBlock Text="Raccoglie Dark e Bias riutilizzabili. Camera, gain, offset, temperatura ed esposizione determinano gli abbinamenti automatici." Classes="muted" FontSize="14" TextWrapping="Wrap"/>
+              <Border Classes="card" Background="#122824" BorderBrush="#397A70" Margin="0,12,0,0"><Grid ColumnDefinitions="*,Auto"><StackPanel Spacing="4"><TextBlock Text="MASTER LIBRARY" Classes="eyebrow"/><TextBlock Text="{Binding MasterLibraries.Count, StringFormat={}{0} collegate}" FontSize="23" FontWeight="SemiBold"/><TextBlock Text="Puoi aggiungerne più di una." Classes="muted"/></StackPanel><Button Grid.Column="1" Content="Sì, aggiungi libreria" Classes="primary" Click="OnboardingAddLibrary_Click"/></Grid></Border>
+              <TextBlock Text="Non ce l’hai? Continua senza: potrai aggiungerla o crearne una in seguito." Classes="muted" TextWrapping="Wrap"/>
+            </StackPanel>
+            <StackPanel x:Name="OnboardingStep3" IsVisible="False" Spacing="13">
+              <TextBlock Text="Passo 2 · Immagini" Classes="eyebrow"/>
+              <TextBlock Text="Importa le acquisizioni" FontSize="30" FontWeight="SemiBold"/>
+              <TextBlock Text="Scegli cartelle complete oppure singoli file FITS/XISF provenienti da qualsiasi software con header utilizzabili." Classes="muted" FontSize="14" TextWrapping="Wrap"/>
+              <Border Classes="card" Background="#101F2A" BorderBrush="#3B607E" Margin="0,12,0,0"><Grid ColumnDefinitions="*,Auto,Auto" ColumnSpacing="8"><StackPanel Spacing="4"><TextBlock Text="IMMAGINI DEL PROGETTO" Classes="eyebrow"/><TextBlock Text="{Binding SourcePaths.Count, StringFormat={}{0} sorgenti importate}" FontSize="23" FontWeight="SemiBold"/><TextBlock Text="Gli originali restano in sola lettura." Classes="muted"/></StackPanel><Button Grid.Column="1" Content="+ Singoli file" Click="OnboardingAddFiles_Click"/><Button Grid.Column="2" Content="+ Cartelle" Classes="primary" Click="OnboardingAddSources_Click"/></Grid></Border>
+            </StackPanel>
+            <StackPanel x:Name="OnboardingStep4" IsVisible="False" Spacing="14" HorizontalAlignment="Center" MaxWidth="580">
+              <Border Width="70" Height="70" CornerRadius="22" Background="#49D9CA" HorizontalAlignment="Center"><TextBlock Text="✓" Foreground="#071411" FontSize="32" FontWeight="Bold" HorizontalAlignment="Center" VerticalAlignment="Center"/></Border>
+              <TextBlock Text="Pronto per la prima analisi" FontSize="31" FontWeight="SemiBold" TextAlignment="Center"/>
+              <TextBlock Text="Il programma leggerà gli header, ricostruirà le notti e proporrà Flat, Dark e Bias." Classes="muted" FontSize="14" TextWrapping="Wrap" TextAlignment="Center"/>
+              <Grid ColumnDefinitions="*,*" ColumnSpacing="9"><Border Classes="note"><StackPanel><TextBlock Text="MASTER LIBRARY" Classes="eyebrow"/><TextBlock Text="{Binding MasterLibraries.Count, StringFormat={}{0} collegate}" FontSize="18" FontWeight="SemiBold"/></StackPanel></Border><Border Grid.Column="1" Classes="note"><StackPanel><TextBlock Text="SORGENTI" Classes="eyebrow"/><TextBlock Text="{Binding SourcePaths.Count, StringFormat={}{0} importate}" FontSize="18" FontWeight="SemiBold"/></StackPanel></Border></Grid>
+            </StackPanel>
+          </Grid>
+          <Border Grid.Row="2" Background="#121C29" BorderBrush="#33445C" BorderThickness="0,1,0,0" CornerRadius="0,0,14,14"><Grid ColumnDefinitions="*,Auto,Auto" Margin="24,0"><StackPanel Orientation="Horizontal" Spacing="10" VerticalAlignment="Center"><TextBlock x:Name="OnboardingProgress" Text="1 / 4" Classes="eyebrow"/><Button Content="Salta" Click="OnboardingSkip_Click"/></StackPanel><Button x:Name="OnboardingBackButton" Grid.Column="1" Content="Indietro" IsVisible="False" Click="OnboardingBack_Click" Margin="0,0,8,0"/><Button x:Name="OnboardingNextButton" Grid.Column="2" Content="Inizia" Classes="primary" Click="OnboardingNext_Click" MinWidth="140"/></Grid></Border>
+        </Grid>
+      </Border>
     </Border>
   </Grid>
 </Window>
diff --git a/dotnet/AstroForge.CrossPlatform/MainWindow.axaml.cs b/dotnet/AstroForge.CrossPlatform/MainWindow.axaml.cs
index 1c6b888..12db182 100644
--- a/dotnet/AstroForge.CrossPlatform/MainWindow.axaml.cs
+++ b/dotnet/AstroForge.CrossPlatform/MainWindow.axaml.cs
@@ -21,6 +21,7 @@ public sealed partial class MainWindow : Window
     private CancellationTokenSource? _qualityCancellation;
     private CancellationTokenSource? _previewCancellation;
     private bool _sourcesVisible = true;
+    private int _onboardingStep = 1;
     private int _blinkIndex = -1;
     private double _qualityZoom = 1;
     private bool _localizationPending;
@@ -200,13 +201,58 @@ private void ToggleSources_Click(object? sender, RoutedEventArgs e)
     }
 
     private void ToggleSettings_Click(object? sender, RoutedEventArgs e) => SettingsPanel.IsVisible = !SettingsPanel.IsVisible;
-    private void OpenOnboarding_Click(object? sender, RoutedEventArgs e) { SettingsPanel.IsVisible = false; _viewModel.OpenOnboarding(); }
+    private void OpenOnboarding_Click(object? sender, RoutedEventArgs e)
+    {
+        SettingsPanel.IsVisible = false;
+        _onboardingStep = 1;
+        UpdateOnboarding();
+        _viewModel.OpenOnboarding();
+    }
     private void OpenGuide_Click(object? sender, RoutedEventArgs e) { SettingsPanel.IsVisible = false; OpenUrl(GuideUrl); }
     private void OpenRepository_Click(object? sender, RoutedEventArgs e) => OpenUrl(RepositoryUrl);
     private void ReportIssue_Click(object? sender, RoutedEventArgs e) { SettingsPanel.IsVisible = false; OpenUrl(IssueUrl); }
     private void OpenDiagnosticsTab_Click(object? sender, RoutedEventArgs e) { SettingsPanel.IsVisible = false; WorkspaceTabs.SelectedIndex = 7; _viewModel.RefreshDiagnostics(); }
     private static void OpenUrl(string url) => Process.Start(new ProcessStartInfo(url) { UseShellExecute = true });
-    private void CompleteOnboarding_Click(object? sender, RoutedEventArgs e) => _viewModel.CompleteOnboarding();
+    private void OnboardingAddLibrary_Click(object? sender, RoutedEventArgs e) => AddLibrary_Click(sender, e);
+    private void OnboardingAddSources_Click(object? sender, RoutedEventArgs e) => AddSources_Click(sender, e);
+    private void OnboardingAddFiles_Click(object? sender, RoutedEventArgs e) => AddFiles_Click(sender, e);
+    private void OnboardingSkip_Click(object? sender, RoutedEventArgs e) => _viewModel.CompleteOnboarding();
+    private void OnboardingBack_Click(object? sender, RoutedEventArgs e)
+    {
+        _onboardingStep = Math.Max(1, _onboardingStep - 1);
+        UpdateOnboarding();
+    }
+    private async void OnboardingNext_Click(object? sender, RoutedEventArgs e)
+    {
+        if (_onboardingStep == 4)
+        {
+            _viewModel.CompleteOnboarding();
+            if (_viewModel.CanAnalyzeProject)
+                await RunAsync("AF-SCAN-001", () => _viewModel.ScanAsync());
+            return;
+        }
+        _onboardingStep++;
+        UpdateOnboarding();
+    }
+
+    private void UpdateOnboarding()
+    {
+        OnboardingStep1.IsVisible = _onboardingStep == 1;
+        OnboardingStep2.IsVisible = _onboardingStep == 2;
+        OnboardingStep3.IsVisible = _onboardingStep == 3;
+        OnboardingStep4.IsVisible = _onboardingStep == 4;
+        OnboardingProgress.Text = $"{_onboardingStep} / 4";
+        OnboardingBackButton.IsVisible = _onboardingStep > 1;
+        OnboardingNextButton.Content = _onboardingStep switch
+        {
+            1 => "Inizia",
+            2 when _viewModel.MasterLibraries.Count == 0 => "Continua senza libreria",
+            4 when _viewModel.CanAnalyzeProject => "Analizza ora",
+            4 => "Vai al progetto",
+            _ => "Continua"
+        };
+        ScheduleLocalization();
+    }
 
     private async void Analyze_Click(object? sender, RoutedEventArgs e) => await RunAsync("AF-SCAN-001", () => _viewModel.ScanAsync());
 
diff --git a/scripts/check-ui-contract.ps1 b/scripts/check-ui-contract.ps1
index 2758f71..60b8def 100644
--- a/scripts/check-ui-contract.ps1
+++ b/scripts/check-ui-contract.ps1
@@ -57,6 +57,8 @@ $contracts = @{
     'Save and Save As behavior (Avalonia)' = $avaloniaCode.Contains('SaveProjectAsync(bool saveAs)')
     'Visible Windows update progress' = $wpfCode.Contains('startInfo.ArgumentList.Add("/SILENT")') -and -not $wpfCode.Contains('startInfo.ArgumentList.Add("/VERYSILENT")')
     'Visible progress from legacy updaters' = $wpfCode.Contains('startInfo.ArgumentList.Add("/APFVISIBLE=1")') -and $installer.Contains('CurInstallProgressChanged') -and $installer.Contains('NeedsCompatibilityProgress')
+    'WPF operational onboarding' = $wpfXaml.Contains('x:Name="OnboardingStep4"') -and $wpfCode.Contains('if (_viewModel.CanAnalyzeProject) Scan_Click')
+    'Avalonia operational onboarding' = (Read-Raw $avaloniaXamlPath).Contains('x:Name="OnboardingStep4"') -and $avaloniaCode.Contains('if (_viewModel.CanAnalyzeProject)')
 }
 
 $failed = @($contracts.GetEnumerator() | Where-Object { -not $_.Value } | ForEach-Object Key)
diff --git a/version.json b/version.json
index 1b2b99c..a3eb51f 100644
--- a/version.json
+++ b/version.json
@@ -1,6 +1,6 @@
 {
-  "version": "1.1.2",
+  "version": "1.2.0",
   "channel": "Stable",
-  "releaseDate": "2026-07-28",
+  "releaseDate": "2026-07-29",
   "minimumWindowsBuild": 19045
 }

From 06798f651e8460e5031bf0fb3478b5cd1a8ba5e7 Mon Sep 17 00:00:00 2001
From: astropuzzo <gianmarcospagnoli345@gmail.com>
Date: Wed, 29 Jul 2026 18:02:25 +0200
Subject: [PATCH 2/2] fix(ci): track new onboarding action

---
 scripts/verify-cross-platform-parity.ps1 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/verify-cross-platform-parity.ps1 b/scripts/verify-cross-platform-parity.ps1
index 92ada77..5b7d3bb 100644
--- a/scripts/verify-cross-platform-parity.ps1
+++ b/scripts/verify-cross-platform-parity.ps1
@@ -30,7 +30,7 @@ $requiredModelCapabilities = @(
 $viewModelText = Get-Content -LiteralPath $viewModel -Raw
 $missing = @($requiredModelCapabilities | Where-Object { $viewModelText -notmatch [regex]::Escape($_) })
 if ($missing.Count -gt 0) { throw "Shared model capabilities missing: $($missing -join ', ')" }
-$requiredUiContracts = @('TreeRoots','PlannedTreeRoots','ApplyOverridesCommand','LinkFlatSetCommand','WbppKeywords','FilterStatistics','QualitySeries','ReviewQueue','MasterOrganizerItems','DiagnosticEvents','Export_Click','RestoreRecovery_Click','ShowOnboarding','CompleteOnboarding_Click')
+$requiredUiContracts = @('TreeRoots','PlannedTreeRoots','ApplyOverridesCommand','LinkFlatSetCommand','WbppKeywords','FilterStatistics','QualitySeries','ReviewQueue','MasterOrganizerItems','DiagnosticEvents','Export_Click','RestoreRecovery_Click','ShowOnboarding','OnboardingNext_Click')
 $missing = @($requiredUiContracts | Where-Object { $windowText -notmatch [regex]::Escape($_) })
 if ($missing.Count -gt 0) { throw "Capabilities not exposed by the cross-platform UI: $($missing -join ', ')" }