feat(web): add versioned first-run welcome

.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
-2026-07-30-deepseek-onboarding-credential-setup.md: 3f75a0893623afc0908cb48f2b838321ed9dedd3
-2026-07-30-deepseek-onboarding-credential-setup.zh.md: 62f8f0b99f167b22051aaddf7331a043bd2ea812
+2026-07-30-deepseek-onboarding-credential-setup.md: 253800b7d94c80f1809c211ad0b3788b4ae4e07c
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: 2dd4de8185d0b6c8c33ad381a1b1aa358b07e872

.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md

@@ -12,11 +12,11 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 **One readiness projection owns both Models and onboarding facts.** `ui-models` keeps a single store that joins `llm.providers({})`, redacted `settings.describe({})`, and batched `credentials.describe({refs})`. The onboarding projection selects the `deepseek-official` configurable-provider entry, resolves its `settingsNs` and `settingsPath`, reads the effective `apiKeyEnv`, and evaluates the matching credential descriptor. A configured literal `apiKey` secret sidecar is also ready, so compatibility configuration does not trigger a false prompt; a configured process-environment credential is ready and remains read-only.
 
-**The settings shell contributes navigation state, not provider policy.** `ui-settings` declares a root-scoped `settings.onboarding` list slot and tells registrants whether the current surface is the empty Hero. Its private `openSection(id)` callback opens the settings panel on one registered section. `ui-models` registers the DeepSeek overlay through the same declaration-aware deferred-registration path as its Models section, so plugin load order does not become a contract.
+**The settings shell contributes ordering and navigation, not provider policy.** `ui-settings` declares a root-scoped `settings.onboarding` list slot and mounts one ordered step at a time while the current surface is the empty Hero. The active registrant receives `complete()` and a private `openSection(id)` callback; completion transfers ownership to the next entry. `ui-models` registers the DeepSeek step through the same declaration-aware deferred-registration path as its Models section, so plugin load order does not become a contract and independently contributed dialogs cannot stack. The product-wide welcome step that precedes it is owned separately by [the versioned welcome decision](2026-07-30-versioned-gui-welcome-onboarding.md).
 
 **The prompt routes to the one credential editor.** A mounted, active adapter with a resolved, writable, unconfigured reference presents one action that opens Settings on Models. The existing DeepSeek setup card there exclusively owns the password input, `credentials.set({ref, value})`, write failures, and post-write refresh; the onboarding overlay never holds or submits a secret. An unavailable settings or credential capability keeps its deployment diagnostic and routes to the same page, while an absent adapter remains skipped because navigation cannot mount a Cordis plugin.
 
-**Unavailable states stay honest.** An absent configurable-provider entry suppresses the prompt because navigation cannot repair the composition. A present provider whose settings or credential capability cannot be resolved renders an actionable deployment diagnostic; a failed initial join names the connection problem and leads to the Models retry surface. Configure later dismisses the overlay for the current mounted surface and writes no completion fact. Settings, credential, provider-topology, and connection invalidations all refresh the shared join, so an external credential update closes an open prompt without a reload.
+**Unavailable states stay honest.** An absent configurable-provider entry completes the step because navigation cannot repair the composition. A present provider whose settings or credential capability cannot be resolved renders an actionable deployment diagnostic; a failed initial join names the connection problem and leads to the Models retry surface. Configure later completes only this mounted coordinator pass and writes no completion fact. Settings, credential, provider-topology, and connection invalidations all refresh the shared join, so an external credential update completes an open step without a reload.
 
 ## Alternatives considered
 
@@ -30,4 +30,4 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 ## Consequences
 
-The first-run flow now leads to the shipped adapter's existing editor without restarting: a keyless browser test boots the real Web composition under an isolated harness home, follows the prompt to Models, stores a generated key through that page into the home's `.env`, verifies no key reaches DOM, ARIA, or browser console output, and confirms the running page reports configured. Pure readiness and React tests pin literal, file, process-environment, missing-provider, missing-capability, navigation, cancellation, and external-invalidation behavior. The flow deliberately inherits the configuration plane's documented base limitations rather than adding local secret storage, redaction, or settings replacement workarounds.
+The ordered flow leads from the product welcome step to the shipped adapter's existing editor without restarting: a keyless browser test boots the real Web composition under an isolated harness home, acknowledges the welcome notice, follows the DeepSeek step to Models, stores a generated key through that page into the home's `.env`, verifies no key reaches DOM, ARIA, or browser console output, and confirms the running page reports configured. Pure readiness and React tests pin literal, file, process-environment, missing-provider, missing-capability, navigation, cancellation, external-invalidation, and coordinator-transfer behavior. The flow deliberately inherits the configuration plane's documented base limitations rather than adding local secret storage, redaction, or settings replacement workarounds.

.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md

@@ -12,11 +12,11 @@ Status: implemented
 
 **Models 与首次使用引导共享同一个就绪状态投影。**`ui-models` 维护一个 store，把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取 `deepseek-official` 可配置提供方条目，解析其 `settingsNs` 与 `settingsPath`，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，也会判定为就绪，兼容配置因此不会误触发浮层；通过进程环境提供的凭据若已配置，同样判定为就绪并保持只读。
 
