galaxy/specs/harryalbert/APP-3809/TECH.md

HOA Onboarding Flow — Tech Spec

Linear: APP-3809 Product spec: specs/harryalbert/APP-3809/PRODUCT.md

Problem

We need a 4-step guided onboarding flow for existing users that introduces HOA features (vertical tabs, agent inbox, tab configs). The flow must be shown exactly once, gated behind a feature flag, and must reuse existing rendering code from SessionConfigModal and the FTU callout pattern.

Relevant Code

Triggering & persistence

• app/src/workspace/one_time_modal_model.rs — OneTimeModalModel: existing pattern for one-time modals (Oz launch, build plan migration). Subscribes to auth events, waits for cloud preferences sync, then triggers.
• app/src/root_view.rs:1614-1631 — HAS_COMPLETED_ONBOARDING_KEY / private_user_preferences: the other persistence approach (local-only, no cloud sync needed).
• app/src/root_view.rs:2143-2155 — post-onboarding flow: opens vertical tabs panel + shows SessionConfigModal for new users.

Session config modal (for extraction)

• app/src/tab_configs/session_config_modal.rs — SessionConfigModal: the full modal with session type pills, directory picker, worktree checkbox. All rendering is in private methods (render_session_type_section, render_directory_section, render_checkboxes).
• app/src/tab_configs/session_config.rs — SessionConfigSelection, SessionType, is_git_repo, build_tab_config, write_tab_config.

FTU callout (for extraction)

• app/src/ai/blocklist/agent_view/agent_input_footer/mod.rs:1758-1840 — render_ftu_callout: renders a bubble with a triangle arrow using stacked CalloutTriangleBorderDown / CalloutTriangleFillDown icons. Positions via OffsetPositioning::offset_from_save_position_element.

Tab layout setting

• app/src/workspace/tab_settings.rs:245 — use_vertical_tabs: bool setting.
• app/src/workspace/view.rs:1607-1614 — open_vertical_tabs_panel_if_enabled: opens the vertical tabs panel based on the setting.

Anchoring targets

• app/src/workspace/view.rs:535 — NOTIFICATIONS_MAILBOX_POSITION_ID = "workspace:notifications_mailbox": the inbox icon already uses SavePosition for anchoring (line 15262).
• app/src/workspace/view.rs:515 — TAB_BAR_POSITION_ID: the tab bar already has a SavePosition.

Feature flags

• crates/warp_features/src/lib.rs:9 — FeatureFlag enum.
• crates/warp_features/src/lib.rs:797 — DOGFOOD_FLAGS array.

Workspace integration

• app/src/workspace/view.rs:779-901 — Workspace struct: holds all modal view handles, panel state.
• app/src/workspace/view.rs:1463-1494 — build_session_config_modal: how modals are constructed and subscribed.
• app/src/workspace/view.rs:1617-1638 — show_session_config_modal / close_session_config_modal.

Current State

• New users go through AgentOnboardingView → then post-onboarding opens vertical tabs + SessionConfigModal (root_view.rs:2143-2155).
• Existing users get no introduction to HOA features.
• The SessionConfigModal rendering methods are private and tightly coupled to the modal's View impl — they can't be reused without extraction.
• The FTU callout rendering is a standalone fn render_ftu_callout but hardcodes text, colors, and arrow direction. The general pattern (bubble + positioned triangle) is reusable.
• OneTimeModalModel handles one-time modal triggering for existing users (auth → cloud sync → check flag → show). It uses AISettings to persist "shown" state via cloud-synced settings.

Proposed Changes

1. Feature flag

Add HOAOnboardingFlow to the FeatureFlag enum and DOGFOOD_FLAGS. Read the create feature flag skill for information on how to do this in a complete way.

File: crates/warp_features/src/lib.rs

2. Shared callout bubble component

Extract from the FTU callout into a general-purpose helper in a new file.

File: app/src/view_components/callout_bubble.rs

pub enum CalloutArrowDirection {
    Up,
    Left,
}

pub enum CalloutArrowPosition {
    Start(f32),
    Center,
    End(f32),
}

pub struct CalloutBubbleConfig {
    pub width: f32,
    pub arrow_direction: CalloutArrowDirection,
    pub arrow_position: CalloutArrowPosition,
}

A render_callout_bubble(content, config, appearance) -> Box<dyn Element> function that:

