feat(walkthrough): add Getting Started tour with first-run invite

Bespoke spotlight walkthrough (no new deps) that guides new users through the
main features. A version-stamped invite bubble offers the tour to new users and
re-offers it once to existing users after an upgrade; restartable from Settings.

- Multi-hole SVG-mask overlay keeps a ringed control and any open modal lit
- Steps: scan, scan history, inventory, nodes, edit, text/zone, grouping,
  style, imports, and a closing recap with a GitHub link
- Scan/history/inventory/import steps inject demo data (no backend calls) and
  are filtered out in standalone, which ends on a full-mode recap
- Persisted invite state via localStorage (utils/walkthrough.ts), live tour
  state via zustand (stores/walkthroughStore.ts)

ha-relevant: maybe

frontend/src/App.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useCallback, useRef, useState } from 'react'
+import { useEffect, useCallback, useMemo, useRef, useState } from 'react'
 import { ReactFlowProvider, type Connection, type Edge } from '@xyflow/react'
 import { type Node } from '@xyflow/react'
 import { applyDagreLayout } from '@/utils/layout'
@@ -46,6 +46,10 @@ import { canvasApi, designsApi, liveviewApi } from '@/api/client'
 import * as standaloneStorage from '@/utils/standaloneStorage'
 import { demoNodes, demoEdges } from '@/utils/demoData'
 import { decideCanvasLoad, isNewUserCanvas } from '@/utils/canvasLoadDecision'
+import { WalkthroughActionsProvider, type WalkthroughActionApi } from '@/walkthrough/actions'
+import { WalkthroughInvite } from '@/walkthrough/WalkthroughInvite'
+import { WalkthroughOverlay } from '@/walkthrough/WalkthroughOverlay'
+import { DEMO_SCAN_RUNS, DEMO_PENDING_DEVICES } from '@/walkthrough/demoTourData'
 import { useStatusPolling } from '@/hooks/useStatusPolling'
 import type { NodeData, EdgeData, CustomStyleDef, FloorMapConfig, NodeType } from '@/types'
 import type { ZigbeeNode, ZigbeeEdge } from '@/components/zigbee/types'
@@ -82,6 +86,11 @@ export default function App() {
   // entry signal for the upcoming Getting Started walkthrough.
   const [isNewUser, setIsNewUser] = useState(false)
 
+  // Getting Started tour: when true, the corresponding modal renders injected demo
+  // data instead of hitting the backend.
+  const [tourScanHistoryDemo, setTourScanHistoryDemo] = useState(false)
+  const [tourInventoryDemo, setTourInventoryDemo] = useState(false)
+
   const [themeModalOpen, setThemeModalOpen] = useState(false)
   const [styleEditorType, setStyleEditorType] = useState<NodeType | null>(null)
   const [searchOpen, setSearchOpen] = useState(false)
@@ -285,6 +294,55 @@ export default function App() {
     void loadDesignsAndCanvasRef.current()
   }, [])
 
