fix: docs

packages/client/ui-directory-picker-native/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-directory-picker-native/README.md
+README.md: feb944b38a17086e0fcc6e4da52e1f16a4055166
+README.zh.md: 72296b18af69749428157302744063056a6a50de

packages/client/ui-directory-picker-native/README.md

@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-ui-directory-picker-native
+
+English | [中文](README.zh.md)
+
+Native directory-picker surface: the browser half of the native picking interaction. It fills ui-workspace's two directory-flow holes (`conversation.hero.workspace.directoryFlow` and `sidebar.workspaces.directoryFlow`) with a renderless occupant that answers each `open` request by driving the local Host's OS chooser through `ctx.workspaces.pickDirectory()`, then reports exactly one outcome — a picked path, a cancellation, or a failure — back through the owner conversation. The OS dialog itself belongs to [`dsh-host-directory-picker-native`](../../host/directory-picker-native/README.md); mounting this package composes the surface with that backend from one cordis.yml row, so no client code branches on a capability kind.
+
+Both registrations install as one transactional effect through nested `slots.inject()` calls, because either declaring entry may activate later or replace its declaration. The occupant arms once per rising `open` edge, so re-renders — including an adoption that keeps `open` true while `busy` — never launch a second chooser, and the owner withdrawing `open` re-arms the next request. Settlements ride a ref so the answer reaches the owner's latest handlers rather than the ones captured when the chooser opened. An unmount (HMR replacing the occupant) discards the settlement wholesale: the wire carries no per-request abort, so the host-side chooser survives until answered, its answer lands nowhere, and the replacement instance re-arms under the owner's still-open request.
+
+The node half is an empty `apply`: it exists so the plugin appears in the host cordis.yml and Loader, while the browser half ships through `exports["./client"]` and is discovered through the `dsh.client` manifest declaration.
+
+## Model Experience
+
+None, as the directory chooser is browser chrome; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No cancellation of an open chooser** — the wire has no per-request abort, so a chooser already on the host display cannot be closed from the browser; a discarded settlement is simply ignored.
+- **Local Host carriers only** — an OS dialog opens on the machine running the Host, so in-process and remote-browser deployments need the `-browse` composition instead. Platform failures surface through the owner's retryable folder dialog.

packages/client/ui-directory-picker-native/README.zh.md

@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-ui-directory-picker-native
+
+[English](README.md) | 中文
+
+原生目录选择界面：原生选取交互的浏览器半边。它通过 ui-workspace 的两个 directory-flow 洞（`conversation.hero.workspace.directoryFlow` 与 `sidebar.workspaces.directoryFlow`）装入一个无渲染占位者，每次收到 `open` 请求就用 `ctx.workspaces.pickDirectory()` 驱动本地 Host 的操作系统选择框，然后通过 owner 会话回报恰好一个结果——选中的路径、取消、或失败。系统对话框本身属于 [`dsh-host-directory-picker-native`](../../host/directory-picker-native/README.md)；挂载本包即用一行 cordis.yml 把界面与该后端组合起来，因此没有任何客户端代码按能力种类分支。
+
+两处注册通过嵌套的 `slots.inject()` 作为一个事务性 effect 安装，因为任一声明方条目都可能稍后激活或替换其声明。占位者在每个 `open` 上升沿只武装一次，所以重渲染（包括采纳期间 `busy` 而 `open` 仍为真）都不会再开第二个选择框；owner 撤回 `open` 会为下一次请求重新武装。结果经由 ref 回报，因此答案落到 owner 最新的处理器上，而不是打开选择框时捕获的那一套。卸载（HMR 替换占位者）会整体丢弃该结果：wire 上没有按请求的中止通道，所以 Host 侧的选择框会一直存在到被回答，它的答案无处可落，替换后的实例则在 owner 仍然打开的请求下重新武装。
+
+node 半边是一个空 `apply`：它的存在只为让插件出现在 host 的 cordis.yml 与 Loader 中，浏览器半边经 `exports["./client"]` 出货，并通过 `dsh.client` 清单声明被发现。
+
+## 模型体验
+
+None, as the directory chooser is browser chrome; nothing here reaches a model request.
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送 provider 请求。
+
+## 已知限制与暂缓事项
+
+- **无法取消已打开的选择框** —— wire 上没有按请求的中止通道，因此已经出现在 Host 显示器上的选择框无法从浏览器关闭；被丢弃的结果只是被忽略。
+- **仅限本地 Host 载体** —— 系统对话框开在运行 Host 的机器上，所以进程内与远程浏览器部署需要改用 `-browse` 组合。平台失败通过 owner 的可重试文件夹对话框呈现。

