@deepseek-ai/dsh-client-ui-commands 0.1.5-rc.2 → 0.1.6-alpha.1

package/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-commands/README.md
-README.md: c5f3c55c08a6df8e6c3f122d0c5e341721c2b41a
-README.zh.md: f728c03e067f74ba5142464adc17531225034aad
+README.md: f802179e08009cd4db8a3b786e52e81b26bb21da
+README.zh.md: 1dee58ab42d67a62099d57d4e631e440d3349f21

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Typing a `/` command in the composer opens the matching surface — a registered popup, a host command's input, or a direct execution — and a command line is never silently downgraded to a plain prompt. Business packages contribute command surfaces through `ctx.commandUi`: a popupSelect spec (`/model`, `/permission`) or an action (`/feedback`), registered as a command or decorating an existing host command while the host keeps its catalog row and argument claim. Space and Enter resolve the line against the session's directory: a host descriptor with `input` is `leadingInput`, a registered `CommandUiSpec` is its kind, and everything else is `execute`.
+Typing a `/` command opens a registered popup, a client action, a host command's input, or direct execution; a command line is never silently downgraded to a plain prompt. Business packages register popupSelect specs (`/model`, `/permission`) or actions through `ctx.commandUi`, or decorate existing host commands with either kind while preserving their catalog rows and argument claims. Space and Enter resolve the line against the session's directory: a host descriptor with `input` is `leadingInput`, a registered `CommandUiSpec` is `popupSelect` or `action`, and everything else is `execute`.
 
 ## Table of Contents
 
@@ -25,11 +25,15 @@ Typing a `/` command in the composer opens the matching surface — a registered
 <a id="use-this-package"></a>
 ## Use this package
 
-Mount this plugin alongside `ui-input-trigger` and `ui-conversation`; the `/` source then appears in the trigger menu, and business packages register their command surfaces through `ctx.commandUi`. Typing `/model` opens the registered popup; a host command with an argument claim opens its input or executes directly.
+Mount this plugin alongside `ui-input-trigger` and `ui-conversation`; the `/` source then appears in the trigger menu, and business packages register their command surfaces through `ctx.commandUi`. Typing `/model` opens the registered popup; a host command with an argument claim opens its input or executes directly. The composer's `+` button and a typed `/` open the same menu: an Add section (File, Goal, Plan, Feedback) and a Commands section (Compact, Permission, Model, Export) in usage order, each row with a glyph, a localized title and description, and the command name as an alias where the localized title differs from it.
 
 ### Kinds and decorations
 
-A contribution is a client-owned command — a host-name collision fails loud. A decoration adds a bare-invocation popup to an EXISTING host command: the host command keeps its catalog row, its argument claim, and its lifecycle logging, and a decorated name with no host row in the session's directory never fires. Menu queries fuzzy-match ordered, case-insensitive subsequences of command names; prefixes rank first.
+A contribution is a client-owned command; a host-name collision fails loudly. Its UI is a popupSelect spec or an action: a callback a bare invocation runs after the trigger token is consumed, without submitting a message. Business packages own their actions and availability; the composer registers File through this same API. A decoration adds a bare-invocation popup or action to an existing host command while preserving its catalog row, argument claim, and lifecycle logging; it never fires without a matching host row. Menu queries fuzzy-match ordered, case-insensitive subsequences of command names and titles, with prefixes first and no section headings.
+
+### Built-in row faces
+
+First-party command definitions carry stable `definitionId` values. The client selects their localized titles, descriptions, icons, and input spellings by identity; changing a Host description cannot change that selection. Same-name overrides without the matching identity keep their own copy and receive no first-party aliases. Chinese and English spellings resolve through the same effective Session catalog in every locale, preserving the typed spelling in the draft and submitting the registered Host name. Contributions supply their own `label`, `description`, and `icon`, read on every candidate pass. Empty-query section order follows names, with unlisted rows closing Commands.
 
 ### Attachment-carrying submissions
 
@@ -43,7 +47,7 @@ When the composer submits with images or generic files, only a host command decl
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-`src/client/contract.ts` is the fixed business contract: `CommandUiContract.register(name, spec)` and `decorate(name, spec)` are everything a business package consumes. `CommandDirectory` is the one wire-derived cache, keyed by session: ordinary sessions fetch through `command.list({sessionId})`, entries are soft-invalidated by the forwarded `commands/change` owner event and hard-invalidated by `connection/reset`, and epoch-guarded so a superseded pull can never overwrite a newer one. `matchSpace` answers synchronously from this cache only; `matchEnter` strong-waits it on the SubmitAttempt signal and rejects on warmup failure. After `command.execute` returns a matched result, the browser emits a local `command/executed` acknowledgment; other clients receive the durable command nodes through the Host event stream but never this acknowledgment. `PopupSelectController` is the headless shell state; `PopupSelectView` self-registers into `conversation.input.overlay` with per-session resolution.
+`src/client/contract.ts` defines contribution and decoration registration, plus `dismiss(name)`, which closes that command's open popups and confirmations: dismissal aborts pending option loads, prevents their late results from reopening the popup, and preserves composer drafts. `CommandDirectory` owns the per-session wire cache and resolves typed commands through `resolution.ts`; that module owns first-party identity matching and localized input spellings. `matchSpace` reads the ready cache synchronously, while `matchEnter` waits for readiness and rejects on warmup failure or cancellation. Forwarded catalog and connection events invalidate the cache. After a matched Host execution, this browser emits `command/executed`; other clients observe only the durable command events. `PopupSelectController` owns popup state, and `PopupSelectView` occupies the input overlay. `presentation.ts` owns row labels, icons, and sections; its helpers and the resolution helpers stay internal to the plugin.
 
 </details>
 
@@ -63,7 +67,7 @@ Read these pages when the command surface is not enough. They move from the comm
 <a id="model-experience"></a>
 ## Model Experience
 
-Indirectly, through the host `command.execute` RPC the dispatch paths trigger: each command handler's host package owns any model-visible effect (the `/plan` handler flips plan mode, whose owning package injects its policy section), while the command line, the detached result, and every menu and notice rendering stay client-side and never enter the session log.
+Indirectly, through the host `command.execute` RPC they trigger, each command handler's host package owns any model-visible effect (the `/plan` handler flips plan mode, whose owning package injects its policy section), while the command line, the detached result, and every menu and notice rendering stay client-side and never enter the session log.
 
 #### KV Cache effect
 
@@ -88,4 +92,4 @@ None.
 
 </details>
 
-**Runtime invariant:** No companion is published. A browser-side source over the wire command directory — it emits no cordis events and owns no cross-plugin mutable state; dispatch and cache behavior are asserted by this package's specs.
+**Runtime invariant:** No companion is published. This browser-side source uses the wire command directory; it emits no Cordis events and owns no cross-plugin mutable state. Its dispatch and cache behavior are asserted by this package's specs.

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-在 composer 中键入 `/` 命令会打开匹配的表面——已注册的弹窗、宿主命令的输入或直接执行——命令行绝不会被静默降级为普通提示词。业务包经 `ctx.commandUi` 贡献命令表面：popupSelect 贡献项（`/model`、`/permission`）或 action（`/feedback`），既可注册为命令，也可装饰既有宿主命令，宿主保留其目录行与参数声明。空格与回车对照会话目录解析命令行：带 `input` 的宿主描述符是 `leadingInput`，注册了 `CommandUiSpec` 的按其种类派发，其余全部是 `execute`。
+键入 `/` 命令会打开已注册的弹窗、运行客户端动作、进入宿主命令的输入或直接执行，命令行不会被静默降级为普通提示词。业务包通过 `ctx.commandUi` 注册 popupSelect（`/model`、`/permission`）或 action，也可用这两种方式装饰既有宿主命令，同时保留其目录行与参数声明。空格与回车根据会话目录解析命令行：带 `input` 的宿主描述符是 `leadingInput`，注册了 `CommandUiSpec` 的是 `popupSelect` 或 `action`，其余是 `execute`。
 
 ## 目录
 
