feat: add guided onboarding

docs/issues/guided-onboarding-first-chat-confirm/plan.md

@@ -0,0 +1,17 @@
+# Implementation Plan
+
+## Cause
+
+`NewThreadPage` handles the `first-chat` confirm action by querying the contenteditable element and calling `HTMLElement.focus()`. The chat input is backed by a TipTap editor, so the editor-aware focus path should be invoked through the component itself.
+
+## Change
+
+- Expose a `focusInput` method from `ChatInputBox` that focuses and scrolls the editor into view.
+- Use that exposed method from `NewThreadPage` when the guided `first-chat` confirm action runs.
+- Keep the existing DOM query as a fallback for older or stubbed component shapes.
+- Add a focused renderer test for the confirm action.
+
+## Validation
+
+- Run focused renderer tests for `NewThreadPage` onboarding and `ModelProviderSettings`.
+- Run the repository-required `pnpm run format`, `pnpm run i18n`, and `pnpm run lint` checks.

docs/issues/guided-onboarding-first-chat-confirm/spec.md

@@ -0,0 +1,21 @@
+# Guided Onboarding First Chat Confirm
+
+## Problem
+
+During the guided `first-chat` step, clicking the confirm action can appear to do nothing because the handler only focuses the raw contenteditable element instead of invoking the chat input's editor-aware focus path.
+
+## User Story
+
+As a user on the final onboarding step, I want the confirm action to move focus into the real chat editor so I can immediately start typing my first message.
+
+## Acceptance Criteria
+
+- When the guided `first-chat` overlay is visible, clicking the primary confirm action focuses the real chat input editor.
+- The guide remains active until the first successful message send completes the onboarding step.
+- A focused renderer test covers the confirm action calling the chat input focus path.
+
+## Non-goals
+
+- No change to onboarding completion semantics for the first-chat step.
+- No change to chat send behavior.
+- No change to the final guide copy.

docs/issues/guided-onboarding-first-chat-confirm/tasks.md

@@ -0,0 +1,7 @@
+# Tasks
+
+- [x] Add SDD artifacts.
+- [x] Expose an editor-aware chat input focus method.
+- [x] Route the `first-chat` confirm action through the exposed focus method.
+- [x] Add focused regression coverage for the confirm action.
+- [x] Run format, i18n, lint, and focused tests.

docs/issues/pr-1621-ai-review-fixes/plan.md

@@ -0,0 +1,15 @@
+# Implementation Plan
+
+## Change
+
+- Update shared onboarding step resolution fallback ordering.
+- Add guarded step selection when `startGuidedOnboarding` receives a terminal requested step.
+- Tighten renderer onboarding step finalization condition for nullish `currentStepId`.
+- Sync provider settings tab selection from onboarding step in one shared helper used by both watchers.
+- Add runtime response parsing in onboarding client using existing route schema.
+- Update onboarding locale strings for the reviewed non-English locale files.
+- Extend tests for onboarding route behavior and onboarding client response validation.
+
+## Validation
+
+- Run format, i18n, lint, and focused onboarding-related tests for touched modules.

docs/issues/pr-1621-ai-review-fixes/spec.md

@@ -0,0 +1,19 @@
+# PR #1621 AI Review Fixes
+
+## Problem
+
+AI review on PR #1621 reported onboarding flow edge cases and missing onboarding localization in several locale files. These issues can leave onboarding on an invalid step, hide the intended settings tab during onboarding, or show untranslated onboarding copy.
+
+## Acceptance Criteria
+
+- Resuming current onboarding step prefers an `in_progress` step before `pending` when `currentStepId` is empty.
+- Starting onboarding with a requested completed/skipped step falls back to the next pending step instead of pinning `currentStepId` to a terminal step.
+- Guided onboarding finalization treats both `null` and `undefined` `currentStepId` as no active step.
+- Provider settings tab selection remains aligned with onboarding steps during provider changes.
+- Onboarding renderer client validates bridge responses and throws clear errors when response shape is invalid.
+- Reviewed locale files in this scope no longer show English onboarding copy.
+
+## Non-goals
+
+- No unrelated onboarding UX redesign.
+- No broad localization rewrite beyond the reviewed onboarding strings.

docs/issues/pr-1621-ai-review-fixes/tasks.md

@@ -0,0 +1,8 @@
+# Tasks
+
+- [ ] Add SDD issue artifacts.
+- [ ] Fix onboarding logic edge cases (shared/main/renderer).
+- [ ] Harden onboarding client bridge response handling.
+- [ ] Update reviewed onboarding locale translations.
+- [ ] Add/update tests for new behavior.
+- [ ] Run validation commands.

docs/issues/prcheck-format-onboarding/plan.md

@@ -0,0 +1,16 @@
+# Plan
+
+## Diagnosis
+
+The local PR Check reproduction fails at `pnpm run format:check` for `src/main/routes/onboarding/onboardingRouteSupport.ts`.
+
+## Approach
+
+Run the repository formatter on the reported file, inspect the resulting diff, then rerun PR Check steps to confirm the failure is resolved.
+
+## Test Strategy
+
+- `pnpm run format:check`
+- `pnpm run i18n`
+- `pnpm run lint`
+- Continue to `pnpm run build` if earlier checks pass.

docs/issues/prcheck-format-onboarding/spec.md

