Welcome Tour (BeakerBot)

What the welcome tour actually is

When you create a brand-new ResearchOS user, BeakerBot pops up to show you around. The tour runs on your real account, against your real local-first data folder. Anything BeakerBot creates (a sample project, a placeholder method, a first experiment) lands on disk just like normal work. At the end BeakerBot plays a short goodbye animation and auto-cleans the demo artifacts in the background, leaving you with your first real project.

Three things are true about every run.

• The tour is one continuous experience inside the app, not a separate demo sandbox. There is no fake fixture you discard on close.
• BeakerBot drives the pacing with a Got it, next or Next button on each step. You can also click Skip this step on any individual step, or the persistent I've got it from here link in the footer to jump straight to the goodbye screen.
• Closing the tab mid-tour is safe. The next time you open the folder, BeakerBot offers Resume, Restart, or Discard.

Who sees the tour

Nobody, by default. The auto-fire path is off, so a fresh account lands straight on the normal empty state with no tour, no banner, and no nag. The rest of this page describes how the tour behaved while it was live, kept for reference and for the parts that still ship (the setup questions used to seed your visible tabs).

Phase 1, setup questions

The first few minutes are a short Q&A that BeakerBot uses to shape the rest of the tour and which tabs appear in your sidebar. Every question is a radio pick with a sensible default if you click Skip this step.

Q1, solo or lab?

The first call is whether you are flying solo (one user, your own account) or running a multi-person lab (everyone points their ResearchOS at the same shared folder). The pick determines whether the PI follow-up question (Q1c, below) fires.

Q1c, are you the PI?

Conditional on Q1 = Lab. After picking Lab, BeakerBot follows up with a single binary question. Are you the PI, or are you a member? Picking PI sets account_type to "lab_head" on this account. Picking Member leaves it at the default. One person in the lab fills the PI slot. The picker badge in the login screen, the audit log, and the Lab Overview surface are all gated on the resulting account_type. See PI.

Q2 through Q6, feature picks

Four questions about ResearchOS surfaces and preferences. The numbering skips Q5, that slot was retired before launch.

• Q2: Will you track lab purchases? (Yes / No / Maybe later)
• Q3: Want calendar feeds? (Yes / No / Maybe later)
• Q4: Want a goal-tracking page? (Yes / No / Maybe later)
• Q6: AI Helper prompt size. ResearchOS can paste a system prompt into Claude, ChatGPT, or Gemini so the assistant understands ResearchOS terminology. Full is the default. Medium and Minimal trim the prompt for smaller-context models. No or Maybe later skips the AI Helper tour cluster entirely.

These answers drive both which tabs appear in your sidebar and which conditional walkthrough clusters fire in Phase 2.

Q7, Links

The final setup question asks whether you want a tab for saving bookmarks, things like VPN links, lab calendars, freezer inventory spreadsheets, manuscript drafts, and so on. Each card holds a URL plus a label so you can jump straight to the resource.

The tab is labeled Links for every account type. On a lab account it is a shared tab visible to everyone in the lab. Saying yes to Q7 adds the tab and fires the links conditional walkthrough later in Phase 2.

Phase 2, walkthrough on your real account

This is where the tour starts touching real data. BeakerBot walks a universal sequence covering the major surfaces (Home, Project, Notifications, Workbench, the editor, Methods, Gantt, Settings, Search, and the wiki pointer), followed by four conditional clusters that fire only when the matching Q answer was yes. Search has since moved off the top nav into the Cmd-K palette, so the search beat below describes a surface you now reach with a keyboard shortcut rather than a tab.

The walkthrough was deliberately trimmed. Most clusters are pitched at awareness now. BeakerBot explains what a surface is for and why you would seek it out, lands one or two live examples so the page is not empty, then moves on. The aim is to leave you knowing the feature exists and what it solves, not to drill every button. A handful of beats still hand you a real action (create a project, create an experiment, wire a Gantt dependency) so the muscle memory sticks.

Universal sequence, major surface tour

Home and your first project

Projects are the top-level container that every experiment, method, and task hangs off, so the tour opens by making one. These two beats are hands-on. You click and type, because there is no better way to learn the create flow than to run it once.

1. home-create-project. BeakerBot spotlights the New Project button on the dashboard toolbar and hands the click to you.
2. home-create-project-fill. BeakerBot frames the name and accent-color fields, you fill them in, and the new project opens to its own page. The rest of the walkthrough runs on the project you just made.