• Wraps content in a bordered, rounded container with accent-tinted background (matching FTU style).
• Appends/prepends a triangle arrow (using the existing CalloutTriangleBorderDown / CalloutTriangleFillDown icon stacking technique) positioned per the config.

This is reused by the HOA flow's Steps 2–4.

3. Shared session config rendering

Extract the rendering portions of SessionConfigModal into free functions that both the modal and the onboarding step can call.

File: app/src/tab_configs/session_config_rendering.rs

Extract these from SessionConfigModal:

• render_session_type_pills(session_types, selected_index, pill_mouse_states, appearance) -> Box<dyn Element>
• render_directory_picker(selected_directory, mouse_state, appearance) -> Box<dyn Element>
• render_worktree_checkbox(enabled, is_git_repo, checkbox_mouse_state, tooltip_mouse_state, appearance) -> Box<dyn Element>

SessionConfigModal calls these extracted functions in its render method instead of its current private methods. The onboarding Step 4 view calls the same functions.

The action dispatch, state management, and file picker logic remain in each caller (SessionConfigModal and the onboarding view) — only the rendering is shared.

4. HOA onboarding view

New module: app/src/workspace/hoa_onboarding/

• mod.rs — re-exports.
• hoa_onboarding_flow.rs — the main HoaOnboardingFlow view.
• welcome_banner.rs — Step 1 rendering.
• tab_config_step.rs — Step 4 rendering (uses shared session config rendering).

HoaOnboardingFlow view

enum HoaOnboardingStep {
    WelcomeBanner,
    VerticalTabsCallout,
    AgentInboxCallout,
    TabConfig,
}

struct HoaOnboardingFlow {
    step: HoaOnboardingStep,
    // Step 1 state
    close_button: ViewHandle<ActionButton>,
    // Step 2 state
    switch_to_horizontal_checkbox_mouse_state: MouseStateHandle,
    // Step 4 state (mirrors SessionConfigModal fields)
    session_types: Vec<SessionType>,
    selected_session_type_index: usize,
    selected_directory: PathBuf,
    is_git_repo: bool,
    enable_worktree: bool,
    session_pill_mouse_states: Vec<MouseStateHandle>,
    directory_button_mouse_state: MouseStateHandle,
    worktree_checkbox_mouse_state: MouseStateHandle,
    worktree_tooltip_mouse_state: MouseStateHandle,
}

Events:

enum HoaOnboardingFlowEvent {
    Completed(Option<SessionConfigSelection>),
    Dismissed,
}

• Completed(Some(selection)) — user clicked Finish with a valid tab config.
• Completed(None) — user completed the flow but didn't reach the tab config (shouldn't happen in normal flow, but covers edge cases).
• Dismissed — user clicked X.

Rendering dispatches to different renderers per step:

• Steps 1: a centered modal with scrim (similar to how SessionConfigModal is wrapped in a Modal).
• Steps 2–3: the shared render_callout_bubble positioned via OffsetPositioning::offset_from_save_position_element, anchored to the vertical tabs panel or NOTIFICATIONS_MAILBOX_POSITION_ID.
• Step 4: the shared render_callout_bubble with the tab config form body, anchored to the vertical tabs panel in vertical tabs mode or the tab bar in horizontal tabs mode.

5. Persistence

Add a new private_user_preferences key: HasCompletedHOAOnboarding.

Use the same pattern as HAS_COMPLETED_ONBOARDING_KEY in root_view.rs:1614-1631 — a simple boolean read/write via ctx.private_user_preferences(). This should be cloud synced.

Helper functions (placed near the onboarding flow or in a shared utils module):

const HAS_COMPLETED_HOA_ONBOARDING_KEY: &str = "HasCompletedHOAOnboarding";

fn has_completed_hoa_onboarding(ctx: &AppContext) -> bool { ... }
fn mark_hoa_onboarding_completed(ctx: &AppContext) { ... }

6. Triggering

Integrate into OneTimeModalModel:

• Add is_hoa_onboarding_open: bool field.
• Add a check_and_trigger_hoa_onboarding method that:
  1. Checks FeatureFlag::HOAOnboardingFlow.is_enabled().
  2. Checks !has_completed_hoa_onboarding(ctx).
  3. Checks has_completed_local_onboarding(ctx) — ensures this is an existing user (not someone mid-new-user-onboarding).
  4. Sets is_hoa_onboarding_open = true and emits the event.
• Call this from check_and_trigger_all_modals alongside the existing Oz launch and build plan migration checks.