-**设置外壳只贡献导航状态，不持有提供方策略。**`ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并告知注册方当前界面是否为空白 Hero。其私有 `openSection(id)` 回调会打开设置面板并切换到一个已注册分区。`ui-models` 沿用 Models 分区所使用、感知 slot 声明的延迟注册路径来注册 DeepSeek 浮层，因此插件加载顺序不会成为契约。
+**设置外壳只贡献排序与导航，不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 沿用 Models 分区所使用、感知 slot 声明的延迟注册路径来注册 DeepSeek 步骤，因此插件加载顺序不会成为契约，独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
 
 **浮层只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用浮层绝不持有或提交 secret。设置或凭据能力不可用时会保留部署诊断，并提供前往同一页面的入口；适配器缺失时仍直接跳过，因为导航无法挂载 Cordis 插件。
 
-**不可用状态如实呈现。**可配置提供方条目缺失时不显示浮层，因为导航无法修复当前组合。提供方存在，但设置或凭据能力无法解析时，界面会显示可采取操作的部署诊断；初始联接失败时会明确指出连接问题，并引导前往 Models 的重试界面。「稍后配置」只会在当前已挂载界面中关闭浮层，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可关闭已打开的浮层。
+**不可用状态如实呈现。** 可配置提供方条目缺失时会完成当前步骤，因为导航无法修复当前组合。提供方存在，但设置或凭据能力无法解析时，界面会显示可采取操作的部署诊断；初始联接失败时会明确指出连接问题，并引导前往 Models 的重试界面。「稍后配置」只会完成协调器当前这一次挂载流程，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可完成已打开的步骤。
 
 ## 曾考虑的替代方案
 
@@ -30,4 +30,4 @@ Status: implemented
 
 ## 后果
 
-首次使用流程现在无需重启即可引导用户前往随产品提供的适配器已有的编辑器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，依照浮层操作前往 Models，通过该页面把生成的密钥存入该目录的 `.env`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的页面报告已配置。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、导航、取消和外部失效行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。
+有序流程从产品欢迎步骤开始，无需重启即可引导用户前往随产品提供的适配器已有的编辑器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，确认欢迎通知后依照 DeepSeek 步骤前往 Models，通过该页面把生成的密钥存入该目录的 `.env`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的页面报告已配置。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、导航、取消、外部失效和协调器移交行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。

.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md
+2026-07-30-versioned-gui-welcome-onboarding.md: 405c6fe833d995123cd15e5694cd5ef75a0cd03d
+2026-07-30-versioned-gui-welcome-onboarding.zh.md: ea83aa958866ab3dcca749f362d43e4b29408e02

.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md

@@ -0,0 +1,35 @@
+# Agent Note: Versioned GUI welcome onboarding
+
+Status: implemented
+
+English | [中文](2026-07-30-versioned-gui-welcome-onboarding.zh.md)
+
+## Problem
+
+The GUI's credential onboarding begins with a DeepSeek-specific readiness check, but the internal-test notice applies to every user and must precede provider setup even when a credential is already configured. Treating both as independent overlays permits simultaneous dialogs, while a process-local dismissal cannot distinguish a completed notice from a window closed before acknowledgement or intentionally present revised copy once.
+
+## Decision
+
+**The Settings shell coordinates ordered steps.** `settings.onboarding` remains a root-scoped list, but `ui-settings` projects its entry ids and order into one coordinator and mounts only the first incomplete step. The active registrant receives `complete()` and `openSection(id)`; no later step mounts until ownership transfers. The product welcome registers at order `-100`, while `ui-models` retains only the conditional DeepSeek readiness and credential-routing step at order `0`.
+
+**Ownerless product onboarding belongs to `ui-settings-general`.** `src/onboarding-copy.ts` is the single editable source for the complete Chinese notice, its faithful English counterpart, the Continue labels, and `WELCOME_NOTICE_VERSION`. Runtime locale dictionaries derive their welcome values from that file, and tests import the same owner instead of repeating paragraph text. The notice is browser UI only: it creates no Session event and contributes no model-visible content.
+
+**Acknowledgement is durable per Harness profile.** The Host half registers a `ui-onboarding` section in the user-settings seam, stored under the active `$DSH_HOME/settings.yaml`. The browser shows the notice unless `welcomeNoticeVersion` equals the owner constant exactly. Continue applies one path mutation with the current version and calls `complete()` only after the Host commits it; a failed write leaves the notice open, and closing the page or process writes nothing. Bumping the constant intentionally makes every profile acknowledge the revised copy once.
+
+**Concurrent views converge without stale replacement.** The acknowledgement write omits `expectedRevision` deliberately: every tab writes the same version to one path, so the operation is idempotent and preserves sibling fields instead of rebuilding the section. `settings/document-updated` becomes `host/settings-changed`; an already mounted tab refetches and advances when another tab or an external editor commits the current version. The API proxy exposes this one product namespace through a closed allowlist beside configurable-provider namespaces, without treating its changes as model-catalog invalidations.
+
+**The welcome modal has one completion path.** It renders no close icon or secondary action, installs no Escape handler, and assigns no click handler to the mask. Its mask starts below the 80 px top chrome and preserves `position:absolute`, zero left/right/bottom offsets, `rgba(0, 0, 0, 0.24)`, and `backdrop-filter: blur(2px)`. Continue is the sole button and receives initial focus.
+
+## Alternatives considered
+
+**Browser local storage** — rejected because acknowledgement would follow one browser profile rather than `$DSH_HOME`; a fresh Harness profile could incorrectly inherit a prior acknowledgement, and external profile edits would have no authoritative update stream.
+
+**A second independent modal in `ui-settings-general`** — rejected because list registrants would still stack whenever welcome and credential readiness were both true. Ordered ownership belongs to the shell that declares and renders the list.
+
+**Persisting on render or window close** — rejected because observation is not acknowledgement and close delivery is unreliable. Only the explicit Continue commit may suppress the next launch.
+
+**A generic public settings-exposure flag** — rejected because one product namespace does not justify widening every settings registrant's public configuration surface. The gateway keeps an explicit closed allowlist.
+
+## Consequences
+
+A fresh profile always sees the welcome notice before provider-specific onboarding; an already configured credential skips only the later DeepSeek step. Reloading after Continue stays past the acknowledged version, changing the owner version presents it again, and closing before Continue leaves the next launch unchanged. Focused store and React tests pin exact-version comparison, write failure, sole-action behavior, no-dismiss paths, coordinator ordering, conditional DeepSeek transfer, and HMR cleanup. The real Chromium scenario boots the shipped Web composition with an isolated harness home, verifies the exact mask geometry and computed styles, reloads before and after acknowledgement, continues into missing-credential setup, confirms an acknowledged-version mismatch returns while the credential is configured, and checks the browser console.

.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md

@@ -0,0 +1,35 @@
+# Agent Note: 版本化 GUI 欢迎引导
+
+Status: implemented
+
+[English](2026-07-30-versioned-gui-welcome-onboarding.md) | 中文
+
+## 问题
+
+GUI 的凭据引导从 DeepSeek 专用的就绪状态检查开始，但内部测试通知适用于每位用户，即使凭据已经配置，也必须先于提供方设置显示。若把两者作为独立浮层处理，多个对话框可能同时出现；仅存于进程内的关闭标记既无法区分通知已完成确认还是窗口在确认前已关闭，也无法在文案有意修订后重新显示一次通知。
+
+## 决策
+
+**设置外壳协调有序步骤。** `settings.onboarding` 仍是根作用域 list，但 `ui-settings` 会把其中各条目的 id 和顺序投影到一个协调器中，并且只挂载第一个未完成的步骤。当前注册方会收到 `complete()` 和 `openSection(id)`；所有权转移前，不会挂载后续步骤。产品欢迎步骤的顺序为 `-100`，`ui-models` 则只保留顺序为 `0` 的 DeepSeek 条件式就绪状态与凭据跳转步骤。
+
+**不属于单一功能的产品引导由 `ui-settings-general` 持有。** `src/onboarding-copy.ts` 是完整中文通知、忠实英文对侧文案、两种语言的「继续」按钮文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源。运行时 locale 字典从该文件派生欢迎文案，测试也导入同一个所有者，而不重复段落文本。该通知只存在于浏览器 UI：它不会创建会话事件，也不会贡献任何模型可见内容。
+
+**确认状态按 Harness profile 持久化。** 宿主端在 user-settings seam 中注册 `ui-onboarding` 分节，并存入当前 `$DSH_HOME/settings.yaml`。除非 `welcomeNoticeVersion` 与文案所有者文件中的常量精确相等，否则浏览器会显示通知。「继续」会以当前版本执行一次路径变更，并且仅在宿主端提交成功后调用 `complete()`；写入失败时通知保持打开，关闭页面或进程则不会写入任何内容。提升该常量会有意要求每个 profile 对修订后的文案重新确认一次。
+
+**并发视图无需陈旧的整体替换即可收敛。** 确认写入有意省略 `expectedRevision`：每个标签页都向同一路径写入相同版本，因此该操作是幂等的，并会保留同级字段，而不是重建整个分节。`settings/document-updated` 会转为 `host/settings-changed`；另一个标签页或外部编辑器提交当前版本后，已挂载的标签页会重新拉取状态并推进。API 网关在可配置提供方 namespace 之外，通过封闭的允许列表暴露这一个产品 namespace，同时不会把它的变更视为模型目录失效事件。
+
+**欢迎模态窗口只有一条完成路径。** 界面不渲染关闭图标或次要操作，不安装 Escape 处理器，也不为遮罩添加点击处理器。遮罩从顶部 80 px 的界面框架下方开始，并保留 `position:absolute`、left/right/bottom 偏移量为零、`rgba(0, 0, 0, 0.24)` 和 `backdrop-filter: blur(2px)`。「继续」是唯一按钮，并会获得初始焦点。
+
+## 曾考虑的替代方案
+
+**浏览器本地存储**：不予采用，因为确认状态会跟随某个浏览器 profile，而不是 `$DSH_HOME`；全新的 Harness profile 可能错误继承此前的确认状态，外部 profile 编辑也没有权威更新流。
+
+**在 `ui-settings-general` 中再增加一个独立模态窗口**：不予采用，因为欢迎通知和凭据就绪状态同时为真时，list 注册方仍会堆叠。声明并渲染该 list 的外壳应当持有有序所有权。
+
+**在渲染或窗口关闭时持久化**：不予采用，因为看见通知不等于确认，窗口关闭事件也无法可靠送达。只有显式提交「继续」才能阻止通知在下次启动时再次显示。
+
+**通用的公开设置暴露标志**：不予采用，因为一个产品 namespace 不足以证明应当扩大每个 settings 注册方的公开配置面。网关保留显式的封闭允许列表。
+
+## 后果
+
+全新 profile 始终会在提供方专用引导之前看到欢迎通知；凭据已经配置时，只会跳过后续 DeepSeek 步骤。点击「继续」后重新加载不会再次显示已确认版本，更改文案所有者文件中的版本值会让通知重新出现，而确认前关闭窗口不会改变下次启动。针对性的 store 与 React 测试固化了精确版本比较、写入失败、单一操作、不可关闭路径、协调器顺序、按条件移交 DeepSeek 步骤和 HMR（热模块替换）清理行为。真实 Chromium 场景会使用隔离的 harness 家目录启动随产品提供的 Web 组合，验证遮罩的精确几何尺寸和计算样式，在确认前后分别重新加载，继续进入凭据缺失设置流程，确认凭据已配置时确认版本不匹配仍会使通知重新出现，并检查浏览器控制台。

apps/web/tests/onboarding-deepseek-config.e2e.ts

@@ -9,12 +9,18 @@ import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import {
-  assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
+  acknowledgeReloadConnectionLoss, assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
   launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
 import { saveFailureShot } from './support.ts'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import {
+  WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_COPY, WELCOME_NOTICE_SETTINGS_NAMESPACE,
+  WELCOME_NOTICE_VERSION,
+} from '@deepseek-ai/dsh-client-ui-settings-general'
 
 const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/onboarding-deepseek-config', import.meta.url))
+const WELCOME_EXPECTED = join(SNAPSHOT_DIR, 'welcome.expected.md')
 const MISSING_EXPECTED = join(SNAPSHOT_DIR, 'missing.expected.md')
 const MODE = webSnapshotMode()
 
@@ -42,6 +48,47 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
 
   it('stores a key write-only and observes configured state without restarting', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-onboarding-deepseek-config'))
+    const welcome = page.getByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.paragraphs[0] })
+    await welcome.waitFor({ timeout: 15_000 })
+    const welcomeAria = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(WELCOME_EXPECTED, welcomeAria, MODE)
+    expect(await welcome.getByRole('button').allTextContents()).toEqual([WELCOME_NOTICE_COPY.zh.continueLabel])
+    expect(await welcome.locator('button').count()).toBe(1)
+
+    const maskStyles = await welcome.locator('xpath=..').locator(':scope > div').first().evaluate((mask) => {
+      const style = getComputedStyle(mask)
+      const rect = mask.getBoundingClientRect()
+      return {
+        position: style.position,
+        left: style.left,
+        right: style.right,
+        top: style.top,
+        bottom: style.bottom,
+        background: style.backgroundColor,
+        backdropFilter: style.backdropFilter,
+        rect: { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom },
+      }
+    })
+    expect(maskStyles).toEqual({
+      position: 'absolute',
+      left: '0px',
+      right: '0px',
+      top: '80px',
+      bottom: '0px',
+      background: 'rgba(0, 0, 0, 0.24)',
+      backdropFilter: 'blur(2px)',
+      rect: { left: 0, top: 80, right: 1440, bottom: 960 },
+    })
+
+    // Closing the process/page before acknowledgement writes nothing, so the
+    // same durable profile presents the notice again after reload.
+    const firstReloadWarnings = tripwire.warnings.length
+    await page.reload({ waitUntil: 'load' })
+    acknowledgeReloadConnectionLoss(tripwire, firstReloadWarnings)
+    await welcome.waitFor({ timeout: 15_000 })
+
+    await welcome.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel }).click()
+    await welcome.waitFor({ state: 'detached', timeout: 15_000 })
     const dialog = page.getByRole('dialog', { name: '添加一个 API Key 开始使用' })
     await dialog.waitFor({ timeout: 15_000 })
     expect(await dialog.getByRole('textbox').count()).toBe(0)
@@ -78,6 +125,29 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
       { timeout: 10_000 },
     ).toBe('已配置——输入新值可替换')
 
+    const acknowledgedSettings = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
+    expect(acknowledgedSettings).toContain(`${WELCOME_NOTICE_ACK_FIELD}: ${WELCOME_NOTICE_VERSION}`)
+
+    const secondReloadWarnings = tripwire.warnings.length
+    await page.reload({ waitUntil: 'load' })
+    acknowledgeReloadConnectionLoss(tripwire, secondReloadWarnings)
+    await page.waitForSelector('[class*="frame"]', { timeout: 15_000 })
+    expect(await page.getByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.paragraphs[0] }).count()).toBe(0)
+    expect(await page.getByRole('dialog', { name: '添加一个 API Key 开始使用' }).count()).toBe(0)
+
+    // A different stored copy version represents an intentional version bump:
+    // the welcome step returns even though the credential is already ready.
+    await scaffold.ctx.settings.mutate(settingsNamespace(WELCOME_NOTICE_SETTINGS_NAMESPACE), [{
+      op: 'set', path: [WELCOME_NOTICE_ACK_FIELD], value: 'previous-copy-version',
+    }])
+    const thirdReloadWarnings = tripwire.warnings.length
+    await page.reload({ waitUntil: 'load' })
+    acknowledgeReloadConnectionLoss(tripwire, thirdReloadWarnings)
+    await welcome.waitFor({ timeout: 15_000 })
+    await welcome.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel }).click()
+    await welcome.waitFor({ state: 'detached', timeout: 15_000 })
+    expect(await page.getByRole('dialog', { name: '添加一个 API Key 开始使用' }).count()).toBe(0)
+
     expect((await page.content()).includes(secret)).toBe(false)
     expect((await page.locator('body').ariaSnapshot()).includes(secret)).toBe(false)
     expect(browserConsole.some(line => line.includes(secret))).toBe(false)
@@ -86,6 +156,6 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
   }, 60_000)
 
   it('keeps the fixture inventory closed', async () => {
-    await assertFixtureInventory(SNAPSHOT_DIR, ['missing.expected.md'])
+    await assertFixtureInventory(SNAPSHOT_DIR, ['missing.expected.md', 'welcome.expected.md'])
   })
 })

apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md

@@ -0,0 +1,6 @@
+- dialog "感谢您愿意拨冗试用 DeepSeek Harness。":
+  - heading "感谢您愿意拨冗试用 DeepSeek Harness。" [level=2]
+  - paragraph: 目前的版本仍处于内部测试阶段，有些功能仍待完善，有些体验难免粗粝。
+  - paragraph: “如切如磋，如琢如磨。” 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中暴露的问题，也可能促使我们重新审视，甚至推翻已有的设计。
+  - paragraph: 我们尤其希望听见那些失败、困惑与不顺手的时刻——如果它未能帮到您，甚至反而为工作平添了麻烦，请在企业微信群中留言，将使用感受告诉我们。每一条反馈，都会帮助我们把它打磨得更好。
+  - button "继续"

docs/event-producer-consumer.md

@@ -66,14 +66,14 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | Event string | Dispatchers | Listeners |
 | --- | --- | --- |
 | `commands/changed` | `runtime` (`emit`) | `ui-command` |
-| `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models` |
+| `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-settings-general` |
 | `credentials/changed` | `runtime` (`emit`) | `ui-models` |
 | `internal/dispatch` | - | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
 | `internal/plugin` | - | `hmr`, `loader`, `modules`, `webserver` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
 | `locale/change` | `locale` (`emit`) | `locale`, `ui-models`, `ui-settings-general` |
 | `models/changed` | `runtime` (`emit`) | `ui-models` |
-| `settings/changed` | `runtime` (`emit`) | `ui-models` |
+| `settings/changed` | `runtime` (`emit`) | `ui-models`, `ui-settings-general` |
 | `slash/input-begin-command` | - | `ui-conversation` |
 | `slash/input-consume-token` | - | `ui-conversation` |
 | `slash/input-insert-reference` | - | `ui-conversation` |

docs/module-graph.md

@@ -367,11 +367,13 @@ flowchart TD
   pkg_client_ui_models --> pkg_invariants
   pkg_client_ui_question --> pkg_client_locale
   pkg_client_ui_question --> pkg_invariants
+  pkg_client_ui_settings_general --> pkg_client_connection
   pkg_client_ui_settings_general --> pkg_client_locale
   pkg_client_ui_settings_general --> pkg_client_runtime
   pkg_client_ui_settings_general --> pkg_client_ui_primitives
   pkg_client_ui_settings_general --> pkg_client_ui_settings
   pkg_client_ui_settings_general --> pkg_client_ui_slots
+  pkg_client_ui_settings_general --> pkg_client_web_react
   pkg_client_ui_settings_general --> pkg_invariants
   pkg_client_ui_sidebar --> pkg_client_locale
   pkg_client_ui_sidebar --> pkg_client_runtime
@@ -1067,7 +1069,7 @@ flowchart TD
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`client-ui-models`](../packages/client/ui-models) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |
-| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |

packages/client/connection/src/index.ts

@@ -54,6 +54,7 @@ const PRIVILEGED_METHODS = new Set([
   'settings.describe',
   'settings.update',
   'settings.replace',
+  'settings.mutate',
   'credentials.describe',
   'credentials.set',
   'credentials.unset',

packages/client/connection/tests/node-half.spec.ts

@@ -107,7 +107,7 @@ describe('connection node half', () => {
     // passed), but each privileged method stays loopback-only and 403s.
     for (const method of [
       'host.pickDirectory', 'host.openPath',
-      'settings.describe', 'settings.update', 'settings.replace',
+      'settings.describe', 'settings.update', 'settings.replace', 'settings.mutate',
       'credentials.describe', 'credentials.set', 'credentials.unset',
     ]) {
       const denied = fakeResponse()
@@ -191,7 +191,7 @@ describe('connection node half over a real HTTP server', () => {
       // Reads are as privileged as writes: describe returns the exposed
       // configuration, and credentials.describe probes arbitrary env-var names.
       for (const method of [
-        'settings.describe', 'settings.update', 'settings.replace',
+        'settings.describe', 'settings.update', 'settings.replace', 'settings.mutate',
         'credentials.describe', 'credentials.set', 'credentials.unset',
         'host.pickDirectory', 'host.openPath',
       ]) {

packages/client/ui-models/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-models/README.md
-README.md: aac437a13f6465196fcf1f8908b1d9ea2ccef401
-README.zh.md: 468537ac217a46395f2ec78174efa1f5d75a679d
+README.md: 2f53024df95a79862d5461d3514987a6e8257f9d
+README.zh.md: 7c95709933fa29a8fd6ed773696e9657d959f753

packages/client/ui-models/README.md

@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-Models settings plugin: the provider configuration page and official-DeepSeek first-run routing overlay. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time.
+Models settings plugin: the provider configuration page and official-DeepSeek conditional onboarding step. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time.
 
 Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), plus `reasoningEffort` (deepseek) or `reasoning` (pi-ai); every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base).
 
-The first-run overlay projects `deepseek-official` readiness from that same joined snapshot. A configured literal `apiKey` secret sidecar or configured credential reference suppresses the prompt, including a read-only launch-environment credential. A mounted adapter with a missing writable reference shows one action that opens Settings on the Models section, whose existing setup card exclusively owns key input and `credentials.set`; the overlay never holds a secret. An absent adapter is skipped because browser navigation cannot mount Cordis plugins, while an unusable settings or credential capability produces a deployment diagnostic with the same route to Models.
+The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding steps complete. A configured literal `apiKey` secret sidecar or configured credential reference completes the step without rendering, including a read-only launch-environment credential. A mounted adapter with a missing writable reference shows one action that opens Settings on the Models section, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter is skipped because browser navigation cannot mount Cordis plugins, while an unusable settings or credential capability produces a deployment diagnostic with the same route to Models.
 
 Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
 

packages/client/ui-models/README.zh.md

@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-模型设置插件：提供方配置页和 DeepSeek 官方首次使用跳转浮层。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片。
+模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片。
 
 行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），另加 `reasoningEffort`（deepseek）或 `reasoning`（pi-ai）；其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base）。
 
-首次使用浮层从同一个联接快照得出 `deepseek-official` 的就绪状态。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，浮层就不再显示，其中包括来自启动环境且只读的凭据。适配器已挂载、引用可写但尚未配置时，浮层只显示一个操作按钮，用于打开「设置」的 Models 分区；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，浮层绝不持有 secret。适配器缺失时直接跳过，因为浏览器导航无法挂载 Cordis 插件；设置或凭据能力不可用时则显示部署诊断，并提供同一个前往 Models 的入口。
+前序首次使用引导步骤完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。适配器已挂载、引用可写但尚未配置时，该步骤只显示一个操作按钮，用于打开「设置」的 Models 分区；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失时直接跳过，因为浏览器导航无法挂载 Cordis 插件；设置或凭据能力不可用时则显示部署诊断，并提供同一个前往 Models 的入口。
 
 每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除整行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
 

packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx

@@ -4,7 +4,7 @@
  * routes the user to that page's single credential editor.
  */
 
-import { useEffect, useState } from 'react'
+import { useEffect } from 'react'
 import type { ReactNode } from 'react'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import { Button, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -64,26 +64,23 @@ function unavailableDiagnostic(
  * @returns the controlled modal or null when onboarding needs no intervention.
  */
 export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps): ReactNode {
-  const { active, openSection, controller, useSnapshot, t } = props
+  const { complete, openSection, controller, useSnapshot, t } = props
   const state = useSnapshot(snapshot => snapshot)
   const readiness = deepSeekReadiness(state)
-  const [dismissed, setDismissed] = useState(false)
 
   useEffect(() => {
-    if (active && !dismissed && state.status === 'idle') void controller.load()
-  }, [active, controller, dismissed, state.status])
+    if (state.status === 'idle') void controller.load()
+  }, [controller, state.status])
 
-  const close = (): void => {
-    setDismissed(true)
-  }
+  useEffect(() => {
+    if (readiness.kind === 'adapter-absent' || readiness.kind === 'configured') complete()
+  }, [complete, readiness.kind])
 
   const openModels = (): void => {
-    close()
+    complete()
     openSection('models')
   }
 
-  if (!active || dismissed) return null
-
   let unavailableReason: UnavailableReason | undefined
   switch (readiness.kind) {
     case 'loading':
@@ -108,7 +105,7 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
   return (
     <Modal
       open
-      onClose={close}
+      onClose={complete}
       title={unavailable ? t('onboardingUnavailableTitle') : t('onboardingTitle')}
       closeLabel={t('onboardingLater')}
       {...(unavailable ? {} : { description: t('onboardingDescription') })}

packages/client/ui-models/tests/onboarding-dialog.spec.tsx

@@ -92,9 +92,11 @@ function harness(options: {
   }
   const controller = new ModelsSettingsStore(face as never)
   const openSection = vi.fn()
+  const complete = vi.fn()
   const unusedHook = (() => { throw new Error('unused standard hook') }) as never
   const props: DeepSeekOnboardingDialogProps = {
-    active: true,
+    stepId: 'deepseek-official',
+    complete,
     openSection,
     useSessions: unusedHook,
     useWorkspaces: unusedHook,
@@ -102,7 +104,7 @@ function harness(options: {
     useSnapshot: bindSnapshotSelector(controller.store),
     t: key => en[key],
   }
-  return { controller, openSection, props, configure: () => { fileConfigured = true } }
+  return { controller, complete, openSection, props, configure: () => { fileConfigured = true } }
 }
 
 describe('DeepSeekOnboardingDialog', () => {
@@ -122,8 +124,8 @@ describe('DeepSeekOnboardingDialog', () => {
     render(<DeepSeekOnboardingDialog {...h.props} />)
     await screen.findByRole('dialog')
     fireEvent.click(screen.getByRole('button', { name: en.onboardingGoToSettings }))
+    expect(h.complete).toHaveBeenCalledOnce()
     expect(h.openSection).toHaveBeenCalledWith('models')
-    expect(screen.queryByRole('dialog', { name: en.onboardingTitle })).toBeNull()
   })
 
   it('allows configure-later dismissal without opening settings', async () => {
@@ -131,7 +133,7 @@ describe('DeepSeekOnboardingDialog', () => {
     render(<DeepSeekOnboardingDialog {...h.props} />)
     await screen.findByRole('dialog')
     fireEvent.click(screen.getByRole('button', { name: en.onboardingLater }))
-    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(h.complete).toHaveBeenCalledOnce()
     expect(h.openSection).not.toHaveBeenCalled()
   })
 
@@ -187,6 +189,7 @@ describe('DeepSeekOnboardingDialog', () => {
       const view = render(<DeepSeekOnboardingDialog {...h.props} />)
       await act(async () => { await h.controller.load() })
       expect(screen.queryByRole('dialog')).toBeNull()
+      await waitFor(() => { expect(h.complete).toHaveBeenCalledOnce() })
       view.unmount()
     }
   })
@@ -198,14 +201,6 @@ describe('DeepSeekOnboardingDialog', () => {
     h.configure()
     await act(async () => { await h.controller.load() })
     await waitFor(() => { expect(screen.queryByRole('dialog')).toBeNull() })
-  })
-
-  it('stays hidden while the onboarding owner is inactive', async () => {
-    const h = harness()
-    const view = render(<DeepSeekOnboardingDialog {...h.props} active={false} />)
-    await act(async () => { await h.controller.load() })
-    expect(screen.queryByRole('dialog')).toBeNull()
-    view.rerender(<DeepSeekOnboardingDialog {...h.props} active />)
-    expect(await screen.findByRole('dialog', { name: en.onboardingTitle })).toBeTruthy()
+    expect(h.complete).toHaveBeenCalledOnce()
   })
 })

packages/client/ui-settings-general/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-README.md: c392d745021c0fc6a752cf71dd0506a435106c50
-README.zh.md: 83ab81e01eae435a74b50fa363a4de203c483002
+#   pnpm run verify-translation-pairing --write packages/client/ui-settings-general/README.md
+README.md: 3ae3f58bd00172ed9b547c01a354023c224f6a1c
+README.zh.md: ffdaf0e4314daa947a4183e2b23b7b1650de7611

packages/client/ui-settings-general/README.md

@@ -2,7 +2,9 @@
 
 English | [中文](README.zh.md)
 
-Settings ownerless-copy plugin: registers everything on the Settings surface that belongs to no single feature — the shell's trigger/header/close chrome content, the General section (Permission/Tool Call skeleton rows + the `settings.general.item` slot declaration), and the `settings` dictionaries. Feature-owned rows (Language, Appearance) and sections (Models) stay with their feature packages.
+Settings ownerless-copy and product-onboarding plugin: registers everything on the Settings surface that belongs to no single feature — the shell's trigger/header/close chrome content, the General section (Permission/Tool Call skeleton rows + the `settings.general.item` slot declaration), the `settings` dictionaries, and the first ordered welcome step. Feature-owned rows (Language, Appearance), sections (Models), and conditional onboarding steps stay with their feature packages.
+
+`src/onboarding-copy.ts` is the single editable owner of the complete Chinese and English notice plus `WELCOME_NOTICE_VERSION`. The Host half registers `ui-onboarding` in the user-settings seam; the browser compares `welcomeNoticeVersion` for exact equality and writes the current value only after Continue succeeds. The path mutation is idempotent across tabs and preserves sibling settings, while `host/settings-changed` makes an externally acknowledged notice advance without a reload. A different version deliberately presents the notice again. The welcome UI has no close, Escape, mask-click, or secondary path, and none of its copy or acknowledgement enters a Session log or model request.
 
 ## Model Experience
 

packages/client/ui-settings-general/README.zh.md

@@ -2,7 +2,9 @@
 
 [English](README.md) | 中文
 
-设置界面文案插件：在设置界面注册所有不属于单一功能的内容，包括外壳的触发器、标题栏与关闭控件内容，「通用」分区（「权限」／「工具调用」骨架行和 `settings.general.item` slot 声明），以及 `settings` 字典。归具体功能所有的行（「语言」、「外观」）和分区（「模型」）仍由各自的功能包提供。
+设置界面无特定功能归属的文案与产品引导插件：在设置界面注册所有不属于单一功能的内容，包括外壳的触发器、标题栏与关闭控件内容，「通用」分区（「权限」／「工具调用」骨架行和 `settings.general.item` slot 声明）、`settings` 字典，以及第一个有序欢迎步骤。归具体功能所有的行（「语言」、「外观」）、分区（「模型」）和条件式首次使用引导步骤仍由各自的功能包提供。
+
+`src/onboarding-copy.ts` 是完整中英文通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源。宿主端在 user-settings seam 中注册 `ui-onboarding`；浏览器比较 `welcomeNoticeVersion` 是否精确相等，仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等，并会保留同级设置；`host/settings-changed` 则让页面在通知被外部确认后，无需重新加载即可推进。版本不同时，系统会有意重新显示通知。欢迎界面没有关闭操作、Escape、点击遮罩或次要操作路径，其文案和确认状态均不会进入会话日志或模型请求。
 
 ## 模型体验
 

packages/client/ui-settings-general/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-settings-general",
-  "description": "Settings ownerless-copy plugin: the General section (skeleton rows + item slot), the shell trigger/header chrome content, and the settings dictionaries",
+  "description": "Settings ownerless-copy and product onboarding plugin: General, shell chrome, dictionaries, and the versioned welcome notice",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -26,7 +26,8 @@
     "inject": [
       "@deepseek-ai/dsh-client-runtime",
       "@deepseek-ai/dsh-client-ui-settings",
-      "@deepseek-ai/dsh-client-locale"
+      "@deepseek-ai/dsh-client-locale",
+      "@deepseek-ai/dsh-client-connection"
     ],
     "platform": "web"
   },
@@ -35,22 +36,30 @@
     "watch": "tsdown --watch"
   },
   "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-settings": "workspace:^",
+    "schemastery": "^3.18.0"
+  },
   "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
     "@deepseek-ai/dsh-client-locale": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-settings": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-client-web-react": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7",
     "react": "^18.2.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",
     "cordis": "^4.0.0-rc.7",

packages/client/ui-settings-general/src/client/WelcomeNotice.module.css

@@ -0,0 +1,70 @@
+.overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1100;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding-top: 80px;
+  box-sizing: border-box;
+}
+
+/* Mask */
+.mask {
+  position: absolute;
+  left: 0px;
+  right: 0px;
+  top: 80px;
+  bottom: 0px;
+  background: rgba(0, 0, 0, 0.24);
+  /* Mask-blur */
+  backdrop-filter: blur(2px);
+}
+
+.dialog {
+  position: relative;
+  z-index: 1;
+  width: min(640px, calc(100vw - 48px));
+  max-height: calc(100vh - 128px);
+  padding: 32px;
+  box-sizing: border-box;
+  overflow-y: auto;
+  border-radius: 24px;
+  background: var(--dsw-alias-bg-layer-2);
+  box-shadow: var(--dsw-shadow-lv3);
+  color: var(--dsw-alias-label-primary);
+}
+
+.title {
+  margin: 0;
+  font-size: 20px;
+  line-height: 30px;
+  font-weight: 600;
+}
+
+.copy {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  margin-top: 18px;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.copy p,
+.error {
+  margin: 0;
+}
+
+.error {
+  margin-top: 14px;
+  font-size: 13px;
+  line-height: 20px;
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.primary {
+  width: 100%;
+  margin-top: 24px;
+}

packages/client/ui-settings-general/src/client/WelcomeNotice.tsx

@@ -0,0 +1,69 @@
+/** Product-wide, versioned first-run welcome step. */
+
+import { useCallback, useEffect, useRef } from 'react'
+import type { ReactNode } from 'react'
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import type { WelcomeNoticeState, WelcomeNoticeStore } from './welcome-store.ts'
+import css from './WelcomeNotice.module.css'
+
+/** Registrant-owned dependencies of {@link WelcomeNotice}. */
+export interface WelcomeNoticeInjected {
+  controller: WelcomeNoticeStore
+  useSnapshot: SnapshotSelectorHook<WelcomeNoticeState>
+  t: (key: string) => string
+}
+
+/** Coordinator owner props plus the welcome step's injected face. */
+export type WelcomeNoticeProps = PropsRuntime<'settings.onboarding'> & WelcomeNoticeInjected
+
+/** Render the mandatory notice until its current version commits durably. */
+export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode {
+  const { complete, controller, useSnapshot, t } = props
+  const state = useSnapshot(snapshot => snapshot)
+  const finished = useRef(false)
+  const finish = useCallback((): void => {
+    if (finished.current) return
+    finished.current = true
+    complete()
+  }, [complete])
+
+  useEffect(() => {
+    if (state.status === 'idle') void controller.load()
+  }, [controller, state.status])
+
+  useEffect(() => {
+    if (state.acknowledged) finish()
+  }, [finish, state.acknowledged])
+
+  if (state.status === 'idle' || state.status === 'loading' || state.acknowledged) return null
+
+  const acknowledge = async (): Promise<void> => {
+    if (await controller.acknowledge()) finish()
+  }
+
+  return (
+    <div className={css.overlay} role="presentation">
+      <div className={css.mask} aria-hidden="true" />
+      <section className={css.dialog} role="dialog" aria-modal="true" aria-labelledby="welcome-notice-title">
+        <h2 id="welcome-notice-title" className={css.title}>{t('welcome.paragraph.0')}</h2>
+        <div className={css.copy}>
+          <p>{t('welcome.paragraph.1')}</p>
+          <p>{t('welcome.paragraph.2')}</p>
+          <p>{t('welcome.paragraph.3')}</p>
+        </div>
+        {state.error === null ? null : <p className={css.error} role="alert">{t('welcome.error')}</p>}
+        <Button
+          variant="primary"
+          className={css.primary}
+          autoFocus
+          disabled={state.status === 'saving'}
+          onClick={() => { void acknowledge() }}
+        >
+          {t('welcome.continue')}
+        </Button>
+      </section>
+    </div>
+  )
+}

packages/client/ui-settings-general/src/client/index.ts

@@ -8,13 +8,19 @@
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 // Type-only: pulls the shell's SlotMap merges (trigger/header/section/item).
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import type { ChromeInjected } from './chrome.tsx'
 import { CloseLabel, HeaderContent, TriggerContent } from './chrome.tsx'
 import type { GeneralSectionInjected } from './GeneralSection.tsx'
 import { GeneralSection } from './GeneralSection.tsx'
+import type { WelcomeNoticeInjected } from './WelcomeNotice.tsx'
+import { WelcomeNotice } from './WelcomeNotice.tsx'
+import { refreshWelcomeIfLoaded, WelcomeNoticeStore } from './welcome-store.ts'
 import { en, zh } from './locales.ts'
+import { WELCOME_NOTICE_SETTINGS_NAMESPACE } from '../onboarding-copy.ts'
 
 export type {
   ChromeInjected, CloseLabelProps, HeaderContentProps, TriggerContentProps,
@@ -22,6 +28,8 @@ export type {
 export type {
   GeneralSectionComponentProps, GeneralSectionInjected,
 } from './GeneralSection.tsx'
+export type { WelcomeNoticeInjected, WelcomeNoticeProps } from './WelcomeNotice.tsx'
+export type { WelcomeNoticeState } from './welcome-store.ts'
 
 /** Dictionary namespace owned by this plugin (shell chrome + General copy). */
 const NS = 'settings'
@@ -31,7 +39,7 @@ const NS = 'settings'
  * ui-settings' apply, whose activation order relative to this one is NOT
  * constrained; registration goes through declaration-aware deferral.
  */
-export const inject = ['slots', 'locale']
+export const inject = ['slots', 'locale', 'connection']
 
 /**
  * Register the `settings` dictionaries, the chrome content, and the General
@@ -48,8 +56,28 @@ export function apply(ctx: ClientContext): void {
   }, 'ui-settings-general: dictionaries')
 
   const t = ctx.locale.bind(NS)
+  const connection = ctx.get('connection') as ConnectionHandle
+  const welcomeController = new WelcomeNoticeStore(connection.api)
+  const useWelcomeSnapshot = bindSnapshotSelector(welcomeController.store)
   const chromeInjected = (): ChromeInjected => ({ t })
   const generalInjected = (): GeneralSectionInjected => ({ t })
+  const welcomeInjected = (): WelcomeNoticeInjected => ({
+    controller: welcomeController,
+    useSnapshot: useWelcomeSnapshot,
+    t,
+  })
+
+  ctx.effect(() => {
+    const refresh = (ns?: string): void => {
+      if (ns !== undefined && ns !== WELCOME_NOTICE_SETTINGS_NAMESPACE) return
+      refreshWelcomeIfLoaded(welcomeController)
+    }
+    const disposers = [
+      ctx.on('settings/changed', refresh),
+      ctx.on('connection/reset', () => { refresh() }),
+    ]
+    return () => { for (const dispose of disposers) dispose() }
+  }, 'ui-settings-general: welcome invalidations')
 
   // All four seats refresh on locale change: re-registration bumps each
   // slot's ledger version, which re-renders the outlets through their own
@@ -70,11 +98,19 @@ export function apply(ctx: ClientContext): void {
         children: { 'settings.general.item': { kind: 'list', scope: 'root' } },
         inject: generalInjected,
       }, GeneralSection))
+    const welcome = deferRegistration(ctx.slots, 'settings.onboarding', WelcomeNotice, () =>
+      ctx.slots.register({
+        name: 'settings.onboarding',
+        id: 'welcome-notice',
+        order: -100,
+        inject: welcomeInjected,
+      }, WelcomeNotice))
     const offLocale = ctx.on('locale/change', () => {
       trigger.refresh()
       header.refresh()
       close.refresh()
       general.refresh()
+      welcome.refresh()
     })
     return () => {
       offLocale()
@@ -82,6 +118,7 @@ export function apply(ctx: ClientContext): void {
       header.dispose()
       close.dispose()
       general.dispose()
+      welcome.dispose()
     }
-  }, 'ui-settings-general: chrome and section registrations')
+  }, 'ui-settings-general: chrome, section, and onboarding registrations')
 }

packages/client/ui-settings-general/src/client/locales.ts

@@ -6,6 +6,7 @@
  * (Language, Appearance) ship their copy in their own packages.
  */
 import type { LocaleDict } from '@deepseek-ai/dsh-client-locale/client'
+import { WELCOME_NOTICE_COPY } from '../onboarding-copy.ts'
 
 const SHARED = {
   'permission.value': 'Read only',
@@ -25,6 +26,12 @@ export const zh: LocaleDict = {
   'permission.title': '权限',
   'permission.desc': '选择默认权限模式',
   'toolcall.title': '工具调用',
+  'welcome.paragraph.0': WELCOME_NOTICE_COPY.zh.paragraphs[0],
+  'welcome.paragraph.1': WELCOME_NOTICE_COPY.zh.paragraphs[1],
+  'welcome.paragraph.2': WELCOME_NOTICE_COPY.zh.paragraphs[2],
+  'welcome.paragraph.3': WELCOME_NOTICE_COPY.zh.paragraphs[3],
+  'welcome.continue': WELCOME_NOTICE_COPY.zh.continueLabel,
+  'welcome.error': '暂时无法保存确认状态，请重试。',
 }
 
 /** English dictionary. */
@@ -37,4 +44,10 @@ export const en: LocaleDict = {
   'permission.title': 'Permission',
   'permission.desc': 'Choose default permission mode',
   'toolcall.title': 'Tool Call',
+  'welcome.paragraph.0': WELCOME_NOTICE_COPY.en.paragraphs[0],
+  'welcome.paragraph.1': WELCOME_NOTICE_COPY.en.paragraphs[1],
+  'welcome.paragraph.2': WELCOME_NOTICE_COPY.en.paragraphs[2],
+  'welcome.paragraph.3': WELCOME_NOTICE_COPY.en.paragraphs[3],
+  'welcome.continue': WELCOME_NOTICE_COPY.en.continueLabel,
+  'welcome.error': 'The acknowledgement could not be saved. Please try again.',
 }

packages/client/ui-settings-general/src/client/welcome-store.ts

@@ -0,0 +1,108 @@
+/** Durable welcome-notice state over the Host settings document. */
+
+import type { IApiClient, SettingsNamespaceView } from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE, WELCOME_NOTICE_VERSION,
+} from '../onboarding-copy.ts'
+
+/** State rendered by the welcome step. */
+export interface WelcomeNoticeState {
+  status: 'idle' | 'loading' | 'ready' | 'saving' | 'error'
+  acknowledged: boolean
+  error: string | null
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function acknowledgementOf(view: SettingsNamespaceView): string | undefined {
+  if (typeof view.value !== 'object' || view.value === null) return undefined
+  const value = (view.value as Record<string, unknown>)[WELCOME_NOTICE_ACK_FIELD]
+  return typeof value === 'string' ? value : undefined
+}
+
+/** Coordinates welcome acknowledgement reads and the sole durable write. */
+export class WelcomeNoticeStore {
+  /** uSES-safe state source shared by the registered welcome step. */
+  readonly store: SnapshotStore<WelcomeNoticeState> = createSnapshotStore({
+    status: 'idle', acknowledged: false, error: null,
+  })
+
+  private generation = 0
+
+  /** @param api - settings wire face used for durable reads and writes. */
+  constructor(private readonly api: Pick<IApiClient, 'settings'>) {}
+
+  /** Load the current acknowledgement from the Host settings document. */
+  async load(): Promise<void> {
+    const generation = ++this.generation
+    this.store.update((state) => { state.status = 'loading'; state.error = null })
+    try {
+      const response = await this.api.settings.describe({})
+      if (!response.result.ok) throw new Error(response.result.error.message)
+      const view = response.result.value.namespaces.find(
+        candidate => candidate.ns === WELCOME_NOTICE_SETTINGS_NAMESPACE,
+      )
+      if (view === undefined) throw new Error('welcome acknowledgement settings are unavailable')
+      if (generation !== this.generation) return
+      this.store.update((state) => {
+        state.status = 'ready'
+        state.acknowledged = acknowledgementOf(view) === WELCOME_NOTICE_VERSION
+        state.error = null
+      })
+    } catch (error) {
+      if (generation !== this.generation) return
+      this.store.update((state) => {
+        state.status = 'error'
+        state.acknowledged = false
+        state.error = messageOf(error)
+      })
+    }
+  }
+
+  /**
+   * Persist this copy version. The path mutation is idempotent across tabs and
+   * preserves every sibling setting; failure leaves the step unacknowledged.
+   * @returns true only when the Host committed the acknowledgement.
+   */
+  async acknowledge(): Promise<boolean> {
+    const generation = ++this.generation
+    this.store.update((state) => { state.status = 'saving'; state.error = null })
+    try {
+      const response = await this.api.settings.mutate({
+        ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
+        ops: [{ op: 'set', path: [WELCOME_NOTICE_ACK_FIELD], value: WELCOME_NOTICE_VERSION }],
+      })
+      if (!response.result.ok) throw new Error(response.result.error.message)
+      if (generation === this.generation) {
+        this.store.update((state) => {
+          state.status = 'ready'
+          state.acknowledged = true
+          state.error = null
+        })
+      }
+      return true
+    } catch (error) {
+      if (generation === this.generation) {
+        this.store.update((state) => {
+          state.status = 'error'
+          state.acknowledged = false
+          state.error = messageOf(error)
+        })
+      }
+      return false
+    }
+  }
+}
+
+/**
+ * Refresh only after the welcome step has begun reading durable state.
+ * @param controller - welcome state owner whose current status decides whether to load.
+ */
+export function refreshWelcomeIfLoaded(controller: WelcomeNoticeStore): void {
+  if (controller.store.getSnapshot().status === 'idle') return
+  void controller.load()
+}

packages/client/ui-settings-general/src/index.ts

@@ -1,4 +1,31 @@
 /** Host loader entry for the browser implementation exported from `./client`. */
 
-/** Host plugin body — no host-side behavior for the general settings plugin. */
-export function apply(): void {}
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import {
+  WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE,
+} from './onboarding-copy.ts'
+
+export {
+  WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_COPY, WELCOME_NOTICE_SETTINGS_NAMESPACE,
+  WELCOME_NOTICE_VERSION,
+} from './onboarding-copy.ts'
+
+interface OnboardingSettings {
+  welcomeNoticeVersion?: string
+}
+
+const OnboardingSettingsSchema: z<OnboardingSettings> = z.object({
+  [WELCOME_NOTICE_ACK_FIELD]: z.string(),
+})
+
+/** Register the durable GUI-onboarding section when a settings provider exists. */
+export function apply(ctx: Context): void {
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.register(
+      settingsNamespace(WELCOME_NOTICE_SETTINGS_NAMESPACE),
+      OnboardingSettingsSchema,
+    )
+  })
+}

packages/client/ui-settings-general/src/invariant.ts

@@ -15,10 +15,9 @@ export const name = 'client-ui-settings-general-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: a copy-owning registrant contributing chrome content
- * and the General section into shell-declared slots — it emits no cordis
- * events and owns no cross-plugin mutable relation; slot conflicts already
- * fail loud in the slot core at load time.
+ * No runtime invariant: the settings seam validates and publishes the durable
+ * welcome section, while slot conflicts fail loud in the slot core; this
+ * package owns no additional event/data relationship between those systems.
  */
 const install: InvariantInstaller = () => {}
 

packages/client/ui-settings-general/src/onboarding-copy.ts

@@ -0,0 +1,33 @@
+/** Durable settings namespace for product-wide GUI onboarding facts. */
+export const WELCOME_NOTICE_SETTINGS_NAMESPACE = 'ui-onboarding'
+
+/** Field storing the last welcome notice version the user acknowledged. */
+export const WELCOME_NOTICE_ACK_FIELD = 'welcomeNoticeVersion'
+
+/**
+ * Bump only when the notice changes materially and every user should see it
+ * again. The acknowledgement is compared for exact equality.
+ */
+export const WELCOME_NOTICE_VERSION = '2026-07-30.1'
+
+/** The complete editable welcome notice in both supported GUI locales. */
+export const WELCOME_NOTICE_COPY = {
+  zh: {
+    paragraphs: [
+      '感谢您愿意拨冗试用 DeepSeek Harness。',
+      '目前的版本仍处于内部测试阶段，有些功能仍待完善，有些体验难免粗粝。',
+      '“如切如磋，如琢如磨。” 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中暴露的问题，也可能促使我们重新审视，甚至推翻已有的设计。',
+      '我们尤其希望听见那些失败、困惑与不顺手的时刻——如果它未能帮到您，甚至反而为工作平添了麻烦，请在企业微信群中留言，将使用感受告诉我们。每一条反馈，都会帮助我们把它打磨得更好。',
+    ],
+    continueLabel: '继续',
+  },
+  en: {
+    paragraphs: [
+      'Thank you for taking the time to try DeepSeek Harness.',
+      'This version is still in internal testing. Some features remain unfinished, and parts of the experience may feel rough.',
+      '“As one cuts and files, as one chisels and polishes.” A product grows through real encounters and candid feedback. Problems you uncover in real use may prompt us to reconsider—or even overturn—our existing designs.',
+      'We especially want to hear about failures, confusion, and friction. If it did not help you, or even made your work harder, please leave a message in the company WeChat group and tell us about your experience. Every piece of feedback helps us refine it.',
+    ],
+    continueLabel: 'Continue',
+  },
+} as const

packages/client/ui-settings-general/tests/apply.spec.ts

@@ -1,12 +1,15 @@
 /** Ownerless-copy registrations: the four seats, the dictionaries, locale refresh, and HMR recovery. */
 import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-settings-general/client'
 import type { GeneralSectionInjected } from '@deepseek-ai/dsh-client-ui-settings-general/client'
 import { CloseLabel, HeaderContent, TriggerContent } from '../src/client/chrome.tsx'
 import { GeneralSection } from '../src/client/GeneralSection.tsx'
+import { WelcomeNotice } from '../src/client/WelcomeNotice.tsx'
+import type { WelcomeNoticeInjected } from '../src/client/WelcomeNotice.tsx'
+import { WELCOME_NOTICE_SETTINGS_NAMESPACE } from '../src/onboarding-copy.ts'
 
 /** The four seats this plugin fills (slot name → expected component). */
 const SEATS = [
@@ -14,6 +17,7 @@ const SEATS = [
   ['settings.header', HeaderContent],
   ['settings.close', CloseLabel],
   ['settings.section', GeneralSection],
+  ['settings.onboarding', WelcomeNotice],
 ] as const
 
 async function bench() {
@@ -21,7 +25,25 @@ async function bench() {
   await ctx.plugin(SlotsService).await()
   const locale = new LocaleService(ctx)
   ctx.provide('locale', locale)
-  return { ctx, slots: ctx.get('slots') as SlotsService, locale }
+  const settingsDescribe = vi.fn(() => Promise.resolve({
+    rpcId: 'settings-general' as never,
+    result: {
+      ok: true as const,
+      value: {
+        writable: true,
+        namespaces: [{
+          ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
+          schema: {},
+          value: {},
+          applies: 'live' as const,
+          secrets: [],
+          revision: 0,
+        }],
+      },
+    },
+  }))
+  ctx.provide('connection', { api: { settings: { describe: settingsDescribe } } } as never)
+  return { ctx, slots: ctx.get('slots') as SlotsService, locale, settingsDescribe }
 }
 
 /** Declare the shell's four child slots the way ui-settings' entry does. */
@@ -34,6 +56,7 @@ function declare(slots: SlotsService): () => void {
         'settings.header': { kind: 'single', scope: 'root' },
         'settings.close': { kind: 'single', scope: 'root' },
         'settings.section': { kind: 'list', scope: 'root' },
+        'settings.onboarding': { kind: 'list', scope: 'root' },
       },
     } as never,
     () => null,
@@ -46,7 +69,7 @@ function generalEntry(slots: SlotsService) {
 
 describe('ui-settings-general apply', () => {
   it('declares the services it uses', () => {
-    expect(inject).toEqual(['slots', 'locale'])
+    expect(inject).toEqual(['slots', 'locale', 'connection'])
   })
 
   it('fills all four seats for declarations before or after apply', async () => {
@@ -61,6 +84,8 @@ describe('ui-settings-general apply', () => {
     expect(before.slots.spec('settings.general.item')).toEqual({ kind: 'list', scope: 'root' })
     const injected = (entry.inject as unknown as () => GeneralSectionInjected)()
     expect(injected.t('permission.title')).toBe('权限')
+    const welcome = before.slots.entries('settings.onboarding')[0]!
+    expect(welcome.options).toEqual({ id: 'welcome-notice', order: -100 })
     // The chrome seats share one inject face: the settings-ns translate.
     const chrome = (before.slots.entries('settings.trigger')[0]!.inject as unknown as () => GeneralSectionInjected)()
     expect(chrome.t('trigger')).toBe('设置')
@@ -116,6 +141,22 @@ describe('ui-settings-general apply', () => {
     b.locale.setLocale('zh')
   })
 
+  it('refreshes loaded welcome state only for its settings namespace or a reconnect', async () => {
+    const b = await bench()
+    declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const entry = b.slots.entries('settings.onboarding')[0]!
+    const { controller } = (entry.inject as unknown as () => WelcomeNoticeInjected)()
+    await controller.load()
+    expect(b.settingsDescribe).toHaveBeenCalledOnce()
+    b.ctx.emit('settings/changed', 'unrelated')
+    expect(b.settingsDescribe).toHaveBeenCalledOnce()
+    b.ctx.emit('settings/changed', WELCOME_NOTICE_SETTINGS_NAMESPACE)
+    await vi.waitFor(() => { expect(b.settingsDescribe).toHaveBeenCalledTimes(2) })
+    b.ctx.emit('connection/reset')
+    await vi.waitFor(() => { expect(b.settingsDescribe).toHaveBeenCalledTimes(3) })
+  })
+
   it('re-registers after an HMR collapse of the declaring chain (stale disposers must not block)', async () => {
     const b = await bench()
     const redeclare = declare(b.slots)

packages/client/ui-settings-general/tests/host.spec.ts

@@ -0,0 +1,29 @@
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { Settings, settingsNamespace, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import { apply } from '../src/index.ts'
+import { WELCOME_NOTICE_SETTINGS_NAMESPACE } from '../src/onboarding-copy.ts'
+
+class MemorySettings extends Settings {
+  readonly writable = true
+  protected load(): Promise<Record<string, unknown>> { return Promise.resolve({}) }
+  protected persist(_ns: SettingsNamespace, _section: Record<string, unknown>): Promise<void> {
+    return Promise.resolve()
+  }
+}
+
+describe('ui-settings-general host', () => {
+  it('registers and disposes the durable onboarding namespace with its fiber', async () => {
+    const ctx = new Context()
+    await ctx.plugin(MemorySettings).await()
+    const fiber = ctx.plugin({ apply })
+    await fiber.await()
+    expect(ctx.settings.describe().map(row => row.ns)).toContain(
+      settingsNamespace(WELCOME_NOTICE_SETTINGS_NAMESPACE),
+    )
+    await fiber.dispose()
+    expect(ctx.settings.describe().map(row => row.ns)).not.toContain(
+      settingsNamespace(WELCOME_NOTICE_SETTINGS_NAMESPACE),
+    )
+  })
+})

packages/client/ui-settings-general/tests/invariant.spec.ts

@@ -9,10 +9,4 @@ describe('invariant companion', () => {
     await ctx.plugin(InvariantService, { enabled: true })
     await expect(ctx.plugin(GeneralInvariant).await()).resolves.toBeDefined()
   })
-
-  it('node-half apply is a no-op host placeholder', async () => {
-    const { apply } = await import('@deepseek-ai/dsh-client-ui-settings-general')
-    apply()
-    expect(true).toBe(true) // reaching here without throw is the contract
-  })
 })

packages/client/ui-settings-general/tests/welcome-notice.spec.tsx

@@ -0,0 +1,101 @@
+// @vitest-environment jsdom
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import { WelcomeNotice } from '../src/client/WelcomeNotice.tsx'
+import type { WelcomeNoticeProps } from '../src/client/WelcomeNotice.tsx'
+import { WelcomeNoticeStore } from '../src/client/welcome-store.ts'
+import { zh } from '../src/client/locales.ts'
+import {
+  WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_COPY, WELCOME_NOTICE_SETTINGS_NAMESPACE,
+  WELCOME_NOTICE_VERSION,
+} from '../src/onboarding-copy.ts'
+
+afterEach(cleanup)
+
+function response<T>(value: T) {
+  return { rpcId: 'welcome-rpc' as never, result: { ok: true as const, value } }
+}
+
+function mount(version?: string, mutateImpl: () => Promise<unknown> = () => Promise.resolve(response({}))) {
+  const mutate = vi.fn(mutateImpl)
+  const api = {
+    settings: {
+      describe: () => Promise.resolve(response({
+        writable: true,
+        namespaces: [{
+          ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
+          schema: {},
+          value: version === undefined ? {} : { [WELCOME_NOTICE_ACK_FIELD]: version },
+          applies: 'live' as const,
+          secrets: [],
+          revision: 0,
+        }],
+      })),
+      mutate,
+    },
+  }
+  const controller = new WelcomeNoticeStore(api as never)
+  const complete = vi.fn()
+  const unusedHook = (() => { throw new Error('unused standard hook') }) as never
+  const props: WelcomeNoticeProps = {
+    stepId: 'welcome-notice',
+    complete,
+    openSection: vi.fn(),
+    useSessions: unusedHook,
+    useWorkspaces: unusedHook,
+    controller,
+    useSnapshot: bindSnapshotSelector(controller.store),
+    t: key => zh[key] ?? key,
+  }
+  return { ...render(<WelcomeNotice {...props} />), complete, controller, mutate }
+}
+
+describe('WelcomeNotice', () => {
+  it('renders the owner copy with one primary action and no dismissal control', async () => {
+    const h = mount()
+    const dialog = await screen.findByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.paragraphs[0] })
+    for (const paragraph of WELCOME_NOTICE_COPY.zh.paragraphs) {
+      expect(screen.getByText(paragraph)).toBeTruthy()
+    }
+    const buttons = dialog.querySelectorAll('button')
+    expect(buttons).toHaveLength(1)
+    expect(screen.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel })).toBeTruthy()
+    fireEvent.keyDown(document, { key: 'Escape' })
+    fireEvent.click(dialog.parentElement!.firstElementChild!)
+    expect(h.complete).not.toHaveBeenCalled()
+    expect(screen.getByRole('dialog')).toBeTruthy()
+  })
+
+  it('completes only after the acknowledgement write commits', async () => {
+    const h = mount()
+    await screen.findByRole('dialog')
+    fireEvent.click(screen.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel }))
+    await act(async () => { await Promise.resolve() })
+    expect(h.mutate).toHaveBeenCalledOnce()
+    expect(h.complete).toHaveBeenCalledOnce()
+  })
+
+  it('skips itself when this exact version was already acknowledged', async () => {
+    const h = mount(WELCOME_NOTICE_VERSION)
+    await act(async () => { await h.controller.load() })
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(h.complete).toHaveBeenCalledOnce()
+  })
+
+  it('keeps the sole action disabled while saving and reports a refused write', async () => {
+    let resolveWrite!: (value: unknown) => void
+    const write = new Promise<unknown>((resolve) => { resolveWrite = resolve })
+    const h = mount(undefined, () => write)
+    await screen.findByRole('dialog')
+    const action = screen.getByRole<HTMLButtonElement>('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel })
+    fireEvent.click(action)
+    expect(action.disabled).toBe(true)
+    resolveWrite({
+      rpcId: 'welcome-refused' as never,
+      result: { ok: false, error: { code: 'settings-rejected', message: 'read only', details: { ns: WELCOME_NOTICE_SETTINGS_NAMESPACE } } },
+    })
+    expect((await screen.findByRole('alert')).textContent).toBe('暂时无法保存确认状态，请重试。')
+    expect(h.complete).not.toHaveBeenCalled()
+  })
+})

packages/client/ui-settings-general/tests/welcome-store.spec.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { RpcResponse } from '@deepseek-ai/dsh-client-connection/client'
+import { WelcomeNoticeStore } from '../src/client/welcome-store.ts'
+import { refreshWelcomeIfLoaded } from '../src/client/welcome-store.ts'
+import {
+  WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE, WELCOME_NOTICE_VERSION,
+} from '../src/onboarding-copy.ts'
+
+let rpc = 0
+function ok<T>(value: T): RpcResponse<T> {
+  return { rpcId: `welcome-${rpc++}` as never, result: { ok: true, value } }
+}
+
+function namespace(version?: string) {
+  return {
+    ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
+    schema: {},
+    value: version === undefined ? {} : { [WELCOME_NOTICE_ACK_FIELD]: version },
+    applies: 'live' as const,
+    secrets: [],
+    revision: 0,
+  }
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (reason: unknown) => void
+  const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej })
+  return { promise, resolve, reject }
+}
+
+describe('WelcomeNoticeStore', () => {
+  it('acknowledges only the exact current copy version', async () => {
+    for (const [version, acknowledged] of [
+      [undefined, false],
+      ['older-copy', false],
+      [WELCOME_NOTICE_VERSION, true],
+    ] as const) {
+      const api = {
+        settings: {
+          describe: vi.fn(() => Promise.resolve(ok({ writable: true, namespaces: [namespace(version)] }))),
+        },
+      }
+      const controller = new WelcomeNoticeStore(api as never)
+      await controller.load()
+      expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged })
+    }
+  })
+
+  it('persists the owner version through one idempotent path mutation', async () => {
+    const mutate = vi.fn(() => Promise.resolve(ok(namespace(WELCOME_NOTICE_VERSION))))
+    const controller = new WelcomeNoticeStore({ settings: { mutate } } as never)
+    await expect(controller.acknowledge()).resolves.toBe(true)
+    expect(mutate).toHaveBeenCalledWith({
+      ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
+      ops: [{ op: 'set', path: [WELCOME_NOTICE_ACK_FIELD], value: WELCOME_NOTICE_VERSION }],
+    })
+    expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: true })
+  })
+
+  it('keeps the notice pending when loading or persistence fails', async () => {
+    const load = new WelcomeNoticeStore({
+      settings: { describe: () => Promise.reject(new Error('offline')) },
+    } as never)
+    await load.load()
+    expect(load.store.getSnapshot()).toEqual({ status: 'error', acknowledged: false, error: 'offline' })
+
+    const save = new WelcomeNoticeStore({
+      settings: { mutate: () => Promise.reject(new Error('disk full')) },
+    } as never)
+    await expect(save.acknowledge()).resolves.toBe(false)
+    expect(save.store.getSnapshot()).toEqual({ status: 'error', acknowledged: false, error: 'disk full' })
+
+    const nonError = new WelcomeNoticeStore({
+      // Durable/wire failures are unknown; exercise containment of a non-Error rejection.
+      // oxlint-disable-next-line typescript/prefer-promise-reject-errors
+      settings: { describe: () => Promise.reject('offline string') },
+    } as never)
+    await nonError.load()
+    expect(nonError.store.getSnapshot().error).toBe('offline string')
+  })
+
+  it('reports business failures, missing namespaces, and malformed durable values', async () => {
+    for (const describe of [
+      () => Promise.resolve({
+        rpcId: 'failed' as never,
+        result: { ok: false as const, error: { code: 'internal' as const, message: 'denied', details: {} } },
+      }),
+      () => Promise.resolve(ok({ writable: true, namespaces: [] })),
+    ]) {
+      const controller = new WelcomeNoticeStore({ settings: { describe } } as never)
+      await controller.load()
+      expect(controller.store.getSnapshot().status).toBe('error')
+    }
+
+    for (const value of [null, 42, { [WELCOME_NOTICE_ACK_FIELD]: 42 }]) {
+      const controller = new WelcomeNoticeStore({
+        settings: { describe: () => Promise.resolve(ok({
+          writable: true,
+          namespaces: [{ ...namespace(), value }],
+        })) },
+      } as never)
+      await controller.load()
+      expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: false })
+    }
+
+    const save = new WelcomeNoticeStore({
+      settings: { mutate: () => Promise.resolve({
+        rpcId: 'failed-save' as never,
+        result: { ok: false, error: { code: 'settings-rejected', message: 'denied', details: { ns: WELCOME_NOTICE_SETTINGS_NAMESPACE } } },
+      }) },
+    } as never)
+    await expect(save.acknowledge()).resolves.toBe(false)
+    expect(save.store.getSnapshot().error).toBe('denied')
+  })
+
+  it('lets the latest load win over stale success and failure', async () => {
+    const first = deferred<ReturnType<typeof ok>>()
+    const describe = vi.fn()
+      .mockImplementationOnce(() => first.promise)
+      .mockImplementationOnce(() => Promise.resolve(ok({ writable: true, namespaces: [namespace()] })))
+    const controller = new WelcomeNoticeStore({ settings: { describe } } as never)
+    const stale = controller.load()
+    await controller.load()
+    first.resolve(ok({ writable: true, namespaces: [namespace(WELCOME_NOTICE_VERSION)] }))
+    await stale
+    expect(controller.store.getSnapshot().acknowledged).toBe(false)
+
+    const failed = deferred<ReturnType<typeof ok>>()
+    describe
+      .mockImplementationOnce(() => failed.promise)
+      .mockImplementationOnce(() => Promise.resolve(ok({ writable: true, namespaces: [namespace(WELCOME_NOTICE_VERSION)] })))
+    const staleFailure = controller.load()
+    await controller.load()
+    failed.reject('stale failure')
+    await staleFailure
+    expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: true, error: null })
+  })
+
+  it('contains stale acknowledgement settlements and refreshes only a loaded store', async () => {
+    const write = deferred<ReturnType<typeof ok>>()
+    const describe = vi.fn(() => Promise.resolve(ok({ writable: true, namespaces: [namespace()] })))
+    const controller = new WelcomeNoticeStore({
+      settings: { mutate: () => write.promise, describe },
+    } as never)
+    refreshWelcomeIfLoaded(controller)
+    expect(describe).not.toHaveBeenCalled()
+    const staleWrite = controller.acknowledge()
+    await controller.load()
+    write.resolve(ok(namespace(WELCOME_NOTICE_VERSION)))
+    await expect(staleWrite).resolves.toBe(true)
+    expect(controller.store.getSnapshot().acknowledged).toBe(false)
+    refreshWelcomeIfLoaded(controller)
+    await vi.waitFor(() => { expect(describe).toHaveBeenCalledTimes(2) })
+
+    const failedWrite = deferred<ReturnType<typeof ok>>()
+    const staleFailure = new WelcomeNoticeStore({
+      settings: { mutate: () => failedWrite.promise, describe },
+    } as never)
+    const pending = staleFailure.acknowledge()
+    await staleFailure.load()
+    failedWrite.reject('late failure')
+    await expect(pending).resolves.toBe(false)
+    expect(staleFailure.store.getSnapshot().status).toBe('ready')
+  })
+})

packages/client/ui-settings-general/tsconfig.json

@@ -14,6 +14,9 @@
     {
       "path": "../ui-slots"
     },
+    {
+      "path": "../connection"
+    },
     {
       "path": "../ui-primitives"
     },
@@ -23,9 +26,15 @@
     {
       "path": "../ui-settings"
     },
+    {
+      "path": "../web-react"
+    },
     {
       "path": "../locale"
     },
+    {
+      "path": "../../settings/settings"
+    },
     {
       "path": "../../support/invariants"
     }

packages/client/ui-settings/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-settings/README.md
-README.md: 9388e9dd3a984bfcebc85b6b1a35bcce4b9b116e
-README.zh.md: 57c91ac5dd0bcc0a3e5e029359bf6c3a2be58ec7
+README.md: 02d8f0e5fdc169d3a45f59d7b42d873943df2b52
+README.zh.md: 465d57847588e9ccbccc9d9067099773de63c0d0

packages/client/ui-settings/README.md

@@ -2,9 +2,9 @@
 
 English | [中文](README.zh.md)
 
-Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.section` (one page per feature), and `settings.onboarding` (feature-owned overlays on the empty Hero). The shell ships no copy and reads no locale state — all text arrives from registrants (ui-settings-general owns chrome and General; features own their sections, rows, and onboarding overlays).
+Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.section` (one page per feature), and `settings.onboarding` (ordered feature-owned steps on the empty Hero). The shell ships no copy and reads no locale state — all text arrives from registrants (ui-settings-general owns chrome, General, and the product welcome step; features own their sections, rows, and conditional onboarding steps).
 
-The shell supplies onboarding registrants only two navigation facts: whether the session surface is the empty Hero and an `openSection(id)` callback that opens the panel on a registered section. Registrants own capability readiness, dismissal, copy, and mutations; the shell therefore does not become a second configuration fact source.
+The shell projects the onboarding ledger into ascending order and mounts exactly one step at a time. The active registrant receives its id, `complete()`, and an `openSection(id)` callback; completing or skipping transfers ownership to the next entry. Registrants own durable completion, capability readiness, copy, and mutations, so two independently registered dialogs cannot stack and the shell does not become a second configuration fact source.
 
 ## Model Experience
 

packages/client/ui-settings/README.zh.md

@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-设置外壳插件：一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`，并声明由注册方填充的 slot：`settings.trigger`／`settings.header`／`settings.close`（界面框架内容）、`settings.section`（每项功能一页）和 `settings.onboarding`（由各功能持有、覆盖在空白 Hero 之上的浮层）。外壳不自带文案，也不读取 locale 状态：所有文本都来自注册方（ui-settings-general 拥有界面框架和「通用」分区；各功能拥有各自的分区、行和首次使用浮层）。
+设置外壳插件：一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`，并声明由注册方填充的 slot：`settings.trigger`／`settings.header`／`settings.close`（界面框架内容）、`settings.section`（每项功能一页）和 `settings.onboarding`（由各功能持有、显示在空白 Hero 上的有序步骤）。外壳不自带文案，也不读取 locale 状态：所有文本都来自注册方（ui-settings-general 拥有界面框架、「通用」分区和产品欢迎步骤；各功能拥有各自的分区、行和条件式首次使用引导步骤）。
 
-外壳只向首次使用注册方提供两个导航事实：当前会话界面是否为空白 Hero，以及一个 `openSection(id)` 回调；后者会打开设置面板并切换到已注册的指定分区。能力就绪状态、浮层关闭、文案和变更操作均由注册方持有，因此外壳不会成为第二个配置事实来源。
+外壳将首次使用引导记录按升序投影，并且每次只挂载一个步骤。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调；完成或跳过当前步骤后，所有权转交给下一项。持久化完成状态、能力就绪状态、文案和变更操作均由注册方持有，因此两个独立注册的对话框无法堆叠，外壳也不会成为第二个配置事实来源。
 
 ## 模型体验
 

packages/client/ui-settings/src/client/SettingsRoot.tsx

@@ -6,8 +6,8 @@
  * names resolve to that content (trigger: its own text; dialog:
  * aria-labelledby the title node; close: visually-hidden slot text). Modal
  * open state and the active section id are component-local viewing state;
- * the onboarding slot receives the sessions-derived empty-Hero fact and a
- * private callback that opens one registered section.
+ * the onboarding coordinator mounts exactly one ordered registrant while the
+ * sessions-derived empty-Hero fact is active.
  */
 import { useCallback, useEffect, useId, useRef, useState } from 'react'
 import clsx from 'clsx'
@@ -95,9 +95,10 @@ function SettingsPanel({ rows, renderSlot, activeId, onSelect, onClose }: PanelP
  * @returns the settings shell element tree.
  */
 export function SettingsRoot(props: SettingsRootComponentProps) {
-  const { wide, useSections, useSessions, renderSlot } = props
+  const { wide, useSections, useOnboardingSteps, useSessions, renderSlot } = props
   const [open, setOpen] = useState(false)
   const [activeId, setActiveId] = useState<string | undefined>(undefined)
+  const [completedOnboarding, setCompletedOnboarding] = useState<ReadonlySet<string>>(() => new Set())
   const close = useCallback(() => {
     setOpen(false)
     setActiveId(undefined)
@@ -111,9 +112,25 @@ export function SettingsRoot(props: SettingsRootComponentProps) {
   // freshly localized text on locale change, and the trigger/header/close
   // seats re-render through their own outlets' subscriptions.
   const rows = useSections(s => s)
+  const onboardingSteps = useOnboardingSteps(s => s)
   const onboardingActive = useSessions(state =>
     state.phase === 'ready'
     && (state.current === undefined || state.byId[state.current]?.blank === true))
+  const onboardingStep = onboardingActive
+    ? onboardingSteps.find(step => !completedOnboarding.has(step.id))
+    : undefined
+
+  useEffect(() => {
+    if (onboardingActive) return
+    setCompletedOnboarding(new Set())
+  }, [onboardingActive])
+
+  const completeOnboardingStep = useCallback((id: string) => {
+    setCompletedOnboarding((previous) => {
+      if (previous.has(id)) return previous
+      return new Set([...previous, id])
+    })
+  }, [])
 
   return (
     <>
@@ -135,7 +152,11 @@ export function SettingsRoot(props: SettingsRootComponentProps) {
           onClose={close}
         />
       )}
-      {renderSlot('settings.onboarding', { active: onboardingActive, openSection })}
+      {onboardingStep !== undefined && renderSlot('settings.onboarding', {
+        stepId: onboardingStep.id,
+        complete: () => { completeOnboardingStep(onboardingStep.id) },
+        openSection,
+      }, { only: onboardingStep.id })}
     </>
   )
 }

packages/client/ui-settings/src/client/contract/slots.ts

@@ -48,10 +48,10 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      */
     'settings.section': { kind: 'list'; scope: 'root'; owner: SettingsSectionOwnerProps }
     /**
-     * Root-scoped onboarding overlays contributed by settings features. The
-     * shell supplies whether the current navigation state is the empty Hero
-     * and a private callback that opens one settings section; registrants own
-     * readiness, copy, and dialog behavior.
+     * Root-scoped onboarding steps contributed by settings features. The
+     * shell mounts one ordered step at a time; the active registrant either
+     * completes itself or keeps ownership until the user completes its sole
+     * path. Registrants own readiness, copy, and dialog behavior.
      */
     'settings.onboarding': { kind: 'list'; scope: 'root'; owner: SettingsOnboardingOwnerProps }
   }
@@ -79,10 +79,12 @@ export interface SettingsSectionOwnerProps {
   children?: never
 }
 
-/** Owner share of a settings-backed onboarding overlay. */
+/** Owner share of the currently active settings-backed onboarding step. */
 export interface SettingsOnboardingOwnerProps {
-  /** Whether the current UI is in its empty Hero/onboarding state. */
-  active: boolean
+  /** Stable id of the step currently selected by the coordinator. */
+  stepId: string
+  /** Complete or skip this step and transfer ownership to the next entry. */
+  complete: () => void
   /** Open the settings panel directly on one registered section. */
   openSection: (id: string) => void
 }
@@ -94,6 +96,12 @@ export interface SettingsSectionRow {
   label: string
 }
 
+/** One ordered onboarding step projected from a slot registration. */
+export interface SettingsOnboardingStep {
+  id: string
+  order: number
+}
+
 /**
  * Registrant-private injected share of the settings shell (assembled in
  * apply): the ledger's nav-row projection as a hooks-compartment source —
@@ -103,6 +111,8 @@ export type SettingsRootInjected = {
   hooks: {
     /** settings.section ledger projected into ordered nav rows. */
     sections: HostObservable<readonly SettingsSectionRow[]>
+    /** settings.onboarding ledger projected into coordinator order. */
+    onboardingSteps: HostObservable<readonly SettingsOnboardingStep[]>
   }
 }
 

packages/client/ui-settings/src/client/index.ts

@@ -9,12 +9,15 @@
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SettingsRootInjected, SettingsSectionRow } from './contract/slots.ts'
+import type {
+  SettingsOnboardingStep, SettingsRootInjected, SettingsSectionRow,
+} from './contract/slots.ts'
 import { SettingsRoot } from './SettingsRoot.tsx'
 
 export type {
   SettingsHeaderOwnerProps, SettingsRootComponentProps, SettingsRootInjected,
-  SettingsOnboardingOwnerProps, SettingsSectionOwnerProps, SettingsSectionRow, SettingsTriggerOwnerProps,
+  SettingsOnboardingOwnerProps, SettingsOnboardingStep, SettingsSectionOwnerProps,
+  SettingsSectionRow, SettingsTriggerOwnerProps,
 } from './contract/slots.ts'
 
 /**
@@ -35,6 +38,8 @@ export function apply(ctx: ClientContext): void {
   // getSnapshot returns the cached rows until the ledger version moves).
   let rowsVersion = -1
   let rows: readonly SettingsSectionRow[] = []
+  let onboardingVersion = -1
+  let onboardingSteps: readonly SettingsOnboardingStep[] = []
   const injected = (): SettingsRootInjected => ({
     hooks: {
       sections: {
@@ -55,6 +60,23 @@ export function apply(ctx: ClientContext): void {
         },
         subscribe: listener => ctx.slots.subscribe('settings.section', listener),
       },
+      onboardingSteps: {
+        getSnapshot: () => {
+          const version = ctx.slots.getVersion('settings.onboarding')
+          if (version !== onboardingVersion) {
+            onboardingVersion = version
+            onboardingSteps = ctx.slots.entries('settings.onboarding')
+              .map(e => ({
+                /* v8 ignore next -- list-slot registration requires id */
+                id: e.options.id ?? '',
+                order: e.options.order ?? 0,
+              }))
+              .sort((a, b) => a.order - b.order)
+          }
+          return onboardingSteps
+        },
+        subscribe: listener => ctx.slots.subscribe('settings.onboarding', listener),
+      },
     },
   })
   ctx.effect(() => {

packages/client/ui-settings/tests/apply.spec.ts

@@ -83,6 +83,29 @@ describe('ui-settings apply', () => {
     off()
   })
 
+  it('projects onboarding entries into stable coordinator order', async () => {
+    const b = await bench()
+    declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const { onboardingSteps } = injectedOf(b.slots).hooks
+    b.slots.register({ name: 'settings.onboarding', id: 'credential', order: 0 } as never, () => null)
+    b.slots.register({ name: 'settings.onboarding', id: 'welcome', order: -100 } as never, () => null)
+    b.slots.register({ name: 'settings.onboarding', id: 'default-order' } as never, () => null)
+    const steps = onboardingSteps.getSnapshot()
+    expect(steps).toEqual([
+      { id: 'welcome', order: -100 },
+      { id: 'credential', order: 0 },
+      { id: 'default-order', order: 0 },
+    ])
+    expect(onboardingSteps.getSnapshot()).toBe(steps)
+    const listener = vi.fn()
+    const off = onboardingSteps.subscribe(listener)
+    b.slots.register({ name: 'settings.onboarding', id: 'later', order: 10 } as never, () => null)
+    await Promise.resolve()
+    expect(listener).toHaveBeenCalledOnce()
+    off()
+  })
+
   it('re-registers after an HMR collapse re-declares the slot (stale disposer must not block)', async () => {
     const b = await bench()
     const redeclare = declare(b.slots)

packages/client/ui-settings/tests/settings-root.spec.tsx

@@ -8,6 +8,7 @@ import { SettingsRoot } from '../src/client/SettingsRoot.tsx'
 afterEach(cleanup)
 
 type Row = { id: string; order: number; label: string }
+type Step = { id: string; order: number }
 
 /** Slot-content stand-ins: the shell renders whatever the seats contribute. */
 const SEAT_CONTENT: Record<string, string> = {
@@ -23,7 +24,11 @@ function mount({
     { id: 'general', order: 0, label: 'General' },
     { id: 'models', order: 10, label: 'Models' },
   ],
-}: { wide?: boolean; onboardingActive?: boolean; rows?: Row[] } = {}) {
+  steps = [
+    { id: 'welcome', order: -100 },
+    { id: 'credential', order: 0 },
+  ],
+}: { wide?: boolean; onboardingActive?: boolean; rows?: Row[]; steps?: Step[] } = {}) {
   // Mutable row source standing in for the bound useSections hook; bump()
   // plays a ledger change through the same observable contract.
   let current = rows
@@ -46,6 +51,7 @@ function mount({
     useSessions,
     useWorkspaces: unusedHook,
     wide,
+    useOnboardingSteps: select => select(steps),
     useSections: (select) => {
       const [, force] = useState(0)
       useEffect(() => {
@@ -164,20 +170,30 @@ describe('SettingsPanel navigation', () => {
     expect(screen.queryByTestId('section-general')).toBeNull()
   })
 
-  it('hands Hero readiness and a direct section opener to onboarding registrants', () => {
+  it('mounts onboarding steps in order and transfers ownership only on completion', () => {
     const { renderSlot } = mount()
-    const onboardingCall = renderSlot.mock.calls.find(call => call[0] === 'settings.onboarding')
-    expect(onboardingCall?.[1]).toMatchObject({ active: true })
+    const first = renderSlot.mock.calls.find(call => call[0] === 'settings.onboarding')
+    expect(first?.[1]).toMatchObject({ stepId: 'welcome' })
+    expect(first?.[2]).toEqual({ only: 'welcome' })
+    act(() => {
+      (first?.[1] as { complete: () => void }).complete()
+      ;(first?.[1] as { complete: () => void }).complete()
+    })
+    const onboardingCalls = renderSlot.mock.calls.filter(call => call[0] === 'settings.onboarding')
+    const second = onboardingCalls.at(-1)
+    expect(second?.[1]).toMatchObject({ stepId: 'credential' })
+    expect(second?.[2]).toEqual({ only: 'credential' })
+
     act(() => {
-      (onboardingCall?.[1] as { openSection: (id: string) => void }).openSection('models')
+      (second?.[1] as { openSection: (id: string) => void }).openSection('models')
     })
     expect(screen.getByRole('dialog')).toBeTruthy()
     expect(screen.getByTestId('section-models')).toBeTruthy()
 
     cleanup()
-    const active = mount({ onboardingActive: false }).renderSlot.mock.calls
-      .find(call => call[0] === 'settings.onboarding')
-    expect(active?.[1]).toMatchObject({ active: false })
+    const inactive = mount({ onboardingActive: false }).renderSlot.mock.calls
+      .filter(call => call[0] === 'settings.onboarding')
+    expect(inactive).toHaveLength(0)
   })
 
   it('falls back to the first row when the active entry unregisters', () => {

packages/host/apiproxy/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
-README.md: 0abbeced0902471f7ff8ce9a73d188619ad2b64a
-README.zh.md: 315ddb06791b8ce7723f8a5349b6cf576fe971de
+README.md: bdf67f7d993df3e0ea7ccd7753c7d492d9d2d904
+README.zh.md: 7b758cfc888dc74ad136a2fc139b856705ee8168

packages/host/apiproxy/src/api-proxy.ts

@@ -69,6 +69,9 @@ const DEFAULT_MAX_MESSAGES = 50
 /** Surface message event types (the pagination counting unit). */
 const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'steering/message'])
 
+/** Product settings intentionally exposed beside model-provider namespaces. */
+const PRODUCT_SETTINGS_NAMESPACES = new Set(['ui-onboarding'])
+
 /**
  * Message-boundary pagination: count maxMessages surface messages backwards from
  * the window tail; the cut is the starting seq of the oldest message group
@@ -1014,24 +1017,26 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     }
   }
 
+  /** Settings namespaces whose values can change the model directory. */
+  function providerSettingsNamespaces(): Set<string> {
+    return new Set(ctx.llm.listConfigurableProviders().map(entry => entry.settingsNs))
+  }
+
   /**
-   * The settings namespaces this proxy serves: exactly those a registered
-   * configurable provider addresses. The settings seam itself is general —
-   * any plugin may register a namespace for its own configuration — but the
-   * Web configuration plane is scoped to model providers, and that boundary
-   * has to be enforced here rather than assumed from the current plugin set.
-   * Without it, every future `settings.register()` would silently become
-   * remotely readable and writable configuration.
+   * The settings namespaces this proxy serves: registered configurable
+   * providers plus a closed product-owned allowlist. The settings seam itself
+   * is general, so exposure stays explicit here; registering a future
+   * namespace never makes it remotely readable or writable by accident.
    */
   function exposedNamespaces(): Set<string> {
-    return new Set(ctx.llm.listConfigurableProviders().map(entry => entry.settingsNs))
+    return new Set([...providerSettingsNamespaces(), ...PRODUCT_SETTINGS_NAMESPACES])
   }
 
-  /** Refuse a namespace outside the model-provider boundary, naming why. */
+  /** Refuse a namespace outside the explicit Web configuration boundary. */
   function notExposed(request: RpcRequest<unknown>, ns: string): RpcResponse<SettingsNamespaceView> {
     return err(request, {
       code: 'settings-not-exposed',
-      message: `settings namespace "${ns}" is not exposed to configuration clients; only a namespace a registered model provider addresses is`,
+      message: `settings namespace "${ns}" is not exposed to configuration clients`,
       details: { ns },
     })
   }
@@ -1909,7 +1914,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             // A provider's own settings carry its model catalog and endpoint,
             // so a change there invalidates the model list even when the route
             // set is untouched — `llm/adapters-updated` alone misses it.
-            if (exposedNamespaces().has(String(ns))) queue.push(frame({ type: 'host/models-changed' }))
+            if (providerSettingsNamespaces().has(String(ns))) queue.push(frame({ type: 'host/models-changed' }))
           }),
           ctx.on('credentials/updated', (ref) => {
             queue.push(frame({ type: 'host/credentials-changed', ref: String(ref) }))

packages/host/apiproxy/tests/api-proxy-config.spec.ts

@@ -222,7 +222,7 @@ describe('settings domain', () => {
     expect(JSON.stringify(value)).not.toContain('user-secret')
   })
 
-  it('serves only namespaces a registered model provider addresses', async () => {
+  it('keeps arbitrary plugin namespaces outside the explicit Web allowlist', async () => {
     // The settings seam is general: any plugin may register a namespace for
     // its own configuration. The Web configuration plane is not — it is the
     // model-provider surface, and a namespace nothing in the provider
@@ -248,6 +248,21 @@ describe('settings domain', () => {
     expect(ctx.settings.describe().find(d => String(d.ns) === 'some-other-plugin')?.value).toEqual({})
   })
 
+  it('serves the product onboarding namespace without invalidating the model catalog', async () => {
+    const ctx = await harness()
+    ctx.settings.register(settingsNamespace('ui-onboarding'), z.object({ welcomeNoticeVersion: z.string() }))
+    const api = createApiProxy(ctx, DEFAULTS)
+    expect(expectOk(await api.settings.describe(request({}))).namespaces.map(view => view.ns))
+      .toEqual(['ui-onboarding'])
+    const frames = await collectHost(api, ['host/settings-changed'], 1, async () => {
+      expectOk(await api.settings.mutate(request({
+        ns: 'ui-onboarding',
+        ops: [{ op: 'set', path: ['welcomeNoticeVersion'], value: 'v1' }],
+      })))
+    })
+    expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'ui-onboarding' }])
+  })
+
   it('refuses even a model-provider namespace once its directory entry is gone', async () => {
     const ctx = await harness({ configurableProviders: false })
     ctx.settings.register(NS, AdapterConfig)

pnpm-lock.yaml

@@ -1559,7 +1559,17 @@ importers:
         version: 18.3.1
 
   packages/client/ui-settings-general:
+    dependencies:
+      '@deepseek-ai/dsh-settings':
+        specifier: workspace:^
+        version: link:../../settings/settings
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
     devDependencies:
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../connection
       '@deepseek-ai/dsh-client-locale':
         specifier: workspace:^
         version: link:../locale
@@ -1575,6 +1585,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-client-web-react':
+        specifier: workspace:^
+        version: link:../web-react
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants