@deepseek-harness-tui/dsh-tui 0.11.2 → 0.12.0

package/README.md

@@ -35,6 +35,8 @@
 - **Session workflow** — `/new` `/compact` `/export` `/btw`, model hot-switch, fork, rewind, vim, fullscreen draft editor.
 - **IDE selection channel** — a VS Code selection lands in the prompt.
 - **DSH integrations** — presets, skills, MCP, goals, todos, subagents, questionnaires.
+- **Account sign-in** — the standard profile offers pi-ai OAuth for ChatGPT/Codex, Claude, and Grok (plus OpenAI direct and Meta Muse when available), and Host-owned DeepSeek browser sign-in as `deepseek-account` on DSH 0.2.0-rc.1+. Use `/provider` or `/auth` without another plugin.
+  A profile-only update from a global TUI patch that already mounts `dsh-tui-auth` can still start the official loopback callback listener on demand; fixed-port SSH forwarding still requires the global package to be aligned.
 - **Extensions** — browser interaction, computer use and more.
 - **Built for long sessions** — event-driven projection, virtualization, bounded caches.
 
@@ -80,10 +82,13 @@ daily** (TypeScript).
 ## Quick Start
 
 Prerequisites: [Node.js](https://nodejs.org/en) and
-[deepseek-harness](https://github.com/deepseek-ai/deepseek-harness), with
-`DEEPSEEK_API_KEY` configured.
+[deepseek-harness](https://github.com/deepseek-ai/deepseek-harness).
+The `deepseek-official` API-key route needs `DEEPSEEK_API_KEY`. On DSH
+0.2.0-rc.1+, the standard profile can instead use `/auth login deepseek-account`
+and select the separate account route through `/model`. Other supported
+accounts can sign in through `/provider` or `/auth` after startup.
 
-The primary compatibility target is DSH `0.2.0-rc.1`. This adapter supports its
+The primary compatibility target is DSH `0.2.0-rc.2`. This adapter supports its
 Shell API, V4 session messages, declarative presets, and profile-backed settings;
 older supported hosts retain their compatibility paths. See [configuration](docs/configuration.en.md).
 
@@ -173,15 +178,25 @@ Incomplete records are held for a bounded recovery window (1 second from first c
 
 A session's very first record can still leave residue if it is split before its record-specific shape forms; once any record has been decoded, every split position is covered. Inside the recovery window, literal input starting with `[digit;…` cannot be told apart from a protocol prefix — it may be held, or re-joined to a preceding `Esc`. To type it, wait for the window to close, or avoid that shape right after `Esc`.
 
+Terminal replies that arrive split are reassembled the same way (native Windows ConPTY is the common source): while the app still has a query awaiting its answer, an unfinished DA1 / DA2 / DSR / DECRPM / XTVERSION tail — even one split again after the introducer `Esc` was flushed — is held across input delays, but only while its shape can still complete into the response type that query expects. It is then consumed as the reply it completes instead of entering the prompt as protocol text.
+
+That claim is evidence-gated, and this is the difference from earlier builds: no query awaiting an answer means nothing is claimed, so a literal `[?61;4c` typed right after `Esc` still enters the prompt exactly as before.
+
+The window is bounded like the record hold (about a second, never extended by later input; 64 bytes max); past either bound it ends, and bytes still shaped like an unfinished reply prefix are dropped rather than shown.
+
+Inside that window, with a query of the matching response type outstanding, same-shaped literal input can still be claimed as a reply; to type it, wait for the window to close (about a second), or avoid that shape while a query is outstanding.
+
 Mouse (fullscreen): drag to select and copy, double/triple click to select a word or line, click tool cards, timeline ticks and `[Image #N]` previews.
 
 **Pasting**: native and bracketed paste keeps ordinary text and newlines, and never submits itself on arrival. On Windows terminals that deliver a paste as win32-input-mode key records, the residue is stripped at the entry point (a multi-line paste no longer leaves stray `_`) and pasted CRLF collapses to a single newline; genuine underscores and bracketed-paste text are untouched.
 
+**Dropped files**: a native Windows desktop drop (Windows Terminal / OpenConsole) arrives as an OSC 8 hyperlink; the parser restores its `file://` URI to a decoded local path before paste hygiene runs, so the `]8;id=…;` parameter bytes never reach the draft. Image paths enter the existing image staging pipeline; other files are inserted as a referenceable path (a path containing whitespace arrives in the composer's quoted `"…"` single-token form). Only `file://` URIs are restored, and it is fail-closed: a remote authority/UNC, a payload carrying several distinct URIs, or a URI that carries several tokens is refused and stays literal text rather than guessed.
+
 Full reference: [Interaction and commands](docs/interaction.en.md).
 
 ## Built-in Commands
 
-`/resume` · `/home` · `/agentview` · `/bg` · `⌸` open the same session manager: workspace rail, live state, filter, ★ pins. Also `/model` `/new` `/compact` `/export` `/btw` `/tree` `/fork` `/rewind` `/settings` `/status` `/cost` `/jobs` `/skills` `/mcp` `/login` `/update`.
+`/resume` · `/home` · `/agentview` · `/bg` · `⌸` open the same session manager: workspace rail, live state, filter, ★ pins. Also `/model` `/new` `/compact` `/export` `/btw` `/tree` `/fork` `/rewind` `/settings` `/status` `/cost` `/jobs` `/skills` `/mcp` `/provider` `/auth` `/login` `/update`.
 
 The session manager paints the last successful list immediately while it checks the persistence store for changes. Titles that require a deeper log scan appear first with a fallback name and update in place when recovery finishes.
 
@@ -209,8 +224,9 @@ Runtime path, module boundaries, performance notes and persistence locations: [A
 - Injected plugin context has no standalone display; it counts into the context segments.
 - `/model` switches by forking the session; the old session stays in `/resume` (a session nobody has typed into records no branch, so your first prompt there still gets a generated title).
 - `Ctrl+V` needs platform clipboard tools; unsupported bitmap formats are rejected.
+- A dropped file is restored from its OSC 8 `file://` URI alone: multi-file drops, non-Windows terminal drop encodings and terminator-less truncated frames are not covered, and the hyperlink's own display name is never used.
 - A background session lives inside this process and stops when the TUI exits.
-- `/thinking` is not persisted; `/compact` is unavailable under the `minimal` preset; `/update` needs a `dsh --profile` launch and is refused while a turn is running.
+- `/thinking` is not persisted; `/compact` is unavailable under the kernel's `minimal` agent preset (极简模式, one persistent-shell tool) — a different thing from the `/settings → Minimal UI` (极简界面) display switch; `/update` needs a `dsh --profile` launch and is refused while a turn is running.
 - The status-bar `≈¥` and `/cost` are session estimates that include subagent usage (priced per each agent's model × peak/idle × cache components); unofficial or unlisted models show tokens only and are marked unpriced. **The platform bill is authoritative.**
 
 Full list: [Architecture and limitations → Known limitations](docs/architecture.en.md#known-limitations).

package/bin/dsh-tui.js

@@ -62,6 +62,16 @@ const ownPackage = readJson(join(ownDir, 'package.json'))
 const ownVersion = ownPackage?.name === '@deepseek-harness-tui/dsh-tui' ? ownPackage.version : undefined
 const PACKAGE = '@deepseek-harness-tui/dsh-tui'
 const PROFILE = 'dsh-tui'
+
+// 随包用户手册（guide/，见 scripts/build-guide.mjs）：交给 dsh 当内核
+// dsh-skill-filesystem 的随包技能根（rank 600 的 bundledSkillDir 默认取这个
+// 环境变量）。会话里模型常驻只多一行技能目录，用户真问到 dsh-tui 时才按需
+// 读手册。用户自己设过就不覆盖；包里没有 guide/（旧安装/裁剪包）时保持原样。
+const withGuideSkillDir = env => {
+  if (env.DSH_BUNDLED_SKILL_DIR !== undefined) return env
+  const guideDir = join(ownDir, 'guide')
+  return existsSync(guideDir) ? { ...env, DSH_BUNDLED_SKILL_DIR: guideDir } : env
+}
 // 救援 profile（最小可用）：同 home 下的空白 profile（仅 base+TUI，无第三方
 // 插件），是主 profile 装炸时的干净启动通道——创建走官方 dsh plugin add
 // （钉当前版本，同 bootstrap 语义）。
@@ -728,7 +738,7 @@ const startDshSession = (dshArgs, profile = PROFILE, env = process.env) =>
   new Promise(resolve => {
     const child = spawn(...cmd('dsh', ['--profile', profile, ...dshArgs]), {
       stdio: 'inherit',
-      env,
+      env: withGuideSkillDir(env),
       ...shellOpt,
     })
     child.on('error', err => resolve({ kind: 'error', error: err }))
@@ -751,6 +761,23 @@ const rescueEnv = () => {
   return env
 }
 
+// 安全模式「重试正常启动」的环境（菜单选项 1，首启 fallback 与 `safe` 共用）：
+// 崩溃往往发生在 TUI 的退出漏斗之前，此时 `~/.dsh-tui/resume.txt` 是"用户上
+// 一刻在哪个会话"的唯一线索（TUI 侧崩溃分支也会写它，见
+// src/dsh-adapter/plugin.ts 的退出漏斗）。不带这个变量重试等于开一个新的空会话
+// ——正是「会话丢了」的观感。已经显式设了该变量（用户自己 `--resume`）则不覆盖；
+// 指针缺失/不可读时保持冷启动语义。
+const resumeEnvForRetry = () => {
+  if (process.env.DSH_TUI_RESUME_SESSION !== undefined) return process.env
+  let target = ''
+  try {
+    target = readFileSync(join(homedir(), '.dsh-tui', 'resume.txt'), 'utf8').trim()
+  } catch {
+    // 没有历史会话可恢复——静默冷启动。
+  }
+  return target === '' ? process.env : { ...process.env, DSH_TUI_RESUME_SESSION: target }
+}
+
 // TTY 判定：询问与菜单都要求 stdin/stdout 均可交互（readline 需要 stdin，
 // 菜单可读需要 stdout）；任一非 TTY（脚本/管道/headless 宿主）走降级。
 const isInteractive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY)
@@ -1071,7 +1098,7 @@ const settleFirstResult = async (result, firstArgs) => {
   if (result.kind === 'error') {
     console.error(msg('launchFailed')(result.error))
     if (isInteractive()) {
-      if (await askSafeEntry(1)) process.exit(await runSafeSession({ pendingExitCode: 1, retryDsh: () => startDshSession(firstArgs) }))
+      if (await askSafeEntry(1)) process.exit(await runSafeSession({ pendingExitCode: 1, retryDsh: () => startDshSession(firstArgs, PROFILE, resumeEnvForRetry()) }))
     } else {
       console.error(msg('safeHint')(1))
     }
@@ -1082,7 +1109,7 @@ const settleFirstResult = async (result, firstArgs) => {
     console.error(msg('profileExited')(result.code))
     if (isInteractive()) {
       if (await askSafeEntry(result.code)) {
-        process.exit(await runSafeSession({ pendingExitCode: result.code, retryDsh: () => startDshSession(firstArgs) }))
+        process.exit(await runSafeSession({ pendingExitCode: result.code, retryDsh: () => startDshSession(firstArgs, PROFILE, resumeEnvForRetry()) }))
       }
     } else {
       console.error(msg('safeHint')(result.code))

package/cordis.patch.yml

@@ -409,11 +409,30 @@
       name: '@deepseek-ai/dsh-cordis-host-runner'
       disabled: !!js "[...ctx.loader.entries()].some(entry => entry.options.id === 'cordis-host-runner' && entry.options.name === '@deepseek-ai/dsh-cordis-host-runner' && !entry.disabled)"
 
-    # Subscription OAuth sign-in (bundled dsh-auth dependency): mounts the
-    # ChatGPT/Codex, Claude Pro/Max and SuperGrok provider routes plus the
-    # /auth command; the TUI's /provider wizard gains its OAuth branch from
-    # the ctx.dshAuth service this row provides. Entry-level inject only —
-    # the plugin module's own inject is empty so a stale patch cannot
+    # DeepSeek account sign-in uses the Host-owned /oauth/callback route. A
+    # TUI-only profile needs a loopback listener; a mixed Web+TUI profile
+    # reuses Web's official webserver instead of opening a second one. Hosts
+    # without an enabled account service row leave this listener disabled.
+    - id: dsh-tui-webserver
+      name: '@deepseek-ai/dsh-host-webserver'
+      disabled: !!js >-
+        (() => {
+          const require = process.getBuiltinModule('node:module').createRequire(ctx.baseUrl)
+          try { require.resolve('@deepseek-ai/dsh-host-webserver/package.json') } catch { return true }
+          const entries = [...ctx.loader.entries()]
+          return !entries.some(entry => entry.options.name === '@deepseek-ai/dsh-deepseek-account-platform' && !entry.disabled)
+            || entries.some(entry => entry.options.id === 'webserver' && entry.options.name === '@deepseek-ai/dsh-host-webserver' && !entry.disabled)
+        })()
+      config:
+        host: 127.0.0.1
+        port: 0
+
+    # Built-in subscription OAuth sign-in: mounts available pi-ai routes
+    # (ChatGPT/Codex, Claude, Grok; newer pi-ai adds OpenAI direct and Meta)
+    # plus the /auth command. Its facade also delegates DeepSeek sign-in to
+    # the Host-owned account service when available. The TUI's /provider
+    # wizard gains its OAuth branch from ctx.dshAuth. Entry-level inject only —
+    # the internal module's own inject is empty so a stale patch cannot
     # deadlock a composition lacking these services (#183 pattern).
     - id: dsh-tui-auth
       name: '@deepseek-harness-tui/dsh-tui/oauth'

package/guide/dsh-tui-guide/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: dsh-tui-guide
+description: Use when the user asks about dsh-tui itself (usage, shortcuts, config, themes, migration, VS Code). Load before answering; skip for normal coding tasks.
+---
+
+# dsh-tui 用户手册（索引）
+
+用户手册全文就在**本文件所在目录**——`skill` 工具返回的 `resourceBase`。共 8 篇，
+每篇中英各一份：中文文件名无后缀，英文加 `.en.md`。拿不到绝对路径时，用
+`glob` 在 dsh-tui 包里搜 `guide/dsh-tui-guide`。
+
+## 怎么用
+
+1. **跟用户同语言**：中文提问读无后缀文件，英文提问读加后缀的那份；回答也用同一种语言。
+2. **先定位再读**：16 个文件合计约 290 KB，整篇读既慢又挤上下文。先 `grep` 关键词拿到命中行，
+   再用 `read` 带 `offset`/`limit` 只展开需要的那几段。
+3. **一次一到两篇**：按下面的路由表挑最贴近的；跨主题时再补第二篇。
+4. **给出处**：回答末尾写清来源（文件名 + 小节标题），用户能直接翻回去核对。
+5. **别编**：手册没写的直说"手册没写"，再给保守建议；不要拿记忆里的旧行为顶替。
+
+## 路由表
+
+| 用户问的 | 文件 |
+| --- | --- |
+| 安装、首次启动、启动失败、排障 | `getting-started.md` |
+| 日常使用、键位、斜杠命令、会话与工作流、设置 | `user-guide.md` |
+| 输入框、鼠标、选中复制、粘贴、图片、问卷与审批 | `interaction.md` |
+| 配置覆盖层、TUI 开关、agent preset、模型路由、MCP | `configuration.md` |
+| 主题、配色、自动检测、自定义主题 | `themes.md` |
+| 从 Claude Code / Codex / OMP / zcode / Grok 迁移会话 | `migrate.md` |
+| VS Code 集成、扩展、IDE 选区 | `vscode.md` |
+| 插件生态、接缝稳定性分级 | `plugins.md` |
+
+英文提问时把上表文件名接上后缀（例如 `user-guide.en.md`）。
+
+> 除本文件外，这些副本由 `scripts/build-guide.mjs` 从仓库 `docs/` 逐字节同步生成，
+> 不要手改；改文档请改 `docs/` 再跑一次构建。

package/guide/dsh-tui-guide/configuration.en.md

@@ -0,0 +1,410 @@
+# Configuration
+
+[Documentation index](README.md) · [简体中文](configuration.md)
+
+## Profiles and patch layers
+
+After an npm/profile installation, user configuration lives at:
+
+```text
+$DSH_HOME/profiles/dsh-tui/cordis.patch.yml
+```
+
+When `DSH_HOME` is unset, it normally defaults to `~/.dsh`. The file is a
+top-level YAML array and may use the `!!js` expressions supported by DSH.
+
+Profile startup layers, in order:
+
+- `dsh-base`
+- Installed bundles
+- The package's `cordis.patch.yml`
+- The user patch (applied last)
+
+A user configuration normally overrides an existing row by `id`; use `insert`
+only for a genuinely new service.
+
+> When a row is overridden, its `config` block is replaced as a whole. It is
+> not deep-merged, so repeat every key that must remain active.
+
+## TUI configuration
+
+On DSH 0.1.7, `/settings` writes plugin Config fields to the active profile's
+`cordis.patch.yml`. Older hosts still use `~/.dsh/settings.yaml`; that file is
+not the new settings entry point. Language and layout preferences update live;
+fullscreen and image previews require `/restart`.
+
+A complete common override looks like this:
+
+```yaml
+- id: dsh-tui
+  config:
+    provider: deepseek-official
+    model: deepseek-flash
+    # Prefer leaving cwd unset — the default resolves to the git worktree
+    # root containing the launch directory. To pin a fixed workspace, use an
+    # absolute path (e.g. cwd: /repo/packages/app), NOT `!!js process.cwd()`
+    # (that pins the workspace to the launch subdirectory, issue #96).
+    effort: max
+    activity: true
+    activityFrames: moon8
+    contextBar: true
+    fullscreen: false
+    terminalImages: true
+    preset: !!js process.env.DSH_TUI_PRESET ?? undefined
+    workspace: !!js process.env.DSH_TUI_WORKSPACE_TARGET ?? undefined
+    sessionId: !!js process.env.DSH_TUI_RESUME_SESSION ?? undefined
+```
+
+| Field | Default/source | Meaning |
+| --- | --- | --- |
+| `provider` | Harness `agentDefaultModel`; bare compositions fall back to `deepseek-official` | DSH model route; provider and model must both be set to form an explicit route |
+| `model` | Harness `agentDefaultModel`; bare compositions fall back to `deepseek-flash` | Startup model; `/model` can switch through a session fork |
+| `cwd` | git worktree root containing the launch directory (`process.cwd()` when outside any worktree; a dotfiles repo at `$HOME` does not count) | TUI-side session workspace: agent meta, `@` completion/mention expansion, /resume filtering, statusline; resuming an existing session adopts that session's persisted cwd. Note the bash/fs-policy/sandbox roots are still owned by the composition layer's cordis config (default: the launch directory, governed by dsh-base) and may differ from this session-side cwd |
+| `workspace` | unset | Startup workspace target: a local path, `file://` URL, or plugin-provided URI; takes precedence over `cwd` |
+| `effort` | normally `max` in the bundle | Reasoning effort applied to every request (validated against the runtime model's levels; invalid levels silently fall back to the adapter default), also shown in the header at startup. Precedence: /settings `effortDefault` (`auto` defers) > this field > the persisted `/effort` choice (`~/.dsh-tui/effort.json`) > the model default |
+| `effortDefault` | unset | Default reasoning effort for new sessions; `auto` defers to `effort`; editable through `/settings` |
+| `whale` / `whaleIdle` | `true` / `true` | Header whale and welcome-page idle animation |
+| `splashFont` | `daily` | Big-text face on the header splash: `daily` rotates by local date (the default), any other value is a face id (`bold` / `square` / `bevel` / `wide` / `dot` / `stencil` / `classic` / `slab`) pinning that one; an unknown value falls back to `daily`. Also editable through `/settings` |
+| `whaleGirl` | `false` | Swap the header's pixel whale for the maid: real raster FIRST (Kitty/Sixel); falls back to the character-art maid without them |
+| `minimal` | `false` | Minimal UI (极简界面): reduce header decoration and colors. **A display switch only** — a different thing from the kernel's `minimal` agent preset under `preset` below (that one decides which tools the model can use) |
+| `modes` | built-in trio | Shift+Tab session-mode cycle (plan/sandbox/approval atom bundles); defaults to default → plan → full-access |
+| `activity` | `true` | Show the live activity row |
+| `activityFrames` | `moon8` | Activity animation preset; `/activity` changes it at runtime. A legacy saved value of `claude` is read as `moon8`, and the picker no longer offers that legacy preset |
+| `contextBar` | `true` | Segmented context-usage bar below the input box; `false` hides the row. Both this and `/settings → statusBar.contextBar` (also on by default) must be on for it to render |
+| `fullscreen` | `true` (factory default since 0.9.0) | `true` uses the alternate screen, app scrolling, and mouse selection; `false` uses inline mode |
+| `terminalImages` | `true` | Allow previews in supported terminals; `false` keeps text metadata and skips image probing and preview decoding. Restart to apply changes |
+| `preset` | roster default `standard` | Agent preset for new sessions; explicit configuration wins over persisted preference |
+| `sessionId` | unset | Session to resume, normally injected by the Windows `--resume` launcher |
+
+### Precedence and force-off
+
+- `/settings → Terminal image previews` overrides `config.terminalImages`.
+- Without a saved choice, the config value applies and defaults to on.
+- Enabling still needs Kitty graphics support and a display mode that allows
+  image rendering.
+- `DSH_TUI_DISABLE_TERMINAL_IMAGES=1` always forces previews off.
+- Disabled previews do not read or decode image data or send image rendering
+  commands; sending images to the model is unaffected.
+- The checkbox edits the preview preference; an environment override is shown
+  separately as “Image previews (forced off)” in the settings list.
+
+### Restart
+
+- This switch is read at startup.
+- Use `/restart` after changing it to restart the TUI and resume the current
+  session; `/reload` does not apply it.
+- If a turn is running, wait for it to finish or stop it with `Ctrl+C` before
+  restarting.
+
+## Diagnostic environment variables
+
+The following variables are for diagnostics or experimental terminal
+integration. They are all off by default and take effect only when explicitly
+set:
+
+| Variable | Purpose |
+| --- | --- |
+| `DSH_TUI_DEBUG_REPAINTS=1` | Record repaint diagnostics |
+| `DSH_TUI_COMMIT_LOG=1` | Record render-commit diagnostics |
+| `DSH_TUI_ACCESSIBILITY=1` | Enable accessibility related display paths |
+| `DSH_TUI_TMUX_TRUECOLOR=1` | Enable the truecolor detection path in tmux |
+| `DSH_TUI_TAB_STATUS=1` | Experimental terminal tab-status opt-in; off by default, with no guarantee of support in every terminal |
+
+Diagnostic output does not change session events or model routing. Enable
+only the variable needed for the terminal or rendering issue being
+investigated.
+
+## Live activity row
+
+`dsh-working-activity` is installed with the package and inserted by its
+patch. The working line reads the plugin's `workingActivity` session
+projection, which requires `dsh-working-activity` ≥ 0.5.0 — that release
+replaced the old `activity/status` event outlet with the projection, so
+older plugin versions produce no working line. Override only the existing
+ID when tuning it:
+
+```yaml
+- id: working-activity
+  config:
+    publishIntervalMs: 500
+```
+
+Do not insert a second row and do not separately run
+`dsh plugin ... add dsh-working-activity` for the same profile.
+
+## Agent presets
+
+Each session composes its model-visible tools and prompt through the official
+preset registry: `@deepseek-ai/dsh-agent-preset-registry` on 0.1.7, or
+`@deepseek-ai/dsh-agent-presets` on older hosts:
+
+| ID | Name | Capability |
+| --- | --- | --- |
+| `standard` | Standard (default) | Editing, shell, search, skills, planning, goals, subagents, and workflows |
+| `ptc` (0.1.2) / `code` (legacy 0.1.1) | PTC | Standard plus the PTC SDK presentation for composing operations in TypeScript; both names resolve compatibly across versions |
+| `minimal` | Minimal | Kernel agent preset: a single persistent-shell tool (bash on POSIX, pwsh on Windows), with no compaction, no plan mode and no runtime context. `str_replace_editor` has been opt-in since 0.1.3-alpha.2, so this preset does not include it |
+| `cordis` | Creation | Standard plus runtime inspection and plugin-experimentation tools |
+| `liangshen` | Liangshen mode | Minimal's minimal tool surface first for root and delegated agents, the full catalog after the first tool call, and a fresh anchor after compaction |
+
+> ⚠️ Do not confuse the 「极简模式」 (Minimal) preset here with `/settings → Appearance → 极简界面`
+> (Minimal UI, config key `dsh-tui.minimal`): the preset is a **kernel agent preset** and changes
+> which tools the model can see and call, while Minimal UI only trims interface decoration
+> (header splash, emoji glyphs, decorative colors, footer fields) and has no effect on capability.
+
+### Selecting and switching
+
+- `/preset` opens the picker.
+- `/preset <id>` selects directly; `/preset status` reports the current state.
+- Picker names and descriptions come from registry declarations (from
+  `preset.yml` on older hosts).
+- Under the `en` UI language (`/lang en`), the built-in presets show localized
+  English names and descriptions.
+- Built-in presets: `standard` / `minimal` / `ptc` (legacy `code`) / `cordis` / `liangshen`;
+  custom presets are shown as-is.
+- A blank session can switch in place. Once a conversation has started, the
+  official blank-only rule stores the choice as the new default for `/new` or
+  the next launch.
+
+### Default and precedence
+
+- The default is stored in `~/.dsh-tui/agent-preset.json`.
+- Precedence: explicit `config.preset` or `DSH_TUI_PRESET`, then persisted
+  preference, then the roster default `standard`.
+- A legacy `code` preference resolves to `ptc` when the active roster no
+  longer provides `code`, then migrates after that successful resolution;
+  rc rosters keep their real `code` id, and session logs are never rewritten.
+- Resuming a session restores the preset recorded in that session's log and
+  does not overwrite it with the current default.
+
+### Liangshen mode
+
+- Liangshen mode ships with dsh-tui. On 0.1.7 it registers with the official
+  registry; an existing profile declaration with the same id takes precedence.
+  Older hosts install it into the user preset root, preserving unmanaged directories.
+- The first-round `bash` on Windows runs an auto-discovered Git Bash, trying
+  in order:
+  - The installation tree of a `git.exe` found on PATH (covers installer,
+    portable, and Scoop layouts; Scoop shims are followed)
+  - Conventional install roots and Scoop's conventional directories
+  - Bare `bash` on PATH (final fallback)
+  - It never accepts the System32 WSL launcher as Git Bash
+- Set `DSH_TUI_LIANGSHEN_BASH_PATH` to an absolute `bash.exe` path to pin it.
+- The pin is the only candidate; a miss warns and skips registration, exposing
+  the full tool catalog on the first round.
+
+### Custom presets
+
+On 0.1.7, declare `@deepseek-ai/dsh-agent-preset` through a profile/bundle with
+`id`, `name`, and `plugins` in its config. Migrate old directory presets to
+bundles using the upstream workflow; TUI no longer scans directories itself.
+Older hosts still discover `$DSH_HOME/.agent-presets/<name>/agent.cordis.yml`.
+
+Since 0.3, model-side tools, planning, compaction, and delegation are owned by
+the preset. Profile mode no longer uses the old `DSH_TUI_COMPACT_RATIO`,
+`DSH_TUI_COMPACT_RETAIN`, or the former TUI's subagent-depth customization; configure
+those policies in the preset instead.
+
+## MCP
+
+The official `@deepseek-ai/dsh-mcp-client` supports both stdio and streamable
+HTTP. Mounted tools are registered as `mcp__<server>__<tool>` and enter the
+model tool set automatically.
+
+Insert servers in the user `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: mcp-context7
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        transport: stdio
+        serverName: context7
+        command: npx
+        args: ['-y', '@upstash/context7-mcp']
+
+    - id: mcp-remote
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        transport: streamable-http
+        serverName: remote
+        url: https://example.com/mcp
+        headers:
+          Authorization: !!js process.env.MCP_TOKEN
+```
+
+Run `/mcp` to inspect connected servers and tool counts. Consult the
+[DeepSeek Harness configuration catalog](https://deepseek-harness.github.io/deepseek-harness/reference/config-catalog#deepseek-ai-dsh-mcp-client)
+for the complete field reference.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `VISUAL` / `EDITOR` | External editor opened by `Ctrl+G` (`VISUAL` wins; arguments like `code --wait` are allowed; with neither set the TUI prompts you to configure one — no `vi` fallback) |
+| `DEEPSEEK_API_KEY` | Required DeepSeek credential |
+| `DEEPSEEK_BASE_URL` | Override the compatible DeepSeek API endpoint |
+| `DSH_HOME` | Harness home (profiles, sessions, credentials, attachments); falls back to the upstream default `~/.dsh` |
+| `DSH_TUI_PERSONA` | Override the Agent persona injected by the composition |
+| `DSH_TUI_PRESET` | Override the default Agent preset for new sessions |
+| `DSH_TUI_THEME` | Pin a built-in (`auto`/`light`/`dark`/`dark-ansi`), static theme, or registered plugin theme ahead of persisted selection |
+| `DSH_TUI_DISABLE_MOUSE` | Temporarily disable mouse handling in fullscreen mode |
+| `DSH_TUI_DISABLE_TERMINAL_IMAGES` | Set to `1` to force Kitty/Sixel probing, preview reads/decoding, and terminal image rendering off, overriding config and /settings; text metadata remains visible |
+| `DSH_TUI_IMAGE_PROTOCOL` | `auto` (default), `kitty`, `sixel`, or `none`; override protocol selection without bypassing the preview preference, disable switch, non-fullscreen, accessibility or multiplexer guards |
+| `DSH_TUI_RESUME_SESSION` | Resume a session at startup, normally set by a launcher |
+| `DSH_TUI_WORKSPACE_TARGET` | Workspace path or URI resolved at startup, normally set by `dsh-tui <target>` |
+| `DSH_TUI_SESSION_ROOT` | Override the JSONL session root; profile default `$DSH_HOME/sessions`, bare `cordis.yml` default `~/.dsh-tui/sessions` |
+| `DSH_PERMISSION_MODE` | Override non-Windows sandbox policy, such as `workspace-write` or `danger-full-access` |
+| `DSH_TUI_WORKSPACE` | Working directory used by the Windows `dsh-tui.cmd` launcher |
+| `DSH_TUI_DEBUG` | Enable dsh-tui diagnostics on stderr |
+| `DSH_TUI_RENDER_LOG` | File path for raw ANSI frame capture |
+
+The old `CC_TUI_*` and `DSH_CC_*` names come from earlier release naming and
+are no longer read as of this release; use the `DSH_TUI_*` prefix.
+
+Two directories are involved and neither substitutes for the other:
+
+- **Harness home**: `$DSH_HOME`, falling back to the upstream default `~/.dsh`.
+  Holds profiles, sessions, credentials, and attachments. Early releases pinned
+  it to `~/.dsh-cc`.
+- **TUI data directory**: `~/.dsh-tui` (a fixed path, independent of
+  `$DSH_HOME`). Holds `/model` (persisted at `~/.dsh-tui/model.json`, surviving
+  restart and `/new`), `/lang`, `/theme` and similar preferences plus
+  `resume.txt`. Early releases wrote these under `$DSH_HOME` instead.
+
+`DSH_TUI_RENDER_LOG` may capture visible prompts, tool arguments, and output.
+Do not attach it to a public issue without reviewing and redacting it.
+
+## `/provider`: manage model providers at runtime
+
+`/provider` opens an interactive wizard to add, edit, or delete model
+providers without a restart.
+
+- Sources: built-in catalog routes or custom API endpoints.
+- Only providers written by the **user settings layer** can be edited or
+  deleted; ones inherited from the composition base cannot be removed.
+- Keys are written to `~/.dsh/.credentials.yaml` (mode 0600) and render as
+  `••••••`.
+- Only non-environment keys are written to the store; a key shared with
+  another provider is kept on delete.
+- Editing the model list re-fetches the candidates: a built-in catalog route
+  starts from the installed catalog snapshot and, whenever the route stores a
+  baseURL (or the add flow just collected one), also probes
+  `GET {baseURL}/models` live with the stored key and merges the listings —
+  ids only the endpoint advertises are tagged as new and carry their
+  disclosed capacities once enabled; already-enabled models are pre-checked
+  and only an explicit un-check removes one. A catalog route without a
+  baseURL shows the snapshot only, with the origin noted in the question
+  detail. Catalog routes with no single known protocol or custom request
+  headers also explain the limitation and stay on the snapshot, rather than
+  saving endpoint-only models into an unverifiable profile.
+
+Where it writes:
+
+| Artifact | Location |
+| --- | --- |
+| Provider profile | `llm-pi-ai.providers.<route>` in the active profile config on 0.1.7, or `~/.dsh/settings.yaml` on older hosts; the route registers on write and unregisters on delete |
+| API key | `~/.dsh/.credentials.yaml` (mode 0600), referenced as `<ROUTE>_API_KEY` |
+
+### Built-in subscription OAuth
+
+The standard profile's `dsh-tui-auth` row loads this package's `./oauth`
+entry; it **no longer depends on a separate `dsh-auth` plugin package**.
+The `/provider` add branch signs in to ChatGPT/Codex (`openai-codex`), Claude
+(`anthropic`), or Grok (`xai`) subscriptions. When the installed host's pi-ai
+catalog ships the corresponding flows, it also offers OpenAI direct ChatGPT sign-in
+(`openai`, using the OpenAI API rather than the legacy Codex backend) and Meta
+Muse (`meta`). The primary validated DSH `0.2.0-rc.2` fixture carries pi-ai
+`0.87.1`, which includes Meta Muse but not OpenAI direct sign-in.
+`/auth status`, `/auth login [provider]`, and `/auth logout <provider>` use
+that credential store for these pi-ai routes. Browser authorization tries to open the page
+automatically and offers the authorization link and manual callback URL/code
+input on one question;
+device-code flows show a copyable code while polling. A host without an
+interactive question surface refuses sign-in explicitly.
+
+The `dsh-tui-auth` row accepts `providers` (default: all supported flows present
+in the installed pi-ai catalog; an explicit non-empty subset must exist in
+that catalog), `credentialsFile` (custom file path), and
+`modelOverrides.<provider>.<model>` (optional `contextWindow` and `maxTokens`).
+A profile override replaces the whole `config` block, so retain every field
+you need. The flow implementation comes from the host's `dsh-llm-pi-ai` / pi-ai
+installation. Subscription authentication uses its subscription backend; it
+is not a general-purpose API key.
+
+The default credential file remains `$DSH_HOME/dsh-auth/credentials.json`
+(`~/.dsh/dsh-auth/credentials.json` when `DSH_HOME` is unset), with
+`DSH_AUTH_CREDENTIALS` as an override. Existing sign-ins need no migration or
+re-login. The `ctx.dshAuth` service name and `dsh-auth` log prefix remain for
+compatibility; they do not imply a separate installed package. The file
+contains long-lived refresh tokens; directory/file modes are best-effort
+0700/0600. OpenAI direct login lazily creates a stable UUID in a sibling
+`device-id` file (0600); pi-ai uses it as the installation's agent-host ID.
+Status surfaces show only sign-in and expiry metadata. Models appear in the
+picker after sign-in. If another `llm-pi-ai` profile already owns the same
+provider route, the OAuth route refuses duplicate registration.
+
+### DeepSeek account authorization
+
+DSH `0.2.0-rc.1+` separately provides the Host-owned `deepseekAccount` service
+and `deepseek-account` model route. The standard profile includes it in the
+same `/provider` account sign-in branch and the `/auth status` and `/login`
+lists. You can also run `/auth login deepseek-account` directly, then select
+a `deepseek-account` model via `/model`. This is a **different route** from
+`deepseek-official`, which still needs `DEEPSEEK_API_KEY`. The command
+`/auth logout deepseek-account` delegates sign-out to the Host: it removes the Host's local
+grant, while the Host handles remote revocation in the background. The TUI
+does not implement PKCE, read the account token, or put the grant in the
+`dsh-auth/credentials.json` file above. DeepSeek account grants have no pi-ai
+token expiry/refresh timestamp, so status surfaces show only signed in/out.
+`dsh-tui-auth.config.providers` and `modelOverrides` still control pi-ai
+routes only; do not put `deepseek-account` in them.
+
+The browser callback uses the Host `webServer` service. A TUI-only profile's
+`dsh-tui-webserver` row listens on `127.0.0.1` with an OS-assigned port; a
+mixed Web+TUI profile reuses the official `webserver` row instead of opening a
+second listener. If a profile-only update leaves an older global TUI patch
+that mounts `dsh-tui-auth` but lacks `dsh-tui-webserver`, the built-in OAuth
+entry starts the same official Host listener on `127.0.0.1` at the first
+DeepSeek sign-in, using an OS-assigned port. It reuses an existing listener
+and closes only its own fallback when the OAuth module unmounts; a declared
+but disabled or failed webserver row is not bypassed. The question
+panel tries to open the authorization URL and offers the full link plus copy,
+reopen, and cancel actions. The DeepSeek flow **requires the callback**; it
+has no manual-code fallback. If a remote TUI
+uses your local browser over SSH, override `dsh-tui-webserver.port` to a fixed
+port and forward that same port (for example,
+`ssh -L 43123:127.0.0.1:43123 ...`):
+
+```yaml
+- id: dsh-tui-webserver
+  config:
+    host: 127.0.0.1
+    port: 43123
+```
+
+In a mixed Web profile, override the official `webserver` row. A stale global
+patch cannot apply a fixed-port override to a row it lacks, so SSH users must
+also update the global TUI package before forwarding a fixed port. Missing or
+unstartable callback listeners fail sign-in clearly without affecting the
+other pi-ai OAuth routes.
+
+## Composition constraints
+
+- `user-interaction` normally comes from `dsh-base`. The plugin creates a
+  fallback in a bare composition, but the profile patch must not insert a
+  duplicate.
+- When manually inserting a subagent provider, mount the core `subagent`
+  service first.
+- A custom `plan-mode` override requires a non-empty `section`.
+- Profile mode uses the base JSONL persistence row rooted at the shared
+  `~/.dsh/sessions`, allowing TUI and Web to read the same history.
+- `cordis.yml` is a bare-composition example and may have a different service
+  topology. Normal installation and user overrides should follow
+  `cordis.patch.yml`.
+
+`DSH_TUI_SESSION_ROOT` always names a JSONL root. `dsh --profile dsh-tui`
+defaults to `$DSH_HOME/sessions` (normally `~/.dsh/sessions/`); direct
+`dsh --config cordis.yml` defaults to `~/.dsh-tui/sessions/`.
+
+See [Architecture and limitations](architecture.en.md#permissions-and-security-boundary)
+for permission behavior and platform differences.