Project overview

The project page is where every experiment, method, and task you attach to a project comes back together in one view. The Overview box at the top is yours to fill in (hypothesis, motivation, why this project exists). The Results, Methods, and Activity tabs next to it surface automatically once you have something to show, and stay hidden while a project is still empty. This single beat introduces the Overview box, then hands you off to notifications.

1. project-overview-typing-demo. A single beat for the whole project page. BeakerBot orients you (every experiment, method, and task attaches to a project, and this page is where it comes back together), notes that the page fills in on its own as you add work, and points out that the Overview box up top is the part you write yourself. It types a short sample into the Overview field so you can see the live render land, then hands off to notifications.

Notifications

Two surfaces live in the top bar. The bell collects anything that needs your attention (reminders for upcoming work, updates from labmates, mentions on your writeups), and the inbox next to it collects files sent in from outside the app, like photos from a phone companion or shared attachments. This cluster was trimmed to two awareness beats. The old field-by-field demos for marking a row read and dismissing one were cut, since the inbox is self-explanatory once you know it exists.

1. notifications-intro. The controller routes to your Workbench so this beat fires from a real page instead of from inside the project. BeakerBot spotlights the bell and frames the bell-and-inbox pair so you know what each one collects before you touch either. Manual advance.
2. notifications-bell. BeakerBot fires a test notification, then asks you to click the bell to open the inbox. The fact that rows can be cleared or dismissed is folded into the speech, no separate demo.

Workbench experiment creation

Methods are the recipe, and the Workbench is where you actually run them. Every experiment gets its own entry with space for notes, results, attached protocols, and files. This is the page you spend most of your time on, so the create flow stays hands-on across two beats.

1. workbench-create-experiment-open. BeakerBot frames the Workbench as your bench record, then asks you to click "+ New Experiment" to open the form.
2. workbench-create-experiment-submit. BeakerBot spotlights the Create Experiment button and folds the name and project guidance into one speech. You fill the form and click Create Experiment yourself. The beat waits on the real save, so the experiment that lands here is the one the Gantt and method-attach beats reuse later.

Open the experiment, meet the Methods tab

The methods detour is set up with a single framing beat before the editor cluster, so you know where reusable protocols get pinned to a run before you go build one.

1. experiment-attach-method-open. A single framing beat. BeakerBot opens the experiment popup and points out the Methods tab, where reusable protocols get pinned to a run. It does not attach anything yet. You build a method first and come back to it after the Methods detour below.

The editor (3 beats)

ResearchOS uses one editor everywhere, in project overviews, standalone notes, method writeups, and the experiment notes you are looking at now. It is inline-only. You just type and your markdown renders as you go, so there is no edit mode to toggle. The old markdown deep-dive (a primer plus cursor demos for bold, italics, headings, shortcuts, and image and file attachment) and the Focus Mode enter/exit demos were all cut once the editor became inline-only. Three awareness beats remain.

1. hybrid-notes-vs-results. BeakerBot explains the notes-versus-results split inside the experiment so you know which part of the page is for narrating work and which is for the data.
2. inline-editor. BeakerBot spotlights the live editor surface and teaches the one thing that matters. You type and your markdown renders as you go. A # starts a heading, **stars** make text bold, and a - begins a list. A closing line points at Save checkpoint as the way to drop a version you can revert to, and notes that this same editor (plus its fullscreen and focus modes) shows up everywhere in the app. Manual advance.
3. hybrid-save-concept. Narration. ResearchOS does not auto-save, every save is version-controlled, and leaving with unsaved changes warns you first.

Workbench notes and lists (2 beats)

After the editor, BeakerBot introduces the standalone Notes and Lists panels on the Workbench. The cluster was collapsed to two explanation beats. The tool is friendly enough that you only need to know what notes and lists are, so the three create demos were cut.

1. workbench-notes-intro. BeakerBot clicks the Notes tab and distinguishes experiment-scoped notes from general notes that do not belong to any one experiment, and explains single notes versus running logs.
2. workbench-lists-intro. BeakerBot clicks the Lists tab and explains a list as checklist tasks without method or results sections, the lighter cousin of an experiment. Good for grocery runs, reagent restocks, and daily to-dos.

Methods deep-dive (3 beats)