packages/client/ui-directory-picker/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-directory-picker/README.md
+README.md: 3ab8ca07f88b61727badf97669ed52b349669efd
+README.zh.md: 8e2dea6a92771ab3f40fccf2ffb3359427627fd4

packages/client/ui-directory-picker/README.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-client-ui-directory-picker
+
+English | [中文](README.zh.md)
+
+In-app directory browsing surface: the browser half of the browse picking interaction. It fills ui-workspace's two directory-flow holes (`conversation.hero.workspace.directoryFlow` and `sidebar.workspaces.directoryFlow`) with the Select Workspace Directory dialog, driving the local Host's `host.listDirectory` and `host.createDirectory` primitives through `ctx.workspaces`. Its node counterpart is [`dsh-host-directory-picker-browse`](../../host/directory-picker-browse/README.md); mounting this package composes the surface with that backend from one cordis.yml row, so no client code branches on a capability kind. Unlike the [`-native`](../ui-directory-picker-native/README.md) surface, the dialog needs no local operating-system chooser, so it also serves in-process and remote-browser deployments.
+
+The dialog is a 680×500 Miller-column view (clamped on short or narrow viewports): a header carrying the title, the selection-path breadcrumb, and a click-to-edit path zone, then one full-width level until a row is selected, after which the row splits evenly into level and children columns. Navigations land selection-anchored and quiet — the previous view keeps rendering while a crumb jump or a submitted path is scanned, and target and parent legs land as one frame — so stepping back keeps two panes away from the display root and no intermediate frame flashes. **New folder** opens a nested create dialog targeting the selected folder and selects what it creates; **Open** adopts the selected folder, falling back to the listed level. Host-flagged hidden entries stay hidden until the footer toggle reveals them, which is a client-side filter only.
+
+Confirming a directory is the picked path and dismissing the dialog is the cancellation. Browse failures — an unreadable target, a create conflict — stay inside the dialog's own alert surfaces, so this occupant never drives the owner's `onError` arm; the owner keeps the workspace-creation error surface. Both registrations install through nested `slots.inject()` calls because either declaring entry may activate later or replace its declaration, and the dialog's copy is registered in this package's own locale namespace: the two dictionaries land as a unit, so a failed activation cannot squat one locale of the namespace.
+
+The node half is an empty `apply`: it exists so the plugin appears in the host cordis.yml and Loader, while the browser half ships through `exports["./client"]` and is discovered through the `dsh.client` manifest declaration.
+
+## Model Experience
+
+None, as the directory browser is browser chrome; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No search, no multi-select, and no rename or delete** — the dialog lists and creates directories; a target is reached by navigating, editing the path, or filtering the last pane by prefix.
+- **Hidden-entry filtering is client-side** — the Host always lists hidden entries and flags them, so the toggle changes only what the dialog renders.

