diff --git a/static/capabilities.js b/static/capabilities.js
index 14720f4..ceee7b9 100644
--- a/static/capabilities.js
+++ b/static/capabilities.js
@@ -816,15 +816,18 @@
     }
 
     function _withTimeout(promise, timeoutMs, participant) {
-        return Promise.race([
-            promise,
-            new Promise(resolve => {
-                setTimeout(() => resolve({
-                    outcome: 'failed',
-                    reason: `Handler ${participant.pluginId} timed out after ${timeoutMs} ms`,
-                }), timeoutMs);
-            }),
-        ]);
+        // Capture + clear the timer once the race settles — otherwise a handler
+        // that resolves first leaves a live setTimeout (up to timeoutMs) that
+        // keeps the event loop alive and, for long overrides (MIDI permission
+        // commands at 15s), accumulates delayed callbacks across repeated calls.
+        let timer;
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(() => resolve({
+                outcome: 'failed',
+                reason: `Handler ${participant.pluginId} timed out after ${timeoutMs} ms`,
+            }), timeoutMs);
+        });
+        return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
     }
 
     function _normalizeDecision(participant, result) {
diff --git a/static/capabilities/midi-input.js b/static/capabilities/midi-input.js
index 5193144..10161b1 100644
--- a/static/capabilities/midi-input.js
+++ b/static/capabilities/midi-input.js
@@ -371,7 +371,11 @@
         _registerProvider({
             providerId: 'web-midi',
             label: 'Web MIDI',
-            participantId: 'core.midi-input',
+            // Distinct from the domain owner's participant id ('core.midi-input').
+            // unregisterProvider() unregisters the provider's participant, so
+            // sharing the owner's id would tear the whole domain's owner down on
+            // a provider swap/hot-reload, leaving midi-input with no owner.
+            participantId: 'core.midi-input.web-midi',
             enumerate: async () => {
                 access = await navigator.requestMIDIAccess({ sysex: false });
                 try { access.onstatechange = () => { _discover(); }; } catch (_) { /* best-effort */ }
diff --git a/static/tour-engine.css b/static/tour-engine.css
index 06bfc50..0fad12c 100644
--- a/static/tour-engine.css
+++ b/static/tour-engine.css
@@ -1,7 +1,9 @@
 /* ── Consolidated tour menu — one floating button + popover for all tours ── */
-/* Palette aligned with the app's dark theme: #4080e0 accent, #e8c040 gold,
-   #181830 dark background, #cbd5e1 / #94a3b8 / #64748b text scale. Per
-   CLAUDE.md → Frontend Conventions. */
+/* Palette aligned with the v3 fee[dB]ack design tokens (tailwind.config.js):
+   fb-card #1e293b surfaces, fb-cardMuted #0b1220 wells, fb-primary #0ea5e9
+   accent, fb-border #334155 hairlines, fb-text #f8fafc / fb-textDim #94a3b8
+   text, fb-gold #e8c040 badge. Plain CSS (no Tailwind classes) so it needs no
+   stylesheet rebuild. Per CLAUDE.md → Frontend Conventions. */
 
 .slopsmith-tour-menu-btn {
     position: fixed;
@@ -14,20 +16,20 @@
     width: 32px;
     height: 32px;
     border-radius: 50%;
-    background: #181830;
-    border: 1.5px solid #4080e0;
-    color: #cbd5e1;
+    background: #1e293b;
+    border: 1.5px solid #0ea5e9;
+    color: #f8fafc;
     font-size: 15px;
     font-weight: bold;
     cursor: pointer;
-    box-shadow: 0 0 6px #4080e066;
+    box-shadow: 0 0 6px #0ea5e966;
     display: flex;
     align-items: center;
     justify-content: center;
     transition: box-shadow 0.2s, transform 0.15s;
 }
 .slopsmith-tour-menu-btn:hover {
-    box-shadow: 0 0 12px #4080e0aa;
+    box-shadow: 0 0 12px #0ea5e9aa;
     transform: translateY(-1px);
 }
 .slopsmith-tour-menu-btn.has-unseen {
@@ -41,12 +43,12 @@
     width: 10px;
     height: 10px;
     background: #e8c040;
-    border: 2px solid #181830;
+    border: 2px solid #1e293b;
     border-radius: 50%;
 }
 @keyframes tour-pulse {
-    0%, 100% { box-shadow: 0 0 6px #4080e066; }
-    50% { box-shadow: 0 0 16px #4080e0cc; }
+    0%, 100% { box-shadow: 0 0 6px #0ea5e966; }
+    50% { box-shadow: 0 0 16px #0ea5e9cc; }
 }
 
 .slopsmith-tour-menu-popover {
@@ -62,12 +64,12 @@
        room for the trigger button + its bottom inset. */
     max-height: calc(100vh - 80px);
     overflow-y: auto;
-    background: #181830;
-    border: 1px solid #4080e044;
+    background: #1e293b;
+    border: 1px solid #0ea5e944;
     border-radius: 8px;
     padding: 6px;
     font-size: 13px;
-    color: #cbd5e1;
+    color: #f8fafc;
     box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
 }
 .slopsmith-tour-menu-popover .tour-menu-header {
@@ -75,13 +77,13 @@
     font-size: 11px;
     text-transform: uppercase;
     letter-spacing: 0.08em;
-    color: #64748b;
-    border-bottom: 1px solid #1e1e3a;
+    color: #94a3b8;
+    border-bottom: 1px solid #334155;
     margin-bottom: 4px;
 }
 .slopsmith-tour-menu-popover .tour-menu-empty {
     padding: 10px;
-    color: #64748b;
+    color: #94a3b8;
     font-style: italic;
     text-align: center;
 }
@@ -95,23 +97,23 @@
     background: transparent;
     border: none;
     border-radius: 4px;
-    color: #cbd5e1;
+    color: #f8fafc;
     font-size: 13px;
     text-align: left;
     cursor: pointer;
     transition: background 0.12s;
 }
 .slopsmith-tour-menu-popover .tour-menu-item:hover {
-    background: #1a1a30;
-    color: #fff;
+    background: #334155;
+    color: #f8fafc;
 }
 /* Keyboard focus gets an explicit ring instead of relying on the hover
    background — matches the :focus-visible treatment elsewhere in the
    app (style.css). Pointer focus is left alone. */
 .slopsmith-tour-menu-popover .tour-menu-item:focus-visible {
-    background: #1a1a30;
-    color: #fff;
-    outline: 2px solid #4080e0;
+    background: #334155;
+    color: #f8fafc;
+    outline: 2px solid #0ea5e9;
     outline-offset: -2px;
 }
 .slopsmith-tour-menu-popover .tour-menu-item-label {
@@ -127,11 +129,11 @@
 }
 .slopsmith-tour-menu-popover .tour-menu-item-status.is-new {
     background: #e8c040;
-    color: #181830;
+    color: #0f172a;
 }
 .slopsmith-tour-menu-popover .tour-menu-item-status.is-seen {
-    background: #1e1e3a;
-    color: #64748b;
+    background: #0b1220;
+    color: #94a3b8;
 }
 
 /* ── First-visit toast — anchored above the menu button ── */
@@ -141,12 +143,12 @@
     bottom: 56px;
     right: 12px;
     z-index: 202;
-    background: #181830;
-    border: 1px solid #4080e044;
+    background: #1e293b;
+    border: 1px solid #0ea5e944;
     border-radius: 8px;
     padding: 10px 14px;
     font-size: 13px;
-    color: #cbd5e1;
+    color: #f8fafc;
     max-width: 240px;
     line-height: 1.4;
     box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
@@ -159,7 +161,7 @@
 .slopsmith-tour-prompt .tour-prompt-more {
     margin-top: 4px;
     font-size: 11px;
-    color: #64748b;
+    color: #94a3b8;
 }
 .slopsmith-tour-prompt .tour-prompt-buttons {
     display: flex;
@@ -178,11 +180,92 @@
     opacity: 0.85;
 }
 .slopsmith-tour-prompt button[data-action="start"] {
-    background: #4080e0;
+    background: #0ea5e9;
     color: #fff;
     font-weight: 600;
 }
 .slopsmith-tour-prompt button[data-action="dismiss"] {
-    background: #1e1e3a;
+    background: #334155;
     color: #94a3b8;
 }
+
+/* ── Shepherd bubble theme — override the vendored light default ──────────── */
+/* The vendored static/vendor/shepherd.css ships Shepherd's stock LIGHT theme
+   (white bubble, black text, blue buttons), which clashes with the dark v3 UI.
+   These overrides load after it (index.html order) and recolor the spotlight
+   bubbles to the fb-* tokens. The vendored file is left untouched so it stays
+   upgradable. */
+.shepherd-element {
+    background: #1e293b;
+    border: 1px solid #334155;
+    border-radius: 10px;
+    box-shadow: 0 8px 28px rgba(0, 0, 0, 0.55);
+    max-width: 360px;
+}
+.shepherd-content {
+    background: #1e293b;
+    border-radius: 10px;
+}
+.shepherd-text {
+    color: #cbd5e1;
+    font-size: 0.9rem;
+    line-height: 1.45;
+    padding: 0.85em 0.9em;
+}
+.shepherd-title {
+    color: #f8fafc;
+    font-size: 0.95rem;
+    font-weight: 700;
+}
+/* Title row: drop the light-grey header fill the stock theme paints behind a
+   titled step, so the header blends into the card. */
+.shepherd-has-title .shepherd-content .shepherd-header {
+    background: transparent;
+    padding: 0.85em 0.9em 0;
+}
+/* Arrow must match the bubble surface (stock paints it white, and grey behind
+   a bottom-placed titled step). */
+.shepherd-arrow:before {
+    background: #1e293b;
+}
+.shepherd-element.shepherd-has-title[data-popper-placement^="bottom"] > .shepherd-arrow:before {
+    background-color: #1e293b;
+}
+.shepherd-footer {
+    padding: 0 0.75rem 0.75rem;
+}
+/* Primary button (Next / Done) → fb-primary. */
+.shepherd-button {
+    background: #0ea5e9;
+    color: #fff;
+    border-radius: 6px;
+    font-weight: 600;
+    padding: 0.4rem 1.1rem;
+}
+.shepherd-button:not(:disabled):hover {
+    background: #38bdf8;
+    color: #fff;
+}
+/* Secondary button (Back / Skip) → muted slate. */
+.shepherd-button.shepherd-button-secondary {
+    background: #334155;
+    color: #f8fafc;
+}
+.shepherd-button.shepherd-button-secondary:not(:disabled):hover {
+    background: #475569;
+    color: #f8fafc;
+}
+.shepherd-cancel-icon {
+    color: #94a3b8;
+}
+.shepherd-cancel-icon:hover,
+.shepherd-has-title .shepherd-content .shepherd-cancel-icon:hover {
+    color: #f8fafc;
+}
+.shepherd-has-title .shepherd-content .shepherd-cancel-icon {
+    color: #94a3b8;
+}
+/* Dim the page a touch more, matching the onboarding overlay (bg-black/60). */
+.shepherd-modal-overlay-container.shepherd-modal-is-visible {
+    opacity: 0.6;
+}
diff --git a/static/tour-engine.js b/static/tour-engine.js
index 17089b3..f15ff87 100644
--- a/static/tour-engine.js
+++ b/static/tour-engine.js
@@ -127,7 +127,13 @@
     }
 
     function _unseenRelevant(screenId) {
-        return _relevantPlugins(screenId).filter(p => !hasSeen(p.id) && !hasDismissed(p.id));
+        // Drives the toast prompt + button "has-unseen" pulse. A tour registered
+        // with autoPrompt:false is excluded — it's started programmatically by
+        // its owner (e.g. the first-run home tour), so nagging via toast/pulse
+        // would double up. It still lists in the menu and runs on demand.
+        return _relevantPlugins(screenId).filter(p =>
+            !hasSeen(p.id) && !hasDismissed(p.id) &&
+            (_registry[p.id] ? _registry[p.id].autoPrompt !== false : true));
     }
 
     // ── Menu UI ────────────────────────────────────────────────────────────
@@ -615,7 +621,24 @@
             onStart: opts.onStart || null,
             onComplete: opts.onComplete || null,
             screens: Array.isArray(opts.screens) ? opts.screens.slice() : null,
+            // autoPrompt:false opts the tour OUT of the unseen toast + button
+            // pulse (it's driven programmatically by its owner, e.g. the
+            // first-run home tour started from onboarding). It still lists in the
+            // menu and runs via start(). Defaults to the legacy always-prompt.
+            autoPrompt: opts.autoPrompt !== false,
         };
+        // A `name` registers a CLIENT/CORE-owned tour — one that isn't a
+        // server-discovered plugin with a tour.json — into the consolidated menu
+        // catalog so it appears in the "?" menu. Never clobber a richer entry the
+        // /api/plugins pass already supplied for a real plugin of the same id.
+        if (opts.name && !_tourPlugins[pluginId]) {
+            _tourPlugins[pluginId] = {
+                id: pluginId,
+                name: opts.name,
+                has_screen: true,
+                is_viz: false,
+            };
+        }
         // If the override changes the relevance for the current screen, refresh.
         _updateMenuVisibility();
     }
diff --git a/static/v3/badges.js b/static/v3/badges.js
index 3398e91..367c7c2 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -291,7 +291,7 @@
         const host = document.getElementById('v3-badge-instrument');
         if (!host) return;
         host.innerHTML =
-            '<div class="relative">' +
+            '<div id="v3-instrument-wrap" class="relative">' +
             '<button type="button" data-inst-toggle title="Instrument: ' + esc(settings.string_count + '-str ' + tuningLabel()) + '" ' +
             'class="bg-fb-card border border-fb-border/50 rounded-2xl h-[92px] w-16 flex flex-col items-center justify-center gap-2 hover:ring-1 hover:ring-fb-primary/40 transition">' +
             guitarIcon +
diff --git a/static/v3/dashboard.js b/static/v3/dashboard.js
index 8c0c292..9adce79 100644
--- a/static/v3/dashboard.js
+++ b/static/v3/dashboard.js
@@ -134,7 +134,7 @@
             const bars = Array.from({ length: segs }, (_, i) =>
                 '<span class="flex-1 h-1.5 rounded-full ' + (i < filled ? 'bg-fb-primary' : 'bg-gray-500/40') + '"></span>').join('');
             continueCard =
-                '<button id="v3-continue" class="group relative text-left rounded-xl overflow-hidden border border-fb-border/50 bg-fb-card aspect-square self-start flex flex-col justify-end">' +
+                '<button id="v3-continue" data-tour="continue" class="group relative text-left rounded-xl overflow-hidden border border-fb-border/50 bg-fb-card aspect-square self-start flex flex-col justify-end">' +
                 songArt(cont.art_url, 'absolute inset-0 w-full h-full object-cover opacity-60 group-hover:opacity-70 transition') +
                 '<div class="absolute inset-0 bg-gradient-to-t from-black/90 via-black/40 to-transparent"></div>' +
                 tuningChip(cont.tuning_name, 'absolute top-3 right-3') +
@@ -146,7 +146,7 @@
                 '<span class="absolute top-3 left-3 text-fb-text/80 group-hover:text-fb-text">▶</span></button>';
         } else if (pick) {
             continueCard =
-                '<button id="v3-pick" data-fn="' + esc(pick.filename) + '" class="group relative text-left rounded-xl overflow-hidden border border-fb-border/50 bg-fb-card aspect-square self-start flex flex-col justify-end">' +
+                '<button id="v3-pick" data-tour="continue" data-fn="' + esc(pick.filename) + '" class="group relative text-left rounded-xl overflow-hidden border border-fb-border/50 bg-fb-card aspect-square self-start flex flex-col justify-end">' +
                 songArt(libArtUrl(pick), 'absolute inset-0 w-full h-full object-cover opacity-60 group-hover:opacity-70 transition') +
                 '<div class="absolute inset-0 bg-gradient-to-t from-black/90 via-black/40 to-transparent"></div>' +
                 tuningChip(pick.tuning_name, 'absolute top-3 right-3') +
@@ -157,7 +157,7 @@
                 '<span class="absolute top-3 left-3 text-fb-text/80 group-hover:text-fb-text">▶</span></button>';
         } else {
             continueCard =
-                '<div class="rounded-xl border border-fb-border/50 bg-fb-card/60 aspect-square self-start flex flex-col items-center justify-center text-center p-4">' +
+                '<div data-tour="continue" class="rounded-xl border border-fb-border/50 bg-fb-card/60 aspect-square self-start flex flex-col items-center justify-center text-center p-4">' +
                 '<div class="text-fb-textDim text-sm mb-3">Pick a song to get started</div>' +
                 '<button id="v3-continue-pick" class="bg-fb-card hover:bg-fb-card/70 border border-fb-border/50 text-fb-text text-sm px-4 py-2 rounded-md">Browse library</button></div>';
         }
@@ -188,7 +188,7 @@
                 '<a href="' + esc(changelogUrl) + '" target="_blank" rel="noopener" class="text-fb-primary hover:text-fb-primaryHi">Patch Notes for ' + esc(ver) + '</a>?</p>' : '') +
             // Featured grid: hero + continue
             '<div class="grid lg:grid-cols-3 gap-6 mt-6">' +
-            '<div class="lg:col-span-2 relative rounded-xl overflow-hidden min-h-[480px] flex items-center bg-fb-bg">' +
+            '<div id="v3-hero" class="lg:col-span-2 relative rounded-xl overflow-hidden min-h-[480px] flex items-center bg-fb-bg">' +
             // Hero artwork (neon note-highway), right-anchored. Placeholder
             // cropped from the design mock — swap static/v3/brand/hero.png for
             // the designer's high-res original (same path) when available.
diff --git a/static/v3/index.html b/static/v3/index.html
index e1dd861..535d11e 100644
--- a/static/v3/index.html
+++ b/static/v3/index.html
@@ -875,6 +875,10 @@
     <script src="/static/v3/songs.js"></script>
     <script src="/static/v3/lessons.js"></script>
     <script src="/static/v3/dashboard.js"></script>
+    <!-- First-run home tour: spotlights the home cards via the shared tour
+         engine (tour-engine.js, loaded above). Auto-runs once after onboarding
+         (triggered from profile.js finish()); replayable from the "?" menu. -->
+    <script src="/static/v3/onboarding-tour.js"></script>
     <script src="/static/v3/feedbarcade.js"></script>
     <script src="/static/v3/player-chrome.js"></script>
     <script>
diff --git a/static/v3/onboarding-tour.js b/static/v3/onboarding-tour.js
new file mode 100644
index 0000000..20e2968
--- /dev/null
+++ b/static/v3/onboarding-tour.js
@@ -0,0 +1,115 @@
+/*
+ * fee[dB]ack v0.3.0 — first-run home tour.
+ *
+ * Registers a spotlight tour over the home-page cards with the shared tour
+ * engine (window.slopsmithTour / Shepherd) and auto-runs it once, the first
+ * time the user lands on the home page after completing onboarding. It stays
+ * replayable forever from the per-screen "?" tour menu (registered with
+ * screens: ['v3-home']).
+ *
+ * Anchors (all stable, on-screen while #v3-home is active):
+ *   #v3-hero               hero / Start Playing      (dashboard.js)
+ *   [data-tour="continue"] continue / pick a song    (dashboard.js, 3 variants)
+ *   #v3-instrument-wrap    instrument selector badge (badges.js, topbar)
+ *   #v3-tuner-wrap         tuner badge               (badges.js, topbar)
+ *   #v3-audio-routing      audio routing card        (dashboard.js)
+ *   [data-v3-open-profile] profile badge             (profile.js, topbar)
+ *   #v3-nav                left sidebar navigation    (index.html)
+ */
+(function () {
+    'use strict';
+
+    var TOUR_ID = 'home-onboarding';
+
+    // Each step dims the page and spotlights one element (shape: 'spotlight').
+    // waitFor blocks the step until its target exists, so the async dashboard
+    // re-render kicked off by 'v3:profile-updated' can't race the first step.
+    function buildSteps() {
+        return [
+            {
+                id: 'hero', shape: 'spotlight', position: 'bottom',
+                selector: '#v3-hero', waitFor: '#v3-hero',
+                title: 'Welcome to fee[dB]ack',
+                content: 'This is your home base. Hit Start Playing to drop straight into a song from your library.',
+            },
+            {
+                id: 'continue', shape: 'spotlight', position: 'left',
+                selector: '[data-tour="continue"]', waitFor: '[data-tour="continue"]',
+                title: 'Pick up where you left off',
+                content: 'Your last song resumes right here in one click. Before you’ve played anything, it’s a quick random pick to get you going.',
+            },
+            {
+                id: 'instrument', shape: 'spotlight', position: 'bottom',
+                selector: '#v3-instrument-wrap', waitFor: '#v3-instrument-wrap',
+                title: 'Choose your instrument',
+                content: 'Set your instrument, string count and tuning here. The highway, tuner and scoring all adapt to this selection.',
+            },
+            {
+                id: 'tuner', shape: 'spotlight', position: 'bottom',
+                selector: '#v3-tuner-wrap', waitFor: '#v3-tuner-wrap',
+                title: 'Tune up first',
+                content: 'Open the tuner and match each string until the meter centers — accurate tuning means accurate scoring.',
+            },
+            {
+                id: 'audio', shape: 'spotlight', position: 'top',
+                selector: '#v3-audio-routing', waitFor: '#v3-audio-routing',
+                title: 'Your signal path',
+                content: 'Input → amp / NAM / IR → output, at a glance. Set up and monitor your gear from this card.',
+            },
+            {
+                id: 'profile', shape: 'spotlight', position: 'bottom',
+                selector: '[data-v3-open-profile]', waitFor: '[data-v3-open-profile]',
+                title: 'Track your progress',
+                content: 'Your profile, avatar and rank live here. Watch your accuracy climb and level up as you play.',
+            },
+            {
+                id: 'nav', shape: 'spotlight', position: 'right',
+                selector: '#v3-nav', waitFor: '#v3-nav',
+                title: 'Find everything here',
+                content: 'Browse your full library, lessons and plugins anytime. You can replay this tour from the ? button in the corner.',
+            },
+        ];
+    }
+
+    function register() {
+        var t = window.slopsmithTour;
+        if (!t || typeof t.register !== 'function') return false;
+        t.register(TOUR_ID, {
+            name: 'Welcome tour',     // label in the "?" tour menu
+            screens: ['v3-home'],     // relevant only on the home screen
+            autoPrompt: false,        // we auto-run it from onboarding; no toast nag
+            buildSteps: buildSteps,
+        });
+        return true;
+    }
+
+    // Auto-run once after a genuine onboarding completion. profile.js gates the
+    // call on !editing (a profile edit must not relaunch it); we additionally
+    // honour the engine's own seen/dismissed state so it never repeats and a
+    // dismissal isn't nagged. Stays replayable from the "?" menu either way.
+    function startFirstRun() {
+        var t = window.slopsmithTour;
+        if (!t || typeof t.start !== 'function') return;
+        try {
+            if (t.hasSeen(TOUR_ID) || t.hasDismissed(TOUR_ID)) return;
+        } catch (e) { /* private mode — fall through and attempt once */ }
+        // Make sure the home screen is in view so the spotlight targets exist;
+        // the per-step waitFor handles the async dashboard render.
+        if (typeof window.showScreen === 'function') {
+            try { window.showScreen('v3-home'); } catch (e) { /* best-effort */ }
+        }
+        // Defer a frame so the 'v3:profile-updated' dashboard re-render has a
+        // chance to begin before Shepherd starts polling for the first target.
+        var raf = window.requestAnimationFrame || function (fn) { return setTimeout(fn, 16); };
+        raf(function () { try { t.start(TOUR_ID); } catch (e) { /* degrade */ } });
+    }
+
+    window.v3OnboardingTour = { startFirstRun: startFirstRun };
+
+    // tour-engine.js assigns window.slopsmithTour at script-eval time, so if it
+    // is loaded before us register() succeeds immediately; otherwise retry once
+    // the DOM (and the engine) are ready.
+    if (!register()) {
+        document.addEventListener('DOMContentLoaded', register, { once: true });
+    }
+})();
diff --git a/static/v3/profile.js b/static/v3/profile.js
index 75c8cb7..58bf2e7 100644
--- a/static/v3/profile.js
+++ b/static/v3/profile.js
@@ -462,7 +462,8 @@
             return body;
         }
 
-        async function finish() {
+        async function finish(finishOpts) {
+            finishOpts = finishOpts || {};
             overlay.remove();
             await fetchProgress();
             if (window.v3Progression && typeof window.v3Progression.refresh === 'function') {
@@ -471,6 +472,16 @@
             renderBadge();
             renderProfileScreen();
             if (window.slopsmith && window.slopsmith.emit) window.slopsmith.emit('v3:profile-updated', _profile);
+            // First-run only: after a genuine onboarding completion (not a
+            // profile edit), kick off the one-time home tour — but NOT when we're
+            // about to launch the diagnostic ("Play it now"), which navigates to
+            // the player; the tour would otherwise spotlight hidden home elements
+            // and steal focus. The Skip path stays on home, so it runs there.
+            // The engine's seen/dismissed state keeps it once; replayable from "?".
+            if (!editing && !finishOpts.launchingSong &&
+                window.v3OnboardingTour && typeof window.v3OnboardingTour.startFirstRun === 'function') {
+                try { window.v3OnboardingTour.startFirstRun(); } catch (e) { /* never block onboarding */ }
+            }
         }
 
         submit.addEventListener('click', async () => {
@@ -529,7 +540,7 @@
             // Step 4 — "Play it now": leave calibration pending (it completes
             // through the normal scored-stats path) and launch the diagnostic.
             const target = diagnosticFilename;
-            await finish();
+            await finish({ launchingSong: !!target });
             if (target && typeof window.playSong === 'function') window.playSong(target);
         });