@elizaos/ui 2.0.0-beta.2 → 2.0.3-beta.2

package/state/AppContext.js

@@ -4,22 +4,30 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *
  * Children access state and actions through the useApp() hook.
  */
-import { ConfirmDialog, PromptDialog, useConfirm, usePrompt, } from "@elizaos/ui";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { client } from "../api/index.js";
-import { AppBootContext } from "../config/boot-config-react.js";
+import { ConfirmDialog, PromptDialog } from "../components/ui/confirm-dialog.js";
+import { useConfirm, usePrompt } from "../components/ui/confirm-dialog.hooks.js";
+import { AppBootContext } from "../config/boot-config-react.hooks.js";
 import { getBootConfig } from "../config/boot-config-store.js";
 import { BrandingContext, DEFAULT_BRANDING } from "../config/branding.js";
+import { isMobileLocalAgentIpcBase, persistMobileRuntimeModeForServerTarget, } from "../first-run/mobile-runtime-mode.js";
+import { activeServerKindToFirstRunRuntimeTarget, } from "../first-run/runtime-target.js";
 import { getWindowNavigationPath, resolveDefaultLandingTab, resolveInitialTabForPath, } from "../navigation/index.js";
+import { getFrontendPlatform } from "../platform/platform-guards.js";
+import { applyThemeToDocument } from "../themes/apply-theme.js";
 import { copyTextToClipboard } from "../utils/index.js";
+import { RESYNC_EVENT } from "./AppContext.hooks.js";
 import { getActiveProfile, loadAgentProfileRegistry, setActiveProfileId, } from "./agent-profiles.js";
-import { ChatComposerCtx, ChatInputRefCtx } from "./ChatComposerContext.js";
-import { CompanionSceneConfigCtx } from "./CompanionSceneConfigContext.js";
+import { ChatComposerCtx, ChatInputRefCtx, clearAllChatDrafts, useChatComposerDraftPersistence, } from "./ChatComposerContext.hooks.js";
+import { CompanionSceneConfigCtx } from "./CompanionSceneConfigContext.hooks.js";
 import { AppContext } from "./internal.js";
-import { PtySessionsCtx } from "./PtySessionsContext.js";
+import { PtySessionsCtx } from "./PtySessionsContext.hooks.js";
 import { createPersistedActiveServer, savePersistedActiveServer, } from "./persistence.js";
 import { deriveUiShellModeForTab } from "./shell-routing.js";
-import { TranslationProvider, useTranslation } from "./TranslationContext.js";
+import { useTranslation } from "./TranslationContext.hooks.js";
+import { TranslationProvider } from "./TranslationProvider.js";
+import { useAppLifecycleEvents } from "./useAppLifecycleEvents.js";
 import { useAgentGreetingEffects, useBackendConnectionSync, useNavigationPathSync, } from "./useAppProviderEffects.js";
 import { useAppShellState } from "./useAppShellState.js";
 import { useCharacterState } from "./useCharacterState.js";
@@ -29,37 +37,30 @@ import { useCloudState } from "./useCloudState.js";
 import { useDataLoaders } from "./useDataLoaders.js";
 import { useDisplayPreferences } from "./useDisplayPreferences.js";
 import { useExportImportState } from "./useExportImportState.js";
+import { useFirstRunCallbacks } from "./useFirstRunCallbacks.js";
+import { useFirstRunState } from "./useFirstRunState.js";
 import { useLifecycleState } from "./useLifecycleState.js";
 import { useLogsState } from "./useLogsState.js";
 import { useMiscUiState } from "./useMiscUiState.js";
 import { useNavigationState } from "./useNavigationState.js";
-import { useOnboardingCallbacks } from "./useOnboardingCallbacks.js";
-import { useOnboardingCompat } from "./useOnboardingCompat.js";
-import { useOnboardingState } from "./useOnboardingState.js";
 import { usePairingState } from "./usePairingState.js";
 import { usePluginsSkillsState } from "./usePluginsSkillsState.js";
 import { useStartupCoordinator } from "./useStartupCoordinator.js";
+import { useTabSync } from "./useTabSync.js";
 import { useTriggersState } from "./useTriggersState.js";
-import { useVincentState } from "./useVincentState.js";
 import { useWalletState } from "./useWalletState.js";
