TUI: Add the first-session zero state (#14580)

## Description
<!-- Please remember to add your design buddy onto the PR for review, if it contains any UI changes! -->

Add the once-per-account first-session zero state. The first-run variant reuses the existing zero-state layout, animation, starfield, project context, input, and footer while presenting the Figma-aligned "What's different about Warp" guidance.

Design: https://www.figma.com/design/yg5nbPZuGoAszHS3Rhvehu/TUI?node-id=1768-18320&m=dev

## Linked Issue
- [ ] The linked issue is labeled `ready-to-spec` or `ready-to-implement`.
- [ ] Where appropriate, screenshots or a short video of the implementation are included below (especially for user-visible or UI changes).

Implementation plan: https://staging.warp.dev/drive/notebook/VEDTJkrbVxEnFZIwM5uC3A

## Testing
- `./script/format`
- `cargo check -p warp_tui --tests`
- Previously passed focused coverage: `first_zero_state_matches_welcome_design_copy` and `first_zero_state_is_provisional_and_reconciles_without_replacing_the_session`.
- Full test execution and Clippy were skipped as requested.

- [ ] I have manually tested my changes locally with `./script/run`

### Screenshots / Videos
Manual verification screenshot and discussion:
https://staging.warp.dev/conversation/b543d79e-e3d9-4f48-9516-50c2372eabc8

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

CHANGELOG-TUI: Added first-run guidance to the Warp Agent CLI welcome screen.

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: moirahuang

app/src/tui_onboarding_markers.rs

@@ -105,6 +105,7 @@ impl TuiOnboardingMarkers {
             load_timeout: MARKER_LOAD_TIMEOUT,
         }
     }
+
     #[cfg(test)]
     fn new_loading_for_test(
         onboarding_client: Arc<dyn TuiOnboardingClient>,
@@ -140,6 +141,7 @@ impl TuiOnboardingMarkers {
         );
         ctx.notify();
     }