+  // Bridge the Getting Started tour steps to the App's modal controls. The overlay
+  // calls closeAll() before each step, then the step's action to open the target.
+  const walkthroughActions = useMemo<WalkthroughActionApi>(() => ({
+    closeAll: () => {
+      setScanConfigOpen(false)
+      setScanHistoryOpen(false)
+      setTourScanHistoryDemo(false)
+      setPendingModalOpen(false)
+      setTourInventoryDemo(false)
+      setEditNodeId(null)
+      setThemeModalOpen(false)
+      setZigbeeImportOpen(false)
+      // Clear any tour-driven multi-selection so the DetailPanel closes.
+      useCanvasStore.setState((s) => ({
+        nodes: s.nodes.map((n) => (n.selected ? { ...n, selected: false } : n)),
+        selectedNodeIds: [],
+        selectedNodeId: null,
+      }))
+    },
+    openScanConfig: () => setScanConfigOpen(true),
+    openScanHistoryDemo: () => {
+      setTourScanHistoryDemo(true)
+      setScanHistoryOpen(true)
+    },
+    openInventoryDemo: () => {
+      setTourInventoryDemo(true)
+      openPendingModal(undefined, 'pending')
+    },
+    editFirstNode: () => {
+      const first = useCanvasStore.getState().nodes.find((n) => n.data.type !== 'groupRect' && n.data.type !== 'text')
+      if (first) setEditNodeId(first.id)
+    },
+    selectTwoNodes: () => {
+      const ids = useCanvasStore.getState().nodes
+        .filter((n) => n.data.type !== 'groupRect' && n.data.type !== 'text')
+        .slice(0, 2)
+        .map((n) => n.id)
+      if (ids.length < 2) return
+      const set = new Set(ids)
+      useCanvasStore.setState((s) => ({
+        nodes: s.nodes.map((n) => ({ ...n, selected: set.has(n.id) })),
+        selectedNodeIds: ids,
+        selectedNodeId: null,
+      }))
+    },
+    openStyle: () => setThemeModalOpen(true),
+    openZigbeeImport: () => setZigbeeImportOpen(true),
+  }), [openPendingModal])
+
   // Load designs + canvas on auth (or immediately in standalone mode, which has
   // no auth gate).
   useEffect(() => {
@@ -867,6 +925,7 @@ export default function App() {
   if (!STANDALONE && !isAuthenticated) return <LoginPage />
 
   return (
+    <WalkthroughActionsProvider value={walkthroughActions}>
     <TooltipProvider>
       <ReactFlowProvider>
         {/* data-new-user marks a first-time (demo) canvas — the hook the upcoming
@@ -1036,6 +1095,7 @@ export default function App() {
           <ScanHistoryModal
             open={scanHistoryOpen}
             onClose={() => setScanHistoryOpen(false)}
+            demoRuns={tourScanHistoryDemo ? DEMO_SCAN_RUNS : undefined}
           />
         )}
 
@@ -1160,6 +1220,7 @@ export default function App() {
           onClose={() => setPendingModalOpen(false)}
           highlightId={pendingHighlightId}
           initialStatus={pendingModalStatus}
+          demoDevices={tourInventoryDemo ? DEMO_PENDING_DEVICES : undefined}
         />
 
         <ExportModal
@@ -1169,7 +1230,10 @@ export default function App() {
         />
 
         <Toaster theme="dark" position="bottom-right" />
+        <WalkthroughInvite />
+        <WalkthroughOverlay />
       </ReactFlowProvider>
     </TooltipProvider>
+    </WalkthroughActionsProvider>
   )
 }

frontend/src/components/modals/PendingDevicesModal.tsx

@@ -25,6 +25,8 @@ interface PendingDevicesModalProps {
   onClose: () => void
   highlightId?: string
   initialStatus?: 'pending' | 'hidden'
+  /** Getting Started tour: render these canned devices and skip the backend fetch. */
+  demoDevices?: PendingDevice[]
 }
 
 const PORT_COLORS: Record<number, string> = {
@@ -113,7 +115,7 @@ function injectAutoEdges(edges: AutoEdge[] | undefined) {
   }))
 }
 
-export function PendingDevicesModal({ open, onClose, highlightId, initialStatus = 'pending' }: PendingDevicesModalProps) {
+export function PendingDevicesModal({ open, onClose, highlightId, initialStatus = 'pending', demoDevices }: PendingDevicesModalProps) {
   const [devices, setDevices] = useState<PendingDevice[]>([])
   const [loading, setLoading] = useState(false)
   const [selected, setSelected] = useState<PendingDevice | null>(null)
@@ -136,6 +138,8 @@ export function PendingDevicesModal({ open, onClose, highlightId, initialStatus
   const [dupPrompt, setDupPrompt] = useState<{ device: PendingDevice; conflict: DuplicateNodeConflict } | null>(null)
 
   const load = useCallback(async () => {
+    // Tour/demo mode: show injected devices, never touch the backend.
+    if (demoDevices) { setDevices(statusFilter === 'pending' ? demoDevices : []); return }
     setLoading(true)
     try {
       const res = statusFilter === 'pending' ? await scanApi.pending() : await scanApi.hidden()
@@ -145,7 +149,7 @@ export function PendingDevicesModal({ open, onClose, highlightId, initialStatus
     } finally {
       setLoading(false)
     }
-  }, [statusFilter])
+  }, [statusFilter, demoDevices])
 
   useEffect(() => { if (open) load() }, [open, load])
   useEffect(() => { if (open && scanEventTs > 0) load() }, [scanEventTs, open, load])

frontend/src/components/modals/ScanHistoryModal.tsx

@@ -20,6 +20,8 @@ export interface ScanRun {
 interface ScanHistoryModalProps {
   open: boolean
   onClose: () => void
+  /** Getting Started tour: render these canned runs and skip the backend fetch. */
+  demoRuns?: ScanRun[]
 }
 
 type KindFilter = 'all' | 'ip' | 'zigbee' | 'zwave' | 'proxmox'
@@ -85,7 +87,7 @@ function runDuration(r: ScanRun, now: number): string {
   return formatDuration(end - start)
 }
 
-export function ScanHistoryModal({ open, onClose }: ScanHistoryModalProps) {
+export function ScanHistoryModal({ open, onClose, demoRuns }: ScanHistoryModalProps) {
   const [runs, setRuns] = useState<ScanRun[]>([])
   const [loading, setLoading] = useState(false)
   const [stopping, setStopping] = useState<string | null>(null)
@@ -95,6 +97,8 @@ export function ScanHistoryModal({ open, onClose }: ScanHistoryModalProps) {
   const prevRunsRef = useRef<ScanRun[]>([])
 
   const load = useCallback(async () => {
+    // Tour/demo mode: show injected runs, never touch the backend.
+    if (demoRuns) { setRuns(demoRuns); prevRunsRef.current = demoRuns; return }
     setLoading(true)
     try {
       const res = await scanApi.runs()
@@ -127,7 +131,7 @@ export function ScanHistoryModal({ open, onClose }: ScanHistoryModalProps) {
     } finally {
       setLoading(false)
     }
-  }, [])
+  }, [demoRuns])
 
   // Load when opened; reset prior-state tracker so we don't replay old transitions
   useEffect(() => {
@@ -155,6 +159,7 @@ export function ScanHistoryModal({ open, onClose }: ScanHistoryModalProps) {
   }, [open, runs])
 
   const handleStop = async (runId: string) => {
+    if (demoRuns) return // tour mode — no backend
     setStopping(runId)
     try {
       await scanApi.stop(runId)

frontend/src/components/modals/SettingsModal.tsx

@@ -11,6 +11,7 @@ import {
   type ZwaveConfigData,
 } from '@/api/client'
 import { useCanvasStore } from '@/stores/canvasStore'
+import { useWalkthroughStore } from '@/stores/walkthroughStore'
 import { toast } from 'sonner'
 import {
   type AlignmentSettings,
@@ -401,6 +402,18 @@ export function SettingsModal({ open, onClose }: SettingsModalProps) {
                 Saves silently after this many seconds with no changes. Manual Ctrl+S still works.
               </p>
             </div>
+
+            <div className="flex items-center justify-between gap-2">
+              <span className="text-xs text-foreground">Getting started tour</span>
+              <Button
+                variant="outline"
+                size="sm"
+                className="h-7 text-xs"
+                onClick={() => { useWalkthroughStore.getState().start(); onClose() }}
+              >
+                Restart walkthrough
+              </Button>
+            </div>
           </div>
           </div>
 

frontend/src/components/panels/DetailPanel.tsx

@@ -516,6 +516,7 @@ function MultiSelectPanel({ nodeIds, nodes, groupName, setGroupName, creatingGro
           </>
         ) : (
           <Button
+            data-tour="create-group"
             size="sm"
             className="w-full gap-2 bg-[#00d4ff]/10 text-[#00d4ff] border border-[#00d4ff]/30 hover:bg-[#00d4ff]/20"
             variant="ghost"

frontend/src/components/panels/Sidebar.tsx

@@ -268,13 +268,13 @@ export function Sidebar({ onAddNode, onAddGroupRect, onAddText, onScan, onZigbee
 
       {/* Actions */}
       <div className="flex flex-col gap-0.5 p-2 border-t border-border">
-        <SidebarItem icon={Plus} label="Add Node" collapsed={collapsed} onClick={onAddNode} />
+        <SidebarItem icon={Plus} label="Add Node" collapsed={collapsed} onClick={onAddNode} dataTour="add-node" />
-        <SidebarItem icon={Square} label="Add Zone" collapsed={collapsed} onClick={onAddGroupRect} />
+        <SidebarItem icon={Square} label="Add Zone" collapsed={collapsed} onClick={onAddGroupRect} dataTour="add-zone" />
-        <SidebarItem icon={Type} label="Add Text" collapsed={collapsed} onClick={onAddText} />
+        <SidebarItem icon={Type} label="Add Text" collapsed={collapsed} onClick={onAddText} dataTour="add-text" />
-        {!STANDALONE && <SidebarItem icon={ScanLine} label="Scan Network" collapsed={collapsed} onClick={handleScan} />}
+        {!STANDALONE && <SidebarItem icon={ScanLine} label="Scan Network" collapsed={collapsed} onClick={handleScan} dataTour="scan-network" />}
-        {!STANDALONE && <SidebarItem icon={Network} label="Zigbee Import" collapsed={collapsed} onClick={onZigbeeImport} />}
+        {!STANDALONE && <SidebarItem icon={Network} label="Zigbee Import" collapsed={collapsed} onClick={onZigbeeImport} dataTour="zigbee-import" />}
-        {!STANDALONE && <SidebarItem icon={RadioTower} label="Z-Wave Import" collapsed={collapsed} onClick={onZwaveImport} />}
+        {!STANDALONE && <SidebarItem icon={RadioTower} label="Z-Wave Import" collapsed={collapsed} onClick={onZwaveImport} dataTour="zwave-import" />}
-        {!STANDALONE && <SidebarItem icon={Server} label="Proxmox Import" collapsed={collapsed} onClick={onProxmoxImport} />}
+        {!STANDALONE && <SidebarItem icon={Server} label="Proxmox Import" collapsed={collapsed} onClick={onProxmoxImport} dataTour="proxmox-import" />}
         <SidebarItem
           icon={Save}
           label="Save Canvas"
@@ -360,12 +360,15 @@ interface SidebarItemProps {
   badge?: boolean
   accent?: boolean
   onClick?: () => void
+  /** Stable anchor for the Getting Started walkthrough spotlight. */
+  dataTour?: string
 }
 
-function SidebarItem({ icon: Icon, label, collapsed, active, badge, accent, onClick }: SidebarItemProps) {
+function SidebarItem({ icon: Icon, label, collapsed, active, badge, accent, onClick, dataTour }: SidebarItemProps) {
   const btn = (
     <button
       onClick={onClick}
+      data-tour={dataTour}
       className={`relative flex items-center gap-2 w-full px-2 py-1.5 rounded-md text-sm transition-colors cursor-pointer ${
         active
           ? 'bg-[#00d4ff]/10 text-[#00d4ff]'

frontend/src/components/panels/Toolbar.tsx

@@ -62,7 +62,7 @@ export function Toolbar({ onSave, onAutoLayout, onExport, onChangeStyle, onUndo,
       <Button size="sm" variant="ghost" className="gap-1.5 text-muted-foreground hover:text-foreground cursor-pointer hover:bg-[#21262d]" onClick={onAutoLayout}>
         <LayoutDashboard size={14} /> Auto Layout
       </Button>
-      <Button size="sm" variant="ghost" className="gap-1.5 text-muted-foreground hover:text-foreground cursor-pointer hover:bg-[#21262d]" onClick={onChangeStyle}>
+      <Button data-tour="style" size="sm" variant="ghost" className="gap-1.5 text-muted-foreground hover:text-foreground cursor-pointer hover:bg-[#21262d]" onClick={onChangeStyle}>
         <Palette size={14} /> Style
       </Button>
       <Button size="sm" variant="ghost" className="gap-1.5 text-muted-foreground hover:text-foreground cursor-pointer hover:bg-[#21262d]" onClick={() => fileInputRef.current?.click()} title="Import from YAML">

frontend/src/stores/__tests__/walkthroughStore.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { useWalkthroughStore } from '../walkthroughStore'
+import { readWalkthrough, WALKTHROUGH_VERSION } from '@/utils/walkthrough'
+
+beforeEach(() => {
+  localStorage.clear()
+  useWalkthroughStore.setState({ isActive: false, stepIndex: 0, total: 0 })
+})
+
+describe('walkthroughStore', () => {
+  it('start activates at step 0', () => {
+    useWalkthroughStore.getState().start()
+    const s = useWalkthroughStore.getState()
+    expect(s.isActive).toBe(true)
+    expect(s.stepIndex).toBe(0)
+  })
+
+  it('next advances and finishes past the last step', () => {
+    const store = useWalkthroughStore.getState()
+    store.start()
+    store.setTotal(3)
+    store.next()
+    expect(useWalkthroughStore.getState().stepIndex).toBe(1)
+    store.next()
+    expect(useWalkthroughStore.getState().stepIndex).toBe(2)
+    // At the last step, next() finishes the tour and stamps it completed.
+    store.next()
+    expect(useWalkthroughStore.getState().isActive).toBe(false)
+    expect(readWalkthrough()).toEqual({ seenVersion: WALKTHROUGH_VERSION, status: 'completed' })
+  })
+
+  it('prev clamps at 0', () => {
+    const store = useWalkthroughStore.getState()
+    store.start()
+    store.setTotal(3)
+    store.prev()
+    expect(useWalkthroughStore.getState().stepIndex).toBe(0)
+  })
+
+  it('goTo clamps within [0, total-1]', () => {
+    const store = useWalkthroughStore.getState()
+    store.start()
+    store.setTotal(3)
+    store.goTo(9)
+    expect(useWalkthroughStore.getState().stepIndex).toBe(2)
+    store.goTo(-1)
+    expect(useWalkthroughStore.getState().stepIndex).toBe(0)
+  })
+
+  it('skip deactivates and stamps skipped', () => {
+    const store = useWalkthroughStore.getState()
+    store.start()
+    store.skip()
+    expect(useWalkthroughStore.getState().isActive).toBe(false)
+    expect(readWalkthrough().status).toBe('skipped')
+    expect(readWalkthrough().seenVersion).toBe(WALKTHROUGH_VERSION)
+  })
+})

frontend/src/stores/walkthroughStore.ts

@@ -0,0 +1,48 @@
+import { create } from 'zustand'
+import { markWalkthroughSeen } from '@/utils/walkthrough'
+
+/**
+ * Runtime state of an active Getting Started tour. Persistence of the "already
+ * seen" flag lives in utils/walkthrough.ts; this store only tracks the live run.
+ *
+ * `total` is set by the overlay from the mode-filtered step list, so next()/goTo
+ * can clamp and finish() fires when the user advances past the last step.
+ */
+interface WalkthroughStore {
+  isActive: boolean
+  stepIndex: number
+  total: number
+  setTotal: (n: number) => void
+  start: () => void
+  next: () => void
+  prev: () => void
+  goTo: (n: number) => void
+  skip: () => void
+  finish: () => void
+}
+
+export const useWalkthroughStore = create<WalkthroughStore>((set, get) => ({
+  isActive: false,
+  stepIndex: 0,
+  total: 0,
+  setTotal: (n) => set({ total: n }),
+  start: () => set({ isActive: true, stepIndex: 0 }),
+  next: () => {
+    const { stepIndex, total } = get()
+    if (stepIndex >= total - 1) {
+      get().finish()
+      return
+    }
+    set({ stepIndex: stepIndex + 1 })
+  },
+  prev: () => set((s) => ({ stepIndex: Math.max(0, s.stepIndex - 1) })),
+  goTo: (n) => set((s) => ({ stepIndex: Math.max(0, Math.min(n, Math.max(0, s.total - 1))) })),
+  skip: () => {
+    markWalkthroughSeen('skipped')
+    set({ isActive: false })
+  },
+  finish: () => {
+    markWalkthroughSeen('completed')
+    set({ isActive: false })
+  },
+}))

frontend/src/utils/__tests__/walkthrough.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import {
+  WALKTHROUGH_VERSION,
+  readWalkthrough,
+  writeWalkthrough,
+  subscribeWalkthrough,
+  shouldOfferWalkthrough,
+  markWalkthroughSeen,
+  resetWalkthrough,
+} from '../walkthrough'
+
+beforeEach(() => localStorage.clear())
+
+describe('readWalkthrough', () => {
+  it('defaults to pending / unseen when nothing is stored', () => {
+    expect(readWalkthrough()).toEqual({ seenVersion: null, status: 'pending' })
+  })
+
+  it('round-trips written state', () => {
+    writeWalkthrough({ seenVersion: 3, status: 'completed' })
+    expect(readWalkthrough()).toEqual({ seenVersion: 3, status: 'completed' })
+  })
+
+  it('falls back to defaults on malformed json', () => {
+    localStorage.setItem('homelable.walkthrough', '{not json')
+    expect(readWalkthrough()).toEqual({ seenVersion: null, status: 'pending' })
+  })
+})
+
+describe('shouldOfferWalkthrough', () => {
+  it('offers a brand-new user (seenVersion null)', () => {
+    expect(shouldOfferWalkthrough()).toBe(true)
+  })
+
+  it('offers an upgrader whose seen version is behind', () => {
+    writeWalkthrough({ seenVersion: WALKTHROUGH_VERSION - 1, status: 'completed' })
+    expect(shouldOfferWalkthrough()).toBe(true)
+  })
+
+  it('stops offering once the current version is stamped', () => {
+    markWalkthroughSeen('completed')
+    expect(shouldOfferWalkthrough()).toBe(false)
+    expect(readWalkthrough().seenVersion).toBe(WALKTHROUGH_VERSION)
+  })
+})
+
+describe('resetWalkthrough', () => {
+  it('re-offers after a reset', () => {
+    markWalkthroughSeen('skipped')
+    expect(shouldOfferWalkthrough()).toBe(false)
+    resetWalkthrough()
+    expect(shouldOfferWalkthrough()).toBe(true)
+  })
+})
+
+describe('subscribeWalkthrough', () => {
+  it('notifies listeners on write and unsubscribes cleanly', () => {
+    const spy = vi.fn()
+    const unsub = subscribeWalkthrough(spy)
+    writeWalkthrough({ seenVersion: 1, status: 'completed' })
+    expect(spy).toHaveBeenCalledWith({ seenVersion: 1, status: 'completed' })
+    unsub()
+    writeWalkthrough({ seenVersion: 2, status: 'skipped' })
+    expect(spy).toHaveBeenCalledTimes(1)
+  })
+})

frontend/src/utils/walkthrough.ts

@@ -0,0 +1,73 @@
+/**
+ * Getting Started walkthrough — persisted invite state (localStorage).
+ *
+ * Mirrors the autosaveSettings.ts pattern: a `homelable.<name>` key plus a
+ * `window` CustomEvent for same-tab sync, so App and SettingsModal stay aligned
+ * without a global store.
+ *
+ * `seenVersion` is stamped with WALKTHROUGH_VERSION when the user finishes or
+ * dismisses the tour. Bump WALKTHROUGH_VERSION whenever new steps ship so
+ * existing users are re-offered the tour exactly once (they may have missed the
+ * new features). A brand-new user starts at seenVersion=null and is offered too.
+ */
+export const WALKTHROUGH_VERSION = 1
+
+export type WalkthroughStatus = 'pending' | 'skipped' | 'completed'
+
+export interface WalkthroughState {
+  seenVersion: number | null
+  status: WalkthroughStatus
+}
+
+const KEY = 'homelable.walkthrough'
+const EVENT = 'homelable:walkthrough-changed'
+
+export const DEFAULT_WALKTHROUGH_STATE: WalkthroughState = { seenVersion: null, status: 'pending' }
+
+function isStatus(v: unknown): v is WalkthroughStatus {
+  return v === 'pending' || v === 'skipped' || v === 'completed'
+}
+
+export function readWalkthrough(): WalkthroughState {
+  try {
+    const raw = localStorage.getItem(KEY)
+    if (!raw) return { ...DEFAULT_WALKTHROUGH_STATE }
+    const parsed = JSON.parse(raw) as Partial<WalkthroughState>
+    return {
+      seenVersion: typeof parsed.seenVersion === 'number' ? parsed.seenVersion : null,
+      status: isStatus(parsed.status) ? parsed.status : 'pending',
+    }
+  } catch {
+    return { ...DEFAULT_WALKTHROUGH_STATE }
+  }
+}
+
+export function writeWalkthrough(state: WalkthroughState): void {
+  try {
+    localStorage.setItem(KEY, JSON.stringify(state))
+    window.dispatchEvent(new CustomEvent(EVENT, { detail: state }))
+  } catch {
+    // ignore quota / SSR
+  }
+}
+
+export function subscribeWalkthrough(listener: (s: WalkthroughState) => void): () => void {
+  const handler = (e: Event) => listener((e as CustomEvent<WalkthroughState>).detail)
+  window.addEventListener(EVENT, handler)
+  return () => window.removeEventListener(EVENT, handler)
+}
+
+/** True when the invite should be offered (new user, or upgraded past the last seen version). */
+export function shouldOfferWalkthrough(state: WalkthroughState = readWalkthrough()): boolean {
+  return state.seenVersion !== WALKTHROUGH_VERSION
+}
+
+/** Stamp the current version so the invite stops auto-showing until the next bump. */
+export function markWalkthroughSeen(status: Exclude<WalkthroughStatus, 'pending'>): void {
+  writeWalkthrough({ seenVersion: WALKTHROUGH_VERSION, status })
+}
+
+/** Clear the stamp so the tour is offered again (used by "Restart" in Settings). */
+export function resetWalkthrough(): void {
+  writeWalkthrough({ ...DEFAULT_WALKTHROUGH_STATE })
+}

frontend/src/walkthrough/WalkthroughInvite.tsx

@@ -0,0 +1,72 @@
+import { useEffect, useState } from 'react'
+import { Compass, X } from 'lucide-react'
+import './walkthrough.css'
+import { Button } from '@/components/ui/button'
+import { useWalkthroughStore } from '@/stores/walkthroughStore'
+import {
+  readWalkthrough,
+  subscribeWalkthrough,
+  shouldOfferWalkthrough,
+  markWalkthroughSeen,
+  type WalkthroughState,
+} from '@/utils/walkthrough'
+
+/**
+ * First-run invite bubble (bottom-right, above the toaster).
+ *
+ *  - Not now         → hide for this session only (no write), reappears next load
+ *  - Don't show again → persist as skipped, stops offering until the next version
+ *  - Getting started  → launch the tour
+ */
+export function WalkthroughInvite() {
+  const [state, setState] = useState<WalkthroughState>(readWalkthrough)
+  useEffect(() => subscribeWalkthrough(setState), [])
+
+  // "Not now" dismissal — session-local, not persisted.
+  const [dismissedThisSession, setDismissedThisSession] = useState(false)
+
+  const isActive = useWalkthroughStore((s) => s.isActive)
+  const start = useWalkthroughStore((s) => s.start)
+
+  if (isActive || dismissedThisSession || !shouldOfferWalkthrough(state)) return null
+
+  return (
+    <div className="fixed bottom-20 right-4 z-[90] w-80 max-w-[calc(100vw-2rem)] rounded-xl border border-[#30363d] bg-[#161b22] p-4 shadow-2xl walkthrough-invite-enter">
+      <button
+        onClick={() => setDismissedThisSession(true)}
+        aria-label="Not now"
+        className="absolute top-2 right-2 text-muted-foreground hover:text-foreground p-1 rounded transition-colors"
+      >
+        <X size={14} />
+      </button>
+      <div className="flex items-start gap-3">
+        <div className="mt-0.5 flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-[#00d4ff]/10 text-[#00d4ff]">
+          <Compass size={18} />
+        </div>
+        <div className="min-w-0">
+          <h3 className="text-sm font-semibold text-foreground">New here? Take the tour</h3>
+          <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+            A 2-minute walkthrough of scanning, devices, and building your canvas.
+          </p>
+        </div>
+      </div>
+      <div className="mt-3 flex items-center justify-end gap-2">
+        <Button
+          variant="ghost"
+          size="sm"
+          className="h-7 px-2 text-xs text-muted-foreground hover:text-foreground"
+          onClick={() => markWalkthroughSeen('skipped')}
+        >
+          Don't show again
+        </Button>
+        <Button
+          size="sm"
+          className="h-7 px-3 text-xs bg-[#00d4ff] text-[#0d1117] hover:bg-[#00d4ff]/90"
+          onClick={start}
+        >
+          Getting started
+        </Button>
+      </div>
+    </div>
+  )
+}

frontend/src/walkthrough/WalkthroughOverlay.tsx

@@ -0,0 +1,219 @@
+import { useEffect, useMemo, useState, useCallback } from 'react'
+import { createPortal } from 'react-dom'
+import { ArrowLeft, ArrowRight, X } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { useWalkthroughStore } from '@/stores/walkthroughStore'
+import { useWalkthroughActions } from './actions'
+import { getSteps, type StepPlacement } from './steps'
+import './walkthrough.css'
+
+const STANDALONE = import.meta.env.VITE_STANDALONE === 'true'
+
+const CARD_W = 320
+const CARD_H_EST = 210
+const GAP = 16
+const PAD = 6 // spotlight padding around the target
+
+/** Coach-card position from the target rect + requested placement. */
+function cardPosition(rect: DOMRect | null, placement: StepPlacement): { left: number; top: number } {
+  const vw = window.innerWidth
+  const vh = window.innerHeight
+  const clampL = (l: number) => Math.max(8, Math.min(l, vw - CARD_W - 8))
+  const clampT = (t: number) => Math.max(8, Math.min(t, vh - CARD_H_EST - 8))
+  if (!rect) return { left: clampL((vw - CARD_W) / 2), top: clampT((vh - CARD_H_EST) / 2) }
+
+  let side = placement
+  if (side === 'auto') {
+    side = rect.right + GAP + CARD_W < vw ? 'right' : rect.left - GAP - CARD_W > 0 ? 'left' : 'bottom'
+  }
+  switch (side) {
+    case 'right': return { left: clampL(rect.right + GAP), top: clampT(rect.top) }
+    case 'left': return { left: clampL(rect.left - GAP - CARD_W), top: clampT(rect.top) }
+    case 'top': return { left: clampL(rect.left), top: clampT(rect.top - GAP - CARD_H_EST) }
+    case 'bottom': return { left: clampL(rect.left), top: clampT(rect.bottom + GAP) }
+    case 'center':
+    default: return { left: clampL((vw - CARD_W) / 2), top: clampT((vh - CARD_H_EST) / 2) }
+  }
+}
+
+export function WalkthroughOverlay() {
+  const { isActive, stepIndex, total, setTotal, next, prev, skip } = useWalkthroughStore()
+  const actions = useWalkthroughActions()
+  const steps = useMemo(() => getSteps(STANDALONE), [])
+  const step = steps[stepIndex]
+
+  // anchorRect: the element the step rings (sidebar/toolbar button). dialogRect:
+  // any open app modal, always kept lit so it stays readable during modal steps.
+  const [anchorRect, setAnchorRect] = useState<DOMRect | null>(null)
+  const [dialogRect, setDialogRect] = useState<DOMRect | null>(null)
+
+  // Keep the store's total in sync with the mode-filtered step list.
+  useEffect(() => {
+    if (isActive) setTotal(steps.length)
+  }, [isActive, steps.length, setTotal])
+
+  // Run the step's action on enter (close leftovers, open the right modal / inject
+  // demo data). Close everything when the tour ends.
+  useEffect(() => {
+    if (!actions) return
+    if (!isActive) { actions.closeAll(); return }
+    actions.closeAll()
+    const key = step?.action as keyof typeof actions | undefined
+    if (key && typeof actions[key] === 'function') (actions[key] as () => void)()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isActive, stepIndex, actions])
+
+  // Track target rects. Polls each frame because modals mount asynchronously after
+  // the step action fires, and layout shifts as they animate in.
+  useEffect(() => {
+    if (!isActive) return
+    let raf = 0
+    const update = () => {
+      const anchorEl = step?.anchor ? document.querySelector(step.anchor) : null
+      setAnchorRect(anchorEl ? anchorEl.getBoundingClientRect() : null)
+      // Any open app modal, excluding our own coach card (inside the overlay).
+      const dialogEl = Array.from(document.querySelectorAll('[role="dialog"]'))
+        .find((el) => !el.closest('[data-walkthrough-overlay]'))
+      setDialogRect(dialogEl ? dialogEl.getBoundingClientRect() : null)
+      raf = window.requestAnimationFrame(update)
+    }
+    update()
+    window.addEventListener('resize', update)
+    window.addEventListener('scroll', update, true)
+    return () => {
+      window.cancelAnimationFrame(raf)
+      window.removeEventListener('resize', update)
+      window.removeEventListener('scroll', update, true)
+    }
+  }, [isActive, stepIndex, step?.anchor])
+
+  const handleKey = useCallback((e: KeyboardEvent) => {
+    if (e.key === 'ArrowRight' || e.key === 'Enter') { e.preventDefault(); next() }
+    else if (e.key === 'ArrowLeft') { e.preventDefault(); prev() }
+    else if (e.key === 'Escape') { e.preventDefault(); skip() }
+  }, [next, prev, skip])
+
+  useEffect(() => {
+    if (!isActive) return
+    window.addEventListener('keydown', handleKey)
+    return () => window.removeEventListener('keydown', handleKey)
+  }, [isActive, handleKey])
+
+  if (!isActive || !step) return null
+
+  const isLast = stepIndex >= total - 1
+  // Ring / card follow the anchor if the step has one, else the open modal.
+  const ringRect = anchorRect ?? dialogRect
+  const pos = cardPosition(ringRect, step.placement ?? 'auto')
+  // Cut-outs keep both the ringed control and any open modal lit.
+  const holes = [anchorRect, dialogRect].filter((r): r is DOMRect => r !== null)
+
+  return createPortal(
+    <div className="fixed inset-0 z-[100]" data-walkthrough-overlay>
+      {/* Backdrop: dim everything except the cut-out holes (multi-hole SVG mask so
+          a ringed button AND an open modal can both stay readable). */}
+      <svg className="pointer-events-none absolute inset-0 h-full w-full">
+        <defs>
+          <mask id="wt-spotlight-mask">
+            <rect x="0" y="0" width="100%" height="100%" fill="white" />
+            {holes.map((r, i) => (
+              <rect
+                key={i}
+                x={r.left - PAD}
+                y={r.top - PAD}
+                width={r.width + PAD * 2}
+                height={r.height + PAD * 2}
+                rx="10"
+                fill="black"
+              />
+            ))}
+          </mask>
+        </defs>
+        <rect x="0" y="0" width="100%" height="100%" fill="#010409" fillOpacity="0.72" mask="url(#wt-spotlight-mask)" />
+      </svg>
+
+      {/* Pulsing ring on the primary target */}
+      {ringRect && (
+        <div
+          className="walkthrough-spotlight--pulse pointer-events-none absolute rounded-lg border-2 border-[#00d4ff]"
+          style={{
+            left: ringRect.left - PAD,
+            top: ringRect.top - PAD,
+            width: ringRect.width + PAD * 2,
+            height: ringRect.height + PAD * 2,
+            transition: 'left 0.25s, top 0.25s, width 0.25s, height 0.25s',
+          }}
+        />
+      )}
+
+      {/* Coach card */}
+      <div
+        role="dialog"
+        aria-modal="false"
+        aria-label="Getting started walkthrough"
+        className="walkthrough-card-enter absolute pointer-events-auto rounded-xl border border-[#30363d] bg-[#161b22] p-4 shadow-2xl"
+        style={{ left: pos.left, top: pos.top, width: CARD_W, transition: 'left 0.25s, top 0.25s' }}
+      >
+        <div className="flex items-start justify-between gap-2">
+          <h3 className="text-sm font-semibold text-foreground">{step.title}</h3>
+          <button
+            onClick={skip}
+            aria-label="Skip walkthrough"
+            className="shrink-0 text-muted-foreground hover:text-foreground p-0.5 rounded transition-colors"
+          >
+            <X size={14} />
+          </button>
+        </div>
+        <p className="mt-1.5 text-xs leading-relaxed text-muted-foreground">{step.body}</p>
+
+        {step.link && (
+          <a
+            href={step.link.href}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="mt-2 inline-flex items-center gap-1 text-xs font-medium text-[#00d4ff] hover:underline"
+          >
+            {step.link.label} <ArrowRight size={12} />
+          </a>
+        )}
+
+        <div className="mt-3 flex items-center justify-between gap-2">
+          {/* Progress dots */}
+          <div className="flex items-center gap-1.5">
+            {steps.map((s, i) => (
+              <span
+                key={s.id}
+                className={`h-1.5 rounded-full transition-all ${
+                  i === stepIndex ? 'w-4 bg-[#00d4ff]' : 'w-1.5 bg-[#30363d]'
+                }`}
+              />
+            ))}
+          </div>
+          <div className="flex items-center gap-1.5">
+            <span className="mr-1 text-[10px] font-mono text-muted-foreground">
+              {stepIndex + 1}/{steps.length}
+            </span>
+            <Button
+              variant="ghost"
+              size="sm"
+              aria-label="Previous step"
+              className="h-7 px-2 text-xs text-muted-foreground hover:text-foreground disabled:opacity-40"
+              onClick={prev}
+              disabled={stepIndex === 0}
+            >
+              <ArrowLeft size={13} />
+            </Button>
+            <Button
+              size="sm"
+              className="h-7 px-3 text-xs bg-[#00d4ff] text-[#0d1117] hover:bg-[#00d4ff]/90"
+              onClick={next}
+            >
+              {isLast ? 'Finish' : <>Next <ArrowRight size={13} className="ml-1" /></>}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  )
+}

frontend/src/walkthrough/__tests__/WalkthroughInvite.test.tsx

@@ -0,0 +1,46 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { renderWithProviders, screen, fireEvent } from '@/test/render'
+import { WalkthroughInvite } from '../WalkthroughInvite'
+import { useWalkthroughStore } from '@/stores/walkthroughStore'
+import { readWalkthrough } from '@/utils/walkthrough'
+
+beforeEach(() => {
+  localStorage.clear()
+  useWalkthroughStore.setState({ isActive: false, stepIndex: 0, total: 0 })
+})
+
+describe('WalkthroughInvite', () => {
+  it('offers the tour to a new user', () => {
+    renderWithProviders(<WalkthroughInvite />)
+    expect(screen.getByText('New here? Take the tour')).toBeInTheDocument()
+  })
+
+  it('is hidden once already seen', () => {
+    localStorage.setItem('homelable.walkthrough', JSON.stringify({ seenVersion: 1, status: 'completed' }))
+    renderWithProviders(<WalkthroughInvite />)
+    expect(screen.queryByText('New here? Take the tour')).not.toBeInTheDocument()
+  })
+
+  it('"Getting started" launches the tour', () => {
+    renderWithProviders(<WalkthroughInvite />)
+    fireEvent.click(screen.getByText('Getting started'))
+    expect(useWalkthroughStore.getState().isActive).toBe(true)
+    // Invite hides while the tour is active.
+    expect(screen.queryByText('New here? Take the tour')).not.toBeInTheDocument()
+  })
+
+  it('"Don\'t show again" persists and hides', () => {
+    renderWithProviders(<WalkthroughInvite />)
+    fireEvent.click(screen.getByText("Don't show again"))
+    expect(readWalkthrough().status).toBe('skipped')
+    expect(screen.queryByText('New here? Take the tour')).not.toBeInTheDocument()
+  })
+
+  it('"Not now" hides without persisting', () => {
+    renderWithProviders(<WalkthroughInvite />)
+    fireEvent.click(screen.getByLabelText('Not now'))
+    expect(screen.queryByText('New here? Take the tour')).not.toBeInTheDocument()
+    // Not persisted → would be offered again on next load.
+    expect(readWalkthrough().seenVersion).toBeNull()
+  })
+})

frontend/src/walkthrough/__tests__/WalkthroughOverlay.test.tsx

@@ -0,0 +1,46 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { renderWithProviders, screen, fireEvent, cleanup, act } from '@/test/render'
+import { WalkthroughOverlay } from '../WalkthroughOverlay'
+import { getSteps } from '../steps'
+import { useWalkthroughStore } from '@/stores/walkthroughStore'
+
+const TOTAL = getSteps(false).length
+
+const startTour = () => act(() => { useWalkthroughStore.getState().start() })
+
+beforeEach(() => {
+  localStorage.clear()
+  useWalkthroughStore.setState({ isActive: false, stepIndex: 0, total: 0 })
+})
+afterEach(() => cleanup())
+
+describe('WalkthroughOverlay', () => {
+  it('renders nothing while inactive', () => {
+    renderWithProviders(<WalkthroughOverlay />)
+    expect(screen.queryByText('Welcome to Homelable')).not.toBeInTheDocument()
+  })
+
+  it('shows the first step and progress when active', () => {
+    renderWithProviders(<WalkthroughOverlay />)
+    startTour()
+    expect(screen.getByText('Welcome to Homelable')).toBeInTheDocument()
+    expect(screen.getByText(`1/${TOTAL}`)).toBeInTheDocument()
+  })
+
+  it('advances and rewinds between steps', () => {
+    renderWithProviders(<WalkthroughOverlay />)
+    startTour()
+    fireEvent.click(screen.getByText('Next'))
+    expect(screen.getByText('Scan your network')).toBeInTheDocument()
+    fireEvent.click(screen.getByLabelText('Previous step'))
+    expect(screen.getByText('Welcome to Homelable')).toBeInTheDocument()
+  })
+
+  it('skip closes the overlay', () => {
+    renderWithProviders(<WalkthroughOverlay />)
+    startTour()
+    fireEvent.click(screen.getByLabelText('Skip walkthrough'))
+    expect(useWalkthroughStore.getState().isActive).toBe(false)
+    expect(screen.queryByText('Welcome to Homelable')).not.toBeInTheDocument()
+  })
+})

frontend/src/walkthrough/__tests__/steps.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest'
+import { getSteps, STEPS } from '../steps'
+
+describe('getSteps', () => {
+  it('returns every step in full mode', () => {
+    expect(getSteps(false)).toHaveLength(STEPS.length)
+  })
+
+  it('drops backend-only (mode:full) steps in standalone', () => {
+    const standalone = getSteps(true)
+    expect(standalone.every((s) => s.mode !== 'full')).toBe(true)
+    expect(standalone.length).toBeLessThan(STEPS.length)
+    const ids = standalone.map((s) => s.id)
+    // Canvas-only steps survive; backend-only steps are filtered out.
+    expect(ids).toEqual(expect.arrayContaining(['welcome', 'nodes', 'grouping', 'style', 'end']))
+    expect(ids).not.toContain('scan')
+    expect(ids).not.toContain('scan-history')
+    expect(ids).not.toContain('inventory')
+    expect(ids).not.toContain('imports')
+  })
+
+  it('ends on a step with a GitHub link (the full-mode recap in standalone)', () => {
+    const last = getSteps(true).at(-1)
+    expect(last?.id).toBe('end')
+    expect(last?.link?.href).toContain('github.com')
+  })
+})

frontend/src/walkthrough/actions.ts

@@ -0,0 +1,30 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Bridge between tour steps and the App's modal/canvas controls. App builds the
+ * concrete implementation from its useState setters and provides it here; the
+ * overlay resolves each step's `action` string to a function on this object.
+ *
+ * `closeAll` is called before every step's action so leftover modals from the
+ * previous step are dismissed.
+ *
+ * Grows as steps land (openInventoryDemo, editDemoNode, openStyle, …).
+ */
+export interface WalkthroughActionApi {
+  closeAll: () => void
+  openScanConfig: () => void
+  openScanHistoryDemo: () => void
+  openInventoryDemo: () => void
+  editFirstNode: () => void
+  selectTwoNodes: () => void
+  openStyle: () => void
+  openZigbeeImport: () => void
+}
+
+const WalkthroughActionsContext = createContext<WalkthroughActionApi | null>(null)
+
+export const WalkthroughActionsProvider = WalkthroughActionsContext.Provider
+
+export function useWalkthroughActions(): WalkthroughActionApi | null {
+  return useContext(WalkthroughActionsContext)
+}

frontend/src/walkthrough/demoTourData.ts

@@ -0,0 +1,65 @@
+import type { ScanRun } from '@/components/modals/ScanHistoryModal'
+import type { PendingDevice } from '@/components/modals/PendingDeviceModal'
+
+/**
+ * Canned data injected into the real modals during the tour, so the demo steps
+ * look alive on a fresh install without hitting the backend. Never persisted.
+ */
+export const DEMO_SCAN_RUNS: ScanRun[] = [
+  {
+    id: 'tour-scan-running',
+    status: 'running',
+    kind: 'ip',
+    ranges: ['192.168.1.0/24'],
+    devices_found: 12,
+    // 8s ago so the live "Duration" reads a realistic elapsed time.
+    started_at: new Date(Date.now() - 8000).toISOString(),
+    finished_at: null,
+    error: null,
+  },
+  {
+    id: 'tour-scan-done',
+    status: 'done',
+    kind: 'ip',
+    ranges: ['192.168.1.0/24'],
+    devices_found: 9,
+    started_at: new Date(Date.now() - 3600_000).toISOString(),
+    finished_at: new Date(Date.now() - 3560_000).toISOString(),
+    error: null,
+  },
+]
+
+export const DEMO_PENDING_DEVICES: PendingDevice[] = [
+  {
+    id: 'tour-dev-1',
+    ip: '192.168.1.20',
+    mac: 'AA:BB:CC:DD:EE:20',
+    hostname: 'synology-nas',
+    os: 'DSM 7.2',
+    services: [{ port: 5000, protocol: 'tcp', service_name: 'Synology DSM', category: 'nas' }],
+    suggested_type: 'nas',
+    status: 'pending',
+    discovery_source: 'arp',
+    friendly_name: 'Synology NAS',
+    vendor: 'Synology',
+    model: 'DS920+',
+    discovered_at: new Date(Date.now() - 120_000).toISOString(),
+    canvas_count: 0,
+  },
+  {
+    id: 'tour-dev-2',
+    ip: '192.168.1.30',
+    mac: 'AA:BB:CC:DD:EE:30',
+    hostname: 'pi-hole',
+    os: null,
+    services: [{ port: 80, protocol: 'tcp', service_name: 'Pi-hole', category: 'network' }],
+    suggested_type: 'generic',
+    status: 'pending',
+    discovery_source: 'arp',
+    friendly_name: 'Pi-hole',
+    vendor: 'Raspberry Pi',
+    model: null,
+    discovered_at: new Date(Date.now() - 90_000).toISOString(),
+    canvas_count: 0,
+  },
+]

frontend/src/walkthrough/steps.ts

@@ -0,0 +1,121 @@
+/**
+ * Declarative Getting Started steps.
+ *
+ * `anchor` is a CSS selector for the element to ring/spotlight (undefined → the
+ * overlay lights any open modal, or centers the card). `action` is a key resolved
+ * against the walkthrough actions context on step enter (opens a modal, injects
+ * demo data, selects nodes, …). `mode: 'full'` marks a backend-only step that is
+ * filtered out of the standalone/public build. `link` renders a link in the card
+ * (used for the closing "questions?" step).
+ */
+export type StepPlacement = 'center' | 'top' | 'bottom' | 'left' | 'right' | 'auto'
+
+export interface TourStep {
+  id: string
+  title: string
+  body: string
+  anchor?: string
+  placement?: StepPlacement
+  action?: string
+  mode?: 'full' | 'all'
+  link?: { label: string; href: string }
+}
+
+export const STEPS: TourStep[] = [
+  {
+    id: 'welcome',
+    title: 'Welcome to Homelable',
+    body: 'Take a quick tour of the main features — scanning your network, managing devices, and building your canvas. You can skip anytime and restart later from Settings.',
+    placement: 'center',
+    mode: 'all',
+  },
+  {
+    id: 'scan',
+    title: 'Scan your network',
+    body: 'Start here: run an IP scan to auto-discover devices on your network. Pick the ranges and ports, then launch — discovered devices land in your inventory for review.',
+    anchor: '[data-tour="scan-network"]',
+    placement: 'right',
+    action: 'openScanConfig',
+    mode: 'full',
+  },
+  {
+    id: 'scan-history',
+    title: 'Follow scan progress',
+    body: 'Scan History shows every run live. A running scan updates in place with elapsed time and device count — you can stop it here too. (This is example data.)',
+    placement: 'left',
+    action: 'openScanHistoryDemo',
+    mode: 'full',
+  },
+  {
+    id: 'inventory',
+    title: 'Review discovered devices',
+    body: 'Discovered devices wait in your inventory. For each one you can approve it onto the canvas, hide it, or delete it — with detected services and vendor shown. (Example devices.)',
+    placement: 'left',
+    action: 'openInventoryDemo',
+    mode: 'full',
+  },
+  {
+    id: 'nodes',
+    title: 'Your devices on the canvas',
+    body: 'Approved devices become nodes on the canvas. Each shows live status, IP, hostname and running services. Drag to arrange them and draw links between them.',
+    anchor: '.react-flow__node',
+    placement: 'auto',
+    mode: 'all',
+  },
+  {
+    id: 'node-edit',
+    title: 'Edit a device',
+    body: 'Double-click any node to edit it: name, type, IP, the status-check method, appearance, and its parent (e.g. a VM inside a Proxmox host). Changes are yours until you Save.',
+    placement: 'left',
+    action: 'editFirstNode',
+    mode: 'all',
+  },
+  {
+    id: 'text-zone',
+    title: 'Annotate with text & zones',
+    body: 'Add free Text labels and Zones (colored rectangles) to document your layout — group a rack, mark a VLAN, or leave a note. Both live under the canvas actions.',
+    anchor: '[data-tour="add-zone"]',
+    placement: 'right',
+    mode: 'all',
+  },
+  {
+    id: 'grouping',
+    title: 'Group related devices',
+    body: 'Select multiple nodes, then Create Group to box them together and drag them as one — perfect for a rack, a site, or a subnet.',
+    anchor: '[data-tour="create-group"]',
+    placement: 'left',
+    action: 'selectTwoNodes',
+    mode: 'all',
+  },
+  {
+    id: 'style',
+    title: 'Make it yours',
+    body: 'Switch the canvas theme from Style, or fine-tune colors, borders and fonts per node type. Your homelab, your look.',
+    anchor: '[data-tour="style"]',
+    placement: 'bottom',
+    action: 'openStyle',
+    mode: 'all',
+  },
+  {
+    id: 'imports',
+    title: 'Import from your stack',
+    body: 'Already running Zigbee2MQTT, Z-Wave JS, or Proxmox? Import devices directly from them instead of scanning — one click brings the whole topology in.',
+    anchor: '[data-tour="zigbee-import"]',
+    placement: 'right',
+    action: 'openZigbeeImport',
+    mode: 'full',
+  },
+  {
+    id: 'end',
+    title: "You're all set",
+    body: "That's the tour! Build your map, save it, and share a read-only view. In full mode you also get network scanning, a device inventory, and Zigbee / Z-Wave / Proxmox import. Have a question or an idea?",
+    placement: 'center',
+    mode: 'all',
+    link: { label: 'Ask on GitHub', href: 'https://github.com/Pouzor/homelable/issues' },
+  },
+]
+
+/** Steps for the current build — backend-only steps are dropped in standalone. */
+export function getSteps(standalone: boolean): TourStep[] {
+  return STEPS.filter((s) => s.mode !== 'full' || !standalone)
+}

frontend/src/walkthrough/walkthrough.css

@@ -0,0 +1,29 @@
+/* Getting Started walkthrough animations. Kept in a shared stylesheet (imported
+   by both the invite bubble and the overlay) so keyframes exist regardless of
+   which component is mounted. */
+
+@keyframes wt-invite-enter {
+  from { opacity: 0; transform: translateY(12px); }
+  to { opacity: 1; transform: none; }
+}
+.walkthrough-invite-enter { animation: wt-invite-enter 0.25s ease-out; }
+
+@keyframes wt-card-enter {
+  from { opacity: 0; transform: translateY(6px); }
+  to { opacity: 1; transform: none; }
+}
+.walkthrough-card-enter { animation: wt-card-enter 0.2s ease-out; }
+
+/* The dim surround is drawn by the overlay's SVG mask; this is just the pulsing
+   cyan ring around the primary target (outline so it sits outside the border). */
+.walkthrough-spotlight--pulse { animation: wt-pulse 1.8s ease-in-out infinite; }
+@keyframes wt-pulse {
+  0%, 100% { outline: 0px solid rgba(0, 212, 255, 0.55); }
+  50% { outline: 7px solid rgba(0, 212, 255, 0); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .walkthrough-invite-enter,
+  .walkthrough-card-enter,
+  .walkthrough-spotlight--pulse { animation: none; }
+}