-export { AGENT_STATES, AGENT_TRANSFER_MIN_PASSWORD_LENGTH, AppContext, applyUiTheme, asApiLikeError, computeStreamingDelta, formatSearchBullet, formatStartupErrorDetail, getCompanionBackgroundUrl, getVrmBackgroundUrl, getVrmCount, getVrmPreviewUrl, getVrmTitle, getVrmUrl, LIFECYCLE_MESSAGES, loadAvatarIndex, loadChatAvatarVisible, loadChatMode, loadChatVoiceMuted, loadCompanionAnimateWhenHidden, loadCompanionHalfFramerateMode, loadCompanionVrmPowerMode, loadUiLanguage, loadUiShellMode, loadUiTheme, mergeStreamingText, normalizeAvatarIndex, normalizeCompanionHalfFramerateMode, normalizeCompanionVrmPowerMode, normalizeCustomActionName, normalizeStreamComparisonText, normalizeUiShellMode, normalizeUiTheme, ONBOARDING_PERMISSION_LABELS, parseAgentStartupDiagnostics, parseAgentStatusEvent, parseAgentStatusFromMainMenuResetPayload, parseConversationMessageEvent, parseCustomActionParams, parseProactiveMessageEvent, parseSlashCommandInput, parseStreamEventEnvelopeEvent, saveAvatarIndex, saveChatAvatarVisible, saveChatMode, saveChatVoiceMuted, saveCompanionAnimateWhenHidden, saveCompanionHalfFramerateMode, saveCompanionVrmPowerMode, saveUiLanguage, saveUiShellMode, saveUiTheme, shouldApplyFinalStreamText, useApp, VRM_COUNT, } from "./internal.js";
-export { AGENT_READY_TIMEOUT_MS } from "./types.js";
 /**
- * RuntimeGate and bare `completeOnboarding()` land on the discovered
- * main-tab app; the wizard opens the companion overlay separately.
+ * FirstRunShell and bare `completeFirstRun()` land on the discovered
+ * main-tab app; callers can open the companion overlay separately.
  *
  * Resolved synchronously from the cached apps catalog at module load.
- * Falls back to "chat" when no installed app declares
- * `elizaos.app.mainTab=true`, preserving pre-Phase-1 behavior. Phase 5
- * lands `app-chat` to claim the seam and drops the chat fallback.
+ * Falls back to chat when no installed app declares `elizaos.app.mainTab=true`.
  */
 const DEFAULT_LANDING_TAB = resolveDefaultLandingTab();
 // ── Provider ───────────────────────────────────────────────────────────
 export function AppProvider({ children, branding: brandingOverride, }) {
-    const onLanguageSyncError = useCallback((lang) => {
-        // Notification is deferred until AppProviderInner mounts; this is
-        // only called on language *changes*, never on initial mount.
-        console.warn("[eliza] Failed to sync language to server:", lang);
+    const onLanguageSyncError = useCallback((_lang) => {
+        // Non-fatal: language change will be reflected on next mount.
     }, []);
     return (_jsx(TranslationProvider, { onLanguageSyncError: onLanguageSyncError, branding: brandingOverride, children: _jsx(AppProviderInner, { branding: brandingOverride, children: children }) }));
 }
@@ -74,10 +75,17 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
     const { t, uiLanguage, setUiLanguage } = useTranslation();
     // --- Display preferences (extracted to useDisplayPreferences) ---
     const displayPrefs = useDisplayPreferences();
-    const { state: { uiTheme, themeId, companionVrmPowerMode, companionAnimateWhenHidden, companionHalfFramerateMode, }, setUiTheme, setThemeId, setCompanionVrmPowerMode, setCompanionAnimateWhenHidden, setCompanionHalfFramerateMode, } = displayPrefs;
+    const { state: { uiTheme, uiThemeMode, companionVrmPowerMode, companionAnimateWhenHidden, companionHalfFramerateMode, }, setUiTheme, setUiThemeMode, setCompanionVrmPowerMode, setCompanionAnimateWhenHidden, setCompanionHalfFramerateMode, } = displayPrefs;
+    // Apply the host app's brand theme (set via BrandingConfig.theme).
+    const brandTheme = brandingOverride?.theme;
+    useEffect(() => {
+        if (!brandTheme)
+            return;
+        return applyThemeToDocument(brandTheme, uiTheme);
+    }, [brandTheme, uiTheme]);
     // ── Lifecycle state (consolidated from 20+ useState hooks) ──
     const lifecycle = useLifecycleState();
-    const { state: { connected, agentStatus, onboardingComplete, onboardingUiRevealNonce, onboardingLoading, startupPhase, startupError, authRequired, actionNotice, lifecycleBusy, lifecycleAction, pendingRestart, pendingRestartReasons, restartBannerDismissed, backendConnection, backendDisconnectedBannerDismissed, systemWarnings, }, setConnected, setAgentStatus, setAgentStatusIfChanged, setOnboardingComplete, incrementOnboardingRevealNonce: setOnboardingUiRevealNonce_increment, setOnboardingLoading, setStartupPhase, setStartupError, setAuthRequired, setActionNotice, beginLifecycleAction, finishLifecycleAction, setPendingRestart: setPendingRestartAction, dismissRestartBanner, showRestartBanner, setBackendConnection, dismissBackendBanner: dismissBackendDisconnectedBanner, resetBackendConnection, dismissSystemWarning, startupStatus, lifecycleBusyRef, lifecycleActionRef, } = lifecycle;
+    const { state: { connected, agentStatus, firstRunComplete, firstRunUiRevealNonce, firstRunLoading, startupPhase, startupError, authRequired, actionNotice, lifecycleBusy, lifecycleAction, pendingRestart, pendingRestartReasons, restartBannerDismissed, backendConnection, backendDisconnectedBannerDismissed, systemWarnings, actionBanner, }, setConnected, setAgentStatus, setAgentStatusIfChanged, setFirstRunComplete, incrementFirstRunRevealNonce: setFirstRunUiRevealNonce_increment, setFirstRunLoading, setStartupPhase, setStartupError, setAuthRequired, setActionNotice, beginLifecycleAction, finishLifecycleAction, setPendingRestart: setPendingRestartAction, dismissRestartBanner, showRestartBanner, setBackendConnection, dismissBackendBanner: dismissBackendDisconnectedBanner, resetBackendConnection, dismissSystemWarning, showActionBanner, dismissActionBanner, startupStatus, lifecycleBusyRef, lifecycleActionRef, } = lifecycle;
     // Compatibility wrappers — old code calls these separately; lifecycle hook combines them.
     const setPendingRestart = useCallback((v) => {
         const resolved = typeof v === "function" ? v(lifecycle.state.pendingRestart) : v;
@@ -91,7 +99,7 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         lifecycle.state.pendingRestartReasons,
         setPendingRestartAction,
     ]);
-    const setOnboardingUiRevealNonce = useCallback((_fn) => setOnboardingUiRevealNonce_increment(), [setOnboardingUiRevealNonce_increment]);
+    const setFirstRunUiRevealNonce = useCallback((_fn) => setFirstRunUiRevealNonce_increment(), [setFirstRunUiRevealNonce_increment]);
     const setBackendDisconnectedBannerDismissed = useCallback((v) => {
         if (v)
             dismissBackendDisconnectedBanner();
@@ -110,15 +118,11 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
     // We store a ref to the coordinator's retry since it's created after this line.
     const coordinatorRetryRef = useRef(null);
     const coordinatorResetRef = useRef(null);
-    const coordinatorOnboardingCompleteRef = useRef(null);
+    const coordinatorFirstRunCompleteRef = useRef(null);
     const retryStartup = useCallback(() => {
         lifecycle.retryStartup();
         coordinatorRetryRef.current?.();
     }, [lifecycle.retryStartup]);
-    const _resetToSplash = useCallback(() => {
-        lifecycle.retryStartup();
-        coordinatorResetRef.current?.();
-    }, [lifecycle.retryStartup]);
     const uiShellMode = deriveUiShellModeForTab(tab);
     // --- Pairing ---
     // --- Pairing (extracted to usePairingState) ---
@@ -128,7 +132,7 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
     // Search for "── StartupCoordinator (sole startup authority) ──" below.
     // ── Chat state (consolidated from 18+ useState + 10 useEffect hooks) ──
     const chatState = useChatState();
-    const { state: { chatInput, chatSending, chatFirstTokenReceived, chatLastUsage, chatAvatarVisible, chatAgentVoiceMuted, chatMode, chatAvatarSpeaking, conversations, activeConversationId, companionMessageCutoffTs, conversationMessages, autonomousEvents, autonomousLatestEventId, autonomousRunHealthByRunId, ptySessions, unreadConversations, chatPendingImages, }, setChatInput, setChatSending, setChatFirstTokenReceived, setChatLastUsage, setChatAvatarVisible, setChatAgentVoiceMuted, setChatMode, setChatAvatarSpeaking, setConversations, setActiveConversationId, setCompanionMessageCutoffTs, setConversationMessages, setAutonomousEvents, setAutonomousLatestEventId, setAutonomousRunHealthByRunId, setPtySessions, setChatPendingImages, resetDraftState: resetConversationDraftState, activeConversationIdRef, chatInputRef, chatPendingImagesRef, conversationMessagesRef, conversationHydrationEpochRef, chatAbortRef, chatSendBusyRef, chatSendNonceRef, greetingFiredRef, greetingInFlightConversationRef, companionStaleConversationRefreshRef, autonomousStoreRef, autonomousEventsRef, autonomousLatestEventIdRef, autonomousRunHealthByRunIdRef, autonomousReplayInFlightRef, addUnread, } = chatState;
+    const { state: { chatInput, chatSending, chatFirstTokenReceived, chatLastUsage, chatAvatarVisible, chatAgentVoiceMuted, chatAvatarSpeaking, conversations, activeConversationId, companionMessageCutoffTs, conversationMessages, autonomousEvents, autonomousLatestEventId, autonomousRunHealthByRunId, ptySessions, unreadConversations, chatPendingImages, }, setChatInput, setChatSending, setChatFirstTokenReceived, setChatLastUsage, setChatAvatarVisible, setChatAgentVoiceMuted, setChatAvatarSpeaking, setConversations, setActiveConversationId, setCompanionMessageCutoffTs, setConversationMessages, setAutonomousEvents, setAutonomousLatestEventId, setAutonomousRunHealthByRunId, setPtySessions, setChatPendingImages, resetDraftState: resetConversationDraftState, activeConversationIdRef, chatInputRef, chatPendingImagesRef, conversationsRef, conversationMessagesRef, conversationHydrationEpochRef, chatAbortRef, chatSendBusyRef, chatSendNonceRef, greetingFiredRef, greetingInFlightConversationRef, companionStaleConversationRefreshRef, autonomousStoreRef, autonomousEventsRef, autonomousLatestEventIdRef, autonomousRunHealthByRunIdRef, autonomousReplayInFlightRef, addUnread, } = chatState;
     const _chatComposerTextareaRef = useRef(null);
     // addUnread / removeUnread wrappers for old setUnreadConversations patterns.
     // Read current unreadConversations through a ref so this callback stays
@@ -159,7 +163,7 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         showRestartBanner,
         triggerRestart: triggerRestartProxy,
     });
-    const { plugins, setPlugins, pluginFilter, setPluginFilter, pluginStatusFilter, setPluginStatusFilter, pluginSearch, setPluginSearch, pluginSettingsOpen, setPluginSettingsOpen, pluginAdvancedOpen, setPluginAdvancedOpen, pluginSaving, pluginSaveSuccess, loadPlugins, ensurePluginsLoaded, handlePluginToggle, handlePluginConfigSave, skills, setSkills, skillsSubTab, setSkillsSubTab, skillCreateFormOpen, setSkillCreateFormOpen, skillCreateName, setSkillCreateName, skillCreateDescription, setSkillCreateDescription, skillCreating, skillReviewReport, setSkillReviewReport, skillReviewId, setSkillReviewId, skillReviewLoading, skillToggleAction, skillsMarketplaceQuery, setSkillsMarketplaceQuery, skillsMarketplaceResults, skillsMarketplaceError, skillsMarketplaceLoading, skillsMarketplaceAction, skillsMarketplaceManualGithubUrl, setSkillsMarketplaceManualGithubUrl, loadSkills, refreshSkills, handleSkillToggle, handleCreateSkill, handleOpenSkill, handleDeleteSkill, handleReviewSkill, handleAcknowledgeSkill, searchSkillsMarketplace, installSkillFromMarketplace, installSkillFromGithubUrl, uninstallMarketplaceSkill, enableMarketplaceSkill, disableMarketplaceSkill, copyMarketplaceSkillSource, storePlugins, setStorePlugins, storeSearch, setStoreSearch, storeFilter, setStoreFilter, storeLoading, setStoreLoading, storeInstalling, setStoreInstalling, storeUninstalling, setStoreUninstalling, storeError, setStoreError, storeDetailPlugin, setStoreDetailPlugin, storeSubTab, setStoreSubTab, catalogSkills, setCatalogSkills, catalogTotal, setCatalogTotal, catalogPage, setCatalogPage, catalogTotalPages, setCatalogTotalPages, catalogSort, setCatalogSort, catalogSearch, setCatalogSearch, catalogLoading, setCatalogLoading, catalogError, setCatalogError, catalogDetailSkill, setCatalogDetailSkill, catalogInstalling, setCatalogInstalling, catalogUninstalling, setCatalogUninstalling, } = pluginsSkillsHook;
+    const { plugins, setPlugins, pluginFilter, setPluginFilter, pluginStatusFilter, setPluginStatusFilter, pluginSearch, setPluginSearch, pluginSettingsOpen, setPluginSettingsOpen, pluginAdvancedOpen, setPluginAdvancedOpen, pluginSaving, pluginSaveSuccess, isLoadingPlugins, pluginsLoadError, pluginsLoaded, loadPlugins, ensurePluginsLoaded, handlePluginToggle, handlePluginConfigSave, skills, setSkills, skillsSubTab, setSkillsSubTab, skillCreateFormOpen, setSkillCreateFormOpen, skillCreateName, setSkillCreateName, skillCreateDescription, setSkillCreateDescription, skillCreating, skillReviewReport, setSkillReviewReport, skillReviewId, setSkillReviewId, skillReviewLoading, skillToggleAction, skillsMarketplaceQuery, setSkillsMarketplaceQuery, skillsMarketplaceResults, skillsMarketplaceError, skillsMarketplaceLoading, skillsMarketplaceAction, skillsMarketplaceManualGithubUrl, setSkillsMarketplaceManualGithubUrl, loadSkills, refreshSkills, handleSkillToggle, handleCreateSkill, handleOpenSkill, handleDeleteSkill, handleReviewSkill, handleAcknowledgeSkill, searchSkillsMarketplace, installSkillFromMarketplace, installSkillFromGithubUrl, uninstallMarketplaceSkill, enableMarketplaceSkill, disableMarketplaceSkill, copyMarketplaceSkillSource, storePlugins, setStorePlugins, storeSearch, setStoreSearch, storeFilter, setStoreFilter, storeLoading, setStoreLoading, storeInstalling, setStoreInstalling, storeUninstalling, setStoreUninstalling, storeError, setStoreError, storeDetailPlugin, setStoreDetailPlugin, storeSubTab, setStoreSubTab, catalogSkills, setCatalogSkills, catalogTotal, setCatalogTotal, catalogPage, setCatalogPage, catalogTotalPages, setCatalogTotalPages, catalogSort, setCatalogSort, catalogSearch, setCatalogSearch, catalogLoading, setCatalogLoading, catalogError, setCatalogError, catalogDetailSkill, setCatalogDetailSkill, catalogInstalling, setCatalogInstalling, catalogUninstalling, setCatalogUninstalling, } = pluginsSkillsHook;
     // --- Logs (extracted to useLogsState) ---
     const logsHook = useLogsState();
     const { state: { logs, logSources, logTags, logTagFilter, logLevelFilter, logSourceFilter, logLoadError, }, setLogs, setLogTagFilter, setLogLevelFilter, setLogSourceFilter, loadLogs, } = logsHook;
@@ -173,10 +177,109 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
     // --- Agent export/import (extracted to useExportImportState) ---
     const exportImportHook = useExportImportState();
     const { state: { exportBusy, exportPassword, exportIncludeLogs, exportError, exportSuccess, importBusy, importPassword, importFile, importError, importSuccess, }, setExportPassword, setExportIncludeLogs, setExportError, setExportSuccess, setImportPassword, setImportFile, setImportError, setImportSuccess, handleAgentExport, handleAgentImport, } = exportImportHook;
-    // ── Onboarding state (consolidated from 35+ useState hooks) ──
-    const onboarding = useOnboardingState(brandingOverride?.cloudOnly);
-    const { state: { step: onboardingStep, mode: onboardingMode, activeGuide: onboardingActiveGuide, deferredTasks: onboardingDeferredTasks, postChecklistDismissed: postOnboardingChecklistDismissed, options: onboardingOptions, name: onboardingName, ownerName: onboardingOwnerName, style: onboardingStyle, avatar: onboardingAvatar, serverTarget: onboardingServerTarget, cloudApiKey: onboardingCloudApiKey, provider: onboardingProvider, apiKey: onboardingApiKey, voiceProvider: onboardingVoiceProvider, voiceApiKey: onboardingVoiceApiKey, smallModel: onboardingSmallModel, largeModel: onboardingLargeModel, openRouterModel: onboardingOpenRouterModel, primaryModel: onboardingPrimaryModel, existingInstallDetected: onboardingExistingInstallDetected, detectedProviders: onboardingDetectedProviders, remoteApiBase: onboardingRemoteApiBase, remoteToken: onboardingRemoteToken, subscriptionTab: onboardingSubscriptionTab, elizaCloudTab: onboardingElizaCloudTab, selectedChains: onboardingSelectedChains, rpcSelections: onboardingRpcSelections, rpcKeys: onboardingRpcKeys, featureTelegram: onboardingFeatureTelegram, featureDiscord: onboardingFeatureDiscord, featurePhone: onboardingFeaturePhone, featureCrypto: onboardingFeatureCrypto, featureBrowser: onboardingFeatureBrowser, featureComputerUse: onboardingFeatureComputerUse, featureOAuthPending: onboardingFeatureOAuthPending, cloudProvisionedContainer: onboardingCloudProvisionedContainer, }, setStep: setOnboardingStep, setMode: setOnboardingMode, setActiveGuide: setOnboardingActiveGuide, addDeferredTask: addDeferredOnboardingTask, setOptions: setOnboardingOptions, setDetectedProviders: setOnboardingDetectedProviders, completionCommittedRef: onboardingCompletionCommittedRefFromHook, forceLocalBootstrapRef: forceLocalBootstrapRefFromHook, } = onboarding;
-    const { onboardingRemoteConnecting, onboardingRemoteError, onboardingRemoteConnected, onboardingTelegramToken, onboardingDiscordToken, onboardingWhatsAppSessionPath, onboardingTwilioAccountSid, onboardingTwilioAuthToken, onboardingTwilioPhoneNumber, onboardingBlooioApiKey, onboardingBlooioPhoneNumber, onboardingGithubToken, setOnboardingName, setOnboardingOwnerName, setOnboardingStyle, setOnboardingServerTarget, setOnboardingCloudApiKey, setOnboardingSmallModel, setOnboardingLargeModel, setOnboardingProvider, setOnboardingApiKey, setOnboardingVoiceProvider, setOnboardingVoiceApiKey, setOnboardingExistingInstallDetected, setOnboardingRemoteApiBase, setOnboardingRemoteToken, setOnboardingRemoteConnecting, setOnboardingRemoteError, setOnboardingRemoteConnected, setOnboardingOpenRouterModel, setOnboardingPrimaryModel, setOnboardingTelegramToken, setOnboardingDiscordToken, setOnboardingWhatsAppSessionPath, setOnboardingTwilioAccountSid, setOnboardingTwilioAuthToken, setOnboardingTwilioPhoneNumber, setOnboardingBlooioApiKey, setOnboardingBlooioPhoneNumber, setOnboardingGithubToken, setOnboardingSubscriptionTab, setOnboardingElizaCloudTab, setOnboardingSelectedChains, setOnboardingRpcSelections, setOnboardingRpcKeys, setOnboardingAvatar, setOnboardingFeatureTelegram, setOnboardingFeatureDiscord, setOnboardingFeaturePhone, setOnboardingFeatureCrypto, setOnboardingFeatureBrowser, setOnboardingFeatureComputerUse, setOnboardingFeatureOAuthPending, setOnboardingCloudProvisionedContainer, setPostOnboardingChecklistDismissed, setOnboardingDeferredTasks, } = useOnboardingCompat(onboarding);
+    // ── First-run state (consolidated from 35+ useState hooks) ──
+    const firstRun = useFirstRunState(brandingOverride?.cloudOnly);
+    const { state: { step: setupStep, mode: firstRunMode, activeGuide: firstRunActiveGuide, deferredTasks: firstRunDeferredTasks, postChecklistDismissed: postFirstRunChecklistDismissed, options: firstRunOptions, name: firstRunName, ownerName: firstRunOwnerName, style: firstRunStyle, avatar: setupAvatar, serverTarget: firstRunRuntimeTarget, cloudApiKey: firstRunCloudApiKey, provider: firstRunProvider, apiKey: firstRunApiKey, voiceProvider: firstRunVoiceProvider, voiceApiKey: firstRunVoiceApiKey, smallModel: firstRunSmallModel, largeModel: firstRunLargeModel, openRouterModel: firstRunOpenRouterModel, primaryModel: firstRunPrimaryModel, existingInstallDetected: firstRunExistingInstallDetected, detectedProviders: firstRunDetectedProviders, remoteApiBase: firstRunRemoteApiBase, remoteToken: firstRunRemoteToken, subscriptionTab: firstRunSubscriptionTab, elizaCloudTab: firstRunElizaCloudTab, selectedChains: firstRunSelectedChains, rpcSelections: firstRunRpcSelections, rpcKeys: firstRunRpcKeys, featureTelegram: firstRunFeatureTelegram, featureDiscord: firstRunFeatureDiscord, featurePhone: firstRunFeaturePhone, featureCrypto: firstRunFeatureCrypto, featureBrowser: firstRunFeatureBrowser, featureComputerUse: firstRunFeatureComputerUse, featureOAuthPending: firstRunFeatureOAuthPending, cloudProvisionedContainer: firstRunCloudProvisionedContainer, }, setStep: setSetupStep, setMode: setFirstRunMode, setActiveGuide: setFirstRunActiveGuide, addDeferredTask: addDeferredFirstRunTask, setOptions: setFirstRunOptions, setDetectedProviders: setFirstRunDetectedProviders, completionCommittedRef: firstRunCompletionCommittedRefFromHook, forceLocalBootstrapRef: forceLocalBootstrapRefFromHook, } = firstRun;
+    const { firstRunRemoteConnecting, firstRunRemoteError, firstRunRemoteConnected, firstRunTelegramToken, firstRunDiscordToken, firstRunWhatsAppSessionPath, firstRunTwilioAccountSid, firstRunTwilioAuthToken, firstRunTwilioPhoneNumber, firstRunBlooioApiKey, firstRunBlooioPhoneNumber, firstRunGithubToken, setFirstRunName, setFirstRunOwnerName, setFirstRunStyle, setFirstRunRuntimeTarget, setFirstRunCloudApiKey, setFirstRunSmallModel, setFirstRunLargeModel, setFirstRunProvider, setFirstRunApiKey, setFirstRunVoiceProvider, setFirstRunVoiceApiKey, setFirstRunExistingInstallDetected, setFirstRunRemoteApiBase, setFirstRunRemoteToken, setFirstRunRemoteConnecting, setFirstRunRemoteError, setFirstRunRemoteConnected, setFirstRunOpenRouterModel, setFirstRunPrimaryModel, setFirstRunTelegramToken, setFirstRunDiscordToken, setFirstRunWhatsAppSessionPath, setFirstRunTwilioAccountSid, setFirstRunTwilioAuthToken, setFirstRunTwilioPhoneNumber, setFirstRunBlooioApiKey, setFirstRunBlooioPhoneNumber, setFirstRunGithubToken, setFirstRunSubscriptionTab, setFirstRunElizaCloudTab, setFirstRunSelectedChains, setFirstRunRpcSelections, setFirstRunRpcKeys, setSetupAvatar, setFirstRunFeatureTelegram, setFirstRunFeatureDiscord, setFirstRunFeaturePhone, setFirstRunFeatureCrypto, setFirstRunFeatureBrowser, setFirstRunFeatureComputerUse, setFirstRunFeatureOAuthPending, setFirstRunCloudProvisionedContainer, setPostFirstRunChecklistDismissed, setFirstRunDeferredTasks, } = useMemo(() => {
+        const { dispatch, setConnectorToken, setDeferredTasks, setField, setRemoteStatus, } = firstRun;
+        const { connectorTokens, remote } = firstRun.state;
+        const bindField = (field) => (value) => {
+            setField(field, value);
+        };
+        const bindConnectorToken = (key) => (value) => {
+            setConnectorToken(key, value);
+        };
+        return {
+            firstRunRemoteConnecting: remote.status === "connecting",
+            firstRunRemoteError: remote.error,
+            firstRunRemoteConnected: remote.status === "connected",
+            firstRunTelegramToken: connectorTokens.telegramToken,
+            firstRunDiscordToken: connectorTokens.discordToken,
+            firstRunWhatsAppSessionPath: connectorTokens.whatsAppSessionPath,
+            firstRunTwilioAccountSid: connectorTokens.twilioAccountSid,
+            firstRunTwilioAuthToken: connectorTokens.twilioAuthToken,
+            firstRunTwilioPhoneNumber: connectorTokens.twilioPhoneNumber,
+            firstRunBlooioApiKey: connectorTokens.blooioApiKey,
+            firstRunBlooioPhoneNumber: connectorTokens.blooioPhoneNumber,
+            firstRunGithubToken: connectorTokens.githubToken,
+            setFirstRunName: bindField("name"),
+            setFirstRunOwnerName: bindField("ownerName"),
+            setFirstRunStyle: bindField("style"),
+            setFirstRunRuntimeTarget: bindField("serverTarget"),
+            setFirstRunCloudApiKey: bindField("cloudApiKey"),
+            setFirstRunSmallModel: bindField("smallModel"),
+            setFirstRunLargeModel: bindField("largeModel"),
+            setFirstRunProvider: bindField("provider"),
+            setFirstRunApiKey: bindField("apiKey"),
+            setFirstRunVoiceProvider: bindField("voiceProvider"),
+            setFirstRunVoiceApiKey: bindField("voiceApiKey"),
+            setFirstRunExistingInstallDetected: bindField("existingInstallDetected"),
+            setFirstRunRemoteApiBase: (value) => {
+                dispatch({ type: "SET_REMOTE_API_BASE", value });
+            },
+            setFirstRunRemoteToken: (value) => {
+                dispatch({ type: "SET_REMOTE_TOKEN", value });
+            },
+            setFirstRunRemoteConnecting: (value) => {
+                if (value) {
+                    setRemoteStatus("connecting");
+                    return;
+                }
+                if (remote.status === "connecting") {
+                    setRemoteStatus("idle");
+                }
+            },
+            setFirstRunRemoteError: (value) => {
+                if (value) {
+                    setRemoteStatus("error", value);
+                    return;
+                }
+                if (remote.status === "error") {
+                    setRemoteStatus("idle");
+                }
+            },
+            setFirstRunRemoteConnected: (value) => {
+                if (value) {
+                    setRemoteStatus("connected");
+                    return;
+                }
+                if (remote.status === "connected") {
+                    setRemoteStatus("idle");
+                }
+            },
+            setFirstRunOpenRouterModel: bindField("openRouterModel"),
+            setFirstRunPrimaryModel: bindField("primaryModel"),
+            setFirstRunTelegramToken: bindConnectorToken("telegramToken"),
+            setFirstRunDiscordToken: bindConnectorToken("discordToken"),
+            setFirstRunWhatsAppSessionPath: bindConnectorToken("whatsAppSessionPath"),
+            setFirstRunTwilioAccountSid: bindConnectorToken("twilioAccountSid"),
+            setFirstRunTwilioAuthToken: bindConnectorToken("twilioAuthToken"),
+            setFirstRunTwilioPhoneNumber: bindConnectorToken("twilioPhoneNumber"),
+            setFirstRunBlooioApiKey: bindConnectorToken("blooioApiKey"),
+            setFirstRunBlooioPhoneNumber: bindConnectorToken("blooioPhoneNumber"),
+            setFirstRunGithubToken: bindConnectorToken("githubToken"),
+            setFirstRunSubscriptionTab: bindField("subscriptionTab"),
+            setFirstRunElizaCloudTab: bindField("elizaCloudTab"),
+            setFirstRunSelectedChains: bindField("selectedChains"),
+            setFirstRunRpcSelections: bindField("rpcSelections"),
+            setFirstRunRpcKeys: bindField("rpcKeys"),
+            setSetupAvatar: bindField("avatar"),
+            setFirstRunFeatureTelegram: bindField("featureTelegram"),
+            setFirstRunFeatureDiscord: bindField("featureDiscord"),
+            setFirstRunFeaturePhone: bindField("featurePhone"),
+            setFirstRunFeatureCrypto: bindField("featureCrypto"),
+            setFirstRunFeatureBrowser: bindField("featureBrowser"),
+            setFirstRunFeatureComputerUse: bindField("featureComputerUse"),
+            setFirstRunFeatureOAuthPending: bindField("featureOAuthPending"),
+            setFirstRunCloudProvisionedContainer: bindField("cloudProvisionedContainer"),
+            setPostFirstRunChecklistDismissed: (value) => {
+                dispatch({ type: "SET_POST_CHECKLIST_DISMISSED", value });
+            },
+            setFirstRunDeferredTasks: (tasks) => {
+                setDeferredTasks(tasks);
+            },
+        };
+    }, [firstRun]);
     // startupStatus is now derived in useLifecycleState
     // --- Command palette / emote picker / MCP / game / dropped files (extracted to useMiscUiState) ---
     const miscUiHook = useMiscUiState();
@@ -190,8 +293,8 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
     // elizaCloudLoginPollTimer are now in useCloudState (cloudHook)
     const _restartNotificationSignatureRef = useRef(null);
     const _heartbeatNotificationKeyRef = useRef(null);
-    // Onboarding refs now come from useOnboardingState
-    const onboardingCompletionCommittedRef = onboardingCompletionCommittedRefFromHook;
+    // First-run refs now come from useFirstRunState
+    const firstRunCompletionCommittedRef = firstRunCompletionCommittedRefFromHook;
     const forceLocalBootstrapRef = forceLocalBootstrapRefFromHook;
     // exportBusyRef and importBusyRef are now managed inside useExportImportState (exportImportHook)
     // walletApiKeySavingRef is now managed inside useWalletState (walletHook)
@@ -212,11 +315,13 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
     // setActionNotice is now provided by useLifecycleState
     // ── Cloud state (extracted to useCloudState) ───────────────────────
     // Placed after walletHook so loadWalletConfig is available.
-    const cloudHook = useCloudState({ setActionNotice, loadWalletConfig, t });
-    // ── Vincent state (extracted to useVincentState) ──────────────────
-    const vincentHook = useVincentState({ setActionNotice, t });
-    const { vincentConnected, vincentLoginBusy, vincentLoginError, handleVincentLogin, handleVincentDisconnect, } = vincentHook;
-    const { elizaCloudEnabled, setElizaCloudEnabled, elizaCloudVoiceProxyAvailable, setElizaCloudVoiceProxyAvailable, elizaCloudConnected, setElizaCloudConnected, elizaCloudHasPersistedKey, setElizaCloudHasPersistedKey, elizaCloudCredits, setElizaCloudCredits, elizaCloudCreditsLow, setElizaCloudCreditsLow, elizaCloudCreditsCritical, setElizaCloudCreditsCritical, elizaCloudAuthRejected, setElizaCloudAuthRejected, elizaCloudCreditsError, setElizaCloudCreditsError, elizaCloudTopUpUrl, setElizaCloudTopUpUrl, elizaCloudUserId, setElizaCloudUserId, elizaCloudStatusReason, setElizaCloudStatusReason, cloudDashboardView, setCloudDashboardView, elizaCloudLoginBusy, elizaCloudLoginError, setElizaCloudLoginError, elizaCloudDisconnecting, elizaCloudPollInterval, elizaCloudPreferDisconnectedUntilLoginRef, elizaCloudLoginPollTimer, pollCloudCredits, handleCloudLogin, handleCloudDisconnect, } = cloudHook;
+    const cloudHook = useCloudState({
+        setActionNotice,
+        loadWalletConfig,
+        t,
+        disconnectLocked: brandingOverride?.cloudOnly === true,
+    });
+    const { elizaCloudEnabled, setElizaCloudEnabled, elizaCloudVoiceProxyAvailable, setElizaCloudVoiceProxyAvailable, elizaCloudConnected, setElizaCloudConnected, elizaCloudHasPersistedKey, setElizaCloudHasPersistedKey, elizaCloudCredits, setElizaCloudCredits, elizaCloudCreditsLow, setElizaCloudCreditsLow, elizaCloudCreditsCritical, setElizaCloudCreditsCritical, elizaCloudAuthRejected, setElizaCloudAuthRejected, elizaCloudCreditsError, setElizaCloudCreditsError, elizaCloudTopUpUrl, setElizaCloudTopUpUrl, elizaCloudUserId, setElizaCloudUserId, elizaCloudStatusReason, setElizaCloudStatusReason, cloudDashboardView, setCloudDashboardView, elizaCloudLoginBusy, elizaCloudLoginError, setElizaCloudLoginError, elizaCloudLoginFallbackUrl, elizaCloudDisconnecting, elizaCloudPollInterval, elizaCloudPreferDisconnectedUntilLoginRef, elizaCloudLoginPollTimer, pollCloudCredits, handleCloudLogin, handleCloudDisconnect, } = cloudHook;
     // ── Clipboard ──────────────────────────────────────────────────────
     const copyToClipboard = useCallback(async (text) => {
         await copyTextToClipboard(text);
@@ -255,7 +360,7 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         characterDraft,
         loadCharacter,
         selectedVrmIndex,
-        onboardingComplete,
+        firstRunComplete,
         uiLanguage,
         setOwnerNameState,
     });
@@ -271,7 +376,6 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         tab,
         agentStatus,
         chatInput,
-        chatMode,
         conversations,
         activeConversationId,
         companionMessageCutoffTs,
@@ -291,6 +395,7 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         activeConversationIdRef,
         chatInputRef,
         chatPendingImagesRef,
+        conversationsRef,
         conversationMessagesRef,
         conversationHydrationEpochRef,
         chatAbortRef,
@@ -332,30 +437,30 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         setElizaCloudUserId,
         setElizaCloudStatusReason,
         setElizaCloudLoginError,
-        onboardingCompletionCommittedRef,
-        setOnboardingUiRevealNonce,
-        setOnboardingLoading,
-        setOnboardingComplete,
-        setOnboardingStep,
-        setOnboardingMode,
-        setOnboardingActiveGuide,
-        setOnboardingDeferredTasks,
-        setPostOnboardingChecklistDismissed,
-        setOnboardingName,
-        setOnboardingStyle,
-        setOnboardingServerTarget,
-        setOnboardingProvider,
-        setOnboardingApiKey,
-        setOnboardingVoiceProvider: setOnboardingVoiceProvider,
-        setOnboardingVoiceApiKey: setOnboardingVoiceApiKey,
-        setOnboardingPrimaryModel,
-        setOnboardingOpenRouterModel,
-        setOnboardingRemoteConnected,
-        setOnboardingRemoteApiBase,
-        setOnboardingRemoteToken,
-        setOnboardingSmallModel,
-        setOnboardingLargeModel,
-        setOnboardingOptions,
+        firstRunCompletionCommittedRef,
+        setFirstRunUiRevealNonce,
+        setFirstRunLoading,
+        setFirstRunComplete,
+        setSetupStep,
+        setFirstRunMode,
+        setFirstRunActiveGuide,
+        setFirstRunDeferredTasks,
+        setPostFirstRunChecklistDismissed,
+        setFirstRunName,
+        setFirstRunStyle,
+        setFirstRunRuntimeTarget,
+        setFirstRunProvider,
+        setFirstRunApiKey,
+        setFirstRunVoiceProvider: setFirstRunVoiceProvider,
+        setFirstRunVoiceApiKey: setFirstRunVoiceApiKey,
+        setFirstRunPrimaryModel,
+        setFirstRunOpenRouterModel,
+        setFirstRunRemoteConnected,
+        setFirstRunRemoteApiBase,
+        setFirstRunRemoteToken,
+        setFirstRunSmallModel,
+        setFirstRunLargeModel,
+        setFirstRunOptions,
         setSelectedVrmIndex,
         setCustomVrmUrl,
         setCustomBackgroundUrl,
@@ -364,38 +469,86 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         setLogs: setLogs,
         coordinatorResetRef,
     });