@@ -25,15 +25,19 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-与 `ui-input-trigger` 及 `ui-conversation` 一起挂载本插件；`/` source 随即出现在触发菜单中，业务包经 `ctx.commandUi` 注册自己的命令表面。键入 `/model` 打开已注册的弹窗；带参数声明的宿主命令打开其输入或直接执行。
+与 `ui-input-trigger` 及 `ui-conversation` 一起挂载本插件；`/` source 随即出现在触发菜单中，业务包经 `ctx.commandUi` 注册自己的命令表面。键入 `/model` 打开已注册的弹窗；带参数声明的宿主命令打开其输入或直接执行。composer 的 `+` 按钮与键入的 `/` 打开同一个菜单：「添加」小节（文件、目标、计划、反馈）与「指令」小节（压缩、权限、模型、下载日志）按使用频次排列，每行带图标、本地化的标题与说明，本地化标题与命令名不同时还显示命令名作为别名。
 
 ### 种类与装饰
 
-贡献项是客户端自有命令——与宿主命令同名会明确报错。装饰为**已存在的**宿主命令添加裸调用弹窗：宿主命令保留其目录行、参数声明与生命周期记账，被装饰的名字在会话目录中无宿主行时永不触发。菜单查询按顺序且不区分大小写地模糊匹配命令名的子序列；前缀排名最高。
+贡献项是客户端自有命令，与宿主命令同名会明确报错。它的 UI 是 popupSelect 规格或动作：裸调用消费触发 token 后运行回调，不提交消息。业务包负责自己的动作及可用性，输入框通过同一 API 注册「文件」。装饰为已有宿主命令添加裸调用弹窗或动作，并保留其目录行、参数认领与生命周期记录；没有匹配的宿主行时不触发。菜单查询按顺序、不区分大小写地模糊匹配命令名与标题的子序列，前缀优先，不显示小节标题。
+
+### 内置行的展示面
+
+内置命令定义携带稳定的 `definitionId`。客户端按标识选择本地化标题、说明、图标和输入写法，修改宿主说明不会改变选择结果。没有匹配标识的同名覆盖保留自己的文案，也不获得内置别名。在任何界面语言下，中英文写法都通过同一个会话有效目录解析，草稿保留手输写法，提交使用宿主注册名。贡献项提供自己的 `label`、`description` 和 `icon`，每次生成候选项时读取。空查询按名称确定小节顺序，未列出的行排在「指令」末尾。
 
 ### 带附件提交
 
-composer 携带图片或通用文件提交时，只有声明了 `input.attachments` 的宿主命令继续。其余命令路径都会抛出本地化的 `attachmentsUnsupported` 拒绝，以瞬态 toast 呈现，草稿与附件卡保持原位。处理器返回错误时保留相同草稿状态供用户重试。
+composer 携带图片或通用文件提交时，只有声明了 `input.attachments` 的宿主命令继续。其余命令路径都会抛出本地化的 `attachmentsUnsupported` 拒绝，以瞬态 toast 呈现，草稿与附件卡保持原位。处理器出错时保留相同草稿状态供用户重试。
 
 -----
 
@@ -43,7 +47,7 @@ composer 携带图片或通用文件提交时，只有声明了 `input.attachmen
 <details>
 <summary>实现细节——点击展开</summary>
 
-`src/client/contract.ts` 是固定的业务约定：`CommandUiContract.register(name, spec)` 与 `decorate(name, spec)` 是业务包消费的全部内容。`CommandDirectory` 是唯一的 wire 派生缓存，以会话为 key：普通会话经 `command.list({sessionId})` 拉取；条目由转发的 `commands/change` owner 事件软失效、由 `connection/reset` 硬失效，并以 epoch 把关，被取代的旧拉取永远无法覆盖更新的结果。`matchSpace` 只凭该缓存同步应答；`matchEnter` 在 SubmitAttempt 信号上强等缓存，预热失败即拒绝。`command.execute` 返回匹配结果后，浏览器发布本地 `command/executed` 确认；其他客户端经宿主事件流收到持久命令节点，但收不到这条确认。`PopupSelectController` 是不含界面的外壳状态；`PopupSelectView` 自注册进 `conversation.input.overlay`，按会话解析。
+`src/client/contract.ts` 定义贡献项和装饰的注册接口，以及 `dismiss(name)`：它关闭该命令已打开的弹窗与确认对话框，中止待完成的选项加载，阻止晚到结果重新打开弹窗，并保留 composer 草稿。`CommandDirectory` 负责会话级协议缓存，并通过 `resolution.ts` 解析输入命令；该模块负责内置命令标识匹配和本地化输入写法。`matchSpace` 同步读取就绪缓存，`matchEnter` 等待缓存就绪，预热失败或取消时拒绝。转发的目录和连接事件使缓存失效。宿主执行匹配的命令后，本浏览器发布 `command/executed`，其他客户端只观察持久命令事件。`PopupSelectController` 负责弹窗状态，`PopupSelectView` 占据输入浮层。`presentation.ts` 负责行标题、图标和分节，展示与解析辅助函数均留在插件内部。
 
 </details>
 
@@ -52,10 +56,10 @@ composer 携带图片或通用文件提交时，只有声明了 `input.attachmen
 <a id="further-exploration"></a>
 ## 进一步探索
 
-当命令面不够用时阅读以下页面。它们从命令 API 进入触发流水线与宿主命令注册表。
+如果仅了解命令交互还不够，请阅读以下页面。它们从命令 API 进入触发流水线与宿主命令注册表。
 
 - [ui-input-trigger](../ui-input-trigger/README.zh.md)——`/` source 注册进的流水线。
-- [ui-conversation](../ui-conversation/README.zh.md)——声明输入浮层槽位并拥有 composer。
+- [ui-conversation](../ui-conversation/README.zh.md)——声明输入浮层 slot 并拥有 composer。
 - [客户端包映射](../README.zh.md)——相邻的浏览器 UI 包。
 
 -----
@@ -63,7 +67,7 @@ composer 携带图片或通用文件提交时，只有声明了 `input.attachmen
 <a id="model-experience"></a>
 ## 模型体验
 
-间接影响，经由派发路径触发的宿主 `command.execute` RPC：每个命令 handler 的宿主包拥有任何模型可见效果（`/plan` 的 handler 翻转 plan 模式，其归属包注入 policy 段），而命令行、分离结果与所有菜单和 notice 渲染都留在客户端，永不进入会话日志。
+派发路径通过其触发的宿主 `command.execute` RPC 间接影响模型：每个命令 handler 的宿主包拥有任何模型可见效果（`/plan` 的 handler 翻转 plan 模式，其归属包注入 policy 段），而命令行、分离结果与所有菜单和 notice 渲染都留在客户端，永不进入会话日志。
 
 #### KV Cache 影响
 
@@ -74,7 +78,7 @@ composer 携带图片或通用文件提交时，只有声明了 `input.attachmen
 <a id="known-limitations-and-deferred-work"></a>
 
 
