spec(M3): Onboarding UI — first-run source OS and distro setup #7

New issue

Open

opened 2026-05-19 07:46:44 -07:00 by pyr0ball · 0 comments

pyr0ball commented

2026-05-19 07:46:44 -07:00

Owner

Goal

When Robin starts for the first time, it needs to know where you came from. M3 builds the Vue onboarding flow that captures this and writes it to config.

Proposed flow

Step 1: What were you using before?

Simple button selection:

macOS
Windows
Linux (different distro)
Android / ChromeOS
iPhone / iPad
Never used a computer much

Step 2: Which distro are you on now?

Robin auto-detects the running distro (reads /etc/os-release) and confirms: "Looks like you're on CachyOS — is that right?" with a manual override option.

Step 3 (Linux-to-Linux only): Which distro were you coming from?

If the user selected "Linux" in Step 1, ask which distro family:

Debian / Ubuntu / Mint / Pop!_OS
Fedora / RHEL / CentOS
Arch / Manjaro
openSUSE
Other

This feeds into the Linux-to-Linux migration paths (see issue #4).

Step 4 (Windows or macOS only): Are you dual-booting?

If the user came from Windows or macOS, ask: "Are you keeping Windows/macOS alongside Linux?"

Yes, I'm dual-booting
No, Linux only

Dual-boot users get a supplementary pattern set layered on top of their primary migration patterns — covering NTFS dirty flags from Windows Fast Startup, clock skew (Windows stores local time, Linux stores UTC), GRUB misconfiguration, and macOS partition mount issues.

Step 5: Fluency check (non-gating)

A single optional question — no wrong answers, no gating:

"When something breaks, what do you usually do first?"

Google the error message

Check settings

Ask someone

Read the log files

Figure it out from the source code

This seeds fluency_level (0–5) without interrogating the user. Robin tracks it passively over time: dismissing a suggestion as "already knew this" bumps the level; opening help text on a command brings it down.

Step 6: Primary use capture (optional, multi-select)

"What will you mainly use this machine for? (Pick all that apply)"

Gaming

Development / coding

Creative work (design, music, video)

Everyday use (web, office, email)

This activates the relevant log paths. A "Gaming" selection enables Steam/Proton/Lutris log watchers from day one. "Development" activates shell and build tool logs.

Step 7: Confirmation

"Got it. Robin will help you navigate CachyOS coming from macOS." — then Robin is live.

Mobile-origin users (Android / iPad)

Users migrating from a phone or tablet as their primary device have a fundamentally different mental model:

No file system familiarity (everything lives inside apps, not paths)
No terminal/command line experience
Package manager = App Store or Google Play
Updates were automatic and invisible
Drivers and firmware were never a user concern

Robin pattern bodies for mobile-origin users explain every command from first principles, avoid assuming any terminal familiarity, and use App Store / Google Play as analogies for package managers. Termux-using Android power users are a slight exception but we target the baseline.

Dual-boot supplement

Dual-boot users get their primary migration pattern file (e.g. windows-to-arch.toml) plus a supplementary pattern file loaded on top (dualboot-windows.toml). The supplement covers coexistence-specific issues that only appear because both OSes share the same hardware:

Windows Fast Startup leaves NTFS volumes dirty — Linux mounts them read-only
Windows stores the RTC in local time; Linux stores it in UTC — dual-boot causes clock drift
GRUB can be overwritten by Windows Update
BitLocker prevents Linux from reading the Windows partition
macOS HFS+/APFS partitions need third-party drivers on Linux
Apple T2 security chip can block Linux from booting without BIOS changes

The supplement is loaded in addition to, not instead of, the primary pattern file.

What's stored

~/.config/robin/config.toml gets:

migration.source_os — the OS family (macos, windows, linux, android, ipad, unknown)
migration.source_distro_family — the distro family for Linux-to-Linux paths (debian, fedora, arch, opensuse)
migration.distro — the target distro (auto-detected)
migration.dual_boot_with — the co-installed OS if dual-booting (windows, macos), or omitted
migration.fluency_level — starts at 0, updated passively
migration.use_domains — list of selected use domains (gaming, dev, creative, general)

MenagerieOS path

On MenagerieOS, source OS is captured by the installer — Robin skips Steps 1, 3, and 4 and goes straight to Step 5. Onboarding on MenagerieOS should feel like a warm welcome, not a setup wizard.

Open questions

Xander: Does the proposed flow feel right for a macOS migrant first booting into a new distro? What would you want asked that isn't here?
Should Step 6 (use domains) be optional or required? Skipping it defaults to watching all log paths.
Should Robin detect dual-boot automatically (check for other EFI entries or /etc/fstab NTFS mounts) rather than asking?
Where should the onboarding panel live — full-screen overlay on first launch, or inside the existing chat panel?

Dependencies

M1 and M2 merged
source_distro_family, dual_boot_with, use_domains fields added to MigrationConfig
Android and iPad variants in SourceOs enum

## Goal When Robin starts for the first time, it needs to know where you came from. M3 builds the Vue onboarding flow that captures this and writes it to config. ## Proposed flow ### Step 1: What were you using before? Simple button selection: - macOS - Windows - Linux (different distro) - Android / ChromeOS - iPhone / iPad - Never used a computer much ### Step 2: Which distro are you on now? Robin auto-detects the running distro (reads `/etc/os-release`) and confirms: "Looks like you're on CachyOS — is that right?" with a manual override option. ### Step 3 (Linux-to-Linux only): Which distro were you coming from? If the user selected "Linux" in Step 1, ask which distro family: - Debian / Ubuntu / Mint / Pop!_OS - Fedora / RHEL / CentOS - Arch / Manjaro - openSUSE - Other This feeds into the Linux-to-Linux migration paths (see issue #4). ### Step 4 (Windows or macOS only): Are you dual-booting? If the user came from Windows or macOS, ask: "Are you keeping Windows/macOS alongside Linux?" - Yes, I'm dual-booting - No, Linux only Dual-boot users get a supplementary pattern set layered on top of their primary migration patterns — covering NTFS dirty flags from Windows Fast Startup, clock skew (Windows stores local time, Linux stores UTC), GRUB misconfiguration, and macOS partition mount issues. ### Step 5: Fluency check (non-gating) A single optional question — no wrong answers, no gating: > "When something breaks, what do you usually do first?" > - Google the error message > - Check settings > - Ask someone > - Read the log files > - Figure it out from the source code This seeds `fluency_level` (0–5) without interrogating the user. Robin tracks it passively over time: dismissing a suggestion as "already knew this" bumps the level; opening help text on a command brings it down. ### Step 6: Primary use capture (optional, multi-select) > "What will you mainly use this machine for? (Pick all that apply)" > - Gaming > - Development / coding > - Creative work (design, music, video) > - Everyday use (web, office, email) This activates the relevant log paths. A "Gaming" selection enables Steam/Proton/Lutris log watchers from day one. "Development" activates shell and build tool logs. ### Step 7: Confirmation "Got it. Robin will help you navigate CachyOS coming from macOS." — then Robin is live. ## Mobile-origin users (Android / iPad) Users migrating from a phone or tablet as their primary device have a fundamentally different mental model: - No file system familiarity (everything lives inside apps, not paths) - No terminal/command line experience - Package manager = App Store or Google Play - Updates were automatic and invisible - Drivers and firmware were never a user concern Robin pattern bodies for mobile-origin users explain every command from first principles, avoid assuming any terminal familiarity, and use App Store / Google Play as analogies for package managers. Termux-using Android power users are a slight exception but we target the baseline. ## Dual-boot supplement Dual-boot users get their primary migration pattern file (e.g. `windows-to-arch.toml`) **plus** a supplementary pattern file loaded on top (`dualboot-windows.toml`). The supplement covers coexistence-specific issues that only appear because both OSes share the same hardware: - Windows Fast Startup leaves NTFS volumes dirty — Linux mounts them read-only - Windows stores the RTC in local time; Linux stores it in UTC — dual-boot causes clock drift - GRUB can be overwritten by Windows Update - BitLocker prevents Linux from reading the Windows partition - macOS HFS+/APFS partitions need third-party drivers on Linux - Apple T2 security chip can block Linux from booting without BIOS changes The supplement is loaded in addition to, not instead of, the primary pattern file. ## What's stored `~/.config/robin/config.toml` gets: - `migration.source_os` — the OS family (`macos`, `windows`, `linux`, `android`, `ipad`, `unknown`) - `migration.source_distro_family` — the distro family for Linux-to-Linux paths (`debian`, `fedora`, `arch`, `opensuse`) - `migration.distro` — the target distro (auto-detected) - `migration.dual_boot_with` — the co-installed OS if dual-booting (`windows`, `macos`), or omitted - `migration.fluency_level` — starts at 0, updated passively - `migration.use_domains` — list of selected use domains (`gaming`, `dev`, `creative`, `general`) ## MenagerieOS path On MenagerieOS, source OS is captured by the installer — Robin skips Steps 1, 3, and 4 and goes straight to Step 5. Onboarding on MenagerieOS should feel like a warm welcome, not a setup wizard. ## Open questions - Xander: Does the proposed flow feel right for a macOS migrant first booting into a new distro? What would you want asked that isn't here? - Should Step 6 (use domains) be optional or required? Skipping it defaults to watching all log paths. - Should Robin detect dual-boot automatically (check for other EFI entries or `/etc/fstab` NTFS mounts) rather than asking? - Where should the onboarding panel live — full-screen overlay on first launch, or inside the existing chat panel? ## Dependencies - M1 and M2 merged - `source_distro_family`, `dual_boot_with`, `use_domains` fields added to `MigrationConfig` - Android and iPad variants in `SourceOs` enum