Onboarding

The onboarding sidebar SHALL display automatically for new users and respect dismissal preferences.

- The sidebar SHALL appear on first visit when the user has not completed onboarding
- The sidebar SHALL appear as a right-aligned drawer on desktop
- The sidebar SHALL appear as a full-screen overlay on mobile devices to prevent interaction issues
- The sidebar SHALL NOT appear if the user has explicitly dismissed it ("Don't show again")
- The sidebar SHALL NOT appear if the user has completed all onboarding steps
- Closing the sidebar (X button) SHALL hide it for the remainder of the current browser tab session; it SHALL NOT reopen on in-session navigations or re-renders but SHALL reopen when the user opens a new tab or restarts the browser
- "Don't show again" SHALL hide the sidebar permanently until the user manually re-opens it
- The sidebar SHALL be re-openable via a help menu or sidebar entry point
- The sidebar SHALL animate in (slide from right) and out (slide to right) with a CSS transition rather than appearing/disappearing instantly
- When closed, the sidebar and its backdrop SHALL be non-interactive: pointer-events-none, aria-hidden="true", and inert to prevent invisible click-blocking and focus trapping
- The slide transition SHALL respect prefers-reduced-motion by disabling the animation for users who prefer reduced motion

Onboarding steps SHALL be organized into stages with clear progress indicators.

- Steps SHALL be grouped into stages (e.g., "Define Your Standard", "Connect Your Workflow", "The Hello World")
- Each step SHALL have: id, title, description, time estimate, CTA label, CTA action
- Each step SHALL have a completion predicate based on user state
- Steps MAY be marked as skippable
- The current stage SHALL be expanded by default; other stages SHALL be collapsed
- Progress text SHALL show completed count and estimated remaining time
- A visual progress bar SHALL render below the text counter, filling proportionally to completedSteps / totalSteps

Steps SHALL complete automatically or via explicit user action.

- Steps with completion predicates SHALL mark complete when the predicate returns true
- Live updates SHALL occur via SSE when backend detects step completion (e.g., first email received)
- Completed steps SHALL display a checkmark and be collapsed, without an infinite animation
- Skipped steps SHALL display a "Skipped" label
- Skipping a step SHALL advance to the next step in the same stage

Step CTAs SHALL perform their configured actions.

- navigate action SHALL navigate to the specified route within the app
- external action SHALL open the specified URL in a new tab
- modal action SHALL open the specified modal (e.g., email verification)
- trigger action SHALL execute the specified action (e.g., copy email to clipboard)
- Copy actions SHALL display toast feedback ("Email copied to clipboard")

Onboarding state SHALL persist across sessions.

- hasDismissedGuide (boolean) SHALL persist to localStorage
- hasCompletedOnboarding (boolean) SHALL persist to localStorage
- skippedStepIds (string[]) SHALL persist to localStorage
- isMinimised (boolean) SHALL be session-only (resets on refresh)
- Persistence SHALL use the Zustand persist middleware with partialize to exclude session-only state

The onboarding flow SHALL complete when all steps are done or skipped.

- Completing all steps SHALL mark hasCompletedOnboarding = true
- The sidebar SHALL display a success message before closing
- The sidebar SHALL be re-openable via help menu even after completion
- The footer SHALL display "Up next: [current step title]" until all steps are complete

The onboarding stage list SHALL be selectable based on the current host so tenant deployments can present domain-specific guidance.

The incentives onboarding flow SHALL guide users to provide property context, request incentives, and view results.

The system SHALL update HiH onboarding flags as users complete incentives actions.

The sidebar's "Setup Guide" toggle button SHALL display a badge showing the number of remaining steps when onboarding is incomplete and not dismissed.

- The badge SHALL show the count of steps that are neither completed nor skipped
- The badge SHALL NOT render when the count is zero
- The badge SHALL NOT render when hasCompletedOnboarding is true
- The badge SHALL NOT render when hasDismissedGuide is true
- The badge SHALL be a small, colored indicator attached to the toggle button