Methods are your reusable protocol library. Write a technique once here, then attach it to every experiment that uses it instead of rewriting the steps each time. The cluster was collapsed from five beats to three. BeakerBot asks what kind of technique you run, opens the New Method picker so you can see the catalog of purpose-built builders, then creates a plain markdown method as the fallback. The two builder demos that used to drive the PCR thermal-cycle editor and the LC gradient chart were cut. The picker still surfaces them for you to explore.

1. methods-category-prompt. BeakerBot asks what kind of technique you run (interactive picker). Your pick is filed as the folder for your first method a moment later, so categories form from real work instead of an empty placeholder.
2. methods-open-picker. The cursor opens the "+ New Method" picker so the catalog of purpose-built builders is visible, then stops. You explore the PCR thermal-cycle builder and the live LC gradient chart at your own pace. A purpose-built UI beats a wall of markdown for any technique where the geometry of the recipe is itself the recipe.
3. methods-create. BeakerBot creates a funny placeholder markdown method of its own as a demo artifact. Markdown is the fallback any time the technique does not have a purpose-built builder.

Method attachment (2 beats)

Now that a method exists, the tour returns to the experiment to pin it. These two beats reopen the experiment popup on its Methods tab and teach the mental model. Methods are the protocol template, variation notes are the per-run delta.

1. experiment-attach-method-attach. The beat reopens the experiment popup on its Methods tab, then the cursor clicks Attach and picks the method BeakerBot just built.
2. experiment-attach-method-notes. BeakerBot spotlights the Variation Notes field and narrates the mental model. The method is the protocol template, and the notes are what changed for this one run. No typing demo, the spotlight plus explanation is enough.

Gantt deep-dive

Six universal beats teach core Gantt mechanics. Lab accounts see an additional six-beat share-feature cluster.

1. gantt-intro. BeakerBot explains what a Gantt chart is in this context.
2. gantt-existing-experiment. BeakerBot spotlights the experiment you already created on your Gantt timeline.
3. gantt-drag-drop. Cursor drags the experiment bar to reschedule it. BeakerBot narrates the date-shift.
4. gantt-deps-beakerbot. BeakerBot wires a fake experiment A as a dependency of your experiment.
5. gantt-deps-user. User-action. You wire fake experiment B as another dependency. Page lock active.
6. gantt-deps-cascade. BeakerBot moves the head dependency, and the cascade shift fires across the downstream chain.

Lab accounts only (gated on Q1 = lab). Six share-feature beats follow the universal arc.

1. gantt-share-intro. BeakerBot explains cross-lab experiment sharing. Both people see the task on Gantt and task lists, only the creator can delete it, and permissions are edit or read-only.
2. gantt-share-beakerbot-spawn. BeakerBot spawns a temporary second lab account (itself, tagged is_tutorial: true), creates a "Make some coffee together" experiment, and shares it with you so it appears on your Gantt.
3. gantt-share-user-explores. User-action. You open the shared experiment popup to explore it. Page lock active.
4. gantt-share-user-shares-back. User-action. You share one of your own experiments back with BeakerBot (open it, click Share, pick a labmate, choose view or edit, and save). Page lock active.
5. gantt-share-profile-switch. BeakerBot performs a real (or faked) profile switch to show the BeakerBot-account perspective.
6. gantt-share-user-sees-edit. User-action. Open the shared experiment popup to read BeakerBot's variation note. Page lock active.

Goals overview (gated on Q4 = yes). A single gantt-goals-overview step fires after the share cluster and explains the Goals overlay on the Gantt toolbar.

Settings deep-dive (12 steps)

Settings is the last stop on the universal arc. BeakerBot opens with a narration beat that establishes scope (everything about the account, from appearance and visible tabs to integrations, the AI Helper prompt, and the re-run button), then walks two personalization beats on the Gantt toolbar, five Settings-page narration beats, and a four-beat AI Helper cluster.

