From 9182db00efa5468814f921e539cb17e64dc9a5be Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 30 Jul 2026 12:41:09 +0800
Subject: [PATCH 1/7] feat(web): configure DeepSeek during onboarding

---
 .../client/connection/src/client/fixture.ts   |  29 +-
 .../client/connection/tests/fixture.spec.ts   |  30 ++
 packages/client/ui-models/package.json        |   4 +-
 .../DeepSeekOnboardingDialog.module.css       |  54 ++++
 .../src/client/DeepSeekOnboardingDialog.tsx   | 186 ++++++++++++
 .../ui-models/src/client/ModelsSection.tsx    |   2 +-
 packages/client/ui-models/src/client/index.ts |  41 ++-
 .../client/ui-models/src/client/locales.ts    |  26 ++
 packages/client/ui-models/src/client/store.ts | 135 ++++++++-
 packages/client/ui-models/tests/apply.spec.ts |  33 ++-
 .../ui-models/tests/components.spec.tsx       |  18 +-
 .../tests/onboarding-dialog.spec.tsx          | 265 ++++++++++++++++++
 .../client/ui-models/tests/readiness.spec.ts  | 112 ++++++++
 packages/client/ui-models/tests/store.spec.ts |  48 ++++
 packages/client/ui-models/tsconfig.json       |   3 +
 packages/client/ui-primitives/src/Modal.tsx   |   6 +-
 .../client/ui-primitives/tests/atoms.spec.tsx |   3 +-
 packages/client/ui-settings/package.json      |   2 +-
 .../ui-settings/src/client/SettingsRoot.tsx   |  35 ++-
 .../ui-settings/src/client/contract/slots.ts  |  19 +-
 .../client/ui-settings/src/client/index.ts    |  14 +-
 .../client/ui-settings/tests/apply.spec.ts    |   7 +-
 .../ui-settings/tests/settings-root.spec.tsx  |  29 +-
 pnpm-lock.yaml                                |   3 +
 24 files changed, 1051 insertions(+), 53 deletions(-)
 create mode 100644 packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
 create mode 100644 packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
 create mode 100644 packages/client/ui-models/tests/onboarding-dialog.spec.tsx
 create mode 100644 packages/client/ui-models/tests/readiness.spec.ts

diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 1c90718aa3..00416ea2c7 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -588,7 +588,11 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
     { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
   ]))
   /** Credential store double: set/unset flip the describe badge, values never read back. */
-  const fixtureCredentials = new Map<string, string>()
+  const fixtureCredentials = new Map<string, true>([
+    // The assembled fixture represents an already-configured shipped
+    // DeepSeek route so unrelated GUI journeys do not enter first-run setup.
+    ['DEEPSEEK_API_KEY', true],
+  ])
   const nextTurn = new Map<SessionId, number>([[sid('fx-alpha'), 60]])
   let nextSession = 1
   let nextRpc = 1
@@ -1284,19 +1288,26 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       },
     },
     settings: {
-      // The fixture registers no namespaces yet: the Models surface renders
-      // its provider list from llm.providers alone, and a real settings form
-      // rides the HTTP transport (a hand-written schema envelope here would
-      // drift from schemastery's real serialization).
-      describe: request => ok(request, { writable: true, namespaces: [] }),
+      // Only the resolved DeepSeek address needed by first-run readiness is
+      // represented here; real schema-driven forms ride the HTTP transport.
+      describe: request => ok(request, {
+        writable: true,
+        namespaces: [{
+          ns: 'llm-deepseek',
+          schema: {},
+          value: { apiKeyEnv: 'DEEPSEEK_API_KEY' },
+          applies: 'live',
+          secrets: [{ path: ['apiKey'], set: false }],
+        }],
+      }),
       update: request => err(request, {
         code: 'settings-rejected',
-        message: 'fixture: no settings namespaces are registered',
+        message: 'fixture: the minimal readiness settings descriptor is read-only',
         details: { ns: request.payload.ns },
       }),
       replace: request => err(request, {
         code: 'settings-rejected',
-        message: 'fixture: no settings namespaces are registered',
+        message: 'fixture: the minimal readiness settings descriptor is read-only',
         details: { ns: request.payload.ns },
       }),
     },