-    const { fetchGreeting, requestGreetingWhenRunning, hydrateInitialConversationState, handleStartDraftConversation, handleStart, handleStop, handleRestart, triggerRestart, retryBackendConnection, restartBackend, relaunchDesktop, notifyAssistantEvent, notifyHeartbeatEvent, handleResetAppliedFromMain, handleReset, handleNewConversation, sendChatText, handleChatSend, sendActionMessage, handleChatStop, handleChatRetry, handleChatEdit, handleChatClear, handleSelectConversation, handleDeleteConversation, handleRenameConversation, suggestConversationTitle, } = chatCallbacks;
+    const { fetchGreeting, requestGreetingWhenRunning, hydrateInitialConversationState, handleStartDraftConversation, handleStart, handleStop, handleRestart, triggerRestart, retryBackendConnection, restartBackend, relaunchDesktop, notifyHeartbeatEvent, handleResetAppliedFromMain, handleReset, handleNewConversation, sendChatText, handleChatSend, sendActionMessage, handleChatStop, handleChatRetry, handleChatEdit, handleChatClear, handleSelectConversation, handleDeleteConversation, handleRenameConversation, suggestConversationTitle, } = chatCallbacks;
     useEffect(() => {
         triggerRestartRef.current = triggerRestart;
     }, [triggerRestart]);