packages/client/ui-directory-picker/README.zh.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-client-ui-directory-picker
+
+[English](README.md) | 中文
+
+应用内目录浏览界面：浏览式选取交互的浏览器半边。它通过 ui-workspace 的两个 directory-flow 洞（`conversation.hero.workspace.directoryFlow` 与 `sidebar.workspaces.directoryFlow`）装入「选择工作区目录」对话框，经 `ctx.workspaces` 驱动本地 Host 的 `host.listDirectory` 与 `host.createDirectory` 原语。它的 node 对侧是 [`dsh-host-directory-picker-browse`](../../host/directory-picker-browse/README.md)；挂载本包即用一行 cordis.yml 把界面与该后端组合起来，因此没有任何客户端代码按能力种类分支。与 [`-native`](../ui-directory-picker-native/README.md) 界面不同，本对话框不需要本地操作系统选择框，因此也服务于进程内与远程浏览器部署。
+
+对话框是 680×500 的 Miller 分栏视图（在窄屏或矮屏上收窄）：头部承载标题、选中路径面包屑和可点击编辑的路径区；下方在未选中行时是一整栏层级，选中后该行均分为「层级 | 选中文件夹的子项」两栏。导航落地是选择锚定且安静的——面包屑跳转或提交路径被扫描期间仍渲染旧视图，目标腿与父腿作为一帧落地——因此回退时离显示根之外始终保持两栏，且不会闪过中间帧。**新建文件夹**打开一个嵌套创建对话框，目标为选中的文件夹，并选中它创建出来的那个；**打开**采纳选中的文件夹，没有选中时回落到当前层级。Host 标记的隐藏条目默认不显示，直到页脚开关将其揭开——那只是客户端过滤。
+
+确认一个目录即为选中的路径，关闭对话框即为取消。浏览类失败——不可读的目标、创建冲突——都留在对话框自己的提示区内，因此本占位者从不驱动 owner 的 `onError` 分支；工作区创建的错误界面仍由 owner 持有。两处注册通过嵌套的 `slots.inject()` 安装，因为任一声明方条目都可能稍后激活或替换其声明；对话框文案注册在本包自己的 locale 命名空间下，两份字典作为一个单元落地，因此激活失败不会占住该命名空间的其中一种语言。
+
+node 半边是一个空 `apply`：它的存在只为让插件出现在 host 的 cordis.yml 与 Loader 中，浏览器半边经 `exports["./client"]` 出货，并通过 `dsh.client` 清单声明被发现。
+
+## 模型体验
+
+None, as the directory browser is browser chrome; nothing here reaches a model request.
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送 provider 请求。
+
+## 已知限制与暂缓事项
+
+- **无搜索、无多选、无重命名或删除** —— 对话框只负责列出与创建目录；到达目标靠导航、编辑路径，或用前缀过滤最后一栏。
+- **隐藏条目的过滤在客户端** —— Host 始终列出隐藏条目并加标记，因此开关只改变对话框渲染什么。

packages/self-modification/tool-cordis/src/api-catalog.ts

@@ -323,7 +323,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         jsDoc: '/**\n * Register a global or calling-agent-scoped command.\n * @param definition - discovery metadata and direct UI handler.\n * @returns the exact effect disposer that unregisters this definition.\n */',
       },
       {
-        signature: 'list(agent: Agent): readonly CommandDescriptor[]',
+        signature: '@Remote list(agent: Agent): readonly CommandDescriptor[]',
         jsDoc: '/**\n * List the effective immutable command descriptors for one agent.\n * @param agent - exact receiving agent and scoped-layer key.\n * @returns name-sorted descriptors after scoped shadowing.\n */',
       },
       {
@@ -331,7 +331,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         jsDoc: '/**\n * Resolve one effective command definition.\n * @param agent - exact receiving agent and scoped-layer key.\n * @param name - command name without a slash.\n * @returns the scoped shadow or global definition.\n */',
       },
       {
-        signature: 'async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>',
+        signature: '@Remote async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>',
         jsDoc: '/**\n * Parse and execute a known command without sending it to the model.\n *\n * A resolved command\'s lifecycle is logged: `command/run` is appended\n * before the handler is invoked and `command/done` after settlement (a\n * thrown or aborted handler settles as `kind: \'error\'`). Both are direct\n * log-only appends — no turn wraps them, and persistence drains them at\n * ordinary checkpoints. Admission misses (syntax or unknown name) log\n * nothing — they never entered a handler. A `command/run` append failure\n * fails the execution loud; a `command/done` append failure on the\n * handler-failure path is contained so the handler\'s own error stays the\n * reported failure.\n *\n * @param agent - exact receiving agent.\n * @param line - complete slash-command line.\n * @param signal - cancellation signal owned by the UI request.\n * @returns the settled execution (result + lifecycle pairing id), or\n *   `undefined` when syntax or name does not resolve.\n */',
       },
     ],
@@ -2266,7 +2266,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'InvocationParameterDescriptor',
-    declaration: 'export interface InvocationParameterDescriptor {\n    readonly name: string;\n    readonly wire: string;\n    readonly source: \'json\' | \'lookup\';\n    readonly lookup?: string;\n    readonly codec: TypeRTCodec;\n}',
+    declaration: 'export interface InvocationParameterDescriptor {\n    readonly name: string;\n    readonly wire: string;\n    readonly source: \'json\' | \'lookup\';\n    readonly lookup?: string;\n    readonly codec: TypeRTCodec;\n    readonly acceptsUndefined?: true;\n}',
   },
   {
     name: 'InvocationSourceLocation',