+
     /// Invalidates the previous account snapshot before a signed-out terminal
     /// can be created for the next browser authentication flow.
     pub fn reset_for_account_transition(&mut self, ctx: &mut ModelContext<Self>) {

crates/warp_tui/src/session.rs

@@ -325,10 +325,12 @@ fn ensure_terminal_session(
 
     let resume_token = sessions.update(ctx, |sessions, _| sessions.take_resume_token());
     let window_id = root.window_id(ctx);
+    let handles_first_run_onboarding = resume_token.is_none();
     let (_, surface) = TuiSessions::create_local_terminal_session(
         sessions,
         window_id,
         true,
+        handles_first_run_onboarding,
         std::env::current_dir().ok(),
         ctx,
     );

crates/warp_tui/src/session_registry.rs

@@ -151,6 +151,7 @@ impl TuiSessions {
         sessions: &ModelHandle<Self>,
         window_id: WindowId,
         focus: bool,
+        handles_first_run_onboarding: bool,
         startup_directory: Option<PathBuf>,
         ctx: &mut AppContext,
     ) -> (TuiSessionId, ViewHandle<TuiTerminalSessionView>) {
@@ -197,6 +198,7 @@ impl TuiSessions {
                         exit_summary,
                         keyboard_enhancement_supported,
                         default_autoexecute_mode,
+                        handles_first_run_onboarding,
                         initial_settings_file_error,
                         ctx,
                     )
@@ -268,8 +270,14 @@ impl TuiSessions {
         conversation: AIConversation,
         ctx: &mut AppContext,
     ) -> (TuiSessionId, ViewHandle<TuiTerminalSessionView>) {
-        let (session_id, surface) =
-            Self::create_local_terminal_session(sessions, window_id, false, startup_directory, ctx);
+        let (session_id, surface) = Self::create_local_terminal_session(
+            sessions,
+            window_id,
+            false,
+            false,
+            startup_directory,
+            ctx,
+        );
         surface.update(ctx, |view, ctx| {
             view.restore_orchestrated_child_conversation(conversation, ctx);
         });
@@ -434,6 +442,7 @@ impl TuiSessions {
                     &sessions,
                     window_id,
                     false,
+                    false,
                     working_directory.clone(),
                     ctx,
                 );

crates/warp_tui/src/terminal_session_view.rs

@@ -36,7 +36,8 @@ use warp::tui_export::{
     SlashCommandDataSource as _, SlashCommandKind, SlashCommandSelectionBehavior,
     StartAgentExecutorEvent, StartAgentRequest, StaticCommand, TelemetryEvent, TerminalColorList,
     TerminalColors, TerminalModel, TerminalSurface, TerminalSurfaceInit, TranscriptScope,
-    TuiMcpAction, TuiMcpManager, TuiMcpServerId, TuiMcpVariableValue, TuiSlashCommandDataSource,
+    TuiMcpAction, TuiMcpManager, TuiMcpServerId, TuiMcpVariableValue, TuiOnboardingMarker,
+    TuiOnboardingMarkers, TuiOnboardingMarkersEvent, TuiSlashCommandDataSource,
     TuiSlashCommandDataSourceArgs, TuiUpArrowHistoryItemKind, TuiUserInfoManager,
     TuiUserInfoManagerEvent, TuiZeroStateDataSource, UserTakeOverReason, WAKEUP_THROTTLE_PERIOD,
     WarpConfig, WarpConfigUpdateEvent, block_context_from_terminal_model,
@@ -1435,6 +1436,7 @@ impl TuiTerminalSessionView {
         exit_summary: TuiExitSummaryHandle,
         keyboard_enhancement_supported: bool,
         default_autoexecute_mode: AIConversationAutoexecuteMode,
+        handles_first_run_onboarding: bool,
         initial_settings_file_error: Option<SettingsFileError>,
         ctx: &mut ViewContext<Self>,
     ) -> Self {
@@ -1769,6 +1771,17 @@ impl TuiTerminalSessionView {
         let suggestions_mode_for_input = suggestions_mode.clone();
         let terminal_model_for_input = model.clone();
         let orchestration_tab_bar = ctx.add_typed_action_tui_view(|_| TuiTabBarView::empty());
+        let onboarding_markers =
+            handles_first_run_onboarding.then(|| TuiOnboardingMarkers::handle(ctx));
+        let show_first_zero_state = onboarding_markers.as_ref().is_some_and(|markers| {
+            markers.update(ctx, |markers, ctx| {
+                if markers.is_ready() {
+                    markers.consume(TuiOnboardingMarker::FirstZeroState, ctx)
+                } else {
+                    true
+                }
+            })
+        });
         let session_state = ctx.add_model(|_| {
             TuiTerminalSessionStateModel::new(
                 &model,
@@ -1777,8 +1790,32 @@ impl TuiTerminalSessionView {
                 &ai_input_model,
                 &suggestions_mode,
                 &orchestration_tab_bar,
+                show_first_zero_state,
             )
         });
+        if let Some(onboarding_markers) = onboarding_markers {
+            let session_state_for_markers = session_state.clone();
+            ctx.subscribe_to_model(
+                &onboarding_markers,
+                move |_, markers, event, ctx| match event {
+                    TuiOnboardingMarkersEvent::Loading => {
+                        session_state_for_markers.update(ctx, |state, ctx| {
+                            state.set_show_first_zero_state(true, ctx);
+                        });
+                    }
+                    TuiOnboardingMarkersEvent::Ready => {
+                        let keep_showing = markers.update(ctx, |markers, ctx| {
+                            markers.consume(TuiOnboardingMarker::FirstZeroState, ctx)
+                        });
+                        session_state_for_markers.update(ctx, |state, ctx| {
+                            if state.show_first_zero_state() {
+                                state.set_show_first_zero_state(keep_showing, ctx);
+                            }
+                        });
+                    }
+                },
+            );
+        }
         let input_editor_for_input = input_editor_model.clone();
         let session_state_for_input = session_state.clone();
         let input_view = ctx.add_typed_action_tui_view(move |ctx| {
@@ -3679,6 +3716,9 @@ impl TuiTerminalSessionView {
         linked_workflow_data: Option<LinkedWorkflowData>,
         ctx: &mut ViewContext<Self>,
     ) {
+        self.session_state.update(ctx, |state, ctx| {
+            state.set_show_first_zero_state(false, ctx);
+        });
         // A stale editor frame must not submit into a shell that is still
         // bootstrapping or has handed input to a foreground process.
         if !self.input_target().agent_editor_owns_input() {
@@ -5024,7 +5064,9 @@ impl TuiTerminalSessionView {
         let mut content = TuiFlex::column();
         let transcript_is_empty = self.transcript.as_ref(ctx).is_empty();
         self.zero_state_interaction.set_visible(transcript_is_empty);
-        if transcript_is_empty {
+        if transcript_is_empty && self.session_state.as_ref(ctx).show_first_zero_state() {
+            content = content.flex_child(self.zero_state_view.as_ref(ctx).render_first_run(ctx));
+        } else if transcript_is_empty {
             content = content.flex_child(TuiChildView::new(&self.zero_state_view).finish());
         } else {
             content = content.flex_child(TuiChildView::new(&self.transcript).finish());

crates/warp_tui/src/terminal_session_view/state.rs

@@ -6,7 +6,9 @@ use std::{error, fmt};
 use parking_lot::FairMutex;
 use warp::tui_export::{BlocklistAIInputModel, CLISubagentController, TerminalModel};
 use warpui_core::keymap::Context;
-use warpui_core::{AppContext, Entity, ModelHandle, ViewHandle, WeakModelHandle, WeakViewHandle};
+use warpui_core::{
+    AppContext, Entity, ModelContext, ModelHandle, ViewHandle, WeakModelHandle, WeakViewHandle,
+};
 
 use super::{
     AUTO_APPROVE_TOGGLE_BINDING_NAME, BlockingInputSource,
@@ -54,6 +56,7 @@ enum TuiTerminalSessionStateSource {
 /// presentation components one shared state source.
 pub(crate) struct TuiTerminalSessionStateModel {
     source: TuiTerminalSessionStateSource,
+    show_first_zero_state: bool,
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -101,6 +104,7 @@ impl TuiTerminalSessionStateModel {
         input_mode: &ModelHandle<BlocklistAIInputModel>,
         suggestions_mode: &ModelHandle<TuiInputSuggestionsModeModel>,
         orchestration_tab_bar: &ViewHandle<TuiTabBarView>,
+        show_first_zero_state: bool,
     ) -> Self {
         Self {
             source: TuiTerminalSessionStateSource::Session {
@@ -111,6 +115,18 @@ impl TuiTerminalSessionStateModel {
                 suggestions_mode: suggestions_mode.downgrade(),
                 orchestration_tab_bar: orchestration_tab_bar.downgrade(),
             },
+            show_first_zero_state,
+        }
+    }
+
+    pub(crate) fn show_first_zero_state(&self) -> bool {
+        self.show_first_zero_state
+    }
+
+    pub(crate) fn set_show_first_zero_state(&mut self, show: bool, ctx: &mut ModelContext<Self>) {
+        if self.show_first_zero_state != show {
+            self.show_first_zero_state = show;
+            ctx.notify();
         }
     }
     #[cfg(test)]
@@ -125,6 +141,7 @@ impl TuiTerminalSessionStateModel {
                 suggestions_mode: suggestions_mode.downgrade(),
                 orchestration_tabs_available: Rc::new(orchestration_tabs_available),
             },
+            show_first_zero_state: false,
         }
     }