Merge remote-tracking branch 'origin/master' into worktree/web-multimodal-image-input

# Conflicts: # docs/architecture.i18n.yaml # docs/architecture.md # docs/architecture.zh.md # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/core.i18n.yaml # docs/core-data-structures/llm-streaming.i18n.yaml # docs/event-producer-consumer.md # docs/module-graph.md # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # packages/client/connection/README.i18n.yaml # packages/client/connection/README.md # packages/client/connection/README.zh.md # packages/client/connection/src/client/fixture.ts # packages/client/runtime/README.i18n.yaml # packages/client/runtime/README.md # packages/client/runtime/README.zh.md # packages/client/ui-conversation/README.i18n.yaml # packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx # packages/client/ui-conversation/src/client/chat/ChatView.tsx # packages/host/apiproxy/README.i18n.yaml # packages/host/apiproxy/src/api-proxy.ts # packages/llm/llm-deepseek/tests/adapter.spec.ts # packages/llm/llm-pi-ai/README.i18n.yaml # packages/llm/llm-pi-ai/src/index.ts # packages/llm/llm/README.i18n.yaml # packages/llm/llm/README.md # packages/llm/llm/README.zh.md # packages/llm/llm/src/index.ts # packages/llm/llm/src/types.ts
2026-07-31 02:14:07 +08:00
parent 451d15429e 085383b145
commit a975eda638
465 changed files with 9284 additions and 1401 deletions
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/connection/README.md
-README.md: 4a4ce324a0482072164d3c4f6badd464bfacfc6f
-README.zh.md: 7fb421ae206563a625df5bd53fbcef1f585bd269
+README.md: e561fdccb0fbe63c05f93823e32fbebe34ac38dc
+README.zh.md: 321045bccee0cdcc49d0fd75c45fbde6c50f85cf
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,7 +2,7 @@

 English | [中文](README.zh.md)

-Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. Each successful generation validates `host.describe` before `onConnected`; a business-error response fails the generation like a transport error. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. Contract: api-contracts v3 §3.
+Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. Each successful generation validates `host.describe` before `onConnected`; a business-error response fails the generation like a transport error. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`, reads included, since describing returns the exposed configuration and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. Contract: api-contracts v3 §3.

 ## /api browser-trust fence

--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。每个成功连接代都会在 `onConnected` 前校验 `host.describe`；业务错误响应会像传输错误一样使该连接代失败。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。契约：api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。每个成功连接代都会在 `onConnected` 前校验 `host.describe`；业务错误响应会像传输错误一样使该连接代失败。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`，读取也在内，因为 describe 会返回已暴露的配置，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。契约：api-contracts v3 §3。

 ## /api 浏览器信任栅栏

--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -14,6 +14,8 @@ export type {
  ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
  InboxItemId, ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels,
  GoalsApi, GoalRef,
+  SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView,
+  CredentialsApi, CredentialView, ConfigurableProviderView, LlmApi,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
 export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
 export type {
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -29,7 +29,7 @@ import type {
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
  ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
-  ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
+  ModelProviderGroup, ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
  ToolCallView, ToolEventView, ToolResultView, WorkspaceId, WorkspaceView,
 } from './api.ts'
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -156,6 +156,35 @@ const OPENAI_REASONING = {
  defaultEffort: 'medium',
 }

+/** Catalog served by `session.models` and `llm.models` alike (fresh copies per call). */
+function fixtureModelGroups(): ModelProviderGroup[] {
+  return [
+    {
+      id: 'deepseek-official',
+      name: 'DeepSeek',
+      models: [
+        {
+          id: 'deepseek-v4-flash',
+          name: 'DeepSeek-V4-Flash',
+          description: '快速响应',
+          reasoning: DEEPSEEK_REASONING,
+        },
+        {
+          id: 'deepseek-v4-pro',
+          name: 'DeepSeek-V4-Pro',
+          description: '复杂任务',
+          reasoning: DEEPSEEK_REASONING,
+        },
+      ],
+    },
+    {
+      id: 'openai',
+      name: 'OpenAI',
+      models: [{ id: 'gpt-5', name: 'GPT-5', reasoning: OPENAI_REASONING }],
+    },
+  ]
+}
+
 function sid(id: string): SessionId {
  return id as SessionId
 }
@@ -732,13 +761,19 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
  const logs = new Map<SessionId, SessionEvent[]>([[sid('fx-alpha'), buildAlphaLog()]])
  const modelTargets = new Map<SessionId, ModelTarget>(sessions.map(session => [
    session.sessionId,
-    { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
  ]))
  const nextTurn = new Map<SessionId, number>([[sid('fx-alpha'), 67]])
  const attachments = new Map<string, { attachment: ImageAttachmentRef; data: string }>([[
    String(FIXTURE_IMAGE_REF.attachmentId),
    { attachment: FIXTURE_IMAGE_REF, data: FIXTURE_IMAGE_DATA },
  ]])
+  /** Credential store double: set/unset flip the describe badge, values never read back. */
+  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],
+  ])
  let nextSession = 1
  let nextRpc = 1
  let attachedSessions = options.empty ? 0 : 1
@@ -1053,7 +1088,7 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
          sessionId: requestedId ?? sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, blank: true, cwd,
        }
        sessions.push(created)
-        modelTargets.set(created.sessionId, { provider: 'deepseek', model: 'deepseek-v4-flash' })
+        modelTargets.set(created.sessionId, { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
        attachedSessions += 1
        const emitSession = (): void => {
          // Mirrors the host: the frame fires at creation, so blank is constantly true.
@@ -1163,32 +1198,8 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
      },
      models: request => ok(request, {
        current: modelTargets.get(request.payload.sessionId)
-          ?? { provider: 'deepseek', model: 'deepseek-v4-flash' },
-        groups: [
-          {
-            id: 'deepseek',
-            name: 'DeepSeek',
-            models: [
-              {
-                id: 'deepseek-v4-flash',
-                name: 'DeepSeek-V4-Flash',
-                description: '快速响应',
-                reasoning: DEEPSEEK_REASONING,
-              },
-              {
-                id: 'deepseek-v4-pro',
-                name: 'DeepSeek-V4-Pro',
-                description: '复杂任务',
-                reasoning: DEEPSEEK_REASONING,
-              },
-            ],
-          },
-          {
-            id: 'openai',
-            name: 'OpenAI',
-            models: [{ id: 'gpt-5', name: 'GPT-5', reasoning: OPENAI_REASONING }],
-          },
-        ],
+          ?? { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+        groups: fixtureModelGroups(),
        failures: [],
      }),
      selectModel: (request) => {
@@ -1671,6 +1682,64 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
        }
      },
    },
+    settings: {
+      // Only the resolved DeepSeek address needed by first-run readiness is
+      // 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: [{
+          ns: 'llm-deepseek',
+          schema: {},
+          value: { apiKeyEnv: 'DEEPSEEK_API_KEY' },
+          applies: 'live',
+          secrets: [{ path: ['apiKey'], set: false }],
+          revision: 0,
+        }],
+      }),
+      update: request => err(request, {
+        code: 'settings-rejected',
+        message: 'fixture: the minimal readiness settings descriptor is read-only',
+        details: { ns: request.payload.ns },
+      }),
+      replace: request => err(request, {
+        code: 'settings-rejected',
+        message: 'fixture: the minimal readiness settings descriptor is read-only',
+        details: { ns: request.payload.ns },
+      }),
+      mutate: request => err(request, {
+        code: 'settings-rejected',
+        message: 'fixture: no settings namespaces are registered',
+        details: { ns: request.payload.ns },
+      }),
+    },
+    credentials: {
+      describe: request => ok(request, {
+        credentials: Object.fromEntries(request.payload.refs.map(ref => [ref, {
+          configured: fixtureCredentials.has(ref),
+          ...fixtureCredentials.has(ref) ? { source: 'file' } : {},
+          writable: true,
+        }])),
+      }),
+      set: (request) => {
+        fixtureCredentials.set(request.payload.ref, true)
+        return ok(request, {})
+      },
+      unset: (request) => {
+        fixtureCredentials.delete(request.payload.ref)
+        return ok(request, {})
+      },
+    },
+    llm: {
+      providers: request => ok(request, {
+        providers: [
+          { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [], active: true },
+          { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'], active: true },
+          { provider: 'anthropic', displayName: 'anthropic', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'anthropic'], active: false },
+        ],
+      }),
+      models: request => ok(request, { groups: fixtureModelGroups(), failures: [] }),
+    },
    respond(message: ClientResponse): Promise<RpcReceipt> {
      // Same routing discipline as the host: rpcId first, then the payload's
      // audit correlation; a settled or unknown id is not-pending.
@@ -1765,6 +1834,15 @@ export class FixtureApiClient extends AbstractApiClient {
      case 'goal.resume': return this.api.goals.resume(request)
      case 'goal.complete': return this.api.goals.complete(request)
      case 'goal.clear': return this.api.goals.clear(request)
+      case 'settings.describe': return this.api.settings.describe(request)
+      case 'settings.update': return this.api.settings.update(request)
+      case 'settings.replace': return this.api.settings.replace(request)
+      case 'settings.mutate': return this.api.settings.mutate(request)
+      case 'credentials.describe': return this.api.credentials.describe(request)
+      case 'credentials.set': return this.api.credentials.set(request)
+      case 'credentials.unset': return this.api.credentials.unset(request)
+      case 'llm.providers': return this.api.llm.providers(request)
+      case 'llm.models': return this.api.llm.models(request)
    }
  }

--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -22,6 +22,8 @@ export type {
  ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
  HostDescription, IApiClient, SessionId, SessionEvent, ContentBlock, StreamChunk,
  GoalsApi, GoalRef,
+  SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView,
+  CredentialsApi, CredentialView, ConfigurableProviderView, LlmApi,
 } from './api.ts'
 export { RpcId, AbstractApiClient, transportError } from './api.ts'

--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -37,10 +37,38 @@ export const Config: z<ConnectionConfig> = z.object({
  trustedHosts: z.array(String).default([]),
 })

+/**
+ * Methods gated to loopback even on a trusted-host deployment. Native dialogs
+ * act on the host machine; the settings and credential domains mutate the
+ * user's configuration and secret store, and READING them is equally
+ * privileged — `settings.describe` returns every exposed namespace's
+ * configuration and `credentials.describe` reports whether an arbitrary
+ * environment-variable name is configured and where from, which is
+ * reconnaissance no anonymous caller should have. `trustedHosts` is a
+ * DNS-rebinding fence, explicitly not authentication, so the whole
+ * configuration plane stays loopback-same-origin until a real authentication
+ * layer exists. The model catalog (`llm.providers`, `llm.models`) is
+ * deliberately NOT here: it carries provider ids, display names, and model
+ * lists — no endpoints, keys, or key state — and a LAN client's model picker
+ * legitimately needs it.
+ */
+const PRIVILEGED_METHODS = new Set([
+  'host.pickDirectory',
+  'host.openPath',
+  'settings.describe',
+  'settings.update',
+  'settings.replace',
+  'credentials.describe',
+  'credentials.set',
+  'credentials.unset',
+])
+
 /**
 * Mounts the API gateway under the browser transport prefix. Every request on
 * the prefix passes the browser-trust fence first (DNS-rebinding and
- * cross-site defense — [api-request-trust](./api-request-trust.ts)).
+ * cross-site defense — [api-request-trust](./api-request-trust.ts));
+ * privileged methods additionally pass it with an empty trust list, which
+ * pins them to loopback.
 * @param ctx - Host plugin context.
 * @param config - resolved plugin config (schema defaults applied).
 */
@@ -58,7 +86,14 @@ export function apply(ctx: Context, config?: ConnectionConfig): void {
    kind: 'prefix',
    path: API_PATH,
    handler: async (req, res) => {
-      if (!isTrustedApiRequest(req, trustedHosts)) {
+      const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
+      const method = pathname.startsWith(`${API_PATH}/`)
+        ? pathname.slice(API_PATH.length + 1)
+        : undefined
+      const allowed = method !== undefined && PRIVILEGED_METHODS.has(method)
+        ? isTrustedApiRequest(req, [])
+        : isTrustedApiRequest(req, trustedHosts)
+      if (!allowed) {
        res.writeHead(403)
        res.end('forbidden')
        return
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -52,11 +52,11 @@ export class FakeApiClient implements IApiClient {
    () => Promise.resolve(ok({
      events: [],
      hasMore: false,
-      modelTarget: { provider: 'deepseek', model: 'deepseek-chat' },
+      modelTarget: { provider: 'deepseek-official', model: 'deepseek-chat' },
    }))

  onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
-    current: { provider: 'deepseek', model: 'deepseek-chat' },
+    current: { provider: 'deepseek-official', model: 'deepseek-chat' },
    groups: [],
    failures: [],
  }))
@@ -159,6 +159,24 @@ export class FakeApiClient implements IApiClient {
    clear: payload => this.record('goal.clear', payload, Promise.resolve(ok({ cleared: true as const }))),
  }

+  readonly settings: IApiClient['settings'] = {
+    describe: payload => this.record('settings.describe', payload, Promise.resolve(ok({ writable: true, namespaces: [] }))),
+    update: payload => this.record('settings.update', payload, Promise.resolve(ok({ ns: 'fake', schema: {}, value: {}, applies: 'live' as const, secrets: [], revision: 0 }))),
+    replace: payload => this.record('settings.replace', payload, Promise.resolve(ok({ ns: 'fake', schema: {}, value: {}, applies: 'live' as const, secrets: [], revision: 0 }))),
+    mutate: payload => this.record('settings.mutate', payload, Promise.resolve(ok({ ns: 'fake', schema: {}, value: {}, applies: 'live' as const, secrets: [], revision: 0 }))),
+  }
+
+  readonly credentials: IApiClient['credentials'] = {
+    describe: payload => this.record('credentials.describe', payload, Promise.resolve(ok({ credentials: {} }))),
+    set: payload => this.record('credentials.set', payload, Promise.resolve(ok({}))),
+    unset: payload => this.record('credentials.unset', payload, Promise.resolve(ok({}))),
+  }
+
+  readonly llm: IApiClient['llm'] = {
+    providers: payload => this.record('llm.providers', payload, Promise.resolve(ok({ providers: [] }))),
+    models: payload => this.record('llm.models', payload, Promise.resolve(ok({ groups: [], failures: [] }))),
+  }
+
  /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
  suppressStreamOpen = false

--- a/packages/client/connection/tests/fixture.spec.ts
+++ b/packages/client/connection/tests/fixture.spec.ts
@@ -119,6 +119,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 }))
--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -1,8 +1,10 @@
 /** Node half: registers the /api prefix route bridging to the api gateway. */
 import { EventEmitter } from 'node:events'
+import { createServer, request as httpRequest } from 'node:http'
 import { Readable } from 'node:stream'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
+import type { AddressInfo } from 'node:net'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { HttpServerService, WebRoute } from '@deepseek-ai/dsh-host-webserver'
@@ -27,9 +29,9 @@ function fakeAttachments(): AttachmentStore {
 }

 /** Bodyless GET carrying the given headers (enough for the trust fence + bridge). */
-function fakeRequest(headers: Record<string, string>): IncomingMessage {
+function fakeRequest(headers: Record<string, string>, url = `${API_PATH}/session.list`): IncomingMessage {
  const request = Readable.from([]) as unknown as IncomingMessage
-  Object.assign(request, { url: `${API_PATH}/session.list`, method: 'GET', headers })
+  Object.assign(request, { url, method: 'GET', headers })
  return request
 }

@@ -105,6 +107,31 @@ describe('connection node half', () => {
    await dispose()
  })

+  it('pins privileged methods to loopback even for a declared trusted authority', async () => {
+    const { routes, dispose } = await mounted({ trustedHosts: ['harness.example'] })
+    // The privileged set: native dialogs plus the whole settings/credential
+    // configuration plane, reads included. The same declared authority reaches
+    // ordinary reads (carrier-level 404 from the empty proxy proves the fence
+    // passed), but each privileged method stays loopback-only and 403s.
+    for (const method of [
+      'host.pickDirectory', 'host.openPath',
+      'settings.describe', 'settings.update', 'settings.replace',
+      'credentials.describe', 'credentials.set', 'credentials.unset',
+    ]) {
+      const denied = fakeResponse()
+      await routes[0]!.handler(
+        fakeRequest({ host: 'harness.example' }, `${API_PATH}/${method}`),
+        denied.response,
+      )
+      expect(denied.state.status).toBe(403)
+      expect(denied.state.body).toBe('forbidden')
+    }
+    const read = fakeResponse()
+    await routes[0]!.handler(fakeRequest({ host: 'harness.example' }), read.response)
+    expect(read.state.status).not.toBe(403)
+    await dispose()
+  })
+
  it('passes loopback and declared-authority requests through to the bridge', async () => {
    const { routes, dispose } = await mounted({ trustedHosts: ['harness.example:3080', '192.168.1.5'] })
    // Loopback, no browser markers (curl shape): the fence passes; the carrier
@@ -126,3 +153,69 @@ describe('connection node half', () => {
    await dispose()
  })
 })
+
+describe('connection node half over a real HTTP server', () => {
+  /** Serve the registered prefix route from a real server and return its port. */
+  async function serve(routes: WebRoute[]): Promise<{ port: number; close: () => Promise<void> }> {
+    const server = createServer((request, response) => {
+      void routes[0]!.handler(request, response)
+    })
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+    const address = server.address() as AddressInfo
+    return {
+      port: address.port,
+      close: () => new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error === undefined || error === null) resolve()
+          else reject(error)
+        })
+      }),
+    }
+  }
+
+  /** One real request; `host` spoofs the authority the way a LAN client's browser would send it. */
+  function call(port: number, method: string, host: string): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const request = httpRequest(
+        { host: '127.0.0.1', port, path: `${API_PATH}/${method}`, method: 'GET', headers: { host } },
+        (response) => {
+          response.resume()
+          response.on('end', () => { resolve(response.statusCode ?? 0) })
+        },
+      )
+      request.on('error', reject)
+      request.end()
+    })
+  }
+
+  it('answers a declared LAN authority with 403 on every configuration method, over real HTTP', async () => {
+    // The fence's input is a real IncomingMessage parsed by Node from the
+    // wire, not a hand-assembled object: the Host header a LAN browser sends
+    // is exactly what decides loopback-only here, so the boundary is asserted
+    // against the parse the server actually performs.
+    const { routes, dispose } = await mounted({ trustedHosts: ['harness.example'] })
+    const { port, close } = await serve(routes)
+    try {
+      // Reads are as privileged as writes: describe returns the exposed
+      // configuration, and credentials.describe probes arbitrary env-var names.
+      for (const method of [
+        'settings.describe', 'settings.update', 'settings.replace',
+        'credentials.describe', 'credentials.set', 'credentials.unset',
+        'host.pickDirectory', 'host.openPath',
+      ]) {
+        expect([method, await call(port, method, 'harness.example')]).toEqual([method, 403])
+      }
+      // The model catalog stays reachable for the same authority: a LAN
+      // client's model picker needs it, and it carries no key or endpoint
+      // state (404 is the empty proxy's carrier answer — the fence passed).
+      for (const method of ['llm.providers', 'llm.models']) {
+        expect([method, await call(port, method, 'harness.example')]).toEqual([method, 404])
+      }
+      // Loopback reaches everything, configuration included.
+      expect(await call(port, 'settings.describe', `127.0.0.1:${String(port)}`)).toBe(404)
+    } finally {
+      await close()
+      await dispose()
+    }
+  })
+})
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: 6917951e1a2b97dc6cab27a1bb046022c726304f
-README.zh.md: 88019725c08355181c97eed4eb917fd96f7ce4e2
+README.md: 966b0258491712182e3affa3416d9bc7a6aeadaf
+README.zh.md: f7f9979c4882f1a145361b4693ba916f8e6afd52
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -2,7 +2,7 @@

 English | [中文](README.zh.md)

-Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects, the Chat-facing list, scope, and event-window state, and the latest successful host capability description; SessionHistoryService lazily owns independent raw-history ledgers for inspection consumers; WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (`connectWorkspace`). The runtime fans the shared Host stream into the Session, Workspace, and activated history owners without routing inspection state through Session or SessionManager. Client sessions are always Host-born (Session+Agent+cwd in one `session.create`); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Contract: api-contracts v3 §4. Each `Session` holds a generic `ProjectionValueStore` seeded from the history-tail `projections` block and updated by `session/projection` frames under higher-seq-wins; domain keys (including `todos`) are read via `projections.faceOf` / `useProjection`, not via `ConversationSnapshot`.
+Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects, the Chat-facing list, scope, event-window state, and the latest successful host capability description; SessionHistoryService lazily owns independent raw-history ledgers for inspection consumers; WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (`connectWorkspace`). The runtime fans the shared Host stream into the Session, Workspace, and activated history owners without routing inspection state through Session or SessionManager, and bridges registry-invalidation frames to typed ctx events (`commands/changed`, `settings/changed`, `credentials/changed`, `models/changed`) so surface caches refetch without touching the stream. Client sessions are always Host-born (Session+Agent+cwd in one `session.create`); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Contract: api-contracts v3 §4. Each `Session` holds a generic `ProjectionValueStore` seeded from the history-tail `projections` block and updated by `session/projection` frames under higher-seq-wins; domain keys (including `todos`) are read via `projections.faceOf` / `useProjection`, not via `ConversationSnapshot`.

 ## Workspace and Session lists