+    // ── Cross-window sync + reconnect reconciliation ───────────────────
+    // Track whether the last active-conversation change came from another window
+    // so applying it doesn't echo straight back out and loop between tabs.
+    const tabSyncActiveConvRef = useRef(null);
+    const tabSync = useTabSync({
+        onActiveConversation: (id) => {
+            tabSyncActiveConvRef.current = id;
+            setActiveConversationId(id);
+        },
+        onPrefs: (prefs) => {
+            if (prefs.language) {
+                setUiLanguage(prefs.language);
+            }
+        },
+    });
+    // Mirror this window's active conversation to the other windows. Suppress the
+    // mirror when the change itself arrived via sync (no echo).
+    useEffect(() => {
+        if (tabSyncActiveConvRef.current === activeConversationId) {
+            tabSyncActiveConvRef.current = null;
+            return;
+        }
+        tabSync.publishActiveConversation(activeConversationId);
+    }, [activeConversationId, tabSync]);
+    // Mirror the UI language to the other windows.
+    useEffect(() => {
+        tabSync.publishPrefs({ language: uiLanguage });
+    }, [uiLanguage, tabSync]);
+    // Reconnect reconciliation: when the socket comes back after a drop, re-arm
+    // this window's per-connection active conversation on the server (the fresh
+    // connection has no memory of it) and ask conversation views to refetch their
+    // recent messages so the UI repairs state lost during the gap. Fires once per
+    // reconnect — no polling.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: subscribe once on mount; the current conversation is read through a ref, and `client` is module-stable.
+    useEffect(() => {
+        return client.onReconnect(() => {
+            const convId = activeConversationIdRef.current;
+            client.sendWsMessage({
+                type: "active-conversation",
+                conversationId: convId,
+            });
+            if (typeof window !== "undefined") {
+                window.dispatchEvent(new CustomEvent(RESYNC_EVENT, {
+                    detail: { conversationId: convId },
+                }));
+            }
+        });
+    }, []);
     // ── Pairing ────────────────────────────────────────────────────────
     // ── Plugin / Skill / Store / Catalog actions are provided by usePluginsSkillsState (pluginsSkillsHook) ──
     // ── Inventory / Registry / Drop / Whitelist actions are provided by useWalletState (walletHook) ──
     // ── Character actions are provided by useCharacterState (characterHook) ──