-这些限制界定了当前命令表面。它们是当前包约束，不是通用命令行对比或任务积压。
+这些限制界定了当前命令交互方式。它们是当前包约束，不是通用命令行对比或任务积压。
 
 - **脱离会话后，分离结果 notice 回退到 console**——fire-and-forget 路径经 `SessionInput.notify` 把结果送到触发会话的 composer；会话销毁后，console 输出行是仅剩的呈现面。
 
@@ -88,4 +92,4 @@ composer 携带图片或通用文件提交时，只有声明了 `input.attachmen
 
 </details>
 
-**运行时不变式：** 不发布伴生入口。这是基于 wire command directory 的浏览器侧 source，不发出 Cordis 事件，也不持有跨插件可变状态；dispatch 与 cache 行为由包测试覆盖。
+**运行时不变式：** 不发布伴生入口。这是基于 wire 命令目录的浏览器侧 source，不发出 Cordis 事件，也不持有跨插件可变状态；dispatch 与 cache 行为由包测试覆盖。

package/lib/client.js

@@ -9,6 +9,118 @@ window.__ModuleLoader__.load({
 		let _deepseek_ai_dsh_client_store = require("@deepseek-ai/dsh-client-store");
 		let react_jsx_runtime = require("react/jsx-runtime");
 		let react = require("react");
+		//#region lib/types/client/locales.js
+		/**
+		* `command` namespace dictionaries: the composer menu's section headings,
+		* the client face (title, description, claim token) of the built-in Host
+		* commands whose catalog descriptors carry English text only, and the
+		* popupSelect shell's copy.
+		*/
+		/** Simplified Chinese dictionary (the key-set source of truth). */
+		const zh = {
+			"section.add": "添加",
+			"section.commands": "指令",
+			"label.goal": "目标",
+			"label.plan": "计划",
+			"label.feedback": "反馈",
+			"label.compact": "压缩",
+			"label.permission": "权限",
+			"label.export": "下载日志",
+			"description.goal": "设置或查看长期任务目标",
+			"description.plan": "进入或退出计划模式",
+			"description.feedback": "发送关于当前会话的反馈",
+			"description.compact": "压缩以上对话内容",
+			"description.permission": "切换权限预设（沙箱模式与审批策略）",
+			"description.export": "将当前会话内容导出为 ZIP",
+			"token.goal": "目标",
+			"token.plan": "计划",
+			"token.feedback": "反馈",
+			"token.compact": "压缩",
+			"token.permission": "权限",
+			"token.export": "导出",
+			"search.placeholder": "搜索…",
+			"search.aria": "筛选选项",
+			"status.loading": "正在加载选项…",
+			"status.applying": "正在应用…",
+			"status.empty": "无选项",
+			"overlay.aria": "/{command} 选项",
+			"listbox.aria": "/{command} 匹配项",
+			"notice.attachmentsUnsupported": "/{command} 不接受附件，请先移除附件"
+		};
+		/** English dictionary, checked complete against the zh key set. */
+		const en = {
+			"section.add": "Add",
+			"section.commands": "Commands",
+			"label.goal": "Goal",
+			"label.plan": "Plan",
+			"label.feedback": "Feedback",
+			"label.compact": "Compact",
+			"label.permission": "Permission",
+			"label.export": "Export",
+			"description.goal": "Set or view the goal for a long-running task",
+			"description.plan": "Enter or leave plan mode",
+			"description.feedback": "Record feedback about this session",
+			"description.compact": "Compact older conversation history",
+			"description.permission": "Switch the permission preset (sandbox mode + approval policy)",
+			"description.export": "Download this Session log as a ZIP archive",
+			"token.goal": "goal",
+			"token.plan": "plan",
+			"token.feedback": "feedback",
+			"token.compact": "compact",
+			"token.permission": "permission",
+			"token.export": "export",
+			"search.placeholder": "Search…",
+			"search.aria": "Filter options",
+			"status.loading": "Loading options…",
+			"status.applying": "Applying…",
+			"status.empty": "No options",
+			"overlay.aria": "/{command} options",
+			"listbox.aria": "/{command} matches",
+			"notice.attachmentsUnsupported": "/{command} does not accept attachments; remove them first"
+		};
+		//#endregion
+		//#region lib/types/client/resolution.js
+		const BUILTINS = {
+			goal: "@deepseek-ai/dsh-command-goal",
+			plan: "@deepseek-ai/dsh-plan-mode",
+			feedback: "@deepseek-ai/dsh-command-feedback",
+			compact: "@deepseek-ai/dsh-command-compact",
+			permission: "@deepseek-ai/dsh-permission-presets",
+			export: "@deepseek-ai/dsh-session-log-export"
+		};
+		/**
+		* Identify a first-party definition without interpreting its display copy.
+		* @param descriptor - effective Host descriptor after scoped shadowing.
+		* @returns its first-party name, or undefined for another definition.
+		*/
+		function builtinCommandName(descriptor) {
+			return Object.keys(BUILTINS).find((name) => descriptor.definitionId === BUILTINS[name]);
+		}
+		/**
+		* Select the input spelling for a menu-picked command.
+		* @param descriptor - effective Host descriptor.
+		* @param t - command-namespace translator.
+		* @returns localized spelling for a known definition, otherwise its registered name.
+		*/
+		function claimToken(descriptor, t) {
+			const name = builtinCommandName(descriptor);
+			return name === void 0 ? descriptor.name : t(`token.${name}`);
+		}
+		const TOKEN_ALIASES = new Map(Object.keys(BUILTINS).flatMap((name) => [zh[`token.${name}`], en[`token.${name}`]].map((token) => [token, name])));
+		/**
+		* Resolve typed spelling against the current Session's effective definitions.
+		* @param token - typed name without its leading slash.
+		* @param descriptors - effective descriptors in the Session's ready catalog.
+		* @returns the matching descriptor; aliases never select an unrelated scoped override.
+		*/
+		function resolveCommand(token, descriptors) {
+			const exact = descriptors.find((descriptor) => descriptor.name === token);
+			if (exact !== void 0) return exact;
+			const name = TOKEN_ALIASES.get(token);
+			if (name === void 0) return void 0;
+			return descriptors.find((descriptor) => descriptor.definitionId === BUILTINS[name]);
+		}
+		//#endregion
 		//#region lib/types/client/directory.js
 		/** One session key's cache cell. */
 		var Entry = class {
@@ -35,15 +147,15 @@ window.__ModuleLoader__.load({
 				return this.entries.get(sessionId)?.state ?? "cold";
 			}
 			/**
-			* Synchronous exact-name lookup over one session's hot snapshot.
+			* Synchronous command lookup over one Session's ready catalog; exact names precede localized aliases.
 			* @param sessionId - session key.
-			* @param name - command name without the leading slash.
+			* @param name - typed command spelling without the leading slash.
 			* @returns the descriptor, or undefined when absent or the entry is not ready.
 			*/
 			resolve(sessionId, name) {
 				const entry = this.entries.get(sessionId);
 				if (entry === void 0 || entry.state !== "ready") return void 0;
-				return entry.commands.find((c) => c.name === name);
+				return resolveCommand(name, entry.commands);
 			}
 			/** Soft invalidation (commands-changed): background repull on every touched key; ready snapshots keep serving. */
 			invalidateAll() {
@@ -159,43 +271,6 @@ window.__ModuleLoader__.load({
 			return signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("command directory wait aborted");
 		}
 		//#endregion
-		//#region lib/types/client/locales.js
-		/** `command` namespace dictionaries (the popupSelect shell's copy). */
-		/** Simplified Chinese dictionary (the key-set source of truth). */
-		const zh = {
-			"description.compact": "压缩以上对话内容",
-			"description.export": "将当前会话内容导出为 ZIP",
-			"description.feedback": "发送关于当前会话的反馈",
-			"description.goal": "设置或查看长期任务目标",
-			"description.permission": "切换权限预设（沙箱模式与审批策略）",
-			"description.plan": "进入或退出计划模式",
-			"search.placeholder": "搜索…",
-			"search.aria": "筛选选项",
-			"status.loading": "正在加载选项…",
-			"status.applying": "正在应用…",
-			"status.empty": "无选项",
-			"overlay.aria": "/{command} 选项",
-			"listbox.aria": "/{command} 匹配项",
-			"notice.attachmentsUnsupported": "/{command} 不接受附件，请先移除附件"
-		};
-		/** English dictionary, checked complete against the zh key set. */
-		const en = {
-			"description.compact": "Compact older conversation history",
-			"description.export": "Download this Session log as a ZIP archive",
-			"description.feedback": "record feedback about this session",
-			"description.goal": "set or view the goal for a long-running task",
-			"description.permission": "Switch the permission preset (sandbox mode + approval policy)",
-			"description.plan": "Enter or leave plan mode",
-			"search.placeholder": "Search…",
-			"search.aria": "Filter options",
-			"status.loading": "Loading options…",
-			"status.applying": "Applying…",
-			"status.empty": "No options",
-			"overlay.aria": "/{command} options",
-			"listbox.aria": "/{command} matches",
-			"notice.attachmentsUnsupported": "/{command} does not accept attachments; remove them first"
-		};
-		//#endregion
 		//#region lib/types/client/popup.js
 		/**
 		* Headless popupSelect shell state: one controller per client
@@ -464,15 +539,92 @@ window.__ModuleLoader__.load({
 			}
 		};
 		//#endregion
+		//#region lib/types/client/presentation.js
+		/** Row names per section, highest usage first; rows outside both lists close the Commands section in catalog order. */
+		const SECTION_ROWS = {
+			add: [
+				"file",
+				"goal",
+				"plan",
+				"feedback"
+			],
+			commands: [
+				"compact",
+				"permission",
+				"model",
+				"export"
+			]
+		};
+		/** One built-in Host command's face, keyed by its dictionary entries. */
+		function hostFace(name, icon) {
+			return [name, {
+				label: `label.${name}`,
+				description: `description.${name}`,
+				icon
+			}];
+		}
+		/** Built-in Host commands whose client face this package owns. */
+		const HOST_FACES = new Map([
+			hostFace("goal", _deepseek_ai_dsh_client_ui_primitives.IconGoalOutline16),
+			hostFace("plan", _deepseek_ai_dsh_client_ui_primitives.IconPlanOutline14),
+			hostFace("feedback", _deepseek_ai_dsh_client_ui_primitives.IconPaperPlaneOutline14),
+			hostFace("compact", _deepseek_ai_dsh_client_ui_primitives.IconCompactOutline16),
+			hostFace("permission", _deepseek_ai_dsh_client_ui_primitives.IconShieldOutline16),
+			hostFace("export", _deepseek_ai_dsh_client_ui_primitives.IconDownloadOutline16)
+		]);
+		/**
+		* The localized menu face of a catalog row.
+		* @param descriptor - effective Host command descriptor.
+		* @param t - the `command` namespace translator.
+		* @returns title, description, and glyph for a built-in command; undefined
+		* for any other row, which keeps its catalog description.
+		*/
+		function builtinRowFace(descriptor, t) {
+			const name = builtinCommandName(descriptor);
+			const face = name === void 0 ? void 0 : HOST_FACES.get(name);
+			return face === void 0 ? void 0 : {
+				label: t(face.label),
+				description: t(face.description),
+				icon: face.icon
+			};
+		}
+		/**
+		* Arrange the empty-query menu: the Add section, then the Commands section,
+		* each in usage order, with unlisted rows closing Commands in their input
+		* order; each row carries its section heading.
+		* @param rows - the visible candidates in catalog-then-contribution order.
+		* @param t - the `command` namespace translator.
+		* @returns the sectioned rows.
+		*/
+		function sectionRows(rows, t) {
+			const listed = new Set([...SECTION_ROWS.add, ...SECTION_ROWS.commands]);
+			const byName = new Map(rows.map((row) => [row.name, row]));
+			const pick = (names) => names.flatMap((name) => {
+				const row = byName.get(name);
+				return row === void 0 ? [] : [row];
+			});
+			const add = pick(SECTION_ROWS.add).map((row) => ({
+				...row,
+				section: t("section.add")
+			}));
+			const commands = [...pick(SECTION_ROWS.commands), ...rows.filter((row) => !listed.has(row.name))].map((row) => ({
+				...row,
+				section: t("section.commands")
+			}));
+			return [...add, ...commands];
+		}
+		//#endregion
 		//#region lib/types/client/service.js
 		/**
 		* CommandUiRuntime (`ctx.commandUi`): the '/' command source over the
 		* session-keyed directory, the client-contribution registry, and the
 		* per-session popupSelect controllers. Candidate synthesis merges the host
-		* catalog with contributions by availability, then position filtering and
-		* the `/` menu's shared name ranking (ui-primitives `rankByName`); a
-		* host/contribution name collision fails loud. Every execute
-		* addresses the session's agent by sessionId — sessions are always
+		* catalog with contributions by availability, gives built-in Host rows their
+		* localized face (presentation.ts), then position-filters; an empty query
+		* lists the Add and Commands sections in usage order, a typed query ranks
+		* every row by the `/` menu's shared name-and-label ranking (ui-primitives
+		* `rankByName`). A host/contribution name collision fails loud. Every
+		* execute addresses the session's agent by sessionId — sessions are always
 		* agent-backed.
 		*/
 		/** Recover the command name from a line the Host confirmed as executed. */
@@ -481,15 +633,6 @@ window.__ModuleLoader__.load({
 			const separator = trimmed.search(/\s/u);
 			return (separator === -1 ? trimmed : trimmed.slice(0, separator)).slice(1);
 		}
-		/** Locale keys for the canonical first-party Host command descriptions. */
-		const HOST_DESCRIPTION_KEYS = new Map([
-			["compact", "description.compact"],
-			["export", "description.export"],
-			["feedback", "description.feedback"],
-			["goal", "description.goal"],
-			["permission", "description.permission"],
-			["plan", "description.plan"]
-		]);
 		/** Command surface: session-keyed directory + '/' source + contribution registry + per-session popups. */
 		var CommandUiRuntime = class extends _deepseek_ai_cordis.Service {
 			static inject = [
@@ -583,6 +726,14 @@ window.__ModuleLoader__.load({
 				};
 			}
 			/**
+			* Close every open popup for a command whose options have become stale.
+			* Pending loads and confirmations lose their binding; drafts stay intact.
+			* @param name - command name without the leading slash.
+			*/
+			dismiss(name) {
+				for (const popup of this.live.popups.values()) if (popup.state.getSnapshot().command === name) popup.dismiss();
+			}
+			/**
 			* Resolve the per-session popup controller (lazy; dies with the session
 			* scope). The controller's consume callback dispatches the scoped
 			* consume-token event back to this session; focusComposer reaches the
@@ -630,7 +781,11 @@ window.__ModuleLoader__.load({
 					if (this.focusHooks.get(id) === focus) this.focusHooks.delete(id);
 				};
 			}
-			/** Menu candidates: host catalog + contribution availability, then position filtering and the shared name ranking. */
+			/**
+			* Menu candidates: host catalog + contribution availability, built-in rows
+			* localized, then position filtering; sections for an empty query, the
+			* shared name-and-label ranking for a typed one.
+			*/
 			async candidates(session, req) {
 				const list = await this.directory.ensureReady(session.sessionId, req.signal);
 				const rows = [];
@@ -639,7 +794,7 @@ window.__ModuleLoader__.load({
 					seen.add(c.name);
 					rows.push({
 						name: c.name,
-						description: this.hostDescription(c),
+						...builtinRowFace(c, this.t) ?? { description: c.description },
 						...c.input !== void 0 ? { hint: c.input.hint } : {}
 					});
 				}
@@ -648,15 +803,13 @@ window.__ModuleLoader__.load({
 					if (seen.has(contribution.name)) throw new Error(`ui-commands: contribution /${contribution.name} collides with a host command`);
 					rows.push({
 						name: contribution.name,
-						description: contribution.description()
+						...contribution.label === void 0 ? {} : { label: contribution.label() },
+						...contribution.description === void 0 ? {} : { description: contribution.description() },
+						...contribution.icon === void 0 ? {} : { icon: contribution.icon }
 					});
 				}
-				return (0, _deepseek_ai_dsh_client_ui_primitives.rankByName)(rows.filter((c) => req.position === "leading" || c.hint === void 0), req.query);
-			}
-			/** Translate exact built-in Host copy while preserving scoped or third-party descriptors verbatim. */
-			hostDescription(command) {
-				const key = HOST_DESCRIPTION_KEYS.get(command.name);
-				return key !== void 0 && command.description === en[key] ? this.t(key) : command.description;
+				const visible = rows.filter((c) => req.position === "leading" || c.hint === void 0);
+				return req.query === "" ? sectionRows(visible, this.t) : (0, _deepseek_ai_dsh_client_ui_primitives.rankByName)(visible, req.query);
 			}
 			/** Decision table, menu column: contribution/decorated-host → popup or action; host input → claim; host bare → detached execute. */
 			dispatch(pick) {
@@ -679,7 +832,7 @@ window.__ModuleLoader__.load({
 					});
 					return "handled";
 				}
-				if (desc.input !== void 0) return { claim: this.leadingClaim(desc, pick.session) };
+				if (desc.input !== void 0) return { claim: this.leadingClaim(desc, pick.session, claimToken(desc, this.t)) };
 				this.consumeVia(pick.session.sessionId, {
 					via: "menu",
 					span: pick.span
@@ -690,11 +843,10 @@ window.__ModuleLoader__.load({
 			/** Decision table, space column: hot-key sync check; only host leadingInput claims. */
 			matchSpace(session, token) {
 				if (!token.startsWith("/")) return void 0;
-				const name = token.slice(1);
-				if (this.live.contributions.has(name)) return void 0;
-				const desc = this.directory.resolve(session.sessionId, name);
+				if (this.live.contributions.has(token.slice(1))) return void 0;
+				const desc = this.directory.resolve(session.sessionId, token.slice(1));
 				if (desc === void 0 || desc.input === void 0) return void 0;
-				return { claim: this.leadingClaim(desc, session) };
+				return { claim: this.leadingClaim(desc, session, token.slice(1)) };
 			}
 			/**
 			* Decision table, enter column. Strong-waits the session's catalog (a
@@ -708,6 +860,9 @@ window.__ModuleLoader__.load({
 			* refusal so the machine surfaces one composer notice and the draft and
 			* attachments stay in place; nothing executes and nothing is dropped. An
 			* action submits nothing and runs regardless.
+			*
+			* A typed token is resolved through the localized claim tokens, so a line
+			* written as `/计划` reaches the `plan` descriptor and executes as `/plan`.
 			*/
 			async matchEnter(session, line, signal, envelope) {
 				const trimmed = line.trim();
@@ -715,24 +870,26 @@ window.__ModuleLoader__.load({
 				const ws = trimmed.search(/\s/);
 				const token = ws === -1 ? trimmed : trimmed.slice(0, ws);
 				const bare = ws === -1;
-				const name = token.slice(1);
-				if (name === "") return void 0;
+				const typedName = token.slice(1);
+				if (typedName === "") return void 0;
 				const refuseAttachments = () => {
-					throw new Error(this.t("notice.attachmentsUnsupported", { command: name }));
+					throw new Error(this.t("notice.attachmentsUnsupported", { command: typedName }));
 				};
-				const contribution = this.live.contributions.get(name);
+				const contribution = this.live.contributions.get(typedName);
 				if (contribution !== void 0 && contribution.available(session)) {
 					if (!bare) return void 0;
 					if (envelope.attachments > 0 && contribution.ui.kind !== "action") refuseAttachments();
-					this.invoke(name, contribution.ui, session, {
+					this.invoke(typedName, contribution.ui, session, {
 						via: "enter",
 						token
 					});
 					return "handled";
 				}
 				await this.directory.ensureReady(session.sessionId, signal);
-				const desc = this.directory.resolve(session.sessionId, name);
+				const desc = this.directory.resolve(session.sessionId, typedName);
 				if (desc === void 0) return void 0;
+				const name = desc.name;
+				const canonical = `/${name}${trimmed.slice(token.length)}`;
 				if (bare) {
 					const decoration = this.live.decorations.get(name);
 					if (decoration !== void 0 && decoration.available(session)) {
@@ -746,7 +903,7 @@ window.__ModuleLoader__.load({
 				}
 				if (desc.input !== void 0) {
 					if (envelope.attachments > 0 && desc.input.attachments !== true) refuseAttachments();
-					return { claim: this.leadingClaim(desc, session) };
+					return { claim: this.leadingClaim(desc, session, token.slice(1)) };
 				}
 				if (!bare) return void 0;
 				if (envelope.attachments > 0) refuseAttachments();
@@ -754,7 +911,7 @@ window.__ModuleLoader__.load({
 					via: "enter",
 					token
 				});
-				this.runDetached(desc, session, trimmed);
+				this.runDetached(desc, session, canonical);
 				return "handled";
 			}
 			/**
@@ -771,14 +928,22 @@ window.__ModuleLoader__.load({
 				if (actx === void 0) return;
 				this.popupFor(actx).open(name, ui, session, segment);
 			}
-			/** Build the leadingInput claim: token `/name ` + the command.execute submit transaction. */
-			leadingClaim(desc, session) {
-				const token = `/${desc.name} `;
+			/**
+			* Build the leadingInput claim. The composer keeps the claimed token in
+			* the draft and reads the arguments after it, so the token is the spelling
+			* the draft will carry: the locale's token for a menu pick, the typed
+			* spelling for Space and Enter. The command.execute submit transaction
+			* always sends the catalog name.
+			*/
+			leadingClaim(desc, session, shown) {
+				const token = `/${shown} `;
+				const line = `/${desc.name} `;
 				return {
+					name: desc.name,
 					token,
 					...desc.input !== void 0 ? { hint: desc.input.hint } : {},
 					...desc.input?.attachments === true ? { attachments: true } : {},
-					submit: (args, _actx, attachments) => this.execute(session, token + args, attachments)
+					submit: (args, _actx, attachments) => this.execute(session, line + args, attachments)
 				};
 			}
 			/**
@@ -890,7 +1055,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region \0dsh-css:/home/runner/work/deepseek-harness/deepseek-harness/packages/client/ui-commands/src/client/PopupSelectView.module.css.mjs
-		const css = ".mufS8W_card{z-index:100;--dsh-scrollbar-thumb:var(--dsw-alias-scrollbar-bg-l2);--dsh-scrollbar-thumb-hover:var(--dsw-alias-scrollbar-hover-l2);background:var(--dsw-specific-menu);--dsw-elevation-stroke-color:var(--dsw-alias-border-l1);min-width:min(220px,100%);max-width:100%;max-height:320px;box-shadow:var(--dsw-elevation-prominent);border:0;border-radius:20px;outline:none;flex-direction:column;padding:4px;display:flex;position:absolute;bottom:calc(100% + 4px);left:0;overflow:hidden}.mufS8W_viewport{flex-direction:column;min-height:0;display:flex;overflow-y:auto}.mufS8W_row{cursor:pointer;color:var(--dsw-alias-label-primary);border-radius:8px;align-items:center;gap:8px;padding:6px 8px;font-size:13px;display:flex}.mufS8W_rowActive{background:var(--dsw-alias-interactive-bg-hover)}.mufS8W_label{white-space:nowrap;text-overflow:ellipsis;flex:auto;min-width:0;overflow:hidden}.mufS8W_detail{color:var(--dsw-alias-label-tertiary);white-space:nowrap;text-overflow:ellipsis;font-size:12px;overflow:hidden}.mufS8W_check{color:var(--dsw-alias-label-primary);flex:none;display:inline-flex}.mufS8W_status{color:var(--dsw-alias-label-tertiary);padding:8px 10px;font-size:13px}.mufS8W_search{border:.5px solid var(--dsw-alias-border-inverted);color:var(--dsw-alias-label-primary);background:0 0;border-radius:8px;outline:none;margin:2px 2px 4px;padding:6px 8px;font-size:13px}.mufS8W_error{color:var(--dsw-alias-state-error-primary);align-items:center;gap:8px;padding:6px 8px;font-size:12px;display:flex}.mufS8W_errorText{text-overflow:ellipsis;flex:1;overflow:hidden}.mufS8W_retry{border:.5px solid var(--dsw-alias-border-inverted);color:var(--dsw-alias-label-primary);cursor:pointer;background:0 0;border-radius:6px;padding:2px 8px;font-size:12px}";
+		const css = ".mufS8W_card{z-index:100;--dsh-scrollbar-thumb:var(--dsw-alias-scrollbar-bg-l2);--dsh-scrollbar-thumb-hover:var(--dsw-alias-scrollbar-hover-l2);background:var(--dsw-specific-menu);--dsw-elevation-stroke-color:var(--dsw-alias-border-l1);min-width:min(220px,100%);max-width:100%;max-height:320px;box-shadow:var(--dsw-elevation-prominent);border:0;border-radius:20px;outline:none;flex-direction:column;padding:4px;display:flex;position:absolute;bottom:calc(100% + 4px);left:0;overflow:hidden}.mufS8W_viewport{flex-direction:column;min-height:0;display:flex;overflow-y:auto}.mufS8W_row{cursor:pointer;color:var(--dsw-alias-label-primary);border-radius:8px;align-items:center;gap:8px;padding:6px 8px;font-size:13px;display:flex}.mufS8W_rowActive{background:var(--dsw-alias-interactive-bg-hover)}.mufS8W_label{flex:0 auto;align-items:baseline;gap:4px;min-width:0;display:flex}.mufS8W_labelText{white-space:nowrap;text-overflow:ellipsis;min-width:0;overflow:hidden}.mufS8W_badge{color:var(--dsw-alias-label-tertiary);letter-spacing:.2px;flex:none;align-self:flex-start;margin-top:-1px;font-size:8px;font-weight:600;line-height:10px}.mufS8W_detail{min-width:0;color:var(--dsw-alias-label-tertiary);white-space:nowrap;text-overflow:ellipsis;flex:1;font-size:12px;overflow:hidden}.mufS8W_check{color:var(--dsw-alias-label-primary);flex:none;margin-left:auto;display:inline-flex}.mufS8W_status{color:var(--dsw-alias-label-tertiary);padding:8px 10px;font-size:13px}.mufS8W_search{border:.5px solid var(--dsw-alias-border-inverted);color:var(--dsw-alias-label-primary);background:0 0;border-radius:8px;outline:none;margin:2px 2px 4px;padding:6px 8px;font-size:13px}.mufS8W_error{color:var(--dsw-alias-state-error-primary);align-items:center;gap:8px;padding:6px 8px;font-size:12px;display:flex}.mufS8W_errorText{text-overflow:ellipsis;flex:1;overflow:hidden}.mufS8W_retry{border:.5px solid var(--dsw-alias-border-inverted);color:var(--dsw-alias-label-primary);cursor:pointer;background:0 0;border-radius:6px;padding:2px 8px;font-size:12px}";
 		const tagId = "@deepseek-ai/dsh-client-ui-commands/PopupSelectView.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
 			const tag = document.createElement("style");
@@ -900,12 +1065,14 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var PopupSelectView_module_css_default = {
+			"badge": "mufS8W_badge",
 			"card": "mufS8W_card",
 			"check": "mufS8W_check",
 			"detail": "mufS8W_detail",
 			"error": "mufS8W_error",
 			"errorText": "mufS8W_errorText",
 			"label": "mufS8W_label",
+			"labelText": "mufS8W_labelText",
 			"retry": "mufS8W_retry",
 			"row": "mufS8W_row",
 			"rowActive": "mufS8W_rowActive",
@@ -1038,6 +1205,7 @@ window.__ModuleLoader__.load({
 						children: rows.map((option, index) => (0, react_jsx_runtime.jsxs)("div", {
 							role: "option",
 							"aria-selected": index === state.active,
+							"aria-label": option.badge === void 0 ? void 0 : `${option.label} ${option.badge}`,
 							className: clsx(PopupSelectView_module_css_default.row, index === state.active && PopupSelectView_module_css_default.rowActive),
 							onClick: () => {
 								popup.select(index);
@@ -1046,9 +1214,15 @@ window.__ModuleLoader__.load({
 								popup.highlight(index);
 							},
 							children: [
-								(0, react_jsx_runtime.jsx)("span", {
+								(0, react_jsx_runtime.jsxs)("span", {
 									className: PopupSelectView_module_css_default.label,
-									children: option.label
+									children: [(0, react_jsx_runtime.jsx)("span", {
+										className: PopupSelectView_module_css_default.labelText,
+										children: option.label
+									}), option.badge !== void 0 && (0, react_jsx_runtime.jsx)("sup", {
+										className: PopupSelectView_module_css_default.badge,
+										children: option.badge
+									})]
 								}),
 								option.detail !== void 0 && (0, react_jsx_runtime.jsx)("span", {
 									className: PopupSelectView_module_css_default.detail,
@@ -1095,8 +1269,7 @@ window.__ModuleLoader__.load({
 			"locale"
 		];
 		/**
-		* Client plugin body: mount the service, then register the popupSelect shell
-		* into the input overlay once its declarer is up.
+		* Mount the command service and its per-session popupSelect overlay.
 		* @param ctx - client root context.
 		*/
 		function apply(ctx) {

package/lib/types/client/contract.d.ts

@@ -1,10 +1,12 @@
 /**
  * Frozen contract of the client command surface. Types only. The
  * CommandUiRuntime (`ctx.commandUi`) implements this face; business packages
- * consume `register` alone.
+ * consume its registration and dismissal operations.
  */
+import type { ComponentType } from 'react';
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
 import type { ClientSessionContext } from '@deepseek-ai/dsh-client-ui-input-trigger/client';
+import type { IconProps } from '@deepseek-ai/dsh-client-ui-primitives';
 /** Copy for an option that must be acknowledged before onSelect can run. */
 export interface SelectConfirmation {
     readonly title: string;
@@ -17,6 +19,8 @@ export interface SelectConfirmation {
 export interface SelectOption {
     readonly id: string;
     readonly label: string;
+    /** Optional short marker rendered as a superscript beside the label. */
+    readonly badge?: string;
     readonly detail?: string;
     readonly active?: boolean;
     /** Optional in-page risk gate owned by the shared popup shell. */
@@ -35,8 +39,7 @@ export interface PopupSelectSpec {
 }
 /**
  * Business registration for the action command kind: a bare invocation
- * consumes the trigger token and runs one client-side callback (the Feedback
- * row opens the feedback dialog). It submits nothing, so an
+ * consumes the trigger token and runs one client-side callback. It submits nothing, so an
  * attachment-carrying draft never refuses it.
  */
 export interface ActionSpec {
@@ -53,13 +56,18 @@ export type CommandUiSpec = PopupSelectSpec | ActionSpec;
  * One client-owned command contribution: a slash-menu entry whose behavior
  * lives entirely on the client (no host descriptor). Merged with the host
  * catalog by name — a collision with a host command fails loud at candidate
- * synthesis, never shadows.
+ * synthesis, never shadows. Row copy is read on every candidate pass, so a
+ * locale change reaches the next menu open without re-registration.
  */
 export interface CommandContribution {
     /** Command name without the leading slash (unique across contributions). */
     readonly name: string;
-    /** Resolve the localized menu row description when candidates are requested. */
-    readonly description: () => string;
+    /** Localized menu row title; the name itself when absent. */
+    label?(): string;
+    /** Localized menu row description; the row shows none when absent. */
+    description?(): string;
+    /** Menu row glyph from the shared icon set. */
+    readonly icon?: ComponentType<IconProps>;
     /** Capability filter, called with a fresh projection per candidate pass. */
     available(session: ClientSessionContext): boolean;
     /** The command's UI behavior. */
@@ -94,6 +102,8 @@ export interface CommandUiContract {
      * Duplicate names throw at registration.
      */
     decorate(decoration: CommandDecoration): () => void;
+    /** Close this command's open popups and confirmations without consuming composer drafts. */
+    dismiss(name: string): void;
     /** Resolve the per-session popup controller for one session scope (wiring/overlay layer). */
     popupFor(actx: ClientContext): unknown;
 }

package/lib/types/client/directory.d.ts

@@ -28,9 +28,9 @@ export declare class CommandDirectory {
      */
     status(sessionId: SessionId): DirectoryStatus;
     /**
-     * Synchronous exact-name lookup over one session's hot snapshot.
+     * Synchronous command lookup over one Session's ready catalog; exact names precede localized aliases.
      * @param sessionId - session key.
-     * @param name - command name without the leading slash.
+     * @param name - typed command spelling without the leading slash.
      * @returns the descriptor, or undefined when absent or the entry is not ready.
      */
     resolve(sessionId: SessionId, name: string): CommandDescriptor | undefined;

package/lib/types/client/index.d.ts

@@ -23,15 +23,14 @@ declare module '@deepseek-ai/cordis' {
 }
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
-        /** The popupSelect shell's copy. */
+        /** The menu rows' and the popupSelect shell's copy. */
         command: CommandKey;
     }
 }
 /** Required services: the '/' source registry, session scopes, commands Remote, and locale registry. */
 export declare const inject: string[];
 /**
- * Client plugin body: mount the service, then register the popupSelect shell
- * into the input overlay once its declarer is up.
+ * Mount the command service and its per-session popupSelect overlay.
  * @param ctx - client root context.
  */
 export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -1,12 +1,31 @@
-/** `command` namespace dictionaries (the popupSelect shell's copy). */
+/**
+ * `command` namespace dictionaries: the composer menu's section headings,
+ * the client face (title, description, claim token) of the built-in Host
+ * commands whose catalog descriptors carry English text only, and the
+ * popupSelect shell's copy.
+ */
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export declare const zh: {
-    'description.compact': string;
-    'description.export': string;
-    'description.feedback': string;
+    'section.add': string;
+    'section.commands': string;
+    'label.goal': string;
+    'label.plan': string;
+    'label.feedback': string;
+    'label.compact': string;
+    'label.permission': string;
+    'label.export': string;
     'description.goal': string;
-    'description.permission': string;
     'description.plan': string;
+    'description.feedback': string;
+    'description.compact': string;
+    'description.permission': string;
+    'description.export': string;
+    'token.goal': string;
+    'token.plan': string;
+    'token.feedback': string;
+    'token.compact': string;
+    'token.permission': string;
+    'token.export': string;
     'search.placeholder': string;
     'search.aria': string;
     'status.loading': string;
@@ -20,12 +39,26 @@ export declare const zh: {
 export type CommandKey = keyof typeof zh;
 /** English dictionary, checked complete against the zh key set. */
 export declare const en: {
-    'description.compact': string;
-    'description.export': string;
-    'description.feedback': string;
+    'section.add': string;
+    'section.commands': string;
+    'label.goal': string;
+    'label.plan': string;
+    'label.feedback': string;
+    'label.compact': string;
+    'label.permission': string;
+    'label.export': string;
     'description.goal': string;
-    'description.permission': string;
     'description.plan': string;
+    'description.feedback': string;
+    'description.compact': string;
+    'description.permission': string;
+    'description.export': string;
+    'token.goal': string;
+    'token.plan': string;
+    'token.feedback': string;
+    'token.compact': string;
+    'token.permission': string;
+    'token.export': string;
     'search.placeholder': string;
     'search.aria': string;
     'status.loading': string;

package/lib/types/client/presentation.d.ts

@@ -0,0 +1,23 @@
+import type { InputTriggerCandidate } from '@deepseek-ai/dsh-client-ui-input-trigger/client';
+import type { TranslateNS } from '@deepseek-ai/dsh-client-locale/client';
+import type { CommandDescriptor } from '@deepseek-ai/dsh-commands/types';
+/** The menu's two sections. */
+export type MenuSection = 'add' | 'commands';
+/**
+ * The localized menu face of a catalog row.
+ * @param descriptor - effective Host command descriptor.
+ * @param t - the `command` namespace translator.
+ * @returns title, description, and glyph for a built-in command; undefined
+ * for any other row, which keeps its catalog description.
+ */
+export declare function builtinRowFace(descriptor: CommandDescriptor, t: TranslateNS<'command'>): Pick<InputTriggerCandidate, 'label' | 'description' | 'icon'> | undefined;
+/**
+ * Arrange the empty-query menu: the Add section, then the Commands section,
+ * each in usage order, with unlisted rows closing Commands in their input
+ * order; each row carries its section heading.
+ * @param rows - the visible candidates in catalog-then-contribution order.
+ * @param t - the `command` namespace translator.
+ * @returns the sectioned rows.
+ */
+export declare function sectionRows(rows: readonly InputTriggerCandidate[], t: TranslateNS<'command'>): readonly InputTriggerCandidate[];
+//# sourceMappingURL=presentation.d.ts.map

package/lib/types/client/resolution.d.ts

@@ -0,0 +1,35 @@
+/** Command identity and localized input spelling over the effective Host catalog. */
+import type { CommandDescriptor } from '@deepseek-ai/dsh-commands/types';
+import type { TranslateNS } from '@deepseek-ai/dsh-client-locale/client';
+declare const BUILTINS: {
+    readonly goal: "@deepseek-ai/dsh-command-goal";
+    readonly plan: "@deepseek-ai/dsh-plan-mode";
+    readonly feedback: "@deepseek-ai/dsh-command-feedback";
+    readonly compact: "@deepseek-ai/dsh-command-compact";
+    readonly permission: "@deepseek-ai/dsh-permission-presets";
+    readonly export: "@deepseek-ai/dsh-session-log-export";
+};
+/** Names whose first-party definitions have localized client presentation. */
+export type BuiltinCommandName = keyof typeof BUILTINS;
+/**
+ * Identify a first-party definition without interpreting its display copy.
+ * @param descriptor - effective Host descriptor after scoped shadowing.
+ * @returns its first-party name, or undefined for another definition.
+ */
+export declare function builtinCommandName(descriptor: CommandDescriptor): BuiltinCommandName | undefined;
+/**
+ * Select the input spelling for a menu-picked command.
+ * @param descriptor - effective Host descriptor.
+ * @param t - command-namespace translator.
+ * @returns localized spelling for a known definition, otherwise its registered name.
+ */
+export declare function claimToken(descriptor: CommandDescriptor, t: TranslateNS<'command'>): string;
+/**
+ * Resolve typed spelling against the current Session's effective definitions.
+ * @param token - typed name without its leading slash.
+ * @param descriptors - effective descriptors in the Session's ready catalog.
+ * @returns the matching descriptor; aliases never select an unrelated scoped override.
+ */
+export declare function resolveCommand(token: string, descriptors: readonly CommandDescriptor[]): CommandDescriptor | undefined;
+export {};
+//# sourceMappingURL=resolution.d.ts.map

package/lib/types/client/service.d.ts

@@ -2,10 +2,12 @@
  * CommandUiRuntime (`ctx.commandUi`): the '/' command source over the
  * session-keyed directory, the client-contribution registry, and the
  * per-session popupSelect controllers. Candidate synthesis merges the host
- * catalog with contributions by availability, then position filtering and
- * the `/` menu's shared name ranking (ui-primitives `rankByName`); a
- * host/contribution name collision fails loud. Every execute
- * addresses the session's agent by sessionId — sessions are always
+ * catalog with contributions by availability, gives built-in Host rows their
+ * localized face (presentation.ts), then position-filters; an empty query
+ * lists the Add and Commands sections in usage order, a typed query ranks
+ * every row by the `/` menu's shared name-and-label ranking (ui-primitives
+ * `rankByName`). A host/contribution name collision fails loud. Every
+ * execute addresses the session's agent by sessionId — sessions are always
  * agent-backed.
  */
 import { Service } from '@deepseek-ai/cordis';
@@ -56,6 +58,12 @@ export declare class CommandUiRuntime extends Service implements CommandUiContra
      * @returns the disposer removing the registration.
      */
     decorate(decoration: CommandDecoration): () => void;
+    /**
+     * Close every open popup for a command whose options have become stale.
+     * Pending loads and confirmations lose their binding; drafts stay intact.
+     * @param name - command name without the leading slash.
+     */
+    dismiss(name: string): void;
     /**
      * Resolve the per-session popup controller (lazy; dies with the session
      * scope). The controller's consume callback dispatches the scoped
@@ -74,10 +82,12 @@ export declare class CommandUiRuntime extends Service implements CommandUiContra
      * @returns the unbind disposer.
      */
     bindComposerFocus(id: SessionId, focus: () => void): () => void;
-    /** Menu candidates: host catalog + contribution availability, then position filtering and the shared name ranking. */
+    /**
+     * Menu candidates: host catalog + contribution availability, built-in rows
+     * localized, then position filtering; sections for an empty query, the
+     * shared name-and-label ranking for a typed one.
+     */
     private candidates;
-    /** Translate exact built-in Host copy while preserving scoped or third-party descriptors verbatim. */
-    private hostDescription;
     /** Decision table, menu column: contribution/decorated-host → popup or action; host input → claim; host bare → detached execute. */
     private dispatch;
     /** Decision table, space column: hot-key sync check; only host leadingInput claims. */
@@ -94,6 +104,9 @@ export declare class CommandUiRuntime extends Service implements CommandUiContra
      * refusal so the machine surfaces one composer notice and the draft and
      * attachments stay in place; nothing executes and nothing is dropped. An
      * action submits nothing and runs regardless.
+     *
+     * A typed token is resolved through the localized claim tokens, so a line
+     * written as `/计划` reaches the `plan` descriptor and executes as `/plan`.
      */
     private matchEnter;
     /**
@@ -101,7 +114,13 @@ export declare class CommandUiRuntime extends Service implements CommandUiContra
      * session's popup, or consume the token and run the action.
      */
     private invoke;
-    /** Build the leadingInput claim: token `/name ` + the command.execute submit transaction. */
+    /**
+     * Build the leadingInput claim. The composer keeps the claimed token in
+     * the draft and reads the arguments after it, so the token is the spelling
+     * the draft will carry: the locale's token for a menu pick, the typed
+     * spelling for Space and Enter. The command.execute submit transaction
+     * always sends the catalog name.
+     */
     private leadingClaim;
     /**
      * The command.execute transaction, addressed to the session's agent — pure

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-commands",
   "description": "Client command surface: global directory cache, '/' source, three command UI kinds, popupSelect registry",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -44,21 +44,21 @@
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
     "clsx": "^2.0.0",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-connection": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-test-runtime": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-commands": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-test-runtime": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-commands": "^0.1.6-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-store": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-input-trigger": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-session": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-api-session-controller": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-input-trigger": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-session": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.6-alpha.1"
   },
   "files": [
     "lib/index.js",