In Workspace, subscribe to OneTimeModalEvent and when the HOA onboarding should show:

• Ensure vertical tabs are enabled (set the use_vertical_tabs setting to true if not already).
• Open the vertical tabs panel.
• Show the HoaOnboardingFlow view as an overlay.

7. New-user onboarding integration

In root_view.rs, after new-user onboarding completes (AgentOnboardingEvent::OnboardingCompleted), call mark_hoa_onboarding_completed(ctx) to ensure the HOA flow never shows for new users (only if the hoa flow feature flag is enabled).

8. Workspace rendering integration

Add hoa_onboarding_flow: Option<ViewHandle<HoaOnboardingFlow>> to Workspace.

In the workspace's render method:

• When hoa_onboarding_flow is Some and the step is WelcomeBanner, render a full-window scrim overlay with the banner centered.
• When the step is VerticalTabsCallout or AgentInboxCallout, render the callout bubble as a positioned overlay (using Stack::add_positioned_overlay_child) anchored to the appropriate SavePosition element.
• When the step is TabConfig, render the tab config popover as a positioned overlay anchored to the content area.

Handle HoaOnboardingFlowEvent:

• On Dismissed: call mark_hoa_onboarding_completed, drop the flow view.
• On Completed(Some(selection)): call mark_hoa_onboarding_completed, process the tab config selection (reuse handle_session_config_completed logic), drop the flow view.
• On Completed(None): call mark_hoa_onboarding_completed, drop the flow view.

End-to-End Flow

1. Existing user launches Warp with HOAOnboardingFlow enabled.
2. OneTimeModalModel receives auth + cloud sync completion → calls check_and_trigger_hoa_onboarding.
3. Checks pass (flag enabled, not completed, is existing user) → emits OneTimeModalEvent.
4. Workspace receives event → enables vertical tabs setting → opens vertical tabs panel → creates HoaOnboardingFlow in WelcomeBanner step → renders scrim + banner.
5. User clicks "See what's new" → flow advances to VerticalTabsCallout → callout bubble rendered anchored to vertical tabs panel.
6. User optionally toggles "Switch back to horizontal tabs" → use_vertical_tabs setting toggled, UI updates live, callout re-anchors.
7. User clicks "Next" → flow advances to AgentInboxCallout → callout bubble rendered anchored to NOTIFICATIONS_MAILBOX_POSITION_ID.
8. User clicks "Next" → flow advances to TabConfig → popover with session config fields rendered.
9. User configures and clicks "Finish" → HoaOnboardingFlowEvent::Completed(Some(selection)) emitted → tab config saved, flow closed, preferences key set.

Risks and Mitigations

1. Rendering extraction breaking SessionConfigModal: The extraction of rendering functions is a refactor of existing code. Risk: subtle visual regressions. Mitigation: compare screenshots before/after extraction to verify pixel-identical output.

2. Callout positioning edge cases: If the vertical tabs panel or inbox icon aren't rendered yet when the callout tries to anchor, offset_from_save_position_element may position incorrectly. Mitigation: the flow ensures vertical tabs are opened before Step 2, and the inbox icon is always in the title bar when HOANotifications is enabled.

3. Interaction with other one-time modals: OneTimeModalModel runs checks sequentially — Oz launch modal takes priority. If the Oz launch modal shows, the HOA flow won't trigger until the next app launch. This is acceptable; the flow persists across launches until shown.

4. Feature flag dependency: The flow assumes VerticalTabs, HOANotifications, and TabConfigs flags are also enabled. If any are disabled, certain steps may reference UI that doesn't exist. Mitigation: gate the HOA flow on all required flags in check_and_trigger_hoa_onboarding.

Testing and Validation

• Unit tests: persistence helpers (has_completed_hoa_onboarding, mark_hoa_onboarding_completed), step transitions in HoaOnboardingFlow, new-user exclusion logic.
• Visual verification: local walkthrough of all 4 steps after building.
• Extraction regression: verify SessionConfigModal still renders identically after extracting shared rendering functions.
• Edge cases: dismiss at Step 1, dismiss at Step 4, toggle horizontal tabs back and forth, select non-git directory for worktree.

Follow-ups

• Remove HOAOnboardingFlow feature flag once stable (promote through preview → release).
• Refactor the existing FTU callout in agent_input_footer to use the shared callout_bubble component.
• Hero art asset: needs a static image to be produced and bundled.