-    // ── Onboarding callbacks (extracted to useOnboardingCallbacks) ──────
-    const onboardingCallbacks = useOnboardingCallbacks({
-        onboarding,
+    // ── First-run callbacks (extracted to useFirstRunCallbacks) ──────
+    const firstRunCallbacks = useFirstRunCallbacks({
+        firstRun,
         setActiveOverlayApp,
-        setOnboardingStep,
-        setOnboardingMode,
-        setOnboardingActiveGuide,
-        addDeferredOnboardingTask: addDeferredOnboardingTask,
-        setOnboardingDetectedProviders,
-        setOnboardingServerTarget,
-        setOnboardingCloudApiKey,
-        setOnboardingProvider,
-        setOnboardingApiKey,
-        setOnboardingPrimaryModel,
-        setOnboardingRemoteApiBase,
-        setOnboardingRemoteToken,
-        setOnboardingRemoteConnecting,
-        setOnboardingRemoteError,
-        setOnboardingRemoteConnected,
-        setPostOnboardingChecklistDismissed,
+        setSetupStep,
+        setFirstRunMode,
+        setFirstRunActiveGuide,
+        addDeferredFirstRunTask: addDeferredFirstRunTask,
+        setFirstRunDetectedProviders,
+        setFirstRunRuntimeTarget,
+        setFirstRunCloudApiKey,
+        setFirstRunProvider,
+        setFirstRunApiKey,
+        setFirstRunPrimaryModel,
+        setFirstRunRemoteApiBase,
+        setFirstRunRemoteToken,
+        setFirstRunRemoteConnecting,
+        setFirstRunRemoteError,
+        setFirstRunRemoteConnected,
+        setPostFirstRunChecklistDismissed,
         setBrowserEnabled,
         setComputerUseEnabled,
-        setOnboardingComplete,
-        coordinatorOnboardingCompleteRef,
+        setFirstRunComplete,
+        coordinatorFirstRunCompleteRef,
         initialTabSetRef,
         setTab,
         defaultLandingTab: DEFAULT_LANDING_TAB,
@@ -410,317 +563,174 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         forceLocalBootstrapRef,
         client,
     });
-    const { handleOnboardingNext, handleOnboardingBack, handleOnboardingJumpToStep, goToOnboardingStep, handleOnboardingRemoteConnect, handleOnboardingUseLocalBackend, handleCloudOnboardingFinish, applyDetectedProviders, completeOnboarding, } = onboardingCallbacks;
+    const { handleFirstRunNext, handleFirstRunBack, handleFirstRunJumpToStep, goToFirstRunStep, handleFirstRunRemoteConnect, handleFirstRunUseLocalBackend, handleCloudFirstRunFinish, applyDetectedProviders, completeFirstRun, } = firstRunCallbacks;
     // handleAgentExport and handleAgentImport are now in useExportImportState (exportImportHook)
     // closeCommandPalette, openEmotePicker, closeEmotePicker are now in useMiscUiState (miscUiHook)
     // ── Generic state setter ───────────────────────────────────────────
-    const setState = useCallback((key, value) => {
-        const setterMap = {
-            tab: setTab,
-            onboardingStep: setOnboardingStep,
-            chatInput: setChatInput,
-            chatAvatarVisible: setChatAvatarVisible,
-            chatAgentVoiceMuted: setChatAgentVoiceMuted,
-            chatLastUsage: setChatLastUsage,
-            chatMode: setChatMode,
-            chatAvatarSpeaking: setChatAvatarSpeaking,
-            companionMessageCutoffTs: setCompanionMessageCutoffTs,
-            uiShellMode: setUiShellMode,
-            uiLanguage: setUiLanguage,
-            autonomousRunHealthByRunId: setAutonomousRunHealthByRunId,
-            startupError: setStartupError,
-            pairingCodeInput: setPairingCodeInput,
-            pluginFilter: setPluginFilter,
-            pluginStatusFilter: setPluginStatusFilter,
-            pluginSearch: setPluginSearch,
-            pluginSettingsOpen: setPluginSettingsOpen,
-            pluginAdvancedOpen: setPluginAdvancedOpen,
-            skillsSubTab: setSkillsSubTab,
-            skillCreateFormOpen: setSkillCreateFormOpen,
-            skillCreateName: setSkillCreateName,
-            skillCreateDescription: setSkillCreateDescription,
-            skillsMarketplaceQuery: setSkillsMarketplaceQuery,
-            skillsMarketplaceManualGithubUrl: setSkillsMarketplaceManualGithubUrl,
-            logTagFilter: setLogTagFilter,
-            logLevelFilter: setLogLevelFilter,
-            logSourceFilter: setLogSourceFilter,
-            browserEnabled: setBrowserEnabled,
-            computerUseEnabled: setComputerUseEnabled,
-            walletEnabled: setWalletEnabled,
-            inventoryView: setInventoryView,
-            inventorySort: setInventorySort,
-            inventorySortDirection: setInventorySortDirection,
-            inventoryChainFilters: setInventoryChainFilters,
-            exportPassword: setExportPassword,
-            exportIncludeLogs: setExportIncludeLogs,
-            exportError: setExportError,
-            exportSuccess: setExportSuccess,
-            importPassword: setImportPassword,
-            importFile: setImportFile,
-            importError: setImportError,
-            importSuccess: setImportSuccess,
-            onboardingName: setOnboardingName,
-            onboardingOwnerName: setOnboardingOwnerName,
-            onboardingStyle: setOnboardingStyle,
-            onboardingServerTarget: setOnboardingServerTarget,
-            onboardingCloudApiKey: setOnboardingCloudApiKey,
-            onboardingSmallModel: setOnboardingSmallModel,
-            onboardingLargeModel: setOnboardingLargeModel,
-            onboardingProvider: setOnboardingProvider,
-            onboardingApiKey: setOnboardingApiKey,
-            onboardingVoiceProvider: setOnboardingVoiceProvider,
-            onboardingVoiceApiKey: setOnboardingVoiceApiKey,
-            onboardingExistingInstallDetected: setOnboardingExistingInstallDetected,
-            onboardingDetectedProviders: setOnboardingDetectedProviders,
-            onboardingRemoteApiBase: setOnboardingRemoteApiBase,
-            onboardingRemoteToken: setOnboardingRemoteToken,
-            onboardingRemoteConnecting: setOnboardingRemoteConnecting,
-            onboardingRemoteError: setOnboardingRemoteError,
-            onboardingRemoteConnected: setOnboardingRemoteConnected,
-            onboardingSelectedChains: setOnboardingSelectedChains,
-            onboardingRpcSelections: setOnboardingRpcSelections,
-            onboardingOpenRouterModel: setOnboardingOpenRouterModel,
-            onboardingPrimaryModel: setOnboardingPrimaryModel,
-            onboardingTelegramToken: setOnboardingTelegramToken,
-            onboardingDiscordToken: setOnboardingDiscordToken,
-            onboardingWhatsAppSessionPath: setOnboardingWhatsAppSessionPath,
-            onboardingTwilioAccountSid: setOnboardingTwilioAccountSid,
-            onboardingTwilioAuthToken: setOnboardingTwilioAuthToken,
-            onboardingTwilioPhoneNumber: setOnboardingTwilioPhoneNumber,
-            onboardingBlooioApiKey: setOnboardingBlooioApiKey,
-            onboardingBlooioPhoneNumber: setOnboardingBlooioPhoneNumber,
-            onboardingGithubToken: setOnboardingGithubToken,
-            onboardingSubscriptionTab: setOnboardingSubscriptionTab,
-            onboardingElizaCloudTab: setOnboardingElizaCloudTab,
-            onboardingRpcKeys: setOnboardingRpcKeys,
-            onboardingAvatar: setOnboardingAvatar,
-            onboardingFeatureTelegram: setOnboardingFeatureTelegram,
-            onboardingFeatureDiscord: setOnboardingFeatureDiscord,
-            onboardingFeaturePhone: setOnboardingFeaturePhone,
-            onboardingFeatureCrypto: setOnboardingFeatureCrypto,
-            onboardingFeatureBrowser: setOnboardingFeatureBrowser,
-            onboardingFeatureComputerUse: setOnboardingFeatureComputerUse,
-            onboardingFeatureOAuthPending: setOnboardingFeatureOAuthPending,
-            elizaCloudEnabled: setElizaCloudEnabled,
-            elizaCloudVoiceProxyAvailable: setElizaCloudVoiceProxyAvailable,
-            cloudDashboardView: setCloudDashboardView,
-            selectedVrmIndex: setSelectedVrmIndex,
-            customVrmUrl: setCustomVrmUrl,
-            customVrmPreviewUrl: setCustomVrmPreviewUrl,
-            customBackgroundUrl: setCustomBackgroundUrl,
-            customCatchphrase: setCustomCatchphrase,
-            customVoicePresetId: setCustomVoicePresetId,
-            activePackId: setActivePackId,
-            customWorldUrl: setCustomWorldUrl,
-            commandQuery: setCommandQuery,
-            commandActiveIndex: setCommandActiveIndex,
-            emotePickerOpen: setEmotePickerOpen,
-            analysisMode: setAnalysisMode,
-            storeSearch: setStoreSearch,
-            storeFilter: setStoreFilter,
-            storeSubTab: setStoreSubTab,
-            catalogSearch: setCatalogSearch,
-            catalogSort: setCatalogSort,
-            catalogPage: setCatalogPage,
-            skillReviewId: setSkillReviewId,
-            skillReviewReport: setSkillReviewReport,
-            appRuns: setAppRuns,
-            activeGameRunId: setActiveGameRunId,
-            gameOverlayEnabled: setGameOverlayEnabled,
-            companionAppRunning: (v) => setActiveOverlayApp(v ? "@elizaos/app-companion" : null),
-            activeOverlayApp: setActiveOverlayApp,
-            activeInboxChat: setActiveInboxChat,
-            activeTerminalSessionId: setActiveTerminalSessionId,
-            storePlugins: setStorePlugins,
-            storeLoading: setStoreLoading,
-            storeInstalling: setStoreInstalling,
-            storeUninstalling: setStoreUninstalling,
-            storeError: setStoreError,
-            storeDetailPlugin: setStoreDetailPlugin,
-            catalogSkills: setCatalogSkills,
-            catalogTotal: setCatalogTotal,
-            catalogTotalPages: setCatalogTotalPages,
-            catalogLoading: setCatalogLoading,
-            catalogError: setCatalogError,
-            catalogDetailSkill: setCatalogDetailSkill,
-            catalogInstalling: setCatalogInstalling,
-            catalogUninstalling: setCatalogUninstalling,
-            mcpConfiguredServers: setMcpConfiguredServers,
-            mcpServerStatuses: setMcpServerStatuses,
-            mcpMarketplaceQuery: setMcpMarketplaceQuery,
-            mcpMarketplaceResults: setMcpMarketplaceResults,
-            mcpMarketplaceLoading: setMcpMarketplaceLoading,
-            mcpAction: setMcpAction,
-            mcpAddingServer: setMcpAddingServer,
-            mcpAddingResult: setMcpAddingResult,
-            mcpEnvInputs: setMcpEnvInputs,
-            mcpHeaderInputs: setMcpHeaderInputs,
-            droppedFiles: setDroppedFiles,
-            shareIngestNotice: setShareIngestNotice,
-            appsSubTab: setAppsSubTab,
-            agentSubTab: setAgentSubTab,
-            pluginsSubTab: setPluginsSubTab,
-            databaseSubTab: setDatabaseSubTab,
-            favoriteApps: setFavoriteApps,
-            recentApps: setRecentApps,
-            configRaw: setConfigRaw,
-            configText: setConfigText,
-            onboardingComplete: setOnboardingComplete,
-        };
-        const setter = setterMap[key];
-        if (setter)
-            setter(value);
-    }, [
-        setOnboardingStep,
-        setSelectedVrmIndex,
-        setUiLanguage,
-        setUiShellMode,
-        setAutonomousRunHealthByRunId,
-        setChatAgentVoiceMuted,
-        setChatAvatarSpeaking,
-        setChatAvatarVisible,
-        setChatInput,
-        setChatLastUsage,
-        setChatMode,
-        setCompanionMessageCutoffTs,
-        setOnboardingApiKey,
-        setOnboardingAvatar,
-        setOnboardingBlooioApiKey,
-        setOnboardingBlooioPhoneNumber,
-        setOnboardingServerTarget,
-        setOnboardingDetectedProviders,
-        setOnboardingDiscordToken,
-        setOnboardingElizaCloudTab,
-        setOnboardingExistingInstallDetected,
-        setOnboardingGithubToken,
-        setOnboardingLargeModel,
-        setOnboardingName,
-        setOnboardingOpenRouterModel,
-        setOnboardingOwnerName,
-        setOnboardingPrimaryModel,
-        setOnboardingProvider,
-        setOnboardingRemoteApiBase,
-        setOnboardingRemoteConnected,
-        setOnboardingRemoteConnecting,
-        setOnboardingRemoteError,
-        setOnboardingRemoteToken,
-        setOnboardingRpcKeys,
-        setOnboardingRpcSelections,
-        setOnboardingSelectedChains,
-        setOnboardingSmallModel,
-        setOnboardingStyle,
-        setOnboardingSubscriptionTab,
-        setOnboardingTelegramToken,
-        setOnboardingTwilioAccountSid,
-        setOnboardingTwilioAuthToken,
-        setOnboardingTwilioPhoneNumber,
-        setOnboardingWhatsAppSessionPath,
-        setOnboardingComplete,
-        setStartupError,
-        setFavoriteApps,
-        setTab,
-        setStoreUninstalling,
-        setStoreSubTab,
-        setCatalogSort,
-        setCatalogTotal,
-        setActiveOverlayApp,
-        setCatalogUninstalling,
-        setCloudDashboardView,
-        setCommandActiveIndex,
-        setCommandQuery,
-        setComputerUseEnabled,
-        setCustomBackgroundUrl,
-        setCustomCatchphrase,
-        setCustomVoicePresetId,
-        setCustomVrmPreviewUrl,
-        setCustomVrmUrl,
-        setCustomWorldUrl,
-        setDroppedFiles,
-        setElizaCloudEnabled,
-        setElizaCloudVoiceProxyAvailable,
-        setEmotePickerOpen,
-        setExportError,
-        setExportIncludeLogs,
-        setExportPassword,
-        setExportSuccess,
-        setGameOverlayEnabled,
-        setImportError,
-        setImportFile,
-        setImportPassword,
-        setImportSuccess,
-        setInventoryChainFilters,
-        setInventorySort,
-        setInventorySortDirection,
-        setInventoryView,
-        setLogLevelFilter,
-        setLogSourceFilter,
-        setLogTagFilter,
-        setMcpAction,
-        setMcpAddingResult,
-        setMcpAddingServer,
-        setMcpConfiguredServers,
-        setMcpEnvInputs,
-        setMcpHeaderInputs,
-        setMcpMarketplaceLoading,
-        setMcpMarketplaceQuery,
-        setMcpMarketplaceResults,
-        setMcpServerStatuses,
-        setOnboardingCloudApiKey,
-        setOnboardingFeatureBrowser,
-        setOnboardingFeatureComputerUse,
-        setOnboardingFeatureCrypto,
-        setOnboardingFeatureDiscord,
-        setOnboardingFeatureOAuthPending,
-        setOnboardingFeaturePhone,
-        setOnboardingFeatureTelegram,
-        setOnboardingVoiceApiKey,
-        setOnboardingVoiceProvider,
-        setPairingCodeInput,
-        setPluginAdvancedOpen,
-        setPluginFilter,
-        setPluginSearch,
-        setPluginSettingsOpen,
-        setPluginStatusFilter,
-        setShareIngestNotice,
-        setSkillCreateDescription,
-        setSkillCreateFormOpen,
-        setSkillCreateName,
-        setSkillReviewId,
-        setSkillReviewReport,
-        setSkillsMarketplaceManualGithubUrl,
-        setSkillsMarketplaceQuery,
-        setSkillsSubTab,
-        setStoreDetailPlugin,
-        setStoreError,
-        setStoreFilter,
-        setStoreInstalling,
-        setStoreLoading,
-        setStorePlugins,
-        setStoreSearch,
-        setCatalogTotalPages,
-        setWalletEnabled,
-        setCatalogSkills,
-        setCatalogSearch,
-        setCatalogPage,
-        setCatalogLoading,
-        setCatalogInstalling,
-        setBrowserEnabled,
-        setCatalogError,
-        setAppsSubTab,
-        setActiveInboxChat,
-        setCatalogDetailSkill,
-        setAppRuns,
-        setActivePackId,
-        setActiveGameRunId,
-        setActiveTerminalSessionId,
-        setAnalysisMode,
-        setRecentApps,
-        setConfigRaw,
-        setPluginsSubTab,
-        setDatabaseSubTab,
-        setConfigText,
-        setAgentSubTab,
-    ]);
+    // Ref-stable generic setter: the exposed `setState` callback never changes
+    // identity (deps `[]`), so it does not bust the AppContext value memo. The
+    // latest setter map is read through a ref on each call, so behavior is
+    // identical to a callback that closed over every setter directly.
+    const setStateImplRef = useRef(() => { });
+    setStateImplRef.current = (key, value) => {
+        {
+            const setterMap = {
+                tab: setTab,
+                setupStep: setSetupStep,
+                chatInput: setChatInput,
+                chatAvatarVisible: setChatAvatarVisible,
+                chatAgentVoiceMuted: setChatAgentVoiceMuted,
+                chatLastUsage: setChatLastUsage,
+                chatAvatarSpeaking: setChatAvatarSpeaking,
+                companionMessageCutoffTs: setCompanionMessageCutoffTs,
+                uiShellMode: setUiShellMode,
+                uiLanguage: setUiLanguage,
+                autonomousRunHealthByRunId: setAutonomousRunHealthByRunId,
+                startupError: setStartupError,
+                pairingCodeInput: setPairingCodeInput,
+                pluginFilter: setPluginFilter,
+                pluginStatusFilter: setPluginStatusFilter,
+                pluginSearch: setPluginSearch,
+                pluginSettingsOpen: setPluginSettingsOpen,
+                pluginAdvancedOpen: setPluginAdvancedOpen,
+                skillsSubTab: setSkillsSubTab,
+                skillCreateFormOpen: setSkillCreateFormOpen,
+                skillCreateName: setSkillCreateName,
+                skillCreateDescription: setSkillCreateDescription,
+                skillsMarketplaceQuery: setSkillsMarketplaceQuery,
+                skillsMarketplaceManualGithubUrl: setSkillsMarketplaceManualGithubUrl,
+                logTagFilter: setLogTagFilter,
+                logLevelFilter: setLogLevelFilter,
+                logSourceFilter: setLogSourceFilter,
+                browserEnabled: setBrowserEnabled,
+                computerUseEnabled: setComputerUseEnabled,
+                walletEnabled: setWalletEnabled,
+                inventoryView: setInventoryView,
+                inventorySort: setInventorySort,
+                inventorySortDirection: setInventorySortDirection,
+                inventoryChainFilters: setInventoryChainFilters,
+                exportPassword: setExportPassword,
+                exportIncludeLogs: setExportIncludeLogs,
+                exportError: setExportError,
+                exportSuccess: setExportSuccess,
+                importPassword: setImportPassword,
+                importFile: setImportFile,
+                importError: setImportError,
+                importSuccess: setImportSuccess,
+                firstRunName: setFirstRunName,
+                firstRunOwnerName: setFirstRunOwnerName,
+                firstRunStyle: setFirstRunStyle,
+                firstRunRuntimeTarget: setFirstRunRuntimeTarget,
+                firstRunCloudApiKey: setFirstRunCloudApiKey,
+                firstRunSmallModel: setFirstRunSmallModel,
+                firstRunLargeModel: setFirstRunLargeModel,
+                firstRunProvider: setFirstRunProvider,
+                firstRunApiKey: setFirstRunApiKey,
+                firstRunVoiceProvider: setFirstRunVoiceProvider,
+                firstRunVoiceApiKey: setFirstRunVoiceApiKey,
+                firstRunExistingInstallDetected: setFirstRunExistingInstallDetected,
+                firstRunDetectedProviders: setFirstRunDetectedProviders,
+                firstRunRemoteApiBase: setFirstRunRemoteApiBase,
+                firstRunRemoteToken: setFirstRunRemoteToken,
+                firstRunRemoteConnecting: setFirstRunRemoteConnecting,
+                firstRunRemoteError: setFirstRunRemoteError,
+                firstRunRemoteConnected: setFirstRunRemoteConnected,
+                firstRunSelectedChains: setFirstRunSelectedChains,
+                firstRunRpcSelections: setFirstRunRpcSelections,
+                firstRunOpenRouterModel: setFirstRunOpenRouterModel,
+                firstRunPrimaryModel: setFirstRunPrimaryModel,
+                firstRunTelegramToken: setFirstRunTelegramToken,
+                firstRunDiscordToken: setFirstRunDiscordToken,
+                firstRunWhatsAppSessionPath: setFirstRunWhatsAppSessionPath,
+                firstRunTwilioAccountSid: setFirstRunTwilioAccountSid,
+                firstRunTwilioAuthToken: setFirstRunTwilioAuthToken,
+                firstRunTwilioPhoneNumber: setFirstRunTwilioPhoneNumber,
+                firstRunBlooioApiKey: setFirstRunBlooioApiKey,
+                firstRunBlooioPhoneNumber: setFirstRunBlooioPhoneNumber,
+                firstRunGithubToken: setFirstRunGithubToken,
+                firstRunSubscriptionTab: setFirstRunSubscriptionTab,
+                firstRunElizaCloudTab: setFirstRunElizaCloudTab,
+                firstRunRpcKeys: setFirstRunRpcKeys,
+                setupAvatar: setSetupAvatar,
+                firstRunFeatureTelegram: setFirstRunFeatureTelegram,
+                firstRunFeatureDiscord: setFirstRunFeatureDiscord,
+                firstRunFeaturePhone: setFirstRunFeaturePhone,
+                firstRunFeatureCrypto: setFirstRunFeatureCrypto,
+                firstRunFeatureBrowser: setFirstRunFeatureBrowser,
+                firstRunFeatureComputerUse: setFirstRunFeatureComputerUse,
+                firstRunFeatureOAuthPending: setFirstRunFeatureOAuthPending,
+                elizaCloudEnabled: setElizaCloudEnabled,
+                elizaCloudVoiceProxyAvailable: setElizaCloudVoiceProxyAvailable,
+                cloudDashboardView: setCloudDashboardView,
+                selectedVrmIndex: setSelectedVrmIndex,
+                customVrmUrl: setCustomVrmUrl,
+                customVrmPreviewUrl: setCustomVrmPreviewUrl,
+                customBackgroundUrl: setCustomBackgroundUrl,
+                customCatchphrase: setCustomCatchphrase,
+                customVoicePresetId: setCustomVoicePresetId,
+                activePackId: setActivePackId,
+                customWorldUrl: setCustomWorldUrl,
+                commandQuery: setCommandQuery,
+                commandActiveIndex: setCommandActiveIndex,
+                emotePickerOpen: setEmotePickerOpen,
+                analysisMode: setAnalysisMode,
+                storeSearch: setStoreSearch,
+                storeFilter: setStoreFilter,
+                storeSubTab: setStoreSubTab,
+                catalogSearch: setCatalogSearch,
+                catalogSort: setCatalogSort,
+                catalogPage: setCatalogPage,
+                skillReviewId: setSkillReviewId,
+                skillReviewReport: setSkillReviewReport,
+                appRuns: setAppRuns,
+                activeGameRunId: setActiveGameRunId,
+                gameOverlayEnabled: setGameOverlayEnabled,
+                companionAppRunning: (v) => setActiveOverlayApp(v ? "@elizaos/plugin-companion" : null),
+                activeOverlayApp: setActiveOverlayApp,
+                activeInboxChat: setActiveInboxChat,
+                activeTerminalSessionId: setActiveTerminalSessionId,
+                storePlugins: setStorePlugins,
+                storeLoading: setStoreLoading,
+                storeInstalling: setStoreInstalling,
+                storeUninstalling: setStoreUninstalling,
+                storeError: setStoreError,
+                storeDetailPlugin: setStoreDetailPlugin,
+                catalogSkills: setCatalogSkills,
+                catalogTotal: setCatalogTotal,
+                catalogTotalPages: setCatalogTotalPages,
+                catalogLoading: setCatalogLoading,
+                catalogError: setCatalogError,
+                catalogDetailSkill: setCatalogDetailSkill,
+                catalogInstalling: setCatalogInstalling,
+                catalogUninstalling: setCatalogUninstalling,
+                mcpConfiguredServers: setMcpConfiguredServers,
+                mcpServerStatuses: setMcpServerStatuses,
+                mcpMarketplaceQuery: setMcpMarketplaceQuery,
+                mcpMarketplaceResults: setMcpMarketplaceResults,
+                mcpMarketplaceLoading: setMcpMarketplaceLoading,
+                mcpAction: setMcpAction,
+                mcpAddingServer: setMcpAddingServer,
+                mcpAddingResult: setMcpAddingResult,
+                mcpEnvInputs: setMcpEnvInputs,
+                mcpHeaderInputs: setMcpHeaderInputs,
+                droppedFiles: setDroppedFiles,
+                shareIngestNotice: setShareIngestNotice,
+                appsSubTab: setAppsSubTab,
+                agentSubTab: setAgentSubTab,
+                pluginsSubTab: setPluginsSubTab,
+                databaseSubTab: setDatabaseSubTab,
+                favoriteApps: setFavoriteApps,
+                recentApps: setRecentApps,
+                configRaw: setConfigRaw,
+                configText: setConfigText,
+                firstRunComplete: setFirstRunComplete,
+            };
+            const setter = setterMap[key];
+            if (setter)
+                setter(value);
+        }
+    };
+    const setState = useCallback((key, value) => setStateImplRef.current(key, value), []);
     const requestGreetingWhenRunningRef = useRef(requestGreetingWhenRunning);
     useEffect(() => {
         requestGreetingWhenRunningRef.current = requestGreetingWhenRunning;
@@ -730,6 +740,11 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
     // calls when no sessions are active.
     const hasPtySessionsRef = useRef(ptySessions.length > 0);
     hasPtySessionsRef.current = ptySessions.length > 0;
+    // Lets the startup coordinator's PTY hydration gate the orchestrator/coding-agent
+    // routes until the agent runtime is running, avoiding the 404/503 console burst
+    // during the post-(re)start window before those services finish starting.
+    const agentRunningRef = useRef(agentStatus?.state === "running");
+    agentRunningRef.current = agentStatus?.state === "running";
     // ── StartupCoordinator (sole startup authority) ──────────────────────
     // Called after all dependency hooks so every setter/callback is available.
     const startupCoordinator = useStartupCoordinator({
@@ -739,30 +754,30 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         setStartupPhase,
         setStartupError,
         setAuthRequired,
-        setOnboardingComplete,
-        setOnboardingLoading,
+        setFirstRunComplete,
+        setFirstRunLoading,
         setPendingRestart,
         setPendingRestartReasons,
         setSystemWarnings,
         showRestartBanner,
         setPairingEnabled,
         setPairingExpiresAt,
-        setOnboardingOptions,
-        setOnboardingExistingInstallDetected,
-        setOnboardingStep,
-        setOnboardingServerTarget,
-        setOnboardingCloudApiKey,
-        setOnboardingProvider,
-        setOnboardingVoiceProvider,
-        setOnboardingApiKey,
-        setOnboardingPrimaryModel,
-        setOnboardingOpenRouterModel,
-        setOnboardingRemoteConnected,
-        setOnboardingRemoteApiBase,
-        setOnboardingRemoteToken,
-        setOnboardingSmallModel,
-        setOnboardingLargeModel,
-        setOnboardingCloudProvisionedContainer,
+        setFirstRunOptions,
+        setFirstRunExistingInstallDetected,
+        setSetupStep,
+        setFirstRunRuntimeTarget,
+        setFirstRunCloudApiKey,
+        setFirstRunProvider,
+        setFirstRunVoiceProvider,
+        setFirstRunApiKey,
+        setFirstRunPrimaryModel,
+        setFirstRunOpenRouterModel,
+        setFirstRunRemoteConnected,
+        setFirstRunRemoteApiBase,
+        setFirstRunRemoteToken,
+        setFirstRunSmallModel,
+        setFirstRunLargeModel,
+        setFirstRunCloudProvisionedContainer,
         applyDetectedProviders,
         hydrateInitialConversationState,
         loadWorkbench,
@@ -776,7 +791,6 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         pollCloudCredits,
         fetchAutonomyReplay,
         appendAutonomousEvent,
-        notifyAssistantEvent,
         notifyHeartbeatEvent,
         setSelectedVrmIndex,
         setCustomVrmUrl,
@@ -784,26 +798,30 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         setWalletAddresses,
         setPtySessions,
         hasPtySessionsRef,
+        agentRunningRef,
         setTab,
         setTabRaw,
         setConversationMessages,
         setUnreadConversations,
         setConversations,
         requestGreetingWhenRunningRef,
-        onboardingCompletionCommittedRef,
+        firstRunCompletionCommittedRef,
         forceLocalBootstrapRef,
         initialTabSetRef,
         activeConversationIdRef,
         elizaCloudPollInterval,
         elizaCloudLoginPollTimer,
         uiLanguage,
-        onboardingMode,
+        firstRunMode,
     });
+    // useReducer dispatch is referentially stable across renders; bind it so
+    // callbacks (e.g. switchAgentProfile) depend on the stable dispatch rather
+    // than the whole coordinator handle (which is a fresh object each render).
+    const startupCoordinatorDispatch = startupCoordinator.dispatch;
     // Wire coordinator refs so callbacks defined before the coordinator can reach it
     coordinatorRetryRef.current = startupCoordinator.retry;
     coordinatorResetRef.current = startupCoordinator.reset;
-    coordinatorOnboardingCompleteRef.current =
-        startupCoordinator.onboardingComplete;
+    coordinatorFirstRunCompleteRef.current = startupCoordinator.firstRunComplete;
     // Memoize the coordinator handle so that unrelated re-renders (e.g. chatInput
     // keystrokes) don't produce a new object reference and bust the value useMemo below.
     // The coordinator's computed fields (legacyPhase, loading, terminal, target, phase)
@@ -817,6 +835,10 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         if (!profile)
             return;
         setActiveProfileId(profileId);
+        // Conversation ids are per-account, so saved drafts from the old
+        // profile would re-attach to whatever conversation happens to land
+        // on the same id after the switch. Wipe them.
+        clearAllChatDrafts();
         const server = createPersistedActiveServer({
             kind: profile.kind,
             apiBase: profile.apiBase,
@@ -824,6 +846,20 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
             label: profile.label,
         });
         savePersistedActiveServer(server);
+        // On mobile the boot-time reconcile (reconcileMobileRestoredActiveServer)
+        // CLEARS the active server whenever the persisted runtime mode disagrees
+        // with it (`mobileLocal && mode !== "local"` → null). So a profile switch
+        // only survives a reboot if we ALSO persist the matching runtime mode —
+        // otherwise switching to the on-device agent reverts to cloud next boot.
+        // The on-device agent is a `remote` profile whose apiBase is the local IPC
+        // base, so detect that and treat it as "local".
+        const frontendPlatform = getFrontendPlatform();
+        if (frontendPlatform === "android" || frontendPlatform === "ios") {
+            const runtimeTarget = server.kind === "local" || isMobileLocalAgentIpcBase(server.apiBase)
+                ? "local"
+                : activeServerKindToFirstRunRuntimeTarget(server.kind);
+            persistMobileRuntimeModeForServerTarget(runtimeTarget);
+        }
         if (profile.apiBase) {
             client.setBaseUrl(profile.apiBase);
         }
@@ -835,11 +871,11 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
             : profile.kind === "remote"
                 ? "remote-backend"
                 : "embedded-local";
-        startupCoordinator.dispatch({
+        startupCoordinatorDispatch({
             type: "SWITCH_AGENT",
             target: target,
         });
-    }, [startupCoordinator]);
+    }, [startupCoordinatorDispatch]);
     useAgentGreetingEffects({
         agentState: agentStatus?.state,
         loadWorkbench,
@@ -852,6 +888,27 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         greetingFiredRef,
         greetingInFlightConversationRef,
     });
+    // ── Capacitor app lifecycle (APP_RESUME / APP_PAUSE) ────────────────
+    // Bridges native lifecycle events into the chat pipeline: aborts
+    // in-flight streams before iOS suspends the process, persists the
+    // active conversation id, and re-probes /api/health on resume so the
+    // renderer notices a respawned FGS / dev server on a new port.
+    useAppLifecycleEvents({
+        activeConversationIdRef,
+        conversationMessagesRef,
+        chatAbortRef,
+        setConversationMessages,
+    });
+    // ── Chat composer draft persistence ────────────────────────────────
+    // Restores the textarea content when the user revisits a conversation
+    // (a common mobile pattern: open the app, start typing, switch apps,
+    // come back later). Drafts are scoped per conversation id and are
+    // cleared after a successful send or when the user switches accounts.
+    useChatComposerDraftPersistence({
+        activeConversationId,
+        chatInput,
+        setChatInput,
+    });
     // ── Context value ──────────────────────────────────────────────────
     // t is provided by TranslationContext (useTranslation() above)
     // Cloud auth-rejected effect is now inside useCloudState.
@@ -908,15 +965,15 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         uiShellMode,
         uiLanguage,
         uiTheme,
-        themeId,
+        uiThemeMode,
         companionVrmPowerMode,
         companionAnimateWhenHidden,
         companionHalfFramerateMode,
         connected,
         agentStatus,
-        onboardingComplete,
-        onboardingUiRevealNonce,
-        onboardingLoading,
+        firstRunComplete,
+        firstRunUiRevealNonce,
+        firstRunLoading,
         startupPhase,
         startupStatus,
         startupError,
@@ -943,7 +1000,6 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         chatLastUsage,
         chatAvatarVisible,
         chatAgentVoiceMuted,
-        chatMode,
         chatAvatarSpeaking,
         conversations,
         activeConversationId,
@@ -969,6 +1025,9 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         pluginAdvancedOpen,
         pluginSaving,
         pluginSaveSuccess,
+        isLoadingPlugins,
+        pluginsLoadError,
+        pluginsLoaded,
         skills,
         skillsSubTab,
         skillCreateFormOpen,
@@ -1058,6 +1117,7 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         cloudDashboardView,
         elizaCloudLoginBusy,
         elizaCloudLoginError,
+        elizaCloudLoginFallbackUrl,
         elizaCloudDisconnecting,
         activeAgentProfile: getActiveProfile(),
         updateStatus,
@@ -1100,55 +1160,55 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         importFile,
         importError,
         importSuccess,
-        onboardingStep,
-        onboardingMode,
-        onboardingActiveGuide,
-        onboardingDeferredTasks,
-        postOnboardingChecklistDismissed,
-        onboardingOptions,
-        onboardingName,
-        onboardingOwnerName,
-        onboardingStyle,
-        onboardingServerTarget,
-        onboardingCloudApiKey,
-        onboardingSmallModel,
-        onboardingLargeModel,
-        onboardingProvider,
-        onboardingApiKey,
-        onboardingVoiceProvider,
-        onboardingVoiceApiKey,
-        onboardingExistingInstallDetected,
-        onboardingDetectedProviders,
-        onboardingRemoteApiBase,
-        onboardingRemoteToken,
-        onboardingRemoteConnecting,
-        onboardingRemoteError,
-        onboardingRemoteConnected,
-        onboardingOpenRouterModel,
-        onboardingPrimaryModel,
-        onboardingTelegramToken,
-        onboardingDiscordToken,
-        onboardingWhatsAppSessionPath,
-        onboardingTwilioAccountSid,
-        onboardingTwilioAuthToken,
-        onboardingTwilioPhoneNumber,
-        onboardingBlooioApiKey,
-        onboardingBlooioPhoneNumber,
-        onboardingGithubToken,
-        onboardingSubscriptionTab,
-        onboardingElizaCloudTab,
-        onboardingSelectedChains,
-        onboardingRpcSelections,
-        onboardingRpcKeys,
-        onboardingAvatar,
-        onboardingFeatureTelegram,
-        onboardingFeatureDiscord,
-        onboardingFeaturePhone,
-        onboardingFeatureCrypto,
-        onboardingFeatureBrowser,
-        onboardingFeatureComputerUse,
-        onboardingFeatureOAuthPending,
-        onboardingCloudProvisionedContainer,
+        setupStep,
+        firstRunMode,
+        firstRunActiveGuide,
+        firstRunDeferredTasks,
+        postFirstRunChecklistDismissed,
+        firstRunOptions,
+        firstRunName,
+        firstRunOwnerName,
+        firstRunStyle,
+        firstRunRuntimeTarget,
+        firstRunCloudApiKey,
+        firstRunSmallModel,
+        firstRunLargeModel,
+        firstRunProvider,
+        firstRunApiKey,
+        firstRunVoiceProvider,
+        firstRunVoiceApiKey,
+        firstRunExistingInstallDetected,
+        firstRunDetectedProviders,
+        firstRunRemoteApiBase,
+        firstRunRemoteToken,
+        firstRunRemoteConnecting,
+        firstRunRemoteError,
+        firstRunRemoteConnected,
+        firstRunOpenRouterModel,
+        firstRunPrimaryModel,
+        firstRunTelegramToken,
+        firstRunDiscordToken,
+        firstRunWhatsAppSessionPath,
+        firstRunTwilioAccountSid,
+        firstRunTwilioAuthToken,
+        firstRunTwilioPhoneNumber,
+        firstRunBlooioApiKey,
+        firstRunBlooioPhoneNumber,
+        firstRunGithubToken,
+        firstRunSubscriptionTab,
+        firstRunElizaCloudTab,
+        firstRunSelectedChains,
+        firstRunRpcSelections,
+        firstRunRpcKeys,
+        setupAvatar,
+        firstRunFeatureTelegram,
+        firstRunFeatureDiscord,
+        firstRunFeaturePhone,
+        firstRunFeatureCrypto,
+        firstRunFeatureBrowser,
+        firstRunFeatureComputerUse,
+        firstRunFeatureOAuthPending,
+        firstRunCloudProvisionedContainer,
         commandPaletteOpen,
         commandQuery,
         commandActiveIndex,
@@ -1199,7 +1259,7 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         navigation,
         setUiLanguage,
         setUiTheme,
-        setThemeId,
+        setUiThemeMode,
         setCompanionVrmPowerMode,
         setCompanionAnimateWhenHidden,
         setCompanionHalfFramerateMode,
@@ -1218,6 +1278,9 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         restartBackend,
         systemWarnings,
         dismissSystemWarning,
+        actionBanner,
+        showActionBanner,
+        dismissActionBanner,
         handleChatSend,
         handleChatStop,
         handleChatRetry,
@@ -1294,22 +1357,17 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         handleCharacterArrayInput,
         handleCharacterStyleInput,
         handleCharacterMessageExamplesInput,
-        handleOnboardingNext,
-        handleOnboardingBack,
-        handleOnboardingJumpToStep,
-        goToOnboardingStep,
-        handleOnboardingRemoteConnect,
-        handleOnboardingUseLocalBackend,
-        completeOnboarding,
+        handleFirstRunNext,
+        handleFirstRunBack,
+        handleFirstRunJumpToStep,
+        goToFirstRunStep,
+        handleFirstRunRemoteConnect,
+        handleFirstRunUseLocalBackend,
+        completeFirstRun,
         handleCloudLogin,
         handleCloudDisconnect,
         switchAgentProfile,
-        handleCloudOnboardingFinish,
-        vincentConnected,
-        vincentLoginBusy,
-        vincentLoginError,
-        handleVincentLogin,
-        handleVincentDisconnect,
+        handleCloudFirstRunFinish,
         loadUpdateStatus,
         handleChannelChange,
         checkExtensionStatus,
@@ -1329,15 +1387,15 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         uiShellMode,
         uiLanguage,
         uiTheme,
-        themeId,
+        uiThemeMode,
         companionVrmPowerMode,
         companionAnimateWhenHidden,
         companionHalfFramerateMode,
         connected,
         agentStatus,
-        onboardingComplete,
-        onboardingUiRevealNonce,
-        onboardingLoading,
+        firstRunComplete,
+        firstRunUiRevealNonce,
+        firstRunLoading,
         startupPhase,
         startupStatus,
         startupError,
@@ -1360,7 +1418,6 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         chatLastUsage,
         chatAvatarVisible,
         chatAgentVoiceMuted,
-        chatMode,
         chatAvatarSpeaking,
         conversations,
         activeConversationId,
@@ -1386,6 +1443,9 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         pluginAdvancedOpen,
         pluginSaving,
         pluginSaveSuccess,
+        isLoadingPlugins,
+        pluginsLoadError,
+        pluginsLoaded,
         skills,
         skillsSubTab,
         skillCreateFormOpen,
@@ -1475,6 +1535,7 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         cloudDashboardView,
         elizaCloudLoginBusy,
         elizaCloudLoginError,
+        elizaCloudLoginFallbackUrl,
         elizaCloudDisconnecting,
         updateStatus,
         updateLoading,
@@ -1516,55 +1577,55 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         importFile,
         importError,
         importSuccess,
-        onboardingStep,
-        onboardingMode,
-        onboardingActiveGuide,
-        onboardingDeferredTasks,
-        postOnboardingChecklistDismissed,
-        onboardingOptions,
-        onboardingName,
-        onboardingOwnerName,
-        onboardingStyle,
-        onboardingServerTarget,
-        onboardingCloudApiKey,
-        onboardingSmallModel,
-        onboardingLargeModel,
-        onboardingProvider,
-        onboardingApiKey,
-        onboardingVoiceProvider,
-        onboardingVoiceApiKey,
-        onboardingExistingInstallDetected,
-        onboardingDetectedProviders,
-        onboardingRemoteApiBase,
-        onboardingRemoteToken,
-        onboardingRemoteConnecting,
-        onboardingRemoteError,
-        onboardingRemoteConnected,
-        onboardingOpenRouterModel,
-        onboardingPrimaryModel,
-        onboardingTelegramToken,
-        onboardingDiscordToken,
-        onboardingWhatsAppSessionPath,
-        onboardingTwilioAccountSid,
-        onboardingTwilioAuthToken,
-        onboardingTwilioPhoneNumber,
-        onboardingBlooioApiKey,
-        onboardingBlooioPhoneNumber,
-        onboardingGithubToken,
-        onboardingSubscriptionTab,
-        onboardingElizaCloudTab,
-        onboardingSelectedChains,
-        onboardingRpcSelections,
-        onboardingRpcKeys,
-        onboardingAvatar,
-        onboardingFeatureTelegram,
-        onboardingFeatureDiscord,
-        onboardingFeaturePhone,
-        onboardingFeatureCrypto,
-        onboardingFeatureBrowser,
-        onboardingFeatureComputerUse,
-        onboardingFeatureOAuthPending,
-        onboardingCloudProvisionedContainer,
+        setupStep,
+        firstRunMode,
+        firstRunActiveGuide,
+        firstRunDeferredTasks,
+        postFirstRunChecklistDismissed,
+        firstRunOptions,
+        firstRunName,
+        firstRunOwnerName,
+        firstRunStyle,
+        firstRunRuntimeTarget,
+        firstRunCloudApiKey,
+        firstRunSmallModel,
+        firstRunLargeModel,
+        firstRunProvider,
+        firstRunApiKey,
+        firstRunVoiceProvider,
+        firstRunVoiceApiKey,
+        firstRunExistingInstallDetected,
+        firstRunDetectedProviders,
+        firstRunRemoteApiBase,
+        firstRunRemoteToken,
+        firstRunRemoteConnecting,
+        firstRunRemoteError,
+        firstRunRemoteConnected,
+        firstRunOpenRouterModel,
+        firstRunPrimaryModel,
+        firstRunTelegramToken,
+        firstRunDiscordToken,
+        firstRunWhatsAppSessionPath,
+        firstRunTwilioAccountSid,
+        firstRunTwilioAuthToken,
+        firstRunTwilioPhoneNumber,
+        firstRunBlooioApiKey,
+        firstRunBlooioPhoneNumber,
+        firstRunGithubToken,
+        firstRunSubscriptionTab,
+        firstRunElizaCloudTab,
+        firstRunSelectedChains,
+        firstRunRpcSelections,
+        firstRunRpcKeys,
+        setupAvatar,
+        firstRunFeatureTelegram,
+        firstRunFeatureDiscord,
+        firstRunFeaturePhone,
+        firstRunFeatureCrypto,
+        firstRunFeatureBrowser,
+        firstRunFeatureComputerUse,
+        firstRunFeatureOAuthPending,
+        firstRunCloudProvisionedContainer,
         commandPaletteOpen,
         commandQuery,
         commandActiveIndex,
@@ -1605,6 +1666,7 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         configText,
         activeGamePostMessagePayload,
         systemWarnings,
+        actionBanner,
         setTab,
         setUiShellMode,
         switchUiShellMode,
@@ -1612,7 +1674,7 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         navigation,
         setUiLanguage,
         setUiTheme,
-        setThemeId,
+        setUiThemeMode,
         setCompanionVrmPowerMode,
         setCompanionAnimateWhenHidden,
         setCompanionHalfFramerateMode,
@@ -1630,6 +1692,8 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         retryBackendConnection,
         restartBackend,
         dismissSystemWarning,
+        showActionBanner,
+        dismissActionBanner,
         handleChatSend,
         handleChatStop,
         handleChatRetry,
@@ -1705,22 +1769,17 @@ function AppProviderInner({ children, branding: brandingOverride, }) {
         handleCharacterArrayInput,
         handleCharacterStyleInput,
         handleCharacterMessageExamplesInput,
-        handleOnboardingNext,
-        handleOnboardingBack,
-        handleOnboardingJumpToStep,
-        goToOnboardingStep,
-        handleOnboardingRemoteConnect,
-        handleOnboardingUseLocalBackend,
-        completeOnboarding,
+        handleFirstRunNext,
+        handleFirstRunBack,
+        handleFirstRunJumpToStep,
+        goToFirstRunStep,
+        handleFirstRunRemoteConnect,
+        handleFirstRunUseLocalBackend,
+        completeFirstRun,
         handleCloudLogin,
         handleCloudDisconnect,
         switchAgentProfile,
-        handleCloudOnboardingFinish,
-        vincentConnected,
-        vincentLoginBusy,
-        vincentLoginError,
-        handleVincentLogin,
-        handleVincentDisconnect,
+        handleCloudFirstRunFinish,
         loadUpdateStatus,
         handleChannelChange,
         checkExtensionStatus,