Onboarding & Product Tour
This area covers 23 features. Watch the walkthrough, then use the reference below — each feature links to the exact moment it appears (▶).
Who this is for: New org owner / first-run user. Each feature below lists the role/permission it requires.
Features
Onboarding Wizard Welcome Step ▶ 00:00
As a new user, I want to see a branded welcome screen with the app logo and onboarding headline, so that I understand what I'm about to set up.
How it works. User lands at /onboarding route. WelcomeStep renders with app logo, headline (from branding config), subheading, and 'Get Started' button. Clicking 'Get Started' advances to step 2. Step indicator shows progress (Step 1 of 6).
Key files
src/components/onboarding/OnboardingWizard.tsx:30-32src/components/onboarding/steps/WelcomeStep.tsx:4-21
Onboarding Privacy Consent Step ▶ 00:00
As a new user, I want to opt in or out of analytics sharing with a clear explanation, so that I control my data usage.
How it works. PrivacyStep renders with ShieldCheck icon, heading 'Help us improve', toggle switch for 'Share usage data'. Toggle defaults to enabled. If disabled, shows warning: 'With analytics disabled, we may not be able to help diagnose problems.' Clicking 'Continue' persists choice and advances to step 3. Back button returns to step 1. Footer includes link to /privacy-policy.
Key files
src/components/onboarding/steps/PrivacyStep.tsx:7-70src/hooks/useAnalyticsConsent.ts
Onboarding Sign-In Step ▶ 00:06
As a new user, I want to sign in to my Frontier account (or create one) to unlock AI and sync features, so that I can collaborate and use cloud features.
How it works. SignInStep defaults to signup mode. Shows 'Create your Frontier account' heading. Renders FrontierSignupForm with onSuccess callback advancing to next step. User can toggle to 'Log in' mode (shows 'Sign in to Frontier'). In login mode, onSuccess calls onLoginComplete handler which checks for existing orgs: if user already has orgs, skips Name + Project steps and lands on dashboard; if brand-new account (no orgs), continues wizard. Password reset mode available ('Forgot password?'). 'Skip for now' button available in both signup and login modes. Dev mode (import.meta.env.DEV) shows 'Dev login' button. Back button returns to step 2. Once session is established, shows success screen: 'Signed in as [username]' with green checkmark and 'Continue' button.
Key files
src/components/onboarding/steps/SignInStep.tsx:12-120src/components/onboarding/OnboardingWizard.tsx:73-87
Onboarding Display Name Step ▶ 00:00
As a new user setting up my account, I want to enter my display name, so that my edits and comments are attributed to me across the project.
How it works. NameStep renders with heading 'What should we call you?' and description 'This name appears on your edits and comments.' Input field (id='display-name', placeholder='Anonymous translator') auto-focuses. Pre-fills from Frontier session.username if user hasn't typed anything yet. 'Continue' button saves name to localStorage key 'codex:username' (or defaults to 'Anonymous' if empty) and advances to step 4. Back button returns to step 3.
Key files
src/components/onboarding/steps/NameStep.tsx:7-60
Onboarding Project Creation Step ▶ 00:11
As a new user, I want to create my first translation project with source and target languages, so that I have a project to start translating in.
How it works. ProjectStep renders form with heading 'Create your first project'. Three text inputs: Project name (placeholder 'My Translation Project'), Source language (placeholder 'English'), Target language (placeholder 'French'). Submit button reads 'Create Project' and is disabled until all three fields are non-empty. On submit, creates server project first (via createRemoteProject), then local IDB record (via createLocalProject). On success, advances to step 6 (ReadyStep). Shows 'Creating…' button state while busy. Errors are caught and displayed inline (e.g., 'Failed to create project.'). If no Frontier session JWT exists, shows alternate message: 'Sign in to create a project' with explanation that projects are server-only. 'Do this later' link skips project creation and advances to dashboard. Back button returns to step 3.
Key files
src/components/onboarding/steps/ProjectStep.tsx:11-168src/components/onboarding/OnboardingWizard.tsx:89-92
Onboarding Ready Step ▶ 00:00
As a new user who just created a project, I want to see a success confirmation, so that I know I'm ready to start translating.
How it works. ReadyStep renders success state: green CheckCircle2 icon, heading 'You're all set!', message 'PROJECT_NAME is ready. We'll walk you through setting up AI and inviting collaborators next.' 'Start Translating' button navigates to project page at `/project/{projectId}` with router state `{ openSetupChecklist: true }`, triggering auto-open of setup checklist.
Key files
src/components/onboarding/steps/ReadyStep.tsx:5-28src/components/onboarding/OnboardingWizard.tsx:94-103
Onboarding Completion Persistence ▶ 00:00
As a returning user, I want the app to remember I completed onboarding, so that I don't see the wizard again on subsequent visits.
How it works. Wizard sets localStorage 'codex:onboardingComplete' = 'true' when user completes (ReadyStep or skips ProjectStep). On subsequent visits, if this flag is set, user bypasses /onboarding and lands on dashboard (/). OnboardingWizard component is only mounted when token is absent or onboarding is incomplete.
Key files
src/components/onboarding/OnboardingWizard.tsx:76-78, 95, 106src/components/onboarding/steps/SignInStep.tsx:76src/components/onboarding/steps/ProjectStep.tsx:105
Product Tour Auto-Start ▶ 00:00
As a new user who just completed onboarding, I want an interactive guided tour of the main workspace, so that I learn where everything is.
How it works. After onboarding completion (localStorage 'codex:onboardingComplete'='true') AND product tour not yet shown (localStorage 'codex:productTourDone'!='1'), ProductTour auto-starts with 600ms delay on first app render. User sees spotlight with semi-transparent backdrop and tooltip card overlaying key UI elements. Tour can be dismissed by clicking X, clicking 'Skip', pressing Escape, or completing all steps (clicking 'Done' on final step). Once dismissed, marked as done via localStorage and tour does not auto-start again.
Key files
src/components/onboarding/ProductTour.tsx:477-496src/hooks/useProductTour.ts:47-54src/context/ProductTourContext.tsx:34-43
Product Tour Step Navigation ▶ 00:00
As a user taking the product tour, I want to navigate between steps and see my progress, so that I can learn at my own pace.
How it works. Tour displays current step in a tooltip card with title, body text, and placement arrow (top/bottom/left/right, auto-repositioning if offscreen). Footer shows step progress dots (filled for current/past, empty for future). 'Back' button navigates to previous step (hidden on first step). 'Next' button advances to next step; on final step, reads 'Done' and closes tour. Step indicator reads 'Tour step N of M'. Keyboard shortcuts: Escape = skip, ArrowRight/Enter = next, ArrowLeft = previous.
Key files
src/components/onboarding/ProductTour.tsx:283-353, 416-444
Product Tour Step Definitions ▶ 00:00
As a new user, I want to understand key workspace features through guided callouts, so that I can navigate and use the app effectively.
How it works. Tour displays 6 steps: (1) splash step centered on screen 'Welcome to your workspace', (2) org-switcher callout, (3) nav-overview (Projects) callout, (4) nav-assigned callout, (5) nav-settings callout, (6) account-switcher callout. Each step has title, body text, and preferred placement. Splash step has no arrow; others point to their target element with rounded-rect spotlight cutout.
Key files
src/components/onboarding/ProductTour.tsx:32-69
Product Tour Spotlight Geometry ▶ 00:00
As a user taking the tour, I want to see the highlighted UI elements clearly with auto-positioned tooltips, so that I don't miss what's being explained.
How it works. Spotlight draws SVG cutout (rounded rect punch-out) around target element with 8px padding. Semi-transparent dark overlay fills remainder of screen. Tooltip card (288px wide, ~160px tall) positions itself relative to target using preferred placement (right/left/bottom/top) with 16px gap; auto-falls back to other sides if current choice doesn't fit viewport; final fallback centers on screen. Tooltip arrow points back to target (or no arrow for center-screen splash steps).
Key files
src/components/onboarding/ProductTour.tsx:102-184, 190-259, 265-271
Product Tour Manual Launch Button ▶ 00:00
As a returning user, I want to be able to restart the product tour, so that I can review features I may have forgotten.
How it works. OrgSidebar footer includes 'Take the tour' button or similar (accessible via useProductTourContext.openTour()). Clicking this button manually opens ProductTour even if it was already completed. Tour re-opens from step 1.
Key files
src/components/org/OrgSidebar.tsxsrc/context/ProductTourContext.tsx:13-23
Setup Checklist Auto-Show ▶ 00:00
As a user creating a first project, I want to see a setup checklist that guides me through configuration steps, so that I can set up AI, collaboration, and other features.
How it works. When user lands on project page after onboarding (ReadyStep navigates with router state openSetupChecklist=true), ProjectWorkspace opens SetupChecklistDrawer automatically. Checklist shows 4 items: Import files, Set translation instructions, Invite collaborators, Configure voice & transcription. Each item has title, description, completion dot (empty/filled), and collapsible body. Progress bar shows X of N complete. Checklist does not auto-open if: (1) user has already dismissed it for this project, (2) setup-auto-shown flag is set in localStorage for this project, (3) member list is still fetching, (4) AI model status is still resolving, OR (5) checklist is already complete (all 4 items done).
Key files
src/components/onboarding/SetupChecklistDrawer.tsx:33-139src/hooks/useSetupChecklist.ts:50-199src/components/onboarding/OnboardingWizard.tsx:98
Setup Checklist Import Files Step ▶ 00:00
As a user setting up a project, I want to import my source text files first, so that I can start working on translation.
How it works. Checklist item 'Import files' has body showing description and 'Import files' button. If files already imported, shows 'X files imported' and button changes to 'Import more files'. Clicking button closes drawer and opens parent's import dialog (ProjectWorkspace.onOpenImport). Item is marked complete when project.files.length > 0.
Key files
src/components/onboarding/checklist/ImportFilesStep.tsx:11-33src/hooks/useSetupChecklist.ts:56
Setup Checklist AI Instructions Step ▶ 00:00
As a user setting up a project, I want to customize translation instructions for the AI, so that suggestions match my project's style and domain.
How it works. Checklist item 'Set translation instructions' expands to show textarea with system prompt. Defaults to DEFAULT_SYSTEM_PROMPT (imported from useCompletionSettings). User can edit prompt; character count displayed at bottom. 'Reset to default' button (disabled if already at default). 'Save instructions' button saves to project.completionSettings.systemPrompt and marks item complete. Prompt supports placeholders {sourceLanguage} and {targetLanguage} (shown as code snippets in UI). Item completed when systemPrompt is non-empty and not the default.
Key files
src/components/onboarding/checklist/AiInstructionsStep.tsx:15-77src/hooks/useSetupChecklist.ts:57
Setup Checklist Collaborators Step ▶ 00:00
As a user setting up a project, I want to invite teammates to collaborate, so that we can work on translation together.
How it works. Checklist item 'Invite collaborators' expands to show InviteStep UI with two invitation paths: (1) Invite by Aquilla username — text input + 'Add' button, adds user directly to project_members server-side as 'contributor' role; (2) Share link — 'Create link' button generates server-backed invite token, displays /join/{token} URL, 'Copy' button copies to clipboard, 'Create another link' button generates new token. Input disabled if user not signed in (Frontier JWT missing). Item completed when memberCount > 0 (other project members, excluding self). Both paths trigger onSharesChanged callback to refresh member list.
Key files
src/components/onboarding/checklist/InviteStep.tsx:30-222src/hooks/useSetupChecklist.ts:58, 163-174
Setup Checklist AI Models Step ▶ 00:00
As a user setting up a project, I want to configure local AI models for voice and transcription, so that I can use offline features without managing large downloads upfront.
How it works. Checklist item 'Configure voice & transcription' starts collapsed; expands to show two sections: Transcription (Whisper checkbox, 140 MB) and Voice generation (radio group: None, Gemini with API key input, Kokoro local, MMS multilingual). Each model option shows label, size, status indicator (Ready/Failed/Downloading N%), and blurb. Selecting Gemini shows nested API key input (password field, saved on blur). Download size shown in amber warning banner. 'Download ~X MB' button (disabled if nothing selected, all-ready, or already downloading) kicks off prefetchAiModels for selected models in background. Download status shown in AiModelDownloadChip (floating bottom-left pill with progress bars). Item completed when all selected models are ready.
Key files
src/components/onboarding/checklist/AiModelsStep.tsx:56-279src/hooks/useSetupChecklist.ts:130-148
Setup Checklist Coming Soon Placeholder ▶ 00:00
As a user, I want to see what's planned for future project setup features, so that I have visibility into roadmap.
How it works. Checklist shows two placeholder items: 'Upload project standards' and 'Import glossary / translation memory', both marked 'Coming soon' badge, with dashed border and reduced opacity (opacity-60). Items are non-interactive (no click handler).
Key files
src/components/onboarding/SetupChecklistDrawer.tsx:106-113src/components/onboarding/checklist/ComingSoonStep.tsx:1-24
Setup Checklist Completion State ▶ 00:00
As a user, I want to see my progress through setup and know when I'm done, so that I feel guided through the onboarding experience.
How it works. Progress bar at top updates as items are completed. Text shows 'N of M complete'. When all items complete, 'Skip for now' button changes to 'All set' with green CheckCircle icon and message 'You can reopen this checklist any time from the project header.' Drawer can still be dismissed before completion ('Skip for now' button).
Key files
src/components/onboarding/SetupChecklistDrawer.tsx:43-156
Setup Checklist Item Expand/Collapse ▶ 00:00
As a user, I want to expand and collapse checklist items, so that I can focus on one step at a time.
How it works. Each ChecklistItem is a collapsible accordion row. Clicking title row toggles open/closed state. When complete prop transitions false→true, item auto-collapses (so next incomplete item gets focus). Chevron icon rotates 90° to indicate open state. Open item shows full body content.
Key files
src/components/onboarding/checklist/ChecklistItem.tsx:23-92
System Prompt Nudge Banner ▶ 00:00
As a user who skipped customizing AI instructions and has content in their project, I want a gentle reminder to set up the system prompt, so that I get better translations.
How it works. Once per day (24h after project creation), if: project has files with content (cellCount > 0), system prompt is still default or empty, and user hasn't dismissed nudge yet (defaultPromptNudgeDismissedAt not set), a banner appears at top of workspace editor showing Sparkles icon and message 'Your AI is still using the default translation instructions. Customize them to match your project's tone and domain — shared with everyone on the project.' 'Customize' button opens project settings or AI instructions dialog. X button dismisses and marks defaultPromptNudgeDismissedAt. Dismissed flag persists on ProjectRecord, preventing re-show.
Key files
src/components/onboarding/SystemPromptNudge.tsx:26-81
AI Model Consent Dialog ▶ 00:00
As a user about to use local AI features for the first time, I want to consent to model download and understand the tradeoffs, so that I'm informed about bandwidth and privacy.
How it works. Global dialog (mounted once at app root) listens to pendingAiConsent via global ai-consent service. When a feature (TTS, ASR) needs to download its first model in this browser, dialog opens with heading 'Download {model.label}?' and description including model size (MB) and rationale. Three buttons: 'Cancel' (rejects consent, feature fails), 'Just [Model Name]' (grants consent for this model only), 'Enable all local models' (grants consent for all, pre-downloads whisper + kokoro + mms in background while dialog closes). Footer note 'You'll only see this prompt once per browser.' Download progress shown in background via AiModelDownloadChip.
Key files
src/components/AiModelConsentDialog.tsx:20-79src/lib/audio/ai-consent.ts
AI Model Download Chip ▶ 00:00
As a user with local models downloading, I want to see live download progress, so that I know the feature is working and can estimate completion time.
How it works. Floating chip appears at bottom-left of screen (z-index 30, above most UI but below modals). Shows Spinner icon and 'Downloading AI models' title. Lists each model being downloaded with label and percentage (e.g., 'Whisper 45%'), progress bar under each. When all models finish, briefly flashes 'AI models ready' with CheckCircle icon for ~4s, then auto-hides. If error occurs, shows AlertCircle and model name + error message, with 'Retry' button. User can dismiss chip with X button (re-appears if new error happens). While downloading, footer note 'Runs in the background — you can keep working as normal.'
Key files
src/components/AiModelDownloadChip.tsx:36-196src/lib/audio/prefetch.ts