--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象、Chat 所需的列表、scope 和事件窗口状态，以及最新一次成功的宿主能力描述；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本；WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。契约：api-contracts v3 §4。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。
+客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象、Chat 所需的列表、scope、事件窗口状态，以及最新一次成功的宿主能力描述；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本；WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager，并把注册表失效帧桥接为类型化 ctx 事件（`commands/changed`、`settings/changed`、`credentials/changed`、`models/changed`），使各表面缓存无需触碰流即可重拉。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。契约：api-contracts v3 §4。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。

 ## Workspace 与 Session 列表

--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -122,6 +122,28 @@ declare module 'cordis' {
     * @mode emit
     */
    'commands/changed'(): void
+    /**
+     * One settings namespace's resolved value changed on the host
+     * (host/settings-changed passthrough). Subscribers refetch
+     * `settings.describe`; the frame carries no values.
+     * @mode emit
+     * @param ns - the namespace whose resolved value changed.
+     */
+    'settings/changed'(ns: string): void
+    /**
+     * One credential reference's state changed on the host
+     * (host/credentials-changed passthrough). The ref is an
+     * environment-variable NAME — never a value.
+     * @mode emit
+     * @param ref - the reference whose configured state changed.
+     */
+    'credentials/changed'(ref: string): void
+    /**
+     * The host provider topology changed (host/models-changed passthrough).
+     * Subscribers refetch `llm.providers`/`llm.models`/`session.models`.
+     * @mode emit
+     */
+    'models/changed'(): void
    /**
     * A connection generation was (re-)established. Wire-derived caches must
     * treat their state as stale and repull (commands directory; the queue
@@ -170,8 +192,13 @@ export function apply(ctx: Context): void {
      sessions.handleHostEnvelope(envelope)
      workspaces.handleHostEnvelope(envelope)
      // Typed-event bridge: the session layer ignores registry frames (no
-      // session routing); consumers (command directory caches) subscribe on ctx.
-      if (envelope.payload.type === 'host/commands-changed') ctx.emit('commands/changed')
+      // session routing); consumers (command directory caches, the settings
+      // and model surfaces) subscribe on ctx.
+      const frame = envelope.payload
+      if (frame.type === 'host/commands-changed') ctx.emit('commands/changed')
+      else if (frame.type === 'host/settings-changed') ctx.emit('settings/changed', frame.ns)
+      else if (frame.type === 'host/credentials-changed') ctx.emit('credentials/changed', frame.ref)
+      else if (frame.type === 'host/models-changed') ctx.emit('models/changed')
      try {
        sessionHistory.handleHostEnvelope(envelope)
      } catch (error) {
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -62,7 +62,7 @@ export class FakeApiClient implements IApiClient {
  // Programmable slots (defaults answer OK-empty); reassign per case.
  onList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))
  onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
-  readonly defaultModel: ModelTarget = { provider: 'deepseek', model: 'deepseek-v4-flash' }
+  readonly defaultModel: ModelTarget = { provider: 'deepseek-official', model: 'deepseek-v4-flash' }
  onRename: (payload: unknown) => Promise<RpcResponse<{ title: string; seq: number }>> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 }))
  onFork: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId }))
  onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
@@ -72,7 +72,7 @@ export class FakeApiClient implements IApiClient {
  onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
    current: this.defaultModel,
    groups: [{
-      id: 'deepseek',
+      id: 'deepseek-official',
      name: 'DeepSeek',
      models: [{ id: 'deepseek-v4-flash', name: 'DeepSeek V4 Flash' }],
    }],
@@ -186,6 +186,24 @@ export class FakeApiClient implements IApiClient {
    clear: payload => this.record('goal.clear', payload, Promise.resolve(ok({ cleared: true as const }))),
  }

+  readonly settings: IApiClient['settings'] = {
+    describe: payload => this.record('settings.describe', payload, Promise.resolve(ok({ writable: true, namespaces: [] }))),
+    update: payload => this.record('settings.update', payload, Promise.resolve(ok({ ns: 'fake', schema: {}, value: {}, applies: 'live' as const, secrets: [], revision: 0 }))),
+    replace: payload => this.record('settings.replace', payload, Promise.resolve(ok({ ns: 'fake', schema: {}, value: {}, applies: 'live' as const, secrets: [], revision: 0 }))),
+    mutate: payload => this.record('settings.mutate', payload, Promise.resolve(ok({ ns: 'fake', schema: {}, value: {}, applies: 'live' as const, secrets: [], revision: 0 }))),
+  }
+
+  readonly credentials: IApiClient['credentials'] = {
+    describe: payload => this.record('credentials.describe', payload, Promise.resolve(ok({ credentials: {} }))),
+    set: payload => this.record('credentials.set', payload, Promise.resolve(ok({}))),
+    unset: payload => this.record('credentials.unset', payload, Promise.resolve(ok({}))),
+  }
+
+  readonly llm: IApiClient['llm'] = {
+    providers: payload => this.record('llm.providers', payload, Promise.resolve(ok({ providers: [] }))),
+    models: payload => this.record('llm.models', payload, Promise.resolve(ok({ groups: [], failures: [] }))),
+  }
+
  /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
  suppressStreamOpen = false

--- a/packages/client/runtime/tests/manager.spec.ts
+++ b/packages/client/runtime/tests/manager.spec.ts
@@ -378,7 +378,7 @@ describe('connected generation', () => {
    api.onHistory = () => Promise.resolve(ok({
      events: entries(plainTurn(0, 0, 'a', 'b')) as never[],
      hasMore: false,
-      modelTarget: { provider: 'deepseek', model: 'deepseek-chat' },
+      modelTarget: { provider: 'deepseek-official', model: 'deepseek-chat' },
    }))
    const manager = new SessionManager(api)
    const openedSession = manager.get(S1)
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -78,7 +78,7 @@ describe('open', () => {
    gate.resolve(ok({
      events: entries(page) as never[],
      hasMore: false,
-      modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
    }))
    await opening
    const seqs = session.getSnapshot().nodes.map(n => n.seq)
@@ -255,7 +255,7 @@ describe('paging', () => {
    gate.resolve(ok({
      events: entries(plainTurn(0, 0, 'a', 'b')) as never[],
      hasMore: false,
-      modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
    }))
    await Promise.all([first, second])
    expect(api.callsOf('session.history')).toHaveLength(2) // open + one page, not two
@@ -586,7 +586,7 @@ describe('remaining branches', () => {
    stale.resolve(ok({
      events: entries(plainTurn(0, 0, '旧', '代')) as never[],
      hasMore: false,
-      modelTarget: { provider: 'deepseek', model: 'stale' },
+      modelTarget: { provider: 'deepseek-official', model: 'stale' },
    })) // success, but its generation is gone
    await Promise.all([opening, resynced])
    expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9]) // only the fresh generation's window
@@ -609,7 +609,7 @@ describe('remaining branches', () => {
    secondPull.resolve(ok({
      events: entries([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]) as never[],
      hasMore: false,
-      modelTarget: { provider: 'deepseek', model: 'stale' },
+      modelTarget: { provider: 'deepseek-official', model: 'stale' },
    }))
    await Promise.all([opening, resynced])
    expect(session.getSnapshot().openState).toBe('open')
@@ -627,7 +627,7 @@ describe('remaining branches', () => {
    repairPull.resolve(ok({
      events: entries(plainTurn(0, 0, '旧', '页')) as never[],
      hasMore: false,
-      modelTarget: { provider: 'deepseek', model: 'stale' },
+      modelTarget: { provider: 'deepseek-official', model: 'stale' },
    })) // repair result: stale, dropped
    await resynced
    expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9])
@@ -672,7 +672,7 @@ describe('remaining branches', () => {
        { event: ev.toolResult(7, 1, 'h1', 'done'), view: { for: 'result', view: { card: 'generic', title: '历史果' } } },
      ] as never[],
      hasMore: false,
-      modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
    }))
    await session.open()
    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
--- a/packages/client/runtime/tests/wire-events.spec.ts
+++ b/packages/client/runtime/tests/wire-events.spec.ts
@@ -44,6 +44,22 @@ describe('wire event bridge', () => {
    expect(changed).toBe(1)
  })

+  it('broadcasts the settings/credentials/models invalidations with their frame payloads', async () => {
+    const bench = await mount()
+    const seen: unknown[][] = []
+    bench.ctx.on('settings/changed', ns => seen.push(['settings', ns]))
+    bench.ctx.on('credentials/changed', ref => seen.push(['credentials', ref]))
+    bench.ctx.on('models/changed', () => seen.push(['models']))
+    bench.sinks?.onHostEnvelope?.({ rpcId: 'r3' as never, payload: { type: 'host/settings-changed', ns: 'llm-pi-ai' } })
+    bench.sinks?.onHostEnvelope?.({ rpcId: 'r4' as never, payload: { type: 'host/credentials-changed', ref: 'OPENAI_API_KEY' } })
+    bench.sinks?.onHostEnvelope?.({ rpcId: 'r5' as never, payload: { type: 'host/models-changed' } })
+    expect(seen).toEqual([
+      ['settings', 'llm-pi-ai'],
+      ['credentials', 'OPENAI_API_KEY'],
+      ['models'],
+    ])
+  })
+
  it('broadcasts connection/reset on every established generation (reconnect invalidation)', async () => {
    const bench = await mount()
    let resets = 0
--- a/packages/client/schema-form/README.i18n.yaml
+++ b/packages/client/schema-form/README.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 packages/client/schema-form/README.md
+README.md: 5dcef89cbffc8b03c3f2d874e870fa9767360d3c
+README.zh.md: a82acb7d85005da25858fb17cf42b49f06ae59db
--- a/packages/client/schema-form/README.md
+++ b/packages/client/schema-form/README.md
@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-client-schema-form
+
+English | [中文](README.zh.md)
+
+Schema/draft model layer for settings editors. The wire's `settings.describe` carries each namespace's serialized schemastery schema (`schema.toJSON()` ref envelope); `rehydrateSchema` turns it back into a live validator with `new Schema(json)` — the same schema object that validates a section on the host validates drafts in the browser, so client-side validation never drifts from the seam's. Editors render their own controls (the Models page hand-writes its card around the fields it probes here); this package owns no React and no rendering.
+
+## Contract
+
+The unit of editing is a **draft user section**: a plain object edited immutably (`setPath` materializes intermediates, `deletePath` is the per-field reset — dropping the key falls the resolved value back to the composition base and schema defaults). A field's presence in the draft marks it **overridden** (`hasPath`) — presence semantics, not value comparison, exactly mirroring the settings seam's layering. `nodeAtPath` resolves the schema node addressed by a configurable-provider directory `settingsPath` (object properties by name, dict entries through `inner`), so an editor can probe which fields a provider's profile carries (and their `meta.role`) before deciding what to render; an unresolvable path returns `undefined` so the caller degrades loudly instead of rendering a wrong subtree. `validateDraft(schema, draft)` runs the rehydrated validator and returns its failure message, letting pages reject an invalid draft before writing.
+
+## Model Experience
+
+None, as this package backs browser configuration editors; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Rehydration executes the served envelope** — `rehydrateSchema` reconstructs a live schemastery validator, and schemastery revives serialized callbacks through `new Function`, so the schema envelope is executable content rather than inert data. That is acceptable only because the envelope comes from the same host that serves the page; a browser schema protocol should carry a description the client cannot execute, which is deferred with the settings seam's [wire-boundary work](../../settings/settings/README.md#known-limitations-and-deferred-work).
+- **Validation is draft-level, not per-field** — `validateDraft` reports schemastery's first failure message (which names the `$.path`); per-field error mapping is deferred until a consumer needs it.
+- **No generic renderer** — a schema-driven form component was built and then replaced by the hand-written Models editor ([Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)); if a future page needs to edit arbitrary sections, it starts from these helpers, not from a resurrected generic renderer, unless the note's trade-off changes.
--- a/packages/client/schema-form/README.zh.md
+++ b/packages/client/schema-form/README.zh.md
@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-client-schema-form
+
+[English](README.md) | 中文
+
+面向 settings 编辑器的 schema／草稿模型层。wire 侧的 `settings.describe` 携带每个 namespace 的序列化 schemastery schema（`schema.toJSON()` 的 ref 信封）；`rehydrateSchema` 用 `new Schema(json)` 将其还原（rehydrate）为活的校验器——在宿主上校验分节的那份 schema 对象，就是在浏览器里校验草稿的那份对象，因此客户端校验绝不会偏离 seam 侧的校验。编辑器各自渲染自己的控件（Models 页围绕它在此探测到的字段手写自己的卡片）；该包（package）不含任何 React，也不做任何渲染。
+
+## 契约
+
+编辑的单元是**用户分节草稿**：一个以不可变方式编辑的普通对象（`setPath` 会物化中间对象，`deletePath` 即逐字段重置——去掉该键，解析值便回退到组合 base 与 schema 默认值）。字段只要出现在草稿中就被标记为**已覆盖**（`hasPath`）——判定采用存在性语义而非值比较，与 settings seam 的分层方式严格对应。`nodeAtPath` 解析可配置提供方目录 `settingsPath` 所寻址的 schema 节点（object 属性按名称解析，dict 条目经由 `inner`），编辑器因此可以在决定渲染什么之前，先探测某提供方的 profile 携带哪些字段（及其 `meta.role`）；无法解析的路径返回 `undefined`，调用方因此会大声降级，而不是渲染出错误的子树。`validateDraft(schema, draft)` 运行还原出的校验器并返回其失败消息，页面因此可以在写入前拒绝无效草稿。
+
+## Model Experience
+
+无。该包支撑的是浏览器配置编辑器；这里没有任何内容进入模型请求。
+
+#### KV Cache effect
+
+无；该包既不组装也不发送提供方请求。
+
+## Known Limitations and Deferred Work
+
+- **重建 schema 会执行所收到的信封**——`rehydrateSchema` 会重建一个活的 schemastery 校验器，而 schemastery 通过 `new Function` 复活序列化过的 callback，因此 schema 信封是可执行内容，而非惰性数据。这只有在信封来自提供该页面的同一 host 时才可接受；面向浏览器的 schema 协议应当传递客户端无法执行的描述，此项与 settings seam 的[协议边界工作](../../settings/settings/README.md#known-limitations-and-deferred-work)一并暂缓。
+- **校验是草稿级的，而非逐字段**——`validateDraft` 报告 schemastery 的第一条失败消息（其中会点名 `$.path`）；逐字段的报错映射延后到出现需要它的消费方再做。
+- **没有通用渲染器**——一个 schema 驱动的表单组件曾被构建出来，随后被手写的 Models 编辑器取代（[Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)）；若未来有页面需要编辑任意分节，起点是这些辅助函数，而不是复活后的通用渲染器——除非该 note 的权衡发生变化。
--- a/packages/client/schema-form/package.json
+++ b/packages/client/schema-form/package.json
@@ -0,0 +1,40 @@
+{
+  "name": "@deepseek-ai/dsh-client-schema-form",
+  "description": "Schema/draft model layer for settings editors: rehydrates a serialized schemastery schema, validates drafts, and edits them immutably by path",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
--- a/packages/client/schema-form/src/index.ts
+++ b/packages/client/schema-form/src/index.ts
@@ -0,0 +1,12 @@
+/**
+ * Schema/draft model layer for settings editors: rehydrate the wire's
+ * serialized schemastery envelope, resolve nodes by settings path, validate
+ * drafts, and edit them immutably by path. Editors render their own controls
+ * (the Models page hand-writes its layout) on top of these helpers.
+ * @module @deepseek-ai/dsh-client-schema-form
+ */
+
+export {
+  deletePath, getPath, hasPath, nodeAtPath, rehydrateSchema, setPath, validateDraft,
+} from './model.ts'
+export type { SchemaNode } from './model.ts'
--- a/packages/client/schema-form/src/invariant.ts
+++ b/packages/client/schema-form/src/invariant.ts
@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-schema-form`.
+ * @module @deepseek-ai/dsh-client-schema-form/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-schema-form'
+
+/** Cordis companion plugin name. */
+export const name = 'client-schema-form-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a pure schema/draft helper library — it emits no
+ * cordis events and owns no cross-plugin mutable relation; draft
+ * immutability, schema rehydration, and path-edit round trips are asserted
+ * directly by this package's model specs.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
--- a/packages/client/schema-form/src/model.ts
+++ b/packages/client/schema-form/src/model.ts
@@ -0,0 +1,151 @@
+/**
+ * Schema introspection and draft-editing helpers behind settings editors.
+ * The serialized schemastery envelope (`schema.toJSON()`) rehydrates into a
+ * live validator whose node relations (`dict`/`inner`) editors probe for
+ * field presence and roles; drafts are edited immutably by path.
+ * @module @deepseek-ai/dsh-client-schema-form/model
+ */
+
+import Schema from 'schemastery'
+
+/** Live schemastery node; the renderer reads only its structural relations. */
+export type SchemaNode = Schema
+
+/**
+ * Rehydrate a serialized schema envelope into a live validator/node tree.
+ * @param serialized - `schema.toJSON()` output received over the wire.
+ * @returns the root schema node.
+ */
+export function rehydrateSchema(serialized: unknown): SchemaNode {
+  return new Schema(serialized as Schema)
+}
+
+/**
+ * Validate a draft against a rehydrated schema.
+ * @param schema - rehydrated root node.
+ * @param draft - candidate value.
+ * @returns the validation failure message, or `undefined` when the draft passes.
+ */
+export function validateDraft(schema: SchemaNode, draft: unknown): string | undefined {
+  try {
+    ;(schema as unknown as (value: unknown) => unknown)(draft)
+    return undefined
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+}
+
+/**
+ * Resolve the schema node at a settings path (the configurable-provider
+ * directory's `settingsPath` vocabulary): object properties by name, dict
+ * entries through `inner`. An unresolvable segment returns `undefined` so
+ * the caller falls back instead of rendering a wrong subtree.
+ * @param root - rehydrated section root node.
+ * @param path - key path from the section root.
+ * @returns the node describing that position, or `undefined`.
+ */
+export function nodeAtPath(root: SchemaNode, path: readonly string[]): SchemaNode | undefined {
+  let node: SchemaNode | undefined = root
+  for (const key of path) {
+    if (node === undefined) return undefined
+    if (node.type === 'object') node = (node.dict as Record<string, SchemaNode> | undefined)?.[key]
+    else if (node.type === 'dict' || node.type === 'array') node = node.inner as SchemaNode | undefined
+    else return undefined
+  }
+  return node
+}
+
+/**
+ * Read a nested value by path.
+ * @param value - root value (draft or fallback layer).
+ * @param path - key path from the root; array indexes as strings.
+ * @returns the value at the path, or `undefined` along a missing branch.
+ */
+export function getPath(value: unknown, path: readonly string[]): unknown {
+  let current: unknown = value
+  for (const key of path) {
+    if (Array.isArray(current)) {
+      current = current[Number(key)]
+      continue
+    }
+    if (typeof current !== 'object' || current === null) return undefined
+    current = (current as Record<string, unknown>)[key]
+  }
+  return current
+}
+
+/**
+ * Whether a draft explicitly carries the path (its presence marks a user
+ * override, independent of the value stored there).
+ * @param value - root value (draft or fallback layer).
+ * @param path - key path from the root; array indexes as strings.
+ * @returns whether the path's final key exists on its parent.
+ */
+export function hasPath(value: unknown, path: readonly string[]): boolean {
+  if (path.length === 0) return value !== undefined
+  const parent = getPath(value, path.slice(0, -1))
+  const key = path[path.length - 1] as string
+  if (Array.isArray(parent)) return Number(key) < parent.length
+  if (typeof parent !== 'object' || parent === null) return false
+  return key in parent
+}
+
+function cloneContainer(container: unknown, key: string): Record<string, unknown> | unknown[] {
+  if (Array.isArray(container)) return [...container as unknown[]]
+  if (typeof container === 'object' && container !== null) return { ...container as Record<string, unknown> }
+  // A missing intermediate materializes as the container the next key needs.
+  return /^\d+$/.test(key) ? [] : {}
+}
+
+/** Clone the container spine down to the leaf's parent, materializing missing intermediates. */
+function cloneSpine(root: Record<string, unknown>, path: readonly string[]): {
+  result: Record<string, unknown>
+  parent: Record<string, unknown> | unknown[]
+  leaf: string
+} {
+  const result = { ...root }
+  let target: Record<string, unknown> | unknown[] = result
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i] as string
+    const child = cloneContainer(
+      Array.isArray(target) ? target[Number(key)] : (target)[key],
+      path[i + 1] as string,
+    )
+    if (Array.isArray(target)) target[Number(key)] = child
+    else (target)[key] = child
+    target = child
+  }
+  return { result, parent: target, leaf: path[path.length - 1] as string }
+}
+
+/**
+ * Immutably set a nested value, materializing missing intermediate containers.
+ * @param root - draft root (never mutated).
+ * @param path - non-empty key path.
+ * @param value - value to store at the path.
+ * @returns the new draft root.
+ */
+export function setPath(root: Record<string, unknown>, path: readonly string[], value: unknown): Record<string, unknown> {
+  if (path.length === 0) throw new Error('schema-form: setPath needs a non-empty path')
+  const { result, parent, leaf } = cloneSpine(root, path)
+  if (Array.isArray(parent)) parent[Number(leaf)] = value
+  else parent[leaf] = value
+  return result
+}
+
+/**
+ * Immutably remove a nested key (the per-field reset: the resolved value
+ * falls back to the composition base and schema defaults). Removing along a
+ * missing branch returns the root unchanged.
+ * @param root - draft root (never mutated).
+ * @param path - non-empty key path.
+ * @returns the new draft root.
+ */
+export function deletePath(root: Record<string, unknown>, path: readonly string[]): Record<string, unknown> {
+  if (path.length === 0) throw new Error('schema-form: deletePath needs a non-empty path')
+  if (!hasPath(root, path)) return root
+  const { result, parent, leaf } = cloneSpine(root, path)
+  if (Array.isArray(parent)) parent.splice(Number(leaf), 1)
+  else Reflect.deleteProperty(parent, leaf)
+  return result
+}
--- a/packages/client/schema-form/tests/invariant.spec.ts
+++ b/packages/client/schema-form/tests/invariant.spec.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as SchemaFormInvariant from '@deepseek-ai/dsh-client-schema-form/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(SchemaFormInvariant).await()).resolves.toBeDefined()
+  })
+})
--- a/packages/client/schema-form/tests/model.spec.ts
+++ b/packages/client/schema-form/tests/model.spec.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import Schema from 'schemastery'
+import {
+  deletePath, getPath, hasPath, nodeAtPath, rehydrateSchema, setPath, validateDraft,
+} from '../src/model.ts'
+
+const Wire = (schema: Schema): unknown => JSON.parse(JSON.stringify(schema.toJSON()))
+
+describe('rehydration and validation', () => {
+  it('rehydrates a serialized envelope into a working validator', () => {
+    const root = rehydrateSchema(Wire(Schema.object({ name: Schema.string().required() })))
+    expect(validateDraft(root, { name: 'ok' })).toBeUndefined()
+    expect(validateDraft(root, { name: 42 })).toContain('name')
+  })
+
+  it('stringifies non-Error validation throws', () => {
+    const hostile = (() => {
+      throw 'plain-string failure'
+    }) as unknown as Parameters<typeof validateDraft>[0]
+    expect(validateDraft(hostile, {})).toBe('plain-string failure')
+  })
+})
+
+describe('path helpers', () => {
+  const root = { providers: { openai: { baseURL: 'https://x' } }, models: [{ id: 'a' }] }
+
+  it('reads nested object and array paths', () => {
+    expect(getPath(root, [])).toBe(root)
+    expect(getPath(root, ['providers', 'openai', 'baseURL'])).toBe('https://x')
+    expect(getPath(root, ['models', '0', 'id'])).toBe('a')
+    expect(getPath(root, ['providers', 'missing', 'x'])).toBeUndefined()
+    expect(getPath(root, ['providers', 'openai', 'baseURL', 'deep'])).toBeUndefined()
+  })
+
+  it('reports draft presence by key existence, not value truthiness', () => {
+    expect(hasPath({ flag: false }, ['flag'])).toBe(true)
+    expect(hasPath({ nested: { key: undefined } }, ['nested', 'key'])).toBe(true)
+    expect(hasPath({}, ['missing'])).toBe(false)
+    expect(hasPath({ leaf: 'x' }, ['leaf', 'deeper'])).toBe(false)
+    expect(hasPath({ models: ['a'] }, ['models', '0'])).toBe(true)
+    expect(hasPath({ models: ['a'] }, ['models', '1'])).toBe(false)
+    expect(hasPath({ root: true }, [])).toBe(true)
+    expect(hasPath(undefined, [])).toBe(false)
+  })
+
+  it('sets nested paths immutably, materializing containers by key shape', () => {
+    const draft = {}
+    const next = setPath(draft, ['providers', 'openai', 'baseURL'], 'https://y')
+    expect(draft).toEqual({})
+    expect(next).toEqual({ providers: { openai: { baseURL: 'https://y' } } })
+    const withArray = setPath(next, ['models', '0'], { id: 'a' })
+    expect(withArray).toEqual({ providers: { openai: { baseURL: 'https://y' } }, models: [{ id: 'a' }] })
+    const replaced = setPath(withArray, ['models', '0', 'id'], 'b')
+    expect(replaced.models).toEqual([{ id: 'b' }])
+    expect((withArray as { models: unknown[] }).models).toEqual([{ id: 'a' }])
+    expect(() => setPath({}, [], 'x')).toThrow(/non-empty path/)
+  })
+
+  it('deletes nested paths immutably and splices array indexes', () => {
+    const draft = { providers: { openai: { baseURL: 'https://x', apiKey: 'k' } }, models: ['a', 'b'] }
+    const withoutKey = deletePath(draft, ['providers', 'openai', 'apiKey'])
+    expect(withoutKey).toEqual({ providers: { openai: { baseURL: 'https://x' } }, models: ['a', 'b'] })
+    expect(draft.providers.openai.apiKey).toBe('k')
+    const withoutModel = deletePath(withoutKey, ['models', '0'])
+    expect(withoutModel.models).toEqual(['b'])
+    expect(deletePath(draft, ['providers', 'missing', 'x'])).toBe(draft)
+    expect(() => deletePath({}, [])).toThrow(/non-empty path/)
+  })
+
+  it('deletes keys through array intermediates immutably', () => {
+    const draft = { models: [{ id: 'a', contextWindow: 1 }] }
+    const next = deletePath(draft, ['models', '0', 'contextWindow'])
+    expect(next).toEqual({ models: [{ id: 'a' }] })
+    expect(draft.models[0]).toEqual({ id: 'a', contextWindow: 1 })
+  })
+})
+
+describe('nodeAtPath', () => {
+  const Root = Schema.object({
+    providers: Schema.dict(Schema.object({ baseURL: Schema.string() })),
+    models: Schema.array(Schema.object({ id: Schema.string() })),
+    leaf: Schema.string(),
+  })
+
+  it('resolves object, dict, and array positions', () => {
+    const root = rehydrateSchema(Wire(Root))
+    expect(nodeAtPath(root, [])).toBe(root)
+    expect(nodeAtPath(root, ['providers', 'openai'])?.type).toBe('object')
+    expect(nodeAtPath(root, ['providers', 'openai', 'baseURL'])?.type).toBe('string')
+    expect(nodeAtPath(root, ['models', '0', 'id'])?.type).toBe('string')
+    expect(nodeAtPath(root, ['missing'])).toBeUndefined()
+    expect(nodeAtPath(root, ['missing', 'deeper'])).toBeUndefined()
+    expect(nodeAtPath(root, ['leaf', 'below'])).toBeUndefined()
+  })
+
+  it('tolerates structural nodes missing their relation maps', () => {
+    expect(nodeAtPath({ type: 'object' } as never, ['x'])).toBeUndefined()
+    expect(nodeAtPath({ type: 'dict' } as never, ['x'])).toBeUndefined()
+  })
+})
--- a/packages/client/schema-form/tsconfig.json
+++ b/packages/client/schema-form/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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-conversation/README.md
-README.md: 3447c3389aaaff37b1f9bf6cbe55f03f7b746a86
-README.zh.md: de097d44e030fc0e1afb46d9d770b0de855e3cf7
+README.md: 9d93f53dc7637b1c3694d780986f8014756b32b9
+README.zh.md: 605dd57c8831d575453280e42df8b515e77d88d3
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -18,7 +18,7 @@ A tool call declaring the `terminal` render intent renders its command output in

 Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.toolviews`/outlet) is retired. The chat entry declares the keyed `'conversation.chat.toolview'` hole (session scope; the key space is runtime-open); its render site dispatches per row via `entryKey: toolName` with `GenericToolCard` as the call-site `fallback`. The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openFile`) and `ToolRowProps` pre-composes it with the session standard kit. A registrant is a plain plugin: `ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)` with `inject: ['slots', 'conversation']` as the load-order seam (apply mounts ConversationService after the chat registration, so the service being present guarantees the slot is declared); session differentiation happens inside the component (`useSessions` reading `parentId` — the bash sample is the third-party-posture exemplar). Trajectory/waterfall toolview slots share this shape and land with their own render sites (RendersCheck rejects a declaration nobody renders).

-The todo surfaces are two registrations over that shape, both plain registrant plugins with `inject: ['slots', 'conversation']`. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> 已完成 · <active item>` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: 10` — between Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus `"<done>/<total> tasks · <n> in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
+The todo surfaces are two registrations over that shape, both plain registrant plugins with `inject: ['slots', 'conversation']`. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> 已完成 · <active item>` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: -1` — above the queue rows — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus `"<done>/<total> tasks · <n> in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.

 `QueueDock` is the terminal input-dock entry at `order: 20`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `"<n> 条排队消息"` header whose button expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Each visible row remains a single-line preview with its exact-occurrence edit and delete actions.

@@ -42,7 +42,7 @@ None; this package neither assembles nor sends a provider request.

 - **Stats-line durations cover the in-window flow only** — LLM and tool wall times fold the snapshot's assistant `timing` and tool call/result pairs, so nodes outside the loaded event window (older history) are not counted.
 - **Details panel is the minimal form and currently has no entry point** — selected call args/result raw display; the Input/Output/Metadata switch, Prev/Next stepping, and See-in-trajectory deep link are deferred. Tool rows stopped being details-panel click targets and nothing replaced that gesture, so `ChatViewInjected.openDetails` is implemented but uncalled and the panel (including its terminal card) is unreachable in the assembled application; its rendering stays covered by mounting it with a selection directly.
- **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / branch / clock) ships under text output only; branch forks through the turn containing that message, increments the inherited title on the client, and then opens the child, while a fork or rename failure leaves the source selected.
+- **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / branch / clock) ships under the last content-text assistant of each turn only; mid-turn narration and Think-only nodes stay chrome-free. Branch forks through the turn containing that message, increments the inherited title on the client, and then opens the child, while a fork or rename failure leaves the source selected.
 - **The sparkle icon for the others tool row is a hand-drawn approximation** — the design glyph's vector geometry is not exportable locally; promotion into ui-primitives waits on an exact export.
 - **The approval panel's "Always allow this type" is deferred** — durable grants need a grant-storage design; only allow-once/reject answer today.
 - **TodoPanel truncates long item text to one ellipsized line** — the figma strip has no wrap or expand affordance; full text is not readable inline.
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -18,7 +18,7 @@

 审批经由本包声明的链接管编辑器：`ApprovalPanel` 注册为按选择器路由的 `'conversation.composer'` 配置项（ui-question 模式），在审批等待未决期间取代 InputBar 占据编辑器（琥珀色条、理由标题、来自运行中调用参数的配对命令行、一次性的拒绝／允许）。`contract/slots.ts` 中的 `PendingApproval` 领域面在运行时 `PendingWait` 载体之上拥有 wire 编码——带审计关联的 `ApprovalResponsePayload` 值；广播的 `approval/resolved` 帧使等待落定并恢复编辑器。侧边栏通过 manager 跟踪的 `waitingApproval` 列表位（未实例化会话同样点亮）镜像该阻塞状态，其优先级高于运行中圆环，直至问题解决。未决等待完全离开消息流：问题（ui-question）与审批（ApprovalPanel）都经编辑器接管作答，不再保留只读占位卡。编辑器底行的 Access 席位挂载 `PermissionSelect`，由 host 计算的 `permissions` 投影经标准工具包 `useProjection` 供数（key 缺席即隐藏 chip）；chip 打开 Menu 原语下拉，kebab-case 预设名渲染为 Title Case 标签（与 `/permission` popup 的显示变换孪生），选中会经由输入栏注入的 `command` 回调提交 `/permission <preset>` 命令行。

-todo 两个面就是在该形状上的两个注册项，都是普通注册方插件，`inject: ['slots', 'conversation']`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。`TodoDock` 以 `order: 10` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 和 Queue 之间），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加 `"<已完成>/<总数> tasks · <n> in progress"`（状态图标为 figma 的勾选／进行中／虚线未开始一组）。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。
+todo 两个面就是在该形状上的两个注册项，都是普通注册方插件，`inject: ['slots', 'conversation']`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。`TodoDock` 以 `order: -1` 占用 `'conversation.input.dock'` 列表 slot（位于队列行之上），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加 `"<已完成>/<总数> tasks · <n> in progress"`（状态图标为 figma 的勾选／进行中／虚线未开始一组）。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。

 `QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `"<n> 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。每条可见行仍是单行预览，并提供针对精确单次入队项的编辑和删除操作。

@@ -42,7 +42,7 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插

 - **统计行的耗时只覆盖窗口内消息流**：LLM（大语言模型）与工具墙钟时间由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。
 - **详情面板是最小形态，且当前没有入口**：以原始形式显示已选择调用的参数／结果；Input/Output/Metadata 切换、Prev/Next 步进与 See-in-trajectory 深链接暂缓实现。工具行已不再是详情面板的点击目标，且没有任何手势接替它，因此 `ChatViewInjected.openDetails` 虽已实现却无人调用，该面板（含其终端卡片）在组装后的应用中不可达；其渲染仍由直接以选中态挂载它来覆盖。
- **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／分支／时钟）只挂在 text 输出下；分支会 fork 到包含该消息的轮次末尾，在 client 端递增继承标题后打开子会话，而 fork 或改名失败时源会话保持选中。
+- **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／分支／时钟）只挂在每个轮次中最后一条带 text 内容的 assistant 下；轮次中间的叙述与纯 Think 节点不带 chrome。分支会 fork 到包含该消息的轮次末尾，在 client 端递增继承标题后打开子会话，而 fork 或改名失败时源会话保持选中。
 - **others 工具行的闪光图标是手绘近似版本**：无法在本地导出设计字形的矢量几何；等到存在精确导出后再将其提升到 ui-primitives。
 - **审批面板的「始终允许此类」暂缓**：持久授权需要授权存储设计；今天只能回答允许一次／拒绝。
 - **TodoPanel 将过长条目截成单行省略号**：figma 条没有换行或展开入口，完整文本无法在行内读完。
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -4,8 +4,9 @@
 // view groups them into tool rows through its keyed toolview slot (figma
 // step-summary flow). Shared by finalized nodes and the streaming partial;
 // the turn-level loading dots live in the chat view's tail, not here.
-// Finalized content (text) nodes append IconActions once streaming ends;
-// Think / tool-head-only nodes stay chrome-free.
+// Finalized turn-tail content (text) nodes append IconActions once streaming
+// ends (`time` is omitted for mid-turn narration); Think / tool-head-only
+// nodes stay chrome-free.

 import { memo } from 'react'
 import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
@@ -23,7 +24,8 @@ export interface AssistantMarkdownProps {
  /** Frozen partial of an aborted turn: rendered with a 已停止 marker. */
  interrupted?: boolean | undefined
  loadImage?: ImageLoader
-  /** Unix epoch ms for the finalized IconActions clock; omitted while streaming. */
+  /** Unix epoch ms for the IconActions clock; omitted while streaming or when
+   *  the parent withholds chrome (mid-turn content assistants). */
  time?: number | undefined
  /** Event sequence used as the fork boundary; omitted while streaming. */
  seq?: number | undefined
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -30,7 +30,7 @@ import type {
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
-import { deriveChatFlow, type ChatFlowItem } from './chat-flow.ts'
+import { assistantActionsSeqs, deriveChatFlow, type ChatFlowItem } from './chat-flow.ts'
 import { AssistantMarkdown } from './AssistantMarkdown.tsx'
 import { GenericCommandCard } from './GenericCommandCard.tsx'
 import { GenericToolCard } from './GenericToolCard.tsx'
@@ -248,6 +248,9 @@ export function ChatView({
  const selectedCallId = useStore(s => s.selection?.callId)

  const items = useMemo(() => deriveChatFlow(nodes), [nodes])
+  // Only the last content assistant of each turn owns IconActions; mid-turn
+  // text (before tools) omits `time` so AssistantMarkdown stays chrome-free.
+  const actionSeqs = useMemo(() => assistantActionsSeqs(nodes), [nodes])

  const listRef = useRef<HTMLDivElement | null>(null)
  const atBottomRef = useRef(true)
@@ -381,7 +384,7 @@ export function ChatView({
          streaming={false}
          interrupted={node.interrupted}
          loadImage={loadImage}
-          time={node.time}
+          time={actionSeqs.has(node.seq) ? node.time : undefined}
          seq={node.seq}
          onFork={forkAt}
        />
--- a/packages/client/ui-conversation/src/client/chat/chat-flow.ts
+++ b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
@@ -3,15 +3,24 @@
 * results group into consecutive-run tool groups (figma step-summary flow,
 * VERTICAL gap10) alternating with narration; everything else passes through.
 * Item identity keys are stable across snapshots so the list parent can
- * subscribe to keys only while rows subscribe to content.
+ * subscribe to keys only while rows subscribe to content. IconActions ownership
+ * (last content assistant per turn) is derived here too so ChatView and the
+ * flow share one gate.
 */
-import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  AssistantBlock, ConversationNode, ToolResultNode,
+} from '@deepseek-ai/dsh-client-runtime/client'

 /** One renderable flow item; key is the React key and the parent's identity unit. */
 export type ChatFlowItem =
  | { kind: 'node'; key: string; node: ConversationNode }
  | { kind: 'tool-group'; key: string; results: readonly ToolResultNode[] }

+/** True when the node has model-visible text content worth IconActions chrome. */
+function hasContentText(blocks: readonly AssistantBlock[]): boolean {
+  return blocks.some(block => block.kind === 'text' && block.text.trim() !== '')
+}
+
 /** An assistant node that renders nothing: only tool-call heads (rows render
 *  via the grouping pass) and blank text/reasoning. Skipped by the flow so it
 *  neither costs column gaps nor splits a tool-row run. Interrupted nodes
@@ -22,6 +31,21 @@ function rendersNothing(node: ConversationNode): boolean {
      || ((b.kind === 'text' || b.kind === 'reasoning') && b.text.trim() === ''))
 }

+/**
+ * Seq set of assistants that own IconActions: the last content-text assistant
+ * in each turn. Mid-turn narration (text before tools) stays chrome-free.
+ * @param nodes - snapshot nodes (surface order).
+ * @returns Seq values ChatView may pass as `time` into AssistantMarkdown.
+ */
+export function assistantActionsSeqs(nodes: readonly ConversationNode[]): ReadonlySet<number> {
+  const lastByTurn = new Map<number, number>()
+  for (const node of nodes) {
+    if (node.kind !== 'assistant' || !hasContentText(node.blocks)) continue
+    lastByTurn.set(node.turn, node.seq)
+  }
+  return new Set(lastByTurn.values())
+}
+
 /**
 * Group finalized nodes into the step-summary flow.
 * @param nodes - snapshot nodes (surface order).
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -16,7 +16,7 @@ import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
 import type { ChatViewSlotProps, SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { createChatStore } from '../src/client/stores.ts'
 import { ChatView } from '../src/client/chat/ChatView.tsx'
-import { deriveChatFlow, flowKeys } from '../src/client/chat/chat-flow.ts'
+import { assistantActionsSeqs, deriveChatFlow, flowKeys } from '../src/client/chat/chat-flow.ts'

 afterEach(cleanup)
 // Keyless create() persists under the bare declared key; clear between cases
@@ -61,8 +61,8 @@ const user = (seq: number, text: string): UserMessageNode => ({
  content: [{ type: 'text', text }] as never,
  source: null,
 })
-const assistant = (seq: number, text: string): AssistantMessageNode => ({
-  kind: 'assistant', seq, time: seq * 1_000, turn: 1, step: 1, blocks: [{ kind: 'text', text }],
+const assistant = (seq: number, text: string, turn = 1): AssistantMessageNode => ({
+  kind: 'assistant', seq, time: seq * 1_000, turn, step: 1, blocks: [{ kind: 'text', text }],
 })
 const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode => ({
  kind: 'tool-result', seq, time: seq * 1_000, callId,
@@ -163,6 +163,23 @@ describe('chat-flow derivation', () => {
    expect(flowKeys(deriveChatFlow([toolResult(3, 'a'), { ...headsOnly, interrupted: true }, toolResult(5, 'b')]))).toBe('g3|n4|g5')
    expect(flowKeys(deriveChatFlow([toolResult(3, 'a'), assistant(4, 'found'), toolResult(5, 'b')]))).toBe('g3|n4|g5')
  })
+
+  it('assistantActionsSeqs keeps only the last content assistant per turn', () => {
+    const thinkOnly: AssistantMessageNode = {
+      kind: 'assistant', seq: 3, time: 3_000, turn: 1, step: 2,
+      blocks: [{ kind: 'reasoning', text: 'planning' }],
+    }
+    const seqs = assistantActionsSeqs([
+      user(1, 'hi'),
+      assistant(2, 'looking', 1),
+      thinkOnly,
+      toolResult(4, 'a'),
+      assistant(5, 'done', 1),
+      user(6, 'again'),
+      assistant(7, 'second turn', 2),
+    ])
+    expect([...seqs].sort((a, b) => a - b)).toEqual([5, 7])
+  })
 })

 describe('ChatView', () => {
@@ -203,6 +220,23 @@ describe('ChatView', () => {
    expect(view.getByText('run a')).toBeTruthy()
  })

+  it('shows assistant IconActions only on the last content message of each turn', () => {
+    const h = makeHarness({
+      nodes: [
+        user(1, 'hi'),
+        assistant(2, 'mid-turn text'),
+        toolResult(3, 'a'),
+        assistant(4, 'final answer'),
+        user(5, 'next'),
+        assistant(6, 'second turn', 2),
+      ],
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    // 2 user + 2 turn-tail assistants; mid-turn text at seq 2 stays chrome-free.
+    expect(view.getAllByRole('button', { name: '复制' })).toHaveLength(4)
+    expect(view.getAllByRole('button', { name: '在新对话中分支' })).toHaveLength(4)
+  })
+
  it('forks from both user and finalized assistant message actions at their event seq', () => {
    const h = makeHarness({ nodes: [user(1, 'question'), assistant(2, 'answer')] })
    const view = render(<h.ChatView {...h.props} />)
--- a/packages/client/ui-model/src/client/service.ts
+++ b/packages/client/ui-model/src/client/service.ts
@@ -44,6 +44,14 @@ export class ModelService extends Service {
    ctx.on('connection/reset', () => {
      for (const directory of this.live.directories.values()) directory.resetConnected()
    })
+    // Provider topology changed on the host (a settings-born route appeared
+    // or dropped): refresh every open directory in the background so pickers
+    // show the new catalog without a reopen. Failures stay on each store.
+    ctx.on('models/changed', () => {
+      for (const directory of this.live.directories.values()) {
+        directory.load().catch(() => undefined)
+      }
+    })
  }

  /**
--- a/packages/client/ui-model/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-model/tests/browser-plugin.spec.ts
@@ -21,7 +21,7 @@ import { apply, inject } from '../src/client/index.ts'
 const sid = (k: string): SessionId => k as SessionId

 const GROUPS = [{
-  id: 'deepseek',
+  id: 'deepseek-official',
  name: 'DeepSeek',
  models: [
    {
@@ -54,7 +54,7 @@ const GROUPS = [{
 /** Boot the plugin over fake faces + a stateful fake host (current moves on selectModel). */
 async function bench() {
  const ctx = new Context()
-  let current: ModelTarget = { provider: 'deepseek', model: 'deepseek-v4-flash' }
+  let current: ModelTarget = { provider: 'deepseek-official', model: 'deepseek-v4-flash' }
  const calls = { models: 0, select: 0 }
  ctx.provide('connection', { api: { sessions: {
    models: () => {
@@ -138,17 +138,17 @@ describe('ui-model dual entry', () => {
    const seatFace = b.seat().inject!(sid('s1'))
    // Switch through the SEAT entry.
    expect(await seatFace.select({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'deepseek-v4-pro',
      reasoningEffort: 'max',
    })).toBe(true)
    expect(b.hostCurrent()).toEqual({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'deepseek-v4-pro',
      reasoningEffort: 'max',
    })
    expect(seatFace.directory.getSnapshot().current).toEqual({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'deepseek-v4-pro',
      reasoningEffort: 'max',
    })
@@ -165,7 +165,7 @@ describe('ui-model dual entry', () => {
    const pro = options.find((o: SelectOption) => o.label === 'DeepSeek-V4-Pro')!
    await b.contribution().ui.onSelect(pro, projection('s1'))
    expect(seatFace.directory.getSnapshot().current).toEqual({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'deepseek-v4-pro',
      reasoningEffort: 'high',
    })
@@ -188,14 +188,14 @@ describe('ui-model dual entry', () => {
    const b = await bench()
    b.mint('s1')
    const face = b.seat().inject!(sid('s1'))
-    await face.select({ provider: 'deepseek', model: 'deepseek-v4-pro' })
-    b.setHostCurrent({ provider: 'deepseek', model: 'deepseek-v4-flash' })
+    await face.select({ provider: 'deepseek-official', model: 'deepseek-v4-pro' })
+    b.setHostCurrent({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })

    b.ctx.emit('connection/reset')
    expect(face.directory.getSnapshot()).toMatchObject({ current: null, status: 'loading' })
    await Promise.resolve()
    expect(face.directory.getSnapshot()).toMatchObject({
-      current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+      current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
      status: 'ready',
    })
  })
--- a/packages/client/ui-model/tests/model-select.spec.tsx
+++ b/packages/client/ui-model/tests/model-select.spec.tsx
@@ -31,9 +31,9 @@ const reasoning = {

 function state(overrides: Partial<ModelDirectoryState> = {}): ModelDirectoryState {
  return {
-    current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
    groups: [{
-      id: 'deepseek',
+      id: 'deepseek-official',
      name: 'DeepSeek',
      models: [{ id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash', reasoning }],
    }],
@@ -72,7 +72,7 @@ describe('ModelSelect reasoning effort', () => {
    fireEvent.click(screen.getByRole('menuitemradio', { name: /Max/ }))
    await waitFor(() => {
      expect(select).toHaveBeenCalledWith({
-        provider: 'deepseek',
+        provider: 'deepseek-official',
        model: 'deepseek-v4-flash',
        reasoningEffort: 'max',
      })
--- 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: 13f51d5338affd65d0705cec6a3b4ef78a534f0f
-README.zh.md: 90f4eb5959e105178844c7bd5b07596aff81e706
+README.md: adfbc084e1b0e227d50032cb6c924401b81c6a79
+README.zh.md: 4ee7d4efa729fdccee392ab8e55078b5a4a239ef
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -2,11 +2,17 @@

 English | [中文](README.zh.md)

-Models settings section plugin: registers the `models` nav entry into `settings.section` with an intentionally empty content column — model management lands in a later phase.
+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. 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.

 ## Model Experience

-None, as the section renders an empty browser UI column; nothing here reaches a model request.
+None, as the section renders a browser configuration UI; nothing here reaches a model request.

 #### KV Cache effect

@@ -14,4 +20,7 @@ None; this package neither assembles nor sends a provider request.

 ## Known Limitations and Deferred Work

- **Content column is empty by design** — provider list, editing form, and activation flow are deferred until the model-management service exists.
+- **Only the API key and the curated fold fields are editable on the card** — the hand-written editor traded schema-generic field coverage for the mockup layout ([Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)); advanced fields (`models`, retry policy, timeouts…) are edited in `settings.yaml`, which the fold points at. A profile schema without the conventional fields renders the hint alone, and the two curated layouts key on the `llm-deepseek`/`llm-pi-ai` namespaces by name.
+- **Deleting a row leaves its stored key in `.env`** — removal unsets the settings profile but deliberately does not unset the derived credential; re-adding the provider finds the key already configured. An explicit key-removal control is deferred.
+- **No per-provider model listing on the page** — the picker surfaces models; this page shows route state only. A models preview per row is deferred until a consumer needs it.
+- **Undeclared live routes render nowhere** — a route registered without a configurable-provider declaration has no settings address; it stays visible in pickers but not on this page's rows.
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -2,11 +2,17 @@

 [English](README.md) | 中文

-模型设置分区插件：注册 `models` 导航项，使其进入 `settings.section`；内容栏有意留空，模型管理将在后续阶段实现。
+模型设置插件：提供方配置页和 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` 的就绪状态。它通过 `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 新生的路由都无需轮询即可收敛。

 ## 模型体验

-无。该分区渲染空白的浏览器 UI 内容栏；这里没有任何内容进入模型请求。
+无。该分区渲染浏览器配置 UI；这里没有任何内容进入模型请求。

 #### KV Cache 影响

@@ -14,4 +20,7 @@

 ## 已知限制与暂缓事项

- **内容栏按设计留空**：提供方列表、编辑表单和激活流程均暂缓，待模型管理服务就绪后实现。
+- **卡片上可编辑的只有 API 密钥与精选折叠区字段**：手写编辑器用 schema 通用的字段覆盖面换来了设计稿上的布局（[Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)）；进阶字段（`models`、重试策略、超时……）在 `settings.yaml` 中编辑，折叠区会指向它。不带这些约定字段的 profile schema 只渲染该提示，两套精选布局则以 `llm-deepseek`/`llm-pi-ai` 这两个 namespace 的名字为键。
+- **删除一行会把它已存储的密钥留在 `.env` 里**：删除取消设置的是 settings profile，却刻意不清除那条派生凭据；重新添加该提供方时会发现密钥已配置。显式的密钥移除控件暂缓。
+- **页面上没有逐提供方的模型列表**：模型由选择器呈现；本页只展示路由状态。逐行的模型预览暂缓，待有消费方需要时再实现。
+- **未声明的存活路由无处渲染**：未附带可配置提供方声明即注册的路由没有 settings 地址；它在各选择器中仍然可见，但不会出现在本页的行里。
--- 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 routing over one live provider/settings/credential join",
  "version": "0.0.1",
  "private": true,
  "type": "module",
@@ -36,17 +36,25 @@
  },
  "license": "BSD-3-Clause",
  "peerDependencies": {
+    "@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",
    "cordis": "^4.0.0-rc.7",
    "react": "^18.2.0"
  },
  "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
    "@deepseek-ai/dsh-client-locale": "workspace:^",
    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-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:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@types/react": "~18.3.1",
    "cordis": "^4.0.0-rc.7",
--- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css
@@ -0,0 +1,7 @@
+.dialog {
+  width: min(420px, 100%);
+}
+
+.primary {
+  width: 100%;
+}
--- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
@@ -0,0 +1,96 @@
+/**
+ * Official-DeepSeek first-run dialog. Readiness comes from the same
+ * 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 { 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 { 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>
+  /** Feature copy. */
+  t: (key: keyof typeof en) => string
+}
+
+/** Slot owner props plus the feature's injected dependencies. */
+export type DeepSeekOnboardingDialogProps =
+  PropsRuntime<'settings.onboarding'> & DeepSeekOnboardingInjected
+
+/* v8 ignore next 3 -- closed-union defaults only defend future source widening */
+function assertNever(_value: never): never {
+  throw new Error('unexpected DeepSeek onboarding state')
+}
+
+/**
+ * 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, t } = props
+  const state = useSnapshot(snapshot => snapshot)
+  const readiness = deepSeekReadiness(state)
+  const [dismissed, setDismissed] = useState(false)
+
+  useEffect(() => {
+    if (active && !dismissed && state.status === 'idle') void controller.load()
+  }, [active, controller, dismissed, state.status])
+
+  const close = (): void => {
+    setDismissed(true)
+  }
+
+  const openModels = (): void => {
+    close()
+    openSection('models')
+  }
+
+  if (!active || dismissed) return null
+
+  switch (readiness.kind) {
+    case 'loading':
+    case 'adapter-absent':
+    case 'configured':
+    case 'unavailable':
+      return null
+    case 'credential-missing':
+      break
+    /* v8 ignore next -- every current readiness variant is handled above */
+    default:
+      return assertNever(readiness)
+  }
+
+  return (
+    <Modal
+      open
+      onClose={close}
+      title={t('onboardingTitle')}
+      closeLabel={t('onboardingLater')}
+      description={t('onboardingDescription')}
+      className={styles['dialog'] as string}
+      footer={(
+        <Button
+          variant="primary"
+          className={styles['primary']}
+          autoFocus
+          onClick={openModels}
+        >
+          {t('onboardingGoToSettings')}
+        </Button>
+      )}
+    />
+  )
+}
--- a/packages/client/ui-models/src/client/ModelsSection.module.css
+++ b/packages/client/ui-models/src/client/ModelsSection.module.css
@@ -0,0 +1,283 @@
+.section {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  max-width: 720px;
+}
+
+.title {
+  margin: 0;
+  font-size: 18px;
+  font-weight: 600;
+}
+
+.intro {
+  margin: 0;
+  font-size: 13px;
+  color: var(--text-tertiary, #888);
+}
+
+.notice {
+  margin: 0;
+  font-size: 12px;
+  color: var(--text-warning, #a15c00);
+}
+
+.rows {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.rowCard {
+  border: 1px solid var(--border, #e2e2e2);
+  border-radius: 12px;
+  padding: 12px 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  background: var(--surface, #fff);
+}
+
+.rowHead {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.rowName {
+  font-size: 15px;
+  font-weight: 600;
+}
+
+.badges {
+  display: inline-flex;
+  gap: 6px;
+  flex: 1;
+}
+
+.badgeOk {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  color: var(--text-success, #0a7d33);
+  font-size: 12px;
+}
+
+.badgeOk::before {
+  content: '';
+  width: 6px;
+  height: 6px;
+  border-radius: 999px;
+  background: currentcolor;
+}
+
+.badgeMuted {
+  color: var(--text-tertiary, #999);
+  font-size: 12px;
+}
+
+.badgeWarn {
+  color: var(--text-warning, #a15c00);
+  font-size: 12px;
+}
+
+.rowActions {
+  display: inline-flex;
+  gap: 8px;
+}
+
+.primaryButton {
+  border: none;
+  border-radius: 999px;
+  padding: 8px 18px;
+  background: var(--accent-strong, #111);
+  color: var(--text-inverse, #fff);
+  font: inherit;
+  cursor: pointer;
+}
+
+.secondaryButton {
+  border: 1px solid var(--border, #d9d9d9);
+  border-radius: 999px;
+  padding: 6px 14px;
+  background: var(--surface, #fff);
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.dangerButton {
+  border: none;
+  background: none;
+  color: var(--text-danger, #c0392b);
+  font: inherit;
+  cursor: pointer;
+}
+
+.primaryButton:disabled,
+.secondaryButton:disabled,
+.dangerButton:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.editor {
+  border: 1px solid var(--border, #e6e6e6);
+  border-radius: 12px;
+  background: var(--surface-secondary, #f7f7f8);
+  padding: 14px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.editorHeader {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+}
+
+.editorTitle {
+  font-size: 14px;
+  font-weight: 600;
+}
+
+.editorRoute {
+  font-size: 12px;
+  color: var(--text-tertiary, #999);
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.fieldLabel {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--text-secondary, #555);
+}
+
+.linkButton {
+  border: none;
+  background: none;
+  padding: 0;
+  color: var(--text-tertiary, #888);
+  font: inherit;
+  font-size: 12px;
+  text-decoration: underline;
+  cursor: pointer;
+}
+
+.linkButton:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.advancedHint {
+  margin: 0;
+  font-size: 12px;
+  color: var(--text-tertiary, #999);
+}
+
+.editorActions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+}
+
+.addBlock {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.addButton {
+  align-self: flex-start;
+  border: 1px solid var(--border, #d9d9d9);
+  border-radius: 999px;
+  padding: 8px 16px;
+  font: inherit;
+  font-size: 13px;
+  background: var(--surface, #fff);
+  color: inherit;
+  cursor: pointer;
+}
+
+.addButton:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.addCard,
+.setupCard {
+  border: 1px solid var(--border, #e6e6e6);
+  border-radius: 12px;
+  background: var(--surface-secondary, #f7f7f8);
+  padding: 14px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  list-style: none;
+}
+
+.addCard .editor,
+.setupCard .editor {
+  border: none;
+  background: none;
+  padding: 0;
+}
+
+.customized {
+  border-top: 1px solid var(--border, #ececec);
+  padding-top: 10px;
+}
+
+.customizedSummary {
+  cursor: pointer;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--text-secondary, #555);
+  list-style: revert;
+}
+
+.customizedBody {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding-top: 12px;
+}
+
+.input {
+  box-sizing: border-box;
+  padding: 9px 12px;
+  border: 1px solid var(--border, #d9d9d9);
+  border-radius: 10px;
+  font: inherit;
+  font-size: 13px;
+  background: var(--surface, #fff);
+  color: inherit;
+}
+
+.input:focus {
+  outline: none;
+  border-color: var(--accent-strong, #111);
+}
+
+.input::placeholder {
+  color: var(--text-tertiary, #aaa);
+}
+
+.error {
+  margin: 0;
+  font-size: 12px;
+  color: var(--text-danger, #c0392b);
+}
--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-models/src/client/ModelsSection.tsx
@@ -1,13 +1,281 @@
 /**
- * Models settings section: an intentionally empty content column — the nav
- * entry exists so the section slot composition is visible; model management
- * lands in a later phase.
+ * Models settings section: the provider rows joined from the configurable
+ * directory, settings namespaces, and credential states, with one editor
+ * card at a time. A whole-section provider without a configured key (the
+ * unconfigured DeepSeek posture) renders as its open setup card instead of a
+ * row; the add flow is a card carrying the dormant-provider select. Every
+ * mutation writes through the wire; the page re-renders from the pushed
+ * invalidations or the post-apply reload.
 */

-/**
- * Render the (empty) Models section content column.
- * @returns null — no content this phase.
- */
-export function ModelsSection() {
-  return null
+import { useState } from 'react'
+import type { ReactNode } from 'react'
+import type { IApiClient } from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import { messageOf } from './store.ts'
+import type { ModelsSettingsState, ModelsSettingsStore, ProviderRow } from './store.ts'
+import { ProviderEditor } from './ProviderEditor.tsx'
+import type { en } from './locales.ts'
+import styles from './ModelsSection.module.css'
+
+/** Injected dependencies of {@link ModelsSection} (slot `inject`). */
+export interface ModelsSectionInjected {
+  /** The page store (loaded on mount, refreshed on pushed invalidations). */
+  controller: ModelsSettingsStore
+  /** uSES subscription hook bound to the store. */
+  useSnapshot: SnapshotSelectorHook<ModelsSettingsState>
+  /** Wire faces the editor writes through. */
+  api: Pick<IApiClient, 'settings' | 'credentials'>
+  /** Section copy. */
+  t: (key: keyof typeof en) => string
+}
+
+/**
+ * Props delivered by the slot outlet: the inject face spread flat (the
+ * renderer erases the share boundary at the render call).
+ */
+export type ModelsSectionProps = Partial<ModelsSectionInjected>
+
+/** The editor target: an existing row or a dormant directory entry. */
+interface EditorTarget {
+  provider: string
+  displayName: string
+  settingsNs: string
+  settingsPath: readonly string[]
+}
+
+/**
+ * Remove one user-added provider profile by unsetting its path in the stored
+ * user section, then reload. The removal names the profile rather than
+ * rebuilding the section: this page only ever holds the redacted descriptor,
+ * so a rebuilt section would drop every literal secret stored elsewhere in
+ * the namespace along with the profile being removed.
+ * @param api - settings wire face.
+ * @param controller - the page store to refresh.
+ * @param target - the provider's settings address.
+ * @returns the failure message, or undefined once the write and reload landed.
+ */
+export async function removeProviderProfile(
+  api: Pick<IApiClient, 'settings'>,
+  controller: ModelsSettingsStore,
+  target: { settingsNs: string; settingsPath: readonly string[] },
+): Promise<string | undefined> {
+  let response
+  try {
+    response = await api.settings.mutate({
+      ns: target.settingsNs,
+      ops: [{ op: 'unset', path: [...target.settingsPath] }],
+    })
+  } catch (error) {
+    // The transport rejected rather than answering; the caller must be able
+    // to say so instead of the row silently staying put.
+    return messageOf(error)
+  }
+  if (!response.result.ok) return response.result.error.message
+  await controller.load()
+  return undefined
+}
+
+/**
+ * Whether a whole-section provider still needs its first key: nothing marks
+ * the credential configured and no literal `apiKey` is stored, so the page
+ * opens the setup card instead of showing a row.
+ * @param row - the joined provider row.
+ * @returns whether to render the setup card.
+ */
+export function needsSetup(row: ProviderRow): boolean {
+  if (row.entry.settingsPath.length > 0) return false
+  if (row.credential?.configured === true) return false
+  return !row.literalApiKeyConfigured
+}
+
+function targetOf(row: ProviderRow): EditorTarget {
+  return {
+    provider: row.entry.provider,
+    displayName: row.entry.displayName,
+    settingsNs: row.entry.settingsNs,
+    settingsPath: row.entry.settingsPath,
+  }
+}
+
+/**
+ * Render the Models section content column.
+ * @param props - slot-delivered injected dependencies.
+ * @returns the section, or null while the shell has not injected yet.
+ */
+export function ModelsSection(props: ModelsSectionProps): ReactNode {
+  const { controller, useSnapshot, api, t } = props
+  if (controller === undefined || useSnapshot === undefined || api === undefined || t === undefined) return null
+  return <Loaded injected={{ controller, useSnapshot, api, t }} />
+}
+
+function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
+  const { controller, api, t } = injected
+  const state = injected.useSnapshot(snapshot => snapshot)
+  const [editing, setEditing] = useState<EditorTarget | undefined>(undefined)
+  const [adding, setAdding] = useState(false)
+
+  const closeEditor = (changed: boolean): void => {
+    setEditing(undefined)
+    setAdding(false)
+    if (changed) void controller.load()
+  }
+
+  if (state.status === 'idle') void controller.load()
+  if (state.status === 'error') {
+    /* v8 ignore next -- an error status always carries text; the fallback satisfies the nullable type */
+    const errorText = state.error ?? ''
+    return (
+      <div className={styles['section']}>
+        <p className={styles['error']}>{`${t('loadFailed')}: ${errorText}`}</p>
+        <button type="button" className={styles['secondaryButton']} onClick={() => { void controller.load() }}>
+          {t('retry')}
+        </button>
+      </div>
+    )
+  }
+
+  const configured = state.rows.filter(row => row.configured)
+  const addable = state.rows.filter(row => !row.configured && row.entry.settingsNs !== '')
+  const addTarget = adding ? editing : undefined
+  const addNamespace = addTarget === undefined ? undefined : state.namespaces.get(addTarget.settingsNs)
+
+  return (
+    <div className={styles['section']}>
+      <h2 className={styles['title']}>{t('title')}</h2>
+      <p className={styles['intro']}>{t('intro')}</p>
+      {!state.writable && state.status === 'ready' ? <p className={styles['notice']}>{t('readOnly')}</p> : null}
+      <ul className={styles['rows']}>
+        {configured.map((row) => {
+          const target = targetOf(row)
+          const namespace = state.namespaces.get(target.settingsNs)
+          /* v8 ignore next -- the join marks a row configured only when its namespace resolved */
+          if (namespace === undefined) return null
+          if (needsSetup(row)) {
+            // First-run posture: the provider exists but has no key — the
+            // setup card IS its presence on the page.
+            return (
+              <li key={row.entry.provider} className={styles['setupCard']}>
+                <ProviderEditor
+                  provider={target.provider}
+                  displayName={target.displayName}
+                  namespace={namespace}
+                  settingsPath={target.settingsPath}
+                  api={api}
+                  t={t}
+                  readOnly={!state.writable}
+                  onClose={closeEditor}
+                />
+              </li>
+            )
+          }
+          const open = !adding && editing?.provider === row.entry.provider
+          return (
+            <li key={row.entry.provider} className={styles['rowCard']}>
+              <div className={styles['rowHead']}>
+                <span className={styles['rowName']}>{row.entry.displayName}</span>
+                <span className={styles['badges']}>
+                  {row.entry.active
+                    ? <span className={styles['badgeOk']}>{t('active')}</span>
+                    : <span className={styles['badgeMuted']}>{t('dormant')}</span>}
+                </span>
+                <span className={styles['rowActions']}>
+                  <button
+                    type="button"
+                    className={styles['secondaryButton']}
+                    onClick={() => { setAdding(false); setEditing(open ? undefined : target) }}
+                  >
+                    {t('edit')}
+                  </button>
+                  {row.removable
+                    ? (
+                      <button
+                        type="button"
+                        className={styles['dangerButton']}
+                        disabled={!state.writable}
+                        onClick={() => {
+                          void removeProviderProfile(api, controller, target).then((failure) => {
+                            if (failure !== undefined) controller.fail(failure)
+                          })
+                        }}
+                      >
+                        {t('remove')}
+                      </button>
+                    )
+                    : null}
+                </span>
+              </div>
+              {open
+                ? (
+                  <ProviderEditor
+                    provider={target.provider}
+                    displayName={target.displayName}
+                    namespace={namespace}
+                    settingsPath={target.settingsPath}
+                    api={api}
+                    t={t}
+                    readOnly={!state.writable}
+                    onClose={closeEditor}
+                  />
+                )
+                : null}
+            </li>
+          )
+        })}
+      </ul>
+      <div className={styles['addBlock']}>
+        {addTarget !== undefined && addNamespace !== undefined
+          ? (
+            <div className={styles['addCard']}>
+              <div className={styles['field']}>
+                <span className={styles['fieldLabel']}>{t('provider')}</span>
+                <select
+                  className={styles['input']}
+                  value={addTarget.provider}
+                  aria-label={t('provider')}
+                  onChange={(event) => {
+                    const row = addable.find(candidate => candidate.entry.provider === event.target.value)
+                    /* v8 ignore next -- the select only lists addable rows */
+                    if (row === undefined) return
+                    setEditing(targetOf(row))
+                  }}
+                >
+                  {addable.map(row => (
+                    <option key={row.entry.provider} value={row.entry.provider}>{row.entry.displayName}</option>
+                  ))}
+                </select>
+              </div>
+              <ProviderEditor
+                key={addTarget.provider}
+                provider={addTarget.provider}
+                displayName={addTarget.displayName}
+                hideTitle
+                namespace={addNamespace}
+                settingsPath={addTarget.settingsPath}
+                api={api}
+                t={t}
+                readOnly={!state.writable}
+                onClose={closeEditor}
+              />
+            </div>
+          )
+          : (
+            <button
+              type="button"
+              className={styles['addButton']}
+              disabled={addable.length === 0 || !state.writable}
+              onClick={() => {
+                const first = addable[0]
+                /* v8 ignore next -- the button is disabled while nothing is addable */
+                if (first === undefined) return
+                setAdding(true)
+                setEditing(targetOf(first))
+              }}
+            >
+              {`+ ${t('add')}`}
+            </button>
+          )}
+      </div>
+    </div>
+  )
 }
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -0,0 +1,334 @@
+/**
+ * One provider's editor card, hand-written per adapter family: the primary
+ * field is a single write-only **API key** input (the page never asks for an
+ * environment-variable name — a typed key stores 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`);
+ * the collapsed 自定义设置 area carries the per-family extras (`baseURL` for
+ * both families, plus `reasoningEffort` for deepseek / `reasoning` for
+ * pi-ai). Everything else stays owned by `settings.yaml`. Profile edits land as
+ * minimal `settings.mutate` path ops against the stored section — the card
+ * reads the redacted descriptor, so it names only the fields it can see and a
+ * stored literal secret is never collaterally removed.
+ */
+
+import { useEffect, useMemo, useState } from 'react'
+import type { ReactNode } from 'react'
+import type { CredentialView, IApiClient, SettingsNamespaceView, SettingsPathOpView } from '@deepseek-ai/dsh-client-connection/client'
+import {
+  deletePath, getPath, nodeAtPath, rehydrateSchema, setPath, validateDraft,
+} from '@deepseek-ai/dsh-client-schema-form'
+import { deriveKeyRef, messageOf } from './store.ts'
+import type { en } from './locales.ts'
+import styles from './ModelsSection.module.css'
+
+/** Per-adapter-family curated field sets (unknown namespaces get the hint alone). */
+type EditorLayout = 'deepseek' | 'pi-ai' | 'unknown'
+
+/** Reasoning vocabularies per layout; the empty option means "inherit". */
+const EFFORT_CHOICES: Record<'deepseek' | 'pi-ai', readonly string[]> = {
+  deepseek: ['off', 'high', 'max'],
+  'pi-ai': ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'],
+}
+
+/** The draft key the effort select edits, per layout. */
+const EFFORT_FIELD: Record<'deepseek' | 'pi-ai', string> = {
+  deepseek: 'reasoningEffort',
+  'pi-ai': 'reasoning',
+}
+
+/** The public DeepSeek endpoint shown as the deepseek base-URL placeholder. */
+const DEEPSEEK_PUBLIC_BASE_URL = 'https://api.deepseek.com'
+
+/** Props of {@link ProviderEditor}. */
+export interface ProviderEditorProps {
+  /** Provider route id. */
+  provider: string
+  /** Display name for the card title. */
+  displayName: string
+  /** Hide the title row (the add card renders its own provider select). */
+  hideTitle?: boolean
+  /** The owning namespace view (schema, layers, secrets). */
+  namespace: SettingsNamespaceView
+  /** Path from the section root to this provider's profile. */
+  settingsPath: readonly string[]
+  /** Wire faces for writes. */
+  api: Pick<IApiClient, 'settings' | 'credentials'>
+  /** Section copy. */
+  t: (key: keyof typeof en) => string
+  /** Disable writes (read-only settings provider). */
+  readOnly: boolean
+  /** Close the editor; `changed` reports whether an Apply committed. */
+  onClose: (changed: boolean) => void
+}
+
+/** A user-section subtree as a plain draft object (absent → empty). */
+function draftAt(namespace: SettingsNamespaceView, path: readonly string[]): Record<string, unknown> {
+  const subtree = getPath(namespace.user, path)
+  if (typeof subtree !== 'object' || subtree === null || Array.isArray(subtree)) return {}
+  return structuredClone(subtree) as Record<string, unknown>
+}
+
+/**
+ * The minimal path ops carrying `after` over `before`, both as the card sees
+ * them (that is, redacted). Only keys the card observed are named: a stored
+ * `role('secret')` field appears in neither side, so it produces no op and
+ * survives the write — the whole reason edits are path-addressed rather than
+ * a rebuilt section.
+ * @param base - path of the edited subtree inside the user section.
+ * @param before - the subtree as loaded, or undefined when it is new.
+ * @param after - the subtree as edited.
+ * @returns ordered set/unset ops; empty when nothing changed.
+ */
+export function pathOps(
+  base: readonly string[],
+  before: unknown,
+  after: Record<string, unknown>,
+): SettingsPathOpView[] {
+  const previous = typeof before === 'object' && before !== null && !Array.isArray(before)
+    ? before as Record<string, unknown>
+    : {}
+  const ops: SettingsPathOpView[] = []
+  for (const [key, value] of Object.entries(after)) {
+    if (JSON.stringify(previous[key]) === JSON.stringify(value)) continue
+    ops.push({ op: 'set', path: [...base, key], value })
+  }
+  for (const key of Object.keys(previous)) {
+    if (!(key in after)) ops.push({ op: 'unset', path: [...base, key] })
+  }
+  return ops
+}
+
+/** The editor layout the owning namespace selects. */
+function layoutOf(ns: string): EditorLayout {
+  if (ns === 'llm-deepseek') return 'deepseek'
+  if (ns === 'llm-pi-ai') return 'pi-ai'
+  return 'unknown'
+}
+
+/** The credential reference this profile resolves keys through. */
+function refFor(namespace: SettingsNamespaceView, path: readonly string[], provider: string): string {
+  const profile = getPath(namespace.value, path)
+  const named = typeof profile === 'object' && profile !== null
+    ? (profile as { apiKeyEnv?: unknown }).apiKeyEnv
+    : undefined
+  return typeof named === 'string' && named.length > 0 ? named : deriveKeyRef(provider)
+}
+
+/**
+ * Render one provider's editing card.
+ * @param props - the addressed profile plus wire faces and copy.
+ * @returns the editor card.
+ */
+export function ProviderEditor(props: ProviderEditorProps): ReactNode {
+  const { namespace, settingsPath, api, t } = props
+  const [draft, setDraft] = useState<Record<string, unknown>>(() => draftAt(namespace, settingsPath))
+  const [keyDraft, setKeyDraft] = useState('')
+  const [keyState, setKeyState] = useState<CredentialView | undefined>(undefined)
+  const [busy, setBusy] = useState(false)
+  const [failure, setFailure] = useState<string | undefined>(undefined)
+  // The revision this card opened at. A write carrying it is refused if
+  // anything else — another tab, an external edit of settings.yaml — moved the
+  // namespace meanwhile, instead of silently overwriting that change.
+  const [openedAt] = useState(() => namespace.revision)
+  const root = useMemo(() => rehydrateSchema(namespace.schema), [namespace.schema])
+  const node = useMemo(() => nodeAtPath(root, settingsPath), [root, settingsPath])
+  const fallback = getPath(namespace.value, settingsPath)
+  const disabled = props.readOnly || busy
+  const layout = layoutOf(namespace.ns)
+  const keyRef = refFor(namespace, settingsPath, props.provider)
+
+  useEffect(() => {
+    let stale = false
+    setKeyState(undefined)
+    // The key state is a placeholder hint, not a precondition for editing:
+    // neither a business rejection nor a transport failure may reach the
+    // browser as an unhandled rejection, so the card simply renders without
+    // the "already configured" hint.
+    void api.credentials.describe({ refs: [keyRef] }).then(
+      (response) => {
+        if (stale || !response.result.ok) return
+        setKeyState(response.result.value.credentials[keyRef])
+      },
+      () => undefined,
+    )
+    return () => { stale = true }
+  }, [api.credentials, keyRef])
+
+  const stringAt = (source: unknown, key: string): string | undefined => {
+    const value = getPath(source, [key])
+    return typeof value === 'string' && value.length > 0 ? value : undefined
+  }
+  const setField = (key: string, next: string | undefined): void => {
+    setDraft(current => next === undefined ? deletePath(current, [key]) : setPath(current, [key], next))
+  }
+
+  /**
+   * The write for this card, or a failure message. Every edit travels as
+   * path ops against the STORED section: the draft comes from the redacted
+   * descriptor, so a wholesale replace rebuilt from it would delete the
+   * literal secrets the wire never returned. Ops name only the fields this
+   * card can see, so a stored secret is untouched by construction.
+   */
+  const applyOnce = async (): Promise<string | undefined> => {
+    const ns = namespace.ns
+    const original = getPath(namespace.user, settingsPath)
+    // The pi-ai profile must name the reference the key stores under, so a
+    // dormant add (or a legacy profile without one) records the derivation.
+    const next = layout === 'pi-ai' && stringAt(draft, 'apiKeyEnv') === undefined
+      && stringAt(fallback, 'apiKeyEnv') === undefined
+      ? setPath(draft, ['apiKeyEnv'], keyRef)
+      : draft
+    /* v8 ignore next -- apply is only reachable from the rendered card, which required a resolved node */
+    if (node !== undefined && settingsPath.length === 0) {
+      const sectionError = validateDraft(node, next)
+      if (sectionError !== undefined) return sectionError
+    }
+    const ops = pathOps(settingsPath, original, next)
+    if (ops.length > 0) {
+      const response = await api.settings.mutate({ ns, ops, expectedRevision: openedAt })
+      if (!response.result.ok) {
+        return response.result.error.code === 'settings-conflict'
+          ? t('conflict')
+          : response.result.error.message
+      }
+    }
+    if (keyDraft.length > 0) {
+      const stored = await api.credentials.set({ ref: keyRef, value: keyDraft })
+      if (!stored.result.ok) return stored.result.error.message
+    }
+    setKeyDraft('')
+    return undefined
+  }
+
+  const apply = async (): Promise<void> => {
+    setBusy(true)
+    setFailure(undefined)
+    try {
+      const failure = await applyOnce()
+      if (failure !== undefined) {
+        setFailure(failure)
+        return
+      }
+      props.onClose(true)
+    } catch (error) {
+      // A transport failure (disconnect, a request the host refuses) rejects
+      // rather than answering; without this the card would stay busy forever
+      // with no error shown.
+      setFailure(messageOf(error))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  if (node === undefined) {
+    // A directory entry addressing a position its schema cannot resolve is a
+    // host-side inconsistency; showing it beats a blank card.
+    return <p className={styles['error']}>{`${props.provider}: unresolvable settings path`}</p>
+  }
+
+  const keyLocked = keyState?.writable === false
+
+  /**
+   * The curated fields of one known adapter family. Taking the narrowed
+   * family as a parameter is what makes `EFFORT_FIELD` total here: an
+   * unknown namespace never reaches this body.
+   */
+  const curatedFields = (family: 'deepseek' | 'pi-ai'): ReactNode => {
+    const effortField = EFFORT_FIELD[family]
+    return (
+      <>
+        <div className={styles['field']}>
+          <span className={styles['fieldLabel']}>{t('keyInput')}</span>
+          <input
+            className={styles['input']}
+            type="password"
+            autoComplete="off"
+            value={keyDraft}
+            placeholder={keyLocked
+              ? t('keyEnvLocked')
+              : keyState?.configured === true ? t('keyStored') : t('keyPlaceholder')}
+            aria-label={t('keyInput')}
+            disabled={disabled || keyLocked}
+            onChange={(event) => { setKeyDraft(event.target.value) }}
+          />
+        </div>
+        <details className={styles['customized']}>
+          <summary className={styles['customizedSummary']}>{t('customized')}</summary>
+          <div className={styles['customizedBody']}>
+            <div className={styles['field']}>
+              <span className={styles['fieldLabel']}>{t('baseUrl')}</span>
+              <input
+                className={styles['input']}
+                type="text"
+                value={stringAt(draft, 'baseURL') ?? ''}
+                placeholder={family === 'deepseek'
+                  ? DEEPSEEK_PUBLIC_BASE_URL
+                  : stringAt(fallback, 'baseURL') ?? t('baseUrlDefault')}
+                aria-label={t('baseUrl')}
+                disabled={disabled}
+                onChange={(event) => {
+                  setField('baseURL', event.target.value === '' ? undefined : event.target.value)
+                }}
+              />
+            </div>
+            <div className={styles['field']}>
+              <span className={styles['fieldLabel']}>{t('effort')}</span>
+              <select
+                className={styles['input']}
+                value={stringAt(draft, effortField) ?? ''}
+                aria-label={t('effort')}
+                disabled={disabled}
+                onChange={(event) => {
+                  setField(effortField, event.target.value === '' ? undefined : event.target.value)
+                }}
+              >
+                <option value="">{t('effortInherit')}</option>
+                {EFFORT_CHOICES[family].map(choice => (
+                  <option key={choice} value={choice}>{choice}</option>
+                ))}
+              </select>
+            </div>
+          </div>
+        </details>
+      </>
+    )
+  }
+
+  return (
+    <div className={styles['editor']}>
+      {props.hideTitle === true
+        ? null
+        : (
+          <div className={styles['editorHeader']}>
+            <span className={styles['editorTitle']}>{props.displayName}</span>
+            {props.provider !== props.displayName
+              ? <span className={styles['editorRoute']}>{props.provider}</span>
+              : null}
+          </div>
+        )}
+      {layout === 'unknown'
+        ? <p className={styles['advancedHint']}>{`${t('advancedHint')} (${namespace.ns})`}</p>
+        : curatedFields(layout)}
+      {failure !== undefined ? <p className={styles['error']}>{failure}</p> : null}
+      <div className={styles['editorActions']}>
+        <button
+          type="button"
+          className={styles['secondaryButton']}
+          disabled={busy}
+          onClick={() => { props.onClose(false) }}
+        >
+          {t('cancel')}
+        </button>
+        <button
+          type="button"
+          className={styles['primaryButton']}
+          disabled={disabled || layout === 'unknown'}
+          onClick={() => { void apply() }}
+        >
+          {busy ? t('applying') : t('apply')}
+        </button>
+      </div>
+    </div>
+  )
+}
--- a/packages/client/ui-models/src/client/index.ts
+++ b/packages/client/ui-models/src/client/index.ts
@@ -1,51 +1,119 @@
 /**
- * Models settings section plugin, browser half. Registers the `models` nav
- * entry into the shell-declared `settings.section` list slot; the content
- * column is intentionally empty until model management lands. 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 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'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 // Type-only: pulls the shell's SlotMap merge (the 'settings.section' entry).
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 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'
+
+export type { ModelsSectionInjected, ModelsSectionProps } from './ModelsSection.tsx'
+export type { ModelsSettingsState, ProviderRow } from './store.ts'
+
+/**
+ * Refetch the page snapshot only after its first load: an unopened Models
+ * page must not fetch on background invalidations.
+ * @param controller - the page store.
+ */
+export function refreshIfLoaded(controller: ModelsSettingsStore): void {
+  if (controller.store.getSnapshot().status === 'idle') return
+  void controller.load()
+}

 /**
 * Required services (cordis fiber inject). The target slot is declared by
 * ui-settings' apply, whose activation order relative to this one is NOT
 * constrained; registration goes through declaration-aware deferral.
 */
-export const inject = ['slots', 'locale']
+export const inject = ['slots', 'locale', 'connection']

 /**
 * Register the Models section once the `settings.section` declaration is on
- * the ledger.
+ * the ledger, wire its store to the connection, and keep it fresh on every
+ * pushed invalidation (settings, credentials, or provider topology).
 * @param ctx - client root context.
 */
 export function apply(ctx: ClientContext): void {
  ctx.effect(() => {
    const disposers = [
-      ctx.locale.register('settings.models', 'zh', { nav: '模型' }),
-      ctx.locale.register('settings.models', 'en', { nav: 'Models' }),
+      ctx.locale.register('settings.models', 'zh', zh),
+      ctx.locale.register('settings.models', 'en', en),
    ]
    return () => { for (const dispose of disposers) dispose() }
-  }, 'ui-models: nav copy dictionaries')
+  }, 'ui-models: copy dictionaries')
+
+  const connection = ctx.get('connection') as ConnectionHandle
+  const controller = new ModelsSettingsStore(connection.api)
+  const useSnapshot = bindSnapshotSelector(controller.store)
+  const t = ctx.locale.bind('settings.models') as ModelsSectionInjected['t']
+  const injected = (): ModelsSectionInjected => ({
+    controller,
+    useSnapshot,
+    api: connection.api,
+    t,
+  })
+  const onboardingInjected = (): DeepSeekOnboardingInjected => ({
+    controller,
+    useSnapshot,
+    t,
+  })
+
+  // Pushed invalidations converge every open surface without polling: any
+  // settings/credentials/topology change refetches once the page loaded.
  ctx.effect(() => {
-    const deferred = deferRegistration(ctx.slots, 'settings.section', ModelsSection, () =>
+    const refresh = (): void => { refreshIfLoaded(controller) }
+    const disposers = [
+      ctx.on('settings/changed', refresh),
+      ctx.on('credentials/changed', refresh),
+      ctx.on('models/changed', refresh),
+      ctx.on('connection/reset', refresh),
+    ]
+    return () => { for (const dispose of disposers) dispose() }
+  }, 'ui-models: pushed invalidations')
+
+  ctx.effect(() => {
+    const section = deferRegistration(ctx.slots, 'settings.section', ModelsSection, () =>
      ctx.slots.register({
        name: 'settings.section',
        id: 'models',
        order: 10,
-        label: ctx.locale.bind('settings.models')('nav'),
+        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')
 }
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -0,0 +1,69 @@
+/** Copy dictionaries for the Models settings section. */
+
+/** English strings. */
+export const en = {
+  nav: 'Models',
+  title: 'Models',
+  intro: 'Enter your API keys to use models from the following providers.',
+  active: 'Active',
+  dormant: 'Inactive',
+  edit: 'Edit',
+  remove: 'Delete',
+  add: 'Add provider',
+  provider: 'Provider',
+  cancel: 'Cancel',
+  apply: 'Apply',
+  applying: 'Applying…',
+  readOnly: 'The settings document is read-only in this deployment.',
+  loadFailed: 'Loading the provider directory failed',
+  conflict: 'Someone else changed these settings while this card was open. Close it and reopen to edit the current values.',
+  retry: 'Retry',
+  keyInput: 'API key',
+  keyPlaceholder: 'Enter your API key',
+  keyStored: 'Configured — enter a new value to replace',
+  keyEnvLocked: 'Provided by the launch environment (read-only)',
+  customized: 'Customized settings',
+  baseUrl: 'Base URL',
+  baseUrlDefault: 'Provider default',
+  effort: 'Reasoning effort',
+  effortInherit: 'Default',
+  advancedHint: 'Other fields live in settings.yaml; edit that section directly.',
+  onboardingTitle: 'Add an API key to get started',
+  onboardingDescription: 'Configure the official DeepSeek provider to start building.',
+  onboardingGoToSettings: 'Go to settings',
+  onboardingLater: 'Configure later',
+}
+
+/** Chinese strings (same keys as {@link en}). */
+export const zh: typeof en = {
+  nav: '模型',
+  title: '模型',
+  intro: '填入各提供方的 API 密钥即可使用其模型。',
+  active: '已启用',
+  dormant: '未启用',
+  edit: '编辑',
+  remove: '删除',
+  add: '添加提供方',
+  provider: '提供方',
+  cancel: '取消',
+  apply: '保存',
+  applying: '保存中…',
+  readOnly: '当前部署的设置文档为只读。',
+  loadFailed: '加载提供方目录失败',
+  conflict: '这张卡片打开期间，这些设置已被其他地方改动。请关闭后重新打开，在当前值上编辑。',
+  retry: '重试',
+  keyInput: 'API 密钥',
+  keyPlaceholder: '输入 API 密钥',
+  keyStored: '已配置——输入新值可替换',
+  keyEnvLocked: '由启动环境提供（只读）',
+  customized: '自定义设置',
+  baseUrl: 'API 地址',
+  baseUrlDefault: '提供方默认',
+  effort: '推理强度',
+  effortInherit: '默认',
+  advancedHint: '其余字段在 settings.yaml 中，请直接编辑对应段。',
+  onboardingTitle: '添加一个 API Key 开始使用',
+  onboardingDescription: '配置 DeepSeek 官方模型，即可开始使用。',
+  onboardingGoToSettings: '前往配置',
+  onboardingLater: '稍后配置',
+}
--- a/packages/client/ui-models/src/client/store.ts
+++ b/packages/client/ui-models/src/client/store.ts
@@ -0,0 +1,285 @@
+/**
+ * Models settings page store: one snapshot joining the configurable-provider
+ * directory (`llm.providers`), the settings namespaces (`settings.describe`),
+ * and the referenced credentials (`credentials.describe`). The host stays the
+ * single fact source — every mutation writes through the wire and the page
+ * re-renders from the next describe, pushed or refetched.
+ */
+
+import type {
+  ConfigurableProviderView, CredentialView, IApiClient, SettingsNamespaceView,
+} from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { getPath, hasPath } from '@deepseek-ai/dsh-client-schema-form'
+
+/** One provider row the page renders. */
+export interface ProviderRow {
+  /** The directory entry (route id, display name, settings address, live state). */
+  entry: ConfigurableProviderView
+  /** Whether any layer configures this provider (its profile resolves). */
+  configured: boolean
+  /** Whether the user layer alone carries the profile (removal restores the base). */
+  removable: boolean
+  /** The credential reference the resolved profile names, when one does. */
+  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. */
+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. */
+  rows: readonly ProviderRow[]
+  /** Namespace views by ns, for the editor's schema/layers/secrets. */
+  namespaces: ReadonlyMap<string, SettingsNamespaceView>
+}
+
+/**
+ * Human text for a rejected wire call. A transport failure rejects with an
+ * Error; a host or a runtime can reject with anything, and the page still has
+ * to say something.
+ * @param error - the rejection value.
+ * @returns the message to show.
+ */
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Derive the conventional credential reference for a provider route: the v1
+ * page never asks for an environment-variable name, so a typed key stores
+ * under this derived reference and the profile records it as `apiKeyEnv`.
+ * @param provider - provider route id (e.g. `anthropic`, `minimax-cn`).
+ * @returns the derived reference name (e.g. `MINIMAX_CN_API_KEY`).
+ */
+export function deriveKeyRef(provider: string): string {
+  return `${provider.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_API_KEY`
+}
+
+/** The credential reference a resolved profile names (its `apiKeyEnv` field). */
+function apiKeyEnvOf(namespace: SettingsNamespaceView | undefined, path: readonly string[]): string | undefined {
+  if (namespace === undefined) return undefined
+  const profile = getPath(namespace.value, path)
+  if (typeof profile !== 'object' || profile === null) return undefined
+  const ref = (profile as { apiKeyEnv?: unknown }).apiKeyEnv
+  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]))
+}
+
+/** 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, credentialError: null, writable: false, rows: [], namespaces: new Map(),
+  })
+
+  /** Latest load wins; an older response never overwrites a newer one. */
+  private generation = 0
+
+  /**
+   * @param api - the wire face (settings/credentials/llm domains).
+   */
+  constructor(private readonly api: Pick<IApiClient, 'settings' | 'credentials' | 'llm'>) {}
+
+  /**
+   * Surface a failure from an operation the page ran outside {@link load} —
+   * a row removal — on the same banner a load failure uses.
+   * @param message - the failure text to show.
+   */
+  fail(message: string): void {
+    this.store.update((s) => {
+      s.status = 'error'
+      s.error = message
+    })
+  }
+
+  /**
+   * Refresh the whole page snapshot: directory and namespaces in parallel,
+   * then one batched credential describe over every referenced ref. A
+   * failure keeps the last good rows and surfaces the error.
+   * @returns nothing; the snapshot carries the outcome.
+   */
+  async load(): Promise<void> {
+    const generation = ++this.generation
+    this.store.update((s) => { s.status = 'loading'; s.error = null })
+    let providers: ConfigurableProviderView[]
+    let writable: boolean
+    let views: SettingsNamespaceView[]
+    try {
+      const [providersResponse, settingsResponse] = await Promise.all([
+        this.api.llm.providers({}),
+        this.api.settings.describe({}),
+      ])
+      if (!providersResponse.result.ok) throw new Error(providersResponse.result.error.message)
+      if (!settingsResponse.result.ok) throw new Error(settingsResponse.result.error.message)
+      providers = providersResponse.result.value.providers
+      writable = settingsResponse.result.value.writable
+      views = settingsResponse.result.value.namespaces
+    } catch (error) {
+      if (generation !== this.generation) return
+      this.store.update((s) => {
+        s.status = 'error'
+        s.error = error instanceof Error ? error.message : String(error)
+      })
+      return
+    }
+    const namespaces = new Map(views.map(view => [view.ns, view]))
+    const rows: ProviderRow[] = providers.map((entry) => {
+      const namespace = namespaces.get(entry.settingsNs)
+      const configured = namespace !== undefined
+        && (entry.settingsPath.length === 0 || getPath(namespace.value, entry.settingsPath) !== undefined)
+      const removable = namespace !== undefined
+        && entry.settingsPath.length > 0
+        && hasPath(namespace.user, entry.settingsPath)
+        && !hasPath(namespace.base, entry.settingsPath)
+      return {
+        entry,
+        configured,
+        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) {
+      try {
+        const response = await this.api.credentials.describe({ refs })
+        // Credential state is an enrichment for the Models page: neither a
+        // business rejection nor a transport failure fails the load. The
+        // onboarding projection below retains the failure distinction.
+        if (response.result.ok) credentials = response.result.value.credentials
+        else credentialError = response.result.error.message
+      } catch (error) {
+        credentialError = messageOf(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,
+        ...row.apiKeyEnv !== undefined && credentials[row.apiKeyEnv] !== undefined
+          ? { credential: credentials[row.apiKeyEnv] }
+          : {},
+      }))
+      s.namespaces = namespaces
+    })
+  }
+}
+
+/** DeepSeek onboarding readiness derived only from the shared Models join. */
+export type DeepSeekReadiness =
+  | { kind: 'loading' }
+  | { kind: 'adapter-absent' }
+  | { 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'
+  }
+
+/**
+ * Project official-DeepSeek readiness from the provider/settings/credential
+ * 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.
+ */
+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: 'load-failed',
+    }
+  }
+  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 {
+      kind: 'unavailable',
+      reason: 'provider-inactive',
+    }
+  }
+  if (!row.configured) {
+    return {
+      kind: 'unavailable',
+      reason: 'settings-unavailable',
+    }
+  }
+  if (row.literalApiKeyConfigured) return { kind: 'configured' }
+  if (row.apiKeyEnv === undefined) {
+    return {
+      kind: 'unavailable',
+      reason: 'credential-ref-unavailable',
+    }
+  }
+  if (state.credentialError !== null) {
+    return {
+      kind: 'unavailable',
+      reason: 'credentials-unavailable',
+    }
+  }
+  if (row.credential === undefined) {
+    return {
+      kind: 'unavailable',
+      reason: 'credentials-unavailable',
+    }
+  }
+  if (row.credential.configured) {
+    return { kind: 'configured' }
+  }
+  if (!state.writable) {
+    return {
+      kind: 'unavailable',
+      reason: 'settings-read-only',
+    }
+  }
+  if (!row.credential.writable) {
+    return {
+      kind: 'unavailable',
+      reason: 'credential-read-only',
+    }
+  }
+  return { kind: 'credential-missing' }
+}
--- a/packages/client/ui-models/tests/apply.spec.ts
+++ b/packages/client/ui-models/tests/apply.spec.ts
@@ -1,29 +1,39 @@
 /** 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 } from '@deepseek-ai/dsh-client-ui-models/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()
  await ctx.plugin(SlotsService).await()
  const locale = new LocaleService(ctx)
  ctx.provide('locale', locale)
+  // The apply path only captures the wire face; no call leaves this fake
+  // until a section actually loads.
+  ctx.provide('connection', { api: {} } as never)
  return { ctx, slots: ctx.get('slots') as SlotsService, locale }
 }

 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,
  )
 }

 describe('ui-models apply', () => {
  it('declares the services it uses', () => {
-    expect(inject).toEqual(['slots', 'locale'])
+    expect(inject).toEqual(['slots', 'locale', 'connection'])
  })

  it('registers the models nav entry for declarations before or after apply', async () => {
@@ -32,14 +42,24 @@ describe('ui-models apply', () => {
    await before.ctx.plugin({ inject: [...inject], apply }).await()
    const entry = before.slots.entries('settings.section')[0]!
    expect(entry.component).toBe(ModelsSection)
-    expect(entry.options).toEqual({ id: 'models', order: 10, label: '模型' })
+    expect(entry.options).toMatchObject({ id: 'models', order: 10, label: '模型' })
+    const injected = (entry.inject as unknown as () => import('../src/client/ModelsSection.tsx').ModelsSectionInjected)()
+    expect(injected.t('nav')).toBe('模型')
+    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)
  })
@@ -71,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')
@@ -88,8 +110,52 @@ 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()
  })
 })
+
+describe('pushed invalidations', () => {
+  it('ignores invalidations before the page ever loaded', async () => {
+    const b = await bench()
+    declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    // The fake wire face has no methods: a fetch attempt would throw.
+    b.ctx.emit('settings/changed', 'llm-pi-ai')
+    b.ctx.emit('credentials/changed', 'OPENAI_API_KEY')
+    b.ctx.emit('models/changed')
+    b.ctx.emit('connection/reset')
+  })
+
+  it('refreshes a loaded page and skips an idle one', () => {
+    const loads: number[] = []
+    const controller = {
+      store: { getSnapshot: () => ({ status: 'ready' }) },
+      load: () => { loads.push(1); return Promise.resolve() },
+    }
+    refreshIfLoaded(controller as unknown as import('../src/client/store.ts').ModelsSettingsStore)
+    expect(loads).toHaveLength(1)
+    const idle = {
+      store: { getSnapshot: () => ({ status: 'idle' }) },
+      load: () => { loads.push(2); return Promise.resolve() },
+    }
+    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)
+  })
+})
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -0,0 +1,606 @@
+// @vitest-environment jsdom
+/** Section, setup-card, and hand-written editor behavior over a scripted wire face. */
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+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, needsSetup, removeProviderProfile } from '../src/client/ModelsSection.tsx'
+import type { ModelsSectionInjected, ModelsSectionProps } from '../src/client/ModelsSection.tsx'
+import { pathOps } from '../src/client/ProviderEditor.tsx'
+import { deriveKeyRef, ModelsSettingsStore } from '../src/client/store.ts'
+import type { ProviderRow } from '../src/client/store.ts'
+import { en } from '../src/client/locales.ts'
+
+afterEach(cleanup)
+
+const t: ModelsSectionInjected['t'] = key => en[key]
+
+const PiAiConfig = Schema.object({
+  token: Schema.string().role('secret'),
+  providers: Schema.dict(Schema.object({
+    apiKey: Schema.string().role('secret'),
+    apiKeyEnv: Schema.string().role('credential-ref'),
+    baseURL: Schema.string(),
+    reasoning: Schema.union(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']),
+    headers: Schema.dict(Schema.string()),
+  })),
+})
+
+const DeepSeekConfig = Schema.object({
+  apiKey: Schema.string().role('secret'),
+  apiKeyEnv: Schema.string().role('credential-ref'),
+  baseURL: Schema.string().pattern(/^https:\/\//),
+  reasoningEffort: Schema.union(['off', 'high', 'max']),
+})
+
+function wireNamespaces(): SettingsNamespaceView[] {
+  return [
+    {
+      ns: 'llm-deepseek',
+      schema: JSON.parse(JSON.stringify(DeepSeekConfig.toJSON())) as unknown,
+      value: { apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://base', reasoningEffort: 'high' },
+      base: {},
+      user: { reasoningEffort: 'high' },
+      applies: 'live',
+      secrets: [{ path: ['apiKey'], set: false }],
+      revision: 0,
+    },
+    {
+      ns: 'llm-plain',
+      schema: JSON.parse(JSON.stringify(Schema.object({
+        profiles: Schema.dict(Schema.object({ note: Schema.string() })),
+      }).toJSON())) as unknown,
+      value: {},
+      applies: 'live',
+      secrets: [],
+      revision: 0,
+    },
+    {
+      ns: 'llm-pi-ai',
+      schema: JSON.parse(JSON.stringify(PiAiConfig.toJSON())) as unknown,
+      value: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://proxy', headers: { 'X-Team': 'a' } }, zombie: {} } },
+      user: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://proxy', headers: { 'X-Team': 'a' } }, zombie: {} } },
+      applies: 'live',
+      secrets: [{ path: ['token'], set: false }, { path: ['providers', 'openai', 'apiKey'], set: false }],
+      revision: 0,
+    },
+  ]
+}
+
+let nextRpc = 0
+function ok<T>(value: T): RpcResponse<T> {
+  return { rpcId: `r-${nextRpc++}` as never, result: { ok: true, value } }
+}
+function fail<T>(message: string, code = 'settings-rejected'): RpcResponse<T> {
+  return {
+    rpcId: `r-${nextRpc++}` as never,
+    result: { ok: false, error: { code, message, details: { ns: 'x' } } as never },
+  }
+}
+
+function scriptedFace(overrides: {
+  update?: ReturnType<typeof vi.fn>
+  replace?: ReturnType<typeof vi.fn>
+  mutate?: ReturnType<typeof vi.fn>
+  set?: ReturnType<typeof vi.fn>
+} = {}) {
+  const update = overrides.update ?? vi.fn(() => Promise.resolve(ok(wireNamespaces()[2])))
+  const replace = overrides.replace ?? vi.fn(() => Promise.resolve(ok(wireNamespaces()[2])))
+  const mutate = overrides.mutate ?? vi.fn(() => Promise.resolve(ok(wireNamespaces()[2])))
+  const set = overrides.set ?? vi.fn(() => Promise.resolve(ok({})))
+  const face = {
+    llm: {
+      providers: vi.fn(() => Promise.resolve(ok({
+        providers: [
+          { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [], active: true },
+          { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'], active: true },
+          { provider: 'anthropic', displayName: 'anthropic', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'anthropic'], active: false },
+          { provider: 'zombie', displayName: 'zombie', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'zombie'], active: false },
+          { provider: 'broken', displayName: 'broken', settingsNs: 'llm-pi-ai', settingsPath: ['nope', 'x'], active: false },
+          { provider: 'plain', displayName: 'plain', settingsNs: 'llm-plain', settingsPath: ['profiles', 'plain'], active: false },
+        ],
+      }))),
+      models: vi.fn(() => Promise.resolve(ok({ groups: [], failures: [] }))),
+    },
+    settings: {
+      describe: vi.fn(() => Promise.resolve(ok({ writable: true, namespaces: wireNamespaces() }))),
+      update,
+      replace,
+      mutate,
+    },
+    credentials: {
+      describe: vi.fn((payload: { refs: string[] }) => Promise.resolve(ok({
+        credentials: Object.fromEntries(payload.refs.map(ref => [ref, {
+          configured: ref === 'OPENAI_API_KEY',
+          ...ref === 'OPENAI_API_KEY' ? { source: 'file' } : {},
+          writable: true,
+        }])),
+      }))),
+      set,
+      unset: vi.fn(() => Promise.resolve(ok({}))),
+    },
+  }
+  return { face, update, replace, mutate, set }
+}
+
+type WireFace = ConstructorParameters<typeof ModelsSettingsStore>[0]
+
+async function mountSection(overrides: Parameters<typeof scriptedFace>[0] = {}) {
+  const { face, update, replace, mutate, set } = scriptedFace(overrides)
+  const controller = new ModelsSettingsStore(face as unknown as WireFace)
+  await controller.load()
+  const injected: ModelsSectionInjected = {
+    controller,
+    useSnapshot: bindSnapshotSelector(controller.store),
+    api: face as never,
+    t,
+  }
+  const view = render(<ModelsSection {...injected} />)
+  return { view, face, update, replace, mutate, set, controller }
+}
+
+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 the unkeyed whole-section provider as an open setup card beside the rows', async () => {
+    await mountSection()
+    // DeepSeek has no configured credential and no stored apiKey → setup card.
+    expect(screen.getByText('DeepSeek')).toBeTruthy()
+    expect(screen.getByLabelText(en.keyInput)).toBeTruthy()
+    // Configured pi-ai profiles render as rows with liveness badges only.
+    expect(screen.getByText('openai')).toBeTruthy()
+    expect(screen.getAllByText(en.active)).toHaveLength(1)
+    expect(screen.getByText(en.dormant)).toBeTruthy()
+    expect(screen.getByText(`+ ${en.add}`)).toBeTruthy()
+  })
+
+  it('turns the setup card into a row once the credential reports configured', async () => {
+    const { face } = await mountSection()
+    face.credentials.describe.mockImplementation((payload: { refs: string[] }) => Promise.resolve(ok({
+      credentials: Object.fromEntries(payload.refs.map(ref => [ref, { configured: true, writable: true }])),
+    })))
+    const controller = new ModelsSettingsStore(face as unknown as WireFace)
+    await controller.load()
+    cleanup()
+    render(<ModelsSection
+      controller={controller}
+      useSnapshot={bindSnapshotSelector(controller.store)}
+      api={face as never}
+      t={t}
+    />)
+    // Now a row with an Edit button, not an open card.
+    expect(screen.getAllByText(en.edit).length).toBeGreaterThan(1)
+    expect(screen.queryByLabelText(en.keyInput)).toBeNull()
+  })
+
+  it('decides setup need from the joined credential state and literal-key sidecar', () => {
+    const entry = { provider: 'p', displayName: 'p', settingsNs: 'llm-deepseek', settingsPath: [], active: true }
+    const row = (
+      credential: ProviderRow['credential'],
+      literalApiKeyConfigured = false,
+    ): ProviderRow => ({
+      entry,
+      configured: true,
+      removable: false,
+      apiKeyEnv: 'X',
+      credential,
+      literalApiKeyConfigured,
+    })
+    expect(needsSetup(row(undefined))).toBe(true)
+    expect(needsSetup(row({ configured: true, writable: true }))).toBe(false)
+    expect(needsSetup(row(undefined, true))).toBe(false)
+    const nested = { ...row(undefined), entry: { ...entry, settingsPath: ['providers', 'x'] } }
+    expect(needsSetup(nested)).toBe(false)
+  })
+
+  it('derives conventional credential references from route ids', () => {
+    expect(deriveKeyRef('anthropic')).toBe('ANTHROPIC_API_KEY')
+    expect(deriveKeyRef('minimax-cn')).toBe('MINIMAX_CN_API_KEY')
+  })
+
+  it('names only the fields the card can see, so an unseen secret survives', () => {
+    // `before` is the REDACTED subtree: a stored literal apiKey is in neither
+    // side, so no op mentions it and the seam leaves it alone.
+    expect(pathOps(['providers', 'openai'], { baseURL: 'https://old', reasoning: 'high' }, { reasoning: 'high' }))
+      .toEqual([{ op: 'unset', path: ['providers', 'openai', 'baseURL'] }])
+    expect(pathOps([], { b: 1 }, { b: 2, d: 3 }))
+      .toEqual([{ op: 'set', path: ['b'], value: 2 }, { op: 'set', path: ['d'], value: 3 }])
+    expect(pathOps([], undefined, {})).toEqual([])
+    expect(pathOps([], { a: 1 }, { a: 1 })).toEqual([])
+  })
+
+  it('stores a typed key write-only from the setup card without touching settings', async () => {
+    const { set, update, face } = await mountSection()
+    const key = screen.getByLabelText<HTMLInputElement>(en.keyInput)
+    fireEvent.change(key, { target: { value: 'sk-live' } })
+    fireEvent.click(screen.getByText(en.apply))
+    await waitFor(() => { expect(set).toHaveBeenCalledWith({ ref: 'DEEPSEEK_API_KEY', value: 'sk-live' }) })
+    expect(update).not.toHaveBeenCalled()
+    await waitFor(() => { expect(face.settings.describe.mock.calls.length).toBeGreaterThan(1) })
+  })
+
+  it('applies customized deepseek fields as path ops', async () => {
+    const { mutate } = await mountSection({
+      mutate: vi.fn(() => Promise.resolve(ok(wireNamespaces()[0]))),
+    })
+    fireEvent.click(screen.getByText(en.customized))
+    const baseURL = screen.getByLabelText<HTMLInputElement>(en.baseUrl)
+    // The deepseek placeholder is pinned to the public endpoint, not the
+    // effective value (which may reflect a launch-environment override).
+    expect(baseURL.placeholder).toBe('https://api.deepseek.com')
+    fireEvent.change(baseURL, { target: { value: 'https://next2' } })
+    fireEvent.click(screen.getByText(en.apply))
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    // Only the field that actually changed: reasoningEffort was already
+    // 'high' in the loaded profile, so it produces no op.
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
+      ns: 'llm-deepseek',
+      ops: [{ op: 'set', path: ['baseURL'], value: 'https://next2' }],
+      expectedRevision: 0,
+    })
+  })
+
+  it('clears an inherited override with an unset op, never a whole-section replace', async () => {
+    // The data-loss shape: the old path rebuilt the section from the REDACTED
+    // user layer and replaced it wholesale, deleting any stored literal key.
+    const { replace, update, mutate } = await mountSection()
+    fireEvent.click(screen.getByText(en.customized))
+    const effort = screen.getByLabelText<HTMLSelectElement>(en.effort)
+    expect(effort.value).toBe('high')
+    fireEvent.change(effort, { target: { value: '' } })
+    fireEvent.click(screen.getByText(en.apply))
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    expect(replace).not.toHaveBeenCalled()
+    expect(update).not.toHaveBeenCalled()
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
+      ns: 'llm-deepseek',
+      ops: [{ op: 'unset', path: ['reasoningEffort'] }],
+      expectedRevision: 0,
+    })
+  })
+
+  it('pins the deepseek placeholder and clears typed input back to inherited', async () => {
+    const { face } = scriptedFace()
+    const bare: SettingsNamespaceView = {
+      ns: 'llm-deepseek',
+      schema: JSON.parse(JSON.stringify(DeepSeekConfig.toJSON())) as unknown,
+      value: {},
+      applies: 'live',
+      secrets: [],
+      revision: 0,
+    }
+    const { ProviderEditor } = await import('../src/client/ProviderEditor.tsx')
+    render(<ProviderEditor
+      provider="deepseek-official"
+      displayName="DeepSeek"
+      namespace={bare}
+      settingsPath={[]}
+      api={face as never}
+      t={t}
+      readOnly={false}
+      onClose={() => {}}
+    />)
+    fireEvent.click(screen.getByText(en.customized))
+    const baseURL = screen.getByLabelText<HTMLInputElement>(en.baseUrl)
+    expect(baseURL.placeholder).toBe('https://api.deepseek.com')
+    fireEvent.change(baseURL, { target: { value: 'https://x' } })
+    expect(baseURL.value).toBe('https://x')
+    fireEvent.change(baseURL, { target: { value: '' } })
+    expect(baseURL.value).toBe('')
+  })
+
+  it('rejects an invalid draft before writing', async () => {
+    const { update } = await mountSection()
+    fireEvent.click(screen.getByText(en.customized))
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'not-a-url' } })
+    fireEvent.click(screen.getByText(en.apply))
+    await screen.findByText(/baseURL/)
+    expect(update).not.toHaveBeenCalled()
+  })
+
+  it('edits a pi-ai profile with the curated fields only', async () => {
+    const { mutate } = await mountSection()
+    fireEvent.click(screen.getAllByText(en.edit)[0] as HTMLElement)
+    // The configured credential shows as the stored placeholder.
+    const keys = await screen.findAllByLabelText<HTMLInputElement>(en.keyInput)
+    const editorKey = keys[keys.length - 1] as HTMLInputElement
+    await waitFor(() => { expect(editorKey.placeholder).toBe(en.keyStored) })
+    // pi-ai carries Base URL too: the stored override shows as the value and
+    // the effective profile endpoint as its placeholder source.
+    fireEvent.click(screen.getAllByText(en.customized)[1] as HTMLElement)
+    const urls = screen.getAllByLabelText<HTMLInputElement>(en.baseUrl)
+    expect(urls).toHaveLength(2)
+    expect((urls[1] as HTMLInputElement).value).toBe('https://proxy')
+    const effort = screen.getAllByLabelText<HTMLSelectElement>(en.effort)
+    fireEvent.change(effort[effort.length - 1] as HTMLSelectElement, { target: { value: 'xhigh' } })
+    fireEvent.click(screen.getAllByText(en.apply)[1] as HTMLElement)
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    // Only the edited field travels: apiKeyEnv, baseURL and headers were
+    // already stored with these values, so no op restates them — and the
+    // profile's stored literal apiKey, absent from the redacted view the card
+    // read, is named by nothing at all.
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
+      ns: 'llm-pi-ai',
+      ops: [{ op: 'set', path: ['providers', 'openai', 'reasoning'], value: 'xhigh' }],
+      expectedRevision: 0,
+    })
+  })
+
+  it('adds a dormant provider with a derived reference and stores its key', async () => {
+    const { mutate, set } = await mountSection()
+    fireEvent.click(screen.getByText(`+ ${en.add}`))
+    const pick = await screen.findByLabelText<HTMLSelectElement>(en.provider)
+    expect([...pick.options].map(option => option.value)).toEqual(['anthropic', 'broken', 'plain'])
+    expect(pick.value).toBe('anthropic')
+    // A dormant profile has no endpoint anywhere: the pi-ai placeholder
+    // falls back to the provider-default wording.
+    fireEvent.click(screen.getAllByText(en.customized)[1] as HTMLElement)
+    const urls = screen.getAllByLabelText<HTMLInputElement>(en.baseUrl)
+    expect((urls[1] as HTMLInputElement).placeholder).toBe(en.baseUrlDefault)
+    const keys = screen.getAllByLabelText<HTMLInputElement>(en.keyInput)
+    const addKey = keys[keys.length - 1] as HTMLInputElement
+    fireEvent.change(addKey, { target: { value: 'sk-ant' } })
+    fireEvent.click(screen.getAllByText(en.apply)[1] as HTMLElement)
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
+      ns: 'llm-pi-ai',
+      ops: [{ op: 'set', path: ['providers', 'anthropic', 'apiKeyEnv'], value: 'ANTHROPIC_API_KEY' }],
+      expectedRevision: 0,
+    })
+    await waitFor(() => { expect(set).toHaveBeenCalledWith({ ref: 'ANTHROPIC_API_KEY', value: 'sk-ant' }) })
+  })
+
+  it('switches the add card target and degrades unknown or broken targets loudly', async () => {
+    await mountSection()
+    fireEvent.click(screen.getByText(`+ ${en.add}`))
+    const pick = await screen.findByLabelText<HTMLSelectElement>(en.provider)
+    fireEvent.change(pick, { target: { value: 'broken' } })
+    await screen.findByText(/unresolvable settings path/)
+    fireEvent.change(pick, { target: { value: 'plain' } })
+    await waitFor(() => {
+      expect(screen.getAllByText(content => content.includes(en.advancedHint)).length).toBeGreaterThan(0)
+    })
+    // The hint-only card cannot apply anything.
+    const applies = screen.getAllByText<HTMLButtonElement>(en.apply)
+    expect((applies[applies.length - 1] as HTMLButtonElement).disabled).toBe(true)
+    expect(screen.getAllByLabelText(en.keyInput)).toHaveLength(1)
+  })
+
+  it('surfaces a rejected settings write and never stores the key after it', async () => {
+    const { set } = await mountSection({
+      mutate: vi.fn(() => Promise.resolve(fail('llm-pi-ai: unknown pi-ai provider "bogus"'))),
+    })
+    fireEvent.click(screen.getByText(`+ ${en.add}`))
+    await screen.findByLabelText(en.provider)
+    const keys = screen.getAllByLabelText<HTMLInputElement>(en.keyInput)
+    fireEvent.change(keys[keys.length - 1] as HTMLInputElement, { target: { value: 'sk-x' } })
+    fireEvent.click(screen.getAllByText(en.apply)[1] as HTMLElement)
+    await screen.findByText(/unknown pi-ai provider/)
+    expect(set).not.toHaveBeenCalled()
+  })
+
+  it('renders the card without the stored-key hint when the credential probe rejects', async () => {
+    // The probe is a placeholder hint, not a precondition: an escaping
+    // rejection would surface in the browser as an unhandled rejection.
+    const { face } = scriptedFace()
+    face.credentials.describe = vi.fn(() => Promise.reject(new Error('connection lost')))
+    const unhandled = vi.fn()
+    process.on('unhandledRejection', unhandled)
+    try {
+      const controller = new ModelsSettingsStore(face as unknown as WireFace)
+      await controller.load()
+      render(<ModelsSection
+        controller={controller}
+        useSnapshot={bindSnapshotSelector(controller.store)}
+        api={face as never}
+        t={t}
+      />)
+      const key = await screen.findByLabelText<HTMLInputElement>(en.keyInput)
+      expect(key.placeholder).toBe(en.keyPlaceholder)
+      await new Promise(resolve => setTimeout(resolve, 10))
+      expect(unhandled).not.toHaveBeenCalled()
+    } finally {
+      process.off('unhandledRejection', unhandled)
+    }
+  })
+
+  it('tells the user to reopen when another writer moved the namespace first', async () => {
+    // The stale-draft overwrite: two tabs open the same card, the other saves,
+    // and this one must be refused rather than replay its opening snapshot.
+    const { set } = await mountSection({
+      mutate: vi.fn(() => Promise.resolve(fail('changed since it was read', 'settings-conflict'))),
+    })
+    fireEvent.click(screen.getByText(en.customized))
+    fireEvent.change(screen.getByLabelText<HTMLInputElement>(en.baseUrl), { target: { value: 'https://mine' } })
+    fireEvent.click(screen.getByText(en.apply))
+    await screen.findByText(en.conflict)
+    expect(set).not.toHaveBeenCalled()
+  })
+
+  it('keeps the card usable when the write rejects instead of answering', async () => {
+    // A transport failure (disconnect, or the 403 a non-loopback browser now
+    // gets on the whole configuration plane) rejects rather than returning a
+    // failed envelope: without a catch the card would stay busy forever.
+    await mountSection({ mutate: vi.fn(() => Promise.reject(new Error('connection lost'))) })
+    fireEvent.click(screen.getByText(en.customized))
+    fireEvent.change(screen.getByLabelText<HTMLInputElement>(en.baseUrl), { target: { value: 'https://next' } })
+    fireEvent.click(screen.getByText(en.apply))
+    await screen.findByText('connection lost')
+    // Not stuck in `applying…`: the finally cleared busy, so Apply is live again.
+    expect(screen.getByText(en.apply)).toBeTruthy()
+  })
+
+  it('surfaces a shadowed credential write on the card', async () => {
+    await mountSection({
+      set: vi.fn(() => Promise.resolve(fail('credentials: DEEPSEEK_API_KEY is shadowed by the read-only environment', 'credential-rejected'))),
+    })
+    const key = screen.getByLabelText<HTMLInputElement>(en.keyInput)
+    fireEvent.change(key, { target: { value: 'sk-live' } })
+    fireEvent.click(screen.getByText(en.apply))
+    await screen.findByText(/shadowed by the read-only environment/)
+  })
+
+  it('locks the key input when the launch environment provides the credential', async () => {
+    const { face } = await mountSection()
+    face.credentials.describe.mockImplementation((payload: { refs: string[] }) => Promise.resolve(ok({
+      credentials: Object.fromEntries(payload.refs.map(ref => [ref, {
+        configured: ref === 'OPENAI_API_KEY', source: 'env', writable: false,
+      }])),
+    })))
+    fireEvent.click(screen.getAllByText(en.edit)[0] as HTMLElement)
+    const keys = await screen.findAllByLabelText<HTMLInputElement>(en.keyInput)
+    const editorKey = keys[keys.length - 1] as HTMLInputElement
+    await waitFor(() => { expect(editorKey.placeholder).toBe(en.keyEnvLocked) })
+    expect(editorKey.disabled).toBe(true)
+  })
+
+  it('keeps a failed credential describe silent and the input usable', async () => {
+    const { face, set } = await mountSection()
+    face.credentials.describe.mockImplementation(() => Promise.resolve(fail('down', 'internal')) as never)
+    fireEvent.click(screen.getAllByText(en.edit)[0] as HTMLElement)
+    const keys = await screen.findAllByLabelText<HTMLInputElement>(en.keyInput)
+    const editorKey = keys[keys.length - 1] as HTMLInputElement
+    expect(editorKey.placeholder).toBe(en.keyPlaceholder)
+    fireEvent.change(editorKey, { target: { value: 'sk-live' } })
+    fireEvent.click(screen.getAllByText(en.apply)[1] as HTMLElement)
+    await waitFor(() => { expect(set).toHaveBeenCalledTimes(1) })
+  })
+
+  it('removes a user-added provider by unsetting its path', async () => {
+    const { replace, mutate } = await mountSection()
+    fireEvent.click(screen.getAllByText(en.remove)[0] as HTMLElement)
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    expect(replace).not.toHaveBeenCalled()
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
+      ns: 'llm-pi-ai',
+      ops: [{ op: 'unset', path: ['providers', 'openai'] }],
+    })
+  })
+
+  it('renders the load failure with a retry control', async () => {
+    const face = scriptedFace()
+    face.face.llm.providers = vi.fn(() => Promise.resolve(fail('directory down', 'internal'))) as never
+    const controller = new ModelsSettingsStore(face.face as unknown as WireFace)
+    await controller.load()
+    render(<ModelsSection
+      controller={controller}
+      useSnapshot={bindSnapshotSelector(controller.store)}
+      api={face.face as never}
+      t={t}
+    />)
+    expect(screen.getByText(/directory down/)).toBeTruthy()
+    fireEvent.click(screen.getByText(en.retry))
+    await waitFor(() => { expect(screen.queryByText(/directory down/)).toBeNull() })
+  })
+
+  it('shows the read-only notice and disables mutations for a read-only provider', async () => {
+    const { face } = await mountSection()
+    face.settings.describe.mockImplementation(() => Promise.resolve(ok({
+      writable: false,
+      namespaces: wireNamespaces(),
+    })))
+    const controller = new ModelsSettingsStore(face as unknown as WireFace)
+    await controller.load()
+    cleanup()
+    render(<ModelsSection
+      controller={controller}
+      useSnapshot={bindSnapshotSelector(controller.store)}
+      api={face as never}
+      t={t}
+    />)
+    expect(screen.getByText(en.readOnly)).toBeTruthy()
+    expect(screen.getAllByText<HTMLButtonElement>(en.remove).every(button => button.disabled)).toBe(true)
+    expect(screen.getByText<HTMLButtonElement>(`+ ${en.add}`).disabled).toBe(true)
+  })
+
+  it('toggles the row editor closed on a second edit click and on cancel', async () => {
+    const { update } = await mountSection()
+    const edit = screen.getAllByText(en.edit)[0] as HTMLElement
+    fireEvent.click(edit)
+    await waitFor(() => { expect(screen.getAllByLabelText(en.keyInput).length).toBe(2) })
+    fireEvent.click(edit)
+    expect(screen.getAllByLabelText(en.keyInput)).toHaveLength(1)
+    fireEvent.click(edit)
+    await waitFor(() => { expect(screen.getAllByLabelText(en.keyInput).length).toBe(2) })
+    fireEvent.click(screen.getAllByText(en.cancel)[1] as HTMLElement)
+    expect(screen.getAllByLabelText(en.keyInput)).toHaveLength(1)
+    expect(update).not.toHaveBeenCalled()
+  })
+
+  it('cancels the add card back to the add button', async () => {
+    await mountSection()
+    fireEvent.click(screen.getByText(`+ ${en.add}`))
+    await screen.findByLabelText(en.provider)
+    fireEvent.click(screen.getAllByText(en.cancel)[1] as HTMLElement)
+    await screen.findByText(`+ ${en.add}`)
+    expect(screen.queryByLabelText(en.provider)).toBeNull()
+  })
+
+  it('loads on first render of an idle controller', async () => {
+    const { face } = scriptedFace()
+    const controller = new ModelsSettingsStore(face as unknown as WireFace)
+    render(<ModelsSection
+      controller={controller}
+      useSnapshot={bindSnapshotSelector(controller.store)}
+      api={face as never}
+      t={t}
+    />)
+    await screen.findByText('DeepSeek')
+  })
+
+  it('removes by unsetting the profile path, never by rebuilding the section', async () => {
+    // The section rebuild is what dropped stored literal secrets: this page
+    // only ever holds the redacted descriptor, so the removal names the path.
+    const { face, mutate, replace, controller } = await mountSection()
+    await removeProviderProfile(
+      face as unknown as Parameters<typeof removeProviderProfile>[0],
+      controller,
+      { settingsNs: 'llm-plain', settingsPath: ['ghost-profile'] },
+    )
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
+      ns: 'llm-plain',
+      ops: [{ op: 'unset', path: ['ghost-profile'] }],
+    })
+    expect(replace).not.toHaveBeenCalled()
+  })
+
+  it('keeps the snapshot untouched and reports the message when a removal write is refused', async () => {
+    const { face, controller } = await mountSection({
+      mutate: vi.fn(() => Promise.resolve(fail('read-only'))),
+    })
+    const before = controller.store.getSnapshot().rows
+    const failure = await removeProviderProfile(
+      face as unknown as Parameters<typeof removeProviderProfile>[0],
+      controller,
+      { settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] },
+    )
+    expect(failure).toBe('read-only')
+    expect(controller.store.getSnapshot().rows).toBe(before)
+  })
+
+  it('shows a failed removal on the page banner, including a non-Error rejection', async () => {
+    // The whole click path: the row's Remove button, the transport rejecting
+    // with a non-Error value, and the store surfacing it where a load failure
+    // would appear — rather than the row silently staying put.
+    await mountSection({ mutate: vi.fn(() => Promise.reject(new Error('the host refused'))) })
+    fireEvent.click(screen.getAllByText(en.remove)[0] as HTMLElement)
+    await screen.findByText(`${en.loadFailed}: the host refused`)
+  })
+
+  it('reports a transport rejection instead of failing the removal silently', async () => {
+    const { face, controller } = await mountSection({
+      mutate: vi.fn(() => Promise.reject(new Error('connection lost'))),
+    })
+    const failure = await removeProviderProfile(
+      face as unknown as Parameters<typeof removeProviderProfile>[0],
+      controller,
+      { settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] },
+    )
+    expect(failure).toBe('connection lost')
+  })
+})
--- a/packages/client/ui-models/tests/invariant.spec.ts
+++ b/packages/client/ui-models/tests/invariant.spec.ts
@@ -17,7 +17,7 @@ describe('invariant companion', () => {
    expect(true).toBe(true) // reaching here without throw is the contract
  })

