Add new welcome screen

packages/types/src/global-settings.ts

@@ -241,6 +241,7 @@ export const globalSettingsSchema = z.object({
 	enterBehavior: z.enum(["send", "newline"]).optional(),
 	profileThresholds: z.record(z.string(), z.number()).optional(),
 	hasOpenedModeSelector: z.boolean().optional(),
+	hasCompletedOnboarding: z.boolean().optional(), // kilocode_change: Track if user has completed onboarding flow
 	lastModeExportPath: z.string().optional(),
 	lastModeImportPath: z.string().optional(),
 	appendSystemPrompt: z.string().optional(), // kilocode_change: Custom text to append to system prompt (CLI only)

packages/types/src/vscode-extension-host.ts

@@ -639,6 +639,7 @@ export type ExtensionState = Pick<
 	marketplaceInstalledMetadata?: { project: Record<string, any>; global: Record<string, any> }
 	profileThresholds: Record<string, number>
 	hasOpenedModeSelector: boolean
+	hasCompletedOnboarding?: boolean // kilocode_change: Track if user has completed onboarding flow
 	openRouterImageApiKey?: string
 	kiloCodeImageApiKey?: string
 	openRouterUseMiddleOutTransform?: boolean
@@ -843,6 +844,7 @@ export interface WebviewMessage {
 		| "searchFiles"
 		| "toggleApiConfigPin"
 		| "hasOpenedModeSelector"
+		| "hasCompletedOnboarding" // kilocode_change: Mark onboarding as completed
 		| "clearCloudAuthSkipModel"
 		| "cloudButtonClicked"
 		| "rooCloudSignIn"

src/core/webview/ClineProvider.ts

@@ -2521,6 +2521,7 @@ export class ClineProvider
 			profileThresholds: profileThresholds ?? {},
 			cloudApiUrl: getRooCodeApiUrl(),
 			hasOpenedModeSelector: this.getGlobalState("hasOpenedModeSelector") ?? false,
+			hasCompletedOnboarding: this.getGlobalState("hasCompletedOnboarding"), // kilocode_change: Track onboarding completion - undefined means new user
 			systemNotificationsEnabled: systemNotificationsEnabled ?? false, // kilocode_change
 			dismissedNotificationIds: dismissedNotificationIds ?? [], // kilocode_change
 			morphApiKey, // kilocode_change
@@ -2589,6 +2590,7 @@ export class ClineProvider
 			| "clineMessages"
 			| "renderContext"
 			| "hasOpenedModeSelector"
+			| "hasCompletedOnboarding" // kilocode_change
 			| "version"
 			| "shouldShowAnnouncement"
 			| "hasSystemPromptOverride"

src/core/webview/webviewMessageHandler.ts

@@ -1908,6 +1908,12 @@ export const webviewMessageHandler = async (
 			await updateGlobalState("hasOpenedModeSelector", message.bool ?? true)
 			await provider.postStateToWebview()
 			break
+		// kilocode_change start: Handle onboarding completion
+		case "hasCompletedOnboarding":
+			await updateGlobalState("hasCompletedOnboarding", message.bool ?? true)
+			await provider.postStateToWebview()
+			break
+		// kilocode_change end
 		// kilocode_change start
 		case "kiloCodeImageApiKey":
 			await provider.contextProxy.setValue("kiloCodeImageApiKey", message.text)

webview-ui/src/App.tsx

@@ -15,6 +15,7 @@ import ChatView, { ChatViewRef } from "./components/chat/ChatView"
 import HistoryView from "./components/history/HistoryView"
 import SettingsView, { SettingsViewRef } from "./components/settings/SettingsView"
 import WelcomeView from "./components/kilocode/welcome/WelcomeView" // kilocode_change
+import OnboardingView from "./components/kilocode/welcome/OnboardingView" // kilocode_change
 import ProfileView from "./components/kilocode/profile/ProfileView" // kilocode_change
 import McpView from "./components/mcp/McpView" // kilocode_change
 import AuthView from "./components/kilocode/auth/AuthView" // kilocode_change
@@ -94,6 +95,8 @@ const App = () => {
 		renderContext,
 		mdmCompliant,
 		apiConfiguration, // kilocode_change
+		hasCompletedOnboarding, // kilocode_change: Track onboarding state
+		taskHistoryFullLength, // kilocode_change: Used to detect existing users
 	} = useExtensionState()
 
 	// Create a persistent state manager
@@ -314,16 +317,59 @@ const App = () => {
 		}
 	}, [tab])
 
+	// kilocode_change start: Onboarding handlers
+	const handleSelectFreeModels = useCallback(() => {
+		// Mark onboarding as complete
+		vscode.postMessage({ type: "hasCompletedOnboarding", bool: true })
+		// The default profile is already set up with a free model, so just close welcome
+		// This will trigger a state update that sets showWelcome to false
+	}, [])
+
+	const handleSelectPremiumModels = useCallback(() => {
+		// Mark onboarding as complete
+		vscode.postMessage({ type: "hasCompletedOnboarding", bool: true })
+		// Navigate to auth view which will show the device code and handle the OAuth flow
+		// The AuthView auto-starts device auth on mount
+		switchTab("auth")
+		setAuthReturnTo("chat")
+	}, [switchTab])
+
+	const handleSelectBYOK = useCallback(() => {
+		// Mark onboarding as complete
+		vscode.postMessage({ type: "hasCompletedOnboarding", bool: true })
+		// Navigate to settings with providers section
+		switchTab("settings")
+		setCurrentSection("providers")
+	}, [switchTab])
+	// kilocode_change end
+
 	if (!didHydrateState) {
 		return null
 	}
 
+	// kilocode_change start: Show OnboardingView for new users who haven't completed onboarding
+	// Show onboarding only if:
+	// 1. hasCompletedOnboarding is not true (undefined or false)
+	// 2. AND user has no task history (meaning they're truly new, not an existing user upgrading)
+	//
+	// This ensures existing users who upgrade don't see the onboarding screen,
+	// while new users who have never used the extension will see it.
+	const isExistingUser = (taskHistoryFullLength ?? 0) > 0
+	const showOnboarding = hasCompletedOnboarding !== true && !isExistingUser
+
 	// Do not conditionally load ChatView, it's expensive and there's state we
 	// don't want to lose (user input, disableInput, askResponse promise, etc.)
 	// kilocode_change: no WelcomeViewProvider toggle
-	return showWelcome ? (
+	return showOnboarding ? (
+		<OnboardingView
+			onSelectFreeModels={handleSelectFreeModels}
+			onSelectPremiumModels={handleSelectPremiumModels}
+			onSelectBYOK={handleSelectBYOK}
+		/>
+	) : showWelcome ? (
 		<WelcomeView />
 	) : (
+		// kilocode_change end
 		<>
 			{/* kilocode_change start */}
 			<MemoryWarningBanner />

webview-ui/src/components/kilocode/welcome/OnboardingView.tsx

@@ -0,0 +1,63 @@
+// kilocode_change - new file
+import React from "react"
+import Logo from "../common/Logo"
+import { useAppTranslation } from "@/i18n/TranslationContext"
+
+interface OnboardingOptionProps {
+	title: string
+	description: string
+	onClick: () => void
+}
+
+const OnboardingOption: React.FC<OnboardingOptionProps> = ({ title, description, onClick }) => {
+	return (
+		<button
+			className="w-full p-5 rounded-lg border border-vscode-panel-border bg-vscode-editor-background hover:bg-vscode-list-hoverBackground cursor-pointer text-left transition-colors"
+			onClick={onClick}>
+			<h3 className="text-lg font-semibold text-vscode-foreground m-0 mb-2">{title}</h3>
+			<p className="text-sm text-vscode-descriptionForeground m-0">{description}</p>
+		</button>
+	)
+}
+
+interface OnboardingViewProps {
+	onSelectFreeModels: () => void
+	onSelectPremiumModels: () => void
+	onSelectBYOK: () => void
+}
+
+const OnboardingView: React.FC<OnboardingViewProps> = ({ onSelectFreeModels, onSelectPremiumModels, onSelectBYOK }) => {
+	const { t } = useAppTranslation()
+
+	return (
+		<div className="flex flex-col items-center justify-center min-h-screen p-6 bg-vscode-sideBar-background">
+			<Logo width={80} height={80} />
+
+			<h1 className="text-2xl font-bold text-vscode-foreground text-center mt-4 mb-10">
+				{t("kilocode:onboarding.title")}
+			</h1>
+
+			<div className="w-full max-w-md flex flex-col gap-4">
+				<OnboardingOption
+					title={t("kilocode:onboarding.freeModels.title")}
+					description={t("kilocode:onboarding.freeModels.description")}
+					onClick={onSelectFreeModels}
+				/>
+
+				<OnboardingOption
+					title={t("kilocode:onboarding.premiumModels.title")}
+					description={t("kilocode:onboarding.premiumModels.description")}
+					onClick={onSelectPremiumModels}
+				/>
+
+				<OnboardingOption
+					title={t("kilocode:onboarding.byok.title")}
+					description={t("kilocode:onboarding.byok.description")}
+					onClick={onSelectBYOK}
+				/>
+			</div>
+		</div>
+	)
+}
+
+export default OnboardingView

webview-ui/src/components/kilocode/welcome/__tests__/OnboardingView.spec.tsx

@@ -0,0 +1,118 @@
+// kilocode_change - new file
+// npx vitest src/components/kilocode/welcome/__tests__/OnboardingView.spec.tsx
+
+import { render, screen, fireEvent } from "@/utils/test-utils"
+import OnboardingView from "../OnboardingView"
+
+// Mock Logo component
+vi.mock("../../common/Logo", () => ({
+	default: () => <div data-testid="kilo-logo">Kilo Logo</div>,
+}))
+
+describe("OnboardingView", () => {
+	const mockOnSelectFreeModels = vi.fn()
+	const mockOnSelectPremiumModels = vi.fn()
+	const mockOnSelectBYOK = vi.fn()
+
+	beforeEach(() => {
+		vi.clearAllMocks()
+	})
+
+	it("renders the Kilo logo", () => {
+		render(
+			<OnboardingView
+				onSelectFreeModels={mockOnSelectFreeModels}
+				onSelectPremiumModels={mockOnSelectPremiumModels}
+				onSelectBYOK={mockOnSelectBYOK}
+			/>,
+		)
+
+		expect(screen.getByTestId("kilo-logo")).toBeInTheDocument()
+	})
+
+	it("renders the title", () => {
+		render(
+			<OnboardingView
+				onSelectFreeModels={mockOnSelectFreeModels}
+				onSelectPremiumModels={mockOnSelectPremiumModels}
+				onSelectBYOK={mockOnSelectBYOK}
+			/>,
+		)
+
+		// The translation key is returned as-is by the test-utils mock
+		expect(screen.getByText("kilocode:onboarding.title")).toBeInTheDocument()
+	})
+
+	it("renders all three options", () => {
+		render(
+			<OnboardingView
+				onSelectFreeModels={mockOnSelectFreeModels}
+				onSelectPremiumModels={mockOnSelectPremiumModels}
+				onSelectBYOK={mockOnSelectBYOK}
+			/>,
+		)
+
+		expect(screen.getByText("kilocode:onboarding.freeModels.title")).toBeInTheDocument()
+		expect(screen.getByText("kilocode:onboarding.freeModels.description")).toBeInTheDocument()
+
+		expect(screen.getByText("kilocode:onboarding.premiumModels.title")).toBeInTheDocument()
+		expect(screen.getByText("kilocode:onboarding.premiumModels.description")).toBeInTheDocument()
+
+		expect(screen.getByText("kilocode:onboarding.byok.title")).toBeInTheDocument()
+		expect(screen.getByText("kilocode:onboarding.byok.description")).toBeInTheDocument()
+	})
+
+	it("calls onSelectFreeModels when Free models option is clicked", () => {
+		render(
+			<OnboardingView
+				onSelectFreeModels={mockOnSelectFreeModels}
+				onSelectPremiumModels={mockOnSelectPremiumModels}
+				onSelectBYOK={mockOnSelectBYOK}
+			/>,
+		)
+
+		const freeModelsButton = screen.getByText("kilocode:onboarding.freeModels.title").closest("button")
+		expect(freeModelsButton).toBeInTheDocument()
+		fireEvent.click(freeModelsButton!)
+
+		expect(mockOnSelectFreeModels).toHaveBeenCalledTimes(1)
+		expect(mockOnSelectPremiumModels).not.toHaveBeenCalled()
+		expect(mockOnSelectBYOK).not.toHaveBeenCalled()
+	})
+
+	it("calls onSelectPremiumModels when Premium models option is clicked", () => {
+		render(
+			<OnboardingView
+				onSelectFreeModels={mockOnSelectFreeModels}
+				onSelectPremiumModels={mockOnSelectPremiumModels}
+				onSelectBYOK={mockOnSelectBYOK}
+			/>,
+		)
+
+		const premiumModelsButton = screen.getByText("kilocode:onboarding.premiumModels.title").closest("button")
+		expect(premiumModelsButton).toBeInTheDocument()
+		fireEvent.click(premiumModelsButton!)
+
+		expect(mockOnSelectPremiumModels).toHaveBeenCalledTimes(1)
+		expect(mockOnSelectFreeModels).not.toHaveBeenCalled()
+		expect(mockOnSelectBYOK).not.toHaveBeenCalled()
+	})
+
+	it("calls onSelectBYOK when BYOK option is clicked", () => {
+		render(
+			<OnboardingView
+				onSelectFreeModels={mockOnSelectFreeModels}
+				onSelectPremiumModels={mockOnSelectPremiumModels}
+				onSelectBYOK={mockOnSelectBYOK}
+			/>,
+		)
+
+		const byokButton = screen.getByText("kilocode:onboarding.byok.title").closest("button")
+		expect(byokButton).toBeInTheDocument()
+		fireEvent.click(byokButton!)
+
+		expect(mockOnSelectBYOK).toHaveBeenCalledTimes(1)
+		expect(mockOnSelectFreeModels).not.toHaveBeenCalled()
+		expect(mockOnSelectPremiumModels).not.toHaveBeenCalled()
+	})
+})

webview-ui/src/context/ExtensionStateContext.tsx

@@ -95,6 +95,8 @@ export interface ExtensionStateContextType extends ExtensionState {
 	mdmCompliant?: boolean
 	hasOpenedModeSelector: boolean // New property to track if user has opened mode selector
 	setHasOpenedModeSelector: (value: boolean) => void // Setter for the new property
+	hasCompletedOnboarding: boolean // kilocode_change: Track if user has completed onboarding flow
+	setHasCompletedOnboarding: (value: boolean) => void // kilocode_change
 	alwaysAllowFollowupQuestions: boolean // New property for follow-up questions auto-approve
 	setAlwaysAllowFollowupQuestions: (value: boolean) => void // Setter for the new property
 	followupAutoApproveTimeoutMs: number | undefined // Timeout in ms for auto-approving follow-up questions
@@ -292,6 +294,7 @@ export const ExtensionStateContextProvider: React.FC<{ children: React.ReactNode
 		customCondensingPrompt: "", // Default empty string for custom condensing prompt
 		yoloGatekeeperApiConfigId: "", // kilocode_change: Default empty string for gatekeeper API config ID
 		hasOpenedModeSelector: false, // Default to false (not opened yet)
+		hasCompletedOnboarding: false, // kilocode_change: Default to false (not completed yet)
 		autoApprovalEnabled: true,
 		customModes: [],
 		maxOpenTabsContext: 20,
@@ -708,6 +711,9 @@ export const ExtensionStateContextProvider: React.FC<{ children: React.ReactNode
 		enterBehavior: state.enterBehavior ?? "send",
 		setEnterBehavior: (value) => setState((prevState) => ({ ...prevState, enterBehavior: value })),
 		setHasOpenedModeSelector: (value) => setState((prevState) => ({ ...prevState, hasOpenedModeSelector: value })),
+		hasCompletedOnboarding: state.hasCompletedOnboarding ?? false, // kilocode_change
+		setHasCompletedOnboarding: (value) =>
+			setState((prevState) => ({ ...prevState, hasCompletedOnboarding: value })), // kilocode_change
 		setAutoCondenseContext: (value) => setState((prevState) => ({ ...prevState, autoCondenseContext: value })),
 		setAutoCondenseContextPercent: (value) =>
 			setState((prevState) => ({ ...prevState, autoCondenseContextPercent: value })),