@@ -1309,7 +1320,7 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
         }])),
       }),
       set: (request) => {
-        fixtureCredentials.set(request.payload.ref, request.payload.value)
+        fixtureCredentials.set(request.payload.ref, true)
         return ok(request, {})
       },
       unset: (request) => {
diff --git a/packages/client/connection/tests/fixture.spec.ts b/packages/client/connection/tests/fixture.spec.ts
index 8f51861283..146206022c 100644
--- a/packages/client/connection/tests/fixture.spec.ts
+++ b/packages/client/connection/tests/fixture.spec.ts
@@ -108,6 +108,36 @@ describe('createFixtureApi', () => {
     expect(JSON.stringify(after.result.value.events)).toContain('openai/gpt-5')
   })
 
+  it('serves configured DeepSeek readiness and keeps credential values write-only', async () => {
+    const api = createFixtureApi()
+    const settings = await api.settings.describe(req({}))
+    if (!settings.result.ok) throw new Error('settings describe failed')
+    expect(settings.result.value.namespaces).toMatchObject([{
+      ns: 'llm-deepseek',
+      value: { apiKeyEnv: 'DEEPSEEK_API_KEY' },
+      secrets: [{ path: ['apiKey'], set: false }],
+    }])
+
+    const initial = await api.credentials.describe(req({ refs: ['DEEPSEEK_API_KEY', 'TEST_API_KEY'] }))
+    if (!initial.result.ok) throw new Error('credential describe failed')
+    expect(initial.result.value.credentials).toEqual({
+      DEEPSEEK_API_KEY: { configured: true, source: 'file', writable: true },
+      TEST_API_KEY: { configured: false, writable: true },
+    })
+    await api.credentials.set(req({ ref: 'TEST_API_KEY', value: 'write-only-fixture-secret' }))
+    const configured = await api.credentials.describe(req({ refs: ['TEST_API_KEY'] }))
+    if (!configured.result.ok) throw new Error('credential describe failed')
+    expect(configured.result.value.credentials.TEST_API_KEY).toEqual({
+      configured: true,
+      source: 'file',
+      writable: true,
+    })
+    await api.credentials.unset(req({ ref: 'TEST_API_KEY' }))
+    const cleared = await api.credentials.describe(req({ refs: ['TEST_API_KEY'] }))
+    if (!cleared.result.ok) throw new Error('credential describe failed')
+    expect(cleared.result.value.credentials.TEST_API_KEY).toEqual({ configured: false, writable: true })
+  })
+
   it('emits the todo/write snapshot at the real tool boundary: between tool/call and tool/result, timestamps monotonic', async () => {
     const api = createFixtureApi()
     const tail = await api.sessions.history(req({ sessionId: sid('fx-alpha'), maxMessages: 10 }))
diff --git a/packages/client/ui-models/package.json b/packages/client/ui-models/package.json
index 9909ed3fb8..825e56d359 100644
--- a/packages/client/ui-models/package.json
+++ b/packages/client/ui-models/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-models",
-  "description": "Models feature plugin: registers its Settings section (nav entry, empty content column; model management lands later)",
+  "description": "Models settings and official-DeepSeek first-run credential UI over one live provider/settings/credential join",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -39,6 +39,7 @@
     "@deepseek-ai/dsh-client-connection": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-schema-form": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^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",
@@ -50,6 +51,7 @@
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-schema-form": "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:^",
diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
new file mode 100644
index 0000000000..bce0eafa4d
--- /dev/null
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
@@ -0,0 +1,54 @@
+.dialog {
+  width: min(420px, 100%);
+}
+
+.fields {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.label {
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.input {
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.input > input {
+  width: 100%;
+}
+
+.advanced {
+  align-self: flex-start;
+  padding-inline: 0;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.error {
+  margin: 0;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.diagnostic {
+  margin: 0;
+  font-size: 13px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.primary {
+  width: 100%;
+}
diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
new file mode 100644
index 0000000000..efec759096
--- /dev/null
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
@@ -0,0 +1,186 @@
+/**
+ * Official-DeepSeek first-run dialog. Readiness comes from the same
+ * provider/settings/credential join as the Models page; the component holds
+ * only the write-only draft and viewing state.
+ */
+
+import { useEffect, useState } from 'react'
+import type { ReactNode } from 'react'
+import type { IApiClient } from '@deepseek-ai/dsh-client-connection/client'
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import { Button, Input, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import type { ModelsSettingsState, ModelsSettingsStore } from './store.ts'
+import { deepSeekReadiness } from './store.ts'
+import type { en } from './locales.ts'
+import styles from './DeepSeekOnboardingDialog.module.css'
+
+/** Injected dependencies of {@link DeepSeekOnboardingDialog}. */
+export interface DeepSeekOnboardingInjected {
+  /** Shared Models-page join controller. */
+  controller: ModelsSettingsStore
+  /** Subscription hook bound to the shared join snapshot. */
+  useSnapshot: SnapshotSelectorHook<ModelsSettingsState>
+  /** Write-only credential wire face. */
+  credentials: IApiClient['credentials']
+  /** Feature copy. */
+  t: (key: keyof typeof en) => string
+}
+
+/** Slot owner props plus the feature's injected dependencies. */
+export type DeepSeekOnboardingDialogProps =
+  PropsRuntime<'settings.onboarding'> & DeepSeekOnboardingInjected
+
+/** Remove the submitted non-empty secret from any error text before it reaches the DOM. */
+function redactSecret(message: string, secret: string): string {
+  return message.split(secret).join('[redacted]')
+}
+
+/**
+ * Render the first-run credential dialog while the official adapter exists
+ * and its effective reference is writable but unconfigured.
+ * @param props - settings-shell owner state and Models feature dependencies.
+ * @returns the controlled modal or null when onboarding needs no intervention.
+ */
+export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps): ReactNode {
+  const { active, openSection, controller, useSnapshot, credentials, t } = props
+  const state = useSnapshot(snapshot => snapshot)
+  const readiness = deepSeekReadiness(state)
+  const [dismissed, setDismissed] = useState(false)
+  const [keyDraft, setKeyDraft] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [failure, setFailure] = useState<string | undefined>(undefined)
+
+  useEffect(() => {
+    if (active && !dismissed && state.status === 'idle') void controller.load()
+  }, [active, controller, dismissed, state.status])
+
+  useEffect(() => {
+    if (!active || readiness.kind !== 'credential-missing') {
+      setKeyDraft('')
+      setFailure(undefined)
+    }
+  }, [active, readiness.kind, readiness.kind === 'credential-missing' ? readiness.ref : undefined])
+
+  const close = (): void => {
+    setKeyDraft('')
+    setFailure(undefined)
+    setDismissed(true)
+  }
+
+  const openModels = (): void => {
+    close()
+    openSection('models')
+  }
+
+  const save = async (): Promise<void> => {
+    /* v8 ignore next -- the form only attaches save while missing and disables it for an empty draft */
+    if (readiness.kind !== 'credential-missing' || keyDraft.length === 0) return
+    const secret = keyDraft
+    const ref = readiness.ref
+    setBusy(true)
+    setFailure(undefined)
+    try {
+      const response = await credentials.set({ ref, value: secret })
+      if (!response.result.ok) {
+        setFailure(`${t('onboardingSaveFailed')}: ${redactSecret(response.result.error.message, secret)}`)
+        return
+      }
+      await controller.load()
+      if (deepSeekReadiness(controller.store.getSnapshot()).kind !== 'configured') {
+        setFailure(t('onboardingVerifyFailed'))
+        return
+      }
+      setKeyDraft('')
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      setFailure(`${t('onboardingSaveFailed')}: ${redactSecret(message, secret)}`)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const retry = async (): Promise<void> => {
+    setBusy(true)
+    try {
+      await controller.load()
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  if (!active || dismissed || readiness.kind === 'loading'
+    || readiness.kind === 'adapter-absent' || readiness.kind === 'configured') return null
+
+  const unavailable = readiness.kind === 'unavailable'
+  const diagnostic = unavailable && readiness.reason === 'credentials-unavailable'
+    ? t('onboardingCredentialsUnavailable')
+    : t('onboardingConfigurationUnavailable')
+  const displayName = readiness.kind === 'credential-missing'
+    ? readiness.displayName
+    : 'DeepSeek'
+
+  return (
+    <Modal
+      open
+      onClose={close}
+      title={unavailable ? t('onboardingUnavailableTitle') : t('onboardingTitle')}
+      closeLabel={t('onboardingLater')}
+      {...(unavailable ? {} : { description: t('onboardingDescription') })}
+      className={styles['dialog'] as string}
+      footer={(
+        <Button
+          variant="primary"
+          className={styles['primary']}
+          disabled={busy || (!unavailable && keyDraft.length === 0)}
+          onClick={() => { void (unavailable ? retry() : save()) }}
+        >
+          {busy
+            ? t('onboardingSaving')
+            : unavailable
+              ? t('retry')
+              : t('onboardingSave')}
+        </Button>
+      )}
+    >
+      <div className={styles['fields']}>
+        <label className={styles['field']}>
+          <span className={styles['label']}>{t('provider')}</span>
+          <Input
+            className={styles['input'] as string}
+            type="text"
+            aria-label={t('provider')}
+            value={displayName}
+            readOnly
+          />
+        </label>
+        {readiness.kind === 'credential-missing'
+          ? (
+            <label className={styles['field']}>
+              <span className={styles['label']}>{t('onboardingKey')}</span>
+              <Input
+                className={styles['input'] as string}
+                type="password"
+                autoComplete="off"
+                autoCapitalize="none"
+                spellCheck={false}
+                aria-label={t('onboardingKey')}
+                placeholder={t('onboardingKeyPlaceholder')}
+                value={keyDraft}
+                disabled={busy}
+                onChange={(event) => {
+                  setKeyDraft(event.target.value)
+                  setFailure(undefined)
+                }}
+              />
+            </label>
+          )
+          : <p className={styles['diagnostic']}>{diagnostic}</p>}
+        <Button variant="ghost" size="sm" className={styles['advanced']} onClick={openModels}>
+          {t('onboardingAdvanced')}
+        </Button>
+        {failure !== undefined ? <p className={styles['error']} role="alert">{failure}</p> : null}
+      </div>
+    </Modal>
+  )
+}
diff --git a/packages/client/ui-models/src/client/ModelsSection.tsx b/packages/client/ui-models/src/client/ModelsSection.tsx
index 7a08441ea9..b76341abed 100644
--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-models/src/client/ModelsSection.tsx
@@ -68,7 +68,7 @@ function StatusBadges({ row, t }: { row: ProviderRow; t: ModelsSectionInjected['
       {row.entry.active
         ? <span className={styles['badgeOk']}>{t('active')}</span>
         : <span className={styles['badgeMuted']}>{t('dormant')}</span>}
-      {row.credential !== undefined && !row.credential.configured
+      {!row.literalApiKeyConfigured && row.credential !== undefined && !row.credential.configured
         ? <span className={styles['badgeWarn']}>{t('keyMissing')}</span>
         : null}
     </span>
diff --git a/packages/client/ui-models/src/client/index.ts b/packages/client/ui-models/src/client/index.ts
index de260dec88..a6ee6478db 100644
--- a/packages/client/ui-models/src/client/index.ts
+++ b/packages/client/ui-models/src/client/index.ts
@@ -1,9 +1,9 @@
 /**
- * Models settings section plugin, browser half. Registers the `models` nav
- * entry into the shell-declared `settings.section` list slot and mounts the
- * provider configuration page: the configurable-provider directory joined
- * with settings namespaces and credential states, edited through the
- * schema-driven form. Export discipline: packages/client/AGENTS.md.
+ * Models settings plugin, browser half. Registers the `models` nav entry and
+ * official-DeepSeek first-run overlay into shell-declared slots. Both consume
+ * one provider/settings/credential join; the full page edits through the
+ * schema-driven form while onboarding exposes only write-only credential
+ * setup. Export discipline: packages/client/AGENTS.md.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
@@ -15,6 +15,8 @@ import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import { ModelsSection } from './ModelsSection.tsx'
 import type { ModelsSectionInjected } from './ModelsSection.tsx'
+import { DeepSeekOnboardingDialog } from './DeepSeekOnboardingDialog.tsx'
+import type { DeepSeekOnboardingInjected } from './DeepSeekOnboardingDialog.tsx'
 import { ModelsSettingsStore } from './store.ts'
 import { en, zh } from './locales.ts'
 
@@ -63,6 +65,12 @@ export function apply(ctx: ClientContext): void {
     api: connection.api,
     t,
   })
+  const onboardingInjected = (): DeepSeekOnboardingInjected => ({
+    controller,
+    useSnapshot,
+    credentials: connection.api.credentials,
+    t,
+  })
 
   // Pushed invalidations converge every open surface without polling: any
   // settings/credentials/topology change refetches once the page loaded.
@@ -78,7 +86,7 @@ export function apply(ctx: ClientContext): void {
   }, 'ui-models: pushed invalidations')
 
   ctx.effect(() => {
-    const deferred = deferRegistration(ctx.slots, 'settings.section', ModelsSection, () =>
+    const section = deferRegistration(ctx.slots, 'settings.section', ModelsSection, () =>
       ctx.slots.register({
         name: 'settings.section',
         id: 'models',
@@ -86,12 +94,27 @@ export function apply(ctx: ClientContext): void {
         label: t('nav'),
         inject: injected,
       }, ModelsSection))
+    const onboarding = deferRegistration(
+      ctx.slots,
+      'settings.onboarding',
+      DeepSeekOnboardingDialog,
+      () => ctx.slots.register({
+        name: 'settings.onboarding',
+        id: 'deepseek-official',
+        order: 0,
+        inject: onboardingInjected,
+      }, DeepSeekOnboardingDialog),
+    )
     // Nav labels are registrant-localized: refresh on locale change so the
     // ledger carries fresh text (the version bump re-renders the shell).
-    const offLocale = ctx.on('locale/change', () => { deferred.refresh() })
+    const offLocale = ctx.on('locale/change', () => {
+      section.refresh()
+      onboarding.refresh()
+    })
     return () => {
       offLocale()
-      deferred.dispose()
+      section.dispose()
+      onboarding.dispose()
     }
-  }, 'ui-models: settings section registration')
+  }, 'ui-models: settings registrations')
 }
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index da525dcb5e..7dd377a1e6 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -33,6 +33,19 @@ export const en = {
   secretUnset: 'Not configured',
   inherited: 'Default',
   unsupported: 'This field has no form control; edit the settings document directly.',
+  onboardingTitle: 'Add a DeepSeek API key',
+  onboardingDescription: 'Configure the official DeepSeek provider to start building.',
+  onboardingKey: 'API key',
+  onboardingKeyPlaceholder: 'Enter your DeepSeek API key',
+  onboardingAdvanced: 'Advanced model settings',
+  onboardingSave: 'Save and continue',
+  onboardingSaving: 'Saving…',
+  onboardingLater: 'Configure later',
+  onboardingSaveFailed: 'Could not save the API key',
+  onboardingVerifyFailed: 'The key was saved, but its configured state could not be verified. Try again.',
+  onboardingUnavailableTitle: 'DeepSeek setup is unavailable',
+  onboardingCredentialsUnavailable: 'This deployment does not expose writable credential storage. Mount @deepseek-ai/dsh-credentials-local, then retry.',
+  onboardingConfigurationUnavailable: 'The live DeepSeek configuration capability cannot be resolved here. Check the deployment composition, then retry.',
 }
 
 /** Chinese strings (same keys as {@link en}). */
@@ -68,4 +81,17 @@ export const zh: typeof en = {
   secretUnset: '未设置',
   inherited: '默认',
   unsupported: '该字段没有对应表单控件；请直接编辑设置文档。',
+  onboardingTitle: '添加 DeepSeek API 密钥',
+  onboardingDescription: '配置 DeepSeek 官方模型，即可开始使用。',
+  onboardingKey: 'API 密钥',
+  onboardingKeyPlaceholder: '输入 DeepSeek API 密钥',
+  onboardingAdvanced: '模型高级设置',
+  onboardingSave: '保存并继续',
+  onboardingSaving: '保存中…',
+  onboardingLater: '稍后配置',
+  onboardingSaveFailed: '无法保存 API 密钥',
+  onboardingVerifyFailed: '密钥已写入，但无法确认配置状态。请重试。',
+  onboardingUnavailableTitle: '无法在此配置 DeepSeek',
+  onboardingCredentialsUnavailable: '当前部署没有可写的凭据存储。请挂载 @deepseek-ai/dsh-credentials-local 后重试。',
+  onboardingConfigurationUnavailable: '无法在此解析 DeepSeek 的实时配置能力。请检查部署组合后重试。',
 }
diff --git a/packages/client/ui-models/src/client/store.ts b/packages/client/ui-models/src/client/store.ts
index 13b1d611df..44fd256f16 100644
--- a/packages/client/ui-models/src/client/store.ts
+++ b/packages/client/ui-models/src/client/store.ts
@@ -25,6 +25,8 @@ export interface ProviderRow {
   apiKeyEnv: string | undefined
   /** Credential state for {@link apiKeyEnv}, once described. */
   credential: CredentialView | undefined
+  /** Whether the redacted secret sidecar reports an effective literal `apiKey`. */
+  literalApiKeyConfigured: boolean
 }
 
 /** Page snapshot. */
@@ -32,6 +34,8 @@ export interface ModelsSettingsState {
   status: 'idle' | 'loading' | 'ready' | 'error'
   /** Whole-load failure text; row-level write failures stay in the editor. */
   error: string | null
+  /** Credential enrichment failure; provider/settings rows remain usable. */
+  credentialError: string | null
   /** Whether the settings provider accepts writes. */
   writable: boolean
   /** Every configurable provider joined with its configured/credential state. */
@@ -49,11 +53,29 @@ function apiKeyEnvOf(namespace: SettingsNamespaceView | undefined, path: readonl
   return typeof ref === 'string' && ref.length > 0 ? ref : undefined
 }
 
+/** Whether one namespace's redacted sidecar reports a set literal API key. */
+function literalApiKeyConfigured(
+  namespace: SettingsNamespaceView | undefined,
+  path: readonly string[],
+): boolean {
+  if (namespace === undefined) return false
+  const secretPath = [...path, 'apiKey']
+  return namespace.secrets.some(secret =>
+    secret.set
+    && secret.path.length === secretPath.length
+    && secret.path.every((key, index) => key === secretPath[index]))
+}
+
+/** Safe display text for a rejected transport or business response. */
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
 /** The models settings page controller (one per settings surface). */
 export class ModelsSettingsStore {
   /** The snapshot the section renders from (uSES-safe store). */
   readonly store: SnapshotStore<ModelsSettingsState> = createSnapshotStore<ModelsSettingsState>({
-    status: 'idle', error: null, writable: false, rows: [], namespaces: new Map(),
+    status: 'idle', error: null, credentialError: null, writable: false, rows: [], namespaces: new Map(),
   })
 
   /** Latest load wins; an older response never overwrites a newer one. */
@@ -109,20 +131,28 @@ export class ModelsSettingsStore {
         removable,
         apiKeyEnv: apiKeyEnvOf(namespace, entry.settingsPath),
         credential: undefined,
+        literalApiKeyConfigured: literalApiKeyConfigured(namespace, entry.settingsPath),
       }
     })
     const refs = [...new Set(rows.flatMap(row => row.apiKeyEnv === undefined ? [] : [row.apiKeyEnv]))]
     let credentials: Record<string, CredentialView> = {}
+    let credentialError: string | null = null
     if (refs.length > 0) {
-      const response = await this.api.credentials.describe({ refs })
-      // Credential state is an enrichment: rows render without it, so a
-      // missing credential provider degrades the badge, not the page.
-      if (response.result.ok) credentials = response.result.value.credentials
+      try {
+        const response = await this.api.credentials.describe({ refs })
+        // Credential state is an enrichment for the Models page, while the
+        // onboarding readiness projection below reports its failure.
+        if (response.result.ok) credentials = response.result.value.credentials
+        else credentialError = response.result.error.message
+      } catch (error) {
+        credentialError = errorText(error)
+      }
     }
     if (generation !== this.generation) return
     this.store.update((s) => {
       s.status = 'ready'
       s.error = null
+      s.credentialError = credentialError
       s.writable = writable
       s.rows = rows.map(row => ({
         ...row,
@@ -134,3 +164,98 @@ export class ModelsSettingsStore {
     })
   }
 }
+
+/** DeepSeek onboarding readiness derived only from the shared Models join. */
+export type DeepSeekReadiness =
+  | { kind: 'loading' }
+  | { kind: 'adapter-absent' }
+  | { kind: 'configured'; source: 'literal' | 'credential'; ref?: string; credential?: CredentialView }
+  | { kind: 'credential-missing'; displayName: string; ref: string }
+  | {
+    kind: 'unavailable'
+    reason:
+      | 'provider-inactive'
+      | 'settings-unavailable'
+      | 'credential-ref-unavailable'
+      | 'credentials-unavailable'
+      | 'credential-read-only'
+    message: string
+  }
+
+/**
+ * Project official-DeepSeek readiness from the provider/settings/credential
+ * join used by the Models page. A missing directory entry means the adapter
+ * is not mounted and therefore cannot be repaired by a key form.
+ * @param state - current shared Models join snapshot.
+ * @returns the onboarding state without reading a parallel fact source.
+ */
+export function deepSeekReadiness(state: ModelsSettingsState): DeepSeekReadiness {
+  if ((state.status === 'idle' || state.status === 'loading') && state.rows.length === 0) {
+    return { kind: 'loading' }
+  }
+  if (state.status === 'error') {
+    return {
+      kind: 'unavailable',
+      reason: 'settings-unavailable',
+      message: state.error ?? 'provider/settings describe failed',
+    }
+  }
+  const row = state.rows.find(candidate => candidate.entry.provider === 'deepseek-official')
+  if (row === undefined) return { kind: 'adapter-absent' }
+  if (!row.entry.active) {
+    return {
+      kind: 'unavailable',
+      reason: 'provider-inactive',
+      message: 'the deepseek-official route is not active',
+    }
+  }
+  if (!row.configured) {
+    return {
+      kind: 'unavailable',
+      reason: 'settings-unavailable',
+      message: `settings namespace "${row.entry.settingsNs}" did not resolve the provider profile`,
+    }
+  }
+  if (row.literalApiKeyConfigured) return { kind: 'configured', source: 'literal' }
+  if (row.apiKeyEnv === undefined) {
+    return {
+      kind: 'unavailable',
+      reason: 'credential-ref-unavailable',
+      message: 'the resolved DeepSeek settings do not name an apiKeyEnv credential reference',
+    }
+  }
+  if (state.credentialError !== null) {
+    return {
+      kind: 'unavailable',
+      reason: 'credentials-unavailable',
+      message: state.credentialError,
+    }
+  }
+  if (row.credential === undefined) {
+    return {
+      kind: 'unavailable',
+      reason: 'credentials-unavailable',
+      message: `credential reference "${row.apiKeyEnv}" was not described`,
+    }
+  }
+  if (row.credential.configured) {
+    return {
+      kind: 'configured',
+      source: 'credential',
+      ref: row.apiKeyEnv,
+      credential: row.credential,
+    }
+  }
+  if (!row.credential.writable) {
+    return {
+      kind: 'unavailable',
+      reason: 'credential-read-only',
+      message: `credential reference "${row.apiKeyEnv}" is missing and read-only`,
+    }
+  }
+  return {
+    kind: 'credential-missing',
+    displayName: row.entry.displayName,
+    ref: row.apiKeyEnv,
+  }
+}
diff --git a/packages/client/ui-models/tests/apply.spec.ts b/packages/client/ui-models/tests/apply.spec.ts
index 7b05930d98..c247960cc4 100644
--- a/packages/client/ui-models/tests/apply.spec.ts
+++ b/packages/client/ui-models/tests/apply.spec.ts
@@ -1,10 +1,11 @@
 /** Models section registration: declaration-aware deferral, locale re-registration, 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, refreshIfLoaded } from '@deepseek-ai/dsh-client-ui-models/client'
 import { ModelsSection } from '../src/client/ModelsSection.tsx'
+import { DeepSeekOnboardingDialog } from '../src/client/DeepSeekOnboardingDialog.tsx'
 
 async function bench() {
   const ctx = new Context()
@@ -19,7 +20,13 @@ async function bench() {
 
 function declare(slots: SlotsService): () => void {
   return slots.register(
-    { name: 'root', children: { 'settings.section': { kind: 'list', scope: 'root' } } } as never,
+    {
+      name: 'root',
+      children: {
+        'settings.section': { kind: 'list', scope: 'root' },
+        'settings.onboarding': { kind: 'list', scope: 'root' },
+      },
+    } as never,
     () => null,
   )
 }
@@ -41,13 +48,18 @@ describe('ui-models apply', () => {
     expect(typeof injected.controller.load).toBe('function')
     expect(typeof injected.useSnapshot).toBe('function')
     expect(injected.api).toBeDefined()
+    const onboarding = before.slots.entries('settings.onboarding')[0]!
+    expect(onboarding.component).toBe(DeepSeekOnboardingDialog)
+    expect(onboarding.options).toMatchObject({ id: 'deepseek-official', order: 0 })
 
     const after = await bench()
     await after.ctx.plugin({ inject: [...inject], apply }).await()
     expect(after.slots.entries('settings.section')).toHaveLength(0)
+    expect(after.slots.entries('settings.onboarding')).toHaveLength(0)
     declare(after.slots)
     await Promise.resolve()
     expect(after.slots.entries('settings.section')[0]!.component).toBe(ModelsSection)
+    expect(after.slots.entries('settings.onboarding')[0]!.component).toBe(DeepSeekOnboardingDialog)
     // The self-inflicted ledger notifications hit the duplicate guard.
     expect(after.slots.entries('settings.section')).toHaveLength(1)
   })
@@ -79,9 +91,11 @@ describe('ui-models apply', () => {
     // disposer variable goes stale.
     redeclare()
     expect(b.slots.entries('settings.section')).toHaveLength(0)
+    expect(b.slots.entries('settings.onboarding')).toHaveLength(0)
     declare(b.slots)
     await Promise.resolve()
     expect(b.slots.entries('settings.section')[0]!.component).toBe(ModelsSection)
+    expect(b.slots.entries('settings.onboarding')[0]!.component).toBe(DeepSeekOnboardingDialog)
     // The locale path also recovers through the same ledger re-check.
     b.locale.setLocale('en')
     expect(b.slots.entries('settings.section')[0]!.options.label).toBe('Models')
@@ -96,6 +110,7 @@ describe('ui-models apply', () => {
     expect(b.locale.bind('settings.models')('nav')).toBe('模型')
     await fiber.dispose()
     expect(b.slots.entries('settings.section')).toHaveLength(0)
+    expect(b.slots.entries('settings.onboarding')).toHaveLength(0)
     // The (ns, locale) seats are free again — the dictionary disposers ran.
     expect(() => b.locale.register('settings.models', 'zh', {})).not.toThrow()
     expect(() => b.locale.register('settings.models', 'en', {})).not.toThrow()
@@ -129,4 +144,18 @@ describe('pushed invalidations', () => {
     refreshIfLoaded(idle as unknown as import('../src/client/store.ts').ModelsSettingsStore)
     expect(loads).toHaveLength(1)
   })
+
+  it('routes pushed credential invalidation into the shared onboarding join', async () => {
+    const b = await bench()
+    declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const injected = (
+      b.slots.entries('settings.onboarding')[0]!.inject as unknown as
+      () => import('../src/client/DeepSeekOnboardingDialog.tsx').DeepSeekOnboardingInjected
+    )()
+    injected.controller.store.update((state) => { state.status = 'ready' })
+    const load = vi.spyOn(injected.controller, 'load').mockResolvedValue()
+    b.ctx.emit('credentials/changed', 'DEEPSEEK_API_KEY')
+    expect(load).toHaveBeenCalledTimes(1)
+  })
 })
diff --git a/packages/client/ui-models/tests/components.spec.tsx b/packages/client/ui-models/tests/components.spec.tsx
index 32d4eb73b6..a8f0f227b6 100644
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -6,7 +6,7 @@ import Schema from 'schemastery'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import type { RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-client-connection/client'
 import { ModelsSection, removeProviderProfile } from '../src/client/ModelsSection.tsx'
-import type { ModelsSectionInjected } from '../src/client/ModelsSection.tsx'
+import type { ModelsSectionInjected, ModelsSectionProps } from '../src/client/ModelsSection.tsx'
 import { ModelsSettingsStore } from '../src/client/store.ts'
 import { en } from '../src/client/locales.ts'
 
@@ -121,6 +121,12 @@ async function mountSection(overrides: Parameters<typeof scriptedFace>[0] = {})
 }
 
 describe('ModelsSection', () => {
+  it('renders nothing before the slot injects its dependencies', () => {
+    const uninjected = {} as ModelsSectionProps
+    render(<ModelsSection {...uninjected} />)
+    expect(document.body.textContent).toBe('')
+  })
+
   it('renders configured rows with status badges and the add vocabulary', async () => {
     await mountSection()
     expect(screen.getByText('DeepSeek')).toBeTruthy()
@@ -135,6 +141,16 @@ describe('ModelsSection', () => {
     expect(screen.getAllByText(en.remove)).toHaveLength(2)
   })
 
+  it('does not mark a provider with a configured literal key as missing', async () => {
+    const { controller } = await mountSection()
+    controller.store.update((state) => {
+      state.rows = state.rows.map(row => row.entry.provider === 'deepseek-official'
+        ? { ...row, literalApiKeyConfigured: true }
+        : row)
+    })
+    await waitFor(() => { expect(screen.queryByText(en.keyMissing)).toBeNull() })
+  })
+
   it('opens the editor, applies an edit as a merge patch, and reloads', async () => {
     const { update, face } = await mountSection()
     fireEvent.click(screen.getAllByText(en.edit)[1] as HTMLElement)
diff --git a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
new file mode 100644
index 0000000000..fa4fd1dac2
--- /dev/null
+++ b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
@@ -0,0 +1,265 @@
+// @vitest-environment jsdom
+/** First-run DeepSeek dialog behavior over the shared Models join. */
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { RpcResponse } from '@deepseek-ai/dsh-client-connection/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import { DeepSeekOnboardingDialog } from '../src/client/DeepSeekOnboardingDialog.tsx'
+import type { DeepSeekOnboardingDialogProps } from '../src/client/DeepSeekOnboardingDialog.tsx'
+import { ModelsSettingsStore } from '../src/client/store.ts'
+import { en } from '../src/client/locales.ts'
+
+afterEach(cleanup)
+
+let nextRpc = 0
+function ok<T>(value: T): RpcResponse<T> {
+  return { rpcId: `onboarding-${nextRpc++}` as never, result: { ok: true, value } }
+}
+function fail<T>(message: string): RpcResponse<T> {
+  return {
+    rpcId: `onboarding-${nextRpc++}` as never,
+    result: { ok: false, error: { code: 'internal', message, details: {} } },
+  }
+}
+
+function harness(options: {
+  provider?: boolean
+  literal?: boolean
+  configured?: () => boolean
+  credential?: { source?: string; writable: boolean }
+  describeFailure?: string
+  set?: (payload: { ref: string; value: string }) => Promise<RpcResponse<{}>>
+} = {}) {
+  let fileConfigured = false
+  const configured = options.configured ?? (() => fileConfigured)
+  const set = vi.fn(options.set ?? ((payload: { ref: string; value: string }) => {
+    fileConfigured = payload.value.length > 0
+    return Promise.resolve(ok({}))
+  }))
+  const face = {
+    llm: {
+      providers: () => Promise.resolve(ok({
+        providers: options.provider === false
+          ? []
+          : [{
+            provider: 'deepseek-official',
+            displayName: 'DeepSeek',
+            settingsNs: 'llm-deepseek',
+            settingsPath: [],
+            active: true,
+          }],
+      })),
+    },
+    settings: {
+      describe: () => Promise.resolve(ok({
+        writable: true,
+        namespaces: [{
+          ns: 'llm-deepseek',
+          schema: {},
+          value: { apiKeyEnv: 'DEEPSEEK_API_KEY' },
+          applies: 'live' as const,
+          secrets: [{ path: ['apiKey'], set: options.literal === true }],
+        }],
+      })),
+    },
+    credentials: {
+      describe: () => options.describeFailure === undefined
+        ? Promise.resolve(ok({
+          credentials: {
+            DEEPSEEK_API_KEY: {
+              configured: configured(),
+              ...configured() && options.credential?.source !== undefined
+                ? { source: options.credential.source }
+                : {},
+              writable: options.credential?.writable ?? true,
+            },
+          },
+        }))
+        : Promise.resolve(fail(options.describeFailure)),
+      set,
+    },
+  }
+  const controller = new ModelsSettingsStore(face as never)
+  const openSection = vi.fn()
+  const unusedHook = (() => { throw new Error('unused standard hook') }) as never
+  const props: DeepSeekOnboardingDialogProps = {
+    active: true,
+    openSection,
+    useSessions: unusedHook,
+    useWorkspaces: unusedHook,
+    controller,
+    useSnapshot: bindSnapshotSelector(controller.store),
+    credentials: face.credentials as never,
+    t: key => en[key],
+  }
+  return { controller, face, openSection, props, set, configure: () => { fileConfigured = true } }
+}
+
+describe('DeepSeekOnboardingDialog', () => {
+  it('loads on first entry and presents an accessible write-only key form', async () => {
+    const h = harness()
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    const dialog = await screen.findByRole('dialog', { name: en.onboardingTitle })
+    expect(dialog).toBeTruthy()
+    expect(screen.getByLabelText<HTMLInputElement>(en.provider).value).toBe('DeepSeek')
+    const key = screen.getByLabelText<HTMLInputElement>(en.onboardingKey)
+    expect(key.type).toBe('password')
+    expect(key.autocomplete).toBe('off')
+    expect(key.getAttribute('spellcheck')).toBe('false')
+  })
+
+  it('stores through credentials.set, verifies through describe, clears the draft, and closes', async () => {
+    const h = harness()
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    const key = await screen.findByLabelText<HTMLInputElement>(en.onboardingKey)
+    const secret = 'test-onboarding-secret'
+    fireEvent.change(key, { target: { value: secret } })
+    fireEvent.click(screen.getByRole('button', { name: en.onboardingSave }))
+    await waitFor(() => { expect(screen.queryByRole('dialog')).toBeNull() })
+    expect(h.set).toHaveBeenCalledWith({ ref: 'DEEPSEEK_API_KEY', value: secret })
+    expect(document.body.textContent).not.toContain(secret)
+    expect(document.documentElement.outerHTML).not.toContain(secret)
+  })
+
+  it('keeps a business failure open without echoing the secret', async () => {
+    const secret = 'business-secret'
+    const h = harness({
+      set: payload => Promise.resolve(fail(`refused ${payload.value}`)),
+    })
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    const key = await screen.findByLabelText<HTMLInputElement>(en.onboardingKey)
+    fireEvent.change(key, { target: { value: secret } })
+    fireEvent.click(screen.getByRole('button', { name: en.onboardingSave }))
+    const alert = await screen.findByRole('alert')
+    expect(alert.textContent).toContain('[redacted]')
+    expect(alert.textContent).not.toContain(secret)
+    expect(screen.getByRole<HTMLButtonElement>('button', { name: en.onboardingSave }).disabled).toBe(false)
+    expect(screen.getByRole('dialog')).toBeTruthy()
+    fireEvent.change(key, { target: { value: 'replacement' } })
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+
+  it('shows saving state and reports a failed configured-state verification', async () => {
+    let settle: (() => void) | undefined
+    const pending = new Promise<void>((resolve) => { settle = resolve })
+    const h = harness({
+      set: async () => {
+        await pending
+        return ok({})
+      },
+    })
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    fireEvent.change(await screen.findByLabelText(en.onboardingKey), { target: { value: 'verify-secret' } })
+    fireEvent.click(screen.getByRole('button', { name: en.onboardingSave }))
+    expect(screen.getByRole('button', { name: en.onboardingSaving })).toBeTruthy()
+    settle?.()
+    expect((await screen.findByRole('alert')).textContent).toBe(en.onboardingVerifyFailed)
+    expect(screen.getByRole<HTMLButtonElement>('button', { name: en.onboardingSave }).disabled).toBe(false)
+  })
+
+  it('recovers busy state after a transport rejection without an unhandled rejection', async () => {
+    const secret = 'transport-secret'
+    const h = harness({
+      set: () => Promise.reject(new Error(`transport rejected ${secret}`)),
+    })
+    const unhandled = vi.fn()
+    window.addEventListener('unhandledrejection', unhandled)
+    try {
+      render(<DeepSeekOnboardingDialog {...h.props} />)
+      const key = await screen.findByLabelText<HTMLInputElement>(en.onboardingKey)
+      fireEvent.change(key, { target: { value: secret } })
+      fireEvent.click(screen.getByRole('button', { name: en.onboardingSave }))
+      const alert = await screen.findByRole('alert')
+      expect(alert.textContent).not.toContain(secret)
+      expect(screen.getByRole<HTMLButtonElement>('button', { name: en.onboardingSave }).disabled).toBe(false)
+      expect(unhandled).not.toHaveBeenCalled()
+    } finally {
+      window.removeEventListener('unhandledrejection', unhandled)
+    }
+  })
+
+  it('stringifies a non-Error transport rejection without exposing its secret', async () => {
+    const secret = 'plain-rejection-secret'
+    const h = harness({
+      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+      set: () => Promise.reject(`transport refused ${secret}`),
+    })
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    fireEvent.change(await screen.findByLabelText(en.onboardingKey), { target: { value: secret } })
+    fireEvent.click(screen.getByRole('button', { name: en.onboardingSave }))
+    const alert = await screen.findByRole('alert')
+    expect(alert.textContent).toContain('[redacted]')
+    expect(alert.textContent).not.toContain(secret)
+  })
+
+  it('cancels without writing and opens the Models section through the owner callback', async () => {
+    const cancelled = harness()
+    const first = render(<DeepSeekOnboardingDialog {...cancelled.props} />)
+    await screen.findByRole('dialog')
+    fireEvent.click(screen.getByRole('button', { name: en.onboardingLater }))
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(cancelled.set).not.toHaveBeenCalled()
+    first.unmount()
+
+    const advanced = harness()
+    render(<DeepSeekOnboardingDialog {...advanced.props} />)
+    await screen.findByRole('dialog')
+    fireEvent.click(screen.getByRole('button', { name: en.onboardingAdvanced }))
+    expect(advanced.openSection).toHaveBeenCalledWith('models')
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(advanced.set).not.toHaveBeenCalled()
+  })
+
+  it('shows an actionable deployment diagnostic when credentials are unavailable', async () => {
+    const h = harness({ describeFailure: 'credentials service is absent' })
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
+    expect(screen.getByText(en.onboardingCredentialsUnavailable)).toBeTruthy()
+    expect(screen.queryByLabelText(en.onboardingKey)).toBeNull()
+    fireEvent.click(screen.getByRole('button', { name: en.retry }))
+    await waitFor(() => {
+      expect(screen.getByRole<HTMLButtonElement>('button', { name: en.retry }).disabled).toBe(false)
+    })
+  })
+
+  it('uses the deployment diagnostic for a missing read-only credential', async () => {
+    const h = harness({ credential: { writable: false } })
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
+    expect(screen.getByText(en.onboardingConfigurationUnavailable)).toBeTruthy()
+    expect(screen.queryByLabelText(en.onboardingKey)).toBeNull()
+  })
+
+  it('skips an absent adapter and already-configured literal or environment credentials', async () => {
+    for (const h of [
+      harness({ provider: false }),
+      harness({ literal: true, describeFailure: 'credential seam absent' }),
+      harness({ configured: () => true, credential: { source: 'env', writable: false } }),
+    ]) {
+      const view = render(<DeepSeekOnboardingDialog {...h.props} />)
+      await act(async () => { await h.controller.load() })
+      expect(screen.queryByRole('dialog')).toBeNull()
+      view.unmount()
+    }
+  })
+
+  it('closes when an external credential invalidation refreshes the shared join', async () => {
+    const h = harness()
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    await screen.findByRole('dialog')
+    h.configure()
+    await act(async () => { await h.controller.load() })
+    await waitFor(() => { expect(screen.queryByRole('dialog')).toBeNull() })
+  })
+
+  it('clears a typed draft when the onboarding owner becomes inactive', async () => {
+    const h = harness()
+    const view = render(<DeepSeekOnboardingDialog {...h.props} />)
+    const key = await screen.findByLabelText<HTMLInputElement>(en.onboardingKey)
+    fireEvent.change(key, { target: { value: 'ephemeral' } })
+    view.rerender(<DeepSeekOnboardingDialog {...h.props} active={false} />)
+    expect(screen.queryByRole('dialog')).toBeNull()
+    view.rerender(<DeepSeekOnboardingDialog {...h.props} active />)
+    expect((await screen.findByLabelText<HTMLInputElement>(en.onboardingKey)).value).toBe('')
+  })
+})
diff --git a/packages/client/ui-models/tests/readiness.spec.ts b/packages/client/ui-models/tests/readiness.spec.ts
new file mode 100644
index 0000000000..275c3ad4cf
--- /dev/null
+++ b/packages/client/ui-models/tests/readiness.spec.ts
@@ -0,0 +1,112 @@
+/** Pure official-DeepSeek readiness projection over the shared Models join. */
+import { describe, expect, it } from 'vitest'
+import type { CredentialView } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelsSettingsState, ProviderRow } from '../src/client/store.ts'
+import { deepSeekReadiness } from '../src/client/store.ts'
+
+const missingCredential: CredentialView = { configured: false, writable: true }
+
+function row(overrides: Partial<ProviderRow> = {}): ProviderRow {
+  return {
+    entry: {
+      provider: 'deepseek-official',
+      displayName: 'DeepSeek',
+      settingsNs: 'llm-deepseek',
+      settingsPath: [],
+      active: true,
+    },
+    configured: true,
+    removable: false,
+    apiKeyEnv: 'DEEPSEEK_API_KEY',
+    credential: missingCredential,
+    literalApiKeyConfigured: false,
+    ...overrides,
+  }
+}
+
+function state(overrides: Partial<ModelsSettingsState> = {}): ModelsSettingsState {
+  return {
+    status: 'ready',
+    error: null,
+    credentialError: null,
+    writable: true,
+    rows: [row()],
+    namespaces: new Map(),
+    ...overrides,
+  }
+}
+
+describe('deepSeekReadiness', () => {
+  it('waits for the first join and skips onboarding when the adapter directory entry is absent', () => {
+    expect(deepSeekReadiness(state({ status: 'idle', rows: [] }))).toEqual({ kind: 'loading' })
+    expect(deepSeekReadiness(state({ status: 'loading', rows: [] }))).toEqual({ kind: 'loading' })
+    expect(deepSeekReadiness(state({ rows: [] }))).toEqual({ kind: 'adapter-absent' })
+  })
+
+  it('addresses the effective credential reference when it is missing and writable', () => {
+    expect(deepSeekReadiness(state())).toEqual({
+      kind: 'credential-missing',
+      displayName: 'DeepSeek',
+      ref: 'DEEPSEEK_API_KEY',
+    })
+  })
+
+  it('accepts file and process-environment credentials without prompting', () => {
+    expect(deepSeekReadiness(state({
+      rows: [row({ credential: { configured: true, source: 'file', writable: true } })],
+    }))).toMatchObject({
+      kind: 'configured',
+      source: 'credential',
+      ref: 'DEEPSEEK_API_KEY',
+      credential: { source: 'file', writable: true },
+    })
+    expect(deepSeekReadiness(state({
+      rows: [row({ credential: { configured: true, source: 'env', writable: false } })],
+    }))).toMatchObject({
+      kind: 'configured',
+      source: 'credential',
+      credential: { source: 'env', writable: false },
+    })
+  })
+
+  it('accepts the redacted literal-key sidecar before judging the credential domain', () => {
+    expect(deepSeekReadiness(state({
+      credentialError: 'credentials service absent',
+      rows: [row({ literalApiKeyConfigured: true, credential: undefined })],
+    }))).toEqual({ kind: 'configured', source: 'literal' })
+  })
+
+  it('turns missing capabilities and inconsistent descriptors into diagnostics', () => {
+    expect(deepSeekReadiness(state({ status: 'error', error: 'settings down' }))).toEqual({
+      kind: 'unavailable',
+      reason: 'settings-unavailable',
+      message: 'settings down',
+    })
+    expect(deepSeekReadiness(state({ status: 'error', error: null }))).toMatchObject({
+      kind: 'unavailable',
+      reason: 'settings-unavailable',
+    })
+    expect(deepSeekReadiness(state({
+      rows: [row({ entry: { ...row().entry, active: false } })],
+    }))).toMatchObject({ kind: 'unavailable', reason: 'provider-inactive' })
+    expect(deepSeekReadiness(state({
+      rows: [row({ configured: false })],
+    }))).toMatchObject({ kind: 'unavailable', reason: 'settings-unavailable' })
+    expect(deepSeekReadiness(state({
+      rows: [row({ apiKeyEnv: undefined })],
+    }))).toMatchObject({ kind: 'unavailable', reason: 'credential-ref-unavailable' })
+    expect(deepSeekReadiness(state({
+      credentialError: 'credentials service is absent',
+    }))).toMatchObject({
+      kind: 'unavailable',
+      reason: 'credentials-unavailable',
+      message: 'credentials service is absent',
+    })
+    expect(deepSeekReadiness(state({
+      rows: [row({ credential: undefined })],
+    }))).toMatchObject({ kind: 'unavailable', reason: 'credentials-unavailable' })
+    expect(deepSeekReadiness(state({
+      rows: [row({ credential: { configured: false, writable: false } })],
+    }))).toMatchObject({ kind: 'unavailable', reason: 'credential-read-only' })
+  })
+})
diff --git a/packages/client/ui-models/tests/store.spec.ts b/packages/client/ui-models/tests/store.spec.ts
index eadeb0d913..d5e50b474a 100644
--- a/packages/client/ui-models/tests/store.spec.ts
+++ b/packages/client/ui-models/tests/store.spec.ts
@@ -75,6 +75,7 @@ describe('ModelsSettingsStore', () => {
     const state = store.store.getSnapshot()
     expect(state.status).toBe('ready')
     expect(state.writable).toBe(true)
+    expect(state.credentialError).toBeNull()
     expect(seenRefs).toEqual([['DEEPSEEK_API_KEY', 'OPENAI_API_KEY']])
     const byProvider = new Map(state.rows.map(row => [row.entry.provider, row]))
     expect(byProvider.get('deepseek-official')).toMatchObject({
@@ -82,6 +83,7 @@ describe('ModelsSettingsStore', () => {
       removable: false,
       apiKeyEnv: 'DEEPSEEK_API_KEY',
       credential: { configured: false, writable: true },
+      literalApiKeyConfigured: false,
     })
     expect(byProvider.get('openai')).toMatchObject({
       configured: true,
@@ -101,9 +103,55 @@ describe('ModelsSettingsStore', () => {
     await store.load()
     const state = store.store.getSnapshot()
     expect(state.status).toBe('ready')
+    expect(state.credentialError).toBe('no provider')
     expect(state.rows.every(row => row.credential === undefined)).toBe(true)
   })
 
+  it('settles a credential transport rejection without leaving the store loading', async () => {
+    const { face } = api({
+      describeCredentials: () => Promise.reject(new Error('credential transport down')),
+    })
+    const store = new ModelsSettingsStore(face)
+    await expect(store.load()).resolves.toBeUndefined()
+    expect(store.store.getSnapshot()).toMatchObject({
+      status: 'ready',
+      credentialError: 'credential transport down',
+    })
+  })
+
+  it('stringifies a non-Error credential transport rejection', async () => {
+    const { face } = api({
+      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+      describeCredentials: () => Promise.reject('credential transport refusal'),
+    })
+    const store = new ModelsSettingsStore(face)
+    await expect(store.load()).resolves.toBeUndefined()
+    expect(store.store.getSnapshot().credentialError).toBe('credential transport refusal')
+  })
+
+  it('joins a configured literal key from the redacted secret sidecar', async () => {
+    const { face } = api({
+      describeSettings: () => Promise.resolve(ok({
+        writable: true,
+        namespaces: [{
+          ...NAMESPACES[0],
+          secrets: [
+            { path: ['apiKey', 'nested'], set: true },
+            { path: ['different'], set: true },
+            { path: ['apiKey'], set: true },
+          ],
+        }] as never,
+      })),
+      providers: () => Promise.resolve(ok({ providers: [DIRECTORY[0]] as never })),
+    })
+    const store = new ModelsSettingsStore(face)
+    await store.load()
+    expect(store.store.getSnapshot().rows[0]).toMatchObject({
+      literalApiKeyConfigured: true,
+      apiKeyEnv: 'DEEPSEEK_API_KEY',
+    })
+  })
+
   it('surfaces a directory failure and keeps the last good rows', async () => {
     const { face } = api()
     const store = new ModelsSettingsStore(face)
diff --git a/packages/client/ui-models/tsconfig.json b/packages/client/ui-models/tsconfig.json
index 7fda5bbb04..79e61ffcba 100644
--- a/packages/client/ui-models/tsconfig.json
+++ b/packages/client/ui-models/tsconfig.json
@@ -23,6 +23,9 @@
     {
       "path": "../schema-form"
     },
+    {
+      "path": "../ui-primitives"
+    },
     {
       "path": "../web-react"
     },
diff --git a/packages/client/ui-primitives/src/Modal.tsx b/packages/client/ui-primitives/src/Modal.tsx
index 820ff3d7a3..3cca69004d 100644
--- a/packages/client/ui-primitives/src/Modal.tsx
+++ b/packages/client/ui-primitives/src/Modal.tsx
@@ -13,15 +13,17 @@ import css from './Modal.module.css'
  * @param props.open - whether the dialog is showing.
  * @param props.onClose - Escape or mask click.
  * @param props.title - dialog heading.
+ * @param props.closeLabel - accessible close-button label.
  * @param props.description - optional supporting sentence under the title.
  * @param props.children - body (inputs, etc.).
  * @param props.footer - action row (Cancel / Create).
  * @returns null when closed; otherwise the overlay tree.
  */
-export function Modal({ open, onClose, title, description, children, footer, className }: {
+export function Modal({ open, onClose, title, closeLabel = 'Close', description, children, footer, className }: {
   open: boolean
   onClose: () => void
   title: string
+  closeLabel?: string
   description?: string
   children?: ReactNode
   footer?: ReactNode
@@ -50,7 +52,7 @@ export function Modal({ open, onClose, title, description, children, footer, cla
         <div className={css.content}>
           <div className={css.header}>
             <h2 className={css.title}>{title}</h2>
-            <button type="button" className={css.close} aria-label="Close" onClick={onClose}>
+            <button type="button" className={css.close} aria-label={closeLabel} onClick={onClose}>
               <IconCloseOutline16 size={14} />
             </button>
           </div>
diff --git a/packages/client/ui-primitives/tests/atoms.spec.tsx b/packages/client/ui-primitives/tests/atoms.spec.tsx
index 7724afa493..dfcf875b1a 100644
--- a/packages/client/ui-primitives/tests/atoms.spec.tsx
+++ b/packages/client/ui-primitives/tests/atoms.spec.tsx
@@ -322,10 +322,11 @@ describe('Modal', () => {
       <Modal open={false} onClose={onClose} title="Create new workspace">body</Modal>)
     expect(screen.queryByRole('dialog')).toBeNull()
     rerender(
-      <Modal open onClose={onClose} title="Create new workspace" description="Name it." footer={<button type="button">Create</button>}>
+      <Modal open onClose={onClose} title="Create new workspace" closeLabel="Configure later" description="Name it." footer={<button type="button">Create</button>}>
         <input aria-label="name" />
       </Modal>)
     expect(screen.getByRole('dialog', { name: 'Create new workspace' })).toBeDefined()
+    expect(screen.getByRole('button', { name: 'Configure later' })).toBeDefined()
     expect(screen.getByText('Name it.')).toBeDefined()
     fireEvent.keyDown(document, { key: 'a' })
     expect(onClose).not.toHaveBeenCalled()
diff --git a/packages/client/ui-settings/package.json b/packages/client/ui-settings/package.json
index efadf3190f..8c65eee5b2 100644
--- a/packages/client/ui-settings/package.json
+++ b/packages/client/ui-settings/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-settings",
-  "description": "Settings shell plugin: sidebar trigger + modal panel occupying sidebar.settings; declares the settings.section list slot",
+  "description": "Settings shell plugin: sidebar trigger, modal panel, feature sections, and root-scoped onboarding overlays",
   "version": "0.0.1",
   "private": true,
   "type": "module",
diff --git a/packages/client/ui-settings/src/client/SettingsRoot.tsx b/packages/client/ui-settings/src/client/SettingsRoot.tsx
index c3480e1d18..4fa5b075b6 100644
--- a/packages/client/ui-settings/src/client/SettingsRoot.tsx
+++ b/packages/client/ui-settings/src/client/SettingsRoot.tsx
@@ -22,6 +22,8 @@ function navIcon(id: string) {
 type PanelProps = {
   rows: readonly SettingsSectionRow[]
   renderSlot: SettingsRootComponentProps['renderSlot']
+  activeId: string | undefined
+  onSelect: (id: string) => void
   onClose: () => void
 }
 
@@ -30,10 +32,9 @@ type PanelProps = {
  * header button, a mask click, and document-level Escape (mounted only while
  * open, so the listener lifetime is the panel's).
  */
-function SettingsPanel({ rows, renderSlot, onClose }: PanelProps) {
-  // Local selection; entries can unmount underneath it, so the render-time
+function SettingsPanel({ rows, renderSlot, activeId, onSelect, onClose }: PanelProps) {
+  // Entries can unmount underneath the requested id, so the render-time
   // projection falls back to the first row when the id is gone.
-  const [activeId, setActiveId] = useState<string | undefined>(undefined)
   const active = rows.find(r => r.id === activeId)?.id ?? rows[0]?.id
   const titleId = useId()
 
@@ -62,7 +63,7 @@ function SettingsPanel({ rows, renderSlot, onClose }: PanelProps) {
                 type="button"
                 className={clsx(css.navCell, row.id === active && css.active)}
                 aria-current={row.id === active ? 'true' : undefined}
-                onClick={() => { setActiveId(row.id) }}
+                onClick={() => { onSelect(row.id) }}
               >
                 {navIcon(row.id)}
                 <span className={css.navLabel}>{row.label}</span>
@@ -92,14 +93,25 @@ function SettingsPanel({ rows, renderSlot, onClose }: PanelProps) {
  * @returns the settings shell element tree.
  */
 export function SettingsRoot(props: SettingsRootComponentProps) {
-  const { wide, useSections, renderSlot } = props
+  const { wide, useSections, useSessions, renderSlot } = props
   const [open, setOpen] = useState(false)
-  const close = useCallback(() => { setOpen(false) }, [])
+  const [activeId, setActiveId] = useState<string | undefined>(undefined)
+  const close = useCallback(() => {
+    setOpen(false)
+    setActiveId(undefined)
+  }, [])
+  const openSection = useCallback((id: string) => {
+    setActiveId(id)
+    setOpen(true)
+  }, [])
 
   // The ledger tick keeps the nav rows fresh: registrants re-register with
   // 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 onboardingActive = useSessions(state =>
+    state.phase === 'ready'
+    && (state.current === undefined || state.byId[state.current]?.blank === true))
 
   return (
     <>
@@ -112,7 +124,16 @@ export function SettingsRoot(props: SettingsRootComponentProps) {
       >
         {renderSlot('settings.trigger', { wide })}
       </button>
-      {open && <SettingsPanel rows={rows} renderSlot={renderSlot} onClose={close} />}
+      {open && (
+        <SettingsPanel
+          rows={rows}
+          renderSlot={renderSlot}
+          activeId={activeId}
+          onSelect={setActiveId}
+          onClose={close}
+        />
+      )}
+      {renderSlot('settings.onboarding', { active: onboardingActive, openSection })}
     </>
   )
 }
diff --git a/packages/client/ui-settings/src/client/contract/slots.ts b/packages/client/ui-settings/src/client/contract/slots.ts
index c20a041858..37847832bf 100644
--- a/packages/client/ui-settings/src/client/contract/slots.ts
+++ b/packages/client/ui-settings/src/client/contract/slots.ts
@@ -47,6 +47,13 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * item registrant; the shell neither declares nor renders it.)
      */
     '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.
+     */
+    'settings.onboarding': { kind: 'list'; scope: 'root'; owner: SettingsOnboardingOwnerProps }
   }
 }
 
@@ -72,6 +79,14 @@ export interface SettingsSectionOwnerProps {
   children?: never
 }
 
+/** Owner share of a settings-backed onboarding overlay. */
+export interface SettingsOnboardingOwnerProps {
+  /** Whether the current UI is in its empty Hero/onboarding state. */
+  active: boolean
+  /** Open the settings panel directly on one registered section. */
+  openSection: (id: string) => void
+}
+
 /** One nav row projected from a settings.section registration's options. */
 export interface SettingsSectionRow {
   id: string
@@ -99,5 +114,7 @@ export type SettingsRootInjected = {
  */
 export type SettingsRootComponentProps =
   PropsRuntime<'sidebar.settings'>
-  & PropsRenderSlots<'settings.trigger' | 'settings.header' | 'settings.close' | 'settings.section'>
+  & PropsRenderSlots<
+    'settings.trigger' | 'settings.header' | 'settings.close' | 'settings.section' | 'settings.onboarding'
+  >
   & InjectFace<SettingsRootInjected>
diff --git a/packages/client/ui-settings/src/client/index.ts b/packages/client/ui-settings/src/client/index.ts
index f858be9c37..dad2f89e77 100644
--- a/packages/client/ui-settings/src/client/index.ts
+++ b/packages/client/ui-settings/src/client/index.ts
@@ -1,12 +1,11 @@
 /**
  * Settings shell plugin, browser half. A pure composition face: occupies the
  * sidebar-owned `sidebar.settings` hole with the trigger chrome + modal
- * panel, declares the `settings.trigger` / `settings.header` /
- * `settings.section` slots, and projects the section ledger into the panel
- * navigation. The shell ships no copy and reads no locale state — all text
- * arrives from registrants (ui-settings-general owns the chrome and General
- * content; features own their rows and sections). Export discipline:
- * packages/client/AGENTS.md.
+ * panel, declares its chrome, section, and onboarding slots, and projects the
+ * section ledger into panel navigation. The shell ships no copy and reads no
+ * locale state — all text arrives from registrants (ui-settings-general owns
+ * the chrome and General content; features own their rows, sections, and
+ * onboarding overlays). Export discipline: packages/client/AGENTS.md.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
@@ -15,7 +14,7 @@ import { SettingsRoot } from './SettingsRoot.tsx'
 
 export type {
   SettingsHeaderOwnerProps, SettingsRootComponentProps, SettingsRootInjected,
-  SettingsSectionOwnerProps, SettingsSectionRow, SettingsTriggerOwnerProps,
+  SettingsOnboardingOwnerProps, SettingsSectionOwnerProps, SettingsSectionRow, SettingsTriggerOwnerProps,
 } from './contract/slots.ts'
 
 /**
@@ -67,6 +66,7 @@ export function apply(ctx: ClientContext): 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' },
         },
         inject: injected,
       }, SettingsRoot))
diff --git a/packages/client/ui-settings/tests/apply.spec.ts b/packages/client/ui-settings/tests/apply.spec.ts
index caec65f3f5..de50c88d87 100644
--- a/packages/client/ui-settings/tests/apply.spec.ts
+++ b/packages/client/ui-settings/tests/apply.spec.ts
@@ -24,12 +24,13 @@ function injectedOf(slots: SlotsService): SettingsRootInjected {
   return (entry.inject as () => SettingsRootInjected)()
 }
 
-/** The shell's four child declarations (chrome seats + the section list). */
+/** The shell's five child declarations (chrome, sections, and onboarding overlays). */
 const CHILD_SPECS = {
   'settings.trigger': { kind: 'single', scope: 'root' },
   '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 const
 
 describe('ui-settings apply', () => {
@@ -37,7 +38,7 @@ describe('ui-settings apply', () => {
     expect(inject).toEqual(['slots'])
   })
 
-  it('registers the shell and declares the four child slots, before or after the declaration', async () => {
+  it('registers the shell and declares the five child slots, before or after the declaration', async () => {
     const before = await bench()
     declare(before.slots)
     await before.ctx.plugin({ inject: [...inject], apply }).await()
@@ -100,7 +101,7 @@ describe('ui-settings apply', () => {
     }
   })
 
-  it('unregisters the shell and collapses all four child slots on teardown', async () => {
+  it('unregisters the shell and collapses all five child slots on teardown', async () => {
     const b = await bench()
     declare(b.slots)
     const fiber = b.ctx.plugin({ inject: [...inject], apply })
diff --git a/packages/client/ui-settings/tests/settings-root.spec.tsx b/packages/client/ui-settings/tests/settings-root.spec.tsx
index dd340dc2ea..a7df311672 100644
--- a/packages/client/ui-settings/tests/settings-root.spec.tsx
+++ b/packages/client/ui-settings/tests/settings-root.spec.tsx
@@ -18,11 +18,12 @@ const SEAT_CONTENT: Record<string, string> = {
 
 function mount({
   wide = true,
+  onboardingActive = true,
   rows = [
     { id: 'general', order: 0, label: 'General' },
     { id: 'models', order: 10, label: 'Models' },
   ],
-}: { wide?: boolean; rows?: Row[] } = {}) {
+}: { wide?: boolean; onboardingActive?: boolean; rows?: Row[] } = {}) {
   // Mutable row source standing in for the bound useSections hook; bump()
   // plays a ledger change through the same observable contract.
   let current = rows
@@ -33,10 +34,16 @@ function mount({
       return SEAT_CONTENT[key]
     }) as SettingsRootComponentProps['renderSlot'],
   )
-  // Global standard kit stubs: the shell consumes neither hook.
+  const useSessions = ((select: (state: unknown) => unknown) => select(onboardingActive
+    ? { phase: 'ready', current: undefined, byId: {} }
+    : {
+      phase: 'ready',
+      current: 'active-session',
+      byId: { 'active-session': { blank: false } },
+    })) as never
   const unusedHook = (() => { throw new Error('unused by SettingsRoot') }) as never
   const props: SettingsRootComponentProps = {
-    useSessions: unusedHook,
+    useSessions,
     useWorkspaces: unusedHook,
     wide,
     useSections: (select) => {
@@ -157,6 +164,22 @@ describe('SettingsPanel navigation', () => {
     expect(screen.queryByTestId('section-general')).toBeNull()
   })
 
+  it('hands Hero readiness and a direct section opener to onboarding registrants', () => {
+    const { renderSlot } = mount()
+    const onboardingCall = renderSlot.mock.calls.find(call => call[0] === 'settings.onboarding')
+    expect(onboardingCall?.[1]).toMatchObject({ active: true })
+    act(() => {
+      (onboardingCall?.[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 })
+  })
+
   it('falls back to the first row when the active entry unregisters', () => {
     const { bump } = mount()
     openPanel()
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4250410f63..5a59fb0652 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1212,6 +1212,9 @@ importers:
       '@deepseek-ai/dsh-client-schema-form':
         specifier: workspace:^
         version: link:../schema-form
+      '@deepseek-ai/dsh-client-ui-primitives':
+        specifier: workspace:^
+        version: link:../ui-primitives
       '@deepseek-ai/dsh-client-ui-settings':
         specifier: workspace:^
         version: link:../ui-settings

From 0b689e0d2c379cb6cc513d566f7a8daa3a5b1f64 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 30 Jul 2026 12:41:22 +0800
Subject: [PATCH 2/7] test(web): cover keyless DeepSeek onboarding

---
 .../tests/onboarding-deepseek-config.e2e.ts   | 83 +++++++++++++++++++
 apps/web/tests/scaffold.ts                    | 55 +++++++++---
 .../missing.expected.md                       | 12 +++
 apps/web/tsconfig.json                        |  1 +
 tsconfig.host.json                            |  1 +
 5 files changed, 140 insertions(+), 12 deletions(-)
 create mode 100644 apps/web/tests/onboarding-deepseek-config.e2e.ts
 create mode 100644 apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md

diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts
new file mode 100644
index 0000000000..2dfb701c96
--- /dev/null
+++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts
@@ -0,0 +1,83 @@
+// Keyless browser e2e: the shipped DeepSeek adapter stays mounted while its
+// credential is absent, onboarding writes the effective reference through
+// the real wire into an isolated harness home, and the live page converges
+// without a reload or model call.
+import { randomBytes } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import {
+  assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
+  launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/onboarding-deepseek-config', import.meta.url))
+const MISSING_EXPECTED = join(SNAPSHOT_DIR, 'missing.expected.md')
+const MODE = webSnapshotMode()
+
+describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+  const browserConsole: string[] = []
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({ deepSeekMissingCredential: true })
+    browser = await chromium.launch()
+    page = await browser.newPage({ viewport: { width: 1440, height: 960 } })
+    tripwire = watchConsole(page)
+    page.on('console', message => browserConsole.push(message.text()))
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it('stores a key write-only and observes configured state without restarting', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-onboarding-deepseek-config'))
+    const dialog = page.getByRole('dialog', { name: '添加 DeepSeek API 密钥' })
+    await dialog.waitFor({ timeout: 15_000 })
+    expect(await dialog.getByLabel('提供方').inputValue()).toBe('DeepSeek')
+    const initial = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(MISSING_EXPECTED, initial, MODE)
+
+    const secret = `dsh_onboarding_${randomBytes(12).toString('hex')}`
+    await dialog.getByLabel('API 密钥', { exact: true }).fill(secret)
+    await dialog.getByRole('button', { name: '保存并继续' }).click()
+    await dialog.waitFor({ state: 'detached', timeout: 15_000 })
+
+    const stored = await readFile(join(scaffold.harnessHome, '.env'), 'utf8')
+    expect(stored.includes(`DEEPSEEK_API_KEY=${secret}`)).toBe(true)
+    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)
+
+    // The same running composition reuses the refreshed join. Opening Models
+    // and its credential control proves the configured view without reload.
+    await page.getByRole('button', { name: '设置', exact: true }).click()
+    const settings = page.getByRole('dialog', { name: '设置' })
+    await settings.getByRole('button', { name: '模型' }).click()
+    const deepSeekRow = settings.getByText('DeepSeek', { exact: true }).first()
+    await deepSeekRow.waitFor({ timeout: 10_000 })
+    await deepSeekRow.locator('xpath=ancestor::li').getByRole('button', { name: '编辑' }).click()
+    await settings.getByText('已配置', { exact: true }).waitFor({ timeout: 10_000 })
+
+    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)
+    expect(tripwire.warnings).toEqual([])
+    expect(tripwire.pageErrors).toEqual([])
+  }, 60_000)
+
+  it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
+    await assertFixtureInventory(SNAPSHOT_DIR, ['missing.expected.md'])
+  })
+})
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 90e98ddf57..14bf7883c4 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -4,18 +4,20 @@
 // the vendored Loader (the same include boot AppCLIEntry drives), patched the
 // snapshot way — so a real chromium exercises the real HTTP/SSE wire, the
 // api-gateway, agent loop, tools, and persistence. Modes ride $DSH_SNAPSHOT:
-// replay (default, keyless: llm-deepseek row disabled, dsh-llm-replay row
-// inserted in providers mode), record (real adapter + key, harvests fixtures
-// from live session memory), refresh (keyless replay that rewrites goldens).
+// replay (default, keyless: normally disables the llm-deepseek row and
+// inserts dsh-llm-replay in providers mode), record (real adapter + key,
+// harvests fixtures from live session memory), refresh (keyless replay that
+// rewrites goldens). A first-run option keeps the real adapter mounted while
+// masking its credential, without making a model call.
 //
 // Composition divergences from `dsh web`, all deliberate, all via include
 // patches over the SAME tree (never a second yml): temp persistenceRoot;
 // workspace-context disabled (recorded fixtures must not embed this repo's
 // AGENTS.md); session-title-llm disabled (its fire-and-forget title call
 // would race the loop for the session's replay cursor); webserver pinned to
-// port 0 with the built dist; keyless modes disable llm-deepseek and fill
-// the open llm seam post-boot with installLlmReplay on the settled root ctx
-// (the plugin-row path discards the ReplayHandle; the direct install keeps
+// port 0 with the built dist; ordinary keyless modes disable llm-deepseek and
+// fill the open llm seam post-boot with installLlmReplay on the settled root
+// ctx (the plugin-row path discards the ReplayHandle; the direct install keeps
 // assertConsumed for the teardown fixture-consumption check).
 import { existsSync } from 'node:fs'
 import { mkdtemp, readFile, readdir, realpath, rm, utimes, writeFile } from 'node:fs/promises'
@@ -125,6 +127,12 @@ export interface LaunchOptions {
    * remain reconstructable without making the tools a product default.
    */
   cordisTools?: boolean
+  /**
+   * Keep the shipped DeepSeek adapter mounted while masking the process
+   * environment's DEEPSEEK_API_KEY for this scaffold lifetime. This is the
+   * keyless first-run configuration lane; the default disables the adapter.
+   */
+  deepSeekMissingCredential?: boolean
 }
 
 /** Dispose the booted tree and remove both owned temp roots, reporting every independent cleanup failure. */
@@ -151,6 +159,21 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
       throw new Error('web e2e record mode needs DEEPSEEK_API_KEY (env or repo-root .env)')
     }
   }
+  if (mode === 'record' && options.deepSeekMissingCredential === true) {
+    throw new Error('deepSeekMissingCredential is a keyless replay/refresh option')
+  }
+  const maskDeepSeekCredential = mode !== 'record' && options.deepSeekMissingCredential === true
+  const originalDeepSeekCredential = process.env.DEEPSEEK_API_KEY
+  let credentialEnvironmentRestored = false
+  const restoreCredentialEnvironment = (): void => {
+    if (credentialEnvironmentRestored || !maskDeepSeekCredential) return
+    credentialEnvironmentRestored = true
+    if (originalDeepSeekCredential === undefined) {
+      Reflect.deleteProperty(process.env, 'DEEPSEEK_API_KEY')
+    } else {
+      process.env.DEEPSEEK_API_KEY = originalDeepSeekCredential
+    }
+  }
   const workspaceCwd = await realpath(await mkdtemp(join(tmpdir(), 'dsh-web-e2e-ws-')))
   // Isolated harness home: the settings/credentials rows resolve $DSH_HOME
   // paths at load, and an in-process boot must NEVER touch the developer's
@@ -165,6 +188,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     if (failures.length > 1) throw new AggregateError(failures, 'web scaffold temp-root setup failed')
     throw error
   }
+  if (maskDeepSeekCredential) Reflect.deleteProperty(process.env, 'DEEPSEEK_API_KEY')
 
   // The include patch set — the same mechanism AppCLIEntry and the ACP
   // snapshot overlay use, applied over the SAME shipped tree (a patch id that
@@ -187,7 +211,9 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     ...options.cordisTools === true
       ? [{ insert: [{ id: 'tool-cordis', name: 'cordis:tool-cordis' }] }]
       : [],
-    ...mode === 'record' ? [] : [{ id: 'llm-deepseek', disabled: true }],
+    ...mode === 'record' || options.deepSeekMissingCredential === true
+      ? []
+      : [{ id: 'llm-deepseek', disabled: true }],
   ]
 
   // Sessions inherit the gateway's process.cwd() default; run the boot from
@@ -216,10 +242,10 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     }
     port = boundPort
 
-    // Fill the open llm seam on the settled root ctx (llm-deepseek is disabled
-    // in keyless modes; a scenario with no fixture leaves the seam empty so a
-    // stray stream fails loud with NO_ADAPTER). The direct install, unlike the
-    // plugin row, returns the ReplayHandle for the teardown consumption check.
+    // Fill the open llm seam on the settled root ctx. Ordinary keyless modes
+    // disable llm-deepseek; the first-run lane keeps it mounted but has no
+    // replay fixture and never streams. The direct install, unlike the plugin
+    // row, returns the ReplayHandle for the teardown consumption check.
     if (mode !== 'record' && options.replayFixture !== undefined) {
       replayHandle = installLlmReplay(ctx, {
         file: options.replayFixture,
@@ -231,6 +257,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
   } catch (error) {
     if (process.cwd() !== originalCwd) process.chdir(originalCwd)
     const cleanupFailures = await cleanupScaffoldWorld(ctx, workspaceCwd, persistenceRoot)
+    restoreCredentialEnvironment()
     if (cleanupFailures.length > 0) {
       throw new AggregateError([error, ...cleanupFailures], 'web scaffold setup failed and cleanup was incomplete')
     }
@@ -279,7 +306,11 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
       } catch (error) {
         failures.push(error)
       }
-      failures.push(...await cleanupScaffoldWorld(ctx, workspaceCwd, persistenceRoot))
+      try {
+        failures.push(...await cleanupScaffoldWorld(ctx, workspaceCwd, persistenceRoot))
+      } finally {
+        restoreCredentialEnvironment()
+      }
       if (failures.length > 0) throw new AggregateError(failures, 'web scaffold teardown failed')
     },
   }
diff --git a/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md b/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md
new file mode 100644
index 0000000000..d8c6e27e56
--- /dev/null
+++ b/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md
@@ -0,0 +1,12 @@
+- dialog "添加 DeepSeek API 密钥":
+  - heading "添加 DeepSeek API 密钥" [level=2]
+  - button "稍后配置":
+    - img
+  - paragraph: 配置 DeepSeek 官方模型，即可开始使用。
+  - text: 提供方
+  - textbox "提供方": DeepSeek
+  - text: API 密钥
+  - textbox "API 密钥":
+    - /placeholder: 输入 DeepSeek API 密钥
+  - button "模型高级设置"
+  - button "保存并继续" [disabled]
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 59b544fc89..6780b7b5ca 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -30,6 +30,7 @@
     "tests/lifecycle-chrome.e2e.ts",
     "tests/settings-chrome.e2e.ts",
     "tests/models-settings.e2e.ts",
+    "tests/onboarding-deepseek-config.e2e.ts",
     "tests/workspace-management.e2e.ts",
     "tests/replay-round-trip.e2e.ts",
     "tests/seeded-history.e2e.ts",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 383718dffa..94d030febd 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -17,6 +17,7 @@
     "apps/web/tests/lifecycle-chrome.e2e.ts",
     "apps/web/tests/settings-chrome.e2e.ts",
     "apps/web/tests/models-settings.e2e.ts",
+    "apps/web/tests/onboarding-deepseek-config.e2e.ts",
     "apps/web/tests/workspace-management.e2e.ts",
     "apps/web/tests/replay-round-trip.e2e.ts",
     "apps/web/tests/seeded-history.e2e.ts",

From 819a7a675184373e089ebdd5814338ad07e4984d Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 30 Jul 2026 12:41:32 +0800
Subject: [PATCH 3/7] docs: record DeepSeek onboarding credential flow

---
 ...seek-onboarding-credential-setup.i18n.yaml |  6 ++++
 ...30-deepseek-onboarding-credential-setup.md | 31 +++++++++++++++++++
 ...deepseek-onboarding-credential-setup.zh.md | 31 +++++++++++++++++++
 packages/client/ui-models/README.i18n.yaml    |  4 +--
 packages/client/ui-models/README.md           |  4 ++-
 packages/client/ui-models/README.zh.md        |  4 ++-
 packages/client/ui-settings/README.i18n.yaml  |  6 ++--
 packages/client/ui-settings/README.md         |  4 ++-
 packages/client/ui-settings/README.zh.md      |  4 ++-
 9 files changed, 85 insertions(+), 9 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
 create mode 100644 .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md

diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
new file mode 100644
index 0000000000..77dc1b2742
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.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-deepseek-onboarding-credential-setup.md
+2026-07-30-deepseek-onboarding-credential-setup.md: e715b3ee9bf4b082f52cf1229b0488799cb2dab6
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: 0b81182ab074c2a41cae1290e6e3f2c7e43891fa
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
new file mode 100644
index 0000000000..e715b3ee9b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
@@ -0,0 +1,31 @@
+# Agent Note: official DeepSeek first-run credential setup
+
+Status: implemented
+
+English | [中文](2026-07-30-deepseek-onboarding-credential-setup.zh.md)
+
+## Problem
+
+The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) makes provider settings and credentials live-editable, but a first-time user still lands on the empty conversation Hero without an actionable explanation when the shipped `deepseek-official` route has no credential. The Models page can repair that state, yet requiring the user to discover it weakens onboarding. A prompt must not confuse a missing credential with a missing adapter: the browser can store a value for an existing credential reference, but it cannot dynamically mount the `llm-deepseek` Cordis plugin.
+
+## Decision
+
+**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 prompt is a credential-only write path.** A mounted, active adapter with a resolved, writable, unconfigured reference presents a password input. Submit calls only `credentials.set({ref, value})`, clears the React draft after success, refetches the shared join, and closes only when the new descriptor reports `configured: true`. Business failures and transport rejections keep the dialog open, restore its busy state in `finally`, and redact the submitted value from rendered error text. The prompt never writes `apiKey`, `baseURL`, or a redacted settings section; advanced configuration opens Models instead.
+
+**Unavailable capability states stay honest.** An absent configurable-provider entry suppresses the form because it cannot repair the composition. A present provider whose settings or credential capability cannot be resolved renders an actionable deployment diagnostic. Cancel 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.
+
+## Alternatives considered
+
+**A separate onboarding store and readiness RPC sequence** — rejected because it would create a second client-side interpretation of provider identity, settings paths, secret sidecars, credential references, and invalidation ordering beside the Models page.
+
+**Writing the API key into provider settings** — rejected because a literal secret would enter the settings mutation path and whole-section replacement cannot safely reconstruct redacted values. Credential storage is already the product seam and supplies immediate invalidation.
+
+**Showing the same key form when `llm-deepseek` is absent** — rejected because success would only store an unused environment reference; the browser has no supported operation that mounts the missing Cordis plugin.
+
+## Consequences
+
+The first-run flow now repairs the shipped adapter without restarting: a keyless browser test boots the real Web composition under an isolated harness home, observes the dialog, stores a generated key into that home's `.env`, verifies no key reaches DOM, ARIA, or browser console output, and confirms the running Models page reports configured. Pure readiness and React tests pin literal, file, process-environment, missing-provider, missing-capability, business-error, transport-error, 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.
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
new file mode 100644
index 0000000000..0b81182ab0
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: DeepSeek 官方首次使用凭据配置
+
+Status: implemented
+
+[English](2026-07-30-deepseek-onboarding-credential-setup.md) | 中文
+
+## 问题
+
+[web 配置平面](../architecture/2026-07-30-web-config-plane.md)让提供方设置与凭据可以实时编辑，但首次使用的用户仍会进入空白对话 Hero；当随产品提供的 `deepseek-official` 路由缺少凭据时，界面没有给出可采取操作的说明。Models 页能修复该状态，但要求用户自行发现这个入口会削弱首次使用引导。界面不得混淆凭据缺失与适配器缺失：浏览器可以为现有凭据引用存入值，但无法动态挂载 `llm-deepseek` Cordis 插件。
+
+## 决策
+
+**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 浮层，因此插件加载顺序不会成为契约。
+
+**浮层只通过凭据写入路径提交。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示密码输入框。提交时只调用 `credentials.set({ref, value})`；成功后清空 React 草稿、重新拉取共享联接，并且仅在新描述符报告 `configured: true` 时关闭浮层。业务失败与传输层拒绝都会让对话框保持打开，在 `finally` 中解除忙碌状态，并从渲染的错误文本中脱敏已提交的值。该浮层绝不写入 `apiKey`、`baseURL` 或经过脱敏的设置分节；高级配置会转到 Models。
+
+**能力不可用时如实呈现。**可配置提供方条目缺失时不显示表单，因为它无法修复当前组合。提供方存在，但设置或凭据能力无法解析时，界面会显示可采取操作的部署诊断。取消只会在当前已挂载界面中关闭浮层，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可关闭已打开的浮层。
+
+## 曾考虑的替代方案
+
+**为首次使用引导单设 store 与就绪状态 RPC 调用序列**：不予采用，因为这会在 Models 页之外，再建立一套客户端解释，用于判定提供方身份、设置路径、secret 槽位的伴随信息、凭据引用及失效事件顺序。
+
+**把 API key 写入提供方设置**：不予采用，因为字面量 secret 会进入设置变更路径，而整个分节替换无法安全重建脱敏值。凭据存储已经是产品 seam，并能立即发出失效事件。
+
+**`llm-deepseek` 缺失时仍显示同一个密钥表单**：不予采用，因为提交成功也只会存储一个无人使用的环境引用；浏览器没有任何受支持的操作可以挂载缺失的 Cordis 插件。
+
+## 后果
+
+首次使用流程无需重启即可修复随产品提供的适配器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，确认对话框出现，把生成的密钥存入该目录的 `.env`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的 Models 页报告已配置。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、业务错误、传输错误、取消和外部失效行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index aca5e8dbb5..ba446d192c 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/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: 5bcfdcdbfe31ada89f787cd4d193e9763dba94d3
-README.zh.md: 84b4b2187851506697de635d56691ca7e988ea00
+README.md: 83a3d8c76ea52acd3a6ac1d76ea60bc8d3f614c0
+README.zh.md: 202cfa756265e330cc74bd97e5c40d086073e642
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index 5bcfdcdbfe..83a3d8c76e 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -2,10 +2,12 @@
 
 English | [中文](README.zh.md)
 
-Models settings section plugin: the provider configuration page. It joins three wire domains into one surface — `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 first-run credential 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.
 
 Rows are the *configured* providers (their profile resolves in the owning namespace); the add select's vocabulary is every dormant directory entry, so a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The editor renders the provider's profile subtree through [`@deepseek-ai/dsh-client-schema-form`](../schema-form); the `credential-ref` role mounts the credential control, which shows the reference's live state and stores key values **write-only** through `credentials.set` — no value ever renders back. 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 writable missing reference opens the password form and writes only through `credentials.set`; success is accepted only after a fresh describe reports configured. An absent adapter is skipped because a browser form cannot mount Cordis plugins, while a present but unusable settings or credential capability produces a deployment diagnostic and an advanced link opens the Models section.
+
 Apply semantics mirror the settings seam: an edit without removals lands as a minimal `settings.update` merge patch (stored secrets outside the patch survive), while a field reset or row deletion lands through `settings.replace` of the whole user section so removals actually take effect. 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.
 
 ## Model Experience
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index 84b4b21878..202cfa7562 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -2,10 +2,12 @@
 
 [English](README.md) | 中文
 
-模型设置分区插件：提供方配置页。它把三个协议领域汇聚为一个界面——`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 中解析得出）；新增选择框的词汇是全部休眠目录条目，因此裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。编辑器经 [`@deepseek-ai/dsh-client-schema-form`](../schema-form) 渲染该提供方的 profile 子树；`credential-ref` 角色会挂载凭据控件，它展示该引用的实时状态，并经 `credentials.set` 以**只写**方式存入密钥值——任何值都绝不回显。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base）。
 
+首次使用浮层从同一个联接快照得出 `deepseek-official` 的就绪状态。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，浮层就不再显示，其中包括来自启动环境且只读的凭据。适配器已挂载、引用可写但尚未配置时，浮层会打开密码表单，且只经 `credentials.set` 写入；只有重新调用 describe 并确认已配置后，才会接受此次提交。适配器缺失时直接跳过，因为浏览器表单无法挂载 Cordis 插件；提供方存在但设置或凭据能力不可用时，则显示部署诊断，并通过高级设置链接打开 Models 分区。
+
 「应用」语义与 settings seam 呈镜像：不含删除的编辑以最小的 `settings.update` 合并 patch 落地（patch 之外已存储的 secret 得以保留），字段重置或整行删除则经对整个用户分节的 `settings.replace` 落地，使删除真正生效。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
 
 ## 模型体验
diff --git a/packages/client/ui-settings/README.i18n.yaml b/packages/client/ui-settings/README.i18n.yaml
index 91f8103288..32a0cdb3a6 100644
--- a/packages/client/ui-settings/README.i18n.yaml
+++ b/packages/client/ui-settings/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: bb99f9b37927eec57650aa4025deb043b369c78e
-README.zh.md: fce11e2cf44fe6c1debe850df644b0114dbde5e3
+#   pnpm run verify-translation-pairing --write packages/client/ui-settings/README.md
+README.md: 9388e9dd3a984bfcebc85b6b1a35bcce4b9b116e
+README.zh.md: 0e66e4c0e5347f0b31c36c735f653bd183232d1a
diff --git a/packages/client/ui-settings/README.md b/packages/client/ui-settings/README.md
index bb99f9b379..9388e9dd3a 100644
--- a/packages/client/ui-settings/README.md
+++ b/packages/client/ui-settings/README.md
@@ -2,7 +2,9 @@
 
 English | [中文](README.zh.md)
 
-Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and the modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content) and `settings.section` (one page per feature). 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 and rows), so the section ledger bump is its only re-render trigger.
+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).
+
+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.
 
 ## Model Experience
 
diff --git a/packages/client/ui-settings/README.zh.md b/packages/client/ui-settings/README.zh.md
index fce11e2cf4..0e66e4c0e5 100644
--- a/packages/client/ui-settings/README.zh.md
+++ b/packages/client/ui-settings/README.zh.md
@@ -2,7 +2,9 @@
 
 [English](README.md) | 中文
 
-设置外壳插件：一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`，并声明由注册方填充的 slot：`settings.trigger`／`settings.header`／`settings.close`（界面框架内容）和 `settings.section`（每项功能一页）。外壳不自带文案，也不读取 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)` 回调；后者会打开设置面板并切换到已注册的指定分区。能力就绪状态、浮层关闭、文案和变更操作均由注册方持有，因此外壳不会成为第二个配置事实来源。
 
 ## 模型体验
 

From 8d24565063c75a253a2c3d2f53854f0a8b93e5e3 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 30 Jul 2026 12:48:46 +0800
Subject: [PATCH 4/7] test(web): follow the updated Models key form

---
 apps/web/tests/onboarding-deepseek-config.e2e.ts | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts
index 2dfb701c96..7105972c82 100644
--- a/apps/web/tests/onboarding-deepseek-config.e2e.ts
+++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts
@@ -61,14 +61,19 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
     expect(browserConsole.some(line => line.includes(secret))).toBe(false)
 
     // The same running composition reuses the refreshed join. Opening Models
-    // and its credential control proves the configured view without reload.
+    // and its write-only key field proves the configured view without reload.
     await page.getByRole('button', { name: '设置', exact: true }).click()
     const settings = page.getByRole('dialog', { name: '设置' })
     await settings.getByRole('button', { name: '模型' }).click()
     const deepSeekRow = settings.getByText('DeepSeek', { exact: true }).first()
     await deepSeekRow.waitFor({ timeout: 10_000 })
     await deepSeekRow.locator('xpath=ancestor::li').getByRole('button', { name: '编辑' }).click()
-    await settings.getByText('已配置', { exact: true }).waitFor({ timeout: 10_000 })
+    const keyInput = settings.getByLabel('API 密钥', { exact: true })
+    await keyInput.waitFor({ timeout: 10_000 })
+    await expect.poll(
+      () => keyInput.getAttribute('placeholder'),
+      { timeout: 10_000 },
+    ).toBe('已配置——输入新值可替换')
 
     expect((await page.content()).includes(secret)).toBe(false)
     expect((await page.locator('body').ariaSnapshot()).includes(secret)).toBe(false)

From 42d0f3c7ba1dd72428b171ac707505ede4d1de4a Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 30 Jul 2026 13:11:07 +0800
Subject: [PATCH 5/7] feat(web): route onboarding to Models settings

---
 ...seek-onboarding-credential-setup.i18n.yaml |   4 +-
 ...30-deepseek-onboarding-credential-setup.md |   6 +-
 ...deepseek-onboarding-credential-setup.zh.md |   6 +-
 .../tests/onboarding-deepseek-config.e2e.ts   |  35 +++--
 .../missing.expected.md                       |  12 +-
 packages/client/ui-models/README.i18n.yaml    |   4 +-
 packages/client/ui-models/README.md           |   4 +-
 packages/client/ui-models/README.zh.md        |   4 +-
 packages/client/ui-models/package.json        |   2 +-
 .../DeepSeekOnboardingDialog.module.css       |  45 ------
 .../src/client/DeepSeekOnboardingDialog.tsx   | 119 ++------------
 packages/client/ui-models/src/client/index.ts |   7 +-
 .../client/ui-models/src/client/locales.ts    |  20 +--
 packages/client/ui-models/src/client/store.ts |  10 +-
 .../tests/onboarding-dialog.spec.tsx          | 146 +++---------------
 .../client/ui-models/tests/readiness.spec.ts  |   8 +-
 16 files changed, 83 insertions(+), 349 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
index 77dc1b2742..dce650b9ef 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
+++ b/.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: e715b3ee9bf4b082f52cf1229b0488799cb2dab6
-2026-07-30-deepseek-onboarding-credential-setup.zh.md: 0b81182ab074c2a41cae1290e6e3f2c7e43891fa
+2026-07-30-deepseek-onboarding-credential-setup.md: 9249b173f8f6da5dc2abf2fb147a3c9aba99c00f
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: f3c647669bd9e0974b2c9f0c407eba0c600bc656
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
index e715b3ee9b..9249b173f8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
@@ -14,7 +14,7 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 **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 prompt is a credential-only write path.** A mounted, active adapter with a resolved, writable, unconfigured reference presents a password input. Submit calls only `credentials.set({ref, value})`, clears the React draft after success, refetches the shared join, and closes only when the new descriptor reports `configured: true`. Business failures and transport rejections keep the dialog open, restore its busy state in `finally`, and redact the submitted value from rendered error text. The prompt never writes `apiKey`, `baseURL`, or a redacted settings section; advanced configuration opens Models instead.
+**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 capability states stay honest.** An absent configurable-provider entry suppresses the form because it cannot repair the composition. A present provider whose settings or credential capability cannot be resolved renders an actionable deployment diagnostic. Cancel 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.
 
@@ -22,10 +22,12 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 **A separate onboarding store and readiness RPC sequence** — rejected because it would create a second client-side interpretation of provider identity, settings paths, secret sidecars, credential references, and invalidation ordering beside the Models page.
 
+**A second API-key editor inside onboarding** — rejected because the Models page already renders its DeepSeek setup card for exactly this state. Duplicating its secret draft, write errors, and configured-state convergence would add a second security-sensitive UI without another user capability.
+
 **Writing the API key into provider settings** — rejected because a literal secret would enter the settings mutation path and whole-section replacement cannot safely reconstruct redacted values. Credential storage is already the product seam and supplies immediate invalidation.
 
 **Showing the same key form when `llm-deepseek` is absent** — rejected because success would only store an unused environment reference; the browser has no supported operation that mounts the missing Cordis plugin.
 
 ## Consequences
 
-The first-run flow now repairs the shipped adapter without restarting: a keyless browser test boots the real Web composition under an isolated harness home, observes the dialog, stores a generated key into that home's `.env`, verifies no key reaches DOM, ARIA, or browser console output, and confirms the running Models page reports configured. Pure readiness and React tests pin literal, file, process-environment, missing-provider, missing-capability, business-error, transport-error, 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 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.
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
index 0b81182ab0..f3c647669b 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 **设置外壳只贡献导航状态，不持有提供方策略。**`ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并告知注册方当前界面是否为空白 Hero。其私有 `openSection(id)` 回调会打开设置面板并切换到一个已注册分区。`ui-models` 沿用 Models 分区所使用、感知 slot 声明的延迟注册路径来注册 DeepSeek 浮层，因此插件加载顺序不会成为契约。
 
-**浮层只通过凭据写入路径提交。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示密码输入框。提交时只调用 `credentials.set({ref, value})`；成功后清空 React 草稿、重新拉取共享联接，并且仅在新描述符报告 `configured: true` 时关闭浮层。业务失败与传输层拒绝都会让对话框保持打开，在 `finally` 中解除忙碌状态，并从渲染的错误文本中脱敏已提交的值。该浮层绝不写入 `apiKey`、`baseURL` 或经过脱敏的设置分节；高级配置会转到 Models。
+**浮层只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用浮层绝不持有或提交 secret。设置或凭据能力不可用时会保留部署诊断，并提供前往同一页面的入口；适配器缺失时仍直接跳过，因为导航无法挂载 Cordis 插件。
 
 **能力不可用时如实呈现。**可配置提供方条目缺失时不显示表单，因为它无法修复当前组合。提供方存在，但设置或凭据能力无法解析时，界面会显示可采取操作的部署诊断。取消只会在当前已挂载界面中关闭浮层，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可关闭已打开的浮层。
 
@@ -22,10 +22,12 @@ Status: implemented
 
 **为首次使用引导单设 store 与就绪状态 RPC 调用序列**：不予采用，因为这会在 Models 页之外，再建立一套客户端解释，用于判定提供方身份、设置路径、secret 槽位的伴随信息、凭据引用及失效事件顺序。
 
+**在首次使用引导中增设第二个 API key 编辑器**：不予采用，因为 Models 页已为这一状态渲染 DeepSeek 设置卡片。复制其中的 secret 草稿、写入错误处理和已配置状态收敛会增加第二个安全敏感的 UI，却不会带来新的用户能力。
+
 **把 API key 写入提供方设置**：不予采用，因为字面量 secret 会进入设置变更路径，而整个分节替换无法安全重建脱敏值。凭据存储已经是产品 seam，并能立即发出失效事件。
 
 **`llm-deepseek` 缺失时仍显示同一个密钥表单**：不予采用，因为提交成功也只会存储一个无人使用的环境引用；浏览器没有任何受支持的操作可以挂载缺失的 Cordis 插件。
 
 ## 后果
 
-首次使用流程无需重启即可修复随产品提供的适配器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，确认对话框出现，把生成的密钥存入该目录的 `.env`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的 Models 页报告已配置。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、业务错误、传输错误、取消和外部失效行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。
+首次使用流程现在无需重启即可引导用户前往随产品提供的适配器已有的编辑器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，依照浮层操作前往 Models，通过该页面把生成的密钥存入该目录的 `.env`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的页面报告已配置。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、导航、取消和外部失效行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。
diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts
index 7105972c82..c4e65b8bbb 100644
--- a/apps/web/tests/onboarding-deepseek-config.e2e.ts
+++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts
@@ -1,7 +1,6 @@
 // Keyless browser e2e: the shipped DeepSeek adapter stays mounted while its
-// credential is absent, onboarding writes the effective reference through
-// the real wire into an isolated harness home, and the live page converges
-// without a reload or model call.
+// credential is absent, onboarding routes to the real Models editor, and its
+// write lands in an isolated harness home without a reload or model call.
 import { randomBytes } from 'node:crypto'
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
@@ -43,16 +42,23 @@ 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 dialog = page.getByRole('dialog', { name: '添加 DeepSeek API 密钥' })
+    const dialog = page.getByRole('dialog', { name: '添加一个 API Key 开始使用' })
     await dialog.waitFor({ timeout: 15_000 })
-    expect(await dialog.getByLabel('提供方').inputValue()).toBe('DeepSeek')
+    expect(await dialog.getByRole('textbox').count()).toBe(0)
     const initial = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(MISSING_EXPECTED, initial, MODE)
 
-    const secret = `dsh_onboarding_${randomBytes(12).toString('hex')}`
-    await dialog.getByLabel('API 密钥', { exact: true }).fill(secret)
-    await dialog.getByRole('button', { name: '保存并继续' }).click()
+    await dialog.getByRole('button', { name: '前往配置' }).click()
     await dialog.waitFor({ state: 'detached', timeout: 15_000 })
+    const settings = page.getByRole('dialog', { name: '设置' })
+    await settings.waitFor({ timeout: 10_000 })
+    const keyInput = settings.getByLabel('API 密钥', { exact: true })
+    await keyInput.waitFor({ timeout: 10_000 })
+
+    const secret = `dsh_onboarding_${randomBytes(12).toString('hex')}`
+    await keyInput.fill(secret)
+    await settings.getByRole('button', { name: '保存', exact: true }).click()
+    await keyInput.waitFor({ state: 'detached', timeout: 15_000 })
 
     const stored = await readFile(join(scaffold.harnessHome, '.env'), 'utf8')
     expect(stored.includes(`DEEPSEEK_API_KEY=${secret}`)).toBe(true)
@@ -60,18 +66,15 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
     expect((await page.locator('body').ariaSnapshot()).includes(secret)).toBe(false)
     expect(browserConsole.some(line => line.includes(secret))).toBe(false)
 
-    // The same running composition reuses the refreshed join. Opening Models
-    // and its write-only key field proves the configured view without reload.
-    await page.getByRole('button', { name: '设置', exact: true }).click()
-    const settings = page.getByRole('dialog', { name: '设置' })
-    await settings.getByRole('button', { name: '模型' }).click()
+    // The same open Models surface reuses the refreshed join and exposes the
+    // configured write-only placeholder without a reload.
     const deepSeekRow = settings.getByText('DeepSeek', { exact: true }).first()
     await deepSeekRow.waitFor({ timeout: 10_000 })
     await deepSeekRow.locator('xpath=ancestor::li').getByRole('button', { name: '编辑' }).click()
-    const keyInput = settings.getByLabel('API 密钥', { exact: true })
-    await keyInput.waitFor({ timeout: 10_000 })
+    const configuredInput = settings.getByLabel('API 密钥', { exact: true })
+    await configuredInput.waitFor({ timeout: 10_000 })
     await expect.poll(
-      () => keyInput.getAttribute('placeholder'),
+      () => configuredInput.getAttribute('placeholder'),
       { timeout: 10_000 },
     ).toBe('已配置——输入新值可替换')
 
diff --git a/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md b/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md
index d8c6e27e56..102b6a7fab 100644
--- a/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md
+++ b/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md
@@ -1,12 +1,6 @@
-- dialog "添加 DeepSeek API 密钥":
-  - heading "添加 DeepSeek API 密钥" [level=2]
+- dialog "添加一个 API Key 开始使用":
+  - heading "添加一个 API Key 开始使用" [level=2]
   - button "稍后配置":
     - img
   - paragraph: 配置 DeepSeek 官方模型，即可开始使用。
-  - text: 提供方
-  - textbox "提供方": DeepSeek
-  - text: API 密钥
-  - textbox "API 密钥":
-    - /placeholder: 输入 DeepSeek API 密钥
-  - button "模型高级设置"
-  - button "保存并继续" [disabled]
+  - button "前往配置"
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index 843987f144..7452e56cc4 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/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: de3c5b93e5f89e7e51236bea436ac71d226b6684
-README.zh.md: 1688f09104ee441e64f1747a07dd73f1be08fc1d
+README.md: eea761859a187b13e08e3cd48e2120cc0cdead15
+README.zh.md: 31e91b0eb1ef52bb3eb6782bdf115602205d5760
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index de3c5b93e5..eea761859a 100644
--- a/packages/client/ui-models/README.md
+++ b/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 credential 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 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.
 
 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 writable missing reference opens the password form and writes only through `credentials.set`; success is accepted only after a fresh describe reports configured. An absent adapter is skipped because a browser form cannot mount Cordis plugins, while a present but unusable settings or credential capability produces a deployment diagnostic and an advanced link opens the Models section.
+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.
 
 Apply semantics mirror the settings seam: an edit without removals lands as a minimal `settings.update` merge patch, while clearing a fold field back to inherited or deleting a row lands through `settings.replace` of the whole user section so removals actually take effect — safe wholesale, because the section stores key references, never key values. 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.
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index 1688f09104..31e91b0eb1 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/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 槽位标记为已设置，或凭据引用已配置，浮层就不再显示，其中包括来自启动环境且只读的凭据。适配器已挂载、引用可写但尚未配置时，浮层会打开密码表单，且只经 `credentials.set` 写入；只有重新调用 describe 并确认已配置后，才会接受此次提交。适配器缺失时直接跳过，因为浏览器表单无法挂载 Cordis 插件；提供方存在但设置或凭据能力不可用时，则显示部署诊断，并通过高级设置链接打开 Models 分区。
+首次使用浮层从同一个联接快照得出 `deepseek-official` 的就绪状态。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，浮层就不再显示，其中包括来自启动环境且只读的凭据。适配器已挂载、引用可写但尚未配置时，浮层只显示一个操作按钮，用于打开「设置」的 Models 分区；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，浮层绝不持有 secret。适配器缺失时直接跳过，因为浏览器导航无法挂载 Cordis 插件；设置或凭据能力不可用时则显示部署诊断，并提供同一个前往 Models 的入口。
 
 「应用」语义与 settings seam 呈镜像：不含删除的编辑以最小的 `settings.update` 合并 patch 落地，把折叠区字段清回继承值或删除整行则经对整个用户分节的 `settings.replace` 落地，使删除真正生效——整体替换是安全的，因为该分节存的是密钥引用，从不存密钥值。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
 
diff --git a/packages/client/ui-models/package.json b/packages/client/ui-models/package.json
index 825e56d359..a649e1308f 100644
--- a/packages/client/ui-models/package.json
+++ b/packages/client/ui-models/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-models",
-  "description": "Models settings and official-DeepSeek first-run credential UI over one live provider/settings/credential join",
+  "description": "Models settings and official-DeepSeek first-run routing over one live provider/settings/credential join",
   "version": "0.0.1",
   "private": true,
   "type": "module",
diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
index eebf96036d..6823556903 100644
--- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
@@ -2,51 +2,6 @@
   width: min(420px, 100%);
 }
 
-.fields {
-  display: flex;
-  flex-direction: column;
-  gap: 14px;
-}
-
-.field {
-  display: flex;
-  flex-direction: column;
-  gap: 6px;
-}
-
-.label {
-  font-size: 12px;
-  line-height: 18px;
-  font-weight: 500;
-  color: var(--dsw-alias-label-secondary);
-}
-
-.input {
-  width: 100%;
-  height: 36px;
-  box-sizing: border-box;
-  padding-inline: 12px;
-  border-radius: 10px;
-}
-
-.input > input {
-  width: 100%;
-  font-size: 13px;
-}
-
-.advanced {
-  align-self: flex-start;
-  padding-inline: 0;
-  color: var(--dsw-alias-label-secondary);
-}
-
-.error {
-  margin: 0;
-  font-size: 12px;
-  line-height: 18px;
-  color: var(--dsw-alias-state-error-primary);
-}
-
 .diagnostic {
   margin: 0;
   font-size: 13px;
diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
index efec759096..011970b10c 100644
--- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
@@ -1,14 +1,13 @@
 /**
  * Official-DeepSeek first-run dialog. Readiness comes from the same
- * provider/settings/credential join as the Models page; the component holds
- * only the write-only draft and viewing state.
+ * provider/settings/credential join as the Models page; the prompt only
+ * routes the user to that page's single credential editor.
  */
 
 import { useEffect, useState } from 'react'
 import type { ReactNode } from 'react'
-import type { IApiClient } from '@deepseek-ai/dsh-client-connection/client'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import { Button, Input, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
+import { Button, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
 import type { ModelsSettingsState, ModelsSettingsStore } from './store.ts'
 import { deepSeekReadiness } from './store.ts'
@@ -21,8 +20,6 @@ export interface DeepSeekOnboardingInjected {
   controller: ModelsSettingsStore
   /** Subscription hook bound to the shared join snapshot. */
   useSnapshot: SnapshotSelectorHook<ModelsSettingsState>
-  /** Write-only credential wire face. */
-  credentials: IApiClient['credentials']
   /** Feature copy. */
   t: (key: keyof typeof en) => string
 }
@@ -31,40 +28,23 @@ export interface DeepSeekOnboardingInjected {
 export type DeepSeekOnboardingDialogProps =
   PropsRuntime<'settings.onboarding'> & DeepSeekOnboardingInjected
 
-/** Remove the submitted non-empty secret from any error text before it reaches the DOM. */
-function redactSecret(message: string, secret: string): string {
-  return message.split(secret).join('[redacted]')
-}
-
 /**
- * Render the first-run credential dialog while the official adapter exists
- * and its effective reference is writable but unconfigured.
+ * Prompt a first-run user to open Models while the official adapter exists
+ * and its effective credential is not configured.
  * @param props - settings-shell owner state and Models feature dependencies.
  * @returns the controlled modal or null when onboarding needs no intervention.
  */
 export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps): ReactNode {
-  const { active, openSection, controller, useSnapshot, credentials, t } = props
+  const { active, openSection, controller, useSnapshot, t } = props
   const state = useSnapshot(snapshot => snapshot)
   const readiness = deepSeekReadiness(state)
   const [dismissed, setDismissed] = useState(false)
-  const [keyDraft, setKeyDraft] = useState('')
-  const [busy, setBusy] = useState(false)
-  const [failure, setFailure] = useState<string | undefined>(undefined)
 
   useEffect(() => {
     if (active && !dismissed && state.status === 'idle') void controller.load()
   }, [active, controller, dismissed, state.status])
 
-  useEffect(() => {
-    if (!active || readiness.kind !== 'credential-missing') {
-      setKeyDraft('')
-      setFailure(undefined)
-    }
-  }, [active, readiness.kind, readiness.kind === 'credential-missing' ? readiness.ref : undefined])
-
   const close = (): void => {
-    setKeyDraft('')
-    setFailure(undefined)
     setDismissed(true)
   }
 
@@ -73,42 +53,6 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
     openSection('models')
   }
 
-  const save = async (): Promise<void> => {
-    /* v8 ignore next -- the form only attaches save while missing and disables it for an empty draft */
-    if (readiness.kind !== 'credential-missing' || keyDraft.length === 0) return
-    const secret = keyDraft
-    const ref = readiness.ref
-    setBusy(true)
-    setFailure(undefined)
-    try {
-      const response = await credentials.set({ ref, value: secret })
-      if (!response.result.ok) {
-        setFailure(`${t('onboardingSaveFailed')}: ${redactSecret(response.result.error.message, secret)}`)
-        return
-      }
-      await controller.load()
-      if (deepSeekReadiness(controller.store.getSnapshot()).kind !== 'configured') {
-        setFailure(t('onboardingVerifyFailed'))
-        return
-      }
-      setKeyDraft('')
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      setFailure(`${t('onboardingSaveFailed')}: ${redactSecret(message, secret)}`)
-    } finally {
-      setBusy(false)
-    }
-  }
-
-  const retry = async (): Promise<void> => {
-    setBusy(true)
-    try {
-      await controller.load()
-    } finally {
-      setBusy(false)
-    }
-  }
-
   if (!active || dismissed || readiness.kind === 'loading'
     || readiness.kind === 'adapter-absent' || readiness.kind === 'configured') return null
 
@@ -116,9 +60,6 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
   const diagnostic = unavailable && readiness.reason === 'credentials-unavailable'
     ? t('onboardingCredentialsUnavailable')
     : t('onboardingConfigurationUnavailable')
-  const displayName = readiness.kind === 'credential-missing'
-    ? readiness.displayName
-    : 'DeepSeek'
 
   return (
     <Modal
@@ -132,55 +73,13 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
         <Button
           variant="primary"
           className={styles['primary']}
-          disabled={busy || (!unavailable && keyDraft.length === 0)}
-          onClick={() => { void (unavailable ? retry() : save()) }}
+          onClick={openModels}
         >
-          {busy
-            ? t('onboardingSaving')
-            : unavailable
-              ? t('retry')
-              : t('onboardingSave')}
+          {t('onboardingGoToSettings')}
         </Button>
       )}
     >
-      <div className={styles['fields']}>
-        <label className={styles['field']}>
-          <span className={styles['label']}>{t('provider')}</span>
-          <Input
-            className={styles['input'] as string}
-            type="text"
-            aria-label={t('provider')}
-            value={displayName}
-            readOnly
-          />
-        </label>
-        {readiness.kind === 'credential-missing'
-          ? (
-            <label className={styles['field']}>
-              <span className={styles['label']}>{t('onboardingKey')}</span>
-              <Input
-                className={styles['input'] as string}
-                type="password"
-                autoComplete="off"
-                autoCapitalize="none"
-                spellCheck={false}
-                aria-label={t('onboardingKey')}
-                placeholder={t('onboardingKeyPlaceholder')}
-                value={keyDraft}
-                disabled={busy}
-                onChange={(event) => {
-                  setKeyDraft(event.target.value)
-                  setFailure(undefined)
-                }}
-              />
-            </label>
-          )
-          : <p className={styles['diagnostic']}>{diagnostic}</p>}
-        <Button variant="ghost" size="sm" className={styles['advanced']} onClick={openModels}>
-          {t('onboardingAdvanced')}
-        </Button>
-        {failure !== undefined ? <p className={styles['error']} role="alert">{failure}</p> : null}
-      </div>
+      {unavailable ? <p className={styles['diagnostic']}>{diagnostic}</p> : undefined}
     </Modal>
   )
 }
diff --git a/packages/client/ui-models/src/client/index.ts b/packages/client/ui-models/src/client/index.ts
index a6ee6478db..6aa925ae7f 100644
--- a/packages/client/ui-models/src/client/index.ts
+++ b/packages/client/ui-models/src/client/index.ts
@@ -1,9 +1,9 @@
 /**
  * Models settings plugin, browser half. Registers the `models` nav entry and
  * official-DeepSeek first-run overlay into shell-declared slots. Both consume
- * one provider/settings/credential join; the full page edits through the
- * schema-driven form while onboarding exposes only write-only credential
- * setup. Export discipline: packages/client/AGENTS.md.
+ * one provider/settings/credential join; the overlay routes missing-key users
+ * to the full page's single credential editor. Export discipline:
+ * packages/client/AGENTS.md.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
@@ -68,7 +68,6 @@ export function apply(ctx: ClientContext): void {
   const onboardingInjected = (): DeepSeekOnboardingInjected => ({
     controller,
     useSnapshot,
-    credentials: connection.api.credentials,
     t,
   })
 
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index f6bd40e038..5472702800 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -27,16 +27,10 @@ export const en = {
   effort: 'Reasoning effort',
   effortInherit: 'Default',
   advancedHint: 'Other fields live in settings.yaml; edit that section directly.',
-  onboardingTitle: 'Add a DeepSeek API key',
+  onboardingTitle: 'Add an API key to get started',
   onboardingDescription: 'Configure the official DeepSeek provider to start building.',
-  onboardingKey: 'API key',
-  onboardingKeyPlaceholder: 'Enter your DeepSeek API key',
-  onboardingAdvanced: 'Advanced model settings',
-  onboardingSave: 'Save and continue',
-  onboardingSaving: 'Saving…',
+  onboardingGoToSettings: 'Go to settings',
   onboardingLater: 'Configure later',
-  onboardingSaveFailed: 'Could not save the API key',
-  onboardingVerifyFailed: 'The key was saved, but its configured state could not be verified. Try again.',
   onboardingUnavailableTitle: 'DeepSeek setup is unavailable',
   onboardingCredentialsUnavailable: 'This deployment does not expose writable credential storage. Mount @deepseek-ai/dsh-credentials-local, then retry.',
   onboardingConfigurationUnavailable: 'The live DeepSeek configuration capability cannot be resolved here. Check the deployment composition, then retry.',
@@ -69,16 +63,10 @@ export const zh: typeof en = {
   effort: '推理强度',
   effortInherit: '默认',
   advancedHint: '其余字段在 settings.yaml 中，请直接编辑对应段。',
-  onboardingTitle: '添加 DeepSeek API 密钥',
+  onboardingTitle: '添加一个 API Key 开始使用',
   onboardingDescription: '配置 DeepSeek 官方模型，即可开始使用。',
-  onboardingKey: 'API 密钥',
-  onboardingKeyPlaceholder: '输入 DeepSeek API 密钥',
-  onboardingAdvanced: '模型高级设置',
-  onboardingSave: '保存并继续',
-  onboardingSaving: '保存中…',
+  onboardingGoToSettings: '前往配置',
   onboardingLater: '稍后配置',
-  onboardingSaveFailed: '无法保存 API 密钥',
-  onboardingVerifyFailed: '密钥已写入，但无法确认配置状态。请重试。',
   onboardingUnavailableTitle: '无法在此配置 DeepSeek',
   onboardingCredentialsUnavailable: '当前部署没有可写的凭据存储。请挂载 @deepseek-ai/dsh-credentials-local 后重试。',
   onboardingConfigurationUnavailable: '无法在此解析 DeepSeek 的实时配置能力。请检查部署组合后重试。',
diff --git a/packages/client/ui-models/src/client/store.ts b/packages/client/ui-models/src/client/store.ts
index 0a32c41dcf..74f90b0067 100644
--- a/packages/client/ui-models/src/client/store.ts
+++ b/packages/client/ui-models/src/client/store.ts
@@ -181,7 +181,7 @@ export type DeepSeekReadiness =
   | { kind: 'loading' }
   | { kind: 'adapter-absent' }
   | { kind: 'configured'; source: 'literal' | 'credential'; ref?: string; credential?: CredentialView }
-  | { kind: 'credential-missing'; displayName: string; ref: string }
+  | { kind: 'credential-missing' }
   | {
     kind: 'unavailable'
     reason:
@@ -196,7 +196,7 @@ export type DeepSeekReadiness =
 /**
  * Project official-DeepSeek readiness from the provider/settings/credential
  * join used by the Models page. A missing directory entry means the adapter
- * is not mounted and therefore cannot be repaired by a key form.
+ * is not mounted and therefore cannot be repaired by navigating to Models.
  * @param state - current shared Models join snapshot.
  * @returns the onboarding state without reading a parallel fact source.
  */
@@ -264,9 +264,5 @@ export function deepSeekReadiness(state: ModelsSettingsState): DeepSeekReadiness
       message: `credential reference "${row.apiKeyEnv}" is missing and read-only`,
     }
   }
-  return {
-    kind: 'credential-missing',
-    displayName: row.entry.displayName,
-    ref: row.apiKeyEnv,
-  }
+  return { kind: 'credential-missing' }
 }
diff --git a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
index fa4fd1dac2..3aa4294118 100644
--- a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
+++ b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-/** First-run DeepSeek dialog behavior over the shared Models join. */
+/** First-run DeepSeek prompt behavior over the shared Models join. */
 import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { RpcResponse } from '@deepseek-ai/dsh-client-connection/client'
@@ -28,14 +28,9 @@ function harness(options: {
   configured?: () => boolean
   credential?: { source?: string; writable: boolean }
   describeFailure?: string
-  set?: (payload: { ref: string; value: string }) => Promise<RpcResponse<{}>>
 } = {}) {
   let fileConfigured = false
   const configured = options.configured ?? (() => fileConfigured)
-  const set = vi.fn(options.set ?? ((payload: { ref: string; value: string }) => {
-    fileConfigured = payload.value.length > 0
-    return Promise.resolve(ok({}))
-  }))
   const face = {
     llm: {
       providers: () => Promise.resolve(ok({
@@ -76,7 +71,6 @@ function harness(options: {
           },
         }))
         : Promise.resolve(fail(options.describeFailure)),
-      set,
     },
   }
   const controller = new ModelsSettingsStore(face as never)
@@ -89,145 +83,53 @@ function harness(options: {
     useWorkspaces: unusedHook,
     controller,
     useSnapshot: bindSnapshotSelector(controller.store),
-    credentials: face.credentials as never,
     t: key => en[key],
   }
-  return { controller, face, openSection, props, set, configure: () => { fileConfigured = true } }
+  return { controller, openSection, props, configure: () => { fileConfigured = true } }
 }
 
 describe('DeepSeekOnboardingDialog', () => {
-  it('loads on first entry and presents an accessible write-only key form', async () => {
+  it('loads on first entry and presents one accessible route to Models', async () => {
     const h = harness()
     render(<DeepSeekOnboardingDialog {...h.props} />)
-    const dialog = await screen.findByRole('dialog', { name: en.onboardingTitle })
-    expect(dialog).toBeTruthy()
-    expect(screen.getByLabelText<HTMLInputElement>(en.provider).value).toBe('DeepSeek')
-    const key = screen.getByLabelText<HTMLInputElement>(en.onboardingKey)
-    expect(key.type).toBe('password')
-    expect(key.autocomplete).toBe('off')
-    expect(key.getAttribute('spellcheck')).toBe('false')
+    expect(await screen.findByRole('dialog', { name: en.onboardingTitle })).toBeTruthy()
+    expect(screen.getByText(en.onboardingDescription)).toBeTruthy()
+    expect(screen.getByRole('button', { name: en.onboardingGoToSettings })).toBeTruthy()
+    expect(screen.queryByRole('textbox')).toBeNull()
   })
 
-  it('stores through credentials.set, verifies through describe, clears the draft, and closes', async () => {
+  it('opens the Models section and dismisses the prompt', async () => {
     const h = harness()
     render(<DeepSeekOnboardingDialog {...h.props} />)
-    const key = await screen.findByLabelText<HTMLInputElement>(en.onboardingKey)
-    const secret = 'test-onboarding-secret'
-    fireEvent.change(key, { target: { value: secret } })
-    fireEvent.click(screen.getByRole('button', { name: en.onboardingSave }))
-    await waitFor(() => { expect(screen.queryByRole('dialog')).toBeNull() })
-    expect(h.set).toHaveBeenCalledWith({ ref: 'DEEPSEEK_API_KEY', value: secret })
-    expect(document.body.textContent).not.toContain(secret)
-    expect(document.documentElement.outerHTML).not.toContain(secret)
+    await screen.findByRole('dialog')
+    fireEvent.click(screen.getByRole('button', { name: en.onboardingGoToSettings }))
+    expect(h.openSection).toHaveBeenCalledWith('models')
+    expect(screen.queryByRole('dialog', { name: en.onboardingTitle })).toBeNull()
   })
 
-  it('keeps a business failure open without echoing the secret', async () => {
-    const secret = 'business-secret'
-    const h = harness({
-      set: payload => Promise.resolve(fail(`refused ${payload.value}`)),
-    })
+  it('allows configure-later dismissal without opening settings', async () => {
+    const h = harness()
     render(<DeepSeekOnboardingDialog {...h.props} />)
-    const key = await screen.findByLabelText<HTMLInputElement>(en.onboardingKey)
-    fireEvent.change(key, { target: { value: secret } })
-    fireEvent.click(screen.getByRole('button', { name: en.onboardingSave }))
-    const alert = await screen.findByRole('alert')
-    expect(alert.textContent).toContain('[redacted]')
-    expect(alert.textContent).not.toContain(secret)
-    expect(screen.getByRole<HTMLButtonElement>('button', { name: en.onboardingSave }).disabled).toBe(false)
-    expect(screen.getByRole('dialog')).toBeTruthy()
-    fireEvent.change(key, { target: { value: 'replacement' } })
-    expect(screen.queryByRole('alert')).toBeNull()
-  })
-
-  it('shows saving state and reports a failed configured-state verification', async () => {
-    let settle: (() => void) | undefined
-    const pending = new Promise<void>((resolve) => { settle = resolve })
-    const h = harness({
-      set: async () => {
-        await pending
-        return ok({})
-      },
-    })
-    render(<DeepSeekOnboardingDialog {...h.props} />)
-    fireEvent.change(await screen.findByLabelText(en.onboardingKey), { target: { value: 'verify-secret' } })
-    fireEvent.click(screen.getByRole('button', { name: en.onboardingSave }))
-    expect(screen.getByRole('button', { name: en.onboardingSaving })).toBeTruthy()
-    settle?.()
-    expect((await screen.findByRole('alert')).textContent).toBe(en.onboardingVerifyFailed)
-    expect(screen.getByRole<HTMLButtonElement>('button', { name: en.onboardingSave }).disabled).toBe(false)
-  })
-
-  it('recovers busy state after a transport rejection without an unhandled rejection', async () => {
-    const secret = 'transport-secret'
-    const h = harness({
-      set: () => Promise.reject(new Error(`transport rejected ${secret}`)),
-    })
-    const unhandled = vi.fn()
-    window.addEventListener('unhandledrejection', unhandled)
-    try {
-      render(<DeepSeekOnboardingDialog {...h.props} />)
-      const key = await screen.findByLabelText<HTMLInputElement>(en.onboardingKey)
-      fireEvent.change(key, { target: { value: secret } })
-      fireEvent.click(screen.getByRole('button', { name: en.onboardingSave }))
-      const alert = await screen.findByRole('alert')
-      expect(alert.textContent).not.toContain(secret)
-      expect(screen.getByRole<HTMLButtonElement>('button', { name: en.onboardingSave }).disabled).toBe(false)
-      expect(unhandled).not.toHaveBeenCalled()
-    } finally {
-      window.removeEventListener('unhandledrejection', unhandled)
-    }
-  })
-
-  it('stringifies a non-Error transport rejection without exposing its secret', async () => {
-    const secret = 'plain-rejection-secret'
-    const h = harness({
-      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
-      set: () => Promise.reject(`transport refused ${secret}`),
-    })
-    render(<DeepSeekOnboardingDialog {...h.props} />)
-    fireEvent.change(await screen.findByLabelText(en.onboardingKey), { target: { value: secret } })
-    fireEvent.click(screen.getByRole('button', { name: en.onboardingSave }))
-    const alert = await screen.findByRole('alert')
-    expect(alert.textContent).toContain('[redacted]')
-    expect(alert.textContent).not.toContain(secret)
-  })
-
-  it('cancels without writing and opens the Models section through the owner callback', async () => {
-    const cancelled = harness()
-    const first = render(<DeepSeekOnboardingDialog {...cancelled.props} />)
     await screen.findByRole('dialog')
     fireEvent.click(screen.getByRole('button', { name: en.onboardingLater }))
     expect(screen.queryByRole('dialog')).toBeNull()
-    expect(cancelled.set).not.toHaveBeenCalled()
-    first.unmount()
-
-    const advanced = harness()
-    render(<DeepSeekOnboardingDialog {...advanced.props} />)
-    await screen.findByRole('dialog')
-    fireEvent.click(screen.getByRole('button', { name: en.onboardingAdvanced }))
-    expect(advanced.openSection).toHaveBeenCalledWith('models')
-    expect(screen.queryByRole('dialog')).toBeNull()
-    expect(advanced.set).not.toHaveBeenCalled()
+    expect(h.openSection).not.toHaveBeenCalled()
   })
 
-  it('shows an actionable deployment diagnostic when credentials are unavailable', async () => {
+  it('routes an unavailable credential deployment to Models with a diagnostic', async () => {
     const h = harness({ describeFailure: 'credentials service is absent' })
     render(<DeepSeekOnboardingDialog {...h.props} />)
     await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
     expect(screen.getByText(en.onboardingCredentialsUnavailable)).toBeTruthy()
-    expect(screen.queryByLabelText(en.onboardingKey)).toBeNull()
-    fireEvent.click(screen.getByRole('button', { name: en.retry }))
-    await waitFor(() => {
-      expect(screen.getByRole<HTMLButtonElement>('button', { name: en.retry }).disabled).toBe(false)
-    })
+    fireEvent.click(screen.getByRole('button', { name: en.onboardingGoToSettings }))
+    expect(h.openSection).toHaveBeenCalledWith('models')
   })
 
-  it('uses the deployment diagnostic for a missing read-only credential', async () => {
+  it('uses the general diagnostic for a missing read-only credential', async () => {
     const h = harness({ credential: { writable: false } })
     render(<DeepSeekOnboardingDialog {...h.props} />)
     await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
     expect(screen.getByText(en.onboardingConfigurationUnavailable)).toBeTruthy()
-    expect(screen.queryByLabelText(en.onboardingKey)).toBeNull()
   })
 
   it('skips an absent adapter and already-configured literal or environment credentials', async () => {
@@ -252,14 +154,12 @@ describe('DeepSeekOnboardingDialog', () => {
     await waitFor(() => { expect(screen.queryByRole('dialog')).toBeNull() })
   })
 
-  it('clears a typed draft when the onboarding owner becomes inactive', async () => {
+  it('stays hidden while the onboarding owner is inactive', async () => {
     const h = harness()
-    const view = render(<DeepSeekOnboardingDialog {...h.props} />)
-    const key = await screen.findByLabelText<HTMLInputElement>(en.onboardingKey)
-    fireEvent.change(key, { target: { value: 'ephemeral' } })
-    view.rerender(<DeepSeekOnboardingDialog {...h.props} active={false} />)
+    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.findByLabelText<HTMLInputElement>(en.onboardingKey)).value).toBe('')
+    expect(await screen.findByRole('dialog', { name: en.onboardingTitle })).toBeTruthy()
   })
 })
diff --git a/packages/client/ui-models/tests/readiness.spec.ts b/packages/client/ui-models/tests/readiness.spec.ts
index 275c3ad4cf..d9f77bb7a8 100644
--- a/packages/client/ui-models/tests/readiness.spec.ts
+++ b/packages/client/ui-models/tests/readiness.spec.ts
@@ -43,12 +43,8 @@ describe('deepSeekReadiness', () => {
     expect(deepSeekReadiness(state({ rows: [] }))).toEqual({ kind: 'adapter-absent' })
   })
 
-  it('addresses the effective credential reference when it is missing and writable', () => {
-    expect(deepSeekReadiness(state())).toEqual({
-      kind: 'credential-missing',
-      displayName: 'DeepSeek',
-      ref: 'DEEPSEEK_API_KEY',
-    })
+  it('reports a missing writable effective credential', () => {
+    expect(deepSeekReadiness(state())).toEqual({ kind: 'credential-missing' })
   })
 
   it('accepts file and process-environment credentials without prompting', () => {

From fc8f992cde067b5802bf87908c62b58e058d7ee3 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 30 Jul 2026 18:56:56 +0800
Subject: [PATCH 6/7] fix(web): address onboarding review feedback

---
 ...seek-onboarding-credential-setup.i18n.yaml |  4 +-
 ...30-deepseek-onboarding-credential-setup.md |  4 +-
 ...deepseek-onboarding-credential-setup.zh.md |  4 +-
 .../tests/onboarding-deepseek-config.e2e.ts   |  2 +-
 docs/module-graph.md                          |  6 +-
 .../client/connection/src/client/fixture.ts   |  3 +-
 .../src/client/DeepSeekOnboardingDialog.tsx   | 61 +++++++++++--
 .../client/ui-models/src/client/locales.ts    | 12 ++-
 packages/client/ui-models/src/client/store.ts | 25 ++---
 .../tests/onboarding-dialog.spec.tsx          | 91 ++++++++++++++-----
 .../client/ui-models/tests/readiness.spec.ts  | 39 +++-----
 .../ui-settings/src/client/SettingsRoot.tsx   |  4 +-
 12 files changed, 168 insertions(+), 87 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
index dce650b9ef..8beabfa66e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
+++ b/.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: 9249b173f8f6da5dc2abf2fb147a3c9aba99c00f
-2026-07-30-deepseek-onboarding-credential-setup.zh.md: f3c647669bd9e0974b2c9f0c407eba0c600bc656
+2026-07-30-deepseek-onboarding-credential-setup.md: 3f75a0893623afc0908cb48f2b838321ed9dedd3
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: 62f8f0b99f167b22051aaddf7331a043bd2ea812
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
index 9249b173f8..3f75a08936 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
@@ -16,7 +16,7 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 **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 capability states stay honest.** An absent configurable-provider entry suppresses the form because it cannot repair the composition. A present provider whose settings or credential capability cannot be resolved renders an actionable deployment diagnostic. Cancel 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 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.
 
 ## Alternatives considered
 
@@ -26,7 +26,7 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 **Writing the API key into provider settings** — rejected because a literal secret would enter the settings mutation path and whole-section replacement cannot safely reconstruct redacted values. Credential storage is already the product seam and supplies immediate invalidation.
 
-**Showing the same key form when `llm-deepseek` is absent** — rejected because success would only store an unused environment reference; the browser has no supported operation that mounts the missing Cordis plugin.
+**Showing the prompt when `llm-deepseek` is absent** — rejected because browser navigation has no supported operation that mounts the missing Cordis plugin.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
index f3c647669b..62f8f0b99f 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 **浮层只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用浮层绝不持有或提交 secret。设置或凭据能力不可用时会保留部署诊断，并提供前往同一页面的入口；适配器缺失时仍直接跳过，因为导航无法挂载 Cordis 插件。
 
-**能力不可用时如实呈现。**可配置提供方条目缺失时不显示表单，因为它无法修复当前组合。提供方存在，但设置或凭据能力无法解析时，界面会显示可采取操作的部署诊断。取消只会在当前已挂载界面中关闭浮层，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可关闭已打开的浮层。
+**不可用状态如实呈现。**可配置提供方条目缺失时不显示浮层，因为导航无法修复当前组合。提供方存在，但设置或凭据能力无法解析时，界面会显示可采取操作的部署诊断；初始联接失败时会明确指出连接问题，并引导前往 Models 的重试界面。「稍后配置」只会在当前已挂载界面中关闭浮层，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可关闭已打开的浮层。
 
 ## 曾考虑的替代方案
 
@@ -26,7 +26,7 @@ Status: implemented
 
 **把 API key 写入提供方设置**：不予采用，因为字面量 secret 会进入设置变更路径，而整个分节替换无法安全重建脱敏值。凭据存储已经是产品 seam，并能立即发出失效事件。
 
-**`llm-deepseek` 缺失时仍显示同一个密钥表单**：不予采用，因为提交成功也只会存储一个无人使用的环境引用；浏览器没有任何受支持的操作可以挂载缺失的 Cordis 插件。
+**`llm-deepseek` 缺失时仍显示浮层**：不予采用，因为浏览器导航没有任何受支持的操作可以挂载缺失的 Cordis 插件。
 
 ## 后果
 
diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts
index c4e65b8bbb..62dd129982 100644
--- a/apps/web/tests/onboarding-deepseek-config.e2e.ts
+++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts
@@ -85,7 +85,7 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
-  it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
+  it('keeps the fixture inventory closed', async () => {
     await assertFixtureInventory(SNAPSHOT_DIR, ['missing.expected.md'])
   })
 })
diff --git a/docs/module-graph.md b/docs/module-graph.md
index fa044d0416..3f2f28f64b 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -360,6 +360,7 @@ flowchart TD
   pkg_client_ui_models --> pkg_client_connection
   pkg_client_ui_models --> pkg_client_runtime
   pkg_client_ui_models --> pkg_client_schema_form
+  pkg_client_ui_models --> pkg_client_ui_primitives
   pkg_client_ui_models --> pkg_client_ui_slots
   pkg_client_ui_models --> pkg_client_web_react
   pkg_client_ui_models --> pkg_invariants
@@ -486,7 +487,6 @@ flowchart TD
   pkg_sandbox_local --> pkg_llm
   pkg_sandbox_local --> pkg_sandbox
   pkg_sandbox_policy --> pkg_invariants
-  pkg_sandbox_policy --> pkg_paths
   pkg_sandbox_policy --> pkg_sandbox
   pkg_sandbox_policy --> pkg_session
   pkg_session_projection --> pkg_invariants
@@ -1072,7 +1072,7 @@ flowchart TD
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`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-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
+| [`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-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) |
@@ -1105,7 +1105,7 @@ flowchart TD
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
-| [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
+| [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`session-projection`](../packages/session-projection/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 39f3515fd8..f1c599b33a 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -1535,7 +1535,8 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
     },
     settings: {
       // Only the resolved DeepSeek address needed by first-run readiness is
-      // represented here; real schema-driven forms ride the HTTP transport.
+      // represented here. Fixture-backed journeys do not open its Models
+      // editor; real schema-driven forms ride the HTTP transport.
       describe: request => ok(request, {
         writable: true,
         namespaces: [{
diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
index 011970b10c..3d43bf2033 100644
--- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
@@ -9,7 +9,7 @@ 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'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
-import type { ModelsSettingsState, ModelsSettingsStore } from './store.ts'
+import type { DeepSeekReadiness, ModelsSettingsState, ModelsSettingsStore } from './store.ts'
 import { deepSeekReadiness } from './store.ts'
 import type { en } from './locales.ts'
 import styles from './DeepSeekOnboardingDialog.module.css'
@@ -28,6 +28,35 @@ export interface DeepSeekOnboardingInjected {
 export type DeepSeekOnboardingDialogProps =
   PropsRuntime<'settings.onboarding'> & DeepSeekOnboardingInjected
 
+type UnavailableReason = Extract<DeepSeekReadiness, { kind: 'unavailable' }>['reason']
+
+/* v8 ignore next 3 -- closed-union defaults only defend future source widening */
+function assertNever(_value: never): never {
+  throw new Error('unexpected DeepSeek onboarding state')
+}
+
+function unavailableDiagnostic(
+  reason: UnavailableReason,
+  t: DeepSeekOnboardingInjected['t'],
+): string {
+  switch (reason) {
+    case 'load-failed':
+      return t('onboardingLoadFailed')
+    case 'credentials-unavailable':
+      return t('onboardingCredentialsUnavailable')
+    case 'settings-read-only':
+    case 'credential-read-only':
+      return t('onboardingReadOnly')
+    case 'provider-inactive':
+    case 'settings-unavailable':
+    case 'credential-ref-unavailable':
+      return t('onboardingConfigurationUnavailable')
+    /* v8 ignore next -- every current unavailable reason is handled above */
+    default:
+      return assertNever(reason)
+  }
+}
+
 /**
  * Prompt a first-run user to open Models while the official adapter exists
  * and its effective credential is not configured.
@@ -53,13 +82,28 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
     openSection('models')
   }
 
-  if (!active || dismissed || readiness.kind === 'loading'
-    || readiness.kind === 'adapter-absent' || readiness.kind === 'configured') return null
+  if (!active || dismissed) return null
 
-  const unavailable = readiness.kind === 'unavailable'
-  const diagnostic = unavailable && readiness.reason === 'credentials-unavailable'
-    ? t('onboardingCredentialsUnavailable')
-    : t('onboardingConfigurationUnavailable')
+  let unavailableReason: UnavailableReason | undefined
+  switch (readiness.kind) {
+    case 'loading':
+    case 'adapter-absent':
+    case 'configured':
+      return null
+    case 'credential-missing':
+      unavailableReason = undefined
+      break
+    case 'unavailable':
+      unavailableReason = readiness.reason
+      break
+    /* v8 ignore next -- every current readiness variant is handled above */
+    default:
+      return assertNever(readiness)
+  }
+  const unavailable = unavailableReason !== undefined
+  const diagnostic = unavailableReason === undefined
+    ? undefined
+    : unavailableDiagnostic(unavailableReason, t)
 
   return (
     <Modal
@@ -73,13 +117,14 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
         <Button
           variant="primary"
           className={styles['primary']}
+          autoFocus
           onClick={openModels}
         >
           {t('onboardingGoToSettings')}
         </Button>
       )}
     >
-      {unavailable ? <p className={styles['diagnostic']}>{diagnostic}</p> : undefined}
+      {diagnostic === undefined ? undefined : <p className={styles['diagnostic']}>{diagnostic}</p>}
     </Modal>
   )
 }
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index 5472702800..f188af6d6c 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -32,8 +32,10 @@ export const en = {
   onboardingGoToSettings: 'Go to settings',
   onboardingLater: 'Configure later',
   onboardingUnavailableTitle: 'DeepSeek setup is unavailable',
-  onboardingCredentialsUnavailable: 'This deployment does not expose writable credential storage. Mount @deepseek-ai/dsh-credentials-local, then retry.',
-  onboardingConfigurationUnavailable: 'The live DeepSeek configuration capability cannot be resolved here. Check the deployment composition, then retry.',
+  onboardingLoadFailed: 'DeepSeek configuration could not be loaded. Check the connection and try again in Models.',
+  onboardingCredentialsUnavailable: 'Credential storage is unavailable in this deployment. Check the deployment configuration.',
+  onboardingReadOnly: 'This deployment does not allow the DeepSeek API key to be changed here. Ask an administrator to provide the credential.',
+  onboardingConfigurationUnavailable: 'DeepSeek configuration is unavailable in this deployment. Check the deployment composition.',
 }
 
 /** Chinese strings (same keys as {@link en}). */
@@ -68,6 +70,8 @@ export const zh: typeof en = {
   onboardingGoToSettings: '前往配置',
   onboardingLater: '稍后配置',
   onboardingUnavailableTitle: '无法在此配置 DeepSeek',
-  onboardingCredentialsUnavailable: '当前部署没有可写的凭据存储。请挂载 @deepseek-ai/dsh-credentials-local 后重试。',
-  onboardingConfigurationUnavailable: '无法在此解析 DeepSeek 的实时配置能力。请检查部署组合后重试。',
+  onboardingLoadFailed: '无法加载 DeepSeek 配置。请检查连接，然后在模型设置中重试。',
+  onboardingCredentialsUnavailable: '当前部署无法使用凭据存储。请检查部署配置。',
+  onboardingReadOnly: '当前部署不允许在此修改 DeepSeek API 密钥。请联系管理员提供凭据。',
+  onboardingConfigurationUnavailable: '当前部署无法使用 DeepSeek 配置。请检查部署组合。',
 }
diff --git a/packages/client/ui-models/src/client/store.ts b/packages/client/ui-models/src/client/store.ts
index 74f90b0067..d773a7100a 100644
--- a/packages/client/ui-models/src/client/store.ts
+++ b/packages/client/ui-models/src/client/store.ts
@@ -180,17 +180,18 @@ export class ModelsSettingsStore {
 export type DeepSeekReadiness =
   | { kind: 'loading' }
   | { kind: 'adapter-absent' }
-  | { kind: 'configured'; source: 'literal' | 'credential'; ref?: string; credential?: CredentialView }
+  | { kind: 'configured' }
   | { kind: 'credential-missing' }
   | {
     kind: 'unavailable'
     reason:
+      | 'load-failed'
       | 'provider-inactive'
       | 'settings-unavailable'
       | 'credential-ref-unavailable'
       | 'credentials-unavailable'
+      | 'settings-read-only'
       | 'credential-read-only'
-    message: string
   }
 
 /**
@@ -207,8 +208,7 @@ export function deepSeekReadiness(state: ModelsSettingsState): DeepSeekReadiness
   if (state.status === 'error') {
     return {
       kind: 'unavailable',
-      reason: 'settings-unavailable',
-      message: state.error ?? 'provider/settings describe failed',
+      reason: 'load-failed',
     }
   }
   const row = state.rows.find(candidate => candidate.entry.provider === 'deepseek-official')
@@ -217,51 +217,46 @@ export function deepSeekReadiness(state: ModelsSettingsState): DeepSeekReadiness
     return {
       kind: 'unavailable',
       reason: 'provider-inactive',
-      message: 'the deepseek-official route is not active',
     }
   }
   if (!row.configured) {
     return {
       kind: 'unavailable',
       reason: 'settings-unavailable',
-      message: `settings namespace "${row.entry.settingsNs}" did not resolve the provider profile`,
     }
   }
-  if (row.literalApiKeyConfigured) return { kind: 'configured', source: 'literal' }
+  if (row.literalApiKeyConfigured) return { kind: 'configured' }
   if (row.apiKeyEnv === undefined) {
     return {
       kind: 'unavailable',
       reason: 'credential-ref-unavailable',
-      message: 'the resolved DeepSeek settings do not name an apiKeyEnv credential reference',
     }
   }
   if (state.credentialError !== null) {
     return {
       kind: 'unavailable',
       reason: 'credentials-unavailable',
-      message: state.credentialError,
     }
   }
   if (row.credential === undefined) {
     return {
       kind: 'unavailable',
       reason: 'credentials-unavailable',
-      message: `credential reference "${row.apiKeyEnv}" was not described`,
     }
   }
   if (row.credential.configured) {
+    return { kind: 'configured' }
+  }
+  if (!state.writable) {
     return {
-      kind: 'configured',
-      source: 'credential',
-      ref: row.apiKeyEnv,
-      credential: row.credential,
+      kind: 'unavailable',
+      reason: 'settings-read-only',
     }
   }
   if (!row.credential.writable) {
     return {
       kind: 'unavailable',
       reason: 'credential-read-only',
-      message: `credential reference "${row.apiKeyEnv}" is missing and read-only`,
     }
   }
   return { kind: 'credential-missing' }
diff --git a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
index 3aa4294118..bb2e5c1992 100644
--- a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
+++ b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
@@ -24,37 +24,53 @@ function fail<T>(message: string): RpcResponse<T> {
 
 function harness(options: {
   provider?: boolean
+  providerActive?: boolean
+  settingsNamespace?: boolean
+  apiKeyEnv?: string | null
   literal?: boolean
   configured?: () => boolean
   credential?: { source?: string; writable: boolean }
   describeFailure?: string
+  settingsWritable?: boolean
+  providersRejectOnce?: boolean
 } = {}) {
   let fileConfigured = false
+  let rejectProviders = options.providersRejectOnce === true
   const configured = options.configured ?? (() => fileConfigured)
   const face = {
     llm: {
-      providers: () => Promise.resolve(ok({
-        providers: options.provider === false
-          ? []
-          : [{
-            provider: 'deepseek-official',
-            displayName: 'DeepSeek',
-            settingsNs: 'llm-deepseek',
-            settingsPath: [],
-            active: true,
-          }],
-      })),
+      providers: () => {
+        if (rejectProviders) {
+          rejectProviders = false
+          return Promise.reject(new Error('provider transport unavailable'))
+        }
+        return Promise.resolve(ok({
+          providers: options.provider === false
+            ? []
+            : [{
+              provider: 'deepseek-official',
+              displayName: 'DeepSeek',
+              settingsNs: 'llm-deepseek',
+              settingsPath: [],
+              active: options.providerActive ?? true,
+            }],
+        }))
+      },
     },
     settings: {
       describe: () => Promise.resolve(ok({
-        writable: true,
-        namespaces: [{
-          ns: 'llm-deepseek',
-          schema: {},
-          value: { apiKeyEnv: 'DEEPSEEK_API_KEY' },
-          applies: 'live' as const,
-          secrets: [{ path: ['apiKey'], set: options.literal === true }],
-        }],
+        writable: options.settingsWritable ?? true,
+        namespaces: options.settingsNamespace === false
+          ? []
+          : [{
+            ns: 'llm-deepseek',
+            schema: {},
+            value: options.apiKeyEnv === null
+              ? {}
+              : { apiKeyEnv: options.apiKeyEnv ?? 'DEEPSEEK_API_KEY' },
+            applies: 'live' as const,
+            secrets: [{ path: ['apiKey'], set: options.literal === true }],
+          }],
       })),
     },
     credentials: {
@@ -94,7 +110,9 @@ describe('DeepSeekOnboardingDialog', () => {
     render(<DeepSeekOnboardingDialog {...h.props} />)
     expect(await screen.findByRole('dialog', { name: en.onboardingTitle })).toBeTruthy()
     expect(screen.getByText(en.onboardingDescription)).toBeTruthy()
-    expect(screen.getByRole('button', { name: en.onboardingGoToSettings })).toBeTruthy()
+    const action = screen.getByRole('button', { name: en.onboardingGoToSettings })
+    expect(action).toBeTruthy()
+    expect(document.activeElement).toBe(action)
     expect(screen.queryByRole('textbox')).toBeNull()
   })
 
@@ -125,11 +143,38 @@ describe('DeepSeekOnboardingDialog', () => {
     expect(h.openSection).toHaveBeenCalledWith('models')
   })
 
-  it('uses the general diagnostic for a missing read-only credential', async () => {
-    const h = harness({ credential: { writable: false } })
+  it('explains read-only credential and settings deployments', async () => {
+    for (const h of [
+      harness({ credential: { writable: false } }),
+      harness({ settingsWritable: false }),
+    ]) {
+      const view = render(<DeepSeekOnboardingDialog {...h.props} />)
+      await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
+      expect(screen.getByText(en.onboardingReadOnly)).toBeTruthy()
+      view.unmount()
+    }
+  })
+
+  it('distinguishes an initial transport failure from deployment misconfiguration', async () => {
+    const h = harness({ providersRejectOnce: true })
     render(<DeepSeekOnboardingDialog {...h.props} />)
     await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
-    expect(screen.getByText(en.onboardingConfigurationUnavailable)).toBeTruthy()
+    expect(screen.getByText(en.onboardingLoadFailed)).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: en.onboardingGoToSettings }))
+    expect(h.openSection).toHaveBeenCalledWith('models')
+  })
+
+  it('uses the configuration diagnostic for inactive or unresolvable adapters', async () => {
+    for (const h of [
+      harness({ providerActive: false }),
+      harness({ settingsNamespace: false }),
+      harness({ apiKeyEnv: null }),
+    ]) {
+      const view = render(<DeepSeekOnboardingDialog {...h.props} />)
+      await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
+      expect(screen.getByText(en.onboardingConfigurationUnavailable)).toBeTruthy()
+      view.unmount()
+    }
   })
 
   it('skips an absent adapter and already-configured literal or environment credentials', async () => {
diff --git a/packages/client/ui-models/tests/readiness.spec.ts b/packages/client/ui-models/tests/readiness.spec.ts
index d9f77bb7a8..d2da587c16 100644
--- a/packages/client/ui-models/tests/readiness.spec.ts
+++ b/packages/client/ui-models/tests/readiness.spec.ts
@@ -50,59 +50,48 @@ describe('deepSeekReadiness', () => {
   it('accepts file and process-environment credentials without prompting', () => {
     expect(deepSeekReadiness(state({
       rows: [row({ credential: { configured: true, source: 'file', writable: true } })],
-    }))).toMatchObject({
-      kind: 'configured',
-      source: 'credential',
-      ref: 'DEEPSEEK_API_KEY',
-      credential: { source: 'file', writable: true },
-    })
+    }))).toEqual({ kind: 'configured' })
     expect(deepSeekReadiness(state({
       rows: [row({ credential: { configured: true, source: 'env', writable: false } })],
-    }))).toMatchObject({
-      kind: 'configured',
-      source: 'credential',
-      credential: { source: 'env', writable: false },
-    })
+    }))).toEqual({ kind: 'configured' })
   })
 
   it('accepts the redacted literal-key sidecar before judging the credential domain', () => {
     expect(deepSeekReadiness(state({
       credentialError: 'credentials service absent',
       rows: [row({ literalApiKeyConfigured: true, credential: undefined })],
-    }))).toEqual({ kind: 'configured', source: 'literal' })
+    }))).toEqual({ kind: 'configured' })
   })
 
   it('turns missing capabilities and inconsistent descriptors into diagnostics', () => {
     expect(deepSeekReadiness(state({ status: 'error', error: 'settings down' }))).toEqual({
       kind: 'unavailable',
-      reason: 'settings-unavailable',
-      message: 'settings down',
-    })
-    expect(deepSeekReadiness(state({ status: 'error', error: null }))).toMatchObject({
-      kind: 'unavailable',
-      reason: 'settings-unavailable',
+      reason: 'load-failed',
     })
     expect(deepSeekReadiness(state({
       rows: [row({ entry: { ...row().entry, active: false } })],
-    }))).toMatchObject({ kind: 'unavailable', reason: 'provider-inactive' })
+    }))).toEqual({ kind: 'unavailable', reason: 'provider-inactive' })
     expect(deepSeekReadiness(state({
       rows: [row({ configured: false })],
-    }))).toMatchObject({ kind: 'unavailable', reason: 'settings-unavailable' })
+    }))).toEqual({ kind: 'unavailable', reason: 'settings-unavailable' })
     expect(deepSeekReadiness(state({
       rows: [row({ apiKeyEnv: undefined })],
-    }))).toMatchObject({ kind: 'unavailable', reason: 'credential-ref-unavailable' })
+    }))).toEqual({ kind: 'unavailable', reason: 'credential-ref-unavailable' })
     expect(deepSeekReadiness(state({
       credentialError: 'credentials service is absent',
-    }))).toMatchObject({
+    }))).toEqual({
       kind: 'unavailable',
       reason: 'credentials-unavailable',
-      message: 'credentials service is absent',
     })
     expect(deepSeekReadiness(state({
       rows: [row({ credential: undefined })],
-    }))).toMatchObject({ kind: 'unavailable', reason: 'credentials-unavailable' })
+    }))).toEqual({ kind: 'unavailable', reason: 'credentials-unavailable' })
     expect(deepSeekReadiness(state({
       rows: [row({ credential: { configured: false, writable: false } })],
-    }))).toMatchObject({ kind: 'unavailable', reason: 'credential-read-only' })
+    }))).toEqual({ kind: 'unavailable', reason: 'credential-read-only' })
+    expect(deepSeekReadiness(state({ writable: false }))).toEqual({
+      kind: 'unavailable',
+      reason: 'settings-read-only',
+    })
   })
 })
diff --git a/packages/client/ui-settings/src/client/SettingsRoot.tsx b/packages/client/ui-settings/src/client/SettingsRoot.tsx
index 4fa5b075b6..cfa3ac6cef 100644
--- a/packages/client/ui-settings/src/client/SettingsRoot.tsx
+++ b/packages/client/ui-settings/src/client/SettingsRoot.tsx
@@ -5,7 +5,9 @@
  * close label, sections) arrives from registrants through slots; accessible
  * 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.
+ * 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.
  */
 import { useCallback, useEffect, useId, useRef, useState } from 'react'
 import clsx from 'clsx'

From 15636fbb8e2d3a65089fdc5733e2f67dcb7a11a8 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 31 Jul 2026 00:44:24 +0800
Subject: [PATCH 7/7] fix(web): skip unavailable DeepSeek onboarding modal

---
 ...seek-onboarding-credential-setup.i18n.yaml |  4 +-
 ...30-deepseek-onboarding-credential-setup.md |  8 ++--
 ...deepseek-onboarding-credential-setup.zh.md |  8 ++--
 packages/client/ui-models/README.i18n.yaml    |  4 +-
 packages/client/ui-models/README.md           |  2 +-
 packages/client/ui-models/README.zh.md        |  2 +-
 .../DeepSeekOnboardingDialog.module.css       |  7 ---
 .../src/client/DeepSeekOnboardingDialog.tsx   | 44 ++---------------
 .../client/ui-models/src/client/locales.ts    | 10 ----
 packages/client/ui-models/src/client/store.ts |  9 ++--
 .../tests/onboarding-dialog.spec.tsx          | 47 +++++--------------
 .../client/ui-models/tests/readiness.spec.ts  |  8 ++++
 12 files changed, 44 insertions(+), 109 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
index 8beabfa66e..dde9f82a6d 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
+++ b/.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: 571b81a1a2e6f392f2553070048964d49941aae9
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: 744c30814f84d063f196ce20ba48fb993d0b7713
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
index 3f75a08936..571b81a1a2 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
@@ -10,13 +10,13 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 ## Decision
 
-**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.
+**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 owned by the `llm-deepseek` namespace and empty settings path, reads the effective `apiKeyEnv`, and evaluates the matching credential descriptor. A live route with the same provider id but no matching configurable-provider declaration is adapter-absent for onboarding. 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 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.
+**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.
 
-**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 do not capture the product.** An absent configurable-provider entry, inactive route, failed initial join, read-only deployment, or unresolved settings or credential capability suppresses the modal because the onboarding action cannot repair that state. The Models page remains the deployment diagnostic and retry surface. Configure later dismisses a missing-credential 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.
 
 ## 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 first-run flow 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. The full keyless Web replay lane also pins that a non-configurable replay route with the same provider id does not block unrelated journeys. 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.
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
index 62f8f0b99f..744c30814f 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
@@ -10,13 +10,13 @@ Status: implemented
 
 ## 决策
 
-**Models 与首次使用引导共享同一个就绪状态投影。**`ui-models` 维护一个 store，把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取 `deepseek-official` 可配置提供方条目，解析其 `settingsNs` 与 `settingsPath`，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，也会判定为就绪，兼容配置因此不会误触发浮层；通过进程环境提供的凭据若已配置，同样判定为就绪并保持只读。
+**Models 与首次使用引导共享同一个就绪状态投影。**`ui-models` 维护一个 store，把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取由 `llm-deepseek` namespace 所有、设置路径为空的 `deepseek-official` 可配置提供方条目，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。同一提供方 ID 下的存活路由若没有匹配的可配置提供方声明，首次使用引导会将其视为适配器缺失。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，也会判定为就绪，兼容配置因此不会误触发浮层；通过进程环境提供的凭据若已配置，同样判定为就绪并保持只读。
 
 **设置外壳只贡献导航状态，不持有提供方策略。**`ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并告知注册方当前界面是否为空白 Hero。其私有 `openSection(id)` 回调会打开设置面板并切换到一个已注册分区。`ui-models` 沿用 Models 分区所使用、感知 slot 声明的延迟注册路径来注册 DeepSeek 浮层，因此插件加载顺序不会成为契约。
 
-**浮层只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用浮层绝不持有或提交 secret。设置或凭据能力不可用时会保留部署诊断，并提供前往同一页面的入口；适配器缺失时仍直接跳过，因为导航无法挂载 Cordis 插件。
+**浮层只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用浮层绝不持有或提交 secret。
 
-**不可用状态如实呈现。**可配置提供方条目缺失时不显示浮层，因为导航无法修复当前组合。提供方存在，但设置或凭据能力无法解析时，界面会显示可采取操作的部署诊断；初始联接失败时会明确指出连接问题，并引导前往 Models 的重试界面。「稍后配置」只会在当前已挂载界面中关闭浮层，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可关闭已打开的浮层。
+**不可用状态不会拦截产品交互。**可配置提供方条目缺失、路由未激活、初始联接失败、部署只读、设置能力无法解析或凭据能力无法解析时均不显示模态框，因为首次使用引导的操作无法修复这些状态。Models 页仍是部署诊断与重试界面。「稍后配置」只会在当前已挂载界面中关闭凭据缺失浮层，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可关闭已打开的浮层。
 
 ## 曾考虑的替代方案
 
@@ -30,4 +30,4 @@ Status: implemented
 
 ## 后果
 
-首次使用流程现在无需重启即可引导用户前往随产品提供的适配器已有的编辑器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，依照浮层操作前往 Models，通过该页面把生成的密钥存入该目录的 `.env`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的页面报告已配置。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、导航、取消和外部失效行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。
+首次使用流程无需重启即可引导用户前往随产品提供的适配器已有的编辑器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，依照浮层操作前往 Models，通过该页面把生成的密钥存入该目录的 `.env`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的页面报告已配置。完整的无密钥 Web 回放链路还固化了同一提供方 ID 下的不可配置回放路由不会阻塞无关流程。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、导航、取消和外部失效行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index 0355080b11..951b1d04fe 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/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: adfbc084e1b0e227d50032cb6c924401b81c6a79
+README.zh.md: 4ee7d4efa729fdccee392ab8e55078b5a4a239ef
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index aac437a13f..adfbc084e1 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -6,7 +6,7 @@ Models settings plugin: the provider configuration page and official-DeepSeek fi
 
 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 first-run overlay projects `deepseek-official` readiness from that same joined snapshot. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured literal `apiKey` secret sidecar or configured credential reference suppresses the prompt, including a read-only launch-environment credential. Only a mounted adapter with a missing writable reference shows the 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, inactive route, failed join, read-only deployment, or unusable settings or credential capability is skipped so onboarding cannot block the rest of the product; the Models page remains the diagnostic surface.
 
 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.
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index 468537ac21..4ee7d4efa7 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -6,7 +6,7 @@
 
 行是*已配置*的提供方（其 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-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此不会把同一提供方 ID 下没有相应声明的存活路由视为可通过配置修复。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，浮层就不再显示，其中包括来自启动环境且只读的凭据。只有适配器已挂载、引用可写但尚未配置时，浮层才显示一个操作按钮，用于打开「设置」的 Models 分区；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，浮层绝不持有 secret。适配器缺失、路由未激活、联接失败、部署只读、设置能力不可用或凭据能力不可用时均跳过，以免首次使用引导阻塞产品的其他部分；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 新生的路由都无需轮询即可收敛。
 
diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
index 6823556903..577b8e0287 100644
--- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
@@ -2,13 +2,6 @@
   width: min(420px, 100%);
 }
 
-.diagnostic {
-  margin: 0;
-  font-size: 13px;
-  line-height: 20px;
-  color: var(--dsw-alias-label-secondary);
-}
-
 .primary {
   width: 100%;
 }
diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
index 3d43bf2033..b4bfcf02d0 100644
--- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
@@ -9,7 +9,7 @@ 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'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
-import type { DeepSeekReadiness, ModelsSettingsState, ModelsSettingsStore } from './store.ts'
+import type { ModelsSettingsState, ModelsSettingsStore } from './store.ts'
 import { deepSeekReadiness } from './store.ts'
 import type { en } from './locales.ts'
 import styles from './DeepSeekOnboardingDialog.module.css'
@@ -28,35 +28,11 @@ export interface DeepSeekOnboardingInjected {
 export type DeepSeekOnboardingDialogProps =
   PropsRuntime<'settings.onboarding'> & DeepSeekOnboardingInjected
 
-type UnavailableReason = Extract<DeepSeekReadiness, { kind: 'unavailable' }>['reason']
-
 /* v8 ignore next 3 -- closed-union defaults only defend future source widening */
 function assertNever(_value: never): never {
   throw new Error('unexpected DeepSeek onboarding state')
 }
 
-function unavailableDiagnostic(
-  reason: UnavailableReason,
-  t: DeepSeekOnboardingInjected['t'],
-): string {
-  switch (reason) {
-    case 'load-failed':
-      return t('onboardingLoadFailed')
-    case 'credentials-unavailable':
-      return t('onboardingCredentialsUnavailable')
-    case 'settings-read-only':
-    case 'credential-read-only':
-      return t('onboardingReadOnly')
-    case 'provider-inactive':
-    case 'settings-unavailable':
-    case 'credential-ref-unavailable':
-      return t('onboardingConfigurationUnavailable')
-    /* v8 ignore next -- every current unavailable reason is handled above */
-    default:
-      return assertNever(reason)
-  }
-}
-
 /**
  * Prompt a first-run user to open Models while the official adapter exists
  * and its effective credential is not configured.
@@ -84,34 +60,26 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
 
   if (!active || dismissed) return null
 
-  let unavailableReason: UnavailableReason | undefined
   switch (readiness.kind) {
     case 'loading':
     case 'adapter-absent':
     case 'configured':
+    case 'unavailable':
       return null
     case 'credential-missing':
-      unavailableReason = undefined
-      break
-    case 'unavailable':
-      unavailableReason = readiness.reason
       break
     /* v8 ignore next -- every current readiness variant is handled above */
     default:
       return assertNever(readiness)
   }
-  const unavailable = unavailableReason !== undefined
-  const diagnostic = unavailableReason === undefined
-    ? undefined
-    : unavailableDiagnostic(unavailableReason, t)
 
   return (
     <Modal
       open
       onClose={close}
-      title={unavailable ? t('onboardingUnavailableTitle') : t('onboardingTitle')}
+      title={t('onboardingTitle')}
       closeLabel={t('onboardingLater')}
-      {...(unavailable ? {} : { description: t('onboardingDescription') })}
+      description={t('onboardingDescription')}
       className={styles['dialog'] as string}
       footer={(
         <Button
@@ -123,8 +91,6 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
           {t('onboardingGoToSettings')}
         </Button>
       )}
-    >
-      {diagnostic === undefined ? undefined : <p className={styles['diagnostic']}>{diagnostic}</p>}
-    </Modal>
+    />
   )
 }
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index 503b3aa3dc..44339d588c 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -32,11 +32,6 @@ export const en = {
   onboardingDescription: 'Configure the official DeepSeek provider to start building.',
   onboardingGoToSettings: 'Go to settings',
   onboardingLater: 'Configure later',
-  onboardingUnavailableTitle: 'DeepSeek setup is unavailable',
-  onboardingLoadFailed: 'DeepSeek configuration could not be loaded. Check the connection and try again in Models.',
-  onboardingCredentialsUnavailable: 'Credential storage is unavailable in this deployment. Check the deployment configuration.',
-  onboardingReadOnly: 'This deployment does not allow the DeepSeek API key to be changed here. Ask an administrator to provide the credential.',
-  onboardingConfigurationUnavailable: 'DeepSeek configuration is unavailable in this deployment. Check the deployment composition.',
 }
 
 /** Chinese strings (same keys as {@link en}). */
@@ -71,9 +66,4 @@ export const zh: typeof en = {
   onboardingDescription: '配置 DeepSeek 官方模型，即可开始使用。',
   onboardingGoToSettings: '前往配置',
   onboardingLater: '稍后配置',
-  onboardingUnavailableTitle: '无法在此配置 DeepSeek',
-  onboardingLoadFailed: '无法加载 DeepSeek 配置。请检查连接，然后在模型设置中重试。',
-  onboardingCredentialsUnavailable: '当前部署无法使用凭据存储。请检查部署配置。',
-  onboardingReadOnly: '当前部署不允许在此修改 DeepSeek API 密钥。请联系管理员提供凭据。',
-  onboardingConfigurationUnavailable: '当前部署无法使用 DeepSeek 配置。请检查部署组合。',
 }
diff --git a/packages/client/ui-models/src/client/store.ts b/packages/client/ui-models/src/client/store.ts
index eda36882ef..282f21fe75 100644
--- a/packages/client/ui-models/src/client/store.ts
+++ b/packages/client/ui-models/src/client/store.ts
@@ -215,8 +215,8 @@ export type DeepSeekReadiness =
 
 /**
  * Project official-DeepSeek readiness from the provider/settings/credential
- * join used by the Models page. A missing directory entry means the adapter
- * is not mounted and therefore cannot be repaired by navigating to Models.
+ * join used by the Models page. A missing official configurable-provider
+ * declaration means the adapter is not repairable by navigating to Models.
  * @param state - current shared Models join snapshot.
  * @returns the onboarding state without reading a parallel fact source.
  */
@@ -230,7 +230,10 @@ export function deepSeekReadiness(state: ModelsSettingsState): DeepSeekReadiness
       reason: 'load-failed',
     }
   }
-  const row = state.rows.find(candidate => candidate.entry.provider === 'deepseek-official')
+  const row = state.rows.find(candidate =>
+    candidate.entry.provider === 'deepseek-official'
+    && candidate.entry.settingsNs === 'llm-deepseek'
+    && candidate.entry.settingsPath.length === 0)
   if (row === undefined) return { kind: 'adapter-absent' }
   if (!row.entry.active) {
     return {
diff --git a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
index be49d52ddd..1d757d340a 100644
--- a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
+++ b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
@@ -25,6 +25,7 @@ function fail<T>(message: string): RpcResponse<T> {
 function harness(options: {
   provider?: boolean
   providerActive?: boolean
+  providerSettingsNs?: string
   settingsNamespace?: boolean
   apiKeyEnv?: string | null
   literal?: boolean
@@ -32,16 +33,14 @@ function harness(options: {
   credential?: { source?: string; writable: boolean }
   describeFailure?: string
   settingsWritable?: boolean
-  providersRejectOnce?: boolean
+  providersReject?: boolean
 } = {}) {
   let fileConfigured = false
-  let rejectProviders = options.providersRejectOnce === true
   const configured = options.configured ?? (() => fileConfigured)
   const face = {
     llm: {
       providers: () => {
-        if (rejectProviders) {
-          rejectProviders = false
+        if (options.providersReject === true) {
           return Promise.reject(new Error('provider transport unavailable'))
         }
         return Promise.resolve(ok({
@@ -50,7 +49,7 @@ function harness(options: {
             : [{
               provider: 'deepseek-official',
               displayName: 'DeepSeek',
-              settingsNs: 'llm-deepseek',
+              settingsNs: options.providerSettingsNs ?? 'llm-deepseek',
               settingsPath: [],
               active: options.providerActive ?? true,
             }],
@@ -135,45 +134,20 @@ describe('DeepSeekOnboardingDialog', () => {
     expect(h.openSection).not.toHaveBeenCalled()
   })
 
-  it('routes an unavailable credential deployment to Models with a diagnostic', async () => {
-    const h = harness({ describeFailure: 'credentials service is absent' })
-    render(<DeepSeekOnboardingDialog {...h.props} />)
-    await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
-    expect(screen.getByText(en.onboardingCredentialsUnavailable)).toBeTruthy()
-    fireEvent.click(screen.getByRole('button', { name: en.onboardingGoToSettings }))
-    expect(h.openSection).toHaveBeenCalledWith('models')
-  })
-
-  it('explains read-only credential and settings deployments', async () => {
+  it('does not block the product when DeepSeek setup is unavailable', async () => {
     for (const h of [
+      harness({ describeFailure: 'credentials service is absent' }),
       harness({ credential: { writable: false } }),
       harness({ settingsWritable: false }),
-    ]) {
-      const view = render(<DeepSeekOnboardingDialog {...h.props} />)
-      await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
-      expect(screen.getByText(en.onboardingReadOnly)).toBeTruthy()
-      view.unmount()
-    }
-  })
-
-  it('distinguishes an initial transport failure from deployment misconfiguration', async () => {
-    const h = harness({ providersRejectOnce: true })
-    render(<DeepSeekOnboardingDialog {...h.props} />)
-    await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
-    expect(screen.getByText(en.onboardingLoadFailed)).toBeTruthy()
-    fireEvent.click(screen.getByRole('button', { name: en.onboardingGoToSettings }))
-    expect(h.openSection).toHaveBeenCalledWith('models')
-  })
-
-  it('uses the configuration diagnostic for inactive or unresolvable adapters', async () => {
-    for (const h of [
+      harness({ providersReject: true }),
       harness({ providerActive: false }),
       harness({ settingsNamespace: false }),
       harness({ apiKeyEnv: null }),
     ]) {
       const view = render(<DeepSeekOnboardingDialog {...h.props} />)
-      await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle })
-      expect(screen.getByText(en.onboardingConfigurationUnavailable)).toBeTruthy()
+      await act(async () => { await h.controller.load() })
+      expect(screen.queryByRole('dialog')).toBeNull()
+      expect(h.openSection).not.toHaveBeenCalled()
       view.unmount()
     }
   })
@@ -181,6 +155,7 @@ describe('DeepSeekOnboardingDialog', () => {
   it('skips an absent adapter and already-configured literal or environment credentials', async () => {
     for (const h of [
       harness({ provider: false }),
+      harness({ providerSettingsNs: '' }),
       harness({ literal: true, describeFailure: 'credential seam absent' }),
       harness({ configured: () => true, credential: { source: 'env', writable: false } }),
     ]) {
diff --git a/packages/client/ui-models/tests/readiness.spec.ts b/packages/client/ui-models/tests/readiness.spec.ts
index d2da587c16..d03cd130f4 100644
--- a/packages/client/ui-models/tests/readiness.spec.ts
+++ b/packages/client/ui-models/tests/readiness.spec.ts
@@ -41,6 +41,14 @@ describe('deepSeekReadiness', () => {
     expect(deepSeekReadiness(state({ status: 'idle', rows: [] }))).toEqual({ kind: 'loading' })
     expect(deepSeekReadiness(state({ status: 'loading', rows: [] }))).toEqual({ kind: 'loading' })
     expect(deepSeekReadiness(state({ rows: [] }))).toEqual({ kind: 'adapter-absent' })
+    expect(deepSeekReadiness(state({
+      rows: [row({
+        entry: {
+          ...row().entry,
+          settingsNs: '',
+        },
+      })],
+    }))).toEqual({ kind: 'adapter-absent' })
   })
 
   it('reports a missing writable effective credential', () => {