-  it('the section content column is intentionally empty this phase', () => {
-    expect(ModelsSection()).toBeNull()
+  it('renders null until the shell injects the section dependencies', () => {
+    expect(ModelsSection({})).toBeNull()
  })
 })
--- a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
+++ b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
@@ -0,0 +1,186 @@
+// @vitest-environment jsdom
+/** 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'
+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
+  providerActive?: boolean
+  providerSettingsNs?: string
+  settingsNamespace?: boolean
+  apiKeyEnv?: string | null
+  literal?: boolean
+  configured?: () => boolean
+  credential?: { source?: string; writable: boolean }
+  describeFailure?: string
+  settingsWritable?: boolean
+  providersReject?: boolean
+} = {}) {
+  let fileConfigured = false
+  const configured = options.configured ?? (() => fileConfigured)
+  const face = {
+    llm: {
+      providers: () => {
+        if (options.providersReject === true) {
+          return Promise.reject(new Error('provider transport unavailable'))
+        }
+        return Promise.resolve(ok({
+          providers: options.provider === false
+            ? []
+            : [{
+              provider: 'deepseek-official',
+              displayName: 'DeepSeek',
+              settingsNs: options.providerSettingsNs ?? 'llm-deepseek',
+              settingsPath: [],
+              active: options.providerActive ?? true,
+            }],
+        }))
+      },
+    },
+    settings: {
+      describe: () => Promise.resolve(ok({
+        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 }],
+            revision: 0,
+          }],
+      })),
+    },
+    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)),
+    },
+  }
+  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),
+    t: key => en[key],
+  }
+  return { controller, openSection, props, configure: () => { fileConfigured = true } }
+}
+
+describe('DeepSeekOnboardingDialog', () => {
+  it('loads on first entry and presents one accessible route to Models', async () => {
+    const h = harness()
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    expect(await screen.findByRole('dialog', { name: en.onboardingTitle })).toBeTruthy()
+    expect(screen.getByText(en.onboardingDescription)).toBeTruthy()
+    const action = screen.getByRole('button', { name: en.onboardingGoToSettings })
+    expect(action).toBeTruthy()
+    expect(document.activeElement).toBe(action)
+    expect(screen.queryByRole('textbox')).toBeNull()
+  })
+
+  it('opens the Models section and dismisses the prompt', async () => {
+    const h = harness()
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    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('allows configure-later dismissal without opening settings', async () => {
+    const h = harness()
+    render(<DeepSeekOnboardingDialog {...h.props} />)
+    await screen.findByRole('dialog')
+    fireEvent.click(screen.getByRole('button', { name: en.onboardingLater }))
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(h.openSection).not.toHaveBeenCalled()
+  })
+
+  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 }),
+      harness({ providersReject: true }),
+      harness({ providerActive: false }),
+      harness({ settingsNamespace: false }),
+      harness({ apiKeyEnv: null }),
+    ]) {
+      const view = render(<DeepSeekOnboardingDialog {...h.props} />)
+      await act(async () => { await h.controller.load() })
+      expect(screen.queryByRole('dialog')).toBeNull()
+      expect(h.openSection).not.toHaveBeenCalled()
+      view.unmount()
+    }
+  })
+
+  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 } }),
+    ]) {
+      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('stays hidden while the onboarding owner is inactive', async () => {
+    const h = harness()
+    const view = render(<DeepSeekOnboardingDialog {...h.props} active={false} />)
+    await act(async () => { await h.controller.load() })
+    expect(screen.queryByRole('dialog')).toBeNull()
+    view.rerender(<DeepSeekOnboardingDialog {...h.props} active />)
+    expect(await screen.findByRole('dialog', { name: en.onboardingTitle })).toBeTruthy()
+  })
+})
--- a/packages/client/ui-models/tests/readiness.spec.ts
+++ b/packages/client/ui-models/tests/readiness.spec.ts
@@ -0,0 +1,105 @@
+/** 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' })
+    expect(deepSeekReadiness(state({
+      rows: [row({
+        entry: {
+          ...row().entry,
+          settingsNs: '',
+        },
+      })],
+    }))).toEqual({ kind: 'adapter-absent' })
+  })
+
+  it('reports a missing writable effective credential', () => {
+    expect(deepSeekReadiness(state())).toEqual({ kind: 'credential-missing' })
+  })
+
+  it('accepts file and process-environment credentials without prompting', () => {
+    expect(deepSeekReadiness(state({
+      rows: [row({ credential: { configured: true, source: 'file', writable: true } })],
+    }))).toEqual({ kind: 'configured' })
+    expect(deepSeekReadiness(state({
+      rows: [row({ credential: { configured: true, 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' })
+  })
+
+  it('turns missing capabilities and inconsistent descriptors into diagnostics', () => {
+    expect(deepSeekReadiness(state({ status: 'error', error: 'settings down' }))).toEqual({
+      kind: 'unavailable',
+      reason: 'load-failed',
+    })
+    expect(deepSeekReadiness(state({
+      rows: [row({ entry: { ...row().entry, active: false } })],
+    }))).toEqual({ kind: 'unavailable', reason: 'provider-inactive' })
+    expect(deepSeekReadiness(state({
+      rows: [row({ configured: false })],
+    }))).toEqual({ kind: 'unavailable', reason: 'settings-unavailable' })
+    expect(deepSeekReadiness(state({
+      rows: [row({ apiKeyEnv: undefined })],
+    }))).toEqual({ kind: 'unavailable', reason: 'credential-ref-unavailable' })
+    expect(deepSeekReadiness(state({
+      credentialError: 'credentials service is absent',
+    }))).toEqual({
+      kind: 'unavailable',
+      reason: 'credentials-unavailable',
+    })
+    expect(deepSeekReadiness(state({
+      rows: [row({ credential: undefined })],
+    }))).toEqual({ kind: 'unavailable', reason: 'credentials-unavailable' })
+    expect(deepSeekReadiness(state({
+      rows: [row({ credential: { configured: false, writable: false } })],
+    }))).toEqual({ kind: 'unavailable', reason: 'credential-read-only' })
+    expect(deepSeekReadiness(state({ writable: false }))).toEqual({
+      kind: 'unavailable',
+      reason: 'settings-read-only',
+    })
+  })
+})
--- a/packages/client/ui-models/tests/store.spec.ts
+++ b/packages/client/ui-models/tests/store.spec.ts
@@ -0,0 +1,287 @@
+/** Page-store join: directory × namespaces × credentials, with last-good rows on failure. */
+import { describe, expect, it } from 'vitest'
+import type { RpcResponse } from '@deepseek-ai/dsh-client-connection/client'
+import { messageOf, ModelsSettingsStore } from '../src/client/store.ts'
+
+let nextRpc = 0
+function ok<T>(value: T): RpcResponse<T> {
+  return { rpcId: `r-${nextRpc++}` as never, result: { ok: true, value } }
+}
+function fail<T>(message: string): RpcResponse<T> {
+  return { rpcId: `r-${nextRpc++}` as never, result: { ok: false, error: { code: 'internal', message, details: {} } } }
+}
+
+const DIRECTORY = [
+  { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [], active: true },
+  { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'], active: true },
+  { provider: 'anthropic', displayName: 'anthropic', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'anthropic'], active: false },
+  { provider: 'ghost', displayName: 'Ghost', settingsNs: '', settingsPath: [], active: true },
+]
+
+const NAMESPACES = [
+  {
+    ns: 'llm-deepseek',
+    schema: {},
+    value: { apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://base' },
+    base: { baseURL: 'https://base' },
+    applies: 'live' as const,
+    secrets: [{ path: ['apiKey'], set: false }],
+    revision: 0,
+  },
+  {
+    ns: 'llm-pi-ai',
+    schema: {},
+    value: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY' } } },
+    user: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY' } } },
+    applies: 'live' as const,
+    secrets: [],
+    revision: 0,
+  },
+]
+
+function api(overrides: {
+  providers?: () => Promise<RpcResponse<{ providers: typeof DIRECTORY }>>
+  describeSettings?: () => Promise<RpcResponse<{ writable: boolean; namespaces: typeof NAMESPACES }>>
+  describeCredentials?: (refs: string[]) => Promise<RpcResponse<{ credentials: Record<string, unknown> }>>
+} = {}) {
+  const seenRefs: string[][] = []
+  const face = {
+    llm: {
+      providers: overrides.providers ?? (() => Promise.resolve(ok({ providers: DIRECTORY }))),
+      models: () => Promise.resolve(ok({ groups: [], failures: [] })),
+    },
+    settings: {
+      describe: overrides.describeSettings ?? (() => Promise.resolve(ok({ writable: true, namespaces: NAMESPACES }))),
+      update: () => Promise.resolve(fail('unused')),
+      replace: () => Promise.resolve(fail('unused')),
+    },
+    credentials: {
+      describe: (payload: { refs: string[] }) => {
+        seenRefs.push(payload.refs)
+        return (overrides.describeCredentials ?? (refs => Promise.resolve(ok({
+          credentials: Object.fromEntries(refs.map(ref => [ref, { configured: ref === 'OPENAI_API_KEY', writable: true }])),
+        }))))(payload.refs)
+      },
+      set: () => Promise.resolve(ok({})),
+      unset: () => Promise.resolve(ok({})),
+    },
+  }
+  return { face: face as never, seenRefs }
+}
+
+describe('ModelsSettingsStore', () => {
+  it('joins rows with configured, removable, and credential state', async () => {
+    const { face, seenRefs } = api()
+    const store = new ModelsSettingsStore(face)
+    await store.load()
+    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({
+      configured: true,
+      removable: false,
+      apiKeyEnv: 'DEEPSEEK_API_KEY',
+      credential: { configured: false, writable: true },
+      literalApiKeyConfigured: false,
+    })
+    expect(byProvider.get('openai')).toMatchObject({
+      configured: true,
+      removable: true,
+      apiKeyEnv: 'OPENAI_API_KEY',
+      credential: { configured: true },
+    })
+    expect(byProvider.get('anthropic')).toMatchObject({ configured: false, removable: false })
+    expect(byProvider.get('anthropic')?.apiKeyEnv).toBeUndefined()
+    expect(byProvider.get('ghost')).toMatchObject({ configured: false, removable: false })
+    expect(state.namespaces.get('llm-pi-ai')?.ns).toBe('llm-pi-ai')
+  })
+
+  it('degrades the credential badge, not the page, when the credential domain fails', async () => {
+    const { face } = api({ describeCredentials: () => Promise.resolve(fail('no provider')) })
+    const store = new ModelsSettingsStore(face)
+    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({
+      // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- the non-Error rejection is the scenario
+      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)
+    await store.load()
+    expect(store.store.getSnapshot().rows).toHaveLength(4)
+    const broken = api({ providers: () => Promise.resolve(fail('directory down')) })
+    const failing = new ModelsSettingsStore(broken.face)
+    await failing.load()
+    expect(failing.store.getSnapshot()).toMatchObject({ status: 'error', error: 'directory down' })
+    // The first store's snapshot is untouched by the second's failure.
+    expect(store.store.getSnapshot().status).toBe('ready')
+  })
+
+  it('lets the newest load win over a stale slow response', async () => {
+    let release: (() => void) | undefined
+    const gate = new Promise<void>((resolve) => { release = resolve })
+    let call = 0
+    const { face } = api({
+      providers: async () => {
+        call += 1
+        if (call === 1) {
+          await gate
+          return fail('stale slow failure')
+        }
+        return ok({ providers: DIRECTORY })
+      },
+    })
+    const store = new ModelsSettingsStore(face)
+    const first = store.load()
+    const second = store.load()
+    release?.()
+    await Promise.all([first, second])
+    expect(store.store.getSnapshot().status).toBe('ready')
+  })
+})
+
+describe('edge joins', () => {
+  it('treats a non-object profile as having no credential reference', async () => {
+    const { face } = api({
+      describeSettings: () => Promise.resolve(ok({
+        writable: true,
+        namespaces: [{
+          ns: 'llm-pi-ai',
+          schema: {},
+          value: { providers: { weird: 'oops' } },
+          applies: 'live' as const,
+          secrets: [],
+          revision: 0,
+        }] as never,
+      })),
+      providers: () => Promise.resolve(ok({
+        providers: [
+          { provider: 'weird', displayName: 'weird', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'weird'], active: false },
+        ] as never,
+      })),
+    })
+    const store = new ModelsSettingsStore(face)
+    await store.load()
+    const state = store.store.getSnapshot()
+    expect(state.rows[0]).toMatchObject({ configured: true, removable: false })
+    expect(state.rows[0]?.apiKeyEnv).toBeUndefined()
+  })
+
+  it('skips the credential describe entirely when no row names a reference', async () => {
+    const { face, seenRefs } = api({
+      describeSettings: () => Promise.resolve(ok({
+        writable: true,
+        namespaces: [{ ns: 'llm-pi-ai', schema: {}, value: { providers: {} }, applies: 'live' as const, secrets: [], revision: 0 }] as never,
+      })),
+      providers: () => Promise.resolve(ok({
+        providers: [
+          { provider: 'anthropic', displayName: 'anthropic', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'anthropic'], active: false },
+        ] as never,
+      })),
+    })
+    const store = new ModelsSettingsStore(face)
+    await store.load()
+    expect(seenRefs).toEqual([])
+    expect(store.store.getSnapshot().status).toBe('ready')
+  })
+
+  it('surfaces a settings describe failure', async () => {
+    const { face } = api({ describeSettings: () => Promise.resolve(fail('settings down')) })
+    const store = new ModelsSettingsStore(face)
+    await store.load()
+    expect(store.store.getSnapshot()).toMatchObject({ status: 'error', error: 'settings down' })
+  })
+
+  it('stringifies a non-Error load failure', async () => {
+    // The wire can surface non-Error throwables; the store must stringify them.
+    // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- the non-Error rejection is the scenario
+    const { face } = api({ providers: () => Promise.reject('plain refusal') })
+    const store = new ModelsSettingsStore(face)
+    await store.load()
+    expect(store.store.getSnapshot()).toMatchObject({ status: 'error', error: 'plain refusal' })
+  })
+
+  it('drops a stale successful response after a newer load finished', async () => {
+    let release: (() => void) | undefined
+    const gate = new Promise<void>((resolve) => { release = resolve })
+    let call = 0
+    const { face } = api({
+      providers: async () => {
+        call += 1
+        if (call === 1) {
+          await gate
+          return ok({ providers: [] as never })
+        }
+        return ok({ providers: DIRECTORY })
+      },
+    })
+    const store = new ModelsSettingsStore(face)
+    const first = store.load()
+    const second = store.load()
+    await second
+    release?.()
+    await first
+    // The stale empty directory never overwrote the newer join.
+    expect(store.store.getSnapshot().rows).toHaveLength(4)
+  })
+})
+
+describe('messageOf', () => {
+  it('reads an Error message, and stringifies anything else a rejection may carry', () => {
+    // The wire layer rejects with an Error, but a host or a runtime can reject
+    // with any value, and the page still has to render something.
+    expect(messageOf(new Error('connection lost'))).toBe('connection lost')
+    expect(messageOf('the host refused')).toBe('the host refused')
+    expect(messageOf(undefined)).toBe('undefined')
+  })
+})
--- a/packages/client/ui-models/tsconfig.json
+++ b/packages/client/ui-models/tsconfig.json
@@ -17,6 +17,18 @@
    {
      "path": "../runtime"
    },
