diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index 80c388280b..3b54366fab 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/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 apps/cli/README.md
-README.md: 7cde0dd8c9c6cf794cf8d1676ed6938e204117cf
-README.zh.md: 3b21d563cbd8458810cd05f1ef71bd88074f294f
+README.md: 25f201a082961db9cd4760334d2ab07a13deab89
+README.zh.md: f288bf61b77e5fe5cfdafafdc1fdfbf9f5669582
diff --git a/apps/cli/README.md b/apps/cli/README.md
index 7cde0dd8c9..25f201a082 100644
--- a/apps/cli/README.md
+++ b/apps/cli/README.md
@@ -3,7 +3,7 @@
 English | [中文](README.zh.md)
 
 
-Argv is parsed once through a [Commander](https://github.com/tj/commander.js) adapter ([`src/args.ts`](src/args.ts)): one program whose default (no subcommand) is the TUI/headless surface (`--config`, `-p`/`--prompt`, `--resume`), whose `meta` subcommand is the same TUI over this checkout, whose `upgrade` subcommands are option-less guided-session entries, and whose `web` subcommand is the browser UI. `src/bin.ts` switches on the resolved mode and dynamic-imports only that mode's module. `dsh --help` lists every mode and `dsh web --help` renders the web usage, `dsh --version` prints this app's version, and an unknown option or a mistyped `--resume` fails loud (stderr, exit 1) instead of misrouting. Every subcommand that shares no option with the default surface — `migrate`, `upgrade`, `web` — rejects a leaked `--config`/`-p`/`--resume` rather than running and dropping it. `dsh web`'s `--host`/`--port` are unvalidated pass-through overrides: the `dsh-host-webserver` schema is the single source of both the default (the shipped `cordis.yml` value when a flag is absent) and validity, and rejects a bad value at boot. `--trusted-host` appends named authorities for the /api browser-trust fence; an all-interfaces bind additionally derives the machine's LAN IP literals itself ([`src/app-cli-entry.ts`](src/app-cli-entry.ts)), so the printed LAN URL works without flags.
+Argv is parsed once through a [Commander](https://github.com/tj/commander.js) adapter ([`src/args.ts`](src/args.ts)): one program whose default (no subcommand) is the TUI/headless surface (`--config`, `-p`/`--prompt`, `--resume`), whose `meta` subcommand is the same TUI over this checkout, whose `upgrade` subcommand is an option-less guided-session entry, and whose `web` subcommand is the browser UI. `src/bin.ts` switches on the resolved mode and dynamic-imports only that mode's module. `dsh --help` lists every mode and `dsh web --help` renders the web usage, `dsh --version` prints this app's version, and an unknown option or a mistyped `--resume` fails loud (stderr, exit 1) instead of misrouting. Every subcommand that shares no option with the default surface — `upgrade`, `web`, `meta` — rejects a leaked `--config`/`-p`/`--resume` rather than running and dropping it. `dsh web`'s `--host`/`--port` are unvalidated pass-through overrides: the `dsh-host-webserver` schema is the single source of both the default (the shipped Web overlay value when a flag is absent) and validity, and rejects a bad value at boot. `--trusted-host` appends named authorities for the /api browser-trust fence; an all-interfaces bind additionally derives the machine's LAN IP literals itself ([`src/app-cli-entry.ts`](src/app-cli-entry.ts)), so the printed LAN URL works without flags.
 
 The TUI surface:
 
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 3b21d563cb..f288bf61b7 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -3,7 +3,7 @@
 [English](README.md) | 中文
 
 
-Argv 只会通过 [Commander](https://github.com/tj/commander.js) 适配器（[`src/args.ts`](src/args.ts)）解析一次：同一个程序的默认形式（无子命令）是 TUI／无头界面（`--config`、`-p`/`--prompt`、`--resume`），`meta` 子命令是以本 checkout 为 workspace 的同一个 TUI，`upgrade` 子命令是无选项的引导会话入口，`web` 子命令则是浏览器 UI。`src/bin.ts` 按解析后的 mode 分支，仅动态导入该 mode 的模块。`dsh --help` 列出所有 mode，`dsh web --help` 渲染 Web 用法，`dsh --version` 打印此应用的版本；未知选项或拼错的 `--resume` 会明确报错（stderr，退出码 1），而不会被错路由。凡与默认界面不共享任何选项的子命令（`migrate`、`upgrade`、`web`）都会拒绝泄漏进来的 `--config`/`-p`/`--resume`，而不会照常运行并丢弃它。`dsh web` 的 `--host`/`--port` 是未验证的直通覆盖：`dsh-host-webserver` schema 是默认值（标志缺失时使用已交付的 `cordis.yml` 值）和有效性的唯一真源，并在启动时拒绝错误值。`--trusted-host` 为 /api 浏览器信任栅栏追加具名权威；全接口绑定还会自行推导本机的 LAN IP 字面量（[`src/app-cli-entry.ts`](src/app-cli-entry.ts)），因此打印出的 LAN URL 无需任何标志即可使用。
+Argv 只会通过 [Commander](https://github.com/tj/commander.js) 适配器（[`src/args.ts`](src/args.ts)）解析一次：同一个程序的默认形式（无子命令）是 TUI／无头界面（`--config`、`-p`/`--prompt`、`--resume`），`meta` 子命令是以本 checkout 为 workspace 的同一个 TUI，`upgrade` 子命令是无选项的引导会话入口，`web` 子命令则是浏览器 UI。`src/bin.ts` 按解析后的 mode 分支，仅动态导入该 mode 的模块。`dsh --help` 列出所有 mode，`dsh web --help` 渲染 Web 用法，`dsh --version` 打印此应用的版本；未知选项或拼错的 `--resume` 会明确报错（stderr，退出码 1），而不会被错路由。凡与默认界面不共享任何选项的子命令（`upgrade`、`web`、`meta`）都会拒绝泄漏进来的 `--config`/`-p`/`--resume`，而不会照常运行并丢弃它。`dsh web` 的 `--host`/`--port` 是未验证的直通覆盖：`dsh-host-webserver` schema 是默认值（标志缺失时使用已交付的 Web 覆盖层值）和有效性的唯一真源，并在启动时拒绝错误值。`--trusted-host` 为 /api 浏览器信任栅栏追加具名权威；全接口绑定还会自行推导本机的 LAN IP 字面量（[`src/app-cli-entry.ts`](src/app-cli-entry.ts)），因此打印出的 LAN URL 无需任何标志即可使用。
 
 TUI 界面：
 
diff --git a/apps/cli/src/app-cli-entry.ts b/apps/cli/src/app-cli-entry.ts
index c0e67bae00..ab86f1f77f 100644
--- a/apps/cli/src/app-cli-entry.ts
+++ b/apps/cli/src/app-cli-entry.ts
@@ -1,8 +1,8 @@
 /**
  * AppCLIEntry — the pre-cordis boot glue the config-tree dsh surfaces share
- * (`dsh web` and `dsh -p` boot the one composition; TUI migrates later).
+ * for the Web/headless surface.
  * Everything here is what must exist before the Loader runs: layered env,
- * the patch composition over the shipped cordis.yml (profile json + CLI
+ * the patch composition over the shipped base and surface overlay (profile json + CLI
  * flags + the resolved frontend dist), and the fail-loud triple after the
  * tree settles.
  */
diff --git a/apps/cli/src/args.ts b/apps/cli/src/args.ts
index ca898b08ea..f5600ff610 100644
--- a/apps/cli/src/args.ts
+++ b/apps/cli/src/args.ts
@@ -49,7 +49,7 @@ interface SkillSessionInvocation {
  * passed — pass-through overrides with no CLI default and no CLI validation:
  * the `dsh-host-webserver` schema (`host` a loopback/all-interfaces literal,
  * `port` a natural ≤ 65535) is the single source of both the default (the
- * shipped `cordis.yml` value stands when a flag is absent) and validity (a bad
+ * shipped Web overlay value stands when a flag is absent) and validity (a bad
  * value fails loud at boot). `port` is `Number`-coerced only because the schema
  * wants a number, not a string. `dev` mounts the client HMR driver;
  * `workspaceRoot` is the parent directory for name-created workspaces.
@@ -185,7 +185,7 @@ Examples:
     })
 
   // Host and port name no default: the CLI passes neither through when the flag
-  // is absent, so the shipped `cordis.yml` value stands and restating it here
+  // is absent, so the shipped Web overlay value stands and restating it here
   // would duplicate a fact this file does not own.
   const web = program.command('web').description('serve the browser UI on the configured host and port')
   web
diff --git a/apps/cli/src/headless.ts b/apps/cli/src/headless.ts
index 8007b30d44..41381a3616 100644
--- a/apps/cli/src/headless.ts
+++ b/apps/cli/src/headless.ts
@@ -1,6 +1,6 @@
 /**
  * `dsh -p "task"` — headless over the one shared composition: AppCLIEntry
- * boots the same cordis.yml as `dsh web` (port 0, so parallel runs never
+ * boots the same base plus Web overlay as `dsh web` (port 0, so parallel runs never
  * collide), then in-process isomorphic injection (InProcessApiClient over
  * toFetchHandler(ctx.apiProxy), so the full carrier chain — wire
  * serialization, zod, SSE framing — really runs). The printed URL opens the
diff --git a/apps/cli/src/tui.ts b/apps/cli/src/tui.ts
index 9fcc3336d9..f1324d8b26 100644
--- a/apps/cli/src/tui.ts
+++ b/apps/cli/src/tui.ts
@@ -1,6 +1,6 @@
 /**
  * `dsh` default surface — the interactive TUI coding agent. Boots the shipped
- * tui-agent config (or the `--config` override) with the personal overlay
+ * shared base and TUI overlay, followed by either `--config` or the personal overlay
  * from the Harness home (`~/.dsh`): its `.env` fills environment gaps (precedence:
  * ambient environment, then the invoking directory's `.env`, then the personal one)
  * and its `config.yaml` patches the booted tree. The workspace is the invoking
@@ -47,9 +47,6 @@ import {
 
 const NAME = 'dsh'
 
-// Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib) sit
-// one directory under apps/cli, so the shipped default config resolves with
-// the same relative hop from either artifact.
 // The shared core every `dsh` surface mounts, and the TUI's own overlay over
 // it. Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib)
 // sit one directory under apps/cli, so each resolves with the same hop.
@@ -81,7 +78,7 @@ export function launcherSessionsRoot(): string {
 }
 
 /* v8 ignore start -- composition over the unit-tested dsh-app-boot helpers;
-   the tui-agent PTY smoke drives this path end to end, personal overlay included */
+   the CLI PTY smoke drives this path end to end, personal overlay included */
 /**
  * Run the interactive TUI with this harness checkout as the workspace
  * (`dsh meta`), whatever directory it was launched from.
diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts
index 85f79d5fc4..d6e0c159d4 100644
--- a/apps/cli/src/web.ts
+++ b/apps/cli/src/web.ts
@@ -1,7 +1,7 @@
 /**
  * `dsh web` — thin bin over the config-tree boot: run AppCLIEntry with the
  * already-parsed host/port/dev, print the URL line, wire signals. All
- * composition lives in cordis.yml; all boot glue lives in AppCLIEntry. Host and
+ * composition lives in the shared base plus Web overlay; all boot glue lives in AppCLIEntry. Host and
  * port are unvalidated pass-through overrides — the `dsh-host-webserver` schema
  * gates them at boot.
  */
@@ -20,7 +20,7 @@ const LOOPBACK_HOST = '127.0.0.1'
 
 /**
  * Serve the browser UI from the shipped config tree. `host`/`port` are passed
- * through only when the flag was given; absent, the `cordis.yml` value stands.
+ * through only when the flag was given; absent, the shipped Web overlay value stands.
  * @param host - the bind host, or `undefined` to keep the config default.
  * @param port - the listen port (`0` requests an OS-assigned port), or `undefined` to keep the config default.
  * @param dev - mount the client HMR driver and watch plugin bundles for rebuilds.
diff --git a/apps/cli/tests/args.spec.ts b/apps/cli/tests/args.spec.ts
index ccbd5fa326..6e7211694c 100644
--- a/apps/cli/tests/args.spec.ts
+++ b/apps/cli/tests/args.spec.ts
@@ -33,7 +33,7 @@ describe('parseDshArgs', () => {
     expect(parse(['meta'])).toEqual({ mode: 'meta' })
     // Credential setup is option-free: it writes the Harness-home .env, so
     // there is nothing for a flag to select.
-    // Bare `web` carries no host/port: the shipped cordis.yml owns the default.
+    // Bare `web` carries no host/port: the shipped Web overlay owns the default.
     expect(parse(['web'])).toEqual({ mode: 'web', dev: false })
     // Host/port are unvalidated pass-throughs (the webserver schema gates them
     // at boot); the adapter only coerces the port string to a number.
@@ -64,7 +64,7 @@ describe('parseDshArgs', () => {
     expect(exitCode(['web', '--resume', 's'])).toBe(1)
     expect(exitCode(['--config', 'c.yml', 'web'])).toBe(1)
     expect(exitCode(['--config-replace', 'tree.yml', 'web'])).toBe(1)
-    // Same rule for credential setup: it shares no option with the default
+    // Same rule for each subcommand that shares no option with the default
     // surface, so a leaked flag is a typo, not something to ignore.
     // `meta` fixes its own config tree and always starts fresh, so every
     // default-surface option is rejected.
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index 1ea7d9f0db..d5bcbfd378 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -16,7 +16,7 @@ import { describe, expect, it } from 'vitest'
  * node_modules, so no external consumer is assembled; missing-config fail-loud
  * and full-boot coverage for the shared dsh-app-boot glue live in cli-demo's
  * built-bin suite, and interactive TTY behavior is PTY-covered by
- * examples/tui-agent. Skips before the bin is built.
+ * apps/cli/tests. Skips before the bin is built.
  */
 
 const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
diff --git a/apps/cli/tests/sessions-root.spec.ts b/apps/cli/tests/sessions-root.spec.ts
index 8f12455f1b..cb9982615a 100644
--- a/apps/cli/tests/sessions-root.spec.ts
+++ b/apps/cli/tests/sessions-root.spec.ts
@@ -3,7 +3,7 @@
  * its opaque `SESSIONS_ROOT_KEY` boot-slot value to `DSH_HOME/sessions`. The
  * plugin side — the slot treated as opaque, explicit config winning, and a
  * project-local fallback with no globality assumption — is pinned by
- * `packages/examples/tui-demo/tests/tui-agent.spec.ts`.
+ * the former bundled TUI tests.
  */
 
 import { join, resolve } from 'node:path'
diff --git a/apps/cli/tests/tui.snapshot.ts b/apps/cli/tests/tui.snapshot.ts
index af7c027d6d..f841c817e6 100644
--- a/apps/cli/tests/tui.snapshot.ts
+++ b/apps/cli/tests/tui.snapshot.ts
@@ -53,7 +53,7 @@ interface Scenario {
   recorded: boolean
   seedWorkspace?: boolean
   /**
-   * Load the opt-in `todo_write` tool for this scenario. The shipped tui-agent
+   * Load the opt-in `todo_write` tool for this scenario. The shipped TUI
    * config omits it, so only the todo-plan scenario (the enabled-path proof)
    * mounts it; the rest cover the default, todo-free composition.
    */