App Tour
Omniscio's guided-onboarding system — the full-screen overlays and spotlight tooltips that walk you through a feature step by step, the tours on offer and where each one surfaces, the JSON that defines them, and how to author a new tour or anchor.
On this page
What it is
The App Tour is Omniscio's built-in guided-onboarding system — full-screen overlays and spotlight tooltips that walk you through a feature step by step, highlighting the actual element you'd click and explaining what it does. Tours are opt-in walkthroughs — no tour ever force-runs; you start them yourself. A few also surface a one-time offer toast you can accept or dismiss ("Never show again"): when you first turn on a feature (Gmail, Voice, Screen Capture), and — for the Start a New Hub tour — right after you finish onboarding. You start a tour from Settings → Setup Wizards, which lists every available tour with a checkmark next to the ones you've completed. Picking a tour dims the rest of the app, cuts a spotlight hole around the relevant element, and shows a tooltip card next to it; an overlay step (welcome / completion cards) replaces the spotlight with a centered card. Use Next / Back to step through, Esc to exit, and Skip to mark the tour as completed without finishing it.
A second entry point — the onboarding demo tour — runs once during first-time setup. It's a sandboxed walkthrough of the app inside a fake project with fake sessions and messages (the scene blocks on most steps inject the demo state on the fly so you can see how the inbox, sessions list, and conversation view behave without ever touching real data; the steps that carry a real action or a full-screen overlay do not need one). It is NOT advertised in the Setup Wizards tour list; it runs as a step inside first-time setup, and afterwards via Settings → Setup Wizards → Show me around the app again. (Until 2026-10-07 the sidebar's empty-projects Get Started card also carried a "Take the tour" link; that card was removed.) A few of the demo's steps are hands-on — instead of pressing Next you perform the real action (add a project, start a session, open the session that needs you) and the tour advances when you do; because the demo is sandboxed, nothing real is created (see Hands-on (interactive) steps below).
A third variant — the keyboard demo (onboarding-demo-hotkeys, dev-gated) — is a keystroke-driven overlay derived at load time from the onboarding demo. It reuses the same 34 steps and the same scene blocks (same sandboxed demo data), but each step advances on a key instead of Next/click: the tooltip shows a key-cap and you press it. The keys are the app's REAL shortcuts (N new session, Enter send, R reply, E archive, I inbox, H snooze; Space for explainer steps), resolved from your effective keybindings so they stay correct even if you rebind. Those keys normally fire real, sometimes-paid actions, so the safety model is a hard gate: while this tour is active, AppTour calls useHardGate(...), and the global shortcut dispatch (useKeyboardShortcuts) early-returns on isHardGateOpen() — every real shortcut stands down wholesale, so pressing N only advances the tour (the next step's scene simulates the result) and can never spawn a session. See app-tour-hotkey-demo-contract.md. It's hidden from the Setup Wizards tour list and launched from its own dev-gated Setup Wizards card.
A fourth variant — the Managing Your Sessions practice tour (manage-sessions) — is an on-demand demo tour launched from the toolbar Tours menu (not first-run). Like the onboarding demo it runs on a sandboxed sample workspace: its scene blocks inject a fake project + sessions, and because it's a demo tour (in DEMO_TOUR_IDS), the demo controller (useDemoTour) hides your real sessions and restores them on exit — nothing real is touched. It walks through pausing/resuming, snoozing (opening the snooze picker), undo, and archiving on the sample session — each beat showing the result plus a key-cap (P / H / Ctrl+Z / E) — then narrates the right-click actions (move / rename / color / pin) and the Stop-vs-Pause distinction. It is scene-driven and advances with Next (the key-caps teach the shortcuts; it is NOT keystroke-gated like the keyboard demo, so it needs no hard gate). It launches through its own DemoTourRunner flag (manageSessionsTourActive), strictly parallel to the keyboard demo and off the first-run chain, and is hidden from the plain Setup-Wizards list so it can only run through that demo runner (the plain startTour path would paint its cards over the real app with no sandbox behind them).
Tour authoring is pure JSON. Every tour lives in src/renderer/src/features/app-tour/tours/<slug>.json, gets Zod-validated at app boot via loadAllTours() in tour-loader.ts, and hydrates into the runtime TourDefinition shape. (The one exception is the keyboard demo, which has no file: deriveHotkeyDemo() in tour-hotkey.ts builds it from onboarding-demo.json plus a small per-step overlay table.) There are no JavaScript helpers (spotlight() / overlay()) any more — you write JSON, the loader does the rest, and if the file fails the schema the app refuses to boot (so a bad tour file is impossible to ship by accident).
Where to find it
How to use it (end-user)
- Open Settings → Setup Wizards — every available tour is listed with a checkmark for the ones you've completed.
- Click a tour to start it — the rest of the app dims, the relevant element gets a spotlight, and a tooltip appears next to it (or a centered overlay card for welcome / completion steps).
- Step through with Next / Back — phase dots at the top of the tooltip show your progress; phases with an empty
label(typically the final "completion" phase) are hidden from the dots. - Exit with Esc or Skip — both mark the tour as completed in
tourCompletionsso the next visit shows a checkmark. - Some tours suggest a follow-up — if the tour's JSON declares a
nextTourSuggestion, finishing it pops a toast 1 second later inviting you into the next tour (suppressed for experienced users with ≥ 10 sessions).
The progress dots, Skip button, and Esc handler are all part of the shared <AppTour /> overlay component (it portals into document.body, so it sits above every modal). The actual highlighted element comes from a CSS-mask cutout — the page itself is not modified, so links and buttons under the dim layer remain non-interactive until the tour exits.
A fifth first-run surface is not a JSON tour at all — the Halo Spotlight Tour (HaloSpotlightTour.tsx, mounted globally from GlobalModals.tsx). It is a short, auto-advancing spotlight sequence (3 s per step, a 3 px ring) that walks the Mission Control toolbar and sidebar once, right after onboarding. useHaloSpotlightGate decides whether it fires, and every clause in it is a real guard: not already completed (tourCompletions['halo-spotlight']), onboarding finished, Mission Control's own first-run setup finished (pmSetupComplete) with no setup screen open (usePmSetupWizardStore.activeModal === null) — so it never runs on top of, or instead of, the "Got data somewhere else?" screen, which with the sample project and the Home comeback card replaced the old intro tour — Mission Control the ACTIVE project, no AppTour already running (the two overlays would paint over each other), and desktop-only — the anchors it targets do not exist on mobile. Mission Control is matched through isVirtualProjectActive, not by comparing activeProjectId to the sentinel, because a project UUID never equals a sentinel string and that direct comparison was the bug that stopped this tour firing at all. Because it is not registered in tour-steps.ts, it has no Setup Wizards row and never appears in the tour list below; it is a first-run surface only.
The tours
| Slug | Label | Where it surfaces |
|---|---|---|
core-workflow |
Your First Session | Setup Wizards |
sessions-productivity |
Productivity Power-Ups | Setup Wizards |
recipes |
Recipes & Filters | Setup Wizards |
gmail |
Gmail | Setup Wizards |
rss |
RSS & Webhooks | Setup Wizards |
automations |
Filters | Setup Wizards |
archive-search |
Archive & Search | Setup Wizards |
onboarding-tour |
Welcome to Omniscio | Setup Wizards — replay button (behind the Onboarding Tour flag); auto-runs after first-run onboarding |
voice-commands |
Voice Commands | Setup Wizards |
settings-tour |
Settings Deep Dive | Setup Wizards |
start-next-project |
Start a New Project | Setup Wizards · one-time offer right after onboarding |
mindmap |
Mind Map | Tours menu (while Mind Map is on) · in-Map button |
writer-onboarding |
Writer Studio Tour | Writer Studio first-open offer (Writer-gated) |
sms |
SMS | SMS onboarding flow only |
screen-recorder |
Screen Capture | Screen Capture settings — "Take the tour" |
onboarding-demo |
Interactive Demo | First-time setup / Setup Wizards |
onboarding-demo-hotkeys |
Keyboard Demo | Setup Wizards (dev-gated) |
manage-sessions |
Managing Your Sessions | Tours menu — dedicated button → demo runner |
tasks-v2 |
Tasks | Tasks MORE menu — "Guided Tour" entry |
vault-kms |
Vault | Vault toolbar — "Guided Tour" button |
__example__ |
Placeholder example tour | Hidden — bootstrap template |
Retired —
welcome("Getting Started"). Removed 2026-07. It spotlighted session-only UI (message box, quick replies, file explorer) that doesn't exist for a brand-new user with nothing set up, so it narrated at empty space; launched from the toolbar over Settings it could also strand the user (its Escape handler swallowed Settings' own Esc-to-close). The sandboxed onboarding demo — surfaced as Interactive Demo, the new-user "Take the tour" CTA, and the first-run walkthrough — is now the single intro tour: it stands up its own sample projects/sessions beneath the walkthrough, so it works with nothing set up. Relatedly, every tour launch now navigates to its home view (dashboard, or the Mind Map) BEFORE the overlay starts, so a tour never renders on top of another screen — seesrc/renderer/src/app/tour-launch.ts. Guard:welcome-tour-retired.test.ts.
The tours hidden from Setup Wizards (sms, onboarding-demo, onboarding-demo-hotkeys, manage-sessions, __example__, mindmap, writer-onboarding, start-next-project, onboarding-tour, tasks-v2, vault-kms) live in the SETTINGS_MENU_HIDDEN_TOUR_IDS set in tour-steps.ts. They're still resolvable via getTourById() so the surfaces that own them can start them directly. writer-onboarding (Writer Studio Tour) is hidden because Writer Studio is a gated feature — it launches as a first-open offer from the Writer view (WriterView.tsx) only for users with Writer enabled. mindmap is hidden because the Mind Map is a feature the person can switch off (it is on by default, in Settings → Features) — its tour is surfaced only through feature-gated entry points: a conditional row in the Tours dropdown, shown while the feature is on, and a "Take a tour" button in the Mind Map toolbar. It is never offered automatically. Keeping it out of the ungated ALL_TOURS list is what stops it leaking into the Setup Wizards list for someone who has switched the feature off. See app-tour-mindmap-tour-contract.md. onboarding-demo-hotkeys (the keyboard demo) is likewise dev-gated and launched from its own Setup Wizards card — see app-tour-hotkey-demo-contract.md. manage-sessions (Managing Your Sessions) is hidden for the same structural reason as a demo tour: it must run through its own DemoTourRunner (which stands up the sandbox and hides/restores real sessions), so it's launched from a dedicated Tours-menu button, never the plain startTour path that the ungated list uses. tasks-v2 (Tasks) is hidden because it launches from the Tasks MORE menu's "Guided Tour" entry — it belongs to the Tasks feature, not the general Setup Wizards. vault-kms (Vault) is hidden for the same reason: it launches from a "Guided Tour" button in the Vault's editor toolbar (KmsEditorToolbarStrip.tsx), not the general Setup Wizards — an 8-step spotlight tour covering note creation, formatting, backlinks/tags, Vault Overview, AI agent tools, and appearance settings.
A command-line or link start (POST /ui/tour/start, omniscio://start-tour/<id>) accepts only the tours on the Setup Wizards list. A hidden tour's id is answered with an "unknown tour" message and nothing starts, because only the surface that owns a hidden tour sets up what its cards point at — starting one bare would paint its cards over your real app.
How it behaves
Hands-on (interactive) steps
A spotlight step can carry an interactive block to make it hands-on — the tour hides Next and advances only when the user performs the highlighted action (the active-learning counterpart to read-and-Next). Invariants are locked by app-tour-interactive-contract.md.
{
"kind": "spotlight",
"anchor": "sidebar-add-project-button",
"title": "Adding Projects",
"description": [{ "type": "text", "text": "This is where you add project folders." }],
"interactive": { "advanceOn": { "type": "click" } }
}
Two modes:
- Scripted (the onboarding demo, and the default). The tour's full-screen click-catcher stays on top; a click over the highlighted element is detected via
document.elementsFromPoint(so it sees the real target beneath the catcher) and the tour advances — the real handler never fires, so clicking the demo's "Start a session" costs nothing and creates nothing. The next step's scene shows the result. The onboarding demo is ALWAYS scripted, regardless of any flag. - Live (
"live": true, for real feature tours). The catcher drops pointer-events so the real action runs, and the tour watches the declaredadvanceOnoutcome. Honored ONLY in a non-demo tour on an anchor flaggedinteractiveSafein the registry — the guardtests/unit/lint/2a/tour-interactive-safe-anchor.test.tsfails the build otherwise. One tour ships withlivetoday: Welcome to Omniscio (onboarding-tour) runs two hands-on steps,ot-03-open-sessionandot-06-open-inbox, where you click the real session row and the real inbox button to advance. The seam exists so other real tours can opt in as their anchors are flagged.
advanceOn — what counts as "done": { "type": "click" } (clicked the highlighted anchor) or { "type": "anchor-appears", "anchor": "<name>" } (a named element mounted — used by live mode to watch an outcome).
Guided-but-rescuable. Next is hidden (you advance by doing), but a "Show me" escape appears if the user stalls (~8s), clicks the wrong spot (with a corrective nudge), or the target never shows — and a missing target degrades to a normal Next step, so nobody is ever stuck.
Authoring one: add "interactive": { "advanceOn": { "type": "click" } } to a spotlight step whose anchor is a clickable control, and make sure the NEXT step's scene depicts the result of the action (in the demo, advancing replays the scripted result).
Related
Related pages: first-time-setup.md covers the first-run setup the onboarding demo runs inside, mindmap.md and kms.md are the gated features whose guided tours launch from their own toolbars rather than the Setup Wizards section, and keyboard-shortcuts.md documents the shortcuts the keyboard demo teaches.
Last verified 2026-10-01