Add Tour

4. Never navigate for the user: use an entry

If a step's target is behind something (a collapsed sidebar, another page, an unopened item), don't open it from the tour. Give the step an entry:

{
  target: REPORTS_TOUR.chart,
  entry: VIEW_SHELL_TOUR.sidebarToggle,
  entryLabel: 'Open the sidebar to continue the tour',
  title: '…',
  description: '…',
}

While the target is missing and the entry is shown, the card hides, a beacon marks the entry, and a small card beside it shows entryLabel with Skip. The beacon stays until the target appears, however the user gets there. Register the entry control as a target like any other.

• Keep entryLabel short and imperative: "Open a channel or DM to continue".
• Chain entries when the entry itself can be hidden. The first shown one wins, so list the real control first and the sidebar toggle last: entry: [CHANNELS_TOUR.conversation, VIEW_SHELL_TOUR.sidebarToggle]. With the sidebar collapsed the beacon marks the toggle; once it opens, the beacon moves to the row.
• ViewTour appends VIEW_SHELL_TOUR.sidebarToggle to every step that has a target, so a step whose target is in a collapsed sidebar always marks the toggle. You still need it explicitly only as the last link of a chain you write yourself.
• A view that collapses its sidebar itself instead of through ViewShell (like Customers' NavigationToggle) must register its own expand control as VIEW_SHELL_TOUR.sidebarToggle, or those steps will float.
• Point entries at a specific control, not a large container. When many elements share a target (every conversation row), the top-most one on screen is used.

5. Mount it

Mount once, inside the view's split (usually in ViewShell.Main or next to the list):

<ViewTour tour={reportsTour} />
<ViewTour tour={tasksTour} actions={<ImportLinearAction />} />  // extra CTAs

• For SoupView-based routes, pass it through the slot: <SoupView … tour={<ViewTour tour={callsTour} />} />.
• Don't put it inside a <Show> branch that remounts on navigation, or the tour restarts at step 1.
• Don't gate it on desktop or on a flag yourself; ViewTour already checks both. All tours sit behind the enableInAppTours flag (enable-in-app-tours in PostHog). To see tours on the local dev server, start it with VITE_ENABLE_IN_APP_TOURS=true.
• Don't pass step callbacks that change pages or open panels.

6. Test and document

• Unit behavior of the primitive lives in Tour/Tour.test.tsx and app behavior in features/tours/ViewTour.test.tsx; add cases there when you change them.
• The primitive's gallery page is Tour/Tour.docs.tsx.
• Progress is saved per user in local storage under macro:tour:<id> (completed, dismissed, or the active step). Changing a tour's steps doesn't reset it for users who finished it; bump the id only if everyone must see the new version.
• Check it in a browser with VITE_ENABLE_IN_APP_TOURS=true: on localhost the tour reopens on every mount. Walk every step, including one that waits on an entry, once with the sidebar open and once collapsed.
• Update docs/AGENT_GUIDE/view-tours.md when a view gains a tour or its steps change.