+    {
+      "path": "../connection"
+    },
+    {
+      "path": "../schema-form"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../web-react"
+    },
    {
      "path": "../ui-settings"
    },
--- a/packages/client/ui-primitives/src/BrandWordmark.tsx
+++ b/packages/client/ui-primitives/src/BrandWordmark.tsx
@@ -1,5 +1,5 @@
 // DeepSeek Harness brand wordmark (figma 356:14644, exact extract): whale +
-// "deepseek" letterforms + HARNESS badge plate in one svg. Native 182x24.
+// "deepseek-official" letterforms + HARNESS badge plate in one svg. Native 182x24.
 // Ink rides currentColor; the badge text is knocked out in the inverted
 // label color so the plate stays legible in both themes.

--- a/packages/client/ui-primitives/src/Modal.tsx
+++ b/packages/client/ui-primitives/src/Modal.tsx
@@ -13,6 +13,7 @@ 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 (aria-label in every mode).
+ * @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).
@@ -21,10 +22,13 @@ import css from './Modal.module.css'
 * header structure; mask, card, Escape, and aria-label remain.
 * @returns null when closed; otherwise the overlay tree.
 */
-export function Modal({ open, onClose, title, description, children, footer, className, headless = false }: {
+export function Modal({
+  open, onClose, title, closeLabel = 'Close', description, children, footer, className, headless = false,
+}: {
  open: boolean
  onClose: () => void
  title: string
+  closeLabel?: string
  description?: string
  children?: ReactNode
  footer?: ReactNode
@@ -58,7 +62,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>
--- a/packages/client/ui-primitives/tests/atoms.spec.tsx
+++ b/packages/client/ui-primitives/tests/atoms.spec.tsx
@@ -324,10 +324,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()
--- a/packages/client/ui-settings/README.i18n.yaml
+++ b/packages/client/ui-settings/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-settings/README.md
-README.md: bb99f9b37927eec57650aa4025deb043b369c78e
-README.zh.md: 64b207aadfbcd7d25c005b3dcd5358013d53c173
+README.md: 9388e9dd3a984bfcebc85b6b1a35bcce4b9b116e
+README.zh.md: 57c91ac5dd0bcc0a3e5e029359bf6c3a2be58ec7
--- 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

--- 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)` 回调；后者会打开设置面板并切换到已注册的指定分区。能力就绪状态、浮层关闭、文案和变更操作均由注册方持有，因此外壳不会成为第二个配置事实来源。

 ## 模型体验

--- 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",
--- 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'
@@ -22,6 +24,8 @@ function navIcon(id: string) {
 type PanelProps = {
  rows: readonly SettingsSectionRow[]
  renderSlot: SettingsRootComponentProps['renderSlot']
+  activeId: string | undefined
+  onSelect: (id: string) => void
  onClose: () => void
 }

@@ -30,10 +34,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 +65,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 +95,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 +126,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 })}
    </>
  )
 }
--- 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>
--- 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))
--- 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 })
--- 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()
--- a/packages/client/web/package.json
+++ b/packages/client/web/package.json
@@ -21,6 +21,7 @@
  "license": "BSD-3-Clause",
  "dependencies": {
    "@deepseek-ai/dsh-client-modules": "workspace:^",
+    "@deepseek-ai/dsh-client-schema-form": "workspace:^",
    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
    "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
--- a/packages/client/web/src/platform.ts
+++ b/packages/client/web/src/platform.ts
@@ -10,6 +10,7 @@ export const PLATFORM_MODULES = [
  '@deepseek-ai/dsh-client-ui-slots',
  '@deepseek-ai/dsh-client-web-react',
  '@deepseek-ai/dsh-client-ui-primitives',
+  '@deepseek-ai/dsh-client-schema-form',
 ] as const

 /** One platform module specifier (a seed-table key). */
--- a/packages/client/web/src/seed.ts
+++ b/packages/client/web/src/seed.ts
@@ -14,6 +14,7 @@ import * as Cordis from 'cordis'
 import * as UiSlots from '@deepseek-ai/dsh-client-ui-slots'
 import * as WebReact from '@deepseek-ai/dsh-client-web-react'
 import * as UiPrimitives from '@deepseek-ai/dsh-client-ui-primitives'
+import * as SchemaForm from '@deepseek-ai/dsh-client-schema-form'
 import type { PlatformModule } from './platform.ts'

 /**
@@ -33,5 +34,6 @@ export function getStaticModules(): Record<string, unknown> {
    '@deepseek-ai/dsh-client-ui-slots': UiSlots,
    '@deepseek-ai/dsh-client-web-react': WebReact,
    '@deepseek-ai/dsh-client-ui-primitives': UiPrimitives,
+    '@deepseek-ai/dsh-client-schema-form': SchemaForm,
  } satisfies Record<PlatformModule, unknown>
 }
--- a/packages/client/web/tsconfig.json
+++ b/packages/client/web/tsconfig.json
@@ -23,6 +23,9 @@
    {
      "path": "../ui-primitives"
    },
+    {
+      "path": "../schema-form"
+    },
    {
      "path": "../web-react"
    },