[ultraelectronica]

Summary

• Replace the single static spotlight tour with five focused guides: Core, Library, Player, Appearance, and Audio. The Interactive Tutorial setting now opens a guide picker, and each guide tracks dismissed/completed progress independently.
• Persist progress per stable guide ID as tutorial_v2_<guide>, migrating the legacy tutorial_completed flag into a completed Core guide without rewinding a guide already started while preferences load.
• Adapt the Core guide to the library: skip the add-music step when songs already exist, and advance off the welcome page instead of replaying setup.
• Advance only on the real action being performed — searching, playing a song, opening the player, using sort, opening song actions, opening the queue, or opening lyrics. Paused, inactive, and picker states ignore those signals, and replay dismissal never downgrades an already completed guide.
• Follow navigation instead of assuming a fixed screen: root and nested route observers expose the full player and queue, hide guidance behind modals, and let the overlay auto-switch tabs or open the tutorial-owned library page when a step needs it.
• Track controls through a shared target registry that supports overlapping layout owners, rejects zero-size or non-current-route anchors, and recomputes spotlight geometry when controls move.
• Keep the app usable while guidance is shown: there is no gesture barrier, real controls receive the tap, and the compact card avoids covering the highlighted target. Guidance pauses for app lifecycle changes, permission pickers, and manual pages.
• Add contextual actions to the overlay: open the add-folder page, use the current song, open the player, jump to navigation/layout/audio/equalizer pages, deep-link into the manual section for the current step, or end the tour. The picker shows per-guide completion.
• Rewire affected surfaces to emit actions and expose targets: add-music folder, search bar, library content, sort button, song-actions sheet, queue and lyrics buttons, mini player, navigation, and player pages. Full-player and tutorial-page back gestures skip guidance rather than closing the underlying screen.
• Add .impeccable/surfaces/tutorial-guidance.md as the interaction contract and update DESIGN.md, plus provider, overlay, locale, and streak-popup test coverage.

Related issue

none

Checklist

• flutter analyze passes
• flutter test passes
• Rust changes: cargo test --manifest-path rust/Cargo.toml passes
• Built and ran the app if the change touches a playback path (flutter run --flavor full)
• Generated code regenerated and committed if bridge/drift/freezed models changed
• CHANGELOG.md updated for user-facing changes
• No secrets, keys, tokens, or machine-local files committed
• One change per PR; no unrelated reformatting in the same diff
• Hardware tested if the Rust audio engine or USB/DAC output changed