1. settings-intro. Pure narration. BeakerBot frames the whole Settings phase. This is where everything about your account lives, and the tour will hit the sections worth knowing about so you can find the rest on your own. Manual advance.
2. personalization-animations. Animated on the Gantt toolbar. BeakerBot demos the animations toggle that fires when you finish an experiment.
3. personalization-color. BeakerBot demos the primary accent color picker and invites you to pick a secondary color at your own pace.
4. settings-tour-folder. Universal. Explains that the connected lab folder is set, and that switching folders means signing out and picking a new one from the entry screen.
5. settings-tour-account-type-toggle. Conditional on Q1 = solo. Explains how to pivot from solo to a lab account via the user picker (no dedicated Settings toggle yet).
6. settings-tour-visible-tabs. Universal. Tabs you said no to are hidden; check the box here to turn one back on, or hide tabs you don't need.
7. settings-tour-streak. Universal. The streak counter is private and on by default. Toggle it off here if you prefer not to be reminded.
8. settings-tour-rerun. Universal. BeakerBot points at the Re-run tour button and tells you the whole walkthrough can be replayed from here.
9. ai-helper-size-diff (conditional on Q6). First AI Helper beat. Explains the economic motivation behind size tradeoffs. External models charge by tokens, so the AI Helper sizes its system prompt to match how much you are willing to spend per chat.
10. ai-helper-size-options (conditional on Q6). Cursor cycles through the Full, Medium, and Minimal tabs in the AI Helper section so you see each one render in place. Full gives the model everything it could want, Minimal strips down to essentials, and Medium sits in between.
11. ai-helper-use-case-paste (conditional on Q6). Paste-and-go use case walkthrough.
12. ai-helper-use-case-agentic (conditional on Q6). Agentic use-case walkthrough.

Search

search-demo. BeakerBot opens the Search tab and live-types a query that matches the experiment you created earlier. The highlighted result lands in the list.

Wiki pointer (2 beats)

The final universal cluster introduces the ? help icon in the top-right of the AppShell. It was collapsed from four beats to two. The two cursor demos that navigated into the wiki and back were cut for a single icon, and the click-and-return behavior folded into the icon-spotlight speech as awareness.

1. wiki-pointer-intro. Speech-only. BeakerBot mentions that there is a wiki with detailed documentation of every page in the app. Manual advance.
2. wiki-pointer-icon-spotlight. Spotlight on the ? icon in the top bar. BeakerBot tells you what it does and that clicking it jumps to the matching wiki page for the current route, then drops you back where you were. Manual advance.

Conditional walkthroughs (Phase 2b)

Four conditional clusters fire after the wiki-pointer cluster. Each cluster gates on the matching Q answer being yes.

• Purchases (Q2 = yes). An eight-step cluster in two phases. Phase 1 teaches on your empty page (intro, create-button click, form fill, autocomplete demo). Phase 2 warps into a read-only viewer over Alex's demo account to show the analytics surface, then navigates back.
• Calendar (Q3 = yes). The calendar step covers the inline calendar-feed subscribe flow. The new feed appears in the Calendar tab when you click Next.
• Links (Q7 = yes). The links step walks the bookmark tab, adding a card with a URL and label, and notes that on a lab account the tab is shared with everyone in the lab.

Terminal step, tour-goodbye

The final step is tour-goodbye. BeakerBot says "You're set! Here's to many great experiments ahead." and presents a single Let's go button.

Clicking Let's go triggers the outro.

1. A full-screen overlay mounts. BeakerBot cheers and confetti fires (~1.8 s).
2. BeakerBot shifts to waving pose and translates off-screen (~1.8 s).
3. The overlay fades out (~0.8 s). The route lands on /.
4. Auto-cleanup runs silently in the background, removing demo artifacts and leaving your first real project intact.
5. A small toast in the lower-right reads "Tour complete. Find BeakerBot again in Settings → Onboarding." It auto-dismisses after 4 s.

Clicking I've got it from here at any earlier step skips the intervening steps and jumps directly to tour-goodbye.

BeakerBot, the character

BeakerBot is the canonical ResearchOS mascot, a sky-blue chemistry beaker with pastel-rainbow liquid, dot eyes, and measurement-mark cheek dashes. The voice is funny and playful throughout. The tour draws from nine or more poses, chosen contextually.

• Idle, the always-on baseline bob.
• Waving, the welcome screen and the resume modal.
• Thinking, head-tilt during setup Q1 to Q7 and the PI prompt.
• Pointing, universal walkthrough steps where BeakerBot directs your attention to a UI element at eye level.
• Pointing-up, steps where BeakerBot directs attention to the top bar (the ? wiki icon cluster).
• Typing, steps where BeakerBot live-types into a form or field.
• Typing-on-laptop, a one-hand typing variant used on notes and list creation beats.
• Cheering, the tour-goodbye outro animation.
• Bouncing, a ~650 ms burst on every step transition.