@@ -0,0 +1,21 @@
+# PR Check Format Failure
+
+## User Story
+
+As a contributor, I want the PR Check workflow to pass for onboarding route changes so review is not blocked by formatting drift.
+
+## Acceptance Criteria
+
+- `pnpm run format:check` passes locally.
+- The workflow-equivalent checks continue past formatting without introducing behavior changes.
+- The fix does not alter guided onboarding state semantics.
+
+## Non-Goals
+
+- No onboarding UX or storage behavior changes.
+- No CI workflow changes unless the reproduced failure requires them.
+
+## Constraints
+
+- Keep the change minimal and compatible with existing formatter rules.
+- Preserve existing user work in the branch.

docs/issues/prcheck-format-onboarding/tasks.md

@@ -0,0 +1,6 @@
+# Tasks
+
+- [x] Reproduce the PR Check failure locally.
+- [x] Apply the minimal formatting fix.
+- [x] Rerun relevant PR Check commands.
+- [x] Summarize the result and any remaining risks.

src/main/events.ts

@@ -128,6 +128,10 @@ export const SETTINGS_EVENTS = {
   PROVIDER_INSTALL: 'settings:provider-install'
 }
 
+export const DEV_EVENTS = {
+  START_GUIDED_ONBOARDING: 'dev:start-guided-onboarding'
+}
+
 // ollama 相关事件
 export const OLLAMA_EVENTS = {
   PULL_MODEL_PROGRESS: 'ollama:pull-model-progress'

src/main/presenter/windowPresenter/index.ts

@@ -1389,6 +1389,25 @@ export class WindowPresenter implements IWindowPresenter {
     return null
   }
 
+  public focusMainWindow(): boolean {
+    if (this.mainWindowId == null) {
+      return false
+    }
+
+    const mainWindow = BrowserWindow.fromId(this.mainWindowId)
+    if (!mainWindow || mainWindow.isDestroyed() || mainWindow.webContents.isDestroyed()) {
+      return false
+    }
+
+    if (mainWindow.isMinimized()) {
+      mainWindow.restore()
+    }
+
+    mainWindow.show()
+    mainWindow.focus()
+    return true
+  }
+
   public setPendingSettingsProviderInstall(preview: ProviderInstallPreview): void {
     this.pendingSettingsProviderInstalls.push(this.clonePendingSettingsProviderInstall(preview))
   }

src/main/routes/index.ts

@@ -89,6 +89,11 @@ import {
   mcpSubmitSamplingDecisionRoute,
   mcpUpdateServerRoute,
   modelsGetProviderCatalogRoute,
+  onboardingCompleteRoute,
+  onboardingGetStateRoute,
+  onboardingResetRoute,
+  onboardingSetStepStatusRoute,
+  onboardingStartRoute,
   pluginsDisableRoute,
   pluginsEnableRoute,
   pluginsGetRoute,
@@ -216,6 +221,13 @@ import { ChatService } from './chat/chatService'
 import { dispatchConfigRoute } from './config/configRouteHandler'
 import { createPresenterHotPathPorts } from './hotPathPorts'
 import { dispatchModelRoute } from './models/modelRouteHandler'
+import {
+  completeGuidedOnboarding,
+  readGuidedOnboardingState,
+  resetGuidedOnboarding,
+  setGuidedOnboardingStepStatus,
+  startGuidedOnboarding
+} from './onboarding/onboardingRouteSupport'
 import { dispatchProviderRoute } from './providers/providerRouteHandler'
 import { createNodeScheduler } from './scheduler'
 import { ProviderService } from './providers/providerService'
@@ -1409,6 +1421,38 @@ export async function dispatchDeepchatRoute(
       return settingsActivityListRoute.output.parse({ activities })
     }
 
+    case onboardingGetStateRoute.name: {
+      onboardingGetStateRoute.input.parse(rawInput)
+      const state = readGuidedOnboardingState(runtime.configPresenter)
+      return onboardingGetStateRoute.output.parse({ state })
+    }
+
+    case onboardingStartRoute.name: {
+      const input = onboardingStartRoute.input.parse(rawInput)
+      const state = startGuidedOnboarding(runtime.configPresenter, input)
+      return onboardingStartRoute.output.parse({ state })
+    }
+
+    case onboardingSetStepStatusRoute.name: {
+      const input = onboardingSetStepStatusRoute.input.parse(rawInput)
+      const state = setGuidedOnboardingStepStatus(runtime.configPresenter, input)
+      return onboardingSetStepStatusRoute.output.parse({ state })
+    }
+
+    case onboardingCompleteRoute.name: {
+      const input = onboardingCompleteRoute.input.parse(rawInput)
+      const state = completeGuidedOnboarding(runtime.configPresenter, Date.now(), {
+        force: input.force
+      })
+      return onboardingCompleteRoute.output.parse({ state })
+    }
+
+    case onboardingResetRoute.name: {
+      onboardingResetRoute.input.parse(rawInput)
+      const state = resetGuidedOnboarding(runtime.configPresenter)
+      return onboardingResetRoute.output.parse({ state })
+    }
+
     case startupGetBootstrapRoute.name: {
       startupGetBootstrapRoute.input.parse(rawInput)
       const coordinator = (runtime as Partial<MainKernelRouteRuntime>).startupWorkloadCoordinator