Behavior contracts

I've got it from here

A persistent link in the footer of every step. Click it, confirm in the sub-modal, and BeakerBot jumps to tour-goodbye. The run gets recorded as a skip rather than a completion, so re-running from Settings still works.

Skip this step (individual)

Each step (after the intro) has a Skip this step link. If a later step depends on the artifact this step creates, BeakerBot silently creates a placeholder version with cleanup_default: "discard".

Mid-walkthrough close

Closing the tab partway through writes the current step plus every artifact created so far into _onboarding.json.wizard_resume_state. The next time you open ResearchOS with this folder, a small modal gives you three options.

• Resume, mount the tour at the saved step with every artifact and feature-pick intact.
• Restart, wipe wizard_resume_state and feature_picks so Q1 through Q7 run fresh, start at welcome.
• Discard, set wizard_skipped_at, clear resume state and feature picks. The tour exits. Settings re-run is the only path back.

Re-running from Settings

Clicking Re-run tour in Settings > Onboarding performs an inline patchOnboarding that clears wizard_completed_at, wizard_skipped_at, wizard_resume_state, feature_picks, wizard_force_show, lab_tour_pending, and lab_tour_dismissed_at in a single write. The controller then calls tourController.start() to re-mount the tour in place. No page reload.

How feature picks change which tabs you see

Your Q1 through Q7 answers determine the visible-tab set through two helpers in frontend/src/lib/onboarding/feature-picks-tabs.ts.

• tabsForFeaturePicks() maps your picks to a canonical list of tab hrefs.
• deriveVisibleTabs() composes that list with the visibleTabs array in settings.json.

The rules work like this.

• Always visible: Home, Workbench, Gantt, Methods, Sequences. Experiments live under Workbench rather than on their own tab, and Search now lives in the Cmd-K palette instead of the nav.
• Lab Overview appears only when account_type === "lab_head" (the PI dashboard at /lab-overview).
• Purchases appears only when purchases === "yes".
• Calendar appears only when calendar === "yes".
• Goals appears only when goals === "yes".
• Links appears only when links === "yes". The tab is labeled Links for every account type. On a lab account it is shared with everyone in the lab.

Settings can manually hide a tab that the picks would otherwise show. Settings cannot unhide a tab that the picks excluded. To get a hidden tab back, re-run the tour and flip the matching Q answer, or toggle it on directly in Settings > Tabs.

Dev affordances, the BeakerBot button

In development builds, a small BeakerBot button sits in the bottom-right floating cluster alongside the data-folder and switch-user controls. Clicking it opens a dropdown with three escape hatches for driving the tour without walking it from scratch. The whole control is gated on process.env.NODE_ENV === "development", so production builds drop it as dead code.

There are three actions.

• Mount at step. Pick any v4 step ID from the dropdown (every node in TOUR_STEP_ORDER, the full step graph from welcome through tour-goodbye) and click Mount wizard at this step. The orchestrator writes a resume_state pointing at your pick, flips the force-show flag on the current user's sidecar, and reloads. The tour re-mounts at the chosen step with every prior artifact intact. Useful for QA on a specific step body or for staging a screenshot capture at an arbitrary point in the flow.
• Reset wizard state. Clears wizard_completed_at, wizard_skipped_at, wizard_resume_state, wizard_force_show, and feature_picks on the current user's sidecar, then reloads. The tour fires from the intro on next mount, identical to a brand-new user. Faster than deleting the JSON by hand when iterating on step bodies.
• Test-N sandbox. The third row, Show welcome wizard (creates Test user), spawns a throwaway Test-N user (auto-incrementing N), force-shows the wizard on that user's sidecar, and swaps the active user. The sandbox user is real (it lives in _user_metadata and writes to disk), but it never touches the seen-once state on your primary account. Useful for capturing fresh-user screenshots or for stress-testing the wizard without disturbing the account you actually use.

Where to go next

• To re-run the tour or trim your visible tabs, see Settings.
• For the Lab Overview dashboard that the PI cluster introduces, see Lab Overview.
• For a hands-on tour against seeded data (no real folder needed), see /demo.
• For how projects work after BeakerBot leaves, see Project Surface.